@sema-agent/core 7.7.0 → 7.8.0

package/dist/core/mcp.js

@@ -18,6 +18,7 @@ import { discloseReminderShaped, observeReminderMarkEcho } from "./reminder-disc
 import { withContentOrigin } from "./memory-engine/content-origin.js";
 import { snapshotMcpEntries } from "./locked-config.js";
 import { validateJsonSchemaShape } from "./runner/strict-output-schema.js";
+import { schemaKeyBoundProblem } from "./tool-roster.js";
 export const MCP_PREFIX = MCP_NAMESPACE.prefix;
 const MCP_OUTPUT_TOKENS_DEFAULT = 25_000;
 const MCP_CHARS_PER_TOKEN = 4;
@@ -1513,7 +1514,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             effectiveInputSchema = normalized.schema;
             effectiveDescription = normalized.note + (effectiveDescription ? `\n\n${effectiveDescription}` : "");
         }
-        const schemaProblem = mcpToolSchemaProblem(effectiveInputSchema);
+        const schemaProblem = mcpToolSchemaProblem(effectiveInputSchema) ?? schemaKeyBoundProblem(effectiveInputSchema);
         if (schemaProblem !== undefined) {
             dropped.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(schemaProblem, 240) });
             continue;
@@ -1551,6 +1552,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             parameters: (effectiveInputSchema ?? { type: "object" }),
             ...(mcpMaxResultSizeChars !== undefined ? { mcpMaxResultSizeChars } : {}),
             ...(mcpAlwaysLoad ? { mcpAlwaysLoad: true } : {}),
