@sema-agent/core 7.23.3 → 7.23.5

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

@@ -7,14 +7,16 @@ 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 { boundaryIsTheSandbox, canonicalPathIsAuthoritative, 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, inlineUntrusted } from "../../core/untrusted-text.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 { NOT_AUTO_ALLOWED, SHELL_SCAN_DECLINES } from "./bash-program-position.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 { toolFace } from "../../core/tool-catalog-entries.js";
 import { thrownText } from "../../core/thrown-value.js";
 const RECURSIVE_CAUSE_MAX_PATHS = 3;
@@ -34,13 +36,13 @@ export function bashReversibilityProbe(allow, boundary) {
         const backgrounded = isBackgroundShellCall(args);
         const detailed = classifyCompoundReadonlyDetailed(command, allowSet, resolved);
         if (backgrounded)
-            return { reversible: false, ...boundaryGate(detailed) };
+            return { reversible: false, ...boundaryGate(detailed), ...probeAccountOf(command, allowSet, resolved, detailed) };
         if (detailed.reason === undefined) {
             if (boundaryUnread(detailed)) {
-                const cause = recursiveReadCause(detailed);
-                if (cause !== undefined)
-                    return { reversible: false, ...boundaryGate(detailed), cause };
-                return { reversible: false, ...outOfRootGate() };
+                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 };
         }
@@ -50,9 +52,8 @@ export function bashReversibilityProbe(allow, boundary) {
         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, ...seatOffer(loop) };
-        const refusedCause = recursiveReadCause(detailed);
-        return { reversible: false, ...boundaryGate(detailed), ...seatOffer(detailed), ...(refusedCause !== undefined ? { cause: refusedCause } : {}) };
+            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);
@@ -89,8 +90,8 @@ function shellCommandOf(args) {
 function isBackgroundShellCall(args) {
     return args?.run_in_background === true;
 }
-export const BOUNDARY_SEAT_DECLINE_EVIDENCE = new Set(SHELL_SCAN_DECLINES);
-export const CLASSIFY_SEAT_DECLINE_EVIDENCE = new Set();
+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 {};
@@ -98,7 +99,7 @@ function readBoundaryMandate(command, allowSet, resolved, verdict, declineEviden
     if (denyJudgeSpoke(verdict) || unjudgedRead(command, allowSet, resolved, verdict, scan))
         return { mandated: true };
     const named = classifyOutOfRootReadGate(command, allowSet, resolved);
-    if (named.gated || named.denied === true)
+    if (named.gated || named.denied !== undefined)
         return { mandated: true };
     return declinedRung(scan);
 }
@@ -121,7 +122,7 @@ function unjudgedRead(command, allowSet, resolved, verdict, scan) {
     if (resolved === undefined)
         return false;
     const named = classifyOutOfRootReadGate(command, allowSet, resolved);
-    return named.gated || named.denied === true;
+    return named.gated || named.denied !== undefined;
 }
 function recursiveReadCause(detailed) {
     const recursive = detailed.recursiveReadPaths;
@@ -135,17 +136,65 @@ function recursiveReadCause(detailed) {
         ...(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))) {
-                const cause = recursiveReadCause(verdict);
-                return { reversible: false, mandated: true, ...(cause !== undefined ? { cause } : {}) };
+                return { reversible: false, mandated: true, ...probeAccountOf(command, allowSet, resolved, verdict) };
             }
             if (boundaryUndecided(verdict)) {
-                const cause = recursiveReadCause(verdict);
-                return { reversible: false, ...(cause !== undefined ? { cause } : {}) };
+                return { reversible: false, ...probeAccountOf(command, allowSet, resolved, verdict) };
             }
             if (verdict.reason === undefined)
                 return { reversible: true };
@@ -164,7 +213,7 @@ export function bashReadBoundaryProbe(boundary) {
         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 };
+            return { reversible: false, mandated: true, ...probeAccountOf(command, allowSet, resolved, detailed) };
         return compoundVerdict ?? loopVerdict ?? { reversible: true };
     };
     return (args) => {
@@ -762,30 +811,7 @@ 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(bashClassifyDefaultAllow());
-    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)
-            return undefined;
-        const ask = { deny: resolvedBoundary.denyMatch, containment: resolvedBoundary.face !== "open" };
-        if (ask.deny === undefined && !ask.containment)
-            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, ask, signal);
-    };
+    const canonicalEscape = createShellCanonicalRecheck(env, taskOpts.readBoundary);
     return defineTool({
         name: "Bash",
         ...toolFace("bash"),
@@ -1258,13 +1284,15 @@ function createCanonicalReadBoundary(env, readRoots) {
                 if (deny === undefined || denied !== undefined)
                     return false;
                 const folded = normalizeAbsPathLexically(p);
+                if (ask.denyAnswered.has(folded))
+                    return false;
                 const pattern = deny(folded);
                 if (pattern === null)
                     return false;
                 denied = { path: folded, pattern };
                 return true;
             };
-            const judge = async (p, canonicalKnown) => {
+            const judge = async (p, canonicalKnown, origin) => {
                 if (denyHit(p))
                     return;
                 const real = canonicalKnown !== undefined ? { value: canonicalKnown, exact: true } : await resolve(p, signal);
@@ -1279,6 +1307,8 @@ function createCanonicalReadBoundary(env, readRoots) {
                 }
                 if (denyHit(real.value))
                     return;
+                if (ask.containmentAnswered.has(normalizeAbsPathLexically(origin ?? p)))
+                    return;
                 if (ask.containment && !withinAnyRoot(roots, real.value) && !escaping.includes(real.value))
                     escaping.push(real.value);
             };
@@ -1299,7 +1329,7 @@ function createCanonicalReadBoundary(env, readRoots) {
                     for (const t of expanded.paths) {
                         if (denied !== undefined)
                             break;
-                        await judge(t, expanded.canonical.get(t));
+                        await judge(t, expanded.canonical.get(t), p);
                     }
                 }
                 else
@@ -1330,42 +1360,90 @@ function createCanonicalReadBoundary(env, readRoots) {
         },
     };
 }
+const NOTHING_ANSWERED = new Set();
+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) {
-        const content = `Error (Bash): reading "${resolved.denied.path}" is refused: the target matches the sensitive-path ` +
-            `read deny list (pattern "${resolved.denied.pattern}"). This list guards credential-class paths and ` +
-            `applies regardless of the containment roots. ${DENY_REFUSAL_NOTE}`;
-        return errorResult(content, violationDetails({ code: "read_path_denied", message: content, target: resolved.denied.path, pattern: resolved.denied.pattern }));
+        return readDenyRefusal(resolved.denied.path, resolved.denied.pattern, face.tool);
     }
     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: [] });
