@sema-agent/core 7.17.4 → 7.17.6

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

@@ -54,6 +54,10 @@ import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
  * The other non-reversible arms stay bare on purpose — their cause is legible in the command itself (a
  * write verb, a pipe, an unlisted name), and manufacturing an account for them would put text on a card
  * that adds nothing the reader cannot already see.
+ *
+ * What the boundary half of this probe is — and what it is not — is stated once on the seat that owns it
+ * ({@link bashReadBoundaryProbe}, `@contract shell.read_boundary.friction_floor`); composing it with the
+ * shape classifier here changes what happens to the residual shell risk, never that reading.
  */
 export declare function bashReversibilityProbe(allow?: readonly string[], boundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => ReversibilityVerdict;
 /**
@@ -99,6 +103,19 @@ export declare function bashReversibilityProbe(allow?: readonly string[], bounda
  * The reader set is the engine's classify set ({@link BASH_CLASSIFY_DEFAULT_ALLOW}) — here it is NOT an
  * auto-allow list but the set of programs whose operands the faces read; a wider set means more reads are
  * judged, never that more runs are vouched.
+ *
+ * @contract shell.read_boundary.friction_floor — what this seat answers is a question about TEXT: which
+ * files the words of a command may name, resolved against the declared roots, the declared home and the
+ * observed working directory. It is not a question about what the process will open, and no amount of
+ * parsing makes it one. A deployment's containment for what a shell may reach is the `ExecutionEnv` the
+ * command runs in (a sandbox, a container, a remote adapter); everything here is the friction floor under
+ * that containment — it raises the cost of an accidental or careless read, and it is not a defence against
+ * a command written to defeat it. The floor's last cell belongs to the full shell's own execute leg: once
+ * the gate has allowed a call and before anything spawns, the candidates this seat accepted are resolved
+ * on the filesystem, and a target that leaves the roots only after a symlink is followed is REFUSED —
+ * refused rather than asked, because by then the approval step is behind the call (see `createBashTool`'s
+ * `readBoundary` option). The leg runs where an environment can resolve a link locally; a remote adapter
+ * keeps the textual answer alone.
  */
 export declare function bashReadBoundaryProbe(boundary: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => ReversibilityVerdict;
 /**
@@ -171,6 +188,17 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
      * unconfined; passing this never gates anything.
      */
     additionalRoots?: readonly string[];
+    /**
+     * The deployment's shell READ BOUNDARY — the same seat the gate's shell probes read
+     * ({@link bashReadBoundaryProbe}), handed to the tool so its execute leg can close the one gap a
+     * synchronous seat structurally cannot: the seat judges the WRITTEN spelling, the kernel opens the
+     * symlink-resolved target. Passed as a FUNCTION wherever the working directory is observable (an
+     * in-task `cd` moves the base a relative operand resolves against); evaluated per call.
+     *
+     * Absent ⇒ no recheck and no I/O: a deployment with no read boundary declared has no roots for a
+     * read to be outside of, exactly as the seat itself reads an absent boundary.
+     */
+    readBoundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined);
     /** Override of the `timeout` parameter's DEFAULT budget, in ms — see
      *  {@link import("./index.js").HandsToolkitOptions.bashDefaultTimeoutMs} for the resolution
      *  contract (options over env over constant; invalid values discarded). */

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

@@ -6,8 +6,8 @@ import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_MISSING_ID_MESS
 import { hasBackgroundShell } from "../../core/background-shell.js";
 import { delimitUntrusted } from "../../core/untrusted-text.js";
 import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
-import { imageMagicMatches, withinAnyRoot } from "./safety.js";
-import { isRemoteExecutionEnv, hasDestroy, isIsolated } from "../../core/remote-env.js";
+import { imageMagicMatches, normalizeAbsPathLexically, withinAnyRoot } from "./safety.js";
+import { boundaryIsTheSandbox, hasDestroy, isIsolated } from "../../core/remote-env.js";
 import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, createShellOverflowSpoolFence, shellRecoveryHint, CWD_SENTINEL, BASH_READONLY_CONFINEMENT_NOTE, } from "./fs-shared.js";
 import { PROBE_CAUSE_PATH_MAX, inlineUntrusted } from "../../core/untrusted-text.js";
