@sema-agent/core 7.17.4 → 7.17.5

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

@@ -615,6 +615,25 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
     const bgRetained = hasBackgroundShell(env) && env.backgroundCapabilities.retainBackgroundProcesses === true;
     const bgSessionScoped = taskOpts.sessionId !== undefined && taskOpts.taskRegistry !== undefined;
     const bgEnvIsolatedOwned = hasDestroy(env) && isIsolated(env);
+    const recheckReaders = new Set(BASH_CLASSIFY_DEFAULT_ALLOW);
+    let canonicalForRoots;
+    const canonicalBoundaryFor = (roots) => {
+        const key = roots.join("\u0000");
+        if (canonicalForRoots?.key !== key)
+            canonicalForRoots = { key, boundary: createCanonicalReadBoundary(env, roots) };
+        return canonicalForRoots.boundary;
+    };
+    const canonicalEscape = async (command, signal) => {
+        const resolvedBoundary = typeof taskOpts.readBoundary === "function" ? taskOpts.readBoundary() : taskOpts.readBoundary;
+        if (resolvedBoundary === undefined || resolvedBoundary.face === "open")
+            return undefined;
+        const faces = [
+            classifyCompoundReadonlyDetailed(command, recheckReaders, resolvedBoundary),
+            classifyBoundedReadonlyPollLoopDetailed(command, recheckReaders, resolvedBoundary),
+        ];
+        const literal = [...new Set(faces.flatMap((v) => v.checkedPaths ?? []))];
+        return await canonicalEscapeRefusal(canonicalBoundaryFor(resolvedBoundary.roots), { literal, patterns: [] }, resolvedBoundary.roots, FULL_SHELL_FACE_ESCAPE_PROSE, signal);
+    };
     return defineTool({
         name: "Bash",
         ...toolFace("bash"),
@@ -650,6 +669,9 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
             const timeoutRefusal = bashTimeoutArgRefusal(timeout, timeoutCaps);
             if (timeoutRefusal !== undefined)
                 return errorResult(timeoutRefusal, { type: "bash_invalid_timeout", code: "bash_invalid_timeout" });
+            const escape = await canonicalEscape(command, ctx.signal);
+            if (escape !== undefined)
+                return escape;
             if (run_in_background) {
                 if (!hasBackgroundShell(env)) {
                     return errorResult("Error (Bash): this environment does not support background processes (run_in_background).");
@@ -659,6 +681,8 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                     if (diagnosis !== undefined)
                         throw new Error(diagnosis);
                 }
+                if (ctx.signal?.aborted === true)
+                    return errorResult("Error (Bash): the call was cancelled before the background command started.");
                 const requestedTimeoutSec = timeout !== undefined ? Math.max(1, Math.round(timeout / 1000)) : undefined;
                 const r = await env.spawnBackground(command, {
                     cwd: cwdRef.current,
@@ -923,6 +947,8 @@ function createCanonicalReadBoundary(env, readRoots) {
         while (parts.length > 0) {
             const canon = await env.canonicalPath(parts.join("/") || "/", signal);
             if (canon.ok) {
+                if (tail.length === 0)
+                    return canon.value;
                 return [canon.value.replace(/[\\/]+$/, ""), ...[...tail].reverse()].join("/");
             }
             tail.push(parts.pop());
@@ -1045,6 +1071,29 @@ function createCanonicalReadBoundary(env, readRoots) {
         },
     };
 }
+async function canonicalEscapeRefusal(canonical, candidates, readRoots, face, signal) {
+    const resolved = await canonical.escapesAfterResolution(candidates, signal);
+    if (resolved.unverifiable !== undefined) {
+        return errorResult(`Error (Bash): ${resolved.unverifiable}, so this command cannot be confirmed to read only inside the allowed directories for this session: ${readRoots.join(", ")}. ` +
+            face.note, { type: "readonly_out_of_root", code: "readonly_out_of_root", paths: [] });
+    }
+    if (resolved.escaping.length > 0) {
+        const quoted = resolved.escaping.map((p) => `"${p}"`).join(", ");
+        return errorResult(`Error (Bash): ${face.subject} resolves through a symlink to ${quoted}, outside the allowed directories for this session: ${readRoots.join(", ")}${face.verdictPhrase}. ` +
+            face.note, { type: "readonly_out_of_root", code: "readonly_out_of_root", paths: resolved.escaping });
+    }
+    return undefined;
+}
+const READONLY_FACE_ESCAPE_PROSE = {
+    subject: "a path this command reads",
+    verdictPhrase: ` ${NOT_AUTO_ALLOWED}`,
+    note: BASH_READONLY_CONFINEMENT_NOTE,
+};
+const FULL_SHELL_FACE_ESCAPE_PROSE = {
+    subject: "a path this command names",
+    verdictPhrase: "",
+    note: "The read boundary judged this command's written spelling before the call was approved, and execution is past the approval step — a target reached only through symlink resolution is refused here rather than escalated.",
+};
 export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
     const timeoutCaps = resolveBashTimeoutCaps(opts);
     const timeoutCapsSecView = bashTimeoutCapsSec(timeoutCaps);
@@ -1092,16 +1141,9 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
                     return errorResult(`Error (Bash): ${boundary.reason}. ${BASH_READONLY_CONFINEMENT_NOTE}`, { type: "readonly_out_of_root", code: "readonly_out_of_root", paths: boundary.outOfRootPaths ?? [] });
                 }
             }
-            const resolved = await canonicalBoundary.escapesAfterResolution({ literal: boundary.checkedPaths ?? [], patterns: boundary.undecidedPaths ?? [] }, ctx.signal);
-            if (resolved.unverifiable !== undefined) {
-                return errorResult(`Error (Bash): ${resolved.unverifiable}, so this command cannot be confirmed to read only inside the allowed directories for this session: ${readRoots.join(", ")}. ` +
-                    BASH_READONLY_CONFINEMENT_NOTE, { type: "readonly_out_of_root", code: "readonly_out_of_root", paths: [] });
-            }
-            if (resolved.escaping.length > 0) {
-                const quoted = resolved.escaping.map((p) => `"${p}"`).join(", ");
-                return errorResult(`Error (Bash): a path this command reads resolves through a symlink to ${quoted}, outside the allowed directories for this session: ${readRoots.join(", ")} ${NOT_AUTO_ALLOWED}. ` +
-                    BASH_READONLY_CONFINEMENT_NOTE, { type: "readonly_out_of_root", code: "readonly_out_of_root", paths: resolved.escaping });
-            }
+            const escape = await canonicalEscapeRefusal(canonicalBoundary, { literal: boundary.checkedPaths ?? [], patterns: boundary.undecidedPaths ?? [] }, readRoots, READONLY_FACE_ESCAPE_PROSE, ctx.signal);
+            if (escape !== undefined)
+                return escape;
             return await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, true);
         },
     });

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

