ai-lens 0.8.69 → 0.8.72

package/.commithash

@@ -1 +1 @@
-fe949b0
+78b5c4c

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 History of changes to the `ai-lens` CLI package on npm. New entries go on top. Format: `## X.Y.Z — YYYY-MM-DD`, followed by user-facing bullets.
 
+## 0.8.72 — 2026-05-29
+- fix: `status` no longer reports hooks as "outdated" when they already capture reliably. A hook is now considered current if it's GUI-safe — either the per-machine launcher (`run.sh`/`run.cmd`, including the transitional `sh -c` wrapper) OR a `capture.js` command with an absolute node path baked in (e.g. `/opt/homebrew/bin/node`). Only PATH-dependent forms (bare `node`, `/usr/bin/env node`) — which break for GUI-launched Cursor/Claude on macOS — stay flagged outdated so `init` rewrites them.
+- fix: `ai-lens status --report` now prints the full status to the screen just like plain `ai-lens status`, in addition to sending the report to the server. Previously it ran silently. The only difference from plain status is that it POSTs the report instead of writing the local `~/ai-lens-status.txt` file.
+
+## 0.8.71 — 2026-05-29
+- feat (ANL-837): Codex switched from the `codex-watcher` background process to native Codex hooks — the same hook-based capture path as Claude Code and Cursor. `init` writes hooks to the project `.codex/hooks.json` under `--project-hooks`; the user-layer `~/.codex/hooks.json` is silently ignored by Codex 0.130.x even though its source reads it, so the project layer is the reliable target.
+- feat (ANL-837): all 10 native Codex events are covered — `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SubagentStart`, `SubagentStop`, `Stop`. `SubagentStart`/`SubagentStop` are Codex 0.135 additions. `capture.js` normalizes all 10 directly; the source is detected via `turn_id` / the `rollout-*.jsonl` transcript path, so Codex events are no longer misclassified as `claude_code` and dropped.
+- feat (ANL-837): `init` pre-trusts every hook by injecting `[hooks.state."<path>:<event>:<group>:<handler>"]` blocks into `~/.codex/config.toml` with the exact `trusted_hash` Codex computes itself (bit-for-bit against `codex-rs/.../command_hook_hash`, bare-path key — no `file:` prefix). Hooks then fire from `codex exec` end-to-end with no manual step — verified live on Codex 0.135.
+- feat (ANL-837): `ai-lens status` now verifies each Codex hook against `[hooks.state.*]` in `~/.codex/config.toml` (`verifyCodexHookTrust`) and surfaces `missing` / `disabled` / `mismatch` separately. A broken `trusted_hash` (e.g. after hand-editing config.toml or moving the repo) previously showed up only as "0 events captured".
+- note: interactive `codex` (TUI) may show a one-time "N hooks need review" banner on first launch — a user-acknowledgement gate independent of the hash check. Codex 0.131+/0.135 offers a single "Trust all and continue" keystroke; when the full set is pre-trusted with matching hashes, Codex 0.135 shows no banner at all. `codex exec` needs no interactive step.
+- cleanup: removed the watcher lifecycle from `init`/`remove`/`status` and the obsolete watcher tests.
+
+## 0.8.70 — 2026-05-28
+- diag: `sender-spawn-failed`, `codex-watcher-spawn-failed` and `queue-write-failed` entries in the capture log now record the OS `error.code` (e.g. EMFILE, EACCES). `ai-lens status` surfaces a per-category code breakdown so these failures can be diagnosed centrally instead of guessing from a bare count. The raw error message (which may contain local paths) stays on your machine — only the short code travels in the status report.
+
 ## 0.8.69 — 2026-05-27
 - feat: per-machine launcher (`~/.ai-lens/client/run.sh` / `run.cmd`) now also accepts an optional script path as its first argument. With no args it still execs the sibling `capture.js` (default install), but `~/.ai-lens/client/run.sh path/to/some/capture.js` execs that script with the launcher's resolved node — letting bootstrap-style workflows (e.g. meta-cursor) route through the launcher for proper node resolution while keeping `capture.js` under git in the workspace repo.
 - feat: new `--install-launcher` flag for `init`. Forces launcher installation even when `--no-hooks` is set, so the meta-cursor setup skill can wire up `~/.ai-lens/client/run.sh` without touching the static hook templates in the workspace repo.

