@sema-agent/core 5.55.0 → 5.56.0

package/dist/core/context-edit.d.ts

@@ -14,11 +14,18 @@ export declare const EDIT_FRACTION = 0.7;
  *   effectiveWindow = autocompactWindow − min(maxOutputTokens, 20000)   (CC `Nye`, cap `uMd`)
  *   trigger         = effectiveWindow − 13000                           (CC `dSo`, buffer `rMd`)
  * i.e. trigger = W − 33000 for every model whose max output is ≥ 20k: a 200k window triggers at
- * 167000 (83.5% of nominal), a 1M window at 967000. (CC additionally ships a sonnet-5-only 1M
- * autocompact-window special of 967000 via dynamic config, making ITS 1M trigger 934000; that is a
- * per-model config delivery, not geometry — an embedder reproduces it EXACTLY via
- * `model.autoCompactTokens = 967000`, which lowers only this trigger-side window while the guard
- * and physical request budgeting stay on the 1M window — CC's dual-window shape.) We take the
+ * 167000 (83.5% of nominal), a 1M window at 967000.
+ *
+ * 1M DIVERGENCE, stated as fact rather than as an equivalence (anchoring re-check 2026-08-23): CC
+ * carries a MODEL-DEFAULT autocompact-window table (2.1.223 `j3u` :242918 — `claude-sonnet-5`
+ * default 967000, and since 223 a surface dimension: `remote_cowork` / `local-agent` 500000), so a
+ * 1M sonnet-5 gets 967000 as its window and 934000 as its trigger WITHOUT anyone configuring
+ * anything. We ship no such table: a model declaring only `contextWindow: 1e6` triggers at 967000
+ * here, 33000 LATER than CC. `model.autoCompactTokens = 967000` reproduces CC's number — but that
+ * is an EMBEDDER action against CC's product default, not the same posture, and the choice not to
+ * follow 934000 is deliberate (design/146 §1.3 argues against living on that thin a cushion). The
+ * knob itself is real and unchanged: `autoCompactTokens` lowers only this trigger-side window while
+ * the guard and physical request budgeting stay on the 1M window — CC's dual-window shape. We take the
  * 20000 cap branch unconditionally (flat 33000), i.e. the `min(maxOutputTokens, 20000)` branch is
  * deliberately NOT ported: the deduction is exact parity only for models with max output ≥ 20k. A
  * model with a smaller max output would deduct less in CC (trigger LATER); we deduct the full
@@ -51,11 +58,53 @@ export declare function contextEditFrontier(window: number): number;
  * PowerShell is kept for CC fidelity even though sema does not mount it. Overridable per call via
  * {@link ContextEditOptions.compactableTools} for custom-tool-heavy embedders.
  */
+/**
+ * How many most-recent CANDIDATE tool results keep their content when the stale-result pass runs.
+ *
+ * 3, UNCHANGED — and the fact that CC's corresponding number is 5 (2.1.223 `uAp`, and the same value
+ * on CC 88's `timeBasedMCConfig`, so it is stable across both corpus generations) is deliberately NOT
+ * adopted here. Two reasons, in order of weight:
+ *
+ *  1. MEASURED: widening the window removes this pass's only lever in the shape where a terminal
+ *     parallel batch holds exactly as many large results as the window keeps. Probed on a 200k model
+ *     with a 140k usage anchor and five 36k-char Bash results: at 3 the pass clears two and the
+ *     request lands at ~167k, UNDER the 177k request guard; at 5 nothing is clearable, the request
+ *     stays at 185k, and the guard cannot recover it either — `trimToBudget` must turn-align back to
+ *     the emitting assistant, so the whole batch is retained. The window is count-based on both
+ *     sides (CC's `slice(-keepRecent)` too), so this ceiling exists at every value; 5 simply widens
+ *     the band that reaches it.
+ *  2. SEAT: the two numbers do not govern the same machine. CC's keep-recent clear runs ONLY on the
+ *     `context_hint` rejection leg — gated off by default — and behind a hard "saves ≥ 20000 tokens
+ *     or don't bother" test, with request REFUSAL as the real backstop. Ours is on by default, is
+ *     the only reduction between the frontier and the guard, and its backstop drops messages instead
+ *     of refusing. Copying a constant across that difference is the "same name, different question"
+ *     mistake, not parity.
+ *
+ * So the VALUE is an open adjudication (recorded with the probe above), while the two things CC
+ * unambiguously answers — the floor and the candidate-scoped window — are followed exactly.
+ */
+export declare const DEFAULT_KEEP_RECENT_TOOL_RESULTS = 3;
+/** Minimum kept results — CC `EUs` :397710 `Math.max(1, keepRecent)`. See
+ *  {@link ContextEditOptions.keepRecentToolResults} for why both degenerate ends are unusable. */
+export declare const MIN_KEEP_RECENT_TOOL_RESULTS = 1;
 export declare const COMPACTABLE_TOOLS: ReadonlySet<string>;
 export interface ContextEditOptions {
     /** Start clearing once estimated context tokens exceed this. */
     budgetTokens: number;
-    /** Always keep the content of this many most-recent tool results. Default 3. */
+    /**
+     * Always keep the content of this many most-recent CANDIDATE tool results (candidates = results
+     * from {@link compactableTools}). Default {@link DEFAULT_KEEP_RECENT_TOOL_RESULTS} = 3 — see that
+     * constant for why CC's 5 is not adopted here.
+     *
+     * Floored at 1, which IS CC's rule (`EUs` `Math.max(1, keepRecent)`), whose own source note gives
+     * the reason: 0 leaves the model with zero working tool context, and in CC's `slice(-0)` spelling
+     * it degenerates the other way into keeping everything — two unusable extremes for one value.
+     * Ours degenerated identically (a 0 or negative `keep` cleared EVERY candidate). Values that are
+     * not a non-negative safe integer are REFUSED rather than floored: a NaN used to make this whole
+     * defense silently inert (`slice(0, NaN)` = clear nothing), which is the one outcome a context
+     * defense must never reach quietly, and there is no config door upstream to announce at — this
+     * option only ever arrives as a direct argument from an embedder.
+     */
     keepRecentToolResults?: number;
     /**
      * roadmap #6② (CC contentReplacementState parity): when set, a result's FULL TEXT is offloaded to

package/dist/core/context-edit.js

@@ -27,6 +27,17 @@ export const COMPACTION_TRIGGER_BUFFER_TOKENS = 13000;
 export function contextEditFrontier(window) {
     return Math.max(window - (CONTEXT_OUTPUT_RESERVE_TOKENS + COMPACTION_TRIGGER_BUFFER_TOKENS), Math.floor(window * EDIT_FRACTION));
 }
+export const DEFAULT_KEEP_RECENT_TOOL_RESULTS = 3;
+export const MIN_KEEP_RECENT_TOOL_RESULTS = 1;
+function resolveKeepRecentToolResults(value) {
+    if (value === undefined)
+        return DEFAULT_KEEP_RECENT_TOOL_RESULTS;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`keepRecentToolResults must be a non-negative safe integer (got ${String(value)}); ` +
+            `omit it for the default ${DEFAULT_KEEP_RECENT_TOOL_RESULTS}`);
+    }
+    return Math.max(MIN_KEEP_RECENT_TOOL_RESULTS, value);
+}
 export const COMPACTABLE_TOOLS = new Set([
     "Read",
     "Bash",
@@ -74,7 +85,7 @@ export function clearStaleToolResults(messages, opts) {
     if (total <= opts.budgetTokens) {
         return messages;
     }
-    const keep = opts.keepRecentToolResults ?? 3;
+    const keep = resolveKeepRecentToolResults(opts.keepRecentToolResults);
     const compactable = opts.compactableTools ?? COMPACTABLE_TOOLS;
     const toolResultCandidates = messages.flatMap((m, i) => isToolResult(m) && !isCleared(m) && compactable.has(m.toolName) ? [{ idx: i, target: m }] : []);
     const clearable = toolResultCandidates.slice(0, Math.max(0, toolResultCandidates.length - keep));

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