@sema-agent/core 7.18.0 → 7.20.0

package/dist/core/skill-listing-budget.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The skills-listing BUDGET SEAT as vocabulary: the two knobs a deployment may declare
+ * (`TaskSpec.skillListingBudgetFraction` / `TaskSpec.skillListingMaxDescChars`), the ONE reader that
+ * lowers them to the numbers the renderer measures against, and the disclosure announced when the
+ * budget costs a skill its description. The reader is pure; the announcer's only effect is the notice.
+ * `runner/synthetic-tools.ts` owns the renderer that consumes the numbers.
+ *
+ * The listing frame is an INTACT-class turn attachment (`runner/turn-attachments.ts`
+ * `ATTACHMENT_DELIVERY_CLASS`): the delivery lane never clips it, so the number this reader produces is
+ * the number the frame is rendered to — there is no lane ceiling above it.
+ *
+ * Sibling of `tool-search-setting.ts` in shape and in posture: a value outside its domain REFUSES
+ * loudly rather than folding back to the default, because a knob that is silently dropped reads to the
+ * deployment as a knob that took effect.
+ */
+import { type EngineNotice } from "./engine-notice.js";
+/** Fraction of the model's context window the listing may spend when the deployment declares nothing. */
+export declare const SKILL_LISTING_BUDGET_FRACTION_DEFAULT = 0.01;
+/** Per-skill description cap (code units, ellipsis included) when the deployment declares nothing. */
+export declare const SKILL_LISTING_DESC_MAX_CHARS_DEFAULT = 1536;
+/** Context window assumed for a model that declares none. */
+export declare const SKILL_LISTING_DEFAULT_CONTEXT_TOKENS = 200000;
+/**
+ * The token→byte exchange rate this budget allocates at.
+ *
+ * @contract skills.listing_budget_exchange_rate — deliberately NOT `DEFAULT_CHARS_PER_TOKEN` (3), and
+ * the difference is directional, not an inconsistency. That constant serves the compaction/context
+ * estimators, which convert bytes→tokens and must OVER-estimate the token count to stay inside a
+ * window; a low rate is the conservative choice there. This seat converts tokens→a byte ALLOWANCE,
+ * where a low rate silently SHRINKS what the deployment may spend. Two directions, two numbers, both
+ * named. At 3 the default allowance would be 6 000 bytes rather than 8 000 — a quarter of every
+ * default deployment's listing, removed by an estimator's safety margin.
+ */
+export declare const SKILL_LISTING_BYTES_PER_TOKEN = 4;
+/** The typed refusal a budget seat outside its domain raises: a bad value never selects a smaller
+ *  listing silently, and never folds back to the default budget. */
+export declare const SKILL_LISTING_BUDGET_INVALID_CODE = "config.skill_listing_budget_invalid";
+/** The notice code minted when the budget cost at least one skill its description or its line. */
+export declare const SKILL_LISTING_TRUNCATED_CODE = "skills.listing_truncated";
+/** The agent-type listing's twin: minted when the budget cost at least one agent type its detail or its line. */
+export declare const AGENT_LISTING_TRUNCATED_CODE = "agents.listing_truncated";
+/** Which listing frame a degradation report describes. */
+export type ListingKind = "skills" | "agents";
+/** The lowered seat: the two numbers the renderer measures against. */
+export interface ResolvedSkillListingBudget {
+    /** The budget the renderer enforces over the whole block (fences, headers, markers, joiners
+     *  included), in UTF-8 bytes. */
+    blockMaxBytes: number;
+    /** Per-skill description cap in code units, ellipsis included. */
+    descMaxChars: number;
+}
+/**
+ * The ONE reader of the two listing-budget seats.
+ *
+ * @contract skills.listing_budget_enforced_as_declared — the resolved `blockMaxBytes` is
+ * `floor(window × 4 × fraction)` with no ceiling above it: the `<skills>` frame is an intact-class
+ * attachment the delivery lane never clips, so what the deployment declares is what the renderer
+ * folds the listing into, on the initial block and on every drift frame alike. The fraction's own
+ * domain `(0, 1]` is the only upper bound (a whole window at most), and a value outside it refuses.
+ *
+ * `skillListingBudgetFraction` must be a finite number in `(0, 1]` — zero is excluded deliberately: a
+ * zero budget is not "spend nothing", it is a listing every skill loses its description to, which the
+ * deployment expresses by declaring fewer skills. `skillListingMaxDescChars` must be a positive safe
+ * integer. Both absent ⇒ the documented defaults, which reproduce the pre-seat render byte for byte
+ * (`200 000 × 4 × 0.01` = 8 000 bytes).
+ *
+ * The window is `contextTokens ?? contextWindow`, the same physical coordinate the deferral gate
+ * measures against. A window that is absent OR unusable (non-finite, non-positive) reads as
+ * {@link SKILL_LISTING_DEFAULT_CONTEXT_TOKENS}: one rule, not a case per bad shape — a model's own
+ * declaration is judged by the model doors, and this seat must still produce a number a renderer can
+ * compare against.
+ */
+export declare function resolveSkillListingBudget(opts: {
+    fraction?: unknown;
+    maxDescChars?: unknown;
+    model?: {
+        contextTokens?: number;
+        contextWindow?: number;
+    } | undefined;
+}): ResolvedSkillListingBudget;
+/** The reader's answer to "no knobs declared, no window declared" — the budget a renderer measures
+ *  against when its caller hands it none. One rule: only the reader turns knobs into numbers. */
+export declare const SKILL_LISTING_DEFAULT_BUDGET: Readonly<ResolvedSkillListingBudget>;
+/**
+ * Announce a listing frame the budget degraded — delivered only when an entry actually lost its detail
+ * (`nameOnly`) or its line (`dropped`), so a deployment whose roster fits hears nothing. One announcer
+ * for both listing frames; the code names the frame (`skills.listing_truncated` / `agents.listing_truncated`).
+ *
+ * Called from the commit of the frame's receipt — the moment the carrying message is in the transcript —
+ * never from the config door: the door cannot see the deployment's listing switches (resolved at run
+ * start), it runs per prepared task rather than per delivered listing, and a resume leg reaches only
+ * the boundary.
+ *
+ * Audience is `operator`: the person who can raise the fraction, shorten a description or remove an
+ * entry runs the deployment, not the session.
+ */
+export declare function announceListingTruncation(onNotice: ((notice: EngineNotice) => void) | undefined, opts: {
+    listing: ListingKind;
+    /** The denominator: how many entries the DELIVERED frame set out to list — the whole roster on an
+     *  initial frame, the newly announced set on a drift frame. Read off that frame's own render. */
+    total: number;
+    nameOnly: readonly string[];
+    dropped: readonly string[];
+    budget: ResolvedSkillListingBudget;
+    sessionId?: string | undefined;
+}): void;

