@sema-agent/core 5.20.0 → 5.21.1

package/dist/core/hooks.d.ts

@@ -1,45 +1,221 @@
 import type { DocumentContent, ImageContent, TextContent } from "../internal/llm.js";
 import type { ExecutionEnv, FileError, Result, SessionTreeEntry } from "../internal/harness-types.js";
 import type { PermissionResult, ResolvedAsk, ToolCallRequest, ToolPolicy } from "./tool-policy.js";
+/**
+ * In-process hook seam (design/37) — a small, provider-agnostic interception layer modeled on CC's
+ * hooks but reduced to three process-internal callbacks (no shell/HTTP executors, no settings files):
+ *
+ *  - {@link Hooks.preToolUse} runs before a tool executes. It may **rewrite** the args (an `allow` with
+ *    `updatedInput`), **restrict** the call (`deny`/`ask`), and/or inject `additionalContext`. It is a
+ *    pre-filter only: a hook's `allow` does NOT bypass the tool-policy gate — the policy still runs on
+ *    the (possibly rewritten) args and has the final say (load-bearing invariant; see {@link runToolGate}).
+ *  - {@link Hooks.postToolUse} runs after a tool executes. It may replace the result content
+ *    (`updatedOutput`) and/or append `additionalContext`.
+ *  - {@link Hooks.userPromptSubmit} runs before the objective becomes a user message. It may `block`
+ *    submission (the task fails with a model-readable reason) or inject `additionalContext` ahead of it.
+ *
+ * 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.
+ */
 export interface Hooks {
     preToolUse?(toolName: string, input: unknown, ctx: HookToolContext): PreToolUseResult | undefined | Promise<PreToolUseResult | undefined>;
+    /**
+     * Deployment SELF-DECLARATION: this deployment's {@link preToolUse} is a pure OBSERVER — a tracer, an
+     * audit sink, a metrics counter — that never judges a call. Declaring it changes exactly one thing:
+     * the face stops being folded into the DELEGATION chain (`InheritedGate.parentConstraints`), so a
+     * delegated child inherits no screening entry for it.
+     *
+     * Why the declaration exists. The delegation fold (issue #33) keys on PRESENCE — "a preToolUse is
+     * wired" — because a callback cannot be inspected for whether it will ever return a verdict. That
+     * reading is right for a screening face and wrong for an observer, and the difference is not free:
+     * every inherited entry is one more OPAQUE constraint on the child, recorded on a durable park as
+     * `parentConstraintCount`. A deployment that flips on a default-OFF diagnostic tracer therefore also
+     * changes the shape every parked child's resume has to re-supply. The declaration is how a deployment
+     * says which of the two it wired, on the same footing as every other thing the library trusts a
+     * deployment to state about its own wiring.
+     *
+     * What does NOT change: the callback still runs in THIS task's own tool gate, on every call, with the
+     * same context and the same crash posture (a throw is still the fail-closed deny). Observation is
+     * untouched; only the inherited constraint goes away.
+     *
+     * The face also receives a DETACHED copy of the arguments rather than the live object, because the
+     * gate reads a rewrite off reference identity and an in-place edit would otherwise be a second channel
+     * that outlives the dropped return value. That detachment is BEST-EFFORT, in the same sense (and by the
+     * same helper) as every other observe-only payload here: a graph `structuredClone` cannot take — a
+     * function, a live handle — falls back to a shallow copy whose nested objects still alias, and a
+     * `SharedArrayBuffer` shares its memory even when the clone succeeds. Phase-1 arguments are the model's
+     * JSON on the ordinary path, which clones whole; the residual is reachable only through values a
+     * DEPLOYMENT put there (its own rewrite, or driving `runToolGate` directly), and the face and the
+     * deployment are one trust principal — this seam helps a deployment keep its own declaration, it is not
+     * a boundary against an adversary.
+     *
+     * If a declared-observational face RETURNS SOMETHING ANYWAY, the return is REFUSED, not obeyed: the
+     * call proceeds as if the hook had no opinion (`undefined`), and the deployment's `onError` face is
+     * told (`phase:"hook"`, classification `observational-hook-verdict-ignored`). That covers the whole
+     * result object — an `additionalContext` injection is a run-affecting capability too, so a face that
+     * declared it only watches does not get to write into the model's transcript either. The refusal is
+     * loud on purpose: a declaration that could be quietly contradicted would be a way to keep a
+     * screening face's verdicts while shedding the delegation constraint they belong to.
+     */
     preToolUseObservational?: true;
     postToolUse?(toolName: string, input: unknown, output: HookToolOutput, ctx: HookToolContext): PostToolUseResult | undefined | Promise<PostToolUseResult | undefined>;
     userPromptSubmit?(prompt: string): UserPromptSubmitResult | undefined | Promise<UserPromptSubmitResult | undefined>;
+    /**
+     * roadmap #5 (CC 198 Stop hook, :473831-): runs when the agent WOULD OTHERWISE END its run (no
+     * more tool calls, steering and follow-up queues dry). Return `{ block: reason }` to PUSH BACK —
+     * the reason is injected as a model-readable message and the run continues another turn (external
+     * adjudication: "the tests still fail", "the deliverable is missing X"). Return `undefined` to let
+     * the run end. Guardrails (CC-exact): consecutive blocks are capped (default 8 — the loop then
+     * overrides and ends with a warning); `ctx.stopHookActive` is true when the run is ALREADY
+     * continuing due to a previous block — a hook that ignores it and blocks unconditionally loops
+     * until the cap. `maxTurns` still outranks everything.
+     */
     stop?(ctx: StopHookContext): StopHookResult | undefined | Promise<StopHookResult | undefined>;
+    /**
+     * design/134 (CC PostToolUseFailure parity, SDK 0.3.202): runs after a tool EXECUTION fails —
+     * mutually exclusive with {@link postToolUse} (success → postToolUse; failure → this). Fires ONLY
+     * for genuine execution failures: a gate/policy block, a plan-mode deny, a pre-execution abort or a
+     * durable suspend triggers NEITHER callback (CC scopes those to the PermissionDenied event domain,
+     * not implemented here). Capability is additionalContext-only (CC-exact): the text is appended to
+     * the error tool result as a `<system-reminder>`; the failure itself cannot be rewritten.
+     */
     postToolUseFailure?(toolName: string, input: unknown, failure: HookToolFailure, ctx: HookToolContext): PostToolUseFailureResult | undefined | Promise<PostToolUseFailureResult | undefined>;
+    /**
+     * design/134 (CC PostToolBatch parity, SDK 0.3.202): fires ONCE after every tool call in a batch
+     * (one assistant turn's calls, design/120 stream-inline included) has resolved, before the next
+     * model request. Per-tool postToolUse/postToolUseFailure fire first; the batch callback fires after,
+     * at the turn boundary. A zero-tool turn does not fire; an aborted/steered-away boundary does not
+     * fire (same gate family as design/133 attachments). additionalContext is injected once for the
+     * whole batch as a boundary `<system-reminder>` (sanitized, shares the attachment byte cap).
+     *
+     * RB-467 (test-AI black-box repro, board 2305: ONE injection ate a whole subsequent batch): a batch
+     * landing on a boundary where the engine itself injected (final-verification nudge / finalize
+     * write-out) is now DELIVERED with `meta.injectedThisTurn` set, instead of being suppressed — for a
+     * deployment observer, any suppressed boundary is lost audit data; attribution belongs to the
+     * observer. On such a boundary the hook's `additionalContext` is IGNORED (the boundary already
+     * carries an engine injection; stacking observer text there is the double-inject this gate
+     * originally guarded against — that half of the old behavior stands).
+     */
     postToolBatch?(batch: PostToolBatchCall[], meta?: {
         injectedThisTurn: "final_verification" | "finalize";
     }): PostToolBatchResult | undefined | Promise<PostToolBatchResult | undefined>;
+    /**
+     * design/134 (CC PreCompact parity): runs before each compaction, AFTER the trigger gate and a
+     * valid cut point are confirmed (so every preCompact corresponds to a compaction that would
+     * actually happen) and before the summary LLM call. `trigger`: "auto" (threshold) | "manual"
+     * (/compact) | "forced" (promptTooLong recovery and trim-pressure — compaction is not optional
+     * there). Return `{ block }` to skip this compaction (honored on auto/manual ONLY; ignored with a
+     * trace on forced — blocking a compaction the provider already demanded would kill the run).
+     * `additionalInstructions` is merged (appended) into the summarization instructions (CC
+     * mergeHookInstructions shape). A THROWING preCompact is swallowed on every path (traced, treated
+     * as no-block): an observer bug must never feed the compaction breaker or kill PTL recovery.
+     */
     preCompact?(ctx: PreCompactContext): PreCompactResult | undefined | Promise<PreCompactResult | undefined>;
+    /**
+     * design/134 (CC PostCompact parity): observe-only, after the compaction landed (summary appended
+     * to the session). No return capability (CC-exact); a throw is swallowed and traced.
+     */
     postCompact?(ctx: PostCompactContext): void | Promise<void>;
+    /**
+     * StopFailure (the last engine-owned event of the registry-core 0.1.51 hooks contract; CC semantics:
+     * "the turn ended because of an API error"). Fires ONCE, after the result is assembled, when the task
+     * terminates `failed` BECAUSE the model/API layer errored (a brain error terminal —
+     * auth / network / rate_limit / server_error / …). It does NOT fire for engine-owned failure classes:
+     * budget, timeout/abort, max-turns, degenerate/walltime cutoffs (deliberate engine cuts), storage
+     * conflict, blocked, or a durable suspend — those are not API errors. Observe-only (CC-exact: the
+     * contract defines no StopFailure output capability); a throwing callback is swallowed + traced
+     * (design/134 discipline — an observer bug must never rewrite a terminal state).
+     */
     stopFailure?(ctx: StopFailureContext): void | Promise<void>;
+    /**
+     * design/134 R5 (CC PermissionDenied parity, SDK 0.3.202 — service [418]③): runs when the tool gate's
+     * adjudicate chain DENY-SHORT-CIRCUITS a tool call — a ToolPolicy deny, a gate tighten (egress /
+     * irreversibility / coarse shellGate) whose `ask` resolved to deny (headless auto-deny included), or the
+     * plan-mode write-deny. Closes the observation blind spot where a blocked call fires NEITHER postToolUse
+     * NOR postToolUseFailure (R3 scoping). Does NOT fire for:
+     *  - a **durable suspend** (the ask path — CC surfaces that via a `can_use_tool` control_request);
+     *  - a **PreToolUse hook deny** (CC-exact: "PreToolUse hook denies bypass canUseTool and are not
+     *    covered here").
+     * DOES fire for a **PreToolUse hook CRASH** (RB-442, `source:"hook"`): a throwing hook is intercepted by
+     * the ENGINE, which then makes its OWN fail-closed deny decision. The R5 exclusion above covers the
+     * hook's own DENY DECISION — not an engine decision that merely happened near a hook.
+     * Observe-only v1 (CC-exact payload `{toolName, input, toolCallId, reason}` + our `source` enum standing
+     * 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).
+     */
     permissionDenied?(payload: PermissionDeniedPayload): void | Promise<void>;
 }
