Repository navigation
Expand file tree
/
Copy pathrelay.ts
More file actions
307 lines (283 loc) · 30.1 KB
/
Copy pathrelay.ts
File metadata and controls
307 lines (283 loc) · 30.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
/** Hook relay — the `token-goat hook <event>` entry point. Claude Code (and the bridge shims) invoke `token-goat hook <event>` for each hook, piping the payload as JSON on stdin and reading the response JSON from stdout. {@link relay} is that entry point: it reads stdin (with a timeout), shapes the payload into a {@link HookEvent}, runs the registered handlers via {@link runHook}, serializes the result with {@link serializeOutput}, and writes it to stdout. The cardinal rule: never block Claude Code. Any failure results in a wire response on stdout so a broken hook degrades rather than wedging the tool call: an unparseable/unreadable stdin payload degrades to an empty payload (letting each handler apply its own missing-field fallback, e.g. `sessionStartHandler`'s `GENERIC_REMINDER`; see {@link relay}), while a throwing handler or an unknown event still degrades all the way to a bare `{}` no-op pass-through. Importing this module pulls in every hook-registering module for its side-effects, so the registry is populated by the time {@link relay} runs. */
import { detectHarness, relaySeededSessionId, setRelaySeededSessionId } from './bridges/registry.js'
import { applyCallStreak } from './call_streak.js'
import { MAX_DOCUMENT_WORK_MILLIS } from './document_refusal.js'
import type { HookEvent } from './hook_registry.js'
import { runHook, serializeOutput, sessionStateKey } from './hook_registry.js'
import { echoedValue, stripUnsafeSuggestions } from './hint_suggestion_guard.js'
import { sharpenRepeatedDeny } from './hint_target.js'
import { normalizePayload, type Harness } from './hooks_cli.js'
import { commitPendingContext } from './pending_context.js'
import { requeueUndeliveredOwedSessionStart } from './session_start_owed.js'
import { applyProbeMarker } from './probe_marker.js'
import { HOOK_EVENTS, type HookEventName, type HookOutput } from './types.js'
import { loadSessionState, saveSessionState } from './session_store.js'
import { setTranscriptPath } from './session.js'
import { HOOK_PROBE_ENV, recordStat } from './stats.js'
import { readStdinJson } from './stdin_json.js'
import { shouldSuppressDuplicateVscodeHook } from './vscode_duplicate.js'
// Side-effect imports: each registers its handlers with the hook registry; hooks_recovery goes first so its advisory handlers run before any that ends the dispatch loop.
import './hooks_recovery.js'
import './hooks_read.js'
import './hooks_read_post.js'
import './hooks_grep.js'
import './hooks_glob.js'
import './hooks_edit.js'
import './hooks_write.js'
import './hooks_index.js'
import './hooks_compact.js'
import './hooks_session.js'
import './hooks_verification.js'
import './hooks_session_start.js'
import './hooks_fetch.js'
import './hooks_skill.js'
import './hooks_bash.js'
import './hooks_bash_post.js'
import './hooks_bashoutput.js'
import './hooks_taskoutput.js'
import './hooks_tool_failure.js'
import './hooks_exitplanmode.js'
import './hooks_mcp.js'
import './hooks_websearch.js'
import './hooks_screenshot.js'
import './hooks_browser_image.js'
import './hooks_agent_spawn_register.js'
import './image_shrink.js'
/** Validate that `name` is a known internal hook event name. */
function isHookEventName(name: string): name is HookEventName {
return (HOOK_EVENTS as readonly string[]).includes(name)
}
/** Shape a raw stdin payload into a {@link HookEvent}. Pulls `tool_name`, `tool_input`, and `session_id` from the Claude Code wire payload (the shapes the relay sees from every supported harness). Missing or malformed fields degrade to safe defaults (`undefined` tool name, empty input, empty session id) rather than throwing — the handlers themselves decide what to do with a thin event. */
export function buildEvent(eventName: HookEventName, payload: unknown): HookEvent {
const obj: Record<string, unknown> =
typeof payload === 'object' && payload !== null && !Array.isArray(payload)
? (payload as Record<string, unknown>)
: {}
const rawToolName = obj['tool_name']
const toolName = typeof rawToolName === 'string' && rawToolName.trim() !== '' ? rawToolName : undefined
const rawInput = obj['tool_input']
const toolInput: Record<string, unknown> =
typeof rawInput === 'object' && rawInput !== null && !Array.isArray(rawInput)
? (rawInput as Record<string, unknown>)
: {}
// Prefer snake_case `session_id` (Claude Code wire format); fall back to camelCase `sessionId` for harnesses that emit camelCase payloads (e.g. Grok, which inherits claudecode's 7-event hook wiring but sends `sessionId`). Without this, non-tool events (stop/pre_compact/notification/...) load and save session state under an empty string.
const rawSession = obj['session_id'] ?? obj['sessionId']
const sessionId = typeof rawSession === 'string' ? rawSession : ''
// agent_id (Claude Code's subagent-invocation id) is present only when this hook fired inside a subagent call; undefined on the main thread. camelCase fallback mirrors sessionId's harness-tolerance above.
const rawAgentId = obj['agent_id'] ?? obj['agentId']
// Except on subagent_start, which runs on the parent's behalf before the new agent exists: VS Code names that new agent in agent_id, and keying on it would read and write state no other hook of the parent ever sees.
const agentId = eventName !== 'subagent_start' && typeof rawAgentId === 'string' && rawAgentId !== '' ? rawAgentId : undefined
// traceparent / tracestate: W3C Trace Context headers from Claude Code / OTel spans or environment.
const rawTraceparent =
obj['traceparent'] ??
obj['traceParent'] ??
process.env['TRACEPARENT'] ??
process.env['traceparent']
const traceparent =
typeof rawTraceparent === 'string' && rawTraceparent.trim() !== '' ? rawTraceparent.trim() : undefined
const rawTracestate =
obj['tracestate'] ??
obj['traceState'] ??
process.env['TRACESTATE'] ??
process.env['tracestate']
const tracestate =
typeof rawTracestate === 'string' && rawTracestate.trim() !== '' ? rawTracestate.trim() : undefined
return { eventName, toolName, toolInput, sessionId, agentId, traceparent, tracestate, raw: obj }
}
/** Map the env-detected harness ({@link detectHarness}) onto {@link Harness}, the narrower harness identifier {@link normalizePayload} understands. Codex, Gemini, and Grok all need tool-name remapping (their harness-native names never match the canonical names registerHook(..., { toolName }) filters on -- Grok's entire wire payload is also camelCase rather than snake_case, handled in hooks_cli.ts's grok branch); 'claudecode' / 'opencode' / 'generic' payloads already use canonical tool names and pass through unchanged. Uses detectHarness() (uncached) rather than getHarnessName(): each hook invocation is a fresh, short-lived process, so there is no benefit to memoizing and no stale-cache risk to worry about. */
function harnessForNormalization(): Harness {
// detectHarness() (bridges/registry.ts) can return 'gemini' (or 'hermes' / 'openclaw') via env-var detection -- it is the single canonical implementation, unioned with the harness set compact.ts used to detect separately. installGemini() (bridges/gemini_install.ts) wires `token-goat hook <event>` directly into ~/.gemini/settings.json (no shim process like Codex's, so no other layer sets a harness flag) -- the child process inherits Gemini CLI's own environment (GEMINI_API_KEY / GOOGLE_API_KEY), so detectHarness() resolving to 'gemini' here is what makes normalizePayload()'s 'gemini' branch in hooks_cli.ts reachable for a real Gemini CLI install. hermes/openclaw still have no bridge/payload-writer, so they fall through to 'claude' unchanged for now.
const detected = detectHarness()
if (detected === 'codex') return 'codex'
if (detected === 'gemini') return 'gemini'
if (detected === 'grok') return 'grok'
// Kimi Code's shim (src/bridges/kimi.ts) sets TOKEN_GOAT_HARNESS_OVERRIDE=kimi before dispatching, so detectHarness() resolves 'kimi' here for a real Kimi install. Its payload needs remapping because Kimi's v2 tools name their path argument `path` rather than `file_path` (and its URL fetcher is `FetchURL`, not `WebFetch`).
if (detected === 'kimi') return 'kimi'
// Qwen Code's install wires `token-goat hook <event> --harness qwen` (qwen_install.ts), which sets TOKEN_GOAT_HARNESS_OVERRIDE=qwen, so detectHarness() resolves 'qwen' here. Before this branch existed, 'qwen' fell through to 'claude' and Qwen's runtime tool ids (read_file/run_shell_command/grep_search/...) reached dispatch unrenamed, matching no registered handler -- every tool-scoped hook was silently dead on Qwen (see QWEN_TOOL_NAME_MAP in hooks_cli.ts for the full producer-side derivation).
if (detected === 'qwen') return 'qwen'
// Copilot CLI's shim (src/bridges/copilot_cli.ts) sets TOKEN_GOAT_HARNESS_OVERRIDE=copilot_cli, so detectHarness() resolves it here. Its branch in normalizePayload() exists only to translate Copilot's `<server>-<tool>` MCP tool names into the `mcp__<server>__<tool>` spelling the MCP handlers gate on; the shim has already canonicalised every built-in name, so nothing else changes.
if (detected === 'copilot_cli') return 'copilot_cli'
// VS Code's agent hooks run through the shared Copilot shim, which sets TOKEN_GOAT_HARNESS_OVERRIDE=vscode when the payload carries VS Code's `hook_event_name`; its model-facing tool names (read_file, run_in_terminal, ...) need VSCODE_TOOL_NAME_MAP.
if (detected === 'vscode') return 'vscode'
// Antigravity's install wires `token-goat hook <event> --harness antigravity` (antigravity_install.ts), which sets TOKEN_GOAT_HARNESS_OVERRIDE=antigravity. Its payload nests the tool call as `toolCall: {name, args}` with PascalCase argument keys, so without this branch no tool-scoped handler would ever match.
if (detected === 'antigravity') return 'antigravity'
return 'claude'
}
/** Remove any `token-goat …` suggestion whose quoting a file path broke out of. Every hook's output passes through here, which is the reason the check lives at this seam rather than at the ~40 places that build one of these strings by concatenation: a new hint site is safe the day it is written, without its author having to know. See {@link stripUnsafeSuggestions} for what a break looks like and why a path can contain one. Only the text token-goat composes itself is rewritten. `rewriteInput` is deliberately excluded: the one command token-goat makes executable is the `token-goat compress -c '<cmd>'` wrapper, which is already quoted at its own call site, and a user command legitimately containing `$` would be destroyed by a check meant for suggestions. `rewriteOutput` is excluded for the mirror-image reason: it carries captured tool output, so a file that merely quotes a token-goat command would be edited as though it were one. A `rewriteOutput`'s out-of-band `context` is composed the way a context hint is, command suggestions and all, so it gets the same check; the rewritten body itself is left as its producer built it, and the words token-goat writes into one (the bash re-read pointer, a fold notice) name a path through fileSubject or quotedArg at their own call sites instead. A `notice` is checked too: the user reads it rather than the model, and a command in it is just as likely to be pasted into a shell. */
function safeSuggestions(output: HookOutput): HookOutput {
if (output.hookType === 'deny') return { hookType: 'deny', message: stripUnsafeSuggestions(output.message) }
if (output.hookType === 'context') return { hookType: 'context', context: stripUnsafeSuggestions(output.context), ...(output.notice !== undefined ? { notice: stripUnsafeSuggestions(output.notice) } : {}) }
if (output.hookType === 'pass' && output.notice !== undefined) return { hookType: 'pass', notice: stripUnsafeSuggestions(output.notice) }
if (output.hookType === 'rewriteOutput' && output.context !== undefined) return { ...output, context: stripUnsafeSuggestions(output.context) }
return output
}
/** How long after a {@link relayInProcess} call started a call queued behind it waits for it to settle before it runs anyway. A handler that never settles would otherwise stall every later hook call in the host process for good, where the bridges' spawn fallback kills its child after 3000 ms. Set far above what a hook call has been seen to take: of 66,625 `hook:*` rows in this machine's ledger (2026-09-20 to 2026-09-24, Claude Code, Codex and Copilot CLI; each row a whole process lifetime, node startup included) p50 was 98 ms, p99 494 ms, p99.9 2,052 ms and the maximum 31,185 ms, and a document extraction a handler starts may run for MAX_DOCUMENT_WORK_MILLIS on its own, so the wait is that plus 5,000 ms. */
export const RELAY_QUEUE_WAIT_MS = MAX_DOCUMENT_WORK_MILLIS + 5_000
/** One {@link relayInProcess} call's place in the queue. `expired` is set {@link RELAY_QUEUE_WAIT_MS} after it started; `paid` once a later call has started without waiting for it; `root` is the paid call whose hang let this one start while calls before it were still running, if any. */
interface QueuedCall {
settled: boolean
expired: boolean
paid: boolean
root: QueuedCall | undefined
}
/** Calls that have not settled, in arrival order. */
const inFlight: QueuedCall[] = []
/** Re-checks of calls waiting for their turn, run whenever a queued call settles or expires. */
const waiters = new Set<() => void>()
/** Resolves once `self` may start: when every call that arrived before it has settled, has run for {@link RELAY_QUEUE_WAIT_MS} since it started, or is excused. A call is excused when it hung past the wait and a call already started without it (`paid`), or when it started ahead of calls still running because its `root` hung and `root` still has not settled. A call that has hung past the wait is paid once, by the call that first starts without it; a call that starts while that one still hangs and calls behind it are still running starts at once, so a host whose handlers keep hanging pays one wait per hung call rather than one per call. Once the hung call settles the calls that went ahead are waited on again, every one of them and not only the last, each for at most the rest of its own wait. Each wait is counted from when the call waited on started, never from when the waiting call was queued, so a backlog of slow but healthy calls never overlaps the one running and a call arriving late behind a hung one waits only for what is left. */
function awaitTurn(self: QueuedCall, earlier: readonly QueuedCall[]): Promise<void> {
return new Promise((resolve) => {
const check = (): void => {
const blocking = earlier.filter((call) => !call.settled && !call.paid && (call.root === undefined || call.root.settled))
if (blocking.some((call) => !call.expired)) return
waiters.delete(check)
for (const call of blocking) call.paid = true
self.root = blocking[0] ?? earlier.find((call) => !call.settled && !call.paid && call.root !== undefined && !call.root.settled)?.root
resolve()
}
waiters.add(check)
check()
})
}
/** Run the hook for `eventName` against an already-parsed payload and return the serialized wire JSON response as a string (never writes to stdout/stdin). This is the in-process counterpart of {@link relay}: it contains every step relay() performs after reading stdin, factored out so bridges that already run inside a long-lived Node process (OpenClaw, opencode, pi) or that spawn their own shim process (Codex, Claude Code, Copilot CLI) can call straight into the hook registry via `import()` instead of `spawnSync`-ing a second `token-goat hook <event>` process. `harnessWaitMs`, when given, is what the harness actually waited on before it stopped waiting — Claude Code's async-detach shim classifies eligibility and prints its early `{"async":true}` marker before this function ever runs, so the shim's own `performance.now()` at that print is the true harness-visible latency; without it, the `finally` below would keep recording this call's own full process lifetime even though the harness stopped listening long before that. Omitted for every synchronous call, where process lifetime and harness wait are the same number. On *any* error — invalid event name, malformed payload, handler throw — it resolves to `'{}'` so the caller's tool call proceeds unchanged. This function never throws and never rejects. Calls within one process run one at a time, in arrival order: each loads its session's state into module-level maps, awaits the handlers, then saves, so a concurrent call's load (opencode, OpenClaw and pi can run tool calls concurrently in one host process) used to replace the maps mid-call and save one session's reads under another's key. A call waits for each call queued before it for at most {@link RELAY_QUEUE_WAIT_MS} from when that one started ({@link awaitTurn}), so one that never settles cannot stall the process's later calls; it still resolves to its own result whenever that arrives. */
/** Options for {@link relayInProcess}. `elapsedMs` replaces the default clock for the duration this call records: `performance.now()` measures this process from its own start, which is what a caller waited on only when this process was started for the call. A resident server (hook_server.ts) serves calls from a process started long before, so it passes the caller's own elapsed time plus its handling time instead. */
export interface RelayInProcessOptions {
elapsedMs?: () => number
/** Takes this call's own bookkeeping (its latency row in `stats`) instead of running it before the result is returned, so a caller able to answer first can run it after. `duration_ms` is fixed when the call ends either way. */
afterReply?: (work: () => void) => void
/** What this call's latency row records in `stats.detail`: `native` for a call the native hook client (native/tg-hook) had served. Omitted, the row carries {@link nativeFallbackDetail} of the caller's environment. */
detail?: string
}
/** The environment variable native/tg-hook sets on the Node command it falls back to, naming why the server did not answer (tg-hook's fallback.rs `REASON_ENV`). */
export const NATIVE_FALLBACK_ENV = 'TOKEN_GOAT_NATIVE_FALLBACK'
/** `native-fallback:<reason>` when this call is the Node command the native client fell back to, else undefined (a Node-form hook, or a call no hook made). The reason is checked for shape before it reaches the database, since any process can set the variable. */
export function nativeFallbackDetail(env: NodeJS.ProcessEnv = process.env): string | undefined {
const reason = env[NATIVE_FALLBACK_ENV]
return reason !== undefined && /^[a-z0-9-]{1,40}$/.test(reason) ? `native-fallback:${reason}` : undefined
}
export function relayInProcess(eventName: string, rawPayload: unknown, harnessWaitMs?: number, opts: RelayInProcessOptions = {}): Promise<string> {
// When this event reached token-goat, before any handler time or wait behind an earlier call: call_streak.ts tells a batched call from a serial one by the gap between events.
const receivedAt = Date.now()
// Read now, under the caller's environment: a resident server swaps it in only for the duration of the request.
const detail = opts.detail ?? nativeFallbackDetail()
const probe = process.env[HOOK_PROBE_ENV] === '1'
const self: QueuedCall = { settled: false, expired: false, paid: false, root: undefined }
const earlier = [...inFlight]
inFlight.push(self)
return awaitTurn(self, earlier).then(() => {
// Unref'd, so a one-shot `token-goat hook` process never waits on it to exit.
const timer = setTimeout(() => {
self.expired = true
for (const waiter of [...waiters]) waiter()
}, RELAY_QUEUE_WAIT_MS)
timer.unref()
return relayOne(eventName, rawPayload, harnessWaitMs, receivedAt, opts.elapsedMs ?? (() => performance.now()), opts.afterReply, detail, probe).finally(() => {
clearTimeout(timer)
self.settled = true
inFlight.splice(inFlight.indexOf(self), 1)
for (const waiter of [...waiters]) waiter()
})
})
}
/** One {@link relayInProcess} call, run once {@link awaitTurn} lets it start. */
async function relayOne(eventName: string, rawPayload: unknown, harnessWaitMs: number | undefined, receivedAt: number, elapsedMs: () => number, afterReply?: (work: () => void) => void, detail?: string, probe = false): Promise<string> {
if (!isHookEventName(eventName)) {
return '{}'
}
// Wall-clock from process start, not from this line: what a harness actually waits on is everything since `node` began -- module load and import resolution included -- not just dispatch, which used to be all this recorded (~28ms of an ~89ms real wait, confirmed against an external stopwatch on the production shim). `performance.now()` reads elapsed time since `performance.timeOrigin` (process start), so reading it once in the finally block below, rather than diffing two timestamps taken inside this function, is what makes the total include everything before this function ever ran -- true for every synchronous call, and for an async-detached one whose caller did not pass `harnessWaitMs`.
let spentEvent: ReturnType<typeof buildEvent> | undefined
try {
// serializeOutput needs the true harness to decide the pre_compact wire form. The CLAUDE_CODE_SESSION_ID seeding below does not change this answer: detectHarness() discounts a value relay seeded (registry.ts::relaySeededSessionId), which a long-lived host still carries from its previous call.
const harness = detectHarness()
// Codex and Gemini send harness-native tool names (e.g. `bash`, `read_file`) that never match the canonical names (`Bash`, `Read`, ...) handlers filter on via registerHook(..., { toolName }). Normalization is scoped to the two tool-scoped events: normalizePayload() treats a payload with no tool_name as invalid and returns {}, which would silently drop session_id off pre_compact/stop/notification payloads if run unconditionally.
const payload =
eventName === 'pre_tool_use' || eventName === 'post_tool_use'
? normalizePayload(rawPayload, harnessForNormalization())
: rawPayload
const event = buildEvent(eventName, payload)
spentEvent = event
// VS Code runs every hooks file it discovers, so one event can arrive here two or more times (user scope alongside project scope, or once per workspace folder). Stand down when another copy is already handling this exact event; see vscode_duplicate.ts for which cases are elected here and which the path gate already settles. Fails open by construction.
if (shouldSuppressDuplicateVscodeHook(event, harness)) return '{}'
// getSessionId() (session.ts) only ever resolves CLAUDE_CODE_SESSION_ID from the environment, which Claude Code sets itself but every other bridge (Codex, opencode, pi, Gemini, Grok, Copilot, OpenClaw) never does — those harnesses deliver the session id only on the wire, via event.sessionId above. Since each hook invocation is a fresh short-lived process, leaving the env var unseeded means every call on a non-Claude-Code harness gets a brand-new random session id from getSessionId(), breaking read-dedup/reread-diffing, context-pressure tiering, and manifest continuity for those harnesses. Seed it here, once, before any handler runs, rather than patching each getSessionId() call site individually. The pi, opencode and OpenClaw bridges run this in one long-lived host process serving session after session, so a value seeded here follows the wire id: replaced when the next event names another session, removed when one names none. A value relay did not seed is the harness's own (Claude Code sets it) and is never touched.
const envSessionId = process.env['CLAUDE_CODE_SESSION_ID']
const seededSessionId = relaySeededSessionId()
if (!envSessionId || envSessionId === seededSessionId) {
if (event.sessionId) {
process.env['CLAUDE_CODE_SESSION_ID'] = event.sessionId
setRelaySeededSessionId(event.sessionId)
} else if (seededSessionId !== undefined) {
delete process.env['CLAUDE_CODE_SESSION_ID']
setRelaySeededSessionId(undefined)
}
}
// Record the transcript path so getContextPressure() can measure real prompt size from it (compact.ts::measurePromptTokens) instead of estimating. Paired with the wire session id rather than the env var seeded just above, which the harness may have set itself and relay then leaves alone. See session.ts::setTranscriptPath.
const rawTranscriptPath = event.raw['transcript_path']
if (typeof rawTranscriptPath === 'string' && rawTranscriptPath !== '') {
setTranscriptPath(rawTranscriptPath, event.sessionId ?? '')
}
// Propagate W3C trace context to environment if delivered on the payload wire, so child subprocesses/tools can correlate spans.
if (!process.env['TRACEPARENT'] && event.traceparent) {
process.env['TRACEPARENT'] = event.traceparent
}
if (!process.env['TRACESTATE'] && event.tracestate) {
process.env['TRACESTATE'] = event.tracestate
}
// Load persisted session state before handlers run; save the mutated state after. Each is isolated in its own try/catch so a persistence failure can never suppress the handler's real output (the cardinal rule above).
const stateKey = sessionStateKey(event)
try {
loadSessionState(stateKey)
} catch {
// fail-soft: a load failure just means a cold session
}
const output = applyProbeMarker(event.eventName, safeSuggestions(sharpenRepeatedDeny(event, applyCallStreak(event, await runHook(event), receivedAt))))
// Clear the deferred-hint queue only once the text is in the output that is about to be serialized. The handler that reads that queue is advisory, and runHook discards an advisory result whenever a later non-advisory handler returns one of its own, so consuming the queue at read time deleted queued compaction manifests that then reached nothing. Checking the emitted string makes delivery a fact rather than an assumption, and leaves an undelivered hint queued for the next tool call. See pending_context.ts.
if (event.sessionId) {
const delivered = output.hookType === 'context' ? output.context : null
commitPendingContext(stateKey, delivered)
requeueUndeliveredOwedSessionStart(event, delivered)
}
try {
saveSessionState(stateKey)
} catch {
// fail-soft: a save failure must not block the tool call
}
return serializeOutput(output, event.eventName, harness, event)
} catch {
// The owed session start was claimed and carried in memory only, so a step that threw after the handler ran must put it back on the queue or it is lost for good; a no-op when the success path already settled it.
if (spentEvent !== undefined) requeueUndeliveredOwedSessionStart(spentEvent, null)
// Pass-through on every failure path — a hook must never block the caller's tool call.
return '{}'
} finally {
// recordStat() is its own already-open, already-fail-soft synchronous write (the same one every other hook-path stat in this codebase makes), so this adds no new blocking behavior -- including on the async-detach path (shim_common.ts), which prints its early marker before this module ever runs and does not wait for relayInProcess to return either way. duration_ms means one thing everywhere it is read (token-goat stats --hooks, doctor's latency check): what the caller waited on. For an async-detached call that is harnessWaitMs, captured by the shim at the moment it printed the marker and handed in by the caller; for every other call it is this call's own full elapsed time, which is also what the caller waited on since nothing detached early.
const durationMs = harnessWaitMs ?? elapsedMs()
// A diagnostic's own call (HOOK_PROBE_ENV) is not one the harness made, so it leaves no row to be counted as one.
const record = (): void => {
if (!probe) recordStat(`hook:${eventName}`, 0, 0, undefined, detail, undefined, durationMs)
}
if (afterReply) afterReply(record)
else record()
}
}
/** Run the hook for `eventName` and write the wire JSON response to stdout. Reads stdin, then delegates to {@link relayInProcess} for everything else, and prints its result. This function never throws. A stdin read failure (timeout, oversized payload, or -- the common real case on Windows -- a caller that string-interpolated a raw backslash path into the JSON text instead of escaping it, so `JSON.parse` rejects) degrades to an *empty* payload (`{}` as a parsed object) rather than abandoning the call outright: the event name is already known from `eventName` (a CLI arg, never part of the unparseable stdin), so every handler still runs with all-fields-missing input and gets the same chance to apply its own graceful fallback that "field omitted" already gives it (e.g. session_start's `sessionStartHandler` falls back to `GENERIC_REMINDER` when `cwd` is missing -- see hooks_session_start.ts). Treating a malformed payload as strictly worse than a merely incomplete one produced a silent `{"hookType":"pass"}`-shaped `{}` with zero diagnostics, indistinguishable from "no hook registered for this event," even though the event itself was perfectly identifiable and every handler was fully able to degrade gracefully. Only a genuinely unknown/invalid `eventName` -- which no fallback can route -- still short-circuits straight to the bare pass-through `{}` below. */
export async function relay(eventName: string): Promise<void> {
try {
if (!isHookEventName(eventName)) {
// Still a pass on stdout -- the cardinal rule above holds and a hook must never wedge the tool call. But this branch is a wiring mistake, not a runtime hazard: a settings.json left behind by an older build, a hand-edited entry, or a bridge shim passing its own spelling means every hook for that event does nothing at all. Nothing failed, nothing was logged, and the exit code stayed 0, so image shrinking, read dedup and the dirty-queue enqueue all quietly stopped while the index went stale with no way to see why. Say so on stderr, where normalizePayload already reports a bad payload and where the harness will not mistake it for the response.
console.error(
`[relay] unknown hook event ${echoedValue(eventName)}; nothing ran. Valid events: ${HOOK_EVENTS.join(', ')}`,
)
process.stdout.write('{}')
return
}
let rawPayload: unknown
try {
rawPayload = await readStdinJson()
} catch {
rawPayload = {}
}
process.stdout.write(await relayInProcess(eventName, rawPayload))
} catch {
// Pass-through on every remaining failure path — a hook must never block Claude Code.
process.stdout.write('{}')
}
}