cd9737d569
New doc-sync gate verify-export-jsdoc walks every module-level exported name under packages/*/*/src and requires description prose everywhere, plus @param per parameter and @returns on non-void annotated returns for function-like exports, public class methods, properties, and accessors. The parsing + check helpers move out of gen-cordis-catalog.ts into a shared scripts/jsdoc.ts so 'documented' means one thing on both gated surfaces. Deliberate exemptions (documented in the RFC): heritage-declared class members (the seam declaration is the doc's one home — the one checker query in an otherwise pure-AST walk), cordis plugin-protocol slots (name/inject/reusable/Config/apply, top-level and static), constructors, overload implementations, declare-module augmentation bodies, and re-export statements (checked at the defining module). The 203 under-documented exports the gate found at adoption are filled in this change, so the gate lands green; generated catalogs/graphs are regenerated for the shifted line pointers. RFC: docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
@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, 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 |
Primitives
matchesMatcher(matcher, query, mode)— match-all on absent/''/'*';claudemode treats a pure[A-Za-z0-9_|]+pattern as a literal (pipe = exact-match alternation) and anything else as a regex;codexmode is always an unanchored regex. An invalid regex matches nothing (never throws).runHook(bash, hook, options, now)— serializeoptions.payloadto the hook's stdin (with a trailing newline iffoptions.trailingNewline), mergeoptions.envafter the executor's credential scrub (thedsh-bashtrusted-plugin surface), honor the hook'stimeoutSec(elseoptions.defaultTimeoutMs— the bridge owns the default, its config defaulting to the lib'sDEFAULT_HOOK_TIMEOUT_MS10-minute reference), and decode the result (threadingoptions.expectedEventNameto the codec). Never throws: an executor rejection (infra fault) becomes aHookOutputwithexitCode: undefined(a non-blocking error).nowis injected for testable durations.parseHookOutput(exitCode, stdout, stderr, expectedEventName?)— the exit-code + structured-stdout codec. Exit0→ parse JSON stdout (lenient: non-JSON is left for the bridge); exit2→ blocking error,stderris the block reason (surfaced asdecision: 'block'); other → non-blocking error.hookSpecificOutput.permissionDecision(allow/deny/ask) overrides a legacy top-leveldecision;additionalContext/updatedInput/systemMessage/continue/stopReasonare parsed too. The schemas key thehookSpecificOutputblock byhookEventName, so passingexpectedEventName(the firing event) DISCARDS a block whosehookEventNamenames a different event — or omits it entirely — its event-scoped fields don't take effect (aPreToolUseblock on aStophook 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 firstcontinue:false, block reasons joined with\n\n,additionalContext/systemMessagesaccumulated in order.
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/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.