@sema-agent/core 2.8.0 → 2.9.0

package/dist/core/task-registry-agent.js

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { uuidv7 } from "../internal/harness.js";
-import { canAccessAgentRecord, BackgroundAgentStoreError, } from "./background-agent-store.js";
+import { canAccessAgentRecord, BackgroundAgentStoreError, REVIVED_ROW_CLEARED_FIELDS, } from "./background-agent-store.js";
 import { shutdownDebug } from "./shutdown-debug.js";
 import { delimitUntrusted } from "./untrusted-text.js";
 import { boundedRedactedSummary } from "./untrusted-egress.js";
@@ -652,6 +652,8 @@ export function settleBackgroundAgentLane(core, id, outcome) {
     const handle = core.handles.get(id);
     if (!handle || handle.type !== "background_agent")
         return undefined;
+    if ((outcome.cycle ?? 0) !== (handle.reviveCycle ?? 0))
+        return undefined;
     if (handle.status !== "running") {
         if (handle.status === "killed") {
             mintCompletionId(handle);
@@ -859,31 +861,11 @@ export function reviveBackgroundAgentLane(core, id, access, abort) {
     handle.reviveCycle = (handle.reviveCycle ?? 0) + 1;
     handle.cycleSeq = (handle.cycleSeq ?? 1) + 1;
     handle.updatedAt = Date.now();
-    durableAgentWriteLane(handle, { status: "running" }, [
-        "settledAt",
-        "stoppedBy",
-        "finalOutput",
-        "finalOutputFull",
-        "error",
-        "errorCode",
-        "errorRetryable",
-        "errorKind",
-        "resultIsPartial",
-        "completionId",
-        "summary",
-        "recentSteps",
-        "editedFiles",
-        "usage",
-    ]);
+    durableAgentWriteLane(handle, { status: "running" }, REVIVED_ROW_CLEARED_FIELDS);
     return { ok: true, cycle: handle.reviveCycle };
 }
 export function settleRevivedAgentLane(core, id, cycle, outcome) {
-    const handle = core.handles.get(id);
-    if (!handle || handle.type !== "background_agent")
-        return undefined;
-    if ((handle.reviveCycle ?? 0) !== cycle)
-        return undefined;
-    return settleBackgroundAgentLane(core, id, outcome);
+    return settleBackgroundAgentLane(core, id, { ...outcome, cycle });
 }
 export function unmarkRetainedContinuationLane(core, id) {
     const handle = core.handles.get(id);
@@ -1023,18 +1005,33 @@ export function notFoundRunningAgentsTail(footer) {
     return ((footer.named.length > 0 ? `. Running named agents: ${footer.named.join(", ")}` : "") +
         (footer.background.length > 0 ? `. Running background agents: ${footer.background.join(", ")}` : ""));
 }
+function buildAgentPollDetails(input) {
+    const failed = input.status === "failed";
+    return {
+        task_id: input.taskId,
+        type: "background_agent",
+        status: input.status,
+        retrieval_status: input.retrievalStatus,
+        ...(input.seq !== undefined ? { seq: input.seq } : {}),
+        ...(input.status === "killed" && input.stoppedBy !== undefined ? { stoppedBy: input.stoppedBy } : {}),
+        ...(failed && input.error !== undefined ? { error: delimitUntrusted("agent error", boundedRedactedSummary(input.error, 300)) } : {}),
+        ...(failed && input.errorCode !== undefined ? { errorCode: input.errorCode } : {}),
+        ...(failed && input.errorRetryable !== undefined ? { retryable: input.errorRetryable } : {}),
+        ...(input.resultIsPartial === true ? { partial_result: true } : {}),
+        ...(input.completionId !== undefined ? { completionId: input.completionId } : {}),
+    };
+}
 export function serveDurableAgentRowLane(row) {
     if (row.status === "parked") {
         return {
             content: delimitUntrusted(`TaskOutput ${row.handle}`, `status: parked
 The agent is durably suspended, waiting for an approval decision. It resumes when the pending approval is decided (durable approval inbox), or lands failed if the approval expires.`),
-            details: {
-                task_id: row.handle,
-                type: "background_agent",
+            details: buildAgentPollDetails({
+                taskId: row.handle,
                 status: "parked",
-                retrieval_status: "success",
+                retrievalStatus: "success",
                 ...(row.seq !== undefined ? { seq: row.seq } : {}),
-            },
+            }),
         };
     }
     const kindClause = row.status === "failed" && row.errorKind !== undefined && row.errorRetryable !== undefined
@@ -1046,18 +1043,18 @@ ${row.error ? `error: ${row.error}${kindClause}
 ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}`;
     return {
         content: delimitUntrusted(`TaskOutput ${row.handle}`, body),
-        details: {
-            task_id: row.handle,
-            type: "background_agent",
+        details: buildAgentPollDetails({
+            taskId: row.handle,
             status: row.status,
-            retrieval_status: "success",
-            ...(row.status === "killed" && row.stoppedBy !== undefined ? { stoppedBy: row.stoppedBy } : {}),
+            retrievalStatus: "success",
             ...(row.seq !== undefined ? { seq: row.seq } : {}),
-            ...(row.resultIsPartial ? { partial_result: true } : {}),
+            ...(row.stoppedBy !== undefined ? { stoppedBy: row.stoppedBy } : {}),
+            ...(row.error !== undefined ? { error: row.error } : {}),
+            ...(row.errorCode !== undefined ? { errorCode: row.errorCode } : {}),
+            ...(row.errorRetryable !== undefined ? { errorRetryable: row.errorRetryable } : {}),
+            ...(row.resultIsPartial === true ? { resultIsPartial: true } : {}),
             ...(row.completionId !== undefined ? { completionId: row.completionId } : {}),
-            ...(row.status === "failed" && row.errorCode !== undefined ? { errorCode: row.errorCode } : {}),
-            ...(row.status === "failed" && row.errorRetryable !== undefined ? { retryable: row.errorRetryable } : {}),
-        },
+        }),
         ...(row.status === "failed" ? { isError: true } : {}),
     };
 }
@@ -1083,13 +1080,12 @@ export async function pollBackgroundAgentLane(handle, deadline, signal, oneShot,
         return {
             content: delimitUntrusted(`TaskOutput ${handle.id}`, `status: parked
 The agent is durably suspended, waiting for an approval decision. It resumes when the pending approval is decided (durable approval inbox), or lands failed if the approval expires.`),
-            details: {
-                task_id: handle.id,
-                type: "background_agent",
+            details: buildAgentPollDetails({
+                taskId: handle.id,
                 status: "parked",
-                retrieval_status: "success",
+                retrievalStatus: "success",
                 ...(handle.cycleSeq !== undefined ? { seq: handle.cycleSeq } : {}),
-            },
+            }),
         };
     }
     const fullResult = handle.result ? (handle.resultFull ?? handle.result) : undefined;
@@ -1109,21 +1105,18 @@ ${handle.error ? `error: ${handle.error}${kindClause}
 ${resultText}` : "(no result text)"}`;
     return {
         content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
-        details: {
-            task_id: handle.id,
-            type: "background_agent",
+        details: buildAgentPollDetails({
+            taskId: handle.id,
             status: handle.status,
-            retrieval_status: retrieval,
+            retrievalStatus: retrieval,
             ...(handle.cycleSeq !== undefined ? { seq: handle.cycleSeq } : {}),
-            ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
-            ...(handle.status === "failed" && handle.error !== undefined
-                ? { error: delimitUntrusted("agent error", boundedRedactedSummary(handle.error, 300)) }
-                : {}),
-            ...(handle.status === "failed" && handle.errorCode !== undefined ? { errorCode: handle.errorCode } : {}),
-            ...(handle.status === "failed" && handle.errorRetryable !== undefined ? { retryable: handle.errorRetryable } : {}),
-            ...(handle.resultIsPartial ? { partial_result: true } : {}),
+            ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+            ...(handle.error !== undefined ? { error: handle.error } : {}),
+            ...(handle.errorCode !== undefined ? { errorCode: handle.errorCode } : {}),
+            ...(handle.errorRetryable !== undefined ? { errorRetryable: handle.errorRetryable } : {}),
+            ...(handle.resultIsPartial === true ? { resultIsPartial: true } : {}),
             ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
-        },
+        }),
         ...(handle.status === "failed" ? { isError: true } : {}),
     };
 }

package/dist/core/task-registry.d.ts

@@ -138,6 +138,7 @@ export declare class TaskRegistry {
         errorKind?: string;
         stoppedBy?: StopSource;
         seq?: number;
+        cycle?: number;
     }): "completed" | "failed" | "killed" | undefined;
     abortBackgroundAgentsForOwner(access: TaskAccess, opts?: {
         skipSessionScoped?: boolean;

package/dist/core/task-registry.js

@@ -518,7 +518,7 @@ export class TaskRegistry {
             this.markStopSource(handle.id, "system");
             const reapTerminalNote = handle.onReapTerminal;
             handle.abort.abort();
-            this.settleBackgroundAgent(handle.id, { status: "killed", error: "session released" });
+            this.settleBackgroundAgent(handle.id, { status: "killed", error: "session released", cycle: handle.reviveCycle ?? 0 });
             if (reapTerminalNote !== undefined && handle.terminalNotified !== true) {
                 handle.terminalNotified = true;
                 try {

package/dist/core/types.d.ts

@@ -97,6 +97,7 @@ export interface ToolExecuteContext {
     clientContext?: TaskSpec["clientContext"];
     excludeTools?: readonly string[];
     deferTools?: readonly string[];
+    alwaysLoadTools?: readonly string[];
     promptProfile?: "simple" | "classic";
     additionalDirectories?: readonly string[];
     envFacts?: TaskSpec["envFacts"];
@@ -465,11 +466,14 @@ export interface TaskEventIdentity {
     sourceTaskId?: string;
     bgAgentId?: string;
 }
-export type BrainStatusPhase = "rate_limited" | "retrying" | "reconnecting" | "circuit_open";
+export type BrainStatusPhase = "rate_limited" | "retrying" | "reconnecting" | "circuit_open" | "recovered" | "gave_up";
 export interface BrainStatus {
     phase: BrainStatusPhase;
     detail?: string;
     retryInSec?: number;
+    retryInMs?: number;
+    attempt?: number;
+    maxRetries?: number;
 }
 export interface ToolActivity {
     phase: "start" | "end";

package/dist/engine/compaction/compaction.js

@@ -256,7 +256,7 @@ export function findTurnStartIndex(entries, entryIndex, startIndex) {
     }
     return -1;
 }
-function enforceToolPairContainment(entries, startIndex, endIndex, cutIndex) {
+function collectToolCallSites(entries, startIndex, endIndex) {
     const callSites = new Map();
     for (let i = startIndex; i < endIndex; i++) {
         const entry = entries[i];
@@ -275,6 +275,22 @@ function enforceToolPairContainment(entries, startIndex, endIndex, cutIndex) {
             }
         }
     }
+    return callSites;
+}
+function emittingCallSite(callSites, toolCallId, resultIndex) {
+    const sites = callSites.get(toolCallId);
+    if (sites === undefined)
+        return -1;
+    let site = -1;
+    for (const s of sites) {
+        if (s < resultIndex)
+            site = s;
+        else
+            break;
+    }
+    return site;
+}
+function enforceToolPairContainment(entries, callSites, endIndex, cutIndex) {
     if (callSites.size === 0)
         return cutIndex;
     for (let i = cutIndex; i < endIndex; i++) {
@@ -284,16 +300,7 @@ function enforceToolPairContainment(entries, startIndex, endIndex, cutIndex) {
         const msg = entry.message;
         if (msg.role !== "toolResult")
             continue;
-        const sites = callSites.get(msg.toolCallId);
-        if (sites === undefined)
-            continue;
-        let site = -1;
-        for (const s of sites) {
-            if (s < i)
-                site = s;
-            else
-                break;
-        }
+        const site = emittingCallSite(callSites, msg.toolCallId, i);
         if (site === -1 || site >= cutIndex)
             continue;
         cutIndex = site;
@@ -301,6 +308,49 @@ function enforceToolPairContainment(entries, startIndex, endIndex, cutIndex) {
     }
     return cutIndex;
 }
+function foldToolPairsForward(entries, callSites, cutPoints, endIndex, cutIndex) {
+    for (let i = cutIndex; i < endIndex; i++) {
+        const entry = entries[i];
+        if (entry.type !== "message")
+            continue;
+        const msg = entry.message;
+        if (msg.role !== "toolResult")
+            continue;
+        const site = emittingCallSite(callSites, msg.toolCallId, i);
+        if (site === -1 || site >= cutIndex)
+            continue;
+        const next = cutPoints.find((c) => c > i);
+        if (next === undefined)
+            return -1;
+        cutIndex = next;
+        i = cutIndex - 1;
+    }
+    return cutIndex;
+}
+function deriveCutPoint(entries, startIndex, cutIndex) {
+    const cutEntry = entries[cutIndex];
+    const isUserMessage = cutEntry.type === "message" && cutEntry.message.role === "user";
+    const turnStartIndex = isUserMessage ? -1 : findTurnStartIndex(entries, cutIndex, startIndex);
+    return {
+        firstKeptEntryIndex: cutIndex,
+        turnStartIndex,
+        isSplitTurn: !isUserMessage && turnStartIndex !== -1,
+    };
+}
+function leavesSummarizableHistory(entries, startIndex, cut) {
+    const historyEnd = cut.isSplitTurn ? cut.turnStartIndex : cut.firstKeptEntryIndex;
+    for (let i = startIndex; i < historyEnd; i++) {
+        if (getMessageFromEntryForCompaction(entries[i]) !== undefined)
+            return true;
+    }
+    if (!cut.isSplitTurn)
+        return false;
+    for (let i = cut.turnStartIndex; i < cut.firstKeptEntryIndex; i++) {
+        if (getMessageFromEntryForCompaction(entries[i]) !== undefined)
+            return true;
+    }
+    return false;
+}
 export function findCutPoint(entries, startIndex, endIndex, keepRecentTokens, charsPerToken = DEFAULT_CHARS_PER_TOKEN) {
     const cutPoints = findValidCutPoints(entries, startIndex, endIndex);
     if (cutPoints.length === 0) {
@@ -335,15 +385,16 @@ export function findCutPoint(entries, startIndex, endIndex, keepRecentTokens, ch
             break;
         }
     }
-    cutIndex = enforceToolPairContainment(entries, startIndex, endIndex, cutIndex);
-    const cutEntry = entries[cutIndex];
-    const isUserMessage = cutEntry.type === "message" && cutEntry.message.role === "user";
-    const turnStartIndex = isUserMessage ? -1 : findTurnStartIndex(entries, cutIndex, startIndex);
-    return {
-        firstKeptEntryIndex: cutIndex,
-        turnStartIndex,
-        isSplitTurn: !isUserMessage && turnStartIndex !== -1,
-    };
+    const callSites = collectToolCallSites(entries, startIndex, endIndex);
+    const budgetCutIndex = cutIndex;
+    cutIndex = enforceToolPairContainment(entries, callSites, endIndex, cutIndex);
+    const kept = deriveCutPoint(entries, startIndex, cutIndex);
+    if (cutIndex !== budgetCutIndex && !leavesSummarizableHistory(entries, startIndex, kept)) {
+        const folded = foldToolPairsForward(entries, callSites, cutPoints, endIndex, budgetCutIndex);
+        if (folded !== -1)
+            return deriveCutPoint(entries, startIndex, folded);
+    }
+    return kept;
 }
 export const SUMMARIZATION_SYSTEM_PROMPT = `You are a context summarization assistant. Your task is to read a conversation between a user and an AI coding assistant, then produce a structured summary following the exact format specified.
 

package/dist/internal/harness-types.d.ts

@@ -1,7 +1,7 @@
 export type { CompactionPreparation, SummarizationClampDryRun } from "../engine/compaction/compaction.js";
 export type { InvokedSkillRetention } from "../engine/compaction/utils.js";
 export type { AgentCoreRuntimeDeps } from "../engine/loop/runtime-deps.js";
-export type { AgentMessage, AgentTool, AgentToolResult, ThinkingLevel, } from "../engine/loop/types.js";
+export type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode, } from "../engine/loop/types.js";
 export type { AgentHarnessEvent, CompactionSettings, ExecutionEnv, ExecutionErrorCode, FileErrorCode, FileInfo, Result, Session, SessionMetadata, SessionRepo, SessionStorage, SessionTreeEntry, Skill, } from "../engine/harness/types.js";
 export type { ExecutionEnvExecOptions } from "../engine/harness/types.js";
 export type { SessionWriteOptions, CompactionEntry } from "../engine/harness/types.js";

package/dist/internal/harness.d.ts

@@ -2,7 +2,7 @@ export * from "./harness-types.js";
 export { AgentHarness } from "../engine/harness/agent-harness.js";
 export { CompactionError, ExecutionError, FileError, ok, err } from "../engine/harness/types.js";
 export { DEFAULT_CHARS_PER_TOKEN, DEFAULT_CLAMP_TOLERANCE, DEFAULT_COMPACTION_SETTINGS, compact, computeFileLists, dryRunSummarizationClamp, estimateContextTokens, estimateTokens, prepareCompaction, shouldCompact, summaryOutputBudgetTokens, } from "../engine/compaction/compaction.js";
-export { SKILL_RETENTION_PER_SKILL_MAX_CHARS, SKILL_RETENTION_TOTAL_MAX_CHARS, SKILL_RETENTION_TRUNCATION_MARKER, readCompactionActiveTools, readRetainedInvokedSkills, renderInvokedSkillsRetention, } from "../engine/compaction/utils.js";
+export { SKILL_RETENTION_PER_SKILL_MAX_CHARS, SKILL_RETENTION_TOTAL_MAX_CHARS, SKILL_RETENTION_TRUNCATION_MARKER, formatPersistedOutputRefs, readCompactionActiveTools, readRetainedInvokedSkills, renderInvokedSkillsRetention, } from "../engine/compaction/utils.js";
 export { NodeExecutionEnv } from "../engine/execution-env/node-execution-env.js";
 export { StoredSession, buildSessionContext } from "../engine/session/session.js";
 export { getEntriesToFork } from "../engine/session/repo-utils.js";

package/dist/internal/harness.js

@@ -2,7 +2,7 @@ export * from "./harness-types.js";
 export { AgentHarness } from "../engine/harness/agent-harness.js";
 export { CompactionError, ExecutionError, FileError, ok, err } from "../engine/harness/types.js";
 export { DEFAULT_CHARS_PER_TOKEN, DEFAULT_CLAMP_TOLERANCE, DEFAULT_COMPACTION_SETTINGS, compact, computeFileLists, dryRunSummarizationClamp, estimateContextTokens, estimateTokens, prepareCompaction, shouldCompact, summaryOutputBudgetTokens, } from "../engine/compaction/compaction.js";
-export { SKILL_RETENTION_PER_SKILL_MAX_CHARS, SKILL_RETENTION_TOTAL_MAX_CHARS, SKILL_RETENTION_TRUNCATION_MARKER, readCompactionActiveTools, readRetainedInvokedSkills, renderInvokedSkillsRetention, } from "../engine/compaction/utils.js";
+export { SKILL_RETENTION_PER_SKILL_MAX_CHARS, SKILL_RETENTION_TOTAL_MAX_CHARS, SKILL_RETENTION_TRUNCATION_MARKER, formatPersistedOutputRefs, readCompactionActiveTools, readRetainedInvokedSkills, renderInvokedSkillsRetention, } from "../engine/compaction/utils.js";
 export { NodeExecutionEnv } from "../engine/execution-env/node-execution-env.js";
 export { StoredSession, buildSessionContext } from "../engine/session/session.js";
 export { getEntriesToFork } from "../engine/session/repo-utils.js";

package/dist/orchestration/run-workflow-tool.d.ts

@@ -58,6 +58,7 @@ export interface RunWorkflowToolDeps {
     governanceBaseline: WorkflowGovernanceBaseline;
     parentExcludeTools?: readonly string[];
     parentDeferTools?: readonly string[];
+    parentAlwaysLoadTools?: readonly string[];
     parentPromptProfile?: "simple" | "classic";
     models?: Record<string, Model>;
     agents?: import("../core/types.js").AgentDefinition[];

package/dist/orchestration/run-workflow-tool.js

@@ -154,9 +154,12 @@ export async function createRunWorkflowTool(d) {
         ...(d.parentDeferTools?.length
             ? { deferTools: [...new Set([...(base.deferTools ?? []), ...d.parentDeferTools])] }
             : {}),
+        ...(d.parentAlwaysLoadTools?.length
+            ? { alwaysLoadTools: [...new Set([...(base.alwaysLoadTools ?? []), ...d.parentAlwaysLoadTools])] }
+            : {}),
     });
     const withParentProfile = (base) => d.parentPromptProfile !== undefined && base.promptProfile === undefined ? { ...base, promptProfile: d.parentPromptProfile } : base;
-    const baselineWithParentFace = (d.parentExcludeTools?.length ?? 0) > 0 || (d.parentDeferTools?.length ?? 0) > 0 || d.parentPromptProfile !== undefined
+    const baselineWithParentFace = (d.parentExcludeTools?.length ?? 0) > 0 || (d.parentDeferTools?.length ?? 0) > 0 || (d.parentAlwaysLoadTools?.length ?? 0) > 0 || d.parentPromptProfile !== undefined
         ? {
             ...d.governanceBaseline,
             base: withParentProfile(withParentFace(d.governanceBaseline.base)),

package/dist/orchestration/workflow.d.ts

@@ -18,7 +18,7 @@ export declare function workflowAgentCallKey(ordinal: number, spec: TaskSpec, op
     schema?: TSchema;
     isolation?: "worktree";
 }): string;
-export declare function assertSupportedAgentIsolation(isolation: unknown): asserts isolation is "worktree" | undefined;
+export declare function assertSupportedAgentIsolation(isolation: unknown): void;
 export interface WorkflowFanOutSlotError {
     index: number;
     kind: string;

package/dist/orchestration/workflow.js

@@ -100,7 +100,7 @@ export function workflowAgentCallKey(ordinal, spec, opts) {
         tools: spec.tools?.map((t) => t.name).slice().sort(),
         mcp: spec.mcp?.map((m) => m.name).slice().sort(),
         outputSchema: opts.schema ?? spec.outputSchema,
-        isolation: opts.isolation,
+        isolation: opts.isolation ? opts.isolation : undefined,
     };
     return `${ordinal}:${boundInputHashOf(identity)}`;
 }
@@ -112,7 +112,7 @@ function resolveChildSessionIdAtSpawn(spec) {
     return randomUUID();
 }
 export function assertSupportedAgentIsolation(isolation) {
-    if (isolation !== undefined && isolation !== "worktree") {
+    if (isolation && isolation !== "worktree") {
         const shown = typeof isolation === "string" ? JSON.stringify(isolation) : String(isolation);
         const e = new Error(`isolation ${shown} is not supported in workflow agents — only "worktree" (omit the option to run in the shared working tree). The agent was not started (fail-closed: an unrecognized isolation value must never silently run in the shared working tree).`);
         e.code = "isolation.invalid";

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

@@ -83,19 +83,80 @@ function resolveOperandLexically(base, operand, homeDir) {
     return normalizeAbsPathLexicalEitherFamily(`${base.replace(/[/\\]+$/, "")}/${raw}`);
 }
 function tokenizeSegment(segment) {
-    return segment
+    const raw = segment
         .trim()
         .split(/\s+/)
-        .filter((t) => t.length > 0)
-        .map(foldQuoteRemovalToken);
+        .filter((t) => t.length > 0);
+    return { folded: raw.map(foldQuoteRemovalToken), raw };
 }
-function collectSegmentBoundaryFindings(toks, boundary) {
-    const name = toks[0];
+function hasUnquotedExpansionMetachar(rawToken) {
+    let open;
+    for (const ch of rawToken) {
+        if (open === undefined && (ch === '"' || ch === "'")) {
+            open = ch;
+            continue;
+        }
+        if (open === ch) {
+            open = undefined;
+            continue;
+        }
+        if (open === undefined && (ch === "{" || ch === "}" || ch === "$" || ch === "`"))
+            return true;
+        if (open === '"' && (ch === "$" || ch === "`"))
+            return true;
+    }
+    return false;
+}
+function isGrepPatternFlagToken(tok) {
+    if (tok.startsWith("--"))
+        return tok.startsWith("--regexp") || tok.startsWith("--file");
+    return /^-[A-Za-z]*[ef]/.test(tok);
+}
+function grepClusterValueOwner(tok) {
+    if (!/^-[A-Za-z]/.test(tok) || tok.startsWith("--"))
+        return undefined;
+    for (const ch of tok.slice(1)) {
+        if (ch === "e" || ch === "f")
+            return ch;
+        if (!/[A-Za-z]/.test(ch))
+            return undefined;
+    }
+    return undefined;
+}
+function attachedOptionPayloads(tok) {
+    const out = [];
+    if (tok.startsWith("--")) {
+        const eq = tok.indexOf("=");
+        if (eq > 0 && eq + 1 < tok.length)
+            out.push(tok.slice(eq + 1));
+        return out;
+    }
+    for (let k = 1; k <= tok.length; k++) {
+        if (!/^[A-Za-z]*$/.test(tok.slice(1, k)))
+            break;
+        const payload = tok.slice(k);
+        if (payload.length > 0)
+            out.push(payload);
+    }
+    return out;
+}
+function collectSegmentBoundaryFindings(tokens, boundary) {
+    const name = tokens.folded[0];
     if (NO_PATH_OPERAND_COMMANDS.has(name))
         return [];
-    const args = toks.slice(1);
+    const args = tokens.folded.slice(1);
     const findings = [];
     const candidates = [];
+    for (const rawArg of tokens.raw.slice(1)) {
+        if (!hasUnquotedExpansionMetachar(rawArg))
+            continue;
+        return [
+            {
+                kind: "unresolvable",
+                reason: `"${name}" is given the argument "${rawArg}", which the shell expands (brace/variable/command expansion) before the command runs — the path it would actually read cannot be resolved statically, so it is not auto-allowed`,
+            },
+        ];
+    }
     if (name === "cd") {
         const target = args.find((t) => !t.startsWith("-") || t === "-");
         if (target === undefined) {
@@ -107,7 +168,7 @@ function collectSegmentBoundaryFindings(toks, boundary) {
         candidates.push(target);
     }
     else {
-        const patternSuppliedByFlag = name === "grep" && args.some((t) => t === "-e" || t.startsWith("-e") || t === "-f" || t.startsWith("-f") || t.startsWith("--regexp") || t.startsWith("--file"));
+        const patternSuppliedByFlag = name === "grep" && args.some(isGrepPatternFlagToken);
         let sawOperand = false;
         for (let k = 0; k < args.length; k++) {
             const t = args[k];
@@ -115,17 +176,21 @@ function collectSegmentBoundaryFindings(toks, boundary) {
                 k++;
                 continue;
             }
+            if (name === "cut" && (/^-d./.test(t) || /^--(output-)?delimiter=/.test(t)))
+                continue;
+            if (name === "grep" && (grepClusterValueOwner(t) === "e" || /^--regexp=/.test(t)))
+                continue;
             if (t.startsWith("-") && t !== "-") {
-                const eq = t.indexOf("=");
-                const value = eq > 0 ? t.slice(eq + 1) : "";
-                if (value.length > 0 && isAbsolutePathToken(value))
-                    candidates.push(value);
+                for (const payload of attachedOptionPayloads(t)) {
+                    if (isAbsolutePathToken(payload) || isPathShapedToken(payload))
+                        candidates.push(payload);
+                }
                 continue;
             }
-            if (t === "-")
-                continue;
             const isGrepPatternSlot = name === "grep" && !patternSuppliedByFlag && !sawOperand;
             sawOperand = true;
+            if (t === "-")
+                continue;
             if (isGrepPatternSlot)
                 continue;
             if (isPathShapedToken(t))
@@ -227,16 +292,17 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
     const STDIN_FILE_FLOOR = { cat: 1, grep: 2, head: 1, tail: 1, wc: 1, cut: 1, tr: Infinity };
     const foldedSegments = [];
     for (let si = 0; si < segments.length; si++) {
-        const toks = tokenizeSegment(segments[si]);
+        const segmentTokens = tokenizeSegment(segments[si]);
+        const toks = segmentTokens.folded;
         if (toks.length === 0)
             continue;
-        foldedSegments.push(toks);
+        foldedSegments.push(segmentTokens);
         const name = toks[0];
         const nonOption = toks.slice(1).filter((t) => !t.startsWith("-"));
         if (!(pipeFed[si] ?? false)) {
             const floor = STDIN_FILE_FLOOR[name];
             const restArgs = toks.slice(1);
-            const grepPatternSuppliedByFlag = name === "grep" && restArgs.some((t) => t === "-e" || t.startsWith("-e") || t === "-f" || t.startsWith("--regexp") || t.startsWith("--file"));
+            const grepPatternSuppliedByFlag = name === "grep" && restArgs.some(isGrepPatternFlagToken);
             let sawNonFlagOperand = false;
             let hasStdinDash = false;
             if (name !== "tr") {
@@ -305,7 +371,7 @@ function evaluateReadBoundary(foldedSegments, boundary) {
 }
 export function classifySimpleCommandReadBoundary(command, boundary) {
     const toks = tokenizeSegment(command);
-    if (toks.length === 0)
+    if (toks.folded.length === 0)
         return {};
     return evaluateReadBoundary([toks], boundary);
 }

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

@@ -7,7 +7,7 @@ import { delimitUntrusted } from "../../core/untrusted-text.js";
 import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
 import { imageMagicMatches, withinAnyRoot } from "./safety.js";
 import { ghRateLimitHint } from "./gh-rate-limit.js";
-import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, shellRecoveryHint, CWD_SENTINEL, } from "./fs-shared.js";
+import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, createShellOverflowSpoolFence, shellRecoveryHint, CWD_SENTINEL, } from "./fs-shared.js";
 import { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyCompoundReadonly, classifySimpleCommandReadBoundary, } from "./bash-readonly-classifier.js";
 export function bashReversibilityProbe(allow, boundary) {
     const allowSet = new Set(allow ?? BASH_READONLY_DEFAULT_ALLOW);
@@ -632,7 +632,19 @@ export function createBashReadonlyTool(env, rootCanonical, allow, execClamp, opt
     const timeoutCapsSecView = bashTimeoutCapsSec(timeoutCaps);
     const sample = [...allow].slice(0, 6).join(", ");
     const readRoots = [rootCanonical, ...(opts?.additionalRoots ?? [])];
-    const mintedOutputFiles = new Set();
+    const overflowSpoolFence = createShellOverflowSpoolFence(env);
+    const readsOnlyEngineOverflowSpool = async (verdict) => {
+        if (verdict.outOfRootRead !== true)
+            return false;
+        const paths = verdict.outOfRootPaths ?? [];
+        if (paths.length === 0)
+            return false;
+        for (const p of paths) {
+            if (!(await overflowSpoolFence(p)))
+                return false;
+        }
+        return true;
+    };
     return defineTool({
         name: "Bash",
         contract: { contractId: "core.bash_readonly@1", implementationRevision: "1" },
@@ -651,17 +663,11 @@ export function createBashReadonlyTool(env, rootCanonical, allow, execClamp, opt
             const reason = coarseReadonlyCheck(command, allow);
             if (reason)
                 return errorResult(`Error (Bash): ${reason}`);
-            const boundary = classifySimpleCommandReadBoundary(command, { roots: [...readRoots, ...mintedOutputFiles], cwd: rootCanonical });
-            if (boundary.reason !== undefined) {
+            const boundary = classifySimpleCommandReadBoundary(command, { roots: readRoots, cwd: rootCanonical });
+            if (boundary.reason !== undefined && !(await readsOnlyEngineOverflowSpool(boundary))) {
                 return errorResult(`Error (Bash): ${boundary.reason}. bash_readonly is confined to the workspace roots; it has no approval path, so the call is refused rather than escalated.`, { code: "readonly_out_of_root", paths: boundary.outOfRootPaths ?? [] });
             }
-            const result = await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, execClamp, ctx.toolCallId, true);
-            if (typeof result !== "string") {
-                const outputFile = result.details.output_file;
-                if (typeof outputFile === "string")
-                    mintedOutputFiles.add(outputFile);
-            }
-            return result;
+            return await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, execClamp, ctx.toolCallId, true);
         },
     });
 }

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

@@ -47,6 +47,7 @@ export declare const FILE_PATH_PARAMS: {
 };
 export declare function clipShellOutput(s: string): string;
 export declare function writeShellOverflowFile(env: ExecutionEnv, stdout: string, stderr: string): Promise<string | undefined>;
+export declare function createShellOverflowSpoolFence(env: ExecutionEnv): (path: string) => Promise<boolean>;
 export declare function shellRecoveryHint(path: string, readOnly: boolean | undefined): string;
 export declare const FILE_STATE_TRAILER = " (file state is current in your context \u2014 no need to Read it back)";
 export declare const CWD_SENTINEL = "__cc_cwd_9f2c1b__";