@sema-agent/core 7.52.0 → 7.54.0

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

@@ -677,6 +677,10 @@ export type TaskEvent = ({
      *  pre-compaction context size. CC parity = `SDKCompactBoundary{trigger, pre_tokens, preserved_segment}`. */
     type: "compacted";
     trigger: "auto" | "manual" | "forced";
+    /** The pass this frame CONCLUDES — the value the pass's `compaction_started` frame carried. A landing is
+     *  always preceded by its start, so the engine sets it on every `compacted` frame; it is optional in the
+     *  type only so a literal a host builds by hand stays valid. */
+    pass?: string;
     tokensBefore: number;
     /** How much context this compaction FREED, as the engine measured it: one structural sum over
      *  the pre-messages minus the same sum over the post-messages, inside the pass. **The only
@@ -712,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;
@@ -763,8 +769,9 @@ export type TaskEvent = ({
      * - `"mooted"` — the pass did not run to its end: a manual request no boundary could serve
      *   (`trigger:"manual"`, `reason:"task_ending"`), or a request withdrawn / a pass cut in flight by its
      *   caller — a `compact({ signal })` withdrawal, `halt()`, `interrupt()`, `destroy()` or the task's own
-     *   `signal` (`reason:"cancelled"`), on any trigger: `"auto"`, `"manual"` or `"forced"`. Read
-     *   `"mooted"` with its `trigger` — it is not a manual-only outcome.
+     *   `signal` (`reason:"cancelled"`), on any trigger: `"auto"`, `"manual"` or `"forced"`, or a turn-boundary
+     *   pass in flight that the task's own end cut — a limit, a timeout (`reason:"task_ending"`, with the
+     *   `pass` the start announced). Read `"mooted"` with its `trigger` — it is not a manual-only outcome.
      */
     type: "compaction_outcome";
     outcome: Exclude<CompactOutcome, "compacted"> | "suppressed";
@@ -772,6 +779,37 @@ export type TaskEvent = ({
     trigger: "auto" | "manual" | "forced";
     /** Optional human-readable detail (mirrors the trace frame's reason where one exists). */
     reason?: string;
+    /** The pass this frame CONCLUDES — the value its `compaction_started` frame carried. Present exactly when a
+     *  start was announced for the pass this frame ends, which makes it `failed` or `mooted` (a pass that ran its
+     *  summary call and did not land, or was cut while it ran). Absent on every outcome of a pass that never
+     *  started — `blocked`, `suppressed`, `disabled`, `noop`, a `mooted` request no boundary served — and on the
+     *  rapid-refill `disabled` frame, which reports a state the landing before it caused, not that pass's end. */
+    pass?: string;
+} & TaskEventIdentity) | ({
+    /**
+     * A compaction pass is under way: the engine has committed to it and is about to produce its summary.
+     * Until now compaction was announced only when it ended (`compacted`, or `compaction_outcome` for a pass
+     * that did not land), so a consumer watching a summary call wait out a provider's retries had nothing to
+     * show for the minutes in between.
+     *
+     * Minted at the one place a pass commits — after the trigger gate, a valid cut point and the
+     * `preCompact` hook (a blocking hook ends the pass before it starts), before the summary provider is
+     * consulted or the model is called — by every lane that compacts: the turn boundary (`"auto"`, `"manual"`,
+     * and `"forced"` under trim pressure), the prompt-too-long recovery and guard-chain arm B (`"forced"`), and
+     * the end-of-task summary (`"auto"`). Retries inside the pass's model call never mint a second one.
+     *
+     * Pairing: exactly one frame concludes each started pass, carrying the same `pass` — `compacted` when it
+     * lands, `compaction_outcome{failed | mooted}` when it does not. A pass that never reaches this point
+     * (`blocked`, `suppressed`, `disabled`, `noop`) announces nothing here and its outcome carries no `pass`.
+     * `pass` is unique across runs, so a consumer multiplexing several tasks on one stream pairs on `pass` alone.
+     */
+    type: "compaction_started";
+    /** Same three-state vocabulary (and the same value) the pass hands the `preCompact` hook and its concluding frame. */
+    trigger: "auto" | "manual" | "forced";
+    /** The pass's identity: an opaque engine-minted id (uuidv7), carried by the frame that concludes the pass. */
+    pass: string;
+    /** The engine clock (epoch ms) at the moment the pass committed. */
+    startedAt: number;
 } & TaskEventIdentity) | ({
     /**
      * TB telemetry B3: the engine injected a SYSTEM steering message (a deadline nudge

package/dist/core/task-notification.js

@@ -2,7 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { escapeEnvelopeTag, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
 import { egressText } from "./untrusted-egress.js";
 import { PEER_MESSAGE_NOTICE } from "../agents/peer-admission.js";
-import { buildCrossSessionEnvelope, CROSS_SESSION_MESSAGE_NOTICE, neutralizePeerBody } from "../agents/cross-session-envelope.js";
+import { buildCrossSessionEnvelope, CROSS_PRINCIPAL_MESSAGE_NOTICE, CROSS_SESSION_MESSAGE_NOTICE, neutralizePeerBody } from "../agents/cross-session-envelope.js";
 export const TASK_NOTIFICATION_TERMINAL_STATUSES = Object.freeze(["completed", "failed", "killed", "cancelled"]);
 export const NOTIFICATION_INJECTION_OUTCOMES = Object.freeze(["queued", "parked", "parked_durably", "dropped_duplicate"]);
 export function isNotificationInjectionOutcome(value) {
@@ -88,7 +88,7 @@ export function renderAgentMessageFrame(frame) {
 }
 export function renderCrossSessionMessageFrame(frame) {
     const { body, ...fields } = frame;
-    return `${buildCrossSessionEnvelope(fields, body)}\n\n${CROSS_SESSION_MESSAGE_NOTICE}`;
+    return `${buildCrossSessionEnvelope(fields, body)}\n\n${fields.fromScope !== undefined ? CROSS_PRINCIPAL_MESSAGE_NOTICE : CROSS_SESSION_MESSAGE_NOTICE}`;
 }
 export function renderCrossSessionNoticeLine(notice) {
     return sanitizeUntrustedText(notice.text);

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,13 +301,13 @@ 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. */
     promptForm?: "minimal";
-    /** The deployment's center binding (a scenario name): selects the adopted center artifact's `scope.binding` overlays; rides the parent spec seat; out of grammar (non-blank, ≤ 128) ⇒ `config.prompt_selector_invalid`. */
+    /** The deployment's binding (a scenario name): a prompt selector value, read by every overlay's `when.binding` (center, deploy and task alike); rides the parent spec seat; out of grammar (non-blank, ≤ 128 Unicode code points — `PROMPT_BINDING_MAX_CHARS`, counted `[...s].length`, not UTF-16 units) ⇒ `config.prompt_selector_invalid`. */
     promptBinding?: string;
     /**
      * APPEND a caller block to the assembled system prompt, keeping the engine's base + harness/safety blocks
@@ -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",