@sema-agent/core 7.6.3 → 7.8.0

package/dist/core/runner/git-leg-delivery.d.ts

@@ -0,0 +1,28 @@
+import type { MaybeCompactOptions } from "../auto-compaction.js";
+import type { Prepared } from "./contracts.js";
+/** env-tail migration — the git frame's authority shell: the single-point F3 wrap the first-frame
+ *  listings use (one `<system-reminder>` per body, body neutralized — idempotent over the already-
+ *  sanitized snapshot; the S2 breakout posture). */
+export declare function wrapGitFrame(body: string, mark: string | undefined): string;
+/**
+ * env-tail migration — the git lane's leg-boundary decision: read ladder (BRANCH AUTHORITY) then
+ * the `(kind, hash)` compare. Ladder rungs:
+ *   ① nearest mirror on the active session branch — a PENDING carrier (or an announced carrier
+ *      whose frame entry is off the branch) is a MANDATORY re-announce gate, overriding everything;
+ *   ② the checkpoint mirror, only when the branch carries no mirror at all — its own `entryId`
+ *      must sit on the active branch to count as announced (a rewound frame under a descendant
+ *      checkpoint reads as pending);
+ *   ③ full absence ⇒ conservative re-announce (duplicate-tolerant by design).
+ * Seeds `ref.announced` with the resolved prior (pendingness preserved — a suspend before the
+ * receipt then mirrors the honest state) and returns the frame BODY to deliver, or undefined when
+ * the announced view already matches (or the lane has nothing to say this leg). Tombstone kinds
+ * fire on the availability FLIP EDGE only: with no prior view at all there is nothing to disown —
+ * no frame (the probe's own onError already told the deployment).
+ */
+export declare function resolveGitLegDelivery(prepared: Prepared, cpMirror: unknown, report: (err: Error) => void): Promise<string | undefined>;
+/** env-tail migration — the compaction interaction option for one `maybeCompact` invocation (ALL
+ *  THREE routes — turn-boundary auto, prompt-too-long recovery, end-of-task finish — thread this
+ *  same builder, the single-source requirement): the current tuple restated as PENDING on the
+ *  compaction entry (same CAS as the new baseline) + the run's re-assert closure as the landing
+ *  hook. Empty when the lane never announced anything (nothing to preserve across the summary). */
+export declare function gitRestateOption(prepared: Prepared): Pick<MaybeCompactOptions, "gitRestate">;

package/dist/core/runner/git-leg-delivery.js

