@sema-agent/core 7.48.0 → 7.49.0

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

@@ -10,7 +10,7 @@
  *
  * Layer-0 vocabulary: depends on the leaf catalog and the face vocabulary only.
  */
-import { type ToolCallPathTarget, type ToolCatalogEntry, type ToolMountTag, type ToolPathAccess } from "./tool-face.js";
+import { type ToolCallPathTarget, type ToolCatalogEntry, type ToolFamily, type ToolMountTag, type ToolPathAccess } from "./tool-face.js";
 /** The whole static catalog, one frozen row per definition (design/388 §2.1 `describeToolCatalog()`).
  *  Replaces the retired name-keyed exports `HAND_TOOL_EFFECTS` / `DEFAULT_BUDGET_EXEMPT_TOOLS` /
  *  `COMPACTABLE_TOOLS`: filter this instead (`e.mountedBy.includes("hands")`, `e.face.budgetExempt`,
@@ -23,6 +23,49 @@ export declare function catalogToolNames(): ReadonlySet<string>;
 /** A-11/12/13/14 — tools this engine can CONFINE BY PATH on a write: `pathTarget.access ≠ read`.
  *  Today {Write, Edit, NotebookEdit}. */
 export declare function pathConfinableWriteToolNames(): ReadonlySet<string>;
+/**
+ * What the persistence judge reads off ONE tool: its name and the three face members (all optional — a mounted
+ * instance carries the ones its definition declared, read straight off the object). A member the tool does not
+ * carry falls to the catalog's declaration for its NAME (a bare caller tool wearing a catalog name, such as a
+ * hands-less host's own `Write`, takes that definition's face — never a wider one).
+ */
+export interface PersistenceProbeTool {
+    readonly name: string;
+    readonly effect?: import("./tool-spec.js").ToolEffect;
+    readonly pathTarget?: {
+        readonly access: ToolPathAccess;
+    };
+    readonly family?: ToolFamily;
+}
+/** The leg facts the judge reads beside the tools. */
+export interface PersistenceFacts {
+    /** Names the leg's frozen tool-face snapshot excludes — an excluded tool is unmounted, so it persists nothing. */
+    readonly exclude?: readonly string[];
+    /** The leg's by-name effect map: the fallback for a tool that declares no `effect` of its own (silent ⇒ `"write"`). */
+    readonly effects?: ReadonlyMap<string, import("./tool-spec.js").ToolEffect>;
+    /** The hand band is mounted on a REMOTE env: its file tools write the sandbox filesystem, not the host-side memory
+     *  root, so their presence proves nothing about persistence there. */
+    readonly remoteHands: boolean;
+}
+/**
+ * The names, among a run's MOUNTED tools (instances, whose face members sit on the object itself), the persistence
+ * judgment passes. The judgment's inputs beyond the tools (the exclude snapshot, the by-name effect map, whether the
+ * hand band is remote) are leg facts only the run holds; {@link rosterCanPersistMemory} is the verdict built on it.
+ */
+export declare function persistenceCapableToolNames(tools: ReadonlyArray<PersistenceProbeTool>, facts: PersistenceFacts): string[];
+/**
+ * The roster-wide persistence verdict a run reads: the deployment's own `declared` statement wins (the only honest
+ * channel for a caller tool that persists through its own closure, which no inference can see); otherwise some tool
+ * of the mounted roster passes {@link persistenceCapableToolNames}' judgment.
+ */
+export declare function rosterCanPersistMemory(tools: ReadonlyArray<PersistenceProbeTool>, facts: PersistenceFacts, declared?: boolean): boolean;
+/**
+ * The CANDIDATE set, from the static catalog alone: the names whose definition passes the same judgment on no leg
+ * facts at all (nothing excluded, no by-name effect map, hands not remote) — the tools that COULD persist on a leg
+ * that mounts them. A prediction, not a verdict: whether a given run's roster persists is
+ * {@link rosterCanPersistMemory}, which the runner calls with the facts the run holds.
+ */
+export declare function persistenceCandidateToolNames(): string[];
 /** A-8 — every definition that names a path target at all (read or write): the file-tool glob lane. */
 export declare function pathTargetingToolNames(): ReadonlySet<string>;
 /**

package/dist/core/tool-registry.js

@@ -26,6 +26,32 @@ const names = (pred) => {
 export function pathConfinableWriteToolNames() {
     return names((e) => e.face.pathTarget !== undefined && e.face.pathTarget.access !== "read");
 }
+function toolCanPersist(t, facts) {
+    if (facts.exclude?.includes(t.name) ?? false)
+        return false;
+    const effect = t.effect ?? facts.effects?.get(t.name) ?? "write";
+    if (effect === "read")
+        return false;
+    const pathTarget = t.pathTarget ?? pathTargetOf(t.name);
+    const family = t.family ?? catalogEntriesNamed(t.name)[0]?.face.family;
+    if (!((pathTarget !== undefined && pathTarget.access !== "read") || family === "shell"))
+        return false;
+    return !facts.remoteHands;
+}
+export function persistenceCapableToolNames(tools, facts) {
+    const out = new Set();
+    for (const t of tools)
+        if (toolCanPersist(t, facts))
+            out.add(t.name);
+    return [...out];
+}
+export function rosterCanPersistMemory(tools, facts, declared) {
+    return declared ?? tools.some((t) => toolCanPersist(t, facts));
+}
+export function persistenceCandidateToolNames() {
+    const rows = TOOL_CATALOG_ENTRIES.map((e) => ({ name: e.name, effect: e.face.effect, pathTarget: e.face.pathTarget, family: e.face.family }));
+    return persistenceCapableToolNames(rows, { remoteHands: false });
+}
 export function pathTargetingToolNames() {
     return names((e) => e.face.pathTarget !== undefined);
 }

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

@@ -1,6 +1,6 @@
 import { Type, type Static, type TSchema } from "typebox";
 import type { AgentTool } from "../internal/harness-types.js";
-import { type ToolFamily, type ToolRosterPathTarget, type ToolMountTag, type ToolPathTarget, type ToolRenderHints, type ToolRuleFace } from "./tool-face.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";
 export declare const ROSTER_SOURCES: readonly ["builtin", "caller", "host", "mcp", "a2a", "external", "synthetic"];
 export type RosterSource = (typeof ROSTER_SOURCES)[number];
@@ -258,6 +258,24 @@ export declare function rosterEntryNamed(roster: ToolRoster, toolName: string):
  */
 export declare function rosterToolName(roster: ToolRoster | undefined, name: string): string;
 export { ruleNamesOf } from "./tool-name-readings.js";
