@sema-agent/core 7.19.0 → 7.20.0

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

@@ -5,6 +5,10 @@
  * 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.
@@ -28,50 +32,37 @@ export declare const SKILL_LISTING_DEFAULT_CONTEXT_TOKENS = 200000;
  * default deployment's listing, removed by an estimator's safety margin.
  */
 export declare const SKILL_LISTING_BYTES_PER_TOKEN = 4;
-/**
- * The hard ceiling on the rendered `<skills>` block, in UTF-8 bytes.
- *
- * @contract skills.listing_budget_ceiling — this is a STRUCTURAL property of the delivery lane, not a
- * policy choice and not a superset optimization. The block is not part of the system prompt: it is the
- * body of the `skills_listing` turn attachment, and every attachment bundle is capped at
- * `ATTACHMENT_BYTE_CAP` (8 KiB) by the boundary's `capAttachments`, which CLIPS anything over. A
- * clipped skills frame never satisfies the run loop's intact-survival commit predicate, so the
- * announced set never advances and the frame is re-rendered and re-clipped at every subsequent
- * boundary — permanently. The cap is therefore enforced byte-exact over the WHOLE render (fences,
- * headers, markers, joiners included) and MUST stay ≤ `ATTACHMENT_BYTE_CAP`; the renderer's module
- * pins that relation, since importing the attachment module here would invert the dependency.
- *
- * The consequence is a one-way knob: {@link resolveSkillListingBudget} clamps the declared budget to
- * this number, so a raised fraction (or a model with a very large window) can LOWER the listing budget
- * but can never raise it above this ceiling. When the clamp costs a description, both numbers ride the
- * disclosure ({@link announceSkillListingTruncation}), so the deployment reads what it asked for beside
- * what it got instead of inferring the ceiling from a short listing.
- */
-export declare const SKILLS_BLOCK_MAX_BYTES = 8000;
 /** 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 lowered seat: the two numbers the renderer measures against, plus what was asked for. */
+/** 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, in UTF-8 bytes — already clamped to
-     *  {@link SKILLS_BLOCK_MAX_BYTES}. */
+    /** The budget the renderer enforces over the whole block (fences, headers, markers, joiners
+     *  included), in UTF-8 bytes. */
     blockMaxBytes: number;
-    /** What the declared fraction asked for BEFORE the structural clamp. Equal to `blockMaxBytes`
-     *  whenever the ceiling did not bind; strictly greater when it did. */
-    requestedBytes: 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 = {@link SKILLS_BLOCK_MAX_BYTES}).
+ * (`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
@@ -87,23 +78,26 @@ export declare function resolveSkillListingBudget(opts: {
         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 the budget degraded — delivered only when a skill actually lost its description
- * (`nameOnly`) or its line (`dropped`), so a deployment whose roster fits hears nothing.
+ * 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 two lanes that DELIVER a listing frame (the leg's first-frame producer and the turn
- * boundary), never from the config door: the door cannot see the deployment's
- * `attachments.skillsListing` switch (resolved at run start), it runs per prepared task rather than per
- * delivered listing, and a resume leg reaches only the boundary.
+ * 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 a
- * skill runs the deployment, not the session. `requestedBudgetBytes` rides beside `budgetBytes`
- * precisely so the structural ceiling ({@link SKILLS_BLOCK_MAX_BYTES}) is legible at the moment it
- * costs something — the two differ only when the clamp bound.
+ * 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 announceSkillListingTruncation(onNotice: ((notice: EngineNotice) => void) | undefined, opts: {
-    /** The denominator: how many skills the DELIVERED frame set out to list — the whole roster on an
-     *  initial block, the newly announced set on a drift frame. Read off that frame's own render. */
+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[];

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

@@ -4,9 +4,9 @@ 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 SKILLS_BLOCK_MAX_BYTES = 8_000;
 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;
@@ -24,35 +24,34 @@ export function resolveSkillListingBudget(opts) {
     const windowTokens = typeof declaredWindow === "number" && Number.isFinite(declaredWindow) && declaredWindow > 0
         ? declaredWindow
         : SKILL_LISTING_DEFAULT_CONTEXT_TOKENS;
-    const requestedBytes = Math.max(1, Math.floor(windowTokens * SKILL_LISTING_BYTES_PER_TOKEN * (fraction ?? SKILL_LISTING_BUDGET_FRACTION_DEFAULT)));
     return {
-        blockMaxBytes: Math.min(requestedBytes, SKILLS_BLOCK_MAX_BYTES),
-        requestedBytes,
+        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 function announceSkillListingTruncation(onNotice, opts) {
-    const { total, nameOnly, dropped, budget } = opts;
+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 clamped = budget.requestedBytes > budget.blockMaxBytes;
-    deliverEngineNotice(onNotice, {
-        code: SKILL_LISTING_TRUNCATED_CODE,
-        message: `The skills listing does not fit its ${budget.blockMaxBytes}-byte budget` +
-            (clamped ? ` (${budget.requestedBytes} bytes were declared; the listing's delivery lane caps it at ${SKILLS_BLOCK_MAX_BYTES})` : "") +
-            `: ${nameOnly.length} of ${total} are listed name-only` +
-            (dropped.length > 0 ? `, and ${dropped.length} did not fit the listing at all` : "") +
-            `. The \`Skill\` tool still serves every one of them. Raise skillListingBudgetFraction, lower` +
-            ` skillListingMaxDescChars, or declare fewer skills.`,
-        detail: {
-            budgetBytes: budget.blockMaxBytes,
-            requestedBudgetBytes: budget.requestedBytes,
-            descMaxChars: budget.descMaxChars,
-            total,
-            kept: total - nameOnly.length - dropped.length,
-            nameOnly: [...nameOnly],
-            dropped: [...dropped],
-            ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
-        },
-    });
+    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

