@sema-agent/core 7.7.0 → 7.8.0

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();

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");

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

@@ -71,6 +71,10 @@ import { selfOrchestrationFailClosedReason } from "../../orchestration/workflow-
 import { remainingBudgetMicroUsd } from "../checkpoint-store.js";
 import { durableParkGapFor } from "../park-selfcheck.js";
 import { deliverEngineNotice } from "../types.js";
+import { ToolRosterDeltaSeat } from "../tool-roster.js";
+import { faceOf } from "../tool-roster.js";
+import { catalogEntriesNamed, pathTargetOf } from "../tool-registry.js";
+import { createStructuredProjector } from "./tool-output-projection.js";
 function warnCompactionWindowHazard(tracer, spec, model, compModel, hostTaskId) {
     if (compModel === undefined)
         return;
@@ -363,7 +367,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         let readDenyAdditionsNormalized = [];
         let handsLessResolvedFace;
         const { liveInheritedGate, seedInheritedGate, inheritedAncestorRules, inheritedShellGate, inheritedParentConstraints, autoModeIntent, inheritedAdmittedOrgScopes, priorOwnOrgVerdict, orgGovernedProvenance, effectiveShellGate, ownSessionRulesRef, memoryAdmittedOrgScopesRef, ownOrgVerdictRef, orgAdmissionCheckpointState, faceCheckpointSection, faceCheckpointState, f012CheckpointState, frozenOnAsk, hookEnvSource, notifyOwnHookCrash, frozenOnQuestion, provenanceForChildrenRef, delegationSettlementRef, inheritedGateForChildren, carrierReadFace, fullShellReachable, gateStopRef, stopForDenialLimit, enrichSpecToolCtx } = prepareInheritedGate({ spec, deps, internals, resume, sessions, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, ownedEnv, lockedPreflight, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, autoModeSeat, handsEnabled, reportUsage, harnessRef, skillScope, forwardEvent, subagentRetain, worktreeIsolation, requestReview, requestStopAfterTurn, enterPlanMode, reminderMark, reminderDisclosureCounts, fileHistoryEnabled, historyScope, historyRoot, historyFs, abortRun: () => { abortController.abort(); void harness.abort(); }, runtimeCaps: () => runtimeCaps, hooks: () => hooks, preToolUseObservational: () => preToolUseObservational, hookTimeoutMs: () => hookTimeoutMs, hookEnvFace: () => hookEnvFace, autoModeDecider: () => autoModeDecider, autoModeDenialTracking: () => autoModeDenialTracking, autoModeArming: () => autoModeArming, agentForkDenial: () => agentForkDenial, observersActive: () => observersActive, resolvedReadFace: () => resolvedReadFace, readDenyAdditionsNormalized: () => readDenyAdditionsNormalized, handsLessResolvedFace: () => handsLessResolvedFace, centerAdoption: () => centerAdoptionRef.current, memoryEngineSession: () => memoryEngineSession });
-        const { tools, blockedRef, runtimeCaps, runtimeCapsFaulted, complianceDenies, complianceDegraded, agentForkDenial, observersActive, autoModeArmReason, autoModeDecider, autoModeDenialTracking, autoModeArming, selfOrchestrationActive, workflowToolsActive, workflowSizeGuideline } = await prepareCapsAndWorkflow({ spec, deps, internals, session, sessionId, runId, hostTaskId, taskScope, taskRootFinal, model, thinking, lockedPreflight, toolEffects, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, harnessRef, frozenOnAsk, carrierReadFace, forwardEvent, inheritedGateForChildren, enrichSpecToolCtx, maybeOffload, requestReview, enterPlanMode, autoModeIntent, peerLaneActive, peerSendMessageBuiltIn, runnerSelf, memoryEngineSession: () => memoryEngineSession, centerAdoption: () => centerAdoptionRef.current, readDenyAdditionsNormalized: () => readDenyAdditionsNormalized });
+        const { roster, blockedRef, runtimeCaps, runtimeCapsFaulted, complianceDenies, complianceDegraded, agentForkDenial, observersActive, autoModeArmReason, autoModeDecider, autoModeDenialTracking, autoModeArming, selfOrchestrationActive, workflowToolsActive, workflowSizeGuideline } = await prepareCapsAndWorkflow({ spec, deps, internals, session, sessionId, runId, hostTaskId, taskScope, taskRootFinal, model, thinking, lockedPreflight, toolEffects, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, harnessRef, frozenOnAsk, carrierReadFace, forwardEvent, inheritedGateForChildren, enrichSpecToolCtx, maybeOffload, requestReview, enterPlanMode, autoModeIntent, peerLaneActive, peerSendMessageBuiltIn, runnerSelf, memoryEngineSession: () => memoryEngineSession, centerAdoption: () => centerAdoptionRef.current, readDenyAdditionsNormalized: () => readDenyAdditionsNormalized });
+        const tools = roster.tools;
         const pausedRef = {};
         const remoteEnvFailures = [];
         const suspendLoopRef = { hit: false };
@@ -419,12 +424,13 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 catch {
                 }
             }
