@sema-agent/core 7.31.0 → 7.32.0

package/dist/core/tool-policy.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { brandPolicyAskClass } from "./ask-class.js";
+import { ownReadRootCandidate, readRootGrantSeat } from "./read-root-grant-screen.js";
 import { decidersNote, settledByPerson } from "./gate-outcome.js";
 import { sanitizeAutoModeArmingRecipe } from "./auto-mode-arming.js";
 import { join, normalize as normalizePath, sep } from "node:path";
@@ -1160,11 +1161,13 @@ function readApproverOutcomeObject(ok, toolName, editLane) {
     let allowed;
     let suppliedEdit;
     let suppliedApprover;
+    let grant;
     try {
         supplied = ok.settledBy;
         allowed = ok.allow;
         suppliedEdit = ok.updatedInput;
         suppliedApprover = ok.approver;
+        grant = ok.readRootGrant;
     }
     catch (err) {
         return refused(`the approver's outcome for "${toolName}" could not be read (${describeThrown(err)}) — denied fail-closed`, settledByNobody("approver_contract"));
@@ -1182,6 +1185,9 @@ function readApproverOutcomeObject(ok, toolName, editLane) {
     if (attribution.defect !== undefined) {
         return refused(`the approver for "${toolName}" reported an attribution this seam refuses: ${attribution.defect}; denied fail-closed`, settledByNobody("approver_contract"));
     }
+    if (editLane === "none" && grant !== undefined) {
+        return refused(`the approver for "${toolName}" attached a readRootGrant on a seat that offers no directory — denied fail-closed (a grant answers an approval card's readRootCandidate)`, settledByNobody("approver_contract"));
+    }
     if (settledWord !== "human" && allowed === true) {
         return refused(`the approver for "${toolName}" returned an allow settled by "${settledWord}" — only a person approves, and that word ` +
             `names a wait that ended with nobody judging: it cannot be what approved a call; denied fail-closed ` +
@@ -1205,6 +1211,7 @@ function readApproverOutcomeObject(ok, toolName, editLane) {
             kind: "deny",
             word: settledWord,
             note,
+            grant,
             settlement: settledWord === "timeout"
                 ? { kind: "approval_window_expired", who: { party: "host" }, when: Date.now() }
                 : settledWord === "policy"
@@ -1213,7 +1220,7 @@ function readApproverOutcomeObject(ok, toolName, editLane) {
         };
     }
     if (suppliedEdit === undefined)
-        return { kind: "allow", edit: undefined, settlement: settledByPerson("human_allowed", attribution.approver) };
+        return { kind: "allow", edit: undefined, settlement: settledByPerson("human_allowed", attribution.approver), grant };
     if (editLane === "none") {
         return refused(`the approver for "${toolName}" attached an edit (updatedInput) on a seat that has no lane to adjudicate one — ` +
             `this seat's answer is the deployment POLICY's verdict, and an edit arriving through it would execute without the ` +
@@ -1224,7 +1231,7 @@ function readApproverOutcomeObject(ok, toolName, editLane) {
     if (!edit.ok) {
         return refused(`the approved edit for "${toolName}" is not safely clonable (${edit.reason}) — denied fail-closed`, settledByNobody("presentation_failed"));
     }
-    return { kind: "allow", edit: { value: edit.value }, settlement: settledByPerson("human_allowed", attribution.approver) };
+    return { kind: "allow", edit: { value: edit.value }, settlement: settledByPerson("human_allowed", attribution.approver), grant };
 }
 async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
     if (onAsk === "allow") {
@@ -1260,6 +1267,7 @@ async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
             settlement: settledByNobody("presentation_failed"),
         };
     }
+    const offered = ownReadRootCandidate(req.readRootCandidate);
     let ok;
     try {
         const approverView = tryCloneArgs(presented.value);
@@ -1278,6 +1286,7 @@ async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
             boundInputHash: boundInputHashOf(presented.value),
             args: approverView.value,
             ...(bidi ? { hasBidiControls: true } : {}),
+            ...(offered !== undefined ? { readRootCandidate: { ...offered } } : {}),
         }, signal));
         const windowMs = req.denialLimitFallback !== undefined && req.denialLimitFallback.autoDenyAfterMs > 0 ? req.denialLimitFallback.autoDenyAfterMs : undefined;
         const raced = await withTimeout(raceAskWaitAgainstSignal(wait, signal), windowMs, () => DEADLINE_ELAPSED);
@@ -1324,6 +1333,7 @@ async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
         const reading = readApproverOutcomeObject(ok, req.toolName, "readjudicated");
         if (reading.kind === "refused")
             return { action: "deny", message: reading.message, decisionReason: "mode", settlement: reading.settlement };
+        const grantSeat = readRootGrantSeat(reading.grant, offered, reading.kind === "allow");
         if (reading.kind === "deny") {
             return {
                 action: "deny",
@@ -1334,11 +1344,12 @@ async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
                         : humanRefusalMessage(req, reading.note),
                 decisionReason: "mode",
                 settlement: reading.settlement,
+                ...grantSeat,
             };
         }
         if (reading.edit === undefined)
-            return { action: "allow", decisionReason: "mode", presentedInput: presented.value, settlement: reading.settlement };
-        return { action: "allow", updatedInput: reading.edit.value, decisionReason: "mode", settlement: reading.settlement };
+            return { action: "allow", decisionReason: "mode", presentedInput: presented.value, settlement: reading.settlement, ...grantSeat };
+        return { action: "allow", updatedInput: reading.edit.value, decisionReason: "mode", settlement: reading.settlement, ...grantSeat };
     }
     const okRaw = ok;
     if (okRaw === true)

package/dist/core/tool-spec.d.ts

@@ -952,6 +952,8 @@ export interface ToolExecuteContext {
      * (only `true` travels there). Undefined when the tool runs outside a Runner task.
      */
     oneShot?: boolean;
+    /** Does this run mount THIS instance in `spec.tools` as handed, pre-gate (Runner-filled)? The parent bound on `SubagentToolOptions.inheritedTools`. */
+    mountsCallerTool?: (tool: ToolSpec) => boolean;
     /**  — the parent's tool-face controls ({@link TaskSpec.excludeTools} /
      *  {@link TaskSpec.deferTools}), inherited down the delegation tree like `principal` (Runner-filled,
      *  read-only): a scenario-wide roster must not be escapable by delegating to a child that remounts

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -2,7 +2,7 @@ import { type ExecResult, type ExecutionEnv, ExecutionError, type ExecutionEnvEx
 import { type SecretEnvFinding } from "../../core/secret-env.js";
 import type { EngineNotice } from "../../core/engine-notice.js";
 import type { SymlinkChain } from "../harness/types.js";
-import type { BackgroundShellCapability, BackgroundShellId, BackgroundPoll, BackgroundSpawnOptions } from "../../core/background-shell.js";
+import type { BackgroundHardKillOutcome, BackgroundShellCapability, BackgroundShellId, BackgroundPoll, BackgroundSpawnOptions } from "../../core/background-shell.js";
 import { BackgroundShellError } from "../../core/background-shell.js";
 import type { SchedulerCapability, ScheduledIntent, SchedulerContext, ScheduledTaskId, ScheduledTaskSummary } from "../../core/scheduler.js";
 import { SchedulerError } from "../../core/scheduler.js";
@@ -125,8 +125,9 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
          * design/128 T1-1 — deliver-a-living-service mode (default false). When true, background processes
          * OUTLIVE the run: `disposeBackgroundShells()` becomes a no-op (the runner's every-exit-path dispose
          * included) and background stdio is spooled to env-owned temp files (0600, `wx`, unpredictable path)
-         * so the child never dies of EPIPE after the host exits. DEPLOYMENT-declared at env construction —
-         * no TaskSpec/model-facing switch exists. The 2h bg-timeout reaper and `killBackground` still work
+         * so the child never dies of EPIPE after the host exits. DEPLOYMENT-declared at env construction (the
+         * env lane; `TaskSpec.retainBackgroundProcesses` is the task lane, without this spooling guarantee on
+         * every platform — docs/background-process-lifetime.md). The 2h bg-timeout reaper and `killBackground` still work
          * while the host lives; after host exit, cleanup is the deployment's responsibility (e.g. the TB
          * container teardown). v1 covers processes spawned via `execBackground` only (a detach-adopted
          * foreground exec keeps pipe stdio — best-effort survival). Incompatible with durable-suspend
@@ -221,6 +222,15 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
     }, BackgroundShellError>>;
     pollBackground(shellId: BackgroundShellId): Promise<Result<BackgroundPoll, BackgroundShellError>>;
     killBackground(shellId: BackgroundShellId): Promise<Result<void, BackgroundShellError>>;
+    /** The synchronous hard kill seat ({@link BackgroundShellCapability.killBackgroundNow}). Reads process truth,
+     *  never `entry.status` (other stops flip it before their attempt, which can fail or wait on a timer). Once
+     *  node has observed the leader's exit its pid may name a stranger: `already_gone`, nothing signalled. Before
+     *  that the leader is still our child (live or an unreaped zombie), so ONE `kill(-pid, SIGKILL)` reaches its
+     *  group and nothing else — no descendant snapshot (a process that left the group is outside this seat).
+     *  win32 has no synchronous hard kill: no process groups, and the tree kill's MSYS group discovery needs its
+     *  deferred step, so this seat answers `no_pgid` and the caller's ordinary kill (the ladder) does the work.
+     *  Only a landed signal sets the latch; a refused one is `no_pgid`. */
+    killBackgroundNow(shellId: BackgroundShellId): BackgroundHardKillOutcome;
     /** design/128 T1-1: incrementally read a retained shell's spool files into the in-memory tails, so
      *  pollBackground serves the same cursor semantics whether stdio came over pipes or spool files.
      *  Bounded single read per stream per poll (the tail keeps only its rolling window anyway).

package/dist/engine/execution-env/node-execution-env.js

@@ -1339,6 +1339,32 @@ export class NodeExecutionEnv {
         }
         return ok(undefined);
     }
+    killBackgroundNow(shellId) {
+        const entry = this.bgShells.get(shellId);
+        if (!entry || entry.hardKilled)
+            return "already_gone";
+        const child = entry.child;
+        if (child.exitCode !== null || child.signalCode !== null)
+            return "already_gone";
+        const pid = child.pid;
+        if (pid === undefined || pid <= 0)
+            return "no_pgid";
+        if (process.platform === "win32")
+            return "no_pgid";
+        shutdownDebug("killBackgroundNow", { shellId, pid });
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch (e) {
+            return e.code === "ESRCH" ? "already_gone" : "no_pgid";
+        }
+        entry.hardKilled = true;
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        if (entry.status === "running")
+            entry.status = "killed";
+        return "killed";
+    }
     syncSpool(entry) {
         const spool = entry.spool;
         if (!spool)

package/dist/index.d.ts

@@ -158,7 +158,7 @@ export { probeParkRoundTrip, durableParkGapOf, durableParkGapFor, PARK_SELFCHECK
 export { type StoreDurability } from "./core/checkpoint-store.js";
 export { type StoreFidelity } from "./core/checkpoint-store.js";
 export { projectHumanInput, buildHumanInputEvent, type HumanInputSource, type HumanInputFrame, type HumanInputEvent, type HumanInputDelivery, } from "./core/human-input-projection.js";
-export { TaskRegistry, defaultTaskRegistry, createTaskOutputTool, createTaskStopTool, type SemaTaskType, type SemaTaskStatus, type SemaTaskHandle, type ParkedClaimTicket, type TaskAccess, type UnifiedTaskOutput, type TaskRetrievalStatus, type StopSource, type RegisterMonitorInput, type MonitorTimers, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccessWorkflowRun, DURABLE_AGENT_HANDLE_RE, } from "./core/task-registry.js";
+export { TaskRegistry, defaultTaskRegistry, createTaskOutputTool, createTaskStopTool, type SemaTaskType, type SemaTaskStatus, type SemaTaskHandle, type ParkedClaimTicket, type TaskAccess, type UnifiedTaskOutput, type TaskRetrievalStatus, type StopSource, type RegisterMonitorInput, type MonitorTimers, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccessWorkflowRun, DURABLE_AGENT_HANDLE_RE, type BackgroundShellHardKillReceipt, } from "./core/task-registry.js";
 export { InMemoryMailboxStore, type MailboxStore, type MailboxMessage, type MailboxLease, MailboxStoreError, type MailboxStoreErrorCode, MAILBOX_TOMBSTONED_RECIPIENT_CODE, type MailboxAppendMessage, type MailboxPeerMeta, type MailboxPeerFromMode, type MailboxPeerRecordKind, type MailboxPeerNoticeMeta, type MailboxPeerNoticeState, MAILBOX_PEER_NOTICE_STATES, MAILBOX_PEER_FROM_MODES, MAILBOX_PEER_RECORD_KINDS, MAILBOX_INVALID_PEER_META_CODE, MAILBOX_CROSS_PROCESS_UNSAFE_CODE, readMailboxPeerMeta, mailboxCrossProcessMountVerdict, type MailboxCrossProcessVerdict, type MailboxAckResult, } from "./core/mailbox-store.js";
 export { FileMailboxStore, type FileMailboxStoreOptions } from "./stores/file/mailbox-store.js";
 export { createFileTaskListStore } from "./stores/file/task-list-store.js";
@@ -172,7 +172,7 @@ export { createWorktreeTools, type WorktreeToolsOptions, type ActiveWorktreeSess
 export { sharpImageResizer, type McpImageResizer } from "./core/image-downsample.js";
 export { createImageDownsampler, sharpImageDownsampler, MCP_IMAGE_MAX_BASE64, IMAGE_TARGET_RAW_SIZE, type ImageDownsampler, type ImageDimensions, } from "./core/image-downsample.js";
 export { hasBackgroundShell, BackgroundShellError } from "./core/background-shell.js";
-export type { BackgroundShellCapability, BackgroundShellId, BackgroundShellStatus, BackgroundShellErrorCode, BackgroundSpawnOptions, BackgroundPoll, } from "./core/background-shell.js";
+export type { BackgroundShellCapability, BackgroundShellId, BackgroundShellStatus, BackgroundShellErrorCode, BackgroundSpawnOptions, BackgroundPoll, BackgroundHardKillOutcome, } from "./core/background-shell.js";
 export { hasScheduler, isValidCronExpr, SchedulerError } from "./core/scheduler.js";
 export type { SchedulerCapability, SchedulerErrorCode, ScheduledIntent, SchedulerContext, ScheduledTaskId, ScheduledTaskSummary, } from "./core/scheduler.js";
 export { createSchedulerTools, type SchedulerToolContext, SCHEDULE_WAKEUP_TOOL_NAME, AUTONOMOUS_LOOP_SENTINEL, AUTONOMOUS_LOOP_DYNAMIC_SENTINEL, } from "./tools/scheduler-tools.js";
@@ -184,7 +184,8 @@ export { createAllowDenyPolicy, createApprovalPolicy,
  *  policy verdict cannot get re-adjudicated). Exported so a host can NAME it instead of deriving it through
  *  `Parameters<typeof createApprovalPolicy>[0]["approve"]`. */
 type ApprovalSeatOutcome, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, type AskRuleEvidence, type AskEvidenceAbsence, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
-export { type AskOrigin, ASK_ORIGINS, isAskOrigin, classifierMayAnswer, ORIGIN_IMPLIES_REAL_APPROVAL, RULE_STORE_UNREADABLE_KINDS, type RuleStoreUnreadable, isRuleStoreUnreadable } from "./core/ask-origin.js";
+export { type ReadRootGrantScreen } from "./core/read-root-grant-screen.js";
+export { type AskOrigin, ASK_ORIGINS, isAskOrigin, classifierMayAnswer, ORIGIN_IMPLIES_REAL_APPROVAL, RULE_STORE_UNREADABLE_KINDS, type RuleStoreUnreadable, isRuleStoreUnreadable, PERSISTED_RULE_MANDATES, type PersistedRuleMandate, isPersistedRuleMandate } from "./core/ask-origin.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource, type AutoModeDenySource } from "./core/runtime-caps.js";
 export { SETTLEMENT_KINDS, type SettlementKind, isSettlementKind, type Settlement, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, type DeniedBy, isDeniedBy, DENIED_BY_MAY_VETO, CLASSIFIER_DENY_CAUSES, type ClassifierDenyCause, isClassifierDenyCause, DENIED_BY_MAY_CARRY_CAUSE, type GateDisposition, type GateOutcome, screenGateOutcome } from "./core/gate-outcome.js";
 export { type AskCarry } from "./core/hooks.js";

package/dist/index.js

@@ -149,7 +149,8 @@ export { createSchedulerTools, SCHEDULE_WAKEUP_TOOL_NAME, AUTONOMOUS_LOOP_SENTIN
 export { resolveAutonomousLoopPrompt, AUTONOMOUS_LOOP_PREAMBLE, AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT, } from "./tools/loop-tick.js";
 export { tightenTaskSpec, TaskSpecTightenError } from "./core/tighten-task-spec.js";
 export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
-export { ASK_ORIGINS, isAskOrigin, classifierMayAnswer, ORIGIN_IMPLIES_REAL_APPROVAL, RULE_STORE_UNREADABLE_KINDS, isRuleStoreUnreadable } from "./core/ask-origin.js";
+export {} from "./core/read-root-grant-screen.js";
+export { ASK_ORIGINS, isAskOrigin, classifierMayAnswer, ORIGIN_IMPLIES_REAL_APPROVAL, RULE_STORE_UNREADABLE_KINDS, isRuleStoreUnreadable, PERSISTED_RULE_MANDATES, isPersistedRuleMandate } from "./core/ask-origin.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./core/runtime-caps.js";
 export { SETTLEMENT_KINDS, isSettlementKind, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, isDeniedBy, DENIED_BY_MAY_VETO, CLASSIFIER_DENY_CAUSES, isClassifierDenyCause, DENIED_BY_MAY_CARRY_CAUSE, screenGateOutcome } from "./core/gate-outcome.js";
 export {} from "./core/hooks.js";

package/dist/scenarios/full-body.d.ts

@@ -16,7 +16,10 @@ export interface CodeToolsConfig {
     webFetch?: WebFetchConfig;
     /** WebSearch backend (BRAIN/model-service leg). Absent ⇒ WebSearch is not assembled (core ships no backend). */
     webSearch?: WebSearchConfig;
-    /** Subagent delegation. Present ⇒ assembled; child rosters are ⊆ parent via `resolveToolSubset` inside the tool.
+    /** Subagent delegation. Present ⇒ assembled. Without an explicit `subagent.tools` a child INHERITS this bundle's
+     *  surface as the leader's own instances (one `TaskListStore`), bounded by what the spawning run mounts and trimmed
+     *  by the spawn tier (`SubagentToolOptions.inheritedTools`). Tools composed BESIDE the bundle are not inherited: a
+     *  host hands those per spawn through `subagent.extraTools`, behind its own gates.
      *  合车复审修③: when this carries NO explicit `systemPrompt`, the assembler defaults it to
      *  `CODE_SYSTEM_PROMPT` — a code-scenario child holds Bash/Write side-effect tools, so it keeps the code
      *  constitution (snapshot-before-mutate / destructive-op care / git discipline) instead of falling to the
@@ -47,7 +50,7 @@ export interface CodeToolsConfig {
      * design/147 §6 D2 (CC 2.1.216 shared team task list): a shared {@link TaskListStore} for the
      * task-list family. Mount the SAME instance into each teammate's bundle to share one team task
      * list (the `owner` claim semantics come alive); absent ⇒ the private per-run list (unchanged
-     * default). Ignored when `taskList: false`.
+     * default). Ignored when `taskList: false`. This bundle's own Agent children share it by inheritance.
      */
     taskListStore?: TaskListStore;
 }

package/dist/scenarios/full-body.js

@@ -4,21 +4,28 @@ import { createTaskListTools } from "../tools/task-list.js";
 import { createSubagentTool } from "../agents/subagent.js";
 import { CODE_SYSTEM_PROMPT } from "../prompts/default.js";
 export function assembleCodeTools(cfg = {}) {
-    const tools = [];
-    tools.push(webFetchToolSpec(cfg.webFetch ?? {}));
+    const web = [webFetchToolSpec(cfg.webFetch ?? {})];
     if (cfg.webSearch)
-        tools.push(createWebSearchTool(cfg.webSearch));
-    if (cfg.subagent)
-        tools.push(createSubagentTool({ ...cfg.subagent, systemPrompt: cfg.subagent.systemPrompt ?? CODE_SYSTEM_PROMPT }));
+        web.push(createWebSearchTool(cfg.webSearch));
     const stamp = (t) => ({ ...t, modelGate: "task-scaffold" });
     const taskListOn = cfg.taskList !== false;
+    const scaffolds = [];
     if (cfg.todoWrite !== false && !taskListOn) {
-        tools.push(cfg.todoWrite === true ? createTodoWriteTool() : stamp(createTodoWriteTool()));
+        scaffolds.push(cfg.todoWrite === true ? createTodoWriteTool() : stamp(createTodoWriteTool()));
     }
     if (taskListOn) {
         const family = createTaskListTools(cfg.taskListStore);
-        tools.push(...(cfg.taskList === true ? family : family.map(stamp)));
+        scaffolds.push(...(cfg.taskList === true ? family : family.map(stamp)));
     }
+    const tools = [...web];
+    if (cfg.subagent) {
+        tools.push(createSubagentTool({
+            ...cfg.subagent,
+            systemPrompt: cfg.subagent.systemPrompt ?? CODE_SYSTEM_PROMPT,
+            inheritedTools: cfg.subagent.inheritedTools ?? [...web, ...scaffolds],
+        }));
+    }
+    tools.push(...scaffolds);
     return tools;
 }
 export const CODE_ROLE = { systemPrompt: CODE_SYSTEM_PROMPT, thinking: "high" };

package/dist/tools/fs/fs-bash-background-text.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The Bash tool's background-lifetime TEXT: the one sentence the tool description and every launch / adoption
+ * receipt render about whether a `run_in_background` process outlives the task, and the three fragments it is
+ * built from. Wording only — which rows the reaps take is the registry's (task-registry.ts); the retain answer is
+ * handed in, judged by the tool mount through THE retain predicate (background-shell.ts).
+ */
+/**
+ * Lifetime guidance AT THE DECISION MOMENT. The tool description alone does not steer the model:
+ * delivered services get hosted via run_in_background and reaped at THEIR OWNING RUN'S teardown — see
+ * {@link bgReapClause} for the session-scoped/session-less/isolated-owned-env split — where CC's models
+ * habitually use `nohup … &` instead, and BOTH engines kill resident bg rows at teardown. Pure prompt
+ * face: the kill semantics
+ * (CC-aligned) are untouched. ONE construction point: a ctrl+b-adopted command is the SAME lifetime class
+ * (its own leg says so in a comment), so the sentence it gets must be the same string, not a second copy.
+ */
+export declare function backgroundLifetimeNote(retained: boolean, sessionScoped: boolean, envIsolatedOwned: boolean, face?: "receipt" | "description"): string;

package/dist/tools/fs/fs-bash-background-text.js

@@ -0,0 +1,22 @@
+function bgReapClause(sessionScoped, envIsolatedOwned) {
+    if (!sessionScoped)
+        return "when this task ends";
+    return envIsolatedOwned
+        ? "at session end, not when this task ends — UNLESS this task's own isolated sandbox is torn down, which reaps it right then instead"
+        : "at session end, not when this task ends: it keeps running across tasks in the same session, and a later task can still read its output or stop it";
+}
+function bgNohupCaveat(envIsolatedOwned) {
+    return envIsolatedOwned
+        ? " — on a per-task isolated sandbox this only helps if the sandbox itself survives; if the deployment tears it down at task end, host the deliverable outside the sandbox instead"
+        : "";
+}
+function bgRetainedIsolatedNote() {
+    return " Background processes are retained here — normally one keeps running past this task and the session. The one exception: a per-task isolated sandbox that gets torn down still reaps it right then despite the retention declaration; if the deliverable must survive that too, host it outside the sandbox instead.";
+}
+export function backgroundLifetimeNote(retained, sessionScoped, envIsolatedOwned, face = "receipt") {
+    if (retained)
+        return envIsolatedOwned ? bgRetainedIsolatedNote() : "";
+    if (face === "description")
+        return ` Background processes do NOT survive the session — they are reaped ${bgReapClause(sessionScoped, envIsolatedOwned)}. A deliverable that must stay alive afterwards (a server, a daemon) needs a self-detaching FOREGROUND start instead: run \`nohup cmd >log 2>&1 &\` as a normal foreground command (portable; setsid does not exist on macOS), or use a service manager${bgNohupCaveat(envIsolatedOwned)}.`;
+    return ` NOTE: background processes do NOT survive the session (reaped ${bgReapClause(sessionScoped, envIsolatedOwned)}). If this is a deliverable service that must stay alive afterwards, host it with a FOREGROUND command instead: \`nohup cmd >log 2>&1 &\` (self-detaching — survives the session)${bgNohupCaveat(envIsolatedOwned)}.`;
+}

package/dist/tools/fs/fs-bash.d.ts

@@ -167,6 +167,12 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
      *  hint's open tag by the mint home (see {@link import("./index.js").HandsToolkitOptions.reminderMark}).
      *  Absent ⇒ historic bare tag. */
     reminderMark?: string;
+    /** The task lane of THE retain predicate (`TaskSpec.retainBackgroundProcesses` of the run this mount
+     *  serves; see {@link import("./index.js").HandsToolkitOptions.retainBackgroundProcesses}). Read by the
+     *  lifetime sentence (description + receipts) and stamped onto every background row this tool registers
+     *  (passing it — true or false — states the lane on the row). Absent ⇒ the sentence reads not-retained
+     *  and the rows leave the lane to the owning run's teardown. */
+    retainBackgroundProcesses?: boolean;
 }): AgentTool;
 /**
  * `bash_readonly` (effect:read) — a restricted shell for the verifier read-only boundary: a single

package/dist/tools/fs/fs-bash.js

@@ -5,13 +5,14 @@ import { defaultTaskRegistry } from "../../core/task-registry.js";
 import { accountDroppedBytes, spoolDropNote } from "../../core/task-registry-shared.js";
 import { RollingTailBuffer } from "../../core/exec-output-tail.js";
 import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, ENV_DIRECT_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "../../core/task-tool-shape.js";
-import { hasBackgroundShell } from "../../core/background-shell.js";
+import { envDeclaresRetain, hasBackgroundShell, retainsBackgroundProcesses } from "../../core/background-shell.js";
 import { delimitUntrusted } from "../../core/untrusted-text.js";
 import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
 import { imageMagicMatches, withinAnyRoot } from "./safety.js";
 import { isDeadCwd, diagnoseDeadCwd } from "./dead-cwd.js";
 import { boundaryIsTheSandbox, hasDestroy, isIsolated } from "../../core/remote-env.js";
 import { ghRateLimitHint } from "./gh-rate-limit.js";
+import { backgroundLifetimeNote } from "./fs-bash-background-text.js";
 import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, shellRecoveryHint, CWD_SENTINEL, stripCwdSentinel, } from "./fs-shared.js";
 import { bashClassifyDefaultAllow, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoopDetailed, classifyCompoundReadonlyDetailed } from "./bash-readonly-classifier.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
@@ -495,21 +496,6 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
         },
     };
 }
-function bgReapClause(sessionScoped, envIsolatedOwned) {
-    if (!sessionScoped)
-        return "when this task ends";
-    return envIsolatedOwned
-        ? "at session end, not when this task ends — UNLESS this task's own isolated sandbox is torn down, which reaps it right then instead"
-        : "at session end, not when this task ends: it keeps running across tasks in the same session, and a later task can still read its output or stop it";
-}
-function bgNohupCaveat(envIsolatedOwned) {
-    return envIsolatedOwned
-        ? " — on a per-task isolated sandbox this only helps if the sandbox itself survives; if the deployment tears it down at task end, host the deliverable outside the sandbox instead"
-        : "";
-}
-function bgRetainedIsolatedNote() {
-    return " This environment declares retention for background processes — normally one keeps running past this task and the session. The one exception: a per-task isolated sandbox that gets torn down still reaps it right then despite the retention declaration; if the deliverable must survive that too, host it outside the sandbox instead.";
-}
 function bashDescription(coAuthor, caps, bgNotifies = false, bgRetained = false, bgSessionScoped = false, bgEnvIsolatedOwned = false) {
     const coAuthorLines = coAuthor === false
         ? "- Follow the deployment's commit-message conventions."
@@ -520,7 +506,7 @@ function bashDescription(coAuthor, caps, bgNotifies = false, bgRetained = false,
 - IMPORTANT: Avoid using this tool to run \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user.
 - File search by name: use the Glob tool (NOT \`find\` or \`ls\`); content search: use the Grep tool (NOT \`grep\`/\`rg\` in the shell).
 - \`timeout\` is in milliseconds: default ${caps.defaultMs}, max ${caps.maxMs}.
-- \`run_in_background\` runs the command detached: it keeps running across turns and ${bgNotifies ? "re-invokes you when it exits" : "you read its output later with TaskOutput(task_id)"}. No \`&\` needed.${bgRetained ? (bgEnvIsolatedOwned ? bgRetainedIsolatedNote() : "") : ` Background processes do NOT survive the session — they are reaped ${bgReapClause(bgSessionScoped, bgEnvIsolatedOwned)}. A deliverable that must stay alive afterwards (a server, a daemon) needs a self-detaching FOREGROUND start instead: run \`nohup cmd >log 2>&1 &\` as a normal foreground command (portable; setsid does not exist on macOS), or use a service manager${bgNohupCaveat(bgEnvIsolatedOwned)}.`}
+- \`run_in_background\` runs the command detached: it keeps running across turns and ${bgNotifies ? "re-invokes you when it exits" : "you read its output later with TaskOutput(task_id)"}. No \`&\` needed.${backgroundLifetimeNote(bgRetained, bgSessionScoped, bgEnvIsolatedOwned, "description")}
 
 # Git
 - Interactive flags (\`-i\`, e.g. \`git rebase -i\`, \`git add -i\`) are not supported in this environment.
@@ -557,6 +543,7 @@ async function adoptBackgroundShell(req) {
             ...(sessionScoped ? { sessionScoped: true } : {}),
             ...(outputFile !== undefined ? { outputFile } : {}),
             ...(onNotify !== undefined ? { onTerminal: (n) => onNotify(n, { priority: "next" }) } : {}),
+            ...(wiring.retainBackgroundProcesses !== undefined ? { retainBackgroundProcesses: wiring.retainBackgroundProcesses } : {}),
         });
         return { ok: true, taskId, outputFile };
     }
@@ -574,16 +561,11 @@ async function adoptBackgroundShell(req) {
         return { ok: false, reason, killed: false, killMsg: kill !== undefined && !kill.ok ? kill.error.message : "killBackground threw" };
     }
 }
-function backgroundLifetimeNote(caps, sessionScoped, envIsolatedOwned) {
-    if (caps.retainBackgroundProcesses === true)
-        return envIsolatedOwned ? bgRetainedIsolatedNote() : "";
-    return ` NOTE: background processes do NOT survive the session (reaped ${bgReapClause(sessionScoped, envIsolatedOwned)}). If this is a deliverable service that must stay alive afterwards, host it with a FOREGROUND command instead: \`nohup cmd >log 2>&1 &\` (self-detaching — survives the session)${bgNohupCaveat(envIsolatedOwned)}.`;
-}
 export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = { current: rootCanonical }, taskOpts = {}) {
     const timeoutCaps = resolveBashTimeoutCaps(taskOpts);
     const timeoutCapsSecView = bashTimeoutCapsSec(timeoutCaps);
     const bgNotifies = taskOpts.taskRegistry !== undefined && taskOpts.onTaskNotification !== undefined;
-    const bgRetained = hasBackgroundShell(env) && env.backgroundCapabilities.retainBackgroundProcesses === true;
+    const bgRetained = hasBackgroundShell(env) && retainsBackgroundProcesses({ env: envDeclaresRetain(env), task: taskOpts.retainBackgroundProcesses === true });
     const bgSessionScoped = taskOpts.sessionId !== undefined && taskOpts.taskRegistry !== undefined;
     const bgEnvIsolatedOwned = hasDestroy(env) && isIsolated(env);
     return defineTool({
@@ -652,7 +634,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                         ? ` Time budget: requested ${requestedTimeoutSec}s, capped at ${bgCaps.maxBgTimeoutSec}s (env ceiling: requests above ${bgCaps.maxBgTimeoutSec}s are reduced to it) — the process may run up to ${appliedTimeoutSec}s.`
                         : ` Time budget: the process may run up to ${appliedTimeoutSec}s (hard cap ${bgCaps.maxBgTimeoutSec}s).`
                     : "";
-                const lifetimeNote = backgroundLifetimeNote(bgCaps, bgSessionScoped, bgEnvIsolatedOwned);
+                const lifetimeNote = backgroundLifetimeNote(bgRetained, bgSessionScoped, bgEnvIsolatedOwned);
                 const registry = taskOpts.taskRegistry;
                 if (registry !== undefined) {
                     const onNotify = taskOpts.onTaskNotification;
@@ -664,7 +646,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                         toolUseId: ctx.toolCallId,
                         ctxTaskId: ctx.taskId,
                         ctxPrincipal: ctx.principal,
-                        wiring: { sessionId: taskOpts.sessionId, taskOwner: taskOpts.taskOwner, taskScope: taskOpts.taskScope, onNotify },
+                        wiring: { sessionId: taskOpts.sessionId, taskOwner: taskOpts.taskOwner, taskScope: taskOpts.taskScope, onNotify, retainBackgroundProcesses: taskOpts.retainBackgroundProcesses },
                     });
                     if (!adopted.ok) {
                         if (adopted.killed) {
@@ -736,7 +718,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                             toolUseId: ctx.toolCallId,
                             ctxTaskId: ctx.taskId,
                             ctxPrincipal: ctx.principal,
-                            wiring: { sessionId: taskOpts.sessionId, taskOwner: taskOpts.taskOwner, taskScope: taskOpts.taskScope, onNotify },
+                            wiring: { sessionId: taskOpts.sessionId, taskOwner: taskOpts.taskOwner, taskScope: taskOpts.taskScope, onNotify, retainBackgroundProcesses: taskOpts.retainBackgroundProcesses },
                         });
                         if (!adopted.ok) {
                             const outTail = stdoutSoFar.slice(-1_000);
@@ -784,7 +766,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                                         ? `You will be notified when it completes — do not poll.`
                                         : `Poll TaskOutput until its status is no longer "running".`) +
                                 adoptBudgetNote +
-                                backgroundLifetimeNote(adoptCaps, bgSessionScoped, bgEnvIsolatedOwned) +
+                                backgroundLifetimeNote(bgRetained, bgSessionScoped, bgEnvIsolatedOwned) +
                                 (tail ? `\n--- output so far (tail) ---\n${tail}` : ""),
                             details: { type: "bash", detached: true, task_id: taskId, ...(description !== undefined ? { description } : {}), ...(outputFile !== undefined ? { output_file: outputFile } : {}), ...(cause === "timeout" || backgroundedForQueuedMessage ? { autoBackgrounded: true } : {}) },
                         };

package/dist/tools/fs/fs-read.d.ts

@@ -1,9 +1,9 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
-import { type ReadFileState } from "./safety.js";
+import { type ReadFileState, type RootsSeat } from "./safety.js";
 import { type PdfModelCapabilities } from "./pdf.js";
 import { type ReadImageDownsamplerOption, type CwdRef } from "./fs-shared.js";
 import { type ReminderDisclosureCounts } from "../../core/reminder-disclosure.js";
-export declare function createReadFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], imageDownsampler?: ReadImageDownsamplerOption, pdfCapabilities?: PdfModelCapabilities, bgOutputReadExemption?: (canonicalKey: string, ctx: {
+export declare function createReadFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: RootsSeat, imageDownsampler?: ReadImageDownsamplerOption, pdfCapabilities?: PdfModelCapabilities, bgOutputReadExemption?: (canonicalKey: string, ctx: {
     taskId?: string;
     principal?: string;
 }) => boolean, readCyberReminder?: boolean, readDeny?: import("./read-deny.js").ReadDenyMatcher, readFace?: import("./containment-face.js").ContainmentFace, reminderMark?: string, reminderDisclosureCounts?: ReminderDisclosureCounts): AgentTool;

package/dist/tools/fs/fs-search-tools.d.ts

@@ -1,4 +1,5 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
+import { type RootsSeat } from "./safety.js";
 import type { ReadDenyMatcher } from "./read-deny.js";
 import type { ContainmentFace } from "./containment-face.js";
 import type { CwdRef } from "./fs-shared.js";
@@ -11,5 +12,5 @@ import type { CwdRef } from "./fs-shared.js";
  * honesty boundary.
  */
 export declare function grepDetailFields(text: string, mode: "files_with_matches" | "content" | "count", offset?: number, structuredRows?: readonly import("./search.js").GrepRow[]): Record<string, unknown>;
-export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef): AgentTool;
-export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef): AgentTool;
+export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: RootsSeat, readDeny?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef): AgentTool;
+export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: RootsSeat, readDeny?: ReadDenyMatcher, readFace?: ContainmentFace, cwdRef?: CwdRef): AgentTool;