@@ -11,6 +11,7 @@ export * from "./fs-search-tools.js";
 export * from "./bash-readonly-classifier.js";
 export * from "./fs-bash.js";
 export * from "./read-deny.js";
+import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
 export { BASH_CLASSIFY_DEFAULT_ALLOW } from "./bash-readonly-classifier.js";
 import { type ReadDenyEntry } from "./read-deny.js";
 export * from "./read-face.js";
@@ -40,6 +41,18 @@ export interface HandsToolkitOptions {
     readOnly?: boolean;
     /** Override the `bash_readonly` command allowlist (default {@link BASH_READONLY_DEFAULT_ALLOW}). */
     bashReadonlyAllow?: readonly string[];
+    /** The deployment's shell READ BOUNDARY, for the FULL `bash` face's execute-time canonical recheck
+     *  (see `createBashTool`'s `readBoundary`). The caller passes the SAME seat it gives the gate's shell
+     *  probes, so the boundary that judges a command's written spelling before approval and the leg that
+     *  re-judges its symlink-resolved targets before execution are one declaration. Ignored in `readOnly`
+     *  mode — `bash_readonly` builds its own from the roots it is confined to.
+     *
+     *  ABSENT ⇒ the leg does not run and costs no I/O: with no boundary declared there is no "outside" for
+     *  a read to be outside of, which is the same reading the probe seats take of an absent boundary. It
+     *  deliberately does NOT fall back to `additionalRoots`/`rootCanonical`: those are the WRITE side's
+     *  fence, they exclude `additionalReadRoots`, and standing a second root table up here would refuse
+     *  reads this deployment sanctions while claiming to enforce the boundary it was never given. */
+    shellReadBoundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined);
     /** Commit-message attribution trailer for the `bash` git protocol. Default NONE — attribution is a
      *  deployment identity asset, so the branded deployment sets it; pass `"Name <email>"` to advertise
      *  one, `false` (≡ unset) for no trailer section. */

package/dist/tools/fs/index.js

@@ -74,6 +74,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
                 ...(opts.autoBackgroundOnTimeout !== undefined ? { autoBackgroundOnTimeout: opts.autoBackgroundOnTimeout } : {}),
                 ...(opts.oneShot !== undefined ? { oneShot: opts.oneShot } : {}),
                 ...(additionalRoots !== undefined ? { additionalRoots } : {}),
+                ...(opts.shellReadBoundary !== undefined ? { readBoundary: opts.shellReadBoundary } : {}),
                 ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
                 ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
                 ...(opts.onNotice !== undefined ? { onNotice: opts.onNotice } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.17.4",
+  "version": "7.17.5",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -40,7 +40,8 @@
     "README.md",
     "NOTICE.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "wire-changes/"
   ],
   "engines": {
     "node": ">=20.3.0"