@sema-agent/core 5.55.0 → 5.57.0

package/dist/core/hooks.d.ts

@@ -25,6 +25,23 @@ import type { WiringLegKind } from "./wiring-manifest.js";
  *
  * All feedback the model should see (a block reason, injected context) is wrapped as a
  * `<system-reminder>` via {@link formatHookFeedback} so the model can read and self-correct.
+ *
+ * **FAILURE POSTURE, and a correction to a widely-quoted anchor (recorded 2026-08-23).** Three repos
+ * have reasoned from the sentence "CC fails open on hook failures, exit code 2 excepted". That sentence
+ * is TRUE OF ONE LANE and false as a general statement, and the difference lands exactly on this seam.
+ * CC runs hooks of seven kinds; the `command` kind is a shell script, and for it a spawn failure, a
+ * non-zero exit and a per-hook timeout are all non-blocking — the call proceeds. But CC ALSO has an
+ * in-process CALLBACK lane, which is the one structurally equivalent to this interface, and there a
+ * PreToolUse callback that throws or times out is FAIL-CLOSED, with its own message stating that the
+ * tool call was not executed. (Two further details the short sentence hides: the decision channel is
+ * stdout JSON, with the exit code only a fallback — so exit 0 can block and a non-zero non-2 exit with
+ * valid JSON does not; and the callback lane's UserPromptSubmit timeout BLOCKS the prompt.)
+ *
+ * So this seam's fail-closed postures are not a sema invention to be justified against CC — they are
+ * the same posture CC takes on the same kind of lane: a `preToolUse` that throws or does not answer
+ * refuses the call, a `userPromptSubmit` that throws or does not answer refuses the prompt, and the
+ * OBSERVATION seats swallow and disclose because an observer has nothing to fail closed about. Anyone
+ * quoting the short sentence to argue this layer "should" fail open is quoting the script lane.
  */
 export interface Hooks {
     preToolUse?(toolName: string, input: unknown, ctx: HookToolContext): PreToolUseResult | undefined | Promise<PreToolUseResult | undefined>;
@@ -159,9 +176,179 @@ export interface Hooks {
      * in for CC `decision_reason_type`): no `retry` capability (recorded — retry semantics vs our adjudicate
      * chain need their own design), no additionalContext. A throwing callback is swallowed + traced via
      * `onError(phase:"hook")` — an observer bug must never alter the deny outcome (design/134 discipline).
+     *
+     * **HOW WIDE THIS SEAT IS, stated honestly (anchoring re-check 2026-08-23).** The exclusion sentence
+     * above is quoted from the SDK's TYPE-LEVEL documentation, and the whole R5 scoping argument was
+     * built on it without ever being checked against a shipped bundle. Against CC 2.1.223's runtime the
+     * picture is different in a way that matters for how this comment may be USED: CC emits its
+     * PermissionDenied event from exactly ONE site, guarded to the auto-mode CLASSIFIER's refusals —
+     * a rule deny, a mode deny and a headless auto-deny emit nothing at all. So "a hook's own deny is
+     * excluded" is TRIVIALLY true there (almost everything is excluded), and it must not be read as
+     * evidence that this seat's TRIGGER SURFACE matches CC's. It does not: sema fires on four engine
+     * emissions with seven `source` values, deliberately WIDER. The width is the useful direction for an
+     * observation seat — the blind spot R3 named is real and a narrower seat would not close it — and it
+     * is a divergence rather than a parity claim. The exclusion itself stays, on its own merit: a hook's
+     * deny is the HOOK's decision, and this seat exists to attribute the ENGINE's.
      */
     permissionDenied?(payload: PermissionDeniedPayload): void | Promise<void>;
+    /**
+     * The TIME BOUND every seat on this object runs under, in milliseconds. Absent ⇒
+     * {@link DEFAULT_HOOK_TIMEOUT_MS}. It is the analog of the CC hook record's own `timeout` field —
+     * declared once per hook record there, once per hook OBJECT here, because this seam's record IS the
+     * object. The unit is ms rather than CC's seconds: every other deadline this library takes ends in
+     * `Ms`, and one unit per codebase beats one unit per upstream.
+     *
+     * **Why the seam has a bound at all.** Every callback above is DEPLOYMENT code awaited on the
+     * engine's critical path, and one that never returns used to stop the whole run — the tool gate
+     * awaited `preToolUse` bare, so a hung screening face left the call unsettled and the task's own
+     * timeout/cancel could not end it. The diagnosis was an internal asymmetry rather than a guess: the
+     * SAME callback installed as an inherited constraint on a delegated child was already bounded, because
+     * that path folds it into a `ToolPolicy` and the policy wait is abort-raced — and the sibling seam in
+     * this very file (`reversibilityProbe`) had already been given a default deadline for the identical
+     * reason. Policies were bounded, probes were bounded, hooks were not.
+     *
+     * **What a bound does NOT change.** A seat that answers keeps its answer, byte for byte; a seat that
+     * throws keeps its existing crash posture (this member changes nothing about a throw). The bound is
+     * consulted only when a seat has not answered yet, and what happens then is per-seat and stated on
+     * each member's own contract — decision seats fail CLOSED (`preToolUse` refuses the call the way a
+     * crash does; `userPromptSubmit` refuses the prompt), observation seats are ABANDONED and the engine
+     * proceeds as if the seat had returned nothing. Either way the deployment is told on its `onError`
+     * lane, because a silently-dropped seat is the failure mode this member exists to make visible.
+     *
+     * **The seat also gets a signal.** An expired wait would otherwise leave the callback running with
+     * nobody reading its answer — an orphan of the deployment's own making. So every context carries an
+     * optional `signal` that aborts when this bound elapses (or the task aborts), and an implementation
+     * that honors it can cancel the read it was waiting on. Honoring it is optional; a seat that ignores
+     * it is exactly as bounded as before, the engine simply stops waiting.
+     *
+     * **WHAT THE BOUND IS ON, stated narrowly because the difference is not academic.** It bounds the
+     * engine's WAIT, not the callback's CPU. A hook that blocks the thread SYNCHRONOUSLY — a spin loop, a
+     * synchronous exec, a synchronous parse of something enormous — cannot be preempted by this bound or
+     * by any other in-process mechanism, because the timer that would fire is queued behind the code that
+     * is not yielding; the ordering of the timer's installation makes no difference to that. In-process
+     * is the seam's whole premise (it is what makes a hook able to rewrite args and return a verdict),
+     * and preemption is what it trades away. A deployment that must survive a hook it does not trust to
+     * yield runs that hook somewhere with its own thread — a worker, a process, a service — and awaits
+     * the result from here. What this member DOES bound is every asynchronous wait, which is where the
+     * failure this was written for lives: a callback that awaits an unreachable host, a lock, a queue.
+     *
+     * **Value discipline** (bad values are loud, never silently reinterpreted): a non-finite, negative, or
+     * above-`setTimeout`-ceiling (2147483647) value is REFUSED to the default and reported on the
+     * deployment's error lane — the same treatment, and the same ceiling, the gate's `approvalTimeoutMs`
+     * seat gives its own garbage. `0` is honored as written (every seat expires immediately), because a
+     * deployment that writes zero has said something, and guessing that it meant "unbounded" would be the
+     * one reading this member cannot support.
+     */
+    timeoutMs?: number;
 }
+/**
+ * The bound a {@link Hooks} seat runs under when the deployment declares none ({@link Hooks.timeoutMs}).
+ *
+ * The value is CC's own hook default (600s) rather than a number invented here. It is deliberately
+ * GENEROUS: the seat bound's job is to make a wedge terminal, not to police how long a legitimate hook
+ * may think — the task's own abort signal is what ends a hung DECISION seat promptly on a run that has a
+ * deadline, and this ceiling is what ends it on a run that does not. A deployment whose hooks should
+ * answer in a second says so with `timeoutMs`.
+ */
+export declare const DEFAULT_HOOK_TIMEOUT_MS = 600000;
+/**
+ * How long an observation seat still gets when the task is cancelled `elapsed` ms into its wait — the
+ * grace, capped by what is LEFT of the declared deadline.
+ *
+ * The `remaining` argument, not the whole deadline, is the correction: arming a fresh
+ * `min(GRACE, timeoutMs)` from the abort moment restarts the clock, so an abort landing near the
+ * deadline pushes the seat's absolute end PAST the number the deployment declared — up to double it for
+ * a sub-second bound — on precisely the cancelled-task settlement path the grace exists to shorten. The
+ * two contract sentences this file already carries ("never an extension", "a deployment that declared a
+ * SHORTER `timeoutMs` keeps its own number") were true only in the aborted-on-entry case, where elapsed
+ * is zero and the two formulas coincide. Now they are true everywhere.
+ *
+ * Clamped at zero: a deadline already spent is no grace at all, not a negative timer.
+ */
+export declare function postAbortGraceMs(remainingMs: number): number;
+/**
+ * Read {@link Hooks.timeoutMs} as a usable deadline: the declared value when it is one, the default
+ * when it is absent, and the default LOUDLY when it is garbage (bad-value loudness — a knob's bad value
+ * must never resolve silently to the default).
+ *
+ * `owner` is the record the value was read off; passing it bounds the disclosure to once per record
+ * (see {@link badHookTimeoutReported}). Omit it where the caller already bounds its own channel.
+ */
+export declare function resolveHookTimeoutMs(supplied: number | undefined, report?: (err: unknown) => void, owner?: object): number;
+/** The ten {@link Hooks} callback seats, named so a bound wait can say WHICH one did not answer. */
+export type HookSeatName = "preToolUse" | "postToolUse" | "postToolUseFailure" | "postToolBatch" | "userPromptSubmit" | "stop" | "stopFailure" | "preCompact" | "postCompact" | "permissionDenied";
+/** What one bounded seat invocation produced: the seat's own value, or the fact that the wait ended
+ *  first. A seat that THREW is neither — the throw propagates out of {@link runHookSeat} unchanged, so
+ *  each site's existing crash arm keeps owning it. */
+export type HookSeatOutcome<T> = {
+    readonly expired: false;
+    readonly value: T;
+} | {
+    readonly expired: true;
+    readonly cause: "timeout" | "aborted";
+};
+/** How one seat invocation is bounded. */
+export interface HookSeatBound {
+    /** The deployment's declared bound ({@link Hooks.timeoutMs}); re-validated here, so a caller that
+     *  already validated pays nothing and a caller that did not cannot pass garbage through. */
+    timeoutMs?: number;
+    /** The task abort signal. It is ALWAYS forwarded to the seat (so an implementation can cancel its own
+     *  underlying wait) and it ALWAYS shortens the wait — the two seat kinds differ only in HOW MUCH.
+     *  Supply it wherever the caller has one: a seat with no signal is bounded by its deadline alone, and
+     *  a ten-minute default deadline is not a cancellation story. */
+    signal?: AbortSignal;
+    /** True for a seat whose answer is MOOT once the task is ending — the DECISION seats. Those settle as
+     *  `aborted` the instant the task is cancelled. An observation seat leaves this false on purpose:
+     *  `postToolUseFailure` fires precisely BECAUSE the task aborted (`isInterrupt`), and cancelling it
+     *  outright would delete the observation the seat exists to deliver — it gets
+     *  {@link POST_ABORT_GRACE_MS} instead of the full deadline. */
+    abortEnds?: boolean;
+    /** Where a bad {@link timeoutMs} is disclosed. The EXPIRY itself is not reported here — each site
+     *  words its own, because the sentence a deployment needs includes what the engine then did. */
+    onBadTimeout?: (err: unknown) => void;
+    /** The hook record the bound was read off, for once-per-record bad-value disclosure. */
+    owner?: object;
+}
+/**
+ * Run ONE {@link Hooks} seat invocation under its bound — the single home of "a deployment callback
+ * gets a deadline", so the ten seats cannot grow ten dialects of one wait.
+ *
+ * Shape notes, each one load-bearing:
+ *  · the seat is invoked SYNCHRONOUSLY, in this turn, exactly where the bare `await` used to be — a
+ *    callback that reads its own mutable state before its first `await` must see the turn it always saw;
+ *  · a SYNCHRONOUS throw propagates unchanged (it never reached a deadline, and the site's crash arm is
+ *    the contract for it), and so does an asynchronous rejection;
+ *  · the seat's signal fires when — and ONLY when — this function stops waiting, and its promise is then
+ *    abandoned with a rejection sink attached (an abandoned seat that fails later must not surface as an
+ *    unhandled rejection somewhere else). The task's own signal is never forwarded raw: for an
+ *    OBSERVATION seat the task being cancelled is not a reason to stop, it is the reason the seat is
+ *    firing at all;
+ *  · the TASK signal ends the wait on both kinds of seat, differently. A DECISION seat
+ *    ({@link HookSeatBound.abortEnds}) settles as `aborted` the moment the task is cancelled, INCLUDING
+ *    when it was already cancelled on entry — a verdict about a call that will not run decides nothing,
+ *    and waiting the full deadline for one holds a cancelled task open for as long as the deadline says.
+ *    On the entry case the callback is still INVOKED (an audit face keeps seeing the attempt) and its
+ *    answer is discarded: settling on the cancellation rather than on whichever of the two happened to
+ *    land first is what makes the arm a rule instead of a race.
+ *    An OBSERVATION seat is not cancelled by the abort — it fires precisely BECAUSE the task aborted
+ *    (`isInterrupt`), and racing it against that same abort would delete the observation it exists to
+ *    deliver — but it does not get the full deadline either: the abort collapses its wait to
+ *    {@link POST_ABORT_GRACE_MS}. Prompt observers still land; a hung one can no longer hold a cancelled
+ *    task's settlement for the length of the whole bound.
+ */
+export declare function runHookSeat<T>(seat: HookSeatName, bound: HookSeatBound, call: (signal: AbortSignal) => T | Promise<T>): Promise<HookSeatOutcome<T>>;
+/**
+ * The ONE wording home for "the engine stopped waiting for a hook seat", so the ten sites cannot drift
+ * into ten sentences about one fact. `consequence` is the half only the site knows: what the engine did
+ * instead.
+ *
+ * The CAUSE is named, not glossed. A deadline that elapsed and a task that was cancelled are different
+ * facts to whoever reads this — the first says a hook is too slow or stuck and wants fixing, the second
+ * says nothing about the hook at all — and one sentence covering both would have to be false about one
+ * of them. (It was: the first version of this said "did not answer within its Nms bound" on every
+ * expiry, including the ones where the bound was never reached.)
+ */
+export declare function hookSeatExpiredError(seat: HookSeatName, timeoutMs: number, cause: "timeout" | "aborted", consequence: string): Error;
 /**
  * Where a {@link Hooks.permissionDenied} deny came from — our gate-source enum standing in for CC's
  * `decision_reason_type` ('classifier'|'asyncAgent'|'mode'|'rule'), named after OUR adjudicate-chain
@@ -170,7 +357,9 @@ export interface Hooks {
  *    (headless auto-deny / approver said no / approval aborted).
  *  - `"hook"` — a PreToolUse hook `ask` (folded allow→ask) resolved to deny, OR the engine's fail-closed
  *    interception of a hook that THREW (RB-442). (A hook's own `deny` short-circuit is EXCLUDED from the
- *    event, CC-exact — a decision the hook made; the crash interception is a decision the ENGINE made.)
+ *    event — a decision the hook made; the crash interception is a decision the ENGINE made. The
+ *    exclusion is ours on that merit; see {@link Hooks.permissionDenied} for why it must NOT be read
+ *    as a parity claim about this seat's trigger surface.)
  *  - `"safety"` — the gate's deterministic egress/irreversibility tighten (design/70 / design/77 §4)
  *    raised the `ask` that resolved to deny, from an explicit per-tool mark.
  *  - `"shellGate"` — same tighten-deny, but the tool's irreversibility tier was installed by the COARSE
@@ -205,6 +394,10 @@ export interface PermissionDeniedPayload {
      *  screen; a policy's direct deny, a hook deny, and the crash/plan-mode/compliance emissions carry
      *  none. See {@link import("./tool-policy.js").AskDenyResolution}. */
     resolution?: import("./tool-policy.js").AskDenyResolution;
+    /** {@link HookSeatSignal} — this invocation's own abort signal. On an OBSERVATION seat the deny has
+     *  already happened and nothing this callback does can change it, so the signal says exactly one
+     *  thing: stop reading, nobody is waiting for your answer any more. */
+    signal?: AbortSignal;
 }
 /**
  * 1.256 复审 MED-1 — observe-only payload isolation for {@link Hooks.permissionDenied}: clone the tool
@@ -227,7 +420,28 @@ export interface StopFailureContext {
     errorKind?: string;
     /** Turns completed when the failure ended the run. */
     turns: number;
