@sema-agent/core 7.7.0 → 7.8.0

package/dist/core/runner/session-rule-policy.js

@@ -1,8 +1,9 @@
 import { canonicalizeTarget, writeTargetPath } from "../../tools/fs/safety.js";
 import { isWinFormPath } from "../../tools/fs/safety.js";
 import { createCoarseCommandNamePolicy, namespacedCoveringEntries, namespacedCoveringHit } from "../tool-policy.js";
-export const PATH_WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit"]);
-export const PATH_CONFINABLE_WRITE_TOOLS = new Set([...PATH_WRITE_TOOLS, "NotebookEdit"]);
+import { declaredPathTargetOf, isProtectedWrite, pathConfinableWriteToolNames, skillScopeWriteToolNames } from "../tool-registry.js";
+export const PATH_WRITE_TOOLS = skillScopeWriteToolNames();
+export const PATH_CONFINABLE_WRITE_TOOLS = pathConfinableWriteToolNames();
 export function isWithin(root, p) {
     if (!root)
         return false;
@@ -49,14 +50,18 @@ export function createSessionRulePolicy(rules, opts) {
                     return d;
             }
             if (allowDirs) {
-                if (!PATH_CONFINABLE_WRITE_TOOLS.has(toolName)) {
+                if (!isProtectedWrite(req)) {
                     const eff = toolEffects?.get(toolName) ?? "write";
                     if (eff !== "read") {
                         return deny(`write-capable tool "${req.toolName}" denied: session rule confines writes to allowDirs but this tool cannot be path-confined`);
                     }
                 }
                 else {
-                    const path = writeTargetPath(toolName, req.args);
+                    const declared = declaredPathTargetOf(req);
+                    if (declared === undefined) {
+                        return deny(`write tool "${req.toolName}" denied: session rule confines writes to allowDirs but the tool declares no path target to confine`);
+                    }
+                    const path = writeTargetPath(req, declared);
                     if (typeof path !== "string" || path.length === 0) {
                         return deny(`write tool "${req.toolName}" denied: session rule confines writes to allowDirs but the call has no resolvable path`);
                     }

package/dist/core/runner/synthetic-tools.js

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { defineTool } from "../tools.js";
 import { sanitizeUntrustedText, SHELLED_BODY_ENVELOPE_TAGS } from "../untrusted-text.js";
+import { toolFace } from "../tool-catalog-entries.js";
 export const OUTPUT_TOOL_NAME = "StructuredOutput";
 export const REPORT_BLOCKED_TOOL_NAME = "ReportBlocked";
 export const REPORT_FINDINGS_TOOL_NAME = "ReportFindings";
@@ -15,10 +16,9 @@ export function resolveOutputRetries(outputRetries) {
 export function createOutputTool(ref, schema, strictSchema) {
     return defineTool({
         name: OUTPUT_TOOL_NAME,
-        contract: { contractId: "core.structured_output@1", implementationRevision: "1" },
+        ...toolFace("structured-output"),
         description: "Call this to submit your FINAL result as a JSON object matching the required schema. The arguments " +
             "ARE the result. Calling this ends the task. Do this once you have the answer (use other tools first if needed).",
-        effect: "read",
         parameters: strictSchema ?? schema,
         execute: (args) => {
             ref.value = args;
@@ -30,9 +30,8 @@ export function createOutputTool(ref, schema, strictSchema) {
 export function createReportBlockedTool(ref) {
     return defineTool({
         name: REPORT_BLOCKED_TOOL_NAME,
-        contract: { contractId: "core.report_blocked@1", implementationRevision: "1" },
+        ...toolFace("report-blocked"),
         description: "Call this ONLY when you cannot complete the task — missing information, missing permission/credentials, or an ambiguous request you cannot resolve. Provide a concise reason that an external system or operator can act on. Calling this ends the task.",
-        effect: "read",
         parameters: Type.Object({ reason: Type.String() }),
         execute: (args) => {
             ref.reason = String(args.reason ?? "").trim() || "blocked";
@@ -59,14 +58,13 @@ const REPORT_FINDING_SCHEMA = Type.Object({
 export function createReportFindingsTool() {
     return defineTool({
         name: REPORT_FINDINGS_TOOL_NAME,
-        contract: { contractId: "core.report_findings@1", implementationRevision: "1" },
+        ...toolFace("report-findings"),
         description: "Report code-review findings as a typed list so the host UI can render them. Use this only when the " +
             "active code-review instructions tell you to report findings with this tool; otherwise follow whatever " +
             "output format those instructions specify. When reporting a review's results, call it once with the " +
             "verified findings ranked most-severe first (empty array if nothing survived verification) and do not " +
             "also print the findings as text. When re-reporting after applying fixes (only if the apply " +
             "instructions ask for it), set `outcome` on each finding to what actually happened.",
-        effect: "read",
         parameters: Type.Object({
             level: Type.Optional(Type.Union([Type.Literal("low"), Type.Literal("medium"), Type.Literal("high"), Type.Literal("xhigh"), Type.Literal("max")], { description: "Effort level the review ran at" })),
             findings: Type.Array(REPORT_FINDING_SCHEMA, {
@@ -177,7 +175,7 @@ export function createSkillTool(skills, scope) {
     const names = skills.map((s) => s.name).join(", ");
     return defineTool({
         name: SKILL_TOOL_NAME,
-        contract: { contractId: "core.skill@1", implementationRevision: "1" },
+        ...toolFace("skill"),
         description: `Invoke a skill.\n\n` +
             `A skill is a packaged set of instructions the user or project has set up for a particular kind of task (deploy steps, a review checklist, a repo-specific workflow). ` +
             `Available skills appear in a system-reminder listing with one-line descriptions. ` +
@@ -192,7 +190,6 @@ export function createSkillTool(skills, scope) {
             skill: Type.String({ description: 'The skill name. E.g., "commit", "review-pr", or "pdf"' }),
             args: Type.Optional(Type.String({ description: "Optional arguments for the skill" })),
         }),
-        effect: "read",
         execute: (rawArgs) => {
             const a = (rawArgs ?? {});
             const name = String(a.skill ?? "");

package/dist/core/runner/tool-disclosure.d.ts

@@ -39,6 +39,9 @@ export interface DeferredToolInfo {
     name: string;
     hint: string;
     description: string;
+    /** The real tool's aliases — a placeholder stands for the tool under EVERY name it answers to, so dispatch by
+     *  alias resolves to the same slot before and after activation (and the roster's name→row resolution agrees). */
+    aliases?: readonly string[];
 }
 /** First line of a description, trimmed to a single short hint for a placeholder / announcement. */
 export declare function deferHint(description: string, max?: number): string;
@@ -90,6 +93,7 @@ export declare function classifyDeferred(opts: {
 export declare function buildDeferredRegistry(deferred: ReadonlySet<string>, tools: ReadonlyArray<{
     name: string;
     description: string;
+    aliases?: readonly string[];
 }>): Map<string, DeferredToolInfo>;
 /**
  * RB-403 — the direct-call lane a placeholder may carry. The upstream defer gate is SHAPE

package/dist/core/runner/tool-disclosure.js

@@ -3,6 +3,7 @@ import { Value } from "typebox/value";
 import { defineTool, errorResult } from "../tools.js";
 import { formatZodValidationError, truncateError } from "../tool-errors.js";
 import { DEFAULT_CHARS_PER_TOKEN } from "../../internal/harness.js";
+import { toolFace } from "../tool-catalog-entries.js";
 export const TOOL_SEARCH_NAME = "ToolSearch";
 const DEFER_AUTO_FRACTION = 0.1;
 const CHARS_PER_TOKEN = DEFAULT_CHARS_PER_TOKEN;
@@ -62,7 +63,7 @@ export function buildDeferredRegistry(deferred, tools) {
     const reg = new Map();
     for (const t of tools) {
         if (deferred.has(t.name))
-            reg.set(t.name, { name: t.name, hint: deferHint(t.description), description: t.description });
+            reg.set(t.name, { name: t.name, hint: deferHint(t.description), description: t.description, ...(t.aliases !== undefined && t.aliases.length > 0 ? { aliases: [...t.aliases] } : {}) });
     }
     return reg;
 }
@@ -127,6 +128,7 @@ export function createPlaceholderTool(info, direct) {
     if (direct !== undefined) {
         return {
             name: info.name,
+            ...(info.aliases !== undefined ? { aliases: [...info.aliases] } : {}),
             label: info.name,
             description: `${info.hint} — deferred: its parameters are not listed here. Call ` +
                 `${TOOL_SEARCH_NAME}({"query":"select:${sn}"}) to load them; a call that already matches this ` +
@@ -156,6 +158,7 @@ export function createPlaceholderTool(info, direct) {
     }
     return defineTool({
         name: info.name,
+        ...(info.aliases !== undefined ? { aliases: [...info.aliases] } : {}),
         description: `${info.hint} — deferred: call ${TOOL_SEARCH_NAME}({"query":"select:${sn}"}) to load its parameters before use.`,
         parameters: EMPTY_PARAMS,
         effect: "read",
@@ -263,8 +266,10 @@ export function extractDiscoveredToolNames(messages, registry) {
                 const resolved = resolveToolSearch(part.arguments, registry);
                 pendingSearch.set(part.id, prior === undefined ? resolved : [...prior, ...resolved]);
             }
-            else if (registry.has(part.name)) {
-                pendingDirect.set(part.id, part.name);
+            else {
+                const canonical = registry.has(part.name) ? part.name : [...registry.values()].find((i) => i.aliases?.includes(part.name))?.name;
+                if (canonical !== undefined)
+                    pendingDirect.set(part.id, canonical);
             }
         }
     }
@@ -299,7 +304,7 @@ export function createToolSearchTool(opts) {
         });
     return defineTool({
         name: TOOL_SEARCH_NAME,
-        contract: { contractId: "core.tool_search@1", implementationRevision: "1" },
+        ...toolFace("tool-search"),
         description: "Discover and activate deferred tools. " +
             activationPosture +
             "Query forms: " +
@@ -317,7 +322,6 @@ export function createToolSearchTool(opts) {
             })),
             max_results: Type.Optional(Type.Number({ description: "Maximum number of results to return (default: 5)" })),
         }),
-        effect: "read",
         execute: async (raw) => {
             const staleSelect = (raw ?? {});
             if (staleSelect.select !== undefined) {

package/dist/core/runner/tool-end-body.js

@@ -2,6 +2,7 @@ import {} from "../../internal/harness.js";
 import { MCP_DELIVERY_VERDICTS } from "../mcp-failure.js";
 import { TOOL_SEARCH_NAME } from "./tool-disclosure.js";
 import { structuredFrom, toolOutputFrom } from "./tool-output-projection.js";
+import { TASK_CREATE_TOOL_NAME, TASK_UPDATE_TOOL_NAME, TODO_WRITE_TOOL_NAME } from "../tool-catalog-entries.js";
 const BATCH_RESPONSE_MAX_CHARS = 500;
 export function batchResponseDigest(result) {
     const content = result !== null && typeof result === "object" ? result.content : result;
@@ -54,9 +55,9 @@ export function reconciledToolEndBody(orphan) {
     return toolEndBodyFrom({ content: orphan.text, details: { code: orphan.errorKind } }, true);
 }
 export function writeFamilyOfCanonical(name) {
-    if (name === "TaskCreate" || name === "TaskUpdate")
+    if (name === TASK_CREATE_TOOL_NAME || name === TASK_UPDATE_TOOL_NAME)
         return "task";
-    if (name === "TodoWrite")
+    if (name === TODO_WRITE_TOOL_NAME)
         return "todo";
     if (name === TOOL_SEARCH_NAME)
         return "tool_search";

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

@@ -0,0 +1,40 @@
+/**
+ * design/388 §1.1 / §2.7 — the MCP `toolFaces` OVERLAY: a deployment's per-tool face declaration for a
+ * protocol tool that has no `ToolSpec` of its own (`McpServerSpec.toolFaces`, keyed by the server's RAW
+ * tool name like `allowTools` / `toolAxes`). Validated against the MATERIALIZED schema at every listing
+ * (the first mount and every RefreshMcpTools): `pathTarget.param` must be a top-level property; an
+ * `approvalCard` must find the keys the card needs; a `ruleFace` may only name scalar keys; `family`
+ * must be a member of the closed set. A failing overlay does NOT mount — the tool mounts BARE (no
+ * face) and the leg announces `config.tool_face_invalid` once per tool; a `toolFaces` key naming a
+ * tool the listing does not carry announces `config.tool_face_undeclared` once per name. Never a
+ * silent partial application: an overlay is one declaration, applied whole or not at all.
+ *
+ * Prepare-path machinery (layer 1): pure over the tool objects and the server specs; the notice sink
+ * is a parameter.
+ */
+import type { AgentTool } from "../../internal/harness-types.js";
+import type { McpServerSpec } from "../mcp-server-spec.js";
+import { type ToolApprovalCard } from "../tool-face.js";
+import { type EngineNotice } from "../engine-notice.js";
+/** The keys each specialised approval card needs on the call (design/388 §2.5 boundary ①: the SHELL owns the
+ *  card's full schema; this is the pre-filter the overlay is validated against). */
+export declare const APPROVAL_CARD_REQUIRED_KEYS: Readonly<Record<ToolApprovalCard, readonly string[]>>;
+export type McpToolFace = NonNullable<McpServerSpec["toolFaces"]>[string];
+/** Why an overlay is refused — a closed reason list, each a distinct declaration mistake. */
+export declare function toolFaceProblem(face: McpToolFace, schema: AgentTool["parameters"]): string | undefined;
+export interface ApplyToolFacesInput {
+    /** The materialized tools of ONE server (namespaced names). */
+    tools: readonly AgentTool[];
+    server: Pick<McpServerSpec, "name" | "toolFaces">;
+    /** The leg's notice sink and its once-per-leg ledger (keys: `invalid:<name>` / `undeclared:<server>/<raw>`). */
+    onNotice: ((notice: EngineNotice) => void) | undefined;
+    announced: Set<string>;
+    sessionId: string;
+    runId: string;
+}
+/** Apply the server's overlay to its tools: a validated face is stamped on a COPY of the tool object (the same
+ *  untyped carry `defineTool` uses, so the roster reads it off the instance). A face that does NOT fit the materialized
+ *  schema is a bad declaration: the tool is NOT mounted on this leg (announced once, `config.tool_face_invalid`) —
+ *  mounting it bare would silently drop the write protection the operator declared for it (an MCP name has no catalog
+ *  floor), and a schema refresh that invalidates only a display hint must fail loud, never open. */
+export declare function applyMcpToolFaces(input: ApplyToolFacesInput): AgentTool[];

package/dist/core/runner/tool-face-overlay.js

@@ -0,0 +1,125 @@
+import { MCP_NAMESPACE } from "../protocol-table.js";
+import { mintNamespacePrefix } from "../protocol-naming.js";
+import { TOOL_APPROVAL_CARDS, TOOL_FAMILIES, RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_CHARS, RENDER_HINT_MAX_LIST, TOOL_KEY_MAX_CHARS } from "../tool-face.js";
+import { inputKeysOf } from "../tool-roster.js";
+import { deliverEngineNotice } from "../engine-notice.js";
+export const APPROVAL_CARD_REQUIRED_KEYS = Object.freeze({
+    "file-edit": ["file_path"],
+    "file-write": ["file_path"],
+    "notebook-edit": ["notebook_path"],
+    shell: ["command"],
+    fetch: ["url"],
+    plan: [],
+    question: [],
+    generic: [],
+});
+export function toolFaceProblem(face, schema) {
+    const { keys, scalar } = inputKeysOf(schema);
+    const top = new Set(keys.map((k) => k.name));
+    if (face.family !== undefined && !TOOL_FAMILIES.includes(face.family))
+        return `family ${JSON.stringify(face.family)} is outside the closed set`;
+    const overlong = (label, values) => {
+        const k = values.find((v) => v.length > TOOL_KEY_MAX_CHARS);
+        return k === undefined ? undefined : `${label} ${JSON.stringify(k.slice(0, 40) + "…")} is ${k.length} characters; a roster key is at most ${TOOL_KEY_MAX_CHARS}`;
+    };
+    const vocabulary = new Set(scalar);
+    if (face.pathTarget !== undefined) {
+        if (typeof face.pathTarget.param !== "string" || !top.has(face.pathTarget.param))
+            return `pathTarget.param ${JSON.stringify(face.pathTarget.param)} is not a top-level property of the tool's schema`;
+        if (!["read", "create", "edit"].includes(face.pathTarget.access))
+            return `pathTarget.access ${JSON.stringify(face.pathTarget.access)} is outside the closed set`;
+        const long = overlong("pathTarget.param", [face.pathTarget.param]) ?? overlong("pathTarget.aliases", face.pathTarget.aliases ?? []);
+        if (long !== undefined)
+            return long;
+        vocabulary.add(face.pathTarget.param);
+        for (const a of face.pathTarget.aliases ?? [])
+            vocabulary.add(a);
+    }
+    const hints = face.renderHints;
+    if (hints !== undefined) {
+        const card = hints.approvalCard;
+        if (card !== undefined) {
+            if (!TOOL_APPROVAL_CARDS.includes(card))
+                return `renderHints.approvalCard ${JSON.stringify(card)} is outside the closed set`;
+            const missing = APPROVAL_CARD_REQUIRED_KEYS[card].filter((k) => !top.has(k));
+            if (missing.length > 0)
+                return `renderHints.approvalCard ${JSON.stringify(card)} needs ${missing.join(", ")} on the tool's schema`;
+        }
+        if (hints.userFacingName !== undefined && hints.userFacingName.length > RENDER_HINT_MAX_CHARS)
+            return `renderHints.userFacingName is ${hints.userFacingName.length} characters; the bound is ${RENDER_HINT_MAX_CHARS}`;
+        if (hints.activity !== undefined && hints.activity.length > RENDER_HINT_ACTIVITY_MAX_CHARS)
+            return `renderHints.activity is ${hints.activity.length} characters; the bound is ${RENDER_HINT_ACTIVITY_MAX_CHARS}`;
+        if ((hints.summaryParams?.length ?? 0) > RENDER_HINT_MAX_LIST)
+            return `renderHints.summaryParams lists ${hints.summaryParams.length} entries; the bound is ${RENDER_HINT_MAX_LIST}`;
+        if ((hints.resultCards?.length ?? 0) > RENDER_HINT_MAX_LIST)
+            return `renderHints.resultCards lists ${hints.resultCards.length} entries; the bound is ${RENDER_HINT_MAX_LIST}`;
+        const long = overlong("renderHints.summaryParams", hints.summaryParams ?? []) ?? overlong("renderHints.resultCards", hints.resultCards ?? []);
+        if (long !== undefined)
+            return long;
+        const stray = (hints.summaryParams ?? []).find((p) => !top.has(p));
+        if (stray !== undefined)
+            return `renderHints.summaryParams names ${JSON.stringify(stray)}, which is not a top-level property`;
+    }
+    for (const p of face.ruleFace?.params ?? [])
+        if (!vocabulary.has(p))
+            return `ruleFace.params names ${JSON.stringify(p)}, which is neither a scalar top-level property nor the declared path target`;
+    for (const p of face.ruleFace?.primaryParams ?? [])
+        if (!vocabulary.has(p))
+            return `ruleFace.primaryParams names ${JSON.stringify(p)}, which is neither a top-level property nor the declared path target`;
+    const long = overlong("ruleFace.params", face.ruleFace?.params ?? []) ?? overlong("ruleFace.primaryParams", face.ruleFace?.primaryParams ?? []);
+    if (long !== undefined)
+        return long;
+    return undefined;
+}
+export function applyMcpToolFaces(input) {
+    const faces = input.server.toolFaces;
+    if (faces === undefined)
+        return [...input.tools];
+    const prefix = mintNamespacePrefix(MCP_NAMESPACE, input.server.name);
+    const accepted = new Set(input.tools.filter((t) => t.name.startsWith(prefix)).map((t) => t.mcpRemoteName).filter((r) => typeof r === "string"));
+    for (const raw of Object.keys(faces)) {
+        if (accepted.has(raw))
+            continue;
+        const key = `undeclared:${input.server.name}/${raw}`;
+        if (input.announced.has(key))
+            continue;
+        input.announced.add(key);
+        deliverEngineNotice(input.onNotice, {
+            code: "config.tool_face_undeclared",
+            message: `MCP server "${input.server.name}": toolFaces declares a face for "${raw}", which the server's tool listing does not carry — the declaration is inert`,
+            detail: { server: input.server.name, tool: raw, sessionId: input.sessionId, runId: input.runId },
+        });
+    }
+    return input.tools.flatMap((t) => {
+        const stamped = stampOne(t);
+        return stamped === undefined ? [] : [stamped];
+    });
+    function stampOne(t) {
+        const raw = t.mcpRemoteName;
+        const face = raw !== undefined && t.name.startsWith(prefix) ? faces?.[raw] : undefined;
+        if (raw === undefined || face === undefined)
+            return t;
+        const hit = { raw, face };
+        const problem = toolFaceProblem(hit.face, t.parameters);
+        if (problem !== undefined) {
+            const key = `invalid:${t.name}`;
+            if (!input.announced.has(key)) {
+                input.announced.add(key);
+                deliverEngineNotice(input.onNotice, {
+                    code: "config.tool_face_invalid",
+                    message: `MCP server "${input.server.name}": the toolFaces overlay for "${hit.raw}" does not fit the tool's materialized schema (${problem}) — the tool is NOT mounted until the overlay fits (mounting it bare would drop the protection the overlay declares)`,
+                    detail: { server: input.server.name, tool: hit.raw, problem, sessionId: input.sessionId, runId: input.runId },
+                });
+            }
+            return undefined;
+        }
+        const f = hit.face;
+        return {
+            ...t,
+            ...(f.family !== undefined ? { family: f.family } : {}),
+            ...(f.pathTarget !== undefined ? { pathTarget: f.pathTarget } : {}),
+            ...(f.renderHints !== undefined ? { renderHints: f.renderHints } : {}),
+            ...(f.ruleFace !== undefined ? { ruleFace: f.ruleFace } : {}),
+        };
+    }
+}

package/dist/core/runner/tool-output-projection.d.ts

@@ -9,4 +9,14 @@ export declare const toolOutputFrom: (result: unknown) => {
     truncated: boolean;
     totalChars?: number;
 } | undefined;
+/**
+ * L4's run-time half (design/388 §2.4): a per-leg projector — the engine card set plus the leg's declared
+ * caller cards — that DROPS an undeclared `details.type` exactly as the module-level gate does and announces
+ * it ONCE per leg (`config.tool_card_undeclared`, audience operator). The module-level {@link structuredFrom}
+ * is this projector over the engine set alone, with no announce seat.
+ */
+export declare function createStructuredProjector(opts: {
+    declaredCards?: Iterable<string>;
+    onUndeclared?: (type: string) => void;
+}): (result: unknown) => unknown;
 export declare const structuredFrom: (result: unknown) => unknown;

package/dist/core/runner/tool-output-projection.js

@@ -1,3 +1,4 @@
+import { engineCardTypes } from "../tool-registry.js";
 const MAX_TOOL_END_OUTPUT_CHARS = 16384;
 const safeJsonLength = (v) => {
     try {
@@ -56,16 +57,38 @@ export const toolOutputFrom = (result) => {
     }
     return { output: raw, truncated: true, totalChars };
 };
-const CC_DETAIL_TYPES = new Set([
-    "ask-question",
-    "edit", "create", "update", "bash", "notebook-edit", "notebook", "file_unchanged", "worktree", "text", "grep", "glob", "mcp",
-    "agent", "task", "task-list", "task-output", "workflow-run",
-    "web-fetch", "web-search", "todo", "cron-create", "cron-delete", "cron-list", "image",
-    "task-stop", "tool-search", "repo-map", "fork", "enter-plan-mode", "exit-plan-mode",
-    "monitor-start", "path_not_in_root", "read_path_denied", "readonly_out_of_root", "bash_invalid_timeout",
-    "report-findings", "schedule-wakeup", "send-message", "agent-transcript", "a2a", "document",
-    "list-agents",
-]);
+const CC_DETAIL_TYPES = engineCardTypes();
+export function createStructuredProjector(opts) {
+    const allowed = new Set([...CC_DETAIL_TYPES, ...(opts.declaredCards ?? [])]);
+    const announced = new Set();
+    return (result) => {
+        const details = result !== null && typeof result === "object" ? result.details : undefined;
+        if (details === null || typeof details !== "object")
+            return undefined;
+        const t = details.type;
+        if (typeof t !== "string")
+            return undefined;
+        if (!allowed.has(t)) {
+            if (opts.onUndeclared !== undefined && !announced.has(t)) {
+                announced.add(t);
+                opts.onUndeclared(t);
+            }
+            return undefined;
+        }
+        return boundedCard(details);
+    };
+}
+function boundedCard(details) {
+    try {
+        const serialized = JSON.stringify(details) ?? "";
+        if (serialized.length > MAX_TOOL_END_OUTPUT_CHARS * 4)
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    return details;
+}
 export const structuredFrom = (result) => {
     const details = result !== null && typeof result === "object" ? result.details : undefined;
     if (details === null || typeof details !== "object")

package/dist/core/sensitive-path-policy.d.ts

@@ -1,5 +1,8 @@
 import type { ExecutionEnv } from "../internal/harness-types.js";
 import type { ToolPolicy } from "./tool-policy.js";
+/** fs hand tools that take a `path` and write — the reliably-guardable surface. NotebookEdit joined
+ *  in [886]①a (mirror of the fs-write-gate's covered set): its target is `notebook_path`, and a
+ *  guard that ignored notebook writes to the same paths by default was the same hole one tool away. */
 /**
  * RECOMMENDED default pattern set for {@link createSensitivePathPolicy} (additive export).
  * NO upstream verbatim anchor exists (cc-anchors/2.1.209 carries no sensitive/dangerous file-pattern

package/dist/core/sensitive-path-policy.js

@@ -2,7 +2,7 @@ import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { canonicalizeTarget, expandHomeTilde, isAbsolutePathForm, isWinFormPath, writeTargetPath } from "../tools/fs/safety.js";
 import { compileSegmentPattern, matchSegmentPatterns } from "../tools/fs/read-deny.js";
-const DEFAULT_GUARDED_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
+import { isProtectedWrite } from "./tool-registry.js";
 export const RECOMMENDED_SENSITIVE_PATTERNS = [
     ".env",
     ".env.*",
@@ -90,13 +90,14 @@ export function createSensitivePathPolicy(opts) {
         }
         return keys;
     };
-    const guarded = new Set(opts.tools ?? DEFAULT_GUARDED_TOOLS);
+    const guardedByName = opts.tools !== undefined ? new Set(opts.tools) : undefined;
     return {
         async check(req, signal) {
-            const canonical = req.toolName;
-            if (compiled.length === 0 || !guarded.has(canonical))
+            if (compiled.length === 0)
                 return { action: "allow" };
-            const path = writeTargetPath(canonical, req.args);
+            if (guardedByName !== undefined ? !guardedByName.has(req.toolName) : !isProtectedWrite(req))
+                return { action: "allow" };
+            const path = writeTargetPath(req);
             if (typeof path !== "string" || path.length === 0)
                 return { action: "allow" };
             const canon = await canonicalizeTarget(opts.env, path, signal, req.cwd ?? opts.rootPath);

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

@@ -2,6 +2,7 @@ import { Type } from "typebox";
 import { errorResult } from "../tools.js";
 import { CONNECTING_MESSAGE, GENERIC_FAILURE_MESSAGE, NO_STORES_MESSAGE, SHARED_STORE_FRAME, UNAVAILABLE_MESSAGE, datePrefixOf, echoUntrusted, foldReaderError, listPrefixArgument, normalizeEntries, normalizeMemoryPath, normalizeReadValue, normalizeSnapshot, pageDocuments, relativePathRefusal, sanitizeSharedContent, validateDocumentPath, validatePathPrefix, } from "./normalize.js";
 import { SHARED_MEMORY_LIST_PAGE_SIZE, SHARED_MEMORY_LIST_TOOL_NAME, SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_READ_TOOL_NAME, } from "./types.js";
+import { toolFace } from "../tool-catalog-entries.js";
 const LIST_HINT = "List shared memory stores and their documents — check here before telling the user you do not have something.";
 const LIST_DESCRIPTION = [
     LIST_HINT,
@@ -125,11 +126,9 @@ export function createSharedMemoryTools(opts) {
     };
     const listTool = {
         name: SHARED_MEMORY_LIST_TOOL_NAME,
+        ...toolFace("memory-list"),
         description: LIST_DESCRIPTION,
-        effect: "read",
         defer: true,
-        offload: false,
-        contract: { contractId: "core.memory_list@1", implementationRevision: "1" },
         parameters: Type.Object({
             store: Type.Optional(Type.String({
                 description: "Id of the connected memory store to list. Omit to list the memory stores connected to this session (id, description, and writable or read-only).",
@@ -258,11 +257,9 @@ export function createSharedMemoryTools(opts) {
     };
     const readTool = {
         name: SHARED_MEMORY_READ_TOOL_NAME,
+        ...toolFace("memory-read"),
         description: READ_DESCRIPTION,
-        effect: "read",
         defer: true,
-        offload: false,
-        contract: { contractId: "core.memory_read@1", implementationRevision: "1" },
         parameters: Type.Object({
             store: Type.String({
                 description: `Id of the connected memory store to read from (call ${SHARED_MEMORY_LIST_TOOL_NAME} with no arguments to see the connected stores).`,

package/dist/core/store-contracts/checkpoint-store-contract.js

@@ -301,6 +301,29 @@ export async function checkpointStoreContract(make, runAssertion) {
         const stored = (await store.get(bitless.token)).pendingAction;
         assert.equal("hasBidiControls" in stored, false, "projection backfill must not write back to the row");
     });
+    run("design/388 B18 × B6 identity + face group: a row's seven optional members (capabilityId/contractId/shapeDigest/implementationRevision/rosterDigest + family/pathTarget) survive the round-trip verbatim; an absent group stays absent", async () => {
+        const store = make();
+        const carried = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "id-carried" });
+        const group = {
+            capabilityId: "caller::Write@acme.write@2",
+            contractId: "acme.write@2",
+            shapeDigest: "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+            implementationRevision: "r7",
+            rosterDigest: "sha256:fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
+            family: "file-write",
+            pathTarget: { param: "destination", aliases: ["path"], access: "create", skillScopeEligible: true },
+        };
+        Object.assign(carried.pendingAction, group);
+        const bare = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "id-bare" });
+        for (const cp of [carried, bare])
+            await store.put(cp.token, cp);
+        const back = (await store.get(carried.token)).pendingAction;
+        for (const [k, v] of Object.entries(group))
+            assert.deepEqual(back[k], v, `the row's ${k} must survive the round-trip verbatim (a whitelisting serializer that drops it makes every resume-edit recheck judge by the catalog's slot for the NAME)`);
+        const bareBack = (await store.get(bare.token)).pendingAction;
+        for (const k of Object.keys(group))
+            assert.equal(k in bareBack, false, `an absent ${k} must stay OMITTED (a pre-388 row reads name-only, never a partial face)`);
+    });
     run("#457 previewWithheld three-form matrix: a row's spelling survives + projects; absent stays absent; an out-of-contract spelling reads as absent", async () => {
         const store = make();
         const oversize = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "pw-oversize" });

package/dist/core/task-event.d.ts

@@ -885,6 +885,16 @@ export type TaskEvent = ({
      */
     type: "wiring_manifest";
     manifest: import("./wiring-manifest.js").WiringManifest;
+} & TaskEventIdentity) | ({
+    /**
+     * design/388 §2.5 — a RUN-TIME change to this leg's mounted tool set (today: the RefreshMcpTools
+     * seam re-inserting a server's tools in place). Carries the WHOLE post-change roster (positions
+     * come from it; a consumer replaces its copy) plus a summary usable only when the consumer holds
+     * `fromDigest` — otherwise it adopts the snapshot and records a skew (never rejects). The prepared
+     * roster itself rides `wiring_manifest.manifest.tools`; this frame never precedes that one.
+     */
+    type: "tool_roster_delta";
+    delta: import("./tool-roster.js").ToolRosterDelta;
 } & TaskEventIdentity) | {
     type: "done";
     result: TaskResult;

package/dist/core/task-registry.js

@@ -9,8 +9,9 @@ import { registerMonitorLane, pollMonitorLane, stopMonitorLane } from "./task-re
 import { registerWorkflowLane, pollWorkflowLane, stopWorkflowLane } from "./task-registry-workflow.js";
 import { mintCompletionId, canAccessWorkflowRun, formatWorkflowRun, clipTaskOutput, assertOwnership, sleepPollStep, statusFromBackground, rollSpoolText, accountDroppedBytes, renderSpoolBody, spoolDropNote, droppedGapNote, alreadyTerminalStopNote, terminalTaskSummary, TASK_OUTPUT_MAX_CHARS, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccess, DURABLE_AGENT_HANDLE_RE, } from "./task-registry-shared.js";
 export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR } from "./task-registry-shared.js";
-import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_CONTRACT, TASK_STOP_CONTRACT, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, REGISTRY_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "./task-tool-shape.js";
+import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, REGISTRY_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "./task-tool-shape.js";
 import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, backgroundAgentCycleSeqLane, activeDelegationHandlesLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
+import { toolFace } from "./tool-catalog-entries.js";
 export { canAccessWorkflowRun, clipTaskOutput, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE };
 const BLOCK_DEFAULT_TIMEOUT_MS = 30_000;
 const BLOCK_MAX_TIMEOUT_MS = 600_000;
@@ -1234,10 +1235,9 @@ export function createTaskOutputTool(opts) {
     const caps = { ...REGISTRY_TASK_TOOL_CAPS, notification: opts.notificationWired !== false };
     return defineTool({
         name: TASK_OUTPUT_TOOL_NAME,
-        contract: TASK_OUTPUT_CONTRACT,
+        ...toolFace("task-output"),
         description: composeTaskOutputDescription(caps),
         parameters: composeTaskOutputParams(caps),
-        effect: "read",
         execute: async (rawArgs, ctx) => {
             const args = rawArgs;
             const id = resolveTaskIdArg(args.task_id);
@@ -1283,10 +1283,9 @@ export function createTaskOutputTool(opts) {
 export function createTaskStopTool(opts) {
     return defineTool({
         name: TASK_STOP_TOOL_NAME,
-        contract: TASK_STOP_CONTRACT,
+        ...toolFace("task-stop"),
         description: composeTaskStopDescription(REGISTRY_TASK_TOOL_CAPS),
         parameters: TASK_STOP_PARAMS,
-        effect: "write",
         execute: async (rawArgs, ctx) => {
             const args = rawArgs;
             const id = resolveTaskIdArg(args.task_id, args.shell_id);

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

@@ -387,6 +387,14 @@ export interface TaskSpec {
      * owns that risk, same trust level as assembling `spec.tools` itself.
      */
     excludeTools?: string[];
+    /**
+     * design/388 §2.2 ⑥ — unmount the WHOLE tool face: the leg mounts nothing (no hands, no
+     * scaffolds, no MCP or skill tools; the effect roster reads `entries: []` and the model request
+     * carries `tools: []`). The utility-task shape a shell used to express with a hand-kept exclusion
+     * list. Not spelled `excludeTools: ["*"]` on purpose — `"*"` is a legal caller tool name (only `__`
+     * is reserved). `excludeTools` beside it is redundant, not an error.
+     */
+    excludeAllTools?: true;
     /**
      * Per-request DEFERRED disclosure for ALREADY-MOUNTED tools (built-ins
      * included — `ToolSpec.defer` only covers caller specs): wire names listed here ship as