@agfpd/iapeer 0.2.31 → 0.2.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.31",
+  "version": "0.2.32",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -284,6 +284,10 @@ export interface RemoveOutcome {
    *  was dropped from the host codex config; a failure detail otherwise. Absent
    *  for non-codex peers and when no entry existed. */
   codexTrust?: string
+  /** Codex hooks-trust cleanup outcome: `removed <n>` when pre-seeded
+   *  `[hooks.state."<cwd>/…"]` entries were dropped (trust-hooks verb is the
+   *  writer); a failure detail otherwise. Absent when nothing matched. */
+  codexHooksTrust?: string
   /** Identity-keyed lifecycle artifacts purged with the record (state/lifecycle/
    *  `<identity>.*` per runtime). Without this purge a NEWBORN peer reusing the
    *  personality inherits the dead namesake's parking (live defect, boris 10.06:
@@ -365,6 +369,7 @@ export async function removePeerCli(
   // unprovision (the provider sees the peer's last consistent state first),
   // best-effort like everything else on this path.
   let trustCleaned: string | undefined
+  let hooksTrustCleaned: string | undefined
   if (peer.runtimes.includes('codex')) {
     try {
       const { removeCodexCwdTrust } = await import('../launch/nativeMemory.ts')
@@ -373,6 +378,16 @@ export async function removePeerCli(
     } catch (e) {
       trustCleaned = `failed (${e instanceof Error ? e.message : String(e)})`
     }
+    // Same class, hooks edition: pre-seeded `[hooks.state."<cwd>/…"]` entries
+    // (trust-hooks verb) must not outlive the peer either.
+    try {
+      const { removeCodexHooksTrustUnder } = await import('../launch/codexHooksTrust.ts')
+      const h = removeCodexHooksTrustUnder(peer.cwd, env)
+      hooksTrustCleaned =
+        h.state === 'written' ? `removed ${h.removed.length}` : h.state === 'already' ? undefined : `${h.state}${h.detail ? ` (${h.detail})` : ''}`
+    } catch (e) {
+      hooksTrustCleaned = `failed (${e instanceof Error ? e.message : String(e)})`
+    }
   }
   // Purge identity-keyed lifecycle state WITH the record (per runtime): stale
   // .stopped/.idle-reaped/... must never outlive the peer and ambush a future
@@ -387,6 +402,7 @@ export async function removePeerCli(
     purgedState,
     ...(unprovisionOutcomes.length ? { unprovision: unprovisionOutcomes } : {}),
     ...(trustCleaned ? { codexTrust: trustCleaned } : {}),
+    ...(hooksTrustCleaned ? { codexHooksTrust: hooksTrustCleaned } : {}),
   }
 }
 
@@ -542,6 +558,7 @@ const USAGE = `usage: iapeer <verb> [args]
   self-done                                                      (agent self-call, ephemeral) silent finish: arm own quiet-reap, wake no one
   native-memory <off|on> (--peer <p> | --all)                    gate/restore runtimes' native memory (canonized lever; контракт «Слот памяти»)
   memory-plugin <on|off> (--peer <p> | --all)                    install/remove the slot-declared provider plugin (claude per-peer, codex host-global)
+  trust-hooks <hooks.json> [--check]                             pre-seed codex hooks trust for a file-form hooks.json (no modal); --check = drift report
 `
 
 export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
@@ -700,6 +717,45 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         }
         return r.ok ? 0 : 1
       }
+      case 'trust-hooks': {
+        // Deterministic pre-seed of the codex hooks trust state for a FILE-form
+        // hooks.json (user- or project-local layer) — the headless replacement for
+        // the "Hooks need review" modal: codex trusts per hook-command HASH, and in
+        // `codex exec` an untrusted hook is SILENTLY skipped (no modal, no error).
+        // Verified on codex-cli 0.138.0 (golden hashes in the module tests).
+        // Consumers: the memory provider's provision command (writes its per-peer
+        // <cwd>/.codex/hooks.json, then shells this verb), operators. `--check` is
+        // the read-only drift detector for verify pipelines — per-hook
+        // trusted/missing/drift, exit 1 on anything but full trust.
+        const target = positionals[0]
+        if (!target) return usage(errOut)
+        const { preSeedCodexHooksTrust, checkCodexHooksTrust } = await import('../launch/codexHooksTrust.ts')
+        if (flags.check === true) {
+          let checks
+          try {
+            checks = checkCodexHooksTrust(target, env)
+          } catch (e) {
+            errOut(`trust-hooks --check: ${e instanceof Error ? e.message : String(e)}\n`)
+            return 1
+          }
+          for (const c of checks.checks) {
+            out(`${c.status}\t${c.event}\t${c.key}${c.status === 'drift' ? ` (state: ${c.found ?? '?'} ≠ expected: ${c.hash})` : ''}\n`)
+          }
+          if (checks.checks.length === 0) out('no command hooks found — nothing to check\n')
+          return checks.checks.every(c => c.status === 'trusted') ? 0 : 1
+        }
+        const r = preSeedCodexHooksTrust(target, env)
+        if (r.state === 'failed') {
+          errOut(`trust-hooks: ${r.detail}\n`)
+          return 1
+        }
+        out(
+          r.state === 'already'
+            ? `already trusted: ${r.entries.length} hook(s) from ${r.source}${r.detail ? ` — ${r.detail}` : ''}\n`
+            : `trusted ${r.entries.length} hook(s) from ${r.source} → ${r.path}\n`,
+        )
+        return 0
+      }
       case 'status': {
         // Host snapshot (контракт «Слот памяти» §status): version + daemon health +
         // the memory-slot line. Exit 1 iff the daemon is unhealthy (usable as a
@@ -850,6 +906,10 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           if (o.codexTrust) {
             out(`codex trust entry: ${o.codexTrust}\n`)
           }
+          // Same for pre-seeded hooks trust state (trust-hooks verb's writes).
+          if (o.codexHooksTrust) {
+            out(`codex hooks trust: ${o.codexHooksTrust}\n`)
+          }
           // Stale identity-keyed markers must die with the record (boris 10.06: a
           // namesake newborn inherited a dead peer's .stopped → refused to wake).
           if (o.purgedState?.length) {

package/src/launch/codexHooksTrust.test.ts

@@ -0,0 +1,248 @@
+// codex hooks trust pre-seed — the deterministic replacement for the "Hooks
+// need review" modal. The HARD anchor here: the GOLDEN hashes — three values
+// codex-cli 0.138.0 itself granted live ("Trust all and continue", smoke
+// 11.06, isolated CODEX_HOME). If the re-implemented algorithm drifts from
+// these, we would seed state codex ignores → hooks silently skipped fleet-wide.
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { realpathSync } from 'fs'
+import {
+  checkCodexHooksTrust,
+  commandHookHash,
+  computeHooksTrustEntries,
+  preSeedCodexHooksTrust,
+  removeCodexHooksTrustUnder,
+} from './codexHooksTrust.ts'
+import { codexGlobalConfigPath } from './nativeMemory.ts'
+
+const dirs: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-hookstrust-'))
+  dirs.push(d)
+  return d
+}
+afterEach(() => {
+  while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true })
+})
+
+/** Env pointing the codex global config into an isolated CODEX_HOME. */
+function isolatedEnv(): { env: NodeJS.ProcessEnv; configPath: string } {
+  const home = mkTmp()
+  const env = { CODEX_HOME: home } as NodeJS.ProcessEnv
+  return { env, configPath: codexGlobalConfigPath(env) }
+}
+
+function writeHooksJson(dir: string, content: unknown): string {
+  const path = join(dir, 'hooks.json')
+  writeFileSync(path, JSON.stringify(content, null, 2))
+  return path
+}
+
+// ─── golden hashes (granted LIVE by codex-cli 0.138.0) ──────────────────────
+
+describe('commandHookHash — golden values from live-granted trust', () => {
+  test('session_start, no matcher, default timeout (V1 smoke hook)', () => {
+    expect(
+      commandHookHash('session_start', undefined, {
+        command: '/tmp/iapeer-codex-hooks-smoke/bin/stamp.sh user-hooks-json-sessionstart',
+      }),
+    ).toBe('sha256:c21b34240dd15d7184bf391f13e820399cb4b8e97c22347689316f8d02207391')
+  })
+
+  test('session_start, no matcher, default timeout (V2 smoke hook)', () => {
+    expect(
+      commandHookHash('session_start', undefined, {
+        command: '/tmp/iapeer-codex-hooks-smoke/bin/stamp.sh user-hooks-json-sessionstart-V2',
+      }),
+    ).toBe('sha256:5727103dc6b7409ae2a811561e28de70b625a2bdd28f8715a73e6542836f34fe')
+  })
+
+  test('post_tool_use, no matcher, default timeout (project-local smoke hook)', () => {
+    expect(
+      commandHookHash('post_tool_use', undefined, {
+        command: '/tmp/iapeer-codex-hooks-smoke/bin/stamp.sh proj-hooks-json-posttooluse',
+      }),
+    ).toBe('sha256:86f96ab754e05851c6f2f9b162bd99c70359099cdb6c93c114d0e6df42971030')
+  })
+
+  test('normalization knobs shift the hash: timeout, matcher, statusMessage', () => {
+    const base = commandHookHash('post_tool_use', undefined, { command: 'x' })
+    expect(commandHookHash('post_tool_use', undefined, { command: 'x', timeout: 30 })).not.toBe(base)
+    expect(commandHookHash('post_tool_use', 'Write|Edit', { command: 'x' })).not.toBe(base)
+    expect(commandHookHash('post_tool_use', undefined, { command: 'x', statusMessage: 's' })).not.toBe(base)
+    // explicit default timeout hashes the SAME as omitted (both normalize to 600)
+    expect(commandHookHash('post_tool_use', undefined, { command: 'x', timeout: 600 })).toBe(base)
+    // timeout 0 clamps to 1 (upstream .max(1)), distinct from the default
+    expect(commandHookHash('post_tool_use', undefined, { command: 'x', timeout: 0 })).toBe(
+      commandHookHash('post_tool_use', undefined, { command: 'x', timeout: 1 }),
+    )
+  })
+})
+
+// ─── hooks.json → entries ────────────────────────────────────────────────────
+
+describe('computeHooksTrustEntries', () => {
+  test('keys carry source:event_snake:group:handler; matcher passes through', () => {
+    const entries = computeHooksTrustEntries(
+      JSON.stringify({
+        hooks: {
+          PostToolUse: [
+            { matcher: 'Write', hooks: [{ type: 'command', command: 'a' }] },
+            { hooks: [{ type: 'command', command: 'b' }, { type: 'command', command: 'c' }] },
+          ],
+        },
+      }),
+      '/some/hooks.json',
+    )
+    expect(entries.map(e => e.key)).toEqual([
+      '/some/hooks.json:post_tool_use:0:0',
+      '/some/hooks.json:post_tool_use:1:0',
+      '/some/hooks.json:post_tool_use:1:1',
+    ])
+    expect(entries[0]!.hash).toBe(commandHookHash('post_tool_use', 'Write', { command: 'a' }))
+    expect(entries[1]!.hash).toBe(commandHookHash('post_tool_use', undefined, { command: 'b' }))
+  })
+
+  test('skipped handlers (async / prompt / empty) consume their index, get no entry', () => {
+    const entries = computeHooksTrustEntries(
+      JSON.stringify({
+        hooks: {
+          SessionStart: [
+            {
+              hooks: [
+                { type: 'command', command: 'first', async: true }, // h=0 skipped
+                { type: 'prompt' }, // h=1 skipped
+                { type: 'command', command: '  ' }, // h=2 skipped (empty)
+                { type: 'command', command: 'real' }, // h=3 KEPT
+              ],
+            },
+          ],
+        },
+      }),
+      '/p/hooks.json',
+    )
+    expect(entries).toHaveLength(1)
+    expect(entries[0]!.key).toBe('/p/hooks.json:session_start:0:3')
+  })
+
+  test('UserPromptSubmit/Stop force the matcher OFF (upstream matcher_pattern_for_event)', () => {
+    const entries = computeHooksTrustEntries(
+      JSON.stringify({
+        hooks: {
+          Stop: [{ matcher: 'ignored', hooks: [{ type: 'command', command: 'x' }] }],
+        },
+      }),
+      '/p/hooks.json',
+    )
+    expect(entries[0]!.hash).toBe(commandHookHash('stop', undefined, { command: 'x' }))
+  })
+
+  test('unknown event / malformed shapes are loud errors', () => {
+    expect(() => computeHooksTrustEntries(JSON.stringify({ hooks: { NotAnEvent: [] } }), '/p')).toThrow(
+      /unknown hook event/,
+    )
+    expect(() => computeHooksTrustEntries('not json', '/p')).toThrow(/not valid JSON/)
+    expect(() => computeHooksTrustEntries(JSON.stringify({}), '/p')).toThrow(/"hooks" object/)
+  })
+})
+
+// ─── pre-seed (state surgery) ────────────────────────────────────────────────
+
+describe('preSeedCodexHooksTrust', () => {
+  test('absent config → sections appended; second run → already', () => {
+    const { env, configPath } = isolatedEnv()
+    const proj = mkTmp()
+    const hooksPath = writeHooksJson(proj, {
+      hooks: { SessionStart: [{ hooks: [{ type: 'command', command: '/x/stamp.sh' }] }] },
+    })
+    const first = preSeedCodexHooksTrust(hooksPath, env)
+    expect(first.state).toBe('written')
+    expect(first.entries).toHaveLength(1)
+    const real = realpathSync(hooksPath)
+    const text = readFileSync(configPath, 'utf8')
+    expect(text).toContain(`[hooks.state."${real}:session_start:0:0"]`)
+    expect(text).toContain(`trusted_hash = "${first.entries[0]!.hash}"`)
+    expect(preSeedCodexHooksTrust(hooksPath, env).state).toBe('already')
+  })
+
+  test('NO-CLOBBER: foreign sections survive; changed hook updates IN PLACE', () => {
+    const { env, configPath } = isolatedEnv()
+    const proj = mkTmp()
+    const hooksPath = writeHooksJson(proj, {
+      hooks: { SessionStart: [{ hooks: [{ type: 'command', command: 'one' }] }] },
+    })
+    mkdirSync(join(env.CODEX_HOME!), { recursive: true })
+    const foreign = '[projects."/keep/me"]\ntrust_level = "trusted"\n\n[features]\nmemories = false\n'
+    writeFileSync(configPath, foreign)
+    preSeedCodexHooksTrust(hooksPath, env)
+    // change the command → hash changes → same section updated, not duplicated
+    writeHooksJson(proj, { hooks: { SessionStart: [{ hooks: [{ type: 'command', command: 'two' }] }] } })
+    const second = preSeedCodexHooksTrust(hooksPath, env)
+    expect(second.state).toBe('written')
+    const text = readFileSync(configPath, 'utf8')
+    expect(text).toContain('[projects."/keep/me"]')
+    expect(text).toContain('memories = false')
+    const real = realpathSync(hooksPath)
+    const headers = text.split('\n').filter(l => l.includes(`${real}:session_start:0:0`))
+    expect(headers).toHaveLength(1) // updated in place — no duplicate section
+    expect(text).toContain(`trusted_hash = "${second.entries[0]!.hash}"`)
+  })
+
+  test('missing hooks.json → failed (loud), config untouched', () => {
+    const { env, configPath } = isolatedEnv()
+    const o = preSeedCodexHooksTrust('/nonexistent/hooks.json', env)
+    expect(o.state).toBe('failed')
+    expect(existsSync(configPath)).toBe(false)
+  })
+})
+
+// ─── check (read-only drift detector) ────────────────────────────────────────
+
+describe('checkCodexHooksTrust', () => {
+  test('missing → trusted after seed → drift after edit without re-seed', () => {
+    const { env } = isolatedEnv()
+    const proj = mkTmp()
+    const hooksPath = writeHooksJson(proj, {
+      hooks: { PostToolUse: [{ hooks: [{ type: 'command', command: 'stamp' }] }] },
+    })
+    expect(checkCodexHooksTrust(hooksPath, env).checks[0]!.status).toBe('missing')
+    preSeedCodexHooksTrust(hooksPath, env)
+    expect(checkCodexHooksTrust(hooksPath, env).checks[0]!.status).toBe('trusted')
+    writeHooksJson(proj, { hooks: { PostToolUse: [{ hooks: [{ type: 'command', command: 'edited' }] }] } })
+    const drifted = checkCodexHooksTrust(hooksPath, env).checks[0]!
+    expect(drifted.status).toBe('drift')
+    expect(drifted.found).toBeDefined()
+  })
+})
+
+// ─── remove (reap-side cleanup) ──────────────────────────────────────────────
+
+describe('removeCodexHooksTrustUnder', () => {
+  test('drops sections under the cwd, keeps everything else', () => {
+    const { env, configPath } = isolatedEnv()
+    const peerCwd = mkTmp()
+    const hooksPath = writeHooksJson(peerCwd, {
+      hooks: { SessionStart: [{ hooks: [{ type: 'command', command: 'x' }] }] },
+    })
+    preSeedCodexHooksTrust(hooksPath, env)
+    // a foreign hooks.state entry from ANOTHER peer must survive
+    const foreign = '[hooks.state."/other/peer/hooks.json:session_start:0:0"]\ntrusted_hash = "sha256:keep"\n'
+    writeFileSync(configPath, readFileSync(configPath, 'utf8') + foreign)
+    const o = removeCodexHooksTrustUnder(peerCwd, env)
+    expect(o.state).toBe('written')
+    expect(o.removed).toHaveLength(1)
+    const text = readFileSync(configPath, 'utf8')
+    expect(text).not.toContain(realpathSync(hooksPath))
+    expect(text).toContain('/other/peer/hooks.json')
+    // idempotent
+    expect(removeCodexHooksTrustUnder(peerCwd, env).state).toBe('already')
+  })
+
+  test('no config / no matches → already', () => {
+    const { env } = isolatedEnv()
+    expect(removeCodexHooksTrustUnder('/nope', env).state).toBe('already')
+  })
+})

package/src/launch/codexHooksTrust.ts

@@ -0,0 +1,372 @@
+// codexHooksTrust — deterministic pre-seed of the codex hooks trust state.
+//
+// codex gates EVERY hook (plugin-form AND file-form alike) behind a one-time
+// interactive "Hooks need review" modal; trust is recorded per hook COMMAND in
+// the codex GLOBAL config as
+//
+//   [hooks.state."<source>:<event_snake>:<group>:<handler>"]
+//   trusted_hash = "sha256:<hex>"
+//
+// where <source> is the absolute (resolved) path of the hooks.json the hook
+// came from. In headless `codex exec` the modal never shows — an untrusted
+// hook is SILENTLY skipped. Writing the state entry BEFORE the first session
+// makes the hook trusted deterministically: no modal, no TUI auto-responder.
+//
+// The hash algorithm is reverse-engineered from openai/codex
+// (`hooks/src/engine/discovery.rs::command_hook_hash` +
+// `config/src/fingerprint.rs::version_for_toml`) and verified against two
+// live-granted hashes (smoke 11.06, isolated CODEX_HOME — the golden values
+// live in the test file):
+//
+//   trusted_hash = "sha256:" + sha256(compactJson(sortKeysDeep(identity)))
+//   identity     = { event_name: "<snake>", matcher?: "<verbatim>",
+//                    hooks: [{ type: "command", command, timeout, async: false,
+//                              statusMessage? }] }
+//
+// Normalization (mirrors upstream discovery before hashing):
+//   - timeout   = given.max(1), default 600 (commandWindows is dropped: the
+//     None fields vanish in the TOML round-trip upstream hashes through)
+//   - matcher   = group's matcher verbatim, EXCEPT UserPromptSubmit/Stop where
+//     codex forces it to None (matcher_pattern_for_event)
+//   - async hooks, non-"command" handlers and empty commands are SKIPPED by
+//     codex before hashing — they get no state entry, but they DO consume
+//     their positional index.
+//
+// FRAGILITY PIN: verified on codex-cli 0.138.0. Upstream carries a TODO to
+// replace the positional key suffix with a durable hook id — when that lands,
+// `--check` (checkCodexHooksTrust) is the detector: it compares the state
+// against a re-computation, so a format drift reads as missing/drift instead
+// of silently lying. A future backend may instead ask codex itself
+// (app-server `hooks/list` returns `current_hash`) without changing callers.
+//
+// Single ecosystem writer: ALL iapeer writes to the host ~/.codex/config.toml
+// live in this repo (preTrustCodexCwd / removeCodexCwdTrust / here) — codex
+// itself also writes the file, so every mutation is a section-scoped
+// read-modify-write + atomic rename, never a rewrite.
+
+import { existsSync, mkdirSync, readFileSync, realpathSync } from 'fs'
+import { createHash } from 'crypto'
+import { dirname } from 'path'
+import { writeFileAtomic } from '../storage/index.ts'
+import { codexGlobalConfigPath } from './nativeMemory.ts'
+
+/** The codex-cli version the hash algorithm + key format were verified on. */
+export const TRUST_HOOKS_TESTED_CODEX_VERSION = '0.138.0'
+
+/** hooks.json event names → the snake_case labels codex keys state with
+ *  (upstream `hook_event_key_label`). */
+const EVENT_LABELS: Record<string, string> = {
+  PreToolUse: 'pre_tool_use',
+  PermissionRequest: 'permission_request',
+  PostToolUse: 'post_tool_use',
+  PreCompact: 'pre_compact',
+  PostCompact: 'post_compact',
+  SessionStart: 'session_start',
+  UserPromptSubmit: 'user_prompt_submit',
+  SubagentStart: 'subagent_start',
+  SubagentStop: 'subagent_stop',
+  Stop: 'stop',
+}
+
+/** Events where codex force-drops the matcher (upstream matcher_pattern_for_event). */
+const MATCHERLESS_EVENTS = new Set(['UserPromptSubmit', 'Stop'])
+
+export interface HookTrustEntry {
+  /** Full state key: `<source path>:<event_snake>:<group>:<handler>`. */
+  key: string
+  /** `sha256:<hex>` of the normalized hook identity. */
+  hash: string
+  event: string
+  command: string
+}
+
+export type HookTrustCheckStatus = 'trusted' | 'missing' | 'drift'
+
+export interface HookTrustCheck extends HookTrustEntry {
+  status: HookTrustCheckStatus
+  /** The hash currently in the state (when present and different). */
+  found?: string
+}
+
+export interface HooksTrustOutcome {
+  path: string // the codex global config written/read
+  source: string // the resolved hooks.json path used as the key source
+  state: 'written' | 'already' | 'failed'
+  entries: HookTrustEntry[]
+  detail?: string
+}
+
+// ─── hashing ─────────────────────────────────────────────────────────────────
+
+function sortKeysDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeysDeep)
+  if (value && typeof value === 'object') {
+    const src = value as Record<string, unknown>
+    const sorted: Record<string, unknown> = {}
+    for (const k of Object.keys(src).sort()) sorted[k] = sortKeysDeep(src[k])
+    return sorted
+  }
+  return value
+}
+
+/** Hash ONE normalized command hook the way codex does (see module header). */
+export function commandHookHash(
+  eventLabel: string,
+  matcher: string | undefined,
+  handler: { command: string; timeout?: number; statusMessage?: string },
+): string {
+  const normalized: Record<string, unknown> = {
+    type: 'command',
+    command: handler.command,
+    timeout: Math.max(1, Math.trunc(handler.timeout ?? 600)),
+    async: false,
+    ...(handler.statusMessage !== undefined ? { statusMessage: handler.statusMessage } : {}),
+  }
+  const identity: Record<string, unknown> = {
+    event_name: eventLabel,
+    ...(matcher !== undefined ? { matcher } : {}),
+    hooks: [normalized],
+  }
+  const json = JSON.stringify(sortKeysDeep(identity))
+  return `sha256:${createHash('sha256').update(json, 'utf8').digest('hex')}`
+}
+
+// ─── hooks.json → trust entries ──────────────────────────────────────────────
+
+interface RawHandler {
+  type?: unknown
+  command?: unknown
+  timeout?: unknown
+  statusMessage?: unknown
+  async?: unknown
+}
+interface RawGroup {
+  matcher?: unknown
+  hooks?: unknown
+}
+
+/**
+ * Parse a hooks.json (Claude-compatible shape codex reads) and compute the
+ * trust entries codex would record for it. `keySource` is the path codex will
+ * see the file at — pass the RESOLVED path (codex keys by realpath).
+ */
+export function computeHooksTrustEntries(hooksJsonText: string, keySource: string): HookTrustEntry[] {
+  let raw: unknown
+  try {
+    raw = JSON.parse(hooksJsonText)
+  } catch (e) {
+    throw new Error(`hooks.json is not valid JSON: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('hooks.json root must be an object')
+  const events = (raw as Record<string, unknown>).hooks
+  if (!events || typeof events !== 'object' || Array.isArray(events)) {
+    throw new Error('hooks.json must carry a "hooks" object ({"hooks": {"<Event>": [...]}})')
+  }
+  const entries: HookTrustEntry[] = []
+  for (const [eventName, groups] of Object.entries(events as Record<string, unknown>)) {
+    const label = EVENT_LABELS[eventName]
+    if (!label) throw new Error(`unknown hook event "${eventName}" (known: ${Object.keys(EVENT_LABELS).join(', ')})`)
+    if (!Array.isArray(groups)) throw new Error(`event "${eventName}" must hold an array of matcher groups`)
+    for (let g = 0; g < groups.length; g++) {
+      const group = groups[g] as RawGroup
+      if (!group || typeof group !== 'object') continue
+      const matcher =
+        !MATCHERLESS_EVENTS.has(eventName) && typeof group.matcher === 'string' ? group.matcher : undefined
+      const handlers = Array.isArray(group.hooks) ? group.hooks : []
+      for (let h = 0; h < handlers.length; h++) {
+        const handler = handlers[h] as RawHandler
+        // Mirror upstream skips — each skip still CONSUMES its index (h):
+        if (!handler || typeof handler !== 'object') continue
+        if (handler.type !== 'command') continue // prompt/agent: unsupported upstream
+        if (handler.async === true) continue // async: skipped before hashing
+        if (typeof handler.command !== 'string' || handler.command.trim() === '') continue
+        entries.push({
+          key: `${keySource}:${label}:${g}:${h}`,
+          hash: commandHookHash(label, matcher, {
+            command: handler.command,
+            timeout: typeof handler.timeout === 'number' ? handler.timeout : undefined,
+            statusMessage: typeof handler.statusMessage === 'string' ? handler.statusMessage : undefined,
+          }),
+          event: eventName,
+          command: handler.command,
+        })
+      }
+    }
+  }
+  return entries
+}
+
+// ─── global-config section surgery ───────────────────────────────────────────
+
+/** Locate the body bounds of `[hooks.state."<key>"]`: header line index and
+ *  [start, end) of the body (up to the next `[` header / EOF). null = absent. */
+function stateSectionBounds(lines: string[], key: string): { header: number; start: number; end: number } | null {
+  const wanted = `[hooks.state."${key}"]`
+  const header = lines.findIndex(l => l.trim() === wanted)
+  if (header < 0) return null
+  let end = lines.length
+  for (let i = header + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i]!)) {
+      end = i
+      break
+    }
+  }
+  return { header, start: header + 1, end }
+}
+
+function readTrustedHash(lines: string[], bounds: { start: number; end: number }): string | undefined {
+  for (let i = bounds.start; i < bounds.end; i++) {
+    const m = lines[i]!.match(/^\s*trusted_hash\s*=\s*"([^"]+)"\s*$/)
+    if (m) return m[1]
+  }
+  return undefined
+}
+
+function resolveHooksSource(hooksJsonPath: string): string {
+  // codex keys trust state on the RESOLVED path (same lesson as cwd trust:
+  // /tmp → /private/tmp made a literal entry miss). The file must exist —
+  // we parse it anyway.
+  return realpathSync(hooksJsonPath)
+}
+
+/** TOML basic strings treat `\` and `"` specially — paths carrying them would
+ *  need escaping codex-side too; refuse instead of guessing. */
+function assertTomlSafeKey(key: string): void {
+  if (key.includes('"') || key.includes('\\')) {
+    throw new Error(`hooks.json path is not TOML-key-safe (contains " or \\): ${key}`)
+  }
+}
+
+/**
+ * Pre-seed the codex hooks trust state for every command hook in the given
+ * hooks.json — the deterministic, headless replacement for the "Hooks need
+ * review → Trust all" modal. Idempotent: unchanged entries are left alone;
+ * changed hashes are updated in place; missing sections are appended.
+ */
+export function preSeedCodexHooksTrust(
+  hooksJsonPath: string,
+  env: NodeJS.ProcessEnv = process.env,
+): HooksTrustOutcome {
+  const path = codexGlobalConfigPath(env)
+  try {
+    const source = resolveHooksSource(hooksJsonPath)
+    assertTomlSafeKey(source)
+    const entries = computeHooksTrustEntries(readFileSync(source, 'utf8'), source)
+    if (entries.length === 0) {
+      return { path, source, state: 'already', entries, detail: 'no command hooks to trust' }
+    }
+    const text = existsSync(path) ? readFileSync(path, 'utf8') : ''
+    const lines = text.length ? text.split('\n') : []
+    let changed = false
+    for (const entry of entries) {
+      const bounds = stateSectionBounds(lines, entry.key)
+      if (bounds) {
+        if (readTrustedHash(lines, bounds) === entry.hash) continue
+        // replace (or insert) the trusted_hash line inside the existing section
+        let replaced = false
+        for (let i = bounds.start; i < bounds.end; i++) {
+          if (/^\s*trusted_hash\s*=/.test(lines[i]!)) {
+            lines[i] = `trusted_hash = "${entry.hash}"`
+            replaced = true
+            break
+          }
+        }
+        if (!replaced) lines.splice(bounds.start, 0, `trusted_hash = "${entry.hash}"`)
+        changed = true
+      } else {
+        if (lines.length && lines[lines.length - 1]!.trim() !== '') lines.push('')
+        lines.push(`[hooks.state."${entry.key}"]`, `trusted_hash = "${entry.hash}"`)
+        changed = true
+      }
+    }
+    if (!changed) return { path, source, state: 'already', entries }
+    mkdirSync(dirname(path), { recursive: true })
+    const outText = lines.join('\n')
+    writeFileAtomic(path, outText.endsWith('\n') ? outText : `${outText}\n`)
+    return { path, source, state: 'written', entries }
+  } catch (e) {
+    return {
+      path,
+      source: hooksJsonPath,
+      state: 'failed',
+      entries: [],
+      detail: e instanceof Error ? e.message : String(e),
+    }
+  }
+}
+
+/**
+ * Read-only drift check: for every command hook in hooks.json, compare the
+ * expected hash against the recorded state. `trusted` = match, `missing` = no
+ * state entry, `drift` = entry exists with a DIFFERENT hash (hooks.json edited
+ * after seeding, or the upstream algorithm/key format moved). Consumers (the
+ * memory provider's verify line) shell this instead of re-implementing the
+ * hash — the algorithm lives in ONE place.
+ */
+export function checkCodexHooksTrust(
+  hooksJsonPath: string,
+  env: NodeJS.ProcessEnv = process.env,
+): { path: string; source: string; checks: HookTrustCheck[] } {
+  const path = codexGlobalConfigPath(env)
+  const source = resolveHooksSource(hooksJsonPath)
+  const entries = computeHooksTrustEntries(readFileSync(source, 'utf8'), source)
+  const lines = existsSync(path) ? readFileSync(path, 'utf8').split('\n') : []
+  const checks: HookTrustCheck[] = entries.map(entry => {
+    const bounds = stateSectionBounds(lines, entry.key)
+    if (!bounds) return { ...entry, status: 'missing' }
+    const found = readTrustedHash(lines, bounds)
+    if (found === entry.hash) return { ...entry, status: 'trusted' }
+    return { ...entry, status: 'drift', found }
+  })
+  return { path, source, checks }
+}
+
+/**
+ * Reap-side counterpart for `iapeer remove`: drop every `[hooks.state."…"]`
+ * section whose key SOURCE path lies under the given cwd (resolved or literal
+ * form — a deleted cwd can no longer be resolved). Same class as
+ * removeCodexCwdTrust: a removed peer must not leave trust state behind.
+ */
+export function removeCodexHooksTrustUnder(
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): { path: string; state: 'written' | 'already' | 'failed'; removed: string[]; detail?: string } {
+  const path = codexGlobalConfigPath(env)
+  try {
+    if (!existsSync(path)) return { path, state: 'already', removed: [] }
+    let real = cwd
+    try {
+      real = realpathSync(cwd)
+    } catch {
+      /* cwd already deleted → only the literal form can match */
+    }
+    const prefixes = [...new Set([real, cwd])].map(p => (p.endsWith('/') ? p : `${p}/`))
+    const lines = readFileSync(path, 'utf8').split('\n')
+    const kept: string[] = []
+    const removed: string[] = []
+    let inDoomed = false
+    for (const line of lines) {
+      const header = line.match(/^\s*\[hooks\.state\."(.+)"\]\s*$/)
+      if (header) {
+        const key = header[1]!
+        // key = `<source path>:<event>:<group>:<handler>` — strip the 3-part
+        // positional suffix to recover the source path.
+        const m = key.match(/^(.*):[a-z_]+:\d+:\d+$/)
+        const sourcePath = m ? m[1]! : key
+        inDoomed = prefixes.some(p => sourcePath.startsWith(p))
+        if (inDoomed) {
+          removed.push(key)
+          continue
+        }
+      } else if (inDoomed && /^\s*\[/.test(line)) {
+        inDoomed = false // next section starts — stop dropping
+      }
+      if (!inDoomed) kept.push(line)
+    }
+    if (removed.length === 0) return { path, state: 'already', removed }
+    writeFileAtomic(path, kept.join('\n').replace(/\n{3,}/g, '\n\n'))
+    return { path, state: 'written', removed }
+  } catch (e) {
+    return { path, state: 'failed', removed: [], detail: e instanceof Error ? e.message : String(e) }
+  }
+}