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

packages/hooks/hooks-codex/README.md

@@ -0,0 +1,54 @@
+# @deepseek-ai/dsh-hooks-codex
+
+A cordis plugin that runs a user's existing **Codex** `hooks.json` on the harness's canonical interception seams. The **Codex dialect** half of the hooks subsystem. The dialect-agnostic primitives come from [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md); this bridge owns the Codex-specific payloads, matcher mode, and decision mapping.
+
+Codex's hook protocol is a deliberate **subset** of Claude Code's (same `hooks.json` shape):
+
+- **Five hook points only:** `PreToolUse`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, `Stop` — no subagent / notification / compaction hooks.
+- **Regex-only matchers** (no literal fast path; the matcher is always an unanchored regex).
+- **snake_case stdin payloads** with `turn_id`/`model` extras, written **without** a trailing newline.
+- **No env vars and no command substitution** (a literal `${…}` in a command survives verbatim).
+- **A block-only decision model** — `allow`/`ask` are not honored; a hook can only block, never pre-approve.
+
+A native cordis plugin could do everything this bridge does, more powerfully; the bridge exists only to run UNMODIFIED external Codex hooks faithfully (see [the interception-seams RFC](../../../docs/rfc/implemented/feature/2026-06-30-interception-seams.md)).
+
+## Config
+
+```ts
+import type { Config } from '@deepseek-ai/dsh-hooks-codex'
+const config: Config = {
+  configPath: '/path/to/.codex/hooks.json', // required
+  model: 'deepseek-v4',                      // optional: stamped on every payload (Codex includes `model`)
+  defaultTimeoutMs: 600_000,                 // optional: per-hook timeout when a hook sets none
+}
+```
+
+In a `cordis.yml`:
+
+```yaml
+- dsh-hooks-codex:
+    configPath: ./.codex/hooks.json
+    model: deepseek-v4
+```
+
+The config is parsed **once** at load; a read/parse failure is contained (logs + registers nothing). Only sync `type: 'command'` hooks run — a non-command or `async: true` hook is parsed-and-skipped with a warning. A hook accepts `timeout` or the `timeoutSec` alias. Events outside the five Codex points are dropped at parse.
+
+## Hook points → seam Decisions
+
+| Codex hook | Harness seam | Mapping |
+|---|---|---|
+| `SessionStart` | `agent/session-start` (emit) | a plain-stdout hook's output → additionalContext → `agent.inject()` |
+| `UserPromptSubmit` | `agent/prompt-submit` (waterfall) | `block` (exit 2) → `PromptDecision.block`; additionalContext → `allow` with context |
+| `PreToolUse` | `tools/pre-execute` (waterfall) | `block` → `PreToolDecision.deny` (no `allow`/`ask`) |
+| `PostToolUse` | `tools/post-execute` (waterfall) | `block` → `block` with feedback; additionalContext → `accept` with context |
+| `Stop` | `agent/turn-continuation` (waterfall) | a blocking Stop hook forces `continue` with the reason as next-step steering |
+
+Codex hardcodes a tool call's `tool_name` to `"Bash"` and `tool_input` to `{ command }` (extracted from the call's arguments, or `''` when absent). The matcher subject is the tool name (`PreToolUse`/`PostToolUse`) or the session source (`SessionStart`); `UserPromptSubmit`/`Stop` ignore matchers.
+
+## Context source
+
+Injected context carries an explicit `{ kind: 'plugin', plugin: 'hooks-codex' }` source (`agent.inject()` would otherwise default it to `{ kind: 'user' }`).
+
+## Deferred
+
+**Stop loop-guard** (`TODO(stop-loop-guard)`): as in CC, a Stop hook that unconditionally blocks would force-continue every step (`stop_hook_active` is always `false` here); the loop-guard is deferred. A hook author must self-limit until it lands.

packages/hooks/hooks-codex/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@deepseek-ai/dsh-hooks-codex",
+  "description": "Bridge plugin: run a Codex hooks.json hook config on the DeepSeek Harness interception seams",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-hook-protocol": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-bash": "workspace:^",
+    "@deepseek-ai/dsh-bash-local": "workspace:^",
+    "@deepseek-ai/dsh-hook-protocol": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/hooks/hooks-codex/src/config.ts