+/** The reserved card a call owns, judged from its wire name alone — the ONE read of "is this the engine's question /
+ *  plan tool": the card minted on a call's face, the park's question mark and the decide's answer binding all ask it. */
+export declare function engineCardOf(call: {
+    readonly toolName: string;
+}): ReservedApprovalCard | undefined;
+/** The approval card a call renders under: a reserved card only for the engine tool that owns it (whatever a row
+ *  declares), otherwise the row's declared card, else `generic`. */
+export declare function approvalCardOf(call: {
+    readonly toolName: string;
+}, declared: ToolApprovalCard | undefined): ToolApprovalCard;
+/** The ask / gate member that carries a call's card: copied off the face the gate stamped, absent on a bare request. */
+export declare function approvalCardMemberOf(call: {
+    readonly face?: {
+        readonly approvalCard?: ToolApprovalCard;
+    } | undefined;
+}): {
+    approvalCard?: ToolApprovalCard;
+};
 /** design/388 B6 — the per-call face a gated request carries, read off a roster snapshot by name (aliases resolve).
  *  `names` leads with the name the face was minted under (the model's spelling at the gate), then the wire name and the
  *  other aliases — the ONE order of a call's names: a reader that must pick one of them by position (a `member` seat)

package/dist/core/tool-roster.js

@@ -3,7 +3,10 @@ import { Type } from "typebox";
 import { getToolContract } from "../prompt-assembly/tool-catalog.js";
 import { protocolOf } from "./protocol-table.js";
 import { describeToolCatalog } from "./tool-registry.js";
-import { RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_CHARS, RENDER_HINT_MAX_LIST, TOOL_APPROVAL_CARDS, TOOL_CARD_ID_MAX_CHARS, TOOL_CONTRACT_MAX_CHARS, TOOL_FAMILIES, TOOL_KEYS_MAX, TOOL_KEY_MAX_CHARS, TOOL_MOUNT_TAGS, TOOL_WIRE_NAME_MAX_CHARS, TOOL_PATH_ABSENCES, TOOL_PATH_BASES, } from "./tool-face.js";
+import { RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_CHARS, RENDER_HINT_MAX_LIST, RESERVED_APPROVAL_CARDS, isToolApprovalCard, TOOL_APPROVAL_CARDS, TOOL_CARD_ID_MAX_CHARS, TOOL_CONTRACT_MAX_CHARS, TOOL_FAMILIES, TOOL_KEYS_MAX, TOOL_KEY_MAX_CHARS, TOOL_MOUNT_TAGS, TOOL_WIRE_NAME_MAX_CHARS, TOOL_PATH_ABSENCES, TOOL_PATH_BASES, } from "./tool-face.js";
+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";
 function lit(values) {
     return Type.Union(values.map((v) => Type.Literal(v)));
 }
@@ -82,6 +85,21 @@ function namesResolvingTo(roster, e) {
     return [e.name, ...e.aliases.filter((a) => a !== e.name && rosterToolName(roster, a) === e.name)];
 }
 export { ruleNamesOf } from "./tool-name-readings.js";
+const RESERVED_CARD_OWNER = {
+    question: () => ASK_USER_QUESTION_TOOL_NAME,
+    plan: () => PRESENT_PLAN_TOOL_NAME,
+};
+export function engineCardOf(call) {
+    const wire = wireOf("card.reserved", call);
+    return RESERVED_APPROVAL_CARDS.find((card) => RESERVED_CARD_OWNER[card]() === wire);
+}
+export function approvalCardOf(call, declared) {
+    return engineCardOf(call) ?? (declared !== undefined && !RESERVED_APPROVAL_CARDS.includes(declared) ? declared : "generic");
+}
+export function approvalCardMemberOf(call) {
+    const card = call.face?.approvalCard;
+    return card !== undefined ? { approvalCard: card } : {};
+}
 export function toolCallFaceOf(roster, toolName) {
     if (roster === undefined)
         return undefined;
@@ -97,6 +115,7 @@ export function toolCallFaceOf(roster, toolName) {
         contractId: e.contract.contractId,
         shapeDigest: e.shapeDigest,
         implementationRevision: e.contract.implementationRevision,
+        approvalCard: approvalCardOf({ toolName: e.name }, e.renderHints?.approvalCard),
     };
 }
 export function parkedToolIdentity(roster, toolName) {
@@ -271,7 +290,7 @@ function capRenderHints(h) {
         out.summaryParams = h.summaryParams.filter((s) => typeof s === "string");
     if (Array.isArray(h.resultCards))
         out.resultCards = h.resultCards.filter((s) => typeof s === "string");
-    if (typeof h.approvalCard === "string" && TOOL_APPROVAL_CARDS.includes(h.approvalCard))
+    if (isToolApprovalCard(h.approvalCard))
         out.approvalCard = h.approvalCard;
     return Object.keys(out).length > 0 ? out : undefined;
 }

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

@@ -0,0 +1,45 @@
+/**
+ * The one reading of a {@link ToolSpec} object. A spec is the caller's own mutable object graph, and the factory and the
+ * run's roster snapshot both turn it into something that outlives the moment it was read; each takes its copy through
+ * here, so a member is read once, by name, through an ordinary property read (an inherited, non-enumerable or
+ * Proxy-answered declaration included — how every phase reads a declaration), and the copy holds no object the caller can
+ * reach: declaration data (lists, schemas, faces, hints) is copied level by level — own string AND symbol keys, so a
+ * TypeBox schema keeps its kind marks — and frozen, and the only values kept by reference are the functions a ToolSpec
+ * declares as functions ({@link FUNCTION_MEMBERS}).
+ *
+ * A declaration the copy cannot take is refused, naming the member path, with the declaration door's code: a function inside
+ * data, an object with a prototype (a class instance, a Date, a Map), an accessor, a graph past the node or depth budget.
+ * A tool-name list is the one lenient place, and only at the places its judge reads one ({@link NAME_LIST_MEMBERS},
+ * {@link FACE_LIST_KEYS}): it is taken through the judge's own snapshot ({@link snapshotToolNameList}), so a container that
+ * cannot be read becomes the judge's failure marker and an entry the copy cannot take stands in as an inert value of the same
+ * JS type — the judge refuses either with the sentence it always had, without the caller's object ever being on the face.
+ */
+import type { ToolSpec } from "./tool-spec.js";
+/** Every {@link ToolSpec} member, by name — the type's own key set, fenced both ways (a member added to `ToolSpec` and not
+ *  listed here, or a name here that `ToolSpec` does not declare, is a compile error). */
+export declare const TOOL_SPEC_MEMBERS: readonly string[];
+/** One copy's ledger: the nodes charged so far (a value is a node; a container is charged for all its slots / keys when it is
+ *  entered, before anything is allocated, and its children are not charged again), the source objects already copied (a graph
+ *  that shares a sub-node copies it once and charges it once — strict and lenient copies kept apart) and the sources being
+ *  copied now (a cycle is refused). */
+export interface CopyState {
+    nodes: number;
+    readonly seen: WeakMap<object, object>;
+    readonly seenLenient: WeakMap<object, object>;
+    readonly inflight: Set<object>;
+}
+export declare const newCopyState: () => CopyState;
+/** One member's value, as the face and the factory's copy hold it. `state` is the ledger of the whole spec / entry. */
+export declare function frozenMember(name: string, value: unknown, state: CopyState): unknown;
+/** A value under a key that is no ToolSpec member (a contract symbol, a decoration): the engine reads no declaration off it, so
+ *  it is carried when it is plain data and left off the face when it is not. */
+export declare function frozenExtra(key: string, value: unknown, state: CopyState): {
+    kept: true;
+    value: unknown;
+} | {
+    kept: false;
+};
+/** A spec as it stands now: a frozen object holding each {@link TOOL_SPEC_MEMBERS} member as read once (a member the spec does
+ *  not answer for stays absent). The caller keeping its own object and changing it afterwards — a member, or anything inside a
+ *  list or a schema — changes nothing here. */
+export declare function frozenToolSpec<T extends ToolSpec>(spec: T): Readonly<T>;

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