+    /** {@link HookSeatSignal} — this invocation's own abort signal. */
+    signal?: AbortSignal;
 }
+/**
+ * The abort signal every hook seat's context carries (`ctx.signal`), documented once here and
+ * referenced from each seat.
+ *
+ * It carries exactly one meaning: **the engine has stopped waiting for this invocation.** It is not the
+ * task's abort signal and it never fires early on the task's behalf — a DECISION seat's wait ends when
+ * the task is cancelled, so its signal fires then; an OBSERVATION seat's wait ends at its deadline or
+ * after the post-abort grace, so its signal fires there and NOT at the cancellation itself. The
+ * difference is deliberate: a `postToolUseFailure` fires precisely BECAUSE the task aborted, and a
+ * signal that went off at the cancellation would tell a cooperative observer to abandon the very
+ * observation it was invoked to deliver.
+ *
+ * Honoring it is optional and it changes nothing about the engine's own behavior — the engine stops
+ * waiting either way. What it is for is the deployment's side of that: a seat that was awaiting a
+ * network read, a lock or a subprocess can cancel it instead of leaving an orphan running with nobody
+ * left to read its answer. Absent when a host drives a seat outside the engine's own invocation (no
+ * bound, nothing to signal).
+ */
+export type HookSeatSignal = AbortSignal;
 /** The failed tool execution a PostToolUseFailure callback inspects (design/134). */
 export interface HookToolFailure {
     /** Model-facing error text of the failed call (the error tool result's text content, joined). */
@@ -273,6 +487,8 @@ export interface PreCompactContext {
     trigger: "auto" | "manual" | "forced";
     /** The summarization instructions in effect (spec/deployment-level), when set. */
     customInstructions?: string;
+    /** {@link HookSeatSignal} — this invocation's own abort signal. */
+    signal?: AbortSignal;
 }
 /** A PreCompact result: skip this compaction (auto/manual only) and/or extend the summary instructions. */
 export interface PreCompactResult {
@@ -293,6 +509,8 @@ export interface PostCompactContext {
     summary: string;
     tokensBefore?: number;
     tokensAfter?: number;
+    /** {@link HookSeatSignal} — this invocation's own abort signal. */
+    signal?: AbortSignal;
 }
 /** Context for the {@link Hooks.stop} hook (CC `stop_hook_active` parity). */
 export interface StopHookContext {
@@ -326,6 +544,8 @@ export interface StopHookContext {
      * Absent when the runner cannot supply one (a stop gate wired without a session).
      */
     getBranch?: () => Promise<readonly SessionTreeEntry[]>;
+    /** {@link HookSeatSignal} — this invocation's own abort signal. */
+    signal?: AbortSignal;
 }
 /** A Stop hook result: block the run from ending, with a model-readable reason. */
 export interface StopHookResult {
@@ -333,11 +553,20 @@ export interface StopHookResult {
      *  model gets another turn to address it. */
     block?: string;
     /**
-     * CC 2.1.201 parity (CC :472050-472077): extra model-readable context injected at the stop point —
-     * DECOUPLED from `block`. When present it is injected (as a `<system-reminder>`, neutral framing:
-     * "Stop hook additional context: …") whether or not the hook blocked; `additionalContext` WITHOUT
-     * `block` still continues the run one more turn, but does NOT count toward the consecutive-block
-     * cap (the cap is driven by `block` alone).
+     * Extra model-readable context injected at the stop point — DECOUPLED from `block`. When present it
+     * is injected (as a `<system-reminder>`, neutral framing: "Stop hook additional context: …") whether
+     * or not the hook blocked, and an `additionalContext` WITHOUT `block` still continues the run one
+     * more turn.
+     *
+     * **It DOES count toward the consecutive-block cap, and it never resets it.** This sentence used to
+     * say the opposite ("the cap is driven by `block` alone", cited to CC 2.1.201), and it was wrong on
+     * both halves. Re-read against CC: the `additionalContext` branch pushes into the SAME array as the
+     * blocking-error branch, the loop counts that array's length against the cap, and CC never resets
+     * mid-run. The engine was fixed to match; the sentence here was not, so the module that DEFINES this
+     * seat and the module that IMPLEMENTS it stated opposite behaviors for years. What the cap bounds is
+     * "the run did not end when it otherwise would have", and a context-only push-back is exactly that —
+     * a hook whose most common failure mode is "no parseable verdict, here is some text" would otherwise
+     * run to `maxTurns` looking busy rather than stuck.
      */
     additionalContext?: string;
 }
@@ -524,6 +753,28 @@ export interface HookToolContext {
      * environment to report). Present ⇒ inspect the individual members: each one is itself optional.
      */
     env?: HookEnvCapabilities;
+    /**
+     * The TASK's tracked working directory at this call — the base the hand tools will resolve a RELATIVE
+     * path against, read live off the same ref the tool policy reads (so a hook and a policy judging the
+     * same call judge it against the same base).
+     *
+     * It is NOT {@link HookEnvCapabilities.cwd}, and the difference is the reason this member exists: that
+     * one is the ENVIRONMENT's own working directory, which never moves when the shell `cd`s or the run
+     * enters a worktree. A hook is documented — on the capability face itself — as the seat that judges
+     * "is this write inside the workspace", and it was the only seat in the gate that could not resolve a
+     * relative target the way the tool would. CC ships its own `cwd` to every hook event for the same
+     * reason; this is that field, named for the value it actually carries.
+     *
+     * ABSENT when the run has no tracked cwd to report — no real write hands (read-only or no shell), a
+     * host driving {@link runToolGate} without one, or the delegation-fold twin (which runs inside a
+     * DESCENDANT's policy fold and would otherwise report the install site's directory, i.e. the wrong
+     * machine's answer). Absence means "this engine cannot tell you", never "the root".
+     */
+    cwd?: string;
+    /** {@link HookSeatSignal} — this invocation's own abort signal. A FRESH one per screening pass, like
+     *  the context object it rides: phase 1 and the approval-edit re-screen are two bounded waits, and a
+     *  shared signal would let the first pass's expiry cancel the second. */
+    signal?: AbortSignal;
 }
 /** The executed tool result a PostToolUse hook inspects. */
 export interface HookToolOutput {
@@ -572,12 +823,16 @@ export interface PostToolUseResult {
 export interface UserPromptSubmitContext {
     /** The run/leg identity envelope — see {@link HookInvocationIdentity} for the presence law. */
     identity?: HookInvocationIdentity;
+    /** {@link HookSeatSignal} — this invocation's own abort signal. */
+    signal?: AbortSignal;
 }
 /** #281 件A — the context of a {@link Hooks.postToolBatch} invocation (third parameter, additive —
  *  deliberately NOT folded into `meta`, whose presence already means "the engine injected here"). */
 export interface PostToolBatchContext {
     /** The run/leg identity envelope — see {@link HookInvocationIdentity} for the presence law. */
     identity?: HookInvocationIdentity;
+    /** {@link HookSeatSignal} — this invocation's own abort signal. */
+    signal?: AbortSignal;
 }
 /** A UserPromptSubmit hook result: block the submission, or inject context ahead of the prompt. */
 export interface UserPromptSubmitResult {
@@ -822,6 +1077,26 @@ export interface ToolGateInput {
      *  system-prompt declaration names. Absent (a host driving the gate directly) ⇒ bare tags. */
     reminderMark?: string;
     preToolUse?: Hooks["preToolUse"];
+    /**
+     * The bound the {@link preToolUse} screenings run under — {@link Hooks.timeoutMs}, carried in from
+     * the hook record the caller resolved it off (the gate receives the callback, not the record). Absent
+     * ⇒ {@link DEFAULT_HOOK_TIMEOUT_MS}. A garbage value is refused loudly to that default via
+     * {@link onHookError}, exactly as {@link approvalTimeoutMs} is.
+     *
+     * On elapse the screening FAILS CLOSED — the call does not execute — and the block reason names the
+     * hook and the bound. That direction is not a new posture for this seat: a hook that THROWS is
+     * already the fail-closed deny here, and a hook that never answers has told the gate strictly less
+     * than one that crashed. A face the deployment declared observational is not exempt, for the same
+     * reason its throw is not: the declaration says its VERDICTS do not count, and a wait that never
+     * ends is not a verdict.
+     */
+    hookTimeoutMs?: number;
+    /** The task's live tracked cwd reader, put on every {@link HookToolContext} this gate call builds
+     *  (see {@link HookToolContext.cwd}). A FUNCTION rather than a string for the reason the policy's own
+     *  threading gives: capturing the value when the gate's wiring is built would freeze the task's
+     *  starting directory and answer for a run that has since `cd`ed. Absent ⇒ the contexts carry no
+     *  `cwd`, which is the honest answer for a run with no tracked one. */
+    trackedCwd?: () => string | undefined;
     /** The read-only env capability face put on every {@link HookToolContext} this gate call
      *  builds ({@link HookEnvCapabilities}). Built ONCE per task by the runner (after the env is minted) and
      *  passed through unchanged; omitted when the deployment wired no execution environment. */
@@ -941,12 +1216,13 @@ export interface ToolGateInput {
     /**
      * design/134 R5: observer for the gate's DENY short-circuit ({@link Hooks.permissionDenied}), pre-wrapped
      * by the caller (swallow + onError) so it never throws. Fired ONCE, at the single deny exit of the
-     * adjudicate chain — a policy deny or a resolved-ask deny. NOT fired for a PreToolUse hook deny
-     * (CC-exact exclusion) or a durable suspend (the ask path). runToolGate still try/catches defensively:
-     * an observer must never alter the deny outcome.
+     * adjudicate chain — a policy deny or a resolved-ask deny. NOT fired for a PreToolUse hook deny (the
+     * exclusion on {@link Hooks.permissionDenied}, which also records why that exclusion is not a parity
+     * claim) or a durable suspend (the ask path). runToolGate still try/catches defensively: an observer
+     * must never alter the deny outcome.
      *
      * RB-442: ALSO fired for the engine's fail-closed interception of a THROWING PreToolUse hook, with
-     * `source:"hook"` — the CC-exact exclusion is the hook's own deny DECISION, not an engine decision.
+     * `source:"hook"` — the exclusion is the hook's own deny DECISION, not an engine decision.
      */
     permissionDenied?: (payload: PermissionDeniedPayload) => void | Promise<void>;
     /**
@@ -1198,7 +1474,13 @@ export interface ToolGateInput {
  * so a broken screening face is distinguishable from a deliberate refusal, and the folded form has to
  * reach the same lane from inside a descendant's fold.
  */
-export declare function createPreToolUseConstraintPolicy(preToolUse: NonNullable<Hooks["preToolUse"]>, env?: HookEnvCapabilities, onCrash?: (err: unknown) => void): ToolPolicy;
+export declare function createPreToolUseConstraintPolicy(preToolUse: NonNullable<Hooks["preToolUse"]>, env?: HookEnvCapabilities, onCrash?: (err: unknown) => void, 
+/** The install site's {@link Hooks.timeoutMs}. The folded form was ALREADY bounded by the descendant's
+ *  abort race — that asymmetry (bounded as an inherited constraint, unbounded in its own gate) is what
+ *  named the hole in the first place — but an abort bound is not a deadline: on a descendant with no
+ *  walltime and no cancel, the race never fires. So the same seat bound rides here too, and the two
+ *  installations of one callback are now bounded the same way for the same reason. */
+timeoutMs?: number): ToolPolicy;
 /**
  * The mandate provenance of one call, judged from the SAME mark inputs the gate is driven with —
  * the single source for "could a persisted allow rule clear this ask?". Allow rules silence the

package/dist/core/hooks.js

@@ -6,6 +6,92 @@ import { PROBE_REASON_MAX, normalizeProbeCause } from "./checkpoint-store.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
 import { createSafeNotifier } from "./safe-notify.js";
 import { ORG_ADJUDICATION_TIMEOUT_MS, ORG_RULE_DECISION_REASON, ORG_UNAVAILABLE_DECISION_REASON, settleOrgVerdictWithin } from "./permission-rule-org.js";
+export const DEFAULT_HOOK_TIMEOUT_MS = 600_000;
+const MAX_HOOK_TIMEOUT_MS = 2_147_483_647;
+const POST_ABORT_GRACE_MS = 1_000;
+export function postAbortGraceMs(remainingMs) {
+    return Math.max(0, Math.min(POST_ABORT_GRACE_MS, remainingMs));
+}
+const badHookTimeoutReported = new WeakSet();
+export function resolveHookTimeoutMs(supplied, report, owner) {
+    if (supplied === undefined)
+        return DEFAULT_HOOK_TIMEOUT_MS;
+    if (Number.isFinite(supplied) && supplied >= 0 && supplied <= MAX_HOOK_TIMEOUT_MS)
+        return supplied;
+    if (report !== undefined && !(owner !== undefined && badHookTimeoutReported.has(owner))) {
+        if (owner !== undefined)
+            badHookTimeoutReported.add(owner);
+        try {
+            report(new Error(`Hooks.timeoutMs must be a non-negative finite number no greater than ${MAX_HOOK_TIMEOUT_MS} (got ${String(supplied)}) — ` +
+                `every hook seat falls back to the ${DEFAULT_HOOK_TIMEOUT_MS}ms default`));
+        }
+        catch {
+        }
+    }
+    return DEFAULT_HOOK_TIMEOUT_MS;
+}
+export async function runHookSeat(seat, bound, call) {
+    void seat;
+    const timeoutMs = resolveHookTimeoutMs(bound.timeoutMs, bound.onBadTimeout, bound.owner);
+    const taskSignal = bound.signal;
+    const controller = new AbortController();
+    const pending = Promise.resolve(call(controller.signal));
+    const startedAt = performance.now();
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        let listening = false;
+        let timer;
+        const clearTimer = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+        };
+        const finish = (act) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimer();
+            if (listening)
+                taskSignal?.removeEventListener("abort", onAbort);
+            act();
+        };
+        const expire = (cause) => finish(() => {
+            void pending.then(undefined, () => {
+            });
+            resolve({ expired: true, cause });
+            queueMicrotask(() => {
+                try {
+                    controller.abort();
+                }
+                catch {
+                }
+            });
+        });
+        const collapseToGrace = () => {
+            if (settled)
+                return;
+            clearTimer();
+            timer = setTimeout(() => expire("aborted"), postAbortGraceMs(timeoutMs - (performance.now() - startedAt)));
+        };
+        const onAbort = () => (bound.abortEnds === true ? expire("aborted") : collapseToGrace());
+        timer = setTimeout(() => expire("timeout"), timeoutMs);
+        if (taskSignal !== undefined) {
+            if (taskSignal.aborted) {
+                onAbort();
+            }
+            else {
+                taskSignal.addEventListener("abort", onAbort, { once: true });
+                listening = true;
+            }
+        }
+        pending.then((value) => finish(() => resolve({ expired: false, value })), (err) => finish(() => reject(err instanceof Error ? err : new Error(String(err)))));
+    });
+}
+export function hookSeatExpiredError(seat, timeoutMs, cause, consequence) {
+    return new Error(cause === "timeout"
+        ? `the deployment's ${seat} hook did not answer within its ${timeoutMs}ms bound (Hooks.timeoutMs) — ${consequence}`
+        : `the deployment's ${seat} hook had not answered when the task was cancelled — ${consequence}`);
+}
 export function cloneObserverInput(input) {
     try {
         return structuredClone(input);
@@ -202,17 +288,35 @@ function preToolUseCrashReason(subject, err) {
         `This is a failure of the deployment's hook, NOT of the tool itself — an identical retry reaches the ` +
         `same hook and fails the same way. Hook error: ${cause || "(no message)"}`);
 }
+function preToolUseUnansweredReason(subject, timeoutMs, cause) {
+    return cause === "timeout"
+        ? `a PreToolUse hook did not answer within its ${timeoutMs}ms bound while screening ${subject}; the call was ` +
+            `NOT executed (fail-closed). This is a failure of the deployment's hook, NOT of the tool itself — the ` +
+            `screening face never returned a verdict, so nothing was decided about this call either way.`
+        : `the task was cancelled while a PreToolUse hook was still screening ${subject}; the call was NOT executed ` +
+            `(fail-closed). No verdict was reached — this is the run ending, not the tool failing.`;
+}
 function screenPreToolUseResult(r) {
     if (r === undefined)
         return undefined;
     return refuseOutOfContractDecision(r, { reasonIsNonInput: true });
 }
-export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash) {
+export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash, timeoutMs) {
     return brandPolicyAskClass({
         check: async (req) => {
             let r;
+            const boundMs = resolveHookTimeoutMs(timeoutMs, onCrash);
             try {
-                r = screenPreToolUseResult(await preToolUse(req.toolName, req.args, { toolCallId: req.toolCallId, toolName: req.toolName, ...(env !== undefined ? { env } : {}) }));
+                const seat = await runHookSeat("preToolUse", { timeoutMs: boundMs }, (sig) => preToolUse(req.toolName, req.args, { toolCallId: req.toolCallId, toolName: req.toolName, signal: sig, ...(env !== undefined ? { env } : {}) }));
+                if (seat.expired) {
+                    try {
+                        onCrash?.(hookSeatExpiredError("preToolUse", boundMs, seat.cause, `the inherited screening of "${req.toolName}" was refused fail-closed`));
+                    }
+                    catch {
+                    }
+                    return { action: "deny", message: preToolUseUnansweredReason(`this call to "${req.toolName}"`, boundMs, seat.cause), decisionReason: "hook" };
+                }
+                r = screenPreToolUseResult(seat.value);
             }
             catch (err) {
                 try {
@@ -284,9 +388,14 @@ export function persistedRuleMandateOf(marks) {
 export async function runToolGate(input) {
     const { event, preToolUse, adjudicate, resolveAsk, suspendAsk } = input;
     const { toolCallId, toolName } = event;
-    const hookCtx = () => ({
+    const hookCtx = (seatSignal) => ({
         toolCallId,
         toolName,
+        ...(seatSignal !== undefined ? { signal: seatSignal } : {}),
+        ...(() => {
+            const c = input.trackedCwd?.();
+            return typeof c === "string" ? { cwd: c } : {};
+        })(),
         ...(input.hookEnv !== undefined ? { env: input.hookEnv } : {}),
         ...(input.identity !== undefined ? { identity: input.identity } : {}),
     });
@@ -296,17 +405,47 @@ export async function runToolGate(input) {
     let parkFailed;
     let askDenyResolution;
     const notifier = createSafeNotifier(input.onNotifyError !== undefined ? { onError: input.onNotifyError } : undefined);
+    const hookSeatMs = resolveHookTimeoutMs(input.hookTimeoutMs, (err) => traceHookCrash(input, err, notifier));
+    const seatBound = (abortEnds) => ({
+        timeoutMs: hookSeatMs,
+        ...(input.abortSignal !== undefined ? { signal: input.abortSignal } : {}),
+        ...(abortEnds ? { abortEnds: true } : {}),
+    });
+    const preToolUseUnansweredBlock = async (subject, cause) => {
+        const reason = preToolUseUnansweredReason(subject, hookSeatMs, cause);
+        if (cause === "timeout") {
+            traceHookCrash(input, hookSeatExpiredError("preToolUse", hookSeatMs, cause, `${subject} was NOT executed (fail-closed) and the screening face was signalled to stop`), notifier);
+        }
+        return reason;
+    };
+    const notifyPermissionDeniedSeat = async (payload) => {
+        if (input.permissionDenied === undefined)
+            return;
+        await notifier.notifyAsync(async () => {
+            const seat = await runHookSeat("permissionDenied", seatBound(false), (sig) => input.permissionDenied?.({ ...payload, signal: sig }));
+            if (seat.expired)
+                throw hookSeatExpiredError("permissionDenied", hookSeatMs, seat.cause, "the deny observation was abandoned; the deny itself is unchanged");
+        }, "toolGate.permissionDenied");
+    };
     if (preToolUse) {
         let r;
+        let unanswered;
         try {
-            r = screenPreToolUseResult(await preToolUse(toolName, currentInput, hookCtx()));
+            const seat = await runHookSeat("preToolUse", seatBound(true), (sig) => preToolUse(toolName, currentInput, hookCtx(sig)));
+            if (seat.expired)
+                unanswered = seat.cause;
+            else
+                r = screenPreToolUseResult(seat.value);
         }
         catch (err) {
             const reason = preToolUseCrashReason(`this call to "${toolName}"`, err);
             traceHookCrash(input, err, notifier);
-            if (input.permissionDenied) {
-                await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason, source: "hook", ...(input.identity !== undefined ? { identity: input.identity } : {}) }), "toolGate.permissionDenied");
-            }
+            await notifyPermissionDeniedSeat({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason, source: "hook", ...(input.identity !== undefined ? { identity: input.identity } : {}) });
+            return { block: true, reason: formatHookFeedback(reason, input.reminderMark), preToolContext };
+        }
+        if (unanswered !== undefined) {
+            const reason = await preToolUseUnansweredBlock(`this call to "${toolName}"`, unanswered);
+            await notifyPermissionDeniedSeat({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason, source: "hook", ...(input.identity !== undefined ? { identity: input.identity } : {}) });
             return { block: true, reason: formatHookFeedback(reason, input.reminderMark), preToolContext };
         }
         if (r) {
@@ -714,8 +853,13 @@ export async function runToolGate(input) {
                     }
                     if (preToolUse) {
                         let hr;
+                        let hrUnanswered;
                         try {
-                            hr = screenPreToolUseResult(await preToolUse(toolName, editArgs, hookCtx()));
+                            const seat = await runHookSeat("preToolUse", seatBound(true), (sig) => preToolUse(toolName, editArgs, hookCtx(sig)));
+                            if (seat.expired)
+                                hrUnanswered = seat.cause;
+                            else
+                                hr = screenPreToolUseResult(seat.value);
                         }
                         catch (err) {
                             traceHookCrash(input, err, notifier);
@@ -723,6 +867,11 @@ export async function runToolGate(input) {
                             denySource = "hook";
                             break;
                         }
+                        if (hrUnanswered !== undefined) {
+                            editDenied = { action: "deny", message: await preToolUseUnansweredBlock(`the approved edit for "${toolName}"`, hrUnanswered) };
+                            denySource = "hook";
+                            break;
+                        }
                         if (hr) {
                             if (hr.additionalContext)
                                 preToolContext.push(hr.additionalContext);
@@ -828,9 +977,7 @@ export async function runToolGate(input) {
             currentInput = decision.updatedInput;
         }
         const denyResolution = askDenyResolution ?? coreMintedResolutionOf(decision, { toolCallId, toolName });
-        if (input.permissionDenied) {
-            await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason: denyReason, source: denySource, ...(denyResolution !== undefined ? { resolution: denyResolution } : {}), ...(input.identity !== undefined ? { identity: input.identity } : {}) }), "toolGate.permissionDenied");
-        }
+        await notifyPermissionDeniedSeat({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason: denyReason, source: denySource, ...(denyResolution !== undefined ? { resolution: denyResolution } : {}), ...(input.identity !== undefined ? { identity: input.identity } : {}) });
         const denySettledBy = decision.settledBy;
         const denyApprover = denySettledBy !== undefined ? resolvedApprover : undefined;
         return {