@sema-agent/core 7.7.0 → 7.9.0

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/store-contracts/permission-rule-sync-contract.js

@@ -5,14 +5,15 @@ const GLOBAL = { kind: "global" };
 function add(actor, counter, origin = "user") {
     return { dot: { actor, counter }, origin, createdAt: "2026-01-01T00:00:00.000Z" };
 }
-function rule(text, adds, scope = GLOBAL) {
+function rule(text, adds, scope = GLOBAL, behavior = "allow") {
     const m = /^Bash\((.+?)(:\*)?\)$/.exec(text);
     if (m === null || m[1] === undefined)
         throw new Error(`contract fixture rule "${text}" is not a Bash(...) form`);
-    return { rule: text, tool: "Bash", match: m[2] !== undefined ? "prefix" : "exact", command: m[1], scope, adds };
+    return { behavior, rule: text, tool: "Bash", match: m[2] !== undefined ? "prefix" : "exact", command: m[1], scope, adds };
 }
-function tomb(text, removed, deletedBy, scope = GLOBAL) {
+function tomb(text, removed, deletedBy, scope = GLOBAL, behavior = "allow") {
     return {
+        behavior,
         rule: text,
         scope,
         removedDots: removed.map(([actor, counter]) => ({ actor, counter })),
@@ -25,10 +26,10 @@ function state(rules = [], tombstones = []) {
 function liveDots(s) {
     const out = new Set();
     for (const r of s.rules) {
-        const removed = s.tombstones.filter((t) => t.rule === r.rule && sameScope(t.scope, r.scope)).flatMap((t) => t.removedDots);
+        const removed = s.tombstones.filter((t) => t.behavior === r.behavior && t.rule === r.rule && sameScope(t.scope, r.scope)).flatMap((t) => t.removedDots);
         for (const a of r.adds) {
             if (!removed.some((d) => d.actor === a.dot.actor && d.counter === a.dot.counter))
-                out.add(`${r.rule}|${a.dot.actor}#${a.dot.counter}`);
+                out.add(`${r.behavior === "allow" ? "" : r.behavior + ":"}${r.rule}|${a.dot.actor}#${a.dot.counter}`);
         }
     }
     return out;
@@ -41,7 +42,7 @@ function sameScope(a, b) {
     return b.kind === "project" && a.root === b.root;
 }
 function allDots(s) {
-    return new Set(s.rules.flatMap((r) => r.adds.map((a) => `${r.rule}|${a.dot.actor}#${a.dot.counter}`)));
+    return new Set(s.rules.flatMap((r) => r.adds.map((a) => `${r.behavior === "allow" ? "" : r.behavior + ":"}${r.rule}|${a.dot.actor}#${a.dot.counter}`)));
 }
 export async function permissionRuleSyncContract(hooks = {}) {
     const join = hooks.join ?? joinRuleStates;
@@ -141,8 +142,24 @@ export async function permissionRuleSyncContract(hooks = {}) {
         assert.deepStrictEqual(new Set(ab.tombstones[0]?.removedDots.map((d) => `${d.actor}#${d.counter}`)), new Set(["a#1", "a#2"]), "the union — a one-sided pick can drop an observed removal");
         assert.deepStrictEqual(ab, join(b, a));
     });
+    run("behavior is an identity member: the same text as an allow and as a deny are two rows, each with its own adds and its own tombstone", async () => {
+        const both = state([rule("Bash(ls)", [add("a", 1)]), rule("Bash(ls)", [add("a", 2)], GLOBAL, "deny")], [tomb("Bash(ls)", [["a", 1]], ["a", 3])]);
+        const merged = join(both, state());
+        assert.strictEqual(merged.rules.length, 2, "one text, two behaviors — two identity groups, never folded");
+        assert.deepStrictEqual(liveDots(merged), new Set(["deny:Bash(ls)|a#2"]), "the allow tombstone must not reach the deny's add");
+        assert.deepStrictEqual(join(state(), both), merged, "commutative across the behavior axis");
+        const badWord = state([rule("Bash(pwd)", [add("b", 1)])], [Object.assign(tomb("Bash(pwd)", [["b", 1]], ["b", 2]), { behavior: "maybe" })]);
+        const screened = join(badWord, state());
+        assert.strictEqual(screened.tombstones.length, 0, "an unreadable behavior word on a tombstone must not land");
+        assert.ok(liveDots(screened).has("Bash(pwd)|b#1"), "…and must not cover anything");
+    });
+    run("closed-set identity: a row carrying a behavior word outside the closed set is refused like invalid text", async () => {
+        const forgedWord = Object.assign(rule("Bash(ls)", [add("z", 1)]), { behavior: "sometimes" });
+        const merged = join(state([forgedWord]), state());
+        assert.strictEqual(allDots(merged).size, 0, "a behavior this engine cannot read must not become an allow (or a deny) by falling through");
+    });
     run("metadata re-projection (r2-F2): a record whose stored fields contradict its rule text is refused, both orders", async () => {
-        const forged = { rule: "Bash(ls)", tool: "Bash", match: "prefix", command: "rm -rf /", scope: GLOBAL, adds: [add("z", 1)] };
+        const forged = { behavior: "allow", rule: "Bash(ls)", tool: "Bash", match: "prefix", command: "rm -rf /", scope: GLOBAL, adds: [add("z", 1)] };
         const clean = state([rule("Bash(git status)", [add("a", 1)])]);
         const ab = join(state([forged]), clean);
         const ba = join(clean, state([forged]));
@@ -150,9 +167,11 @@ export async function permissionRuleSyncContract(hooks = {}) {
         assert.deepStrictEqual(ab, ba, "refusal must preserve commutativity");
         assert.ok(allDots(ab).has("Bash(git status)|a#1"), "refusing one record must not disturb the rest");
     });
-    run("single-validator door: an illegal rule shape (bare-interpreter prefix) cannot ride a join", async () => {
+    run("single-validator door: an illegal ALLOW shape (bare-interpreter prefix) cannot ride a join — while the same text as a DENY is a legitimate wide tightening and lands", async () => {
         const merged = join(state([rule("Bash(node:*)", [add("z", 1)])]), state());
         assert.strictEqual(allDots(merged).size, 0, "Bash(node:*) must be refused by the shared validator inside the join");
+        const denied = join(state([rule("Bash(node:*)", [add("z", 1)], GLOBAL, "deny")]), state());
+        assert.deepStrictEqual(allDots(denied), new Set(["deny:Bash(node:*)|z#1"]), "the tightening floor admits the interpreter-headed prefix");
     });
     run("durable two-member face (design/382 §4.3): a session-scope row or tombstone never survives a join, and never poisons the round", async () => {
         const sessionScope = { kind: "session", sessionId: "sess-1" };
@@ -168,8 +187,8 @@ export async function permissionRuleSyncContract(hooks = {}) {
         const scopeA = { kind: "project", root: "/x" };
         const scopeB = { kind: "project", root: "/x a" };
         const s = state([rule("Bash(ls)", [add("v", 1)], scopeA), rule("Bash(ls)", [add("w", 1)], scopeB)], [
-            { rule: "Bash(ls)", scope: scopeA, removedDots: [{ actor: "v", counter: 1 }], deletedBy: { actor: "a 1", counter: 2 } },
-            { rule: "Bash(ls)", scope: scopeB, removedDots: [{ actor: "w", counter: 1 }], deletedBy: { actor: "1", counter: 2 } },
+            { behavior: "allow", rule: "Bash(ls)", scope: scopeA, removedDots: [{ actor: "v", counter: 1 }], deletedBy: { actor: "a 1", counter: 2 } },
+            { behavior: "allow", rule: "Bash(ls)", scope: scopeB, removedDots: [{ actor: "w", counter: 1 }], deletedBy: { actor: "1", counter: 2 } },
         ]);
         const merged = join(s, state());
         assert.strictEqual(merged.tombstones.length, 2, "two distinct delete intents must both survive — a colliding key folds one away");

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

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

@@ -0,0 +1,48 @@
+/**
+ * The STATIC TOOL CATALOG (design/388 §2.1 "静态目录"): one row per built-in / synthetic tool DEFINITION
+ * core owns — its wire name, the conditions core (or a host scenario factory) mounts it under, the
+ * `details.type` cards it mints, and its declared FACE (family / axes / contract / path target / rule
+ * vocabulary / render hints / policy bits).
+ *
+ * SINGLE SOURCE, TWO READERS. Each definition module spreads its row's `face` into the `ToolSpec` it
+ * hands `defineTool` (`...TOOL_FACES.read`), so the face a tool declares at mount time IS the face
+ * listed here — there is no second declaration to drift. The effect roster (tool-roster.ts) reads every
+ * axis off the MOUNTED INSTANCE; the static catalog (`describeToolCatalog()`) reads this table without
+ * an env or a deps object. The conformance gate (test/tool-catalog-conformance.test.ts) proves the two
+ * agree for every definition it can instantiate; the catalog completeness gate
+ * (scripts/verify-tool-catalog.mjs) proves every `defineTool` site in src/ that mints a core-owned name
+ * has a row here that declares a `family` — a missing declaration is a RED gate naming the file, never a
+ * silent `"other"`.
+ *
+ * LEAF MODULE by design: it imports vocabulary types and one leaf constant module only. Every definition
+ * module and every policy module that derives a name set from the catalog imports THIS file, so a
+ * dependency from here back into a tool module would be a load-order cycle with a `const` table in it.
+ *
+ * Keyed by DEFINITION identity (`id`), not by name — the full and the read-only shell both answer to
+ * `Bash`; a catalog predicate counts a name as a member when ANY row under that name matches.
+ */
+import type { ToolCatalogEntry, ToolFaceDeclaration } from "./tool-face.js";
+/** The full shell's contract id — declared here (the leaf) and re-exported by fs-bash.ts. */
+export declare const FULL_SHELL_CONTRACT_ID = "core.bash@1";
+export declare const READONLY_SHELL_CONTRACT_ID = "core.bash_readonly@1";
+/** Wire-name constants for definitions that had none (design/388 A-21: literals become references). */
+export declare const TASK_CREATE_TOOL_NAME = "TaskCreate";
+export declare const TASK_GET_TOOL_NAME = "TaskGet";
+export declare const TASK_UPDATE_TOOL_NAME = "TaskUpdate";
+export declare const TASK_LIST_TOOL_NAME = "TaskList";
+export declare const TODO_WRITE_TOOL_NAME = "TodoWrite";
+export declare const REFRESH_MCP_TOOLS_TOOL_NAME = "RefreshMcpTools";
+/**
+ * Every row. Order is documentation order (hands → delegation → scaffolds → memory → scheduler → host
+ * scenarios); nothing reads the order.
+ */
+export declare const TOOL_CATALOG_ENTRIES: readonly ToolCatalogEntry[];
+/**
+ * `details.type` cards the ENGINE mints outside any tool definition — the protocol channels' result
+ * cards and the fs boundary refusals (minted by the shared safety module on behalf of every fs tool).
+ */
+export declare const ENGINE_CARDS: Readonly<Record<string, string>>;
+/** The declared face of one definition, by definition id — what a definition module spreads into its spec. */
+export declare function toolFace(id: string): ToolFaceDeclaration;
+/** Definition-id → face, for the modules that spread one (`...TOOL_FACES.read`). Frozen: a face is data. */
+export declare const TOOL_FACES: Readonly<Record<string, ToolFaceDeclaration>>;

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

@@ -0,0 +1,174 @@
+import { TASK_OUTPUT_CONTRACT, TASK_STOP_CONTRACT } from "./task-tool-shape.js";
+export const FULL_SHELL_CONTRACT_ID = "core.bash@1";
+export const READONLY_SHELL_CONTRACT_ID = "core.bash_readonly@1";
+export const TASK_CREATE_TOOL_NAME = "TaskCreate";
+export const TASK_GET_TOOL_NAME = "TaskGet";
+export const TASK_UPDATE_TOOL_NAME = "TaskUpdate";
+export const TASK_LIST_TOOL_NAME = "TaskList";
+export const TODO_WRITE_TOOL_NAME = "TodoWrite";
+export const REFRESH_MCP_TOOLS_TOOL_NAME = "RefreshMcpTools";
+const SHELL_RULE_FACE = { primaryParams: ["command"], params: ["command", "timeout", "description", "run_in_background"] };
+const c = (contractId, implementationRevision = "1") => ({ contractId, implementationRevision });
+export const TOOL_CATALOG_ENTRIES = [
+    {
+        id: "read", name: "Read", source: "builtin", definedIn: "src/tools/fs/fs-read.ts", mountedBy: ["hands"],
+        cards: ["text", "notebook", "file_unchanged", "image", "document"],
+        face: {
+            family: "file-read", effect: "read", contract: c("core.read@1"),
+            pathTarget: { param: "file_path", aliases: ["path"], access: "read" },
+            ruleFace: { params: ["file_path", "path", "offset", "limit", "pages"] },
+            renderHints: { summaryParams: ["file_path"] },
+            offload: false, compactable: true, budgetExempt: true,
+        },
+    },
+    {
+        id: "edit", name: "Edit", source: "builtin", definedIn: "src/tools/fs/fs-write.ts", mountedBy: ["hands"],
+        cards: ["edit"],
+        face: {
+            family: "file-write", effect: "write", contract: c("core.edit@1"),
+            pathTarget: { param: "file_path", aliases: ["path"], access: "edit", skillScopeEligible: true },
+            ruleFace: { params: ["file_path", "path", "old_string", "new_string", "replace_all"] },
+            renderHints: { summaryParams: ["file_path"], approvalCard: "file-edit" },
+            compactable: true,
+        },
+    },
+    {
+        id: "write", name: "Write", source: "builtin", definedIn: "src/tools/fs/fs-write.ts", mountedBy: ["hands"],
+        cards: ["create", "update"],
+        face: {
+            family: "file-write", effect: "write", contract: c("core.write@1"),
+            pathTarget: { param: "file_path", aliases: ["path"], access: "create", skillScopeEligible: true },
+            ruleFace: { params: ["file_path", "path", "content"] },
+            renderHints: { summaryParams: ["file_path"], approvalCard: "file-write" },
+            offload: false, compactable: true,
+        },
+    },
+    {
+        id: "notebook-edit", name: "NotebookEdit", source: "builtin", definedIn: "src/tools/fs/fs-write.ts", mountedBy: ["hands"],
+        cards: ["notebook-edit"],
+        face: {
+            family: "file-write", effect: "write", contract: c("core.notebook_edit@1"),
+            pathTarget: { param: "notebook_path", aliases: ["path"], access: "edit" },
+            ruleFace: { params: ["notebook_path", "path", "cell_id", "cell_type", "edit_mode", "new_source"] },
+            renderHints: { userFacingName: "Edit Notebook", summaryParams: ["notebook_path"], approvalCard: "notebook-edit" },
+        },
+    },
+    {
+        id: "bash", name: "Bash", source: "builtin", definedIn: "src/tools/fs/fs-bash.ts", mountedBy: ["hands"],
+        cards: ["bash", "bash_invalid_timeout"],
+        face: {
+            family: "shell", effect: "write", contentOrigin: "execution", contract: c(FULL_SHELL_CONTRACT_ID),
+            ruleFace: SHELL_RULE_FACE,
+            renderHints: { summaryParams: ["command"], approvalCard: "shell" },
+            offloadThresholdChars: 30_000, compactable: true,
+        },
+    },
+    {
+        id: "bash-readonly", name: "Bash", source: "builtin", definedIn: "src/tools/fs/fs-bash.ts", mountedBy: ["hands"],
+        cards: ["bash", "readonly_out_of_root", "bash_invalid_timeout"],
+        face: {
+            family: "shell", effect: "read", contract: c(READONLY_SHELL_CONTRACT_ID),
+            ruleFace: SHELL_RULE_FACE,
+            renderHints: { summaryParams: ["command"], approvalCard: "shell" },
+            offloadThresholdChars: 30_000, compactable: true,
+        },
+    },
+    {
+        id: "grep", name: "Grep", source: "builtin", definedIn: "src/tools/fs/fs-search-tools.ts", mountedBy: ["hands"],
+        cards: ["grep"],
+        face: {
+            family: "search", effect: "read", contract: c("core.grep@1"),
+            pathTarget: { param: "path", access: "read" },
+            ruleFace: { params: ["pattern", "path", "glob", "type", "output_mode", "head_limit", "offset", "multiline", "context", "ignore_case", "-i", "-n", "-o", "-A", "-B", "-C"] },
+            renderHints: { userFacingName: "Search", summaryParams: ["pattern", "path"] },
+            offloadThresholdChars: 20_000, compactable: true,
+        },
+    },
+    {
+        id: "glob", name: "Glob", source: "builtin", definedIn: "src/tools/fs/fs-search-tools.ts", mountedBy: ["hands"],
+        cards: ["glob"],
+        face: {
+            family: "search", effect: "read", contract: c("core.glob@1"),
+            pathTarget: { param: "path", access: "read" },
+            ruleFace: { params: ["pattern", "path", "max_results"] },
+            renderHints: { userFacingName: "Search", summaryParams: ["pattern", "path"] },
+            compactable: true,
+        },
+    },
+    { id: "repo-map", name: "RepoMap", source: "builtin", definedIn: "src/tools/fs/repo-map.ts", mountedBy: ["hands"], cards: ["repo-map"], face: { family: "search", effect: "read", contract: c("core.repo_map@1") } },
+    { id: "lsp", name: "LSP", source: "builtin", definedIn: "src/core/lsp.ts", mountedBy: ["optional"], cards: [], face: { family: "search", effect: "read", contract: c("core.lsp@1") } },
+    { id: "enter-worktree", name: "EnterWorktree", source: "builtin", definedIn: "src/tools/worktree.ts", mountedBy: ["hands"], cards: ["worktree"], face: { family: "other", effect: "write", contract: c("core.enter_worktree@1") } },
+    { id: "exit-worktree", name: "ExitWorktree", source: "builtin", definedIn: "src/tools/worktree.ts", mountedBy: ["hands"], cards: ["worktree"], face: { family: "other", effect: "write", contract: c("core.exit_worktree@1") } },
+    { id: "task-output-hands", name: "TaskOutput", source: "builtin", definedIn: "src/tools/fs/fs-bash.ts", mountedBy: ["hands"], cards: [], face: { family: "delegate", effect: "read", contract: TASK_OUTPUT_CONTRACT } },
+    { id: "task-stop-hands", name: "TaskStop", source: "builtin", definedIn: "src/tools/fs/fs-bash.ts", mountedBy: ["hands"], cards: [], face: { family: "delegate", effect: "write", contract: TASK_STOP_CONTRACT } },
+    { id: "task-output", name: "TaskOutput", source: "builtin", definedIn: "src/core/task-registry.ts", mountedBy: ["delegation"], cards: ["task-output"], face: { family: "delegate", effect: "read", contract: TASK_OUTPUT_CONTRACT } },
+    { id: "task-stop", name: "TaskStop", source: "builtin", definedIn: "src/core/task-registry.ts", mountedBy: ["delegation"], cards: ["task-stop"], face: { family: "delegate", effect: "write", contract: TASK_STOP_CONTRACT } },
+    { id: "monitor", name: "Monitor", source: "builtin", definedIn: "src/tools/monitor.ts", mountedBy: ["backgroundTasks"], cards: ["monitor-start"], face: { family: "other", effect: "write", contract: c("core.monitor@1"), offloadThresholdChars: 10_000 } },
+    { id: "send-message", name: "SendMessage", source: "builtin", definedIn: "src/agents/send-message-tool.ts", mountedBy: ["delegation", "hostInternals", "peerLane"], cards: ["send-message"], face: { family: "protocol", effect: "write", contract: c("core.send_message@1") } },
+    { id: "agent-transcript", name: "AgentTranscript", source: "builtin", definedIn: "src/agents/agent-transcript-tool.ts", mountedBy: ["delegation"], cards: ["agent-transcript"], face: { family: "delegate", effect: "read", contract: c("core.agent_transcript@1") } },
+    { id: "list-agents", name: "ListAgents", source: "builtin", definedIn: "src/agents/list-agents-tool.ts", mountedBy: ["peerLane"], cards: ["list-agents"], face: { family: "protocol", effect: "read", aliases: ["ListPeers"], contract: c("core.list_agents@1") } },
+    { id: "workflow", name: "Workflow", source: "builtin", definedIn: "src/orchestration/run-workflow-tool.ts", mountedBy: ["workflow"], cards: ["workflow-run"], face: { family: "delegate", effect: "write", contract: c("core.workflow@1") } },
+    { id: "report-blocked", name: "ReportBlocked", source: "builtin", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["always"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.report_blocked@1") } },
+    { id: "report-findings", name: "ReportFindings", source: "builtin", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["always"], cards: ["report-findings"], face: { family: "scaffold", effect: "read", contract: c("core.report_findings@1") } },
+    { id: "structured-output", name: "StructuredOutput", source: "synthetic", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["optional"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.structured_output@1") } },
+    { id: "skill", name: "Skill", source: "builtin", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["optional"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.skill@1") } },
+    { id: "read-tool-result", name: "ReadToolResult", source: "builtin", definedIn: "src/core/tool-result-store.ts", mountedBy: ["optional"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.read_tool_result@1"), budgetExempt: true } },
+    { id: "tool-search", name: "ToolSearch", source: "builtin", definedIn: "src/core/runner/tool-disclosure.ts", mountedBy: ["optional"], cards: ["tool-search"], face: { family: "scaffold", effect: "read", contract: c("core.tool_search@1") } },
+    { id: "ask-user-question", name: "AskUserQuestion", source: "builtin", definedIn: "src/core/ask-question.ts", mountedBy: ["optional"], cards: ["ask-question"], face: { family: "other", effect: "read", contract: c("core.ask_user_question@1"), renderHints: { approvalCard: "question" } } },
+    { id: "exit-plan-mode", name: "ExitPlanMode", source: "builtin", definedIn: "src/core/present-plan-tool.ts", mountedBy: ["optional"], cards: ["exit-plan-mode"], face: { family: "plan", effect: "read", contract: c("core.exit_plan_mode@1"), renderHints: { userFacingName: "", approvalCard: "plan" } } },
+    { id: "enter-plan-mode", name: "EnterPlanMode", source: "builtin", definedIn: "src/core/present-plan-tool.ts", mountedBy: ["optional"], cards: ["enter-plan-mode"], face: { family: "plan", effect: "read", contract: c("core.enter_plan_mode@1") } },
+    { id: "refresh-mcp-tools", name: REFRESH_MCP_TOOLS_TOOL_NAME, source: "builtin", definedIn: "src/core/runner/prepare-protocol-tools.ts", mountedBy: ["optional"], cards: [], face: { family: "protocol", effect: "read" } },
+    { id: "memory-search", name: "memory_search", source: "builtin", definedIn: "src/core/memory-engine/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", effect: "read", contentOrigin: "local", contract: c("core.memory_search@1", "6"), offload: false } },
+    { id: "memory-get", name: "memory_get", source: "builtin", definedIn: "src/core/memory-engine/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", effect: "read", contentOrigin: "local", contract: c("core.memory_get@1", "6"), offload: false } },
+    { id: "memory-index", name: "memory_index", source: "builtin", definedIn: "src/core/memory-engine/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", effect: "read", contentOrigin: "local", contract: c("core.memory_index@1"), offload: false } },
+    { id: "memory-list", name: "memory_list", source: "builtin", definedIn: "src/core/shared-memory/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", effect: "read", contract: c("core.memory_list@1"), offload: false } },
+    { id: "memory-read", name: "memory_read", source: "builtin", definedIn: "src/core/shared-memory/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", effect: "read", contract: c("core.memory_read@1"), offload: false } },
+    { id: "cron-create", name: "CronCreate", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-create"], face: { family: "other", effect: "write", contract: c("core.cron_create@1") } },
+    { id: "cron-delete", name: "CronDelete", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-delete"], face: { family: "other", effect: "idempotent", contract: c("core.cron_delete@1") } },
+    { id: "cron-list", name: "CronList", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-list"], face: { family: "other", effect: "read", contract: c("core.cron_list@1") } },
+    { id: "schedule-wakeup", name: "ScheduleWakeup", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["schedule-wakeup"], face: { family: "other", effect: "write", contract: c("core.schedule_wakeup@1") } },
+    {
+        id: "web-fetch", name: "WebFetch", source: "builtin", definedIn: "src/tools/web.ts", mountedBy: ["scenario"], cards: ["web-fetch"],
+        face: { family: "web", effect: "read", contentOrigin: "external", contract: c("core.web_fetch@1"), ruleFace: { primaryParams: ["url"] }, renderHints: { summaryParams: ["url"], approvalCard: "fetch" }, compactable: true },
+    },
+    {
+        id: "web-search", name: "WebSearch", source: "builtin", definedIn: "src/tools/web.ts", mountedBy: ["scenario"], cards: ["web-search"],
+        face: { family: "web", effect: "read", contentOrigin: "external", contract: c("core.web_search@1"), ruleFace: { primaryParams: ["query"] }, renderHints: { summaryParams: ["query"] }, compactable: true },
+    },
+    { id: "todo-write", name: TODO_WRITE_TOOL_NAME, source: "builtin", definedIn: "src/tools/todo.ts", mountedBy: ["scenario"], cards: ["todo"], modelGate: "task-scaffold", face: { family: "plan", effect: "idempotent", contract: c("core.todo_write@1") } },
+    { id: "task-create", name: TASK_CREATE_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "write", contract: c("core.task_create@1") } },
+    { id: "task-get", name: TASK_GET_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "read", contract: c("core.task_get@1") } },
+    { id: "task-update", name: TASK_UPDATE_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "idempotent", contract: c("core.task_update@1") } },
+    { id: "task-list", name: TASK_LIST_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task-list"], modelGate: "task-scaffold", face: { family: "plan", effect: "read", contract: c("core.task_list@1") } },
+    { id: "agent", name: "Agent", source: "builtin", definedIn: "src/agents/subagent.ts", mountedBy: ["scenario"], cards: ["agent", "fork"], face: { family: "delegate", contentOrigin: "local", contract: c("core.agent@1") } },
+    { id: "observer-report", name: "ObserverReport", source: "builtin", definedIn: "src/agents/observer.ts", mountedBy: ["scenario"], cards: [], face: { family: "scaffold", effect: "write", contract: c("core.observer_report@1") } },
+    { id: "declare-done", name: "DeclareDone", source: "builtin", definedIn: "src/orchestration/goal.ts", mountedBy: ["scenario"], cards: [], face: { family: "scaffold", effect: "read" } },
+];
+export const ENGINE_CARDS = Object.freeze({
+    mcp: "src/core/mcp.ts",
+    a2a: "src/core/a2a.ts",
+    path_not_in_root: "src/tools/fs/safety.ts",
+    read_path_denied: "src/tools/fs/safety.ts",
+});
+const byId = new Map();
+for (const e of TOOL_CATALOG_ENTRIES) {
+    if (byId.has(e.id))
+        throw new Error(`tool catalog: duplicate definition id ${JSON.stringify(e.id)}`);
+    byId.set(e.id, e);
+}
+export function toolFace(id) {
+    const e = byId.get(id);
+    if (e === undefined)
+        throw new Error(`tool catalog: no definition ${JSON.stringify(id)}`);
+    return structuredClone(e.face);
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const k of Object.keys(value))
+            deepFreeze(value[k]);
+    }
+    return value;
+}
+deepFreeze(TOOL_CATALOG_ENTRIES);
+export const TOOL_FACES = Object.freeze(Object.fromEntries(TOOL_CATALOG_ENTRIES.map((e) => [e.id, e.face])));

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

@@ -0,0 +1,22 @@
+import type { ToolMountTag } from "./tool-face.js";
+export interface ToolConformanceVector {
+    id: string;
+    /** The mount conditions the vector activates. */
+    active: readonly ToolMountTag[];
+    /** Predicted names the vector cannot mount, each with the seat it lacks. */
+    absent: ReadonlyArray<{
+        name: string;
+        why: string;
+    }>;
+    /** Mounted names no tag spells, each with the seat that mounts them. */
+    extra: ReadonlyArray<{
+        name: string;
+        why: string;
+    }>;
+    /** The vector's expected core-mounted name set: predict(active) − absent + extra. */
+    expected: readonly string[];
+}
+/** The matrix. Vector ids are stable (a host's own conformance test keys on them). */
+export declare const TOOL_CONFORMANCE_VECTORS: readonly ToolConformanceVector[];
+/** The matrix as a host reads it (a frozen copy). */
+export declare function describeToolConformanceVectors(): readonly ToolConformanceVector[];

package/dist/core/tool-conformance.js

@@ -0,0 +1,37 @@
+import { predictMountedToolNames } from "./tool-registry.js";
+const vector = (id, active, absent = [], extra = []) => {
+    const predicted = new Set(predictMountedToolNames(new Set(active)));
+    for (const a of absent)
+        predicted.delete(a.name);
+    for (const e of extra)
+        predicted.add(e.name);
+    return { id, active, absent, extra, expected: [...predicted].sort() };
+};
+const OFFLOAD_READER = { name: "ReadToolResult", why: "the offload store is wired by default (the deployment threshold), an `optional` seat every vector carries" };
+export const TOOL_CONFORMANCE_VECTORS = [
+    vector("bare", ["always"], [], [OFFLOAD_READER]),
+    vector("hands-full", ["always", "hands", "backgroundTasks", "delegation"], [
+        { name: "SendMessage", why: "needs the runner self seat (a direct prepare has none)" },
+        { name: "AgentTranscript", why: "needs the runner self seat (a direct prepare has none)" },
+    ], [OFFLOAD_READER]),
+    vector("hands-readonly", ["always", "hands"], [
+        { name: "Edit", why: "the read-only band mounts the read half only" },
+        { name: "Write", why: "the read-only band mounts the read half only" },
+        { name: "NotebookEdit", why: "the read-only band mounts the read half only" },
+        { name: "TaskOutput", why: "the background-shell pair mounts on the full shell only" },
+        { name: "TaskStop", why: "the background-shell pair mounts on the full shell only" },
+        { name: "EnterWorktree", why: "the worktree pair needs the tracked cwd the full shell owns" },
+        { name: "ExitWorktree", why: "the worktree pair needs the tracked cwd the full shell owns" },
+    ], [OFFLOAD_READER]),
+    vector("plan-mode", ["always", "optional"], [
+        { name: "LSP", why: "needs a wired LSP manager" },
+        { name: "Skill", why: "needs a skills listing" },
+        { name: "StructuredOutput", why: "needs an output schema" },
+        { name: "ToolSearch", why: "needs a deferred tool" },
+        { name: "RefreshMcpTools", why: "needs a declared MCP server" },
+        { name: "EnterPlanMode", why: "needs a checkpoint store beside plan mode" },
+    ]),
+];
+export function describeToolConformanceVectors() {
+    return TOOL_CONFORMANCE_VECTORS;
+}