@@ -0,0 +1,169 @@
+import { UNREADABLE_LIST, snapshotToolNameList } from "./tool-name-list.js";
+export const TOOL_SPEC_MEMBERS = Object.keys({
+    name: true, aliases: true, description: true, descriptionClassic: true, label: true, parameters: true, execute: true, effect: true,
+    egress: true, irreversibility: true, reversibilityProbe: true, permissionSeat: true, isConcurrencySafe: true, executionMode: true,
+    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,
+});
+const FUNCTION_MEMBERS = new Set(["execute", "prepareArguments", "validateInput", "approvalPreview", "reversibilityProbe", "isConcurrencySafe", "withAgents"]);
+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 };
+const MAX_NODES = 20_000;
+const MAX_DEPTH = 64;
+const COPIED = new WeakSet();
+class DeclarationRefused extends Error {
+}
+function refuse(path, why) {
+    const e = new DeclarationRefused(`ToolSpec ${path}: ${why}. A tool's declaration is data the run fixes once, before its first await — pass lists, schemas and hints as plain data (functions only in execute / prepareArguments / validateInput / approvalPreview / reversibilityProbe / isConcurrencySafe / withAgents).`);
+    e.code = "config.tool_mount_denied";
+    throw e;
+}
+const inertObject = () => Object.freeze(Object.create(null));
+const inertFunction = () => Object.freeze(() => undefined);
+function standIn(value) {
+    let list = false;
+    try {
+        list = Array.isArray(value);
+    }
+    catch {
+    }
+    return list ? Object.freeze([]) : inertObject();
+}
+function overBudget(path) {
+    return refuse(path, `declaration data over budget (${MAX_NODES} nodes / ${MAX_DEPTH} levels)`);
+}
+export const newCopyState = () => ({ nodes: 0, seen: new WeakMap(), seenLenient: new WeakMap(), inflight: new Set() });
+function spendNodes(state, nodes, path) {
+    state.nodes += nodes;
+    if (state.nodes > MAX_NODES)
+        overBudget(path);
+}
+function copyNode(value, path, depth, state, lenient, places) {
+    if (value === null || (typeof value !== "object" && typeof value !== "function"))
+        return value;
+    if (typeof value === "function")
+        return lenient ? inertFunction() : refuse(path, "a function inside declaration data");
+    if (COPIED.has(value))
+        return value;
+    const seen = lenient ? state.seenLenient : state.seen;
+    const shared = seen.get(value);
+    if (shared !== undefined)
+        return shared;
+    if (depth > MAX_DEPTH)
+        overBudget(path);
+    if (state.inflight.has(value))
+        refuse(path, "a reference cycle is not declaration data");
+    state.inflight.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const length = value.length;
+            spendNodes(state, length, path);
+            const items = new Array(length);
+            for (let i = 0; i < length; i++) {
+                const d = Object.getOwnPropertyDescriptor(value, i);
+                if (d === undefined)
+                    continue;
+                if (!("value" in d)) {
+                    if (lenient)
+                        return standIn(value);
+                    refuse(`${path}[${i}]`, "an accessor is not declaration data");
+                }
+                items[i] = copyNode(d.value, `${path}[${i}]`, depth + 1, state, lenient, places?.elementKeys === undefined ? undefined : { ownKeys: places.elementKeys });
+            }
+            const sealed = Object.freeze(items);
+            COPIED.add(sealed);
+            seen.set(value, sealed);
+            return sealed;
+        }
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== null && proto !== Object.prototype)
+            return lenient ? inertObject() : refuse(path, "an object with a prototype (a class instance, a Date, a Map …) is not declaration data");
+        const out = Object.create(proto);
+        const keys = Reflect.ownKeys(value);
+        spendNodes(state, keys.length, path);
+        for (const key of keys) {
+            const d = Object.getOwnPropertyDescriptor(value, key);
+            if (d === undefined)
+                continue;
+            const at = `${path}.${String(key)}`;
+            if (!("value" in d)) {
+                if (lenient)
+                    return inertObject();
+                refuse(at, "an accessor is not declaration data");
+            }
+            const kept = typeof key === "string" && places?.ownKeys?.has(key) === true ? copyNameList(d.value, at, state) : copyNode(d.value, at, depth + 1, state, lenient);
+            Object.defineProperty(out, key, { value: kept, enumerable: d.enumerable, writable: false, configurable: false });
+        }
+        const sealed = Object.freeze(out);
+        COPIED.add(sealed);
+        seen.set(value, sealed);
+        return sealed;
+    }
+    catch (cause) {
+        if (cause instanceof DeclarationRefused || !lenient)
+            throw cause;
+        return standIn(value);
+    }
+    finally {
+        state.inflight.delete(value);
+    }
+}
+function copyNameList(value, path, state) {
+    if (typeof value === "object" && value !== null) {
+        if (COPIED.has(value))
+            return value;
+        const shared = state.seenLenient.get(value);
+        if (shared !== undefined)
+            return shared;
+    }
+    let slots = 0;
+    try {
+        if (Array.isArray(value))
+            slots = value.length;
+    }
+    catch {
+    }
+    spendNodes(state, slots, path);
+    const kept = snapshotToolNameList(value);
+    if (kept === UNREADABLE_LIST)
+        return kept;
+    if (kept === value || !Array.isArray(kept))
+        return copyNode(value, path, 0, state, true);
+    if (kept.length > slots)
+        spendNodes(state, kept.length - slots, path);
+    const sealed = Object.freeze(kept.map((entry, i) => copyNode(entry, `${path}[${i}]`, 1, state, true)));
+    COPIED.add(sealed);
+    if (typeof value === "object" && value !== null)
+        state.seenLenient.set(value, sealed);
+    return sealed;
+}
+export function frozenMember(name, value, state) {
+    if (FUNCTION_MEMBERS.has(name) && typeof value === "function")
+        return value;
+    spendNodes(state, 1, name);
+    if (NAME_LIST_MEMBERS.has(name))
+        return copyNameList(value, name, state);
+    return copyNode(value, name, 0, state, false, name === "agentToolFaces" ? FACE_PLACES : undefined);
+}
+export function frozenExtra(key, value, state) {
+    try {
+        spendNodes(state, 1, key);
+        return { kept: true, value: copyNode(value, key, 0, state, false) };
+    }
+    catch {
+        return { kept: false };
+    }
+}
+export function frozenToolSpec(spec) {
+    const copy = {};
+    const state = newCopyState();
+    for (const name of TOOL_SPEC_MEMBERS) {
+        const value = Reflect.get(spec, name);
+        if (value !== undefined)
+            copy[name] = frozenMember(name, value, state);
+    }
+    return Object.freeze(copy);
+}

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

