@sema-agent/core 7.17.3 → 7.17.5

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

@@ -109,7 +109,7 @@ export function splitShellCompoundSegments(source, options) {
     }
     const scanned = options?.trailingTerminator !== "keep" ? source.replace(/;\s*$/, "") : source;
     const segments = [];
-    const pipeFed = [false];
+    const connectors = ["start"];
     const mask = quoteMask(scanned);
     const quoted = (i) => mask.balanced && mask.quoted[i] === true;
     let cur = "";
@@ -122,7 +122,7 @@ export function splitShellCompoundSegments(source, options) {
             if (scanned[i + 1] === "&") {
                 segments.push(cur);
                 cur = "";
-                pipeFed.push(false);
+                connectors.push("&&");
                 i++;
             }
             else
@@ -132,25 +132,25 @@ export function splitShellCompoundSegments(source, options) {
             if (scanned[i + 1] === "|") {
                 segments.push(cur);
                 cur = "";
-                pipeFed.push(false);
+                connectors.push("||");
                 i++;
             }
             else {
                 segments.push(cur);
                 cur = "";
-                pipeFed.push(true);
+                connectors.push("|");
             }
         }
         else if (c === ";") {
             segments.push(cur);
             cur = "";
-            pipeFed.push(false);
+            connectors.push(";");
         }
         else
             cur += c;
     }
     segments.push(cur);
