@sema-agent/core 7.7.0 → 7.9.0

package/dist/core/runner/compaction-call-options.d.ts

@@ -15,7 +15,7 @@ import type { Prepared } from "./contracts.js";
  * end-of-task lane's deliberate ABSENCE of `signal`) is a legitimate per-lane difference and stays at
  * the call site, where its reason is written down.
  *
- * Every export is a free function: the turn-boundary lane assembles its call inside `makeTurnBoundary`
+ * Every export is a free function: the turn-boundary lane assembles its call inside `createTurnBoundary`
  * (a module-level function with no `this`), so a method would not be reachable from all three sites.
  * Nothing here reads or writes runner state — pure assembly over `spec` + `Prepared`.
  */

package/dist/core/runner/contracts.d.ts

@@ -315,6 +315,14 @@ export interface Prepared {
     /** design/99 §E6 — the DENY-NARROWING layers (session rules + skill scope, deny-only). Re-checked on RESUME
      *  before an approved pending tool executes, so a rule tightened during the suspend still applies. */
     denyNarrowingPolicy?: ToolPolicy;
+    /** #632 — the person's own persisted-rule lane (deny/ask rows), re-adjudicated on RESUME at the same
+     *  station as the deny-narrowing layers: a deny row added while the call was parked vetoes the execution
+     *  (`deniedBy: "persisted_rule"`); an ask row or an unreadable store fails closed the same way (the approval
+     *  answered a question the person has since asked to be asked again — re-issue and re-approve). Absent when
+     *  no rule store is wired. */
+    persistedRuleLane?: {
+        adjudicate: (req: ToolCallRequest) => Promise<import("../hooks.js").PersistedRuleAnswer>;
+    };
     /** RB-63: the deployment's own caller policy, re-checked on a durable resume ONLY when the approver
      *  rewrote the pending call's args (see the composition site for why the edit case is special). */
     basePolicyForResumeEdit?: ToolPolicy;
@@ -718,7 +726,10 @@ export interface Prepared {
      *  the human already adjudicated it). Same wrapping (offload + ctx) the harness runs with.
      *
      *  ONE array, mutated in place; identity is the contract (every closure that resolves a name at run time
-     *  reads this exact array). WRITER TABLE (design/238 R-3) — the only stations that write it, in prepare order:
+     *  reads this exact array). Since design/388 the array is PRIVATE to the `RosterBuilder` (tool-roster.ts) —
+     *  every station below writes through its verbs (`mount` / `mountAll` / `unmountWhere` / `replaceAt` /
+     *  `replaceDomain`) and this field is the builder's read face. WRITER TABLE (design/238 R-3) — the only
+     *  stations that write it, in prepare order:
      *   · caps-and-workflow — MINTS it (`spec.tools` through the ctx wrap + the large-result wrapper), then pushes
      *     ReportBlocked (enableBlockedReport ≠ false), ReportFindings (no caller tool of that name/alias),
      *     ExitPlanMode + EnterPlanMode (enablePlanMode ∧ the plan-review face), Workflow (self-orchestration active
@@ -740,7 +751,28 @@ export interface Prepared {
      *     memory session or a recorder channel); the refresh seam re-runs the same pass through `contentOriginWrapRef`
      *     after a re-splice (identity-tracked, so a wrapper is never wrapped again).
      *  tool-disclosure and listings only READ it (`harnessTools` is a derived list; placeholders never enter here). */
-    tools: AgentTool[];
+    tools: readonly AgentTool[];
+    /**
+     * design/388 §2.5 — this leg's minted TOOL ROSTER (the same object `wiringManifest.tools` carries):
+     * one row per mounted instance in wire order. Minted ONCE at the prompt-assembly station (the same
+     * pass that projects the prompt manifest's tool rows, so the two agree by construction); the park
+     * station reads the gated call's identity off it, the exemption probe hands it to the host.
+     */
+    toolRoster: import("../tool-roster.js").ToolRoster;
+    /**
+     * design/388 §2.5 — the run-time delta seat: every roster change after prepare (the RefreshMcpTools
+     * seam) re-mints the roster here and publishes a `ToolRosterDelta`. The run loop subscribes at the
+     * point it emits `wiring_manifest` and forwards each delta as a `tool_roster_delta` event; until it
+     * does, deltas are buffered in order.
+     */
+    toolRosterDeltas: import("../tool-roster.js").ToolRosterDeltaSeat;
+    /**
+     * design/388 L4 — the leg's `tool_end.structured` projector: the engine card set ∪ the caller rows' declared
+     * `renderHints.resultCards`; an undeclared `details.type` is dropped and announced ONCE per leg
+     * (`config.tool_card_undeclared`). The ONE card port: every tool_end body projection (the live loop, the resumed
+     * batch, the reconcile-recovered orphan) takes it as a parameter; no module-level card set exists to fall back to.
+     */
+    structuredProjector: (result: unknown) => unknown;
     /** Name→effect map for every tool this task can call (design/44 §3). Used by the abort-path orphan
      *  reconcile (design/64 §9) to make interrupted tool_results effect-aware (read/idempotent = safe to
      *  repeat; write/unknown = outcome unknown). Unknown names default to `write` (conservative). */
@@ -1985,7 +2017,7 @@ export interface ParkAsk {
  * Grouped by lifecycle semantics per the B15 pre-recon partition. Function members start as inert
  * placeholders and are assigned at their ORIGINAL declaration sites (the original code could not
  * call them earlier either — TDZ proved it). Not on the npm face; this extraction is what enabled
- * makeTurnBoundary / makeHarnessHandlers (三期, both in runtask.ts).
+ * createTurnBoundary / createHarnessHandlers (三期, both in runtask.ts).
  */
 export interface RunState {
     telemetry: {
@@ -2331,6 +2363,17 @@ export interface HarnessHandlersDeps {
  * Signatures are spelled out (not `Pick<Runner, …>`), because naming the class from here would be the
  * very edge this seat exists to remove.
  */
+/**
+ * The Runner's deployment deps as a LIVE read for the lanes that read them after an await (the resume ladder's
+ * rungs). `Runner.deps` is not a constant: `swapModels` replaces the object, so a lane handed the object at its
+ * call would read a stale catalog — and a stale anything — where the one-function ladder read `this.deps.x` at the
+ * instant of the read. The seat is the Runner's own view (a getter over the private field), so `runner.deps.x`
+ * in a lane is exactly `this.deps.x` in the method it came from.
+ */
+export interface RunnerDepsSeat {
+    /** The deps object the Runner holds RIGHT NOW — never cache it across an await. */
+    readonly deps: RunnerDeps;
+}
 export interface RunnerSelfSeat {
     /** The session store this Runner was constructed over — the delegation tools acquire / release / fork through it. */
     readonly sessions: SessionStore;

package/dist/core/runner/permission-rule-lanes.d.ts

@@ -9,13 +9,15 @@
  *
  * ## One read per adjudicated call
  *
- * The gate consults the org lane (`orgRules.adjudicate`) on every decision and the personal lane
- * (`persistedRules.admits`) only on a surviving ask, in that order. The org lane's read is therefore
+ * The gate consults the org lane (`orgRules.adjudicate`) and then the personal lane
+ * (`persistedRules.adjudicate`) on every decision, in that order (the personal lane's deny/ask rows must
+ * be able to tighten an allow, so it can no longer wait for a surviving ask). The org lane's read is
  * HANDED to the personal lane by `toolCallId` (taken once, then forgotten), so a governed deployment pays
  * one store query — one org-source fetch — per call, exactly as it did with two seams. An entry the
- * personal lane never claims (an allow, a deny) is evicted first-in-first-out past a small bound; an
- * evicted or never-handed entry simply costs the personal lane its own read. The handoff is a cost
- * device, not a semantic one: both lanes judge one snapshot, which is the honest shape for one decision.
+ * personal lane never claims (a call on a tool it does not speak for) is evicted first-in-first-out past
+ * a small bound; an evicted or never-handed entry simply costs the personal lane its own read. The
+ * handoff is a cost device, not a semantic one: both lanes judge one snapshot, which is the honest shape
+ * for one decision.
  *
  * ## Where the lanes do NOT go
  *
@@ -25,14 +27,12 @@
  */
 import type { AskRuleEvidence, ToolCallRequest } from "../tool-policy.js";
 import { persistedRuleMandateOf, type OrgGateVerdict, type PersistedRuleAnswer, type PersistedRuleHit } from "../hooks.js";
-import type { PersistedAllowRule, RuleOffer, SegmentCoverage } from "../permission-rule-model.js";
+import type { PersistedRule, PersistedRuleVerdict, RuleOffer, SegmentCoverage } from "../permission-rule-model.js";
 import { type OrgRuleResolution } from "../permission-rule-org.js";
 import type { PermissionRuleStoreProvider } from "../permission-rule-provider.js";
-/** The one SHELL tool the persisted-rule lane speaks for. */
+/** The one SHELL tool the persisted-rule lane's COMMAND grammar speaks for (the rule-offer face mints for
+ *  it alone). The PATH grammar's tools are derived from the catalog (`ruleToolGrammarOf`). */
 export declare const PERSISTED_RULE_TOOL = "Bash";
-/** design/382 §2.5 — the READ tool the directory-rule family speaks for (its one other admission
- *  point, the cd-segment notch, lives inside the model's own conjunction/coverage arms). */
-export declare const DIRECTORY_RULE_TOOL = "Read";
 /**
  * design/252 G-2 — the evidence an INHERITED-lane ask carries.
  *
@@ -67,28 +67,35 @@ export declare function orgRevisionEvidenceOf(resolution: OrgRuleResolution, onD
     revision?: number;
 };
 /**
- * design/252 G-2 / design/375 — project the admitting COVERAGE SET onto the gate's rule-lane answer:
- * each member's canonical text plus its own add DOTS. A single rule admitting the whole command is a
- * one-element set; a compound admitted by the per-segment conjunction is the set of covering rules in
- * segment order (the model's own reporting-order contract).
+ * design/252 G-2 / design/375 — project the model's verdict onto the gate's rule-lane answer: the
+ * behavior that spoke, and each member's canonical text plus its own add DOTS. For an allow the set is
+ * the admitting COVERAGE SET (a single rule admitting the whole command is a one-element set; a compound
+ * admitted by the per-segment conjunction is the set of covering rules in segment order — the model's
+ * own reporting-order contract); for a deny/ask it is the one reaching rule the precedence walk chose.
  *
  * `adds` on a listed rule are the LIVE adds — the store's read already dropped tombstoned dots — so
- * this is the set that actually admitted the call, which is the identity a later audit reconciles a
+ * this is the set that actually decided the call, which is the identity a later audit reconciles a
  * shadowed ask against. The sanitized display text deliberately is not one. Copied rather than
  * aliased: the evidence must not change under a store that reuses its row objects.
  */
-export declare function persistedRuleHitOf(admitting: readonly PersistedAllowRule[] | undefined): PersistedRuleHit | undefined;
+export declare function persistedRuleHitOf(verdict: PersistedRuleVerdict | undefined): PersistedRuleHit | undefined;
 /**
- * design/382 §2.5-1 — the persisted-rule lane's READ arm: the call's target path in the SAME lexical
- * identity the rule family is defined over — absolute as spelled, relative resolved against the LIVE
- * tracked working directory (the very base the Read tool itself resolves against; task root when no
- * tracker moved), then normalized lexically, zero IO. One admission predicate
- * ({@link directoryRuleAdmits}), the one eligibility predicate for scope/liveness, first table-order hit
- * reported. Everything this lane does NOT do is structural: it clears ASKS only — the read fences
- * (workspace containment, the sensitive-read deny face) judge inside the tool exactly as they would with
- * no rule anywhere, and an unresolvable path is simply no admission (fail toward asking).
+ * design/382 §2.5-1, widened to every path-targeting tool — the persisted-rule lane's PATH arm: the call's
+ * target path in the SAME lexical identity the rule family is defined over — absolute as spelled, relative
+ * resolved against the LIVE tracked working directory (the very base the file tools themselves resolve
+ * against; task root when no tracker moved), then normalized lexically, zero IO.
+ *
+ * TWO readings of the call's path slot, one per direction (design/388 B6/B17): the tightening arms judge
+ * the PROTECTIVE target (the object face's declaration, the catalog's for the name as the floor — reading
+ * the catalog for an undeclared same-name tool can only tighten a deny); the allow arm judges the DECLARED
+ * target (the face's OWN declaration only — a same-name tool that declares no path target is unconfirmable
+ * and no grant admits it). The precedence walk, the admission predicates and the Read-only allow are the
+ * model's (`adjudicatePersistedPathRules`). An ALLOW here clears ASKS only — the read fences (workspace
+ * containment, the sensitive-read deny face) judge inside the tool exactly as they would with no rule
+ * anywhere — and an unresolvable path is simply no verdict (fail toward asking on the allow side, no
+ * refusal on the tightening side: a rule about a path speaks about no other shape).
  */
-export declare function directoryRuleLaneAnswer(table: readonly PersistedAllowRule[], args: unknown, ctx: {
+export declare function pathRuleLaneAnswer(table: readonly PersistedRule[], req: Pick<ToolCallRequest, "toolName" | "args" | "face">, ctx: {
     root: string | undefined;
     sessionId: string | undefined;
     liveCwd: string | undefined;
@@ -97,7 +104,7 @@ export declare function directoryRuleLaneAnswer(table: readonly PersistedAllowRu
  *  a deployment without one keeps a decision path byte-identical to a build without the feature. */
 export interface PermissionRuleLanes {
     personal: {
-        admits: (req: ToolCallRequest) => Promise<PersistedRuleAnswer>;
+        adjudicate: (req: ToolCallRequest) => Promise<PersistedRuleAnswer>;
     } | undefined;
     org: {
         adjudicate: (req: ToolCallRequest) => Promise<OrgGateVerdict>;

package/dist/core/runner/permission-rule-lanes.js

@@ -1,8 +1,8 @@
 import { persistedRuleMandateOf } from "../hooks.js";
-import { directoryRuleAdmits, eligiblePersisted, findAdmittingRule, lexicalNormalAbsolutePathOf, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
+import { adjudicatePersistedPathRules, adjudicatePersistedRules, lexicalNormalAbsolutePathOf, ruleToolGrammarOf, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
+import { declaredPathTargetOf, pathTargetValue, protectivePathTargetOf } from "../tool-registry.js";
 import { orgRuleVerdictFor } from "../permission-rule-org.js";
 export const PERSISTED_RULE_TOOL = "Bash";
-export const DIRECTORY_RULE_TOOL = "Read";
 const HANDOFF_BOUND = 256;
 export function inheritedAskRuleEvidence(provider) {
     const org = provider?.partitions.org === true ? "not_adjudicated" : "not_wired";
@@ -19,21 +19,26 @@ export function orgRevisionEvidenceOf(resolution, onDefect) {
         `the adjudication stands, but the ask carries no revision evidence for this call`);
     return {};
 }
-export function persistedRuleHitOf(admitting) {
-    return admitting === undefined
+export function persistedRuleHitOf(verdict) {
+    return verdict === undefined
         ? undefined
-        : { rules: admitting.map((r) => ({ rule: r.rule, dots: r.adds.map((a) => ({ actor: a.dot.actor, counter: a.dot.counter })) })) };
+        : { behavior: verdict.behavior, rules: verdict.rules.map((r) => ({ rule: r.rule, dots: r.adds.map((a) => ({ actor: a.dot.actor, counter: a.dot.counter })) })) };
 }
-export function directoryRuleLaneAnswer(table, args, ctx) {
-    const filePath = args?.file_path;
-    if (typeof filePath !== "string" || filePath === "")
-        return undefined;
-    const spelled = filePath.startsWith("/") ? filePath : `${(ctx.liveCwd ?? ctx.root ?? "").replace(/\/+$/, "")}/${filePath}`;
-    const target = lexicalNormalAbsolutePathOf(spelled);
-    if (target === undefined)
+export function pathRuleLaneAnswer(table, req, ctx) {
+    const base = (ctx.liveCwd ?? ctx.root ?? "").replace(/\/+$/, "");
+    const resolve = (pt) => {
+        if (pt === undefined)
+            return undefined;
+        const spelled = pathTargetValue(req.args, pt);
+        if (spelled === undefined)
+            return undefined;
+        return lexicalNormalAbsolutePathOf(spelled.startsWith("/") ? spelled : `${base}/${spelled}`);
+    };
+    const tighten = resolve(protectivePathTargetOf(req));
+    const allow = resolve(declaredPathTargetOf(req));
+    if (tighten === undefined && allow === undefined)
         return undefined;
-    const hit = table.find((r) => eligiblePersisted(r, { tool: DIRECTORY_RULE_TOOL, cwd: ctx.root, sessionId: ctx.sessionId }) && directoryRuleAdmits(r, target));
-    return hit !== undefined ? persistedRuleHitOf([hit]) : undefined;
+    return persistedRuleHitOf(adjudicatePersistedPathRules(table, { tool: req.toolName, cwd: ctx.root, sessionId: ctx.sessionId }, { ...(tighten !== undefined ? { tighten } : {}), ...(allow !== undefined ? { allow } : {}) }, { ...(ctx.root !== undefined ? { root: ctx.root } : {}), ...(ctx.liveCwd !== undefined ? { cwd: ctx.liveCwd } : {}) }));
 }
 export function createPermissionRuleLanes(cfg) {
     const provider = cfg.provider;
@@ -103,10 +108,11 @@ export function createPermissionRuleLanes(cfg) {
         : undefined;
     const personal = provider.partitions.durable
         ? {
-            admits: async (req) => {
+            adjudicate: async (req) => {
                 if (anonymous && !cfg.localOwnerDeclared)
                     return undefined;
-                if (req.toolName !== PERSISTED_RULE_TOOL && req.toolName !== DIRECTORY_RULE_TOOL)
+                const grammar = ruleToolGrammarOf(req.toolName);
+                if (grammar === undefined)
                     return undefined;
                 let view;
                 try {
@@ -122,16 +128,16 @@ export function createPermissionRuleLanes(cfg) {
                 }
                 const table = view.rules;
                 const liveCwd = cfg.liveCwd();
-                if (req.toolName === DIRECTORY_RULE_TOOL) {
-                    return directoryRuleLaneAnswer(table, req.args, { root: cfg.root, sessionId: cfg.sessionId, liveCwd });
+                if (grammar === "path") {
+                    return pathRuleLaneAnswer(table, req, { root: cfg.root, sessionId: cfg.sessionId, liveCwd });
                 }
                 const command = req.args?.command;
                 if (typeof command !== "string")
                     return undefined;
                 const execCwd = liveCwd !== undefined ? { execCwd: liveCwd } : {};
-                const admitting = findAdmittingRule(table, { tool: req.toolName, command, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
-                if (admitting !== undefined)
-                    return persistedRuleHitOf(admitting);
+                const verdict = adjudicatePersistedRules(table, { tool: req.toolName, command, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
+                if (verdict !== undefined)
+                    return persistedRuleHitOf(verdict);
                 const coverage = segmentCoverageOf(command, { persisted: table }, { tool: req.toolName, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
                 return coverage !== undefined ? { segmentCoverage: coverage } : undefined;
             },

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,7 +2,7 @@ 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";
@@ -20,6 +20,7 @@ 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,
@@ -65,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);
         }
@@ -73,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" });
             }
         }
     }
@@ -210,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,
@@ -266,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 };
 }