-            tools.push(createOutputTool(outputRef, spec.outputSchema, compiled.strict ? compiled.modelSchema : undefined));
+            roster.mount(createOutputTool(outputRef, spec.outputSchema, compiled.strict ? compiled.modelSchema : undefined), { source: "synthetic", mountedBy: "optional" });
         }
-        const { mcp, a2a, rebuildHarnessToolsRef, contentOriginWrapRef, toolCallGateArmedRef } = await prepareProtocolTools({ lockedPreflight, spec, deps, reminderMark, reminderDisclosureCounts, runId, sessionId, onceLedger, tools, remoteToolOffload, toolFaceSnapshot, toolEffects, axisExplicitNegatives, irreversibilityTier, irreversibleTools, egressTools, abortController, rollback });
+        const rosterSeat = new ToolRosterDeltaSeat();
+        const { mcp, a2a, rebuildHarnessToolsRef, contentOriginWrapRef, toolCallGateArmedRef } = await prepareProtocolTools({ lockedPreflight, spec, deps, reminderMark, reminderDisclosureCounts, runId, sessionId, onceLedger, roster, rosterSeat, remoteToolOffload, toolFaceSnapshot, toolEffects, axisExplicitNegatives, irreversibilityTier, irreversibleTools, egressTools, abortController, rollback });
         const callIssuedAtRef = {};
         const memoryWriteGateRef = {};
-        const handsReadFaceInput = { handsEnabled, executionEnv, taskRootFinal, rebaseRestoredPath, resume, session, sessionId, hostTaskId, taskScope, fullShellReachable, effectiveShellGate, toolFaceSnapshot, model, spec, deps, internals, memoryWriteGateRef, firstPartyOffload, tools, egressTools, irreversibilityTier, irreversibleTools, reversibilityProbes, reminderMark, reminderDisclosureCounts, ...(trackFileEdit !== undefined ? { trackFileEdit } : {}), onFileEdited: noteFileEdited, ...(restoredFilePaths.length > 0 ? { restoredFilePaths } : {}) };
+        const handsReadFaceInput = { handsEnabled, executionEnv, taskRootFinal, rebaseRestoredPath, resume, session, sessionId, hostTaskId, taskScope, fullShellReachable, effectiveShellGate, toolFaceSnapshot, model, spec, deps, internals, memoryWriteGateRef, firstPartyOffload, roster, egressTools, irreversibilityTier, irreversibleTools, reversibilityProbes, reminderMark, reminderDisclosureCounts, ...(trackFileEdit !== undefined ? { trackFileEdit } : {}), onFileEdited: noteFileEdited, ...(restoredFilePaths.length > 0 ? { restoredFilePaths } : {}) };
         const handsReadFace = handsEnabled ? await prepareHandsMount(handsReadFaceInput) : resolveHandsLessReadFace(handsReadFaceInput);
         const { readFileStateForCheckpoint, seedContextFiles, handsCwdRef, workspaceStateSettle, wsSnapshot, rebaseWsPath, backgroundTaskToolsActive, additionalRootsCanonical, additionalReadRootsCanonical, attachmentRootCanonical, readDenyMatcher, envHandToolNames, sealReadStateSeat } = handsReadFace;
         resolvedReadFace = handsReadFace.resolvedReadFace;
@@ -432,16 +438,16 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         handsLessResolvedFace = handsReadFace.handsLessResolvedFace;
         shellGatedBash = handsReadFace.shellGatedBash;
         shellGatedMonitor = handsReadFace.shellGatedMonitor;
