feat(hooks): dsh-hooks-claude + dsh-hooks-codex bridges (hooks stack PR-F)

The two bridge plugins that run a user's existing Claude Code / Codex hook
config on the harness's typed interception seams, built on the shared
dsh-hook-protocol library. A bridge is a faithfulness adapter, not a power
tool: anything it does a native cordis plugin does more powerfully — the
bridge exists only to run UNMODIFIED external hooks.

- dsh-hooks-claude: CC dialect. Seven hook points (SessionStart,
  UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart,
  SubagentStop), CC per-event stdin payloads, env + ${CLAUDE_PLUGIN_ROOT}/
  ${CLAUDE_PROJECT_DIR} substitution, literal-or-regex matcher.
- dsh-hooks-codex: Codex dialect — a deliberate subset. Five hook points,
  always-regex matcher, snake_case payloads (turn_id/model, no trailing
  newline), no env/substitution, block-only decisions.

Both map the neutral merged outcome onto the seam's typed Decision and stamp
an explicit {kind:'plugin'} source on injected context (so it is never
mislabeled as a user prompt). Config parse-failure is contained; only command
hooks run. updatedInput is logged+warned (input rewrite deferred); the Stop
loop-guard is deferred (TODO).

Tests: per-file 100% — config-parse unit branches + per-seam mappings
end-to-end through the REAL loop + REAL bash + REAL shell scripts (scripted
mock model only) + a real-Loader export-shape guard. A keyless ACP snapshot
scenario (hook-prompt-block) proves a UserPromptSubmit hook blocks a prompt
end-to-end (rejected turn -> ACP cancelled, hook/* events in the log); a
with-key e2e (hooks.e2e.ts) proves a PreToolUse hook blocks real bash
(verified on disk). The snapshot normalizer now scrubs hook/result.durationMs.

RFC: docs/rfc/implemented/feature/2026-06-30-hook-bridges.md

examples/acp-agent/cordis.snapshot.yml

@@ -83,3 +83,13 @@
 # replayed todo_write tool call resolves to a real tool during snapshot replay.
 - id: tool-todo
   name: '@deepseek-ai/dsh-tool-todo'
+
+# The Claude Code hook bridge, pointed at a `hooks.json` in the session cwd. A
+# scenario that ships `workspace/hooks.json` (copied into the cwd before the run)
+# exercises the hooks path end-to-end; every other scenario has no such file, so
+# the bridge's parse fails-soft and it registers nothing (a silent no-op — the
+# ACP app loads no logger exporter, so the warning never reaches stdout).
+- id: hooks-claude
+  name: '@deepseek-ai/dsh-hooks-claude'
+  config:
+    configPath: ./hooks.json

examples/acp-agent/cordis.yml

@@ -94,3 +94,13 @@
 # session log (todo/write), surfaced to the ACP client as a `plan` update.
 - id: tool-todo
   name: '@deepseek-ai/dsh-tool-todo'
+
+# The Claude Code hook bridge, pointed at a `hooks.json` in the session cwd. With
+# no such file present the parse fails-soft and the bridge registers nothing (a
+# silent no-op); a session whose cwd holds a `hooks.json` runs those hooks on the
+# interception seams. stdout is the ACP JSON-RPC channel — the bridge's warnings
+# go through ctx.logger (no exporter here), never to stdout.
+- id: hooks-claude
+  name: '@deepseek-ai/dsh-hooks-claude'
+  config:
+    configPath: ./hooks.json

examples/acp-agent/tests/acp.snapshot.ts

@@ -29,12 +29,22 @@ interface Scenario {
   name: string
   /** Whether the scenario drives at least one model turn (so a JSONL golden applies). */
   hasModelTurn: boolean
+  /**
+   * Whether the run persists a comparable session log to diff against the
+   * `session.jsonl` fixture. Defaults to {@link hasModelTurn} (a model turn
+   * always produces a log worth comparing). Set it independently for a scenario
+   * that produces a non-trivial log WITHOUT a model turn — e.g. a prompt blocked
+   * by a `UserPromptSubmit` hook, which opens a `rejected` turn carrying `hook/*`
+   * events but never calls the model.
+   */
+  comparesLog?: boolean
   /**
    * Whether `test:snapshot:record` regenerates this scenario's `session.jsonl`
    * from the LIVE API. `recorded` scenarios are model-driven and reproducible;
    * `authored` scenarios (a hand-written `replay.override.json` sidecar drives
    * replay — e.g. a provider error or a cancel, which the live API can't be
-   * coaxed into deterministically) are NEVER re-recorded.
+   * coaxed into deterministically — or a deterministic hook scenario whose
+   * derived empty script needs no sidecar) are NEVER re-recorded.
    */
   recorded: boolean
   /**
@@ -61,6 +71,11 @@ const SCENARIOS: Scenario[] = [
   { name: 'subagent-multi', hasModelTurn: true, recorded: true, childSessions: 2 },
   { name: 'subagent-fork', hasModelTurn: true, recorded: true, childSessions: 1 },
   { name: 'subagent-mixed', hasModelTurn: true, recorded: true, childSessions: 2 },
+  // A UserPromptSubmit hook blocks the prompt before any step runs: no model
+  // call (keyless, authored — its derived script is empty so it needs no
+  // sidecar), but it persists a `rejected` turn carrying `hook/*` events, so its
+  // log IS compared. The hooks.json riding in workspace/ drives the bridge.
+  { name: 'hook-prompt-block', hasModelTurn: false, comparesLog: true, recorded: false },
 ]
 
 /** The sibling child-fixture paths for a scenario (`session.1.jsonl` …). */
@@ -139,12 +154,15 @@ for (const scenario of SCENARIOS) {
       await expect(normalizeStdout(result.rawStdout, ctx))
         .toMatchFileSnapshot(join(dir, 'stdout.golden.jsonl'))
 
-      if (scenario.hasModelTurn) {
+      // A model turn always produces a log worth comparing; a hook scenario can
+      // produce one without a model turn (a `rejected` turn carrying `hook/*`).
+      const comparesLog = scenario.comparesLog ?? scenario.hasModelTurn
+      if (comparesLog) {
         // The harvested logs (primary-first) must match their committed fixtures
         // 1:1. Each side passes through normalizeSessionLog, scrubbed against ITS
         // OWN volatile values — the live run's via `ctx`, the committed fixture's
         // via its own header (a committed file cannot share the live run's ids).
-        expect(result.sessionLogs.length, 'a model scenario must persist a session log').toBe(childSessions + 1)
+        expect(result.sessionLogs.length, 'this scenario must persist a session log').toBe(childSessions + 1)
         const fixtureFiles = ['session.jsonl', ...Array.from({ length: childSessions }, (_, i) => `session.${i + 1}.jsonl`)]
         for (let i = 0; i < fixtureFiles.length; i++) {
           const harvested = (result.sessionLogs[i] as HarvestedLog).content

examples/acp-agent/tests/hooks.e2e.ts

@@ -0,0 +1,119 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import { Readable, Writable } from 'node:stream'
+import { mkdtemp, rm, writeFile, access } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  ClientSideConnection,
+  ndJsonStream,
+  PROTOCOL_VERSION,
+  type Agent as AcpAgent,
+  type Client,
+  type RequestPermissionRequest,
+  type RequestPermissionResponse,
+  type SessionNotification,
+} from '@agentclientprotocol/sdk'
+
+/**
+ * With-key e2e: the Claude Code hook bridge running against the REAL acp-agent
+ * subprocess and the REAL model. The example `cordis.yml` loads `dsh-hooks-claude`
+ * pointed at `./hooks.json` in the session cwd; this test writes a `hooks.json`
+ * with a PreToolUse hook that BLOCKS every bash command, then asks the live model
+ * to write a file — and verifies the WORLD (the file never appears on disk),
+ * proving the hook actually intercepted execution rather than the agent merely
+ * claiming it couldn't. Key-gated; owns and disposes its subprocess.
+ *
+ * A keyless companion lives in acp.e2e.ts (stdout purity + session/new); the
+ * full hook-fires-end-to-end transcript is the keyless `hook-prompt-block`
+ * snapshot scenario. This one closes the "green plumbing, broken product" gap:
+ * only a real model deciding to call bash exercises the PreToolUse seam live.
+ */
+
+const binScript = fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
+const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
+const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+
+interface Spawned {
+  child: ChildProcessWithoutNullStreams
+  client: ClientSideConnection
+  updates: SessionNotification['update'][]
+  stderr: string[]
+}
+
+function spawnAcpAgent(cwd: string): Spawned {
+  const child = spawn(
+    process.execPath,
+    ['--import', tsxLoader, binScript, configPath],
+    { cwd, env: { ...process.env, TSX_TSCONFIG_PATH: repoTsconfig }, stdio: ['pipe', 'pipe', 'pipe'] },
+  )
+  const stderr: string[] = []
+  child.stderr.setEncoding('utf8')
+  child.stderr.on('data', (chunk: string) => stderr.push(chunk))
+
+  const updates: SessionNotification['update'][] = []
+  const stream = ndJsonStream(
+    Writable.toWeb(child.stdin) as WritableStream<Uint8Array>,
+    Readable.toWeb(child.stdout) as ReadableStream<Uint8Array>,
+  )
+  const makeClient = (_agent: AcpAgent): Client => ({
+    sessionUpdate(params: SessionNotification): Promise<void> {
+      updates.push(params.update)
+      return Promise.resolve()
+    },
+    requestPermission(_params: RequestPermissionRequest): Promise<RequestPermissionResponse> {
+      return Promise.resolve({ outcome: { outcome: 'cancelled' } })
+    },
+  })
+  const client = new ClientSideConnection(makeClient, stream)
+  return { child, client, updates, stderr }
+}
+
+let spawned: Spawned | undefined
+let workdir: string | undefined
+
+afterEach(async () => {
+  if (spawned) {
+    spawned.child.kill('SIGKILL')
+    spawned = undefined
+  }
+  if (workdir !== undefined) await rm(workdir, { recursive: true, force: true })
+  workdir = undefined
+})
+
+describe.skipIf(!process.env.DEEPSEEK_API_KEY)('acp-agent e2e: a PreToolUse hook blocks bash (real model)', () => {
+  it('denies every bash command, so the requested file is never written (verified on disk)', async () => {
+    workdir = await mkdtemp(join(tmpdir(), 'acp-hooks-e2e-'))
+    // A PreToolUse hook that blocks EVERY tool (exit 2, no matcher = match-all).
+    // The session cwd is `workdir`, and the bridge resolves `./hooks.json` from
+    // the process cwd (the launch dir = workdir), so this is the config it loads.
+    await writeFile(join(workdir, 'hooks.json'), JSON.stringify({
+      hooks: { PreToolUse: [{ hooks: [{ type: 'command', command: 'echo "bash blocked by policy" >&2; exit 2' }] }] },
+    }))
+
+    spawned = spawnAcpAgent(workdir)
+    const { client, updates } = spawned
+
+    await client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await client.newSession({ cwd: workdir, mcpServers: [] })
+
+    const res = await client.prompt({
+      sessionId,
+      prompt: [{ type: 'text', text: 'Use the bash tool to write the exact text HOOK_FAIL into a file named proof.txt in the current directory. Then stop.' }],
+    })
+    // The turn completes normally (the block is a tool-result error fed back to
+    // the model, not a turn failure).
+    expect(['end_turn', 'max_tokens']).toContain(res.stopReason)
+
+    // Verify the WORLD: the hook denied execution, so the file must NOT exist —
+    // a keyword probe a "cheating" agent could fake in prose cannot pass this.
+    await expect(access(join(workdir, 'proof.txt'))).rejects.toThrow()
+
+    // The client still saw a tool_call stream (the model TRIED), and its result
+    // carried the hook's block reason back as an error.
+    const toolCalls = updates.filter(u => u.sessionUpdate === 'tool_call' || u.sessionUpdate === 'tool_call_update')
+    expect(toolCalls.length).toBeGreaterThan(0)
+  }, 180_000)
+})

examples/acp-agent/tests/snapshot-normalize.spec.ts

@@ -90,4 +90,21 @@ describe('normalizeSessionLog', () => {
     const out = normalizeSessionLog(`${header({ id: ctx.sessionIds[0] })}\n`, ctx)
     expect(out).toContain('{{sessionId}}')
   })
+
+  it('zeroes a hook/result durationMs (run-to-run noise) but keeps its decision', () => {
+    const ev = JSON.stringify({
+      type: 'hook/result', seq: 2, time: 5,
+      data: { turn: 1, point: 'UserPromptSubmit', handlerId: 'h', decision: 'block', exitCode: 2, durationMs: 37 },
+    })
+    const out = normalizeSessionLog(`${header({})}\n${ev}\n`, ctx)
+    expect(out).toContain('"durationMs":0')
+    expect(out).not.toContain('37')
+    expect(out).toContain('"decision":"block"') // the decision is the behavior — kept
+  })
+
+  it('leaves a non-hook event durationMs untouched (only hook/result is scrubbed)', () => {
+    const ev = JSON.stringify({ type: 'tool/result', seq: 2, time: 5, data: { durationMs: 88 } })
+    const out = normalizeSessionLog(`${header({})}\n${ev}\n`, ctx)
+    expect(out).toContain('"durationMs":88')
+  })
 })

examples/acp-agent/tests/snapshot-normalize.ts

@@ -8,7 +8,8 @@
  * Scrubbed: `randomUUID()` session ids → `{{sessionId}}`; the temp `mkdtemp`
  * cwd → `{{cwd}}` (it appears in terminal-card `_meta` and the log header);
  * JSON-RPC request `id` → a stable per-transcript sequence; the log's per-event
- * `time` (epoch ms) and header `createdAt` → 0. NOT scrubbed: the log's `seq`
+ * `time` (epoch ms) and header `createdAt` → 0; a `hook/result` event's
+ * `durationMs` (wall-clock hook runtime) → 0. NOT scrubbed: the log's `seq`
  * (deterministic — `seq = log.length`, part of the event-log contract).
  *
  * See docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md.
@@ -97,6 +98,13 @@ export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): stri
     } else if ('time' in record) {
       // Event line: zero the epoch-ms timestamp; keep seq (deterministic).
       record.time = 0
+      // A hook/result carries the hook's wall-clock runtime (`data.durationMs`),
+      // which is run-to-run noise like `time` — zero it so the golden reflects
+      // the hook's decision/exit, not how long the shell took.
+      if (record.type === 'hook/result' && record.data !== null && typeof record.data === 'object') {
+        const data = record.data as Record<string, unknown>
+        if ('durationMs' in data) data.durationMs = 0
+      }
     }
     return scrubValue(record, ctx) as Record<string, unknown>
   })