@@ -944,11 +944,12 @@ export interface TaskSpec {
      * 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.
      *
-     * ⚠️ ONE-WAY IN PRACTICE (`@contract skills.listing_budget_ceiling`): the listing rides the turn-
-     * attachment lane, whose bundle cap is a hard structural limit, so the resolved budget is clamped to
-     * 8 000 bytes. A fraction that asks for MORE lowers nothing and raises nothing; a fraction that asks
-     * for less takes effect exactly. When the clamp costs a skill its description, both numbers ride the
-     * `skills.listing_truncated` notice.
+     * 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.
@@ -1251,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

@@ -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;

package/dist/core/tool-policy.js

@@ -26,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)
@@ -60,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 });
@@ -73,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;
@@ -439,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;
@@ -448,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;
                 }
@@ -484,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;
         },
     };

package/dist/core/write-protect.d.ts

@@ -1,3 +1,5 @@
+import type { ExecutionEnv } from "../internal/harness-types.js";
+import type { PermissionResult } from "./tool-policy.js";
 import { type ToolCallLike } from "./tool-registry.js";
 /**
  * How one table row matches the judged path:
@@ -45,12 +47,44 @@ export declare function foldWriteProtectCase(s: string): string;
  * candidate configuration with the engine's own rules.
  */
 export declare function resolveWriteProtectedTable(entries?: readonly WriteProtectedEntry[]): readonly WriteProtectedRow[];
