Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* The hook engine: runs one dispatch's hooks as a hook chain and turns what
* they return into attributed, severity-gated, validated, applied actions.
*
* Execution (§4.4.1): a dispatch is one firing of one event. Its applicable
* hooks run one at a time, in effective order — a left fold the engine drives,
* never `next()` middleware, so no hook can stall or stop the chain. Each step
* builds a fresh shallow-frozen context from the dispatch's WORKING STATE (the
* event's input plus every action earlier steps applied), calls the handler
* inside the hook output scope with its own timeout and `AbortSignal`, then
* severity-gates and validates what it returned and hands the step's fix
* actions to the event's applier, in the order the hook returned them, before
* the next hook is called. `ctx.prior` lists what earlier steps applied.
*
* Latency is the sum of the steps, bounded by an event budget (§4.5): a step's
* timeout is its own or the budget left, whichever is shorter, and a hook whose
* step would start with no budget left is journaled `skipped`. Separate
* dispatches (two requests, two tool calls, two sessions) are independent.
*
* Failure posture: fail open, always. A throw, a rejection, a timeout or an
* invalid return value is journaled and treated as "no actions", and the next
* step sees what the failed one saw; an invalid action is journaled and
* ignored. Five consecutive failures of one hook disable it for the process
* (journal `disabled`, one stderr line); any success resets the count. A
* timeout the event budget caused, and a skipped step, do not count. There is
* no fail-closed option: a throwing hook never breaks a request or a session.
*
* Observability: one private `journal()` fans out to the local journal and —
* for the surfaces and decision values the telemetry backend accepts — to
* `recordTelemetryDecision`, the session aggregate that actually uploads. The
* two privacy rules are applied there, before the aggregate sees anything: a
* user hook's id uploads as `"user"`, and an `mcp__` tool name on a user hook's
* row is withheld. Built-in ids and tool names pass through. The local line
* keeps the real id.
*/
import { log, logStderr } from "../logger.js";
import {
type ActionResult,
type ClosedEvent,
type PlannedAction,
validateAction,
} from "./actions.js";
import type { HooksConfig, WarnSink } from "./config.js";
import { deepFreeze } from "./freeze.js";
import {
type Decision,
JOURNAL_SCHEMA_VERSION,
type JournalEntry,
type JournalEvent,
MAX_DETAIL_CHARS,
type Surface,
classifyPath,
isUploadDecision,
isUploadSurface,
recordDecision,
} from "./journal.js";
import { runInHookScope } from "./output-capture.js";
import type {
HookAction,
HookDefinition,
HostMode,
ObserveAction,
PriorAction,
RequestAction,
ResponseEndAction,
RewriteAction,
SessionAction,
Severity,
ToolCallAction,
} from "./public.js";
import type {
ApplicabilityScope,
ApplicableHook,
HookEventName,
HookRegistry,
} from "./registry.js";
import { recordTelemetryDecision, setTelemetryConsent } from "./telemetry/aggregate.js";
/* ───────────── timeouts (§4.5) ───────────── */
/** Default and maximum handler timeout per event, in ms. */
export const EVENT_TIMEOUTS: Readonly<Record<HookEventName, { default: number; max: number }>> = {
request: { default: 1_000, max: 5_000 },
toolCall: { default: 1_000, max: 5_000 },
responseRewrite: { default: 2_000, max: 10_000 },
responseEnd: { default: 5_000, max: 30_000 },
sessionStart: { default: 5_000, max: 30_000 },
sessionIdle: { default: 5_000, max: 30_000 },
sessionBlocked: { default: 5_000, max: 30_000 },
sessionEnd: { default: 1_500, max: 1_500 },
"raw.providerRequest": { default: 1_000, max: 5_000 },
// Synchronous; no timeout applies.
"raw.providerChunk": { default: 0, max: 0 },
"raw.providerStreamEnd": { default: 1_000, max: 5_000 },
"raw.response": { default: 1_000, max: 5_000 },
};
/**
* The event budget (§4.5): the time the whole hook chain of one dispatch may
* take, in ms. Each equals the event's per-hook maximum, so no dispatch's
* worst case is longer than one hook at its maximum. `null` = no budget: raw
* `providerChunk` is synchronous, and each raw `response` step keeps its own
* call and close deadlines (a budget would cut a replacement mid-decision).
*/
export const EVENT_BUDGETS: Readonly<Record<HookEventName, number | null>> = {
request: 5_000,
toolCall: 5_000,
responseRewrite: 10_000,
responseEnd: 30_000,
sessionStart: 30_000,
sessionIdle: 30_000,
sessionBlocked: 30_000,
sessionEnd: 1_500,
"raw.providerRequest": 5_000,
"raw.providerChunk": null,
"raw.providerStreamEnd": 5_000,
"raw.response": null,
};
/** A hook's timeout for an event: its own `timeoutMs` clamped to the event's maximum. */
export function timeoutFor(def: HookDefinition, event: HookEventName): number {
const bounds = EVENT_TIMEOUTS[event];
const own = def.timeoutMs;
if (typeof own !== "number" || !Number.isFinite(own) || own <= 0) return bounds.default;
return Math.min(own, bounds.max);
}
/**
* The dispatch bound of an event (§4.5): the smaller of its budget and the sum
* of its applicable hooks' step timeouts. With no budget, the sum.
*/
export function dispatchBoundMs(
event: HookEventName,
hooks: ReadonlyArray<{ hook: { def: HookDefinition } }>
): number {
let sum = 0;
for (const a of hooks) sum += timeoutFor(a.hook.def, event);
const budget = EVENT_BUDGETS[event];
return budget === null ? sum : Math.min(budget, sum);
}
/** One step's timeout: its own, or the budget left, whichever is shorter. */
export interface StepTimeout {
ms: number;
/**
* true when the earlier steps cut this step's time by MORE than `clipMarginMs`, so a
* timeout is theirs: journaled `event_budget`, not counted toward the breaker. A cut
* within the margin leaves this false even though `ms` may be a little under the
* hook's own timeout: that timeout is the hook's own and counts.
*/
clipped: boolean;
}
/** The smallest cut, in ms, that makes a budget-shortened step's timeout the budget's fault. */
export const CLIP_MARGIN_MIN_MS = 250;
/** The same margin as a share of the hook's own timeout, when that is larger. */
export const CLIP_MARGIN_SHARE = 0.1;
/** The margin never exceeds this share of the hook's own timeout (short hooks). */
export const CLIP_MARGIN_MAX_SHARE = 0.5;
/**
* How much shorter than its own timeout a step must be before a timeout is not counted:
* max(250 ms, 10 % of its own timeout), capped at half its own timeout. Without the cap a
* hook whose own timeout is 250 ms or less could never be clipped by more than the
* margin, so a slow hook before it would get it disabled.
*/
export function clipMarginMs(ownMs: number): number {
return Math.min(
ownMs * CLIP_MARGIN_MAX_SHARE,
Math.max(CLIP_MARGIN_MIN_MS, ownMs * CLIP_MARGIN_SHARE)
);
}
/**
* The step timeout of a hook whose step starts with `remaining` ms of budget
* left (`null` = no budget), or null when nothing is left: the hook is skipped.
*
* The breaker rule (§2.4): a step timeout counts toward the hook's breaker unless the
* step was clipped by MORE than `clipMarginMs(own)` — max(250 ms, 10 % of the hook's own
* timeout), capped at half its own timeout — and therefore the hook did not get its own
* full timeout. A clip within the
* margin is what the earlier steps' ordinary run time costs (the built-ins before every
* `request` hook, a 1 ms boundary between deadline and `Date.now()`); exempting it let a
* hook that hangs at its own maximum escape the breaker forever whenever any step ran
* before it. A larger clip means an earlier hook really spent the budget, and a slow hook
* A must not disable a healthy hook B.
*/
export function stepTimeout(
def: HookDefinition,
event: HookEventName,
remaining: number | null
): StepTimeout | null {
const own = timeoutFor(def, event);
if (remaining === null) return { ms: own, clipped: false };
if (remaining <= 0) return null;
if (remaining >= own) return { ms: own, clipped: false };
return { ms: remaining, clipped: own - remaining > clipMarginMs(own) };
}
/** The journal detail of a timeout or a skip the event budget caused. */
export const EVENT_BUDGET_DETAIL = "event_budget";
/** Consecutive failures that disable a hook for the process. */
export const BREAKER_THRESHOLD = 5;
/**
* Actions one hook may return from one step; the rest are journaled `invalid`
* (`too_many_actions`) and not applied. Applying a step is synchronous and runs
* outside the step's timeout, and a `responseRewrite` step re-applies every text
* action so far over a held response of up to 8 MiB, so an unbounded list could
* hold the response (and its keepalive) far past the event's budget.
*/
export const MAX_ACTIONS_PER_STEP = 64;
/** The synthetic hook id carried by a pending note on the request it is applied to. */
export const PENDING_NOTE_ID = "behavior/pending-correction";
/** Sessions the pending-note store tracks; the oldest is evicted past this. */
export const MAX_PENDING_SESSIONS = 64;
/** Journal surface per event. `responseEnd` keeps the old `onModelOutput` surface. */
export const SURFACE_OF: Readonly<Record<HookEventName, Surface>> = {
request: "request",
toolCall: "tool_call",
responseRewrite: "response",
responseEnd: "model_output",
sessionStart: "session",
sessionIdle: "session",
sessionBlocked: "session",
sessionEnd: "session",
"raw.providerRequest": "request",
"raw.providerChunk": "response",
"raw.providerStreamEnd": "response",
"raw.response": "response",
};
/** The action union each closed event returns. */
export interface EventActions {
request: RequestAction;
toolCall: ToolCallAction;
responseRewrite: RewriteAction;
responseEnd: ResponseEndAction;
sessionStart: SessionAction;
sessionIdle: SessionAction;
sessionBlocked: ObserveAction;
sessionEnd: ObserveAction;
}
/** The engine-built part of every context (§4.3 `BaseContext`). */
export interface BaseContextParts {
hookId: string;
severity: Exclude<Severity, "off">;
log(message: string): void;
/** this step's own signal: its step timeout, or the dispatch's abort */
signal: AbortSignal;
/** what earlier steps of this dispatch applied or handed on, in order (§4.4.1 rule 5) */
prior: ReadonlyArray<PriorAction>;
}
/** Facts every journal line of one dispatch shares. */
export interface JournalMeta {
model: string;
provider: string;
sessionId?: string;
toolName?: string;
}
/** Everything one journal line can carry. */
export interface JournalInput extends JournalMeta {
event: HookEventName | JournalEvent;
hookId: string;
decision: Decision;
action?: string;
surface?: Surface;
argKeys?: string[];
observedPath?: string;
expectedPath?: string;
note?: string;
detail?: string;
/** Never sent to the telemetry aggregate, whatever the surface and decision (raw-tier rows). */
localOnly?: boolean;
}
export type HookRunStatus = "ok" | "timeout" | "error" | "invalid" | "aborted" | "skipped";
/** One hook's step within a dispatch. */
export interface HookRun<A extends HookAction> {
applicable: ApplicableHook;
status: HookRunStatus;
/** Every valid action the hook returned, `warn` included, before the severity gate. */
returned: A[];
/** The actions this step applied (or handed on): what it added to `ctx.prior`. */
applied: Array<PlannedAction<A>>;
}
/** What one step's applier did with that step's fix actions. */
export interface StepApplied<A extends HookAction, S> {
/** The working state the next step starts from. */
state: S;
/** Outcomes the engine journals at this step (an applier may journal itself and return none). */
results: ReadonlyArray<ActionResult<A>>;
/** The actions that took effect, in order: appended to `ctx.prior`. */
applied: ReadonlyArray<PlannedAction<A>>;
}
/**
* One event's step functions (§4.4.1). `context` builds a step's context from
* the working state; `apply` applies one step's fix actions — valid, non-`warn`,
* in the order the hook returned them — and must not mutate `state`: the
* engine replaces the working state only when it returns, so a step is atomic.
* The one exception is `responseEnd`, whose applier delivers each action as it
* routes it; it contains a throw per action instead (`SeamHooks.end`).
* An observe-only chain passes no `apply`: nothing it returns can be applied.
*/
export interface ChainStep<A extends HookAction, S> {
context(applicable: ApplicableHook, base: BaseContextParts, state: S): object;
apply?(state: S, items: ReadonlyArray<PlannedAction<A>>): StepApplied<A, S>;
/** Extra fields for the journal line of one result this step's applier returned. */
journalExtra?(result: ActionResult<A>, before: S): Partial<JournalInput>;
/**
* Called once a hook's step ended (not for a skipped or aborted one, nor for one
* whose applier threw: that step's lines are its `apply_failed` errors), with
* the state the step saw: for journal lines that are not action outcomes.
*/
afterStep?(run: HookRun<A>, before: S): void;
}
export interface ChainOptions<S> {
/** The working state step 1 starts from. */
initial: S;
/**
* Aborting it aborts the running step's signal and starts no later step;
* the running hook ends `aborted`, unjournaled.
*/
signal?: AbortSignal;
/** `ctx.prior` of step 1: actions applied before the chain (the request's pending notes). */
prior?: ReadonlyArray<PriorAction>;
}
export interface ChainResult<A extends HookAction, S> {
/** One entry per hook the chain reached, in effective order. */
runs: Array<HookRun<A>>;
/** The working state after the last step. */
state: S;
/** Every action the chain's steps applied (or handed on), in order. */
applied: Array<PlannedAction<A>>;
}
function isUserHook(hookId: string): boolean {
return hookId.startsWith("hook:");
}
function errorText(err: unknown): string {
return err instanceof Error ? err.message : String(err);
}
function clip(text: string | undefined): string | undefined {
if (text === undefined) return undefined;
return text.length > MAX_DETAIL_CHARS ? `${text.slice(0, MAX_DETAIL_CHARS - 1)}…` : text;
}
/** The function and its `this` for one event of a definition. */
function handlerOf(
def: HookDefinition,
event: ClosedEvent
): { fn: (ctx: unknown) => unknown; self: unknown } | null {
const on = (def.on ?? {}) as Record<string, unknown>;
const entry = on[event];
if (event === "toolCall" || event === "responseRewrite") {
const container = entry as { handle?: unknown } | undefined;
return typeof container?.handle === "function"
? { fn: container.handle as (ctx: unknown) => unknown, self: container }
: null;
}
return typeof entry === "function" ? { fn: entry as (ctx: unknown) => unknown, self: on } : null;
}
interface PendingNote {
seq: number;
hookId: string;
text: string;
}
export interface HookEngineOptions {
registry: HookRegistry;
config: HooksConfig;
hostMode: HostMode;
/** Local journal writer. Default: append to `~/.claudish/behavior-journal.jsonl`. */
journalSink?: (entry: JournalEntry) => void;
/** Where the breaker's stderr line goes. Default: `logStderr`. */
warn?: WarnSink;
/**
* Deliver telemetry a previous process spooled, in the background, when
* consent is on. Default true; tests turn it off so nothing reaches the network.
*/
drainTelemetryOutbox?: boolean;
}
export class HookEngine {
readonly registry: HookRegistry;
readonly config: HooksConfig;
readonly hostMode: HostMode;
private readonly journalSink: (entry: JournalEntry) => void;
private readonly warnSink: WarnSink;
private readonly failures = new Map<string, number>();
private readonly disabled = new Set<string>();
private readonly notes = new Map<string, PendingNote[]>();
private noteSeq = 0;
constructor(opts: HookEngineOptions) {
this.registry = opts.registry;
this.config = opts.config;
this.hostMode = opts.hostMode;
this.journalSink = opts.journalSink ?? ((entry) => void recordDecision(entry));
this.warnSink = opts.warn ?? ((line) => logStderr(line));
// The engine owns the parsed config, so consent is pushed to the collector
// from here rather than re-read on the request path.
const optedIn = opts.config.telemetry?.enabled === true;
setTelemetryConsent(optedIn);
// Deliver what a PREVIOUS process spooled at exit. In the background of a
// live process, because shutdown is synchronous and cannot await a POST.
if (optedIn && opts.drainTelemetryOutbox !== false) {
void import("./telemetry/upload.js")
.then((m) => m.drainOutbox())
.catch((err) => log(`[hooks:telemetry] drain unavailable: ${err}`));
}
}
/* ───────────── selection ───────────── */
/** Applicable hooks for an event, in effective order, minus those the breaker disabled. */
select(event: HookEventName, scope: ApplicabilityScope = {}): ApplicableHook[] {
return this.registry.applicable(event, scope).filter((a) => !this.disabled.has(a.hook.id));
}
/** True when the circuit breaker disabled this hook. */
isDisabled(hookId: string): boolean {
return this.disabled.has(hookId);
}
/* ───────────── dispatch: the hook chain (§4.4.1) ───────────── */
/**
* Run one dispatch's hooks as a hook chain: one at a time, in the order of
* `hooks` (effective order), each step's fix actions applied by `step.apply`
* before the next hook is called.
*
* Per step: a hook the breaker disabled since selection is passed over with
* no journal line; a hook whose step would start with no budget left is
* journaled `skipped`; otherwise its context is built from the working state
* (shallow-frozen, with `prior`), it is called with its step timeout and its
* own signal, its return value is validated, `warn` actions and everything a
* warn-severity hook returned are journaled `warned`, and its remaining
* actions are applied atomically. An applier that throws (a claudish bug)
* leaves the working state as it was and journals each action of the step
* `error` with detail `apply_failed:<message>`.
*/
async runChain<E extends ClosedEvent, S>(
event: E,
hooks: ReadonlyArray<ApplicableHook>,
step: ChainStep<EventActions[E], S>,
meta: JournalMeta,
opts: ChainOptions<S>
): Promise<ChainResult<EventActions[E], S>> {
type A = EventActions[E];
const budget = EVENT_BUDGETS[event];
const deadline = budget === null ? null : Date.now() + budget;
const prior: PriorAction[] = [...(opts.prior ?? [])];
const runs: Array<HookRun<A>> = [];
const appliedAll: Array<PlannedAction<A>> = [];
let state = opts.initial;
for (const applicable of hooks) {
if (opts.signal?.aborted) break;
const { hook, severity } = applicable;
if (this.disabled.has(hook.id)) continue;
const timeout = stepTimeout(
hook.def,
event,
deadline === null ? null : deadline - Date.now()
);
if (timeout === null) {
this.journal({
...meta,
event,
hookId: hook.id,
decision: "skipped",
detail: EVENT_BUDGET_DETAIL,
});
runs.push({ applicable, status: "skipped", returned: [], applied: [] });
continue;
}
const seen = state;
const frozenPrior = Object.freeze([...prior]);
const run = await this.runStep<E>(
event,
applicable,
(base) => step.context(applicable, { ...base, prior: frozenPrior }, seen),
meta,
opts.signal,
timeout
);
runs.push(run);
if (run.status === "aborted") break;
// Severity gate: warn actions journal at the step; a warn hook applies nothing.
const items: Array<PlannedAction<A>> = [];
for (const action of run.returned) {
if (action.type === "warn") {
log(`[hooks] ${hook.id} warn: ${action.message}`);
this.journal({
...meta,
event,
hookId: hook.id,
action: "warn",
decision: "warned",
detail: action.message,
});
continue;
}
if (severity !== "fix") {
this.journal({
...meta,
event,
hookId: hook.id,
action: action.type,
decision: "warned",
detail: "severity warn: not applied",
});
continue;
}
items.push({ hookId: hook.id, action });
}
if (items.length === 0 || !step.apply) {
step.afterStep?.(run, seen);
continue;
}
let outcome: StepApplied<A, S>;
try {
outcome = step.apply(seen, items);
} catch (err) {
log(`[hooks] ${hook.id}: applying its actions failed: ${errorText(err)}`);
for (const item of items) {
this.journal({
...meta,
event,
hookId: hook.id,
action: item.action.type,
decision: "error",
detail: `apply_failed:${errorText(err)}`,
});
}
// No afterStep: the step's lines are the `error` ones above. An `ignored` line
// from afterStep (no repair applied) would contradict them.
continue;
}
state = outcome.state;
if (outcome.results.length > 0) {
this.recordResults(
event,
outcome.results,
meta,
step.journalExtra
? (r) => step.journalExtra?.(r as ActionResult<A>, seen) ?? {}
: undefined
);
}
for (const p of outcome.applied) {
run.applied.push(p);
appliedAll.push(p);
// Already a deep-frozen copy (`collect`): the same object the working state
// holds, so a later hook cannot write into it through ctx.prior.
prior.push(Object.freeze({ hookId: p.hookId, action: p.action }));
}
step.afterStep?.(run, seen);
}
return { runs, state, applied: appliedAll };
}
/** One step: call the handler within `timeout`, validate what it returned. */
private runStep<E extends ClosedEvent>(
event: E,
applicable: ApplicableHook,
context: (base: BaseContextParts) => object,
meta: JournalMeta,
parent: AbortSignal | undefined,
timeout: StepTimeout
): Promise<HookRun<EventActions[E]>> {
const { hook, severity } = applicable;
const done = (status: HookRunStatus, returned: Array<EventActions[E]> = []) => ({
applicable,
status,
returned,
applied: [],
});
const handler = handlerOf(hook.def, event);
if (!handler) return Promise.resolve(done("ok"));
if (parent?.aborted) return Promise.resolve(done("aborted"));
const controller = new AbortController();
const timeoutMs = timeout.ms;
const observe =
event === "toolCall" &&
(hook.def.on?.toolCall as { observe?: boolean } | undefined)?.observe === true;
return new Promise((resolveRun) => {
let settled = false;
const finish = (run: HookRun<EventActions[E]>) => {
if (settled) return;
settled = true;
clearTimeout(timer);
parent?.removeEventListener("abort", onParentAbort);
resolveRun(run);
};
const onParentAbort = () => {
controller.abort(parent?.reason ?? new Error("aborted"));
finish(done("aborted"));
};
parent?.addEventListener("abort", onParentAbort, { once: true });
// A late result is discarded: once the timer fired, `settled` is true.
const timer = setTimeout(() => {
controller.abort(new Error(`hook ${hook.id} timed out after ${timeoutMs} ms`));
this.journal({
...meta,
event,
hookId: hook.id,
decision: "timeout",
detail: timeout.clipped ? EVENT_BUDGET_DETAIL : `${timeoutMs} ms`,
});
// Clipped beyond the margin: the steps before this one spent the budget, so it is
// not this hook's failure. Within the margin it is the hook's own (stepTimeout).
if (!timeout.clipped) this.noteFailure(hook.id, meta, event);
finish(done("timeout"));
}, timeoutMs);
const base: BaseContextParts = {
hookId: hook.id,
severity,
log: (message: string) => log(`[hook ${hook.id}] ${message}`),
signal: controller.signal,
prior: [],
};
let value: unknown;
try {
const ctx = Object.freeze(context(base));
value = runInHookScope(hook.id, () => handler.fn.call(handler.self, ctx));
} catch (err) {
this.journal({
...meta,
event,
hookId: hook.id,
decision: "error",
detail: errorText(err),
});
this.noteFailure(hook.id, meta, event);
finish(done("error"));
return;
}
Promise.resolve(value).then(
(returned) => {
if (settled) return;
const result = this.collect(event, hook.id, returned, meta, observe);
if (result === null) {
this.noteFailure(hook.id, meta, event);
finish(done("invalid"));
return;
}
const actions = result.actions as Array<EventActions[E]>;
if (result.notPlainData) {
// Its other, valid actions still apply, as with any invalid action; but a
// value claudish cannot copy is a broken return, so the step counts.
this.noteFailure(hook.id, meta, event);
finish(done("invalid", actions));
return;
}
this.noteSuccess(hook.id);
finish(done("ok", actions));
},
(err: unknown) => {
if (settled) return;
this.journal({
...meta,
event,
hookId: hook.id,
decision: "error",
detail: errorText(err),
});
this.noteFailure(hook.id, meta, event);
finish(done("error"));
}
);
});
}
/**
* Validate a handler's return value. Returns the valid actions, or null when
* the value itself is invalid (not an array, not undefined).
*
* Each action is COPIED before it is validated, and the deep-frozen copy is the
* only object claudish uses from then on: the applier, stage B's held list, the
* rewrite plan and `ctx.prior` all share it. So a hook cannot change an action
* after returning it (from a timer, say) to slip past the limits checked here,
* and a getter or a Proxy cannot show validation one value and the applier
* another. A value that cannot be copied as plain data (a method, a Symbol, a
* Proxy) is journaled `invalid` (`not_plain_data`) and sets `notPlainData`,
* which counts the step toward the breaker.
*/
private collect(
event: ClosedEvent,
hookId: string,
returned: unknown,
meta: JournalMeta,
observe: boolean
): { actions: HookAction[]; notPlainData: boolean } | null {
if (returned === undefined || returned === null) return { actions: [], notPlainData: false };
if (!Array.isArray(returned)) {
this.journal({
...meta,
event,
hookId,
decision: "invalid",
detail: "return value is not an array",
});
return null;
}
const valid: HookAction[] = [];
if (returned.length > MAX_ACTIONS_PER_STEP) {
// One line for the excess, not one per action: the array is unbounded.
this.journal({
...meta,
event,
hookId,
decision: "invalid",
detail: `too_many_actions:${returned.length - MAX_ACTIONS_PER_STEP} over ${MAX_ACTIONS_PER_STEP}`,
});
}
let notPlainData = false;
for (const value of returned.slice(0, MAX_ACTIONS_PER_STEP)) {
let copy: unknown;
try {
copy = structuredClone(value);
} catch {
notPlainData = true;
let type: unknown;
try {
type = (value as { type?: unknown } | null)?.type;
} catch {
// a Proxy may throw on any read
}
this.journal({
...meta,
event,
hookId,
action: typeof type === "string" ? type : undefined,
decision: "invalid",
detail: "not_plain_data",
});
continue;
}
const checked = validateAction(event, copy, { observe });
if (checked.ok) {
valid.push(deepFreeze(checked.action));
continue;
}
const type = (copy as { type?: unknown } | null)?.type;
this.journal({
...meta,
event,
hookId,
action: typeof type === "string" ? type : undefined,
decision: "invalid",
detail: checked.reason,
});
}
return { actions: valid, notPlainData };
}
/**
* Call a synchronous predicate (`armed`, `claims`) inside the hook's scope.
* A throw, or a non-boolean, counts as `false`.
*/
callPredicate(
hookId: string,
fn: ((ctx: never) => unknown) | undefined,
self: unknown,
ctx: object,
fallback = true
): boolean {
if (typeof fn !== "function") return fallback;
try {
const value = runInHookScope(hookId, () =>
(fn as (c: object) => unknown).call(self, Object.freeze(ctx))
);
return value === true;
} catch (err) {
log(`[hooks] ${hookId} predicate threw: ${errorText(err)}`);
return false;
}
}
/* ───────────── circuit breaker ───────────── */
/** Count one failed call. The fifth in a row disables the hook for the process. */
noteFailure(hookId: string, meta: JournalMeta, event: HookEventName | JournalEvent): void {
if (this.disabled.has(hookId)) return;
const count = (this.failures.get(hookId) ?? 0) + 1;
this.failures.set(hookId, count);
if (count < BREAKER_THRESHOLD) return;
this.disabled.add(hookId);
this.journal({
...meta,
event,
hookId,
decision: "disabled",
detail: `${BREAKER_THRESHOLD} consecutive failures`,
});
this.warnSink(
`hook ${hookId} disabled after ${BREAKER_THRESHOLD} consecutive failures (see the debug log)`
);
}
/** Any success resets the consecutive-failure count. */
noteSuccess(hookId: string): void {
this.failures.delete(hookId);
}
/* ───────────── journal ───────────── */
/**
* The single fan-out: the local journal line, and — for an uploadable
* surface and decision — the telemetry aggregate, after the privacy
* projection. Fire-and-forget; journaling never sits on the request path.
*/
journal(input: JournalInput): void {
const event = input.event.startsWith("raw.") ? "raw" : (input.event as JournalEvent);
const surface = input.surface ?? SURFACE_OF[input.event as HookEventName] ?? "request";
const upload = isUploadSurface(surface);
const pathRelation = upload ? classifyPath(input.observedPath, input.expectedPath) : undefined;
if (upload && input.localOnly !== true && isUploadDecision(input.decision)) {
const user = isUserHook(input.hookId);
recordTelemetryDecision({
sessionId: input.sessionId,
model: input.model,
provider: input.provider,
surface,
decision: input.decision,
// A user hook's id is a user-chosen name, and so is an MCP server's.
ruleId: user ? "user" : input.hookId,
toolName: user && input.toolName?.startsWith("mcp__") ? undefined : input.toolName,
pathRelation,
});
}
const entry: JournalEntry = {
schema: JOURNAL_SCHEMA_VERSION,
ts: new Date().toISOString(),
event,
hookId: input.hookId,
model: input.model,
provider: input.provider,
surface,
decision: input.decision,
ruleId: input.hookId,
};
if (input.action !== undefined) entry.action = input.action;
if (input.sessionId !== undefined) entry.sessionId = input.sessionId;
if (input.toolName !== undefined) entry.toolName = input.toolName;
if (input.argKeys !== undefined) entry.argKeys = input.argKeys;
if (pathRelation !== undefined) entry.pathRelation = pathRelation;
if (
input.observedPath !== undefined ||
input.expectedPath !== undefined ||
input.note !== undefined
) {
entry.local = {
observedPath: input.observedPath,
expectedPath: input.expectedPath,
note: input.note,
};
}
const detail = clip(input.detail);
if (detail !== undefined) entry.detail = detail;
try {
this.journalSink(entry);
} catch (err) {
log(`[hooks:journal] could not record: ${errorText(err)}`);
}
}
/** Journal what the appliers decided for each planned action. */
recordResults(
event: HookEventName,
results: ReadonlyArray<ActionResult>,
meta: JournalMeta,
extra?: (result: ActionResult) => Partial<JournalInput>
): void {
for (const r of results) {
const toolName =
"tool" in r.action && typeof r.action.tool === "string" ? r.action.tool : meta.toolName;
// A repaired tool call keeps the decision the telemetry backend knows it by.
const decision: Decision =
r.action.type === "repairToolArgs" && r.decision === "matched" ? "repaired" : r.decision;
this.journal({
...meta,
toolName,
event,
hookId: r.hookId,
action: r.action.type,
decision,
detail: r.detail,
...(extra?.(r) ?? {}),
});
}
}
/* ───────────── pending notes ───────────── */
/**
* Store an `injectSystemNote` from `responseEnd` for the Claude session's
* NEXT request. Bounded to MAX_PENDING_SESSIONS sessions, oldest evicted.
*/
queueNote(sessionId: string, hookId: string, text: string): void {
const list = this.notes.get(sessionId) ?? [];
list.push({ seq: ++this.noteSeq, hookId, text });
// Re-insert so a busy session is the newest, not evicted first.
this.notes.delete(sessionId);
this.notes.set(sessionId, list);
while (this.notes.size > MAX_PENDING_SESSIONS) {
const oldest = this.notes.keys().next().value;
if (oldest === undefined) break;
this.notes.delete(oldest);
}
}
/**
* The notes pending for a session, WITHOUT removing them. They are removed by
* `consumeNotes` only once a request carrying them is accepted, so a failed
* fallback attempt cannot lose a note.
*/
peekNotes(sessionId: string | undefined): ReadonlyArray<Readonly<PendingNote>> {
if (!sessionId) return [];
return [...(this.notes.get(sessionId) ?? [])];
}
/** Remove the notes a committed request carried (by `seq`; already-removed ones are ignored). */
consumeNotes(sessionId: string, seqs: ReadonlyArray<number>): void {
const list = this.notes.get(sessionId);
if (!list) return;
const drop = new Set(seqs);
const rest = list.filter((n) => !drop.has(n.seq));
if (rest.length === 0) this.notes.delete(sessionId);
else this.notes.set(sessionId, rest);
}
}