-        const { worktreeSessionRef } = prepareDelegationSurface({ spec, deps, internals, resume, sessionId, hostTaskId, taskScope, taskRootFinal, executionEnv, runnerSelf, backgroundTaskToolsActive, workflowToolsActive, peerLaneActive, peerSendMessageBuiltIn, peerLaneRefs, tools, toolEffects, axisExplicitNegatives, envHandToolNames, toolFaceSnapshot, firstPartyOffload, offloadStore, subagentRetain, enrichSpecToolCtx, handsCwdRef, wsSnapshot, rebaseWsPath, rebaseRestoredPath, workspaceStateSettle });
-        const { checkpointStore, liveQuestionFace, contentAskBindings, contentAskRoutable, lateStrandedAnswers, discloseStrandedAnswers, settleContentAskBindings, durableQuestionFace, questionToolMounted, mountedQuestionTool } = prepareQuestionFace({ frozenOnQuestion, spec, deps, runtimeCaps, resolvedInteractionPosture, resume, sessionId, tools, inheritedUnavailableAsks: () => inheritedUnavailableAsks });
+        const { worktreeSessionRef } = prepareDelegationSurface({ spec, deps, internals, resume, sessionId, hostTaskId, taskScope, taskRootFinal, executionEnv, runnerSelf, backgroundTaskToolsActive, workflowToolsActive, peerLaneActive, peerSendMessageBuiltIn, peerLaneRefs, roster, toolEffects, axisExplicitNegatives, envHandToolNames, toolFaceSnapshot, firstPartyOffload, offloadStore, subagentRetain, enrichSpecToolCtx, handsCwdRef, wsSnapshot, rebaseWsPath, rebaseRestoredPath, workspaceStateSettle });
+        const { checkpointStore, liveQuestionFace, contentAskBindings, contentAskRoutable, lateStrandedAnswers, discloseStrandedAnswers, settleContentAskBindings, durableQuestionFace, questionToolMounted, mountedQuestionTool } = prepareQuestionFace({ frozenOnQuestion, spec, deps, runtimeCaps, resolvedInteractionPosture, resume, sessionId, roster, inheritedUnavailableAsks: () => inheritedUnavailableAsks });
         if (spec.handsReadOnly !== true) {
             const sessionScope = sessionId ?? spec.principal ?? spec.taskId ?? "default";
-            tools.push(...createSchedulerTools(executionEnv, {
+            roster.mountAll(createSchedulerTools(executionEnv, {
                 scope: sessionScope,
                 ...(spec.principal !== undefined ? { principal: spec.principal } : {}),
                 ...(sessionId !== undefined ? { sessionId } : {}),
                 requestStopAfterTurn,
-            }).map((t) => (envHandToolNames.add(t.name), t)));
+            }).map((t) => (envHandToolNames.add(t.name), t)), { source: "builtin", mountedBy: "scheduler" });
         }
         if (internals?.insideFork !== true &&
             runnerSelf &&
@@ -451,7 +457,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             deps.onError?.(new Error(`Fork DENIED for principal "${spec.principal ?? ""}" by runtimeCaps.allowFork=false ` +
                 `(per-principal entitlement governance, not a misconfiguration — Agent(subagent_type:"fork") will refuse honestly)`), { phase: "config", sessionId });
         }
-        const { lspDiagnostics, nudgeLspOnEdit, lspRunIdent } = prepareLsp({ spec, deps, executionEnv, taskRootFinal, handsEnabled, sessionId, handsCwdRef, tools, envHandToolNames });
+        const { lspDiagnostics, nudgeLspOnEdit, lspRunIdent } = prepareLsp({ spec, deps, executionEnv, taskRootFinal, handsEnabled, sessionId, handsCwdRef, roster, envHandToolNames });
         const memoryPairNameDomain = new Set();
         for (const t of tools) {
             memoryPairNameDomain.add(t.name);
@@ -503,7 +509,10 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     const effect = (t.effect ?? toolEffects.get(t.name) ?? "write");
                     if (effect === "read")
                         return false;
-                    if (t.name !== "Write" && t.name !== "Edit" && t.name !== "NotebookEdit" && t.name !== "Bash")
+                    const face = faceOf(t);
+                    const pt = face.pathTarget ?? pathTargetOf(t.name);
+                    const family = face.family ?? catalogEntriesNamed(t.name)[0]?.face.family;
+                    if (!((pt !== undefined && pt.access !== "read") || family === "shell"))
                         return false;
                     return !(handsEnabled && isRemoteExecutionEnv(executionEnv));
                 }),
@@ -551,13 +560,22 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "config", sessionId });
             }
         }
-        const projectContext = await prepareProjectContext({ deps, spec, internals, session, sessionId, hostTaskId, taskRootFinal, handsEnabled, delegation, seedContextFiles, memoryBlockFromEngine, skillScope, tools, toolFaceSnapshot, onceLedger, memoryTools, memoryEngineSession, memorySearchToolsPlanned, memoryPairExcludedName, memoryPairOccupiedName, resume });
+        const projectContext = await prepareProjectContext({ deps, spec, internals, session, sessionId, hostTaskId, taskRootFinal, handsEnabled, delegation, seedContextFiles, memoryBlockFromEngine, skillScope, roster, toolFaceSnapshot, onceLedger, memoryTools, memoryEngineSession, memorySearchToolsPlanned, memoryPairExcludedName, memoryPairOccupiedName, resume });
         const { memoryBlock: memoryBlockWithProject, instructionSources, projectInstructionContent, hasSkillManifest, skillsListing, sharedMemoryPairMounted, memoryEnginePairMounted } = projectContext;
         const { provider, featureFlags, userSystemPrompt, userAppendSystemPrompt, mcpInstructionsBlock, envFacts, tzValid, userTz, gitStatusRef } = await preparePromptInputs({ spec, deps, failClosedReason: selfOrchestrationFailClosedReason(spec, deps), lockedPreflight, selfOrchestrationActive, executionEnv, reminderMark, resolvedReadFace, toolFaceSnapshot, promptProfile, fableMitigations, internals, thinking, ownedEnv, delegation, resolvedRole, mcp, model, externalContentTargetActive, resume, handsEnabled, taskRootFinal, additionalRootsCanonical, additionalReadRootsCanonical, sessionId });