@@ -0,0 +1,79 @@
+/**
+ * Parse a Codex `hooks.json` into the shared {@link MatcherGroup} shape. Codex's
+ * config format is a SUBSET of Claude Code's: the same event-name → matcher-group
+ * structure and the same `{ type: 'command', command, timeout?/timeoutSec? }`
+ * hook shape, but only five events and NO command-string substitution (Codex sets
+ * no hook env vars and does not expand `${…}`). Non-command hooks (and Codex's
+ * `async: true` commands) are parsed-and-skipped with a warning.
+ *
+ * @module @deepseek-ai/dsh-hooks-codex/config
+ */
+
+import type { MatcherGroup } from '@deepseek-ai/dsh-hook-protocol'
+
+/** The five hook points Codex's engine supports. */
+export const CODEX_EVENTS = ['PreToolUse', 'PostToolUse', 'SessionStart', 'UserPromptSubmit', 'Stop'] as const
+
+/** A parsed Codex config: event name → its matcher groups (command hooks only). */
+export type CodexHookConfig = Record<string, MatcherGroup[]>
+
+/** A skipped non-command (or async) hook, surfaced so the bridge can warn. */
+export interface SkippedHook {
+  event: string
+  reason: string
+}
+
+/** The outcome of parsing one Codex config file. */
+export interface ParsedCodexConfig {
+  config: CodexHookConfig
+  skipped: SkippedHook[]
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
+}
+
+/**
+ * Parse a raw Codex `hooks.json` object into runnable {@link MatcherGroup}s.
+ * Only the five {@link CODEX_EVENTS} are honored; an unknown event is dropped.
+ * `type !== 'command'` and `async: true` command hooks are skipped (recorded in
+ * `skipped`). Malformed entries are ignored rather than thrown — a bad config
+ * must not crash boot. No command substitution (Codex does none).
+ */
+export function parseCodexConfig(raw: unknown): ParsedCodexConfig {
+  const config: CodexHookConfig = {}
+  const skipped: SkippedHook[] = []
+  const root = asObject(raw)
+  const hooksMap = root ? asObject(root.hooks) ?? root : undefined
+  if (!hooksMap) return { config, skipped }
+
+  for (const event of CODEX_EVENTS) {
+    const rawGroups = hooksMap[event]
+    if (!Array.isArray(rawGroups)) continue
+    const groups: MatcherGroup[] = []
+    for (const rawGroup of rawGroups) {
+      const group = asObject(rawGroup)
+      if (!group || !Array.isArray(group.hooks)) continue
+      const commands: MatcherGroup['hooks'] = []
+      for (const rawHook of group.hooks) {
+        const hook = asObject(rawHook)
+        if (!hook) continue
+        const type = typeof hook.type === 'string' ? hook.type : 'command'
+        if (type !== 'command') { skipped.push({ event, reason: `unsupported "${type}" hook` }); continue }
+        if (hook.async === true) { skipped.push({ event, reason: 'async hook' }); continue }
+        if (typeof hook.command !== 'string') continue
+        // Codex accepts `timeout` or the `timeoutSec` alias.
+        const timeout = typeof hook.timeout === 'number' ? hook.timeout
+          : typeof hook.timeoutSec === 'number' ? hook.timeoutSec : undefined
+        commands.push({ command: hook.command, ...timeout !== undefined ? { timeoutSec: timeout } : {} })
+      }
+      if (commands.length === 0) continue
+      groups.push({ ...typeof group.matcher === 'string' ? { matcher: group.matcher } : {}, hooks: commands })
+    }
+    if (groups.length > 0) config[event] = groups
+  }
+
+  return { config, skipped }
+}

packages/hooks/hooks-codex/src/index.ts

