feat: add native Codex hook integration

README.md

@@ -66,6 +66,7 @@ npx elydora install \
 | Agent | Key |
 |-------|-----|
 | Claude Code | `claudecode` |
+| OpenAI Codex | `codex` |
 | Cursor | `cursor` |
 | Gemini CLI | `gemini` |
 | Kiro CLI | `kirocli` |
@@ -74,6 +75,8 @@ npx elydora install \
 | Copilot CLI | `copilot` |
 | Letta Code | `letta` |
 
+Codex performs a one-time trust review for user hooks. Run `/hooks` in Codex after installation and trust the Elydora `PreToolUse` and `PostToolUse` definitions.
+
 ## API Reference
 
 ### Configuration

src/cli.ts

@@ -14,6 +14,7 @@ import { kiroidePlugin } from './plugins/kiroide.js';
 import { opencodePlugin } from './plugins/opencode.js';
 import { copilotPlugin } from './plugins/copilot.js';
 import { lettaPlugin } from './plugins/letta.js';
+import { codexPlugin } from './plugins/codex.js';
 
 const ELYDORA_DIR = path.join(os.homedir(), '.elydora');
 
@@ -26,6 +27,7 @@ const PLUGINS: ReadonlyMap<string, AgentPlugin> = new Map([
   ['opencode', opencodePlugin],
   ['copilot', copilotPlugin],
   ['letta', lettaPlugin],
+  ['codex', codexPlugin],
 ]);
 
 // ---------------------------------------------------------------------------

src/plugins/codex.ts

