@sema-agent/core 5.19.0 → 5.21.0

package/dist/core/tool-policy.d.ts

@@ -1,18 +1,133 @@
+/** A tool call presented to a policy before it executes. */
 export interface ToolCallRequest {
     toolName: string;
     args: unknown;
     toolCallId: string;
+    /**
+     * RB-108 — the LIVE working directory this call's RELATIVE path arguments will actually resolve
+     * against, read at adjudication time from the same tracked `cwdRef` the fs hand tools resolve with
+     * (design/64 §16.3: a resident shell's `cd` persists and moves the fs tools' relative base with it).
+     *
+     * WHY IT EXISTS: every path guard here (sensitive-path, fs-write gate, session rules, skill scope,
+     * transcript integrity) re-resolves the model's spelling itself, and each was handed a STATIC root at
+     * wiring time. After a `cd` the two sides of a single call disagreed about which file it was: the tool
+     * wrote `<liveCwd>/pre-commit` while the guard judged `<wiringRoot>/pre-commit` — measured on a host
+     * lane, `cd .git/hooks` + `Write("pre-commit")` landed a git hook past a guard that names `.git/hooks`.
+     * Reading THIS field makes the guard's resolution base the same value the tool will use.
+     *
+     * Applies to the call's TARGET only. A guard's own configured directories (accept/exempt domains,
+     * `allowDirs`, manifest `allowPaths`) are DEPLOYMENT text and keep resolving against the static root —
+     * a shell `cd` must never relocate an allow-domain.
+     *
+     * ABSENT when the run has no tracked cwd (read-only hands, no execution env) or when a policy is
+     * invoked directly outside a Runner: consumers then fall back to their own configured root, which is
+     * exactly the pre-RB-108 behavior. Read-only — a policy cannot move the shell by writing it back.
+     *
+     * RESIDUAL (recorded honestly — this is a snapshot of a mutable ref, not a frozen binding): the gate
+     * reads the ref when it adjudicates and the tool reads it again when it executes. No interleaving that
+     * moves the cwd in between is constructible on the current loop, and it is worth naming WHY, because
+     * the reason is a property of the tool declarations rather than of this field: the loop adjudicates a
+     * whole batch before executing it, but only calls classified concurrency-safe ever share a batch, and
+     * every cwd MOVER (a `cd`-bearing Bash — `cd` is not on the readonly allowlist and any shell operator
+     * disqualifies — plus the worktree enter/exit tools) and every path-confinable WRITE tool declares
+     * `effect: "write"`, which derives `executionMode: "sequential"`, which forces a batch of one. A
+     * deployment tool that declared itself read/parallel while moving the shared cwd would reopen the
+     * window — at that declaration, not here.
+     */
     cwd?: string;
+    /**
+     * design/80 D-E-core: read-only per-run budget snapshot so a STATELESS policy can self-limit against
+     * state that survives suspend/resume (a fresh in-memory counter would reset every leg — the supervisor
+     * escalation-budget gap). Built by core at prepare time from the DURABLE resource ledger
+     * ({@link import("./checkpoint-store.js").ResourceLedger}) + the durable suspend chain; the policy CANNOT
+     * widen it (no write-back). Present on every gated `check()` once the runner builds the gate; absent only
+     * when a policy is invoked directly (outside a Runner). A NORMAL-ask escalation policy reads it; a SAFETY
+     * ask (egress / irreversible) ignores it and ALWAYS asks (invariant #2 stays structural — core mints
+     * `irreversible_ask` for safety tools regardless of any budget).
+     */
     budget?: {
+        /**
+         * Durable resource $ this run may STILL spend (micro-USD); `undefined` = no $ ceiling configured. Frozen
+         * total, prior-wins → it monotonically SHRINKS across legs and is NEVER re-granted by a resume (a
+         * deny-resume continues with the same frozen remaining). **NEVER falsy-test** (`0` = exhausted, NOT
+         * "unlimited" — only `undefined` is unlimited).
+         */
         resourceRemainingMicroUsd?: number;
+        /** Durable cumulative resource $ already spent across all prior legs (micro-USD); accumulates, never refunded. */
         resourceSpentMicroUsd: number;
+        /** How many times this run has already suspended (the durable suspend chain). Lets the policy tighten as
+         *  the chain grows — the precise complement to the unconditional `suspendLoopCap` backstop. */
         suspendCount: number;
     };
 }
+/** Where a decision came from, for audit (design/37). */
 export type DecisionReason = "rule" | "mode" | "hook" | "safety" | "classifier" | "persisted_rule";
+/**
+ * WHO (or what) ENDED an approval — the machine-readable twin of a settlement's human-readable text,
+ * so a consumer tells "a person decided this" from "nobody answered" without prose-matching a sentence.
+ * The sibling axis of {@link DecisionReason}, which says which LAYER produced a verdict; this one says
+ * what ended the WAIT.
+ *
+ *  - `"human"` — a person, or the approver acting for one, returned a final verdict (allow or deny).
+ *  - `"timeout"` — the configured approval window elapsed with no answer.
+ *  - `"aborted"` — every other NON-HUMAN end: the task aborted, the approver threw or reported nobody
+ *    reachable, the decision arrived out of contract, a store or transport gave way, retries ran out.
+ *
+ * The three words are exhaustive and mutually exclusive over the ways an approval can end, and the
+ * minimum discrimination a consumer needs — someone refused vs nobody answered — is `"human"` vs the
+ * other two.
+ *
+ * **Fill it AT the settlement site.** Each site knows its own cause and names it; deriving the value
+ * afterwards from whatever outcome happens to be at hand is exactly how a window that elapsed comes to
+ * be reported as a person's refusal.
+ *
+ * ABSENT means this settlement named no source: an older caller that predates the field, or a verdict
+ * that settled no wait at all (a policy POSTURE — headless auto-deny, a blanket bypass — where nobody
+ * was ever asked). A consumer MUST NOT read a semantic out of the absence; render the text instead.
+ */
 export type ApprovalSettledBy = "human" | "timeout" | "aborted";