+            mcpRemoteName: remoteName,
             execute: async (_toolCallId, params, signal) => {
                 const what = `The call to tool ${inlineUntrusted(remoteName)}`;
                 if (isServerRevoked?.(spec.name) === true) {

package/dist/core/memory-engine/tools.js

@@ -6,6 +6,7 @@ import { formatMemoryAge } from "../memory-recall.js";
 import { committedOriginOf } from "./frontmatter.js";
 import { MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, MEMORY_PROVENANCE_INDEX_SENTENCE, MEMORY_PROVENANCE_SEARCH_SENTENCE, MEMORY_SEARCH_BAND_ORDER_HEADER } from "./provenance-wording.js";
 import { deriveSupersededSet, memorySupersededNote, MEMORY_SEARCH_SUPERSEDED_TAG } from "./consolidation.js";
+import { toolFace } from "../tool-catalog-entries.js";
 export const MEMORY_SEARCH_TOOL_NAME = "memory_search";
 export const MEMORY_GET_TOOL_NAME = "memory_get";
 export const MEMORY_INDEX_TOOL_NAME = "memory_index";
@@ -175,11 +176,8 @@ export function createMemoryEngineTools(opts) {
     };
     const searchTool = {
         name: MEMORY_SEARCH_TOOL_NAME,
+        ...toolFace("memory-search"),
         description: carry ? `${SEARCH_DESCRIPTION}\n\n${MEMORY_PROVENANCE_SEARCH_SENTENCE}` : SEARCH_DESCRIPTION,
-        effect: "read",
-        offload: false,
-        contentOrigin: "local",
-        contract: { contractId: "core.memory_search@1", implementationRevision: "6" },
         parameters: Type.Object({
             query: Type.String({ description: "Keywords to look for (lexical match against entry names, descriptions and bodies)." }),
             limit: Type.Optional(Type.Number({ description: `Maximum hits to return (default ${MEMORY_SEARCH_DEFAULT_LIMIT}, max ${MEMORY_SEARCH_MAX_LIMIT}).` })),
@@ -319,11 +317,8 @@ export function createMemoryEngineTools(opts) {
     };
     const getTool = {
         name: MEMORY_GET_TOOL_NAME,
+        ...toolFace("memory-get"),
         description: GET_DESCRIPTION,
-        effect: "read",
-        offload: false,
-        contentOrigin: "local",
-        contract: { contractId: "core.memory_get@1", implementationRevision: "6" },
         parameters: Type.Object({
             id: Type.Optional(Type.String({ description: "Entry id (exact lookup). Pass either id or slug, not both." })),
             slug: Type.Optional(Type.String({ description: "Entry slug (its file path without .md). Ambiguous across scopes unless scope is also passed." })),
@@ -545,11 +540,8 @@ export function createMemoryEngineTools(opts) {
     };
     const indexTool = {
         name: MEMORY_INDEX_TOOL_NAME,
+        ...toolFace("memory-index"),
         description: carry ? `${INDEX_DESCRIPTION}\n\n${MEMORY_PROVENANCE_INDEX_SENTENCE}` : INDEX_DESCRIPTION,
-        effect: "read",
-        offload: false,
-        contentOrigin: "local",
-        contract: { contractId: "core.memory_index@1", implementationRevision: "1" },
         parameters: Type.Object({
             offset: Type.Optional(Type.Number({ description: "Zero-based row offset into the listing (default 0) — pass the previous page's footer value to continue." })),
             limit: Type.Optional(Type.Number({ description: `Maximum rows for this page (default ${MEMORY_INDEX_PAGE_ROWS}, max ${MEMORY_INDEX_MAX_PAGE_ROWS}).` })),

package/dist/core/permission-rules.d.ts

@@ -43,6 +43,11 @@ export interface PermissionRuleIssue {
     /** `invalid.*` = 语法/语义错;`unsupported.*` = CC 合法但 v1 不支持的 lane(独立
      *  分类,绝不静默 no-op —— `Bash(npm run:*)` 被当 generic 参数规则接受后永不匹配是最危险的失败形态)。 */
     code: "invalid.empty_tool" | "invalid.paren" | "invalid.param_split" | "invalid.allow_param_rule" | "invalid.primary_field" | "invalid.cap_exceeded" | "unsupported.bash_prefix"
+    /** design/388 B15 — the closed rule-lint set over a tool's RULE FACE (derived scalar vocabulary; a
+     *  declaration only narrows it): the named parameter is not one the tool carries; it is carried but
+     *  is an object/array (a rule on it can never match); the tool is unknown to the resolver a leg
+     *  supplied (absent resolver ⇒ the catalog alone judges and an unknown tool stays permissive). */
+     | "unsupported.param_unknown" | "unsupported.param_non_scalar" | "unsupported.tool_unknown"
     /** design/179 D7: a Bash prefix rule under `bashPrefixLane:"rules-store"` — reported so a migration
      *  report can tell "route this through the rule store" apart from "this is a mistake". */
      | "unsupported.bash_prefix_rules_store" | "unsupported.file_glob" | "unsupported.mcp_paren"
@@ -98,6 +103,13 @@ export interface PermissionRulePolicyOptions {
      */
     bashPrefixLane?: "reject" | "rules-store";
     caps?: Partial<PermissionRuleCaps>;
+    /**
+     * design/388 B15 — the leg's RULE-FACE resolver (typically `ruleFacesFromRoster(prepared.toolRoster)`): with it
+     * every tool on the leg is judged — MCP and caller tools included — and a rule naming a tool the leg does not
+     * mount is `unsupported.tool_unknown`. Without it the static catalog alone judges; a tool the catalog does not
+     * carry stays permissive (a rule for it compiles unjudged).
+     */
+    ruleFaces?: (toolName: string) => RuleFaceView | undefined;
 }
 /**
  * Parse one rule string — CC `Lh` :55214 parity, including its lenient downgrades (malformed parens /
@@ -134,11 +146,29 @@ export declare function namespacedRuleNameCovers(ruleName: string, toolName: str
  *  — i.e. the shapes {@link namespacedRuleNameCovers} answers and an exact name table cannot. Every
  *  lane that keys rules by exact tool name needs this to know which entries it must NOT key that way. */
 export declare function isNamespacedCoveringRuleName(name: string): boolean;
-/** Exported for the lockstep guard only (see {@link FILE_TOOL_PARAMS}) — not part of the rule DSL. */
+/**
+ * design/388 A-6/7/8/9 (D-3): the per-tool RULE FACE — the parameters a `Tool(param:pattern)` rule may name
+ * (`params`, the SCALAR top-level keys ∪ the path target's aliases), the ones the generic lexical matcher must
+ * not be pointed at (`primaryParams`), the carried-but-non-scalar keys a rule can never match (`nonScalar`), and
+ * whether the tool names a path target at all (the file-tool glob lane). Resolved through
+ * {@link PermissionRulePolicyOptions.ruleFaces} when a leg supplies its roster, else from the static catalog
+ * — the three hand-kept tables (`PRIMARY_FIELDS` / `FILE_TOOLS` / `FILE_TOOL_PARAMS`) this replaced are gone.
+ */
+export interface RuleFaceView {
+    primaryParams: readonly string[];
+    /** The full scalar vocabulary; ABSENT when the resolver does not know it (the static catalog for a
+     *  definition whose schema is factory-built) — then only the primary-field check applies. */
+    params?: readonly string[];
+    nonScalar?: readonly string[];
+    pathTargeting?: boolean;
+}
+/** The static catalog's answer for a wire name (undefined ⇒ the catalog does not carry it). */
+export declare function catalogRuleFaceView(toolName: string): RuleFaceView | undefined;
+/** Exported for the lockstep guard only (the scalar vocabulary of a catalog tool) — not part of the rule DSL. */
 export declare const fileToolParamVocabulary: (canonicalTool: string) => ReadonlySet<string> | undefined;
 /** Dry-run 校验/迁移报告:不 throw,返回全部 issues(含 `unsupported.*` 分类,
  *  供从 CC settings 迁移的部署逐条对照)。 */
-export declare function validatePermissionRules(rules: PermissionRule[], opts?: Pick<PermissionRulePolicyOptions, "primaryFieldGeneric" | "caps" | "bashPrefixLane">): PermissionRuleIssue[];
+export declare function validatePermissionRules(rules: PermissionRule[], opts?: Pick<PermissionRulePolicyOptions, "primaryFieldGeneric" | "caps" | "bashPrefixLane" | "ruleFaces">): PermissionRuleIssue[];
 /**
  * Compile declarative permission rules into ONE {@link ToolPolicy} (design/127). Evaluation order
  * inside the policy (CC `G1e` :595272 isomorph): bare deny → param deny → bare ask → param ask →

package/dist/core/permission-rules.js

@@ -1,5 +1,6 @@
 import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
-export const BASH_GENERIC_PARAMS = new Set(["command", "timeout", "description", "run_in_background"]);
+import { catalogRuleFaceOf, pathTargetOf } from "./tool-registry.js";
+export const BASH_GENERIC_PARAMS = new Set(catalogRuleFaceOf("Bash")?.params ?? []);
 const DEFAULT_CAPS = {
     maxRules: 256,
     maxRuleLength: 512,
@@ -107,31 +108,16 @@ export function isNamespacedCoveringRuleName(name) {
     const parsed = parseNamespacedRuleName(name);
     return parsed !== undefined && (parsed.tool === undefined || parsed.tool.includes("*"));
 }
-const PRIMARY_FIELDS = {
-    Bash: new Set(["command"]),
-    Read: new Set(["file_path", "path"]),
-    Edit: new Set(["file_path", "path"]),
-    Write: new Set(["file_path", "path"]),
-    MultiEdit: new Set(["file_path", "path"]),
-    NotebookEdit: new Set(["notebook_path", "path"]),
-    Grep: new Set(["path"]),
-    Glob: new Set(["path"]),
-    WebFetch: new Set(["url"]),
-    WebSearch: new Set(["query"]),
-};
-const FILE_TOOLS = new Set(["Read", "Edit", "Write", "MultiEdit", "NotebookEdit", "Grep", "Glob"]);
-const FILE_TOOL_PARAMS = {
-    Read: new Set(["file_path", "path", "offset", "limit", "pages"]),
-    Edit: new Set(["file_path", "path", "old_string", "new_string", "replace_all"]),
-    Write: new Set(["file_path", "path", "content"]),
-    NotebookEdit: new Set(["notebook_path", "path", "cell_id", "cell_type", "edit_mode", "new_source"]),
-    Grep: new Set([
-        "pattern", "path", "glob", "type", "output_mode", "head_limit", "offset",
-        "multiline", "context", "ignore_case", "-i", "-n", "-o", "-A", "-B", "-C",
-    ]),
-    Glob: new Set(["pattern", "path", "max_results"]),
+export function catalogRuleFaceView(toolName) {
+    const face = catalogRuleFaceOf(toolName);
+    if (face === undefined)
+        return undefined;
+    return { ...face, pathTargeting: pathTargetOf(toolName) !== undefined };
+}
+export const fileToolParamVocabulary = (canonicalTool) => {
+    const face = catalogRuleFaceOf(canonicalTool);
+    return face?.params === undefined || pathTargetOf(canonicalTool) === undefined ? undefined : new Set(face.params);
 };
-export const fileToolParamVocabulary = (canonicalTool) => FILE_TOOL_PARAMS[canonicalTool];
 function countStars(s) {
     let n = 0;
     for (const c of s)
@@ -139,7 +125,15 @@ function countStars(s) {
             n++;
     return n;
 }
-function compile(rules, caps, primaryFieldGeneric, bashPrefixLane = "reject") {
+function compile(rules, caps, primaryFieldGeneric, bashPrefixLane = "reject", ruleFaces) {
+    const faceOf = (toolName) => {
+        if (ruleFaces !== undefined) {
+            const face = ruleFaces(toolName);
+            return { face, judged: true };
+        }
+        const face = catalogRuleFaceView(toolName);
+        return { face, judged: face !== undefined };
+    };
     const byTool = new Map();
     const namespacedCovering = { deny: [], ask: [], allow: [] };
     const issues = [];
@@ -209,18 +203,30 @@ function compile(rules, caps, primaryFieldGeneric, bashPrefixLane = "reject") {
                 continue;
             }
         }
-        else if (FILE_TOOLS.has(toolName)) {
-            if (colon <= 0) {
-                bad(text, "unsupported.file_glob", "file-tool glob rules (`Edit(src/**)`) are the tool-specific lane — not supported by the generic param DSL");
+        else {
+            const resolved = faceOf(toolName);
+            if (resolved.judged && resolved.face === undefined) {
+                bad(text, "unsupported.tool_unknown", `"${toolName}" is not a tool on this leg's roster — the rule would compile and never match`);
                 continue;
             }
-            const paramPart = content.slice(0, colon).trim();
-            const vocabulary = FILE_TOOL_PARAMS[toolName];
-            if (vocabulary !== undefined && !vocabulary.has(paramPart)) {
-                bad(text, "unsupported.unknown_param", `"${paramPart}" is not a parameter of ${toolName} (it carries ${[...vocabulary].sort().join(", ")}) — the rule would compile and never match. ` +
-                    `For a path glob use the tool-specific lane (\`${toolName}(src/**)\` is not the generic param DSL); a Windows path such as \`${toolName}(C:/foo)\` parses as the param "C".`);
+            const face = resolved.face;
+            if (face !== undefined && face.pathTargeting === true && colon <= 0) {
+                bad(text, "unsupported.file_glob", "file-tool glob rules (`Edit(src/**)`) are the tool-specific lane — not supported by the generic param DSL");
                 continue;
             }
+            if (face?.params !== undefined && colon > 0) {
+                const paramPart = content.slice(0, colon).trim();
+                if (!face.params.includes(paramPart)) {
+                    if (face.nonScalar?.includes(paramPart)) {
+                        bad(text, "unsupported.param_non_scalar", `"${paramPart}" is a parameter of ${toolName} but its value is an object or an array — the generic matcher compares scalars only; the rule would compile and never match`);
+                    }
+                    else {
+                        bad(text, "unsupported.param_unknown", `"${paramPart}" is not a parameter of ${toolName} (it carries ${[...face.params].sort().join(", ")}) — the rule would compile and never match. ` +
+                            `For a path glob use the tool-specific lane (\`${toolName}(src/**)\` is not the generic param DSL); a Windows path such as \`${toolName}(C:/foo)\` parses as the param "C".`);
+                    }
+                    continue;
+                }
+            }
         }
         if (colon <= 0) {
             bad(text, "invalid.param_split", "param-level ruleContent must be `param:pattern`");
@@ -240,7 +246,7 @@ function compile(rules, caps, primaryFieldGeneric, bashPrefixLane = "reject") {
             bad(text, "invalid.cap_exceeded", `pattern exceeds maxPatternLength ${caps.maxPatternLength} or maxStars ${caps.maxStars}`);
             continue;
         }
-        if (PRIMARY_FIELDS[toolName]?.has(param) && primaryFieldGeneric === "reject") {
+        if (faceOf(toolName).face?.primaryParams.includes(param) === true && primaryFieldGeneric === "reject") {
             bad(text, "invalid.primary_field", `"${param}" is ${toolName}'s primary field — the generic matcher is a trim+FULL-STRING lexical match (no shell/path semantics); '${toolName}(${param}:git push*)' would NOT match 'cd /x && git push'. Opt in with primaryFieldGeneric:"allow-lexical" if you understand this.`);
             continue;
         }
@@ -251,7 +257,7 @@ function compile(rules, caps, primaryFieldGeneric, bashPrefixLane = "reject") {
 }
 export function validatePermissionRules(rules, opts) {
     const caps = { ...DEFAULT_CAPS, ...opts?.caps };
-    return compile(rules, caps, opts?.primaryFieldGeneric ?? "reject", opts?.bashPrefixLane ?? "reject").issues;
+    return compile(rules, caps, opts?.primaryFieldGeneric ?? "reject", opts?.bashPrefixLane ?? "reject", opts?.ruleFaces).issues;
 }
 function isPlainObjectArgs(args) {
     return typeof args === "object" && args !== null && !Array.isArray(args);
@@ -281,7 +287,7 @@ function ruleMessage(kind, ruleText, source) {
 }
 export function createPermissionRulePolicy(rules, opts) {
     const caps = { ...DEFAULT_CAPS, ...opts?.caps };
-    const { byTool, namespacedCovering, issues } = compile(rules, caps, opts?.primaryFieldGeneric ?? "reject", opts?.bashPrefixLane ?? "reject");
+    const { byTool, namespacedCovering, issues } = compile(rules, caps, opts?.primaryFieldGeneric ?? "reject", opts?.bashPrefixLane ?? "reject", opts?.ruleFaces);
     const setLevelCap = issues.some((i) => i.code === "invalid.cap_exceeded" && i.rule === "");
     if (issues.length > 0 && ((opts?.onInvalidRule ?? "throw") === "throw" || setLevelCap)) {
         const e = new Error(`createPermissionRulePolicy: ${issues.length} invalid/unsupported rule(s):\n` +

package/dist/core/present-plan-tool.js

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
 import { delimitUntrusted } from "./untrusted-text.js";
+import { toolFace } from "./tool-catalog-entries.js";
 export const PRESENT_PLAN_TOOL_NAME = "ExitPlanMode";
 export const ENTER_PLAN_MODE_TOOL_NAME = "EnterPlanMode";
 const ENTER_PLAN_MODE_DESCRIPTION = `Enter PLAN MODE (read-only): stop making changes and switch to exploration/planning. For the rest of this run, write/edit/mutating tool calls are REJECTED while read-only tools (Read, Grep, Glob, etc.) still work. When your plan is ready, call ${PRESENT_PLAN_TOOL_NAME} with it — the run PAUSES for a human to approve it, then continues (read-only lifted) so you can execute.
@@ -31,10 +32,9 @@ BAD: "Fix the typo in the README" (trivial; nothing to align on). "Remove the le
 export function createEnterPlanModeTool(enterPlanMode) {
     return {
         name: ENTER_PLAN_MODE_TOOL_NAME,
-        contract: { contractId: "core.enter_plan_mode@1", implementationRevision: "1" },
+        ...toolFace("enter-plan-mode"),
         description: ENTER_PLAN_MODE_DESCRIPTION,
         parameters: Type.Object({}),
-        effect: "read",
         executionMode: "sequential",
         execute: async () => {
             enterPlanMode();
@@ -61,14 +61,13 @@ const PRESENT_PLAN_DESCRIPTION = [
 export function createPresentPlanTool(requestReview) {
     return {
         name: PRESENT_PLAN_TOOL_NAME,
-        contract: { contractId: "core.exit_plan_mode@1", implementationRevision: "1" },
+        ...toolFace("exit-plan-mode"),
         description: PRESENT_PLAN_DESCRIPTION,
         parameters: Type.Object({
             plan: Type.String({
                 description: "Your full proposed plan, in markdown. The human reviewer approves / edits / rejects it before you act.",
             }),
         }),
-        effect: "read",
         execute: async (args) => {
             const { plan } = args;
             requestReview({ reason: "ExitPlanMode" });

package/dist/core/runner/active-skill-scope.js

@@ -1,4 +1,5 @@
-import { canonicalizeTarget, fileArgPath } from "../../tools/fs/safety.js";
+import { canonicalizeTarget } from "../../tools/fs/safety.js";
+import { pathTargetValue } from "../tool-registry.js";
 import { PATH_WRITE_TOOLS, isWithin } from "./session-rule-policy.js";
 import { parseSkillToolEntry, skillSpecifierRejection } from "../skill-tool-specifier.js";
 export class ActiveSkillScope {
@@ -74,7 +75,9 @@ export function createActiveSkillScopePolicy(opts) {
                 }
             }
             const pathConstrainingActive = manifests.some((m) => m.allowPaths && m.allowPaths.length > 0);
-            if (pathConstrainingActive && !PATH_WRITE_TOOLS.has(toolName)) {
+            const declaredTarget = req.face?.pathTarget;
+            const skillScopeEligible = declaredTarget !== undefined && declaredTarget.skillScopeEligible === true;
+            if (pathConstrainingActive && !skillScopeEligible) {
                 const eff = toolEffects?.get(toolName) ?? "write";
                 if (eff !== "read") {
                     const ids = manifests.filter((m) => m.allowPaths?.length).map((m) => m.lineageId).join(", ");
@@ -85,10 +88,10 @@ export function createActiveSkillScopePolicy(opts) {
                     };
                 }
             }
-            if (PATH_WRITE_TOOLS.has(toolName)) {
+            if (skillScopeEligible) {
                 const constraining = manifests.filter((m) => m.allowPaths && m.allowPaths.length > 0);
                 if (constraining.length > 0) {
-                    const path = fileArgPath(req.args);
+                    const path = pathTargetValue(req.args, declaredTarget);
                     if (typeof path !== "string" || path.length === 0) {
                         return {
                             action: "deny",

package/dist/core/runner/compaction-call-options.d.ts

@@ -15,7 +15,7 @@ import type { Prepared } from "./contracts.js";
  * end-of-task lane's deliberate ABSENCE of `signal`) is a legitimate per-lane difference and stays at
  * the call site, where its reason is written down.
  *
- * Every export is a free function: the turn-boundary lane assembles its call inside `makeTurnBoundary`
+ * Every export is a free function: the turn-boundary lane assembles its call inside `createTurnBoundary`
  * (a module-level function with no `this`), so a method would not be reachable from all three sites.
  * Nothing here reads or writes runner state — pure assembly over `spec` + `Prepared`.
  */

package/dist/core/runner/contracts.d.ts

@@ -718,7 +718,10 @@ export interface Prepared {
      *  the human already adjudicated it). Same wrapping (offload + ctx) the harness runs with.
      *
      *  ONE array, mutated in place; identity is the contract (every closure that resolves a name at run time
-     *  reads this exact array). WRITER TABLE (design/238 R-3) — the only stations that write it, in prepare order:
+     *  reads this exact array). Since design/388 the array is PRIVATE to the `RosterBuilder` (tool-roster.ts) —
+     *  every station below writes through its verbs (`mount` / `mountAll` / `unmountWhere` / `replaceAt` /
+     *  `replaceDomain`) and this field is the builder's read face. WRITER TABLE (design/238 R-3) — the only
+     *  stations that write it, in prepare order:
      *   · caps-and-workflow — MINTS it (`spec.tools` through the ctx wrap + the large-result wrapper), then pushes
      *     ReportBlocked (enableBlockedReport ≠ false), ReportFindings (no caller tool of that name/alias),
      *     ExitPlanMode + EnterPlanMode (enablePlanMode ∧ the plan-review face), Workflow (self-orchestration active
@@ -740,7 +743,28 @@ export interface Prepared {
      *     memory session or a recorder channel); the refresh seam re-runs the same pass through `contentOriginWrapRef`
      *     after a re-splice (identity-tracked, so a wrapper is never wrapped again).
      *  tool-disclosure and listings only READ it (`harnessTools` is a derived list; placeholders never enter here). */
-    tools: AgentTool[];
+    tools: readonly AgentTool[];
+    /**
+     * design/388 §2.5 — this leg's minted TOOL ROSTER (the same object `wiringManifest.tools` carries):
+     * one row per mounted instance in wire order. Minted ONCE at the prompt-assembly station (the same
+     * pass that projects the prompt manifest's tool rows, so the two agree by construction); the park
+     * station reads the gated call's identity off it, the exemption probe hands it to the host.
+     */
+    toolRoster: import("../tool-roster.js").ToolRoster;
+    /**
+     * design/388 §2.5 — the run-time delta seat: every roster change after prepare (the RefreshMcpTools
+     * seam) re-mints the roster here and publishes a `ToolRosterDelta`. The run loop subscribes at the
+     * point it emits `wiring_manifest` and forwards each delta as a `tool_roster_delta` event; until it
+     * does, deltas are buffered in order.
+     */
+    toolRosterDeltas: import("../tool-roster.js").ToolRosterDeltaSeat;
+    /**
+     * design/388 L4 — the leg's `tool_end.structured` projector: the engine card set ∪ the caller rows' declared
+     * `renderHints.resultCards`; an undeclared `details.type` is dropped and announced ONCE per leg
+     * (`config.tool_card_undeclared`). The run loop's tool_end body projection reads it in place of the
+     * module-level `structuredFrom` (which has no announce seat).
+     */
+    structuredProjector: (result: unknown) => unknown;
     /** Name→effect map for every tool this task can call (design/44 §3). Used by the abort-path orphan
      *  reconcile (design/64 §9) to make interrupted tool_results effect-aware (read/idempotent = safe to
      *  repeat; write/unknown = outcome unknown). Unknown names default to `write` (conservative). */
@@ -1985,7 +2009,7 @@ export interface ParkAsk {
  * Grouped by lifecycle semantics per the B15 pre-recon partition. Function members start as inert
  * placeholders and are assigned at their ORIGINAL declaration sites (the original code could not
  * call them earlier either — TDZ proved it). Not on the npm face; this extraction is what enabled
- * makeTurnBoundary / makeHarnessHandlers (三期, both in runtask.ts).
+ * createTurnBoundary / createHarnessHandlers (三期, both in runtask.ts).
  */
 export interface RunState {
     telemetry: {

package/dist/core/runner/prepare-ask-lane.d.ts

@@ -46,7 +46,7 @@ export interface PrepareAskLaneInput {
     handsCwdRef: CwdRef | undefined;
     /** borrowed-readonly — the shared mount roster; read at RUN time by the approval-preview projection (alias-aware
      *  lookup over whatever the roster holds when the ask is minted). Never mutated here. */
-    tools: AgentTool[];
+    tools: readonly AgentTool[];
     /** borrowed-mutable — the inherited-unavailable marker set. Writer here: `resolveAskBound` consumes (`delete`) a
      *  marked call at its fail-closed intercept; the policy-chain phase records, the gate station sweeps. */
     inheritedUnavailableAsks: Set<string>;

package/dist/core/runner/prepare-caps-and-workflow.d.ts

@@ -34,6 +34,7 @@ import type { AutoModeArmReason } from "../wiring-manifest.js";
 import type { ReadFace } from "../../tools/fs/index.js";
 import type { InheritedGate, Prepared, RunInternals, RunnerSelfSeat, ToolFaceSnapshot } from "./contracts.js";
 import { type BlockedRef } from "./synthetic-tools.js";
+import { RosterBuilder } from "../tool-roster.js";
 export interface PrepareCapsAndWorkflowInput {
     /** borrowed-readonly — the REBOUND spec, whole: the roster map reads `tools`; the mounts read `enableBlockedReport`,
      *  `enablePlanMode`, `interactiveTools`, `checkpointStore`; the caps/compliance stations read `principal`, `selfOrchestration`,
@@ -124,10 +125,10 @@ export interface PrepareCapsAndWorkflowInput {
     }>;
 }
 export interface PrepareCapsAndWorkflowResult {
-    /** owned — THE run's roster, minted here from the caller's tools; every later mount pushes into this same array
-     *  (`Prepared.tools`, whose JSDoc carries the writer table). Writers here: the map that mints it, then the ReportBlocked,
-     *  ReportFindings, ExitPlanMode, EnterPlanMode and Workflow pushes. */
-    tools: AgentTool[];
+    /** owned — THE run's roster BUILDER (design/388: the mount array is private to it; `Prepared.tools` is its read face,
+     *  whose JSDoc carries the writer table). Minted here from the caller's tools; every later mount goes through its verbs.
+     *  Writers here: the caller mounts, then the ReportBlocked, ReportFindings, ExitPlanMode, EnterPlanMode and Workflow mounts. */
+    roster: RosterBuilder;
     /** borrowed-mutable — the ReportBlocked tool's write seat (`Prepared.blockedRef`). Writer: the tool at run time; read at
      *  result assembly. */
     blockedRef: BlockedRef;

package/dist/core/runner/prepare-caps-and-workflow.js

@@ -2,7 +2,7 @@ import { isSyntheticApiErrorMessage } from "../../internal/harness.js";
 import { createHash } from "node:crypto";
 import { forkGovernanceDenial } from "../../agents/subagent.js";
 import { CROSS_SESSION_CLASSIFIER_RULE } from "../../agents/cross-session-envelope.js";
-import { createRunWorkflowTool, RUN_WORKFLOW_TOOL_NAME } from "../../orchestration/run-workflow-tool.js";
+import { createRunWorkflowTool } from "../../orchestration/run-workflow-tool.js";
 import { isSelfOrchestrationActive } from "../../orchestration/workflow-script-runner.js";
 import { resolveWorkflowSizeGuideline } from "../../orchestration/workflow-size-guideline.js";
 import { thinkingOffExpressible } from "../../brain/reasoning.js";
@@ -20,6 +20,7 @@ import { emitTrace } from "../trace.js";
 import { defineTool, isDefineToolProduct } from "../tools.js";
 import { derivedRouteFallsBack } from "./derived-route-fallback.js";
 import { REPORT_FINDINGS_TOOL_NAME, createReportBlockedTool, createReportFindingsTool } from "./synthetic-tools.js";
+import { RosterBuilder, callerMountSource } from "../tool-roster.js";
 function assembleParentCaptureState(o, i, ctl, ancestors) {
     const build = (optedOut, indeterminate) => ({
         optedOut: optedOut === true,
@@ -65,7 +66,12 @@ function autoModeArmReasonOf(intent, facePresent, capsAutoMode, capsFaulted) {
 }
 export async function prepareCapsAndWorkflow(input) {
     const { spec, deps, internals, session, sessionId, runId, hostTaskId, taskScope, taskRootFinal, model, thinking, lockedPreflight, toolEffects, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, harnessRef, frozenOnAsk, carrierReadFace, forwardEvent, inheritedGateForChildren, enrichSpecToolCtx, maybeOffload, requestReview, enterPlanMode, autoModeIntent, peerLaneActive, peerSendMessageBuiltIn, runnerSelf } = input;
-    const tools = (spec.tools ?? []).map((t) => {
+    const roster = new RosterBuilder(toolEffects);
+    for (const t of spec.tools ?? []) {
+        const mounted = mountCallerTool(t);
+        roster.mount(mounted, { source: callerMountSource(mounted), mountedBy: "scenario" });
+    }
+    function mountCallerTool(t) {
         if (isDefineToolProduct(t)) {
             return maybeOffload(t, t);
         }
@@ -73,20 +79,20 @@ export async function prepareCapsAndWorkflow(input) {
             ...t,
             execute: (args, ctx) => t.execute(args, enrichSpecToolCtx(ctx)),
         }), t);
-    });
+    }
     const blockedRef = {};
     if (spec.enableBlockedReport !== false) {
-        tools.push(createReportBlockedTool(blockedRef));
+        roster.mount(createReportBlockedTool(blockedRef), { source: "builtin", mountedBy: "always" });
     }
     if (!(spec.tools ?? []).some((t) => t.name === REPORT_FINDINGS_TOOL_NAME || t.aliases?.includes(REPORT_FINDINGS_TOOL_NAME))) {
-        tools.push(createReportFindingsTool());
+        roster.mount(createReportFindingsTool(), { source: "builtin", mountedBy: "always" });
     }
     if (spec.enablePlanMode === true && spec.interactiveTools !== false) {
         const planReviewFace = resolveCheckpointStore(spec, deps) !== undefined;
         if (spec.interactiveTools === true || planReviewFace) {
-            tools.push(defineTool(createPresentPlanTool(requestReview)));
+            roster.mount(defineTool(createPresentPlanTool(requestReview)), { source: "builtin", mountedBy: "optional" });
             if (planReviewFace) {
-                tools.push(defineTool(createEnterPlanModeTool(enterPlanMode)));
+                roster.mount(defineTool(createEnterPlanModeTool(enterPlanMode)), { source: "builtin", mountedBy: "optional" });
             }
         }
     }
@@ -210,8 +216,7 @@ export async function prepareCapsAndWorkflow(input) {
         workflowToolsActive = true;
         const currentSizeGuideline = () => resolveWorkflowSizeGuideline(deps.workflowLimits?.sizeGuideline).size;
         workflowSizeGuideline = { legGuideline: currentSizeGuideline(), current: currentSizeGuideline };
-        toolEffects.set(RUN_WORKFLOW_TOOL_NAME, "write");
-        tools.push(await createRunWorkflowTool({
+        roster.mount(await createRunWorkflowTool({
             runner: runnerSelf,
             scriptRunner: deps.workflowScriptRunner,
             governanceBaseline: deps.workflowGovernanceBaseline,
@@ -266,7 +271,7 @@ export async function prepareCapsAndWorkflow(input) {
             parentCenterSourceRevision: () => input.centerAdoption()?.sourceRevision,
             ...(forwardEvent ? { forwardEvent } : {}),
             inheritedGateForChildren,
-        }));
+        }), { source: "builtin", mountedBy: "workflow" });
     }
-    return { tools, blockedRef, runtimeCaps, runtimeCapsFaulted, complianceDenies, complianceDegraded, agentForkDenial, observersActive, autoModeArmReason, autoModeDecider, autoModeDenialTracking, autoModeArming, selfOrchestrationActive, workflowToolsActive, workflowSizeGuideline };
+    return { roster, blockedRef, runtimeCaps, runtimeCapsFaulted, complianceDenies, complianceDegraded, agentForkDenial, observersActive, autoModeArmReason, autoModeDecider, autoModeDenialTracking, autoModeArming, selfOrchestrationActive, workflowToolsActive, workflowSizeGuideline };
 }

package/dist/core/runner/prepare-defer-classify.d.ts

@@ -1,43 +1,22 @@
-/**
- * design/390 M11 — prepareTask's TOOL-FACE FOLD + DEFERRED CLASSIFICATION phase: the exclusion valve's
- * true unmount (in place, on the shared mount array), the full-shell anti-drift invariant, the classic-
- * profile description swap, `classifyDeferredOverFace` (the one classifier both counterfactual passes
- * run), the built-in memory pairs' support-name pre-check (sole-cause counterfactual, whole-group
- * retraction, the engine pair's recall paragraph stripped back out of the memory block) and the final
- * `deferred` set. The body is the driver's stretch moved verbatim (one exception, named below); the
- * interface is the dependency list it had implicitly (design/238 R-1).
- *
- * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between
- * the git-status probe before it and the content-origin wrap after it (design/390 §1.5 S1: a stretch
- * with no await is extracted as a sync function — an `async` wrapper would open a microtask window).
- *
- * The one non-move: the stretch used to write `sharedMemoryPairMounted = false` /
- * `memoryEnginePairMounted = false` on the retraction arm. Nothing reads either flag after this stretch
- * (the driver's next reader was this stretch's own pair derivation, which runs first), so the two dead
- * writes are not carried into the Result — the flags arrive as borrowed-readonly inputs.
- *
- * Throws pass through unchanged: `internal.full_shell_reachable_mismatch` (an engine invariant, never a
- * configuration error). The reserved-name refusal for a standing ToolSearch collision is NOT here — it
- * belongs to the disclosure mount downstream, which reads the `deferred` set this phase returns.
- */
-import type { AgentTool } from "../../internal/harness.js";
 import type { Model } from "../../internal/llm.js";
 import type { MaterializedA2a } from "../a2a.js";
 import type { MaterializedMcp } from "../mcp.js";
 import type { RunnerDeps, TaskSpec } from "../types.js";
 import type { AnnounceOnceSink, ToolFaceSnapshot } from "./contracts.js";
+import { RosterBuilder } from "../tool-roster.js";
 export interface PrepareDeferClassifyInput {
     /** borrowed-readonly — the REBOUND spec (`spec′`); only `tools` is read (the caller roster the
      *  classifier judges: names for the full-schema filter, specs for the `defer` declarations). */
-    spec: Pick<TaskSpec, "tools">;
+    spec: Pick<TaskSpec, "tools" | "excludeAllTools">;
     /** borrowed-readonly — deployment deps; only `deferMode` is read (the classifier's mode knob). */
     deps: Pick<RunnerDeps, "deferMode">;
     /** borrowed-mutable — the shared mount array (later refs alias it; in-place contract, never
      *  re-created). Mutated here, in order: `splice` of every excluded name; element REPLACEMENT with a
      *  shallow copy for the classic-profile description swap (the caller's ToolSpec object is never
      *  mutated); `splice` of a retracted memory group. After this phase: the content-origin wrap
-     *  (element replacement with the wrapped object), the disclosure mount, the MCP refresh re-splice. */
-    tools: AgentTool[];
+     *  (element replacement with the wrapped object), the disclosure mount, the MCP refresh re-splice. Since
+     *  design/388 every one of those writes is a builder verb (`unmountWhere` / `replaceAt`). */
+    roster: RosterBuilder;
     /** borrowed-readonly — the frozen task-start tool face: `exclude` (the valve), `defer` (operator
      *  defers, exact wire names), `alwaysLoad` (the inline pins). */
     toolFaceSnapshot: Pick<ToolFaceSnapshot, "exclude" | "defer" | "alwaysLoad">;

package/dist/core/runner/prepare-defer-classify.js

@@ -4,6 +4,7 @@ import { ASK_USER_QUESTION_TOOL_NAME } from "../ask-question.js";
 import { MEMORY_ENGINE_TOOL_NAMES } from "../memory-engine/tools.js";
 import { SHARED_MEMORY_TOOL_NAMES } from "../shared-memory/types.js";
 import { TOOL_SEARCH_NAME, classifyDeferred } from "./tool-disclosure.js";
+import { RosterBuilder } from "../tool-roster.js";
 function explicitlyDeferredMemoryTrio(mounted, roster, deferNames) {
     return mounted ? MEMORY_ENGINE_TOOL_NAMES.filter((n) => roster.some((t) => t.name === n) && (deferNames ?? []).includes(n)) : [];
 }
@@ -11,13 +12,15 @@ function memoryGroupRetractionSet(builtinDeferPairNames, engineTrioInPlay) {
     return new Set([...builtinDeferPairNames, ...(engineTrioInPlay ? MEMORY_ENGINE_TOOL_NAMES : [])]);
 }
 export function prepareDeferClassify(input) {
-    const { spec, deps, tools, toolFaceSnapshot, handsEnabled, fullShellReachable, promptProfile, model, mcp, a2a, sharedMemoryPairMounted, memoryEnginePairMounted, memoryRecallSegment, onceLedger, sessionId } = input;
+    const { spec, deps, roster, toolFaceSnapshot, handsEnabled, fullShellReachable, promptProfile, model, mcp, a2a, sharedMemoryPairMounted, memoryEnginePairMounted, memoryRecallSegment, onceLedger, sessionId } = input;
+    const tools = roster.tools;
     let memoryBlock = input.memoryBlock;
-    if (toolFaceSnapshot.exclude !== undefined && toolFaceSnapshot.exclude.length > 0) {
+    if (spec.excludeAllTools === true) {
+        roster.unmountWhere(() => true);
+    }
+    else if (toolFaceSnapshot.exclude !== undefined && toolFaceSnapshot.exclude.length > 0) {
         const excluded = new Set(toolFaceSnapshot.exclude);
-        for (let i = tools.length - 1; i >= 0; i--)
-            if (excluded.has(tools[i].name))
-                tools.splice(i, 1);
+        roster.unmountWhere((t) => excluded.has(t.name));
     }
     if (handsEnabled) {
         const fullShellOnRoster = tools.some((t) => t.name === "Bash" && getToolContract(t, "core").contractId === FULL_SHELL_CONTRACT_ID);
@@ -33,7 +36,7 @@ export function prepareDeferClassify(input) {
         for (let i = 0; i < tools.length; i++) {
             const t = tools[i];
             if (t.descriptionClassic !== undefined)
-                tools[i] = { ...t, description: t.descriptionClassic };
+                roster.replaceAt(i, { ...t, description: t.descriptionClassic });
         }
     }
     const userToolNames = (spec.tools ?? []).map((t) => t.name);
@@ -73,10 +76,7 @@ export function prepareDeferClassify(input) {
         const supportNameTaken = tools.some((t) => t.name === TOOL_SEARCH_NAME || (t.aliases ?? []).includes(TOOL_SEARCH_NAME));
         if (soleCause && supportNameTaken) {
             const retractNames = memoryGroupRetractionSet(builtinDeferPairNames, memoryEnginePair.length > 0);
-            for (let i = tools.length - 1; i >= 0; i--) {
-                if (retractNames.has(tools[i].name))
-                    tools.splice(i, 1);
-            }
+            roster.unmountWhere((t) => retractNames.has(t.name));
             if (sharedMemoryPair.length > 0) {
                 onceLedger.onError(new Error(`Shared memory tools ${SHARED_MEMORY_TOOL_NAMES.join("/")} were NOT mounted: mounting them would inject ` +
                     `the "${TOOL_SEARCH_NAME}" tool, whose name this task already declares — the pair mounts together or not at all.`), { phase: "config", sessionId, classification: "shared-memory-not-mounted" });