@sema-agent/core 7.15.0 → 7.17.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
@@ -73,24 +73,28 @@ export declare function bashReversibilityProbe(allow?: readonly string[], bounda
  *  · 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);
+ *    reports it as undecided), a `~`-rooted operand under an adapter that declares no home, 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). The engine wires the environment's
+ *    declared home, so `~/x`, `$HOME/x` and `${HOME}/x` RESOLVE and are judged like the absolute spelling;
  *  · 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).
+ *    `"off"` the doctrine asks nothing. A listed reader refused for a PER-SEGMENT shape (follow mode, a device,
+ *    a blocking stdin read) is different: the compound face still walks its operands and carries the boundary's
+ *    structural findings beside the sentence, so `tail -f <denied>` is the declared ask `cat <denied>` is.
+ *    `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
+ * read hidden in a shape the faces refuse whole (`cat x | <unlisted>`, `$(cat x)`, `cat $DIR/x` — a variable other
+ * than the home's own deterministic spellings — 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}).
+ * add a mandate to an ask, never originate one). The poll-loop face's structured verdict
+ * ({@link classifyBoundedReadonlyPollLoopDetailed}) is read the same three ways as the compound face's.
  *
  * 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
@@ -98,7 +102,7 @@ export declare function bashReversibilityProbe(allow?: readonly string[], bounda
  */
 export declare function bashReadBoundaryProbe(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 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).
@@ -107,36 +111,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)
@@ -151,7 +155,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
@@ -160,18 +164,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
@@ -179,36 +183,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). */
@@ -217,21 +221,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

@@ -11,7 +11,7 @@ import { isRemoteExecutionEnv, hasDestroy, isIsolated } from "../../core/remote-
 import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, createShellOverflowSpoolFence, shellRecoveryHint, CWD_SENTINEL, BASH_READONLY_CONFINEMENT_NOTE, } from "./fs-shared.js";
 import { PROBE_CAUSE_PATH_MAX, inlineUntrusted } from "../../core/untrusted-text.js";
-import { BASH_CLASSIFY_DEFAULT_ALLOW, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoop, classifyCompoundReadonlyDetailed, classifyOutOfRootReadGate, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
+import { BASH_CLASSIFY_DEFAULT_ALLOW, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoopDetailed, classifyCompoundReadonlyDetailed, classifyOutOfRootReadGate, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
 const RECURSIVE_CAUSE_MAX_PATHS = 3;
 const RECURSIVE_READ_CAUSE_CODE = "shell.recursive_read_unbounded";
@@ -36,7 +36,7 @@ export function bashReversibilityProbe(allow, boundary) {
         if (backgrounded)
             return { reversible: false, ...boundaryGate(detailed) };
         if (detailed.reason === undefined) {
-            if (detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0) {
+            if (boundaryUnread(detailed)) {
                 const cause = recursiveReadCause(detailed);
                 if (cause !== undefined)
                     return { reversible: false, ...boundaryGate(detailed), cause };
@@ -44,23 +44,16 @@ export function bashReversibilityProbe(allow, boundary) {
             }
             return { reversible: true };
         }
-        const loopRefusal = classifyBoundedReadonlyPollLoop(command, allowSet, resolved);
-        if (loopRefusal === undefined)
+        const loop = classifyBoundedReadonlyPollLoopDetailed(command, allowSet, resolved);
+        if (loop.reason === undefined)
             return { reversible: true };
-        return { reversible: false, ...(pollLoopBoundaryVerdict(command, allowSet, resolved, loopRefusal) === "declared" ? { mandated: true } : boundaryGate(detailed)) };
+        if (boundaryDeclared(loop))
+            return { reversible: false, mandated: true };
+        return { reversible: false, ...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 boundaryUnread(verdict) {
+    return (verdict.undecidedPaths !== undefined && verdict.undecidedPaths.length > 0) || (verdict.unresolvedOperands !== undefined && verdict.unresolvedOperands.length > 0);
 }
 function boundaryDeclared(verdict) {
     return denyJudgeSpoke(verdict) || verdict.outOfRootRead === true;
@@ -106,19 +99,18 @@ export function bashReadBoundaryProbe(boundary) {
             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")
+        if (boundaryUnread(detailed))
             return { reversible: false };
-        const loopRefusal = classifyBoundedReadonlyPollLoop(command, allowSet, resolved);
-        if (loopRefusal === undefined)
+        if (detailed.reason === undefined)
+            return { reversible: true };
+        const loop = classifyBoundedReadonlyPollLoopDetailed(command, allowSet, resolved);
+        if (loop.reason === undefined)
             return { reversible: true };
-        const loop = pollLoopBoundaryVerdict(command, allowSet, resolved, loopRefusal);
-        return loop === "shape" ? { reversible: true } : loop === "declared" ? { reversible: false, mandated: true } : { reversible: false };
+        if (boundaryDeclared(loop))
+            return { reversible: false, mandated: true };
+        if (boundaryUnread(loop))
+            return { reversible: false };
+        return { reversible: true };
     };
 }
 export { FULL_SHELL_CONTRACT_ID } from "../../core/tool-catalog-entries.js";

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;

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

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { resolveKey, violationText, violationDetails } from "./safety.js";
+import { clipSpelling, pathFamilyOf, resolveKey, violationText, violationDetails, WIN32_NAMESPACE_REFUSAL_TEXT } from "./safety.js";
 import { runGrepDetailed, runGlobDetailed, invalidGlobTokens } from "./search.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
 import { pathTargetBaseOf, splitAbsoluteGlobPattern } from "../../core/effective-path-target.js";
@@ -205,7 +205,10 @@ export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, re
             let path = declaredTarget === undefined ? undefined : pathTargetValue(args, declaredTarget);
             const { max_results } = args;
             if (path === undefined) {
-                const split = splitAbsoluteGlobPattern(pattern);
+                const split = splitAbsoluteGlobPattern(pattern, pathFamilyOf({ root: rootCanonical }));
+                if (split !== undefined && "refused" in split) {
+                    return errorResult(`Error (Glob): pattern "${clipSpelling(pattern)}" ${WIN32_NAMESPACE_REFUSAL_TEXT[split.refused]}; refused (${split.refused}).`);
+                }
                 if (split) {
                     path = split.baseDir;
                     pattern = split.relativePattern;