@@ -0,0 +1,94 @@
+import { gitFrameContextVisible, normalizeGitAnnouncement } from "../../internal/harness.js";
+import { mintSystemReminder } from "../reminder-mint.js";
+import { sanitizeUntrustedText, SHELLED_BODY_ENVELOPE_TAGS } from "../untrusted-text.js";
+import { branchCarriesVisiblePositiveGitFrame, newestEngineGitFrame } from "./git-status-frame.js";
+export function wrapGitFrame(body, mark) {
+    return mintSystemReminder(sanitizeUntrustedText(body, SHELLED_BODY_ENVELOPE_TAGS), mark);
+}
+export async function resolveGitLegDelivery(prepared, cpMirror, report) {
+    const ref = prepared.gitStatusRef;
+    const frame = ref.frame;
+    if (frame === undefined)
+        return undefined;
+    let prior;
+    let pending = false;
+    try {
+        const branchReadout = await prepared.session.getGitAnnouncement?.();
+        if (branchReadout !== undefined) {
+            if (branchReadout.status === "pending") {
+                pending = true;
+                prior = { kind: branchReadout.kind, hash: branchReadout.hash };
+            }
+            else {
+                prior = { kind: branchReadout.kind, hash: branchReadout.hash, ...(branchReadout.entryId !== undefined ? { entryId: branchReadout.entryId } : {}) };
+            }
+        }
+        else {
+            const shaped = normalizeGitAnnouncement(cpMirror);
+            if (shaped !== undefined) {
+                if (shaped.pending === true || shaped.entryId === undefined) {
+                    pending = true;
+                    prior = { kind: shaped.kind, hash: shaped.hash };
+                }
+                else if (gitFrameContextVisible(await prepared.session.getBranch(), shaped.entryId)) {
+                    prior = { kind: shaped.kind, hash: shaped.hash, entryId: shaped.entryId };
+                }
+                else {
+                    pending = true;
+                    prior = { kind: shaped.kind, hash: shaped.hash };
+                }
+            }
+        }
+    }
+    catch (err) {
+        pending = true;
+        report(err instanceof Error ? err : new Error(String(err)));
+    }
+    if (prior !== undefined && !pending && prior.entryId !== undefined) {
+        try {
+            const newest = newestEngineGitFrame(await prepared.session.getBranch(), prepared.reminderMark);
+            if (newest === undefined || newest.entryId !== prior.entryId)
+                pending = true;
+        }
+        catch (err) {
+            pending = true;
+            report(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    if (prior !== undefined)
+        ref.announced = pending ? { ...prior, pending: true } : { ...prior };
+    const negative = frame.kind === "unavailable" || frame.kind === "non-repo";
+    if (negative) {
+        if (prior === undefined && !pending) {
+            let mustDisown;
+            try {
+                mustDisown = branchCarriesVisiblePositiveGitFrame(await prepared.session.getBranch(), prepared.reminderMark);
+            }
+            catch (err) {
+                mustDisown = true;
+                report(err instanceof Error ? err : new Error(String(err)));
+            }
+            return mustDisown ? frame.body : undefined;
+        }
+        if (prior !== undefined && !pending && prior.kind === frame.kind && prior.hash === frame.hash)
+            return undefined;
+        return frame.body;
+    }
+    if (!pending && prior !== undefined && prior.kind === frame.kind && prior.hash === frame.hash) {
+        ref.protectedText = wrapGitFrame(frame.body, prepared.reminderMark);
+        if (frame.kind === "full" && frame.shrunk !== undefined) {
+            ref.wrappedShrink = { find: ref.protectedText, replace: wrapGitFrame(frame.shrunk.body, prepared.reminderMark) };
+        }
+        return undefined;
+    }
+    return frame.body;
+}
+export function gitRestateOption(prepared) {
+    const ref = prepared.gitStatusRef;
+    if (ref.frame === undefined || ref.announced === undefined || ref.reassert === undefined)
+        return {};
+    const use = ref.overBudgetShrunk && ref.frame.shrunk !== undefined
+        ? { kind: "degraded", hash: ref.frame.shrunk.hash }
+        : { kind: ref.frame.kind, hash: ref.frame.hash };
+    return { gitRestate: { pending: use, land: ref.reassert } };
+}

package/dist/core/runner/initial-run-state.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The zero-value constructor of {@link RunState}, the run loop's ONE shared mutable record (seven groups,
+ * sixty fields; its writers are the run loop's three top-level machines, see the interface's own doc in
+ * contracts.ts). The driver mints one per run leg and hands it to every machine as a `borrowed-mutable`
+ * seat; nothing here reads or writes host state, so the skeleton is machinery, not a phase.
+ *
+ * Named without the `run-` family prefix on purpose: that prefix marks a DRIVEN run lane (one the driver
+ * calls with an Input and reads a Result from — the phase-api gate judges every such file), and the
+ * layering registry's run-lanes stratum is a glob over the same prefix. A machinery module the lanes stand
+ * on sits one layer below them under a name of its own, exactly as the prepare-path machinery does.
+ */
+import type { RunState } from "./contracts.js";
+/** Zero-value skeleton — every REAL value is assigned at the field's original declaration site. */
+export declare function createRunState(): RunState;

package/dist/core/runner/initial-run-state.js

@@ -0,0 +1,11 @@
+export function createRunState() {
+    return {
+        telemetry: { cacheFamily: "input-excludes-cached", pricing: { inputPer1M: 0, outputPer1M: 0 }, pricingConfigured: true, unpricedSpend: false, tracer: undefined, taskId: "", runId: "", taskStart: 0, taskStartMonotonic: 0, cacheBreakReported: false },
+        degrade: { degradeToModel: undefined, degraded: undefined, outputErrorStreak: 0, outputInvalid: false, recordDegraded: () => { } },
+        limits: { turnsExceeded: false, budgetHit: undefined, budgetAxis: undefined, platformTerminal: undefined, outputRetryCap: 0, effectiveMaxTurns: undefined },
+        budget: { remainingMicroUsd: undefined, maxCostMicroUsd: undefined, remainingTokens: undefined, maxTokensWindow: undefined, overBudget: () => undefined, streamCancel: false, callOutputChars: 0, lastStreamBudgetCheck: 0, projectedOverBudget: () => undefined },
+        turn: { callStartAt: undefined, firstTokenAt: undefined, turnUsage: undefined, turnUsageMissing: false, turnStopReason: undefined, lastTurnHadToolCalls: false, toolBatch: [] },
+        counters: { approachNoticesSent: 0, walltimeSyncBackstopFired: false, compactionFloor: 0, trimForceBackoff: false, repetitionCuts: 0, repetitionSpared: 0, repetitionEvents: [], REPETITION_EVENTS_CAP: 0, preemptIgnoredReported: false, wroteThisRun: false, finalVerifyInjections: 0, groundingSignalPreR9: false, groundingSignalPostR9: false, cadenceTurns: 0 },
+        attach: { attachmentsCfg: undefined, agentListingOn: false, skillsListingOn: false, attachState: undefined, dateState: undefined, instrProbe: undefined, instrState: undefined, sizeGuidelineState: undefined, attachmentsInjected: 0 },
+    };
+}

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

@@ -46,7 +46,7 @@ export interface PrepareAskLaneInput {
     handsCwdRef: CwdRef | undefined;
     /** borrowed-readonly — the shared mount roster; read at RUN time by the approval-preview projection (alias-aware
      *  lookup over whatever the roster holds when the ask is minted). Never mutated here. */
-    tools: AgentTool[];
+    tools: readonly AgentTool[];
     /** borrowed-mutable — the inherited-unavailable marker set. Writer here: `resolveAskBound` consumes (`delete`) a
      *  marked call at its fail-closed intercept; the policy-chain phase records, the gate station sweeps. */
     inheritedUnavailableAsks: Set<string>;

package/dist/core/runner/prepare-caps-and-workflow.d.ts

@@ -34,6 +34,7 @@ import type { AutoModeArmReason } from "../wiring-manifest.js";
 import type { ReadFace } from "../../tools/fs/index.js";
 import type { InheritedGate, Prepared, RunInternals, RunnerSelfSeat, ToolFaceSnapshot } from "./contracts.js";
 import { type BlockedRef } from "./synthetic-tools.js";
+import { RosterBuilder } from "../tool-roster.js";
 export interface PrepareCapsAndWorkflowInput {
     /** borrowed-readonly — the REBOUND spec, whole: the roster map reads `tools`; the mounts read `enableBlockedReport`,
      *  `enablePlanMode`, `interactiveTools`, `checkpointStore`; the caps/compliance stations read `principal`, `selfOrchestration`,
@@ -124,10 +125,10 @@ export interface PrepareCapsAndWorkflowInput {
     }>;
 }
 export interface PrepareCapsAndWorkflowResult {
-    /** owned — THE run's roster, minted here from the caller's tools; every later mount pushes into this same array
-     *  (`Prepared.tools`, whose JSDoc carries the writer table). Writers here: the map that mints it, then the ReportBlocked,
-     *  ReportFindings, ExitPlanMode, EnterPlanMode and Workflow pushes. */
-    tools: AgentTool[];
+    /** owned — THE run's roster BUILDER (design/388: the mount array is private to it; `Prepared.tools` is its read face,
+     *  whose JSDoc carries the writer table). Minted here from the caller's tools; every later mount goes through its verbs.
+     *  Writers here: the caller mounts, then the ReportBlocked, ReportFindings, ExitPlanMode, EnterPlanMode and Workflow mounts. */
+    roster: RosterBuilder;
     /** borrowed-mutable — the ReportBlocked tool's write seat (`Prepared.blockedRef`). Writer: the tool at run time; read at
      *  result assembly. */
     blockedRef: BlockedRef;

package/dist/core/runner/prepare-caps-and-workflow.js

@@ -2,10 +2,12 @@ import { isSyntheticApiErrorMessage } from "../../internal/harness.js";
 import { createHash } from "node:crypto";
 import { forkGovernanceDenial } from "../../agents/subagent.js";
 import { CROSS_SESSION_CLASSIFIER_RULE } from "../../agents/cross-session-envelope.js";
-import { createRunWorkflowTool, RUN_WORKFLOW_TOOL_NAME } from "../../orchestration/run-workflow-tool.js";
+import { createRunWorkflowTool } from "../../orchestration/run-workflow-tool.js";
 import { isSelfOrchestrationActive } from "../../orchestration/workflow-script-runner.js";
 import { resolveWorkflowSizeGuideline } from "../../orchestration/workflow-size-guideline.js";
+import { thinkingOffExpressible } from "../../brain/reasoning.js";
 import { autoModeArmingRecipeOf } from "../auto-mode-arming.js";
+import { AUTO_MODE_CLASSIFIER_MAX_TOKENS } from "../auto-mode-defaults.js";
 import { buildAutoModePrompt, renderAutoModeAction, renderAutoModeWindow } from "../auto-mode-prompt.js";
 import { createAutoModeDecider, createAutoModeDenialTracker } from "../auto-mode.js";
 import { resolveCheckpointStore } from "../checkpoint-store.js";
@@ -14,9 +16,11 @@ import { createPresentPlanTool, createEnterPlanModeTool } from "../present-plan-
 import { resolveTaskModel } from "../roles.js";
 import { brainToRuntime } from "../runtime.js";
 import { defaultTaskRegistry } from "../task-registry.js";
+import { emitTrace } from "../trace.js";
 import { defineTool, isDefineToolProduct } from "../tools.js";
 import { derivedRouteFallsBack } from "./derived-route-fallback.js";
 import { REPORT_FINDINGS_TOOL_NAME, createReportBlockedTool, createReportFindingsTool } from "./synthetic-tools.js";
+import { RosterBuilder, callerMountSource } from "../tool-roster.js";
 function assembleParentCaptureState(o, i, ctl, ancestors) {
     const build = (optedOut, indeterminate) => ({
         optedOut: optedOut === true,
@@ -62,7 +66,12 @@ function autoModeArmReasonOf(intent, facePresent, capsAutoMode, capsFaulted) {
 }
 export async function prepareCapsAndWorkflow(input) {
     const { 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 } = input;
-    const tools = (spec.tools ?? []).map((t) => {
+    const roster = new RosterBuilder(toolEffects);
+    for (const t of spec.tools ?? []) {
+        const mounted = mountCallerTool(t);
+        roster.mount(mounted, { source: callerMountSource(mounted), mountedBy: "scenario" });
+    }
+    function mountCallerTool(t) {
         if (isDefineToolProduct(t)) {
             return maybeOffload(t, t);
         }
@@ -70,20 +79,20 @@ export async function prepareCapsAndWorkflow(input) {
             ...t,
             execute: (args, ctx) => t.execute(args, enrichSpecToolCtx(ctx)),
         }), t);
-    });
+    }
     const blockedRef = {};
     if (spec.enableBlockedReport !== false) {
-        tools.push(createReportBlockedTool(blockedRef));
+        roster.mount(createReportBlockedTool(blockedRef), { source: "builtin", mountedBy: "always" });
     }
     if (!(spec.tools ?? []).some((t) => t.name === REPORT_FINDINGS_TOOL_NAME || t.aliases?.includes(REPORT_FINDINGS_TOOL_NAME))) {
-        tools.push(createReportFindingsTool());
+        roster.mount(createReportFindingsTool(), { source: "builtin", mountedBy: "always" });
     }
     if (spec.enablePlanMode === true && spec.interactiveTools !== false) {
         const planReviewFace = resolveCheckpointStore(spec, deps) !== undefined;
         if (spec.interactiveTools === true || planReviewFace) {
-            tools.push(defineTool(createPresentPlanTool(requestReview)));
+            roster.mount(defineTool(createPresentPlanTool(requestReview)), { source: "builtin", mountedBy: "optional" });
             if (planReviewFace) {
-                tools.push(defineTool(createEnterPlanModeTool(enterPlanMode)));
+                roster.mount(defineTool(createEnterPlanModeTool(enterPlanMode)), { source: "builtin", mountedBy: "optional" });
             }
         }
     }
@@ -156,11 +165,23 @@ export async function prepareCapsAndWorkflow(input) {
         const classifierLaneRule = peerLaneActive && peerSendMessageBuiltIn;
         const classifierSystemPrompt = buildAutoModePrompt(classifierLaneRule ? { ...am, crossSessionMessagesRule: CROSS_SESSION_CLASSIFIER_RULE } : am);
         const classifierRuntime = brainToRuntime(deps.brain);
+        const classifierCap = thinkingOffExpressible(classifierModel) ? { maxTokens: AUTO_MODE_CLASSIFIER_MAX_TOKENS } : {};
         autoModeDenialTracking = createAutoModeDenialTracker(am.denialLimit);
         autoModeDecider = createAutoModeDecider({
             ...(am.timeoutMs !== undefined ? { timeoutMs: am.timeoutMs } : {}),
             ...(am.failureThreshold !== undefined ? { failureThreshold: am.failureThreshold } : {}),
             ...(am.onBreakerOpen !== undefined ? { onBreakerOpen: am.onBreakerOpen } : {}),
+            onClassified: (info) => emitTrace(deps.tracer, () => ({
+                kind: "auto_mode.classified",
+                version: 1,
+                taskId: hostTaskId,
+                toolCallId: info.toolCallId,
+                model: classifierModel.id,
+                ms: info.ms,
+                verdict: info.verdict,
+                ...(info.cause !== undefined ? { cause: info.cause } : {}),
+                ts: Date.now(),
+            })),
             classify: async (input, signal) => {
                 const ctx = await session.buildContext();
                 const known = ctx.messages.filter((m) => !isSyntheticApiErrorMessage(m) &&
@@ -169,6 +190,8 @@ export async function prepareCapsAndWorkflow(input) {
                 const classifierAuth = await spec.getApiKeyAndHeaders?.(classifierModel);
                 const response = await classifierRuntime.completeSimple(classifierModel, { systemPrompt: classifierSystemPrompt, messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }] }, {
                     signal,
+                    reasoning: "off",
+                    ...classifierCap,
                     ...(classifierAuth?.apiKey !== undefined ? { apiKey: classifierAuth.apiKey } : {}),
                     ...(classifierAuth?.headers !== undefined ? { headers: classifierAuth.headers } : {}),
                 });
@@ -193,8 +216,7 @@ export async function prepareCapsAndWorkflow(input) {
         workflowToolsActive = true;
         const currentSizeGuideline = () => resolveWorkflowSizeGuideline(deps.workflowLimits?.sizeGuideline).size;
         workflowSizeGuideline = { legGuideline: currentSizeGuideline(), current: currentSizeGuideline };
-        toolEffects.set(RUN_WORKFLOW_TOOL_NAME, "write");
-        tools.push(await createRunWorkflowTool({
+        roster.mount(await createRunWorkflowTool({
             runner: runnerSelf,
             scriptRunner: deps.workflowScriptRunner,
             governanceBaseline: deps.workflowGovernanceBaseline,
@@ -249,7 +271,7 @@ export async function prepareCapsAndWorkflow(input) {
             parentCenterSourceRevision: () => input.centerAdoption()?.sourceRevision,
             ...(forwardEvent ? { forwardEvent } : {}),
             inheritedGateForChildren,
-        }));
+        }), { source: "builtin", mountedBy: "workflow" });
     }
-    return { tools, blockedRef, runtimeCaps, runtimeCapsFaulted, complianceDenies, complianceDegraded, agentForkDenial, observersActive, autoModeArmReason, autoModeDecider, autoModeDenialTracking, autoModeArming, selfOrchestrationActive, workflowToolsActive, workflowSizeGuideline };
+    return { roster, blockedRef, runtimeCaps, runtimeCapsFaulted, complianceDenies, complianceDegraded, agentForkDenial, observersActive, autoModeArmReason, autoModeDecider, autoModeDenialTracking, autoModeArming, selfOrchestrationActive, workflowToolsActive, workflowSizeGuideline };
 }

package/dist/core/runner/prepare-defer-classify.d.ts

@@ -1,43 +1,22 @@
-/**
- * design/390 M11 — prepareTask's TOOL-FACE FOLD + DEFERRED CLASSIFICATION phase: the exclusion valve's
- * true unmount (in place, on the shared mount array), the full-shell anti-drift invariant, the classic-
- * profile description swap, `classifyDeferredOverFace` (the one classifier both counterfactual passes
- * run), the built-in memory pairs' support-name pre-check (sole-cause counterfactual, whole-group
- * retraction, the engine pair's recall paragraph stripped back out of the memory block) and the final
- * `deferred` set. The body is the driver's stretch moved verbatim (one exception, named below); the
- * interface is the dependency list it had implicitly (design/238 R-1).
- *
- * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between
- * the git-status probe before it and the content-origin wrap after it (design/390 §1.5 S1: a stretch
- * with no await is extracted as a sync function — an `async` wrapper would open a microtask window).
- *
- * The one non-move: the stretch used to write `sharedMemoryPairMounted = false` /
- * `memoryEnginePairMounted = false` on the retraction arm. Nothing reads either flag after this stretch
- * (the driver's next reader was this stretch's own pair derivation, which runs first), so the two dead
- * writes are not carried into the Result — the flags arrive as borrowed-readonly inputs.
- *
- * Throws pass through unchanged: `internal.full_shell_reachable_mismatch` (an engine invariant, never a
- * configuration error). The reserved-name refusal for a standing ToolSearch collision is NOT here — it
- * belongs to the disclosure mount downstream, which reads the `deferred` set this phase returns.
- */
-import type { AgentTool } from "../../internal/harness.js";
 import type { Model } from "../../internal/llm.js";
 import type { MaterializedA2a } from "../a2a.js";
 import type { MaterializedMcp } from "../mcp.js";
 import type { RunnerDeps, TaskSpec } from "../types.js";
 import type { AnnounceOnceSink, ToolFaceSnapshot } from "./contracts.js";
+import { RosterBuilder } from "../tool-roster.js";
 export interface PrepareDeferClassifyInput {
     /** borrowed-readonly — the REBOUND spec (`spec′`); only `tools` is read (the caller roster the
      *  classifier judges: names for the full-schema filter, specs for the `defer` declarations). */
-    spec: Pick<TaskSpec, "tools">;
+    spec: Pick<TaskSpec, "tools" | "excludeAllTools">;
     /** borrowed-readonly — deployment deps; only `deferMode` is read (the classifier's mode knob). */
     deps: Pick<RunnerDeps, "deferMode">;
     /** borrowed-mutable — the shared mount array (later refs alias it; in-place contract, never
      *  re-created). Mutated here, in order: `splice` of every excluded name; element REPLACEMENT with a
      *  shallow copy for the classic-profile description swap (the caller's ToolSpec object is never
      *  mutated); `splice` of a retracted memory group. After this phase: the content-origin wrap
-     *  (element replacement with the wrapped object), the disclosure mount, the MCP refresh re-splice. */
-    tools: AgentTool[];
+     *  (element replacement with the wrapped object), the disclosure mount, the MCP refresh re-splice. Since
+     *  design/388 every one of those writes is a builder verb (`unmountWhere` / `replaceAt`). */
+    roster: RosterBuilder;
     /** borrowed-readonly — the frozen task-start tool face: `exclude` (the valve), `defer` (operator
      *  defers, exact wire names), `alwaysLoad` (the inline pins). */
     toolFaceSnapshot: Pick<ToolFaceSnapshot, "exclude" | "defer" | "alwaysLoad">;

package/dist/core/runner/prepare-defer-classify.js

@@ -4,6 +4,7 @@ import { ASK_USER_QUESTION_TOOL_NAME } from "../ask-question.js";
 import { MEMORY_ENGINE_TOOL_NAMES } from "../memory-engine/tools.js";
 import { SHARED_MEMORY_TOOL_NAMES } from "../shared-memory/types.js";
 import { TOOL_SEARCH_NAME, classifyDeferred } from "./tool-disclosure.js";
+import { RosterBuilder } from "../tool-roster.js";
 function explicitlyDeferredMemoryTrio(mounted, roster, deferNames) {
     return mounted ? MEMORY_ENGINE_TOOL_NAMES.filter((n) => roster.some((t) => t.name === n) && (deferNames ?? []).includes(n)) : [];
 }
@@ -11,13 +12,15 @@ function memoryGroupRetractionSet(builtinDeferPairNames, engineTrioInPlay) {
     return new Set([...builtinDeferPairNames, ...(engineTrioInPlay ? MEMORY_ENGINE_TOOL_NAMES : [])]);
 }
 export function prepareDeferClassify(input) {
-    const { spec, deps, tools, toolFaceSnapshot, handsEnabled, fullShellReachable, promptProfile, model, mcp, a2a, sharedMemoryPairMounted, memoryEnginePairMounted, memoryRecallSegment, onceLedger, sessionId } = input;
+    const { spec, deps, roster, toolFaceSnapshot, handsEnabled, fullShellReachable, promptProfile, model, mcp, a2a, sharedMemoryPairMounted, memoryEnginePairMounted, memoryRecallSegment, onceLedger, sessionId } = input;
+    const tools = roster.tools;
     let memoryBlock = input.memoryBlock;
-    if (toolFaceSnapshot.exclude !== undefined && toolFaceSnapshot.exclude.length > 0) {
+    if (spec.excludeAllTools === true) {
+        roster.unmountWhere(() => true);
+    }
+    else if (toolFaceSnapshot.exclude !== undefined && toolFaceSnapshot.exclude.length > 0) {
         const excluded = new Set(toolFaceSnapshot.exclude);
-        for (let i = tools.length - 1; i >= 0; i--)
-            if (excluded.has(tools[i].name))
-                tools.splice(i, 1);
+        roster.unmountWhere((t) => excluded.has(t.name));
     }
     if (handsEnabled) {
         const fullShellOnRoster = tools.some((t) => t.name === "Bash" && getToolContract(t, "core").contractId === FULL_SHELL_CONTRACT_ID);
@@ -33,7 +36,7 @@ export function prepareDeferClassify(input) {
         for (let i = 0; i < tools.length; i++) {
             const t = tools[i];
             if (t.descriptionClassic !== undefined)
-                tools[i] = { ...t, description: t.descriptionClassic };
+                roster.replaceAt(i, { ...t, description: t.descriptionClassic });
         }
     }
     const userToolNames = (spec.tools ?? []).map((t) => t.name);
@@ -73,10 +76,7 @@ export function prepareDeferClassify(input) {
         const supportNameTaken = tools.some((t) => t.name === TOOL_SEARCH_NAME || (t.aliases ?? []).includes(TOOL_SEARCH_NAME));
         if (soleCause && supportNameTaken) {
             const retractNames = memoryGroupRetractionSet(builtinDeferPairNames, memoryEnginePair.length > 0);
-            for (let i = tools.length - 1; i >= 0; i--) {
-                if (retractNames.has(tools[i].name))
-                    tools.splice(i, 1);
-            }
+            roster.unmountWhere((t) => retractNames.has(t.name));
             if (sharedMemoryPair.length > 0) {
                 onceLedger.onError(new Error(`Shared memory tools ${SHARED_MEMORY_TOOL_NAMES.join("/")} were NOT mounted: mounting them would inject ` +
                     `the "${TOOL_SEARCH_NAME}" tool, whose name this task already declares — the pair mounts together or not at all.`), { phase: "config", sessionId, classification: "shared-memory-not-mounted" });

package/dist/core/runner/prepare-delegation-surface.d.ts

@@ -6,6 +6,7 @@ import type { CwdRef } from "../../tools/fs/index.js";
 import { type ToolResultStore } from "../tool-result-store.js";
 import type { RunnerDeps, TaskSpec, ToolEffect, ToolExecuteContext } from "../types.js";
 import type { PrepareResume, RunInternals, RunnerSelfSeat, ToolFaceSnapshot } from "./contracts.js";
+import { RosterBuilder } from "../tool-roster.js";
 export interface PrepareDelegationSurfaceInput {
     /** borrowed-readonly — the REBOUND spec. Read: `tools` (the shadow checks and the revival spawner's delegation-tool
      *  lookup), `oneShot` (the read/kill faces' completion promises), `retainBackgroundProcesses` (the Monitor receipt),
@@ -44,10 +45,10 @@ export interface PrepareDelegationSurfaceInput {
     /** borrowed-mutable — the lane's late-bound facts; the SendMessage mount hands the SAME object to its peer seats (identity is
      *  the contract: the wiring station fills `askEffective` later). Not written here. */
     peerLaneRefs: PeerLaneRefs;
-    /** borrowed-mutable — the run's shared roster (`Prepared.tools`, whose JSDoc carries the writer table). Writers here: the
-     *  eight mounts (TaskOutput, TaskStop, SendMessage, AgentTranscript, ListAgents, Monitor, the worktree pair, the offload
-     *  reader), every one a push. */
-    tools: AgentTool[];
+    /** borrowed-mutable — the run's roster builder (`Prepared.tools` is its read face; the writer table is on that field).
+     *  Writers here: the eight mounts (TaskOutput, TaskStop, SendMessage, AgentTranscript, ListAgents, Monitor, the worktree
+     *  pair, the offload reader), every one a `mount`. */
+    roster: RosterBuilder;
     /** borrowed-mutable — the effect collection (`Prepared.toolEffects`). Writers here: TaskOutput → read, TaskStop / SendMessage
      *  (built-in mount only) / Monitor / EnterWorktree / ExitWorktree → write. */
     toolEffects: Map<string, ToolEffect>;

package/dist/core/runner/prepare-delegation-surface.js

@@ -8,6 +8,7 @@ import { createTaskOutputTool, createTaskStopTool, defaultTaskRegistry } from ".
 import { createReadToolResultTool } from "../tool-result-store.js";
 import { emitTrace } from "../trace.js";
 import { deliverEngineNotice } from "../types.js";
+import { RosterBuilder } from "../tool-roster.js";
 function buildTier3ReviveSpawn(delegationForRevive, enrichSpecToolCtx) {
     if (delegationForRevive === undefined)
         return undefined;
@@ -29,21 +30,21 @@ function buildTier3ReviveSpawn(delegationForRevive, enrichSpecToolCtx) {
     };
 }
 export function prepareDelegationSurface(input) {
-    const { 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 } = input;
+    const { 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 } = input;
     let worktreeSessionRef;
     const delegationSurfaceActive = backgroundTaskToolsActive || workflowToolsActive;
     if (delegationSurfaceActive || internals?.parentNotify !== undefined || peerLaneActive) {
         if (delegationSurfaceActive) {
-            toolEffects.set("TaskOutput", "read");
-            toolEffects.set("TaskStop", "write");
-            tools.push(firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore, notificationWired: internals?.onTaskNotification !== undefined, oneShot: spec.oneShot, toolResultStore: offloadStore })), firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore })));
+            roster.mountAll([
+                firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore, notificationWired: internals?.onTaskNotification !== undefined, oneShot: spec.oneShot, toolResultStore: offloadStore })),
+                firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore })),
+            ], { source: "builtin", mountedBy: "delegation" });
         }
         if (runnerSelf && !(spec.tools ?? []).some((t) => t.name === SEND_MESSAGE_TOOL_NAME)) {
-            toolEffects.set(SEND_MESSAGE_TOOL_NAME, "write");
             axisExplicitNegatives.set(SEND_MESSAGE_TOOL_NAME, { ...axisExplicitNegatives.get(SEND_MESSAGE_TOOL_NAME), egress: false });
             const delegationForRevive = (spec.tools ?? []).find((t) => t.agentListing !== undefined);
             const reviveSpawn = deps.backgroundAgentStore !== undefined && deps.mailboxStore !== undefined ? buildTier3ReviveSpawn(delegationForRevive, enrichSpecToolCtx) : undefined;
-            tools.push(firstPartyOffload(createSendMessageTool({
+            roster.mount(firstPartyOffload(createSendMessageTool({
                 runner: runnerSelf,
                 registry: defaultTaskRegistry,
                 ...(subagentRetain ? { retain: subagentRetain } : {}),
@@ -76,9 +77,9 @@ export function prepareDelegationSurface(input) {
                     message: `delegation transcript integrity: agent ${handle}'s durable row binds a transcript session the session store attests is gone — the declared transcript durability is being contradicted (check the session store wiring/retention)`,
                     detail: { handle, ...(scope !== undefined ? { scope } : {}) },
                 }),
-            })));
+            })), { source: "builtin", mountedBy: delegationSurfaceActive ? "delegation" : internals?.parentNotify !== undefined ? "hostInternals" : "peerLane" });
             if (delegationSurfaceActive && !(spec.tools ?? []).some((t) => t.name === AGENT_TRANSCRIPT_TOOL_NAME)) {
-                tools.push(firstPartyOffload(createAgentTranscriptTool({
+                roster.mount(firstPartyOffload(createAgentTranscriptTool({
                     runner: runnerSelf,
                     registry: defaultTaskRegistry,
                     agentStore: deps.backgroundAgentStore,
@@ -91,17 +92,16 @@ export function prepareDelegationSurface(input) {
                         message: `delegation transcript integrity: agent ${handle}'s durable row binds a transcript session the session store attests is gone — the declared transcript durability is being contradicted (check the session store wiring/retention)`,
                         detail: { handle, ...(scope !== undefined ? { scope } : {}) },
                     }),
-                })));
+                })), { source: "builtin", mountedBy: "delegation" });
             }
         }
     }
     const listAgents = peerLaneActive && peerSendMessageBuiltIn && listAgentsMountable({ exclude: toolFaceSnapshot.exclude, specTools: spec.tools ?? [] }) ? mountListAgents({ peerDirectory: deps.peerDirectory, sessionId, scope: taskScope, hostTaskId, ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}), ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}), registry: defaultTaskRegistry, ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}), specTools: spec.tools ?? [], toolEffects }) : undefined;
     if (listAgents !== undefined)