@@ -221,6 +221,13 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
         aliases?: readonly string[];
         contentOrigin?: ToolContentOrigin;
     }>;
+    /**
+     * TRUE ⇔ the children of this delegation tool inherit the MCP tools their spawning run mounts (no explicit pool: the pool is
+     * the inherited surface, and the MCP mount is part of it). Filled by `createSubagentTool` beside {@link agentToolPool}, which
+     * is a declaration and cannot list a run's mount: the memory content-origin face reads this to add the spawning run's MCP tools
+     * to the child's pool, through the same universe reader the spawn filters with.
+     */
+    agentToolInheritsMcp?: true;
     /** approval display projection (see AgentTool.approvalPreview): pure args→display value
      *  for human approval surfaces; clamped + throw-swallowed by the gate; never adjudication input. */
     approvalPreview?: (args: unknown) => unknown;
@@ -793,10 +800,10 @@ export interface ToolExecuteContext {
      * root session's), so the root session's `rewindFilesTo` reaches the child's edits; a child on a
      * different tree (worktree isolation, an explicit `cwd`, a fresh per-task sandbox) starts its own
      * lineage, because root-relative keys re-joined against a different tree would name files that run
-     * never edited. Three delegated legs deliberately carry NO lineage and keep their own scope: the
+     * never edited. Two delegated legs deliberately carry NO lineage and keep their own scope: the
      * Agent tool's REVIVE arm (a revival's lineage would be the REVIVER's tree, which says nothing
-     * about the revived row's), and the workflow / team orchestration spawn legs (`run_workflow`,
-     * `runTeamDiscussion` — they build their children's internals without this seat). Edits made by
+     * about the revived row's), and the workflow orchestration spawn leg (`run_workflow` — it builds its
+     * children's internals without this seat). Edits made by
      * those children are therefore NOT reachable from the root session's rewind, and a restore request
      * on one of them is not refused either — it converges that child's own scope.
      */
@@ -958,6 +965,18 @@ export interface ToolExecuteContext {
      * Runner-filled trusted seat, never a model argument.
      */
     readDenyPatterns?: readonly import("../tools/fs/read-deny.js").ReadDenyEntry[];
+    /**
+     * The parent task's OWN write-protection additions ({@link TaskSpec.writeProtectedAdditions}), traveling the delegation
+     * tree add-only (a child guards at least every row its parent's request added). Runner-filled trusted seat, never a
+     * model argument.
+     */
+    writeProtectedAdditions?: readonly import("./write-protect.js").WriteProtectedEntry[];
+    /**
+     * The parent task's OWN compliance deny additions ({@link TaskSpec.complianceAdditionalDenies}), traveling the
+     * delegation tree add-only (a child denies at least every capability its parent's request denied). Runner-filled
+     * trusted seat, never a model argument.
+     */
+    complianceAdditionalDenies?: readonly import("./compliance.js").ComplianceCapability[];
     /**
      * The HARD-HEADLESS clamp ({@link TaskSpec.interactiveTools} set to `false` — "never mount a
      * human-facing tool on this run, whatever faces exist"), Runner-filled read-only on the same trusted
@@ -990,11 +1009,20 @@ export interface ToolExecuteContext {
     oneShot?: boolean;
     /** Does this run mount THIS instance in `spec.tools` as handed, pre-gate (Runner-filled)? The parent bound on `SubagentToolOptions.inheritedTools`. */
     mountsCallerTool?: (tool: ToolSpec) => boolean;
-    /**  — the parent's tool-face controls ({@link TaskSpec.excludeTools} /
-     *  {@link TaskSpec.deferTools}), inherited down the delegation tree like `principal` (Runner-filled,
-     *  read-only): a scenario-wide roster must not be escapable by delegating to a child that remounts
-     *  the excluded tool. Children merge these with their own spec values (union — tighten-only). */
-    excludeTools?: readonly string[];
+    /**
+     * The MCP surface THIS run mounts (Runner-filled, read-only, answered at call time off the live roster): per declared server,
+     * the tools of it mounted right now, and the aggregate tools no server owns. A delegation tool reads it AT SPAWN TIME for the
+     * protocol half of the one universe a child's lists govern, and declares the child the servers the lists leave — the child
+     * connects for itself (it outlives the spawning leg when it runs in the background or is kept for a later turn). Absent when
+     * the tool runs outside a Runner task, and for a run that declared no server.
+     */
+    mountedMcp?: () => import("./mounted-mcp.js").MountedMcp;
+    /** The run's compiled tool selector (its `allowTools` / `excludeTools` under the ceiling it was spawned with): `admits` answers
+     *  "may this run use this tool", and `layers` is the ceiling every child this run spawns inherits, so a scenario-wide roster cannot
+     *  be escaped by delegating to a child that remounts a tool this run may not use (Runner-filled, read-only, never a model argument). */
+    toolSelector?: import("./tool-face.js").ToolSelector;
+    /** The parent's deferred-disclosure list ({@link TaskSpec.deferTools}), inherited down the delegation tree like `principal`
+     *  (Runner-filled, read-only). */
     deferTools?: readonly string[];
     /** DD-3 — the INLINE-PIN half of the same tool-face control ({@link TaskSpec.alwaysLoadTools}),
      *  inherited on the same seat and by the same rule as {@link deferTools} (Runner-filled, read-only).
@@ -1204,6 +1232,16 @@ export interface ToolExecuteContext {
      * park in its subtree). Same discipline as `principal`: inherit verbatim off the trusted seat.
      */
     checkpointStoreForChildren?: import("./checkpoint-store.js").CheckpointStore | "disabled";
+    /**
+     * The host run's checkpoint SCOPE, for its children — the scope this run's own parked rows land in (the one
+     * value its prepare derived; a delegated host's is the scope ITS parent handed it, so a whole tree answers
+     * with the root's). A delegation tool copies it verbatim into every child's `RunInternals.checkpointScope`, so
+     * a child's parked row is listed where its parent's is, on the synchronous lane as on the background one.
+     * Scope only: the park capability is {@link durableApprovalForChildren}'s business. Runner-filled, read-only,
+     * NEVER a model/tool argument; ABSENT when the tool runs outside a Runner task (the child then derives its
+     * scope from its own spec, as a root run does).
+     */
+    checkpointScopeForChildren?: string;
     /**
      * design/99 (nested-subagent live observability): the host run's stable taskId (`spec.taskId ?? sessionId`),
      * filled by the Runner. A delegation tool (`createSubagentTool`) reads it AT SPAWN TIME and threads it into the

package/dist/core/tools.d.ts

@@ -28,7 +28,7 @@ export declare function isDefineToolProduct(x: unknown): x is AgentTool;
  *  "cannot enrich" arm). `defineTool` uses it on its own product; the only OTHER legitimate caller is a
  *  wrapper that (a) starts from a branded product, (b) preserves the AgentTool
  *  `execute(toolCallId, rawParams, signal, onUpdate)` contract faithfully and (c) hands over a `rebind`
- *  that re-wraps the REBOUND inner product the same way (e.g. teacher.ts's logging wrapper) — so a mount
+ *  that re-wraps the REBOUND inner product the same way (e.g. a logging wrapper) — so a mount
  *  rebinding the wrapper gets a wrapper over an enriched product, not an enriched product without the
  *  wrapper. A shallow copy that does NOT re-stamp deliberately loses the brand — that is the brand's
  *  documented survival contract, not an accident. Internal only. */
@@ -76,6 +76,10 @@ export interface DefineToolOptions {
      *  `{toolCallId, signal}` ctx, so every mount that does not opt in stays byte-identical. */
     enrichCtx?: ToolCtxEnricher;
 }
-/** Adapt a friendly ToolSpec into the vendored AgentTool the agent loop expects. */
+/** Adapt a friendly ToolSpec into the vendored AgentTool the agent loop expects. The product is built from the spec as it
+ *  stands HERE: the factory takes its one frozen copy ({@link frozenToolSpec}) and builds the product, its call-time reads
+ *  and every later rebind from that copy, so a caller that keeps the object it handed in and changes it afterwards
+ *  (replacing `execute`, `parameters`, a mark) changes nothing about the tool. The spec's own functions are called on the
+ *  caller's object, as they always were. */
 export declare function defineTool<TParams extends TSchema = TSchema>(spec: ToolSpec<TParams>, options?: DefineToolOptions): AgentTool<TParams>;
 export {};

package/dist/core/tools.js

@@ -1,6 +1,7 @@
 import { Value } from "typebox/value";
 import { formatToolError, formatZodValidationError } from "./tool-errors.js";
 import { readMember } from "./thrown-value.js";
+import { frozenToolSpec } from "./tool-spec-members.js";
 import { attachToolContract } from "../prompt-assembly/tool-catalog.js";
 function normalizeContent(ret) {
     if (typeof ret === "string") {
@@ -68,10 +69,13 @@ function stampCallIdentity(enriched, toolCallId, signal) {
     return Object.create(Object.getPrototypeOf(enriched), { ...Object.getOwnPropertyDescriptors(enriched), toolCallId: own(toolCallId), signal: own(signal) });
 }
 export function defineTool(spec, options) {
+    return buildProduct(frozenToolSpec(spec), spec, options);
+}
+function buildProduct(spec, owner, options) {
     const executionMode = spec.executionMode ?? (spec.effect === "read" ? "parallel" : "sequential");
     const tool = {
         name: spec.name,
-        ...(spec.aliases && spec.aliases.length > 0 ? { aliases: spec.aliases } : {}),
+        ...(spec.aliases && spec.aliases.length > 0 ? { aliases: [...spec.aliases] } : {}),
         description: spec.description,
         ...(spec.descriptionClassic !== undefined ? { descriptionClassic: spec.descriptionClassic } : {}),
         label: spec.label ?? spec.name,
@@ -99,7 +103,7 @@ export function defineTool(spec, options) {
         ...(spec.approvalPreview ? { approvalPreview: spec.approvalPreview } : {}),
         ...(spec.validateInput ? { validateInput: spec.validateInput } : {}),
         execute: async (toolCallId, rawParams, signal) => {
-            const params = spec.prepareArguments ? spec.prepareArguments(rawParams) : rawParams;
+            const params = spec.prepareArguments ? spec.prepareArguments.call(owner, rawParams) : rawParams;
             if (!Value.Check(spec.parameters, params)) {
                 const detail = formatZodValidationError(spec.parameters, params);
                 return {
@@ -112,7 +116,7 @@ export function defineTool(spec, options) {
             try {
                 const baseCtx = { toolCallId, signal };
                 const ctx = options?.enrichCtx ? stampCallIdentity(options.enrichCtx(baseCtx), toolCallId, signal) : baseCtx;
-                const ret = await spec.execute(params, ctx);
+                const ret = await spec.execute.call(owner, params, ctx);
                 const { content, details, terminate, isError } = normalizeContent(ret);
                 const guarded = isEmptyToolContent(content)
                     ? [{ type: "text", text: isError ? `(${spec.name} reported an error with no further output)` : `(${spec.name} completed with no output)` }]
@@ -141,7 +145,7 @@ export function defineTool(spec, options) {
     }
     stampDefineToolBrand(tool, (enrich) => {
         const composed = options?.enrichCtx === undefined ? enrich : (base) => options.enrichCtx(enrich(base));
-        const rebuilt = defineTool(spec, { ...options, enrichCtx: composed });
+        const rebuilt = buildProduct(spec, owner, { ...options, enrichCtx: composed });
         const { [DEFINE_TOOL_BRAND]: _brand, [DEFINE_TOOL_REBIND]: _seat, ...face } = Object.getOwnPropertyDescriptors(tool);
         const copy = Object.create(Object.getPrototypeOf(tool), { ...face, execute: { value: rebuilt.execute, enumerable: true, configurable: true, writable: true } });
         return stampDefineToolBrand(copy, (again) => rebindDefineToolCtx(rebuilt, again));

package/dist/core/untrusted-egress.js

@@ -1,14 +1,13 @@
 import { delimitUntrusted, neutralizeForFence } from "./untrusted-text.js";
-import { scrubSecrets, SECRET_PASSES, runRedactionPasses } from "./arg-summary.js";
+import { egressPasses, runRedactionPasses } from "./arg-summary.js";
+import { CREDENTIAL_VOCABULARY, egressPassGroups, URI_SCHEME_SOURCE } from "./credential-vocabulary.js";
 import { sliceHeadSafe } from "./surrogate-safe-slice.js";
 export { summarizeRedactions } from "./arg-summary.js";
-const URI_SCHEME = String.raw `[A-Za-z][A-Za-z0-9+.\-_]{0,63}`;
-const CREDENTIALS_IN_AUTHORITY = new RegExp(String.raw `(${URI_SCHEME}:\/\/)((?:[^/\s"'@]*@)+)`, "gi");
-const URL_OF_ANY_PROTOCOL = new RegExp(String.raw `${URI_SCHEME}:\/\/[^\s"'\`]+`, "gi");
+const URL_OF_ANY_PROTOCOL = new RegExp(String.raw `${URI_SCHEME_SOURCE}:\/\/[^\s"'\`]+`, "gi");
 const BARE_USERNAME_MAX_LEN = 20;
 function redactUserinfo(scheme, userinfoWithAt) {
     const userinfo = userinfoWithAt.slice(0, -1);
-    if (userinfo.includes("@"))
+    if (CREDENTIAL_VOCABULARY.policy.urlUserinfo === "whole" || userinfo.includes("@"))
         return `${scheme}[redacted-credentials]@`;
     const colonIdx = userinfo.indexOf(":");
     if (colonIdx === -1) {
@@ -16,18 +15,9 @@ function redactUserinfo(scheme, userinfoWithAt) {
     }
     return `${scheme}${userinfo.slice(0, colonIdx)}:[redacted-credentials]@`;
 }
-const SECRET_TIER_PASSES = [
-    ...SECRET_PASSES,
-    {
-        kind: "url-credentials",
-        confidence: "medium",
-        marker: "[redacted-credentials]",
-        source: "untrusted-egress",
-        re: CREDENTIALS_IN_AUTHORITY,
-        replace: (_m, scheme, userinfo) => redactUserinfo(scheme, userinfo),
-    },
-    { kind: "signed-url-param", confidence: "high", marker: "[redacted]", source: "untrusted-egress", re: /([?&#](?:sig|signature|sas|code)=)[^&\s"'#]+/gi, replace: "$1[redacted]" },
-];
+const SECRET_TIER_PASSES = egressPasses(egressPassGroups(CREDENTIAL_VOCABULARY), {
+    "url-credentials": (_m, scheme, userinfo) => redactUserinfo(scheme, userinfo),
+});
 export function redactSecrets(s, report) {
     return runRedactionPasses(s, SECRET_TIER_PASSES, report);
 }
@@ -99,14 +89,27 @@ export function boundedRedactedSummary(value, max) {
 }
 export function untrustedEgressForHuman(value, opts) {
     const source = boundedString(value, Number.POSITIVE_INFINITY, redactHostLeaks);
-    let budget = opts.max;
-    let bounded = boundedString(source, budget, (s) => s);
-    for (let i = 0; i < 4 && budget > 0; i++) {
-        const overflow = [...neutralizeForFence(bounded)].length - opts.max;
-        if (overflow <= 0)
-            break;
-        budget = Math.max(0, budget - overflow);
-        bounded = boundedString(source, budget, (s) => s);
+    const probe = (budget) => {
+        const bounded = boundedString(source, budget, (s) => s);
+        return { bounded, overflow: [...neutralizeForFence(bounded)].length - opts.max };
+    };
+    let chosen = probe(opts.max);
+    if (chosen.overflow > 0) {
+        let fits;
+        let lo = 0;
+        let hi = opts.max;
+        while (hi - lo > 1) {
+            const mid = lo + Math.floor((hi - lo) / 2);
+            const p = probe(mid);
+            if (p.overflow <= 0) {
+                lo = mid;
+                fits = p;
+            }
+            else {
+                hi = mid;
+            }
+        }
+        chosen = fits ?? probe(lo);
     }
-    return delimitUntrusted(opts.label, bounded, opts.max);
+    return delimitUntrusted(opts.label, chosen.bounded, opts.max);
 }