@sema-agent/core 7.14.0 → 7.16.0

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

@@ -4,11 +4,11 @@ import { type CwdRef } from "./fs-shared.js";
 import type { ReversibilityVerdict } from "../../core/types.js";
 import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
 /**
- * design/80 D-2 (part-1): a parsed-command classifier for the `bash` tool, exposed as a
+ * A parsed-command classifier for the `bash` tool, exposed as a
  * `ToolSpec.reversibilityProbe`. A full shell is treated as egress+irreversible by DEFAULT; this probe is the
- * "real parsed classifier" that lets a deployment safely auto-allow the provably-benign subset (the §4-OQ4
- * doctrine: shell⇒always-gate UNLESS a parsed classifier is wired). design/154 upgraded it from
- * single-command to {@link classifyCompoundReadonly}: a command is reversible ONLY if every `;`/`&&`/`||`/`|`
+ * "real parsed classifier" that lets a deployment safely auto-allow the provably-benign subset (the
+ * doctrine: shell⇒always-gate UNLESS a parsed classifier is wired). It is COMPOUND-aware
+ * ({@link classifyCompoundReadonly}): a command is reversible ONLY if every `;`/`&&`/`||`/`|`
  * connected segment is a bare command (no redirects/substitution/subshells/escapes/`&` anywhere — those
  * whole-string reject, so it can't chain to `curl`/`git push`/`rm` or background past TaskStop) whose
  * `argv[0]` is in the reversible allowlist (default
@@ -23,7 +23,7 @@ import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
  * Wire it on the `bash` tool with `irreversibility: "maybe"` (or via `TaskSpec.shellGate: "classify"`); without
  * a classifier a deployment should mark `bash` `irreversibility: "always"` (`shellGate: "always"`) — fail-closed.
  *
- * RB-412 closed the DATA-side residual named above for the read direction: pass `boundary` and a listed
+ * The DATA-side residual named above is closed for the read direction: pass `boundary` and a listed
  * reader whose path arguments leave the allowed directories stops being reversible, so the gate asks
  * instead of auto-allowing. Pass it as a FUNCTION wherever the working directory is observable (an
  * in-task `cd` moves the base a relative operand resolves against, and the probe is called per command).
@@ -38,7 +38,7 @@ import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
  * safety argument lives on that function). Additive by construction: the plain verdict is tried
  * first and is never overridden.
  *
- * backlog #239 — the RECURSIVE-READ demotion returns a STRUCTURED cause alongside the verdict. That
+ * The RECURSIVE-READ demotion returns a STRUCTURED cause alongside the verdict. That
  * demotion is the one arm whose reason is genuinely unrecoverable downstream: a recursive read is
  * refused for what the traversal REACHES, and the reached set is by definition not in the command text
  * an approval card shows. The cause is minted from the SAME classification pass that produced the
@@ -57,7 +57,48 @@ import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
  */
 export declare function bashReversibilityProbe(allow?: readonly string[], boundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => ReversibilityVerdict;
 /**
- * design/199 D-6 — the FULL shell's contract id, single-sourced: both shell faces share the wire
+ * The READ-BOUNDARY seat of the full shell: a `ToolSpec.reversibilityProbe` that answers exactly ONE
+ * question — does the deployment's read boundary object to where this command reads? — and nothing about
+ * the command's shape. It is the shell face of the rule every read face obeys: the structured readers
+ * (Read/Grep/Glob) refuse a deny-listed or out-of-root target; the shell reader gets a MANDATED ask for the
+ * same target. The engine installs it on Bash and Monitor whenever a real writable shell is mounted and the
+ * shellGate doctrine adds no residual-risk classifier of its own (`shellGate:"off"`, the default); under
+ * `"classify"` the doctrine installs {@link bashReversibilityProbe} instead, which composes THIS judgment
+ * with the read-only shape classifier, and under `"always"` the tier itself is the mandate and no probe runs.
+ * The boundary is therefore judged under every doctrine; the doctrine decides only what happens to the
+ * residual shell risk.
+ *
+ * The verdict, in the probe vocabulary the gate reads (`reversible` here means "the boundary raised no
+ * question — the seat vouches the call may run"):
+ *  · the boundary DECLARED an objection — a deny-listed operand, a recursive walk under the deny judge, an
+ *    operand outside the roots — ⇒ `{ reversible: false, mandated: true }` (+ the recursive-reach `cause`);
+ *  · the boundary could NOT READ where the command reads — an unexpanded glob operand (the compound face
+ *    reports it as undecided), a `~`-rooted operand with no home declared, a working-directory move the walk
+ *    cannot model — ⇒ `{ reversible: false }` (fail-closed; a plain ask, which a stored allow rule may retire —
+ *    the seat did not declare anything, it declined to guess);
+ *  · otherwise ⇒ `{ reversible: true }`. This includes every command whose SHAPE the read faces refuse whole
+ *    (an unlisted program, a redirection, a substitution, a segment that is not a reader): those shapes carry
+ *    no read-face verdict, so this seat has no question to ask — the residual is the doctrine's, and under
+ *    `"off"` the doctrine asks nothing. `run_in_background` is likewise not this seat's question (it changes
+ *    WHEN the command runs, never WHERE it reads).
+ *
+ * Reach = the read faces' reach, and nothing wider: the compound face walks the operands of a command whose
+ * every segment is a listed reader, and the bounded poll-loop face walks a loop body of listed readers. A
+ * read hidden in a shape the faces refuse whole (`cat x | <unlisted>`, `$(cat x)`, `cat $DIR/x`, a launcher
+ * `env cat x`, a path-prefixed `/bin/cat x`) is not seen here — deny-listed or out-of-root alike — exactly
+ * the shapes the `"classify"` doctrine exists to ask about. The text-level containment gate the classify
+ * seat consults on its demotion arms is deliberately not consulted here ({@link boundaryDeclared}: it may
+ * add a mandate to an ask, never originate one). The poll-loop face reports its refusal as one sentence,
+ * so the boundary's share of it is read by removing the boundary's judging seats
+ * ({@link pollLoopBoundaryVerdict}).
+ *
+ * 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.
+ */
+export declare function bashReadBoundaryProbe(boundary: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => ReversibilityVerdict;
+/**
+ * The FULL shell's contract id, single-sourced: both shell faces share the wire
  * name "Bash", so this id is the ONE structural discriminator between the write-capable shell and
  * the read-only allowlist face (`core.bash_readonly@1`). Consumed by prepare-task's
  * fullShellReachable roster assertion (its first load-bearing consumer).
@@ -66,36 +107,36 @@ export { FULL_SHELL_CONTRACT_ID } from "../../core/tool-catalog-entries.js";
 /** The CC-verbatim exit-1 interpretation for `command`, or undefined when exit 1 means a real error.
  *  Conservative parse: last `;`/`&&`/`||`/newline statement → last `|` pipeline segment → leading
  *  command name (env-assignments skipped, path prefix stripped); `git grep`/`git diff` special-cased
- *  (CC cLp). Exported for the 批④ unit tests. */
+ *  (CC `cLp`). Exported for its unit tests. */
 export declare function bashExitOneInterpretation(command: string): string | undefined;
 export declare function canAutoBackground(command: string, depth?: number): boolean;
 /**
  * `bash` (effect:write) — a full shell. ⚠️ It runs with `rootCanonical` as the initial cwd but is NOT
  * sandboxed: a command can `cd` out, read/write/delete any path the process can reach, and use the
- * network. `rootPath` is a file-tool guard rail, NOT a bash sandbox (design/44 §5, DESIGN#6) — real
- * isolation is the deployment's job (inject a chroot/container `ExecutionEnv`). Every call still goes
- * through the design/37 policy gate, which a multi-tenant deployment MUST wire to constrain it. The cwd
- * persists across calls (design/64 §8.1A): a per-task `cwdRef` starts at `rootCanonical` and is updated
+ * network. `rootPath` is a file-tool guard rail, NOT a bash sandbox — real isolation is the
+ * deployment's job (inject a chroot/container `ExecutionEnv`). Every call still goes through the
+ * tool-policy gate, which a multi-tenant deployment MUST wire to constrain it. The cwd
+ * persists across calls: a per-task `cwdRef` starts at `rootCanonical` and is updated
  * from the shell's final pwd after each command.
  */
 export declare function createBashTool(env: ExecutionEnv, rootCanonical: string, coAuthor?: string | false, cwdRef?: CwdRef, taskOpts?: {
     taskRegistry?: TaskRegistry;
     taskOwner?: string;
     taskScope?: string;
-    /** (design/129, mirrors MonitorToolOptions.sessionId): when the task runs INSIDE a session,
+    /** (mirrors MonitorToolOptions.sessionId): when the task runs INSIDE a session,
      *  a background command registers session-resident (owner = sessionId, sessionScoped flag) — it
      *  survives the run teardown like CC's bg shells and is reaped at the session terminal. Absent ⇒
      *  run-scoped registration exactly as before (killed-with-receipt at teardown). */
     sessionId?: string;
-    /** design/116 §7 G2b: completion-notification sink — a finished background command fires ONE
+    /** Completion-notification sink — a finished background command fires ONE
      *  task-notification (priority "next": boundary interrupt, CC LocalShellTask posture). */
     onTaskNotification?: (n: import("../../core/task-notification.js").TaskNotificationPayload, opts?: {
         priority?: "now" | "next" | "later";
     }) => void;
-    /** design/116 detach: per-tool-call detach hub — a fired signal adopts the running command as background. */
+    /** Per-tool-call detach hub — a fired signal adopts the running command as background. */
     detachHub?: import("../../core/tool-detach.js").ToolDetachHub;
     /**
-     * RB-198 F1 (CC 220 `Zry`/`WZi.#m` parity) — EXPLICIT deployment opt-in: on this command's own
+     * EXPLICIT deployment opt-in: on this command's own
      * timeout, an eligible foreground command (see `canAutoBackground`'s own docstring — a
      * DELIBERATELY simplified, narrower-than-CC classifier) is adopted as a background task instead
      * of being killed. Defaults to `false` (the pre-existing, unconditional kill-on-timeout behavior)
@@ -110,7 +151,7 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
      */
     autoBackgroundOnTimeout?: boolean;
     /**
-     * RB-220 — mirrors {@link import("../../core/types.js").TaskSpec.oneShot}: this run has no later
+     * Mirrors {@link import("../../core/types.js").TaskSpec.oneShot}: this run has no later
      * turn for an async background notification to land in (a headless `-p` process exits once the
      * turn ends). Branches the background-launch receipt's guidance toward an active block-wait
      * instruction instead of "you will be notified — do not poll", the same failure form
@@ -119,18 +160,18 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
      */
     oneShot?: boolean;
     /**
-     * RB-371 ②: the EXTRA containment roots of the structured file tools (additionalDirectories,
+     * The EXTRA containment roots of the structured file tools (additionalDirectories,
      * canonical) — combined with `rootCanonical` and consulted ONLY for the post-`cd` disclosure
      * note (a committed cwd outside every root gets one trailer line saying the structured tools'
      * relative paths now resolve there and may be refused). Bash itself stays deliberately
      * unconfined; passing this never gates anything.
      */
     additionalRoots?: readonly string[];
-    /** RB-370 ② (cli): override of the `timeout` parameter's DEFAULT budget, in ms — see
+    /** 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). */
     bashDefaultTimeoutMs?: number;
-    /** RB-370 ② (cli): override of the `timeout` parameter's engine CEILING, in ms — only-widen
+    /** Override of the `timeout` parameter's engine CEILING, in ms — only-widen
      *  vs the resolved default; see {@link import("./index.js").HandsToolkitOptions.bashMaxTimeoutMs}. */
     bashMaxTimeoutMs?: number;
     /** Structured sink for this leg's timeout-cap discard announcements — consumed by
@@ -138,36 +179,36 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
      *  {@link import("./index.js").HandsToolkitOptions.onNotice} for the replace-vs-warn contract). */
     onNotice?: (n: import("../../core/types.js").EngineNotice) => void;
     /**
-     * #181-F6 — whether the Monitor tool is on THIS run's roster (the Runner's own mount predicate is
+     * Whether the Monitor tool is on THIS run's roster (the Runner's own mount predicate is
      * `backgroundTaskToolsActive`; it, not this tool, mounts Monitor). Read by the SR-2 gh rate-limit
      * hint, whose closing clause teaches the Monitor tool: `false` ⇒ the clause is dropped (the sleep
      * advice stays), absent/`true` ⇒ historic full wording (a standalone toolkit consumer may well have
      * mounted Monitor itself — the omitted default must not silently rewrite its hint).
      */
     monitorToolActive?: boolean;
-    /** design/319 (A ticket) — the session's reminder provenance mark: stamped on the gh rate-limit
+    /** The session's reminder provenance mark: stamped on the gh rate-limit
      *  hint's open tag by the mint home (see {@link import("./index.js").HandsToolkitOptions.reminderMark}).
      *  Absent ⇒ historic bare tag. */
     reminderMark?: string;
 }): AgentTool;
 /**
- * `bash_readonly` (effect:read) — a restricted shell for the verifier read-only boundary (design/44 M2):
- * a single allowlisted, bare command with no shell operators. effect:read lets it survive the verifier's
- * read-only filter, but it is NOT a policy circumvention — it still goes through the design/37 gate (council #7:
- * a read can still be a side channel, e.g. dumping a secret file). The allowlist is a coarse pre-filter;
+ * `bash_readonly` (effect:read) — a restricted shell for the verifier read-only boundary: a single
+ * allowlisted, bare command with no shell operators. effect:read lets it survive the verifier's
+ * read-only filter, but it is NOT a policy circumvention — it still goes through the tool-policy gate,
+ * because a read can still be a side channel (dumping a secret file). The allowlist is a coarse pre-filter;
  * the policy gate is the authoritative control.
  *
- * RB-413 (安全面, adjudicated: hard refusal) — that allowlist vets argv[0] and nothing else, so until this
- * leg carried a path boundary an allowlisted reader could name ANY file on the host and get it: `cat
- * /etc/passwd` went straight through. RB-412 gave the full `bash` leg the same boundary as a DEMOTION —
- * that leg's verdict feeds an approval gate, so "outside the roots" can become a prompt. This face has no
+ * Hard refusal, not a demotion: the allowlist vets argv[0] and nothing else, so without a path
+ * boundary an allowlisted reader could name ANY file on the host and get it (`cat /etc/passwd` would go
+ * straight through). The full `bash` leg carries the same boundary as a DEMOTION — that leg's verdict
+ * feeds an approval gate, so "outside the roots" can become a prompt. This face has no
  * such channel: `effect:"read"` is precisely what lets it run where the write shell may not (the verifier's
  * read-only band), so an out-of-root read here is not something to escalate, it is outside what the tool
  * is. It is refused, fail-closed, before anything executes — including the conservative direction, where
  * the operand cannot be resolved statically (there is nothing to degrade to).
  */
 export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, opts?: {
-    /** RB-370 ② (cli): same timeout-cap overrides the full `bash` leg takes — see
+    /** Same timeout-cap overrides the full `bash` leg takes — see
      *  {@link import("./index.js").HandsToolkitOptions.bashDefaultTimeoutMs} /
      *  {@link import("./index.js").HandsToolkitOptions.bashMaxTimeoutMs} (类修完整域: both foreground
      *  legs share runShell's clamp, so both must share the configurable resolution). */
@@ -176,21 +217,21 @@ export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical:
     /** Structured sink for the timeout-cap discard announcements — same seat the full `bash` leg
      *  takes (both foreground legs share the resolver, so both must share the sink). */
     onNotice?: (n: import("../../core/types.js").EngineNotice) => void;
-    /** RB-413: the extra containment roots the structured file tools got (design/119 `--add-dir`,
+    /** The extra containment roots the structured file tools got (the CC `--add-dir` family,
      *  canonical). A read this deployment already sanctions for Read/Grep/Glob is equally sanctioned
      *  here — the two faces must not disagree about which directories exist for this session. */
     additionalRoots?: readonly string[];
 }): AgentTool;
 /**
- * design/115 P0 `TaskOutput` (legacy aliases: BashOutput/AgentOutput*) — read a background shell's NEW output
+ * `TaskOutput` — read a background shell's NEW output
  * since the last call (cursor), by task_id. Optional legacy `filter` regex is applied BEFORE the per-poll truncation so a watched line survives even when it
  * falls in a high-throughput middle window. Untrusted process output is fenced (delimitUntrusted) — observe-only,
  * never re-fed as instructions.
  */
 export declare function createEnvTaskOutputTool(env: ExecutionEnv): AgentTool;
-/** design/115 P0 `TaskStop` (RB-476-A: legacy aliases cleared) — terminate a background shell by task_id.
+/** `TaskStop` — terminate a background shell by task_id.
  *
- *  design/134 KNOWN-ISSUES close-out: this band kills ENV-DIRECT (it mounts precisely when the toolkit has
+ *  This band kills ENV-DIRECT (it mounts precisely when the toolkit has
  *  no registry — the createHandsToolkit ternary routes registry deployments to createTaskStopTool), so a
  *  row for the SAME shell in the process-local {@link defaultTaskRegistry} (a Runner-mounted run sharing
  *  this env) used to settle via the watcher's no-claimant floor as stoppedBy:"system". The tool now marks

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

@@ -25,40 +25,100 @@ function operandFamily(paths) {
 export function bashReversibilityProbe(allow, boundary) {
     const allowSet = new Set(allow ?? BASH_CLASSIFY_DEFAULT_ALLOW);
     return (args) => {
-        const a = args;
-        const command = a?.command;
-        if (typeof command !== "string")
+        const command = shellCommandOf(args);
+        if (command === undefined)
             return { reversible: false };
         const resolved = typeof boundary === "function" ? boundary() : boundary;
-        const outOfRootGate = () => resolved !== undefined && classifyOutOfRootReadGate(command, allowSet, resolved).gated ? { mandated: true } : {};
-        const boundaryGate = (verdict) => verdict.readDenied === true || (verdict.recursiveReadPaths !== undefined && verdict.recursiveReadPaths.length > 0) ? { mandated: true } : outOfRootGate();
-        const backgrounded = a?.run_in_background === true;
+        const boundaryGate = (verdict) => readBoundaryMandate(command, allowSet, resolved, verdict);
+        const outOfRootGate = () => readBoundaryMandate(command, allowSet, resolved, {});
+        const backgrounded = isBackgroundShellCall(args);
         const detailed = classifyCompoundReadonlyDetailed(command, allowSet, resolved);
         if (backgrounded)
             return { reversible: false, ...boundaryGate(detailed) };
         if (detailed.reason === undefined) {
             if (detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0) {
-                const recursive = detailed.recursiveReadPaths;
-                if (recursive !== undefined && recursive.length > 0) {
-                    const recursiveSet = new Set(recursive);
-                    const others = detailed.undecidedPaths.filter((p) => !recursiveSet.has(p));
-                    return {
-                        reversible: false,
-                        ...boundaryGate(detailed),
-                        cause: {
-                            code: RECURSIVE_READ_CAUSE_CODE,
-                            roots: operandFamily(recursive),
-                            ...(others.length > 0 ? { further: operandFamily(others) } : {}),
-                        },
-                    };
-                }
+                const cause = recursiveReadCause(detailed);
+                if (cause !== undefined)
+                    return { reversible: false, ...boundaryGate(detailed), cause };
                 return { reversible: false, ...outOfRootGate() };
             }
             return { reversible: true };
         }
-        return classifyBoundedReadonlyPollLoop(command, allowSet, resolved) === undefined
-            ? { reversible: true }
-            : { reversible: false, ...boundaryGate(detailed) };
+        const loopRefusal = classifyBoundedReadonlyPollLoop(command, allowSet, resolved);
+        if (loopRefusal === undefined)
+            return { reversible: true };
+        return { reversible: false, ...(pollLoopBoundaryVerdict(command, allowSet, resolved, loopRefusal) === "declared" ? { mandated: true } : boundaryGate(detailed)) };
+    };
+}
+function attributeRefusal(face, resolved, fullRefusal) {
+    if (resolved === undefined)
+        return "shape";
+    const { denyMatch: _deny, ...withoutDenyJudge } = resolved;
+    const opened = face({ ...withoutDenyJudge, face: "open" });
+    if (opened === undefined || opened !== fullRefusal)
+        return "declared";
+    return face(undefined) === opened ? "shape" : "unread";
+}
+function pollLoopBoundaryVerdict(command, allowSet, resolved, fullRefusal) {
+    return attributeRefusal((b) => classifyBoundedReadonlyPollLoop(command, allowSet, b), resolved, fullRefusal);
+}
+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;
+}
+function isBackgroundShellCall(args) {
+    return args?.run_in_background === true;
+}
+function readBoundaryMandate(command, allowSet, resolved, verdict) {
+    if (denyJudgeSpoke(verdict))
+        return { mandated: true };
+    return resolved !== undefined && classifyOutOfRootReadGate(command, allowSet, resolved).gated ? { mandated: true } : {};
+}
+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) } : {}),
+    };
+}
+export function bashReadBoundaryProbe(boundary) {
+    const allowSet = new Set(BASH_CLASSIFY_DEFAULT_ALLOW);
+    return (args) => {
+        const command = shellCommandOf(args);
+        if (command === undefined)
+            return { reversible: false };
+        const resolved = typeof boundary === "function" ? boundary() : boundary;
+        if (resolved === undefined)
+            return { reversible: true };
+        const detailed = classifyCompoundReadonlyDetailed(command, allowSet, resolved);
+        if (boundaryDeclared(detailed)) {
+            const cause = recursiveReadCause(detailed);
+            return { reversible: false, mandated: true, ...(cause !== undefined ? { cause } : {}) };
+        }
+        if (detailed.reason === undefined) {
+            return detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0 ? { reversible: false } : { reversible: true };
+        }
+        const compound = attributeRefusal((b) => classifyCompoundReadonlyDetailed(command, allowSet, b).reason, resolved, detailed.reason);
+        if (compound === "declared")
+            return { reversible: false, mandated: true };
+        if (compound === "unread")
+            return { reversible: false };
+        const loopRefusal = classifyBoundedReadonlyPollLoop(command, allowSet, resolved);
+        if (loopRefusal === undefined)
+            return { reversible: true };
+        const loop = pollLoopBoundaryVerdict(command, allowSet, resolved, loopRefusal);
+        return loop === "shape" ? { reversible: true } : loop === "declared" ? { reversible: false, mandated: true } : { reversible: false };
     };
 }
 export { FULL_SHELL_CONTRACT_ID } from "../../core/tool-catalog-entries.js";
@@ -563,13 +623,10 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
             })),
         }),
         isConcurrencySafe: (args) => {
-            const cmd = args?.command;
-            if (typeof cmd !== "string")
-                return false;
-            const bg = args.run_in_background;
-            if (bg === true)
+            const command = shellCommandOf(args);
+            if (command === undefined || isBackgroundShellCall(args))
                 return false;
-            return coarseReadonlyCheck(cmd, new Set(BASH_READONLY_DEFAULT_ALLOW)) === undefined;
+            return coarseReadonlyCheck(command, new Set(BASH_READONLY_DEFAULT_ALLOW)) === undefined;
         },
         execute: async (args, ctx) => {
             const { command, timeout, run_in_background, description } = args;

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

@@ -4,7 +4,7 @@ import type { ExecutionEnv } from "../../internal/harness-types.js";
 import { type PdfModelCapabilities } from "./pdf.js";
 import { type ReadImageDownsamplerOption } from "./fs-shared.js";
 import { type ReminderDisclosureCounts } from "../../core/reminder-disclosure.js";
-/** design/319 (B ticket) — the Read tool's disclosure state, threaded into the PDF TEXT legs (the
+/** The Read tool's disclosure state, threaded into the PDF TEXT legs (the
  *  two `pdftotext` extraction arms — the only PDF returns with a model-facing text projection of
  *  the document; the native document block and rendered page images have no text to scan). Shares
  *  the Read closure's throttle windows so a PDF and its text read dedup on the same file key. */
@@ -21,7 +21,7 @@ type ReadPdfReturn = string | {
     details: unknown;
 };
 /**
- * PDF read pipeline (CC FileReadTool parity — mechanism取证 + limits in fs/pdf.ts):
+ * PDF read pipeline (CC FileReadTool parity — mechanism + limits in fs/pdf.ts):
  * - no `pages` → whole file as a native `document` block, gated at ≤{@link PDF_TARGET_RAW_SIZE} raw and
  *   ≤{@link PDF_INLINE_PAGE_THRESHOLD} pages (page count via `pdfinfo`, byte-scan fallback; unknown = fail-open,
  *   CC-identical — the size gate still bounds the request);
@@ -30,11 +30,11 @@ type ReadPdfReturn = string | {
  *   degradation with the working alternative, never a fake success.
  * Wire discipline: the base64 payload rides `details.file` only while ≤48K chars (same OMIT rule as the
  * image variant — a bigger card would be dropped whole by the card projector's 4×cap and blind the shell).
- * structured-card audit item B (2026-08-05): that budget management assumed `"document"` was on `CC_DETAIL_TYPES`, which
- * it was not — every `document` card, sized or not, was dropped at the gate, making the 48K rule dead
- * code and the pages/fallback-level disclosure invisible to a host. The word is registered now.
+ * The budget rule only means anything while `"document"` is registered on `CC_DETAIL_TYPES`: without
+ * that word every `document` card, sized or not, is dropped at the gate, which makes the 48K rule dead
+ * code and the pages/fallback-level disclosure invisible to a host.
  *
- * Degradation chain v2 (裁定: the brain-level placeholder is NOT the end state): when the SERVING model
+ * Degradation chain (the brain-level placeholder is NOT the end state): when the SERVING model
  * cannot take a native document block (`caps.document === false` — e.g. any openai-compatible API), the
  * whole-PDF path degrades IN THE TOOL (the only layer holding env.exec), best first:
  *   1. `pdftotext -layout` text extraction → the content arrives as TEXT (Read byte-cap discipline applies);
@@ -42,10 +42,10 @@ type ReadPdfReturn = string | {
  *      pages via the existing `pdftoppm` pipeline (note directs `pages` for more);
  *   3. honest placeholder explaining WHY levels 1–2 did not run + the Bash self-help.
  * Every degraded return carries `details.fallback = { level, reason }` (telemetry on the structured frame).
- * `caps` absent ⇒ fully capable (byte-compat: native document block; the brain placeholder still guards).
+ * `caps` absent ⇒ fully capable (native document block; the brain placeholder still guards).
  */
 export declare function readPdfFile(env: ExecutionEnv, path: string, key: string, pages: string | undefined, signal: AbortSignal | undefined, downsamplerOpt: ReadImageDownsamplerOption, cwd: string, preRead?: Uint8Array, caps?: PdfModelCapabilities, readDeny?: import("./read-deny.js").ReadDenyMatcher, disclosure?: PdfReminderDisclosure): Promise<ReadPdfReturn>;
-/** E1: readPdfFile's own return type stays `ReadPdfReturn` (its INTERNAL string-means-error dispatch
+/** readPdfFile's own return type stays `ReadPdfReturn` (its INTERNAL string-means-error dispatch
  *  contract, shared with pdfPagesToImageBlocks) — the isError flag is applied once, here, at the tool's
  *  actual execute() boundary, not inside the helper. */
 export declare function pdfResultToToolReturn(r: ReadPdfReturn): ReturnType<typeof errorResult> | Exclude<ReadPdfReturn, string>;

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

@@ -5,10 +5,10 @@ import type { CwdRef } from "./fs-shared.js";
 /**
  * The Grep card's details assembly, PURE over the engine text ({mode, offset} from the request) —
  * exported so the text→structured mapping is pinnable with synthetic texts (the byte-truncation and
- * fenced-partial shapes are impractical to construct through a live tool call). #313 moved PATH
- * IDENTITY off the text and onto the engines' served rows (both legs supply them now); the counts
- * and totals below still read the engine's own honesty markers out of the text, which is what keeps
- * this seam the honesty boundary.
+ * fenced-partial shapes are impractical to construct through a live tool call). PATH IDENTITY comes
+ * off the engines' served rows, not the text (both legs supply them); the counts and totals below
+ * still read the engine's own honesty markers out of the text, which is what keeps this seam the
+ * honesty boundary.
  */
 export declare function grepDetailFields(text: string, mode: "files_with_matches" | "content" | "count", offset?: number, structuredRows?: readonly import("./search.js").GrepRow[]): Record<string, unknown>;
 export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ReadFace, cwdRef?: CwdRef): AgentTool;