@sema-agent/core 7.53.0 → 7.54.1

package/dist/core/store-contracts/session-store-incarnation-contract.d.ts

@@ -25,3 +25,15 @@ export interface SessionStoreIncarnationContractHooks {
     runAssertion?: ContractAssertionRunner;
 }
 export declare function sessionStoreIncarnationContract(make: () => SessionStore, hooks: SessionStoreIncarnationContractHooks): Promise<void>;
+/**
+ * The incarnation cases themselves, registered through the caller's `run` (which builds and disposes the
+ * store each case gets). One text for both kits that carry them: this one, and `sessionStoreContract`'s
+ * incarnation group — a case changed here changes in both, so the two can never pin different laws.
+ * Module-internal (not a package export).
+ */
+export declare function registerSessionIncarnationCases(run: (name: string, fn: (store: SessionStore) => Promise<void>) => void, hooks: {
+    deleteSession: SessionStoreIncarnationContractHooks["deleteSession"];
+    /** This kit's own hook is synchronous; `sessionStoreContract`'s may also resolve later (a backend whose
+     *  restart must first release an exclusive lock). Awaiting a plain value changes nothing for this kit. */
+    reopen: (store: SessionStore) => SessionStore | Promise<SessionStore>;
+}): void;

package/dist/core/store-contracts/session-store-incarnation-contract.js

@@ -23,6 +23,10 @@ export async function sessionStoreIncarnationContract(make, hooks) {
             await store.dispose();
         }
     });