@@ -0,0 +1,235 @@
+/**
+ * `dsh-hooks-codex` — a bridge plugin that runs a user's existing Codex
+ * `hooks.json` on the harness's canonical interception seams. The CODEX DIALECT
+ * half of the hooks subsystem.
+ *
+ * Codex's hook protocol is a deliberate SUBSET of Claude Code's: five hook points
+ * (`PreToolUse`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, `Stop` — no
+ * subagent/notification/compaction), regex-only matchers, snake_case stdin
+ * payloads with `turn_id`/`model` extras and NO trailing newline, no env vars and
+ * no command substitution, and a block-only decision model (allow/ask are not
+ * honored — a hook can only block, never pre-approve). The dialect-agnostic
+ * primitives come from `@deepseek-ai/dsh-hook-protocol`; this bridge owns the
+ * Codex-specific payloads + matcher mode + decision mapping.
+ *
+ * @module @deepseek-ai/dsh-hooks-codex
+ */
+
+import { readFileSync } from 'node:fs'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import type { Agent, ContinuationDecision, HookContext, PromptDecision } from '@deepseek-ai/dsh-agent'
+import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
+import type { PostToolDecision, PreToolDecision, ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
+import {
+  appendHookInvoked,
+  appendHookResult,
+  matchesMatcher,
+  mergeHookOutputs,
+  runHook,
+  type HookOutput,
+  type MatcherGroup,
+  type MergedHookOutcome,
+} from '@deepseek-ai/dsh-hook-protocol'
+import { parseCodexConfig, type CodexHookConfig } from './config.ts'
+
+export const name = 'hooks-codex'
+export const inject = ['bash']
+
+/** Plugin config: where the Codex hooks.json lives + the model name for payloads. */
+export interface Config {
+  /** Path to a Codex `hooks.json`. */
+  configPath: string
+  /** The model name stamped on every payload (Codex includes `model` on each event). */
+  model?: string
+  /** Default per-hook timeout in ms when a hook sets none (Codex default: 600000). */
+  defaultTimeoutMs?: number
+}
+
+export const Config: z<Config> = z.object({
+  configPath: z.string().required(),
+  model: z.string().default(''),
+  defaultTimeoutMs: z.number().default(600_000),
+})
+
+let handlerCounter = 0
+function nextHandlerId(point: string): string {
+  return `codex:${point}:${++handlerCounter}`
+}
+
+const PLUGIN_SOURCE: MessageSource = { kind: 'plugin', plugin: 'hooks-codex' }
+
+function summarize(stderr: string): string | undefined {
+  const t = stderr.trim()
+  if (t.length === 0) return undefined
+  return t.length > 500 ? t.slice(0, 500) + '…' : t
+}
+
+export function apply(ctx: Context, config: Config): void {
+  let parsed: CodexHookConfig = {}
+  try {
+    const raw: unknown = JSON.parse(readFileSync(config.configPath, 'utf8'))
+    const result = parseCodexConfig(raw)
+    parsed = result.config
+    for (const s of result.skipped) {
+      ctx.logger.warn(`hooks-codex: skipping ${s.reason} on ${s.event} (only sync command hooks run)`)
+    }
+  } catch (error: unknown) {
+    ctx.logger.warn(`hooks-codex: could not load hook config "${config.configPath}": ${String(error)} — no hooks registered`)
+    return
+  }
+
+  const defaultTimeoutMs = config.defaultTimeoutMs ?? 600_000
+  const model = config.model ?? ''
+
+  async function runPoint(
+    point: string,
+    matchQuery: string,
+    payload: unknown,
+    opts: { agent?: Agent; turn?: number; signal?: AbortSignal },
+  ): Promise<MergedHookOutcome> {
+    const groups: MatcherGroup[] = parsed[point] ?? []
+    const outputs: HookOutput[] = []
+    for (const group of groups) {
+      // Codex matches with PURE regex (no literal fast path).
+      if (!matchesMatcher(group.matcher, matchQuery, 'codex')) continue
+      for (const hook of group.hooks) {
+        const handlerId = nextHandlerId(point)
+        const session = opts.agent?.session
+        if (session && opts.turn !== undefined) {
+          appendHookInvoked(session, {
+            turn: opts.turn, point, dialect: 'codex', handlerId,
+            ...group.matcher !== undefined ? { matcher: group.matcher } : {},
+          })
+        }
+        const { output, durationMs } = await runHook(ctx.bash, hook, {
+          payload,
+          ...opts.signal ? { signal: opts.signal } : {},
+          defaultTimeoutMs,
+          trailingNewline: false, // Codex writes stdin WITHOUT a trailing newline.
+        }, () => performance.now())
+        outputs.push(output)
+        if (session && opts.turn !== undefined) {
+          const stderrSummary = summarize(output.stderr)
+          appendHookResult(session, {
+            turn: opts.turn, point, handlerId,
+            decision: output.decision ?? (output.continue === false ? 'stop' : 'pass'),
+            ...output.exitCode !== undefined ? { exitCode: output.exitCode } : {},
+            ...stderrSummary !== undefined ? { stderrSummary } : {},
+            durationMs,
+          })
+        }
+      }
+    }
+    return mergeHookOutputs(outputs)
+  }
+
+  function contextFrom(merged: MergedHookOutcome): HookContext | undefined {
+    if (merged.additionalContext.length === 0) return undefined
+    const content: ContentBlock[] = merged.additionalContext.map(text => ({ type: 'text', text }))
+    return { content, source: PLUGIN_SOURCE }
+  }
+
+  // SessionStart: emit. Codex passes a plain-stdout hook's output as additionalContext.
+  ctx.on('agent/session-start', (agent, source) => {
+    void runPoint('SessionStart', source, { ...base(agent, 'SessionStart', model), source }, { agent })
+      .then((merged) => {
+        const context = contextFrom(merged)
+        if (context) agent.inject(context.content, { source: context.source })
+      })
+      .catch((error: unknown) => { ctx.logger.warn(`hooks-codex: SessionStart hook failed: ${String(error)}`) })
+  })
+
+  // UserPromptSubmit → PromptDecision. Codex can only BLOCK (no allow/ask).
+  ctx.on('agent/prompt-submit', async (agent, content, _source, next): Promise<PromptDecision> => {
+    const turn = lastTurn(agent)
+    const merged = await runPoint('UserPromptSubmit', '', { ...turnBase(agent, 'UserPromptSubmit', model), prompt: blocksToText(content) }, { agent, turn })
+    if (merged.decision === 'deny') return { kind: 'block', reason: merged.reason ?? 'blocked by UserPromptSubmit hook' }
+    const context = contextFrom(merged)
+    if (context) return { kind: 'allow', additionalContext: context }
+    return next()
+  })
+
+  // PreToolUse → PreToolDecision. Codex blocks only (no allow/ask honored).
+  ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
+    const turn = lastTurn(exec.agent)
+    const merged = await runPoint('PreToolUse', exec.name, preToolPayload(exec, model), { ...exec.agent ? { agent: exec.agent } : {}, turn, ...exec.signal ? { signal: exec.signal } : {} })
+    if (merged.decision === 'deny') return { kind: 'deny', reason: merged.reason ?? 'blocked by PreToolUse hook' }
+    return next()
+  })
+
+  // PostToolUse → PostToolDecision (block with feedback, or attach context).
+  ctx.on('tools/post-execute', async (exec, result, next): Promise<PostToolDecision> => {
+    const turn = lastTurn(exec.agent)
+    const merged = await runPoint('PostToolUse', exec.name, postToolPayload(exec, result, model), { ...exec.agent ? { agent: exec.agent } : {}, turn, ...exec.signal ? { signal: exec.signal } : {} })
+    const context = contextFrom(merged)
+    if (merged.decision === 'deny') {
+      return { kind: 'block', feedback: [{ type: 'text', text: merged.reason ?? 'blocked by PostToolUse hook' }], ...context ? { additionalContext: context } : {} }
+    }
+    if (context) return { kind: 'accept', additionalContext: context }
+    return next()
+  })
+
+  // Stop → ContinuationDecision. A blocking Stop hook forces continuation.
+  // TODO(stop-loop-guard): like CC, a Stop hook that unconditionally blocks would
+  // force-continue every step (`stop_hook_active` is always false here); the
+  // loop-guard (stop_hook_active + a max-consecutive cap) is deferred.
+  ctx.on('agent/turn-continuation', async (agent, turn, _default, next): Promise<ContinuationDecision> => {
+    const merged = await runPoint('Stop', '', { ...turnBase(agent, 'Stop', model), stop_hook_active: false, last_assistant_message: null }, { agent, turn })
+    if (merged.decision === 'deny' && merged.reason !== undefined) {
+      return { action: 'continue', reason: { content: [{ type: 'text', text: merged.reason }], source: PLUGIN_SOURCE } }
+    }
+    return next()
+  })
+}
+
+// --- Codex DIALECT payloads: snake_case, model on every event, turn_id on
+// turn-scoped events. ---
+
+function lastTurn(agent: Agent | undefined): number {
+  if (!agent) return 0
+  const last = [...agent.session.events].findLast(e => e.type === 'turn/start')
+  /* v8 ignore next -- the `: 0` arm is a defensive fallback: when an agent is
+     present, lastTurn is only called from the mid-turn seams, which always run
+     inside an open turn, so `last` is always a turn/start here. */
+  return last?.type === 'turn/start' ? last.data.turn : 0
+}
+
+function blocksToText(content: ContentBlock[]): string {
+  return content.filter((b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text').map(b => b.text).join('')
+}
+
+/** Base fields on every Codex payload (no turn_id). */
+function base(agent: Agent | undefined, event: string, model: string): Record<string, unknown> {
+  return {
+    session_id: agent?.session.header.id ?? '',
+    transcript_path: null,
+    cwd: agent?.session.header.cwd ?? process.cwd(),
+    hook_event_name: event,
+    model,
+    permission_mode: 'default',
+  }
+}
+
+/** Base + turn_id, for the turn-scoped events (PreToolUse/PostToolUse/UserPromptSubmit/Stop). */
+function turnBase(agent: Agent | undefined, event: string, model: string): Record<string, unknown> {
+  return { ...base(agent, event, model), turn_id: String(lastTurn(agent)) }
+}
+
+/** Extract a `command` string from a tool call's parsed arguments, else ''. */
+function commandOf(args: unknown): string {
+  if (typeof args === 'object' && args !== null && 'command' in args) {
+    const command: unknown = args.command
+    if (typeof command === 'string') return command
+  }
+  return ''
+}
+
+function preToolPayload(exec: ToolExecution, model: string): Record<string, unknown> {
+  // Codex hardcodes tool_name to "Bash" and tool_input to { command }.
+  return { ...turnBase(exec.agent, 'PreToolUse', model), tool_name: 'Bash', tool_input: { command: commandOf(exec.arguments) }, tool_use_id: exec.callId }
+}
+
+function postToolPayload(exec: ToolExecution, result: ToolExecutionResult, model: string): Record<string, unknown> {
+  return { ...turnBase(exec.agent, 'PostToolUse', model), tool_name: 'Bash', tool_input: { command: commandOf(exec.arguments) }, tool_use_id: exec.callId, tool_response: blocksToText(result.content) }
+}

packages/hooks/hooks-codex/tests/bridge.spec.ts

@@ -0,0 +1,167 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync, chmodSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore, { type SessionEvent } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentLoop, { type ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import * as HooksCodex from '@deepseek-ai/dsh-hooks-codex'
+import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+
+/**
+ * Full-loop Codex-bridge tests: scripted mock MODEL + REAL loop + REAL bash +
+ * REAL `dsh-hooks-codex` running REAL shell scripts from a temp `hooks.json`.
+ * Codex dialect specifics exercised here: regex matcher (substring), block-only
+ * decisions, the five-event subset.
+ */
+
+const dirs: string[] = []
+afterEach(() => { for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true }) })
+
+function configDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-codex-'))
+  dirs.push(dir)
+  return dir
+}
+function script(dir: string, name: string, body: string): string {
+  const path = join(dir, name)
+  writeFileSync(path, body)
+  chmodSync(path, 0o755)
+  return path
+}
+function writeHooks(dir: string, hooks: unknown): void {
+  writeFileSync(join(dir, 'hooks.json'), JSON.stringify({ hooks }))
+}
+
+async function harness(dir: string, adapter: MockAdapter): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
+  await ctx.plugin(HooksCodex, { configPath: join(dir, 'hooks.json'), model: 'test-model' })
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return ctx
+}
+
+function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'idle') { dispose(); resolve() }
+    })
+  })
+}
+function events(agent: ReactLoopAgent): SessionEvent[] { return [...agent.session.events] }
+
+describe('hooks-codex bridge', () => {
+  it('a PreToolUse hook (exit 2) denies a tool the regex matcher matches as a substring', async () => {
+    const dir = configDir()
+    const deny = script(dir, 'deny.sh', '#!/usr/bin/env bash\necho "codex blocked it" >&2\nexit 2\n')
+    // Codex regex matcher: "Bash" is /Bash/ — matches the tool name "Bash".
+    writeHooks(dir, { PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: deny }] }] })
+
+    const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'ls' }), textResponse('done')])
+    const ctx = await harness(dir, adapter)
+    let ran = false
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'no' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'run ls' }])
+    await waitForIdle(ctx, agent)
+
+    expect(ran).toBe(false)
+    const result = events(agent).find(e => e.type === 'tool/result')
+    expect(result?.type === 'tool/result' && result.data.isError).toBe(true)
+    expect(result?.type === 'tool/result' && result.data.content.some(b => b.type === 'text' && b.text.includes('codex blocked it'))).toBe(true)
+    // recorded under the codex dialect
+    expect(events(agent).some(e => e.type === 'hook/invoked' && e.data.dialect === 'codex' && e.data.point === 'PreToolUse')).toBe(true)
+  })
+
+  it('a Stop hook (exit 2) forces the turn to continue with the reason as steering', async () => {
+    const dir = configDir()
+    // Block exactly ONCE (a marker file), then allow — without a one-shot guard a
+    // hook that always exits 2 would force-continue forever (the deferred
+    // stop_hook_active loop-guard is the real fix; here we self-limit so the test
+    // exercises the continue path without looping).
+    const marker = join(dir, 'fired')
+    const cont = script(dir, 'cont.sh', `#!/usr/bin/env bash\nif [ -e "${marker}" ]; then exit 0; fi\ntouch "${marker}"\necho "keep going: address the goal" >&2\nexit 2\n`)
+    writeHooks(dir, { Stop: [{ hooks: [{ type: 'command', command: cont }] }] })
+
+    // Step 1 has no tool calls → would stop; the Stop hook forces step 2.
+    const adapter = new MockAdapter([textResponse('first answer'), textResponse('second answer after goal')])
+    const ctx = await harness(dir, adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    // The Stop hook's reason became next-step steering → a second model request ran.
+    expect(adapter.requests).toHaveLength(2)
+    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('keep going: address the goal')
+  })
+
+  it('only the five Codex events are honored — a SubagentStop entry is ignored', async () => {
+    const dir = configDir()
+    const s = script(dir, 'x.sh', '#!/usr/bin/env bash\nexit 2\n')
+    // SubagentStop is NOT a Codex event; it must be dropped (no crash, no effect).
+    writeHooks(dir, { SubagentStop: [{ hooks: [{ type: 'command', command: s }] }] })
+
+    const adapter = new MockAdapter([textResponse('fine')])
+    const ctx = await harness(dir, adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+    // Ran normally; the unknown event was dropped at parse.
+    expect(adapter.requests).toHaveLength(1)
+  })
+
+  it('a missing config registers no hooks and does not crash', async () => {
+    const dir = configDir() // no hooks.json written
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(dir, adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+    expect(adapter.requests).toHaveLength(1)
+  })
+
+  it('disposing the bridge fiber is clean (HMR safety)', async () => {
+    const dir = configDir()
+    writeHooks(dir, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'true' }] }] })
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(AgentLoop, { agents: [] })
+    await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
+    const fiber = await ctx.plugin(HooksCodex, { configPath: join(dir, 'hooks.json'), model: 'm' })
+    await fiber.dispose()
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+    expect(adapter.requests).toHaveLength(1)
+  })
+
+  it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/inject/apply', () => {
+    expect('default' in HooksCodex).toBe(false)
+    expect(HooksCodex.name).toBe('hooks-codex')
+    expect(HooksCodex.inject).toEqual(['bash'])
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(HooksCodex) as Record<string, unknown>
+    expect(unwrapped).toBe(HooksCodex)
+    expect(unwrapped.name).toBe('hooks-codex')
+    expect(unwrapped.inject).toEqual(['bash'])
+    expect(typeof unwrapped.apply).toBe('function')
+  })
+})

