deepseek-harness/packages/hooks/README.md

# hooks/ — hook bridges + shared protocol

The hooks subsystem lets users extend the agent at lifecycle points the way Claude Code and Codex do — by pointing a bridge plugin at an existing `hooks.json` (or settings) so those external shell hooks run faithfully. The canonical extension surface itself is the harness's typed interception seams ([the interception-seams RFC](../../docs/rfc/implemented/feature/2026-06-30-interception-seams.md)); a "native hook" is just an ordinary cordis plugin on those seams. These packages are the **bridges** that translate the external shell-hook protocol onto that same surface, plus the shared wire-protocol library they build on.

| Package | Role | Shape |
|---|---|---|
| `hook-protocol/` | Shared wire-protocol core: matcher primitive, exit-code/stdout codec, `runHook` (via `ctx.bash`), most-restrictive merge, `hook/*` session events, detached-run quiescence | library (no plugin) |
| `hooks-claude/` | Bridge for a Claude Code `hooks.json` / settings | plugin |
| `hooks-codex/` | Bridge for a Codex `hooks.json` | plugin |

Codex deliberately reimplements a *subset* of the Claude Code protocol (same `hooks.json` shape, 5 events vs CC's many, command-only, regex-only matcher, no env/substitution), so `hook-protocol` owns the genuinely-identical primitives and each bridge owns only what differs (its per-event stdin payload, env, and the mapping of a hook's neutral outcome onto the harness's typed Decisions). See [hook-protocol/README.md](hook-protocol/README.md).
feat(hooks): dsh-hook-protocol — shared Claude Code / Codex hook wire-protocol core The two hook bridges (dsh-hooks-claude, dsh-hooks-codex) would otherwise duplicate the bulk of the protocol — Codex deliberately reimplements a SUBSET of the Claude Code protocol (same hooks.json shape, exit-code/stdout contract, command-hook model). This library holds the genuinely-identical primitives; each bridge owns only what differs (per-event stdin payload, env/substitution, decision mapping). New packages/hooks/ group; hook-protocol is a LIBRARY (no plugin, registers/injects nothing): - matcher: matchesMatcher(pattern, query, mode) — the one dialect axis collapsed to a mode param (claude = literal-or-regex with pipe alternation; codex = always unanchored regex). Match-all on absent/''/''; invalid regex matches nothing. - codec: parseHookOutput(exit, stdout, stderr) → dialect-neutral HookOutput. Exit 0 → lenient JSON; exit 2 → blocking error (stderr = reason, surfaced as decision:'block'); other → non-blocking. Parses the CC superset (continue/stopReason/decision/hookSpecificOutput.{permissionDecision, additionalContext,updatedInput}/systemMessage); permissionDecision overrides the legacy top-level decision. - runner: runHook(bash, hook, opts, now) — runs a command hook via ctx.bash (stdin payload + trusted-plugin env), honors timeoutSec, never throws (executor reject → non-blocking-error HookOutput). Injected clock for testable durations. - merge: mergeHookOutputs — most-restrictive fold (deny>ask>allow, sticky stop, block reasons joined, context/system-messages accumulated). - hook/ session events (declaration-merged into SessionEventMap, log-only like compact/) + appendHookInvoked/appendHookResult helpers. updatedInput is parsed but NOT honored (deferred pre-tool-input-rewrite RFC); a bridge logs+warns. 47 unit tests at per-file 100% (matcher per-mode, codec per exit-code/field, runner plumbing w/ stub executor, merge precedence, hook/ helpers). RFC: implemented/feature/2026-06-30-hook-protocol-lib.md. 2026-07-01 00:38:06 +08:00			`# hooks/ — hook bridges + shared protocol`

			The hooks subsystem lets users extend the agent at lifecycle points the way Claude Code and Codex do — by pointing a bridge plugin at an existing `hooks.json` (or settings) so those external shell hooks run faithfully. The canonical extension surface itself is the harness's typed interception seams ([the interception-seams RFC](../../docs/rfc/implemented/feature/2026-06-30-interception-seams.md)); a "native hook" is just an ordinary cordis plugin on those seams. These packages are the bridges that translate the external shell-hook protocol onto that same surface, plus the shared wire-protocol library they build on.

			`\| Package \| Role \| Shape \|`
			`\|---\|---\|---\|`
fix(hooks): drain detached hook runs on bridge dispose The emit-shaped hook points (SessionStart, SubagentStart, SubagentStop) run fire-and-forget: no seam awaits the run chain, so disposing a bridge could strand a live hook process and let a late continuation inject into a disposed context. The floating continuation also made the coverage gate racy: the only coverage of the SubagentStart continuation's no-context branch arm rode on an un-awaited .then, and on a loaded CI runner the fork's per-file coverage snapshot beat it — master run 28798191671 failed the 100% branch gate on hooks-claude/src/index.ts at 99.03% (uncovered line 336) with the identical tree passing the PR run three minutes earlier. New shared primitive createDetachedRuns() in dsh-hook-protocol: a bridge tracks each detached run chain, passes the tracker's abort signal to runHook, and registers drain() as its effect disposer — drain aborts still-running hook processes (a kill via the bash seam, not a wait out to the 10-minute default hook timeout), then resolves once every chain has settled. fiber.dispose() resolving now means the bridge's detached work is quiescent (docs/defensive-patterns.md). The subagent marker test disposes the bridge as its sync point, so the formerly racy branch arm is executed deterministically before the file's coverage snapshot; new tests pin abort-on-dispose promptness for both bridges and the tracker's settle/drain contract in hook-protocol. 2026-07-06 23:27:54 +08:00			\| `hook-protocol/` \| Shared wire-protocol core: matcher primitive, exit-code/stdout codec, `runHook` (via `ctx.bash`), most-restrictive merge, `hook/*` session events, detached-run quiescence \| library (no plugin) \|
feat(hooks): dsh-hook-protocol — shared Claude Code / Codex hook wire-protocol core The two hook bridges (dsh-hooks-claude, dsh-hooks-codex) would otherwise duplicate the bulk of the protocol — Codex deliberately reimplements a SUBSET of the Claude Code protocol (same hooks.json shape, exit-code/stdout contract, command-hook model). This library holds the genuinely-identical primitives; each bridge owns only what differs (per-event stdin payload, env/substitution, decision mapping). New packages/hooks/ group; hook-protocol is a LIBRARY (no plugin, registers/injects nothing): - matcher: matchesMatcher(pattern, query, mode) — the one dialect axis collapsed to a mode param (claude = literal-or-regex with pipe alternation; codex = always unanchored regex). Match-all on absent/''/''; invalid regex matches nothing. - codec: parseHookOutput(exit, stdout, stderr) → dialect-neutral HookOutput. Exit 0 → lenient JSON; exit 2 → blocking error (stderr = reason, surfaced as decision:'block'); other → non-blocking. Parses the CC superset (continue/stopReason/decision/hookSpecificOutput.{permissionDecision, additionalContext,updatedInput}/systemMessage); permissionDecision overrides the legacy top-level decision. - runner: runHook(bash, hook, opts, now) — runs a command hook via ctx.bash (stdin payload + trusted-plugin env), honors timeoutSec, never throws (executor reject → non-blocking-error HookOutput). Injected clock for testable durations. - merge: mergeHookOutputs — most-restrictive fold (deny>ask>allow, sticky stop, block reasons joined, context/system-messages accumulated). - hook/ session events (declaration-merged into SessionEventMap, log-only like compact/) + appendHookInvoked/appendHookResult helpers. updatedInput is parsed but NOT honored (deferred pre-tool-input-rewrite RFC); a bridge logs+warns. 47 unit tests at per-file 100% (matcher per-mode, codec per exit-code/field, runner plumbing w/ stub executor, merge precedence, hook/ helpers). RFC: implemented/feature/2026-06-30-hook-protocol-lib.md. 2026-07-01 00:38:06 +08:00			\| `hooks-claude/` \| Bridge for a Claude Code `hooks.json` / settings \| plugin \|
			\| `hooks-codex/` \| Bridge for a Codex `hooks.json` \| plugin \|

			Codex deliberately reimplements a subset of the Claude Code protocol (same `hooks.json` shape, 5 events vs CC's many, command-only, regex-only matcher, no env/substitution), so `hook-protocol` owns the genuinely-identical primitives and each bridge owns only what differs (its per-event stdin payload, env, and the mapping of a hook's neutral outcome onto the harness's typed Decisions). See [hook-protocol/README.md](hook-protocol/README.md).