+/**
+ * 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
+ * sources (design/134 R5):
+ *  - `"policy"` — the ToolPolicy denied directly, or a policy-raised `ask` resolved to deny
+ *    (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.)
+ *  - `"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
+ *    `TaskSpec.shellGate` doctrine (design/80 D-E), not an explicit per-tool mark.
+ *  - `"planMode"` — the design/108 plan-mode write-deny short-circuit (a read-only fidelity gate).
+ */
 export type PermissionDeniedSource = "policy" | "hook" | "safety" | "shellGate" | "planMode" | "classifier";
+/** The payload a {@link Hooks.permissionDenied} callback observes (CC-exact fields + `source`). */
 export interface PermissionDeniedPayload {
     toolName: string;
+    /** The FINAL (post-hook-rewrite / post-policy-rewrite) args the chain adjudicated — what would have
+     *  executed; not necessarily the model's original args. */
     input: unknown;
     toolCallId: string;
+    /** Human/model-readable deny reason (CC `reason`) — the RAW decision text, NOT `<system-reminder>`-wrapped. */
     reason: string;
+    /** Which gate source produced the deny (our `decision_reason_type` analog). */
     source: PermissionDeniedSource;
 }
+/**
+ * 1.256 复审 MED-1 — observe-only payload isolation for {@link Hooks.permissionDenied}: clone the tool
+ * args before they ride the observer payload, so a hook mutating `payload.input` can never pollute the
+ * LIVE args object (later events / audit records share it). Same posture as the postToolUseFailure
+ * details clone (prepare-task): `structuredClone` first; a non-structured-cloneable graph
+ * (functions/handles) falls back to a SHALLOW plain object/array copy (top-level mutation isolated);
+ * a non-object primitive passes through as-is (immutable anyway).
+ */
 export declare function cloneObserverInput(input: unknown): unknown;
