@sema-agent/core 7.47.0 → 7.49.0

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

@@ -19,6 +19,11 @@ export interface ToolCallFace {
     contractId: string;
     shapeDigest: string;
     implementationRevision: string;
+    /** Which approval card this call renders under (the closed set `TOOL_APPROVAL_CARDS`; `generic` when the tool
+     *  declares none). Minted with the face — a reserved card only for the engine tool that owns it — and copied onto the
+     *  ask, the parked gate and the pending row, so no reader recovers the card from a name. Absent on a face rebuilt
+     *  from a park row (a re-judgment reads no card). */
+    approvalCard?: import("./tool-face.js").ToolApprovalCard;
 }
 export interface ToolCallRequest {
     /** The tool's wire name — the Runner's gate resolves a call made under an alias to the wire name of the tool it
@@ -114,6 +119,17 @@ export interface ToolCallRequest {
      * directory by writing one back.
      */
     advertisedWritableRoots?: readonly string[];
+    /**
+     * The engine data root's spellings — the ONE exempt root every exemptible path row is judged under (the data-root
+     * exemption, path-guard-rows.ts): resolved once per leg from `RunnerDeps.memoryEngineDir` (absent ⇒ the resolver's own
+     * chain, `$AGENT_DATA_DIR ?? ~/.ai-agent`) and stamped by the Runner on every policy adjudication of the leg. A path guard
+     * that judges a write under the exemption reads it here, so the guard and the engine's own write judgment speak about
+     * the same directory instead of a second copy the deployment keeps by hand.
+     *
+     * ABSENT outside a Runner (a policy driven directly by a host): the guard then reads the resolver's own chain, the root
+     * a Runner with no `memoryEngineDir` would stamp. Read-only, frozen.
+     */
+    exemptRoots?: readonly 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
@@ -177,68 +193,87 @@ export declare function advertisedWritableRootsSeat(seat: {
 } | undefined): {
     advertisedWritableRoots?: readonly string[];
 };
+/** Stamp {@link ToolCallRequest.exemptRoots} from the leg's one resolution of the data root — the ONE place that value
+ *  becomes a request field, beside {@link advertisedWritableRootsSeat} at every adjudication station. */
+export declare function exemptRootsSeat(exemptRoots: readonly string[]): {
+    exemptRoots: readonly string[];
+};
 /** Declared beside the receipt's list (decision-receipt.ts) — a new member added to either side is a compile error rather
  *  than a silent drift between the type and the screen; re-exported here, the module every consumer of the decision reads. */
 export type { DecisionReason };
-/** The `task_aborted`-attested deny an engine policy answers on an aborted signal instead of reaching a seat. */
-export declare function abortedSeatDeny(req: {
-    toolCallId: string;
-    toolName: string;
-}, message: string, origin: AskOrigin): PermissionResult;
-/** Carry every engine attestation from a decision onto a reconstruction of it — the
- *  seam for the engine's OWN clone sites outside this module (the inherited chain's final-form re-check carries the
- *  post-rewrite args on a spread of an ancestor's deny). Returns the reconstruction. Not re-exported from `src/index.ts`. */
-export declare function carryEngineAttestations<T extends object>(from: object, to: T): T;
-/** Carry a PRECEDING decision's settlement onto a later deny that has none of its own — the veto record (a person's
- *  yes on the settlement, the refusing layer on the disposition; invariant I3) for the engine's own clone sites,
- *  where the deny is minted over a decision that already carried an attested approval. A deny that carries its own
- *  settlement keeps it (the latest resolution wins). Not re-exported from `src/index.ts`. */
-export declare function carryPrecedingSettlement(preceding: object, to: object): void;
-/** Attest that `d` is a deny a classifier station minted for `call` out of a round of the named FORM. */
-export declare function attestClassifierDenyCause<T extends object>(d: T, cause: import("./gate-outcome.js").ClassifierDenyCause, call: {
-    toolCallId: string;
-    toolName: string;
-}): T;
-/** Read the attested classifier cause off a deny FOR the named call (the gate's fold and exit are the
- *  consumers): a binding to a different call is a replayed object and answers absence. An internal seam
- *  between engine modules — deliberately NOT re-exported from `src/index.ts`. */
-export declare function classifierDenyCauseOf(d: unknown, call: {
-    toolCallId: string;
-    toolName: string;
-}): import("./gate-outcome.js").ClassifierDenyCause | undefined;
-/** Attest that `d` is a decision a classifier station minted for `call` out of the named classification. */
-export declare function attestClassifierRound<T extends object>(d: T, round: import("./auto-mode.js").AutoModeClassifierRound, call: {
+/**
+ * The engine's ATTESTATION record — the one carrier of what an engine station knows about a decision and a policy cannot
+ * state: WHO settled the call's wait and WHICH question that answered (the settlement, the ask's origin word and class set,
+ * the digest of the arguments the answer licenses), and the facts the classifier stations, the in-fold unresolvable arms
+ * and the policy fold record. It rides the decision as its `attestation` member and is read through {@link attestationOf}
+ * alone; the decision object's identity carries nothing.
+ *
+ * Minted only by {@link mintAttestation} and combined only by {@link mergeAttestation}: both freeze the record and enter it
+ * in a module-private brand set, so a value a caller composed — a literal, a copy, a structured clone — is not a record, and
+ * the receipt refuses a decision carrying one. A record is bound to the call it was minted for (`toolCallId` + `toolName`):
+ * handed back for another call it reads as absent. A spread of a decision keeps its record, and the record still says only
+ * what the engine minted — a refusal record on an allow is a contradiction the gate's exit refuses, and a resolution's
+ * answer binds the arguments it licensed (`inputDigest`).
+ */
+export interface EngineAttestation {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    /** What ended the call's wait. The answer group — `settlement`, `origin`, `classes`, `inputDigest` — travels as one. */
+    readonly settlement?: Settlement;
+    /** The settled ask's origin word. */
+    readonly origin?: AskOrigin;
+    /** The settled ask's class set (`ASK_CLASSES` order), when the minting station held one. */
+    readonly classes?: readonly import("./ask-origin.js").AskClass[];
+    /** `boundInputHashOf` of the arguments the settlement licenses: an approver's edit, the snapshot shown, or the asked args. */
+    readonly inputDigest?: string;
+    /** The FORM of a classifier round that did not rule (a classifier deny's cause). */
+    readonly classifierCause?: import("./gate-outcome.js").ClassifierDenyCause;
+    /** WHICH model answered a classification, on either arm. */
+    readonly classifierRound?: import("./auto-mode.js").AutoModeClassifierRound;
+    /** Why an in-fold deny refused an ask nobody could resolve. */
+    readonly unresolvableCause?: import("./ask-unresolvable-notice.js").AskUnresolvableCause;
+    /** The classes of the asks a policy fold collapsed — the proof behind a decision's `foldedAskClasses`. */
+    readonly foldedClasses?: readonly import("./ask-origin.js").AskClass[];
+}
+/** The members a station attests — everything but the call binding. */
+export type AttestationMembers = Omit<EngineAttestation, "toolCallId" | "toolName">;
+/** Mint a record for `call`. Engine stations only: not re-exported from `src/index.ts`. The values are DETACHED snapshots, so a
+ *  caller that later mutates the settlement object it was handed cannot rewrite what the engine attests. */
+export declare function mintAttestation(call: {
     toolCallId: string;
     toolName: string;
-}): T;
-/** Read the attested classification off a decision FOR the named call (the gate's fold is the consumer): a
- *  binding to a different call is a replayed object and answers absence. Internal seam — not re-exported. */
-export declare function classifierRoundOf(d: unknown, call: {
+}, members: AttestationMembers): EngineAttestation;
+/** Is `v` a record the engine minted (the brand alone — no binding)? The receipt's test. */
+export declare function isEngineAttestation(v: unknown): v is EngineAttestation;
+/** THE read: the record `d` carries FOR `call` — a branded record bound to that call, else `undefined` (a record bound to
+ *  another call is a replayed one and reads as absent). Read off the own data member, never through an accessor. */
+export declare function attestationOf(d: unknown, call: {
     toolCallId: string;
     toolName: string;
-}): import("./auto-mode.js").AutoModeClassifierRound | undefined;
-/** Attest that `d` is an in-fold deny of an ask nobody could resolve, for `call`, for the named cause. */
-export declare function attestAskUnresolvableCause<T extends object>(d: T, cause: import("./ask-unresolvable-notice.js").AskUnresolvableCause, call: {
+}): EngineAttestation | undefined;
+/**
+ * Combine two records for `call`, member GROUP by group: the later record's group stands where it has one, the earlier's
+ * fills a group the later lacks. A record not bound to `call` contributes nothing. `answer` scope is the veto's merge: the
+ * earlier record contributes ONLY its answer, and only when the later carries none — a person's yes rides a later layer's
+ * deny (invariant I3) while the refusing station's own facts stay its own.
+ */
+export declare function mergeAttestation(call: {
     toolCallId: string;
     toolName: string;
-}): T;
-/** Read the attested unresolvable cause off a deny FOR the named call (the gate's exit is the consumer); a
- *  binding to a different call is a replayed object and answers absence. Internal seam — not re-exported. */
-export declare function askUnresolvableCauseOf(d: unknown, call: {
+}, earlier: EngineAttestation | undefined, later: EngineAttestation | undefined, scope?: "all" | "answer"): EngineAttestation | undefined;
+/** `d` with `members` attested for `call`, merged over the record it already carries for that call (the new members' groups
+ *  win). Always a fresh object — the receipt hands out frozen ones. */
+export declare function attest<T extends object>(d: T, call: {
     toolCallId: string;
     toolName: string;
-}): import("./ask-unresolvable-notice.js").AskUnresolvableCause | undefined;
-/** Read the engine-attested settlement off a funneled decision FOR the named call (the gate's exit is the
- *  one consumer): an attestation bound to a different call is a replayed object and answers absence.
- *  Exported for the gate module only — deliberately NOT re-exported from `src/index.ts` (an internal seam
- *  between engine modules, not a facility deployments call). */
-export declare function engineSettlementOf(d: unknown, call: {
+}, members: AttestationMembers): T;
+/** `d` carrying `record` (a fresh object), or `d` itself when there is no record to put on it. */
+export declare function withAttestation<T extends object>(d: T, record: EngineAttestation | undefined): T;
+/** The `task_aborted`-attested deny an engine policy answers on an aborted signal instead of reaching a seat. */
+export declare function abortedSeatDeny(req: {
     toolCallId: string;
     toolName: string;
-}): {
-    settlement: Settlement;
-    origin: AskOrigin;
-} | undefined;
+}, message: string, origin: AskOrigin): PermissionResult;
 /**
  * design/252 G-7 — how long an approver-attribution identifier may be.
  *
@@ -288,9 +323,9 @@ export declare function screenApproverAttribution(v: unknown): {
  *  - `deny` blocks the call.
  * Human-readable text is `message`; read it via {@link decisionText}.
  *
- * NO arm carries a settlement: what ended a wait is not a policy's to state. The engine's own settlement
- * sites attest it through a module-private seat ({@link engineSettlementOf}) and the gate's exit mints the
- * one settlement record ({@link import("./gate-outcome.js").GateOutcome}); a policy that puts a `settledBy`
+ * What ended a wait is not a policy's to state: it rides only the `attestation` member, an engine-minted
+ * record ({@link EngineAttestation}) the receipt refuses in any other form, and the gate's exit mints the one
+ * settlement record ({@link import("./gate-outcome.js").GateOutcome}) from it; a policy that puts a `settledBy`
  * or `approver` member on its verdict is putting an unread property on it.
  * RB-479-B① (ruled 2026-08-02): the legacy `reason` field is REMOVED — one name for one thing.
  *
@@ -303,6 +338,7 @@ export type PermissionResult = {
     updatedInput?: unknown;
     message?: string;
     decisionReason?: DecisionReason;
+    attestation?: EngineAttestation;
 } | {
     action: "ask";
     updatedInput?: unknown;
@@ -418,12 +454,12 @@ export type PermissionResult = {
     /** The ask's whole class set, in {@link import("./ask-origin.js").ASK_CLASSES} order (see
      *  {@link AskRequest.classes}). Stamped beside {@link askClass}, under the same rule. */
     classes?: readonly import("./ask-origin.js").AskClass[];
-    /** WHICH integrity guard minted this ask — a removal of a protected location, an unverifiable recursive delete
-     *  or the session-transcript write. ENGINE-STAMPED by the guard policies; a fold-internal fact the class
+    /** WHICH integrity guard minted this ask — a removal of a protected location, an unverifiable recursive delete,
+     *  shell text the engine cannot read or the session-transcript write. ENGINE-STAMPED by the guard policies; a fold-internal fact the class
      *  derivation reads ({@link import("./ask-origin.js").classifyAsk}) so the guards, which mint the same
      *  `requiresRealApproval` ask, are told apart by a fact and not by their prose. Never copied onto the
      *  approval request or the park row. */
-    guard?: "dangerous_delete" | "unverifiable_delete" | "transcript_write" | "artifact_shared_read";
+    guard?: "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "artifact_shared_read";
     /** The call could not be READ against a rule that may reach it — a content-form deny row, a content-form
      *  ask row, or a persisted-rule row (the lexer's word). ENGINE-STAMPED at the three unreadable mint sites;
      *  the class derivation reads it as `rule_unreadable` (a mode may release it, a person may clear it, no
@@ -439,14 +475,17 @@ export type PermissionResult = {
     /** The classes of the OTHER asks a policy fold collapsed into this one
      *  ({@link import("./ask-origin.js").decisionAskClassesOf} per contributing ask, unioned), so a member the
      *  fold does not copy — a guard mark, an unreadable-rule fact, a bare real-approval bit — is not lost behind
-     *  the ask that won the slot. ENGINE-WRITTEN by {@link combinePolicies}, which attests the object it returns; the receipt
-     *  refuses the member on any other object (a policy's own, a copy, an edited list). Fold-internal, never on the request. */
+     *  the ask that won the slot. ENGINE-WRITTEN by {@link combinePolicies}, which attests the list it wrote
+     *  ({@link EngineAttestation.foldedClasses}); the receipt refuses the member unless the decision's record carries that very
+     *  list (a policy's own, an edited list are refused). Fold-internal, never on the request. */
     foldedAskClasses?: readonly import("./ask-origin.js").AskClass[];
+    attestation?: EngineAttestation;
 } | {
     action: "deny";
     updatedInput?: unknown;
     message?: string;
     decisionReason?: DecisionReason;
+    attestation?: EngineAttestation;
 };
 /**
  * design/252 G-2 — WHY a piece of rule-provenance evidence is not on an ask.
@@ -556,12 +595,18 @@ export interface ToolPolicy {
      *  through {@link combinePolicies}; read with {@link toolPolicyPathRules}. Its presence also tells the Runner to read
      *  each call's target ({@link ToolCallRequest.targetReading}). */
     readonly pathRules?: (anchors: import("./permission-rule-model.js").PathRuleBases) => readonly import("./path-rule-binding.js").BoundPathRule[];
-    /** Does this policy guard a write to this ABSOLUTE target — would it refuse the write if a write tool made it? The
-     *  policy's answer for a writer it cannot see as a call (the shell's file commands), read by the shell station's
-     *  `writesPlaced` fact alone: a guarded target is not placed, so no permission mode answers the command and its ask
-     *  reaches a person — it is not refused. A PURE judgment: no side effect, no audit record, no hook, no approver; `true`
-     *  on a target it cannot judge. Carried through {@link combinePolicies} (any member's `true` is the answer). */
-    readonly writeTargetGuard?: (target: string, signal?: AbortSignal) => Promise<boolean>;
+    /** The guarded WRITE rows this policy refuses — rows of the one path table (path-guard-rows.ts), stated as data. The
+     *  engine judges them for a writer the policy cannot see as a call (the shell's file commands) by its ONE write judgment:
+     *  the leg's views of the target (spelling, real target, symlink chain) under the leg's one exempt root
+     *  ({@link ToolCallRequest.exemptRoots}) beside the always-on write-protection table. A target one of them covers is not
+     *  placed, so no permission mode answers the command and its ask reaches a person — it is not refused. The rows of ONE
+     *  judgment: a row placed below a declared root is placed where that root resolves in `env` (resolved per call). A PURE
+     *  statement: no side effect, no verdict; a call that throws leaves the target unplaced. Carried through
+     *  {@link combinePolicies} (the members' rows, in order); read with {@link toolPolicyWriteGuardRows}. */
+    readonly writeGuardRows?: (at: {
+        readonly env?: import("../internal/harness-types.js").ExecutionEnv;
+        readonly signal?: AbortSignal;
+    }) => Promise<readonly import("./path-guard-rows.js").PathGuardRow[]>;
     /** The raw tool-name lists a name-keyed policy was built from — the prepare-time policy-name audit's feed (a retired
      *  name refuses the run, an unmounted one is advised). Carried through {@link combinePolicies} (the union of the
      *  members' groups); read with {@link toolPolicyNameSets}. */
@@ -572,10 +617,11 @@ export interface ToolPolicy {
  * each by name off the wrapped policy, {@link combinePolicies} folds each. The fence makes a new {@link ToolPolicy} member
  * a compile error until the table names it.
  */
-declare const TOOL_POLICY_CARRIED_MEMBERS: readonly ["projection", "pathRules", "writeTargetGuard", "nameSets"];
+declare const TOOL_POLICY_CARRIED_MEMBERS: readonly ["projection", "pathRules", "writeGuardRows", "nameSets"];
 type ToolPolicyCarriedMember = (typeof TOOL_POLICY_CARRIED_MEMBERS)[number];
 export type ToolPolicyCarriesEveryMember = AssertAllKeysHandled<Exclude<Exclude<keyof ToolPolicy, "check">, ToolPolicyCarriedMember>>;
-/** The carried members that are set on `p`, each read by name — an accessor or a non-enumerable member included. */
+/** The carried members that are set on `p`, each read by name — an accessor or a non-enumerable member included. A
+ *  retired member `p` still holds would not be carried: it is refused by name instead (`config.deps_retired_key`). */
 export declare function carriedMembersOf(p: {
     readonly [K in ToolPolicyCarriedMember]?: ToolPolicy[K];
 }): {
@@ -583,7 +629,7 @@ export declare function carriedMembersOf(p: {
 };
 /**
  * The ONE way to wrap a policy: the wrapper decides through `check`; every member {@link ToolPolicy} declares beside it
- * (projection, name sets, path deny rows, write-target guard — the carried-member table) rides as `inner` holds it, read
+ * (projection, name sets, path deny rows, guarded write rows — the carried-member table) rides as `inner` holds it, read
  * by name, so a class instance's accessor or a non-enumerable member rides too — a `{ check }` literal drops them, and
  * engine stations the wrapper never sees read each one. The carried members describe what `inner` refuses, so the wrapper
  * must refuse at least that (an observer, a tightener); one that releases what `inner` refuses is a policy of its own.
@@ -594,9 +640,10 @@ export declare function wrapToolPolicy<P extends ToolPolicy>(inner: P, check: To
  *  the leg the policies are installed on (a policy already installed answers with its own installation's rows). The deny
  *  tables take the rows that guard a face (`faces` non-empty) of a deny rule. */
 export declare function toolPolicyPathRules(policies: readonly (ToolPolicy | undefined)[], anchors: import("./permission-rule-model.js").PathRuleBases): readonly import("./path-rule-binding.js").BoundPathRule[];
-/** The one write-target guard the given policies carry together (combined policies included): `true` when any member
- *  guards the target, a member that throws counting as guarding it. `undefined` when none carries one. */
-export declare function toolPolicyWriteTargetGuard(policies: readonly (ToolPolicy | undefined)[]): ToolPolicy["writeTargetGuard"];
+/** The guarded write rows the given policies carry together (combined policies included): every member's rows of one
+ *  judgment, in member order (a member that throws throws here — the judgment leaves the target unplaced). `undefined`
+ *  when none carries any. */
+export declare function toolPolicyWriteGuardRows(policies: readonly (ToolPolicy | undefined)[]): ToolPolicy["writeGuardRows"];
 /**
  * One deterministic DENY component of a {@link ToolPolicyProjection} (F-012 L1). All fields are plain
  * serializable data — a component round-trips JSON/`structuredClone` unchanged, which is what lets a
@@ -813,7 +860,7 @@ export declare const DECISION_MEMBERS: readonly DecisionMember[];
  * allow; a `canUseTool` result outside its set is a failure in CC) and `decisionReason` in {@link DECISION_REASONS} when
  * present (absence stays legal); (5) the DETACH —
  * the contract members' values structured-cloned ({@link tryCloneArgs}; one that cannot be, a function inside a rewrite,
- * is refused), the engine's identity-keyed records carried across ({@link carryEngineAttestations}), the copy frozen and
+ * is refused), the engine's `attestation` record re-attached by reference after its brand check, the copy frozen and
  * marked as this module's. A refusal is a deny in the screen's words, one code for every arm (`decisionReason: "rule"`),
  * carrying no `updatedInput` from the refused object (a rewrite from an EARLIER, contract-shaped layer still rides out of
  * {@link combinePolicies}' deny path). `null` / `undefined` carry nothing and take the carrier's refusal (the caller's own
@@ -1037,12 +1084,12 @@ export declare function createCoarseCommandNamePolicy(opts: {
     /** Override the shell tool names this gate parses (default {@link COARSE_SHELL_TOOLS}, the shell face). */
     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
+ * `ask` doc), never to allow. The guard reads ONE plan, the read station's (`removalReadingOf`,
+ * removal-targets.ts): its firing conditions are `removalFindingsOf`'s there. 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.
  *
@@ -1108,10 +1155,10 @@ export declare function findUnverifiableRecursiveDelete(command: string, safeVar
  * 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). */
+    /** Extra variable names treated as well-known-safe roots, ADDED to the default set `TMPDIR`/`HOME`
+     *  (`KNOWN_SAFE_ROOTS`, removal-targets.ts — `HOME` is a registered sema divergence from CC's temp-only carve-out).
+     *  Each must be a shell identifier; `PWD` / `OLDPWD` are refused — their value is where the command stands, read off
+     *  the working-directory thread, not a root the shell provides. A bad entry throws here. */
     safeVars?: readonly string[];
     /** Override the shell tool names this gate parses (default {@link COARSE_SHELL_TOOLS}, the shell face). */
     tools?: string[];
@@ -1476,6 +1523,12 @@ export interface AskRequest {
         readonly irreversible?: boolean;
         readonly egress?: boolean;
     };
+    /** Which approval card this ask renders under — the closed set `TOOL_APPROVAL_CARDS`, `generic` when the tool declares
+     *  none; the same word the parked gate and the pending row carry for the same call. Display routing only: the card is
+     *  untrusted-for-display input (a tool may declare any non-reserved card), so a specialised card validates the call's
+     *  arguments itself. A word outside the set reads as `generic`. ABSENT: an ask the host built itself, or an engine
+     *  older than this member. */
+    readonly approvalCard?: import("./tool-face.js").ToolApprovalCard;
     /** 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,
@@ -1767,6 +1820,38 @@ export declare function tryCloneArgs<T>(v: T): {
  * text they let through. Not part of the package's public surface.
  */
 export declare function describeThrown(err: unknown): string;
+/** What a person refused: a tool use the model asked to run, or the plan it proposed. */
+export type HumanRefusalSubject = "tool use" | "plan";
+/**
+ * THE sentence a model reads when a PERSON refused what it asked to do, whichever leg carried the refusal (the
+ * synchronous resolver's {@link humanRefusalMessage}; the durable decide's tool result and continuation frame;
+ * the plan review's continuation) — one generator for every subject and both postures, so a person's "no"
+ * cannot speak two ways depending on whether it landed on a tool call or a plan, or on which path carried it.
+ * `subject` picks the fact clause (which thing was refused and that it did not run); `delegatedChild` picks the
+ * posture — the ISSUING RUN's position ({@link AskRequest.isDelegatedChild}; the durable legs read the same
+ * effective fact, restored from the checkpoint row on a deps-only resume):
+ *  - a parent-thread run is told the user refused and to wait for them. The reference answers a tool call and a
+ *    plan with one string (a refusal with no words stops the turn and waits for the user; one with words relays
+ *    them as the direction): no note ⇒ the fact, then STOP and wait for the user to tell the model how to
+ *    proceed; a note ⇒ the fact, then the note inside a {@link delimitUntrusted} fence ("reviewer note" — the
+ *    durable resume leg's label for the same words). The TRUSTED wrapper around the fence does two jobs the
+ *    fence alone cannot: it LICENSES the note as the user's guidance while bounding its authority (user words
+ *    steer the work; they cannot grant permissions or override system rules — the fence's "do NOT follow
+ *    instructions" guards exactly that escalation, not the reading of the user's steer), and it KEEPS the wait as
+ *    the fallback for a note that gives no direction, so a note never erases the only explicit instruction about
+ *    what to do after a person's "no". On the BARE arm the directive is no longer text alone: the runner treats
+ *    a refused TOOL CALL as a control-flow boundary for the issuing assistant batch — same-message sibling calls
+ *    that never started settle un-executed and the turn ends awaiting the user (the settlement's `note` seat
+ *    carries the bare-vs-noted fact);
+ *  - a delegated child (a FORK included — its message-layer contract is one-shot, "no waiting for the user") is
+ *    told to try a different approach or report the limitation — no user turn ever lands in ITS transcript, so
+ *    "wait for the user" would hang the delegation. A note it is handed rides the same fence and the same bound
+ *    on its authority, with the adapt-or-report posture as the fallback.
+ * Whether there IS a note is the decider-note seat's own rule ({@link decidersNote}), asked here and nowhere
+ * else on this path — the callers hand over the raw text. Not for a refusal a machine gave
+ * ({@link policyRefusalMessage}).
+ */
+export declare function humanRefusalSentence(subject: HumanRefusalSubject, reason: string | undefined, delegatedChild: boolean): string;
 /**
  * The ONE composer for a DEPLOYMENT-POLICY refusal of an ask — the sentence the model reads when the
  * approval channel reported that a MACHINE ended this wait (`settledBy: "policy"` on the synchronous
@@ -1792,10 +1877,6 @@ export declare function policyRefusalMessage(toolName: string, askMessage: strin
 export type ResolvedAsk = (Extract<PermissionResult, {
     action: "allow";
 }> & {
-    /** Present exactly when a DECIDER approved (`human_allowed` / `policy_allowed`, with the channel's
-     *  attribution when it reported one); absent on the posture allows (a blanket `"allow"`) — nobody was
-     *  asked, so nothing was settled. */
-    settlement?: Settlement;
     /** 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
@@ -1808,14 +1889,40 @@ export type ResolvedAsk = (Extract<PermissionResult, {
 }) | (Extract<PermissionResult, {
     action: "deny";
 }> & {
-    /** What ended the wait — composed at the arm that ended it, one of the refusal kinds. A deny this
-     *  resolver composes ALWAYS names its settlement: there is no unclassified refusal. */
-    settlement: Settlement;
     presentedInput?: unknown;
     approverUnavailable?: true;
     /** A grant riding a refusal: always `rejected` (`on_refusal`). */
     readRootGrant?: ReadRootGrantScreen;
 });