+/** The closed set above, for runtime domain checks at the seams that accept a caller-supplied value. */
 export declare const APPROVAL_SETTLED_BY_VALUES: readonly ApprovalSettledBy[];
+/** True iff `v` is one of the three {@link ApprovalSettledBy} words. */
 export declare function isApprovalSettledBy(v: unknown): v is ApprovalSettledBy;
+/**
+ * A three-state permission decision for a tool call (design/37). Upgrades the old two-state
+ * `{allow|deny}`:
+ *  - `allow` may carry `updatedInput` — REWRITTEN args (redact a secret, clamp a path/value) that
+ *    REPLACE the model's args before execution (re-validated against the tool schema first).
+ *    `deny` may ALSO carry `updatedInput` (1.256 复审 MED-2): it never executes anything, but a
+ *    combined-policy deny reports the ACCUMULATED pre-deny rewrite (policy A redacted → policy B
+ *    denied) so a deny OBSERVER (`Hooks.permissionDenied`) sees the final post-rewrite args, not the
+ *    stale un-redacted ones.
+ *  - `ask` requests human confirmation; with no approver wired it resolves deterministically to deny
+ *    (headless auto-deny, see `RunnerDeps.onAsk`). `requiresRealApproval: true` (RB-203 codex review,
+ *    confirmed P1) additionally refuses to let a BLANKET `onAsk: "allow"` bypass clear it — that
+ *    configuration is "no approver looked at this at all", indistinguishable from headless, for a rule
+ *    whose whole point is that a blanket policy setting must not be the thing that clears it (see
+ *    {@link resolveAsk}). A live auto-mode classifier verdict (tried earlier in the gate, if configured)
+ *    or a genuine approver CALLBACK (actual judgment, even if it always says yes) still can.
+ *  - `deny` blocks the call.
+ * Human-readable text is `message`; read it via {@link decisionText}.
+ *
+ * The two TERMINAL arms may also carry {@link ApprovalSettledBy} as `settledBy` — what ended the wait,
+ * when this verdict ended one. It is on `allow`/`deny` and deliberately NOT on `ask`: an `ask` has
+ * settled nothing yet, so a source there would name a decider who has not decided. A layer that never
+ * waited for anyone omits it (see the type's ABSENT clause).
+ * RB-479-B① (ruled 2026-08-02): the legacy `reason` field is REMOVED — one name for one thing.
+ *
+ * How far the TYPE carries that retirement (measured 2026-08-03, correcting this note's earlier claim
+ * that a policy returning `{reason}` "compiles red for TS consumers"): TypeScript's excess-property
+ * check fires only where the decision is a LITERAL in an ANNOTATED position — `const d: PermissionResult
+ * = {…}`, or a `check` written with an explicit `: PermissionResult` return annotation. The ordinary
+ * policy shape, `{ check: () => ({…}) }` with an INFERRED return type (also the method-syntax and
+ * assign-then-return forms), compiles GREEN with a stray `reason`. That is not a hole to plug in the
+ * type system — it is how contextual typing works — so the enforcement is at RUNTIME instead: every
+ * point that CONSUMES a decision REFUSES one carrying an own `reason` property, fail-closed (deny, with
+ * a migration message) — the {@link combinePolicies} fold, the PreToolUse hook face, and the durable
+ * resume-edit rechecks (see {@link refuseOutOfContractDecision}). Same doctrine as the strict `approve`
+ * / `onAsk` folds in this file: an out-of-contract value on the permission face is a loud rejection,
+ * never a best-effort read.
+ */
 export type PermissionResult = {
     action: "allow";
     updatedInput?: unknown;
@@ -32,87 +147,482 @@ export type PermissionResult = {
     decisionReason?: DecisionReason;
     settledBy?: ApprovalSettledBy;
 };
+/** The human/model-readable text of a decision. */
 export declare function decisionText(d: PermissionResult): string | undefined;
+/**
+ * Gates tool calls before they execute (the production safety layer for "processing/changing data").
+ *
+ * `check` runs before each tool call. Return `{ action: "deny", message }` to block it — the model
+ * receives an error tool result with the reason and can continue or report blocked. Return
+ * `{ action: "allow" }` to permit it.
+ *
+ * `check` may be async, which is also how **human-in-the-loop approval** works: a deployment can
+ * hold the promise open until an operator approves/denies. `signal` fires when the task aborts
+ * (timeout / max turns / cancel) — honor it to release a pending approval instead of hanging (F4).
+ * The Runner also races `check` against `signal` itself, so a policy that ignores it still cannot
+ * hang the worker past the deadline; passing it through just lets you clean up the wait early.
+ */
 export interface ToolPolicy {
     check(req: ToolCallRequest, signal?: AbortSignal): PermissionResult | Promise<PermissionResult>;
 }
+/**
+ * Refuse a decision that speaks the retired `reason` dialect (RB-479-B①, tripwire ruled 2026-08-03).
+ *
+ * Applied at every point a decision is CONSUMED, because no single fold sees them all (ruled
+ * 2026-08-03): {@link combinePolicies} (the runner's gate path), the PreToolUse hook's result seam
+ * (`hooks.ts` — a hook result reaches the gate decision without ever passing through a fold), and the
+ * durable resume-edit rechecks (`runtask.ts` — direct `check()` calls on the caller's own policy). The
+ * wording is face-neutral for that reason: one construction point, three consumers. The export exists
+ * for those two engine modules only and is deliberately NOT re-exported from `src/index.ts`: this is an
+ * internal screen on inputs the engine receives, not a facility deployments call.
+ *
+ * Why this is a DENY and not a best-effort read of the old field: the retirement is settled, so the
+ * value is out-of-contract input to the permission face — the same class as an untyped `approve`
+ * returning a truthy non-`true`, which this file already refuses fail-closed. Reading the old name
+ * anyway would re-open the two-names-for-one-thing surface; ignoring it (the pre-tripwire behavior)
+ * silently dropped the policy's own text and returned the per-site generic default, so a deployment
+ * whose deny messages had quietly degraded looked healthy. The type system cannot carry this alone —
+ * excess-property checking does not reach an inferred `check` return (see {@link PermissionResult}).
+ *
+ * OWN property only (`hasOwnProperty`, not `in`): a decision whose PROTOTYPE happens to expose
+ * `reason` never wrote the retired field. A non-object decision is passed through untouched — reading
+ * `.action` off it is the caller's existing failure, and inventing a second failure mode here would
+ * change which error a broken policy raises.
+ *
+ * Any accumulated `updatedInput` is deliberately NOT carried onto this deny: it came from the same
+ * out-of-contract decision object, so it is not a rewrite this layer is willing to report as audited.
+ * (A rewrite from an EARLIER, contract-shaped policy still rides out — {@link combinePolicies} adds it
+ * on the deny path per the observer contract.)
+ */
 export declare function refuseOutOfContractDecision(d: PermissionResult): PermissionResult;
+/** The raw tool-name lists a name-keyed policy was built from (audit feed, see block note above). */
 export interface ToolPolicyNameSets {
     readonly allow?: readonly string[];
     readonly deny?: readonly string[];
+    /** Names gated behind an approval decision ({@link createApprovalPolicy.requireApproval}) — a typo
+     *  here silently WIDENS (the tool runs without ever asking), so it is audited too. */
     readonly ask?: readonly string[];
 }
+/** A policy that exposes its name lists for the host-side pool audit. Composition-transparent:
+ *  {@link combinePolicies} (and therefore {@link tightenTaskSpec}) unions children's groups onto the
+ *  combined policy, so metadata survives the deployment's tighten/compose path. */
 export type NamedToolPolicy = ToolPolicy & {
     readonly nameSets: readonly ToolPolicyNameSets[];
 };
+/** All name-set groups reachable on `p` — `[]` when it carries none (e.g. a custom closure policy,
+ *  which simply opts out of the audit). */
 export declare function toolPolicyNameSets(p: ToolPolicy | undefined): readonly ToolPolicyNameSets[];
+/**
+ * Name-based allow/deny. `deny` always wins. If `allow` is provided, only those tools are permitted
+ * (everything else denied). Without `allow`, everything not in `deny` is permitted.
+ * Carries {@link NamedToolPolicy.nameSets} so the host can audit the raw lists against the mounted
+ * pool ([c209-E] advisory); enforcement semantics are unchanged.
+ */
 export declare function createAllowDenyPolicy(opts: {
     allow?: string[];
     deny?: string[];
+    /**
+     * What to do with an entry that is not a tool NAME but a rule CONTENT form (`Bash(ps:*)`, `Edit(src/**)`).
+     * `"throw"` (default, matching {@link createPermissionRulePolicy}'s posture toward a rule it cannot
+     * compile) refuses at construction; `"skip"` drops the entry and reports it. Under BOTH, the entry never
+     * silently narrows the allowlist.
+     */
     onInvalidName?: "throw" | "skip";
+    /** Called once per dropped entry under `"skip"`. */
     onInvalidNameIssue?: (issue: {
         entry: string;
         list: "allow" | "deny";
         message: string;
     }) => void;
 }): NamedToolPolicy;
+/**
+ * Human-in-the-loop approval for selected tools. Tools in `requireApproval` call `approve(req)` and
+ * are allowed only if it resolves true; tools in `deny` are always blocked; everything else is allowed
+ * (override with `denyByDefault: true` to allow only `requireApproval` + an explicit `autoAllow`).
+ */
 export declare function createApprovalPolicy(opts: {
+    /** Tools that need an approval decision. */
     requireApproval: string[];
+    /**
+     * The approval decision (e.g. await an operator). Resolve true to allow, false to deny. `signal`
+     * fires when the task aborts — race your wait against it (e.g. an OA approval callback) so a
+     * never-answered request is released at the deadline rather than holding the worker.
+     */
     approve: (req: ToolCallRequest, signal?: AbortSignal) => boolean | Promise<boolean>;
+    /** Always-denied tools. */
     deny?: string[];
+    /** Always-allowed tools (only meaningful with `denyByDefault`). */
     autoAllow?: string[];
+    /** When true, deny anything not in `requireApproval` or `autoAllow`. Default false. */
     denyByDefault?: boolean;
+    /**
+     * Optional self-contained deadline (ms): if `approve` hasn't resolved by then, deny. Belt-and-
+     * suspenders for **direct** callers — the Runner already races `check` against the task signal, so
+     * a Runner-driven task is bounded regardless; this protects a caller invoking `check()` without a
+     * signal. OMIT to wait indefinitely on `approve` — omission is the only spelling of "no deadline"
+     * (CLS-A-9): a written-down `0` is the tightest deadline (deny at once), and a non-finite value is
+     * refused at construction.
+     */
     approvalTimeoutMs?: number;
 }): NamedToolPolicy;
+/**
+ * Combine policies with the three-state fold **deny > ask > allow** (design/37): the WORST outcome
+ * across all policies wins. A `deny` short-circuits (nothing can override it); an `ask` does NOT
+ * short-circuit — scanning continues, because a later policy may still `deny` (which outranks ask).
+ * With no deny, the first `ask` wins; with neither, `allow`.
+ *
+ * **Idempotency requirement:** because the fold continues past an `ask` to look for a later `deny`, a
+ * policy's `check()` can be invoked even after an earlier policy returned `ask`. `check()` MUST be
+ * idempotent — repeated calls with the same {@link ToolCallRequest} return the same decision and
+ * accumulate no side effects (e.g. don't fire a duplicate approval notification on each call).
+ */
 export declare function combinePolicies(...policies: ToolPolicy[]): ToolPolicy;
+/**
+ * The shell tools whose `{ command }` arg a coarse command-name policy parses. Other tools are out of scope.
+ *
+ * RB-130 (2026-07-25, defect probe): `Monitor` belongs here. It takes a `command` and runs it through the
+ * SAME `env.spawnBackground` seam as Bash, and prepare-task's own note says so in as many words — "Monitor
+ * runs an arbitrary shell `command` through the SAME env seam — it must sit behind the SAME shellGate
+ * tighten (else it becomes a policy side-door around a gated Bash)". The shellGate half was implemented;
+ * this half — the two ALWAYS-ON, core-owned parity gates that a caller's policy cannot remove — was keyed
+ * on a list containing only "Bash". The probe drove the whole thing end to end: the identical
+ * `rm -rf $(cat targets)` was denied as Bash and executed as Monitor, deleting a real directory with no
+ * gate at all; the same substitution makes `rm -rf ~/.ai-agent/sessions` a way to erase the audit trail.
+ */
+/**
+ * RB-153 (server [1708]): EXPORTED. A downstream governance layer keeps its own copy of this list so its
+ * per-command ask-list gates the same tools core does, and it had no way to read the real one — its guard
+ * had to probe a hand-written candidate list of names, which stays green for any name nobody thought to
+ * put in it. The list itself is the fact; publishing it removes the guess.
+ */
 export declare const COARSE_SHELL_TOOLS: string[];
+/**
+ * design/center §10 — a COARSE allow/deny gate keyed on the LEADING command NAME (`argv[0]`) of a single
+ * simple shell command. It reuses the ONE shared simple-command parser
+ * ({@link import("../tools/fs/index.js").parseLeadingCommandName}) — it does NOT re-implement argv[0] parsing
+ * (a second parser would drift and open a bypass). For a `bash`/`bash_readonly` call it extracts the leading
+ * command name and:
+ *  - if the name is in `deny` → `deny` (deny-wins, matching {@link createAllowDenyPolicy}; NOT last-match-wins,
+ *    which would fight {@link combinePolicies}'s deny>ask>allow fold);
+ *  - else if `allow` is provided and the name is NOT in it → `defaultAction` (`"ask"` default, or `"deny"`);
+ *  - else → `allow`.
+ * A command the parser cannot reduce to a single bare name (it has shell operators / a path-prefix / a leading
+ * env-assignment) is treated by `defaultAction` (fail-toward-gate): such a command is exactly what would bypass
+ * an argv[0] filter, so it should not silently `allow`. NON-shell tools are out of scope → `allow` (this gate
+ * only speaks about shell command names; compose it with other policies for the rest).
+ *
+ * **core ships NO opinionated command list** — only this mechanism. The actual `allow`/`deny` rule set is
+ * injected by the profile/config/deployment.
+ *
+ * ⚠️ **NOT A SANDBOX — coarse filter / defense-in-depth only.** This matches `argv[0]` NAME and nothing else,
+ * so the bypass surface is large and the gate MUST NOT be relied on as containment:
+ *   - command substitution / subshells (`$(curl …)`, backticks), pipes, redirects, `;`/`&&` chaining — all
+ *     rejected as un-parseable here (→ `defaultAction`), so they don't sneak past `allow`, but that is a GATE
+ *     not a guarantee of safety;
+ *   - an indirection wrapper runs an arbitrary inner program under an allowlisted `argv[0]`: `sh -c '…'`,
+ *     `env FOO=bar curl …`, `sudo rm …`, `timeout 5 curl …`, `xargs curl`, `find . -exec rm {} \;`,
+ *     `python -c '…'`, `npm run <script>`, `git <subcommand>` — the inner action is INVISIBLE to an
+ *     argv[0]-name filter. Allowlisting any such wrapper effectively allowlists everything it can launch.
+ * Real isolation is the deployment's sandboxed `executionEnv` (a remote/E2B container with no egress, a
+ * read-only FS, dropped capabilities). Use this only as a cheap first-line coarse filter layered over that.
+ *
+ * 🪤 **TRAP #1 — `TaskSpec.toolPolicy` OVERRIDES (does not merge) `RunnerDeps.toolPolicy`.** A consumer that
+ * sets `TaskSpec.toolPolicy = createCoarseCommandNamePolicy(…)` directly **silently discards the deployment's
+ * baseline policy** (the runner does `spec.toolPolicy ?? deps.toolPolicy`). To LAYER this on top of a baseline
+ * you MUST compose explicitly: `combinePolicies(deploymentBaseline, createCoarseCommandNamePolicy(…))`
+ * (deny-wins — both policies' denies still fire). {@link tightenTaskSpec} does this for you.
+ *
+ * 🪤 **TRAP #2 — under `TaskSpec.shellGate: "classify"`, a plain `ask` from this policy is promoted to a
+ * NON-budgetable `irreversible_ask`.** `shellGate:"classify"` statically marks `bash` `irreversibility:"maybe"`;
+ * the safety gate keys the checkpoint axis on that STATIC tool mark (not on `decisionReason`), so a `bash`
+ * command that doesn't prove reversible suspends as `irreversible_ask` — which a budget-aware escalation
+ * resolver will NEVER auto-approve. Net: combining this policy's `ask` with `shellGate:"classify"` does NOT
+ * give you a budgetable normal-ask on `bash`; it gives a hard human-approval suspend. Choose `shellGate` and a
+ * `defaultAction:"ask"` deliberately.
+ */
 export declare function createCoarseCommandNamePolicy(opts: {
+    /** Command names (argv[0]) explicitly allowed. If provided, a name NOT listed falls to `defaultAction`. */
     allow?: string[];
+    /** Command names (argv[0]) explicitly denied — `deny` always wins (checked before `allow`). */
     deny?: string[];
+    /** What to do for a command not matched by `allow` (or un-parseable): `"ask"` (default) or `"deny"`. */
     defaultAction?: "ask" | "deny";
+    /** Override the shell tool names this gate parses (default `Bash` — bash + bash_readonly share the CC name). */
     tools?: string[];
 }): ToolPolicy;
 export declare function findUnverifiableRecursiveDelete(command: string, safeVars?: ReadonlySet<string>): string | undefined;
+/**
+ * CC 220 "Unverifiable Deletion Target" parity (auto-mode rule): ASK on a recursive+forced delete whose
+ * target is a variable / substitution that cannot be resolved from the command itself — fail-closed in the
+ * sense that with no live classifier/approver the ask degrades to deny (see {@link PermissionResult}'s
+ * `ask` doc), never to allow. See {@link findUnverifiableRecursiveDelete} for exact firing conditions. The
+ * message carries the CC-sanctioned remediation (re-run with the resolved LITERAL path written into the
+ * command, or assign the variable in the same command) — it doubles as the `askMessage` a classifier sees.
+ *
+ * RB-203 (2026-07-26): this used to be an unconditional `deny`, on the theory that the CC rule text forbids
+ * auto-allow («must be explicitly approved … cannot be auto-allowed by a permission rule»).
+ *
+ * RB-341 (2026-07-29) re-checked that citation against the 220 corpus and corrected it in BOTH directions.
+ * The RB-203 note claimed the phrase "traces to the 206 bundle; it does not appear anywhere in the 220
+ * corpus for THIS rule" — that sentence was wrong and is retracted. The phrase has 8 hits in 220, and two
+ * of them are this exact rule's own message text: `pretty220` 461365 (the `rm -rf $UNSET/*`
+ * variable-expansion arm, verbatim «e.g. `rm -rf $UNSET/*` becomes `rm -rf /*`. This requires explicit
+ * approval and cannot be auto-allowed by permission rules.») and 461444 (its command-substitution twin).
+ * Five more are the sibling deterministic `rm`/`rmdir` arms (457337/457364/457379/457387/457402) and one is
+ * an unrelated `find` rule (249564).
+ *
+ * The `ask` decision survives that correction, on a stronger anchor than the one RB-203 used:
+ *
+ *  - **It is not a deny in 220 either.** Every one of those messages is built by the same constructor
+ *    (`T7e`, 457298), whose `behavior` is literally `"ask"` — a deterministic gate that ASKS. The phrase
+ *    scopes to permission RULES: no static allow rule may clear the gate. sema's equivalent is
+ *    `combinePolicies`'s deny > ask > allow fold — an `allow` from any composed policy loses to this ask,
+ *    in either composition order (pinned in tool-policy.test.ts).
+ *  - **A live classifier MAY clear it, in 220 as here.** `T7e` marks the reason `classifierApprovable:
+ *    false`, but pairs it with `circuitBreaker: "dangerousRemoval"`, and 220's auto-mode gate diverts an
+ *    ask away from the classifier only when `!classifierApprovable && !(circuitBreaker !== undefined &&
+ *    isAutoModePermissionSurface(ctx))` (604049-604053). The circuit-breaker arm exempts exactly this
+ *    family, so on the auto-mode surface the classifier DOES adjudicate it. That is consistent with the
+ *    rule's listing in the classifier prompt's **SOFT BLOCK** bucket ("destructive or irreversible — User
+ *    Intent Rule CAN clear these", 519698 / rule text 519726), escapable when the user's own words (or an
+ *    agent proposal they affirmed) name the exact target — the same design sema's classifier prompt already
+ *    implements verbatim (`auto-mode-prompt-assets.ts`, unchanged). A `classifierApprovable:false` reason
+ *    WITHOUT a `circuitBreaker` is the shape that genuinely forbids the classifier — e.g. the design-agent
+ *    consent ASK at 480999/481016, which takes the fallback-to-human path this rule does not. This rule is
+ *    not that shape, so "follow `classifierApprovable:false` literally" would be STRICTER than CC.
+ *
+ * So a hard `deny` was wrong twice over: it short-circuited `combinePolicies`'s fold before a live
+ * classifier ever ran, and CC's classifier does run here. `ask` reuses the existing generic per-ask
+ * classifier arm (`hooks.ts`, `decision.action === "ask"`): a `block` verdict still denies
+ * (`decisionReason: "classifier"`, fully audited), an `allow` verdict still requires a live classifier to
+ * have actually cleared it, and "no classifier configured" still means deny.
+ *
+ * codex review (confirmed P1): the one piece of NEW plumbing this DOES need — `requiresRealApproval: true`
+ * (see {@link PermissionResult}'s `ask` doc) — closes a real gap the first cut of this fix missed. A
+ * deployment using the documented `onAsk: "allow"` bypass mode (sandbox-is-the-boundary posture, the
+ * shape a sandboxed autonomy container runs) would otherwise have this rule's `ask` rubber-stamped by that blanket
+ * configuration with NO classifier ever consulted and NO judgment of any kind applied — silently WEAKER
+ * than the unconditional deny it replaced, for exactly the deployments that opted into the most permissive
+ * mode for OTHER, unrelated reasons. `requiresRealApproval` makes `resolveAsk` treat a blanket
+ * `onAsk:"allow"` as equivalent to no approver at all for this specific ask (deny, same as headless) while
+ * leaving every other path untouched: a live classifier (tried first, unaffected), a real approver
+ * CALLBACK (genuine per-call judgment, even one that usually says yes), and "no classifier + no approver"
+ * (already denied). Core wires this policy ALWAYS-ON in the runner's gate composition (prepare-task); it is
+ * exported so deployments can also compose/test it directly.
+ *
+ * RB-341: `requiresRealApproval` also turns out to be the correct sema analog of the one thing
+ * `classifierApprovable: false` still buys in 220 that a `circuitBreaker` does NOT take back — 220's
+ * bypassPermissions arm refuses to auto-allow an ask carrying `circuitBreaker === "dangerousRemoval"`
+ * (603856-603869), i.e. a blanket MODE setting cannot clear it, only judgment can. That is exactly the
+ * `onAsk:"allow"` refusal above, so no new hard bit is owed. The field's remaining 220 effects have no core
+ * surface to attach to: it suppresses the "always allow / don't ask again" affordance in the CC permission
+ * dialog (908517 / 909563) and re-attaches a matching user `ask` rule on the auto-mode surface (461507).
+ * Core has neither a persisted always-allow surface nor rule re-attachment — noted for whichever UI layer
+ * grows one.
+ */
 export declare function createUnverifiableDeletePolicy(opts?: {
+    /** Extra variable names treated as well-known-safe roots, ADDED to the default set
+     *  `TMPDIR`/`HOME`/`PWD` ({@link UNVERIFIABLE_DELETE_SAFE_VARS} — RB-396-a: this doc used to claim
+     *  the default was `TMPDIR` alone, reading STRICTER than the gate really is; `HOME`/`PWD` are a
+     *  registered sema divergence from CC's temp-only carve-out, see the RB-340 note there). */
     safeVars?: readonly string[];
+    /** Override the shell tool names this gate parses (default `Bash`). */
     tools?: string[];
 }): ToolPolicy;
 export declare function createTranscriptIntegrityPolicy(opts?: {
+    /** Transcript directories to protect. Default: `($AGENT_DATA_DIR ?? ~/.ai-agent)/sessions`. */
     sessionsDirs?: readonly string[];
+    /** argv[0] allowlist for read-only access to the transcript dir (default {@link BASH_READONLY_DEFAULT_ALLOW}). */
     readAllow?: readonly string[];
+    /** Override the shell tool names this gate parses (default `Bash`). */
     tools?: string[];
 }): ToolPolicy;
+/**
+ * Provenance of the DELEGATION whose child raised an ask (ruled 2026-08-04) — filled by the delegation
+ * tool when it forwards the parent run's approver into a child, never by the child itself (it rides the
+ * trusted `ToolExecuteContext.onAsk` seat, which no tool argument reaches).
+ *
+ * The INNERMOST (issuing) frame wins: a grandchild's ask carries the grandchild's own spawn facts, not
+ * the intermediate one's — each delegation forwards an already-stamped request verbatim.
+ *
+ * Relation to the sibling source-identity fields on {@link AskRequest}: `fromSubagent`/`sourceAgentName`
+ * answer "a delegated child asked, and this is its display identity" from the CHILD's own prepare; this
+ * one answers "which delegation CALL it belongs to" from the SPAWNER's side — the correlation an approver
+ * UI needs to attach the approval card to the Agent card the operator is already looking at.
+ */
 export interface AskDelegationProvenance {
+    /** The spawning tool call in the PARENT run (`ToolExecuteContext.toolCallId` at spawn time) — the
+     *  delegation's stable identity, minted by the engine. */
     readonly parentToolCallId: string;
+    /** Delegation nesting depth of the ISSUING child: 1 = a child of the run that owns the approver,
+     *  2 = its grandchild, … (as counted by the delegation-tool tree that spawned it). */
     readonly depth: number;
+    /** The explicit spawn name / agent-definition name of the issuing child, when it has one.
+     *  **UNTRUSTED-for-display** (the spawning model chooses `name`): redact + bound before rendering,
+     *  never adjudication input — same posture as {@link AskRequest.sourceAgentName}. */
     readonly agentName?: string;
 }
+/** The structured context an `onAsk` approver receives for an `ask` decision (design/37). */
 export interface AskRequest {
     toolName: string;
     toolCallId: string;
+    /** The (post-rewrite) args the tool would run with. */
     args: unknown;
+    /** [1245] — the tool's approval display projection of {@link args} (AgentTool.approvalPreview),
+     *  clamped + control-char-sanitized by the gate. **UNTRUSTED, ADVISORY display metadata**: render
+     *  with contextual escaping and show {@link args} alongside — the preview can misrepresent the
+     *  executable action and never replaces args. Never adjudication input. */
     readonly preview?: unknown;
+    /** Canonical digest of {@link args} as presented in THIS ask, computed by the engine's one
+     *  `boundInputHashOf` — the same digest a durable park binds its checkpoint to, so an aggregating
+     *  approver can reconcile a synchronous ask row against a parked checkpoint row for the same call
+     *  by `(toolCallId, hash)` equality. RECONCILIATION metadata only, never adjudication input: it
+     *  repeats for two asks over identical args, and an `updatedInput` edit round re-mints it over the
+     *  edited args. Filled at the `resolveAsk` chokepoint (present for every wired-approver call, so a
+     *  mint site added later is covered by construction); optional on the type because a deployment may
+     *  invoke its approver function directly. */
     readonly boundInputHash?: string;
+    /**
+     * design/179 §4 — the persistable allow-rule forms this exact call could be covered by, so a surface can
+     * offer "allow, and stop asking me this" with something concrete behind it. Present only when a
+     * persisted allow-rule lane is armed AND the call is one the lane can speak for: a compound, a
+     * redirection or a substitution yields NO suggestion, which is the honest answer rather than an option
+     * that would be refused on redemption.
+     *
+     * ADVISORY display metadata, never adjudication input, and never a rule by itself: minting one is a
+     * separate act that goes through the approval-record protocol, so a surface that ignores this field
+     * changes nothing about what is allowed.
+     */
     readonly ruleSuggestions?: readonly import("./permission-rule-model.js").RuleSuggestion[];
+    /** The human/model-readable prompt explaining what needs approval. */
     message: string;
+    /** Runner-filled source identity (design S1d §1): the end-user {@link AskRequest} issuing task's
+     *  `principal` (design/62). An AGGREGATING `onAsk` (one approver fanning over N delegated workers)
+     *  attributes asks per-user by this. Worker/tool cannot set it (not a tool arg). Undefined ⇒ no principal.
+     *  A non-aggregating `onAsk` simply ignores it (additive, no-op). `readonly`: Runner-populated metadata,
+     *  not a caller/worker-settable field. Populated ONLY on the synchronous `resolveAsk`/`onAsk` path — a
+     *  durable suspend/checkpoint flow does NOT invoke `onAsk` on the suspend side, so v1 ask-aggregation
+     *  requires `checkpointStore` unset (design S1d §1.4 P-a). */
     readonly principal?: string;
+    /** Runner-filled source-task identity (= the issuing task's session id). An aggregating `onAsk` uses it
+     *  to tell which worker an ask came from (nested grandchildren each carry their own session id).
+     *  **worker-unforgeable for Runner-created delegated subagents** (a child never sets sessionId — the
+     *  Runner mints it); a top-level caller MAY continue its own session id via `TaskSpec.sessionId`, so this
+     *  is NOT a global "never forgeable" run id — aggregation only aggregates delegated workers, the context
+     *  where it holds (design S1d §1.3). `readonly` + same sync-path-only / P-a caveat as `principal`.
+     *  Undefined ⇒ no source task id. **NOT a subagent discriminator** ([1546] MED-1: the HOST's own asks
+     *  carry it too — it is always the issuing task's session id); "from a background agent" attribution
+     *  keys on {@link fromSubagent}, never on this field's presence. */
     readonly sourceTaskId?: string;
+    /** design/153 §1 (RB-39②) — Runner-filled: present (`true`) exactly when the gate raising this ask
+     *  belongs to a DELEGATED SUBAGENT (the prepareTask `isSubagent` fact — trusted `internals.parentTaskId`
+     *  presence; a child cannot forge or suppress it, internals never ride a TaskSpec). Undefined ⇒ the
+     *  host / a top-level task. THE explicit "from a background agent" discriminator (replaces presence-
+     *  or equality-heuristics on {@link sourceTaskId}). `readonly`, sync-path-only, S1d posture. */
     readonly fromSubagent?: true;
+    /** design/153 §1 — Runner-filled: the issuing task's display identity (a subagent's explicit agent
+     *  name, else its agent-type; undefined for the host and unnamed children). **UNTRUSTED-for-display**
+     *  (the spawning model chooses names): redact + bound before rendering; never adjudication input.
+     *  `readonly`, same posture as {@link fromSubagent}. */
     readonly sourceAgentName?: string;
+    /** RB-203 (codex review, confirmed P1) — carried from the originating {@link PermissionResult}'s ask
+     *  variant of the same name: `true` ⇒ {@link resolveAsk} must not let a blanket `onAsk: "allow"`
+     *  clear this ask (see that field's doc). `readonly`, filled by the gate from the decision, never a
+     *  caller/worker-settable field. */
     readonly requiresRealApproval?: boolean;
+    /** Engine-judged risk axes of the action awaiting approval, for the human decision surface: a
+     *  coarse `requiresRealApproval` cannot tell "cannot be undone" from "data leaves the machine",
+     *  and those call for different scrutiny. Filled by the gate from the SAME resolved axes the
+     *  safety tightens read (tool declarations + caller `toolAxes` folds) — never derived from tool
+     *  names, never caller/worker-settable. `irreversible: true` covers both the declared-`"always"`
+     *  and the `"maybe"` (unproven-reversible) tiers. ABSENT — the whole object or either member —
+     *  means the engine did not judge that axis: render it as unjudged, never fold absence to `false`. */
     readonly riskAxes?: {
         readonly irreversible?: boolean;
         readonly egress?: boolean;
     };
+    /** ruled 2026-08-04 — present exactly when this ask was raised inside a DELEGATED child whose approver
+     *  is the ancestor run's (the `ToolExecuteContext.onAsk` seat the delegation tool forwards). Additive:
+     *  an approver that ignores it is unaffected; a durable park/suspend flow never invokes `onAsk` at all,
+     *  so this — like `principal`/`sourceTaskId` — exists only on the synchronous resolution path.
+     *  See {@link AskDelegationProvenance} for the trust posture of each member. */
     readonly delegation?: AskDelegationProvenance;
 }
+/**
+ * How an `ask` decision is resolved when a policy/hook requests human confirmation (design/37):
+ *  - `"deny"` (and the default when omitted) — **headless auto-deny**: no approver, so `ask` resolves
+ *    deterministically to `deny` with a model-readable reason. The safe default for stateless automation.
+ *  - `"allow"` — auto-approve every `ask` (e.g. a trusted batch run).
+ *  - a function — await an operator's decision (true=allow, false=deny). `signal` fires when the task
+ *    aborts; race your wait against it so an unanswered ask is released at the deadline, not hung.
+ *    G1 three-value ([871]①): the function may also return `"unavailable"` — an affirmative "no operator
+ *    is reachable for THIS ask right now" (judged PER-ASK inside the callback, not at wire time). It is a
+ *    ROUTING verdict, not a decision: the gate re-routes the ask onto the durable park leg (same behavior
+ *    as if no live approver were wired — checkpoint + suspend, the 1.293 fallback), and when no park
+ *    facility is armed the ask falls to the headless auto-deny (fail-closed). This lets a durable
+ *    deployment wire ONE callback that serves live synchronous three-choice cards while attached AND
+ *    still lands asks in the durable approval inbox when the operator goes away.
+ *
+ * **Contract:** the function MUST be fail-closed (a throw → deny, surfacing the real cause), idempotent
+ * for a given request, and tolerant of being called after the task signal aborted. `"unavailable"` MUST
+ * only be returned when NO operator interaction happened (a partial interaction that then reported
+ * unavailable could double-resolve the same approval once the park re-surfaces it).
+ */
 export type OnAsk = "deny" | "allow" | ((req: AskRequest, signal?: AbortSignal) => AskOutcome | Promise<AskOutcome>);
+/**
+ * What an `onAsk` approver may return ([1458]/[1462] object arm):
+ *  - `boolean` — plain verdict (true=allow, false=deny). STRICT fold (RB-482 #17, server bridge
+ *    zero-ripple confirmed): only the literal `true` approves; an out-of-contract truthy from an
+ *    untyped bridge is a fail-closed deny naming the defect (the historical truthy leniency was a
+ *    fail-open on the security face with no live producer).
+ *  - `"unavailable"` — the G1 per-ask routing verdict (see {@link OnAsk}).
+ *  - `{ allow, updatedInput? }` — verdict PLUS an operator EDIT of the presented args
+ *    (whole-replacement form, e.g. ctrl+g "edit script in $EDITOR"): the human approved a MODIFIED
+ *    action, and executing the un-edited args would betray that consent. `allow` folds STRICTLY
+ *    (`allow === true`) — an object arm is a deliberate caller, so no truthy leniency — and
+ *    `updatedInput` is honored only on allow (a deny edit never executes anything). The edit is
+ *    applied as the resolved decision's own rewrite: the gate re-validates it against the tool
+ *    schema exactly like a hook/policy rewrite.
+ */
 export type AskOutcome = boolean | "unavailable" | {
     allow: boolean;
     updatedInput?: unknown;
 };
+/**
+ * ruled 2026-08-04 — forward an approver into a delegated child, stamping every ask it raises with the
+ * delegation it came from ({@link AskDelegationProvenance}).
+ *
+ * Only the FUNCTION form is wrapped: `"allow"`/`"deny"` are policy SETTINGS, not approvers, and
+ * {@link resolveAsk} reads them structurally — wrapping would invent an approver where the deployment
+ * declared a blanket mode.
+ *
+ * An ask that ALREADY carries provenance passes through untouched: chained down a delegation tree, the
+ * INNERMOST (actually issuing) frame is the one the approver must see, and each outer hop would
+ * otherwise overwrite it with its own shallower one.
+ */
 export declare function withDelegationProvenance(onAsk: OnAsk, delegation: AskDelegationProvenance): OnAsk;
+/**
+ * ruled 2026-08-04 — the APPROVER BEHIND a possibly-forwarded `onAsk`: the identity that answers
+ * "is this the same human/UI?" across delegation hops.
+ *
+ * Consumers compare approvers by function reference to decide whether one consultation's consent covers
+ * another (the RB-40 duplicate-frame collapse). A provenance wrapper is a different function object but
+ * the same decision-maker, so a bare `===` would ask one operator the same question twice for one tool
+ * call. Never used for authority (it grants nothing); only for "these two consultations are the same
+ * consultation". A non-wrapper value (including `"allow"`/`"deny"`/undefined) is its own identity.
+ */
 export declare function askApproverIdentity(onAsk: unknown): unknown;
+/** EXACT structural clone for the approval boundary (alias isolation) — fail-closed, never lossy,
+ *  never identity: a JSON round-trip would silently DROP unclonable members (presented ≠ executing =
+ *  consent misrepresentation) and an identity fallback would hand the approver the live executing
+ *  object (in-place mutation + TOCTOU). Tool args are model-JSON in practice, so failure is exotic —
+ *  and exotic means deny, not leak.
+ *
+ *  Exported for the DURABLE half of the same boundary (the runner's park mint): a checkpoint row holds
+ *  the args a human will approve and a resume will execute, so it needs exactly this snapshot — and
+ *  exactly this refusal when the value cannot be one. Not part of the package's public surface
+ *  (index.ts does not re-export it); one implementation so the two halves cannot drift on what
+ *  "safely presentable" means. */
 export declare function tryCloneArgs<T>(v: T): {
     ok: true;
     value: T;
@@ -121,9 +631,54 @@ export declare function tryCloneArgs<T>(v: T): {
     reason: string;
     cause?: unknown;
 };
+/**
+ * A label for a value that was THROWN at us, safe to put in a fail-closed refusal. Never coerces: `String(x)`
+ * throws on a null-prototype object or a hostile `toString`/`Symbol.toPrimitive`, and the thrower here is
+ * deployment-supplied (a getter inside the args can throw any object at `structuredClone`, an approver can
+ * throw one at the gate). A coercion failure inside the catch would escape `resolveAsk` as a raw TypeError —
+ * turning a classified fail-closed DENY into an unclassified crash, i.e. the failing input escaping the very
+ * classification the refusal exists to give.
+ *
+ * The result is CONTAINED, not just described. Every caller interpolates it into a refusal that reaches
+ * the model inside a `<system-reminder>` frame, and the text is not ours: a `DataCloneError` renders the
+ * offending value INTO its message (`structuredClone` of a function yields that function's SOURCE), and
+ * a deployment approver throws whatever it likes. A rewrite handing over a function whose body contains
+ * `</system-reminder>` would otherwise close the trusted frame and continue as instructions — the exact
+ * threat `inlineUntrusted` exists for. So the description is one line, neutralized and capped here, at
+ * the single point where a thrown value becomes prose; the RAW exception is unaffected and still reaches
+ * the deployment's own error face, which is where an operator reads the untruncated story.
+ *
+ * Exported for the durable half of the same boundary (the runner's park mint), which now has a SECOND
+ * way a deployment-supplied value can throw at capture time — the target backend's own codec refusing to
+ * encode it. One containment point, so the two refusals cannot differ on how much of a hostile value's
+ * text they let through. Not part of the package's public surface.
+ */
 export declare function describeThrown(err: unknown): string;
+/**
+ * A {@link resolveAsk} result: always a TERMINAL `allow`/`deny` (never `ask`). `approverUnavailable`
+ * is the out-of-band G1 three-value marker: the live approver returned `"unavailable"` for this ask —
+ * the carried `deny` is the FAIL-CLOSED FALLBACK, and the gate may instead re-route the ask onto the
+ * durable park leg (the only consumer; everywhere else the result reads as a plain deny).
+ */
 export type ResolvedAsk = PermissionResult & {
     approverUnavailable?: true;
+    /** [1462] r5 — the EXACT data snapshot the approver was shown (the `structuredClone` of the
+     *  presented args). On a plain approval (no edit) the gate EXECUTES this snapshot, not the original
+     *  object: a stateful getter or an external alias must not be able to make the executed action
+     *  differ from the approved one (shown == executed, by construction). Set only on the
+     *  function-approver path (string modes present nothing). */
     presentedInput?: unknown;
 };
+/**
+ * Resolve an `ask` decision to a terminal `allow`/`deny` via {@link OnAsk}. Centralizes the headless
+ * auto-deny default, fail-closed error handling, and stable deny reasons so every ask site is
+ * consistent. Never returns `ask`.
+ *
+ * Every arm that ENDED A WAIT names what ended it ({@link ApprovalSettledBy}, per-arm, at the arm):
+ * the approver's own verdicts are `"human"`, and the fail-closed ends around them (abort, a throw, an
+ * "unavailable" report, an unclonable presentation, an out-of-contract value) are `"aborted"`. The
+ * three POSTURE arms at the top — blanket `"allow"`, its `requiresRealApproval` refusal, and the
+ * headless auto-deny — carry NO source on purpose: nobody was asked, so there is no wait for anyone to
+ * have ended, and `decisionReason: "mode"` is already the honest word for what produced them.
+ */
 export declare function resolveAsk(req: AskRequest, onAsk: OnAsk | undefined, signal?: AbortSignal): Promise<ResolvedAsk>;