@sema-agent/core 7.24.3 → 7.25.0

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

@@ -7,82 +7,14 @@ import { RollingTailBuffer } from "../../core/exec-output-tail.js";
 import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, ENV_DIRECT_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "../../core/task-tool-shape.js";
 import { hasBackgroundShell } from "../../core/background-shell.js";
 import { delimitUntrusted } from "../../core/untrusted-text.js";
-import { sliceHeadSafe, sliceTailSafe } from "../../core/surrogate-safe-slice.js";
 import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
-import { imageMagicMatches, normalizeAbsPathLexically, violationDetails, withinAnyRoot } from "./safety.js";
+import { imageMagicMatches, 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, stripCwdSentinel, BASH_READONLY_CONFINEMENT_NOTE, } from "./fs-shared.js";
-import { PROBE_CAUSE_PATH_MAX, PROBE_REASON_MAX, inlineUntrusted } from "../../core/untrusted-text.js";
-import { bashClassifyDefaultAllow, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoopDetailed, classifyCompoundReadonlyDetailed, classifyOutOfRootReadGate, refusedCommandMayRead, classifySimpleCommandReadBoundary, } from "./bash-readonly-classifier.js";
-import { BOUNDARY_SEAT_READS_DECLINE, CLASSIFY_SEAT_READS_DECLINE, NOT_AUTO_ALLOWED, seatDeclineEvidence, } from "./bash-program-position.js";
-import { readDenySeat, sensitivePathDenyList, SENSITIVE_PATH_DENY_SCOPE } from "./read-deny.js";
+import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, shellRecoveryHint, CWD_SENTINEL, stripCwdSentinel, } from "./fs-shared.js";
+import { bashClassifyDefaultAllow, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoopDetailed, classifyCompoundReadonlyDetailed } from "./bash-readonly-classifier.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
 import { thrownText } from "../../core/thrown-value.js";
