@sema-agent/core 2.6.0 → 2.8.0

package/dist/agents/send-message-tool.d.ts

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import type { Runner } from "../core/runner/runtask.js";
 import type { TaskNotificationPayload } from "../core/task-notification.js";
+import { type ToolCtxEnricher } from "../core/tools.js";
 import { SubagentRetainLedger } from "./retain-ledger.js";
 import { type SubagentSteerHandle } from "./subagent.js";
 export declare const SEND_MESSAGE_TOOL_NAME = "SendMessage";
@@ -35,6 +36,7 @@ export interface SendMessageToolOptions {
         content: string;
         details?: unknown;
     }>;
+    enrichCtx?: ToolCtxEnricher;
 }
 export declare const SEND_MESSAGE_SUMMARY_MAX = 200;
 export declare function clipSendMessageSummary(raw: string): string;

package/dist/agents/send-message-tool.js

@@ -554,5 +554,5 @@ export function createSendMessageTool(opts) {
                 }
             });
         },
-    });
+    }, opts.enrichCtx !== undefined ? { enrichCtx: opts.enrichCtx } : {});
 }

package/dist/core/background-agent-store.d.ts

@@ -37,6 +37,9 @@ export interface BackgroundAgentRecord {
     finalOutput?: string;
     finalOutputFull?: string;
     error?: string;
+    errorCode?: string;
+    errorRetryable?: boolean;
+    errorKind?: string;
     resultIsPartial?: boolean;
     recentSteps?: SubagentStep[];
     editedFiles?: SubagentEditedFile[];

package/dist/core/runner/prepare-task.js

@@ -1225,14 +1225,18 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 shellGatedBash = !egressTools.has("Bash") && !irreversibilityTier.has("Bash");
                 irreversibilityTier.set("Bash", shellGate === "always" ? "always" : "maybe");
                 irreversibleTools.add("Bash");
+                const shellReadBoundary = () => ({
+                    roots: [rootCanonical, ...additionalRootsCanonical],
+                    ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
+                });
                 if (shellGate === "classify")
-                    reversibilityProbes.set("Bash", bashReversibilityProbe());
+                    reversibilityProbes.set("Bash", bashReversibilityProbe(undefined, shellReadBoundary));
                 if (backgroundTaskToolsActive) {
                     shellGatedMonitor = !egressTools.has("Monitor") && !irreversibilityTier.has("Monitor");
                     irreversibilityTier.set("Monitor", shellGate === "always" ? "always" : "maybe");
                     irreversibleTools.add("Monitor");
                     if (shellGate === "classify")
-                        reversibilityProbes.set("Monitor", bashReversibilityProbe());
+                        reversibilityProbes.set("Monitor", bashReversibilityProbe(undefined, shellReadBoundary));
                 }
             }
         }
@@ -1274,6 +1278,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     ...(internals?.parentRetainLedger !== undefined ? { siblingRetain: internals.parentRetainLedger } : {}),
                     ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
                     ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}),
+                    enrichCtx: enrichSpecToolCtx,
                     ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}),
                     ...(deps.onBackgroundChildEvent ? { onBackgroundChildEvent: deps.onBackgroundChildEvent } : {}),
                     ...(deps.backgroundAgentStore !== undefined ? { agentStore: deps.backgroundAgentStore } : {}),

package/dist/core/store-contracts/file-snapshot-store-contract.d.ts

@@ -1,3 +1,5 @@
 import type { FileSnapshotStore } from "../file-snapshot-store.js";
 import { type ContractAssertionRunner } from "./contract-harness.js";
