mirror of
https://github.com/deepseek-ai/deepseek-harness.git
synced 2026-09-09 04:02:35 +00:00
Tianyi Cui
65165b5d54
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.
73 lines
2.9 KiB
TypeScript
73 lines
2.9 KiB
TypeScript
/**
|
|
* Append helpers for the log-only `hook/*` session events — the durable record
|
|
* that a hook ran and what it decided. Thin wrappers over `session.append` so a
|
|
* bridge does not hand-build the payloads (and so the `turn`-enclosure +
|
|
* invoked/result pairing stay consistent across both bridges).
|
|
*
|
|
* `hook/*` events are log-only (not {@link SurfaceEventType}), so they carry no
|
|
* `surfaceOp` and append with no surface intent — but, like every event, they
|
|
* must sit inside an OPEN turn (the invariants oracle rejects an un-enclosed
|
|
* event). The mid-turn hook points (`PreToolUse`/`PostToolUse`/`UserPromptSubmit`/
|
|
* `Stop`) fire inside the loop's open turn by construction; `SessionStart` is the
|
|
* exception (its injected `context/message` is the durable evidence instead), so
|
|
* a bridge does NOT write `hook/*` for session-start — see the hooks RFC.
|
|
*
|
|
* @module @deepseek-ai/dsh-hook-protocol/events
|
|
*/
|
|
|
|
import type { Session } from '@deepseek-ai/dsh-session'
|
|
import type { HookDialect } from './types.ts'
|
|
|
|
/** What identifies a hook invocation across its invoked/result pair. */
|
|
export interface HookInvocation {
|
|
/** The open turn the invocation lives inside. */
|
|
turn: number
|
|
/** The hook point (`PreToolUse`, `Stop`, …). */
|
|
point: string
|
|
/** The bridge dialect that ran it. */
|
|
dialect: HookDialect
|
|
/** A stable id correlating the invoked event with its result. */
|
|
handlerId: string
|
|
/** The matcher-group pattern that selected it (absent for match-all). */
|
|
matcher?: string
|
|
}
|
|
|
|
/** The decided outcome half of the pair. */
|
|
export interface HookResultRecord {
|
|
turn: number
|
|
point: string
|
|
handlerId: string
|
|
/** The dialect-neutral decision the bridge resolved (`deny`/`allow`/`block`/…). */
|
|
decision: string
|
|
/** The process exit code (absent when the hook could not run). */
|
|
exitCode?: number
|
|
/** A truncated stderr summary (the block-reason source on exit 2). */
|
|
stderrSummary?: string
|
|
/** Wall-clock duration of the run. */
|
|
durationMs: number
|
|
}
|
|
|
|
/** Append a `hook/invoked` provenance event to `session`. */
|
|
export function appendHookInvoked(session: Session, invocation: HookInvocation): void {
|
|
session.append('hook/invoked', {
|
|
turn: invocation.turn,
|
|
point: invocation.point,
|
|
dialect: invocation.dialect,
|
|
handlerId: invocation.handlerId,
|
|
...invocation.matcher !== undefined ? { matcher: invocation.matcher } : {},
|
|
})
|
|
}
|
|
|
|
/** Append a `hook/result` outcome event to `session` (pairs with a prior `hook/invoked`). */
|
|
export function appendHookResult(session: Session, record: HookResultRecord): void {
|
|
session.append('hook/result', {
|
|
turn: record.turn,
|
|
point: record.point,
|
|
handlerId: record.handlerId,
|
|
decision: record.decision,
|
|
...record.exitCode !== undefined ? { exitCode: record.exitCode } : {},
|
|
...record.stderrSummary !== undefined ? { stderrSummary: record.stderrSummary } : {},
|
|
durationMs: record.durationMs,
|
|
})
|
|
}
|