package/dist/core/skill-listing-budget.js

@@ -0,0 +1,57 @@
+import { deliverEngineNotice } from "./engine-notice.js";
+import { describeRejectedValue } from "./tool-search-setting.js";
+export const SKILL_LISTING_BUDGET_FRACTION_DEFAULT = 0.01;
+export const SKILL_LISTING_DESC_MAX_CHARS_DEFAULT = 1_536;
+export const SKILL_LISTING_DEFAULT_CONTEXT_TOKENS = 200_000;
+export const SKILL_LISTING_BYTES_PER_TOKEN = 4;
+export const SKILL_LISTING_BUDGET_INVALID_CODE = "config.skill_listing_budget_invalid";
+export const SKILL_LISTING_TRUNCATED_CODE = "skills.listing_truncated";
+export const AGENT_LISTING_TRUNCATED_CODE = "agents.listing_truncated";
+function budgetRefusal(problem) {
+    const e = new Error(`TaskSpec.${problem}; a bad value refuses loudly, nothing falls back to the default listing budget.`);
+    e.code = SKILL_LISTING_BUDGET_INVALID_CODE;
+    return e;
+}
+export function resolveSkillListingBudget(opts) {
+    const { fraction, maxDescChars } = opts;
+    if (fraction !== undefined && (typeof fraction !== "number" || !Number.isFinite(fraction) || fraction <= 0 || fraction > 1)) {
+        throw budgetRefusal(`skillListingBudgetFraction: invalid value ${describeRejectedValue(fraction)} — expected a finite fraction in (0, 1]`);
+    }
+    if (maxDescChars !== undefined && (typeof maxDescChars !== "number" || !Number.isSafeInteger(maxDescChars) || maxDescChars <= 0)) {
+        throw budgetRefusal(`skillListingMaxDescChars: invalid value ${describeRejectedValue(maxDescChars)} — expected a positive integer`);
+    }
+    const declaredWindow = opts.model?.contextTokens ?? opts.model?.contextWindow;
+    const windowTokens = typeof declaredWindow === "number" && Number.isFinite(declaredWindow) && declaredWindow > 0
+        ? declaredWindow
+        : SKILL_LISTING_DEFAULT_CONTEXT_TOKENS;
+    return {
+        blockMaxBytes: Math.max(1, Math.floor(windowTokens * SKILL_LISTING_BYTES_PER_TOKEN * (fraction ?? SKILL_LISTING_BUDGET_FRACTION_DEFAULT))),
+        descMaxChars: maxDescChars ?? SKILL_LISTING_DESC_MAX_CHARS_DEFAULT,
+    };
+}
+export const SKILL_LISTING_DEFAULT_BUDGET = Object.freeze(resolveSkillListingBudget({}));
+export function announceListingTruncation(onNotice, opts) {
+    const { listing, total, nameOnly, dropped, budget } = opts;
+    if (nameOnly.length === 0 && dropped.length === 0)
+        return;
+    const skills = listing === "skills";
+    const message = `The ${skills ? "skills" : "agent-type"} listing does not fit its ${budget.blockMaxBytes}-byte budget` +
+        `: ${nameOnly.length} of ${total} are listed name-only` +
+        (dropped.length > 0 ? `, and ${dropped.length} did not fit the listing at all` : "") +
+        (skills
+            ? `. The \`Skill\` tool still serves every one of them. Raise skillListingBudgetFraction, lower skillListingMaxDescChars, or declare fewer skills.`
+            : `. Raise skillListingBudgetFraction or declare fewer agent types.`);
+    const detail = {
+        budgetBytes: budget.blockMaxBytes,
+        ...(skills ? { descMaxChars: budget.descMaxChars } : {}),
+        total,
+        kept: total - nameOnly.length - dropped.length,
+        nameOnly: [...nameOnly],
+        dropped: [...dropped],
+        ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+    };
+    if (skills)
+        deliverEngineNotice(onNotice, { code: SKILL_LISTING_TRUNCATED_CODE, message, detail });
+    else
+        deliverEngineNotice(onNotice, { code: AGENT_LISTING_TRUNCATED_CODE, message, detail });
+}