package/README.md

@@ -20,7 +20,7 @@ This will:
 1. Detect installed AI tools (Claude Code, Cursor, Codex)
 2. Copy client files to `~/.ai-lens/client/`
 3. Configure hooks in `~/.claude/settings.json` and/or `~/.cursor/hooks.json`
-4. Start the Codex watcher for user-level and project-local Codex sessions
+4. Configure Codex native hooks in project `.codex/hooks.json` via `--project-hooks` (Codex 0.130.x ignores user-layer `~/.codex/hooks.json`)
 5. Register the MCP server for in-editor analytics (optional)
 
 Re-running is safe — it updates outdated hooks and skips current ones.
@@ -99,13 +99,34 @@ export AI_LENS_PROJECTS="~/meta/, ~/meta-cursor/"   # optional, default: all
 }
 ```
 
-**Codex** — no hook file. Run `ai-lens init` to start the local watcher, or start it manually:
+**Codex** — `<project>/.codex/hooks.json` (use `npx -y ai-lens init --project-hooks`; user-layer `~/.codex/hooks.json` is silently ignored by Codex 0.130.x):
 
-```bash
-node ~/.ai-lens/client/codex-watcher.js
+```json
+{
+  "hooks": {
+    "SessionStart":      [{ "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }],
+    "UserPromptSubmit":  [{ "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }],
+    "PreToolUse":        [{ "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }],
+    "PostToolUse":       [{ "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }],
+    "PermissionRequest": [{ "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }],
+    "PreCompact":        [{ "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }],
+    "PostCompact":       [{ "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }],
+    "SubagentStart":     [{ "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }],
+    "SubagentStop":      [{ "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }],
+    "Stop":              [{ "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }]
+  }
+}
 ```
 