-export declare function fileSnapshotStoreContract(make: () => FileSnapshotStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+export declare function fileSnapshotStoreContract(make: () => FileSnapshotStore, runAssertion?: ContractAssertionRunner, options?: {
+    blobGc?: "immediate" | "eventual";
+}): Promise<void>;

package/dist/core/store-contracts/file-snapshot-store-contract.js

@@ -4,8 +4,9 @@ import { beginContract } from "./contract-harness.js";
 const bytes = (s) => new TextEncoder().encode(s);
 const sha256 = (s) => createHash("sha256").update(bytes(s)).digest("hex");
 const srcBlob = async (hash) => hash === sha256("alpha") ? bytes("alpha") : hash === sha256("beta") ? bytes("beta") : undefined;
-export async function fileSnapshotStoreContract(make, runAssertion) {
+export async function fileSnapshotStoreContract(make, runAssertion, options) {
     const { run, settle } = beginContract(runAssertion);
+    const blobGc = options?.blobGc ?? "immediate";
     run("kit prerequisites: exportManifest/getBlob/putBlob/importManifest are implemented (REQUIRED by this kit)", async () => {
         const probe = make();
         const missing = ["exportManifest", "getBlob", "putBlob", "importManifest"].filter((m) => typeof probe[m] !== "function");
@@ -115,12 +116,19 @@ export async function fileSnapshotStoreContract(make, runAssertion) {
         assert.deepEqual(await store.listKeys("sc"), ["k1"]);
         assert.deepEqual([...(await store.getBlob(sha256("alpha")))], [...bytes("alpha")]);
     });
-    run("reap keep-nothing drops the key and GCs the now-unreferenced blobs", async () => {
+    run("reap keep-nothing drops the key IMMEDIATELY (every backend)", async () => {
         const store = make();
         await store.importManifest("sc", "k1", new Map([["a.txt", sha256("alpha")]]), srcBlob);
         assert.equal(await store.reap("sc", []), 1);
         assert.equal(await store.has("sc", "k1"), false);
-        assert.equal(await store.getBlob(sha256("alpha")), undefined);
     });
+    if (blobGc === "immediate") {
+        run("reap keep-nothing GCs the now-unreferenced blob bytes immediately (blobGc: immediate)", async () => {
+            const store = make();
+            await store.importManifest("sc", "k1", new Map([["a.txt", sha256("alpha")]]), srcBlob);
+            assert.equal(await store.reap("sc", []), 1);
+            assert.equal(await store.getBlob(sha256("alpha")), undefined);
+        });
+    }
     await settle();
 }

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

@@ -723,6 +723,9 @@ export function settleBackgroundAgentLane(core, id, outcome) {
         ...(handle.resultFull !== undefined ? { finalOutputFull: handle.resultFull } : {}),
         ...(handle.resultIsPartial ? { resultIsPartial: true } : {}),
         ...(handle.error !== undefined ? { error: handle.error } : {}),
+        ...(handle.errorCode !== undefined ? { errorCode: handle.errorCode } : {}),
+        ...(handle.errorRetryable !== undefined ? { errorRetryable: handle.errorRetryable } : {}),
+        ...(handle.errorKind !== undefined ? { errorKind: handle.errorKind } : {}),
     }, ["parkedCheckpointToken", "parkClaimId", "parkedAt"]);
     return outcome.status;
 }
@@ -856,7 +859,22 @@ 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", "resultIsPartial", "completionId", "summary", "recentSteps", "editedFiles", "usage"]);
+    durableAgentWriteLane(handle, { status: "running" }, [
+        "settledAt",
+        "stoppedBy",
+        "finalOutput",
+        "finalOutputFull",
+        "error",
+        "errorCode",
+        "errorRetryable",
+        "errorKind",
+        "resultIsPartial",
+        "completionId",
+        "summary",
+        "recentSteps",
+        "editedFiles",
+        "usage",
+    ]);
     return { ok: true, cycle: handle.reviveCycle };
 }
 export function settleRevivedAgentLane(core, id, cycle, outcome) {
@@ -1019,8 +1037,11 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
             },
         };
     }
+    const kindClause = row.status === "failed" && row.errorKind !== undefined && row.errorRetryable !== undefined
+        ? ` (error_kind: ${row.errorKind}, retryable: ${row.errorRetryable})`
+        : "";
     const body = `status: ${row.status}
-${row.error ? `error: ${row.error}
+${row.error ? `error: ${row.error}${kindClause}
 ` : ""}${row.finalOutput ? `--- result${row.resultIsPartial ? " (partial — produced before the task was stopped)" : ""} ---
 ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}`;
     return {
@@ -1034,6 +1055,8 @@ ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}
             ...(row.seq !== undefined ? { seq: row.seq } : {}),
             ...(row.resultIsPartial ? { partial_result: 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 } : {}),
     };

package/dist/core/tools.d.ts

@@ -1,6 +1,6 @@
 import type { TSchema } from "typebox";
 import type { AgentTool } from "../internal/harness.js";
