@sema-agent/core 7.7.0 → 7.9.0

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

@@ -33,6 +33,7 @@ import type { CwdRef } from "../../tools/fs/fs-shared.js";
 import type { AskLane, IrreversibilityTier, ParkAsk, Prepared, ReversibilityProbes } from "./contracts.js";
 import type { StopForDenialLimit } from "./denial-limit-arms.js";
 import type { PermissionRuleLanes } from "./permission-rule-lanes.js";
+import { type ToolRosterDeltaSeat } from "../tool-roster.js";
 export interface PrepareGateStationsInput {
     /** borrowed-readonly — the in-stream ask lane, or undefined when the gate machinery is inactive (then no `tool_call`
      *  station is built). Read: `adjudicate`, `resolveAskBound`, `notifyPermissionDenied`, `notifyHookError`. */
@@ -41,7 +42,9 @@ export interface PrepareGateStationsInput {
     parkAsk: ParkAsk | undefined;
     /** borrowed-readonly — the FINAL mount roster: iterated once for the effect sync and the write-protection arming. Never
      *  mutated here. */
-    tools: AgentTool[];
+    tools: readonly AgentTool[];
+    /** borrowed-readonly — the leg's delta seat (design/388): its current roster is the face source for every gated call. */
+    toolRosterDeltas: ToolRosterDeltaSeat;
     /** borrowed-mutable — the effect collection. Writer here: the final-roster sync fills MISSING entries from each
      *  first-party tool's declared effect (never overrides a scanned one); the plan-mode deny reads it per call. */
     toolEffects: Map<string, ToolEffect>;

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

@@ -7,6 +7,7 @@ import { directDeny } from "./gate-exit.js";
 import { emitTrace } from "../trace.js";
 import { createWriteProtectionCheck } from "../write-protect.js";
 import { PATH_CONFINABLE_WRITE_TOOLS } from "./session-rule-policy.js";
+import { toolCallFaceOf } from "../tool-roster.js";
 function screenGateResult(result) {
     if (result.suspend !== undefined)
         return { defects: [] };
@@ -39,7 +40,7 @@ function maybeHumanRejectionHalt(input) {
     };
 }
 export function prepareGateStations(input) {
-    const { askLane, parkAsk, tools, toolEffects, deps, toolCallGateArmedRef, effectivePolicy, hooks, egressTools, irreversibleTools, spec, complianceDenies, harness, blockedToolCalls, inheritedAskGrants, inheritedUnavailableAsks, foldAskClasses, ancestorSandboxAdmissions, preToolContexts, gateOutcomes, batchHaltRef, blockedTracked, hookIdentity, reminderMark, planModeRef, hostTaskId, sessionId, ownGatePreToolUse, hookTimeoutMs, handsCwdRef, hookEnvFace, irreversibilityTier, reversibilityProbes, abortController, shellGatedBash, shellGatedMonitor, autoModeDecider, autoModeDenialTracking, stopForDenialLimit, permissionRuleLane, permissionRuleOrgLane, questionToolMounted, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, delegation, notifyOwnHookCrash } = input;
+    const { askLane, parkAsk, tools, toolRosterDeltas, toolEffects, deps, toolCallGateArmedRef, effectivePolicy, hooks, egressTools, irreversibleTools, spec, complianceDenies, harness, blockedToolCalls, inheritedAskGrants, inheritedUnavailableAsks, foldAskClasses, ancestorSandboxAdmissions, preToolContexts, gateOutcomes, batchHaltRef, blockedTracked, hookIdentity, reminderMark, planModeRef, hostTaskId, sessionId, ownGatePreToolUse, hookTimeoutMs, handsCwdRef, hookEnvFace, irreversibilityTier, reversibilityProbes, abortController, shellGatedBash, shellGatedMonitor, autoModeDecider, autoModeDenialTracking, stopForDenialLimit, permissionRuleLane, permissionRuleOrgLane, questionToolMounted, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, delegation, notifyOwnHookCrash } = input;
     if (askLane !== undefined && parkAsk !== undefined) {
         const { adjudicate, resolveAskBound, notifyPermissionDenied, notifyHookError } = askLane;
         const { resolveContentAsk, suspendAsk } = parkAsk;
@@ -103,6 +104,7 @@ export function prepareGateStations(input) {
                         hookTimeoutMs,
                         ...(handsCwdRef !== undefined ? { trackedCwd: () => handsCwdRef.current } : {}),
                         ...(hookEnvFace !== undefined ? { hookEnv: hookEnvFace } : {}),
+                        toolFaceOf: (name) => toolCallFaceOf(toolRosterDeltas.current, name),
                         adjudicate,
                         resolveAsk: resolveAskBound,
                         suspendAsk,
@@ -121,7 +123,7 @@ export function prepareGateStations(input) {
                         ...(permissionRuleLane
                             ? {
                                 persistedRules: {
-                                    admits: permissionRuleLane.admits,
+                                    adjudicate: permissionRuleLane.adjudicate,
                                     onResolved: (info) => emitTrace(deps.tracer, () => ({
                                         kind: "permission.persisted_rule_allowed",
                                         version: 2,

package/dist/core/runner/prepare-hands-readface.d.ts

@@ -5,6 +5,7 @@ import type { Model } from "../../internal/llm.js";
 import type { AgentTool, ExecutionEnv, WorkspaceState } from "../../internal/harness.js";
 import type { StoredSession } from "../session.js";
 import type { IrreversibilityTier, PrepareResume, ReversibilityProbes, RunInternals, ToolFaceSnapshot } from "./contracts.js";
+import { RosterBuilder } from "../tool-roster.js";
 /** Test seam (mirrors `__resetMalformedNoticeSeatAnnouncement`): never called by production code.
  *  Deliberately asymmetric — it resets only the console latch: the WeakSet arm needs no seam
  *  because a test resets it by minting a fresh sink function (identity IS the ledger key), while
@@ -174,8 +175,8 @@ export interface PrepareHandsReadFaceInput {
      *  contract, never map/copy). This phase pushes the hands band IN PLACE (after caller tools /
      *  built-ins / MCP / A2A, before the background-task mounts — T22 order). Mutation owners after
      *  this phase: P11 background/Monitor/worktree pushes, the driver's excludeTools splice, the
-     *  refresh seam's runtime splice/push. */
-    tools: AgentTool[];
+     *  refresh seam's runtime splice/push. Since design/388 the array is builder-private: this phase `mountAll`s the band. */
+    roster: RosterBuilder;
     /** borrowed-readonly HERE (census divergence #5 vs the design row): this phase only reads
      *  `.has("Bash")`/`.has("Monitor")` for the provenance bits — its mutation owners are B-2/P8/P9
      *  (+refresh seam)/P11/P22, per the B-2 Result's mutation-owner table. */

package/dist/core/runner/prepare-hands-readface.js

@@ -8,6 +8,7 @@ import { normalizeFileText } from "../../tools/fs/encoding.js";
 import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
 import { deliverEngineNotice } from "../types.js";
 import { rebaseWorkspacePath } from "./workspace-path.js";
+import { RosterBuilder } from "../tool-roster.js";
 const readFaceClampAnnouncedSinks = new WeakSet();
 let readFaceClampConsoleAnnounced = false;
 export function __resetReadFaceClampAnnouncement() {
@@ -123,7 +124,7 @@ export function resolveHandsLessReadFace(input) {
 }
 export async function prepareHandsMount(input) {
     const envHandToolNames = new Set();
-    const { handsEnabled, executionEnv, taskRootFinal, rebaseRestoredPath, resume, session, sessionId, hostTaskId, taskScope, fullShellReachable, effectiveShellGate, toolFaceSnapshot, model, spec, deps, internals, memoryWriteGateRef, firstPartyOffload, tools, egressTools, irreversibilityTier, irreversibleTools, reversibilityProbes } = input;
+    const { handsEnabled, executionEnv, taskRootFinal, rebaseRestoredPath, resume, session, sessionId, hostTaskId, taskScope, fullShellReachable, effectiveShellGate, toolFaceSnapshot, model, spec, deps, internals, memoryWriteGateRef, firstPartyOffload, roster, egressTools, irreversibilityTier, irreversibleTools, reversibilityProbes } = input;
     assertStringArraySeat(spec.additionalDirectories, "TaskSpec.additionalDirectories", "strings");
     assertStringArraySeat(spec.additionalReadDirectories, "TaskSpec.additionalReadDirectories", "strings");
     assertStringArraySeat(deps.readDenyPatterns, "RunnerDeps.readDenyPatterns", "compiler-owned");
@@ -351,7 +352,7 @@ export async function prepareHandsMount(input) {
                 deps.onError?.(new Error(`spec.tools ${shadowed.length > 1 ? "entries" : "entry"} ${names} collide${shadowed.length > 1 ? "" : "s"} with the built-in hands tool band — the built-in wins (registered later; the harness tool Map is last-write-wins) and the caller tool never dispatches this task. Rename the caller tool, or don't inject executionEnv if you intend to replace the band.`), { phase: "config", sessionId });
             }
         }
-        tools.push(...band.map((t) => (envHandToolNames.add(t.name), firstPartyOffload(t))));
+        roster.mountAll(band.map((t) => (envHandToolNames.add(t.name), firstPartyOffload(t))), { source: "builtin", mountedBy: "hands" });
         const shellGate = effectiveShellGate;
         if (shellGate === "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
             deps.onError?.(new Error(`shell gate doctrine is "off" while a real writable shell (Bash) is mounted — no shell safety-axis ` +

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-run-refs.d.ts

@@ -86,4 +86,20 @@ export interface PrepareRunRefsResult {
     worktreeIsolation: SubagentWorktreeIsolation | undefined;
 }
 /** The M3a phase body — prepareTask's run-refs stretch, verbatim (see the module header). */
+/**
+ * A run that opted into `forwardSubagentEvents` may have BACKGROUND children whose frames are forwarded to the
+ * deployment's sink from the child's own run. Those forwards are scheduled on later microtasks than the parent's
+ * turn, so "the parent stream ended" and "the child's already-emitted frames reached the sink" are two different
+ * moments — the gap is one microtask ladder deep and moves whenever the gate's station structure changes (design/393
+ * / #594: the three-layer gate added three async frames to a child's gated call, and a consumer that read the parent
+ * to `done` then inspected the sink lost the child's `tool_end`). The rule is not a tick count: **before the parent
+ * says `done`, every frame a child had already handed to the forward channel is delivered.** One macrotask turn is
+ * the smallest boundary that strictly orders after all pending microtasks; it is taken only on the opted-in run,
+ * only once, right before `done`.
+ */
+export declare function forwardsSubagentEvents(spec: Pick<TaskSpec, "forwardSubagentEvents">): boolean;
+/** The drain itself — one macrotask turn. Callers gate it with {@link forwardsSubagentEvents} SYNCHRONOUSLY so a
+ *  non-forwarding run's terminal push is not one microtask later than it was (an `await` of an early-returning
+ *  async function still yields once; the black-box round measured that tick). */
+export declare function drainForwardedFramesBeforeDone(): Promise<void>;
 export declare function prepareRunRefs(input: PrepareRunRefsInput): PrepareRunRefsResult;

package/dist/core/runner/prepare-run-refs.js

@@ -2,6 +2,12 @@ import { createSubagentWorktreeHelper } from "../../agents/subagent.js";
 import { SubagentRetainLedger } from "../../agents/retain-ledger.js";
 import { ActiveSkillScope } from "./active-skill-scope.js";
 import { createEditedFilesLedger } from "./edited-files-ledger.js";
+export function forwardsSubagentEvents(spec) {
+    return spec.forwardSubagentEvents === true;
+}
+export function drainForwardedFramesBeforeDone() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
 export function prepareRunRefs(input) {
     const { spec, internals, executionEnv, taskRootFinal } = input;
     const { note: noteFileEdited, snapshot: editedFilesSnapshot } = createEditedFilesLedger();