@sema-agent/core 7.7.0 → 7.8.0

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;
+}

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

@@ -0,0 +1,171 @@
+/**
+ * The tool FACE vocabulary (design/388 §2.1–§2.2): the closed word sets and the small declaration
+ * shapes that describe a tool WITHOUT executing it — its display family, the parameter that names its
+ * path target, the parameter vocabulary a permission rule may speak about it, the render hints a shell
+ * may read, and the mount-condition tags the static catalog lists it under.
+ *
+ * Layer-0 vocabulary: nothing here reads an env, a deps object, or a tool instance. `ToolSpec`
+ * (tool-spec.ts) carries the declaration half of these shapes as optional fields; the static catalog
+ * (tool-catalog-entries.ts) lists every built-in's face; the effect roster (tool-roster.ts) reads the
+ * same shapes off the MOUNTED instance. One vocabulary, three readers, no second table.
+ */
+/** The display / dispatch family of a tool. INPUT to grouping and card pre-selection only — never an
+ *  authorization source (a `"file-write"` family grants nothing; the path-confinable predicate reads
+ *  {@link ToolPathTarget}, and the approval card is chosen by {@link ToolRenderHints.approvalCard}). */
+export declare const TOOL_FAMILIES: readonly ["shell", "file-read", "file-write", "search", "web", "delegate", "plan", "scaffold", "memory", "protocol", "other"];
+export type ToolFamily = (typeof TOOL_FAMILIES)[number];
+/**
+ * The closed set of MOUNT-CONDITION tags a static catalog entry is listed under. The static half of the
+ * catalog carries an ARRAY (a tool can be mounted by more than one condition — TaskOutput rides both the
+ * hand band and the delegation surface); the effect roster records the ONE tag that actually fired.
+ *
+ *  - `hands` — the hand band (an execution env is wired: `deps.executionEnv` / `executionEnvFactory`);
+ *  - `backgroundTasks` — the background-task surface (`Monitor`);
+ *  - `workflow` — the workflow tool surface (`Workflow`);
+ *  - `delegation` — the union of the background-task and workflow surfaces (TaskOutput/TaskStop/
+ *    AgentTranscript, SendMessage's first condition);
+ *  - `hostInternals` — a host-internal seat is present (`RunInternals.parentNotify`);
+ *  - `peerLane` — the peer-session lane is mounted;
+ *  - `scheduler` — the env carries a scheduler daemon (the Cron family + ScheduleWakeup);
+ *  - `memory` — an engine-memory / shared-memory session is wired;
+ *  - `scenario` — mounted by a HOST scenario factory through `TaskSpec.tools` (core defines the tool,
+ *    the host decides to mount it);
+ *  - `always` — mounted on every task unless excluded (ReportBlocked/ReportFindings);
+ *  - `optional` — mounted by a per-task opt-in or a wired seat (plan mode, an output schema, an
+ *    offload store, a question face, a skills listing, an MCP configuration).
+ */
+export declare const TOOL_MOUNT_TAGS: readonly ["hands", "backgroundTasks", "workflow", "delegation", "hostInternals", "peerLane", "scheduler", "memory", "scenario", "always", "optional"];
+export type ToolMountTag = (typeof TOOL_MOUNT_TAGS)[number];
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+/** The closed set of specialised approval cards a shell may pre-select from a render hint. The hint is a
+ *  PRE-FILTER: the shell owns each card's input schema and validates the call's full args before
+ *  mounting the card (design/388 §2.5 boundary ①). */
+export declare const TOOL_APPROVAL_CARDS: readonly ["file-edit", "file-write", "notebook-edit", "shell", "fetch", "plan", "question", "generic"];
+export type ToolApprovalCard = (typeof TOOL_APPROVAL_CARDS)[number];
+/** How a path-targeting tool touches its target. `read` never enters a write-confinement face. */
+export declare const TOOL_PATH_ACCESSES: readonly ["read", "create", "edit"];
+export type ToolPathAccess = (typeof TOOL_PATH_ACCESSES)[number];
+/**
+ * The parameter that names this tool's filesystem target, and how the target is touched. Present ⇔ the
+ * tool can be confirmed BY PATH (write confinement, sensitive-path guards, edited-file tracking, the
+ * transcript-directory gate). `param` outranks every alias (NotebookEdit's `notebook_path` beats a decoy
+ * `file_path`). `skillScopeEligible` (default false) is the SEPARATE authorization domain of the
+ * active-skill `allowPaths` face — a confinable write tool is not automatically eligible there.
+ */
+export interface ToolPathTarget {
+    param: string;
+    aliases?: readonly string[];
+    access: ToolPathAccess;
+    skillScopeEligible?: true;
+}
+/**
+ * The parameter vocabulary a permission rule (`Tool(param:pattern)`) may name. DERIVED by default from
+ * the tool's schema: the SCALAR top-level parameters (string/number/integer/boolean and their enum/const/
+ * union forms) plus {@link ToolPathTarget.aliases}; object/array parameters never enter (a rule on them
+ * can never match — `matchParamRules` skips non-scalar values). A declaration can only NARROW the derived
+ * set; `primaryParams` defaults to the path target's `param` + aliases.
+ */
+export interface ToolRuleFace {
+    primaryParams?: readonly string[];
+    params?: readonly string[];
+}
+/** The roster's WIRE bounds on a tool name and a contract member (design/388 §2.5 / B20). Distinct from
+ *  protocol-naming's `TOOL_NAME_MAX_CHARS` (64), the provider-facing bound the MCP/A2A namespacing helper
+ *  budgets a MINTED name to — a minted name is always inside this wire bound by construction; a CALLER
+ *  declaration is judged against it at prepare. */
+export declare const TOOL_WIRE_NAME_MAX_CHARS = 128;
+export declare const TOOL_CONTRACT_MAX_CHARS = 64;
+/** The roster's wire bound on a KEY — a schema property name, a path-target `param`/alias, a rule-face param. A key is a
+ *  SEMANTIC name every fence reads an argument by, so it is never truncated: a declaration over the bound is refused at
+ *  the door (caller) or dropped with a disclosed reason (MCP intake), and a row carries every key exactly. */
+export declare const TOOL_KEY_MAX_CHARS = 256;
+/** The roster's bound on how many top-level keys one row carries (the same refuse/drop treatment). */
+export declare const TOOL_KEYS_MAX = 1024;
+/** Bounds every render-hint string is held to on the roster (design/388 §2.2 ④). */
+export declare const RENDER_HINT_MAX_CHARS = 64;
+export declare const RENDER_HINT_ACTIVITY_MAX_CHARS = 32;
+export declare const RENDER_HINT_MAX_LIST = 16;
+/**
+ * Declarative, template-free display hints (design/388 §2.2 ④, D-4). UNTRUSTED display input on the
+ * wire: the engine length-caps them at the roster mint; the shell strips control / newline / bidi
+ * characters before rendering. `resultCards` may only name cards in the tool's OWN namespace
+ * (`caller:<contractId>/<type>`) — engine cards (`builtin:*`, `mcp`, the refusal cards) are minted by
+ * the engine alone and a declaration naming one is refused at prepare.
+ */
+export interface ToolRenderHints {
+    userFacingName?: string;
+    activity?: string;
+    summaryParams?: readonly string[];
+    resultCards?: readonly string[];
+    approvalCard?: ToolApprovalCard;
+}
+/**
+ * The static FACE of a tool — the subset of `ToolSpec` a catalog entry declares and a definition module
+ * spreads into its spec. Everything here is readable without an env or a deps object; the effect roster
+ * reads the same members off the mounted instance.
+ */
+export interface ToolFaceDeclaration {
+    family: ToolFamily;
+    effect?: import("./tool-spec.js").ToolEffect;
+    egress?: true;
+    irreversibility?: "never" | "maybe" | "always";
+    contentOrigin?: import("./tool-spec.js").ToolContentOrigin;
+    contract?: {
+        contractId: string;
+        implementationRevision: string;
+    };
+    aliases?: string[];
+    pathTarget?: ToolPathTarget;
+    ruleFace?: ToolRuleFace;
+    renderHints?: ToolRenderHints;
+    offload?: boolean;
+    offloadThresholdChars?: number;
+    compactable?: true;
+    budgetExempt?: true;
+}
+/**
+ * One row of the static tool catalog (design/388 §2.1 "静态目录"). Keyed by DEFINITION identity, not by
+ * name: two definitions may share a wire name (the full and the read-only shell both answer to `Bash`),
+ * and every catalog predicate counts a name as a member when ANY entry under it matches.
+ */
+export interface ToolCatalogEntry {
+    /** Definition identity — unique across the catalog (`bash`, `bash-readonly`). */
+    id: string;
+    /** Wire name; may repeat across entries. */
+    name: string;
+    /** `builtin` = a core definition mounted by core or by a host factory; `synthetic` = core mints it
+     *  per task with a per-task shape (the structured-output tool). */
+    source: "builtin" | "synthetic";
+    /** Where the definition lives (repo-relative), so a catalog gate can name the file. */
+    definedIn: string;
+    /** The conditions under which core (or a host scenario) mounts this definition. */
+    mountedBy: readonly ToolMountTag[];
+    /** The `details.type` cards this definition mints on `tool_end.structured`. */
+    cards: readonly string[];
+    /** The declared face — spread into the definition's `ToolSpec` by the module that owns it. */
+    face: ToolFaceDeclaration;
+    /** A `modelGate` class the default-bundle assembler stamps on this definition's default arm. */
+    modelGate?: string;
+}
+/**
+ * The band-membership table over the mount tags: a host derives its hand band as the definitions listed under a
+ * TRUE row (server B-1). Every tag has a row — the fence reds `tsc` when a tag is added without one. The
+ * background-task surface is hands-derived (`backgroundTaskToolsActive` requires the shell), so a definition
+ * mounted by it alone is a band member that is NOT dual-use.
+ */
+export declare const MOUNT_TAG_IN_HANDS_BAND: {
+    readonly hands: true;
+    readonly backgroundTasks: true;
+    readonly workflow: false;
+    readonly delegation: true;
+    readonly hostInternals: true;
+    readonly peerLane: true;
+    readonly scheduler: false;
+    readonly memory: false;
+    readonly scenario: false;
+    readonly always: false;
+    readonly optional: false;
+};
+export type HandsBandTableCoversEveryMountTag = AssertAllKeysHandled<Exclude<ToolMountTag, keyof typeof MOUNT_TAG_IN_HANDS_BAND>>;
+/** The tags whose definitions form the hand band a host derives (server B-1 `HANDS_BAND_TAGS`). */
+export declare const HANDS_BAND_TAGS: ReadonlySet<ToolMountTag>;