-import type { ToolSpec } from "./types.js";
+import type { ToolExecuteContext, ToolSpec } from "./types.js";
 export declare function errorResult(text: string, details?: unknown): {
     content: string;
     isError: true;
@@ -8,4 +8,8 @@ export declare function errorResult(text: string, details?: unknown): {
 };
 export declare function isDefineToolProduct(x: unknown): x is AgentTool;
 export declare function stampDefineToolBrand<T extends object>(tool: T): T;
-export declare function defineTool<TParams extends TSchema = TSchema>(spec: ToolSpec<TParams>): AgentTool<TParams>;
+export type ToolCtxEnricher = (base: ToolExecuteContext) => ToolExecuteContext;
+export interface DefineToolOptions {
+    enrichCtx?: ToolCtxEnricher;
+}
+export declare function defineTool<TParams extends TSchema = TSchema>(spec: ToolSpec<TParams>, options?: DefineToolOptions): AgentTool<TParams>;

package/dist/core/tools.js

@@ -33,7 +33,7 @@ export function stampDefineToolBrand(tool) {
     Object.defineProperty(tool, DEFINE_TOOL_BRAND, { value: true, enumerable: false });
     return tool;
 }
-export function defineTool(spec) {
+export function defineTool(spec, options) {
     const executionMode = spec.executionMode ?? (spec.effect === "read" ? "parallel" : "sequential");
     const tool = {
         name: spec.name,
@@ -60,7 +60,8 @@ export function defineTool(spec) {
             }
             let ret;
             try {
-                ret = await spec.execute(params, { toolCallId, signal });
+                const baseCtx = { toolCallId, signal };
+                ret = await spec.execute(params, options?.enrichCtx ? { ...options.enrichCtx(baseCtx), toolCallId, signal } : baseCtx);
             }
             catch (err) {
                 throw new Error(formatToolError(err));

package/dist/index.d.ts

@@ -67,8 +67,9 @@ export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export type { InvariantKind, FunctionContract, Invariant, InvariantViolation, CheckResult, } from "./core/property-harness.js";
 export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, type BashReadonlyRootBoundary, type CompoundReadonlyVerdict, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
-export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, type ToolResultStore, type ToolResultSlice, } from "./core/tool-result-store.js";
+export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, type ToolResultStore, type ToolResultSlice, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, WALLTIME_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingWalltimeMs, winnerFromOutcome, validatePendingSteer, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type ResourceLedger, type ResourceLimitReason, } from "./core/checkpoint-store.js";
 export { InMemoryFileSnapshotStore, DEFAULT_SNAPSHOT_BOUNDS } from "./core/file-snapshot-store.js";
 export { captureManifest, applyManifest } from "./core/file-snapshot-store.js";

package/dist/index.js

@@ -58,8 +58,9 @@ export { runExecGate } from "./core/exec-gate.js";
 export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core/untrusted-text.js";
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
-export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, } from "./core/tool-result-store.js";
+export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, WALLTIME_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingWalltimeMs, winnerFromOutcome, validatePendingSteer, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";
 export { InMemoryFileSnapshotStore, DEFAULT_SNAPSHOT_BOUNDS } from "./core/file-snapshot-store.js";
 export { captureManifest, applyManifest } from "./core/file-snapshot-store.js";

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

@@ -5,4 +5,17 @@ export declare function parseLeadingCommandName(command: string): {
     reject: string;
 };
 export declare function coarseReadonlyCheck(command: string, allow: ReadonlySet<string>): string | undefined;
-export declare function classifyCompoundReadonly(command: string, allow: ReadonlySet<string>): string | undefined;
+export interface BashReadonlyRootBoundary {
+    roots: readonly string[];
+    cwd?: string;
+    homeDir?: string;
+}
+export interface CompoundReadonlyVerdict {
+    reason?: string;
+    outOfRootRead?: true;
+    outOfRootPaths?: readonly string[];
+}
+export declare function formatOutOfRootReadApprovalOption(directory: string): string;
+export declare function classifyCompoundReadonlyDetailed(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
+export declare function classifySimpleCommandReadBoundary(command: string, boundary: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
+export declare function classifyCompoundReadonly(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): string | undefined;

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

@@ -1,4 +1,4 @@
-import { isBlockedDevicePath, normalizeAbsPathLexically } from "./safety.js";
+import { isBlockedDevicePath, normalizeAbsPathLexically, withinAnyRoot } from "./safety.js";
 export const BASH_READONLY_DEFAULT_ALLOW = [
     "ls", "cat", "head", "tail", "wc", "pwd", "echo", "whoami", "uname",
     "grep", "cut", "tr", "basename", "dirname", "stat", "du", "df", "which",
@@ -49,12 +49,109 @@ function foldQuoteRemovalToken(tok) {
     }
     return out;
 }
-export function classifyCompoundReadonly(command, allow) {
+export function formatOutOfRootReadApprovalOption(directory) {
+    const trimmed = directory.replace(/[/\\]+$/, "");
+    const cut = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
+    const leaf = cut >= 0 ? trimmed.slice(cut + 1) : trimmed;
+    return `Yes, allow reading from ${leaf || directory}/ from this project`;
+}
+const NO_PATH_OPERAND_COMMANDS = new Set(["pwd", "echo", "whoami", "uname", "which", "tr", "basename", "dirname"]);
+function isAbsolutePathToken(p) {
+    return p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p);
+}
+function isPathShapedToken(tok) {
+    return tok.includes("/") || tok.startsWith("~") || tok === "." || tok === "..";
+}
+function normalizeAbsPathLexicalEitherFamily(p) {
+    const s = p.replace(/\\/g, "/");
+    return /^[A-Za-z]:\//.test(s) ? s.slice(0, 2) + normalizeAbsPathLexically(s.slice(2)) : normalizeAbsPathLexically(s);
+}
+function resolveOperandLexically(base, operand, homeDir) {
+    let raw = operand;
+    if (raw === "~" || raw.startsWith("~/")) {
+        if (homeDir === undefined || !isAbsolutePathToken(homeDir))
+            return undefined;
+        raw = raw === "~" ? homeDir : `${homeDir.replace(/[/\\]+$/, "")}/${raw.slice(2)}`;
+    }
+    else if (raw.startsWith("~")) {
+        return undefined;
+    }
+    if (isAbsolutePathToken(raw))
+        return normalizeAbsPathLexicalEitherFamily(raw);
+    if (base === undefined || !isAbsolutePathToken(base))
+        return undefined;
+    return normalizeAbsPathLexicalEitherFamily(`${base.replace(/[/\\]+$/, "")}/${raw}`);
+}
+function tokenizeSegment(segment) {
+    return segment
+        .trim()
+        .split(/\s+/)
+        .filter((t) => t.length > 0)
+        .map(foldQuoteRemovalToken);
+}
+function collectSegmentBoundaryFindings(toks, boundary) {
+    const name = toks[0];
+    if (NO_PATH_OPERAND_COMMANDS.has(name))
+        return [];
+    const args = toks.slice(1);
+    const findings = [];
+    const candidates = [];
+    if (name === "cd") {
+        const target = args.find((t) => !t.startsWith("-") || t === "-");
+        if (target === undefined) {
+            return [{ kind: "unresolvable", reason: '`cd` with no argument targets the home directory, which cannot be checked against the allowed directories — not auto-allowed' }];
+        }
+        if (target === "-") {
+            return [{ kind: "unresolvable", reason: '`cd -` targets the previous working directory, which cannot be resolved statically — not auto-allowed' }];
+        }
+        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"));
+        let sawOperand = false;
+        for (let k = 0; k < args.length; k++) {
+            const t = args[k];
+            if (name === "cut" && (t === "-d" || t === "--delimiter" || t === "--output-delimiter")) {
+                k++;
+                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);
+                continue;
+            }
+            if (t === "-")
+                continue;
+            const isGrepPatternSlot = name === "grep" && !patternSuppliedByFlag && !sawOperand;
+            sawOperand = true;
+            if (isGrepPatternSlot)
+                continue;
+            if (isPathShapedToken(t))
+                candidates.push(t);
+        }
+    }
+    for (const candidate of candidates) {
+        const resolved = resolveOperandLexically(boundary.cwd ?? boundary.roots[0], candidate, boundary.homeDir);
+        if (resolved === undefined) {
+            findings.push({
+                kind: "unresolvable",
+                reason: `"${name}" names the path "${candidate}", which cannot be resolved statically — not auto-allowed`,
+            });
+            continue;
+        }
+        if (!withinAnyRoot(boundary.roots, resolved))
+            findings.push({ kind: "outside", command: name, path: resolved });
+    }
+    return findings;
+}
+export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
     const trimmed = command.trim();
     if (!trimmed)
-        return "empty command";
+        return { reason: "empty command" };
     if (SHELL_SEGMENT_HARD_REJECT.test(trimmed)) {
-        return "redirection, command/variable substitution, subshells, escapes, and line breaks are not allowed";
+        return { reason: "redirection, command/variable substitution, subshells, escapes, and line breaks are not allowed" };
     }
     const source = trimmed.endsWith(";") ? trimmed.slice(0, -1) : trimmed;
     const segments = [];
@@ -70,7 +167,7 @@ export function classifyCompoundReadonly(command, allow) {
                 i++;
             }
             else
-                return "`&` backgrounding is not allowed — a backgrounded process outlives the command";
+                return { reason: "`&` backgrounding is not allowed — a backgrounded process outlives the command" };
         }
         else if (c === "|") {
             if (source[i + 1] === "|") {
@@ -97,7 +194,7 @@ export function classifyCompoundReadonly(command, allow) {
     for (const segment of segments) {
         const reason = coarseReadonlyCheck(segment, allow);
         if (reason !== undefined)
-            return reason;
+            return { reason };
     }
     const HEAD_AUTO_ALLOW_MAX = 1_000_000;
     const headBoundIsSmall = (name, toks) => {
@@ -128,11 +225,12 @@ export function classifyCompoundReadonly(command, allow) {
         return byteBound;
     };
     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 = segments[si].trim().split(/\s+/).filter((t) => t.length > 0)
-            .map(foldQuoteRemovalToken);
+        const toks = tokenizeSegment(segments[si]);
         if (toks.length === 0)
             continue;
+        foldedSegments.push(toks);
         const name = toks[0];
         const nonOption = toks.slice(1).filter((t) => !t.startsWith("-"));
         if (!(pipeFed[si] ?? false)) {
@@ -165,21 +263,52 @@ export function classifyCompoundReadonly(command, allow) {
                 }
             }
             if (floor !== undefined && hasStdinDash) {
-                return `"${name}" reads stdin via an explicit "-" argument and would block until the tool timeout — not auto-allowed`;
+                return { reason: `"${name}" reads stdin via an explicit "-" argument and would block until the tool timeout — not auto-allowed` };
             }
             if (floor !== undefined && nonOption.length < floor) {
-                return `"${name}" with no file argument reads stdin and would block until the tool timeout — not auto-allowed`;
+                return { reason: `"${name}" with no file argument reads stdin and would block until the tool timeout — not auto-allowed` };
             }
         }
         if (name === "tail" && toks.slice(1).some((t) => t === "--follow" || t.startsWith("--follow=") || /^[-+][^\s]*[fF]/.test(t))) {
-            return "`tail` in follow mode never terminates — not auto-allowed";
+            return { reason: "`tail` in follow mode never terminates — not auto-allowed" };
         }
         const GENERATOR_DEVICES = new Set(["/dev/zero", "/dev/random", "/dev/urandom", "/dev/full"]);
         const deviceArgs = toks.slice(1).filter((t) => !t.startsWith("-")).map(normalizeAbsPathLexically).filter(isBlockedDevicePath);
         const rescuedByHead = headBoundIsSmall(name, toks) && deviceArgs.every((d) => GENERATOR_DEVICES.has(d));
         if (!rescuedByHead && deviceArgs.length > 0) {
-            return "reads a device/special file that is either unbounded (/dev/zero, /dev/stdin, /proc/<pid>/fd/0, … — blocks the pipeline until the tool timeout) or process-private (/proc/<pid>/environ, /proc/<pid>/mem, …) — not auto-allowed";
+            return { reason: "reads a device/special file that is either unbounded (/dev/zero, /dev/stdin, /proc/<pid>/fd/0, … — blocks the pipeline until the tool timeout) or process-private (/proc/<pid>/environ, /proc/<pid>/mem, …) — not auto-allowed" };
         }
     }
-    return undefined;
+    if (boundary !== undefined)
+        return evaluateReadBoundary(foldedSegments, boundary);
+    return {};
+}
+function evaluateReadBoundary(foldedSegments, boundary) {
+    const outside = [];
+    for (const toks of foldedSegments) {
+        for (const finding of collectSegmentBoundaryFindings(toks, boundary)) {
+            if (finding.kind === "unresolvable")
+                return { reason: finding.reason };
+            if (!outside.some((o) => o.path === finding.path))
+                outside.push(finding);
+        }
+    }
+    if (outside.length === 0)
+        return {};
+    const paths = outside.map((o) => `"${o.path}"`).join(", ");
+    const allowed = boundary.roots.length > 0 ? boundary.roots.join(", ") : "(none)";
+    return {
+        reason: `"${outside[0].command}" reads ${paths}, outside the allowed directories for this session: ${allowed} — not auto-allowed`,
+        outOfRootRead: true,
+        outOfRootPaths: outside.map((o) => o.path),
+    };
+}
+export function classifySimpleCommandReadBoundary(command, boundary) {
+    const toks = tokenizeSegment(command);
+    if (toks.length === 0)
+        return {};
+    return evaluateReadBoundary([toks], boundary);
+}
+export function classifyCompoundReadonly(command, allow, boundary) {
+    return classifyCompoundReadonlyDetailed(command, allow, boundary).reason;
 }

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

@@ -1,7 +1,8 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import { type TaskRegistry } from "../../core/task-registry.js";
 import { type CwdRef } from "./fs-shared.js";
-export declare function bashReversibilityProbe(allow?: readonly string[]): (args: unknown) => {
+import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
+export declare function bashReversibilityProbe(allow?: readonly string[], boundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => {
     reversible: boolean;
 };
 export interface ExecClampOption {
@@ -30,9 +31,10 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
     bashDefaultTimeoutMs?: number;
     bashMaxTimeoutMs?: number;
 }): AgentTool;
-export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, execClamp?: ExecClampOption, timeoutOpts?: {
+export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, execClamp?: ExecClampOption, opts?: {
     bashDefaultTimeoutMs?: number;
     bashMaxTimeoutMs?: number;
+    additionalRoots?: readonly string[];
 }): AgentTool;
 export declare function createEnvTaskOutputTool(env: ExecutionEnv): AgentTool;
 export declare function createEnvTaskStopTool(env: ExecutionEnv, registry?: TaskRegistry): AgentTool;

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

@@ -8,14 +8,15 @@ 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 { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyCompoundReadonly } from "./bash-readonly-classifier.js";
-export function bashReversibilityProbe(allow) {
+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);
     return (args) => {
         const command = args?.command;
         if (typeof command !== "string")
             return { reversible: false };
-        return { reversible: classifyCompoundReadonly(command, allowSet) === undefined };
+        const resolved = typeof boundary === "function" ? boundary() : boundary;
+        return { reversible: classifyCompoundReadonly(command, allowSet, resolved) === undefined };
     };
 }
 const EXIT1_INTERPRETATION = {
@@ -626,16 +627,20 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
         },
     });
 }