-The watcher tails the user-level Codex directory (`~/.codex`) and any project-local `.codex` directories found under `AI_LENS_PROJECTS`. It respects `AI_LENS_PROJECTS` the same way as Claude Code and Cursor: only sessions whose `cwd` is inside a configured monitored root are sent.
+All 10 native Codex events are installed: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SubagentStart`, `SubagentStop`, `Stop` (the last two are 0.135 additions). Pre-trust hashes match Codex's `command_hook_hash` bit-for-bit for all 10 — verified against Codex 0.135: with the full set pre-trusted, no "needs review" banner appears and codex leaves every `[hooks.state.*]` entry untouched.
+
+The `matcher` field is intentionally omitted — Codex coerces `matcher` to `None` for `UserPromptSubmit`/`Stop` before hashing, so writing `matcher: ""` leaves those entries stuck in `Modified` trust status.
+
+Init also pre-trusts each hook by writing `[hooks.state."<hooks.json-path>:<event>:<group>:<handler>"]` blocks into `~/.codex/config.toml` with a `trusted_hash` matching what Codex computes. The state key is the **bare hooks.json path** (no `file:` scheme prefix) — that's the exact key `codex-rs/hooks/src/lib.rs::hook_key` looks up. (An earlier `file:` prefix never matched, so the pre-trust was silently ignored and hooks never fired.)
+
+**`codex exec`** captures events end-to-end with no interactive step — the pre-trust is all it needs (verified on Codex 0.135).
+
+**Interactive `codex` (TUI)** — when the full hook set is pre-trusted with matching hashes, Codex 0.135 shows no review banner and fires hooks immediately. If a banner does appear (e.g. partial/older trust state), pick **"Trust all and continue"** on Codex 0.131+/0.135 (one keystroke for all hooks); after that, every interactive session fires hooks automatically. Pre-trust still earns its keep: without it the hooks show as `Modified` and re-prompt on every command change.
 
 </details>
 
@@ -261,7 +282,7 @@ Aggregate endpoints for dashboard charts: overview, teams, developers, tokens, M
 |------|---------------|
 | **Claude Code** | Hooks via `~/.claude/settings.json` |
 | **Cursor** | Hooks via `~/.cursor/hooks.json` |
-| **Codex** | File watcher on `~/.codex` and project-local `.codex` directories |
+| **Codex** | Native hooks via project `.codex/hooks.json` (Codex 0.130.x ignores user-layer `~/.codex/hooks.json`) |
 
 ## Client Data
 

package/bin/ai-lens.js

@@ -42,6 +42,8 @@ switch (command) {
     console.log('    --no-hooks      Skip writing hooks and MCP (config + auth only)');
     console.log('    --no-mcp        Skip MCP server registration');
     console.log('    --mcp-scope S   MCP scope: user, local, or project (default: user)');
+    console.log('    --project-hooks Write Cursor/Claude hooks to project .cursor/ and .claude/ (not ~/.cursor)');
+    console.log('    --use-repo-path Run capture.js from this package; skip copy to ~/.ai-lens/client/');
     console.log('  remove          Remove AI Lens hooks and client files');
     console.log('  status          Run diagnostics and generate a status report');
     console.log('  version         Show package version and commit hash');

package/cli/hooks.js

@@ -527,6 +527,18 @@ const CURSOR_HOOK_NAMES = [
   'afterAgentResponse', 'afterAgentThought', 'stop', 'sessionEnd',
 ];
 
+// All 10 native Codex hook events (codex-rs/hooks/src/events/ plus the
+// SubagentStart/SubagentStop events added in Codex 0.135). Codex uses the nested
+// MatcherGroup format `{ hooks: [{ type:"command", command }] }` with NO matcher
+// field — a flat `{ command }` parses as an empty MatcherGroup and never fires,
+// and a `matcher: ""` would change the trust hash for UserPromptSubmit/Stop
+// (codex coerces their matcher to None before hashing).
+const CODEX_HOOK_NAMES = [
+  'SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse',
+  'PermissionRequest', 'PreCompact', 'PostCompact',
+  'SubagentStart', 'SubagentStop', 'Stop',
+];
+
 // Wrap captureCommand in a memoised getter so makeXxxHookDefs(null) does NOT
 // trigger node-path resolution at builder time — the first .hookDefs[name]()
 // call does it instead, and subsequent calls reuse the cached string.
@@ -576,6 +588,22 @@ export function makeCursorHookDefs(ctx = null, mode = 'global') {
   return defs;
 }
 
+/**
+ * Build Codex hookDefs bound to a ctx. mode: 'global' (default) | 'project'.
+ * Codex uses the nested MatcherGroup format with no matcher. Project-hooks bake a
+ * ~/.ai-lens/... path; Codex spawns hooks via `/bin/sh -lc`, which expands ~.
+ * captureCommand is deferred (see makeClaudeHookDefs).
+ */
+export function makeCodexHookDefs(ctx = null, mode = 'global') {
+  const useTilde = mode === 'project';
+  const getCmd = memoizeCmd(() => captureCommand({ useTilde, rawPath: true, ctx }));
+  const defs = {};
+  for (const name of CODEX_HOOK_NAMES) {
+    defs[name] = () => ({ hooks: [{ type: 'command', command: getCmd() }] });
+  }
+  return defs;
+}
+
 /**
  * Claude Code hook defs that point to a custom path (e.g. REPO_CAPTURE_PATH for --use-repo-path).
  * @param {string} capturePath - Absolute path to client/capture.js.
@@ -604,6 +632,15 @@ export function getCursorHookDefsWithPath(capturePath, ctx = null) {
   return defs;
 }
 
+export function getCodexHookDefsWithPath(capturePath, ctx = null) {
+  const getCmd = memoizeCmd(() => captureCommand({ rawPath: true, customPath: capturePath, ctx }));
+  const defs = {};
+  for (const name of CODEX_HOOK_NAMES) {
+    defs[name] = () => ({ hooks: [{ type: 'command', command: getCmd() }] });
+  }
+  return defs;
+}
+
 /**
  * Build the array of TOOL_CONFIGS (Claude Code + Cursor at user-global paths).
  * Pass ctx for production use; omit for the legacy TOOL_CONFIGS export
@@ -628,6 +665,13 @@ export function makeToolConfigs(ctx = null) {
       hookDefs: makeCursorHookDefs(ctx, 'global'),
       topLevelFields: { version: 1 },
     },
+    {
+      name: 'Codex',
+      dirPath: join(homedir(), '.codex'),
+      configPath: join(homedir(), '.codex', 'hooks.json'),
+      hookDefs: makeCodexHookDefs(ctx, 'global'),
+      topLevelFields: {},
+    },
   ];
 }
 
@@ -676,6 +720,18 @@ export function getClaudeCodeToolConfig(projectRoot, label = 'Claude Code (proje
   };
 }
 
+export function getCodexToolConfig(projectRoot, label = 'Codex (project)', ctx = null) {
+  const base = TOOL_CONFIGS.find(t => t.name === 'Codex');
+  if (!base) return null;
+  return {
+    ...base,
+    name: label,
+    dirPath: join(projectRoot, '.codex'),
+    configPath: join(projectRoot, '.codex', 'hooks.json'),
+    hookDefs: makeCodexHookDefs(ctx, 'project'),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // AI Lens hook detection
 // ---------------------------------------------------------------------------
@@ -798,35 +854,48 @@ function normalizePath(p) {
   return (p || '').replace(/\\/g, '/');
 }
 
+// A hook command is "GUI-safe" — i.e. survives a GUI app's minimal launchd PATH —
+// if it either routes through the per-machine launcher (run.sh / run.cmd, directly
+// OR via the transitional wrapper that execs it) OR runs capture.js with an
+// ABSOLUTE node path baked in. Bare `node` and `/usr/bin/env node` are NOT GUI-safe
+// (they depend on node being on PATH, which GUI Cursor/Claude often lack).
+//
+// Both GUI-safe forms capture events reliably, so init produces one of them and we
+// treat either as "current". Only the PATH-dependent forms get flagged outdated.
+export function isGuiSafeHookCommand(cmd) {
+  if (!isAiLensCommand(cmd).isAiLens) return false;
+  const n = (cmd || '').replace(/\\/g, '/');
+  // Launcher: direct path, or the transitional wrapper that execs run.sh/run.cmd.
+  if (n.includes('.ai-lens/client/run.sh') || n.includes('.ai-lens/client/run.cmd')) return true;
+  // capture.js form: GUI-safe only when the node binary is an absolute path
+  // (e.g. /opt/homebrew/bin/node), not bare `node` or an env shim.
+  const p = _parseHookCommand(cmd);
+  if (p.kind === 'captureJs' && p.nodePrefix) {
+    const np = p.nodePrefix;
+    const isAbsolute = np.startsWith('/') || /^[a-zA-Z]:\//.test(np);
+    const isEnvShim = np === '/usr/bin/env' || np.endsWith('/env');
+    if (isAbsolute && !isEnvShim) return true;
+  }
+  return false;
+}
+
 function isCurrentAiLensHook(entry, expected) {
+  // "Current" = a GUI-safe install (launcher OR absolute-node capture.js). We do
+  // NOT require an exact match against the expected command form — both valid
+  // install methods capture reliably, so neither should be reported outdated.
+  // Only PATH-dependent forms (bare `node`, `/usr/bin/env node`) are outdated.
   // Flat format (Cursor): single command per entry.
   if (entry?.command != null) {
-    const expectedCmd = expected?.command || expected?.hooks?.[0]?.command || '';
-    return commandsMatch(entry.command, expectedCmd);
+    return isGuiSafeHookCommand(entry.command);
   }
-  // Nested format (Claude Code): { matcher, hooks: [{ command }] }
+  // Nested format (Claude Code / Codex): { matcher, hooks: [{ command }] }
   if (Array.isArray(entry?.hooks)) {
-    const expectedCmd = expected?.hooks?.[0]?.command || '';
     if (expected?.matcher !== undefined && entry.matcher !== expected.matcher) return false;
-    return entry.hooks.some(h => commandsMatch(h?.command || '', expectedCmd));
+    return entry.hooks.some(h => isGuiSafeHookCommand(h?.command || ''));
   }
   return false;
 }
 
-function commandsMatch(entryCmd, expectedCmd) {
-  const e = _parseHookCommand(entryCmd);
-  const x = _parseHookCommand(expectedCmd);
-  if (x.kind === 'unknown') {
-    // Best-effort fallback: literal compare after slash-normalisation.
-    return normalizePath(entryCmd) === normalizePath(expectedCmd);
-  }
-  if (e.kind !== x.kind) return false;
-  if (e.prefix !== x.prefix) return false;
-  if (e.path !== x.path) return false;
-  if (x.kind === 'captureJs' && e.nodePrefix !== x.nodePrefix) return false;
-  return true;
-}
-
 // ---------------------------------------------------------------------------
 // Tool detection
 // ---------------------------------------------------------------------------
@@ -1028,7 +1097,12 @@ export function buildStrippedConfig(tool, existingConfig) {
 // ---------------------------------------------------------------------------
 
 export function writeHooksConfig(tool, config) {
-  mkdirSync(dirname(tool.configPath), { recursive: true });
+  const parentDir = dirname(tool.configPath);
+  if (existsSync(parentDir) && !lstatSync(parentDir).isDirectory()) {
+    const bakPath = parentDir + '.bak';
+    try { renameSync(parentDir, bakPath); } catch {}
+  }
+  mkdirSync(parentDir, { recursive: true });
   const tmpPath = tool.configPath + '.tmp.' + process.pid;
   writeFileSync(tmpPath, JSON.stringify(config, null, 2) + '\n');
   try {
@@ -1098,6 +1172,306 @@ export function cleanupLegacyHooks(tool) {
   return results;
 }
 
+/**
+ * Codex (>=0.130.0) marks every newly discovered hook as Untrusted and refuses
+ * to fire it until the user trusts it via the interactive TUI hooks browser.
+ * `codex exec` (non-interactive) has no UI to do that, so AI Lens hooks would
+ * stay inert forever after install.
+ *
+ * The trust state lives under `[hooks.state."<key>"]` tables in the user
+ * config.toml, where `<key>` is `<hooks.json-path>:<event_key>:<group_idx>:<handler_idx>`
+ * (codex-rs/hooks/src/lib.rs::hook_key — the key is the bare hooks.json path as
+ * rendered by AbsolutePathBuf::display(), with NO `file:` scheme prefix; an
+ * earlier `file:` prefix here never matched Codex's lookup, so the pre-trust was
+ * silently ignored and hooks stayed Untrusted) and the value is `{ enabled = true,
+ * trusted_hash = "sha256:<hex>" }`. Codex re-checks the hash on each run; if
+ * it doesn't match the live entry it falls back to Modified/Untrusted and
+ * silently drops the hook. So the hash must mirror Codex's
+ * `command_hook_hash` exactly: SHA-256 of the canonical-JSON encoding of a
+ * NormalizedHookIdentity { event_name (snake_case), matcher, hooks:
+ * [{ type:"command", command, command_windows:null, timeout:600,
+ * async:false, status_message:null }] } (see
+ * codex-rs/hooks/src/engine/discovery.rs and config/src/fingerprint.rs).
+ *
+ * The CLI bypass flag (--dangerously-bypass-hook-trust, shared_options.rs)
+ * was added 2026-05-13, after codex-cli 0.130.0 shipped, so it's not a
+ * universal substitute yet. Writing trust state directly works on every
+ * version that supports hooks at all.
+ *
+ * Returns { changed, configPath, alreadyTrusted, missing, hooks }.
+ * `hooks` is the list of injected keys (debug-friendly).
+ */
+import { createHash } from 'node:crypto';
+
+const CODEX_HOOK_EVENT_KEYS = {
+  SessionStart: 'session_start',
+  UserPromptSubmit: 'user_prompt_submit',
+  PreToolUse: 'pre_tool_use',
+  PostToolUse: 'post_tool_use',
+  PermissionRequest: 'permission_request',
+  PreCompact: 'pre_compact',
+  PostCompact: 'post_compact',
+  SubagentStart: 'subagent_start',
+  SubagentStop: 'subagent_stop',
+  Stop: 'stop',
+};
+
+// Codex's matcher_pattern_for_event (codex-rs/hooks/src/events/common.rs):
+// UserPromptSubmit and Stop ignore any matcher in the source file and hash
+// with matcher=None. Every other event passes the matcher through verbatim.
+const CODEX_EVENTS_WITHOUT_MATCHER = new Set(['user_prompt_submit', 'stop']);
+
+function canonicalJson(value) {
+  // Mirrors codex-rs/config/src/fingerprint.rs::canonical_json — sort object
+  // keys recursively; arrays preserve order; primitives unchanged.
+  if (Array.isArray(value)) return value.map(canonicalJson);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const k of Object.keys(value).sort()) out[k] = canonicalJson(value[k]);
+    return out;
+  }
+  return value;
+}
+
+function codexCommandHookHash(eventKey, command, fileMatcher) {
+  // Reproduces command_hook_hash (codex-rs/hooks/src/engine/discovery.rs):
+  //   struct → toml::Value → serde_json::to_value → canonical_json → sha256(JSON)
+  // Codex first runs matcher_pattern_for_event(event, file_matcher) which
+  // forces None for UserPromptSubmit/Stop regardless of what the file says,
+  // then writes that back into group.matcher before hashing. TOML omits None
+  // fields, so we drop matcher from the canonical JSON for those events.
+  // The handler we install has command_windows=None and status_message=None,
+  // so neither key appears in the hashed JSON either.
+  // After canonical key sort: { async, command, timeout, type } in handler.
+  const handler = {
+    type: 'command',
+    command,
+    timeout: 600,
+    async: false,
+  };
+  const identity = { event_name: eventKey, hooks: [handler] };
+  const effectiveMatcher = CODEX_EVENTS_WITHOUT_MATCHER.has(eventKey)
+    ? null
+    : (fileMatcher === undefined ? null : fileMatcher);
+  if (effectiveMatcher !== null) identity.matcher = effectiveMatcher;
+  const canonical = canonicalJson(identity);
+  const serialized = JSON.stringify(canonical);
+  return 'sha256:' + createHash('sha256').update(serialized).digest('hex');
+}
+
+export function enableCodexHookTrust(hooksFilePath, userConfigDir = join(homedir(), '.codex')) {
+  // userConfigDir is always the user's ~/.codex/ — Codex reads trust state
+  // only from the User config layer (codex-rs/hooks/src/config_rules.rs).
+  // Project-scoped hooks still trust through the user's config.toml, keyed
+  // by the absolute project hooks.json path.
+  const codexDir = userConfigDir;
+  const configPath = join(codexDir, 'config.toml');
+  if (!existsSync(codexDir)) {
+    return { changed: false, configPath, alreadyTrusted: false, missing: true, hooks: [] };
+  }
+  if (!existsSync(hooksFilePath)) {
+    return { changed: false, configPath, alreadyTrusted: false, missing: true, hooks: [] };
+  }
+
+  let hooksJson;
+  try {
+    hooksJson = JSON.parse(readFileSync(hooksFilePath, 'utf-8'));
+  } catch (err) {
+    return { changed: false, configPath, alreadyTrusted: false, missing: false, hooks: [], error: `unreadable ${hooksFilePath}: ${err.message}` };
+  }
+
+  // Build per-handler trust entries for every AI Lens hook in the file.
+  const trustEntries = [];
+  for (const [eventName, eventKey] of Object.entries(CODEX_HOOK_EVENT_KEYS)) {
+    const groups = hooksJson?.hooks?.[eventName];
+    if (!Array.isArray(groups)) continue;
+    groups.forEach((group, groupIdx) => {
+      const handlers = Array.isArray(group?.hooks) ? group.hooks : [];
+      handlers.forEach((handler, handlerIdx) => {
+        const command = handler?.command;
+        if (typeof command !== 'string' || !isAiLensCapturePath(command)) return;
+        const key = `${hooksFilePath}:${eventKey}:${groupIdx}:${handlerIdx}`;
+        // Pass the file's matcher value through — codex's matcher_pattern_for_event
+        // strips it for UserPromptSubmit/Stop, mirrored inside codexCommandHookHash.
+        const fileMatcher = typeof group?.matcher === 'string' ? group.matcher : undefined;
+        const hash = codexCommandHookHash(eventKey, command, fileMatcher);
+        trustEntries.push({ key, hash });
+      });
+    });
+  }
+  if (trustEntries.length === 0) {
+    return { changed: false, configPath, alreadyTrusted: false, missing: false, hooks: [] };
+  }
+
+  let original = '';
+  let hadFile = false;
+  try { original = readFileSync(configPath, 'utf-8'); hadFile = true; } catch {}
+
+  // Strip any existing AI Lens [hooks.state."<key>"] blocks (and the banner
+  // comment that introduces them) before reinserting — repeated init runs
+  // would otherwise accumulate duplicate banners and key collisions.
+  let stripped = original;
+  for (const { key } of trustEntries) {
+    const headerRe = new RegExp(`(^|\\n)\\[hooks\\.state\\.${escapeRegex(JSON.stringify(key))}\\][^\\[]*`, 'g');
+    stripped = stripped.replace(headerRe, '$1');
+    // Also strip legacy `file:`-prefixed blocks left by pre-fix installs (the
+    // prefix never matched Codex's lookup, so these are dead state).
+    const legacyRe = new RegExp(`(^|\\n)\\[hooks\\.state\\.${escapeRegex(JSON.stringify('file:' + key))}\\][^\\[]*`, 'g');
+    stripped = stripped.replace(legacyRe, '$1');
+  }
+  // Drop our own banner if present from a prior run (matches both the legacy
+  // bypass_hook_trust banner and the new pre-trusted-hooks banner).
+  stripped = stripped.replace(/(?:^|\n)# AI Lens:[^\n]*(?:\n#[^\n]*)*\n?/g, '\n');
+  stripped = stripped.replace(/\n{3,}/g, '\n\n').replace(/\n+$/, '\n');
+
+  const block = trustEntries.map(({ key, hash }) => (
+    `[hooks.state.${JSON.stringify(key)}]\n` +
+    `enabled = true\n` +
+    `trusted_hash = "${hash}"\n`
+  )).join('\n');
+
+  const banner = '\n# AI Lens: pre-trusted Codex hooks so they fire from `codex exec`\n# (the TUI trust flow is unreachable for non-interactive sessions).\n';
+  const updated = (hadFile ? stripped.replace(/\n*$/, '\n') : '') + banner + block;
+
+  // If the file is unchanged after our rebuild, nothing to do.
+  if (updated === original) {
+    return { changed: false, configPath, alreadyTrusted: true, missing: false, hooks: trustEntries.map(e => e.key) };
+  }
+
+  mkdirSync(codexDir, { recursive: true });
+  const tmpPath = configPath + '.tmp.' + process.pid;
+  writeFileSync(tmpPath, updated);
+  try {
+    renameSync(tmpPath, configPath);
+  } catch (err) {
+    try { unlinkSync(tmpPath); } catch {}
+    throw err;
+  }
+  return { changed: true, configPath, alreadyTrusted: false, missing: false, hooks: trustEntries.map(e => e.key) };
+}
+
+/**
+ * Uninstall counterpart to enableCodexHookTrust: strip the AI Lens
+ * `[hooks.state."<hooksFilePath>:..."]` pre-trust blocks (plus legacy
+ * `file:`-prefixed ones and the AI Lens banner) from the user's
+ * ~/.codex/config.toml. Keyed purely by hooksFilePath, so it works even after
+ * the hooks.json itself has already been deleted (the usual remove order).
+ * Leaves all unrelated config.toml content intact. Returns
+ * { changed, configPath, removed } where `removed` is the count of blocks dropped.
+ */
+export function removeCodexHookTrust(hooksFilePath, userConfigDir = join(homedir(), '.codex')) {
+  const configPath = join(userConfigDir, 'config.toml');
+  let original;
+  try { original = readFileSync(configPath, 'utf-8'); }
+  catch { return { changed: false, configPath, removed: 0, missing: true }; }
+
+  // Match every [hooks.state."<key>"] block whose key targets this hooks.json —
+  // both the correct bare-path form and the legacy `file:`-prefixed form.
+  const pathRe = escapeRegex(hooksFilePath);
+  // Match the [hooks.state."..."] header then its value lines — any following
+  // lines that do NOT start a new section ([...]). Using a line-based body (not
+  // `[^[]*`) avoids consuming the newline before the next block, which would
+  // make adjacent blocks match only every other one.
+  const blockRe = new RegExp(
+    `(^|\\n)\\[hooks\\.state\\."(?:file:)?${pathRe}:[^"]*"\\](?:\\n(?!\\[)[^\\n]*)*`,
+    'g',
+  );
+  let removed = 0;
+  let stripped = original.replace(blockRe, (m, lead) => { removed++; return lead; });
+
+  if (removed === 0) return { changed: false, configPath, removed: 0, missing: false };
+
+  // Drop our banner and any now-empty `[hooks.state]` header, then tidy blank runs.
+  stripped = stripped.replace(/(?:^|\n)# AI Lens:[^\n]*(?:\n#[^\n]*)*\n?/g, '\n');
+  stripped = stripped.replace(/(^|\n)\[hooks\.state\]\s*(?=\n\[|\n*$)/g, '$1');
+  stripped = stripped.replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '').replace(/\n+$/, '\n');
+
+  if (stripped === original) return { changed: false, configPath, removed, missing: false };
+
+  const tmpPath = configPath + '.tmp.' + process.pid;
+  writeFileSync(tmpPath, stripped);
+  try { renameSync(tmpPath, configPath); }
+  catch (err) { try { unlinkSync(tmpPath); } catch {} throw err; }
+  return { changed: true, configPath, removed, missing: false };
+}
+
+export function verifyCodexHookTrust(hooksFilePath, userConfigDir = join(homedir(), '.codex')) {
+  // Diagnostic counterpart to enableCodexHookTrust: for every AI Lens hook in
+  // hooksFilePath, recompute the expected trusted_hash and check that the
+  // matching [hooks.state."<key>"] block in ~/.codex/config.toml has it.
+  // Returns { ok, configPath, entries: [{ key, expected, stored, status }] }
+  // where status is one of:
+  //   'ok'       — block exists, enabled, hash matches
+  //   'missing'  — no [hooks.state."<key>"] block at all
+  //   'mismatch' — block exists but hash differs (likely command/path drift)
+  //   'disabled' — block exists but enabled = false
+  const configPath = join(userConfigDir, 'config.toml');
+  if (!existsSync(hooksFilePath)) {
+    return { ok: null, configPath, entries: [], reason: 'hooks file missing' };
+  }
+  if (!existsSync(configPath)) {
+    return { ok: false, configPath, entries: [], reason: 'config.toml missing — run init to pre-trust' };
+  }
+
+  let hooksJson;
+  try {
+    hooksJson = JSON.parse(readFileSync(hooksFilePath, 'utf-8'));
+  } catch (err) {
+    return { ok: false, configPath, entries: [], reason: `unreadable ${hooksFilePath}: ${err.message}` };
+  }
+
+  let tomlText = '';
+  try { tomlText = readFileSync(configPath, 'utf-8'); } catch {}
+
+  // Lightweight parse: we wrote each block as exactly three lines
+  // ([header], enabled = true|false, trusted_hash = "..."), so a per-key regex
+  // is sufficient and avoids pulling in a TOML lib for one diagnostic.
+  function readBlock(key) {
+    const headerLiteral = `[hooks.state.${JSON.stringify(key)}]`;
+    const idx = tomlText.indexOf(headerLiteral);
+    if (idx === -1) return null;
+    const tail = tomlText.slice(idx + headerLiteral.length);
+    const next = tail.search(/\n\[/);
+    const body = next === -1 ? tail : tail.slice(0, next);
+    const enabledMatch = body.match(/\benabled\s*=\s*(true|false)\b/);
+    const hashMatch = body.match(/\btrusted_hash\s*=\s*"([^"]+)"/);
+    return {
+      enabled: enabledMatch ? enabledMatch[1] === 'true' : null,
+      hash: hashMatch ? hashMatch[1] : null,
+    };
+  }
+
+  const entries = [];
+  for (const [eventName, eventKey] of Object.entries(CODEX_HOOK_EVENT_KEYS)) {
+    const groups = hooksJson?.hooks?.[eventName];
+    if (!Array.isArray(groups)) continue;
+    groups.forEach((group, groupIdx) => {
+      const handlers = Array.isArray(group?.hooks) ? group.hooks : [];
+      handlers.forEach((handler, handlerIdx) => {
+        const command = handler?.command;
+        if (typeof command !== 'string' || !isAiLensCapturePath(command)) return;
+        const key = `${hooksFilePath}:${eventKey}:${groupIdx}:${handlerIdx}`;
+        const fileMatcher = typeof group?.matcher === 'string' ? group.matcher : undefined;
+        const expected = codexCommandHookHash(eventKey, command, fileMatcher);
+        const block = readBlock(key);
+        let status;
+        if (!block) status = 'missing';
+        else if (block.enabled === false) status = 'disabled';
+        else if (block.hash !== expected) status = 'mismatch';
+        else status = 'ok';
+        entries.push({ key, eventName, expected, stored: block?.hash || null, status });
+      });
+    });
+  }
+
+  const ok = entries.length > 0 && entries.every(e => e.status === 'ok');
+  return { ok, configPath, entries };
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 /**
  * Delete .mcp.json in cwd if it was left with empty mcpServers by `claude mcp remove`.
  */