package/dist/core/tool-face.js

@@ -0,0 +1,25 @@
+export const TOOL_FAMILIES = ["shell", "file-read", "file-write", "search", "web", "delegate", "plan", "scaffold", "memory", "protocol", "other"];
+export const TOOL_MOUNT_TAGS = ["hands", "backgroundTasks", "workflow", "delegation", "hostInternals", "peerLane", "scheduler", "memory", "scenario", "always", "optional"];
+export const TOOL_APPROVAL_CARDS = ["file-edit", "file-write", "notebook-edit", "shell", "fetch", "plan", "question", "generic"];
+export const TOOL_PATH_ACCESSES = ["read", "create", "edit"];
+export const TOOL_WIRE_NAME_MAX_CHARS = 128;
+export const TOOL_CONTRACT_MAX_CHARS = 64;
+export const TOOL_KEY_MAX_CHARS = 256;
+export const TOOL_KEYS_MAX = 1024;
+export const RENDER_HINT_MAX_CHARS = 64;
+export const RENDER_HINT_ACTIVITY_MAX_CHARS = 32;
+export const RENDER_HINT_MAX_LIST = 16;
+export const MOUNT_TAG_IN_HANDS_BAND = {
+    hands: true,
+    backgroundTasks: true,
+    workflow: false,
+    delegation: true,
+    hostInternals: true,
+    peerLane: true,
+    scheduler: false,
+    memory: false,
+    scenario: false,
+    always: false,
+    optional: false,
+};
+export const HANDS_BAND_TAGS = new Set(Object.keys(MOUNT_TAG_IN_HANDS_BAND).filter((t) => MOUNT_TAG_IN_HANDS_BAND[t]));

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