-        tools.push(firstPartyOffload(listAgents));
+        roster.mount(firstPartyOffload(listAgents), { source: "builtin", mountedBy: "peerLane" });
     if (backgroundTaskToolsActive) {
-        toolEffects.set("Monitor", "write");
         envHandToolNames.add("Monitor");
-        tools.push(firstPartyOffload(createMonitorTool(executionEnv, {
+        roster.mount(firstPartyOffload(createMonitorTool(executionEnv, {
             registry: defaultTaskRegistry,
             owner: hostTaskId,
             scope: taskScope,
@@ -110,11 +110,9 @@ export function prepareDelegationSurface(input) {
             ...(handsCwdRef !== undefined ? { cwdRef: handsCwdRef } : {}),
             ...(offloadStore !== undefined ? { toolResultStore: offloadStore } : {}),
             ...(spec.retainBackgroundProcesses === true ? { retainBackgroundProcesses: true } : {}),
-        })));
+        })), { source: "builtin", mountedBy: "backgroundTasks" });
     }
     if (handsCwdRef !== undefined) {
-        toolEffects.set("EnterWorktree", "write");
-        toolEffects.set("ExitWorktree", "write");
         worktreeSessionRef = {
             ...(resume?.seed.activeWorktree
                 ? {
@@ -136,9 +134,9 @@ export function prepareDelegationSurface(input) {
         };
         if (workspaceStateSettle !== undefined)
             workspaceStateSettle.restoredWorktreeDir = worktreeSessionRef.current?.worktreeDir;
-        tools.push(...createWorktreeTools(executionEnv, { repoRoot: taskRootFinal, cwdRef: handsCwdRef, session: worktreeSessionRef }).map((t) => (envHandToolNames.add(t.name), firstPartyOffload(t))));
+        roster.mountAll(createWorktreeTools(executionEnv, { repoRoot: taskRootFinal, cwdRef: handsCwdRef, session: worktreeSessionRef }).map((t) => (envHandToolNames.add(t.name), firstPartyOffload(t))), { source: "builtin", mountedBy: "hands" });
     }
     if (offloadStore)
-        tools.push(createReadToolResultTool(offloadStore));
+        roster.mount(createReadToolResultTool(offloadStore), { source: "builtin", mountedBy: "optional" });
     return { delegationSurfaceActive, worktreeSessionRef };
 }

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,

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 ` +