+/** Context for {@link Hooks.stopFailure} — aligned with the TaskResult error face (observe-only). */
 export interface StopFailureContext {
+    /** Human-readable error message (the assembled `errorMessage`; any `[code]` prefix already stripped). */
     error: string;
+    /** Machine-readable kind — the assembled `errorCode` lifted from the brain's `[code]` prefix
+     *  (auth / network / rate_limit / server_error / …); absent when the provider stamped no code. */
     errorKind?: string;
+    /** Turns completed when the failure ended the run. */
     turns: number;
 }
+/** 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). */
     error: string;
+    /** Wide any-abort semantics (⊇ CC `is_interrupt`, which is user-interrupt specifically): true when
+     *  the task abort signal fired — timeout, budget, cancel or suspend — not only a human interrupt. */
     isInterrupt: boolean;
+    /** Tool execution time in ms when the engine has it (CC 0.3.202 `duration_ms` parity); else absent. */
     durationMs?: number;
+    /** Element-level clone of the error result's content blocks (mutating them cannot rewrite the
+     *  transcript — the failure is observe-only). */
     content: Array<TextContent | ImageContent | DocumentContent>;
+    /** BEST-EFFORT deep clone (structuredClone) of the tool's raw details. When the details graph is
+     *  not structured-cloneable (functions/handles), this is the LIVE reference — treat it as
+     *  READ-ONLY: a mutation would corrupt the result the loop is about to commit. */
     details: unknown;
 }
+/** A PostToolUseFailure result: append model-readable context to the error result (CC-exact, no rewrite). */
 export interface PostToolUseFailureResult {
     additionalContext?: string;
 }
