@sema-agent/core 7.53.0 → 7.54.1

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

@@ -2,6 +2,7 @@ import { Type, type Static, type TSchema } from "typebox";
 import type { AgentTool } from "../internal/harness-types.js";
 import { type ReservedApprovalCard, type ToolApprovalCard, type ToolFamily, type ToolRosterPathTarget, type ToolMountTag, type ToolPathTarget, type ToolRenderHints, type ToolRuleFace } from "./tool-face.js";
 import type { ToolContentOrigin, ToolEffect } from "./tool-spec.js";
+import type { ToolMarkSource } from "./ask-origin.js";
 export declare const ROSTER_SOURCES: readonly ["builtin", "caller", "host", "mcp", "a2a", "external", "synthetic"];
 export type RosterSource = (typeof ROSTER_SOURCES)[number];
 export declare const ToolRosterRenderHints: Type.TObject<{
@@ -50,6 +51,9 @@ export declare const ToolRosterEntry: Type.TObject<{
     contentOrigin: Type.TUnion<[Type.TLiteral<"local">, Type.TLiteral<"execution">, Type.TLiteral<"external">]>;
     contentOriginProvenance: Type.TUnion<[Type.TLiteral<"declared">, Type.TLiteral<"server">, Type.TLiteral<"exempted">, Type.TLiteral<"default">]>;
     family: Type.TUnion<[Type.TLiteral<"shell">, Type.TLiteral<"file-read">, Type.TLiteral<"file-write">, Type.TLiteral<"search">, Type.TLiteral<"web">, Type.TLiteral<"delegate">, Type.TLiteral<"plan">, Type.TLiteral<"scaffold">, Type.TLiteral<"memory">, Type.TLiteral<"protocol">, Type.TLiteral<"other">]>;
+    /** The legs a call of this tool travels (`BOUNDARY_LEGS`), or `"per_call"` when its dispatch gives them per call: the engine's own
+     *  definitions and the protocol tools state them, every other row follows its `effect` (`rosterBoundaryLegs`). */
+    boundaryLegs: Type.TUnion<[Type.TLiteral<"per_call">, Type.TArray<Type.TUnion<[Type.TLiteral<"env">, Type.TLiteral<"outside_read">, Type.TLiteral<"outside_write">]>>]>;
     pathTarget: Type.TOptional<Type.TObject<{
         param: Type.TString;
         aliases: Type.TArray<Type.TString>;
@@ -124,6 +128,9 @@ export declare const ToolRoster: Type.TObject<{
         contentOrigin: Type.TUnion<[Type.TLiteral<"local">, Type.TLiteral<"execution">, Type.TLiteral<"external">]>;
         contentOriginProvenance: Type.TUnion<[Type.TLiteral<"declared">, Type.TLiteral<"server">, Type.TLiteral<"exempted">, Type.TLiteral<"default">]>;
         family: Type.TUnion<[Type.TLiteral<"shell">, Type.TLiteral<"file-read">, Type.TLiteral<"file-write">, Type.TLiteral<"search">, Type.TLiteral<"web">, Type.TLiteral<"delegate">, Type.TLiteral<"plan">, Type.TLiteral<"scaffold">, Type.TLiteral<"memory">, Type.TLiteral<"protocol">, Type.TLiteral<"other">]>;
+        /** The legs a call of this tool travels (`BOUNDARY_LEGS`), or `"per_call"` when its dispatch gives them per call: the engine's own
+         *  definitions and the protocol tools state them, every other row follows its `effect` (`rosterBoundaryLegs`). */
+        boundaryLegs: Type.TUnion<[Type.TLiteral<"per_call">, Type.TArray<Type.TUnion<[Type.TLiteral<"env">, Type.TLiteral<"outside_read">, Type.TLiteral<"outside_write">]>>]>;
         pathTarget: Type.TOptional<Type.TObject<{
             param: Type.TString;
             aliases: Type.TArray<Type.TString>;
@@ -206,6 +213,9 @@ export declare const ToolRosterDelta: Type.TObject<{
             contentOrigin: Type.TUnion<[Type.TLiteral<"local">, Type.TLiteral<"execution">, Type.TLiteral<"external">]>;
             contentOriginProvenance: Type.TUnion<[Type.TLiteral<"declared">, Type.TLiteral<"server">, Type.TLiteral<"exempted">, Type.TLiteral<"default">]>;
             family: Type.TUnion<[Type.TLiteral<"shell">, Type.TLiteral<"file-read">, Type.TLiteral<"file-write">, Type.TLiteral<"search">, Type.TLiteral<"web">, Type.TLiteral<"delegate">, Type.TLiteral<"plan">, Type.TLiteral<"scaffold">, Type.TLiteral<"memory">, Type.TLiteral<"protocol">, Type.TLiteral<"other">]>;
+            /** The legs a call of this tool travels (`BOUNDARY_LEGS`), or `"per_call"` when its dispatch gives them per call: the engine's own
+             *  definitions and the protocol tools state them, every other row follows its `effect` (`rosterBoundaryLegs`). */
+            boundaryLegs: Type.TUnion<[Type.TLiteral<"per_call">, Type.TArray<Type.TUnion<[Type.TLiteral<"env">, Type.TLiteral<"outside_read">, Type.TLiteral<"outside_write">]>>]>;
             pathTarget: Type.TOptional<Type.TObject<{
                 param: Type.TString;
                 aliases: Type.TArray<Type.TString>;
@@ -281,15 +291,10 @@ export declare function approvalCardMemberOf(call: {
  *  other aliases — the ONE order of a call's names: a reader that must pick one of them by position (a `member` seat)
  *  picks the spelling first, as the same call was judged before name resolution. */
 export declare function toolCallFaceOf(roster: ToolRoster | undefined, toolName: string): import("./tool-policy.js").ToolCallFace | undefined;
-/** design/388 B18 — the identity members a park row carries, read off a roster snapshot by name; an empty object when
- *  the name is not on the snapshot (the row then reads pre-identity and the resume takes the name-only path). */
-export declare function parkedToolIdentity(roster: ToolRoster | undefined, toolName: string): {
-    capabilityId?: string;
-    contractId?: string;
-    shapeDigest?: string;
-    implementationRevision?: string;
-    rosterDigest?: string;
-};
+/** design/388 B18 — the identity members a park row carries (the tool member of its approval object,
+ *  `approval-object.ts`), read off a roster snapshot by name; an empty object when the name is not on the snapshot
+ *  (the row then reads pre-identity and the resume binds the name alone). */
+export declare function parkedToolIdentity(roster: ToolRoster | undefined, toolName: string): Partial<ToolIdentity>;
 /** design/388 B6 × B18 — the FACE members a park row carries beside its identity: the display family, the declared
  *  path target and the names the parked call was judged under. `names` is copied from the face the gate stamped on the
  *  request (the model's spelling first — the row carries the judged fact, it is not re-derived); a request with no face
@@ -375,7 +380,7 @@ export type RosterBoundCode = "config.tool_name_too_long" | "config.tool_contrac
  * undefined when every member fits. Read by the declaration door (a `TaskSpec.tools` entry, refused before session
  * acquire) and by the row mint (every source — an MCP/A2A peer, a definition that reached the mint by a route the
  * door does not cover — refused before the row exists). A member over its bound is NEVER truncated onto the row: a
- * truncated identity is a different identity (`judgeParkedToolIdentity` compares it across a park; the card
+ * truncated identity is a different identity (`judgeApprovalObject` compares it across a park; the card
  * namespace door reads it), and the schema's own bounds would then describe a row the mint never made.
  */
 export declare function rosterMemberBoundProblem(m: RosterBoundMembers): {
@@ -427,6 +432,7 @@ export interface MountedToolFace {
     compactable?: true;
     budgetExempt?: true;
     modelGate?: string;
+    boundaryLegs?: unknown;
 }
 export declare const faceOf: (t: AgentTool) => MountedToolFace;
 /** The leg facts the snapshot reads beside the instances — the safety scan's folds and the per-task knobs. */
@@ -441,20 +447,32 @@ export interface RosterSnapshotFacts {
     /** `TaskSpec.memory.trustedTools` — the exemption channel for an undeclared content class. */
     trustedTools: ReadonlySet<string>;
 }
+/** The leg's per-name safety-axis tables the builder keeps aligned with its mounts beside the effect map (the safety scan mints
+ *  them; the protocol folds and the shell seat also write them). */
+export interface RosterAxisTables {
+    irreversibilityTier: Map<string, "never" | "maybe" | "always">;
+    irreversibleTools: Set<string>;
+    reversibilityProbes: Map<string, unknown>;
+    egressTools: Set<string>;
+    toolMarkSources: Map<string, Set<ToolMarkSource>>;
+}
 export declare class RosterBuilder {
     #private;
-    constructor(effects: Map<string, ToolEffect>);
+    /** `axes` — the leg's safety-axis tables beside the effect map (a builder for a single probe tool may go without). */
+    constructor(effects: Map<string, ToolEffect>, axes?: RosterAxisTables);
     /** The mount array as a READ face. The order is the wire order. */
     get tools(): readonly AgentTool[];
     get length(): number;
     metaOf(tool: AgentTool): RosterMountMeta | undefined;
     /** Mount one instance at the tail. An engine-lane instance that DECLARES an effect writes it into the leg's effect
      *  map — the later mount under a name is the one the harness dispatches to (`snapshot`'s yield rule), so its
-     *  declaration is the map's truth for that name; a pre-mount registration (the hand band, the plan pair, an
-     *  MCP axis) stands only for names no mounted instance declares. The `scenario` lane never writes the map: its
+     *  declaration is the map's truth for that name — an engine tool's effect reaches the map from its own declaration, here at its
+     *  mount (nothing writes it by name beforehand; a protocol axis fills a name no mounted instance declares, and the gate's
+     *  post-assembly sync a kept instance the map still lacks). The `scenario` lane never writes the map: its
      *  declarations were latched by the safety scan BEFORE any mount (on the kept instance of each name, on the
      *  synchronous doors+scan stretch — a microtask cannot flip them), so a scenario mount, kept or dropped, leaves
-     *  the map as the scan made it; an engine lane's mount under that name still displaces it. */
+     *  the map as the scan made it; an engine lane's mount under that name still displaces it, and the aliases the displaced
+     *  instance answered to move to the member they now resolve to (`#resettleAliases`). */
     mount(tool: AgentTool, meta: RosterMountMeta): void;
     /** An ENGINE-INJECTED instance the harness list carries outside the mount array (the ToolSearch lane): a roster
      *  row — the model can call it — never a mount-array element (the disclosure lane owns that list and appends the
@@ -497,6 +515,20 @@ export declare function rosterCardId(source: RosterSource, toolName: string, pee
 /** The card namespace a `TaskSpec.tools` entry will own once mounted — the same mint the row makes, so the prepare
  *  door and the roster row cannot disagree about which namespace a caller card must live under. */
 export declare function callerCardIdOf(tool: Pick<AgentTool, "name" | "parameters">): string;
+/** The protocol segment of a mounted protocol tool's name (`mcp__srv__write_file` ⇒ `write_file`): the name itself when no protocol owns it.
+ *  ONE reading, asked by the row's mint below and by the judge that holds an MCP face's cards to the namespace that row will own. */
+export declare function protocolToolOf(toolName: string): string;
+/** The refusal of a `boundaryLegs` declaration that is not one — the ONE sentence the roster's declaration door and the row mint both
+ *  throw (`config.tool_face_invalid`, the code a caller tool's bad face has). */
+export declare function boundaryLegsRefusal(toolName: unknown): Error & {
+    code: string;
+};
+/** The judge of a caller roster's `boundaryLegs` where the roster enters, every entry the caller handed, mounted or not: the config-door
+ *  phase over the snapshot's faces and a resume's screen before its claim over the entries it is handed (one function, so the row stays
+ *  pending). A declaration that is not one is refused. Not judged here — the snapshot reads it, and only by running the caller's code:
+ *  an entry or a list of another prototype (its prototype chain answers), a Proxy, an accessor (or a non-enumerable member the receipt
+ *  does not take) as the name, the declaration or a slot of the list. The row mint judges every other source. */
+export declare function assertToolBoundaryLegs(tools: unknown): void;
 /** One row (design/388 §2.5). Every axis is read off the instance or the leg facts; nothing off a name table. */
 export declare function mintRosterEntry(tool: AgentTool, meta: RosterMountMeta, facts: RosterSnapshotFacts): ToolRosterEntry;
 /**
@@ -533,20 +565,6 @@ export declare function ruleFacesFromRoster(roster: ToolRoster): (toolName: stri
 } | undefined;
 /** The delta between two snapshots (design/388 §2.5): the whole `next` roster plus the name summary. */
 export declare function diffToolRoster(prev: ToolRoster, next: ToolRoster): ToolRosterDelta;
-/**
- * The resume-side identity judgement (design/388 §2.5 boundary ②, B18/B19): a parked action carrying the
- * four identity members is redeemed only against a same-name row whose four members ALL match; a row
- * whose contract / shape / revision / source-peer moved is a replacement wearing the name, and the
- * resume refuses it (`resume.tool_contract_mismatch`, same family and disposition as
- * `resume.tool_unavailable`). A parked action minted BEFORE the identity members existed (all four absent)
- * follows the name-only path and is never widened by their absence.
- */
-export declare function judgeParkedToolIdentity(pending: {
-    capabilityId?: string;
-    contractId?: string;
-    shapeDigest?: string;
-    implementationRevision?: string;
-}, row: ToolRosterEntry | undefined): "match" | "mismatch" | "name_only" | "absent";
 /** The card-namespace check a CALLER declaration must pass at prepare (design/388 §2.2 ④): a `resultCards`
  *  entry must live under the tool's own `cardId`; naming an engine card (`builtin:*`, or a bare engine card
  *  type) is refused. Returns the offending entry, or undefined. */

package/dist/core/tool-roster.js

@@ -1,5 +1,7 @@
 import { createHash } from "node:crypto";
+import { types } from "node:util";
 import { Type } from "typebox";
+import { findToolByName } from "../internal/llm.js";
 import { getToolContract } from "../prompt-assembly/tool-catalog.js";
 import { protocolOf } from "./protocol-table.js";
 import { describeToolCatalog } from "./tool-registry.js";
@@ -7,6 +9,8 @@ import { RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_CHARS, RENDER_HINT_MAX_
 import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
 import { PRESENT_PLAN_TOOL_NAME } from "./present-plan-tool.js";
 import { wireOf } from "./tool-name-readings.js";
+import { BOUNDARY_LEGS, rosterBoundaryLegs } from "./cross-boundary-taint.js";
+import { isPlainRecord, receive } from "./mods/kernel/receive.js";
 function lit(values) {
     return Type.Union(values.map((v) => Type.Literal(v)));
 }
@@ -46,6 +50,7 @@ export const ToolRosterEntry = Type.Object({
     contentOrigin: lit(["local", "execution", "external"]),
     contentOriginProvenance: lit(["declared", "server", "exempted", "default"]),
     family: lit(TOOL_FAMILIES),
+    boundaryLegs: Type.Union([Type.Literal("per_call"), Type.Array(lit(BOUNDARY_LEGS), { uniqueItems: true })]),
     pathTarget: Type.Optional(Type.Object({
         param: Key,
         aliases: Type.Array(Key),
@@ -122,9 +127,7 @@ export function parkedToolIdentity(roster, toolName) {
     if (roster === undefined)
         return {};
     const e = rosterEntryNamed(roster, toolName);
-    if (e === undefined)
-        return {};
-    return { capabilityId: e.capabilityId, contractId: e.contract.contractId, shapeDigest: e.shapeDigest, implementationRevision: e.contract.implementationRevision, rosterDigest: roster.digest };
+    return e === undefined ? {} : toolIdentityOf(e);
 }
 export function parkedToolFace(roster, req) {
     if (roster === undefined)
@@ -301,6 +304,18 @@ export function survivorsByName(mounted) {
     return winner;
 }
 export const faceOf = (t) => t;
+const setOrClear = (m, key, value) => {
+    if (value === undefined)
+        m.delete(key);
+    else
+        m.set(key, value);
+};
+const memberIf = (s, key, member) => {
+    if (member)
+        s.add(key);
+    else
+        s.delete(key);
+};
 function configError(code, message) {
     const e = new Error(message);
     e.code = code;
@@ -311,8 +326,10 @@ export class RosterBuilder {
     #engineLane = [];
     #meta = new WeakMap();
     #effects;
-    constructor(effects) {
+    #axes;
+    constructor(effects, axes) {
         this.#effects = effects;
+        this.#axes = axes;
     }
     get tools() {
         return this.#tools;
@@ -324,12 +341,18 @@ export class RosterBuilder {
         return this.#meta.get(tool);
     }
     mount(tool, meta) {
+        const displaced = this.#survivorNamed(tool.name);
         this.#admit(tool, meta);
         this.#tools.push(tool);
+        if (meta.mountedBy !== "scenario")
+            this.#resettleAliases([...(displaced?.aliases ?? []), ...(tool.aliases ?? [])]);
     }
     mountEngineLane(tool, meta) {
+        const displaced = this.#survivorNamed(tool.name);
         this.#admit(tool, meta);
         this.#engineLane.push(tool);
+        if (meta.mountedBy !== "scenario")
+            this.#resettleAliases([...(displaced?.aliases ?? []), ...(tool.aliases ?? [])]);
     }
     #admit(tool, meta) {
         if ((meta.source === "mcp" || meta.source === "a2a" || meta.source === "external") !== (meta.origin !== undefined)) {
@@ -342,6 +365,32 @@ export class RosterBuilder {
         if (eff !== undefined && meta.mountedBy !== "scenario")
             this.#effects.set(tool.name, eff);
     }
+    #survivorNamed(name) {
+        return survivorsByName([...this.#tools, ...this.#engineLane]).get(name);
+    }
+    #resettleAliases(aliases) {
+        if (aliases.length === 0)
+            return;
+        const live = [...survivorsByName([...this.#tools, ...this.#engineLane]).values()];
+        for (const a of new Set(aliases)) {
+            const owner = findToolByName(live, a);
+            if (owner?.name === a)
+                continue;
+            this.#repoint(a, owner?.name);
+        }
+    }
+    #repoint(key, from) {
+        const pick = (m) => (from === undefined ? undefined : m.get(from));
+        const marks = this.#axes === undefined ? undefined : pick(this.#axes.toolMarkSources);
+        setOrClear(this.#effects, key, pick(this.#effects));
+        if (this.#axes === undefined)
+            return;
+        setOrClear(this.#axes.irreversibilityTier, key, pick(this.#axes.irreversibilityTier));
+        setOrClear(this.#axes.reversibilityProbes, key, pick(this.#axes.reversibilityProbes));
+        setOrClear(this.#axes.toolMarkSources, key, marks === undefined ? undefined : new Set(marks));
+        memberIf(this.#axes.irreversibleTools, key, from !== undefined && this.#axes.irreversibleTools.has(from));
+        memberIf(this.#axes.egressTools, key, from !== undefined && this.#axes.egressTools.has(from));
+    }
     mountAll(tools, meta) {
         for (const t of tools)
             this.mount(t, meta);
@@ -355,6 +404,10 @@ export class RosterBuilder {
                 removed.unshift(t);
             }
         }
+        for (const t of removed)
+            if (this.#survivorNamed(t.name) === undefined)
+                this.#effects.delete(t.name);
+        this.#resettleAliases(removed.flatMap((t) => t.aliases ?? []));
         return removed;
     }
     replaceAt(index, tool) {
@@ -449,18 +502,50 @@ export function callerCardIdOf(tool) {
     const t = tool;
     return rosterCardId(callerMountSource(t), t.name, null, t.name, getToolContract(t, "caller").contractId);
 }
+export function protocolToolOf(toolName) {
+    return protocolOf(toolName)?.parse(toolName)?.tool ?? toolName;
+}
+export function boundaryLegsRefusal(toolName) {
+    const named = typeof toolName === "string" ? JSON.stringify(toolName.slice(0, 128)) : `(a ${typeof toolName} name)`;
+    return configError("config.tool_face_invalid", `tool ${named}: its boundaryLegs declaration is neither "per_call" nor a list of ${BOUNDARY_LEGS.join(" | ")}`);
+}
+const ROSTER_LEGS_RECEIPT = Object.freeze({ accessors: "refuse", depth: 3, others: "as-is", contain: true, isProxy: (v) => types.isProxy(v) });
+const SLOT = /^(?:0|[1-9]\d*)$/;
+export function assertToolBoundaryLegs(tools) {
+    const got = receive(tools, ROSTER_LEGS_RECEIPT);
+    if (!got.ok || !Array.isArray(got.value))
+        return;
+    const unread = new Set();
+    for (const f of got.faults ?? []) {
+        const [at, member, slot] = f.path;
+        if (at !== undefined && (member === "name" || (member === "boundaryLegs" && slot !== undefined && SLOT.test(slot))))
+            unread.add(at);
+    }
+    got.value.forEach((t, i) => {
+        if (!isPlainRecord(t) || unread.has(String(i)))
+            return;
+        const legs = t["boundaryLegs"];
+        if (Array.isArray(legs) && Object.getPrototypeOf(legs) !== Array.prototype)
+            return;
+        if (rosterBoundaryLegs("caller", legs, "write") === undefined)
+            throw boundaryLegsRefusal(t["name"]);
+    });
+}
 export function mintRosterEntry(tool, meta, facts) {
     const face = faceOf(tool);
     const fallbackOrigin = meta.source === "builtin" ? "core" : meta.source === "synthetic" ? "synthetic" : meta.source === "mcp" || meta.source === "a2a" ? meta.source : "caller";
     const d = getToolContract(tool, fallbackOrigin);
     const peer = meta.origin?.peer ?? null;
-    const protocolTool = peer !== null ? protocolOf(tool.name)?.parse(tool.name)?.tool ?? tool.name : tool.name;
+    const protocolTool = peer !== null ? protocolToolOf(tool.name) : tool.name;
     const cardId = rosterCardId(meta.source, tool.name, peer, protocolTool, d.contractId);
     const { keys: inputKeys } = inputKeysOf(tool.parameters);
     const declaredEffect = face.effect;
     const foldedEffect = facts.effects.get(tool.name);
     const effect = declaredEffect ?? foldedEffect ?? "write";
     const effectProvenance = declaredEffect !== undefined ? (meta.source === "synthetic" ? "synthetic" : "declared") : foldedEffect !== undefined && (meta.source === "mcp" || meta.source === "a2a") ? "caller" : "default";
+    const boundaryLegs = rosterBoundaryLegs(meta.source, face.boundaryLegs, effect);
+    if (boundaryLegs === undefined)
+        throw boundaryLegsRefusal(tool.name);
     const egress = face.egress === true || facts.egress.has(tool.name);
     const egressProvenance = face.egress === true ? "declared" : egress ? "caller" : "default";
     const irreversibility = face.irreversibility ?? facts.irreversibilityTier.get(tool.name);
@@ -505,6 +590,7 @@ export function mintRosterEntry(tool, meta, facts) {
         contentOrigin,
         contentOriginProvenance,
         family: face.family !== undefined && TOOL_FAMILIES.includes(face.family) ? face.family : "other",
+        boundaryLegs: boundaryLegs === "per_call" ? boundaryLegs : [...boundaryLegs],
         ...(pathTarget !== undefined
             ? {
                 pathTarget: {
@@ -608,15 +694,6 @@ export function diffToolRoster(prev, next) {
             removed.push(name);
     return { fromDigest: prev.digest, roster: next, summary: { added, removed, changed } };
 }
-export function judgeParkedToolIdentity(pending, row) {
-    const carried = pending.capabilityId !== undefined || pending.contractId !== undefined || pending.shapeDigest !== undefined || pending.implementationRevision !== undefined;
-    if (row === undefined)
-        return "absent";
-    if (!carried)
-        return "name_only";
-    const id = toolIdentityOf(row);
-    return pending.capabilityId === id.capabilityId && pending.contractId === id.contractId && pending.shapeDigest === id.shapeDigest && pending.implementationRevision === id.implementationRevision ? "match" : "mismatch";
-}
 export function offendingResultCard(hints, cardId, engineCards) {
     for (const c of hints?.resultCards ?? []) {
         if (typeof c !== "string")

package/dist/core/tool-spec-members.js

@@ -5,9 +5,9 @@ export const TOOL_SPEC_MEMBERS = Object.keys({
     contentOrigin: true, offload: true, offloadThresholdChars: true, defer: true, alwaysLoad: true, prepareArguments: true,
     validateInput: true, approvalPreview: true, family: true, pathTarget: true, ruleFace: true, renderHints: true, compactable: true,
     budgetExempt: true, modelGate: true, contract: true, agentListing: true, agentModels: true, agentToolFaces: true,
-    agentToolLevelAllowTools: true, agentToolLevelDenyTools: true, agentToolPool: true, agentToolInheritsMcp: true, withAgents: true,
+    agentToolLevelAllowTools: true, agentToolLevelDenyTools: true, agentToolPool: true, agentToolInheritsMcp: true, withAgents: true, boundaryLegs: true, boundaryLegsFor: true,
 });
-const FUNCTION_MEMBERS = new Set(["execute", "prepareArguments", "validateInput", "approvalPreview", "reversibilityProbe", "isConcurrencySafe", "withAgents"]);
+const FUNCTION_MEMBERS = new Set(["execute", "prepareArguments", "validateInput", "approvalPreview", "reversibilityProbe", "isConcurrencySafe", "withAgents", "boundaryLegsFor"]);
 const NAME_LIST_MEMBERS = new Set(["aliases", "agentModels", "agentToolLevelAllowTools", "agentToolLevelDenyTools"]);
 const FACE_LIST_KEYS = new Set(["allowTools", "denyTools"]);
 const FACE_PLACES = { elementKeys: FACE_LIST_KEYS };

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

@@ -306,10 +306,10 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
     egress?: true;
     /**
      * The tool's PERMISSION SEAT. `"passthrough"`: the tool states no permission of its own — under an asking permission mode
-     * (`default` / `acceptEdits` / `plan` / `auto` / `dontAsk`) a call to it runs only when some layer STATES an allow (an allow
-     * rule or allow-list entry naming it, an approver's yes, a PreToolUse hook's own `allow`); a policy fold in which nobody
-     * stated it ("no objection") gets the mode's question (class `unstated`, origin `policy`), which dontAsk refuses, auto's
-     * classifier may answer, and `bypassPermissions` never raises. The MCP and A2A materializers set it on a remote peer's
+     * (`default` / `acceptEdits` / `plan` / `auto` / `dontAsk`) a policy fold's allow is "no objection" and gets the mode's
+     * question (class `unstated`, origin `policy`) unless an approver's yes was given for the bytes that run; the allow layer
+     * answers it (an allow entry in `RunnerDeps.allowedTools` / `TaskSpec.allowedTools`, a stored row, a skill's list, a PreToolUse
+     * hook's own `allow`), dontAsk refuses it, auto's classifier may answer it, and `bypassPermissions` never raises it. The MCP and A2A materializers set it on a remote peer's
      * tool. Absent: the tool answers for itself (the engine's own stations and the deployment's declarations). Tightening only —
      * it can make a tool ask, never let one run.
      */
@@ -524,6 +524,18 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * missing declaration rather than defaulting it).
      */
     family?: ToolFamily;
+    /**
+     * The legs a call of this tool travels across the device boundary — the engine's own definitions declare it on their catalog face
+     * ({@link import("./tool-face.js").ToolFaceDeclaration.boundaryLegs}, required there), and this member carries it onto the mounted
+     * instance. Read only on a roster row of source `builtin` / `synthetic` (a `TaskSpec.tools` entry is one only when it carries a core
+     * contract); any other tool's row states legs from its `effect`. A value that is neither `"per_call"` nor a list of legs is refused
+     * (`config.tool_face_invalid`): for a `TaskSpec.tools` entry where the roster enters, whether or not the entry mounts.
+     */
+    boundaryLegs?: import("./cross-boundary-taint.js").BoundaryLegsDeclaration;
+    /** The per-call half of a `"per_call"` {@link boundaryLegs} declaration, written beside the code that dispatches the call: the legs one
+     *  call travels, given its arguments as the tool reads them ({@link import("./cross-boundary-taint.js").BoundaryLegsFor}). Read only for
+     *  a row that declares `"per_call"`; such a row with no resolver, or a resolver that throws, reads as every leg off-target. */
+    boundaryLegsFor?: import("./cross-boundary-taint.js").BoundaryLegsFor;
     /**
      * design/388 §2.2 ② — the parameter that names this tool's filesystem TARGET and how it is touched.
      * Present ⇔ the tool can be confirmed BY PATH: write confinement (`allowDirs`, the fs-write gate,
@@ -1156,6 +1168,10 @@ export interface ToolExecuteContext {
      * tool runs outside a Runner task.
      */
     inheritedGateForChildren?: () => import("./runner/contracts.js").InheritedGate;
+    /** The run tree's cross-boundary token ({@link import("./runner/contracts.js").RunInternals.crossBoundaryTree}) — Runner-filled, opaque
+     *  and frozen; a delegation or workflow tool hands this SAME token into its child's trusted internals (and records it on a background
+     *  handle), so the child joins the tree and a bit any leg sets is read by every other. No tool reads or writes the state through it. */
+    crossBoundaryTreeForChildren?: import("./cross-boundary-taint.js").CrossBoundaryTreeToken;
     /**
      * design/180 half A — the delegation runtime-provenance ARMING face. Runner-filled; a delegation
      * tool calls it at spawn time: a non-undefined return means this (parent) run is armed (it mounts

package/dist/core/tools.js

@@ -95,6 +95,8 @@ function buildProduct(spec, owner, options) {
         ...(spec.alwaysLoad !== undefined ? { alwaysLoad: spec.alwaysLoad } : {}),
         ...(spec.prepareArguments ? { prepareArguments: spec.prepareArguments } : {}),
         ...(spec.family !== undefined ? { family: spec.family } : {}),
+        ...(spec.boundaryLegs !== undefined ? { boundaryLegs: spec.boundaryLegs } : {}),
+        ...(spec.boundaryLegsFor !== undefined ? { boundaryLegsFor: spec.boundaryLegsFor } : {}),
         ...(spec.pathTarget !== undefined ? { pathTarget: spec.pathTarget } : {}),
         ...(spec.ruleFace !== undefined ? { ruleFace: spec.ruleFace } : {}),
         ...(spec.renderHints !== undefined ? { renderHints: spec.renderHints } : {}),

package/dist/core/trace.d.ts

@@ -332,8 +332,11 @@ export type TraceEvent = {
      * `tool.call.turn`. Lets a bridge put a `chat` span and the `execute_tool` spans of the tools that
      * call requested under one parent without re-deriving turn boundaries from event order.
      *
-     * ABSENT on the compaction summarizer's own call: that call fires from the turn-boundary hook and
-     * is not a loop turn, so any number here would be a different measurement wearing the same name.
+     * ABSENT on every provider call fired beside the loop — the compaction summarizer (it fires from the turn-boundary hook), the
+     * classifier gate, a mod's own call: none is a loop turn, so any number here would be a different measurement wearing the same
+     * name. So `turn` present ⇔ the call is the main loop's own; absent ⇔ a call outside the loop. Those rows also carry
+     * `latencyMs: 0` (no wall time is measured for them), so a latency average taken over the rows that carry a `turn` is not diluted
+     * by them.
      */
     turn?: number;
     /** Normalized prompt tokens that MISSED the cache (Anthropic-protocol `input_tokens`
@@ -555,6 +558,25 @@ export type TraceEvent = {
      *  joined — provider failure, refused snapshot, rollback refusal, missing durable persistence. */
     message: string;
     ts: number;
+} | {
+    /**
+     * The device lane's cross-boundary TAINT on a tree that executes on a target device: once when a leg is prepared on an armed
+     * tree (`phase: "prepare"`; `"resume"` on a durable resume's leg), and once when this leg first lets an off-target read into the
+     * tree (`"observed"`, with the call). A tree that never armed emits none. Metadata only.
+     */
+    kind: "permission.cross_boundary_taint";
+    version: 1;
+    taskId: string;
+    runId: string;
+    phase: "prepare" | "resume" | "observed";
+    /** The tree's taint bits after the event. */
+    taint: readonly import("./cross-boundary-taint.js").CrossBoundaryTaintBit[];
+    /** The tree has run under the `multi_tenant` posture since it armed. */
+    governed: boolean;
+    /** The call that let the off-target read in (`observed` only). */
+    toolName?: string;
+    toolCallId?: string;
+    ts: number;
 } | {
     /**
      * F-012 L2 — a pending ask was AUTO-ADMITTED by the sandbox-admission leg: the deployment's

package/dist/core/types.d.ts

@@ -19,7 +19,7 @@ export type { ToolEffect, ToolContentOrigin, ReversibilityVerdict, ReadRootGrant
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook, FileEditedNotice, FileEditedHook, HandsBandOptions } from "./hands-band.js";
 export type { AgentDefinition, SkillSpec } from "./agent-definition.js";
 export type { McpServerSpec, A2aServerSpec, McpElicitRequest, McpElicitResponse, OnElicit, McpRevocationLedger, McpMountIdentity, DeclarationFault, DeclarationPathRule, DeclarationRead, ToolAxesRead, ToolAxesSurface } from "./mcp-server-spec.js";
-export { DECLARATION_PATH_RULES, declarationFaultOf, declarerWord, readMcpToolAxes, readToolAxes, receiveDeclaration, toolAxesRefusal } from "./mcp-server-spec.js";
+export { DECLARATION_PATH_RULES, NO_DECLARATION_PATH_RULES, dataKind, declarationFaultOf, declarerWord, perToolEmptyName, perToolEntryRefusal, quotedName, readMcpToolAxes, readToolAxes, receiveDeclaration, receivePerToolDeclaration, toolAxesRefusal } from "./mcp-server-spec.js";
 export type { TaskLimits } from "./task-limits.js";
 export type { TaskStatus, RemoteEnvFailureNote, EffectiveMemoryScopes, TaskResult, HumanReviewGateRow } from "./task-result.js";
 export type { TerminalCause, PausedCause } from "./terminal-cause.js";
@@ -30,6 +30,6 @@ export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js"
 export type { BackgroundChildEvent, BackgroundChildRow, DelegationLifecycleEvent } from "./delegation-frames.js";
 export { __resetMalformedDelegationSeatAnnouncement, backgroundChildTerminal, deliverDelegationLifecycle, emitsChildRowFrames, taskStartedFrame } from "./delegation-frames.js";
 export type { ProjectMemoryLoad, ResumePreflightInfo, ResumePreflightVerdict, RunnerDeps } from "./runner-deps.js";
-export type { EngineNotice, OwedUserInputAccount, UserInputUndrainedCause } from "./engine-notice.js";
+export type { ApprovalCarryRefusal, EngineNotice, OwedUserInputAccount, UserInputUndrainedCause } from "./engine-notice.js";
 export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, parentLegIds, settleOwedUserInput, undrainedUserInputNotices, USER_INPUT_UNDRAINED_CAUSES, USER_INPUT_UNDRAINED_FAMILIES } from "./engine-notice.js";
 export type { AgentTool, Model, StreamFn, ThinkingLevel, ToolInputValidationContext, ToolInputVerdict };

package/dist/core/types.js

@@ -1,5 +1,5 @@
 export { MODEL_ROLES } from "./model-seat.js";
-export { DECLARATION_PATH_RULES, declarationFaultOf, declarerWord, readMcpToolAxes, readToolAxes, receiveDeclaration, toolAxesRefusal } from "./mcp-server-spec.js";
+export { DECLARATION_PATH_RULES, NO_DECLARATION_PATH_RULES, dataKind, declarationFaultOf, declarerWord, perToolEmptyName, perToolEntryRefusal, quotedName, readMcpToolAxes, readToolAxes, receiveDeclaration, receivePerToolDeclaration, toolAxesRefusal } from "./mcp-server-spec.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";
 export { __resetMalformedDelegationSeatAnnouncement, backgroundChildTerminal, deliverDelegationLifecycle, emitsChildRowFrames, taskStartedFrame } from "./delegation-frames.js";
 export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, parentLegIds, settleOwedUserInput, undrainedUserInputNotices, USER_INPUT_UNDRAINED_CAUSES, USER_INPUT_UNDRAINED_FAMILIES } from "./engine-notice.js";

package/dist/core/untrusted-text.d.ts

@@ -238,6 +238,13 @@ export declare function defuseExactMarkInSegments(segments: readonly string[], m
  * {@link FENCED_LANE_ENVELOPE_TAGS}) and at each envelope's own mint site (the registry's guard column).
  */
 export declare function sanitizeUntrustedText(text: string, extraTags?: string[]): string;
+/**
+ * THE sentence every arm speaks when it refuses a person's text because {@link sanitizeUntrustedText} would change it — the engine's own
+ * sentinel tag, opening (with or without attributes) or closing, which the judge refuses alike. `subject` names what carried it. Produced
+ * once, here beside the judge, so the sentence and the rule cannot drift apart by arm (the decide's deny / reject `reason`, a plan's
+ * `editedPlan`, an allow's `feedback`, a trusted live steer).
+ */
+export declare function sentinelTagRefusal(subject: string): string;
 /**
  * [c209-C] 收口 C1/C2 (metadata-driven, replaces the shape-anchored
  * `stripLeadingSystemReminders`) — cut the engine-prepended prefix off a user-lane message using the

package/dist/core/untrusted-text.js

@@ -66,14 +66,6 @@ export const ENGINE_ENVELOPES = Object.freeze([
         fenced: true,
         disclosed: true,
     },
-    {
-        tag: "working-file",
-        kind: "framing",
-        mint: "core/auto-compaction.ts (post-compaction working-file snapshot)",
-        guard: "sanitizeUntrustedText(WORKING_FILE_BREAKOUT_TAGS) + escapeWorkingFilePathAttr",
-        fenced: false,
-        disclosed: false,
-    },
     {
         tag: "summary",
         kind: "framing",
@@ -482,6 +474,9 @@ export function defuseExactMarkInSegments(segments, mark) {
 export function sanitizeUntrustedText(text, extraTags = []) {
     return text.replace(breakoutRe(extraTags), (m) => ESCAPED_LT + m.slice(1));
 }
+export function sentinelTagRefusal(subject) {
+    return `${subject} must not contain a <system-reminder> tag (opening or closing)`;
+}
 export function cutEnginePrefix(text, enginePrefixChars) {
     if (typeof enginePrefixChars === "number" &&
         Number.isInteger(enginePrefixChars) &&

package/dist/core/user-attachment.d.ts

@@ -27,6 +27,8 @@ import type { HumanInputAttachment } from "./task-event.js";
 import { type ModelFileReader } from "../tools/fs/fs-read.js";
 import type { SyntheticReadJudge } from "./synthetic-read-verdict.js";
 import { type ReminderDisclosureCounts } from "./reminder-disclosure.js";
+import { type AgentMessage } from "../internal/harness.js";
+import type { ReadEntry } from "../tools/fs/safety.js";
 import type { ContextWindowOverlay } from "./context-settings.js";
 /** At most this many attachments on one objective. */
 export declare const USER_ATTACHMENTS_MAX = 20;
@@ -116,6 +118,13 @@ export declare function userAttachmentDeclarations(screened: readonly ScreenedUs
  * run on the captured values before any attachment is read or delivered. Throws `config.user_attachment_invalid`.
  */
 export declare function admitUserAttachmentImages(screened: readonly ScreenedUserAttachment[]): Promise<ReadonlyMap<number, ImageContent>>;
+/** The transmission an attachment frame is (the read-state entry its delivery records carries it): when the frame leaves
+ *  the request — a trim drops it — the entry retires with it. One spelling for the mint and every remover. */
+export declare function attachmentTransmissionId(a: Pick<UserMessageAttachment, "inputId" | "ordinal">): string;
+/** The transmissions a request-view drop took out: those of `view`'s messages that no message of `kept` still carries (a
+ *  reused call id kept elsewhere is not gone). The guard trim retires the read-state entries they delivered (so the next
+ *  Read sends the contents again); a later read of the same file is a transmission of its own and stays. */
+export declare function droppedTransmissions(view: ReadonlyArray<AgentMessage>, kept: ReadonlyArray<AgentMessage>): string[];
 /** One minted frame: the trailing message's seed, and the commit its delivery owes (absent ⇒ nothing to commit). */
 export interface MintedAttachmentFrame {
     readonly seed: {
@@ -160,6 +169,40 @@ export declare function readObjectiveAttachments(prepared: Pick<import("./runner
     frames: MintedAttachmentFrame[];
     chars: number;
 }>;
+/** What a compaction's restore reads with: the leg's one file reader (the Read tool's) and the run's synthetic-Read judge,
+ *  and where a file it does not deliver is reported (a restored file's outcome has no wire face of its own). */
+export interface CompactionRestoreSeat {
+    readonly reader: ModelFileReader;
+    readonly judge: SyntheticReadJudge;
+    readonly cwd: () => string | undefined;
+    readonly mark: string | undefined;
+    readonly counts: ReminderDisclosureCounts | undefined;
+    readonly signal: AbortSignal;
+    readonly report: (path: string, reason: string) => void;
+}
+/** One restore: the files to re-read (most recent first) and its bounds. */
+export interface CompactionRestoreRequest {
+    readonly candidates: readonly string[];
+    readonly maxFiles: number;
+    /** What one file may deliver, in its own characters (before the Read's line numbers); an image the estimator's fixed
+     *  weight × `charsPerToken`. A file over it, or whose frame would send more of its contents (line numbers included)
+     *  than what is left of `totalChars`, is named, not sent. */
+    readonly perFileChars: number;
+    readonly totalChars: number;
+    readonly charsPerToken: number;
+    /** The read state of the context the summary leaves (`readFileStateAfterSummary`): what the reads dedup against. */
+    readonly dedupAgainst: ReadonlyMap<string, ReadEntry>;
+}
+/** The synthetic-Read judge's probe face for the restore (probe id `compaction-restore-visibility-probe`). */
+export declare const COMPACTION_RESTORE_PROBE_FACE = "compaction-restore";
+/**
+ * Re-read the files a compaction restores and mint their frames — each a Read on the model's behalf ({@link readRestored}),
+ * deduplicated against the context the summary leaves, so a file the summary takes out of view is never answered
+ * "unchanged"; the frame is the attachment seat's own. A file the context still holds is skipped; a file over
+ * its share is a frame that names it and says it is too large (no part of its contents); a refused file is a frame with
+ * the reason. Side-effect free toward the run: each frame carries the commit its delivery owes.
+ */
+export declare function readCompactionRestore(seat: CompactionRestoreSeat, req: CompactionRestoreRequest): Promise<MintedAttachmentFrame[]>;
 /** The last attachment frame of the group the message `id` opens, or `id` when it has none (a `resumeAt` that keeps the
  *  message keeps its group). The frames of one input are appended one after another under its message (each the child of
  *  the one before), all carrying its input id. */