package/dist/tools/fs/index.d.ts

@@ -28,7 +28,8 @@ export interface HandsToolkitOptions {
     /** The read-boundary whitelist: extra allowed containment roots for the READ faces only —
      *  read_file/grep/glob/repo_map and `bash_readonly` admit them; edit_file/write_file/notebook_edit
      *  and the full `bash`'s disclosure roots deliberately do NOT (widening reads must never silently
-     *  widen writes). Caveat, the same tradeoff `additionalRoots` states:
+     *  widen writes). Read per call, never copied: a caller that grows the array it passed (the Runner's
+     *  in-flight read-root grant) widens the structured read tools for their later calls. Caveat, the same tradeoff `additionalRoots` states:
      *  `bash_readonly`'s COMMAND allowlist is a deployment declaration — a
      *  deployment that puts a mutating command into `bashReadonlyAllow` has declared it read-safe,
      *  and that declaration applies inside every root, these included. Keep the allowlist genuinely
@@ -69,6 +70,12 @@ export interface HandsToolkitOptions {
     taskScope?: string;
     /** See createBashTool's taskOpts.sessionId: session-resident background commands. */
     sessionId?: string;
+    /** The task lane of THE retain predicate (`retainsBackgroundProcesses`): the serving run's
+     *  `TaskSpec.retainBackgroundProcesses`. The Runner fills it from the spec of the run it builds this band
+     *  for; a direct mount passes its own declaration. Read by Bash's lifetime sentence (description +
+     *  receipts) and stamped onto every background row Bash registers (stated). Absent ⇒ not stated: the rows
+     *  leave the lane to the owning run's teardown. */
+    retainBackgroundProcesses?: boolean;
     /** Mount TaskOutput/TaskStop directly from this band. Runner sets false and mounts the unified dispatcher once. */
     mountBackgroundTaskTools?: boolean;
     /** Completion-notification sink for finished background commands (threaded to createBashTool's

package/dist/tools/fs/index.js

@@ -26,9 +26,7 @@ export function handsWriteHalfMounts(opts) {
 }
 export function createHandsToolkit(env, readFileState, rootCanonical, opts = {}) {
     const { includeShell = false, readOnly = false, bashReadonlyAllow, commitCoAuthor = false, mountBackgroundTaskTools = true, additionalRoots, additionalReadRoots, } = opts;
-    const readFaceRoots = additionalReadRoots === undefined || additionalReadRoots.length === 0
-        ? additionalRoots
-        : [...(additionalRoots ?? []), ...additionalReadRoots];
+    const readFaceRoots = additionalReadRoots === undefined ? additionalRoots : () => (additionalReadRoots.length === 0 ? additionalRoots : [...(additionalRoots ?? []), ...additionalReadRoots]);
     const cwdRef = opts.cwdRef ?? { current: rootCanonical };
     const bgReadRegistry = opts.taskRegistry;
     const bgOutputReadExemption = bgReadRegistry === undefined
@@ -79,6 +77,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
                 taskOwner: opts.taskOwner,
                 taskScope: opts.taskScope,
                 ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+                ...(opts.retainBackgroundProcesses !== undefined ? { retainBackgroundProcesses: opts.retainBackgroundProcesses } : {}),
                 onTaskNotification: opts.taskNotification,
                 detachHub: opts.detachHub,
                 ...(opts.autoBackgroundOnTimeout !== undefined ? { autoBackgroundOnTimeout: opts.autoBackgroundOnTimeout } : {}),

package/dist/tools/fs/repo-map.d.ts

@@ -1,5 +1,6 @@
 import type { AgentTool } from "../../internal/harness-types.js";
 import type { ExecutionEnv } from "../../internal/harness-types.js";
+import { type RootsSeat } from "./safety.js";
 import type { ReadDenyMatcher } from "./read-deny.js";
 import type { ContainmentFace } from "./containment-face.js";
 /** Extract top-level symbol names (deduped, in first-seen order) from source text. A lightweight
@@ -13,4 +14,4 @@ import type { ContainmentFace } from "./containment-face.js";
  *  (src/core/auto-promote.ts) consumes it in ESCALATE-ONLY mode — a clean scan contributes nothing;
  *  it can only ever raise an escalation, never clear one. */
 export declare function extractSymbols(text: string): string[];
-export declare function createRepoMapTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ContainmentFace): AgentTool;
+export declare function createRepoMapTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: RootsSeat, readDeny?: ReadDenyMatcher, readFace?: ContainmentFace): AgentTool;

