@sema-agent/core 7.6.3 → 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/steer-admission.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Admission bookkeeping for HUMAN INPUTS accepted mid-run (design/171 §6.2–§6.3): the per-leg ordinal an
+ * accepted input is stamped with, and the field-for-field "is this repeat the same instruction" test the
+ * live steer verb applies under an already-used `inputId`. Two accepting arms share both — the stream's
+ * `steer` verb and the run body — which is why the ordinal is keyed on the leg's harness in a module-level
+ * WeakMap rather than held by either arm: one counter per leg, one ascending sequence across both.
+ *
+ * Run-loop machinery (layer 1), not a driven lane: nothing here takes an Input or hands back a Result, and
+ * nothing here reads host state. Named without the `run-` family prefix for that reason.
+ */
+import type { AcceptedSteerInput } from "./contracts.js";
+export declare function nextHumanInputSeq(key: object): number;
+/** design/171 §6.3 parity, LIVE leg — is a repeat under an already-accepted `inputId` the SAME
+ *  instruction (an idempotent retry) or a different one wearing a used key? Compared field for field,
+ *  exactly like the parked leg's replay check: the key alone is never evidence of a replay, and two
+ *  callers colliding on one id must not silently lose the second instruction. */
+export declare function sameAcceptedSteerInput(a: AcceptedSteerInput, b: AcceptedSteerInput): boolean;

package/dist/core/runner/steer-admission.js

@@ -0,0 +1,17 @@
+const humanInputOrdinals = new WeakMap();
+export function nextHumanInputSeq(key) {
+    let box = humanInputOrdinals.get(key);
+    if (box === undefined) {
+        box = { n: 0 };
+        humanInputOrdinals.set(key, box);
+    }
+    return ++box.n;
+}
+export function sameAcceptedSteerInput(a, b) {
+    return (a.payload === b.payload &&
+        a.trusted === b.trusted &&
+        a.priority === b.priority &&
+        a.actor?.id === b.actor?.id &&
+        a.actor?.hostAsserted === b.actor?.hostAsserted &&
+        a.actor?.issuer === b.actor?.issuer);
+}

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.d.ts

@@ -0,0 +1,71 @@
+/**
+ * What the run loop derives from a tool call's END, in every leg that closes one: the `tool_end` frame
+ * body (the ONE projection the live loop, the resumed batch and the reconcile-recovered orphan all go
+ * through), the `toolResult` transcript message the resume engine closes pending calls with, the thin
+ * `response` digest the post-tool-batch observer is handed, and the canonical write-tool → reminder-window
+ * family the attachment reducer keys on when a write tool ends.
+ *
+ * Projections over values the caller already holds, with ONE clock read: `toolResultMsg` stamps the message
+ * it mints with `Date.now()` (as it did inside the driver — the transcript's timestamp is minted where the
+ * message is). Nothing here reads host state through a callback, awaits, or keeps state between calls.
+ * Layer-1 machinery, not a driven lane; the prefix rule it follows is written once, on initial-run-state.ts.
+ */
+import { type AgentMessage } from "../../internal/harness.js";
+import type { GateOutcome } from "../gate-outcome.js";
+import { type McpDelivered } from "../mcp-failure.js";
+import type { RecoveredOrphan } from "../session-reconcile.js";
+import type { WriteFamily } from "./turn-attachments.js";
+/** design/134 §3.1b — derive the thin `response` digest from a harness tool result: model-facing text
+ *  content only (never `details` — the H4 thin-projection discipline), capped with a truncation note. */
+export declare function batchResponseDigest(result: unknown): string | undefined;
+/** The `tool_end` body fields projected from a harness tool result — output/truncated/totalChars via
+ *  {@link toolOutputFrom} and the CC card via {@link structuredFrom}. Single construction point for BOTH
+ *  the live loop's frames and the resumed batch's frames (`resolvePendingCall` + the deferred-sibling
+ *  close): the resumed frames used to carry only `isError`, so a client rendering tool output from frames
+ *  showed an empty body for every durable-approved call. Same projection = same source as the transcript.
+ *  Also the one place the gate outcome reaches a frame — see the parameter. */
+export declare function toolEndBodyFrom(result: unknown, isError: boolean, 
+/** The gate's record of the pass that admitted or refused this call, supplied by the CALLER of this
+ *  projection — the live loop reads it off the gate's per-call sideband, the resumed leg off the decide's
+ *  minted record. Deliberately a parameter and never derived from `result`: a tool's own `details`
+ *  (which post-tool hooks may also replace) is writable by layers that adjudicate nothing, so reading
+ *  provenance out of it would let a failing tool claim a person approved it. Omitted ⇒ the call never
+ *  went through the gate (see the `tool_end.gate` doc, the one home). */
+gate?: GateOutcome, 
+/** WHICH call this run's committed durable park is holding ({@link import("./park-commit.js").gatedCallIdOf}), for the frames the
+ *  abort short-circuits. Same never-derived-from-`result` posture as the outcome above, and for the
+ *  sharpest version of that reason: this one is an assertion about a DIFFERENT call, so a tool able to
+ *  author it could point an approval UI at a call nobody is waiting on. Omitted ⇒ no park is holding a
+ *  call (nothing parked, or the park that did holds none), and the frame then carries no id at all. */
+gatedCallIdOfRun?: string): {
+    output?: unknown;
+    truncated?: boolean;
+    totalChars?: number;
+    structured?: unknown;
+    errorCode?: string;
+    delivered?: McpDelivered;
+    gatedCallId?: string;
+    gate?: GateOutcome;
+};
+/**
+ * scan-1/A1 — the BODY of the synthetic `tool_end` that closes a reconcile-recovered orphan. ONE
+ * construction point for BOTH minting legs (the live-abort loop at the end of a run, and the wake/crash
+ * leg's replay at run open), so the two can never disagree about the shape of the same event.
+ *
+ * Both frames used to carry `isError:true` and NOTHING else: a consumer rendering tool output from the
+ * event stream showed an EMPTY body for every interrupted call, even though the persisted transcript
+ * (which the model reads) carried the full `[INTERRUPTED]` explanation — the two faces of one call
+ * disagreed. The projection goes through the same {@link toolEndBodyFrom} every live tool result uses, so
+ * `output` = the persisted model-facing text and `errorCode` = the persisted `details.errorKind`
+ * (`interrupted_never_started` / `interrupted_outcome_unknown`) — a consumer discriminates on the code
+ * instead of prose-matching. No `structured`: the reconcile mints no CC card (no `details.type`), which
+ * `structuredFrom`'s allowlist already enforces.
+ */
+export declare function reconciledToolEndBody(orphan: Pick<RecoveredOrphan, "text" | "errorKind">): ReturnType<typeof toolEndBodyFrom>;
+/** task #51 F2/F3 — the CANONICAL write-tool → reminder-window mapping (CC qFm :480253-480254
+ *  `a.name === bD || a.name === hF` = TaskCreate/TaskUpdate; BFm :480217-480219 = TodoWrite). Live
+ *  deployment-alias resolution happens at the call sites (run-local `writeFamilyOf` over the mounted
+ *  roster); retired-name normalization is gone (RB-476-A, 5.0.0). */
+export declare function writeFamilyOfCanonical(name: string): WriteFamily | undefined;
+/** A `toolResult` transcript message (text content). Used by the resume engine to close pending calls. */
+export declare function toolResultMsg(toolCallId: string, toolName: string, text: string, isError: boolean): AgentMessage;

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