-        const { deferred, memoryBlock } = prepareDeferClassify({ spec, deps, tools, toolFaceSnapshot, handsEnabled, fullShellReachable, promptProfile, model, mcp, a2a, sharedMemoryPairMounted, memoryEnginePairMounted, memoryBlock: memoryBlockWithProject, memoryRecallSegment, onceLedger, sessionId });
-        prepareMemoryEngineSession({ memoryEngineSession, internals, memoryDelegationEvidence, externalContentTargetActive, lockedPreflight, mcp, sessionId, runId, deps, provenanceForChildrenRef, delegationSettlementRef, spec, envHandToolNames, tools, contentOriginWrapRef });
+        const { deferred, memoryBlock } = prepareDeferClassify({ spec, deps, roster, toolFaceSnapshot, handsEnabled, fullShellReachable, promptProfile, model, mcp, a2a, sharedMemoryPairMounted, memoryEnginePairMounted, memoryBlock: memoryBlockWithProject, memoryRecallSegment, onceLedger, sessionId });
+        prepareMemoryEngineSession({ memoryEngineSession, internals, memoryDelegationEvidence, externalContentTargetActive, lockedPreflight, mcp, sessionId, runId, deps, provenanceForChildrenRef, delegationSettlementRef, spec, envHandToolNames, roster, contentOriginWrapRef });
         const { systemPromptSeat, renderWithDate, systemBlocks, promptManifest, epochDeclaredSections, epochArtifactDigestForSnapshot, buildAssembleInputs, centerAdoptionRef } = await preparePromptAssembly({ session, deps, internals, resume, provider, userSystemPrompt, userAppendSystemPrompt, featureFlags, mcpInstructionsBlock, memoryBlock, envFacts, promptProfile, fableMitigations, tools, model, sessionId, reminderMark, onceLedger });
-        const { activeTools, fpRef, turnSnapshotRef, harnessTools, toolsDeltaRef, toolMaterializeStatic, deferDirectCall, staticFaceForRef, listingRideRef } = await prepareToolDisclosureMount({ spec, deps, session, resume, deferred, tools, onceLedger, mcp, promptManifest, offloadReachableToolsRef, contentOriginWrapRef, rebuildHarnessToolsRef, harnessRef });
+        const { activeTools, fpRef, turnSnapshotRef, harnessTools, toolsDeltaRef, toolMaterializeStatic, deferDirectCall, staticFaceForRef, listingRideRef, toolSearch } = await prepareToolDisclosureMount({ spec, deps, session, resume, deferred, tools, onceLedger, mcp, promptManifest, offloadReachableToolsRef, contentOriginWrapRef, rebuildHarnessToolsRef, harnessRef });
+        if (toolSearch !== undefined)
+            roster.mountEngineLane(toolSearch, { source: "builtin", mountedBy: "optional" });
+        const rosterFacts = { effects: toolEffects, egress: egressTools, irreversibilityTier, reversibilityProbes, deferred, trustedTools: new Set(spec.memory?.trustedTools ?? []) };
+        const toolRoster = roster.snapshot(rosterFacts);
+        rosterSeat.arm(toolRoster, () => roster.snapshot(rosterFacts));
+        const structuredProjector = createStructuredProjector({
+            declaredCards: toolRoster.entries.flatMap((e) => e.renderHints?.resultCards ?? []),
+            onUndeclared: (type) => deliverEngineNotice(deps.onNotice, { code: "config.tool_card_undeclared", message: `a tool minted a \`details.type\` card ${JSON.stringify(type)} its definition never declared — dropped from tool_end.structured (declare it on the definition's catalog row or the caller's renderHints.resultCards)`, detail: { type, sessionId, runId } }),
+        });
         const { agentListing, announcedListingsRef, dateChange } = prepareListings({ spec, tools, onceLedger, sessionId, toolFaceSnapshot, activeTools, resume, skillsListing, listingRideRef, renderWithDate, envFacts, tzValid, userTz });
         const lastBrainContextRef = {};
         const requestLossyRef = { current: false };
@@ -614,7 +632,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             ...(spec.streamingToolExecution === true ? { streamingToolExecution: true } : {}),
             env: executionEnv,
             session,
-            tools: harnessTools,
+            tools: [...harnessTools],
             model,
             thinkingLevel: thinking ?? "off",
             systemPrompt: systemPromptSeat.current,