package/dist/core/skills-directory.js

@@ -197,6 +197,19 @@ function listRelativeFiles(base, dir, prefix, out, walk) {
         }
     }
 }
+function skillPhysicalRoot(skillDir, skillName, warn) {
+    try {
+        return physicalPathOf(skillDir);
+    }
+    catch (err) {
+        warn({
+            code: "read_failed",
+            skill: skillName,
+            detail: `the skill directory could not be resolved (${errText(err)}) — attachments skipped and no base directory is stated`,
+        });
+        return undefined;
+    }
+}
 function resolveInsideSkill(abs, rel, walk) {
     let real;
     let stats;
@@ -218,15 +231,7 @@ function resolveInsideSkill(abs, rel, walk) {
     }
     return { real, stats };
 }
-function readAttachments(skillDir, skillName, budgetBytes, warn) {
-    let realRoot;
-    try {
-        realRoot = physicalPathOf(skillDir);
-    }
-    catch (err) {
-        warn({ code: "read_failed", skill: skillName, detail: `the skill directory could not be resolved (${errText(err)}) — attachments skipped` });
-        return [];
-    }
+function readAttachments(skillDir, realRoot, skillName, budgetBytes, warn) {
     const walk = { realRoot, skill: skillName, warn, visited: new Set([realRoot]) };
     const relPaths = [];
     for (const d of RESOURCE_DIRS) {
@@ -442,11 +447,13 @@ export function createSkillsFromDirectory(dir, options = {}) {
                 detail: `disallowed-tools names ${disallowed.map((n) => `"${n}"`).join(", ")}, but this skill produced no allowlist to subtract from (allowed-tools is absent or claims every tool) — the deny declaration is NOT enforced (express it in the task's own tool policy)`,
             });
         }
-        const files = readAttachments(skillDir, name, budget, warn);
+        const baseDir = skillPhysicalRoot(skillDir, name, warn);
+        const files = baseDir === undefined ? [] : readAttachments(skillDir, baseDir, name, budget, warn);
         skills.push({
             name: declaredName,
             description,
             content: parsed.body,
+            ...(baseDir !== undefined ? { baseDir } : {}),
             ...(manifest !== undefined ? { manifest } : {}),
             ...(files.length > 0 ? { files } : {}),
         });

package/dist/core/task-registry.js

@@ -5,6 +5,7 @@ import { shutdownDebug } from "./shutdown-debug.js";
 import { canAccessAgentRecord, } from "./background-agent-store.js";
 import { delimitUntrusted } from "./untrusted-text.js";
 import { createSafeNotifier } from "./safe-notify.js";
+import { stripCwdSentinel } from "../tools/fs/fs-shared.js";
 import { registerMonitorLane, pollMonitorLane, stopMonitorLane } from "./task-registry-monitor.js";
 import { registerWorkflowLane, pollWorkflowLane, stopWorkflowLane } from "./task-registry-workflow.js";
 import { mintCompletionId, canAccessWorkflowRun, formatWorkflowRun, clipTaskOutput, assertOwnership, sleepPollStep, statusFromBackground, rollSpoolText, accountDroppedBytes, renderSpoolBody, spoolDropNote, droppedGapNote, alreadyTerminalStopNote, terminalTaskSummary, TASK_OUTPUT_MAX_CHARS, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccess, DURABLE_AGENT_HANDLE_RE, } from "./task-registry-shared.js";
@@ -46,7 +47,7 @@ function noTaskForStop(taskId, enrich) {
 }
 function bashTerminalResult(spool) {
     const out = spool.stdout.slice(-2_000);
-    const err = spool.stderr.slice(-2_000);
+    const err = stripCwdSentinel(spool.stderr).stderr.slice(-2_000);
     return err.length > 0 ? `${out}${out.length > 0 ? "\n" : ""}--- stderr (tail) ---\n${err}` : out;
 }
 async function drainBashTailBestEffort(handle) {

package/dist/core/task-spec.d.ts

@@ -935,6 +935,33 @@ export interface TaskSpec {
      * end-user-authored skills are responsible for vetting them: a skill IS instructions by design.
      */
     skills?: SkillSpec[];
+    /**
+     * Fraction of the model's context window the `<skills>` listing may spend. Absent ⇒ `0.01` (1%).
+     * Domain `(0, 1]`; anything else — including `0`, a string, `NaN` — REFUSES at the door with
+     * `config.skill_listing_budget_invalid` rather than folding back to the default.
+     *
+     * The budget is `(contextTokens ?? contextWindow ?? 200 000) × 4 × fraction`, in UTF-8 bytes, and the
+     * listing degrades inside it: every skill stays listed, the lower-priority ones (declaration order)
+     * lose their descriptions first. Raising this is opting in to a higher per-turn context cost.
+     *
+     * Enforced as declared (`@contract skills.listing_budget_enforced_as_declared`): the listing frames are
+     * intact-class turn attachments the delivery lane never clips, so the resolved budget has no ceiling
+     * above it — a fraction that asks for more gets more (a 1 000 000-token window at the default 0.01 is
+     * 40 000 bytes). The same fraction is EACH listing attachment's budget: the agent-type roster frame
+     * folds into `window × 4 × fraction` too (every type stays listed, the last-declared lose their detail
+     * first; `agents.listing_truncated` reports it).
+     *
+     * ⚠️ A model declaring a window SMALLER than 200 000 tokens now gets a proportionally smaller listing
+     * budget than the flat 8 000 bytes that preceded this seat.
+     */
+    skillListingBudgetFraction?: number;
+    /**
+     * Per-skill description cap inside the `<skills>` listing, in code units, ellipsis included. Absent ⇒
+     * `1536`. Must be a positive integer; anything else REFUSES with
+     * `config.skill_listing_budget_invalid`. A description longer than the cap is truncated to exactly
+     * this many units; lowering it is how a deployment fits more skills' descriptions inside one budget.
+     */
+    skillListingMaxDescChars?: number;
     /**
      * design/129 — lifetime scope for BACKGROUND children (Agent/Fork `run_in_background`). Default `"task"`:
      * the parent runTask's terminal reaps them (design/115 — no orphans burning tokens; turn-end killed
@@ -1225,8 +1252,8 @@ export interface TaskSpec {
      *    back to a transcript probe for older checkpoints — never replayed when already delivered.
      *  - `skillsListing` ([c209-C], DEFAULT-ON, mechanism-family sibling of `agentListing` — no CC
      *    delta anchor, registered in cc-divergences): the FIRST user turn carries the full `<skills>`
-     *    disclosure block (the exact render that used to sit in the stable system prompt — capped
-     *    byte-exact at SKILLS_BLOCK_MAX_BYTES 8000 ≤ the 8192 bundle cap since [c209-C] R2 C4, with
+     *    disclosure block (the exact render that used to sit in the stable system prompt — folded
+     *    byte-exact into the listing budget, `skillListingBudgetFraction` × the window, with
      *    name-only overflow); boundaries announce only skill-set drift. Resume seeding mirrors
      *    `agentListing`.
      *  - `mcpInstructions` (G1 续批 — CC `mcp_instructions_delta` parity): the INITIAL server

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

@@ -1,5 +1,5 @@
 import type { AskOrigin } from "./ask-origin.js";
-import type { Settlement } from "./gate-outcome.js";
+import { type Settlement } from "./gate-outcome.js";
 /** A tool call presented to a policy before it executes. */
 /** design/388 B6 — the per-call face (see {@link ToolCallRequest.face}). */
 export interface ToolCallFace {
@@ -147,7 +147,7 @@ export declare function advertisedWritableRootsSeat(seat: {
 };
 declare const DECISION_REASONS: readonly ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable", "read_only"];
 export type DecisionReason = (typeof DECISION_REASONS)[number];
-/** Carry every engine attestation (settlement, classifier cause) from a decision onto a reconstruction of it — the
+/** 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). Not re-exported from `src/index.ts`. */
 export declare function carryEngineAttestations(from: object, to: object): void;
@@ -168,6 +168,17 @@ 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: {
+    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: {
+    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: {
     toolCallId: string;
@@ -310,6 +321,11 @@ export type PermissionResult = {
      *  in the one direction the stamp cannot reach (a caller composing its own ask) the claim is
      *  tightening-only: it can make an ask outlive a rule, never turn one into an allow. */
     probeMandated?: true;
+    /** The probe named a directory that would clear this ask
+     *  ({@link import("./types.js").ReversibilityVerdict.readRootCandidate}). Display metadata like the two
+     *  `probe*` above; ENGINE-STAMPED and VALIDATED at the tighten, and deliberately NOT merged onto an ask
+     *  another layer raised, which a grant leaves standing. */
+    probeReadRootCandidate?: import("./types.js").ReadRootGrantCandidate;
     /** An EXPLICIT `ask` permission rule matched this call (design/127 DSL — the CC `alwaysAskRules`
      *  shape); carries the matched rule's text. Present ⇔ a rule someone WROTE says "ask about this",
      *  never for a `defaultAction:"ask"` fallback (an unmatched call is default-closed posture, not a
@@ -1013,6 +1029,15 @@ export interface AskRequest {
      *  structure: render the entries as data, never re-derive structure by splitting or joining them.
      *  The durable park route carries the same value as `RiskDescriptor.probeCause`. */
     readonly probeCause?: import("./checkpoint-store.js").ProbeCause;
+    /**
+     * The ask-facing face of {@link import("./types.js").ReversibilityVerdict.readRootCandidate}, which owns
+     * the meaning, the absence reading and the spelling contract: PRESENT ⇒ declaring this one directory
+     * clears THIS ask, so a card can offer "add it and stop being asked" beside "yes, this once". Filled at
+     * the synchronous MINT station by the tighten that ran the probe — the three INHERITED-lane sites present
+     * an ancestor's decision from upstream of it and carry none, and the durable park row has NO twin: a
+     * parked out-of-root ask renders the confirmation alone.
+     */
+    readonly readRootCandidate?: import("./types.js").ReadRootGrantCandidate;
     /** design/252 G-2: the RULE-PROVENANCE evidence behind this ask — the org snapshot revision and the
      *  matched rules' own identity keys, each present as a value or as a named absence (see
      *  {@link AskRuleEvidence}). Present on EVERY ask the engine mints, so a consumer never has to tell a
@@ -1121,9 +1146,10 @@ export interface AskRequest {
      *    probe declared structural — for the built-in shell probe, a read outside the directories this
      *    session declared. A surface must NOT point at rule-writing here — "allow rules silence the
      *    classifier's questions, never a mandated one", so a rule minted in answer to this line would
-     *    never take effect where it was minted. It must not point at a directory GRANT either: the
-     *    out-of-root arm has no clearing configuration in this version, and confirming the call is the
-     *    whole of what a person can do about it;
+     *    never take effect where it was minted. Whether a DIRECTORY grant is worth pointing at is not this
+     *    seat's to say: it is answered per ask by {@link readRootCandidate}, which is present exactly when
+     *    widening the session's read directories would clear this one and absent for every other member of
+     *    the family — so a surface reads that seat and never infers an answer from this word;
      *  · `"shadowed"` — a rule the person already wrote is speaking and does not clear this ask (a
      *    matching allow rule that the lane refuses to honor here, or their own explicit `ask` rule);
      *  · `"lane_cannot_speak"` — the lane is armed and this ask IS clearable, but the offer lane

package/dist/core/tool-policy.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { brandPolicyAskClass } from "./ask-class.js";
+import { decidersNote, settledByPerson } from "./gate-outcome.js";
 import { sanitizeAutoModeArmingRecipe } from "./auto-mode-arming.js";
 import { join, normalize as normalizePath, sep } from "node:path";
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
@@ -18,9 +19,6 @@ const DECISION_REASON_SET = new Set(DECISION_REASONS);
 function settledByNobody(kind) {
     return { kind, who: { party: "none" }, when: Date.now() };
 }
-function settledByPerson(kind, approver, note) {
-    return { kind, who: { party: "person", ...(approver !== undefined ? { approver } : {}) }, when: Date.now(), ...(note !== undefined ? { note } : {}) };
-}
 const ENGINE_SETTLEMENTS = new WeakMap();
 function attestEngineSettlement(d, record, call) {
     const s = record.settlement;
@@ -28,19 +26,18 @@ function attestEngineSettlement(d, record, call) {
     ENGINE_SETTLEMENTS.set(d, { settlement, origin: record.origin, toolCallId: call.toolCallId, toolName: call.toolName });
     return d;
 }
-function transferEngineSettlement(from, to) {
-    const v = ENGINE_SETTLEMENTS.get(from);
-    if (v !== undefined)
-        ENGINE_SETTLEMENTS.set(to, v);
-    const c = CLASSIFIER_DENY_CAUSES_SEAT.get(from);
-    if (c !== undefined)
-        CLASSIFIER_DENY_CAUSES_SEAT.set(to, c);
-    const u = ASK_UNRESOLVABLE_CAUSES_SEAT.get(from);
-    if (u !== undefined)
-        ASK_UNRESOLVABLE_CAUSES_SEAT.set(to, u);
+function transferEngineAttestations(from, to) {
+    for (const seat of ENGINE_ATTESTATION_SEATS) {
+        const v = seat.get(from);
+        if (v !== undefined)
+            seat.set(to, v);
+    }
+}
+function hasEngineAttestation(o) {
+    return ENGINE_ATTESTATION_SEATS.some((seat) => seat.has(o));
 }
 export function carryEngineAttestations(from, to) {
-    transferEngineSettlement(from, to);
+    transferEngineAttestations(from, to);
 }
 export function carryPrecedingSettlement(preceding, to) {
     if (ENGINE_SETTLEMENTS.get(to) !== undefined)
@@ -62,6 +59,19 @@ export function classifierDenyCauseOf(d, call) {
         return undefined;
     return v.cause;
 }
+const CLASSIFIER_ROUNDS_SEAT = new WeakMap();
+export function attestClassifierRound(d, round, call) {
+    CLASSIFIER_ROUNDS_SEAT.set(d, { round, toolCallId: call.toolCallId, toolName: call.toolName });
+    return d;
+}
+export function classifierRoundOf(d, call) {
+    if (typeof d !== "object" || d === null)
+        return undefined;
+    const v = CLASSIFIER_ROUNDS_SEAT.get(d);
+    if (v === undefined || v.toolCallId !== call.toolCallId || v.toolName !== call.toolName)
+        return undefined;
+    return v.round;
+}
 const ASK_UNRESOLVABLE_CAUSES_SEAT = new WeakMap();
 export function attestAskUnresolvableCause(d, cause, call) {
     ASK_UNRESOLVABLE_CAUSES_SEAT.set(d, { cause, toolCallId: call.toolCallId, toolName: call.toolName });
@@ -75,6 +85,7 @@ export function askUnresolvableCauseOf(d, call) {
         return undefined;
     return v.cause;
 }
+const ENGINE_ATTESTATION_SEATS = [ENGINE_SETTLEMENTS, CLASSIFIER_DENY_CAUSES_SEAT, ASK_UNRESOLVABLE_CAUSES_SEAT, CLASSIFIER_ROUNDS_SEAT];
 export function engineSettlementOf(d, call) {
     if (typeof d !== "object" || d === null)
         return undefined;
@@ -441,7 +452,8 @@ export function combinePolicies(...policies) {
             let asked;
             let current = req;
             let rewrite;
-            let settledAllow;
+            const records = {};
+            let anyRecord = false;
             let ruleAskText;
             let probeMandateSeen = false;
             let fallbackSeen;
@@ -450,23 +462,23 @@ export function combinePolicies(...policies) {
                 if (d.action === "deny") {
                     const out = rewrite?.updatedInput !== undefined ? { ...d, updatedInput: rewrite.updatedInput } : d;
                     if (out !== d) {
-                        transferEngineSettlement(d, out);
-                    }
-                    if (settledAllow !== undefined && ENGINE_SETTLEMENTS.get(out) === undefined) {
-                        const owned = out === d ? { ...d } : out;
-                        if (owned !== d)
-                            transferEngineSettlement(d, owned);
-                        transferEngineSettlement(settledAllow, owned);
-                        return owned;
+                        transferEngineAttestations(d, out);
                     }
-                    return out;
+                    if (!anyRecord)
+                        return out;
+                    const owned = out === d ? { ...d } : out;
+                    transferEngineAttestations(records, owned);
+                    transferEngineAttestations(d, owned);
+                    return owned;
                 }
                 if (d.updatedInput !== undefined) {
                     current = { ...current, args: d.updatedInput };
                     rewrite = d;
                 }
-                if (d.action === "allow" && ENGINE_SETTLEMENTS.has(d))
-                    settledAllow = d;
+                if (d.action === "allow" && hasEngineAttestation(d)) {
+                    transferEngineAttestations(d, records);
+                    anyRecord = true;
+                }
                 if (d.action === "ask" && (asked === undefined || (d.requiresRealApproval === true && asked.requiresRealApproval !== true))) {
                     asked = d;
                 }
@@ -486,10 +498,10 @@ export function combinePolicies(...policies) {
                 return merged !== undefined ? { ...withFallback, updatedInput: merged } : withFallback;
             }
             const allowed = rewrite ?? ALLOW;
-            if (settledAllow === undefined)
+            if (!anyRecord)
                 return allowed;
             const out = { ...allowed };
-            transferEngineSettlement(settledAllow, out);
+            transferEngineAttestations(records, out);
             return out;
         },
     };
@@ -1273,7 +1285,7 @@ async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
                         settlement: settledByNobody("approver_contract"),
                     };
                 }
-                reasonText = typeof suppliedReason === "string" && suppliedReason !== "" ? suppliedReason : undefined;
+                reasonText = typeof suppliedReason === "string" ? suppliedReason : undefined;
             }
             catch (err) {
                 return {
@@ -1283,15 +1295,16 @@ async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
                     settlement: settledByNobody("approver_contract"),
                 };
             }
+            const note = decidersNote(reasonText);
             return {
                 action: "deny",
                 message: supplied === "timeout"
-                    ? `approval for "${req.toolName}" was not answered before the approver's own window elapsed: ${req.message}${reasonText !== undefined ? `\nReviewer note:\n${delimitUntrusted("reviewer note", reasonText, REVIEWER_NOTE_MAX_BODY)}` : ""}`
-                    : humanRefusalMessage(req, reasonText),
+                    ? `approval for "${req.toolName}" was not answered before the approver's own window elapsed: ${req.message}${note !== undefined ? `\nReviewer note:\n${delimitUntrusted("reviewer note", note, REVIEWER_NOTE_MAX_BODY)}` : ""}`
+                    : humanRefusalMessage(req, note),
                 decisionReason: "mode",
                 settlement: supplied === "timeout"
                     ? { kind: "approval_window_expired", who: { party: "host" }, when: Date.now() }
-                    : settledByPerson("human_refused", attribution.approver, reasonText),
+                    : settledByPerson("human_refused", attribution.approver, note),
             };
         }
         if (suppliedEdit === undefined)

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

@@ -62,12 +62,45 @@ export interface ReversibilityVerdict {
      * its own deployment a re-confirmation and can never turn an ask into an allow.
      *
      * The built-in shell probe sets it for exactly one family: a listed reader naming a path outside the
-     * session's allowed directories. The engine's own out-of-root demotion has no clearing channel in
-     * this version other than confirming the call each time — a directory-scoped grant that WOULD clear
-     * it is a separate, later mechanism, and until it exists a surface must not word the refusal as
-     * though one already answers it.
+     * session's allowed directories. That demotion HAS a clearing channel — widening the declared read
+     * directories retires it — and where the probe can name the directory, {@link readRootCandidate} carries
+     * it. A mandated ask WITHOUT that member has no configuration behind it: the rest of the family (an
+     * operator `shellGate:"always"`, the tool's egress/irreversibility marks, an org demand, an out-of-root
+     * arm with no named directory) is confirm-or-refuse, and must not be worded as though a grant answers it.
      */
     mandated?: boolean;
+    /**
+     * The directory-scoped GRANT that would clear THIS ask, when the probe can name one: PRESENT ⇒ the only
+     * thing between this call and a plain `reversible: true` verdict is the session's declared read
+     * containment, and adding {@link ReadRootGrantCandidate.dir} to it makes the same call run with no card.
+     *
+     * ABSENT is the ordinary world and no claim that nothing would clear the ask — it covers every demotion
+     * with no directory answer (a deny row, a read the walk could not read, an unenumerable expansion, a
+     * shape refused whatever the roots say) and every probe silent on this member. Read presence, never
+     * absence. ADVISORY display metadata, never adjudication input.
+     */
+    readRootCandidate?: ReadRootGrantCandidate;
+}
+/**
+ * A directory-scoped grant a surface can offer on an approval card — see
+ * {@link ReversibilityVerdict.readRootCandidate} and `AskRequest.readRootCandidate`.
+ *
+ * @contract shell.read_boundary.grant_candidate_is_the_grant — {@link dir} is the string to ADD, not a
+ * string to show: a consumer that renders a shortened or home-relative form must send this exact spelling
+ * back when the person accepts. Core mints one spelling for both errands, and the promise is over THAT
+ * spelling reaching the directories the boundary compares against: a deployment that REWRITES a declared
+ * directory — canonicalizing a symlinked one included — must rewrite the command's spelling the same way,
+ * or it will compare a rewritten root against an unrewritten operand and ask again. Where the two differ
+ * the ask was unclearable before this seat existed and still is; the offer names the directory the command
+ * spelled, which is the only one derivable from the text.
+ */
+export interface ReadRootGrantCandidate {
+    /** An absolute, lexically folded directory in the boundary's own spelling; never a file or a pattern. */
+    readonly dir: string;
+    /** Always the literal `true` — a shape, not a value, so the seat cannot be widened into a "maybe this
+     *  helps" hint without a visible type change. It claims THIS ask: not the deny layer (judged by pattern
+     *  rather than by root, and unmoved by any grant), and not another ask the same call may raise. */
+    readonly clearsThisAsk: true;
 }
 export interface ToolSpec<TParams extends TSchema = TSchema> {
     /**

package/dist/core/types.d.ts

@@ -13,7 +13,7 @@ import type { AgentTool, ThinkingLevel, ToolInputValidationContext, ToolInputVer
 import type { Model, StreamFn } from "../internal/llm.js";
 export type { ModelRef, ModelRole, RoleSpec, ModelRoles, Brain } from "./model-seat.js";
 export type { StaleToolResultOffloadOptions, ImageInput, TaskSpec, ShellGateDoctrine } from "./task-spec.js";
-export type { ToolEffect, ToolContentOrigin, ReversibilityVerdict, ToolSpec, ToolReturn, NestedUsage, NestedUsageAccum, ToolExecuteContext } from "./tool-spec.js";
+export type { ToolEffect, ToolContentOrigin, ReversibilityVerdict, ReadRootGrantCandidate, ToolSpec, ToolReturn, NestedUsage, NestedUsageAccum, ToolExecuteContext } from "./tool-spec.js";
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook, FileEditedNotice, FileEditedHook, HandsBandOptions } from "./hands-band.js";
 export type { AgentDefinition, SkillManifest, SkillSpec } from "./agent-definition.js";
 export type { McpServerSpec, A2aServerSpec, McpElicitRequest, McpElicitResponse, OnElicit } from "./mcp-server-spec.js";