+/** One resolved call in a postToolBatch payload (CC PostToolBatchToolCall shape, thin projection —
+ *  `response` is a bounded text digest of the result, never the full details object). */
 export interface PostToolBatchCall {
     toolName: string;
     input: unknown;
@@ -47,88 +223,307 @@ export interface PostToolBatchCall {
     response?: string;
     isError: boolean;
 }
+/** A PostToolBatch result: inject context once for the whole batch at the turn boundary. */
 export interface PostToolBatchResult {
     additionalContext?: string;
 }
+/** Context for {@link Hooks.preCompact} (design/134). */
 export interface PreCompactContext {
+    /** "auto" = threshold-triggered; "manual" = /compact; "forced" = promptTooLong recovery or
+     *  trim-pressure propagation (block is ignored on forced — the compaction is not optional). */
     trigger: "auto" | "manual" | "forced";
+    /** The summarization instructions in effect (spec/deployment-level), when set. */
     customInstructions?: string;
 }
+/** A PreCompact result: skip this compaction (auto/manual only) and/or extend the summary instructions. */
 export interface PreCompactResult {
+    /** When set (and trigger is not "forced"), this compaction is skipped; the reason is traced. */
     block?: string;
+    /** Appended to the summarization instructions for this compaction (never replaces them).
+     *  LLM-summary path only: a compaction served from a `summaryProvider` reuse (Seam C) never runs
+     *  the summarization call, so these instructions are not consumed there (recorded design gap —
+     *  extending the provider contract is out of scope for design/134). */
     additionalInstructions?: string;
 }
+/** Context for {@link Hooks.postCompact} (design/134, observe-only). */
 export interface PostCompactContext {
     trigger: "auto" | "manual" | "forced";
+    /** The conversation summary the compaction produced (CC `compact_summary` parity). */
     summary: string;
     tokensBefore?: number;
     tokensAfter?: number;
 }
+/** Context for the {@link Hooks.stop} hook (CC `stop_hook_active` parity). */
 export interface StopHookContext {
+    /** True when this run is already continuing because a previous stop() blocked — check it and
+     *  return success (undefined) once your condition can't be improved, or you will loop to the cap. */
     stopHookActive: boolean;
+    /** Consecutive blocks so far in this run (resets when a stop() call lets the run proceed). */
     consecutiveBlocks: number;
+    /**
+     * RB-177 ([1730], measured downstream) — a view of the conversation this hook is being asked to judge.
+     *
+     * Until now a Stop hook received two counters and nothing else. That is enough for a hook that asks
+     * "have I blocked too often?", and structurally insufficient for the entire class of hooks that ask
+     * anything ABOUT THE RUN — which is what the prompt-shaped hooks a settings file can declare are for.
+     * Measured end to end downstream: the carrier was constructed, invoked, and returned without error, and
+     * the model answered "I don't have direct access to your file system…" — because nobody had given the
+     * evaluator the session. Every layer reported success and the feature could not work. A hook cannot
+     * judge a run it cannot see, so the gap belonged here rather than in any of the layers that were
+     * dutifully passing an empty view along.
+     *
+     * LAZY on purpose: a hook that only reads the counters pays nothing, and a hook that needs the
+     * conversation gets it in full rather than through a truncation policy the engine would have to invent
+     * on its behalf. Callers decide what to send to a model and how much — that decision has a budget and a
+     * trust tier attached, and both belong to the caller.
+     *
+     * Absent when the runner cannot supply one (a stop gate wired without a session).
+     */
     getBranch?: () => Promise<readonly SessionTreeEntry[]>;
 }
+/** A Stop hook result: block the run from ending, with a model-readable reason. */
 export interface StopHookResult {
+    /** When set, the run does NOT end: this reason is injected (as a `<system-reminder>`) and the
+     *  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).
+     */
     additionalContext?: string;
 }
+/**
+ * A READ-ONLY path-resolution capability face over the task's {@link ExecutionEnv}, handed to tool hooks
+ * on {@link HookToolContext.env} (the hook-env capability seam).
+ *
+ * **Why it exists.** A hook that judges a path — "is this write inside the workspace", "does this
+ * innocent-looking name resolve onto a guarded file" — must resolve it in the filesystem the HANDS
+ * actually write to. For a sandboxed/remote deployment that filesystem is NOT the host process's `fs`:
+ * the env is minted by `RunnerDeps.executionEnvFactory` DURING prepare, i.e. after the spec (and any
+ * policy/hook the caller built with it) already exists, so a hook closed over a spec-time env resolves
+ * against the wrong disk and answers `exists`/symlink questions about a different machine. Reading the
+ * env off the CALL CONTEXT removes the ordering problem structurally: the context is built after the env
+ * is, and a resumed/revived run's rebuilt env is picked up with no re-instantiation protocol.
+ *
+ * **Capabilities, not the object.** Hooks are an extension boundary the deployment fills with code whose
+ * job is to DECIDE; the whole `ExecutionEnv` is a face that can ACT (`exec`, `writeFile`, `remove`,
+ * `cleanup`). So this is four INDEPENDENTLY BOUND read primitives and nothing else: no `env`
+ * back-reference, no prototype of the env object, and the face itself is frozen (a hook cannot re-point a
+ * member for a later hook in the same run). Widening it later is additive and cheap; taking a wide object
+ * back is not.
+ *
+ * The line this draws, stated so nobody reads more into it: it separates what a hook is HANDED from what
+ * the environment can do. It is NOT an isolation boundary against code that can already reach the env's own
+ * class — anything that can redefine `SomeExecutionEnv.prototype.exec` intercepts every call the ENGINE
+ * makes into that env, receiver included, and needs nothing from this face to do it. Deployments that must
+ * withstand that run their hooks somewhere else, not behind a narrower argument.
+ *
+ * **Names are the env's own** ({@link ExecutionEnv} / `FileSystem`), deliberately: a hook author reads one
+ * contract, not a translation of it. The seam sketch's `canonicalize`/`root` are `canonicalPath`/`cwd`
+ * here — `canonicalPath` IS the realpath-semantics primitive, and `ExecutionEnv` declares no "root" at all
+ * (the engine's task root is a RUNNER notion — `deps.rootPath`/worktree/`requestedCwd` — not something the
+ * environment reports about itself), so the honest anchor is the env's own working directory. `cwd` is a
+ * FUNCTION, not the snapshot string, so a hook reading it late sees where the env is NOW. Read {@link
+ * HookEnvCapabilities.cwd} before using it as a base for RELATIVE paths — the task's tracked cwd is a
+ * different value, and this face carries the env's, on purpose.
+ *
+ * **Every member is optional, and absence is the signal.** A member is present iff the underlying env
+ * exposes that primitive (`readLink` is optional in `FileSystem`; a transport env may implement less than
+ * it declares). A missing member is never a stub that throws or an emulation that guesses — the hook is
+ * told, in the only way that cannot be misread, that this environment cannot answer, and takes its own
+ * conservative branch. The face carries a NULL PROTOTYPE so that reading is a question about this object
+ * alone (see {@link createHookEnvCapabilities}). Errors that the env CAN report stay in the `Result`
+ * (these methods never throw, inheriting the `FileSystem` contract verbatim).
+ */
 export interface HookEnvCapabilities {
+    /** {@link ExecutionEnv.canonicalPath} — the canonical path of an EXISTING path, symlinks resolved
+     *  (realpath semantics), in the env's own namespace. */
     canonicalPath?(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** {@link ExecutionEnv.exists} — `false` for a missing path; other failures (permission, transport)
+     *  come back as a `FileError`, which is NOT an answer of "absent". */
     exists?(path: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
+    /** {@link ExecutionEnv.readLink} — a symlink's raw target, ONE hop, not followed. Absent whenever the
+     *  env omits the primitive: a DANGLING symlink's real target is then unknowable to the hook. */
     readLink?(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /**
+     * {@link ExecutionEnv.cwd} — the ENVIRONMENT's own working directory, read live: the base the env's own
+     * primitives resolve a relative path against, and the only anchor it reports about itself.
+     *
+     * NOT the task's tracked cwd, and the difference is load-bearing for anyone judging a RELATIVE path.
+     * The engine keeps a separate per-task cwd — it starts at the resolved task root (which is
+     * `deps.rootPath` when that is set, not necessarily the env's cwd) and moves with the shell's `cd` and
+     * with worktree entry — and the TOOLS' relative paths resolve against THAT, while the environment is
+     * never told it moved. So a hook that must decide a relative target the way the tool will interpret it
+     * cannot take the base from here: judge absolute targets, or have the deployment hand the tracked cwd
+     * to the hook through its own channel. What this member is good for is the env-side anchor — which
+     * filesystem/mount the answers below are about.
+     */
     cwd?(): string;
 }
+/**
+ * Build the {@link HookEnvCapabilities} face for `env`. One wrapper per primitive (never a bound method of
+ * the env, never the env itself), presence probed at build time so the face's shape reports what this env
+ * can actually do, and frozen so it cannot be re-pointed by whoever receives it.
+ *
+ * Two details the "absent means cannot" contract rests on, both cheap and both load-bearing:
+ *  · **null prototype, both ways.** Absence must be a fact about THIS object — on the way OUT (a face
+ *    behind `Object.prototype` would answer `ctx.env.readLink` from there, turning "this env cannot read
+ *    links" into "here is some function"; freezing the face does not freeze what it inherits) and on the
+ *    way IN ({@link findEnvSlot} stops before `Object.prototype`, so an ambient property of that name is
+ *    never adopted as a capability and never gets called with the env as its receiver).
+ *  · **capture, do not re-read.** Each primitive is read ONCE, checked, and that captured callable is what
+ *    the wrapper invokes — through module-load-captured intrinsics, never a build-time or call-time global
+ *    lookup. Re-reading the property, or the machinery that does the reading, would let something other
+ *    than what was validated end up running, or the receiver end up somewhere it was never handed.
+ *    {@link createCwdReader} carries the one live read under the same rules.
+ */
 export declare function createHookEnvCapabilities(env: ExecutionEnv): HookEnvCapabilities;
+/** Identifying context passed to tool hooks. */
 export interface HookToolContext {
     toolCallId: string;
     toolName: string;
+    /**
+     * The read-only path-resolution face over the env the hands run against (see
+     * {@link HookEnvCapabilities} for the why, and for why it is capabilities rather than the env object).
+     *
+     * ABSENT when the deployment wired no execution environment at all (no `executionEnv` /
+     * `executionEnvFactory`: the run has no hands, and the engine's internal no-I/O placeholder is not an
+     * environment to report). Present ⇒ inspect the individual members: each one is itself optional.
+     */
     env?: HookEnvCapabilities;
 }
+/** The executed tool result a PostToolUse hook inspects. */
 export interface HookToolOutput {
     content: Array<TextContent | ImageContent | DocumentContent>;
     details: unknown;
     isError: boolean;
 }
+/**
+ * A PreToolUse hook result: a {@link PermissionResult} (so a hook can `deny`/`ask`, or `allow` with an
+ * `updatedInput` rewrite) plus optional `additionalContext` injected into the eventual tool result.
+ */
 export type PreToolUseResult = PermissionResult & {
     additionalContext?: string;
 };
+/** A PostToolUse hook result: replace the tool output and/or append context (both optional). */
 export interface PostToolUseResult {
+    /** If provided, replaces the tool result content array in full. */
     updatedOutput?: Array<TextContent | ImageContent | DocumentContent>;
+    /** Appended to the result as a `<system-reminder>` the model can read. */
     additionalContext?: string;
 }
+/** A UserPromptSubmit hook result: block the submission, or inject context ahead of the prompt. */
 export interface UserPromptSubmitResult {
+    /** Block submission entirely; the task fails with this model-readable reason. */
     block?: string;
+    /** Injected ahead of the user's prompt (wrapped as a `<system-reminder>`). */
     additionalContext?: string;
 }
+/** Wrap model-facing hook/gate feedback in a `<system-reminder>` so it reads as guidance, not data.
+ *  NOTE (council design/74 #6): this does NOT escape a literal `</system-reminder>` in `text` — callers MUST
+ *  pass trusted, first-party strings (every current caller does: fixed gate/limit messages). If a future
+ *  caller needs to relay UNTRUSTED content (tool output, user data), it must sanitize the close tag first
+ *  (or use the `delimitUntrusted` fence), or a crafted payload could break out of the reminder framing. */
 export declare function formatHookFeedback(text: string): string;
+/** The outcome of the two-phase tool gate, mapped onto the harness `tool_call` hook return shape. */
 export interface ToolGateResult {
+    /** Block execution (the loop emits an error tool result with `reason`). */
     block?: boolean;
+    /** Model-readable block reason (already `<system-reminder>`-wrapped). */
     reason?: string;
+    /**
+     * What ended the approval this call was waiting on, when this gate pass settled one (the ask
+     * resolution's own {@link import("./tool-policy.js").ApprovalSettledBy}, carried out verbatim — this
+     * layer classifies nothing). Present on BOTH terminal exits, the block and the allow: an approved
+     * call is a settled approval too, and a caller that saw the source only on refusals would read its
+     * absence on an execution as "nobody approved this". Absent on everything that settled no approval —
+     * a straight policy deny, a hook deny, a posture verdict where nobody was asked, every ordinary
+     * allow. The caller records it on its own per-call sideband so it reaches that call's `tool_end`
+     * frame: the machine-readable half of the disclosure `reason` makes in words, on a channel no tool
+     * and no post-tool hook can write.
+     */
     settledBy?: import("./tool-policy.js").ApprovalSettledBy;
+    /** Rewritten args to execute with (re-validated by the loop); omitted when nothing rewrote. */
     updatedInput?: unknown;
+    /**
+     * design/45: the gate routed a policy `ask` to a **durable suspension** (no synchronous approver).
+     * `suspendAsk` already persisted the checkpoint and aborted the run; the caller records this so the
+     * task assembles as `status:"suspended"` with the token. Suspend lives ONLY here in the gate's `ask`
+     * branch — it never becomes a `PermissionResult` action (policy stays pure allow/ask/deny, §15.2).
+     */
     suspend?: {
         token: import("./checkpoint-store.js").CheckpointToken;
         gate: import("./checkpoint-store.js").CheckpointGate;
     };
+    /** PreToolUse `additionalContext` to append to this call's eventual tool result (correlated by id). */
     preToolContext: string[];
 }
+/**
+ * The gate's content-ask routing outcome — deliberately a channel of its OWN, not a
+ * field on the permission verdict. A permission verdict is folded, re-adjudicated and re-presented by
+ * layers that know nothing about answers; an answer riding one of those would be dropped by the fold or
+ * carried into a second adjudication. Three arms, one per thing that can happen:
+ *  · `answered` — a person answered. The gate lets the call execute and the answer is delivered to the
+ *    tool through the run's own one-shot binding (the gate never carries the answer itself).
+ *  · `unavailable` — nobody was reachable and NOTHING was shown (the {@link
+ *    import("./ask-question.js").QuestionUnavailable} contract). Only this arm may be re-routed — the
+ *    gate parks the question for a later human, or answers the honest "it was NOT shown" refusal.
+ *  · `delivery_failure` — delivery was attempted and failed. NEVER re-routed: the question may already
+ *    have been rendered to a person, so parking it would put one question in front of two deciders. It
+ *    is reported to the model through the tool's own coded-failure / degrade exits.
+ */
 export type ContentAskOutcome = {
     kind: "answered";
+    /** The EXACT batch that was put in front of the person, retained by the resolver as an isolated
+     *  snapshot. The gate executes this and nothing else, so "what was shown" and "what runs" are the
+     *  same object graph by construction rather than by two parties agreeing not to mutate one. */
     presentedInput: unknown;
 } | {
     kind: "unavailable";
+    /** The retained snapshot, when the resolver got far enough to make one (i.e. it actually waited
+     *  on a callback). The park persists THIS, not the caller's live object: the wait is a window in
+     *  which whoever owns the rewrite can change it, and a checkpoint holding bytes the gate never
+     *  adjudicated is one a later human would answer as a different question. Absent when no wait
+     *  happened, in which case there is no window and the live object is still the validated one. */
     presentedInput?: unknown;
+    /** True iff the park closure took its SYNC-FIRST DECLINE for this call — it has not yet made a
+     *  real suspend attempt, so re-entering it now IS that attempt rather than a second one. False
+     *  when the park already had its attempt (no live face to prefer, or a durable mandate): the gate
+     *  must not re-enter, because a suspend and a checkpoint write are not idempotent, and a backend
+     *  that committed before surfacing a transport error would be left an orphan row under a second
+     *  token. Exactly one real attempt per call, on every path. */
     parkDeclined: boolean;
 } | {
     kind: "delivery_failure";
     code: string;
+    /** The retained snapshot, when the resolver got far enough to make one. Executed for the same
+     *  reason the answered arm's is: the bound failure names the batch it belongs to, and executing a
+     *  different one would drop it and re-ask the person. Absent when the refusal happened before a
+     *  snapshot could be taken. */
     presentedInput?: unknown;
 };
+/**
+ * A durable park that was ATTEMPTED for this call and could not be minted, carrying the reason in the
+ * words of whatever refused it. Distinct from the `undefined` return, which means "no park attempt
+ * happened" (no facility armed, or the closure took its sync-first decline) — that case hides nothing,
+ * while this one does: the gate falls back to the synchronous approver chain either way (the
+ * compensation contract — an uncommitted checkpoint is a safe fallback — is unchanged), but on a
+ * headless deployment that fallback is the auto-deny whose text is "no approver is wired". True as far
+ * as it goes, and the whole reason the call did not park lives somewhere else entirely (the host's
+ * `onError` face). So the reason travels with the fall-through and the deny quotes it.
+ */
 export interface ParkAttemptFailed {
+    /** Why the park could not be minted — a sentence, already worded for a reader. */
     parkFailed: string;
 }
+/** Inputs to the two-phase tool gate. `adjudicate`/`resolveAsk` are pre-bound to the task abort signal. */
 export interface ToolGateInput {
+    /** RB-473 batch 2b — bounded disclosure for a HOST callback that throws inside this gate call's
+     *  isolation scope (onHookError itself, the deny observer, the durable-park observer). The runner
+     *  wires this to an `observer.notify_failed` trace event; absent = counted only (unchanged). */
     onNotifyError?: (failure: import("./safe-notify.js").SafeNotifyFailure) => void;
     event: {
         toolCallId: string;
@@ -136,29 +531,181 @@ export interface ToolGateInput {
         input: Record<string, unknown>;
     };
     preToolUse?: Hooks["preToolUse"];
+    /** 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. */
     hookEnv?: HookEnvCapabilities;
+    /** The combined tool-policy check (abort-bound), or undefined when no policy is wired (→ allow). */
     adjudicate?: (req: ToolCallRequest) => Promise<PermissionResult>;
+    /** Resolve an `ask` to allow/deny via `onAsk` (abort-bound). Required iff a decision can be `ask`.
+     *  G1 three-value ([871]①): the result may carry `approverUnavailable` — the live approver affirmed no
+     *  operator is reachable for THIS ask; the gate then re-routes onto the durable park leg (below),
+     *  keeping the carried fail-closed deny when no park is armed. */
     resolveAsk: (decision: PermissionResult, req: ToolCallRequest) => Promise<ResolvedAsk>;
-    suspendAsk?: (req: ToolCallRequest, postHookArgs: unknown, safety?: import("./checkpoint-store.js").SafetyAxis, liveFaceUnavailable?: boolean) => Promise<ToolGateResult["suspend"] | ParkAttemptFailed | undefined>;
+    /**
+     * design/45: route a policy `ask` to a **durable suspension** instead of the synchronous `resolveAsk`
+     * (onAsk) path. Called in the `ask` branch with the FINAL post-hook args; if it returns a suspend
+     * directive it has already persisted the checkpoint + aborted the run, and the gate short-circuits to
+     * `{ suspend }`. Returns `undefined` to fall through to `resolveAsk` (non-durable / declined). A
+     * {@link ParkAttemptFailed} ALSO falls through to `resolveAsk` — same fallback, same compensation —
+     * but carries why the mint failed so a resulting deny can name it instead of leaving the model and
+     * the operator with the fallback's own reason as if it were the cause.
+     * Omitted entirely → no durable mode (the 1.63 synchronous path, unchanged).
+     *
+     * The armed closure itself may also DECLINE (return `undefined` up front) to prefer the live
+     * synchronous approver: the Runner's closure does so for a plain AND for a SAFETY ask whenever the
+     * resolved seat is a FUNCTION-valued `onAsk` — even under `durableApproval`, which is the FALLBACK for
+     * when no live approver is present, not an "always park" mandate — an interactive per-edit ask must
+     * resolve in-stream, not cost a park/rebuild round-trip. The gate stays a pure fall-through consumer of
+     * that choice. What KEEPS the durable leg is no function seat (absent, or a blanket `"allow"`/`"deny"`
+     * string mode — a policy setting is not a live approver), a control-plane `forceDurableGate`, a live
+     * face that already answered `"unavailable"` for this ask, or an inherited-unavailable marked call.
+     * `safety` no longer participates in the park/sync decision at all — it only selects the gate KIND
+     * (`irreversible_ask`) once a park is minted.
+     */
+    suspendAsk?: (req: ToolCallRequest, postHookArgs: unknown, 
+    /** design/80 D-2: present (non-undefined) ONLY when this ask is a SAFETY tighten (the egress/
+     *  irreversibility gate tightened a surviving `allow` to `ask`, `decisionReason === "safety"`). Drives the
+     *  mint-site gate-kind choice — a safety tighten mints `irreversible_ask` (non-budgetable) EVEN WHEN
+     *  `durableApproval` is wired. The object records which axis(es) tightened (persisted as the gate's
+     *  `safetyAxis`). Absent for a plain policy/hook `ask` (→ the normal `human`/`irreversible_ask` choice). */
+    safety?: import("./checkpoint-store.js").SafetyAxis, 
+    /** The three-valued live-face verdict, widened by design/174 to cover BOTH live faces: true ⇒ the live face this
+     *  ask would have been routed to already answered `"unavailable"` for it — the permission approver for
+     *  a permission ask, the question face for a content ask. Either way there is no live leg left to
+     *  prefer, so the closure must NOT take its sync-first decline and should park durably. All other
+     *  decline/pre-commit-failure paths keep their existing `undefined` fallbacks (the gate then keeps the
+     *  fail-closed deny / typed refusal the caller carries). */
+    liveFaceUnavailable?: boolean) => Promise<ToolGateResult["suspend"] | ParkAttemptFailed | undefined>;
+    /**
+     * design/174 — route a policy `ask` on the reserved question tool to this run's CONTENT-ask channel
+     * before it can become a park or a refusal. Called in the `ask` branch with the FINAL post-hook,
+     * post-policy request (the same args that will execute), and it owns everything about delivery:
+     * validating the batch before anything is put in front of a person, calling the live face, and binding
+     * the answer to this call id for the tool to pick up. It returns only WHICH of the three outcomes
+     * happened — never the answer, which travels the run's own binding.
+     *
+     * CONTRACT: it must not throw (a delivery failure is a returned value, so the gate can tell "failed"
+     * from "nobody home" — the two have opposite re-routing rules). Passed UNCONDITIONALLY by the runner,
+     * including on runs with no live face: it then answers `unavailable` without contacting anything, which
+     * is exactly the pre-174 park/refusal behavior. Absent entirely ⇒ the pre-174 path verbatim.
+     */
     resolveContentAsk?: (req: ToolCallRequest) => Promise<ContentAskOutcome>;
+    /**
+     * design/70: the called tool is egress-marked (`ToolSpec.egress` — an external write: open a PR,
+     * push, send). The gate tightens a surviving `allow` to `ask` so an egress tool is NEVER
+     * auto-allowed — execution always passes an explicit ask-resolution (onAsk / durable suspend);
+     * headless resolves to deny. Filled by the caller from the tool's spec; policies stay egress-blind.
+     */
     egress?: boolean;
+    /**
+     * design/77 §4 (Gate 4): the called tool's irreversibility tier (`ToolSpec.irreversibility`), filled by
+     * the caller from the tool's spec. After the egress tighten, the gate runs a SECOND deterministic tighten:
+     * `"always"` tightens a surviving `allow` to `ask`; `"maybe"` calls {@link reversibilityProbe} and tightens
+     * UNLESS the probe reports reversible (fail-closed on timeout/throw); `"never"`/undefined → untouched.
+     * Policies stay irreversibility-blind; the gate is the single chokepoint.
+     */
     irreversibility?: "never" | "maybe" | "always";
+    /**
+     * design/77 §4: the `"maybe"`-tier probe from the tool's spec (read at prepare-time, captured here — not a
+     * tool argument). Called ONLY when `irreversibility === "maybe"` && the surviving decision is `allow`,
+     * time-bounded by {@link approvalTimeoutMs}. Fail-closed: anything other than `{ reversible: true }`
+     * (including a timeout or a throw) tightens to `ask`. A probe is never trusted to AUTO-ALLOW past the gate.
+     */
     reversibilityProbe?: (args: unknown) => {
         reversible: boolean;
     } | Promise<{
         reversible: boolean;
     }>;
+    /** design/77 §4: deadline (ms) for {@link reversibilityProbe}; on timeout the gate fails closed to `ask`. */
     approvalTimeoutMs?: number;
+    /** design/77 §4: the task abort signal — bounds {@link reversibilityProbe} by the task's real deadline
+     *  (timeout/cancel) in addition to {@link approvalTimeoutMs}; an abort while probing fails closed to `ask`. */
     abortSignal?: AbortSignal;
+    /**
+     * 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.
+     *
+     * 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.
+     */
     permissionDenied?: (payload: PermissionDeniedPayload) => void | Promise<void>;
+    /**
+     * RB-442: trace sink for a PreToolUse hook that THREW — the deployment-facing half of the crash
+     * (`onError(phase:"hook")`, wired by the caller). The model-facing half is the fail-closed block reason;
+     * this one carries the exception object itself to whoever runs the deployment, because a crashing hook is
+     * a bug someone has to fix and the model-facing summary is bounded/sanitized. Never affects the outcome
+     * (a throwing sink is swallowed).
+     */
     onHookError?: (err: unknown) => void;
+    /**
+     * design/134 R5: true when this tool's `irreversibility` tier was installed by the COARSE
+     * `TaskSpec.shellGate` doctrine (design/80 D-E `shellGatedBash`/`shellGatedMonitor`), not an explicit
+     * per-tool mark — attributes a tighten-deny to `source:"shellGate"` instead of `"safety"`.
+     */
     shellGated?: boolean;
+    /**
+     * design/143 批2 ([672]-A, CC 2.1.207 auto mode): when present, a surviving `ask` is routed to the
+     * small-model policy CLASSIFIER before any human/durable resolution:
+     *  - verdict `allow` → the ask resolves to allow (`decisionReason:"classifier"`) — no suspend, no onAsk;
+     *  - verdict `block` → deny (`decisionReason:"classifier"`, `source:"classifier"`; CC `automode-blocked`);
+     *  - `unavailable`/`parse_error` → FAIL-CLOSED: the ask continues down the ORIGINAL chain
+     *    (durable suspend / onAsk / headless auto-deny) exactly as if auto mode were absent
+     *    (CC `automode-unavailable`/`automode-parsing-error` — "NOT a policy decision").
+     * SCOPE (declared semantic): this covers EVERY surviving ask, INCLUDING the deterministic egress/
+     * irreversibility safety tightens — auto mode is the deployment's explicit choice to let the
+     * classifier be the "explicit ask-resolution" for this session (its rule set covers exactly those
+     * action classes: outbound writes, irreversible operations, and sensitive-value handling). A
+     * deployment that wants human-only
+     * resolution for safety asks simply does not arm auto mode. The classifier can never AUTO-ALLOW by
+     * failing — only an affirmative `<block>no</block>` allows.
+     */
     autoMode?: {
         decider: import("./auto-mode.js").AutoModeDecider;
     };
+    /**
+     * design/153 §2/§7.4 (件4 复审, MED): true means this call's ask is MARKED — an inherited ancestor
+     * constraint already determined "no synchronous layer may resolve this ask" (the ancestor's frozen
+     * approver was unreachable, OR an ancestor durable mandate was floated back because THIS task's own
+     * park facility can honor it). The marker's whole contract is that the ask reaches EITHER the durable
+     * park leg OR the fail-closed `resolveAskBound` intercept, with no synchronous decision-maker in
+     * between — the auto-mode classifier is exactly such a decision-maker (`decide()` can `allow`, executing
+     * the call) and sat strictly BEFORE both marker consumers, so a marked call under an armed classifier
+     * bypassed the marker's contract entirely. When true, the classifier step is skipped (falls through to
+     * `suspendAsk`/`resolveAsk` untouched) so a marked ask can only ever be resolved by an operator (durable
+     * park) or fail closed — never by the classifier.
+     */
     isMarkedUnresolvable?: (toolCallId: string) => boolean;
+    /**
+     * design/179 — the persisted allow-rule lane. Present only when a deployment wired a rule store; absent
+     * it, this whole step does not exist and the gate's decision path is byte-identical to what it was.
+     *
+     * A persisted rule is the standing form of ONE recorded human approval, so it resolves the asks a real
+     * person saying "allow" would have resolved — and nothing else. It sits post-fold, at the entry of the
+     * `ask` branch, BEFORE the classifier and AFTER every tighten: earlier and a tighten would simply put
+     * the ask back; later and the classifier would already have spoken.
+     *
+     * Its consumption predicate is its own, not the classifier's blanket flip:
+     *  · `requiresRealApproval` asks are never consumed — the two integrity gates are the floor, and the
+     *    same flag is what a v2 organization-level ask will carry;
+     *  · a PreToolUse hook's ask is never consumed — that is the deployment's own adjudication, and a rule
+     *    minted for a command does not overrule it;
+     *  · the reserved question tool and a call MARKED unresolvable are excluded for the same reason the
+     *    classifier excludes them: both contracts require that no synchronous decision-maker stands between
+     *    the ask and the park / content route, and this lane is one.
+     * What it DOES consume is the egress and irreversibility/shellGate tightens and unmarked bare asks —
+     * deliberately, because a deployment forcing shell classification is exactly where the feature is for.
+     * Consuming such an ask also skips the park it would have minted; that IS what a standing approval
+     * means, and the first bullet is what keeps an integrity ask out of that set.
+     */
     persistedRules?: {
+        /** The canonical text of the rule that admits this call, or `undefined`. Must not throw: a store that
+         *  cannot be read answers "no rule" and discloses on its own channel (fail-closed = more asks). */
         admits: (req: ToolCallRequest) => Promise<string | undefined>;
+        /** Observation sink for an ask a rule resolved — the allow-side disclosure. Never affects the outcome. */
         onResolved?: (info: {
             toolName: string;
             toolCallId: string;
@@ -166,5 +713,65 @@ export interface ToolGateInput {
         }) => void;
     };
 }
+/**
+ * Fold a {@link Hooks.preToolUse} callback into a {@link ToolPolicy} layer, so a screening face a task
+ * installed for ITSELF can also travel down a delegation chain as one more inherited constraint.
+ *
+ * Why a policy and not a second hook channel: a delegated child already folds each ancestor's caller
+ * policy (`InheritedGate.parentConstraints`), and that fold is where `deny > ask > allow`, the rewrite
+ * cascade, the ancestor-frozen approver and the durable mandate all already live. Expressing the
+ * screening face in the same shape means the child gains no new decision channel — the existing fold
+ * consumes it — and the tighten-only property is structural rather than restated.
+ *
+ * The mapping mirrors the gate's own phase 1 (see {@link runToolGate}) decision for decision:
+ *  - no opinion (`undefined`) → `allow`, contributing nothing;
+ *  - `deny` → `deny` in the fold's own words (the fold short-circuits, and the gate's deny exit supplies
+ *    the same `formatHookFeedback` envelope phase 1 would have);
+ *  - `ask` → `ask`, stamped `decisionReason:"hook"` so every consumer that distinguishes a screening ask
+ *    from a policy ask reads the same fact one level down — notably the persisted-rule lane, which must
+ *    not let a standing allow-rule resolve a screening ask;
+ *  - `allow`/`ask` with `updatedInput` → the same rewrite, which the fold cascades to later layers and
+ *    re-checks against the narrowing layers;
+ *  - a THROW → the fail-closed deny with the RB-442 attribution text (naming the hook and the
+ *    non-execution), because a screening face that cannot answer must not pass the call.
+ *
+ * **The callback inherits the fold's idempotency requirement** ({@link combinePolicies}): a layer's
+ * `check` may run more than once for a single tool call — the fold scans past an `ask` looking for a
+ * later `deny`, a rewrite emitted by a LATER layer re-runs the prefix that never saw the final args, and
+ * an approved operator edit is re-adjudicated. A callback whose consultation has a side effect (an audit
+ * row, a counter) will therefore see that call more than once on those paths. Its own gate's phase 1 has
+ * always had the second of these (an approved edit is re-screened there too).
+ *
+ * Two properties are deliberately NOT carried, and neither is reconstructible in this shape:
+ *  - `additionalContext` — a policy verdict has no channel for model-facing text. Context a screening
+ *    face injects is a property of the run whose gate ran it; a descendant's transcript does not receive
+ *    it. (The decision half — the part that restricts — is what travels.)
+ *  - the phase-1 observer exclusion — a deny raised here is a fold deny, so the descendant's
+ *    `permissionDenied` observer sees it with `source:"policy"`. That exclusion is about a hook deciding
+ *    in ITS OWN gate; here the descendant's policy fold is what refused the call.
+ *
+ * `env` is the capability face of the environment the callback was installed against — captured at the
+ * install site, not rebuilt in the descendant, for the same reason an inherited policy closure keeps its
+ * own captured environment (the descendant may run against a different root). `onCrash` is the install
+ * site's deployment error lane: the gate's phase 1 routes a crashing callback to `onError(phase:"hook")`
+ * 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;
+/**
+ * The design/37 **two-phase tool gate** — the single chokepoint that makes the load-bearing invariant
+ * structural ("a hook's `allow` cannot bypass the policy's `deny`/`ask`"):
+ *
+ *  1. **collect** — run the PreToolUse hook, threading any `updatedInput` rewrite into `currentInput`
+ *     and collecting `additionalContext`. A hook `deny` short-circuits to a block immediately; a hook
+ *     `ask` is remembered (it does not short-circuit — a later policy `deny` outranks it).
+ *  2. **adjudicate** — run the tool policy on the FINAL `currentInput` (never the model's stale args),
+ *     fold it with any remembered hook-ask via `deny > ask > allow`, and resolve a surviving `ask`
+ *     through `onAsk`. The policy ALWAYS runs regardless of the hook's verdict. A policy `allow` may
+ *     itself carry an `updatedInput` rewrite (redact/clamp), applied last over any hook rewrite.
+ *
+ * Because both phases run in this one linear function, the ordering — and the "policy is final"
+ * invariant — is enforced by the call stack, not by registration convention. Returns the gate result
+ * for the harness `tool_call` hook plus the PreToolUse context to attach to the tool result.
+ */
 export declare function runToolGate(input: ToolGateInput): Promise<ToolGateResult>;