+        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 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 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 judged this command's written spelling before the call was approved; what the shell " +
-    "would actually read was established only at execution, and a deny-listed read is refused here rather than escalated.";
+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)
@@ -1377,6 +1455,9 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
             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;
         }
@@ -1404,17 +1485,30 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
             const reason = coarseReadonlyCheck(command, allow);
             if (reason)
                 return errorResult(`Error (Bash): ${reason}`);
-            const boundary = classifySimpleCommandReadBoundary(command, { roots: readRoots, cwd: rootCanonical });
+            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 errorResult(`Error (Bash): ${boundary.reason}. ${BASH_READONLY_CONFINEMENT_NOTE}`, { type: "readonly_out_of_root", code: "readonly_out_of_root", paths: boundary.outOfRootPaths ?? [] });
+                    return readContainmentRefusal(`Error (Bash): ${boundary.reason}. ${BASH_READONLY_CONFINEMENT_NOTE}`, boundary.outOfRootPaths ?? []);
                 }
             }
-            const escape = await canonicalEscapeRefusal(canonicalBoundary, { literal: [...(boundary.checkedPaths ?? []), ...(boundary.checkedSpellings ?? [])], patterns: [...(boundary.undecidedPaths ?? []), ...(boundary.undecidedSpellings ?? [])] }, readRoots, READONLY_FACE_ESCAPE_PROSE, { deny: undefined, containment: true }, ctx.signal);
+            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 readOnlyTick = opts?.onToolProgress === undefined ? undefined : (t) => describeSafely(opts.onToolProgress, { toolCallId: ctx.toolCallId, toolName: "Bash", ...t });

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