@@ -0,0 +1,75 @@
+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;
+    if (content === undefined || content === null)
+        return undefined;
+    let text;
+    if (typeof content === "string") {
+        text = content;
+    }
+    else if (Array.isArray(content)) {
+        text = content
+            .map((c) => (c !== null && typeof c === "object" && typeof c.text === "string" ? c.text : ""))
+            .filter((t) => t.length > 0)
+            .join("\n");
+    }
+    else {
+        try {
+            text = JSON.stringify(content) ?? "";
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (text.length === 0)
+        return undefined;
+    return text.length > BATCH_RESPONSE_MAX_CHARS
+        ? `${text.slice(0, BATCH_RESPONSE_MAX_CHARS)}…[+${text.length - BATCH_RESPONSE_MAX_CHARS} chars truncated]`
+        : text;
+}
+export function toolEndBodyFrom(result, isError, gate, gatedCallIdOfRun) {
+    const o = toolOutputFrom(result);
+    const st = structuredFrom(result);
+    const det = isError ? result?.details : undefined;
+    const codeRaw = det?.code;
+    const kindRaw = det?.errorKind;
+    const code = typeof codeRaw === "string" ? codeRaw : typeof kindRaw === "string" ? kindRaw : undefined;
+    const deliveredRaw = det?.delivered;
+    const delivered = typeof deliveredRaw === "string" && MCP_DELIVERY_VERDICTS.includes(deliveredRaw) ? deliveredRaw : undefined;
+    const gatedCallId = code === "gate.parked" ? gatedCallIdOfRun : undefined;
+    return {
+        ...(o !== undefined ? { output: o.output, ...(o.truncated ? { truncated: true } : {}), ...(o.totalChars !== undefined ? { totalChars: o.totalChars } : {}) } : {}),
+        ...(st !== undefined ? { structured: st } : {}),
+        ...(typeof code === "string" ? { errorCode: code } : {}),
+        ...(delivered !== undefined ? { delivered } : {}),
+        ...(gatedCallId !== undefined ? { gatedCallId } : {}),
+        ...(gate !== undefined ? { gate } : {}),
+    };
+}
+export function reconciledToolEndBody(orphan) {
+    return toolEndBodyFrom({ content: orphan.text, details: { code: orphan.errorKind } }, true);
+}
+export function writeFamilyOfCanonical(name) {
+    if (name === TASK_CREATE_TOOL_NAME || name === TASK_UPDATE_TOOL_NAME)
+        return "task";
+    if (name === TODO_WRITE_TOOL_NAME)
+        return "todo";
+    if (name === TOOL_SEARCH_NAME)
+        return "tool_search";
+    return undefined;
+}
+export function toolResultMsg(toolCallId, toolName, text, isError) {
+    return {
+        role: "toolResult",
+        toolCallId,
+        toolName,
+        content: [{ type: "text", text }],
+        isError,
+        timestamp: Date.now(),
+    };
+}

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);