-/** The compiled judge over one resolved table. Pure and synchronous — literal folded comparisons,
- *  no filesystem access (see the module header for the declared lexical scope). */
+/**
+ * The judge's answer for ONE covered write ({@link WriteProtectionMatcher.judge}):
+ *  · `clear` — no row on either view: the write is not this layer's business;
+ *  · `hit` — a row matched; `via` says which view named it: `"spelling"` (the anchored spelling, no
+ *    filesystem consulted) or `"target"` (the resolved real target, the spelling being innocent);
+ *  · `unresolvable` — the real target could not be resolved (an unfollowable symlink, an errored probe, a
+ *    namespace spelling the tree refuses); `cause` is the canonicalizer's own sentence and the consumer
+ *    REFUSES, an unjudged target never being vouched.
+ */
+export type WriteProtectionVerdict = {
+    readonly kind: "clear";
+} | {
+    readonly kind: "hit";
+    readonly hit: WriteProtectedHit;
+    readonly via: "spelling" | "target";
+} | {
+    readonly kind: "unresolvable";
+    readonly cause: string;
+    readonly unresolvedSymlink: boolean;
+};
+/** What one judgment knows about the call, all optional — every member has an absence reading. */
+export interface WriteProtectionJudgeContext {
+    /** The call's LIVE tracked working directory (see {@link WriteProtectionMatcher.matchPath}). */
+    readonly cwd?: string;
+    /** The base a RELATIVE spelling resolves against on the TARGET view — the tool's own declared base
+     *  ({@link pathTargetBaseOf}). Absent ⇒ `cwd`, then the compile-time `rootPath`, then the environment's
+     *  own working directory: the same fallback chain the write tool itself walks. */
+    readonly base?: string;
+    /** Bounds the filesystem probes of the target view. */
+    readonly signal?: AbortSignal;
+}
+/** The compiled judge over one resolved table. `matchPath` is the SPELLING view alone (literal folded
+ *  comparisons, no filesystem access — the admin preview face); `judge` is the whole judgment (see the
+ *  module header for the two views). */
 export interface WriteProtectionMatcher {
     /** The resolved rows this judge was compiled from (canonical names — the disclosure face). */
     readonly rows: readonly WriteProtectedRow[];
-    /** Judge ONE path spelling. Returns the first matching row (basename rows first, then segment,
+    /** Judge ONE path SPELLING. Returns the first matching row (basename rows first, then segment,
      *  then segment-run — deterministic), or null.
      *
      *  `cwd` = the call's LIVE tracked working directory, read at judgment time off the ONE ref the fs
@@ -58,33 +92,79 @@ export interface WriteProtectionMatcher {
      *  Absent ⇒ judged exactly as given — the historical reading, and the honest answer for a host
      *  that tracks no cwd. */
     matchPath(path: string, cwd?: string): WriteProtectedHit | null;
+    /**
+     * Judge ONE covered write by the file the tool will write: the spelling view first (`matchPath`; a hit
+     * there is the answer and costs no I/O), then — on a miss, and only when the judge was compiled with an
+     * execution environment — the resolved real target through the shared `canonicalizeTarget`.
+     *
+     * @contract write_protection.judges_the_real_target — the always-on write-protection table and the
+     * opt-in sensitive-path deny set differ in VOCABULARY (literal rows / segment globs) and SEVERITY
+     * (ask / deny), never in REACH: both judge the file the tool will write — the spelling anchored at the
+     * live cwd AND its resolved real target, through one canonicalizer — and a target neither can resolve is
+     * refused, never vouched. An environment-less judge has no target view and answers by the spelling alone —
+     * the same absence law the cwd follows (absent ⇒ the spelling is judged exactly as given). REACH is what
+     * this sentence promises, not a LOCK: the identity is resolved at judgment time and re-resolved by the
+     * tool at execute time (the module header states that window and the seat that would close it).
+     */
+    judge(path: string, ctx?: WriteProtectionJudgeContext): Promise<WriteProtectionVerdict>;
+}
+/** Compile-time seats of {@link compileWriteProtection}. Every member is optional and has an absence reading. */
+export interface WriteProtectionCompileOptions {
+    /** The engine data root for the passthrough in the module header (same seat and same meaning as
+     *  `createSensitivePathPolicy`'s): omitted ⇒ the knob its consumers read (`$AGENT_DATA_DIR ?? ~/.ai-agent`). */
+    readonly dataRoot?: string;
+    /** The execution environment the hands write against — the TARGET view resolves in ITS filesystem
+     *  (a remote/sandboxed task resolves in its container). Omitted ⇒ no target view: the spelling is the
+     *  judgment (a host with no hands has no filesystem to resolve against). */
+    readonly env?: ExecutionEnv;
+    /** The task root — the base a `base: "root"` write tool's relative spelling resolves against, and the
+     *  path-family source when the call carries no cwd. Omitted ⇒ relative spellings resolve against the
+     *  cwd, then the environment's own working directory. */
+    readonly rootPath?: string;
 }
 /**
  * Compile the write-protection judge for a deployment configuration. Returns `undefined` when the
  * resolved table is EMPTY (`[]` replacement) — the caller then mounts no tighten at all, keeping an
  * opted-out deployment's decision path byte-identical to a build without this layer.
  *
- * `opts.dataRoot` names the engine data root for the passthrough in the module header (same seat and
- * same meaning as `createSensitivePathPolicy`'s): omitted ⇒ the knob its consumers read
- * (`$AGENT_DATA_DIR ?? ~/.ai-agent`), read ONCE here at compile so the judge stays pure and
- * synchronous. The passthrough is a property of the JUDGE, not of the default table — a deployment
+ * The data-root spellings are read ONCE here at compile (a judge that re-read `process.env` per call
+ * would answer two calls of one run differently); their CANONICAL keys are resolved per judgment, on the
+ * target view only, and only once a row has matched there (see {@link canonicalDataRootKeys} for why they
+ * are never cached). The passthrough is a property of the JUDGE, not of the default table — a deployment
  * that replaces the table wholesale gets the same law over its own rows.
  */