@@ -1,10 +1,34 @@
 import type { AskOrigin } from "./ask-origin.js";
 import type { Settlement } from "./gate-outcome.js";
 /** A tool call presented to a policy before it executes. */
+/** design/388 B6 — the per-call face (see {@link ToolCallRequest.face}). */
+export interface ToolCallFace {
+    family: import("./tool-face.js").ToolFamily;
+    pathTarget?: {
+        param: string;
+        aliases: readonly string[];
+        access: "read" | "create" | "edit";
+        skillScopeEligible: boolean;
+    };
+    capabilityId: string;
+    contractId: string;
+    shapeDigest: string;
+    implementationRevision: string;
+}
 export interface ToolCallRequest {
     toolName: string;
     args: unknown;
     toolCallId: string;
+    /**
+     * design/388 B6 (additive) — the mounted tool's FACE as the leg's roster minted it: the declared path target
+     * (how the target may be confirmed by path), the display family, and the engine-minted identity
+     * (`capabilityId` / `contractId` / `shapeDigest`) an exemption store keys on. Stamped at the gate entry
+     * from the live roster, so identity follows the OBJECT the call dispatches to — a caller tool that merely
+     * took a built-in's name carries its own face, never the built-in's. ABSENT when a policy is invoked
+     * outside a Runner (a bare producer): a path-confining face then reads the catalog's declaration for the
+     * NAME (the pre-388 posture, never wider), and a skill-scope face treats the write as unconfirmable.
+     */
+    face?: ToolCallFace;
     /**
      * RB-108 — the LIVE working directory this call's RELATIVE path arguments will actually resolve
      * against, read at adjudication time from the same tracked `cwdRef` the fs hand tools resolve with

package/dist/core/tool-policy.js

@@ -4,6 +4,7 @@ import { brandPolicyAskClass } from "./ask-class.js";
 import { sanitizeAutoModeArmingRecipe } from "./auto-mode-arming.js";
 import { join, normalize as normalizePath, posix as posixPath, sep, win32 as winPath } from "node:path";
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
+import { protectivePathTargetOf } from "./tool-registry.js";
 import { boundInputHashOf } from "./canonical-json.js";
 import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./untrusted-text.js";
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
@@ -847,8 +848,9 @@ export function createTranscriptIntegrityPolicy(opts) {
                         ? "the shell's working directory is inside the transcript directory and this is not a single read-only command (fail-closed)"
                         : "the command references the transcript directory and is not a single read-only command (fail-closed)");
             }
-            if (toolName === "Write" || toolName === "Edit" || toolName === "NotebookEdit") {
-                const p = writeTargetPath(toolName, req.args);
+            const writeTarget = protectivePathTargetOf(req);
+            if (writeTarget !== undefined && writeTarget.access !== "read") {
+                const p = writeTargetPath(req);
                 if (typeof p === "string" && inProtectedDir(p, req.cwd)) {
                     return askReason(`"${p}" is inside the session-transcript directory`);
                 }