packages/hooks/hooks-codex/tests/config.spec.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+import { parseCodexConfig, CODEX_EVENTS } from '@deepseek-ai/dsh-hooks-codex/src/config.ts'
+
+describe('parseCodexConfig', () => {
+  it('honors only the five Codex events, dropping unknown ones', () => {
+    const { config } = parseCodexConfig({
+      PreToolUse: [{ hooks: [{ type: 'command', command: 'a.sh' }] }],
+      SubagentStop: [{ hooks: [{ type: 'command', command: 'b.sh' }] }], // not a Codex event
+      Notification: [{ hooks: [{ type: 'command', command: 'c.sh' }] }], // not a Codex event
+    })
+    expect(Object.keys(config)).toEqual(['PreToolUse'])
+    expect(CODEX_EVENTS).toContain('PreToolUse')
+    expect(CODEX_EVENTS).not.toContain('SubagentStop' as never)
+  })
+
+  it('accepts both timeout and the timeoutSec alias, no substitution', () => {
+    const { config } = parseCodexConfig({
+      Stop: [{ hooks: [{ type: 'command', command: '${NOT_SUBSTITUTED}/s.sh', timeout: 10 }] }],
+      UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'u.sh', timeoutSec: 20 }] }],
+    })
+    // Codex does NO substitution — the literal ${…} survives.
+    expect(config.Stop).toEqual([{ hooks: [{ command: '${NOT_SUBSTITUTED}/s.sh', timeoutSec: 10 }] }])
+    expect(config.UserPromptSubmit).toEqual([{ hooks: [{ command: 'u.sh', timeoutSec: 20 }] }])
+  })
+
+  it('skips non-command and async:true hooks (recorded)', () => {
+    const { config, skipped } = parseCodexConfig({
+      PreToolUse: [{ hooks: [
+        { type: 'prompt' },
+        { type: 'command', command: 'sync.sh' },
+        { type: 'command', command: 'bg.sh', async: true },
+      ] }],
+    })
+    expect(config.PreToolUse).toEqual([{ hooks: [{ command: 'sync.sh' }] }])
+    expect(skipped).toEqual([{ event: 'PreToolUse', reason: 'unsupported "prompt" hook' }, { event: 'PreToolUse', reason: 'async hook' }])
+  })
+
+  it('parses the { hooks: … } wrapper and the bare map identically', () => {
+    const groups = { Stop: [{ hooks: [{ type: 'command', command: 's.sh' }] }] }
+    expect(parseCodexConfig(groups).config).toEqual(parseCodexConfig({ hooks: groups }).config)
+  })
+
+  it('drops malformed entries and a non-object top level without throwing', () => {
+    expect(parseCodexConfig(null).config).toEqual({})
+    expect(parseCodexConfig({ PreToolUse: 'no' }).config).toEqual({})
+    expect(parseCodexConfig({ Stop: [7, { hooks: 'x' }, { hooks: [{ type: 'command', command: 9 }] }] }).config).toEqual({})
+  })
+
+  it('skips a non-object element inside a hooks array, keeping the valid sibling', () => {
+    const { config } = parseCodexConfig({ Stop: [{ hooks: [null, 7, { type: 'command', command: 's.sh' }] }] })
+    expect(config.Stop).toEqual([{ hooks: [{ command: 's.sh' }] }])
+  })
+
+  it('treats a hook with no `type` field as a command (the default)', () => {
+    const { config } = parseCodexConfig({ Stop: [{ hooks: [{ command: 's.sh' }] }] })
+    expect(config.Stop).toEqual([{ hooks: [{ command: 's.sh' }] }])
+  })
+
+  it('omits the matcher key for a match-all group', () => {
+    const { config } = parseCodexConfig({ Stop: [{ hooks: [{ type: 'command', command: 's.sh' }] }] })
+    expect('matcher' in config.Stop![0]!).toBe(false)
+  })
+
+  it('keeps a matcher when present', () => {
+    const { config } = parseCodexConfig({ PreToolUse: [{ matcher: '^Bash$', hooks: [{ type: 'command', command: 'b.sh' }] }] })
+    expect(config.PreToolUse![0]!.matcher).toBe('^Bash$')
+  })
+})