-export function createBashReadonlyTool(env, rootCanonical, allow, execClamp, timeoutOpts) {
-    const timeoutCaps = resolveBashTimeoutCaps(timeoutOpts);
+export function createBashReadonlyTool(env, rootCanonical, allow, execClamp, opts) {
+    const timeoutCaps = resolveBashTimeoutCaps(opts);
     const timeoutCapsSecView = bashTimeoutCapsSec(timeoutCaps);
     const sample = [...allow].slice(0, 6).join(", ");
+    const readRoots = [rootCanonical, ...(opts?.additionalRoots ?? [])];
+    const mintedOutputFiles = new Set();
     return defineTool({
         name: "Bash",
         contract: { contractId: "core.bash_readonly@1", implementationRevision: "1" },
         description: `Run a SINGLE read-only inspection command (e.g. ${sample}, …) and return its output. Shell ` +
             "operators (pipes, redirects, ;, &&, command substitution, subshells) are rejected and only " +
-            "allowlisted commands run. Still subject to the deployment's approval policy.",
+            "allowlisted commands run. Reads are confined to the workspace root(s): a path outside them is " +
+            "refused, as is one that cannot be resolved statically (e.g. a `~` path). Still subject to the " +
+            "deployment's approval policy.",
         parameters: Type.Object({
             command: Type.String({ description: "A single allowlisted read-only command (no shell operators)." }),
             timeout: Type.Optional(Type.Number({ description: `Timeout in milliseconds (default ${timeoutCaps.defaultMs}, max ${timeoutCaps.maxMs}; requests above the max are capped to it).` })),
@@ -646,7 +651,17 @@ export function createBashReadonlyTool(env, rootCanonical, allow, execClamp, tim
             const reason = coarseReadonlyCheck(command, allow);
             if (reason)
                 return errorResult(`Error (Bash): ${reason}`);
-            return runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, execClamp, ctx.toolCallId, true);
+            const boundary = classifySimpleCommandReadBoundary(command, { roots: [...readRoots, ...mintedOutputFiles], cwd: rootCanonical });
+            if (boundary.reason !== undefined) {
+                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;
         },
     });
 }

package/dist/tools/fs/index.js

@@ -38,6 +38,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
             ? createBashReadonlyTool(env, rootCanonical, new Set(bashReadonlyAllow ?? BASH_READONLY_DEFAULT_ALLOW), opts.execClamp, {
                 ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
                 ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
+                ...(additionalRoots !== undefined ? { additionalRoots } : {}),
             })
             : createBashTool(env, rootCanonical, commitCoAuthor, cwdRef, {
                 taskRegistry: opts.taskRegistry,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",