+    registerSessionIncarnationCases(run, hooks);
+    await settle();
+}
+export function registerSessionIncarnationCases(run, hooks) {
     run("a session created through acquire carries a token, and every later read of the row answers the same one", async (store) => {
         await store.acquire(ID_A);
         const first = await tokenOf(store, ID_A);
@@ -44,7 +48,7 @@ export async function sessionStoreIncarnationContract(make, hooks) {
         await store.acquire(ID_A);
         const first = await tokenOf(store, ID_A);
         assertToken(first, "first instance");
-        const second = hooks.reopen(store);
+        const second = await hooks.reopen(store);
         try {
             assert.equal(await tokenOf(second, ID_A), first, "an instance-local token would name a different occupant after every restart");
             await second.acquire(ID_A, { requireExisting: true });
@@ -88,5 +92,4 @@ export async function sessionStoreIncarnationContract(make, hooks) {
         assert.notEqual(forked, source, "a fork copies the history, never the occupant");
         assert.equal(await tokenOf(store, ID_B), source, "forking does not touch the source's occupant");
     });
-    await settle();
 }

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

@@ -716,10 +716,12 @@ export type TaskEvent = ({
      *  handed over again by the engine (once; a second loss is disclosed `resupply_exhausted`), so
      *  this counts what the summary swallowed, not what is gone. Present iff at least one. */
     summarizedCrossSessionMessages?: number;
-    /** CC post-compact file-restore parity (2026-07-03): the working files the engine
-     *  re-read into the summary (attachWorkingFiles), attachment order. A shell renders CC's
-     *  `Read {path} (…)` cards under the compaction divider from this. Absent when the feature is
-     *  off or nothing was attached. `truncated` = the content was clipped at the per-file cap. */
+    /** CC post-compact file-restore parity: the files this compaction's restore delivered (attachWorkingFiles) —
+     *  projected from the restore frames' delivery records, frame order. A shell renders CC's `Read {path} (…)`
+     *  cards under the compaction divider from this. `chars` = the characters of the file's data the frame
+     *  delivered (the line-numbered contents — the share itself counts the file's own text); `truncated` = the frame
+     *  holds a partial view. A file the restore named but did not send (too large, refused, gone, a PDF reference)
+     *  is not listed. Absent when the feature is off or nothing was delivered. */
     attachedFiles?: Array<{
         path: string;
         chars: number;

package/dist/core/task-registry-agent.js

@@ -380,6 +380,7 @@ export function registerBackgroundAgentLane(core, input) {
         ...(input.parentTaskId !== undefined ? { parentTaskId: input.parentTaskId } : {}),
         ...(input.parentSessionId !== undefined ? { parentSessionId: input.parentSessionId } : {}),
         ...(input.rootSessionId !== undefined ? { rootSessionId: input.rootSessionId } : {}),
+        ...(input.crossBoundaryTree !== undefined ? { crossBoundaryTree: input.crossBoundaryTree } : {}),
         ...(input.deliveryChannel !== undefined ? { channelState: input.deliveryChannel } : {}),
         ...(input.retainedContinuation !== undefined ? { retainedContinuation: input.retainedContinuation } : {}),
         ...(input.owner !== undefined ? { owner: input.owner } : {}),

package/dist/core/task-registry-shared.d.ts

@@ -248,6 +248,8 @@ export interface DurableAgentLane {
 }
 export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
     type: "background_agent";
+    /** The spawning tree's cross-boundary token ({@link RegisterBackgroundAgentInput.crossBoundaryTree}), compared by identity. */
+    crossBoundaryTree?: object;
     /** design/115 P3: aborting this cancels the child run (TaskStop / parent teardown). */
     abort: AbortController;
     /** Lineage axes, declared (registration always spread them into the handle; readers used
@@ -908,6 +910,9 @@ export declare function commitCompletionIdIfEmpty(target: {
     completionId?: string;
 }, value: string): string;
 export interface RegisterBackgroundAgentInput extends TaskAccess {
+    /** The spawning tree's cross-boundary token (`RunInternals.crossBoundaryTree`, the tree the child joins): a poll of this handle
+     *  from a leg of the SAME tree moves nothing across the device boundary — the child's bits are already in that tree. */
+    crossBoundaryTree?: object;
     /** design/153 §7.2d (件3c) — parked-resume registration shape: the handle is born PARKED (the
      *  pre-consume window keeps the live face's checkpoint arbitration; the consume flip
      *  {@link TaskRegistry.adoptParkedResume} is the only path to running). Pass the ticket's token

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

@@ -1,6 +1,7 @@
 import type { AgentTool, ExecutionEnv } from "../internal/harness.js";
 import type { ToolEffect } from "./types.js";
 import { type BackgroundHardKillOutcome, type BackgroundShellCapability, type BackgroundShellId } from "./background-shell.js";
+import type { BoundaryLegsGiven } from "./cross-boundary-taint.js";
 import type { WorkflowRunStore } from "./workflow-run-store.js";
 import { type BackgroundAgentStore } from "./background-agent-store.js";
 import type { TaskNotificationPayload } from "./task-notification.js";
@@ -638,6 +639,12 @@ export declare class TaskRegistry {
      *  one terminal notification (exit code / timeout / auto-stop / env-side kill). */
     registerMonitor(input: RegisterMonitorInput): string;
     registerWorkflow(input: RegisterWorkflowInput): string;
+    /** The legs one TaskOutput (`"output"`) or TaskStop (`"stop"`) call travels, read off the handle the call dispatches to by the same
+     *  resolution the poll and the stop take: a background shell's or a monitor's process lives in its own environment (the `env` leg
+     *  reaches that one); an agent handle that recorded the calling tree's own token moves nothing across the boundary; any other handle — an
+     *  agent of another tree, a workflow run, an id no live handle answers (a durable row read back) — is content from beyond the
+     *  boundary on a poll and nothing on a stop. */
+    boundaryLegsOf(id: string, access: TaskAccess, verb: "output" | "stop", tree: object): BoundaryLegsGiven;
     pollTask(id: string, access: TaskAccess, opts?: TaskPollOptions): Promise<UnifiedTaskResult>;
     stopTask(id: string, access: TaskAccess, opts?: TaskStopOptions): Promise<UnifiedTaskResult>;
     /** S2b — bounded delivery-confirmation wait (see deliverToRunningAgent). Test-tunable. */

package/dist/core/task-registry.js

@@ -863,6 +863,14 @@ export class TaskRegistry {
     registerWorkflow(input) {
         return registerWorkflowLane(this.core, input);
     }
+    boundaryLegsOf(id, access, verb, tree) {
+        const handle = this.resolveInternal(id.trim(), access);
+        if (handle?.type === "background_bash" || handle?.type === "monitor")
+            return { legs: ["env"], env: handle.env };
+        if (handle?.type === "background_agent" && handle.crossBoundaryTree === tree)
+            return { legs: [] };
+        return { legs: verb === "output" ? ["outside_read"] : [] };
+    }
     async pollTask(id, access, opts = {}) {
         const taskId = id.trim();
         const deadline = opts.block ? blockDeadline(opts.timeoutMs, Date.now()) : undefined;
@@ -1301,6 +1309,10 @@ export function createTaskOutputTool(opts) {
         ...toolFace("task-output"),
         description: composeTaskOutputDescription(caps),
         parameters: composeTaskOutputParams(caps),
+        boundaryLegsFor: (rawArgs, at) => {
+            const id = resolveTaskIdArg(rawArgs?.task_id);
+            return id ? opts.registry.boundaryLegsOf(id, { owner: opts.owner, scope: opts.scope, ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}) }, "output", at.tree) : { legs: [] };
+        },
         execute: async (rawArgs, ctx) => {
             const args = rawArgs;
             const id = resolveTaskIdArg(args.task_id);
@@ -1350,6 +1362,11 @@ export function createTaskStopTool(opts) {
         ...toolFace("task-stop"),
         description: composeTaskStopDescription(REGISTRY_TASK_TOOL_CAPS),
         parameters: TASK_STOP_PARAMS,
+        boundaryLegsFor: (rawArgs, at) => {
+            const a = rawArgs;
+            const id = resolveTaskIdArg(a?.task_id, a?.shell_id);
+            return id ? opts.registry.boundaryLegsOf(id, { owner: opts.owner, scope: opts.scope, ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}) }, "stop", at.tree) : { legs: [] };
+        },
         execute: async (rawArgs, ctx) => {
             const args = rawArgs;
             const id = resolveTaskIdArg(args.task_id, args.shell_id);

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

@@ -762,7 +762,7 @@ export interface TaskResult {
             finalVerifyInjected?: true;
             /** oracle-grounding gate (opus LOW 复审, additive): HOW MANY final-verification injections
              *  fired this run — 1 = the R9 one-shot only, 2 = R9 + the grounding re-entry (hard cap).
-             *  Present iff `finalVerifyInjected` is (the boolean stays for compatibility). */
+             *  Present iff `finalVerifyInjected` is (the boolean stays for compatibility, RL-1336-finalverify-bool). */
             finalVerifyInjections?: number;
             /** design/133: number of attachment blocks injected this run — turn-boundary bundles
              *  (todo/task reminders, changed-files notes, plan-mode re-reminders, listing drift frames;

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

@@ -301,8 +301,8 @@ export interface TaskSpec {
     systemPrompt?: string;
     /** The role base `core/role.base` selects: `"general"` (absent), `"code"`, `"coordinator"`, `"cowork"` (rendered from the
      *  mounted tools and the working directory); `systemPrompt` replaces whichever is selected. Not inherited (a child gets
-     *  the sub-agent persona). A value outside the closed set is refused at prepare. */
-    promptRole?: "general" | "code" | "coordinator" | "cowork";
+     *  the sub-agent persona). A value outside the closed set (`HOST_ROLES`, tested by `isHostRole`) is refused at prepare. */
+    promptRole?: import("../prompt-assembly/catalog/schema.js").HostRole;
     /** `"minimal"` leaves the core-behavior band out; the locked sections (mode sections in play among them) and
      *  `appendSystemPrompt` stay. Absent ⇒ standard. Rides the parent spec seat to every engine-built child (a clamp-table
      *  row: no child authors the standard form back). A value outside the closed set is refused at prepare. */
@@ -1312,10 +1312,10 @@ export interface TaskSpec {
      * `attachWorkingFiles` (LONGRUN-2; **default ON since 2026-07-03** — CC 198 hard-codes its
      * post-compact file restore, and LONGRUN-2 measured ≈2.3 extra read round-trips per compaction
      * without it): after each compaction, re-read the task's most recently READ files (CC
-     * readFileState semantics; falls back to modified-by-recency when read tracking is absent) and
-     * append their current contents to the summary (bounded: `maxFiles` default 3,
-     * `maxCharsPerFile` default 16k chars ≈ 4k tokens, plus a total cap that self-scales to ~15% of
-     * the model window). The `compacted` wire event carries the attached list as `attachedFiles`
+     * readFileState semantics; else modified-by-recency) the summary leaves out of view, with the Read tool's
+     * read, into attachment frames after the summary (`maxFiles` default 3, `maxCharsPerFile` default 16k chars
+     * of the file's own text, a total cap ~15% of the window in the file contents the frames send, line numbers
+     * included; a file over either is named, never sent in part). The `compacted` wire event lists the files whose contents were delivered as `attachedFiles`
      * (shell renders CC's post-compact Read cards). `false` opts out; an object customizes caps;
      * no-op when the task has no execution env (no hands, nothing to re-read).
      */

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

@@ -12,10 +12,12 @@ export declare class TaskSpecTightenError extends Error {
  *    the override can only ADD denials/asks). Either alone ⇒ that one. This is the central fix: a blind spread
  *    would drop the base policy entirely.
  *  - **every row of the clamp table** (`CLAMP_SET`: `handsReadOnly`, `interactiveTools`, `approvalReach`, the two
- *    containment faces, `readDenyPatterns`, `oneShot`, `memoryPersistenceCapable`, `fileHistory`, `promptForm`) — a base carrying the
- *    row's restricting value meeting an override that states a different one ⇒ **throw** (loosening); otherwise the
- *    restricting value wins if either side carries it, an add-only list unions, and an override writing `undefined`
- *    erases nothing.
+ *    containment faces, `readDenyPatterns`, `oneShot`, `memoryPersistenceCapable`, `fileHistory`, `promptForm`, and
+ *    `memory.enabled`) — a base carrying the row's restricting value meeting an override that states a different one ⇒
+ *    **throw** (loosening); otherwise the restricting value wins if either side carries it, an add-only list unions, and an
+ *    override writing `undefined` erases nothing. `memory` is an object seat with ONE clamped member (`enabled: false`):
+ *    the later declaration stands whole (its own scopes, write scope and knobs — never mixed with the base's) with
+ *    `enabled: false` stated on it when either side carries that.
  *  - **`shellGate`** — one value (`"always"`, the operator floor). Either side set ⇒ the floor stands; it cannot
  *    be loosened because absence is the only other state and an override cannot unset a base value.
  *  - **`onAsk`** — no safe automatic merge (the approver and the policy must be coordinated). Both set to

package/dist/core/tighten-task-spec.js

@@ -1,6 +1,6 @@
 import { combinePolicies } from "./tool-policy.js";
 import { clampPermissionMode } from "./ask-origin.js";
-import { CLAMP_SEATS, composeClampSeat, loosensClampSeat } from "./child-clamp-seats.js";
+import { CLAMP_SEATS, clampCellOf, clampCellPath, composeClampSeat, loosensClampSeat } from "./child-clamp-seats.js";
 export class TaskSpecTightenError extends Error {
     constructor(message) {
         super(message);
@@ -40,7 +40,7 @@ export function tightenTaskSpec(base, overrides) {
         const b = base[seat];
         const o = overrides[seat];
         if (loosensClampSeat(seat, b, o)) {
-            throw new TaskSpecTightenError(`tightenTaskSpec: cannot loosen ${seat} from ${JSON.stringify(b)} to ${JSON.stringify(o)} (override may only tighten)`);
+            throw new TaskSpecTightenError(`tightenTaskSpec: cannot loosen ${clampCellPath(seat)} from ${JSON.stringify(clampCellOf(seat, b))} to ${JSON.stringify(clampCellOf(seat, o))} (override may only tighten)`);
         }
         if (b !== undefined || o !== undefined)
             Object.assign(merged, { [seat]: composeClampSeat(seat, b, o) });

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

@@ -1,7 +1,7 @@
 /**
  * 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
+ * `details.type` cards it mints, and its declared FACE (family / boundary legs / 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

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

@@ -16,7 +16,7 @@ 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"),
+            family: "file-read", boundaryLegs: ["env"], effect: "read", contract: c("core.read@1"),
             pathTarget: { param: "file_path", aliases: ["path"], access: "read", base: "cwd", absent: "none" },
             ruleFace: { params: ["file_path", "path", "offset", "limit", "pages"] },
             renderHints: { summaryParams: ["file_path"] },
@@ -27,7 +27,7 @@ export const TOOL_CATALOG_ENTRIES = [
         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"),
+            family: "file-write", boundaryLegs: ["env"], effect: "write", contract: c("core.edit@1"),
             pathTarget: { param: "file_path", aliases: ["path"], access: "edit", skillScopeEligible: true, base: "cwd", absent: "none" },
             ruleFace: { params: ["file_path", "path", "old_string", "new_string", "replace_all"] },
             renderHints: { summaryParams: ["file_path"], approvalCard: "file-edit" },
@@ -38,7 +38,7 @@ export const TOOL_CATALOG_ENTRIES = [
         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"),
+            family: "file-write", boundaryLegs: ["env"], effect: "write", contract: c("core.write@1"),
             pathTarget: { param: "file_path", aliases: ["path"], access: "create", skillScopeEligible: true, base: "cwd", absent: "none" },
             ruleFace: { params: ["file_path", "path", "content"] },
             renderHints: { summaryParams: ["file_path"], approvalCard: "file-write" },
@@ -49,7 +49,7 @@ export const TOOL_CATALOG_ENTRIES = [
         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"),
+            family: "file-write", boundaryLegs: ["env"], effect: "write", contract: c("core.notebook_edit@1"),
             pathTarget: { param: "notebook_path", aliases: ["path"], access: "edit", base: "cwd", absent: "none" },
             ruleFace: { params: ["notebook_path", "path", "cell_id", "cell_type", "edit_mode", "new_source"] },
             renderHints: { userFacingName: "Edit Notebook", summaryParams: ["notebook_path"], approvalCard: "notebook-edit" },
@@ -59,7 +59,7 @@ export const TOOL_CATALOG_ENTRIES = [
         id: "bash", name: "Bash", source: "builtin", definedIn: "src/tools/fs/fs-bash.ts", mountedBy: ["hands"],
         cards: ["bash", "readonly_out_of_root", "read_unestablished", "bash_invalid_timeout"],
         face: {
-            family: "shell", effect: "write", contentOrigin: "execution", contract: c(FULL_SHELL_CONTRACT_ID),
+            family: "shell", boundaryLegs: ["env"], effect: "write", contentOrigin: "execution", contract: c(FULL_SHELL_CONTRACT_ID),
             ruleFace: SHELL_RULE_FACE,
             renderHints: { summaryParams: ["command"], approvalCard: "shell" },
             offloadThresholdChars: 30_000, compactable: true,
@@ -69,7 +69,7 @@ export const TOOL_CATALOG_ENTRIES = [
         id: "bash-readonly", name: "Bash", source: "builtin", definedIn: "src/tools/fs/fs-bash.ts", mountedBy: ["hands"],
         cards: ["bash", "readonly_out_of_root", "read_unestablished", "bash_invalid_timeout"],
         face: {
-            family: "shell", effect: "read", contract: c(READONLY_SHELL_CONTRACT_ID),
+            family: "shell", boundaryLegs: ["env"], effect: "read", contract: c(READONLY_SHELL_CONTRACT_ID),
             ruleFace: SHELL_RULE_FACE,
             renderHints: { summaryParams: ["command"], approvalCard: "shell" },
             offloadThresholdChars: 30_000, compactable: true,
@@ -79,7 +79,7 @@ export const TOOL_CATALOG_ENTRIES = [
         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"),
+            family: "search", boundaryLegs: ["env"], effect: "read", contract: c("core.grep@1"),
             pathTarget: { param: "path", access: "read", base: "root", absent: "base" },
             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"] },
@@ -90,7 +90,7 @@ export const TOOL_CATALOG_ENTRIES = [
         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"),
+            family: "search", boundaryLegs: ["env"], effect: "read", contract: c("core.glob@1"),
             pathTarget: { param: "path", access: "read", base: "root", absent: "base", patternParam: "pattern" },
             ruleFace: { params: ["pattern", "path", "max_results"] },
             renderHints: { userFacingName: "Search", summaryParams: ["pattern", "path"] },
@@ -100,7 +100,7 @@ export const TOOL_CATALOG_ENTRIES = [
     {
         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"),
+            family: "search", boundaryLegs: ["env"], effect: "read", contract: c("core.repo_map@1"),
             pathTarget: { param: "path", access: "read", base: "root", absent: "base" },
             ruleFace: { params: ["path", "max_chars", "max_files"] },
         },
@@ -108,62 +108,62 @@ export const TOOL_CATALOG_ENTRIES = [
     {
         id: "lsp", name: "LSP", source: "builtin", definedIn: "src/core/lsp.ts", mountedBy: ["hands"], cards: [],
         face: {
-            family: "search", effect: "read", contract: c("core.lsp@1"),
+            family: "search", boundaryLegs: ["env"], effect: "read", contract: c("core.lsp@1"),
             pathTarget: { param: "filePath", access: "read", base: "cwd", absent: "none" },
             ruleFace: { params: ["operation", "filePath", "line", "character", "query"] },
         },
     },
     {
         id: "artifact", name: ARTIFACT_TOOL_NAME, source: "builtin", definedIn: "src/tools/artifact/artifact-tool.ts", mountedBy: ["optional"], cards: ["artifact"],
-        face: { family: "other", effect: "write", contract: c("core.artifact@1"), ruleFace: { primaryParams: ["action"] }, renderHints: { summaryParams: ["action", "file_path", "url"] } },
+        face: { family: "other", boundaryLegs: "per_call", effect: "write", contract: c("core.artifact@1"), ruleFace: { primaryParams: ["action"] }, renderHints: { summaryParams: ["action", "file_path", "url"] } },
     },
-    { 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", "readonly_out_of_root", "read_unestablished"], face: { family: "other", effect: "write", contract: c("core.monitor@1"), ruleFace: shellRuleFace(["command", "description", "timeout_ms", "persistent"]), offloadThresholdChars: 10_000 } },
-    { id: "send-message", name: "SendMessage", protocol: ["teammate"], 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: ["delegation", "peerLane"], cards: ["list-agents"], face: { family: "protocol", effect: "read", aliases: ["ListPeers"], contract: c("core.list_agents@1") } },
-    { id: "read-inbox", name: "ReadInbox", source: "builtin", definedIn: "src/agents/read-inbox-tool.ts", mountedBy: ["peerLane"], cards: ["read-inbox"], face: { family: "protocol", effect: "read", contract: c("core.read_inbox@1"), offload: false, budgetExempt: true } },
-    { 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", protocol: ["delegated"], 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", protocol: ["structured"], 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", "7"), 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", "7"), 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", "2"), 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", protocol: ["teammate"], 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", protocol: ["teammate"], 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", protocol: ["teammate"], 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: "enter-worktree", name: "EnterWorktree", source: "builtin", definedIn: "src/tools/worktree.ts", mountedBy: ["hands"], cards: ["worktree"], face: { family: "other", boundaryLegs: ["env"], 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", boundaryLegs: ["env"], 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", boundaryLegs: ["env"], 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", boundaryLegs: ["env"], 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", boundaryLegs: "per_call", 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", boundaryLegs: "per_call", effect: "write", contract: TASK_STOP_CONTRACT } },
+    { id: "monitor", name: "Monitor", source: "builtin", definedIn: "src/tools/monitor.ts", mountedBy: ["backgroundTasks"], cards: ["monitor-start", "readonly_out_of_root", "read_unestablished"], face: { family: "other", boundaryLegs: ["env"], effect: "write", contract: c("core.monitor@1"), ruleFace: shellRuleFace(["command", "description", "timeout_ms", "persistent"]), offloadThresholdChars: 10_000 } },
+    { id: "send-message", name: "SendMessage", protocol: ["teammate"], source: "builtin", definedIn: "src/agents/send-message-tool.ts", mountedBy: ["delegation", "hostInternals", "peerLane"], cards: ["send-message"], face: { family: "protocol", boundaryLegs: ["outside_write"], 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", boundaryLegs: [], effect: "read", contract: c("core.agent_transcript@1") } },
+    { id: "list-agents", name: "ListAgents", source: "builtin", definedIn: "src/agents/list-agents-tool.ts", mountedBy: ["delegation", "peerLane"], cards: ["list-agents"], face: { family: "protocol", boundaryLegs: [], effect: "read", aliases: ["ListPeers"], contract: c("core.list_agents@1") } },
+    { id: "read-inbox", name: "ReadInbox", source: "builtin", definedIn: "src/agents/read-inbox-tool.ts", mountedBy: ["peerLane"], cards: ["read-inbox"], face: { family: "protocol", boundaryLegs: [], effect: "read", contract: c("core.read_inbox@1"), offload: false, budgetExempt: true } },
+    { id: "workflow", name: "Workflow", source: "builtin", definedIn: "src/orchestration/run-workflow-tool.ts", mountedBy: ["workflow"], cards: ["workflow-run"], face: { family: "delegate", boundaryLegs: [], effect: "write", contract: c("core.workflow@1") } },
+    { id: "report-blocked", name: "ReportBlocked", protocol: ["delegated"], source: "builtin", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["always"], cards: [], face: { family: "scaffold", boundaryLegs: [], 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", boundaryLegs: [], effect: "read", contract: c("core.report_findings@1") } },
+    { id: "structured-output", name: "StructuredOutput", protocol: ["structured"], source: "synthetic", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["optional"], cards: [], face: { family: "scaffold", boundaryLegs: [], 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", boundaryLegs: [], 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", boundaryLegs: [], 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", boundaryLegs: [], 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", boundaryLegs: [], 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", boundaryLegs: [], 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", boundaryLegs: [], 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", boundaryLegs: ["outside_read"], effect: "read" } },
+    { id: "memory-search", name: "memory_search", source: "builtin", definedIn: "src/core/memory-engine/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", boundaryLegs: [], effect: "read", contentOrigin: "local", contract: c("core.memory_search@1", "7"), offload: false } },
+    { id: "memory-get", name: "memory_get", source: "builtin", definedIn: "src/core/memory-engine/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", boundaryLegs: [], effect: "read", contentOrigin: "local", contract: c("core.memory_get@1", "7"), offload: false } },
+    { id: "memory-index", name: "memory_index", source: "builtin", definedIn: "src/core/memory-engine/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", boundaryLegs: [], effect: "read", contentOrigin: "local", contract: c("core.memory_index@1", "2"), offload: false } },
+    { id: "memory-list", name: "memory_list", source: "builtin", definedIn: "src/core/shared-memory/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", boundaryLegs: [], 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", boundaryLegs: [], effect: "read", contract: c("core.memory_read@1"), offload: false } },
+    { id: "cron-create", name: "CronCreate", protocol: ["teammate"], source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-create"], face: { family: "other", boundaryLegs: ["env"], effect: "write", contract: c("core.cron_create@1") } },
+    { id: "cron-delete", name: "CronDelete", protocol: ["teammate"], source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-delete"], face: { family: "other", boundaryLegs: ["env"], effect: "idempotent", contract: c("core.cron_delete@1") } },
+    { id: "cron-list", name: "CronList", protocol: ["teammate"], source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-list"], face: { family: "other", boundaryLegs: ["env"], 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", boundaryLegs: ["env"], 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 },
+        face: { family: "web", boundaryLegs: ["outside_read"], 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 },
+        face: { family: "web", boundaryLegs: ["outside_read"], 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, protocol: ["teammate"], protocolUnderCeiling: true, 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, protocol: ["teammate"], protocolUnderCeiling: true, 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, protocol: ["teammate"], protocolUnderCeiling: true, 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, protocol: ["teammate"], protocolUnderCeiling: true, 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", protocol: ["observer"], 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", protocol: ["goal"], source: "builtin", definedIn: "src/orchestration/goal.ts", mountedBy: ["scenario"], cards: [], face: { family: "scaffold", effect: "read" } },
+    { 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", boundaryLegs: [], effect: "idempotent", contract: c("core.todo_write@1") } },
+    { id: "task-create", name: TASK_CREATE_TOOL_NAME, protocol: ["teammate"], source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", boundaryLegs: [], effect: "write", contract: c("core.task_create@1") } },
+    { id: "task-get", name: TASK_GET_TOOL_NAME, protocol: ["teammate"], source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", boundaryLegs: [], effect: "read", contract: c("core.task_get@1") } },
+    { id: "task-update", name: TASK_UPDATE_TOOL_NAME, protocol: ["teammate"], source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", boundaryLegs: [], effect: "idempotent", contract: c("core.task_update@1") } },
+    { id: "task-list", name: TASK_LIST_TOOL_NAME, protocol: ["teammate"], source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task-list"], modelGate: "task-scaffold", face: { family: "plan", boundaryLegs: [], 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", boundaryLegs: [], contentOrigin: "local", contract: c("core.agent@1") } },
+    { id: "observer-report", name: "ObserverReport", protocol: ["observer"], source: "builtin", definedIn: "src/agents/observer.ts", mountedBy: ["scenario"], cards: [], face: { family: "scaffold", boundaryLegs: [], effect: "write", contract: c("core.observer_report@1") } },
+    { id: "declare-done", name: "DeclareDone", protocol: ["goal"], source: "builtin", definedIn: "src/orchestration/goal.ts", mountedBy: ["scenario"], cards: [], face: { family: "scaffold", boundaryLegs: [], effect: "read" } },
 ];
 export const ENGINE_CARDS = Object.freeze({
     mcp: "src/core/mcp.ts",

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

@@ -0,0 +1,49 @@
+/**
+ * The READER of an MCP server's `toolFaces` declaration ({@link McpServerSpec.toolFaces}, the per-tool FACE overlay): `readToolFaces(declared)`,
+ * the face-side sibling of `readToolAxes` (`mcp-server-spec.ts`). The engine's preparation door and its MCP materialization entrance ask it
+ * (`locked-config.ts`), and a host that assembles the field from JSON (a console's write door, a deployment intake) asks it at its own door:
+ * one reading of the declaration, whoever asks and whenever. The mount ({@link applyMcpToolFaces}) then consumes the reader's copy and never
+ * the raw object, and judges each face against the materialized schema with the very judge this reader ends in.
+ *
+ * It sits beside `mcp-server-spec.ts` rather than in the runner directory the mount lives in: it is the declaration's door, not a station of
+ * the prepare path, and the public surface is tiered by where a symbol is declared (`readToolAxes` is `advanced` for the same reason).
+ */
+import { type McpServerSpec } from "./mcp-server-spec.js";
+/**
+ * {@link readToolFaces}'s answer. `ok: true` hands back a copy of the faces that the reader itself built, plain data and none of the caller's own
+ * objects; `faces` is absent when nothing is declared (no key at all, or an empty record). `ok: false` carries one sentence (its detail cut at
+ * 240 characters) naming the tool and the member that did not fit. What it may quote of the declaration is its structure and nothing of its content:
+ * a tool or member name (quoted, a tool name cut at 80 characters), the word a closed table refuses, a key or a list entry over its bound (its
+ * first 40 characters), a key a pattern parameter names, a count and its bound. It never quotes display text (`userFacingName`, `activity`) or
+ * the entries of a list that fits. These are the mount's judge's own sentences, the ones it announces at the listing, so the reader and the mount
+ * tell one operator one thing; `readToolAxes` refuses in the same sentence shape and names no word because an axis word is never a name the
+ * operator needs echoed to find the fault.
+ */
+export type ToolFacesRead = {
+    ok: true;
+    faces?: NonNullable<McpServerSpec["toolFaces"]>;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * The one reader of a raw `toolFaces` declaration — {@link McpServerSpec.toolFaces}, the per-tool FACE overlay — and the face-side sibling of
+ * `readToolAxes` (the safety axes `effect` / `egress` / `irreversibility` are that declaration's, read once, there). The preparation door asks it
+ * for every MCP server of a task (`config.tool_face_invalid` refuses the whole prepare — the code a caller tool's bad face has at the caller door;
+ * a declaration the entry's own plain-data receipt refuses first keeps `config.invalid_argument`), `materializeMcpTools` asks it per server (that
+ * server's dial fails, the same code), and a host that assembles the field from JSON asks it at its own door and hands the engine what it answered.
+ *
+ * It judges the declaration alone, which is everything the declaration can say without the tool's schema: the receipt of a plain-data
+ * declaration (`receiveDeclaration`: a Proxy, a map, a class instance, a getter that throws, a cycle, a nesting past the engine's one
+ * depth, a tool named `__proto__` are refusals that say where they sit), the shape of each face (the members the types have, each of its
+ * kind), then the very judge the mount runs (`toolFaceProblem`) minus the checks that need the schema — the five closed words
+ * (`family`, `pathTarget.access` / `base` / `absent`, `renderHints.approvalCard`), the bounds, and the cross-member rules (a write path
+ * target's `base: "root"` / `absent: "base"`, an inert `patternParam`). The checks that read the schema (a `param` that is a top-level
+ * property, the keys an approval card needs, the names a summary or a rule face lists) and the one that reads the minted tool (a result card
+ * lives under the tool's own namespace) stay with the listing, where the schema and the tool are known.
+ *
+ * Any one face that does not fit refuses the WHOLE declaration (`ok: false`): a face is an overlay applied whole or not at all, and a
+ * dropped face is a tool mounted without the protection its operator declared. Absent ⇒ `{ ok: true }`. An empty record is no declaration
+ * either; an empty face `{}` under a tool name is kept as written. An empty tool name is refused (no tool answers to it).
+ */
+export declare function readToolFaces(declared: unknown): ToolFacesRead;