@@ -615,6 +615,27 @@ 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 ?? []), ...(v.checkedSpellings ?? [])]))];
+        const asked = new Set(faces.flatMap((v) => v.outOfRootPaths ?? []));
+        const patterns = [...new Set(faces.flatMap((v) => [...(v.undecidedPaths ?? []), ...(v.undecidedSpellings ?? [])]))].filter((p) => !asked.has(normalizeAbsPathLexically(p)));
+        return await canonicalEscapeRefusal(canonicalBoundaryFor(resolvedBoundary.roots), { literal, patterns }, resolvedBoundary.roots, FULL_SHELL_FACE_ESCAPE_PROSE, signal);
+    };
     return defineTool({
         name: "Bash",
         ...toolFace("bash"),
@@ -650,6 +671,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 +683,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,
@@ -904,7 +930,7 @@ function pathSegmentsFrom(p, from) {
     return segs;
 }
 function createCanonicalReadBoundary(env, readRoots) {
-    const lexicalOnly = isRemoteExecutionEnv(env);
+    const lexicalOnly = boundaryIsTheSandbox(env);
     let rootsOnce;
     const canonicalRoots = async (signal) => {
         rootsOnce ??= (async () => {
@@ -917,18 +943,60 @@ function createCanonicalReadBoundary(env, readRoots) {
         })();
         return await rootsOnce;
     };
-    const resolve = async (p, signal) => {
+    const resolveWithoutParentSteps = async (p, signal) => {
         const parts = p.split(/[\\/]/);
         const tail = [];
+        let allAbsent = true;
         while (parts.length > 0) {
             const canon = await env.canonicalPath(parts.join("/") || "/", signal);
             if (canon.ok) {
-                return [canon.value.replace(/[\\/]+$/, ""), ...[...tail].reverse()].join("/");
+                if (tail.length === 0)
+                    return { value: canon.value, exact: true };
+                return { value: [canon.value.replace(/[\\/]+$/, ""), ...[...tail].reverse()].join("/"), exact: false, missing: allAbsent };
             }
+            if (canon.error.code !== "not_found" && canon.error.code !== "not_directory")
+                allAbsent = false;
             tail.push(parts.pop());
         }
         return undefined;
     };
+    const parentOf = (canonical) => normalizeAbsPathLexically(`${canonical}/..`);
+    const resolve = async (p, signal) => {
+        const parts = p.split(/[\\/]/);
+        const first = parts.findIndex((seg) => seg === "..");
+        if (first < 0)
+            return await resolveWithoutParentSteps(p, signal);
+        const headEnd = parts.slice(0, first).reduce((n, seg) => n + seg.length + 1, 0);
+        let head = await resolveWithoutParentSteps(p.slice(0, headEnd) || "/", signal);
+        if (head === undefined)
+            return undefined;
+        let pending = [];
+        const flush = async () => {
+            if (pending.length === 0)
+                return true;
+            const next = await resolveWithoutParentSteps([head.value.replace(/[\\/]+$/, ""), ...pending].join("/"), signal);
+            pending = [];
+            if (next === undefined)
+                return false;
+            head = next;
+            return true;
+        };
+        for (let i = first; i < parts.length; i++) {
+            const seg = parts[i];
+            if (seg === "" || seg === ".")
+                continue;
+            if (seg !== "..") {
+                pending.push(seg);
+                continue;
+            }
+            if (!(await flush()))
+                return undefined;
+            if (!head.exact)
+                return head;
+            head = { value: parentOf(head.value), exact: true };
+        }
+        return (await flush()) ? head : undefined;
+    };
     const literalRootHead = (p, roots) => {
         let best;
         for (const r of [...readRoots, ...roots]) {
@@ -971,7 +1039,13 @@ function createCanonicalReadBoundary(env, readRoots) {
                 if (++dirsUsed > MAX_GLOB_DIRS) {
                     return { unverifiable: `"${p}" expands over more than ${MAX_GLOB_DIRS} directories, too many to enumerate to verify` };
                 }
-                const listed = await env.listDir(dir, signal);
+                const canonDir = await resolve(dir, signal);
+                if (canonDir !== undefined && canonDir.missing === true)
+                    continue;
+                if (canonDir !== undefined && !canonDir.exact) {
+                    return { unverifiable: `"${dir}" cannot be resolved to verify what "${seg}" would expand to` };
+                }
+                const listed = await env.listDir(canonDir?.value ?? dir, signal);
                 if (!listed.ok) {
                     if (listed.error.code === "not_found" || listed.error.code === "not_directory")
                         continue;
@@ -984,9 +1058,8 @@ function createCanonicalReadBoundary(env, readRoots) {
                 }
                 let dirInside = false;
                 if (isLast) {
-                    const canonDir = await resolve(dir, signal);
-                    if (canonDir !== undefined && !withinAnyRoot(roots, canonDir)) {
-                        next.push(canonDir);
+                    if (canonDir !== undefined && !withinAnyRoot(roots, canonDir.value)) {
+                        next.push(canonDir.value);
                         continue;
                     }
                     dirInside = canonDir !== undefined;
@@ -1014,12 +1087,17 @@ function createCanonicalReadBoundary(env, readRoots) {
                 return { escaping: [] };
             const roots = await canonicalRoots(signal);
             const escaping = [];
+            let unresolvable;
             const judge = async (p) => {
                 const real = await resolve(p, signal);
                 if (real === undefined)
                     return;
-                if (!withinAnyRoot(roots, real) && !escaping.includes(real))
-                    escaping.push(real);
+                if (!real.exact && real.missing !== true) {
+                    unresolvable ??= `"${p}" cannot be resolved to verify where it reads`;
+                    return;
+                }
+                if (!withinAnyRoot(roots, real.value) && !escaping.includes(real.value))
+                    escaping.push(real.value);
             };
             for (const p of paths.literal)
                 await judge(p);
@@ -1030,7 +1108,13 @@ function createCanonicalReadBoundary(env, readRoots) {
                 for (const t of expanded !== undefined && expanded.paths.length > 0 ? expanded.paths : [p])
                     await judge(t);
             }
-            return { escaping };
+            return unresolvable === undefined ? { escaping } : { escaping, unverifiable: unresolvable };
+        },
+        canonicalOf: async (path, signal) => {
+            if (lexicalOnly)
+                return undefined;
+            const real = await resolve(path, signal);
+            return real === undefined || (!real.exact && real.missing !== true) ? undefined : real.value;
         },
         allResolveInside: async (paths, signal) => {
             if (lexicalOnly || paths.length === 0)
@@ -1038,13 +1122,38 @@ function createCanonicalReadBoundary(env, readRoots) {
             const roots = await canonicalRoots(signal);
             for (const p of paths) {
                 const real = await resolve(p, signal);
-                if (real === undefined || !withinAnyRoot(roots, real))
+                if (real === undefined || (!real.exact && real.missing !== true))
+                    return false;
+                if (!withinAnyRoot(roots, real.value))
                     return false;
             }
             return true;
         },
     };
 }
+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);
@@ -1054,11 +1163,14 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
     const readsOnlyEngineOverflowSpool = async (verdict) => {
         if (verdict.outOfRootRead !== true)
             return false;
+        if ((verdict.unresolvedOperands ?? []).length > 0)
+            return false;
         const paths = verdict.outOfRootPaths ?? [];
         if (paths.length === 0)
             return false;
-        for (const p of paths) {
-            if (!(await overflowSpoolFence(p)))
+        for (const p of [...paths, ...(verdict.outOfRootSpellings ?? [])]) {
+            const real = await canonicalBoundary.canonicalOf(p);
+            if (!(await overflowSpoolFence(real ?? p)))
                 return false;
         }
         return true;
@@ -1071,7 +1183,7 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
             "operators (pipes, redirects, ;, &&, command substitution, subshells) are rejected and only " +
             "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). " +
-            (isRemoteExecutionEnv(env) ? "" : "A path that leads outside via a symlink counts as outside, including one a glob pattern expands to. ") +
+            (boundaryIsTheSandbox(env) ? "" : "A path that leads outside via a symlink counts as outside, including one a glob pattern expands to. ") +
             "Still subject to the deployment's approval policy.",
         parameters: Type.Object({
             command: Type.String({ description: "A single allowlisted read-only command (no shell operators)." }),
@@ -1087,21 +1199,17 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
                 return errorResult(`Error (Bash): ${reason}`);
             const boundary = classifySimpleCommandReadBoundary(command, { roots: readRoots, cwd: rootCanonical });
             if (boundary.reason !== undefined) {
-                const rescued = boundary.outOfRootRead === true && (await canonicalBoundary.allResolveInside(boundary.outOfRootPaths ?? [], ctx.signal));
+                const rescueCandidates = [...(boundary.outOfRootPaths ?? []), ...(boundary.outOfRootSpellings ?? [])];
+                const rescued = boundary.outOfRootRead === true &&
+                    (boundary.unresolvedOperands ?? []).length === 0 &&
+                    (await canonicalBoundary.allResolveInside(rescueCandidates, ctx.signal));
                 if (!rescued && !(await readsOnlyEngineOverflowSpool(boundary))) {
                     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 ?? []), ...(boundary.checkedSpellings ?? [])], patterns: [...(boundary.undecidedPaths ?? []), ...(boundary.undecidedSpellings ?? [])] }, 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.6",
   "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"