@sema-agent/core 7.48.0 → 7.49.1

package/dist/core/tighten-task-spec.js

@@ -1,5 +1,6 @@
 import { combinePolicies } from "./tool-policy.js";
 import { clampPermissionMode } from "./ask-origin.js";
+import { CLAMP_SEATS, composeClampSeat, loosensClampSeat } from "./child-clamp-seats.js";
 export class TaskSpecTightenError extends Error {
     constructor(message) {
         super(message);
@@ -21,34 +22,28 @@ export function tightenTaskSpec(base, overrides) {
             merged[field] = [...new Set([...(b ?? []), ...(o ?? [])])];
         }
     }
-    for (const faceKey of ["readFace", "writeFace"]) {
-        if (base[faceKey] === "roots" && overrides[faceKey] === "open") {
-            throw new TaskSpecTightenError(`tightenTaskSpec: cannot loosen ${faceKey} from "roots" to "open" (override may only tighten)`);
-        }
-        if (base[faceKey] !== undefined || overrides[faceKey] !== undefined) {
-            merged[faceKey] = base[faceKey] === "roots" || overrides[faceKey] === "roots" ? "roots" : (overrides[faceKey] ?? base[faceKey]);
+    {
+        const b = base.allowTools;
+        const o = overrides.allowTools;
+        if (b !== undefined && o !== undefined && !b.includes("*")) {
+            const wider = o.filter((entry) => !b.includes(entry));
+            if (wider.length > 0)
+                throw new TaskSpecTightenError(`tightenTaskSpec: cannot widen allowTools beyond the base list (override names ${JSON.stringify(wider)}; the override may only narrow)`);
         }
+        const kept = o ?? b;
+        if (kept !== undefined)
+            merged.allowTools = [...kept];
+        else
+            delete merged.allowTools;
     }
-    if (base.readDenyPatterns !== undefined || overrides.readDenyPatterns !== undefined) {
-        const seen = new Set();
-        const union = [];
-        for (const e of [...(base.readDenyPatterns ?? []), ...(overrides.readDenyPatterns ?? [])]) {
-            const key = typeof e === "string" ? `i:${e}` : `${e.caseSensitive === true ? "s" : "i"}:${e.pattern}`;
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            union.push(e);
+    for (const seat of CLAMP_SEATS) {
+        const b = base[seat];
+        const o = overrides[seat];
+        if (loosensClampSeat(seat, b, o)) {
+            throw new TaskSpecTightenError(`tightenTaskSpec: cannot loosen ${seat} from ${JSON.stringify(b)} to ${JSON.stringify(o)} (override may only tighten)`);
         }
-        merged.readDenyPatterns = union;
-    }
-    if (base.handsReadOnly === true && overrides.handsReadOnly === false) {
-        throw new TaskSpecTightenError("tightenTaskSpec: cannot loosen handsReadOnly from true to false (override may only tighten)");
-    }
-    if (base.handsReadOnly !== undefined || overrides.handsReadOnly !== undefined) {
-        merged.handsReadOnly = base.handsReadOnly === true || overrides.handsReadOnly === true;
-    }
-    if (base.approvalReach !== undefined || overrides.approvalReach !== undefined) {
-        merged.approvalReach = base.approvalReach === "none" || overrides.approvalReach === "none" ? "none" : (overrides.approvalReach ?? base.approvalReach);
+        if (b !== undefined || o !== undefined)
+            Object.assign(merged, { [seat]: composeClampSeat(seat, b, o) });
     }
     if (base.permissionMode !== undefined && overrides.permissionMode !== undefined) {
         const { effective, clamped } = clampPermissionMode(overrides.permissionMode, base.permissionMode);

package/dist/core/tool-catalog-entries.d.ts

@@ -55,16 +55,14 @@ export declare const TOOL_FACES: Readonly<Record<string, ToolFaceDeclaration>>;
  */
 export declare const ENGINE_BUILTIN_TOOL_NAMES: readonly string[];
 /**
- * The engine's HAND tools, once each, with the other spellings they answer to: the catalog rows mounted by `hands` — what a run
- * mounts for itself over an execution environment (the file and shell band, the worktree pair, the band's background-shell
- * pair). A delegated child's tool-name lists govern these beside the tools the delegation tool hands it, so the spawn reads
- * this set rather than a list of its own.
+ * EVERY tool the catalog describes, once per wire name, with the other spellings it answers to — the engine's side of the one
+ * universe a delegated child's tool-name lists govern (beside the tools the delegation tool hands it and the protocol tools
+ * its spawning run mounts). The spawn reads this set rather than a list of its own: a definition a catalog row adds later is
+ * governed the day it lands, whatever band mounts it.
  */
-export declare const HAND_TOOLS: ReadonlyArray<{
+export declare const ENGINE_TOOLS: ReadonlyArray<{
     readonly name: string;
     readonly aliases?: readonly string[];
 }>;
-/** The wire names of {@link HAND_TOOLS}. */
-export declare const HAND_TOOL_NAMES: readonly string[];
 /** Is this name one the engine mounts itself ({@link ENGINE_BUILTIN_TOOL_NAMES})? A caller tool, an MCP tool or a skill tool is not. */
 export declare function isEngineBuiltinToolName(name: string): boolean;

package/dist/core/tool-catalog-entries.js

@@ -110,14 +110,14 @@ export const TOOL_CATALOG_ENTRIES = [
     { id: "task-output", name: "TaskOutput", source: "builtin", definedIn: "src/core/task-registry.ts", mountedBy: ["delegation"], cards: ["task-output"], face: { family: "delegate", effect: "read", contract: TASK_OUTPUT_CONTRACT } },
     { id: "task-stop", name: "TaskStop", source: "builtin", definedIn: "src/core/task-registry.ts", mountedBy: ["delegation"], cards: ["task-stop"], face: { family: "delegate", effect: "write", contract: TASK_STOP_CONTRACT } },
     { id: "monitor", name: "Monitor", source: "builtin", definedIn: "src/tools/monitor.ts", mountedBy: ["backgroundTasks"], cards: ["monitor-start", "readonly_out_of_root", "read_unestablished"], face: { family: "other", effect: "write", contract: c("core.monitor@1"), ruleFace: shellRuleFace(["command", "description", "timeout_ms", "persistent"]), offloadThresholdChars: 10_000 } },
-    { id: "send-message", name: "SendMessage", source: "builtin", definedIn: "src/agents/send-message-tool.ts", mountedBy: ["delegation", "hostInternals", "peerLane"], cards: ["send-message"], face: { family: "protocol", effect: "write", contract: c("core.send_message@1") } },
+    { id: "send-message", name: "SendMessage", protocol: ["teammate"], source: "builtin", definedIn: "src/agents/send-message-tool.ts", mountedBy: ["delegation", "hostInternals", "peerLane"], cards: ["send-message"], face: { family: "protocol", effect: "write", contract: c("core.send_message@1") } },
     { id: "agent-transcript", name: "AgentTranscript", source: "builtin", definedIn: "src/agents/agent-transcript-tool.ts", mountedBy: ["delegation"], cards: ["agent-transcript"], face: { family: "delegate", effect: "read", contract: c("core.agent_transcript@1") } },
     { id: "list-agents", name: "ListAgents", source: "builtin", definedIn: "src/agents/list-agents-tool.ts", mountedBy: ["delegation", "peerLane"], cards: ["list-agents"], face: { family: "protocol", effect: "read", aliases: ["ListPeers"], contract: c("core.list_agents@1") } },
     { id: "read-inbox", name: "ReadInbox", source: "builtin", definedIn: "src/agents/read-inbox-tool.ts", mountedBy: ["peerLane"], cards: ["read-inbox"], face: { family: "protocol", effect: "read", contract: c("core.read_inbox@1"), offload: false, budgetExempt: true } },
     { id: "workflow", name: "Workflow", source: "builtin", definedIn: "src/orchestration/run-workflow-tool.ts", mountedBy: ["workflow"], cards: ["workflow-run"], face: { family: "delegate", effect: "write", contract: c("core.workflow@1") } },
-    { id: "report-blocked", name: "ReportBlocked", source: "builtin", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["always"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.report_blocked@1") } },
+    { id: "report-blocked", name: "ReportBlocked", protocol: ["delegated"], source: "builtin", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["always"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.report_blocked@1") } },
     { id: "report-findings", name: "ReportFindings", source: "builtin", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["always"], cards: ["report-findings"], face: { family: "scaffold", effect: "read", contract: c("core.report_findings@1") } },
-    { id: "structured-output", name: "StructuredOutput", source: "synthetic", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["optional"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.structured_output@1") } },
+    { id: "structured-output", name: "StructuredOutput", protocol: ["structured"], source: "synthetic", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["optional"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.structured_output@1") } },
     { id: "skill", name: "Skill", source: "builtin", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["optional"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.skill@1") } },
     { id: "read-tool-result", name: "ReadToolResult", source: "builtin", definedIn: "src/core/tool-result-store.ts", mountedBy: ["optional"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.read_tool_result@1"), budgetExempt: true } },
     { id: "tool-search", name: "ToolSearch", source: "builtin", definedIn: "src/core/runner/tool-disclosure.ts", mountedBy: ["optional"], cards: ["tool-search"], face: { family: "scaffold", effect: "read", contract: c("core.tool_search@1") } },
@@ -130,9 +130,9 @@ export const TOOL_CATALOG_ENTRIES = [
     { id: "memory-index", name: "memory_index", source: "builtin", definedIn: "src/core/memory-engine/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", effect: "read", contentOrigin: "local", contract: c("core.memory_index@1", "2"), offload: false } },
     { id: "memory-list", name: "memory_list", source: "builtin", definedIn: "src/core/shared-memory/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", effect: "read", contract: c("core.memory_list@1"), offload: false } },
     { id: "memory-read", name: "memory_read", source: "builtin", definedIn: "src/core/shared-memory/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", effect: "read", contract: c("core.memory_read@1"), offload: false } },
-    { id: "cron-create", name: "CronCreate", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-create"], face: { family: "other", effect: "write", contract: c("core.cron_create@1") } },
-    { id: "cron-delete", name: "CronDelete", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-delete"], face: { family: "other", effect: "idempotent", contract: c("core.cron_delete@1") } },
-    { id: "cron-list", name: "CronList", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-list"], face: { family: "other", effect: "read", contract: c("core.cron_list@1") } },
+    { id: "cron-create", name: "CronCreate", protocol: ["teammate"], source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-create"], face: { family: "other", effect: "write", contract: c("core.cron_create@1") } },
+    { id: "cron-delete", name: "CronDelete", protocol: ["teammate"], source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-delete"], face: { family: "other", effect: "idempotent", contract: c("core.cron_delete@1") } },
+    { id: "cron-list", name: "CronList", protocol: ["teammate"], source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-list"], face: { family: "other", effect: "read", contract: c("core.cron_list@1") } },
     { id: "schedule-wakeup", name: "ScheduleWakeup", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["schedule-wakeup"], face: { family: "other", effect: "write", contract: c("core.schedule_wakeup@1") } },
     {
         id: "web-fetch", name: "WebFetch", source: "builtin", definedIn: "src/tools/web.ts", mountedBy: ["scenario"], cards: ["web-fetch"],
@@ -143,13 +143,13 @@ export const TOOL_CATALOG_ENTRIES = [
         face: { family: "web", effect: "read", contentOrigin: "external", contract: c("core.web_search@1"), ruleFace: { primaryParams: ["query"] }, renderHints: { summaryParams: ["query"] }, compactable: true },
     },
     { id: "todo-write", name: TODO_WRITE_TOOL_NAME, source: "builtin", definedIn: "src/tools/todo.ts", mountedBy: ["scenario"], cards: ["todo"], modelGate: "task-scaffold", face: { family: "plan", effect: "idempotent", contract: c("core.todo_write@1") } },
-    { id: "task-create", name: TASK_CREATE_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "write", contract: c("core.task_create@1") } },
-    { id: "task-get", name: TASK_GET_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "read", contract: c("core.task_get@1") } },
-    { id: "task-update", name: TASK_UPDATE_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "idempotent", contract: c("core.task_update@1") } },
-    { id: "task-list", name: TASK_LIST_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task-list"], modelGate: "task-scaffold", face: { family: "plan", effect: "read", contract: c("core.task_list@1") } },
+    { id: "task-create", name: TASK_CREATE_TOOL_NAME, protocol: ["teammate"], protocolUnderCeiling: true, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "write", contract: c("core.task_create@1") } },
+    { id: "task-get", name: TASK_GET_TOOL_NAME, protocol: ["teammate"], protocolUnderCeiling: true, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "read", contract: c("core.task_get@1") } },
+    { id: "task-update", name: TASK_UPDATE_TOOL_NAME, protocol: ["teammate"], protocolUnderCeiling: true, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "idempotent", contract: c("core.task_update@1") } },
+    { id: "task-list", name: TASK_LIST_TOOL_NAME, protocol: ["teammate"], protocolUnderCeiling: true, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task-list"], modelGate: "task-scaffold", face: { family: "plan", effect: "read", contract: c("core.task_list@1") } },
     { id: "agent", name: "Agent", source: "builtin", definedIn: "src/agents/subagent.ts", mountedBy: ["scenario"], cards: ["agent", "fork"], face: { family: "delegate", contentOrigin: "local", contract: c("core.agent@1") } },
-    { id: "observer-report", name: "ObserverReport", source: "builtin", definedIn: "src/agents/observer.ts", mountedBy: ["scenario"], cards: [], face: { family: "scaffold", effect: "write", contract: c("core.observer_report@1") } },
-    { id: "declare-done", name: "DeclareDone", source: "builtin", definedIn: "src/orchestration/goal.ts", mountedBy: ["scenario"], cards: [], face: { family: "scaffold", effect: "read" } },
+    { id: "observer-report", name: "ObserverReport", protocol: ["observer"], source: "builtin", definedIn: "src/agents/observer.ts", mountedBy: ["scenario"], cards: [], face: { family: "scaffold", effect: "write", contract: c("core.observer_report@1") } },
+    { id: "declare-done", name: "DeclareDone", protocol: ["goal"], source: "builtin", definedIn: "src/orchestration/goal.ts", mountedBy: ["scenario"], cards: [], face: { family: "scaffold", effect: "read" } },
 ];
 export const ENGINE_CARDS = Object.freeze({
     mcp: "src/core/mcp.ts",
@@ -182,11 +182,10 @@ function deepFreeze(value) {
 deepFreeze(TOOL_CATALOG_ENTRIES);
 export const TOOL_FACES = Object.freeze(Object.fromEntries(TOOL_CATALOG_ENTRIES.map((e) => [e.id, e.face])));
 export const ENGINE_BUILTIN_TOOL_NAMES = Object.freeze([...new Set(TOOL_CATALOG_ENTRIES.filter((e) => e.source === "builtin").map((e) => e.name))]);
-export const HAND_TOOLS = Object.freeze([...new Set(TOOL_CATALOG_ENTRIES.filter((e) => e.mountedBy.includes("hands")).map((e) => e.name))].map((name) => {
-    const aliases = [...new Set(TOOL_CATALOG_ENTRIES.filter((e) => e.name === name && e.mountedBy.includes("hands")).flatMap((e) => e.face.aliases ?? []))];
+export const ENGINE_TOOLS = Object.freeze([...new Set(TOOL_CATALOG_ENTRIES.map((e) => e.name))].map((name) => {
+    const aliases = [...new Set(TOOL_CATALOG_ENTRIES.filter((e) => e.name === name).flatMap((e) => e.face.aliases ?? []))];
     return Object.freeze(aliases.length > 0 ? { name, aliases: Object.freeze(aliases) } : { name });
 }));
-export const HAND_TOOL_NAMES = Object.freeze(HAND_TOOLS.map((t) => t.name));
 export function isEngineBuiltinToolName(name) {
     return ENGINE_BUILTIN_TOOL_NAMES.includes(name);
 }

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

@@ -42,6 +42,12 @@ import type { AssertAllKeysHandled } from "./ask-origin.js";
  *  mounting the card (design/388 §2.5 boundary ①). */
 export declare const TOOL_APPROVAL_CARDS: readonly ["file-edit", "file-write", "notebook-edit", "shell", "fetch", "plan", "question", "generic"];
 export type ToolApprovalCard = (typeof TOOL_APPROVAL_CARDS)[number];
+/** Membership in the closed set — the one screen a stored or declared card word passes before it is read. */
+export declare function isToolApprovalCard(word: unknown): word is ToolApprovalCard;
+/** The cards only an engine-defined tool owns: a caller or protocol tool cannot declare one, and the card is minted
+ *  from the engine's own judgment of the call, never from a row's declaration. */
+export declare const RESERVED_APPROVAL_CARDS: readonly ["question", "plan"];
+export type ReservedApprovalCard = (typeof RESERVED_APPROVAL_CARDS)[number];
 /** How a path-targeting tool touches its target. `read` never enters a write-confinement face. */
 export declare const TOOL_PATH_ACCESSES: readonly ["read", "create", "edit"];
 export type ToolPathAccess = (typeof TOOL_PATH_ACCESSES)[number];
@@ -182,6 +188,7 @@ export interface ToolRenderHints {
     activity?: string;
     summaryParams?: readonly string[];
     resultCards?: readonly string[];
+    /** The card family this tool asks under; absent reads `generic`. `question` / `plan` are the engine's own tools' cards — a declaration of either is refused. */
     approvalCard?: ToolApprovalCard;
 }
 /**
@@ -217,6 +224,39 @@ export interface ToolFaceDeclaration {
     compactable?: true;
     budgetExempt?: true;
 }
+/**
+ * The kinds of leg a run can be, as far as which tools a leg itself relies on: a delegated child (every lane a delegation
+ * tool, a workflow or a team spawns), a NAMED delegated child (a teammate), an iteration of a goal loop, an observer sidecar,
+ * a run with an output schema (it finishes by submitting through the structured-output tool). A catalog row's
+ * {@link ToolCatalogEntry.protocol} names the kinds whose legs carry that tool as part of their protocol.
+ */
+export declare const TOOL_LEG_KINDS: readonly ["delegated", "teammate", "goal", "observer", "structured"];
+export type ToolLegKind = (typeof TOOL_LEG_KINDS)[number];
+/**
+ * One layer of a tool selector, as data: an allowed-tools list (absent = no allowlist on this layer) and a denied-tools list,
+ * each a frozen copy of the entries a list was written with. A run's own layer is its `allowTools` and `excludeTools`; the
+ * layers above it are the ones the run that spawned it was bounded by, plus that run's own.
+ */
+export interface ToolSelectorLayer {
+    readonly allow?: readonly string[];
+    readonly deny: readonly string[];
+}
+/**
+ * The compiled tool selector of one run — the one answer to "is this tool available on this run", read at the roster valve
+ * and on every later roster change (an MCP refresh or re-dial, the deferred-search lane), and handed down as the ceiling of
+ * every run this one spawns (`layers`). A tool is admitted when it is a protocol tool of this run's leg kind, or when every
+ * layer admits it: the layer's allowlist (if any) reaches it and its denylist does not.
+ */
+export interface ToolSelector {
+    readonly layers: readonly ToolSelectorLayer[];
+    admits(tool: {
+        readonly name: string;
+        readonly aliases?: readonly string[];
+    }): boolean;
+    /** Can ANY tool of the protocol peer whose minted prefix is `prefix` (`mcp__srv__`) be admitted — read off the lists alone,
+     *  never off what the peer lists now, so a tool the peer lists later is judged by the same answer. */
+    admitsPeer(prefix: string): boolean;
+}
 /**
  * One row of the static tool catalog (design/388 §2.1 "静态目录"). Keyed by DEFINITION identity, not by
  * name: two definitions may share a wire name (the full and the read-only shell both answer to `Bash`),
@@ -240,6 +280,13 @@ export interface ToolCatalogEntry {
     face: ToolFaceDeclaration;
     /** A `modelGate` class the default-bundle assembler stamps on this definition's default arm. */
     modelGate?: string;
+    /** The leg kinds whose legs rely on this tool as part of their protocol: on such a leg the tool's availability is not a
+     *  selector's to decide (an allowlist need not name it), and a denylist that reaches it there is a contradiction the run
+     *  refuses at prepare. */
+    protocol?: readonly ToolLegKind[];
+    /** A protocol row the leg shares with the run that spawned it (the team task-list family a teammate shares with its leader): on its
+     *  leg the leg's OWN lists do not decide it, but the ceiling still does — the leg holds it exactly when its spawner may. */
+    protocolUnderCeiling?: true;
 }
 /**
  * The band-membership table over the mount tags: a host derives its hand band as the definitions listed under a

package/dist/core/tool-face.js

@@ -1,6 +1,10 @@
 export const TOOL_FAMILIES = Object.freeze(["shell", "file-read", "file-write", "search", "web", "delegate", "plan", "scaffold", "memory", "protocol", "other"]);
 export const TOOL_MOUNT_TAGS = Object.freeze(["hands", "backgroundTasks", "workflow", "delegation", "hostInternals", "peerLane", "scheduler", "memory", "scenario", "always", "optional"]);
 export const TOOL_APPROVAL_CARDS = Object.freeze(["file-edit", "file-write", "notebook-edit", "shell", "fetch", "plan", "question", "generic"]);
+export function isToolApprovalCard(word) {
+    return typeof word === "string" && TOOL_APPROVAL_CARDS.includes(word);
+}
+export const RESERVED_APPROVAL_CARDS = Object.freeze(["question", "plan"]);
 export const TOOL_PATH_ACCESSES = Object.freeze(["read", "create", "edit"]);
 export const TOOL_PATH_BASES = Object.freeze(["cwd", "root"]);
 export const TOOL_PATH_ABSENCES = Object.freeze(["none", "base"]);
@@ -20,6 +24,7 @@ export const TOOL_KEYS_MAX = 1024;
 export const RENDER_HINT_MAX_CHARS = 64;
 export const RENDER_HINT_ACTIVITY_MAX_CHARS = 32;
 export const RENDER_HINT_MAX_LIST = 16;
+export const TOOL_LEG_KINDS = Object.freeze(["delegated", "teammate", "goal", "observer", "structured"]);
 export const MOUNT_TAG_IN_HANDS_BAND = {
     hands: true,
     backgroundTasks: true,

package/dist/core/tool-model-gate.d.ts

@@ -76,12 +76,12 @@ export declare function isModelGatedForClass(modelId: string, rule: ToolModelGat
 export declare function assertRestoreGatedToolsValue(value: unknown): asserts value is true | readonly string[] | undefined;
 /** Doors-facing decision (built + applied inside `prepareConfigDoors`' synchronous stretch —
  *  decision and application share one atomic window, no drift gap). */
-export interface ToolModelGateDecision {
+export interface ToolModelGateDecision<T extends ToolSpec = ToolSpec> {
     /** Present ⇔ at least one entry was removed: the fresh, PRIVATE survivor array `spec.tools` is
      *  rebound to (a caller mutating its original live array afterwards can neither re-add a removed
      *  entry nor displace anything — there are no indices left to misalign). `undefined` = no
      *  removal, the spec is left untouched. */
-    survivors: ToolSpec[] | undefined;
+    survivors: T[] | undefined;
     /** gate-class → removed wire names (sorted, unique) — the removal-notice payload. */
     removedByClass: ReadonlyMap<string, readonly string[]>;
     /** Stamped classes with no row in the merged table — announce-once material (the loud half of
@@ -116,10 +116,10 @@ export interface ToolModelGateDecision {
  *  - the exclusion valve (`excludeTools`, applied downstream at the roster splice) ALWAYS wins in
  *    the result: no restore channel resurrects an excluded name.
  */
-export declare function applyToolModelGate(input: {
-    tools: ReadonlyArray<ToolSpec> | undefined;
+export declare function applyToolModelGate<T extends ToolSpec>(input: {
+    tools: ReadonlyArray<T> | undefined;
     modelId: string;
     depsSeat: unknown;
     restoreGated: true | readonly string[] | undefined;
     envRaw: string | undefined;
-}): ToolModelGateDecision;
+}): ToolModelGateDecision<T>;

package/dist/core/tool-name-aliases.d.ts

@@ -10,8 +10,9 @@ import { type ProtocolNamespace } from "./protocol-table.js";
  *    rather than carried.
  *  - `canonicalToolName` is gone with it: with the mapping cleared it was the identity function, and
  *    keeping an identity shim invites the next mapping to grow back silently.
- *  - `TOMBSTONED_TOOLS` (per-name re-education messages) is gone: a retired name now gets the same
- *    loud generic roster miss as any unknown tool.
+ *  - `TOMBSTONED_TOOLS` (a second table of per-name re-education prose) is gone. A CALL to a retired name is
+ *    told what the one table here says about it ({@link judgeToolNameMiss}): the miss is `expected-absent`
+ *    with the successor, where any other unknown name stays the generic roster miss.
  *
  * What REMAINS is validation data: {@link RETIRED_TOOL_NAMES} maps every name the engine ever
  * retired to a one-line guidance string, and {@link judgeRuleToolName} is the ONE reading of it a rule's
@@ -78,8 +79,31 @@ export declare function splitNamespacedName(name: string): {
 } | undefined;
 /** See {@link RuleToolNameVerdict}. Pure; the one answer to "is this rule's tool name a name that reaches no tool". */
 export declare function judgeRuleToolName(name: string, roster: ReadonlySet<string>): RuleToolNameVerdict;
+/** The two kinds of tool-name miss — a closed set. `unknown`: the name is none the engine ever mounted (a typo, a
+ *  guess). `expected-absent`: the name is one the engine RETIRED ({@link RETIRED_TOOL_NAMES}), so its absence is no
+ *  surprise and the table says what replaced it (CC 2.1.296 spells the same two words for its render-time miss). */
+export declare const TOOL_MISS_KINDS: readonly ["unknown", "expected-absent"];
+declare const UNKNOWN_MISS: "unknown", ABSENT_MISS: "expected-absent";
+/** What {@link judgeToolNameMiss} answers: the kind (a {@link TOOL_MISS_KINDS} word) and, for `expected-absent`, the clause. */
+export type ToolNameMiss = {
+    readonly kind: typeof UNKNOWN_MISS;
+} | {
+    readonly kind: typeof ABSENT_MISS;
+    readonly detail: string;
+    readonly successor?: string;
+};
+/**
+ * The answer to "a call named `name` matched nothing in `roster`" — the ONE place a tool-call miss is classified:
+ * `expected-absent` (with the model-facing `detail`) for a retired name, `unknown` for everything else. It reads the
+ * table through {@link judgeRuleToolName}, so a rule's tool name and a call's tool name are judged by the same reading.
+ * The detail is the successor (`renamed "<name>"`) when the table names one AND this run mounts it — a successor the
+ * roster lacks (plan mode, no shell) is named as unavailable, never offered as the way forward, and is not returned as
+ * `successor` — else the table's own line (`folded into …` / `removed — …`), the grammar in the module header.
+ */
+export declare function judgeToolNameMiss(name: string, roster: ReadonlySet<string>): ToolNameMiss;
 /** The names a run mounts — every tool's primary name and its aliases: the roster {@link judgeRuleToolName} is given. */
 export declare function mountedToolNames(tools: ReadonlyArray<{
     readonly name: string;
     readonly aliases?: readonly string[];
 }>): Set<string>;
+export {};

package/dist/core/tool-name-aliases.js

@@ -80,6 +80,19 @@ export function judgeRuleToolName(name, roster) {
         return carriesNamespaceSeparator(name) ? UNPREFIXED : CURRENT;
     return unmintableSegmentOf(split) ?? CURRENT;
 }
+export const TOOL_MISS_KINDS = Object.freeze(["unknown", "expected-absent"]);
+const [UNKNOWN_MISS, ABSENT_MISS] = TOOL_MISS_KINDS;
+export function judgeToolNameMiss(name, roster) {
+    const v = judgeRuleToolName(name, roster);
+    if (v.kind !== "retired")
+        return { kind: UNKNOWN_MISS };
+    const next = v.currentName;
+    if (next === undefined)
+        return { kind: ABSENT_MISS, detail: v.guidance };
+    if (!roster.has(next))
+        return { kind: ABSENT_MISS, detail: `renamed to "${next}", which this run does not mount` };
+    return { kind: ABSENT_MISS, detail: `renamed to "${next}"`, successor: next };
+}
 export function mountedToolNames(tools) {
     return new Set(tools.flatMap((t) => [t.name, ...(t.aliases ?? [])]));
 }

package/dist/core/tool-name-list.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The one reading and the one snapshot of a host-written tool-name list (an agent definition's allowed-tools or denied-tools list,
+ * a tool's alias list, a model-id list). The judge before the run, the spawn-time filter, the memory content-origin face and the
+ * roster snapshot all meet a list through here, so a hostile container is answered once and the same way everywhere.
+ */
+/** A fixed label of a host value's TYPE for a sentence that must not print or convert the value (`typeof` and the array test only). */
+export declare function valueTypeLabel(value: unknown): string;
+/**
+ * How a tool-name list's VALUE (an agent definition's allowed-tools or denied-tools list) reads as a list. A host that reads its
+ * definitions from a file can hand over anything, and a list can be hostile as a container (an accessor or a proxy trap that
+ * throws, an overridden iterator, holes): it is read BY INDEX over its length, once, into a dense copy — no iterator of the host
+ * runs, a hole reads as `undefined` (an entry that is not a string) — and a value that is not an array, or an array whose read
+ * throws, is reported as such and never printed or converted.
+ */
+export type ToolNameListReading = {
+    readonly kind: "entries";
+    readonly entries: readonly unknown[];
+} | {
+    readonly kind: "not_a_list";
+    readonly type: string;
+} | {
+    readonly kind: "unreadable";
+};
+/** What the mount keeps of a list it could not read: one frozen marker, so the judgment and every later reader meet the same
+ *  failure and never read the host's container again (a list that throws once and answers afterwards must not pass the second look). */
+export declare const UNREADABLE_LIST: object;
+export declare function readToolNameList(value: unknown): ToolNameListReading;
+/** A tool-name list as the mount keeps it: the dense copy when it reads as a list, the failure marker when it cannot be read, else
+ *  the value itself (not a list: the judge refuses it, and its type never changes). */
+export declare function snapshotToolNameList(value: unknown): unknown;

package/dist/core/tool-name-list.js

@@ -0,0 +1,55 @@
+export function valueTypeLabel(value) {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "string":
+            return "a string";
+        case "undefined":
+            return "undefined";
+        case "number":
+            return "a number";
+        case "boolean":
+            return "a boolean";
+        case "bigint":
+            return "a bigint";
+        case "symbol":
+            return "a symbol";
+        case "function":
+            return "a function";
+        default:
+            try {
+                return Array.isArray(value) ? "an array" : "an object";
+            }
+            catch {
+                return "an object";
+            }
+    }
+}
+const isList = (value) => Array.isArray(value);
+export const UNREADABLE_LIST = Object.freeze({});
+export function readToolNameList(value) {
+    if (value === UNREADABLE_LIST)
+        return { kind: "unreadable" };
+    let list;
+    try {
+        list = isList(value) ? value : undefined;
+    }
+    catch {
+        return { kind: "not_a_list", type: "an object" };
+    }
+    if (list === undefined)
+        return { kind: "not_a_list", type: valueTypeLabel(value) };
+    try {
+        const entries = [];
+        for (let i = 0; i < list.length; i++)
+            entries.push(list[i]);
+        return { kind: "entries", entries };
+    }
+    catch {
+        return { kind: "unreadable" };
+    }
+}
+export function snapshotToolNameList(value) {
+    const read = readToolNameList(value);
+    return read.kind === "entries" ? read.entries : read.kind === "unreadable" ? UNREADABLE_LIST : value;
+}

package/dist/core/tool-name-readings.d.ts

@@ -193,10 +193,6 @@ export declare const NAME_READINGS: {
         readonly rank: "tier";
         readonly file: string;
     };
-    readonly "park.syncFirstRoute": {
-        readonly kind: "wire";
-        readonly file: string;
-    };
     readonly "report.riskAxes": {
         readonly kind: "seat";
         readonly rank: "tier";
@@ -259,11 +255,7 @@ export declare const NAME_READINGS: {
         readonly kind: "wire";
         readonly file: string;
     };
-    readonly "park.contentKindProjection": {
-        readonly kind: "wire";
-        readonly file: string;
-    };
-    readonly "resume.contentAskRow": {
+    readonly "card.reserved": {
         readonly kind: "wire";
         readonly file: string;
     };

package/dist/core/tool-name-readings.js

@@ -49,7 +49,6 @@ export const NAME_READINGS = {
     "offer.marks": seat("tier", OFFER),
     "offer.marks.egress": any(OFFER),
     "park.riskDescriptor": seat("tier", PARK),
-    "park.syncFirstRoute": wire(PARK),
     "report.riskAxes": seat("tier", CHAIN),
     "report.riskAxes.egress": any(CHAIN),
     "report.riskAxes.negatives": seat("member", CHAIN),
@@ -65,8 +64,7 @@ export const NAME_READINGS = {
     "reconcile.orphanEffect": spelling("src/core/session-reconcile.ts"),
     "inherited.questionFloat": wire(CHAIN),
     "inherited.askFace": wire(CHAIN),
-    "park.contentKindProjection": wire("src/core/checkpoint-store.ts"),
-    "resume.contentAskRow": wire("src/core/runner/decide-continuation.ts"),
+    "card.reserved": wire("src/core/tool-roster.ts"),
     "resume.editRecheckQuestionSkip": wire("src/core/runner/resume-apply.ts"),
     "resume.questionArgsShown": wire("src/core/runner/run-leg.ts"),
     "budget.exemptResult": wire("src/core/tool-result-budget.ts"),