-const RECURSIVE_CAUSE_MAX_PATHS = 3;
-const RECURSIVE_READ_CAUSE_CODE = "shell.recursive_read_unbounded";
-function operandFamily(paths) {
-    const enc = (s) => s.replace(/%/g, "%25").replace(/;/g, "%3B").replace(/:/g, "%3A");
-    return {
-        shown: paths.slice(0, RECURSIVE_CAUSE_MAX_PATHS).map((p) => enc(inlineUntrusted(p, PROBE_CAUSE_PATH_MAX))),
-        total: paths.length,
-    };
-}
-export function bashReversibilityProbe(allow, boundary) {
-    const allowSet = new Set(allow ?? bashClassifyDefaultAllow());
-    const judge = (args, command, resolved, offers) => {
-        const boundaryGate = (verdict) => readBoundaryMandate(command, allowSet, resolved, verdict, CLASSIFY_SEAT_DECLINE_EVIDENCE);
-        const outOfRootGate = () => readBoundaryMandate(command, allowSet, resolved, {}, CLASSIFY_SEAT_DECLINE_EVIDENCE);
-        const backgrounded = isBackgroundShellCall(args);
-        const detailed = classifyCompoundReadonlyDetailed(command, allowSet, resolved);
-        if (backgrounded)
-            return { reversible: false, ...boundaryGate(detailed), ...probeAccountOf(command, allowSet, resolved, detailed) };
-        if (detailed.reason === undefined) {
-            if (boundaryUnread(detailed)) {
-                const account = probeAccountOf(command, allowSet, resolved, detailed);
-                if (account.cause !== undefined)
-                    return { reversible: false, ...boundaryGate(detailed), ...account };
-                return { reversible: false, ...outOfRootGate(), ...account };
-            }
-            return { reversible: true };
-        }
-        const loop = classifyBoundedReadonlyPollLoopDetailed(command, allowSet, resolved);
-        if (loop.reason === undefined)
-            return { reversible: true };
-        const seatOffer = (verdict) => (offers ? readRootCandidateOf(verdict) : {});
-        const loopScan = refusedCommandScan(command, allowSet, resolved, loop, CLASSIFY_SEAT_DECLINE_EVIDENCE);
-        if (boundaryDeclared(loop) || unjudgedRead(command, allowSet, resolved, loop, loopScan))
-            return { reversible: false, mandated: true, ...probeAccountOf(command, allowSet, resolved, loop), ...seatOffer(loop) };
-        return { reversible: false, ...boundaryGate(detailed), ...seatOffer(detailed), ...probeAccountOf(command, allowSet, resolved, detailed) };
-    };
-    return (args) => {
-        const command = shellCommandOf(args);
-        if (command === undefined)
-            return { reversible: false };
-        const resolved = typeof boundary === "function" ? boundary() : boundary;
-        if (resolved === undefined)
-            return judge(args, command, undefined, true);
-        return grantClearsSeat((c, b, o) => judge(args, c, b, o), command, resolved);
-    };
-}
-function boundaryUnread(verdict) {
-    return boundaryUndecided(verdict) || boundaryUnjudged(verdict);
-}
-function readRootCandidateOf(verdict) {
-    const dir = verdict.outOfRootGrantCandidate;
-    if (dir === undefined)
-        return {};
-    return { readRootCandidate: { dir, clearsThisAsk: true, ...(verdict.outOfRootGrantCoversExactPath === true ? { covers: "exact" } : {}) } };
-}
-function boundaryUndecided(verdict) {
-    return verdict.undecidedPaths !== undefined && verdict.undecidedPaths.length > 0;
-}
-function boundaryDeclared(verdict) {
-    return denyJudgeSpoke(verdict) || verdict.outOfRootRead === true;
-}
-function denyJudgeSpoke(verdict) {
-    return verdict.readDenied === true || (verdict.recursiveReadPaths !== undefined && verdict.recursiveReadPaths.length > 0);
-}
 function shellCommandOf(args) {
     const command = args?.command;
     return typeof command === "string" ? command : undefined;
@@ -90,152 +22,23 @@ function shellCommandOf(args) {
 function isBackgroundShellCall(args) {
     return args?.run_in_background === true;
 }
-export const BOUNDARY_SEAT_DECLINE_EVIDENCE = seatDeclineEvidence(BOUNDARY_SEAT_READS_DECLINE);
-export const CLASSIFY_SEAT_DECLINE_EVIDENCE = seatDeclineEvidence(CLASSIFY_SEAT_READS_DECLINE);
-function readBoundaryMandate(command, allowSet, resolved, verdict, declineEvidence) {
-    if (resolved === undefined)
-        return {};
-    const scan = refusedCommandScan(command, allowSet, resolved, verdict, declineEvidence);
-    if (denyJudgeSpoke(verdict) || unjudgedRead(command, allowSet, resolved, verdict, scan))
-        return { mandated: true };
-    const named = classifyOutOfRootReadGate(command, allowSet, resolved);
-    if (named.gated || named.denied !== undefined)
-        return { mandated: true };
-    return declinedRung(scan);
-}
-function declinedRung(scan) {
-    return scan.declined ? { boundaryDeclined: true } : {};
-}
-function refusedCommandScan(command, allowSet, resolved, verdict, declineEvidence) {
-    return verdict.refusedWhole === true ? refusedCommandMayRead(command, allowSet, resolved, declineEvidence) : { mayRead: false, declined: false };
-}
-function boundaryUnjudged(verdict) {
-    return verdict.refusedWhole === true || (verdict.unresolvedOperands !== undefined && verdict.unresolvedOperands.length > 0);
-}
-function unjudgedRead(command, allowSet, resolved, verdict, scan) {
-    if (verdict.unresolvedOperands !== undefined && verdict.unresolvedOperands.length > 0)
-        return true;
-    if (verdict.refusedWhole !== true)
-        return false;
-    if (scan.mayRead)
-        return true;
-    if (resolved === undefined)
-        return false;
-    const named = classifyOutOfRootReadGate(command, allowSet, resolved);
-    return named.gated || named.denied !== undefined;
-}
-function recursiveReadCause(detailed) {
-    const recursive = detailed.recursiveReadPaths;
-    if (recursive === undefined || recursive.length === 0)
-        return undefined;
-    const recursiveSet = new Set(recursive);
-    const others = (detailed.undecidedPaths ?? []).filter((p) => !recursiveSet.has(p));
-    return {
-        code: RECURSIVE_READ_CAUSE_CODE,
-        roots: operandFamily(recursive),
-        ...(others.length > 0 ? { further: operandFamily(others) } : {}),
-    };
-}
-function denyHitReason(finding) {
-    if (finding === undefined)
-        return {};
-    const { path, pattern } = finding;
-    const composed = (target, pat) => `reading "${target}" matches ${sensitivePathDenyList(pat)}.`;
-    const room = PROBE_REASON_MAX - composed("", "").length;
-    const patternRoom = Math.min(pattern.length, Math.max(Math.floor(room / 2), room - path.length));
-    return { reason: composed(fitMiddle(path, room - patternRoom), fitMiddle(pattern, patternRoom)) };
-}
-export function fitMiddle(s, budget) {
-    return s.length <= budget ? s : elideMiddle(s, budget);
-}
-export function elideMiddle(s, budget) {
-    if (budget < 12)
-        return sliceHeadSafe(s, Math.max(0, budget));
-    const keep = budget - 1;
-    const head = Math.ceil(keep / 2);
-    return `${sliceHeadSafe(s, head)}\u2026${sliceTailSafe(s, keep - head)}`;
-}
-function denyFindingOf(command, allowSet, resolved, verdict) {
-    if (verdict.readDenied === true && verdict.readDeniedPath !== undefined && verdict.readDeniedPattern !== undefined) {
-        return { path: verdict.readDeniedPath, pattern: verdict.readDeniedPattern };
-    }
-    return resolved === undefined ? undefined : classifyOutOfRootReadGate(command, allowSet, resolved).denied;
-}
-function recursiveDenyReason(resolved, verdict) {
-    const roots = verdict.recursiveReadPaths;
-    const entries = resolved?.denyEntries;
-    if (roots === undefined || roots.length === 0 || entries === undefined || entries.length === 0)
-        return {};
-    const composed = (root, rows) => `a recursive read form traverses "${root}", which this walk does not enumerate, past ${sensitivePathDenyList(rows)}.`;
-    const root = roots[0] ?? "";
-    const label = (rows) => rows.length < entries.length ? [...rows, `+${entries.length - rows.length} more`] : rows;
-    let rows = entries.slice(0, MAX_DENY_ROWS_NAMED);
-    while (rows.length > 1 && PROBE_REASON_MAX - composed("", label(rows)).length < MIN_TRAVERSAL_ROOT_ROOM)
-        rows = rows.slice(0, -1);
-    let shown = label(rows);
-    if (PROBE_REASON_MAX - composed("", shown).length < MIN_TRAVERSAL_ROOT_ROOM) {
-        const over = MIN_TRAVERSAL_ROOT_ROOM - (PROBE_REASON_MAX - composed("", shown).length);
-        shown = label([fitMiddle(rows[0] ?? "", Math.max((rows[0] ?? "").length - over, 8))]);
-    }
-    return { reason: composed(fitMiddle(root, Math.max(PROBE_REASON_MAX - composed("", shown).length, 0)), shown) };
-}
-const MAX_DENY_ROWS_NAMED = 3;
-const MIN_TRAVERSAL_ROOT_ROOM = 24;
-function probeAccountOf(command, allowSet, resolved, verdict) {
-    const cause = recursiveReadCause(verdict);
-    const hit = denyHitReason(denyFindingOf(command, allowSet, resolved, verdict));
-    return { ...(hit.reason !== undefined ? hit : recursiveDenyReason(resolved, verdict)), ...(cause !== undefined ? { cause } : {}) };
-}
-export function bashReadBoundaryProbe(boundary) {
-    const allowSet = new Set(bashClassifyDefaultAllow());
-    const judge = (command, resolved, offers) => {
-        const seatVerdict = (verdict) => {
-            if (boundaryDeclared(verdict) || unjudgedRead(command, allowSet, resolved, verdict, refusedCommandScan(command, allowSet, resolved, verdict, BOUNDARY_SEAT_DECLINE_EVIDENCE))) {
-                return { reversible: false, mandated: true, ...probeAccountOf(command, allowSet, resolved, verdict) };
-            }
-            if (boundaryUndecided(verdict)) {
-                return { reversible: false, ...probeAccountOf(command, allowSet, resolved, verdict) };
-            }
-            if (verdict.reason === undefined)
-                return { reversible: true };
-            return undefined;
-        };
-        const detailed = classifyCompoundReadonlyDetailed(command, allowSet, resolved);
-        if (detailed.reason === undefined)
-            return seatVerdict(detailed) ?? { reversible: true };
-        const loop = classifyBoundedReadonlyPollLoopDetailed(command, allowSet, resolved);
-        if (loop.reason === undefined)
-            return seatVerdict(loop) ?? { reversible: true };
-        const compoundVerdict = seatVerdict(detailed);
-        const loopVerdict = seatVerdict(loop);
-        const mandated = [compoundVerdict, loopVerdict].find((verdict) => verdict?.mandated === true);
-        const offerFrom = (verdict) => (offers ? readRootCandidateOf(verdict) : {});
-        if (mandated !== undefined)
-            return { ...mandated, ...offerFrom(detailed), ...offerFrom(loop) };
-        if (readBoundaryMandate(command, allowSet, resolved, detailed, BOUNDARY_SEAT_DECLINE_EVIDENCE).mandated === true)
-            return { reversible: false, mandated: true, ...probeAccountOf(command, allowSet, resolved, detailed) };
-        return compoundVerdict ?? loopVerdict ?? { reversible: true };
-    };
+export function bashReversibilityProbe(allow, boundary) {
+    const allowSet = new Set(allow ?? bashClassifyDefaultAllow());
     return (args) => {
         const command = shellCommandOf(args);
         if (command === undefined)
             return { reversible: false };
-        const resolved = typeof boundary === "function" ? boundary() : boundary;
-        if (resolved === undefined)
+        if (isBackgroundShellCall(args))
+            return { reversible: false };
+        const home = typeof boundary === "function" ? boundary() : boundary;
+        const fold = home?.homeDir !== undefined ? { homeDir: home.homeDir } : undefined;
+        if (classifyCompoundReadonlyDetailed(command, allowSet, fold).reason === undefined)
+            return { reversible: true };
+        if (classifyBoundedReadonlyPollLoopDetailed(command, allowSet, fold).reason === undefined)
             return { reversible: true };
-        return grantClearsSeat(judge, command, resolved);
+        return { reversible: false };
     };
 }
-function grantClearsSeat(judge, command, resolved) {
-    const verdict = judge(command, resolved, true);
-    const dir = verdict.readRootCandidate?.dir;
-    if (dir === undefined)
-        return verdict;
-    if (judge(command, { ...resolved, roots: [...resolved.roots, dir] }, false).reversible)
-        return verdict;
-    const { readRootCandidate: _withdrawn, ...withoutOffer } = verdict;
-    return withoutOffer;
-}
 export { FULL_SHELL_CONTRACT_ID } from "../../core/tool-catalog-entries.js";
 const EXIT1_INTERPRETATION = {
     grep: "No matches found",
@@ -811,7 +614,6 @@ 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 canonicalEscape = createShellCanonicalRecheck(env, taskOpts.readBoundary);
     return defineTool({
         name: "Bash",
         ...toolFace("bash"),
@@ -847,9 +649,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;
+            const refused = await taskOpts.shellReadAdmission?.("Bash", ctx.toolCallId, command, ctx.signal);
+            if (refused !== undefined)
+                return refused;
             if (run_in_background) {
                 if (!hasBackgroundShell(env)) {
                     return errorResult("Error (Bash): this environment does not support background processes (run_in_background).");
@@ -1037,110 +839,10 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
         },
     });
 }
-import { createCanonicalReadBoundary, NOTHING_ANSWERED } from "./shell-read-establish.js";
-export function createShellCanonicalRecheck(env, readBoundary, face) {
-    const recheckReaders = new Set(bashClassifyDefaultAllow());
-    let canonicalForRoots;
-    const canonicalBoundaryFor = (roots) => {
-        const key = roots.join("\u0000");
-        if (canonicalForRoots?.key !== key)
-            canonicalForRoots = { key, boundary: createCanonicalReadBoundary(env, roots) };
-        return canonicalForRoots.boundary;
-    };
-    return async (command, signal) => {
-        const resolvedBoundary = typeof readBoundary === "function" ? readBoundary() : readBoundary;
-        if (resolvedBoundary === undefined)
-            return undefined;
-        const containmentAsked = resolvedBoundary.face !== "open";
-        if (resolvedBoundary.denyMatch === undefined && !containmentAsked)
-            return undefined;
-        const faces = [
-            classifyCompoundReadonlyDetailed(command, recheckReaders, resolvedBoundary),
-            classifyBoundedReadonlyPollLoopDetailed(command, recheckReaders, resolvedBoundary),
-        ];
-        const named = classifyOutOfRootReadGate(command, recheckReaders, resolvedBoundary);
-        const literalAll = [
-            ...new Set([
-                ...faces.flatMap((v) => [...(v.checkedPaths ?? []), ...(v.checkedSpellings ?? []), ...(v.outOfRootPaths ?? [])]),
-                ...named.checked,
-                ...named.paths,
-            ]),
-        ];
-        const folded = (ps) => new Set(ps.map((p) => normalizeAbsPathLexically(p)));
-        const answered = {
-            containment: folded([...faces.flatMap((v) => v.outOfRootPaths ?? []), ...named.paths]),
-            deny: folded([...faces.flatMap((v) => (v.readDeniedPath !== undefined ? [v.readDeniedPath] : [])), ...(named.denied !== undefined ? [named.denied.path] : [])]),
-        };
-        const patterns = [...new Set([...faces.flatMap((v) => [...(v.undecidedPaths ?? []), ...(v.undecidedSpellings ?? [])]), ...named.undecided])];
-        return await canonicalEscapeRefusal(canonicalBoundaryFor(resolvedBoundary.roots), { literal: literalAll, patterns }, resolvedBoundary.roots, face ?? FULL_SHELL_FACE_ESCAPE_PROSE, { deny: resolvedBoundary.denyMatch, containment: containmentAsked, denyAnswered: answered.deny, containmentAnswered: answered.containment }, signal);
-    };
-}
-async function canonicalEscapeRefusal(canonical, candidates, readRoots, face, ask, signal) {
-    const resolved = await canonical.escapesAfterResolution(candidates, ask, signal);
-    if (resolved.denied !== undefined) {
-        return readDenyRefusal(resolved.denied.path, resolved.denied.pattern, face.tool);
-    }
-    if (resolved.unverifiable !== undefined) {
-        return readContainmentRefusal(`Error (${face.tool}): ${resolved.unverifiable}, so this command cannot be confirmed to read only inside the allowed directories for this session: ${readRoots.join(", ")}. ` +
-            face.note);
-    }
-    if (resolved.escaping.length > 0) {
-        const quoted = resolved.escaping.map((p) => `"${p}"`).join(", ");
-        return readContainmentRefusal(`Error (${face.tool}): ${face.subject} resolves through a symlink to ${quoted}, outside the allowed directories for this session: ${readRoots.join(", ")}${face.verdictPhrase}. ` +
-            face.note, resolved.escaping);
-    }
-    return undefined;
-}
-const DENY_REFUSAL_NOTE = "The read boundary judges this command's written spelling and, where a filesystem can be consulted, the " +
-    "paths it would actually read; a deny-listed read is refused here rather than escalated.";
-function readContainmentRefusal(content, paths = []) {
-    return errorResult(content, { type: "readonly_out_of_root", code: "readonly_out_of_root", paths });
-}
-function readDenyRefusal(target, pattern, tool = "Bash") {
-    const content = `Error (${tool}): reading "${target}" is refused: the target matches ${sensitivePathDenyList(pattern)}. ` +
-        `${SENSITIVE_PATH_DENY_SCOPE} ${DENY_REFUSAL_NOTE}`;
-    return errorResult(content, violationDetails({ code: "read_path_denied", message: content, target, pattern }));
-}
-const READONLY_FACE_ESCAPE_PROSE = {
-    tool: "Bash",
-    subject: "a path this command reads",
-    verdictPhrase: ` ${NOT_AUTO_ALLOWED}`,
-    note: BASH_READONLY_CONFINEMENT_NOTE,
-};
-const FULL_SHELL_FACE_ESCAPE_PROSE = {
-    tool: "Bash",
-    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 const MONITOR_ESCAPE_PROSE = { ...FULL_SHELL_FACE_ESCAPE_PROSE, tool: "Monitor" };
 export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
     const timeoutCaps = resolveBashTimeoutCaps(opts);
     const timeoutCapsSecView = bashTimeoutCapsSec(timeoutCaps);
     const sample = [...allow].slice(0, 6).join(", ");
-    const readRoots = [rootCanonical, ...(opts?.additionalRoots ?? [])];
-    const denySeat = readDenySeat(opts?.readDeny);
-    const readBoundary = { roots: readRoots, cwd: rootCanonical, ...denySeat };
-    const overflowSpoolFence = createShellOverflowSpoolFence(env);
-    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, ...(verdict.outOfRootSpellings ?? [])]) {
-            const real = await canonicalBoundary.canonicalOf(p);
-            for (const view of [real, p])
-                if (view !== undefined && denySeat.denyMatch?.(normalizeAbsPathLexically(view)) != null)
-                    return false;
-            if (!(await overflowSpoolFence(real ?? p)))
-                return false;
-        }
-        return true;
-    };
-    const canonicalBoundary = createCanonicalReadBoundary(env, readRoots);
     return defineTool({
         name: "Bash",
         ...toolFace("bash-readonly"),
@@ -1148,7 +850,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). " +
-            (boundaryIsTheSandbox(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 or a recursive read traverses. ") +
             "Still subject to the deployment's approval policy.",
         parameters: Type.Object({
             command: Type.String({ description: "A single allowlisted read-only command (no shell operators)." }),
@@ -1162,32 +864,9 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
             const reason = coarseReadonlyCheck(command, allow);
             if (reason)
                 return errorResult(`Error (Bash): ${reason}`);
-            const boundary = classifySimpleCommandReadBoundary(command, readBoundary);
-            let releasedByGrant = [];
-            if (boundary.readDeniedPath !== undefined && boundary.readDeniedPattern !== undefined)
-                return readDenyRefusal(boundary.readDeniedPath, boundary.readDeniedPattern);
-            const traversal = boundary.recursiveReadPaths ?? [];
-            if (traversal.length > 0) {
-                const shown = traversal.slice(0, RECURSIVE_CAUSE_MAX_PATHS);
-                return readContainmentRefusal(`Error (Bash): this lexical check cannot bound what a recursive read form in this command traverses, and a deny list is in force — ` +
-                    `${traversal.length} path(s) taken as traversal roots: ${shown.join(", ")}${traversal.length > shown.length ? `, and ${traversal.length - shown.length} more` : ""}. ` +
-                    `Use the Grep tool to search a directory tree — it applies the same deny list to every file it reads. ` +
-                    `${BASH_READONLY_CONFINEMENT_NOTE}`);
-            }
-            if (boundary.reason !== undefined) {
-                const rescueCandidates = [...(boundary.outOfRootPaths ?? []), ...(boundary.outOfRootSpellings ?? [])];
-                const rescued = boundary.outOfRootRead === true &&
-                    (boundary.unresolvedOperands ?? []).length === 0 &&
-                    (await canonicalBoundary.allResolveInside(rescueCandidates, ctx.signal));
-                if (rescued)
-                    releasedByGrant = rescueCandidates;
-                if (!rescued && !(await readsOnlyEngineOverflowSpool(boundary))) {
-                    return readContainmentRefusal(`Error (Bash): ${boundary.reason}. ${BASH_READONLY_CONFINEMENT_NOTE}`, boundary.outOfRootPaths ?? []);
-                }
-            }
-            const escape = await canonicalEscapeRefusal(canonicalBoundary, { literal: [...(boundary.checkedPaths ?? []), ...(boundary.checkedSpellings ?? []), ...releasedByGrant], patterns: [...(boundary.undecidedPaths ?? []), ...(boundary.undecidedSpellings ?? [])] }, readRoots, READONLY_FACE_ESCAPE_PROSE, { deny: denySeat.denyMatch, containment: true, denyAnswered: NOTHING_ANSWERED, containmentAnswered: NOTHING_ANSWERED }, ctx.signal);
-            if (escape !== undefined)
-                return escape;
+            const refused = await opts?.shellReadAdmission?.("Bash", ctx.toolCallId, command, ctx.signal);
+            if (refused !== undefined)
+                return refused;
             const readOnlyTick = opts?.onToolProgress === undefined ? undefined : (t) => describeSafely(opts.onToolProgress, { toolCallId: ctx.toolCallId, toolName: "Bash", ...t });
             return await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, true, undefined, readOnlyTick);
         },

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

@@ -11,7 +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";
+import type { ShellReadAdmission } from "./shell-read-check.js";
 export { BASH_CLASSIFY_EXTRA_ALLOW, bashClassifyDefaultAllow } from "./bash-readonly-classifier.js";
 import { type ReadDenyEntry } from "./read-deny.js";
 import { type ContainmentFace } from "./containment-face.js";
@@ -42,19 +42,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: containment from the roots it is confined to, DENY from the same
-     *  compiled table this band hands the structured read faces.
+    /** The gate's shell read station's pre-spawn ADMISSION (`ShellReadAdmission`, shell-read-check.ts), handed to
+     *  BOTH shell faces this band mounts: what a shell tool runs is what the station judged before approval, and
+     *  the admission re-establishes the same candidates right before the spawn. The station itself — ONE parse of
+     *  the command, its candidates established on the filesystem, judged by the read deny seat and the read
+     *  roots — is the gate's (`ToolGateInput.shellReadCheck`, built by the Runner's hands phase for every shell
+     *  face and every doctrine); this band judges nothing on its own.
      *
-     *  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);
+     *  ABSENT ⇒ no station judged this mount (a library-direct toolkit with no gate): the full shell runs
+     *  unconfined as it always did, and `bash_readonly` confines NOTHING — its containment IS the station, so a
+     *  consumer mounting the read-only band outside the Runner must run `runToolGate` with a station of its own
+     *  (`createShellReadStation`). */
+    shellReadAdmission?: ShellReadAdmission;
     /** 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

@@ -11,7 +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 { BASH_READONLY_DEFAULT_ALLOW, } from "./bash-readonly-classifier.js";
+import { BASH_READONLY_DEFAULT_ALLOW } from "./bash-readonly-classifier.js";
 export { BASH_CLASSIFY_EXTRA_ALLOW, bashClassifyDefaultAllow } from "./bash-readonly-classifier.js";
 import { compileReadDeny } from "./read-deny.js";
 import { deploymentFaceClampNotice, resolveContainmentFace } from "./containment-face.js";
@@ -71,8 +71,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
                 ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
                 ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
                 ...(opts.onNotice !== undefined ? { onNotice: opts.onNotice } : {}),
-                ...(readFaceRoots !== undefined ? { additionalRoots: readFaceRoots } : {}),
-                readDeny,
+                ...(opts.shellReadAdmission !== undefined ? { shellReadAdmission: opts.shellReadAdmission } : {}),
                 ...(opts.onToolProgress !== undefined ? { onToolProgress: opts.onToolProgress } : {}),
             })
             : createBashTool(env, rootCanonical, commitCoAuthor, cwdRef, {
@@ -87,7 +86,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
                 ...(opts.queuedHumanInput !== undefined ? { queuedHumanInput: opts.queuedHumanInput } : {}),
                 ...(opts.oneShot !== undefined ? { oneShot: opts.oneShot } : {}),
                 ...(additionalRoots !== undefined ? { additionalRoots } : {}),
-                ...(opts.shellReadBoundary !== undefined ? { readBoundary: opts.shellReadBoundary } : {}),
+                ...(opts.shellReadAdmission !== undefined ? { shellReadAdmission: opts.shellReadAdmission } : {}),
                 ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
                 ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
                 ...(opts.onNotice !== undefined ? { onNotice: opts.onNotice } : {}),

package/dist/tools/fs/read-deny.d.ts

@@ -89,6 +89,31 @@ export declare function readDenySeat(matcher: ReadDenyMatcher | undefined): Read
 export declare function sensitivePathDenyList(pattern: string | readonly string[]): string;
 /** The deny table's REACH: a deny row holds INSIDE the containment roots, so no root grant answers it. */
 export declare const SENSITIVE_PATH_DENY_SCOPE = "This list guards credential-class paths and applies regardless of the containment roots.";
+/**
+ * THE deny refusal sentence — five segments, one mint, every read face: the ACTION, the ABSOLUTE target as the
+ * caller spelled it (with its canonical target in parentheses when the two differ), the DISPOSITION (a deny row is
+ * refused, never escalated), the table BY NAME with the PATTERN verbatim ({@link sensitivePathDenyList}), and
+ * one sentence of why ({@link SENSITIVE_PATH_DENY_SCOPE}). `matchedView` names the view the pattern actually hit
+ * when that is the requested SPELLING rather than the target — under a symlink or case alias the two strings
+ * differ, only one matches, and naming the other sends the reader chasing a path the pattern does not match.
+ * A face prefixes its own `Error (<tool>): ` and may append its own closing clause; the finding itself is
+ * never re-spelled.
+ */
+export declare function readDenySentence(finding: {
+    readonly action?: string;
+    readonly target: string;
+    readonly canonical?: string;
+    readonly pattern: string;
+    readonly matchedView?: string;
+}): string;
+/** The per-part budget of the deny sentence — the gate's own card-account cap, not a second number. */
+export declare const READ_DENY_SENTENCE_PART_MAX = 200;
+/** `s` verbatim when it fits `budget`, else elided in its MIDDLE ({@link elideMiddle}). */
+export declare function fitMiddle(s: string, budget: number): string;
+/** `s` shortened to `budget` by removing its MIDDLE, marked — cut through the repo's surrogate-safe
+ *  primitive, never a raw `slice` (a raw cut leaves half an astral code point on a card and in a durable
+ *  row). Under a dozen characters the HEAD is taken. */
+export declare function elideMiddle(s: string, budget: number): string;
 /**
  * The closed set of built-in tiers. A tier is the deployment's selection unit
  * ({@link ReadDenyBuiltinConfig.tiers}); every {@link READ_FACE_BUILTIN_DENY_TABLE} row belongs to

package/dist/tools/fs/read-deny.js

@@ -1,3 +1,5 @@
+import { sliceHeadSafe, sliceTailSafe } from "../../core/surrogate-safe-slice.js";
+import { PROBE_REASON_MAX } from "../../core/untrusted-text.js";
 export function readDenySeat(matcher) {
     const entries = (matcher?.entries ?? []).map((e) => e.pattern);
     if (matcher === undefined || entries.length === 0)
@@ -9,6 +11,23 @@ export function sensitivePathDenyList(pattern) {
     return `the sensitive-path read deny list (pattern${rows.length === 1 ? "" : "s"} ${rows.map((p) => `"${p}"`).join(", ")})`;
 }
 export const SENSITIVE_PATH_DENY_SCOPE = "This list guards credential-class paths and applies regardless of the containment roots.";
+export function readDenySentence(finding) {
+    const canonicalNote = finding.canonical !== undefined && finding.canonical !== finding.target ? `(canonical target: "${fitMiddle(finding.canonical, READ_DENY_SENTENCE_PART_MAX)}") ` : "";
+    const lexicalHit = finding.matchedView !== undefined && finding.matchedView !== (finding.canonical ?? finding.target);
+    const judged = lexicalHit ? `the requested path's spelling ("${fitMiddle(finding.matchedView, READ_DENY_SENTENCE_PART_MAX)}") matches` : "the target matches";
+    return `${finding.action ?? "reading"} "${fitMiddle(finding.target, READ_DENY_SENTENCE_PART_MAX)}" ${canonicalNote}is refused: ${judged} ${sensitivePathDenyList(fitMiddle(finding.pattern, READ_DENY_SENTENCE_PART_MAX))}. ${SENSITIVE_PATH_DENY_SCOPE}`;
+}
+export const READ_DENY_SENTENCE_PART_MAX = PROBE_REASON_MAX;
+export function fitMiddle(s, budget) {
+    return s.length <= budget ? s : elideMiddle(s, budget);
+}
+export function elideMiddle(s, budget) {
+    if (budget < 12)
+        return sliceHeadSafe(s, Math.max(0, budget));
+    const keep = budget - 1;
+    const head = Math.ceil(keep / 2);
+    return `${sliceHeadSafe(s, head)}\u2026${sliceTailSafe(s, keep - head)}`;
+}
 export const READ_DENY_BUILTIN_TIERS = ["credentials", "shell-history", "browser", "wallet", "agent-config"];
 export const READ_FACE_BUILTIN_DENY_TABLE = [
     { pattern: ".ssh", tier: "credentials" },

package/dist/tools/fs/safety.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { sensitivePathDenyList, SENSITIVE_PATH_DENY_SCOPE } from "./read-deny.js";
+import { readDenySentence } from "./read-deny.js";
 import { sliceHeadSafe } from "../../core/surrogate-safe-slice.js";
 import { pathTargetValue, protectivePathTargetOf } from "../../core/tool-registry.js";
 import { withGateTimeout, DEFAULT_GATE_AWAIT_TIMEOUT_MS } from "../../core/gate-bounded-await.js";
@@ -461,15 +461,11 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
             aliasResolved: canon.aliasResolved === true,
         });
         if (hit !== null) {
-            const lexicalHit = hit.matchedView !== undefined && hit.matchedView !== key;
-            const judged = lexicalHit
-                ? `the requested path's spelling ("${hit.matchedView}") matches`
-                : `the target matches`;
             return {
                 ok: false,
                 violation: {
                     code: "read_path_denied",
-                    message: `reading "${path}" ${key !== path ? `(canonical target: "${key}") ` : ""}is refused: ${judged} ${sensitivePathDenyList(hit.pattern)}. ${SENSITIVE_PATH_DENY_SCOPE}`,
+                    message: readDenySentence({ target: path, canonical: key, pattern: hit.pattern, ...(hit.matchedView !== undefined ? { matchedView: hit.matchedView } : {}) }),
                     target: key,
                     pattern: hit.pattern,
                 },