-export declare function compileWriteProtection(entries?: readonly WriteProtectedEntry[], opts?: {
-    dataRoot?: string;
-}): WriteProtectionMatcher | undefined;
+export declare function compileWriteProtection(entries?: readonly WriteProtectedEntry[], opts?: WriteProtectionCompileOptions): WriteProtectionMatcher | undefined;
+/**
+ * The gate tighten's DECISION for one judgment — the words the fold writes on the pass, minted beside the
+ * verdict they read so the two cannot drift:
+ *  · `hit` ⇒ `ask` (`safety`; no `requiresRealApproval` — one explicit look, clearable by an approver, a
+ *    blanket `onAsk:"allow"`, the classifier or a matching persisted rule). The matched row NAME goes on the
+ *    message (table names are deployment-validated vocabulary); the model-authored target path deliberately
+ *    does not — `message` is the classifier's `askMessage`, and the approval card already shows the args. The
+ *    spelling form's sentence is the historical one byte for byte; the target form says the target RESOLVED.
+ *  · `unresolvable` ⇒ `deny` naming the cause: an unjudged target is never vouched, and an ask would be a
+ *    question about a file nobody can name — the rule the canonicalizing deny set follows for the same reason.
+ *  · `clear` ⇒ `undefined`: the surviving decision stands.
+ */
+export declare function writeProtectionTightenDecision(toolName: string, verdict: WriteProtectionVerdict): PermissionResult | undefined;
+/**
+ * The ENGINE-FILLED gate input (`ToolGateInput.writeProtectionCheck`). Returns `null` SYNCHRONOUSLY when the
+ * call is not this layer's business — not a covered write, or no resolvable target string — and otherwise
+ * the judgment of {@link WriteProtectionMatcher.judge}, a promise. The split is load-bearing for the gate:
+ * a call the judge does not cover must not cost the fold a suspension point.
+ */
+export type WriteProtectionCheck = (toolName: string, args: unknown, face?: ToolCallLike["face"], cwd?: string, signal?: AbortSignal) => Promise<WriteProtectionVerdict> | null;
 /**
  * Build the ENGINE-FILLED gate input (`ToolGateInput.writeProtectionCheck`): covered tools are the
  * path-confinable write set (Write/Edit/NotebookEdit — the shared spelling), the judged target is
  * the SAME string the tool itself will resolve (`writeTargetPath`, the shared single source with
  * the sensitive-path guard and the fs-write gate), and the verdict is the table judge's. A covered
- * write with NO resolvable target returns null here — this layer is ADDITIVE friction on a named
- * set of targets, not a containment boundary (a target-less call cannot land on a named row, and
- * the tool's own schema validation refuses it before any write); the fail-closed treatment of the
- * unresolvable case belongs to the containment gates (fs-write-gate-policy documents that split).
+ * write with NO resolvable target string returns null here — this layer is ADDITIVE friction on a named
+ * set of targets, not a containment boundary (a target-less call cannot land on a named row, and the
+ * tool's own schema validation refuses it before any write); the fail-closed treatment of that case
+ * belongs to the containment gates (fs-write-gate-policy documents that split). A target string the
+ * environment cannot RESOLVE is the judge's own `unresolvable` verdict, not this null.
  * Returns `undefined` when the resolved table is empty — nothing to judge, mount nothing.
- * `opts.dataRoot` is the judge's own seat, passed straight through ({@link compileWriteProtection}).
+ * `opts` are the judge's own seats, passed straight through ({@link compileWriteProtection}).
  */
-export declare function createWriteProtectionCheck(entries?: readonly WriteProtectedEntry[], opts?: {
-    dataRoot?: string;
-}): ((toolName: string, args: unknown, face?: ToolCallLike["face"], cwd?: string) => WriteProtectedHit | null) | undefined;
+export declare function createWriteProtectionCheck(entries?: readonly WriteProtectedEntry[], opts?: WriteProtectionCompileOptions): WriteProtectionCheck | undefined;