@@ -652,7 +670,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             }
         }
         const { hooks, hookTimeoutMs, preToolUseObservational, ownGatePreToolUse, basePolicyForResumeEdit, denyNarrowingPolicy, policyLayers, effectivePolicy, inheritedUnavailableAsks, inheritedAskGrants, askSourceIdentity, riskAxesOf, ruleOffersOf, permissionRuleLane, permissionRuleOrgLane, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, foldAskClasses, ancestorSandboxAdmissions } = await preparePolicyChain({ spec, deps, internals, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, lockedPreflight, tools, harnessTools, toolEffects, egressTools, irreversibilityTier, axisExplicitNegatives, ownToolNames, shellGatedBash, handsCwdRef, readDenyMatcher, questionToolMounted, runtimeCaps, inheritedAncestorRules, inheritedParentConstraints, seedInheritedGate, hasSkillManifest, skillScope, frozenOnAsk, hookEnvSource, notifyOwnHookCrash, autoModeDecider, stopForDenialLimit, delegation, abortController, now, ownSessionRulesRef });
-        const { onAsk, preToolContexts, blockedToolCalls, gateOutcomes, batchHaltRef, blockedTracked, incompleteSuspendAdapter, durableSuspendInfraReady, resourceSuspendEligible, usageGovernance, durableApproval, wiringManifest, parkLaneArmed, gateMachineryActive, hookIdentity, hookEnvFace } = prepareWiringManifest({ spec, deps, internals, resume, sessionId, runId, hostTaskId, taskScope, hooks, preToolUseObservational, policyLayers, effectivePolicy, handsEnabled, mcp, irreversibleTools, egressTools, toolEffects, ownedEnv, executionEnv, offloadStore, onceLedger, usageWindows, envLifetimeSuspendAt, runtimeCaps, resolvedInteractionPosture, durableQuestionFace, liveQuestionFace, checkpointStore, sessions, modelGateManifest, autoModeArmReason, lockedPreflight, peerLaneRefs, peerLaneActive, harness, pausedRef, frozenOnAsk, liveInheritedGate, delegation });
+        const { onAsk, preToolContexts, blockedToolCalls, gateOutcomes, batchHaltRef, blockedTracked, incompleteSuspendAdapter, durableSuspendInfraReady, resourceSuspendEligible, usageGovernance, durableApproval, wiringManifest, parkLaneArmed, gateMachineryActive, hookIdentity, hookEnvFace } = prepareWiringManifest({ spec, deps, internals, resume, sessionId, runId, hostTaskId, taskScope, hooks, preToolUseObservational, policyLayers, effectivePolicy, handsEnabled, mcp, irreversibleTools, egressTools, toolEffects, ownedEnv, executionEnv, offloadStore, onceLedger, usageWindows, envLifetimeSuspendAt, runtimeCaps, resolvedInteractionPosture, durableQuestionFace, liveQuestionFace, checkpointStore, sessions, modelGateManifest, autoModeArmReason, lockedPreflight, peerLaneRefs, peerLaneActive, harness, pausedRef, frozenOnAsk, liveInheritedGate, delegation, toolRoster });
         if (fileHistoryBoundary !== undefined) {
             harness.on("tool_call", async () => {
                 await fileHistoryBoundary.settle();
@@ -662,13 +680,13 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const { askLane } = prepareAskLane({ gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, now, ruleOffersOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash });
         const { saga } = prepareSuspendSaga({ gateMachineryActive, abortController, harness, checkpointStore, deps, sessionId, hostTaskId, taskScope, liveSpendRef, resume, nestedStats, internals, activeTools, outputRef, readFileStateForCheckpoint, faceCheckpointSection, reminderMark, handsCwdRef, worktreeSessionRef, inheritedParentConstraints, seedInheritedGate, inheritedAncestorRules, inheritedShellGate, autoModeIntent, autoModeDecider, inheritedAdmittedOrgScopes, ownOrgVerdictRef, orgGovernedProvenance, announcedListingsRef, gitStatusRef, hookIdentity, placementRootResolved, externalContentTargetActive, remoteEnvFailures, memoryEngineSession, suspendLoopRef, ownedEnv, incompleteSuspendAdapter });
         const { suspendForResource, suspendForPlatformLimit, suspendForReview } = prepareBoundaryParks({ saga, spec, checkpointStore, abortController, harness, session, sessions, sessionId, deps, priorLedger, maxSlices, maxSuspends, resourceTotal, priorSuspendCount, suspendChainBase, humanReviewRef, liveSpendRef, now, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, pausedRef, remoteEnvFailures, resourceSuspendEligible, durableSuspendInfraReady, incompleteSuspendAdapter });
-        const { parkAsk } = prepareParkAsk({ 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 });
-        prepareGateStations({ 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 });
+        const { parkAsk } = prepareParkAsk({ askLane, saga, spec, deps, sessionId, checkpointStore, toolRosterDeltas: rosterSeat, 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 });
+        prepareGateStations({ askLane, parkAsk, tools, toolRosterDeltas: rosterSeat, 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 });
         const { microCompact, charsPerToken } = prepareContextLane({ model, deps, sessionId, runId, hostTaskId, offloadStore, microCompactKnob, harness, batchHaltRef, gitStatusRef, requestLossyRef, trimPressureRef });
         const preparedHolder = {};
         const { cacheBreakDetector, cacheFingerprint, promptOverheadTokens, readTaskFile, normalizeAttachmentPath, isDedupStubResult, recentlyReadFiles, onCompactionApplied, detectExternalChanges, listBackgroundTasks, centerCompactionCandidate, effectiveReadFaceObserved, effectiveReadDenyObserved } = prepareTurnWiring({ deps, systemPromptSeat, harnessTools, fpRef, model, epochArtifactDigestForSnapshot, promptProfile, fableMitigations, systemBlocks, thinking, spec, sessionId, turnSnapshotRef, promptManifest, charsPerToken, handsEnabled, executionEnv, attachmentRootCanonical, additionalRootsCanonical, additionalReadRootsCanonical, readDenyMatcher, resolvedReadFace, handsCwdRef, readFileStateForCheckpoint, denyNarrowingPolicy, abortController, hostTaskId, taskScope, buildAssembleInputs, centerAdoptionRef, harnessRef, epochDeclaredSections, carrierReadFace, readDenyAdditionsNormalized, preparedHolder });
         await onceLedger.settle(session, announcedListingsRef);
-        const buildPrepared = () => ({ harness, session, sessionId, runId, reminderMark, reminderDisclosureCounts, editedFilesSnapshot, taskRootPath: taskRootFinal, model, thinking, compModel: effectiveCompModel, mcp, ...(a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, gateOutcomes, batchHaltRef, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(fileHistoryBoundary !== undefined ? { fileHistoryBoundary } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), effectiveMemoryScopes: memoryEffectiveScopes, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), ...(sealReadStateSeat !== undefined ? { sealReadStateSeat } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, pausedRef, suspendProgressRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, gateStopRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, microCompact, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, stopRequestedRef, announcedSnapshotRecovered: onceLedger.recovered, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(projectInstructionContent !== undefined ? { projectInstructionContent } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, gitStatusRef, listBackgroundTasks, hookIdentity, hookTimeoutMs, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, runId, reminderMark, reminderDisclosureCounts, editedFilesSnapshot, taskRootPath: taskRootFinal, model, thinking, compModel: effectiveCompModel, mcp, ...(a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, gateOutcomes, batchHaltRef, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(fileHistoryBoundary !== undefined ? { fileHistoryBoundary } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), effectiveMemoryScopes: memoryEffectiveScopes, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), ...(sealReadStateSeat !== undefined ? { sealReadStateSeat } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, pausedRef, suspendProgressRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, gateStopRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolRoster, toolRosterDeltas: rosterSeat, structuredProjector, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, microCompact, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, stopRequestedRef, announcedSnapshotRecovered: onceLedger.recovered, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(projectInstructionContent !== undefined ? { projectInstructionContent } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, gitStatusRef, listBackgroundTasks, hookIdentity, hookTimeoutMs, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         rollback.commit();
         const prepared = buildPrepared();
         preparedHolder.current = prepared;

package/dist/core/runner/prepare-tool-disclosure-mount.d.ts

@@ -36,7 +36,7 @@ export interface PrepareToolDisclosureMountInput {
     deferred: ReadonlySet<string>;
     /** borrowed-readonly — the run's shared roster (`Prepared.tools`): READ here — the registry build, the reserved-name
      *  check, the live resolution the placeholders and the static face perform at call time. Never written by this phase. */
-    tools: AgentTool[];
+    tools: readonly AgentTool[];
     /** borrowed-readonly — the once-per-session ledger's failed-server projection (current failures minus the pairs this
      *  session already announced). */
     onceLedger: {
@@ -87,7 +87,10 @@ export interface PrepareToolDisclosureMountResult {
     };
     /** owned — the list the harness is built from: the roster with placeholders in the deferred slots plus ToolSearch (or the
      *  roster itself when nothing is deferred). */
-    harnessTools: AgentTool[];
+    harnessTools: readonly AgentTool[];
+    /** owned — the ToolSearch instance the deferred arm appended to the harness list (absent when nothing is deferred): the
+     *  driver mounts it on the roster's ENGINE LANE so the roster carries every name the model can call. */
+    toolSearch?: AgentTool;
     /** owned — the boundary delta ref (`Prepared.toolsDeltaRef`), minted when anything is deferred OR a server failed. */
     toolsDeltaRef: Prepared["toolsDeltaRef"];
     /** owned — the effective strategy (`Prepared.toolMaterializeStatic`). */

package/dist/core/runner/prepare-tool-disclosure-mount.js

@@ -31,6 +31,7 @@ export async function prepareToolDisclosureMount(input) {
     const fpRef = {};
     const turnSnapshotRef = {};
     let harnessTools = tools;
+    let toolSearchMounted;
     const failedMcpServers = onceLedger.mcpFailuresToAnnounce(mcp.statuses);
     let toolsDeltaRef;
     let toolMaterializeStatic = false;
@@ -204,6 +205,7 @@ export async function prepareToolDisclosureMount(input) {
             serializeActivation,
         });
         harnessTools = buildToolList(activeTools);
+        toolSearchMounted = toolSearch;
     }
     else {
         rebuildHarnessToolsRef.current = async () => {
@@ -215,5 +217,5 @@ export async function prepareToolDisclosureMount(input) {
             turnSnapshotRef.current?.refreshTools(toolsToFingerprintInputs(list));
         };
     }
-    return { activeTools, fpRef, turnSnapshotRef, harnessTools, toolsDeltaRef, toolMaterializeStatic, deferDirectCall, staticFaceForRef, listingRideRef };
+    return { activeTools, fpRef, turnSnapshotRef, harnessTools, toolsDeltaRef, toolMaterializeStatic, deferDirectCall, staticFaceForRef, listingRideRef, ...(toolSearchMounted !== undefined ? { toolSearch: toolSearchMounted } : {}) };
 }

package/dist/core/runner/prepare-wiring-manifest.d.ts

@@ -29,6 +29,7 @@ import { type OnAsk, type ToolPolicy } from "../tool-policy.js";
 import type { GateOutcome } from "../gate-outcome.js";
 import type { RunnerDeps, RuntimeCaps, TaskSpec, ToolEffect, ToolExecuteContext } from "../types.js";
 import { type UsageWindow } from "../usage-window-store.js";
+import type { ToolRoster } from "../tool-roster.js";
 import { type AutoModeArmReason, type WiringManifest, type WiringManifestMcpEntry } from "../wiring-manifest.js";
 import type { AnnounceOnceSink, Prepared, PrepareResume, RunInternals, UsageGovernance } from "./contracts.js";
 export interface PrepareWiringManifestInput {
@@ -102,6 +103,9 @@ export interface PrepareWiringManifestInput {
     sessions: SessionStore;
     /** borrowed-readonly — the model gate's per-leg read face, or undefined. */
     modelGateManifest: WiringManifest["modelGate"];
+    /** borrowed-readonly — the leg's minted tool roster (design/388): rides the manifest's `tools` section and is the
+     *  source of the hand band's write-capable names for the ungated-write warning (what actually MOUNTED). */
+    toolRoster: ToolRoster;
     /** borrowed-readonly — the arming outcome the caps phase minted (the manifest's auto-mode face). */
     autoModeArmReason: AutoModeArmReason;
     /** borrowed-readonly — the frozen preflight; only `mcp` (the declared servers the manifest face joins). */

package/dist/core/runner/prepare-wiring-manifest.js

@@ -1,5 +1,4 @@
 import { bindPeerLaneDrain } from "../../agents/peer-session-drain.js";
-import { HAND_TOOL_EFFECTS } from "../../tools/fs/index.js";
 import { resolveCheckpointStore } from "../checkpoint-store.js";
 import { createHookEnvCapabilities, mintHookInvocationIdentity } from "../hooks.js";
 import { isRemoteExecutionEnv, missingRestoreSurface } from "../remote-env.js";
@@ -109,14 +108,9 @@ function announceDurableGateUnavailable(args) {
     });
 }
 export function prepareWiringManifest(input) {
-    const { spec, deps, internals, resume, sessionId, runId, hostTaskId, taskScope, hooks, preToolUseObservational, policyLayers, effectivePolicy, handsEnabled, mcp, irreversibleTools, egressTools, toolEffects, ownedEnv, executionEnv, offloadStore, onceLedger, usageWindows, envLifetimeSuspendAt, runtimeCaps, resolvedInteractionPosture, durableQuestionFace, liveQuestionFace, checkpointStore, sessions, modelGateManifest, autoModeArmReason, lockedPreflight, peerLaneRefs, peerLaneActive, harness, pausedRef, frozenOnAsk, liveInheritedGate, delegation } = input;
+    const { spec, deps, internals, resume, sessionId, runId, hostTaskId, taskScope, hooks, preToolUseObservational, policyLayers, effectivePolicy, mcp, irreversibleTools, egressTools, toolEffects, ownedEnv, executionEnv, offloadStore, onceLedger, usageWindows, envLifetimeSuspendAt, runtimeCaps, resolvedInteractionPosture, durableQuestionFace, liveQuestionFace, checkpointStore, sessions, modelGateManifest, autoModeArmReason, lockedPreflight, peerLaneRefs, peerLaneActive, harness, pausedRef, frozenOnAsk, liveInheritedGate, delegation, toolRoster } = input;
     const onAsk = spec.onAsk ?? deps.onAsk;
-    const handWriteTools = handsEnabled && spec.handsReadOnly !== true
-        ? Object.keys(HAND_TOOL_EFFECTS).filter((name) => {
-            const eff = HAND_TOOL_EFFECTS[name];
-            return eff === "write" || eff === "idempotent";
-        })
-        : [];
+    const handWriteTools = toolRoster.entries.filter((e) => e.mountedBy === "hands" && (e.effect === "write" || e.effect === "idempotent")).map((e) => e.name);
     const hasEffectAwareGate = Boolean(policyLayers.length > 0 || (hooks?.preToolUse !== undefined && !preToolUseObservational));
     const destructiveMcpUngated = mcp.tools.some((t) => !irreversibleTools.has(t.name) && !egressTools.has(t.name) && (toolEffects.get(t.name) ?? "write") !== "read");
     const firstPartyWriteUngated = (spec.tools ?? [])
@@ -207,6 +201,7 @@ export function prepareWiringManifest(input) {
         ...(modelGateManifest !== undefined ? { modelGate: modelGateManifest } : {}),
         autoMode: { armed: autoModeArmReason === "armed", reason: autoModeArmReason },
         mcp: mcpManifestEntries(lockedPreflight.mcp, mcp.statuses),
+        tools: toolRoster,
     });
     peerLaneRefs.askEffective = wiringManifest.ask.effective;
     if (peerLaneActive && internals?.onTaskNotification !== undefined) {

package/dist/core/runner/run-harness-handlers.d.ts

@@ -0,0 +1,46 @@
+import type { AgentHarnessEvent } from "../../internal/harness.js";
+import type { Stats } from "./assemble-result.js";
+import type { HarnessHandlersDeps, Prepared, RunState } from "./contracts.js";
+/**
+ * What the driver hands the harness-handlers lane, once per leg — the four positional parameters the
+ * factory used to take, as one carrier of REFERENCES (the handlers read the seats live on every event).
+ */
+export interface RunHarnessHandlersInput {
+    /** borrowed-mutable — the leg's prepared seat. Read throughout; written only into one per-run ref cell
+     *  (`callIssuedAtRef.current`, cleared when the model's turn ends). */
+    prepared: Prepared;
+    /** borrowed-mutable — the run's usage counters. This lane is their WRITER: the turn's usage lands on
+     *  them in onMessageEnd, tool calls and turns are counted in onToolStart / onTurnEnd. */
+    stats: Stats;
+    /** borrowed-mutable — the run's mutable state; the handlers write the turn / counters / limits /
+     *  budget groups, per the writer table on the type. */
+    rs: RunState;
+    /** borrowed-readonly — the driver-declared const seats + the runner's onError, see
+     *  {@link HarnessHandlersDeps}. */
+    deps: HarnessHandlersDeps;
+}
+/** The five harness event handlers + the workspace-move mint, as the driver destructures them. */
+export interface RunHarnessHandlersResult {
+    onMessageUpdate: (event: Extract<AgentHarnessEvent, {
+        type: "message_update";
+    }>) => void;
+    onMessageEnd: (event: Extract<AgentHarnessEvent, {
+        type: "message_end";
+    }>) => void;
+    onToolStart: (event: Extract<AgentHarnessEvent, {
+        type: "tool_execution_start";
+    }>) => void;
+    onToolEnd: (event: Extract<AgentHarnessEvent, {
+        type: "tool_execution_end";
+    }>) => void;
+    onTurnEnd: () => void;
+    /** RB-475 — the single workspace_changed mint (cwd diff vs the closure's dedupe state); the run body
+     *  calls it after a resume's approved-call resolution, which bypasses onToolEnd. */
+    announceWorkspaceMove: () => void;
+}
+/** design/157 B15 尾件 — R5 抽取:runLocked 的五个 harness 事件处理器(onMessageUpdate/onMessageEnd/
+ *  onToolStart/onToolEnd/onTurnEnd,~530 行)整块搬迁。正文逐字;唯一字面变化 = this.deps.onError →
+ *  deps.runnerHooks.onError(1 处)。`lastWorkspaceCwd` 是纯 R5 局部(读写全在 onToolEnd 内,零段外
+ *  读者),声明随迁进工厂体——调用点放在原声明位之后,初值 `prepared.cwdRef?.current` 的求值时机不变
+ *  (中间只有声明无执行)。*/
+export declare function createHarnessHandlers(input: RunHarnessHandlersInput): RunHarnessHandlersResult;