@@ -0,0 +1,204 @@
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import type { AgentPlugin, InstallConfig, PluginStatus } from './base.js';
+import { SUPPORTED_AGENTS } from './registry.js';
+
+const AGENT_KEY = 'codex';
+const GUARD_STATUS = 'Checking Elydora agent state';
+const AUDIT_STATUS = 'Recording Elydora tool use';
+const entry = SUPPORTED_AGENTS.get(AGENT_KEY)!;
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function resolveConfigPath(): string {
+  const configDir = entry.configDir.replace(/^~/, os.homedir());
+  return path.join(configDir, entry.configFile);
+}
+
+function quotePosix(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+function quoteWindows(value: string): string {
+  return `"${value.replaceAll('"', '\\"')}"`;
+}
+
+function buildHandler(scriptPath: string, statusMessage: string): JsonObject {
+  return {
+    type: 'command',
+    command: `${quotePosix(process.execPath)} ${quotePosix(scriptPath)}`,
+    commandWindows: `${quoteWindows(process.execPath)} ${quoteWindows(scriptPath)}`,
+    timeout: 10,
+    statusMessage,
+  };
+}
+
+function eventGroups(hooks: JsonObject, event: string): JsonObject[] {
+  const value = hooks[event];
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || !value.every(isObject)) {
+    throw new Error(`Codex hooks config field "hooks.${event}" must be an array of objects`);
+  }
+  return value;
+}
+
+function isElydoraHandler(handler: JsonObject, agentId?: string): boolean {
+  if (handler.statusMessage !== GUARD_STATUS && handler.statusMessage !== AUDIT_STATUS) return false;
+  if (!agentId) return true;
+  return [handler.command, handler.commandWindows].some(
+    (command) => typeof command === 'string' && command.includes(agentId),
+  );
+}
+
+function withoutElydora(groups: JsonObject[], agentId?: string): JsonObject[] {
+  const result: JsonObject[] = [];
+  for (const group of groups) {
+    if (!Array.isArray(group.hooks) || !group.hooks.every(isObject)) {
+      throw new Error('Codex hook matcher group must contain a hooks array');
+    }
+    const handlers = group.hooks.filter((handler) => !isElydoraHandler(handler, agentId));
+    if (handlers.length > 0) result.push({ ...group, hooks: handlers });
+  }
+  return result;
+}
+
+function findHandler(groups: JsonObject[], statusMessage: string): JsonObject | undefined {
+  for (const group of groups) {
+    if (!Array.isArray(group.hooks)) continue;
+    const handler = group.hooks.find(
+      (candidate) => isObject(candidate) && candidate.statusMessage === statusMessage,
+    );
+    if (isObject(handler)) return handler;
+  }
+  return undefined;
+}
+
+function commandReferences(handler: JsonObject, scriptPath: string): boolean {
+  return [handler.command, handler.commandWindows].some(
+    (command) => typeof command === 'string' && command.includes(scriptPath),
+  );
+}
+
+async function readSettings(configPath: string): Promise<JsonObject | undefined> {
+  let raw: string;
+  try {
+    raw = await fsp.readFile(configPath, 'utf-8');
+  } catch (error) {
+    if (isObject(error) && error.code === 'ENOENT') return undefined;
+    throw new Error(`Read Codex hooks config: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Failed to parse Codex hooks config: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!isObject(value)) throw new Error('Codex hooks config must contain a JSON object');
+  return value;
+}
+
+async function writeSettings(configPath: string, settings: JsonObject): Promise<void> {
+  await fsp.mkdir(path.dirname(configPath), { recursive: true });
+  const tempPath = `${configPath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await fsp.writeFile(tempPath, JSON.stringify(settings, null, 2) + '\n', {
+      encoding: 'utf-8',
+      mode: 0o600,
+    });
+    await fsp.rename(tempPath, configPath);
+  } catch (error) {
+    await fsp.unlink(tempPath).catch(() => undefined);
+    throw new Error(`Write Codex hooks config: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function getHooks(settings: JsonObject): JsonObject {
+  if (settings.hooks === undefined) return {};
+  if (!isObject(settings.hooks)) throw new Error('Codex hooks config field "hooks" must be an object');
+  return { ...settings.hooks };
+}
+
+async function runtimeScriptsExist(guard: JsonObject, audit: JsonObject): Promise<boolean> {
+  const root = path.join(os.homedir(), '.elydora');
+  let entries;
+  try {
+    entries = await fsp.readdir(root, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+
+  for (const directory of entries) {
+    if (!directory.isDirectory()) continue;
+    const agentDir = path.join(root, directory.name);
+    try {
+      const config = JSON.parse(await fsp.readFile(path.join(agentDir, 'config.json'), 'utf-8'));
+      if (config.agent_name !== AGENT_KEY) continue;
+      const guardPath = path.join(agentDir, 'guard.js');
+      const hookPath = path.join(agentDir, 'hook.js');
+      if (!commandReferences(guard, guardPath) || !commandReferences(audit, hookPath)) continue;
+      await Promise.all([fsp.access(guardPath), fsp.access(hookPath)]);
+      return true;
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}
+
+export const codexPlugin: AgentPlugin = {
+  async install(config: InstallConfig): Promise<void> {
+    const configPath = resolveConfigPath();
+    const settings = (await readSettings(configPath)) ?? {};
+    const hooks = getHooks(settings);
+
+    hooks.PreToolUse = [
+      ...withoutElydora(eventGroups(hooks, 'PreToolUse')),
+      { matcher: '*', hooks: [buildHandler(config.guardScriptPath, GUARD_STATUS)] },
+    ];
+    hooks.PostToolUse = [
+      ...withoutElydora(eventGroups(hooks, 'PostToolUse')),
+      { matcher: '*', hooks: [buildHandler(config.hookScriptPath, AUDIT_STATUS)] },
+    ];
+
+    await writeSettings(configPath, { ...settings, hooks });
+    console.log('  Codex: run /hooks to review and trust the Elydora hooks.');
+  },
+
+  async uninstall(agentId?: string): Promise<void> {
+    const configPath = resolveConfigPath();
+    const settings = await readSettings(configPath);
+    if (!settings) return;
+    const hooks = getHooks(settings);
+    hooks.PreToolUse = withoutElydora(eventGroups(hooks, 'PreToolUse'), agentId);
+    hooks.PostToolUse = withoutElydora(eventGroups(hooks, 'PostToolUse'), agentId);
+    await writeSettings(configPath, { ...settings, hooks });
+  },
+
+  async status(): Promise<PluginStatus> {
+    const configPath = resolveConfigPath();
+    const settings = await readSettings(configPath);
+    let guard: JsonObject | undefined;
+    let audit: JsonObject | undefined;
+    if (settings) {
+      const hooks = getHooks(settings);
+      guard = findHandler(eventGroups(hooks, 'PreToolUse'), GUARD_STATUS);
+      audit = findHandler(eventGroups(hooks, 'PostToolUse'), AUDIT_STATUS);
+    }
+    const hookConfigured = Boolean(guard && audit);
+    const hookScriptExists = guard && audit ? await runtimeScriptsExist(guard, audit) : false;
+    return {
+      installed: hookConfigured && hookScriptExists,
+      agentName: AGENT_KEY,
+      displayName: entry.name,
+      hookConfigured,
+      hookScriptExists,
+      configPath,
+    };
+  },
+};

src/plugins/registry.ts

@@ -13,4 +13,5 @@ export const SUPPORTED_AGENTS: ReadonlyMap<string, AgentRegistryEntry> = new Map
   ['opencode', { name: 'OpenCode', configDir: '.config/opencode/plugins', configFile: 'elydora-audit.mjs' }],
   ['copilot', { name: 'Copilot CLI', configDir: '.github/hooks', configFile: 'hooks.json' }],
   ['letta', { name: 'Letta Code', configDir: '~/.letta', configFile: 'settings.json' }],
+  ['codex', { name: 'OpenAI Codex', configDir: '~/.codex', configFile: 'hooks.json' }],
 ]);

test/codex-plugin.test.mjs

@@ -0,0 +1,236 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { pathToFileURL } from 'node:url';
+
+const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/codex.js')).href;
+const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
+
+function runNode(args, env, input = '') {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, args, {
+      env: { ...process.env, ...env },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.once('error', reject);
+    child.once('close', (code) => resolve({ code, stdout, stderr }));
+    child.stdin.end(input);
+  });
+}
+
+function runCommand(command, input = '') {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, {
+      shell: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.once('error', reject);
+    child.once('close', (code) => resolve({ code, stdout, stderr }));
+    child.stdin.end(input);
+  });
+}
+
+function findHandler(settings, event, statusMessage) {
+  for (const group of settings.hooks?.[event] ?? []) {
+    const handler = group.hooks?.find((item) => item.statusMessage === statusMessage);
+    if (handler) return handler;
+  }
+  return undefined;
+}
+
+async function runPlugin(homeDir, method, argument) {
+  const script = `
+    import { codexPlugin } from ${JSON.stringify(pluginModuleUrl)};
+    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
+    const result = await codexPlugin[process.env.ELYDORA_TEST_METHOD](argument);
+    if (result !== undefined) console.log(JSON.stringify(result));
+  `;
+  return runNode(
+    ['--input-type=module', '--eval', script],
+    {
+      HOME: homeDir,
+      USERPROFILE: homeDir,
+      ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
+      ELYDORA_TEST_METHOD: method,
+    },
+  );
+}
+
+async function createFixture({ guardSource, hookSource, existingSettings } = {}) {
+  const homeDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-codex-'));
+  const agentDir = path.join(homeDir, '.elydora', 'agent-1');
+  const configDir = path.join(homeDir, '.codex');
+  await mkdir(agentDir, { recursive: true });
+  await mkdir(configDir, { recursive: true });
+
+  const guardScriptPath = path.join(agentDir, 'guard.js');
+  const hookScriptPath = path.join(agentDir, 'hook.js');
+  await writeFile(
+    guardScriptPath,
+    guardSource ?? "process.stderr.write('Agent is frozen by Elydora.'); process.exit(2);\n",
+  );
+  await writeFile(hookScriptPath, hookSource ?? 'process.exit(0);\n');
+  await writeFile(path.join(agentDir, 'config.json'), JSON.stringify({
+    agent_id: 'agent-1',
+    agent_name: 'codex',
+  }));
+
+  const configPath = path.join(configDir, 'hooks.json');
+  if (existingSettings !== undefined) {
+    await writeFile(configPath, typeof existingSettings === 'string'
+      ? existingSettings
+      : JSON.stringify(existingSettings, null, 2));
+  }
+
+  const installResult = await runPlugin(homeDir, 'install', {
+    agentName: 'codex',
+    agentId: 'agent-1',
+    baseUrl: 'https://api.elydora.com',
+    guardScriptPath,
+    hookScriptPath,
+  });
+
+  return {
+    agentDir,
+    configPath,
+    guardScriptPath,
+    homeDir,
+    hookScriptPath,
+    installResult,
+    async close() {
+      await rm(homeDir, { recursive: true, force: true });
+    },
+  };
+}
+
+test('Codex is registered as a native hook integration', async () => {
+  const { SUPPORTED_AGENTS } = await import(registryModuleUrl);
+  assert.deepEqual(SUPPORTED_AGENTS.get('codex'), {
+    name: 'OpenAI Codex',
+    configDir: '~/.codex',
+    configFile: 'hooks.json',
+  });
+});
+
+test('Codex install preserves existing hooks and is idempotent', async () => {
+  const existing = {
+    description: 'Workspace hooks',
+    hooks: {
+      SessionStart: [{ hooks: [{ type: 'command', command: 'existing-command' }] }],
+    },
+  };
+  const fixture = await createFixture({ existingSettings: existing });
+  try {
+    assert.equal(fixture.installResult.code, 0, fixture.installResult.stderr);
+    assert.match(fixture.installResult.stdout, /run \/hooks to review and trust/i);
+    const secondInstall = await runPlugin(fixture.homeDir, 'install', {
+      agentName: 'codex',
+      agentId: 'agent-1',
+      baseUrl: 'https://api.elydora.com',
+      guardScriptPath: fixture.guardScriptPath,
+      hookScriptPath: fixture.hookScriptPath,
+    });
+    assert.equal(secondInstall.code, 0, secondInstall.stderr);
+
+    const settings = JSON.parse(await readFile(fixture.configPath, 'utf-8'));
+    assert.equal(settings.description, 'Workspace hooks');
+    assert.equal(settings.hooks.SessionStart[0].hooks[0].command, 'existing-command');
+    assert.equal(settings.hooks.PreToolUse.length, 1);
+    assert.equal(settings.hooks.PostToolUse.length, 1);
+    assert.equal(settings.hooks.PreToolUse[0].matcher, '*');
+    assert.equal(settings.hooks.PostToolUse[0].matcher, '*');
+  } finally {
+    await fixture.close();
+  }
+});
+
+test('Codex hook commands enforce freezes and forward the official event payload', async () => {
+  const capturePath = path.join(os.tmpdir(), `elydora-codex-event-${process.pid}-${Date.now()}.json`);
+  const hookSource = `
+    const fs = require('node:fs');
+    const chunks = [];
+    process.stdin.on('data', (chunk) => chunks.push(chunk));
+    process.stdin.on('end', () => fs.writeFileSync(${JSON.stringify(capturePath)}, Buffer.concat(chunks)));
+  `;
+  const fixture = await createFixture({ hookSource });
+  try {
+    assert.equal(fixture.installResult.code, 0, fixture.installResult.stderr);
+    const settings = JSON.parse(await readFile(fixture.configPath, 'utf-8'));
+    const guard = findHandler(settings, 'PreToolUse', 'Checking Elydora agent state');
+    const audit = findHandler(settings, 'PostToolUse', 'Recording Elydora tool use');
+    assert(guard);
+    assert(audit);
+
+    const commandKey = process.platform === 'win32' ? 'commandWindows' : 'command';
+    const guardResult = await runCommand(guard[commandKey], JSON.stringify({
+      hook_event_name: 'PreToolUse',
+      session_id: 'session-1',
+      tool_name: 'Bash',
+      tool_input: { command: 'echo test' },
+    }));
+    assert.equal(guardResult.code, 2);
+    assert.match(guardResult.stderr, /Agent is frozen by Elydora/);
+
+    const payload = {
+      hook_event_name: 'PostToolUse',
+      session_id: 'session-1',
+      tool_name: 'Bash',
+      tool_use_id: 'call-1',
+      tool_input: { command: 'echo test' },
+      tool_response: { output: 'test' },
+    };
+    const auditResult = await runCommand(audit[commandKey], JSON.stringify(payload));
+    assert.equal(auditResult.code, 0, auditResult.stderr);
+    assert.deepEqual(JSON.parse(await readFile(capturePath, 'utf-8')), payload);
+  } finally {
+    await fixture.close();
+    await rm(capturePath, { force: true });
+  }
+});
+
+test('Codex status requires both runtime scripts and uninstall preserves other hooks', async () => {
+  const fixture = await createFixture({ existingSettings: {
+    hooks: { PreToolUse: [{ hooks: [{ type: 'command', command: 'existing-command' }] }] },
+  } });
+  try {
+    assert.equal(fixture.installResult.code, 0, fixture.installResult.stderr);
+    const status = await runPlugin(fixture.homeDir, 'status', null);
+    assert.equal(status.code, 0, status.stderr);
+    assert.equal(JSON.parse(status.stdout).installed, true);
+
+    await rm(fixture.guardScriptPath);
+    const degradedStatus = await runPlugin(fixture.homeDir, 'status', null);
+    assert.equal(JSON.parse(degradedStatus.stdout).installed, false);
+
+    const uninstall = await runPlugin(fixture.homeDir, 'uninstall', 'agent-1');
+    assert.equal(uninstall.code, 0, uninstall.stderr);
+    const settings = JSON.parse(await readFile(fixture.configPath, 'utf-8'));
+    assert.equal(settings.hooks.PreToolUse.length, 1);
+    assert.equal(settings.hooks.PreToolUse[0].hooks[0].command, 'existing-command');
+    assert.deepEqual(settings.hooks.PostToolUse, []);
+  } finally {
+    await fixture.close();
+  }
+});
+
+test('Codex install preserves malformed config for recovery', async () => {
+  const fixture = await createFixture({ existingSettings: '{ malformed' });
+  try {
+    assert.equal(fixture.installResult.code, 1);
+    assert.match(fixture.installResult.stderr, /parse Codex hooks config/i);
+    assert.equal(await readFile(fixture.configPath, 'utf-8'), '{ malformed');
+  } finally {
+    await fixture.close();
+  }
+});