package/dist/tools/fs/safety.d.ts

@@ -434,6 +434,8 @@ export declare function joinForFamily(family: PathFamily, base: string, rel: str
  *  view's "does the TARGET" — a symlink AT a guarded spelling resolves away from it canonically,
  *  and only this view still names it. */
 export declare function lexicalViewOf(spelled: string, base: string): string;
+/** A face's extra containment roots: a fixed list, or a getter over a run's live set (read once per resolution). */
+export type RootsSeat = readonly string[] | (() => readonly string[] | undefined);
 /**
  * Resolve a model-supplied path to a canonical key AND enforce rootPath containment. Existing paths
  * use `canonicalPath` (resolves symlinks, so the same file cannot get two keys). New paths
@@ -441,7 +443,7 @@ export declare function lexicalViewOf(spelled: string, base: string): string;
  * therefore cannot land the target outside root. Returns the canonical key, or a `path_not_in_root`
  * violation. Defense-in-depth at the tool layer; NOT a substitute for a sandboxed `executionEnv`.
  */
-export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, path: string, signal?: AbortSignal, baseCwd?: string, additionalRootsCanonical?: readonly string[], exactFileReadExemption?: (canonicalKey: string) => boolean, readDeny?: {
+export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, path: string, signal?: AbortSignal, baseCwd?: string, additionalRoots?: RootsSeat, exactFileReadExemption?: (canonicalKey: string) => boolean, readDeny?: {
     matchTarget(canonicalKey: string, lexicalView?: string, opts?: {
         readonly aliasResolved?: boolean;
     }): {

package/dist/tools/fs/safety.js

@@ -448,11 +448,12 @@ function within(rootCanonical, p) {
         return true;
     return pN.identity.startsWith(rootN.identity.endsWith(SEP) ? rootN.identity : rootN.identity + SEP);
 }
-export async function resolveKey(env, rootCanonical, path, signal, baseCwd, additionalRootsCanonical, exactFileReadExemption, readDeny, containmentFace) {
+export async function resolveKey(env, rootCanonical, path, signal, baseCwd, additionalRoots, exactFileReadExemption, readDeny, containmentFace) {
     const canon = await canonicalizeTarget(env, path, signal, pathFamilyOf({ root: rootCanonical }), baseCwd);
     if (!canon.ok)
         return { ok: false, violation: { code: "invalid", message: canon.message } };
     const key = canon.key;
+    const additionalRootsCanonical = typeof additionalRoots === "function" ? additionalRoots() : additionalRoots;
     if (isBlockedDevicePath(key)) {
         return { ok: false, violation: { code: "invalid", message: `path "${path}" is a blocked device/special file (reading it can hang the process); refused.` } };
     }

package/dist/tools/fs/shell-read-check.d.ts

@@ -89,6 +89,9 @@ export interface ShellReadStationOptions {
     readonly boundaryOf: (toolName: string, cwd: string | undefined) => ShellReadBoundary | undefined;
     /** The listed read verbs (decides whether a segment is read by verb slots or word by word). */
     readonly readers?: ReadonlySet<string>;
+    /** `true` ⇔ every root `boundaryOf` returns is already a canonical identity (the Runner's): the station never
+     *  re-resolves one, so a root swapped for a link after it was declared or granted cannot bring in the link's target. */
+    readonly rootsCanonical?: boolean;
 }
 /** What a consumer hands {@link judgeShellRead}: the command as written, the environment whose filesystem
  *  answers where its words land (symlinks resolved, patterns expanded — a `NodeExecutionEnv` over a real

package/dist/tools/fs/shell-read-check.js

@@ -170,7 +170,7 @@ export function createShellReadStation(opts) {
         const key = roots.join("\0");
         let e = establishers.get(key);
         if (e === undefined) {
-            e = createShellReadEstablisher(opts.env, roots);
+            e = createShellReadEstablisher(opts.env, roots, { rootsCanonical: opts.rootsCanonical === true });
             establishers.set(key, e);
         }
         return e;

package/dist/tools/fs/shell-read-establish.d.ts

@@ -79,4 +79,6 @@ export declare function establishShellReadsLexically(plan: ShellReadPlan, bounda
  * as declared (canonical by contract); they are resolved once more per instance because the comparison is
  * against `realpath` output on both sides — an aliased root would otherwise refuse every read under itself.
  */
-export declare function createShellReadEstablisher(env: ExecutionEnv, readRoots: readonly string[]): ShellReadEstablisher;
+export declare function createShellReadEstablisher(env: ExecutionEnv, readRoots: readonly string[], opts?: {
+    readonly rootsCanonical?: boolean;
+}): ShellReadEstablisher;