@sema-agent/core 7.6.3 → 7.8.0

package/dist/core/runner/prepare-inherited-gate.d.ts

@@ -53,7 +53,7 @@ export interface PrepareInheritedGateInput {
      *  / `oneShot` / `clientContext` / `principal` / `additionalDirectories` / `additionalReadDirectories` / `envFacts` /
      *  `memoryPersistenceCapable` / `getApiKeyAndHeaders` / `checkpointStore` / `backgroundScope` / `enablePlanMode` (the ctx
      *  enrichment's trusted seats). Never mutated. */
-    spec: Pick<TaskSpec, "shellGate" | "durableApproval" | "onAsk" | "onQuestion" | "handsReadOnly" | "interactiveTools" | "oneShot" | "clientContext" | "principal" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable" | "getApiKeyAndHeaders" | "checkpointStore" | "backgroundScope" | "enablePlanMode">;
+    spec: Pick<TaskSpec, "shellGate" | "durableApproval" | "onAsk" | "onQuestion" | "handsReadOnly" | "interactiveTools" | "oneShot" | "clientContext" | "principal" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable" | "getApiKeyAndHeaders" | "checkpointStore" | "backgroundScope" | "enablePlanMode" | "excludeAllTools">;
     /** borrowed-readonly — the deployment seats: `autoMode.denialLimit` (the rebuilt trackers' bounds), `memoryScopeAdmission` /
      *  `deploymentMemoryScopes` / `compliancePostureResolver` (the governed-provenance bit), `onError` (the screening-face crash
      *  lane), `onNotice` (the stop seat's notice), `executionEnv` (the hook-env identity predicate), `delegationEntryCaps` (resolved

package/dist/core/runner/prepare-inherited-gate.js

@@ -162,6 +162,7 @@ export function prepareInheritedGate(input) {
     const fullShellReachable = handsEnabled &&
         !(executionEnv instanceof StubExecutionEnv) &&
         spec.handsReadOnly !== true &&
+        spec.excludeAllTools !== true &&
         !(toolFaceSnapshot.exclude?.includes("Bash") ?? false);
     const { gateStopRef, stopForDenialLimit } = createDenialLimitStop({ sessionId, runId, onNotice: deps.onNotice, abort: abortRun });
     const delegationEntryCapsResolved = resolveDelegationEntryCaps(deps.delegationEntryCaps);

package/dist/core/runner/prepare-lsp.d.ts

@@ -11,10 +11,11 @@
  * with no await is extracted as a sync function — an `async` wrapper would open a microtask window).
  * Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
  */
-import type { AgentTool, ExecutionEnv } from "../../internal/harness.js";
+import type { ExecutionEnv } from "../../internal/harness.js";
 import type { LspDiagnosticsRegistry } from "../lsp-diagnostics.js";
 import type { RunnerDeps, TaskSpec } from "../types.js";
 import type { Prepared } from "./contracts.js";
+import { RosterBuilder } from "../tool-roster.js";
 export interface PrepareLspInput {
     /** borrowed-readonly — the REBOUND spec. Read: `lspManager` (the per-task manager, outranks the deployment's),
      *  `lspDiagnostics` (the lane's opt-out), `handsReadOnly` (a read-only run has no lane). Never mutated. */
@@ -34,9 +35,9 @@ export interface PrepareLspInput {
     /** borrowed-readonly — the tracked-cwd cell the hands band writes; the nudge READS `current` per call as its
      *  resolution base (identity is the contract — the band's `cd` handling writes this exact cell). */
     handsCwdRef: Prepared["cwdRef"];
-    /** borrowed-mutable — the run's shared roster (identity is the contract). Writer here: ONE push (the LSP tool)
+    /** borrowed-mutable — the run's roster builder (identity is the contract). Writer here: ONE mount (the LSP tool)
      *  when a manager exists. */
-    tools: AgentTool[];
+    roster: RosterBuilder;
     /** borrowed-mutable — the env-hand membership set the read-posture observer projects; writer here: `add("LSP")`
      *  on the mount. */
     envHandToolNames: Set<string>;

package/dist/core/runner/prepare-lsp.js

@@ -1,11 +1,12 @@
 import { createLspTool, gitCheckIgnoreFilter, resolveLspPath } from "../lsp.js";
 import { pathToUri } from "../lsp-protocol.js";
+import { RosterBuilder } from "../tool-roster.js";
 export function prepareLsp(input) {
-    const { spec, deps, executionEnv, taskRootFinal, handsEnabled, sessionId, handsCwdRef, tools, envHandToolNames } = input;
+    const { spec, deps, executionEnv, taskRootFinal, handsEnabled, sessionId, handsCwdRef, roster, envHandToolNames } = input;
     const lspManager = spec.lspManager ?? deps.lspManager;
     if (lspManager) {
         const lspRoot = taskRootFinal;
-        tools.push(createLspTool(lspManager, { isPathIgnored: gitCheckIgnoreFilter(executionEnv, lspRoot), env: executionEnv }));
+        roster.mount(createLspTool(lspManager, { isPathIgnored: gitCheckIgnoreFilter(executionEnv, lspRoot), env: executionEnv }), { source: "builtin", mountedBy: "optional" });
         envHandToolNames.add("LSP");
     }
     const lspDiagnostics = spec.lspDiagnostics !== false && lspManager?.diagnostics !== undefined && handsEnabled && spec.handsReadOnly !== true

package/dist/core/runner/prepare-memory-engine-session.d.ts

@@ -16,12 +16,12 @@
  * One read changed spelling and nothing else: the declared-class announcement read `mcp?.statuses` while `mcp` had
  * long been the protocol-tools phase's non-null handle; the optional chain was dead and is now the plain member read.
  */
-import type { AgentTool } from "../../internal/harness.js";
 import type { LockedPreflight } from "../locked-config.js";
 import type { MaterializedMcp } from "../mcp.js";
 import { type DelegationContentSafety } from "../memory-engine/delegation-provenance.js";
 import type { RunnerDeps, TaskSpec } from "../types.js";
 import type { Prepared, RunInternals } from "./contracts.js";
+import { RosterBuilder } from "../tool-roster.js";
 export interface PrepareMemoryEngineSessionInput {
     /** borrowed-readonly — the mounted engine session, or undefined (the ARMING fact's first half). Read: `pollution`
      *  (the mark face), `contentSafety` (the own half of the narrowing), `settlement` (the seat + the receipt ledger),
@@ -64,10 +64,10 @@ export interface PrepareMemoryEngineSessionInput {
     spec: Pick<TaskSpec, "tools">;
     /** borrowed-readonly — the env-hand roster (membership minted at the mount sites); read by the classification. */
     envHandToolNames: ReadonlySet<string>;
-    /** borrowed-mutable — the run's ONE tool roster. Writer here: the wrap pass REPLACES entries in place
-     *  (`tools[i] = wrapped`, identity-tracked so a re-run never stacks wrappers); see the roster's writer table on
+    /** borrowed-mutable — the run's roster builder. Writer here: the wrap pass REPLACES entries in place
+     *  (`roster.replaceAt(i, wrapped)`, identity-tracked so a re-run never stacks wrappers); see the roster's writer table on
      *  {@link Prepared.tools}. */
-    tools: AgentTool[];
+    roster: RosterBuilder;
     /** borrowed-mutable — the re-runnable wrap pass's seat (the protocol-tools phase mints it; the rebuild seam re-runs it
      *  after a refresh re-splice). Writer: THIS phase installs the pass and runs it once. */
     contentOriginWrapRef: {

package/dist/core/runner/prepare-memory-engine-session.js

@@ -5,8 +5,10 @@ import { protocolOf } from "../protocol-table.js";
 import { deliverEngineNotice } from "../types.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { fileArgPath } from "../../tools/fs/safety.js";
+import { RosterBuilder } from "../tool-roster.js";
 export function prepareMemoryEngineSession(input) {
-    const { memoryEngineSession, internals, memoryDelegationEvidence, externalContentTargetActive, lockedPreflight, mcp, sessionId, runId, deps, provenanceForChildrenRef, delegationSettlementRef, spec, envHandToolNames, tools, contentOriginWrapRef } = input;
+    const { memoryEngineSession, internals, memoryDelegationEvidence, externalContentTargetActive, lockedPreflight, mcp, sessionId, runId, deps, provenanceForChildrenRef, delegationSettlementRef, spec, envHandToolNames, roster, contentOriginWrapRef } = input;
+    const tools = roster.tools;
     const delegationProvenanceChannel = internals?.delegationProvenance;
     if (memoryEngineSession !== undefined || delegationProvenanceChannel !== undefined) {
         const pollution = memoryEngineSession?.pollution;
@@ -196,7 +198,7 @@ export function prepareMemoryEngineSession(input) {
                     },
                 };
                 contentOriginWrapped.add(wrapped);
-                tools[i] = wrapped;
+                roster.replaceAt(i, wrapped);
             }
         };
         contentOriginWrapRef.current();

package/dist/core/runner/prepare-offload-wrappers.js

@@ -1,4 +1,6 @@
-import { DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, firstPartyOffloadPolicy, InMemoryToolResultStore, RunnerSharedToolResultStore, ScopedToolResultStore, withToolResultOffload, } from "../tool-result-store.js";
+import { DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, InMemoryToolResultStore, RunnerSharedToolResultStore, ScopedToolResultStore, withToolResultOffload, } from "../tool-result-store.js";
+import { faceOf } from "../tool-roster.js";
+const FIRST_PARTY_OFFLOAD_THRESHOLD_CHARS = 50_000;
 export function prepareOffloadWrappers(input) {
     const { spec, deps, resume, offloadScope, sessionId } = input;
     const nestedStats = { tokens: 0, turns: 0, tasks: 0, costMicroUsd: 0, anyUnpriced: false };
@@ -31,10 +33,10 @@ export function prepareOffloadWrappers(input) {
         return withToolResultOffload(tool, offloadStore, perTool?.offloadThresholdChars ?? offloadThreshold, sessionId, () => offloadReachableToolsRef.current?.());
     };
     const firstPartyOffload = (tool) => {
-        const policy = firstPartyOffloadPolicy(tool.name);
-        if (policy.offload === false)
-            return maybeOffload(tool, policy);
-        return maybeOffload(tool, explicitGlobalThreshold === undefined ? policy : undefined);
+        const face = faceOf(tool);
+        if (face.offload === false)
+            return maybeOffload(tool, { offload: false });
+        return maybeOffload(tool, explicitGlobalThreshold === undefined ? { offloadThresholdChars: face.offloadThresholdChars ?? FIRST_PARTY_OFFLOAD_THRESHOLD_CHARS } : undefined);
     };
     const remoteToolOffload = (tool) => {
         if (explicitGlobalThreshold !== undefined)

package/dist/core/runner/prepare-park-ask.d.ts

@@ -30,6 +30,7 @@ import type { CwdRef } from "../../tools/fs/fs-shared.js";
 import { type ContentAskBinding } from "./content-ask-bindings.js";
 import type { AskLane, ParkAsk, Prepared, SuspendSaga } from "./contracts.js";
 import type { createRuleOffersOf } from "./permission-rule-lanes.js";
+import { type ToolRosterDeltaSeat } from "../tool-roster.js";
 export interface PrepareParkAskInput {
     /** borrowed-readonly — the in-stream ask lane, or undefined when the gate machinery is inactive (then both closures are
      *  absent). Read: `composedCallSignal` (the fence and the delivery race), `approvalPreviewOf` (the row's preview). */
@@ -49,6 +50,9 @@ export interface PrepareParkAskInput {
     /** borrowed-readonly — the leg's checkpoint store, or undefined (then `suspendAsk` is absent — the park predicate's store
      *  term). Read: the declared fidelity; the saga writes to it. */
     checkpointStore: CheckpointStore | undefined;
+    /** borrowed-readonly — the leg's delta seat (design/388 B18): the park reads the gated tool's identity off its
+     *  CURRENT roster snapshot so the row carries who the action was minted against. */
+    toolRosterDeltas: ToolRosterDeltaSeat;
     /** borrowed-readonly — the wiring-manifest phase's park predicate (`parkLane.effective`): arms `suspendAsk`. */
     parkLaneArmed: boolean;
     /** borrowed-readonly — the question-face phase's routability predicate (the mounted question tool is the engine's own,

package/dist/core/runner/prepare-park-ask.js

@@ -14,6 +14,7 @@ import { checkpointScopeOf } from "./checkpoint-scope.js";
 import { CONTENT_ASK_BINDING_CAP } from "./content-ask-bindings.js";
 import { DEFAULT_UNATTENDED_APPROVAL_TTL_MS, publishCommittedSuspend, sanitizedTtlMs } from "./park-commit.js";
 import { remoteEnvFailureNote } from "./remote-env-retry.js";
+import { callFaceSeat, parkedToolIdentity, parkedToolFace } from "../tool-roster.js";
 class ParkRefusal extends Error {
     constructor(message, options) {
         super(message, options);
@@ -21,7 +22,7 @@ class ParkRefusal extends Error {
     }
 }
 export function prepareParkAsk(input) {
-    const { askLane, saga, spec, deps, sessionId, checkpointStore, parkLaneArmed, contentAskRoutable, liveQuestionFace, mountedQuestionTool, contentAskBindings, lateStrandedAnswers, discloseStrandedAnswers, onAsk, runtimeCaps, inheritedUnavailableAsks, basePolicyForResumeEdit, budgetSnapshot, handsCwdRef, offloadStore, ownedEnv, incompleteSuspendAdapter, session, sessions, suspendChainBase, maxSuspends, remoteEnvFailures, shellGatedBash, shellGatedMonitor, effectiveShellGate, durableApproval, priorLedger, liveSpendRef, resourceTotal, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, ruleOffersOf, now, humanReviewRef, abortController, harness, pausedRef } = input;
+    const { askLane, saga, spec, deps, sessionId, checkpointStore, toolRosterDeltas, parkLaneArmed, contentAskRoutable, liveQuestionFace, mountedQuestionTool, contentAskBindings, lateStrandedAnswers, discloseStrandedAnswers, onAsk, runtimeCaps, inheritedUnavailableAsks, basePolicyForResumeEdit, budgetSnapshot, handsCwdRef, offloadStore, ownedEnv, incompleteSuspendAdapter, session, sessions, suspendChainBase, maxSuspends, remoteEnvFailures, shellGatedBash, shellGatedMonitor, effectiveShellGate, durableApproval, priorLedger, liveSpendRef, resourceTotal, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, ruleOffersOf, now, humanReviewRef, abortController, harness, pausedRef } = input;
     if (askLane === undefined || saga === undefined)
         return { parkAsk: undefined };
     const { composedCallSignal, approvalPreviewOf } = askLane;
@@ -157,6 +158,7 @@ export function prepareParkAsk(input) {
                         args: presented.value,
                         toolCallId: req.toolCallId,
                         budget: budgetSnapshot,
+                        ...callFaceSeat(req.face),
                         ...(handsCwdRef !== undefined ? { cwd: handsCwdRef.current } : {}),
                     }, cutSignal)), cutSignal);
                     if (reprojectedRaced.tag === "aborted")
@@ -277,6 +279,7 @@ export function prepareParkAsk(input) {
                         kind: "tool_approval",
                         toolCallId: req.toolCallId,
                         toolName: req.toolName,
+                        ...parkedToolIdentity(toolRosterDeltas.current, req.toolName), ...parkedToolFace(toolRosterDeltas.current, req.toolName),
                         args: parkedArgs,
                         ...(() => {
                             const p = approvalPreviewOf(req.toolName, parkedArgs);

package/dist/core/runner/prepare-project-context.d.ts

@@ -1,27 +1,9 @@
-/**
- * design/390 M9 — prepareTask's PROJECT-CONTEXT phase: the deployment's project memory snapshot (the
- * `loadProjectMemory` seam: phase derivation, instruction sources, the framed + fenced project layer
- * appended to the memory block), the skills roster (declaration rank, normalization, the 1MB load gate,
- * the manifest-scope door, the `skill` tool mount), the two built-in memory pairs' mount-or-yield
- * (shared-memory pair, engine-memory pair), and the skills-listing projection the run loop announces.
- * The body is the driver's stretch moved verbatim; the interface below is the dependency list it had
- * implicitly (design/238 R-1: a new read is an Input field, i.e. a review event).
- *
- * ASYNC BY CONTENT: the stretch awaits the session branch read, the seam itself and the read-state
- * seeding (all inside the `loadProjectMemory` arm). It already sits past prepareTask's first await, so
- * the one extra microtask the driver's `await` adds on the seam-less path opens no window any caller
- * could reach (design/390 §1.5 S1 synchronicity rule: only pre-first-await stretches must stay sync).
- *
- * Throws pass through unchanged: `config.reserved_tool_name` (a caller tool named like the skill tool
- * while skills are present) is the only refusal here; the seam's own throw and the seeding's are
- * caught and forwarded to `deps.onError` (best-effort, never block the task).
- */
-import type { AgentTool } from "../../internal/harness.js";
 import { type StoredSession } from "../session.js";
 import type { RunnerDeps, TaskSpec, ToolSpec } from "../types.js";
 import type { ActiveSkillScope } from "./active-skill-scope.js";
 import type { AnnounceOnceSink, Prepared, PrepareResume, RunInternals, ToolFaceSnapshot } from "./contracts.js";
 import { normalizeSkills } from "./synthetic-tools.js";
+import { RosterBuilder } from "../tool-roster.js";
 export interface PrepareProjectContextInput {
     /** borrowed-readonly — the deployment seams this phase reads: `loadProjectMemory` (the snapshot),
      *  `onError` (the operator lane for a throwing seam / seeding / oversize skill), `sharedMemoryStores`
@@ -64,10 +46,10 @@ export interface PrepareProjectContextInput {
      *  and the `skill` tool alias this exact object). Mutated here: `push` of every inherited parent
      *  frame; after this phase only the `skill` tool's execute pushes/pops. */
     skillScope: ActiveSkillScope;
-    /** borrowed-mutable — the shared mount array (later refs alias it; in-place contract). Mutated
-     *  here: `push` of the `skill` tool, the shared-memory pair and the engine-memory pair. Occupancy
-     *  is judged on this ALREADY-MOUNTED roster (names + aliases). */
-    tools: AgentTool[];
+    /** borrowed-mutable — the run's roster builder (later refs alias its read face; in-place contract). Mutated
+     *  here: `mount` of the `skill` tool, the shared-memory pair and the engine-memory pair. Occupancy
+     *  is judged on the ALREADY-MOUNTED read face (names + aliases). */
+    roster: RosterBuilder;
     /** borrowed-readonly — the frozen task-start tool face; only `exclude` is read (pair yield ①). */
     toolFaceSnapshot: Pick<ToolFaceSnapshot, "exclude">;
     /** borrowed-readonly — the once-per-session announcement ledger; only its deduplicated `onError`

package/dist/core/runner/prepare-project-context.js

@@ -6,8 +6,10 @@ import { createSharedMemoryTools } from "../shared-memory/tools.js";
 import { SHARED_MEMORY_TOOL_NAMES } from "../shared-memory/types.js";
 import { defineTool } from "../tools.js";
 import { SKILL_CONTENT_MAX_CHARS, SKILL_TOOL_NAME, createSkillTool, normalizeSkills } from "./synthetic-tools.js";
+import { RosterBuilder } from "../tool-roster.js";
 export async function prepareProjectContext(input) {
-    const { deps, spec, internals, session, sessionId, hostTaskId, taskRootFinal, handsEnabled, delegation, seedContextFiles, memoryBlockFromEngine, skillScope, tools, toolFaceSnapshot, onceLedger, memoryTools, memoryEngineSession, memorySearchToolsPlanned, memoryPairExcludedName, memoryPairOccupiedName, resume } = input;
+    const { deps, spec, internals, session, sessionId, hostTaskId, taskRootFinal, handsEnabled, delegation, seedContextFiles, memoryBlockFromEngine, skillScope, roster, toolFaceSnapshot, onceLedger, memoryTools, memoryEngineSession, memorySearchToolsPlanned, memoryPairExcludedName, memoryPairOccupiedName, resume } = input;
+    const tools = roster.tools;
     let memoryBlock = memoryBlockFromEngine;
     let instructionSources;
     let projectInstructionContent;
@@ -88,7 +90,7 @@ export async function prepareProjectContext(input) {
             e.code = "config.reserved_tool_name";
             throw e;
         }
-        tools.push(createSkillTool(skillSpecs, skillScope));
+        roster.mount(createSkillTool(skillSpecs, skillScope), { source: "builtin", mountedBy: "optional" });
     }
     const sharedMemoryProvider = deps.sharedMemoryStores;
     let sharedMemoryPairMounted = false;
@@ -110,16 +112,16 @@ export async function prepareProjectContext(input) {
                 " — the pair mounts together or not at all."), { phase: "config", sessionId, classification: "shared-memory-not-mounted" });
         }
         else {
-            tools.push(...createSharedMemoryTools({
+            roster.mountAll(createSharedMemoryTools({
                 provider: sharedMemoryProvider,
                 context: { sessionId, taskId: hostTaskId, ...(spec.principal !== undefined ? { principal: spec.principal } : {}) },
-            }).map((s) => defineTool(s)));
+            }).map((s) => defineTool(s)), { source: "builtin", mountedBy: "memory" });
             sharedMemoryPairMounted = true;
         }
     }
     let memoryEnginePairMounted = false;
     if (memoryTools !== undefined && memoryTools.length > 0) {
-        tools.push(...memoryTools.map((s) => defineTool(s)));
+        roster.mountAll(memoryTools.map((s) => defineTool(s)), { source: "builtin", mountedBy: "memory" });
         memoryEnginePairMounted = true;
     }
     else if (memoryEngineSession !== undefined && !memorySearchToolsPlanned) {

package/dist/core/runner/prepare-prompt-assembly.d.ts

@@ -48,7 +48,7 @@ export interface PreparePromptAssemblyInput {
     fableMitigations: boolean;
     /** borrowed-readonly — the run's ONE tool roster, read only: the assembly receives DETACHED copies, the audit and the
      *  manifest read it in place. Never mutated here. */
-    tools: AgentTool[];
+    tools: readonly AgentTool[];
     /** borrowed-readonly — the task model; only `promptGuidance` (the model-guidance section). */
     model: Pick<Model, "promptGuidance">;
     /** borrowed-readonly — the acquired session id (every operator line's attribution). */

package/dist/core/runner/prepare-protocol-tools.d.ts

@@ -4,6 +4,7 @@ import { type MaterializedA2a } from "../a2a.js";
 import type { LockedPreflight } from "../locked-config.js";
 import type { RunnerDeps, TaskSpec, ToolEffect } from "../types.js";
 import type { AnnounceOnceSink, IrreversibilityTier, Prepared, RollbackStack, ToolFaceSnapshot } from "./contracts.js";
+import { RosterBuilder, type ToolRosterDeltaSeat } from "../tool-roster.js";
 export interface PrepareProtocolToolsInput {
     /** borrowed-readonly — the frozen preflight; only `mcp` (the declared server entries) is read: the
      *  materialize input, the RefreshMcpTools mount predicate, and whether a real client was acquired. */
@@ -34,7 +35,10 @@ export interface PrepareProtocolToolsInput {
      *  Writers here: three pushes (the MCP tools through the wrapper, RefreshMcpTools, the A2A tools through the
      *  wrapper) and, at RUN time, the refresh closure's splice within a server's name-prefix domain. Later
      *  phases push their own mounts; the roster's full writer table is the delegation-surface phase's. */
-    tools: AgentTool[];
+    roster: RosterBuilder;
+    /** borrowed-mutable — the run-time delta seat (design/388 §2.5): the refresh closure re-mints the roster through it after
+     *  every re-splice so the stream learns of the change. Armed by the driver after the roster is minted. */
+    rosterSeat: ToolRosterDeltaSeat;
     /** borrowed-readonly — the large-result wrapper for protocol tools (per-tool `_meta` bar, 50K default). */
     remoteToolOffload: (tool: AgentTool) => AgentTool;
     /** borrowed-readonly — the frozen tool face; `exclude` is read at REFRESH time so a deployment-excluded

package/dist/core/runner/prepare-protocol-tools.js

@@ -2,8 +2,13 @@ import { Type } from "typebox";
 import { materializeMcpTools } from "../mcp.js";
 import { materializeA2aTools } from "../a2a.js";
 import { deliverEngineNotice } from "../types.js";
+import { RosterBuilder } from "../tool-roster.js";
+import { REFRESH_MCP_TOOLS_TOOL_NAME, toolFace } from "../tool-catalog-entries.js";
+import { MCP_NAMESPACE, A2A_NAMESPACE } from "../protocol-table.js";
+import { mintNamespacePrefix } from "../protocol-naming.js";
+import { applyMcpToolFaces } from "./tool-face-overlay.js";
 export async function prepareProtocolTools(input) {
-    const { lockedPreflight, spec, deps, reminderMark, reminderDisclosureCounts, runId, sessionId, onceLedger, tools, remoteToolOffload, toolFaceSnapshot, toolEffects, axisExplicitNegatives, irreversibilityTier, irreversibleTools, egressTools, abortController, rollback } = input;
+    const { lockedPreflight, spec, deps, reminderMark, reminderDisclosureCounts, runId, sessionId, onceLedger, roster, rosterSeat, remoteToolOffload, toolFaceSnapshot, toolEffects, axisExplicitNegatives, irreversibilityTier, irreversibleTools, egressTools, abortController, rollback } = input;
     const mcp = lockedPreflight.mcp?.length
         ? await materializeMcpTools(lockedPreflight.mcp, spec.principal, deps.onElicit, deps.mcpImageResizer, { reminderMark, counts: reminderDisclosureCounts }, mcpRevocationWiring(deps, runId))
         : { tools: [], toolAxes: [], warnings: [], serverInstructions: [], instructionsDelta: { pendingAdds: [], pendingRemovals: [] }, droppedTools: [], statuses: [], refresh: async () => [], dispose: async () => { } };
@@ -24,14 +29,35 @@ export async function prepareProtocolTools(input) {
             throw e;
         }
     }
-    tools.push(...mcp.tools.map((t) => remoteToolOffload(t)));
+    const faceAnnounced = new Set();
+    const withFaces = (tools, serverName) => {
+        const server = (lockedPreflight.mcp ?? []).find((s) => s.name === serverName);
+        return server === undefined ? [...tools] : applyMcpToolFaces({ tools, server, onNotice: deps.onNotice, announced: faceAnnounced, sessionId: sessionId ?? "", runId });
+    };
+    {
+        const servers = (lockedPreflight.mcp ?? []).map((s) => ({ name: s.name, prefix: mintNamespacePrefix(MCP_NAMESPACE, s.name) }));
+        const faced = new Map();
+        for (const server of servers) {
+            const own = mcp.tools.filter((x) => x.name.startsWith(server.prefix));
+            for (const t of withFaces(own, server.name))
+                faced.set(t.name, t);
+        }
+        for (const t of mcp.tools) {
+            const server = servers.find((s) => t.name.startsWith(s.prefix));
+            const mounted = server === undefined ? t : faced.get(t.name);
+            if (mounted === undefined)
+                continue;
+            roster.mount(remoteToolOffload(mounted), { source: "mcp", mountedBy: "optional", origin: { peer: server?.name ?? MCP_NAMESPACE.parse(t.name)?.peer ?? t.name } });
+        }
+    }
     const rebuildHarnessToolsRef = {};
     const contentOriginWrapRef = {};
     const toolCallGateArmedRef = { armed: false };
     if (lockedPreflight.mcp?.length) {
-        tools.push({
-            name: "RefreshMcpTools",
-            label: "RefreshMcpTools",
+        roster.mount({
+            ...toolFace("refresh-mcp-tools"),
+            name: REFRESH_MCP_TOOLS_TOOL_NAME,
+            label: REFRESH_MCP_TOOLS_TOOL_NAME,
             description: "Refresh the tool list of connected MCP servers. Never dials or re-dials connections — it only re-reads the tool list over the existing connection. The refreshed tools are available immediately; you can call them on your next step. Use when a server's expected tool is missing, or the tool list looks stale after a connection recovered. Omit `server` to refresh every connected server.",
             parameters: Type.Object({
                 server: Type.Optional(Type.String({ description: "Name of a single MCP server to refresh; omit to refresh all connected servers." })),
@@ -76,19 +102,8 @@ export async function prepareProtocolTools(input) {
                         anyActiveFailure = true;
                         continue;
                     }
-                    let domainAnchor = -1;
-                    for (let i = tools.length - 1; i >= 0; i--) {
-                        const t = tools[i];
-                        if (t.name.startsWith(r.prefix)) {
-                            domainAnchor = i;
-                            tools.splice(i, 1);
-                        }
-                    }
-                    const refreshedMounts = pushable.map((t) => remoteToolOffload(t));
-                    if (domainAnchor >= 0)
-                        tools.splice(domainAnchor, 0, ...refreshedMounts);
-                    else
-                        tools.push(...refreshedMounts);
+                    const refreshedMounts = withFaces(pushable, r.server).map((t) => remoteToolOffload(t));
+                    roster.replaceDomain(r.prefix, refreshedMounts, { source: "mcp", mountedBy: "optional", origin: { peer: r.server } });
                     changed = true;
                     const detail = [];
                     const shownAdded = r.added.filter((n) => !excludedSet.has(n));
@@ -104,6 +119,8 @@ export async function prepareProtocolTools(input) {
                 }
                 if (changed)
                     await rebuildHarnessToolsRef.current?.();
+                if (changed)
+                    rosterSeat.republish();
                 if (changed && !toolCallGateArmedRef.armed && (irreversibleTools.size > 0 || egressTools.size > 0)) {
                     lines.push("WARNING: refreshed tools declare irreversible/egress safety hints, but this task started with no approval gate registered (no policy/hooks and no gated tools at start) — these hints cannot arm a gate mid-task (RB-46); the refreshed tools run ungated on this deployment shape.");
                 }
@@ -115,8 +132,7 @@ export async function prepareProtocolTools(input) {
                     ...(anyActiveFailure && !changed ? { isError: true } : {}),
                 };
             },
-        });
-        toolEffects.set("RefreshMcpTools", "read");
+        }, { source: "builtin", mountedBy: "optional" });
     }
     const foldProtocolAxes = (axes, protocolLabel) => {
         for (const axis of axes) {
@@ -160,7 +176,8 @@ export async function prepareProtocolTools(input) {
             throw e;
         }
     }
-    tools.push(...a2a.tools.map((t) => remoteToolOffload(t)));
+    for (const t of a2a.tools)
+        roster.mount(remoteToolOffload(t), { source: "a2a", mountedBy: "optional", origin: { peer: A2A_NAMESPACE.parse(t.name)?.peer ?? t.name } });
     foldProtocolAxes(a2a.toolAxes, "A2A");
     return { mcp, a2a, rebuildHarnessToolsRef, contentOriginWrapRef, toolCallGateArmedRef };
 }

package/dist/core/runner/prepare-question-face.d.ts

@@ -22,6 +22,7 @@ import { type CheckpointStore } from "../checkpoint-store.js";
 import type { RunnerDeps, RuntimeCaps, TaskSpec } from "../types.js";
 import type { PrepareResume } from "./contracts.js";
 import { type ContentAskBinding } from "./content-ask-bindings.js";
+import { RosterBuilder } from "../tool-roster.js";
 export { CONTENT_ASK_BINDING_CAP, type ContentAskBinding } from "./content-ask-bindings.js";
 export interface PrepareQuestionFaceInput {
     /** borrowed-readonly — the run's frozen question seat (spec > deps), resolved once at the top of prepare;
@@ -45,10 +46,10 @@ export interface PrepareQuestionFaceInput {
     resume: Pick<PrepareResume, "redeemedContentAskCallId" | "redeemedContentAskQuestionsHash"> | undefined;
     /** borrowed-readonly — the acquired session id (the tool's source task id; operator-line context). */
     sessionId: string;
-    /** borrowed-mutable — the run's shared roster (identity is the contract). Writer here: ONE push (the question
+    /** borrowed-mutable — the run's roster builder (identity is the contract). Writer here: ONE mount (the question
      *  tool) when the mount predicate holds; `contentAskRoutable` reads `includes` per call against the LIVE
-     *  array (the roster is edited in place after the mount). */
-    tools: AgentTool[];
+     *  read face (the roster is edited in place after the mount). */
+    roster: RosterBuilder;
     /** borrowed-readonly — LIVE GETTER over the inherited-unavailable marker set (declared by the driver's
      *  gate-fold section after this phase; `has` only, per call at run time). See the module header. */
     inheritedUnavailableAsks: () => ReadonlySet<string>;

package/dist/core/runner/prepare-question-face.js

@@ -2,9 +2,11 @@ import { createAskUserQuestionTool, isLiveQuestionFace } from "../ask-question.j
 import { boundInputHashOf } from "../canonical-json.js";
 import { resolveCheckpointStore } from "../checkpoint-store.js";
 import { CONTENT_ASK_BINDING_CAP } from "./content-ask-bindings.js";
+import { RosterBuilder } from "../tool-roster.js";
 export { CONTENT_ASK_BINDING_CAP } from "./content-ask-bindings.js";
 export function prepareQuestionFace(input) {
-    const { frozenOnQuestion, spec, deps, runtimeCaps, resolvedInteractionPosture, resume, sessionId, tools, inheritedUnavailableAsks } = input;
+    const { frozenOnQuestion, spec, deps, runtimeCaps, resolvedInteractionPosture, resume, sessionId, roster, inheritedUnavailableAsks } = input;
+    const tools = roster.tools;
     const onQuestion = frozenOnQuestion;
     const liveQuestionFace = isLiveQuestionFace(onQuestion) ? onQuestion : undefined;
     const contentAskBindings = new Map();
@@ -60,7 +62,7 @@ export function prepareQuestionFace(input) {
     const questionToolMounted = spec.interactiveTools === true || (spec.interactiveTools !== false && (onQuestion !== undefined || durableQuestionFace));
     let mountedQuestionTool;
     if (questionToolMounted)
-        tools.push((mountedQuestionTool =
+        roster.mount((mountedQuestionTool =
             createAskUserQuestionTool(mountedQuestionFace, { principal: spec.principal, sourceTaskId: sessionId }, {
                 ...(resume?.redeemedContentAskCallId !== undefined
                     ? {
@@ -79,6 +81,6 @@ export function prepareQuestionFace(input) {
                                 : "the wired question channel failed") +
                         `) — the model was instructed to self-answer and the run CONTINUES (warning, not a failure).`), { phase: "degraded", sessionId, classification: "no-human-autoanswered" });
                 },
-            })));
+            })), { source: "builtin", mountedBy: "optional" });
     return { checkpointStore, liveQuestionFace, contentAskBindings, contentAskRoutable, lateStrandedAnswers, discloseStrandedAnswers, settleContentAskBindings, durableQuestionFace, mountedQuestionFace, questionToolMounted, mountedQuestionTool };
 }

package/dist/core/runner/prepare-safety-scan.js

@@ -1,5 +1,8 @@
 import { NAMESPACED_NAME_SHAPES } from "../protocol-table.js";
-import { HAND_TOOL_EFFECTS } from "../../tools/fs/index.js";
+import { handBandEffects } from "../tool-registry.js";
+import { TOOL_CONTRACT_MAX_CHARS, TOOL_WIRE_NAME_MAX_CHARS } from "../tool-face.js";
+import { schemaKeyBoundProblem } from "../tool-roster.js";
+import { toolFaceProblem } from "./tool-face-overlay.js";
 import { OFFLOAD_TOOL_NAME } from "../tool-result-store.js";
 import { PRESENT_PLAN_TOOL_NAME, ENTER_PLAN_MODE_TOOL_NAME } from "../present-plan-tool.js";
 export function prepareSafetyScan(input) {
@@ -13,6 +16,43 @@ export function prepareSafetyScan(input) {
     const axisExplicitNegatives = new Map();
     const reversibilityProbes = new Map();
     for (const t of spec.tools ?? []) {
+        if (t.name.length > TOOL_WIRE_NAME_MAX_CHARS) {
+            const e = new Error(`Tool name "${t.name.slice(0, 40)}…" is invalid: ${t.name.length} characters, the roster's bound is ${TOOL_WIRE_NAME_MAX_CHARS}.`);
+            e.code = "config.tool_name_too_long";
+            throw e;
+        }
+        for (const alias of t.aliases ?? []) {
+            if (alias.length > TOOL_WIRE_NAME_MAX_CHARS) {
+                const e = new Error(`Tool alias "${alias.slice(0, 40)}…" (of "${t.name}") is invalid: ${alias.length} characters, the roster's bound is ${TOOL_WIRE_NAME_MAX_CHARS}.`);
+                e.code = "config.tool_name_too_long";
+                throw e;
+            }
+        }
+        if (t.contract !== undefined && (t.contract.contractId.length > TOOL_CONTRACT_MAX_CHARS || t.contract.implementationRevision.length > TOOL_CONTRACT_MAX_CHARS)) {
+            const e = new Error(`Tool "${t.name}" declares a contract member over ${TOOL_CONTRACT_MAX_CHARS} characters (contractId ${t.contract.contractId.length}, implementationRevision ${t.contract.implementationRevision.length}) — the roster's bound.`);
+            e.code = "config.tool_contract_too_long";
+            throw e;
+        }
+        {
+            const keyProblem = schemaKeyBoundProblem(t.parameters);
+            if (keyProblem !== undefined) {
+                const e = new Error(`Tool "${t.name}" cannot ride a roster row: ${keyProblem}.`);
+                e.code = "config.tool_schema_bound";
+                throw e;
+            }
+            const declared = {
+                ...(t.family !== undefined ? { family: t.family } : {}),
+                ...(t.pathTarget !== undefined ? { pathTarget: t.pathTarget } : {}),
+                ...(t.ruleFace !== undefined ? { ruleFace: t.ruleFace } : {}),
+                ...(t.renderHints !== undefined ? { renderHints: t.renderHints } : {}),
+            };
+            const faceProblem = toolFaceProblem(declared, t.parameters);
+            if (faceProblem !== undefined) {
+                const e = new Error(`Tool "${t.name}" declares a face its schema cannot carry: ${faceProblem}.`);
+                e.code = "config.tool_face_invalid";
+                throw e;
+            }
+        }
         if (t.name.includes("__")) {
             const e = new Error(`Tool name "${t.name}" is invalid: "__" is reserved for the engine's protocol tool namespaces (${NAMESPACED_NAME_SHAPES}) and must not appear in a caller tool name.`);
             e.code = "config.tool_name_invalid";
@@ -65,7 +105,7 @@ export function prepareSafetyScan(input) {
     }
     toolEffects.set(OFFLOAD_TOOL_NAME, "read");
     if (deps.executionEnvFactory || deps.executionEnv) {
-        for (const [name, effect] of Object.entries(HAND_TOOL_EFFECTS))
+        for (const [name, effect] of handBandEffects())
             toolEffects.set(name, effect);
         if (spec.handsReadOnly === true)
             toolEffects.set("Bash", "read");