@sema-agent/core 2.8.0 → 2.10.0

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/index.d.ts

@@ -7,7 +7,7 @@ export { createSkillsFromDirectory, type SkillsDirectoryOptions, type SkillsDire
 export { REPORT_FINDINGS_TOOL_NAME, type ReportedFinding } from "./core/runner/synthetic-tools.js";
 export { formatToolError, formatZodValidationError, formatValidationPath, truncateError, errorClassOf } from "./core/tool-errors.js";
 export type { WorkerErrorClass } from "./core/tool-errors.js";
-export { createWebFetchTool, webFetchToolSpec, htmlToText, type WebFetchConfig, createWebSearchTool, type WebSearchConfig, createWebFetchSummarizer, WEBFETCH_SUMMARY_MAX_CONTENT, WEBFETCH_SUMMARY_GUIDELINES, } from "./tools/web.js";
+export { createWebFetchTool, webFetchToolSpec, htmlToText, type WebFetchConfig, createWebSearchTool, type WebSearchConfig, createSearxngSearchBackend, probeSearchBackend, type SearxngBackendOptions, createWebFetchSummarizer, WEBFETCH_SUMMARY_MAX_CONTENT, WEBFETCH_SUMMARY_GUIDELINES, } from "./tools/web.js";
 export { createTodoWriteTool } from "./tools/todo.js";
 export { createTaskListTools, createMemoryTaskListStore, assertJsonMetadata, type TaskListItem, type TaskListStore } from "./tools/task-list.js";
 export { assembleCodeTools, type CodeToolsConfig, CODE_ROLE } from "./scenarios/full-body.js";

package/dist/index.js

@@ -5,7 +5,7 @@ export { SKILL_TOOL_NAME } from "./core/runner/synthetic-tools.js";
 export { createSkillsFromDirectory, } from "./core/skills-directory.js";
 export { REPORT_FINDINGS_TOOL_NAME } from "./core/runner/synthetic-tools.js";
 export { formatToolError, formatZodValidationError, formatValidationPath, truncateError, errorClassOf } from "./core/tool-errors.js";
-export { createWebFetchTool, webFetchToolSpec, htmlToText, createWebSearchTool, createWebFetchSummarizer, WEBFETCH_SUMMARY_MAX_CONTENT, WEBFETCH_SUMMARY_GUIDELINES, } from "./tools/web.js";
+export { createWebFetchTool, webFetchToolSpec, htmlToText, createWebSearchTool, createSearxngSearchBackend, probeSearchBackend, createWebFetchSummarizer, WEBFETCH_SUMMARY_MAX_CONTENT, WEBFETCH_SUMMARY_GUIDELINES, } from "./tools/web.js";
 export { createTodoWriteTool } from "./tools/todo.js";
 export { createTaskListTools, createMemoryTaskListStore, assertJsonMetadata } from "./tools/task-list.js";
 export { assembleCodeTools, CODE_ROLE } from "./scenarios/full-body.js";

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

@@ -9,6 +9,7 @@ import { combinePolicies, createAllowDenyPolicy } from "../core/tool-policy.js";
 import { callKeyOrdinal, oversizeJournalResult, journalOversizeTombstone, JOURNAL_OVERSIZE_ERROR_CODE, MAX_JOURNAL_RESULT_BYTES } from "../core/workflow-journal-store.js";
 import { isWorkflowRunActive, closeWorkflowChannel, markWorkflowActive, publishWorkflowEvent } from "./workflow-observe.js";
 import { isDurablePause, mapNestedSuspend } from "../agents/suspend-guard.js";
+import { RUNNING_AGENT_OBSERVE_EVERY_BEATS } from "../config/defaults.js";
 import { boundInputHashOf } from "../core/canonical-json.js";
 import { boundedRedactedSummary } from "../core/untrusted-egress.js";
 import { delimitUntrusted } from "../core/untrusted-text.js";
@@ -20,7 +21,6 @@ const MAX_TRANSCRIPT_CHARS = 4000;
 const WORKFLOW_RESULT_MAX = 4000;
 const WORKFLOW_RESULT_FULL_MAX = 200_000;
 const MAX_ACTIVITY = 30;
-const RUNNING_AGENT_PERSIST_EVERY_BEATS = 4;
 function workflowModelLabel(spec) {
     const model = spec.model;
     if (model === undefined)
@@ -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";
@@ -453,16 +453,17 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     };
     const waIdOf = (callKey) => `wa${createHash("sha256").update(`${runId}:${callKey}`).digest("hex").slice(0, 16)}`;
     const bceLive = new Map();
-    const bceSpawn = (callKey, label, agentType, replayed) => {
+    const bceSpawn = (callKey, label, agentType, replayed, sessionId) => {
         if (!bceSink)
             return;
         const id = waIdOf(callKey);
-        bceLive.set(id, { callKey, label, ...(agentType !== undefined ? { agentType } : {}) });
+        bceLive.set(id, { callKey, label, ...(agentType !== undefined ? { agentType } : {}), ...(sessionId !== undefined ? { sessionId } : {}) });
         bceEmit({
             kind: "spawn",
             taskId: id,
             sessionScoped: false,
             owner: runId,
+            ...(sessionId !== undefined ? { sessionId, transcriptId: sessionId } : {}),
             ...(scope !== undefined ? { scope } : {}),
             description: replayed ? `${label} (replayed)` : label,
             agentType: agentType ?? "workflow-agent",
@@ -474,6 +475,11 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             startedAt: Date.now(),
         });
     };
+    const bceBindSession = (callKey, sessionId) => {
+        const row = bceLive.get(waIdOf(callKey));
+        if (row !== undefined)
+            row.sessionId = sessionId;
+    };
     const bceTick = (callKey, e) => {
         if (!bceSink)
             return;
@@ -489,6 +495,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             workflowRunId: runId,
             ...(scope !== undefined ? { scope } : {}),
             ...(row.agentType !== undefined ? { agentType: row.agentType } : { agentType: "workflow-agent" }),
+            ...(row.sessionId !== undefined ? { sessionId: row.sessionId, transcriptId: row.sessionId } : {}),
             name: e.name ?? row.label,
             progressTaskId: e.taskId,
             ...(e.parentTaskId !== undefined ? { progressParentTaskId: e.parentTaskId } : {}),
@@ -635,7 +642,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 rec.toolCalls = (rec.toolCalls ?? 0) + 1;
             rec.activity = tail;
             beatCount += 1;
-            if (beatCount === 1 || beatCount % RUNNING_AGENT_PERSIST_EVERY_BEATS === 0) {
+            if (beatCount === 1 || beatCount % RUNNING_AGENT_OBSERVE_EVERY_BEATS === 0) {
                 void persist("update");
             }
         };
@@ -768,7 +775,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         agentPhaseOf.set(replayRec, phaseInstance);
                     emit({ type: "agent_start", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), callKey, prompt, ...(model !== undefined ? { model } : {}), replayed: true, ts: at });
                     emit({ type: "agent_end", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), status: replayRec.status, output: cachedOutput, ...(rs.toolCalls !== undefined ? { toolCalls: rs.toolCalls } : {}), replayed: true, ts: at });
-                    bceSpawn(callKey, label, agentOpts.agentType, true);
+                    bceSpawn(callKey, label, agentOpts.agentType, true, r.sessionId || undefined);
                     bceTerminal(callKey, replayRec.status === "completed" ? "completed" : "failed", cachedOutput, r.sessionId || undefined, replayRec.stats);
                     accumulateStats(r, false);
                     void persist("update");
@@ -810,7 +817,8 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 if (finalized)
                     throw new Error("workflow run already finalized — ctx.agent cannot spawn after the run ended");
                 rec.startedAt = now();
-                bceSpawn(callKey, label, agentOpts.agentType, false);
+                const bornChildSessionId = resolveChildSessionIdAtSpawn(spec);
+                bceSpawn(callKey, label, agentOpts.agentType, false, bornChildSessionId);
                 const typedSpec0 = applyWorkflowAgentType(spec, agentOpts.agentType, agentRegistry);
                 const typedSpec = typedSpec0.model === undefined && inheritedModelSnap !== undefined ? { ...typedSpec0, model: inheritedModelSnap } : typedSpec0;
                 const framedSpec = withWorkflowChildPersona(typedSpec, agentOpts.schema ?? typedSpec.outputSchema);
@@ -852,10 +860,11 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     const onCallerAbort = () => attemptCtl.abort(new Error("workflow aborted"));
                     effectiveSignal?.addEventListener("abort", onCallerAbort, { once: true });
                     armWatchdog();
-                    const attemptSessionId = resolveChildSessionIdAtSpawn(runSpec);
+                    const attemptSessionId = attempts === 1 ? bornChildSessionId : resolveChildSessionIdAtSpawn(runSpec);
                     const attemptSpec = attemptSessionId !== undefined ? { ...runSpec, sessionId: attemptSessionId, signal: attemptCtl.signal } : { ...runSpec, signal: attemptCtl.signal };
                     if (attemptSessionId !== undefined && !finalized) {
                         rec.sessionId = attemptSessionId;
+                        bceBindSession(callKey, attemptSessionId);
                         void persist("update");
                     }
                     const attemptInternals = {
@@ -1143,9 +1152,9 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 throw new Error(finalized ? "workflow run already finalized — ctx.agentStream cannot spawn after the run ended" : "workflow aborted");
             }
             rec.startedAt = now();
-            bceSpawn(callKey, label, agentOpts.agentType, false);
+            const childSessionId = resolveChildSessionIdAtSpawn(spec);
+            bceSpawn(callKey, label, agentOpts.agentType, false, childSessionId);
             let stream;
-            let childSessionId;
             try {
                 const typedSpec0 = applyWorkflowAgentType(spec, agentOpts.agentType, agentRegistry);
                 const typedSpec = typedSpec0.model === undefined && inheritedModelSnap !== undefined ? { ...typedSpec0, model: inheritedModelSnap } : typedSpec0;
@@ -1154,7 +1163,6 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 const baseRunSpec = agentOpts.schema
                     ? { ...framedSpec, ...authInherit, signal: effectiveSignal, outputSchema: agentOpts.schema }
                     : { ...framedSpec, ...authInherit, signal: effectiveSignal };
-                childSessionId = resolveChildSessionIdAtSpawn(baseRunSpec);
                 const runSpec = childSessionId !== undefined ? { ...baseRunSpec, sessionId: childSessionId } : baseRunSpec;
                 const enrichedForwardS = opts.onForwardEvent !== undefined
                     ? (e) => {

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

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

@@ -52,7 +52,10 @@ export const BASH_MAX_TIMEOUT_SEC = 600;
 export const BASH_DEFAULT_TIMEOUT_MS = BASH_DEFAULT_TIMEOUT_SEC * 1000;
 export const BASH_MAX_TIMEOUT_MS = BASH_MAX_TIMEOUT_SEC * 1000;
 function validTimeoutMs(n) {
-    return n !== undefined && Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
+    if (n === undefined || !Number.isFinite(n))
+        return undefined;
+    const floored = Math.floor(n);
+    return floored >= 1 ? floored : undefined;
 }
 export function resolveBashTimeoutCaps(opts) {
     const defaultMs = validTimeoutMs(opts?.bashDefaultTimeoutMs) ??
@@ -80,7 +83,7 @@ export function clipShellOutput(s) {
     return clipWithFilePointer(s, bashMaxOutputChars());
 }
 export async function writeShellOverflowFile(env, stdout, stderr) {
-    const tf = await env.createTempFile({ prefix: "bash-output-", suffix: ".log" });
+    const tf = await env.createTempFile({ prefix: SHELL_OVERFLOW_FILE_PREFIX, suffix: SHELL_OVERFLOW_FILE_SUFFIX });
     if (!tf.ok)
         return undefined;
     const body = stderr.length > 0 ? `${stdout}${stdout.length > 0 && !stdout.endsWith("\n") ? "\n" : ""}--- stderr ---\n${stderr}` : stdout;
@@ -90,6 +93,45 @@ export async function writeShellOverflowFile(env, stdout, stderr) {
     const canon = await env.canonicalPath(tf.value);
     return canon.ok ? canon.value : tf.value;
 }
+const SHELL_OVERFLOW_FILE_PREFIX = "bash-output-";
+const SHELL_OVERFLOW_FILE_SUFFIX = ".log";
+function toPosixPathKey(p) {
+    return p.replace(/\\/g, "/").replace(/(.)\/+$/, "$1");
+}
+function isShellOverflowFileName(base) {
+    if (!base.startsWith(SHELL_OVERFLOW_FILE_PREFIX) || !base.endsWith(SHELL_OVERFLOW_FILE_SUFFIX))
+        return false;
+    const middle = base.slice(SHELL_OVERFLOW_FILE_PREFIX.length, base.length - SHELL_OVERFLOW_FILE_SUFFIX.length);
+    return /^[0-9A-Za-z][0-9A-Za-z._-]*$/.test(middle);
+}
+export function createShellOverflowSpoolFence(env) {
+    let tempArea;
+    const learnTempArea = async () => {
+        const probe = await env.createTempDir();
+        if (!probe.ok)
+            return undefined;
+        const canon = await env.canonicalPath(probe.value);
+        const resolved = toPosixPathKey(canon.ok ? canon.value : probe.value);
+        await env.remove(probe.value, { recursive: true, force: true });
+        const cut = resolved.lastIndexOf("/");
+        return cut > 0 ? resolved.slice(0, cut) : undefined;
+    };
+    return async (path) => {
+        const target = toPosixPathKey(path);
+        const cut = target.lastIndexOf("/");
+        if (cut <= 0 || !isShellOverflowFileName(target.slice(cut + 1)))
+            return false;
+        tempArea ??= learnTempArea();
+        const area = await tempArea;
+        if (area === undefined)
+            return false;
+        const parent = target.slice(0, cut);
+        if (parent === area)
+            return true;
+        const up = parent.lastIndexOf("/");
+        return up > 0 && parent.slice(0, up) === area;
+    };
+}
 export function shellRecoveryHint(path, readOnly) {
     const quoted = shellQuote(path);
     const example = readOnly ? `tail -c 50000 ${quoted}` : `sed -n 'START,ENDp' ${quoted}`;

package/dist/tools/web.d.ts

@@ -29,3 +29,18 @@ export interface WebSearchConfig {
 }
 export declare function clipCodePoints(s: string, max: number): string;
 export declare function createWebSearchTool(config: WebSearchConfig): ToolSpec;
+export interface SearxngBackendOptions {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    extraParams?: Record<string, string>;
+}
+export declare function createSearxngSearchBackend(baseUrl: string, options?: SearxngBackendOptions): WebSearchConfig["search"];
+export declare function probeSearchBackend(search: WebSearchConfig["search"], options?: {
+    timeoutMs?: number;
+}): Promise<{
+    ok: true;
+    results: number;
+} | {
+    ok: false;
+    error: string;
+}>;