0 Fork 0

Files

T

Tianyi Cui cd49670f4e refactor(hooks): tighten the hook-protocol contract surface

Implement the tighten-hook-protocol-contract RFC (moved to implemented/):

- HookDialect narrows to 'claude' | 'codex': the 'native' variant had zero
  producers (native plugins on the seams write no hook/* provenance), and the
  dialect is defined as the bridge that ran the hook.
- HookOutput.suppressOutput is gone: the codec parsed it and every path
  discarded it with no warn and no deferral — hook stdout never enters a
  transcript, so there is nothing to suppress.
- hook/result.durationMs is gone: durable timing telemetry with no reader
  that the snapshot normalizer had to scrub as replay noise. With no duration
  to measure, runHook loses its injected now clock and the single-field
  RunHookResult wrapper — it returns the HookOutput directly. The committed
  hook fixtures had the field stripped mechanically (field-only diff); the
  stdout goldens never carried it.
- The bridges' double-defaulted defaultTimeoutMs config knob is replaced by
  one reference-default constant, DEFAULT_HOOK_TIMEOUT_MS, exported from the
  lib's runner and applied inside runHook; per-hook timeoutSec stays the
  override surface.
- The hook/result semantics move into the lib that declares the event:
  HookResultRecord now carries the decoded HookOutput and appendHookResult
  derives the decision string (decision ?? stop-on-continue:false ?? pass)
  and the 500-char stderrSummary truncation; both bridges delete their
  byte-identical private copies. The snapshot suite passes against the
  existing goldens, proving the derived values are unchanged.
- Rider: BLOCKING_EXIT_CODE is codec-internal again (zero importers).

Amend the hook-protocol-lib and hook-snapshot-matrix RFCs to the new facts,
update the lib/bridge READMEs and the session.md event tables, and retarget
the affected unit tests (including new lib-level coverage of the derivation
rules).

2026-07-04 15:44:26 +08:00

4.9 KiB

Raw Blame History

@deepseek-ai/dsh-hook-protocol

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)` — 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

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) — 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 DEFAULT_HOOK_TIMEOUT_MS, the 10-minute reference default both dialects share), and decode the result (threading options.expectedEventName to the codec). Never throws: an executor rejection (infra fault) becomes a HookOutput with exitCode: undefined (a non-blocking error).
parseHookOutput(exitCode, stdout, stderr, expectedEventName?) — the exit-code + structured-stdout codec. Exit 0 → parse JSON stdout (lenient: non-JSON is left for the bridge); exit 2 → blocking error, stderr is the block reason (surfaced as decision: 'block'); other → non-blocking error. hookSpecificOutput.permissionDecision (allow/deny/ask) overrides a legacy top-level decision; additionalContext/updatedInput/systemMessage/continue/stopReason are parsed too. The schemas key the hookSpecificOutput block by hookEventName, so passing expectedEventName (the firing event) DISCARDS a block whose hookEventName names a different event — or omits it entirely — its event-scoped fields don't take effect (a PreToolUse block on a Stop hook is malformed, and so is a discriminator-less block that would otherwise apply to any event), while the event-agnostic top-level fields still apply. Pure and total.
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.

`hook/*` session events

Declaration-merged into SessionEventMap (log-only, like compact/* — NOT a SurfaceEventType, no surfaceOp):

hook/invoked — { turn, point, dialect, matcher?, handlerId }: a hook command ran.
hook/result — { turn, point, handlerId, decision, exitCode?, stderrSummary? }: its outcome, paired by handlerId. appendHookResult owns the semantics: decision is the hook's parsed decision, else 'stop' on continue:false, else 'pass'; stderrSummary is the trimmed stderr truncated to 500 characters (omitted when empty).

Like every event they must sit inside an open turn. The mid-turn points (PreToolUse/PostToolUse/UserPromptSubmit/Stop) fire inside the loop's open turn by construction; SessionStart gets no hook/* record (its injected context/message is the durable evidence) — see the hooks RFC.

Input rewrite is parsed but not honored

HookOutput.updatedInput carries a hook's requested tool-input rewrite (CC updatedInput), but the harness does not honor it yet — input rewrite is a deferred consistency-design problem (the pre-tool-input-rewrite RFC). A bridge logs + warns when a hook sets it. See src/types.ts for the full contracts.

4.9 KiB Raw Blame History