deepseek-harness/packages/hooks/hook-protocol/README.md

@deepseek-ai/dsh-hook-protocol

English | 中文

The shared core of the Claude Code / Codex hook wire protocol. NOT a cordis plugin — it registers nothing and injects nothing. It is a library of dialect-neutral primitives the two bridge plugins (@deepseek-ai/dsh-hooks-claude, @deepseek-ai/dsh-hooks-codex) import so neither re-implements the identical halves of the protocol.

Why a shared lib at all: Codex deliberately reimplements a subset of the Claude Code hook protocol — the same hooks.json matcher-group shape, the same exit-code/stdout output contract, the same command-hook execution model. The genuinely-shared parts live here; each bridge owns only what differs.

What's shared (here) vs. per-dialect (the bridges)

Concern	Here (dsh-hook-protocol)	The bridge (dsh-hooks-claude / -codex)
Matcher test	matchesMatcher(pattern, query, mode) — literal-or-regex by mode	picks its mode (claude = literal-or-regex, codex = always regex)
Run a hook	runHook(bash, hook, opts, now) — stdin payload + env via ctx.bash, decode	builds the per-event stdin payload + the dialect's env
Decode output	parseHookOutput(exit, stdout, stderr) → neutral HookOutput	maps the neutral HookOutput onto a seam-specific typed Decision
Merge N hooks	mergeHookOutputs(outputs) → most-restrictive MergedHookOutcome	—
Durable record	appendHookInvoked / appendHookResult (hook/* session events; the result's decision/stderrSummary derive from the HookOutput here)	calls them around each invocation
Detached-run quiescence	createDetachedRuns() — track fire-and-forget run chains; drain() aborts, then awaits them	passes signal to each detached runHook, registers drain as its effect disposer

Primitives

• matchesMatcher(matcher, query, mode) — match-all on absent/''/'*'; claude mode treats a pure [A-Za-z0-9_|]+ pattern as a literal (pipe = exact-match alternation) and anything else as a regex; codex mode is always an unanchored regex. An invalid regex matches nothing (never throws).
• runHook(bash, hook, options, now) — require and forward the caller-owned options.signal, serialize options.payload to the hook's stdin (with a trailing newline iff options.trailingNewline), merge options.env after the executor's credential scrub (the dsh-bash trusted-plugin surface), honor the hook's timeoutSec (else options.defaultTimeoutMs — the bridge owns the default, its config defaulting to the lib's DEFAULT_HOOK_TIMEOUT_MS 10-minute reference), and decode the result (threading options.expectedEventName to the codec). Cancellation therefore reaches the executor's process-group kill and join boundary. Never throws: an executor rejection (infra fault) becomes a HookOutput with exitCode: undefined (a non-blocking error). now is injected for testable durations.
• parseHookOutput(exitCode, stdout, stderr, expectedEventName?) decodes exit status and structured stdout. Exit 2 blocks with stderr; other failures are non-blocking. A matching hook-specific permission decision overrides the legacy top-level decision; mismatched or missing event discriminators suppress only event-specific fields. Top-level fields remain event-agnostic, and successful non-JSON output is left to the bridge.
• mergeHookOutputs(outputs) — fold the results of every hook that matched one point: permission precedence deny > ask > allow, halt sticky on the first continue:false, block reasons joined with \n\n, additionalContext/systemMessages accumulated in order.
• createDetachedRuns() — quiescence tracking for the emit-shaped points, which run detached (no seam awaits them). The bridge tracks each run chain — the hook run PLUS its continuation — and registers drain() as its effect disposer: drain fires the tracker's abort signal (so a still-running hook process is killed via runHook, not awaited out to its timeout), then resolves once every tracked chain has settled. fiber.dispose() resolving therefore means no detached hook work is left to fire into a disposed context (defensive patterns: dispose must reach quiescence).

hook/* session events

Declaration-merged into SessionEventMap (log-only, like compact/* — NOT a SurfaceEventType, no surfaceOp): hook/invoked (a hook command ran) and hook/result (its outcome, paired by handlerId, with appendHookResult owning the decision rule). Payloads and per-event JSDoc are in the generated persistence log event catalog; stderrSummary is truncated to the record's stderrSummaryMaxChars (the bridge's config, reference default DEFAULT_STDERR_SUMMARY_MAX_CHARS = 500; omitted when empty).

Like every event they must sit inside an open turn. The mid-turn points (PreToolUse/PostToolUse/Stop) fire inside the loop's open turn by construction. SessionStart and the pre-turn UserPromptSubmit admission seam get no hook/* record; allowed context is instead evidenced by its sourced user/message — see the hooks Agent Note.

Model Experience

Indirectly, through dsh-hooks-claude and dsh-hooks-codex, which can turn parsed hook output into prompt context, blocked outcomes, or continuation feedback.

KV Cache effect

No direct invalidation; the named consumer owns any request-prefix changes.

Known Limitations and Deferred Work

• HookOutput.updatedInput is parsed but not honored — input rewrite is a deferred consistency-design problem (the pre-tool-input-rewrite Agent Note); a bridge logs + warns when a hook sets it. See src/types.ts for the full contracts.
• An invalid matcher regex matches nothing, silently — matchesMatcher never throws; surfacing the error needs a diagnostic-returning variant or parse-time validation (TODO(matcher-diagnostics)).