-    return { segments, pipeFed };
+    return { segments, pipeFed: connectors.map((k) => k === "|"), connectors };
 }
 const EXEMPT_REDIRECTION = /^(?:2>\/dev\/null|[12]?>&[12])$/;
 function stripExemptRedirections(command) {
@@ -259,7 +259,8 @@ function tokensMoveBase(toks, allow) {
     const unwrapped = unwrapLauncher(toks.folded.slice(from), allow);
     return unwrapped.kind === "refused" || (unwrapped.kind === "reader" && unwrapped.head === "cd");
 }
-const SHELL_REENTRY_PROGRAM_RE = /^(?:(?:ba|z|da|k|fi)?sh|eval|source|\.)$/;
+const SHELL_REENTRY_PROGRAM_RE = /^(?:(?:ba|z|da|k|fi)?sh|eval|source|\.|parallel)$/;
+const ARGV_REENTRY_PROGRAM_RE = /^xargs$/;
 export function refusedCommandMayRead(command, allow, boundary) {
     return !refusedCommandExempt(command, allow, boundary, 0);
 }
@@ -579,6 +580,8 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
             const unwrapped = unwrapLauncher(toks.slice(i).map(fold), allow);
             if (unwrapped.kind === "refused")
                 return false;
+            if (argvReentryUnjudged(unwrapped))
+                return false;
             if (unwrapped.kind === "unlisted") {
                 if (!unlistedSegmentJudgedInside(toks, i))
                     return false;
@@ -621,18 +624,35 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
     return true;
 }
 function unwrapLauncher(folded, allow) {
+    let argvFromStdin = ARGV_REENTRY_PROGRAM_RE.test(programBasename(folded[0] ?? ""));
+    let lastReentry = argvFromStdin ? 0 : -1;
     for (let i = 1; i < folded.length; i++) {
         const t = folded[i];
-        if (ASSIGNMENT_WORD.test(t) || /^\d+[smhd]?$/.test(t) || COMMAND_LAUNCHERS.has(t))
+        if (ASSIGNMENT_WORD.test(t) || /^\d+[smhd]?$/.test(t))
+            continue;
+        const wordBasename = programBasename(t);
+        if (ARGV_REENTRY_PROGRAM_RE.test(wordBasename)) {
+            argvFromStdin = true;
+            lastReentry = i;
+            continue;
+        }
+        if (COMMAND_LAUNCHERS.has(wordBasename))
             continue;
         if (t.startsWith("-"))
             return { kind: "refused", reason: `"${folded[0]}" is given an option before the program it runs — which program runs is not readable without the launcher's option table ${NOT_AUTO_ALLOWED}` };
-        const head = t.includes("/") ? t.slice(t.lastIndexOf("/") + 1) : t;
+        const head = wordBasename;
         if (SHELL_CONTROL_PREFIXES.has(head) || SHELL_BLOCK_WORDS.has(head))
             return { kind: "refused", reason: `"${folded[0]}" is given shell control syntax ("${head}") where the program it runs would be ${NOT_AUTO_ALLOWED}` };
-        return allow.has(head) || head === "cd" ? { kind: "reader", index: i, head } : { kind: "unlisted", head };
+        return allow.has(head) || head === "cd" ? { kind: "reader", index: i, head, argvFromStdin } : { kind: "unlisted", head, argvFromStdin };
     }
-    return { kind: "unlisted" };
+    return { kind: "unlisted", argvFromStdin, runsDefaultProgram: lastReentry === folded.length - 1 };
+}
+const ARGV_REENTRY_DEFAULT_PROGRAM = "echo";
+function argvReentryUnjudged(unwrapped) {
+    if (!unwrapped.argvFromStdin)
+        return false;
+    const runs = unwrapped.head ?? (unwrapped.runsDefaultProgram === true ? ARGV_REENTRY_DEFAULT_PROGRAM : undefined);
+    return runs === undefined || !NO_PATH_OPERAND_COMMANDS.has(runs);
 }
 function tokenizeSegment(segment) {
     const raw = splitWordsQuoteAware(segment);
@@ -983,13 +1003,14 @@ function isGrepFileStdinLongOption(tok) {
     const name = longOptionNameOf(tok);
     return name !== undefined && isLongOptionAbbrevOf(name, "file");
 }
+const CLUSTER_OPTION_CHAR = /[A-Za-z0-9]/;
 function grepClusterValueOwner(tok) {
-    if (!/^-[A-Za-z]/.test(tok) || tok.startsWith("--"))
+    if (!tok.startsWith("-") || tok.startsWith("--") || !CLUSTER_OPTION_CHAR.test(tok[1] ?? ""))
         return undefined;
     for (const ch of tok.slice(1)) {
         if (ch === "e" || ch === "f")
             return ch;
-        if (!/[A-Za-z]/.test(ch))
+        if (!CLUSTER_OPTION_CHAR.test(ch))
             return undefined;
     }
     return undefined;
@@ -1003,8 +1024,11 @@ function attachedOptionPayloads(tok) {
             out.push(literal(tok.slice(eq + 1)));
         return out;
     }
-    for (let k = 1; k <= tok.length; k++) {
-        if (!/^[A-Za-z]*$/.test(tok.slice(1, k)))
+    const whole = literal(tok.slice(1));
+    if (whole.length > 0 && (isPathShapedToken(whole) || isAbsolutePathForm(whole)))
+        out.push(whole);
+    for (let k = 2; k <= tok.length; k++) {
+        if (![...tok.slice(1, k)].every((ch) => CLUSTER_OPTION_CHAR.test(ch)))
             break;
         const payload = tok.slice(k);
         if (payload.length > 0)
@@ -1020,6 +1044,9 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
     const findings = [];
     const candidates = [];
     const bareWordOperands = [];
+    const judgeOperand = (text, globbed) => {
+        (isPathShapedToken(text) || isAbsolutePathForm(text) ? candidates : bareWordOperands).push({ text, globbed });
+    };
     const positionalOperands = [];
     let stdinOperand = false;
     const argGlobs = (k) => {
@@ -1076,10 +1103,8 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
                 if (name === "grep" && (grepClusterValueOwner(t) === "e" || isGrepPatternPayloadLongOption(t)))
                     continue;
                 if (t.startsWith("-") && t !== "-") {
-                    for (const payload of attachedOptionPayloads(t)) {
-                        if (isAbsolutePathForm(payload) || isPathShapedToken(payload))
-                            candidates.push({ text: payload, globbed: argGlobs(k) });
-                    }
+                    for (const payload of attachedOptionPayloads(t))
+                        judgeOperand(payload, argGlobs(k));
                     continue;
                 }
             }
@@ -1099,10 +1124,7 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
             if (isGrepPatternSlot)
                 continue;
             positionalOperands.push(t);
-            if (isPathShapedToken(t))
-                candidates.push({ text: t, globbed: argGlobs(k) });
-            else
-                bareWordOperands.push({ text: t, globbed: argGlobs(k) });
+            judgeOperand(t, argGlobs(k));
         }
     }
     for (let k = 0; k < args.length; k++) {
@@ -1206,7 +1228,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
     const split = segmentCompoundForReadonly(command, boundary?.homeDir);
     if ("reject" in split)
         return { reason: split.reject, refusedWhole: true };
-    const { segments, pipeFed } = split;
+    const { segments, pipeFed, connectors } = split;
     let nameRefusal;
     const unlistedSegments = new Set();
     const reheaded = new Map();
@@ -1248,6 +1270,9 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
             if (unwrapped.kind === "unlisted" && unwrapped.head !== undefined && SHELL_REENTRY_PROGRAM_RE.test(unwrapped.head)) {
                 return { reason: `"${written}" runs "${unwrapped.head}", which runs its argument as shell text this walk does not judge ${NOT_AUTO_ALLOWED}`, refusedWhole: true };
             }
+            if (argvReentryUnjudged(unwrapped)) {
+                return { reason: `"${written}" takes the operands of the program it runs from its standard input, which this walk does not judge ${NOT_AUTO_ALLOWED}`, refusedWhole: true };
+            }
             if (unwrapped.kind === "unlisted")
                 unlistedSegments.add(si);
             else
@@ -1286,13 +1311,29 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
     };
     const STDIN_FILE_FLOOR = { cat: 1, grep: 2, head: 1, tail: 1, wc: 1, cut: 1, tr: Infinity, diff: 2, cmp: 2, comm: 2, sed: 2 };
     const foldedSegments = [];
+    const foldedReach = [];
+    let crossedAllAnd = true;
+    let crossedAnyOr = false;
     let shapeRefusal = nameRefusal;
     for (let si = 0; si < segments.length; si++) {
+        if (si > 0) {
+            if (connectors[si] !== "&&")
+                crossedAllAnd = false;
+            if (connectors[si] === "||")
+                crossedAnyOr = true;
+        }
+        const moveProvable = pipeFed[si] !== true && pipeFed[si + 1] !== true && reheaded.get(si) === undefined;
+        const pushReach = () => {
+            foldedReach.push({ andJoined: si > 0 && crossedAllAnd, orBroken: !crossedAllAnd && crossedAnyOr, moveProvable });
+            crossedAllAnd = true;
+            crossedAnyOr = false;
+        };
         if (unlistedSegments.has(si)) {
             const unlisted = tokenizeSegment(segments[si]);
             if (unlisted.folded.length === 0)
                 continue;
             foldedSegments.push({ folded: [LAUNCHER_SCAN_HEAD, ...unlisted.folded], raw: [LAUNCHER_SCAN_HEAD, ...unlisted.raw] });
+            pushReach();
             continue;
         }
         const rehead = reheaded.get(si);
@@ -1301,6 +1342,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
         if (toks.length === 0)
             continue;
         foldedSegments.push(segmentTokens);
+        pushReach();
         const name = toks[0];
         const guardReason = guardedVerbFormReason(name, toks, segmentTokens.raw);
         if (guardReason !== undefined) {
@@ -1381,7 +1423,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
             shapeRefusal ??= `multiple directory changes in one command require approval for clarity ${NOT_AUTO_ALLOWED}`;
     }
     if (boundary !== undefined) {
-        const walk = evaluateReadBoundary(foldedSegments, boundary);
+        const walk = evaluateReadBoundary(foldedSegments, boundary, foldedReach);
         if (shapeRefusal === undefined)
             return walk;
         const { reason: _walkSentence, ...structure } = walk;
@@ -1394,7 +1436,9 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
     }
     return {};
 }
-function evaluateReadBoundary(foldedSegments, boundary) {
+const BASE_CANDIDATE_MAX = 256;
+function evaluateReadBoundary(foldedSegments, boundary, reach) {
+    const seen = { outside: new Set(), inside: new Set(), undecided: new Set(), recursive: new Set(), unresolved: new Set() };
     const outside = [];
     const inside = [];
     let unresolvable;
@@ -1402,60 +1446,120 @@ function evaluateReadBoundary(foldedSegments, boundary) {
     let baseLost = false;
     const undecided = [];
     const recursive = [];
-    let currentBase = boundary.cwd ?? boundary.roots[0];
-    for (const toks of foldedSegments) {
+    let candidates = [{ base: boundary.cwd ?? boundary.roots[0], skippedCd: -1 }];
+    let andRunStart = 0;
+    const findingsByWords = new Map();
+    const findingsRowFor = (wordsKey) => {
+        const row = findingsByWords.get(wordsKey);
+        if (row !== undefined)
+            return row;
+        const fresh = new Map();
+        findingsByWords.set(wordsKey, fresh);
+        return fresh;
+    };
+    const findingsFor = (row, toks, base) => {
+        const hit = row.get(base);
+        if (hit !== undefined)
+            return hit;
+        const segBoundary = base === (boundary.cwd ?? boundary.roots[0]) ? boundary : { ...boundary, cwd: base };
+        const computed = collectSegmentBoundaryFindings(toks, segBoundary);
+        row.set(base, computed);
+        return computed;
+    };
+    for (let si = 0; si < foldedSegments.length; si++) {
+        const toks = foldedSegments[si];
         if (baseLost)
             break;
-        const segBoundary = currentBase === (boundary.cwd ?? boundary.roots[0]) ? boundary : { ...boundary, cwd: currentBase };
-        for (const finding of collectSegmentBoundaryFindings(toks, segBoundary)) {
-            if (finding.kind === "unresolvable") {
-                unresolvable ??= finding.reason;
-                if (!unresolved.includes(finding.operand))
-                    unresolved.push(finding.operand);
-                if (toks.folded[0] === "cd")
-                    baseLost = true;
-                continue;
-            }
-            const denied = boundary.denyMatch?.(finding.path);
-            if (denied != null) {
-                return {
-                    reason: `a command operand resolves to "${finding.path}", which matches the sensitive-path read deny list (pattern "${denied}") ${NOT_AUTO_ALLOWED}`,
-                    readDenied: true,
-                };
-            }
-            if (finding.kind === "inside") {
-                if (!inside.includes(finding.path))
-                    inside.push(finding.path);
-                continue;
-            }
-            if (finding.kind === "undecided") {
-                if (!undecided.includes(finding.path))
-                    undecided.push(finding.path);
-                continue;
-            }
-            if (finding.kind === "recursive") {
-                if (!recursive.includes(finding.path))
-                    recursive.push(finding.path);
-                continue;
-            }
-            if (boundary.face === "open") {
-                if (!inside.includes(finding.path))
-                    inside.push(finding.path);
-                continue;
+        if (si > 0 && reach?.[si]?.andJoined !== true)
+            andRunStart = reach?.[si]?.orBroken === true ? si + 1 : si;
+        const reachable = candidates.filter((c) => c.skippedCd < andRunStart);
+        const row = findingsRowFor(JSON.stringify([toks.folded, toks.raw]));
+        for (const { base: currentBase } of reachable) {
+            for (const finding of findingsFor(row, toks, currentBase)) {
+                if (finding.kind === "unresolvable") {
+                    unresolvable ??= finding.reason;
+                    if (!seen.unresolved.has(finding.operand)) {
+                        seen.unresolved.add(finding.operand);
+                        unresolved.push(finding.operand);
+                    }
+                    if (toks.folded[0] === "cd")
+                        baseLost = true;
+                    continue;
+                }
+                const denied = boundary.denyMatch?.(finding.path);
+                if (denied != null) {
+                    return {
+                        reason: `a command operand resolves to "${finding.path}", which matches the sensitive-path read deny list (pattern "${denied}") ${NOT_AUTO_ALLOWED}`,
+                        readDenied: true,
+                    };
+                }
+                if (finding.kind === "inside") {
+                    if (!seen.inside.has(finding.path)) {
+                        seen.inside.add(finding.path);
+                        inside.push(finding.path);
+                    }
+                    continue;
+                }
+                if (finding.kind === "undecided") {
+                    if (!seen.undecided.has(finding.path)) {
+                        seen.undecided.add(finding.path);
+                        undecided.push(finding.path);
+                    }
+                    continue;
+                }
+                if (finding.kind === "recursive") {
+                    if (!seen.recursive.has(finding.path)) {
+                        seen.recursive.add(finding.path);
+                        recursive.push(finding.path);
+                    }
+                    continue;
+                }
+                if (boundary.face === "open") {
+                    if (!seen.inside.has(finding.path)) {
+                        seen.inside.add(finding.path);
+                        inside.push(finding.path);
+                    }
+                    continue;
+                }
+                if (!seen.outside.has(finding.path)) {
+                    seen.outside.add(finding.path);
+                    outside.push(finding);
+                }
             }
-            if (!outside.some((o) => o.path === finding.path))
-                outside.push(finding);
         }
         if (!baseLost && toks.folded[0] === "cd") {
             const cdArgs = toks.folded.slice(1);
             const cdTargetIdx = cdArgs.findIndex((t) => !t.startsWith("-") || t === "-");
             const cdTarget = cdTargetIdx === -1 ? undefined : cdArgs[cdTargetIdx];
             if (cdTarget !== undefined && cdTarget !== "-") {
-                currentBase = resolveOperandLexically(currentBase, cdTarget, boundary.homeDir) ?? currentBase;
+                const provable = reach?.[si]?.moveProvable === true;
+                const branched = [];
+                for (const c of candidates) {
+                    if (c.skippedCd < andRunStart)
+                        branched.push({ base: resolveOperandLexically(c.base, cdTarget, boundary.homeDir) ?? c.base, skippedCd: c.skippedCd });
+                    branched.push({ base: c.base, skippedCd: provable ? si : c.skippedCd });
+                }
+                const byBase = new Map();
+                for (const c of branched) {
+                    const prior = byBase.get(c.base);
+                    if (prior === undefined || c.skippedCd < prior.skippedCd)
+                        byBase.set(c.base, c);
+                }
+                const next = [...byBase.values()];
+                if (next.length > BASE_CANDIDATE_MAX) {
+                    unresolvable ??= `too many directory changes to track where "${cdTarget}" leaves the working directory ${NOT_AUTO_ALLOWED}`;
+                    if (!seen.unresolved.has(cdTarget)) {
+                        seen.unresolved.add(cdTarget);
+                        unresolved.push(cdTarget);
+                    }
+                    baseLost = true;
+                }
+                else
+                    candidates = next;
             }
         }
     }
-    const undecidedAll = [...undecided, ...recursive.filter((p) => !undecided.includes(p))];
+    const undecidedAll = [...undecided, ...recursive.filter((p) => !seen.undecided.has(p))];
     const undecidedField = {
         ...(undecidedAll.length > 0 ? { undecidedPaths: undecidedAll } : {}),
         ...(recursive.length > 0 ? { recursiveReadPaths: recursive } : {}),
@@ -1502,7 +1606,7 @@ const COMMAND_LAUNCHERS = new Set([
     "env", "command", "builtin", "exec", "noglob", "xargs",
     "sudo", "doas", "pkexec", "su", "runuser", "chroot", "setpriv",
     "nohup", "nice", "ionice", "chrt", "taskset", "stdbuf", "timeout", "time", "watch",
-    "setsid", "flock", "unshare", "nsenter", "script", "numactl", "prlimit", "systemd-run", "parallel",
+    "setsid", "flock", "unshare", "nsenter", "script", "numactl", "prlimit", "systemd-run",
     "strace", "ltrace", "valgrind", "firejail", "bwrap",
 ]);
 export const COMMAND_LAUNCHERS_FOR_TEST = COMMAND_LAUNCHERS;
@@ -1522,8 +1626,25 @@ export function classifyOutOfRootReadGate(command, allow, boundary) {
         if ("reject" in split)
             return NOT_GATED;
         const readers = [];
+        const readerReach = [];
+        let crossedAllAnd = true;
+        let crossedAnyOr = false;
         let baseMoved = false;
-        for (const segment of split.segments) {
+        for (let si = 0; si < split.segments.length; si++) {
+            const segment = split.segments[si];
+            if (si > 0) {
+                if (split.connectors[si] !== "&&")
+                    crossedAllAnd = false;
+                if (split.connectors[si] === "||")
+                    crossedAnyOr = true;
+            }
+            const moveProvable = split.pipeFed[si] !== true && split.pipeFed[si + 1] !== true;
+            const pushReader = (st) => {
+                readers.push(st);
+                readerReach.push({ andJoined: si > 0 && crossedAllAnd, orBroken: !crossedAllAnd && crossedAnyOr, moveProvable });
+                crossedAllAnd = true;
+                crossedAnyOr = false;
+            };
             const toks = tokenizeSegment(segment);
             if (toks.folded.length === 0)
                 continue;
@@ -1537,16 +1658,16 @@ export function classifyOutOfRootReadGate(command, allow, boundary) {
             if (UNMODELLED_BASE_MOVERS.has(name))
                 baseMoved = true;
             if (!allow.has(name) && name !== "cd") {
-                readers.push({ folded: [LAUNCHER_SCAN_HEAD, ...toks.folded.slice(i)], raw: [LAUNCHER_SCAN_HEAD, ...toks.raw.slice(i)] });
+                pushReader({ folded: [LAUNCHER_SCAN_HEAD, ...toks.folded.slice(i)], raw: [LAUNCHER_SCAN_HEAD, ...toks.raw.slice(i)] });
                 continue;
             }
-            readers.push(i === 0 && name === written ? toks : { folded: [name, ...toks.folded.slice(i + 1)], raw: [toks.raw[i] ?? name, ...toks.raw.slice(i + 1)] });
+            pushReader(i === 0 && name === written ? toks : { folded: [name, ...toks.folded.slice(i + 1)], raw: [toks.raw[i] ?? name, ...toks.raw.slice(i + 1)] });
         }
         if (readers.length === 0)
             return NOT_GATED;
         if (baseMoved)
             return { gated: true, paths: [] };
-        const verdict = evaluateReadBoundary(readers, containmentOnly);
+        const verdict = evaluateReadBoundary(readers, containmentOnly, readerReach);
         return verdict.outOfRootRead === true ? { gated: true, paths: verdict.outOfRootPaths ?? [] } : NOT_GATED;
     };
     const direct = judge(command);

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

@@ -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 } : {}),