@sema-agent/core 2.7.0 → 2.9.0

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

@@ -82,13 +82,81 @@ function resolveOperandLexically(base, operand, homeDir) {
         return undefined;
     return normalizeAbsPathLexicalEitherFamily(`${base.replace(/[/\\]+$/, "")}/${raw}`);
 }
-function collectSegmentBoundaryFindings(toks, boundary) {
-    const name = toks[0];
+function tokenizeSegment(segment) {
+    const raw = segment
+        .trim()
+        .split(/\s+/)
+        .filter((t) => t.length > 0);
+    return { folded: raw.map(foldQuoteRemovalToken), raw };
+}
+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) {
@@ -100,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];
@@ -108,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))
@@ -220,17 +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 = segments[si].trim().split(/\s+/).filter((t) => t.length > 0)
-            .map(foldQuoteRemovalToken);
+        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") {
@@ -273,27 +345,35 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
             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" };
         }
     }
-    if (boundary !== undefined) {
-        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) {
-            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),
-            };
+    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);
         }
     }
-    return {};
+    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.folded.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

@@ -31,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

@@ -7,8 +7,8 @@ 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 { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyCompoundReadonly } from "./bash-readonly-classifier.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);
     return (args) => {
@@ -627,16 +627,32 @@ 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 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" },
         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).` })),
@@ -647,7 +663,11 @@ 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, 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 ?? [] });
+            }
+            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/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.7.0",
+  "version": "2.9.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",