@sema-agent/core 7.48.0 → 7.49.0

package/dist/core/synthetic-read-verdict.js

@@ -1,4 +1,4 @@
-import { describeThrown, engineSettlementOf, refuseOutOfContractDecision } from "./tool-policy.js";
+import { attestationOf, describeThrown, refuseOutOfContractDecision } from "./tool-policy.js";
 import { skillRowRefusal } from "./skill-grant.js";
 import { applyPersistedTightening } from "./persisted-rule-arms.js";
 import { readOrgRuleLane, readPersistedRuleLane } from "./rule-lane-reads.js";
@@ -62,7 +62,7 @@ export function createSyntheticReadJudge(layers) {
             }
             if (read.action !== "deny")
                 return undefined;
-            if (engineSettlementOf(d, req) !== undefined) {
+            if (attestationOf(read, req)?.settlement !== undefined) {
                 cannot(layer, "approval_seat", "the policy would ask an approver, who is never consulted for a visibility probe");
                 return undefined;
             }

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

@@ -9,6 +9,7 @@
 import type { ActorAssertion } from "../internal/llm.js";
 import type { TaskResult } from "./task-result.js";
 import type { TaskNotificationPayload } from "./task-notification.js";
+import type { ProviderCondition, ProviderConditionSource } from "../brain/provider-dialect.js";
 /**
  * Identity fields carried by every CONTENT event of a task stream (design/99 §E2 — lightweight message
  * identity). Both are OPTIONAL and ADDITIVE; a consumer that ignores them is unchanged.
@@ -198,6 +199,25 @@ export interface BrainStatus {
      * `control_request_progress` frame, where CC itself makes the key optional.
      */
     errorStatus?: number;
+    /**
+     * What the provider said about the account or its capacity on the response being retried — one word of
+     * `PROVIDER_CONDITIONS`, judged off the provider dialect table keyed by where the request went
+     * (`brain/provider-dialect.ts`). Fills the gap {@link errorStatus} states: {@link errClass} `rate_limit`
+     * buckets a 429 that clears on its own with one the provider pinned on the account. Only the RETRYABLE words
+     * ride a retry frame (`throttled` / `overloaded` / `unknown`): a response judged `quota_exhausted` or
+     * `stop_other` is not retried — its word rides the terminal (`terminal.detail.providerCondition`) — unless
+     * the provider's own `x-should-retry: true` sent it back into the ladder, in which case the frame states the
+     * word the response was judged by.
+     *
+     * PRESENCE — exactly the connect-ladder backoff frames that carry {@link errorStatus}: a response named the
+     * failure. ABSENT on a transport failure, a stall, a mid-stream tear, the output-cap re-send (a re-shaped
+     * request, not a provider condition), `circuit_open`, and the terminal `recovered` / `gave_up` frames. A
+     * consumer reads absence as "not judged" — the same reading as `unknown`: back off, do not claim a quota.
+     */
+    providerCondition?: ProviderCondition;
+    /** Which evidence {@link providerCondition} rests on (`unified_header` / `provider_code` / `status`). Present
+     *  exactly when it is. */
+    providerConditionSource?: ProviderConditionSource;
 }
 /**
  * design/97 CORE-8 (③): one lightweight TOOL-ACTIVITY beat surfaced from a running task, for a per-agent live
@@ -282,9 +302,19 @@ export type TaskEvent = ({
 } & TaskEventIdentity) | ({
     type: "tool_start";
     toolCallId: string;
-    toolName: string; /** {@link ToolSpec.label} when distinct from `toolName` (design/71 liveness); omitted otherwise. */
+    toolName: string;
+    /** {@link ToolSpec.label} when distinct from `toolName`; omitted otherwise. */
     label?: string;
     args: unknown;