packages/hooks/hooks-codex/tests/coverage.spec.ts

@@ -0,0 +1,308 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync, chmodSync, existsSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from 'cordis'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore, { type SessionEvent } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentLoop, { type ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import * as HooksCodex from '@deepseek-ai/dsh-hooks-codex'
+import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+
+const dirs: string[] = []
+afterEach(() => { for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true }) })
+function dir(): string { const d = mkdtempSync(join(tmpdir(), 'dsh-hx-cov-')); dirs.push(d); return d }
+function sh(d: string, name: string, body: string): string {
+  const p = join(d, name); writeFileSync(p, body); chmodSync(p, 0o755); return p
+}
+function hooks(d: string, h: unknown): string {
+  writeFileSync(join(d, 'hooks.json'), JSON.stringify({ hooks: h })); return join(d, 'hooks.json')
+}
+
+async function harness(configPath: string, adapter: MockAdapter): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(LlmService); await ctx.plugin(SessionStore); await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry); await ctx.plugin(AgentRegistry); await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
+  await ctx.plugin(HooksCodex, { configPath, model: 'm' })
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return ctx
+}
+function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+  return new Promise((resolve) => { const d = ctx.on('agent/status', (s, st) => { if (s === agent && st === 'idle') { d(); resolve() } }) })
+}
+function events(agent: ReactLoopAgent): SessionEvent[] { return [...agent.session.events] }
+
+describe('hooks-codex coverage — decision mapping paths', () => {
+  it('UserPromptSubmit block (exit 2) → rejected turn; default reason on empty stderr', async () => {
+    const d = dir()
+    hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'b.sh', '#!/usr/bin/env bash\nexit 2\n') }] }] })
+    const adapter = new MockAdapter([textResponse('no')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    expect(adapter.requests).toHaveLength(0)
+    const te = events(agent).findLast(e => e.type === 'turn/end')
+    expect(te?.type === 'turn/end' && te.data.reason.kind).toBe('rejected')
+  })
+
+  it('UserPromptSubmit additionalContext is injected; a no-op hook proceeds', async () => {
+    const d = dir()
+    hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'c.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"ctx-x"}}\'\n') }] }] })
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('ctx-x')
+  })
+
+  it('SessionStart additionalContext is injected for the first request', async () => {
+    const d = dir()
+    hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: sh(d, 's.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"start-ctx"}}\'\n') }] }] })
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    await new Promise(r => setTimeout(r, 60))
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('start-ctx')
+  })
+
+  it('PostToolUse block (exit 2) → isError feedback; default reason', async () => {
+    const d = dir()
+    hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'p.sh', '#!/usr/bin/env bash\nexit 2\n') }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'ls' }), textResponse('done')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    const r = events(agent).find(e => e.type === 'tool/result')
+    expect(r?.type === 'tool/result' && r.data.isError).toBe(true)
+    expect(r?.type === 'tool/result' && r.data.content.some(b => b.type === 'text' && b.text.includes('blocked by PostToolUse hook'))).toBe(true)
+  })
+
+  it('PostToolUse additionalContext (clean exit) is attached after the result', async () => {
+    const d = dir()
+    hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'pc.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"post-ctx"}}\'\n') }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'ls' }), textResponse('done')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    expect(events(agent).some(e => e.type === 'context/message' && e.data.content.some(b => b.type === 'text' && b.text.includes('post-ctx')))).toBe(true)
+  })
+
+  it('PreToolUse for a tool call WITHOUT a command arg passes an empty command (commandOf non-object/missing arm)', async () => {
+    const d = dir()
+    hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'pre.sh', '#!/usr/bin/env bash\ncat >/dev/null\nexit 0\n') }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', {}), textResponse('done')]) // no command arg
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    let ran = false
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    expect(ran).toBe(true) // clean-exit hook allows; commandOf returned ''
+  })
+
+  it('a clean exit-0 hook records exitCode 0 and omits stderrSummary', async () => {
+    const d = dir()
+    hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'n.sh', '#!/usr/bin/env bash\nexit 0\n') }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    const res = events(agent).find(e => e.type === 'hook/result')
+    expect(res?.type === 'hook/result' && res.data.exitCode).toBe(0)
+    expect(res?.type === 'hook/result' && 'stderrSummary' in res.data).toBe(false)
+  })
+
+  it('a long stderr is truncated in the hook/result summary', async () => {
+    const d = dir()
+    hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'l.sh', '#!/usr/bin/env bash\nprintf "x%.0s" {1..600} >&2\nexit 2\n') }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    const res = events(agent).find(e => e.type === 'hook/result')
+    expect(res?.type === 'hook/result' && res.data.stderrSummary?.endsWith('…')).toBe(true)
+  })
+
+  it('warns on a skipped async hook and a direct apply() defaults the timeout', async () => {
+    const d = dir()
+    const marker = join(d, 'ran')
+    hooks(d, { UserPromptSubmit: [{ hooks: [
+      { type: 'command', command: 'bg.sh', async: true }, // skipped → warn
+      { type: 'command', command: sh(d, 'h.sh', `#!/usr/bin/env bash\ntouch "${marker}"\n`) },
+    ] }] })
+    const warn = vi.fn()
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = new Context()
+    await ctx.plugin(LlmService); await ctx.plugin(SessionStore); await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry); await ctx.plugin(AgentRegistry); await ctx.plugin(AgentLoop, { agents: [] })
+    await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
+    ctx.logger.warn = warn as never
+    // Direct apply (schema bypass) → defaultTimeoutMs ?? 600_000 + model ?? '' fallbacks.
+    HooksCodex.apply(ctx, { configPath: join(d, 'hooks.json') })
+    await new Promise(r => setTimeout(r, 10))
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    expect(existsSync(marker)).toBe(true)
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('async hook'))
+  })
+
+  it('a no-op clean hook proceeds (contextFrom empty → next)', async () => {
+    const d = dir()
+    hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'n.sh', '#!/usr/bin/env bash\nexit 0\n') }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    let ran = false
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    expect(ran).toBe(true)
+  })
+
+  it('SessionStart with no additionalContext is a no-op (contextFrom empty)', async () => {
+    const d = dir()
+    hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: sh(d, 's.sh', '#!/usr/bin/env bash\nexit 0\n') }] }] })
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    await new Promise(r => setTimeout(r, 60))
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    expect(events(agent).some(e => e.type === 'context/message')).toBe(false)
+  })
+
+  it('a throwing SessionStart inject is contained (logged)', async () => {
+    const d = dir()
+    hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: sh(d, 's.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"x"}}\'\n') }] }] })
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    const warn = vi.fn(); ctx.logger.warn = warn as never
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.inject = (() => { throw new Error('inject boom') })
+    await new Promise(r => setTimeout(r, 60))
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('SessionStart hook failed'))
+  })
+
+  it('a clean PreToolUse with no decision allows the tool (no deny)', async () => {
+    const d = dir()
+    hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'ok.sh', '#!/usr/bin/env bash\nexit 0\n') }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    let ran = false
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    expect(ran).toBe(true)
+  })
+
+  it('a non-matching regex matcher skips the hook (matchesMatcher false → continue)', async () => {
+    const d = dir()
+    // /^Edit$/ does not match the tool name "Bash" → the group is skipped.
+    hooks(d, { PreToolUse: [{ matcher: '^Edit$', hooks: [{ type: 'command', command: sh(d, 'deny.sh', '#!/usr/bin/env bash\nexit 2\n') }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    let ran = false
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    expect(ran).toBe(true) // matcher didn't match → no hook ran → tool proceeded
+    expect(events(agent).some(e => e.type === 'hook/invoked')).toBe(false)
+  })
+
+  it('a {"continue":false} hook with no decision records decision "stop"', async () => {
+    const d = dir()
+    hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 's.sh', '#!/usr/bin/env bash\necho \'{"continue":false,"stopReason":"halt"}\'\n') }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    const res = events(agent).find(e => e.type === 'hook/result')
+    expect(res?.type === 'hook/result' && res.data.decision).toBe('stop')
+  })
+
+  it('PreToolUse deny with EMPTY stderr uses the default reason (?? right arm)', async () => {
+    const d = dir()
+    hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'd.sh', '#!/usr/bin/env bash\nexit 2\n') }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    const r = events(agent).find(e => e.type === 'tool/result')
+    expect(r?.type === 'tool/result' && r.data.content.some(b => b.type === 'text' && b.text.includes('blocked by PreToolUse hook'))).toBe(true)
+  })
+
+  it('PostToolUse block AND additionalContext are surfaced together', async () => {
+    const d = dir()
+    hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'bc.sh', '#!/usr/bin/env bash\necho \'{"decision":"block","reason":"bad","hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"ctx too"}}\'\n') }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    const r = events(agent).find(e => e.type === 'tool/result')
+    expect(r?.type === 'tool/result' && r.data.isError).toBe(true)
+    expect(r?.type === 'tool/result' && r.data.content.some(b => b.type === 'text' && b.text.includes('bad'))).toBe(true)
+    expect(events(agent).some(e => e.type === 'context/message' && e.data.content.some(b => b.type === 'text' && b.text.includes('ctx too')))).toBe(true)
+  })
+
+  it('commandOf reads a non-string command arg as an empty command', async () => {
+    const d = dir()
+    // The tool-call arguments carry `command` as a NUMBER → commandOf's
+    // `typeof command === 'string'` false arm → '' (the payload's tool_input.command).
+    const cap = join(d, 'payload')
+    hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'cap.sh', `#!/usr/bin/env bash\ncat > "${cap}"\nexit 0\n`) }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 7 }), textResponse('done')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'number' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    const payload = JSON.parse(readFileSync(cap, 'utf8')) as { tool_input: { command: string } }
+    expect(payload.tool_input.command).toBe('')
+  })
+
+  it('a no-agent direct PreToolUse run uses process.cwd() and turn 0 (no session to record)', async () => {
+    const d = dir()
+    hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'd.sh', '#!/usr/bin/env bash\nexit 2\n') }] }] })
+    const ctx = await harness(join(d, 'hooks.json'), new MockAdapter([]))
+    let ran = false
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
+    const { CallId } = await import('@deepseek-ai/dsh-llm')
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'Bash', arguments: { command: 'x' } })
+    expect(ran).toBe(false) // denied
+    expect(result.isError).toBe(true)
+  })
+
+  it('a no-agent direct PostToolUse run attaches context with no session to record', async () => {
+    const d = dir()
+    hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'pc.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"x"}}\'\n') }] }] })
+    const ctx = await harness(join(d, 'hooks.json'), new MockAdapter([]))
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    const { CallId } = await import('@deepseek-ai/dsh-llm')
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'Bash', arguments: { command: 'x' } })
+    expect(result.isError).toBeFalsy()
+    expect(result.additionalContext?.content.some(b => b.type === 'text' && b.text === 'x')).toBe(true)
+  })
+
+  it('when the bash executor REJECTS, the hook/result omits exitCode (non-blocking)', async () => {
+    const d = dir()
+    hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'h.sh', '#!/usr/bin/env bash\nexit 0\n') }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    ctx.bash.run = (() => Promise.reject(new Error('executor down')))
+    ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+    const res = events(agent).find(e => e.type === 'hook/result')
+    expect(res?.type === 'hook/result' && 'exitCode' in res.data).toBe(false)
+  })
+})

packages/hooks/hooks-codex/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../hook-protocol"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../bash/bash"
+    }
+  ]
+}