examples/acp-agent/tests/snapshots/hook-prompt-block/input.json

@@ -0,0 +1,7 @@
+{
+  "steps": [
+    { "op": "initialize" },
+    { "op": "newSession" },
+    { "op": "prompt", "text": "Delete everything in the repo." }
+  ]
+}

examples/acp-agent/tests/snapshots/hook-prompt-block/session.jsonl

@@ -0,0 +1,5 @@
+{"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}"}
+{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"hook/invoked","seq":1,"time":0,"data":{"turn":1,"point":"UserPromptSubmit","dialect":"claude","handlerId":"claude:UserPromptSubmit:1"}}
+{"type":"hook/result","seq":2,"time":0,"data":{"turn":1,"point":"UserPromptSubmit","handlerId":"claude:UserPromptSubmit:1","decision":"block","exitCode":2,"stderrSummary":"blocked by policy hook","durationMs":0}}
+{"type":"turn/end","seq":3,"time":0,"data":{"turn":1,"reason":{"kind":"rejected","reason":"blocked by policy hook"}}}

examples/acp-agent/tests/snapshots/hook-prompt-block/stdout.golden.jsonl

@@ -0,0 +1,3 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"cancelled"}}

examples/acp-agent/tests/snapshots/hook-prompt-block/workspace/hooks.json

@@ -0,0 +1,11 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          { "type": "command", "command": "echo 'blocked by policy hook' >&2; exit 2" }
+        ]
+      }
+    ]
+  }
+}