+    /**
+     * @contract tool_start.recovered — `true` on a start frame the engine minted at the moment it CLOSED a call
+     * whose start never went out on this stream: an interrupted run's reconcile closing a call the loop never
+     * reached, or a resumed process closing a call a dead process had announced. Every `tool_end` is preceded by
+     * a `tool_start` with the same id on the same stream — this frame is how that holds for those closes. `args`
+     * is the call's input as the transcript recorded it. It asserts NOTHING about execution (whether the call
+     * ran is the paired `tool_end.notExecuted`); absent on every start the loop announced itself.
+     */
+    recovered?: true;
 } & TaskEventIdentity) | ({
     /**
      * A LIVENESS TICK for a tool call that is still running. Emitted on the run's own queue between this
@@ -477,17 +507,41 @@ export type TaskEvent = ({
      * denied by which LAYER), `settlement` (how the ask this pass consumed ENDED — a person's yes or
      * no with the channel's attribution and, on a bare "no", no note; a window that elapsed and whose;
      * nobody reachable; the wait aborted…) and `origin` (who ASKED). It is the SAME object the
-     * `permissionDenied` observer received and the engine's per-call sideband recorded — one mint, three
+     * `permissionDenied` observer received and the call's occurrence record holds — one mint, three
      * faces — so a renderer never branches on prose to tell "a person refused" from "the window closed".
      *
      * WHERE IT COMES FROM — never inferred here: the gate mints it at its exit, the decide lane mints it
      * from the host's decision facts joined with the row's persisted origin.
      *
-     * ABSENT on every frame of a call the gate never saw (a tool call on an unarmed gate, a deferred
-     * re-issue, a reconcile-recovered orphan). A gated call's frame ALWAYS carries it — an absence is
-     * not a fact about the call, and a consumer must not read one out of it.
+     * THE LATEST RECORD: a station that refuses the call AFTER its gate exit (the shell read admission that
+     * re-establishes what the gate judged and finds it moved, a resumed leg's re-checks) adds one more
+     * record, minted as a veto — the refusing layer is the disposition, an approval already given stays on
+     * the settlement — and this member is that record. A call refused after its gate allowed it therefore
+     * reads `denied`, never `allowed` beside an error, and {@link isError} is `true` whatever the tool's own
+     * result said.
+     *
+     * ABSENT on every frame of a call no gate exit on this stream saw (a tool call on an unarmed gate, a
+     * deferred re-issue, a call a reconcile closed that never reached a gate here). A gated call's frame
+     * ALWAYS carries it — an absence is not a fact about the call, and a consumer must not read one out of it.
      */
     gate?: import("./gate-outcome.js").GateOutcome;
+    /**
+     * @contract tool_end.wireName — on a REFUSED call's frame only (`gate.disposition.kind === "denied"`): the name of
+     * the tool the call dispatched to on the live roster — the name the gate judged and the deny observer's `toolName`
+     * — where {@link toolName} is the model's spelling (an alias, a retired name the roster still answers to). A
+     * refusals list keyed on the tool reads this member; absent on every other frame, and on a refused frame whose
+     * station did not know the roster name.
+     */
+    wireName?: string;
+    /**
+     * @contract tool_end.notExecuted — `true` when the engine has POSITIVE evidence this call never executed:
+     * the loop closed it without running it (a sibling settled by a halted batch, a call a turn interrupt
+     * reached before it started) or an interrupted run's reconcile closed a call this run never started.
+     * ABSENT means only that no such evidence exists — never "it ran": a call closed with its outcome unknown
+     * (a reconcile at the next process start, a call interrupted mid-execution) carries no mark, because
+     * telling a consumer it did not run could invite a replay of a write that already took effect.
+     */
+    notExecuted?: true;
     /**
      * design/99 §E1 — `true` when {@link output} was SIZE-bounded by core (the full body exceeded the cap and
      * was degraded to a truncated string). Lets a consumer detect truncation programmatically instead of

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

@@ -11,7 +11,7 @@ import type { NestedUsage } from "./tool-spec.js";
  * `"suspended"` (design/45) is a **non-terminal** outcome: the task hit a durable tool-policy gate
  * (`ask` with a `CheckpointStore` wired) and persisted a checkpoint instead of finishing — resume it
  * with `runner.resume(checkpointToken, outcome)`. v1 contract: it is only safe at the **top-level
- * `runTask` boundary**; the orchestrators (cascade/teacher/verify/team) map an unexpected `suspended`
+ * `runTask` boundary**; the orchestrators (cascade/verify/repair-loop) map an unexpected `suspended`
  * to `failed` + `errorCode:"unexpected.suspended"` and pass the token up (§11 Q6, hard boundary).
  *
  * `"needs_review"` (design/76 §2.5, dry-run / shadow; design/80 D-B, plan-gate) is also a **non-terminal,

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

@@ -426,15 +426,34 @@ export interface TaskSpec {
      */
     tools?: ToolSpec[];
     /**
-     * per-scenario tool ROSTER (true unmount, NOT a permission gate): wire names listed here
-     * are removed from the mounted tool set AFTER assembly — their schemas never reach `tools[]`
-     * (unlike a policy deny, which gates calls but still ships the schema bytes every request —
-     * measured at zero token savings). Exact wire-name match (aliases resolve to their
-     * canonical wire name at mount, so list the canonical name). Unknown names are ignored (a
-     * center-distributed roster may cover tools this deployment doesn't mount). The injected
-     * ToolSearch cannot be excluded (it mounts after this filter, only when deferred tools exist).
-     * ⚠️ Excluding structural tools (submit_output / ReportBlocked) can strand the task — the caller
-     * owns that risk, same trust level as assembling `spec.tools` itself.
+     * The run's tool ALLOWLIST — the availability selector (true unmount, NOT a permission gate): when set, the run may use only the
+     * tools it names, out of everything the engine would otherwise mount for it (the caller's tools, the hands, the engine's own
+     * tools, MCP and A2A tools, scenario and leg tools); the rest never reach `tools[]`. Omitted ⇒ the default set (a delegated
+     * child: whatever its parent could use). `[]` ⇒ no tools. An entry `"*"` ⇒ no allowlist on this layer (still bounded by the
+     * ceiling a spawning run handed down — a child's `"*"` never widens its parent).
+     *
+     * Entries are read like {@link excludeTools}: a wire name or an alias it declares, `mcp__srv` / `mcp__srv__*` for every tool
+     * of a server (including tools it lists later), a glob over the tool segment. The engine resolves the list against its OWN
+     * roster at prepare — a host passes the names it was given and never computes a complement. A name no tool answers to, a
+     * protocol-wide `mcp__*`, or an entry that is not a string is REFUSED at prepare (`config.tool_face_control`). The same
+     * compiled selector is applied on every later roster change (an MCP refresh or re-dial, the deferred-search lane): an exact name
+     * admits no new tool. Deferral is reached through ToolSearch, so a list that leaves it out defers nothing.
+     *
+     * A tool a leg relies on (a delegated child's ReportBlocked, a teammate's SendMessage, a goal iteration's DeclareDone, an
+     * observer's report tool — the catalog's protocol column) is not an allowlist's to name; a denylist that reaches one on such a
+     * leg is refused at prepare.
+     */
+    allowTools?: string[];
+    /**
+     * per-scenario tool ROSTER removal (true unmount, NOT a permission gate): the tools this list names are removed from the
+     * mounted tool set AFTER assembly — their schemas never reach `tools[]` (unlike a policy deny, which gates calls but still
+     * ships the schema bytes every request — measured at zero token savings). The DENY half of the run's tool selector, read
+     * exactly as a sub-agent's denied tools are: a wire name or an alias it declares; `Tool(content)` names the whole `Tool`;
+     * `mcp__srv` / `mcp__srv__*` / a glob over the tool segment for a server's tools, `mcp__*` for every MCP tool (including tools
+     * a server lists later). A name no tool answers to, `"*"`, or an entry that is not a string is REFUSED at prepare
+     * (`config.tool_face_control`) — a misspelt exclusion guards nothing. A deny wins over {@link allowTools}.
+     * ⚠️ A list that reaches a tool this kind of leg relies on (see {@link allowTools}) is refused; excluding a host-requested
+     * structural tool (the structured-output tool) can still strand the task — the caller owns that risk.
      */
     excludeTools?: string[];
     /**
@@ -854,6 +873,20 @@ export interface TaskSpec {
      * (#123). The write faces are untouched.
      */
     readDenyPatterns?: readonly import("../tools/fs/read-deny.js").ReadDenyEntry[];
+    /**
+     * TASK-layer rows ADDED to the write-protection table ({@link readDenyPatterns}' law): the run's table is the deployment's
+     * ({@link RunnerDeps.writeProtectedPaths}) UNION these; `[]` ≡ absent; no task-layer value removes a deployment row. A
+     * covered write is the judge's mandated ask (`write_protection`), as for a deployment row. Bad shapes refuse at prepare
+     * (`config.invalid_argument`); rides every engine-built child spec add-only.
+     */
+    writeProtectedAdditions?: readonly import("./write-protect.js").WriteProtectedEntry[];
+    /**
+     * TASK-layer denies ADDED to the compliance posture ({@link readDenyPatterns}' law): the run's deny set is the deployment's
+     * ({@link RunnerDeps.compliancePostureResolver}) UNION these; `[]` ≡ absent; nothing here removes a deployment deny. A hit
+     * is refused exactly as a deployment deny is. Members outside the closed capability set refuse at prepare
+     * (`config.invalid_argument`) — never a silently dropped deny; rides every engine-built child spec add-only.
+     */
+    complianceAdditionalDenies?: readonly import("./compliance.js").ComplianceCapability[];
     /**
      * design/199 件A — the TASK layer's read-face containment declaration
      * ({@link import("../tools/fs/containment-face.js").ContainmentFace}). "roots" pins this task (and, via the

package/dist/core/terminal-cause.d.ts

@@ -9,6 +9,9 @@
  * `runner/terminal-projection.ts` — the one cause→plane derivation.
  */
 import type { AssertAllKeysHandled } from "./ask-origin.js";
+import type { ProviderCondition, ProviderConditionSource } from "../brain/provider-dialect.js";
+import type { RequestRoute } from "../brain/request-route.js";
+import type { ModelOutputInvalidCause, OutputLimit } from "../internal/llm.js";
 /**
  * WHY a run ended — ONE tagged cause, and the ONLY terminal record a {@link TaskResult} carries. The run
  * loop's terminal arbitration used to decide a `status` word plus seven optional plane fields one by one
@@ -32,6 +35,14 @@ import type { AssertAllKeysHandled } from "./ask-origin.js";
  */
 export type TerminalCause = {
     kind: "completed";
+    /**
+     * A machine-readable account beside a completion, for the one shape that completes yet may be short:
+     * `finish_reason_unknown` — the final turn's provider ended it with a stream-end word the brain does not read
+     * (`AssistantMessage.finishReasonUnknown`); the turn was kept as the model left it, and the run announced the
+     * word (`route.finish_reason_unknown`). PRESENCE: only when the final assistant message carried that seat and the
+     * run completed on it; every other completion leaves it absent.
+     */
+    detail?: TerminalCompletedDetail;
 } | {
     kind: "failed";
     /**
@@ -69,14 +80,16 @@ export type TerminalCause = {
     /** Human-readable failure text. */
     message?: string;
     /**
-     * A machine-readable account of the failure beside `code`, for the one shape a consumer offers its own way out
-     * of: `provider_rejected` — the provider REFUSED the request as sent (a 4xx answer) and that refusal named this
-     * result. `status` is the refusal's HTTP status (`TaskResult.apiFailure.status`, the same value);
-     * `code` the provider's own word for it from its error envelope (`AssistantMessage.apiErrorCode`), when it
-     * stated one. PRESENCE: only on that terminal — a run whose higher-ranked cause named the result, a 5xx, a
-     * connect / stream failure, an in-band error inside a 200 and every non-provider failure leave it absent.
-     * A 401 / 403 (credentials) and a 429 (rate limit) are refusals too: branch on `status` (or on `code` above)
-     * to tell a request a consumer may change and resend from one it may not.
+     * A machine-readable account of the failure beside `code` — the fact the failure's mint point stated, projected
+     * once ({@link TerminalFailureDetail}; branch on `detail.kind`, never on `message`):
+     *  - `provider_rejected` — the provider REFUSED the request as sent (a 4xx answer) and that refusal named this
+     *    result. `status` is the refusal's HTTP status (`TaskResult.apiFailure.status`, the same value); `code` the
+     *    provider's own word (`AssistantMessage.apiErrorCode`); `route` the request's route. A run whose
+     *    higher-ranked cause named the result, a 5xx, a connect / stream failure and an in-band error inside a 200
+     *    carry none. A 401 / 403 (credentials) and a 429 (rate limit) are refusals too: branch on `status`.
+     *  - `coded` — the run threw a coded error (this `code`) whose throw site stated a structured `detail`.
+     *  - `model_output_invalid` — the model's final turn failed because its tool calls could not be executed.
+     * PRESENCE: only when the arm that named this result has such a fact to project; absent otherwise.
      */
     detail?: TerminalFailureDetail;
     /**
@@ -144,14 +157,84 @@ export type TerminalCause = {
      */
     restoreMode?: "snapshot" | "park_only";
 };
-/** The machine-readable account a `failed` cause may carry ({@link TerminalCause}). `kind` is closed; one member. */
-export interface TerminalFailureDetail {
+/** The machine-readable account a `completed` cause may carry ({@link TerminalCause}). `kind` is closed; one member. */
+export interface TerminalCompletedDetail {
+    kind: "finish_reason_unknown";
+    /** The provider's stream-end word, in the provider echo shape (`?` when it had bytes outside it). */
+    finishReasonUnknown: string;
+}
+/**
+ * The machine-readable account a `failed` cause may carry ({@link TerminalCause}) — the ONE projection of a fact the
+ * failure's mint point already stated, carried as it was stated (a missing fact stays missing; nothing is re-derived
+ * from the message). `kind` is closed:
+ *  - `provider_rejected` — the provider REFUSED the request as sent (a 4xx answer) and that refusal named the result:
+ *    the terminal message's refusal account (`apiErrorStatus` / `apiErrorCode` / the provider-condition verdict / the
+ *    request's `apiErrorRoute`).
+ *  - `coded` — a failure THROWN with a machine code whose throw site stated a structured `detail` beside it (e.g. a
+ *    `CheckpointError`'s `{ reason }` on `resume.parent_constraint_mismatch`): that detail, as a JSON-plain snapshot.
+ *    `terminal.code` is the same error's code.
+ *  - `model_output_invalid` — the model's turn failed because its tool calls could not be executed: the terminal
+ *    message's `modelOutputInvalid` account.
+ * New members join with a minor; a consumer that branches on `kind` keeps a default arm.
+ */
+export type TerminalFailureDetail = {
     kind: "provider_rejected";
     /** The refusal's HTTP status, 400–499. */
     status: number;
     /** The provider's own word for the refusal (its error envelope's `error.code`, else `error.type`), when stated. */
     code?: string;
-}
+    /**
+     * What the refusal says about the account — the engine's closed word for it (`PROVIDER_CONDITIONS`), judged off
+     * the provider dialect table by where the request went: `quota_exhausted` (stop; someone must act or a window
+     * must reset), `throttled` / `overloaded` / `unknown` (a retryable condition the retry budget ran out on, or the
+     * provider's own `x-should-retry: false` stopped), `stop_other` (credentials, model access, the request itself).
+     * The terminal's reading of the same verdict the call's retry frames carried. Present whenever the terminal
+     * message states one (`AssistantMessage.providerCondition`); a host-minted message that did not judge leaves it
+     * absent.
+     */
+    providerCondition?: ProviderCondition;
+    /** Which evidence {@link providerCondition} rests on. Present exactly when it is. */
+    providerConditionSource?: ProviderConditionSource;
+    /** The terminal message's `providerResetAtMs`, carried beside a `quota_exhausted` condition. */
+    providerResetAtMs?: number;
+    /**
+     * The route the refused request took (`AssistantMessage.apiErrorRoute`): where its credential came from, how it
+     * rode, which knob named its root — the knob words of `ROUTE_CREDENTIAL_PAIRING`, never a key value or a URL.
+     * Present whenever the terminal message states one (the first-party brains always do); a host-minted message that
+     * states none leaves it absent.
+     */
+    route?: RequestRoute;
+} | {
+    kind: "coded";
+    /**
+     * The thrown error's own `detail`, as its throw site stated it — a snapshot of its JSON-plain members (strings,
+     * finite numbers, booleans, null, and arrays / plain objects of those, bounded; a member of any other kind is left
+     * out; bytes — an `ArrayBuffer` view, an index-keyed object — are never a record). A member under a credential
+     * name (the env-credential judge's names: `password`, `apiKey`, `token` …) stands as `"[redacted]"`, unread; every
+     * other string leaf passes the secret-tier redaction (credential shapes masked; a path is kept — it rides this
+     * structured seat, never `message`); a member whose key is not JSON-safe (visible ASCII 1–128, nothing the
+     * redaction would mask) is left out. Read off the same link of the error's `cause` chain whose `code` became
+     * `terminal.code`. PRESENCE: only when that link carried a plain-object `detail` with at least one such member — a
+     * code thrown without one (or a higher-ranked terminal that named the result) leaves the whole account absent.
+     */
+    detail: CodedFailureDetail;
+} | {
+    kind: "model_output_invalid";
+    /** Which drop cause failed the turn (`MODEL_OUTPUT_INVALID_CAUSES`: `truncated` — arguments cut before they
+     *  parsed; `unnamed` — a call with no tool name). The same words `task.tool_turn_incomplete` announces. */
+    cause: ModelOutputInvalidCause;
+    /** With `truncated`: the output-cap facts the stream reported (the cap stop, the counted output, the request's
+     *  cap) — what the brain's sentence words as its cap clause. */
+    outputLimit?: OutputLimit;
+};
+/** A JSON-plain value as a `coded` account carries it. */
+export type CodedFailureDetailValue = string | number | boolean | null | readonly CodedFailureDetailValue[] | {
+    readonly [key: string]: CodedFailureDetailValue;
+};
+/** The `coded` account's body: the thrown error's `detail` members ({@link TerminalFailureDetail}). */
+export type CodedFailureDetail = {
+    readonly [key: string]: CodedFailureDetailValue;
+};
 /**
  * The endings of a `userPromptSubmit` hook that keep a prompt from being submitted — the closed set of
  * {@link TerminalBlockedDetail.cause} words:

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

@@ -11,10 +11,11 @@ export declare class TaskSpecTightenError extends Error {
  *  - **`toolPolicy`** — both set ⇒ `combinePolicies(base, override)` (deny-wins; the base's denials survive,
  *    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.
- *  - **`handsReadOnly`** — `true` is stricter. `base:true` + `override:false` ⇒ **throw** (loosening). Otherwise
- *    the stricter (`true` if either is true) wins.
- *  - **`approvalReach`** — `"none"` (nobody can be asked) is the only word; a base declaration survives an override that
- *    omits it or writes `undefined`.
+ *  - **every row of the clamp table** (`CLAMP_SET`: `handsReadOnly`, `interactiveTools`, `approvalReach`, the two
+ *    containment faces, `readDenyPatterns`, `oneShot`, `memoryPersistenceCapable`, `fileHistory`) — 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.
  *  - **`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,5 +1,6 @@
 import { combinePolicies } from "./tool-policy.js";
 import { clampPermissionMode } from "./ask-origin.js";
+import { CLAMP_SEATS, composeClampSeat, loosensClampSeat } from "./child-clamp-seats.js";
 export class TaskSpecTightenError extends Error {
     constructor(message) {
         super(message);
@@ -21,34 +22,28 @@ export function tightenTaskSpec(base, overrides) {
             merged[field] = [...new Set([...(b ?? []), ...(o ?? [])])];
         }
     }
-    for (const faceKey of ["readFace", "writeFace"]) {
-        if (base[faceKey] === "roots" && overrides[faceKey] === "open") {
-            throw new TaskSpecTightenError(`tightenTaskSpec: cannot loosen ${faceKey} from "roots" to "open" (override may only tighten)`);
-        }
-        if (base[faceKey] !== undefined || overrides[faceKey] !== undefined) {
-            merged[faceKey] = base[faceKey] === "roots" || overrides[faceKey] === "roots" ? "roots" : (overrides[faceKey] ?? base[faceKey]);
+    {
+        const b = base.allowTools;
+        const o = overrides.allowTools;
+        if (b !== undefined && o !== undefined && !b.includes("*")) {
+            const wider = o.filter((entry) => !b.includes(entry));
+            if (wider.length > 0)
+                throw new TaskSpecTightenError(`tightenTaskSpec: cannot widen allowTools beyond the base list (override names ${JSON.stringify(wider)}; the override may only narrow)`);
         }
+        const kept = o ?? b;
+        if (kept !== undefined)
+            merged.allowTools = [...kept];
+        else
+            delete merged.allowTools;
     }
-    if (base.readDenyPatterns !== undefined || overrides.readDenyPatterns !== undefined) {
-        const seen = new Set();
-        const union = [];
-        for (const e of [...(base.readDenyPatterns ?? []), ...(overrides.readDenyPatterns ?? [])]) {
-            const key = typeof e === "string" ? `i:${e}` : `${e.caseSensitive === true ? "s" : "i"}:${e.pattern}`;
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            union.push(e);
+    for (const seat of CLAMP_SEATS) {
+        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)`);
         }
-        merged.readDenyPatterns = union;
-    }
-    if (base.handsReadOnly === true && overrides.handsReadOnly === false) {
-        throw new TaskSpecTightenError("tightenTaskSpec: cannot loosen handsReadOnly from true to false (override may only tighten)");
-    }
-    if (base.handsReadOnly !== undefined || overrides.handsReadOnly !== undefined) {
-        merged.handsReadOnly = base.handsReadOnly === true || overrides.handsReadOnly === true;
-    }
-    if (base.approvalReach !== undefined || overrides.approvalReach !== undefined) {
-        merged.approvalReach = base.approvalReach === "none" || overrides.approvalReach === "none" ? "none" : (overrides.approvalReach ?? base.approvalReach);
+        if (b !== undefined || o !== undefined)
+            Object.assign(merged, { [seat]: composeClampSeat(seat, b, o) });
     }
     if (base.permissionMode !== undefined && overrides.permissionMode !== undefined) {
         const { effective, clamped } = clampPermissionMode(overrides.permissionMode, base.permissionMode);

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

@@ -55,16 +55,14 @@ export declare const TOOL_FACES: Readonly<Record<string, ToolFaceDeclaration>>;
  */
 export declare const ENGINE_BUILTIN_TOOL_NAMES: readonly string[];
 /**
- * The engine's HAND tools, once each, with the other spellings they answer to: the catalog rows mounted by `hands` — what a run
- * mounts for itself over an execution environment (the file and shell band, the worktree pair, the band's background-shell
- * pair). A delegated child's tool-name lists govern these beside the tools the delegation tool hands it, so the spawn reads
- * this set rather than a list of its own.
+ * EVERY tool the catalog describes, once per wire name, with the other spellings it answers to — the engine's side of the one
+ * universe a delegated child's tool-name lists govern (beside the tools the delegation tool hands it and the protocol tools
+ * its spawning run mounts). The spawn reads this set rather than a list of its own: a definition a catalog row adds later is
+ * governed the day it lands, whatever band mounts it.
  */
-export declare const HAND_TOOLS: ReadonlyArray<{
+export declare const ENGINE_TOOLS: ReadonlyArray<{
     readonly name: string;
     readonly aliases?: readonly string[];
 }>;
-/** The wire names of {@link HAND_TOOLS}. */
-export declare const HAND_TOOL_NAMES: readonly string[];
 /** Is this name one the engine mounts itself ({@link ENGINE_BUILTIN_TOOL_NAMES})? A caller tool, an MCP tool or a skill tool is not. */
 export declare function isEngineBuiltinToolName(name: string): boolean;

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

@@ -110,14 +110,14 @@ export const TOOL_CATALOG_ENTRIES = [
     { 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", 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: "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", 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-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", source: "synthetic", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["optional"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.structured_output@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") } },
@@ -130,9 +130,9 @@ export const TOOL_CATALOG_ENTRIES = [
     { 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", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-create"], face: { family: "other", effect: "write", contract: c("core.cron_create@1") } },
-    { id: "cron-delete", name: "CronDelete", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-delete"], face: { family: "other", effect: "idempotent", contract: c("core.cron_delete@1") } },
-    { id: "cron-list", name: "CronList", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-list"], face: { family: "other", effect: "read", contract: c("core.cron_list@1") } },
+    { id: "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: "web-fetch", name: "WebFetch", source: "builtin", definedIn: "src/tools/web.ts", mountedBy: ["scenario"], cards: ["web-fetch"],
@@ -143,13 +143,13 @@ export const TOOL_CATALOG_ENTRIES = [
         face: { family: "web", effect: "read", contentOrigin: "external", contract: c("core.web_search@1"), ruleFace: { primaryParams: ["query"] }, renderHints: { summaryParams: ["query"] }, compactable: true },
     },
     { id: "todo-write", name: TODO_WRITE_TOOL_NAME, source: "builtin", definedIn: "src/tools/todo.ts", mountedBy: ["scenario"], cards: ["todo"], modelGate: "task-scaffold", face: { family: "plan", effect: "idempotent", contract: c("core.todo_write@1") } },
-    { id: "task-create", name: TASK_CREATE_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "write", contract: c("core.task_create@1") } },
-    { id: "task-get", name: TASK_GET_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "read", contract: c("core.task_get@1") } },
-    { id: "task-update", name: TASK_UPDATE_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "idempotent", contract: c("core.task_update@1") } },
-    { id: "task-list", name: TASK_LIST_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task-list"], modelGate: "task-scaffold", face: { family: "plan", effect: "read", contract: c("core.task_list@1") } },
+    { id: "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", source: "builtin", definedIn: "src/agents/observer.ts", mountedBy: ["scenario"], cards: [], face: { family: "scaffold", effect: "write", contract: c("core.observer_report@1") } },
-    { id: "declare-done", name: "DeclareDone", source: "builtin", definedIn: "src/orchestration/goal.ts", mountedBy: ["scenario"], cards: [], face: { family: "scaffold", effect: "read" } },
+    { 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" } },
 ];
 export const ENGINE_CARDS = Object.freeze({
     mcp: "src/core/mcp.ts",
@@ -182,11 +182,10 @@ function deepFreeze(value) {
 deepFreeze(TOOL_CATALOG_ENTRIES);
 export const TOOL_FACES = Object.freeze(Object.fromEntries(TOOL_CATALOG_ENTRIES.map((e) => [e.id, e.face])));
 export const ENGINE_BUILTIN_TOOL_NAMES = Object.freeze([...new Set(TOOL_CATALOG_ENTRIES.filter((e) => e.source === "builtin").map((e) => e.name))]);
-export const HAND_TOOLS = Object.freeze([...new Set(TOOL_CATALOG_ENTRIES.filter((e) => e.mountedBy.includes("hands")).map((e) => e.name))].map((name) => {
-    const aliases = [...new Set(TOOL_CATALOG_ENTRIES.filter((e) => e.name === name && e.mountedBy.includes("hands")).flatMap((e) => e.face.aliases ?? []))];
+export const ENGINE_TOOLS = Object.freeze([...new Set(TOOL_CATALOG_ENTRIES.map((e) => e.name))].map((name) => {
+    const aliases = [...new Set(TOOL_CATALOG_ENTRIES.filter((e) => e.name === name).flatMap((e) => e.face.aliases ?? []))];
     return Object.freeze(aliases.length > 0 ? { name, aliases: Object.freeze(aliases) } : { name });
 }));
-export const HAND_TOOL_NAMES = Object.freeze(HAND_TOOLS.map((t) => t.name));
 export function isEngineBuiltinToolName(name) {
     return ENGINE_BUILTIN_TOOL_NAMES.includes(name);
 }

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

@@ -42,6 +42,12 @@ import type { AssertAllKeysHandled } from "./ask-origin.js";
  *  mounting the card (design/388 §2.5 boundary ①). */
 export declare const TOOL_APPROVAL_CARDS: readonly ["file-edit", "file-write", "notebook-edit", "shell", "fetch", "plan", "question", "generic"];
 export type ToolApprovalCard = (typeof TOOL_APPROVAL_CARDS)[number];
+/** Membership in the closed set — the one screen a stored or declared card word passes before it is read. */
+export declare function isToolApprovalCard(word: unknown): word is ToolApprovalCard;
+/** The cards only an engine-defined tool owns: a caller or protocol tool cannot declare one, and the card is minted
+ *  from the engine's own judgment of the call, never from a row's declaration. */
+export declare const RESERVED_APPROVAL_CARDS: readonly ["question", "plan"];
+export type ReservedApprovalCard = (typeof RESERVED_APPROVAL_CARDS)[number];
 /** How a path-targeting tool touches its target. `read` never enters a write-confinement face. */
 export declare const TOOL_PATH_ACCESSES: readonly ["read", "create", "edit"];
 export type ToolPathAccess = (typeof TOOL_PATH_ACCESSES)[number];
@@ -182,6 +188,7 @@ export interface ToolRenderHints {
     activity?: string;
     summaryParams?: readonly string[];
     resultCards?: readonly string[];
+    /** The card family this tool asks under; absent reads `generic`. `question` / `plan` are the engine's own tools' cards — a declaration of either is refused. */
     approvalCard?: ToolApprovalCard;
 }
 /**
@@ -217,6 +224,39 @@ export interface ToolFaceDeclaration {
     compactable?: true;
     budgetExempt?: true;
 }
+/**
+ * The kinds of leg a run can be, as far as which tools a leg itself relies on: a delegated child (every lane a delegation
+ * tool, a workflow or a team spawns), a NAMED delegated child (a teammate), an iteration of a goal loop, an observer sidecar,
+ * a run with an output schema (it finishes by submitting through the structured-output tool). A catalog row's
+ * {@link ToolCatalogEntry.protocol} names the kinds whose legs carry that tool as part of their protocol.
+ */
+export declare const TOOL_LEG_KINDS: readonly ["delegated", "teammate", "goal", "observer", "structured"];
+export type ToolLegKind = (typeof TOOL_LEG_KINDS)[number];
+/**
+ * One layer of a tool selector, as data: an allowed-tools list (absent = no allowlist on this layer) and a denied-tools list,
+ * each a frozen copy of the entries a list was written with. A run's own layer is its `allowTools` and `excludeTools`; the
+ * layers above it are the ones the run that spawned it was bounded by, plus that run's own.
+ */
+export interface ToolSelectorLayer {
+    readonly allow?: readonly string[];
+    readonly deny: readonly string[];
+}
+/**
+ * The compiled tool selector of one run — the one answer to "is this tool available on this run", read at the roster valve
+ * and on every later roster change (an MCP refresh or re-dial, the deferred-search lane), and handed down as the ceiling of
+ * every run this one spawns (`layers`). A tool is admitted when it is a protocol tool of this run's leg kind, or when every
+ * layer admits it: the layer's allowlist (if any) reaches it and its denylist does not.
+ */
+export interface ToolSelector {
+    readonly layers: readonly ToolSelectorLayer[];
+    admits(tool: {
+        readonly name: string;
+        readonly aliases?: readonly string[];
+    }): boolean;
+    /** Can ANY tool of the protocol peer whose minted prefix is `prefix` (`mcp__srv__`) be admitted — read off the lists alone,
+     *  never off what the peer lists now, so a tool the peer lists later is judged by the same answer. */
+    admitsPeer(prefix: string): boolean;
+}
 /**
  * One row of the static tool catalog (design/388 §2.1 "静态目录"). Keyed by DEFINITION identity, not by
  * name: two definitions may share a wire name (the full and the read-only shell both answer to `Bash`),
@@ -240,6 +280,13 @@ export interface ToolCatalogEntry {
     face: ToolFaceDeclaration;
     /** A `modelGate` class the default-bundle assembler stamps on this definition's default arm. */
     modelGate?: string;
+    /** The leg kinds whose legs rely on this tool as part of their protocol: on such a leg the tool's availability is not a
+     *  selector's to decide (an allowlist need not name it), and a denylist that reaches it there is a contradiction the run
+     *  refuses at prepare. */
+    protocol?: readonly ToolLegKind[];
+    /** A protocol row the leg shares with the run that spawned it (the team task-list family a teammate shares with its leader): on its
+     *  leg the leg's OWN lists do not decide it, but the ceiling still does — the leg holds it exactly when its spawner may. */
+    protocolUnderCeiling?: true;
 }
 /**
  * The band-membership table over the mount tags: a host derives its hand band as the definitions listed under a