+/** What one resolver ARM composes: the resolution plus the settlement it ended the wait with — composed at the arm, every deny
+ *  naming one (there is no unclassified refusal), an allow only when a DECIDER approved (a blanket `"allow"` asked nobody). The
+ *  exported {@link resolveAsk} turns the settlement into the resolution's `attestation`. Not re-exported from `src/index.ts`. */
+export type ResolverArmResult = (Extract<ResolvedAsk, {
+    action: "allow";
+}> & {
+    settlement?: Settlement;
+}) | (Extract<ResolvedAsk, {
+    action: "deny";
+}> & {
+    settlement: Settlement;
+});
+/**
+ * The DIRECTIONAL format controls, as a closed set (see {@link AskRequest.hasBidiControls}):
+ * ALM (U+061C), LRM/RLM (U+200E/U+200F), the embeddings and overrides (U+202A–U+202E) and the
+ * isolates (U+2066–U+2069). These reorder what a reader SEES without changing a byte of what runs.
+ *
+ * Why the whole directional family and not only the four the reordering demos use: the bit is a
+ * WARNING, and for a warning the safe direction is to fire on a member a reader would have to
+ * enumerate correctly to be safe from. ALM is in for that reason, though it is the least-abused one.
+ *
+ * Deliberately NARROWER than `permission-rule-model`'s `CONTROL_CHARS_RE` and than
+ * {@link APPROVER_REFUSED_CHARS_RE}: those are REFUSAL/ESCAPE classes covering every control and
+ * zero-width character (a rule text or an identifier has no use for any of them). This one answers a
+ * different question — "can this display as something other than what it is" — and a zero-width joiner
+ * or a soft hyphen does not reorder anything, so folding them in would make the bit fire on ordinary
+ * text and mean nothing where it matters.
+ */
+export declare const BIDI_CONTROL_CHARS = "\\u061C\\u200E\\u200F\\u202A-\\u202E\\u2066-\\u2069";
 /**
  * Does any string reachable in `value` carry a {@link BIDI_CONTROL_RE} member? Bounded, cycle-safe,
  * and never throwing — every caller is on an approval/projection path, where a scan that failed must
@@ -1834,8 +1941,11 @@ export type ResolvedAsk = (Extract<PermissionResult, {
  * row's work is bounded regardless of the row's provenance. Both members are required when the
  * object is given — a half-specified tier would silently mix two tiers in one scan.
  *
- * Not a public export: the contract is the {@link AskRequest.hasBidiControls} bit, and a second
- * spelling of "does this carry bidi" on the public surface would be one more thing to keep in step.
+ * Exported as the ONE judge of the question: a host that renders or sanitizes text next to an approval
+ * card answers "does this carry a directional control" with this function, and composes a wider class
+ * (control characters, line separators) from {@link BIDI_CONTROL_CHARS} rather than restating the members.
+ * The allowances above are part of the answer, not an implementation detail: a payload past them reads
+ * "not detected", exactly as the bit on the card does.
  */
 export declare function carriesBidiControls(value: unknown, limits?: {
     maxNodes: number;