@@ -46,7 +46,8 @@ export interface HandsToolkitOptions {
      *  (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.
+     *  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.
      *
      *  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

package/dist/tools/fs/index.js

@@ -72,6 +72,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
                 ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
                 ...(opts.onNotice !== undefined ? { onNotice: opts.onNotice } : {}),
                 ...(readFaceRoots !== undefined ? { additionalRoots: readFaceRoots } : {}),
+                readDeny,
                 ...(opts.onToolProgress !== undefined ? { onToolProgress: opts.onToolProgress } : {}),
             })
             : createBashTool(env, rootCanonical, commitCoAuthor, cwdRef, {

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

@@ -61,6 +61,34 @@ export interface ReadDenyMatcher {
      *  matching the deny list exist under the scope and were excluded). */
     readonly rgProbeGlobs: readonly ReadDenyRgGlob[];
 }
+/** The DENY HALF of a shell read boundary, in the shape `BashReadonlyRootBoundary` declares it (structural:
+ *  this module is the leaf every face depends on). `denyMatch` judges one LEXICALLY RESOLVED operand,
+ *  returning the matched pattern or null; PRESENT-IFF there is something to judge. */
+export interface ReadDenySeat {
+    denyMatch?: (resolvedPath: string) => string | null;
+    denyEntries: readonly string[];
+}
+/** The ONE adapter from a compiled matcher to that seat, so every face mounts it the SAME way and the "wire
+ *  the judge only when it has something to judge" rule is spelled once. That rule is load-bearing: the
+ *  seat's PRESENCE is itself read as a fact (the recursive-read demotion mints on "a deny judge is wired" =
+ *  the check a traversal would outflank is in place), so a judge over an EMPTY set must not be wired. Call
+ *  ONCE per mount and reuse the result — the returned closure is then the function OBJECT every face mounted
+ *  from that matcher shares, which makes "the same judge" checkable rather than argued. */
+export declare function readDenySeat(matcher: ReadDenyMatcher | undefined): ReadDenySeat;
+/** The ONE naming of the deny table and the pattern that matched. Every face composes its own SUBJECT and
+ *  VERB in front of it and its own DISPOSITION behind it (the verb is not shared: one face names the
+ *  target, another the REQUESTED SPELLING under a symlink alias). What must not fork is the naming — a
+ *  reader comparing two surfaces about one finding must not be reading two findings. A LIST of patterns is
+ *  the same naming in the plural, for the one finding that names no single row: a traversal that goes PAST
+ *  the judge names the table IN FORCE, never a match it did not make. Four composers: the
+ *  structured read faces' refusal (`safety.ts`), the shell faces' refusal card (`readDenyRefusal`), the
+ *  lexical walk's verdict sentence (`bash-readonly-classifier.ts`), and the full shell's MANDATED ask card,
+ *  which is approvable and so states the finding without claiming a refusal. NOT composers, each stating
+ *  its own fact: the compaction lane's withheld-attachment HTML attribute, and the traversal notes'
+ *  withheld-COUNT lines, which name the table and a pattern LIST. */
+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 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,14 @@
+export function readDenySeat(matcher) {
+    const entries = (matcher?.entries ?? []).map((e) => e.pattern);
+    if (matcher === undefined || entries.length === 0)
+        return { denyEntries: entries };
+    return { denyMatch: (p) => matcher.matchPath(p)?.pattern ?? null, denyEntries: entries };
+}
+export function sensitivePathDenyList(pattern) {
+    const rows = typeof pattern === "string" ? [pattern] : 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 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.d.ts

@@ -1,3 +1,4 @@
+import type { AssertAllKeysHandled } from "../../core/ask-origin.js";
 import type { ExecutionEnv } from "../../internal/harness-types.js";
 import { protectivePathTargetOf, type ToolCallLike } from "../../core/tool-registry.js";
 /**
@@ -320,7 +321,6 @@ export declare const WIN32_NAMESPACE_REFUSAL_TEXT: {
 };
 /** The fence over the text table: `never` while every refusal word has a row. */
 export type NamespaceRefusalTextCoversEveryWord = AssertAllKeysHandled<Exclude<Win32NamespaceRefusal, keyof typeof WIN32_NAMESPACE_REFUSAL_TEXT>>;
-type AssertAllKeysHandled<T extends never> = T;
 /**
  * The Win32 namespace screen — run on every model-spelled target BEFORE the family join, at every site
  * (the fs throat, the effective-target reader, the rule side, the glob splitter), so one spelling is

package/dist/tools/fs/safety.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { sensitivePathDenyList, SENSITIVE_PATH_DENY_SCOPE } 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";
@@ -468,7 +469,7 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
                 ok: false,
                 violation: {
                     code: "read_path_denied",
-                    message: `reading "${path}" ${key !== path ? `(canonical target: "${key}") ` : ""}is refused: ${judged} the sensitive-path read deny list (pattern "${hit.pattern}"). This list guards credential-class paths and applies regardless of the containment roots.`,
+                    message: `reading "${path}" ${key !== path ? `(canonical target: "${key}") ` : ""}is refused: ${judged} ${sensitivePathDenyList(hit.pattern)}. ${SENSITIVE_PATH_DENY_SCOPE}`,
                     target: key,
                     pattern: hit.pattern,
                 },

package/dist/tools/monitor.d.ts

@@ -42,6 +42,7 @@ import type { AgentTool, ExecutionEnv } from "../internal/harness-types.js";
 import { type MonitorTimers, type TaskRegistry } from "../core/task-registry.js";
 import type { TaskNotificationPayload } from "../core/task-notification.js";
 import type { ToolResultStore } from "../core/tool-result-store.js";
+import type { BashReadonlyRootBoundary } from "./fs/bash-readonly-classifier.js";
 export interface MonitorToolOptions {
     registry: TaskRegistry;
     /** Fallbacks when the runtime ctx carries no identity (direct mounts) — same posture as createBashTool. */
@@ -68,6 +69,10 @@ export interface MonitorToolOptions {
      *  task-registry-monitor.ts's spill helper). Absent ⇒ legal degrade, byte-identical rolling (no spill,
      *  same loss shape as before this design). */
     toolResultStore?: ToolResultStore;
+    /** The deployment's shell READ BOUNDARY — the SAME option `createBashTool` takes: this face spawns a
+     *  shell command too, so the seat that judges the WRITTEN spelling needs the leg that re-judges where the
+     *  kernel takes it. BUILT here, so a library mount is not fail-open on one face and closed on the other. */
+    readBoundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined);
     /** RB-465-b (HRD-PTL-3 残件): spec-level retain (`TaskSpec.retainBackgroundProcesses`) — the SECOND
      *  retain lane, OR-composed with the env capability at the teardown sweep. Without this bit the mount
      *  could only see the env lane, so a deployment retaining per spec still got the "session ends it"

package/dist/tools/monitor.js

@@ -3,6 +3,7 @@ import { defineTool, errorResult } from "../core/tools.js";
 import { hasBackgroundShell } from "../core/background-shell.js";
 import { MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, } from "../core/task-registry.js";
 import { toolFace } from "../core/tool-catalog-entries.js";
+import { createShellCanonicalRecheck, MONITOR_ESCAPE_PROSE } from "./fs/fs-bash.js";
 import { thrownText } from "../core/thrown-value.js";
 const MONITOR_DESCRIPTION = "Run a shell command in the background and watch its stdout as a stream of events.\n" +
     "\n" +
@@ -42,6 +43,7 @@ function envBackgroundWallSec(caps, requestedSec) {
     return Math.min(base, cap);
 }
 export function createMonitorTool(env, opts) {
+    const canonicalRecheck = opts.readBoundary === undefined ? undefined : createShellCanonicalRecheck(env, opts.readBoundary, MONITOR_ESCAPE_PROSE);
     return defineTool({
         name: "Monitor",
         ...toolFace("monitor"),
@@ -68,6 +70,11 @@ export function createMonitorTool(env, opts) {
             const isPersistent = persistent === true;
             const timeoutMs = Math.min(MONITOR_MAX_TIMEOUT_MS, Math.max(1, Math.floor(timeout_ms ?? MONITOR_DEFAULT_TIMEOUT_MS)));
             const spawnTimeoutSec = isPersistent ? undefined : Math.ceil(timeoutMs / 1000) + 5;
+            const escape = await canonicalRecheck?.(command, ctx.signal);
+            if (escape !== undefined)
+                return escape;
+            if (ctx.signal?.aborted === true)
+                return errorResult("Error (Monitor): the call was cancelled before the watch started.");
             const spawn = await env.spawnBackground(command, {
                 ...(opts.cwdRef !== undefined ? { cwd: opts.cwdRef.current } : {}),
                 ...(spawnTimeoutSec !== undefined ? { timeout: spawnTimeoutSec } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.23.3",
+  "version": "7.23.5",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",

package/wire-changes/core@7.23.4.json

@@ -0,0 +1,58 @@
+{
+  "repo": "core",
+  "version": "7.23.4",
+  "from": "141b1687631b53cf2998a56c7541bb4aab5ca9af",
+  "to": "v7.23.4",
+  "added": [],
+  "removed": [],
+  "changed": [],
+  "narrowed": [
+    {
+      "id": "F1",
+      "source": "behaviorFlips.summary",
+      "text": "NARROWING, the `bash_readonly` read-only shell face (`handsReadOnly`), deployments with a deny judge wired (#937 = sema-internal #67, P1; stock since design/199 — measured identical on 7.22.0 and 7.23.3): ONE deny judge for every read face. The v1 exception that kept `denyMatch` off the read-only shell face is retired: `readDenySeat()` (`src/tools/fs/read-deny.ts`) is the single adapter from the compiled deny set to a boundary's deny half, mounted by the structured read faces and now by `bash_readonly` at both of its judging moments — the lexical verdict and the execute-time recheck (`src/tools/fs/fs-bash.ts`, `{ deny: denySeat.denyMatch, containment: true }`). One mint for the deny refusal (`readDenyRefusal`) and one for the containment refusal (`readContainmentRefusal`). A containment GRANT (root rescue, overflow-spool recovery) answers containment only, never deny (codex r1/r2). Rules −4. WHO NEEDS IT: a deployment that mounts the read-only shell (server autonomy read-only tier) AND configures `readDenyPatterns` / `READ_DENY_BUILTIN_TIERS` — until now `cat .env` ran there at zero cards with the bytes returned. WHO IS AFFECTED: (a) on that face, a deny-listed read is REFUSED (`read_path_denied`, naming the pattern) — named spelling, glob, symlink target, and a recursive walk that would enter a deny row; (b) a recursive verb (`grep -r <needle> .`) on such a deployment is refused as a whole with the Grep tool named as the way out (KL-937b); (c) a bracket-named glob spelling may over-fire fail-closed (KL-937a). Deployments with no deny judge: byte-identical on this face; the full Bash face: unchanged (contrast column pinned)."
+    }
+  ],
+  "closedSetMembers": [],
+  "closedSetsUnreadable": [],
+  "typeKeys": [
+    {
+      "type": "CompoundReadonlyVerdict",
+      "at": [
+        "src/tools/fs/bash-readonly-classifier.ts:644"
+      ],
+      "added": [
+        "readDeniedPath",
+        "readDeniedPattern"
+      ],
+      "removed": [],
+      "breaking": false,
+      "criteriaCovered": false
+    }
+  ],
+  "declarationMoves": [],
+  "mintMoves": [],
+  "criteriaObserves": [
+    {
+      "kind": "taskEventField",
+      "name": "tool_end.isError",
+      "assertions": [
+        "G1.a",
+        "G1.b"
+      ]
+    }
+  ],
+  "consumersHint": {
+    "cli": [
+      "CompoundReadonlyVerdict"
+    ],
+    "server": [
+      "CompoundReadonlyVerdict"
+    ],
+    "sdk": [],
+    "note": "scanned cli@4e3b6980 server@866e273b sdk@0a6aeb7 — a name listed is MENTIONED there today, which is evidence of consumption, not proof of it"
+  },
+  "breakingCount": 0,
+  "breakingItems": [],
+  "toResolvedAt": "2a5d3b7f6c6d633510d8866e95d66e7b2b85446a"
+}