bare-agent 0.54.0 → 0.55.0

package/bareagent.context.md

@@ -425,7 +425,7 @@ naming the opt-in — rather than silently ignoring it. Pass `confirmServer(name
 def) => boolean` to approve each server **before its command is spawned** (return
 `false` to skip it; a throw fails closed). When no `confirmServer` is set, the
 bridge still trusts all *discovered* servers and prints a one-time warning naming
-every command it is about to spawn — `confirmServer` is how you actually *gate* it.
+every server and command it is about to spawn (an arg count only, never arg or env values) — `confirmServer` is how you actually *gate* it.
 
 **RPC timeouts (Unreleased).** Every JSON-RPC round-trip is now bounded, so a
 server that never answers can't hang the bridge or the loop. `opts.timeout`
@@ -435,8 +435,13 @@ timed-out tool call rejects with a labelled `ToolError`
 (`MCP server "s" tool "t" timed out after Nms`, `context: { timeout: true, server, tool, timeoutMs, stderr }` —
 stderr is in `context`, not the message; `wireGate`'s `onToolResult` forwards only the
 non-stderr label fields to the audit row as an allow-listed `errorContext`) rather
-than blocking forever; a server that breaks its stdin pipe surfaces as a
-failed connection, never an uncaught `EPIPE` crash.
+than blocking forever; a handshake timeout (`initialize`/`tools/list`) is labelled the same way
+(`MCP server "s" "method" timed out after Nms`, `context: { timeout: true, server, method, timeoutMs, stderr }`);
+a server that breaks its stdin pipe surfaces as a failed connection, never an uncaught `EPIPE`
+crash; and a server whose `command` cannot start (ENOENT/EACCES, or a sync `spawn()` refusal such as an empty command or NUL byte) rejects with
+`MCP server "s" failed to start: command "<cmd>" (<code>)`, `context: { spawnError: true, server, code }`
+(`code` = Node error code if a string, else `'ESPAWN'`; command only with control chars escaped, never args/env) — `listServerTools` throws it, `allow` mode puts it in `errors` + `missing`,
+bulk mode in `errors` — instead of crashing the host.
 
 ## Wiring with bareguard
 
@@ -1454,6 +1459,8 @@ Mobile tools follow the observe-act pattern: action tools auto-return a fresh sn
 >
 > **Opt-in symlink refusal:** `createShellTools({ noFollowSymlinks: true })` makes `shell_read`, `shell_write`, `shell_edit`, and `shell_grep` refuse to open a path whose **final** path component is a symlink — a file, a dir, or dangling — instead of silently following it. Refusal is a **thrown** error with `err.code === 'ELOOP'` (feeds the Loop's `maxIdenticalToolErrors` guard like any other tool error), and for `shell_write` the link's target is never created or touched. Scope is the final component **only** — a symlinked *parent* directory is not covered (per the canonicalization note above), and neither is the `cwd` option of `shell_run`/`shell_exec` — it only gets `~` expansion, never this flag or `resolveToolPath`'s full canonicalization, so a symlinked `cwd` is always followed. `shell_grep` refuses only a symlinked **root** path loudly, via the same atomic open every other tool uses (open-then-fstat, not a look-then-open `lstat`); a file that turns into a symlink partway through the walk is skipped silently, the same as any other read error. The check is atomic (`O_NOFOLLOW`) on linux/macOS; on Windows, which has no `O_NOFOLLOW`-equivalent open flag, it falls back to a non-atomic `lstat`-then-open check — a symlink planted in that gap slips through. A directory listing (`shell_read` on a dir, `shell_grep`'s root when it's a dir) additionally rechecks the path's `dev`+`ino` against the open handle right after listing — Node has no `fdopendir`, so the listing itself still goes by path, and this narrows (does not close) the window where a directory swapped in between the open and the listing would report a different directory's names; a swap-and-swap-back inside that narrow window still passes undetected. Default `false` — omitting the option is byte-identical to the pre-existing behavior.
 >
+> **Opt-in `canRead` (F259) — closes the root-grep bypass of `fs.deny`.** The Loop `policy` gates `shell_grep` as ONE action on the ROOT path, so `shell_grep` on a repo root walks into paths a gate `fs.deny`s (a direct `shell_read` of them is denied). `createShellTools({ canRead: async (absPath, { isDir, tool }) => boolean })` makes `shell_grep` ask before every directory (`false` prunes the whole subtree, never listed) and every file (`false` skips silently); the root is not passed. Wire bareguard as `canRead: (p, { tool }) => gate.allows({ type: 'read', tool, path: p })`. Unset ⇒ byte-identical; when set the walk runs on the main thread and the worker reads only the allowed list. A throw or non-boolean return rejects the grep (type only in the message), `HaltError` propagates, a non-function `canRead` throws `ValidationError` at creation. `shell_read` on a dir is unaffected (names of one dir, gated on its own path). The grep `timeout` bounds the WHOLE call including the canRead walk (a slow/hung `canRead` rejects with a `canRead walk exceeded` error). TOCTOU: `canRead` vets paths at walk time; a path swapped for a symlink between vetting and the worker's read is followed unless `noFollowSymlinks:true` — pair `canRead` with `noFollowSymlinks:true`. `shell_grep` builds its worker payload from an explicit allow-list: a model-supplied `files` arg is ignored (only the `canRead`-vetted list, set by `grepPath` itself, reaches the worker). A `timeout` above 2^31-1 is clamped to 2^31-1 (Node's timer max); non-finite, zero, negative or non-number values use the 5000ms default. Cost on a 5.4k-file tree: ~2.5s → ~3.7s with a real gate. See `poc/f259-grep-canread.mjs`.
+>
 > **`resolveToolPath(p)`** — exported alongside `createShellTools` from `bare-agent/tools`. THE canonicalizer every shell file tool applies internally before opening: expand `~`/`~/…` via `os.homedir()` (throws rather than silently degrading `~/x` to `/x` when no home directory can be determined), then `path.resolve` against `process.cwd()`. Idempotent; rejects a non-string/empty path (thrown, naming only the type/category of the bad value, never the value itself) — every file tool routes through it, so `shell_read`/`shell_grep` with `""` now error instead of silently reading/searching `process.cwd()`. Call it in your `actionTranslator` on `args.path` before returning the gated action, so the string the gate judges is the exact string the tool opens.
 
 > **⚠️ `shell_write` requires `content` — and a gate cannot cover for it (v0.27+).** `content` used to default to `''`, so a tool call that OMITTED it silently overwrote the target with **zero bytes** and returned `"wrote 0 bytes to <path>"` as success. That is the ordinary shape of a model hitting its **output-token cap** mid-generation on a long file — observed live emptying a 1789-line source file. **No policy can catch it:** a 0-byte write is a *legal* write, and bareguard's `fs` primitive judges `{type:'write', path}` without inspecting the body (the gate correctly `allow`s it). `shell_write` now **rejects** an absent, `null`, or non-string `content` and leaves the file byte-identical; the error tells the model to retry with the full content. An explicit `content: ""` still empties the file — that one is deliberate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "files": [
     "index.js",
     "index.d.ts",

package/primitives.json

@@ -141,7 +141,7 @@
       "category": "tools",
       "when": "you want to give an agent shell/file tools (read, grep, write, edit, run, exec) — cross-platform, pure Node, zero deps",
       "import": "import { createShellTools } from 'bare-agent/tools'",
-      "signature": "createShellTools(options?: {noFollowSymlinks?: boolean}) => {tools: ToolDef[]}",
+      "signature": "createShellTools(options?: {noFollowSymlinks?: boolean, canRead?: CanRead}) => {tools: ToolDef[]}",
       "fails": "never throws at creation; gating is the caller's via Loop({ policy }) and fs.writeScope, shell_edit refuses a non-unique anchor as a tool result (file untouched), and with noFollowSymlinks:true the four file tools throw ELOOP on a symlinked final path component.",
       "example": "const { tools } = createShellTools();\nconst loop = new Loop({ provider, tools, policy });\nconst { tools: safeTools } = createShellTools({ noFollowSymlinks: true });"
     },

package/src/mcp-bridge.js

@@ -231,6 +231,23 @@ function resolveEnv(env) {
 
 // --- JSON-RPC stdio client ---
 
+/**
+ * Labelled spawn-failure error. Names the command ONLY (args/env can carry tokens); control
+ * characters in the command are escaped so a NUL/newline can't corrupt logs. `code` is the Node
+ * error code when it is a string, else 'ESPAWN'.
+ * @param {string} name
+ * @param {any} command
+ * @param {any} err
+ * @returns {ToolError}
+ */
+function spawnFailure(name, command, err) {
+  const code = typeof err?.code === 'string' ? err.code : 'ESPAWN';
+  const shown = String(command).replace(/[\u0000-\u001f\u007f]/g, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+  return new ToolError(`MCP server "${name}" failed to start: command "${shown}" (${code})`, {
+    context: { spawnError: true, server: name, code },
+  });
+}
+
 /**
  * @param {string} name
  * @param {ServerDef} def
@@ -240,11 +257,28 @@ function createRpcClient(name, def) {
   const { command, args = [], env, cwd } = def;
   const mergedEnv = { ...process.env, ...resolveEnv(env) };
 
-  const child = spawn(command, args, {
-    stdio: ['pipe', 'pipe', 'pipe'],
-    env: mergedEnv,
-    ...(cwd && { cwd }),
-  });
+  /** @type {import('node:child_process').ChildProcessWithoutNullStreams} */
+  let child;
+  try {
+    child = spawn(command, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: mergedEnv,
+      ...(cwd && { cwd }),
+    });
+  } catch (err) {
+    // spawn() throws SYNCHRONOUSLY for some bad input (empty command, NUL byte, E2BIG), so no
+    // child 'error' event will ever fire. Same labelled shape as the async path; never the args.
+    // Dead client: rpc() rejects every call; notify() is a no-op; `child` is a minimal stand-in
+    // that killServer() skips (exitCode !== null) — the simplest shape that needs no null-guards
+    // in connectAndListTools / killServer / close().
+    const dead = spawnFailure(name, command, err);
+    return {
+      rpc: () => Promise.reject(dead),
+      notify: () => {},
+      child: /** @type {any} */ ({ exitCode: -1, pid: undefined }),
+      stderr: '',
+    };
+  }
 
   /** @type {Map<number, {resolve: (v: any) => void, reject: (e: any) => void, timer: NodeJS.Timeout | null}>} */
   const pending = new Map();
@@ -297,9 +331,25 @@ function createRpcClient(name, def) {
   // and rpc()/notify() guard writability before writing.
   child.stdin.on('error', () => { /* child gone; surfaced via close + write guards */ });
 
+  // Spawn failure (ENOENT/EACCES/...): with NO 'error' listener Node re-throws it as an uncaught
+  // exception and crashes the HOST. Record it once; it WINS over any later pipe/close error and
+  // rejects every pending and future rpc. Names the command ONLY (args/env can carry tokens).
+  /** @type {ToolError | null} */
+  let spawnErr = null;
+  child.on('error', (err) => {
+    // Only a child that never got a pid is a spawn failure. Node also emits 'error' for a failed
+    // kill() or IPC send on a LIVE child; keep the listener (so it can't crash the host) but do
+    // not mark the server failed — a live server's lifecycle belongs to the 'close' handler.
+    if (child.pid !== undefined || spawnErr) return;
+    spawnErr = spawnFailure(name, command, err);
+    for (const id of [...pending.keys()]) settle(id, false, spawnErr);
+  });
+
   child.on('close', (code) => {
     for (const id of [...pending.keys()]) {
-      settle(id, false, new ToolError(`MCP server "${name}" exited (code ${code}). stderr: ${stderrBuf.slice(-500)}`));
+      // Belt-and-braces: on Node 22 the observed order is error -> EPIPE -> close, so the 'error'
+      // handler has already settled these ids; `spawnErr ||` guards a different ordering elsewhere.
+      settle(id, false, spawnErr || new ToolError(`MCP server "${name}" exited (code ${code}). stderr: ${stderrBuf.slice(-500)}`));
     }
   });
 
@@ -318,6 +368,7 @@ function createRpcClient(name, def) {
   function rpc(method, params = {}, timeoutMs = 0, label) {
     const id = nextId++;
     return new Promise((resolve, reject) => {
+      if (spawnErr) return reject(spawnErr);
       if (!child.stdin.writable) {
         return reject(new ToolError(`MCP server "${name}" stdin is not writable (process exited or pipe closed). stderr: ${stderrBuf.slice(-500)}`));
       }
@@ -331,7 +382,10 @@ function createRpcClient(name, def) {
               { context: { timeout: true, server: label.server, tool: label.tool, timeoutMs, stderr: stderrBuf.slice(-500) } },
             ));
           } else {
-            settle(id, false, new ToolError(`MCP server "${name}" "${method}" timed out after ${timeoutMs}ms. stderr: ${stderrBuf.slice(-500)}`));
+            settle(id, false, new ToolError(
+              `MCP server "${name}" "${method}" timed out after ${timeoutMs}ms`,
+              { context: { timeout: true, server: name, method, timeoutMs, stderr: stderrBuf.slice(-500) } },
+            ));
           }
         }, timeoutMs);
         timer.unref?.();
@@ -340,7 +394,10 @@ function createRpcClient(name, def) {
       const msg = JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n';
       child.stdin.write(msg, (err) => {
         // settle() no-ops if 'close'/timeout already settled this id.
-        if (err) settle(id, false, new ToolError(`MCP server "${name}" write failed: ${err.message}. stderr: ${stderrBuf.slice(-500)}`));
+        // Belt-and-braces (Node 22 order is error -> EPIPE -> close, already settled by 'error').
+        // Deferred a tick: a failed spawn's EPIPE/destroyed-stream callback can land before the
+        // 'error' event; the recorded spawn error must win, so re-check after it has had its turn.
+        if (err) setImmediate(() => settle(id, false, spawnErr || new ToolError(`MCP server "${name}" write failed: ${err.message}. stderr: ${stderrBuf.slice(-500)}`)));
       });
     });
   }
@@ -724,7 +781,8 @@ function makeUnvettedWarner(confirmServer) {
   return (specs) => {
     if (confirmServer || warned || specs.length === 0) return;
     warned = true;
-    const cmds = specs.map(s => `${s.name} → ${s.command} ${(s.args || []).join(' ')}`.trim());
+    // Server name + command ONLY: args/env can carry tokens and stderr lands in logs. A count only.
+    const cmds = specs.map(s => `${s.name} → ${s.command}${s.args && s.args.length ? ` (${s.args.length} args)` : ''}`);
     console.warn(
       `[MCP Bridge] spawning ${specs.length} server command(s) without a confirmServer hook:\n  ` +
       cmds.join('\n  ') +

package/tools/grep-worker.js

@@ -14,7 +14,7 @@ const { _grepCore } = require('./shell.js');
 if (!parentPort) throw new Error('grep-worker.js must be run as a worker thread');
 const port = parentPort;
 
-_grepCore(workerData).then(
+_grepCore(workerData.args, workerData.files).then(
   (result) => port.postMessage({ ok: true, result }),
   (err) => port.postMessage({ ok: false, error: err && err.message ? err.message : String(err) }),
 );

package/tools/shell.d.ts

@@ -1,5 +1,5 @@
 declare namespace _exports {
-    export { GrepArgs, RunArgvArgs, ExecCommandArgs, ToolDef };
+    export { GrepArgs, CanRead, RunArgvArgs, ExecCommandArgs, ToolDef };
 }
 declare namespace _exports {
     export { createShellTools };
@@ -21,7 +21,9 @@ type GrepArgs = {
     /**
      * - Hard wall-clock ceiling in ms (default 5000). The match runs in a
      * worker thread; on overrun the worker is terminated and the call rejects, so a pattern that slips
-     * past `looksCatastrophic` can no longer hang the host event loop.
+     * past `looksCatastrophic` can no longer hang the host event loop. When `canRead` is set it bounds
+     * the WHOLE call, the canRead walk included. Values above 2^31-1 are clamped to 2^31-1 (Node's
+     * timer max); non-finite, zero, negative or absent values use the default.
      */
     timeout?: number | undefined;
     /**
@@ -31,6 +33,10 @@ type GrepArgs = {
      */
     noFollowSymlinks?: boolean | undefined;
 };
+type CanRead = (absPath: string, info: {
+    isDir: boolean;
+    tool: string;
+}) => Promise<boolean> | boolean;
 type RunArgvArgs = {
     argv: string[];
     cwd?: string | undefined;
@@ -50,7 +56,7 @@ type ToolDef = import("../types").ToolDef;
  * Create the six shell tools. Configuration is mostly per-call via tool args; gating is the
  * caller's responsibility via `new Loop({ policy })`.
  *
- * @param {{noFollowSymlinks?: boolean}} [options] - `noFollowSymlinks` (default `false`, byte-
+ * @param {{noFollowSymlinks?: boolean, canRead?: CanRead}} [options] - `noFollowSymlinks` (default `false`, byte-
  *   identical to the pre-existing behavior when omitted): when `true`, `shell_read`, `shell_write`,
  *   `shell_edit`, and `shell_grep` refuse to open a path whose FINAL path component is a symlink
  *   (file, dir, or dangling) — THROWN, `err.code:'ELOOP'`, never a silently-followed link. Scope is
@@ -65,6 +71,20 @@ type ToolDef = import("../types").ToolDef;
  *   not a bug. Set per `createShellTools()` instance, not module-global — safe to mix a
  *   `noFollowSymlinks:true` toolset for one agent alongside a default toolset for another in the same
  *   process.
+ *   `canRead` (opt-in; unset => byte-identical to before): `async (absPath, {isDir, tool}) => boolean`,
+ *   consulted by `shell_grep` for EVERY directory (before descending; `false` prunes the whole subtree,
+ *   never listed) and file (`false` skips it silently) found under a directory root. Closes the
+ *   root-grep bypass of a gate's `fs.deny`: the Loop policy gates only the ROOT path, so a deny on
+ *   `<root>/.secret` is invisible to a grep of `<root>`. The root itself is NOT passed (already
+ *   policy-gated). Wire bareguard as `(p, {tool}) => gate.allows({type:'read', tool, path:p})`. When
+ *   set, the walk runs on the main thread (the gate can't cross into the Worker) and the worker
+ *   receives only the allowed list. Fail-closed LOUD: a throw or non-boolean return rejects the grep
+ *   (type only in the message); `HaltError` propagates as-is. A non-function `canRead` throws
+ *   `ValidationError` at creation. `shell_read` on a directory lists one dir's names and is gated on
+ *   its own path — unaffected. The grep `timeout` bounds the WHOLE call, the canRead walk included (a slow or
+ *   hung `canRead` rejects with a distinct `canRead walk exceeded` error). TOCTOU: `canRead` vets paths at WALK
+ *   time; a path swapped for a symlink between vetting and the worker's read is followed unless
+ *   `noFollowSymlinks:true` — pair `canRead` with `noFollowSymlinks:true`.
  * @returns {{tools: ToolDef[]}}
  * @when you want to give an agent shell/file tools (read, grep, write, edit, run, exec) — cross-platform, pure Node, zero deps
  * @fails never throws at creation; gating is the caller's via Loop({ policy }) and fs.writeScope, shell_edit refuses a non-unique anchor as a tool result (file untouched), and with noFollowSymlinks:true the four file tools throw ELOOP on a symlinked final path component.
@@ -75,6 +95,7 @@ type ToolDef = import("../types").ToolDef;
  */
 declare function createShellTools(options?: {
     noFollowSymlinks?: boolean;
+    canRead?: CanRead;
 }): {
     tools: ToolDef[];
 };
@@ -101,20 +122,6 @@ declare function createShellTools(options?: {
  *   const resolved = resolveToolPath('~/notes.txt');
  */
 declare function resolveToolPath(p: string): string;
-/**
- * @typedef {object} GrepArgs
- * @property {string} pattern
- * @property {string} path
- * @property {boolean} [recursive]
- * @property {number} [maxMatches]
- * @property {string} [flags]
- * @property {number} [timeout] - Hard wall-clock ceiling in ms (default 5000). The match runs in a
- *   worker thread; on overrun the worker is terminated and the call rejects, so a pattern that slips
- *   past `looksCatastrophic` can no longer hang the host event loop.
- * @property {boolean} [noFollowSymlinks] - When true, refuses a symlinked ROOT path (thrown, loud)
- *   and skips (silently, like any other read error) a file that is or becomes a symlink during the
- *   walk. Threaded into `workerData` so the worker thread's file reads honor it too.
- */
 /**
  * The actual search: walk, skip binaries, regex-test each line. Runs in a worker thread (see
  * grep-worker.js) so a runaway regex is killable via `worker.terminate()`. JS RegExp has no
@@ -122,8 +129,10 @@ declare function resolveToolPath(p: string): string;
  * only sound bound (the static `looksCatastrophic` guard is a best-effort fast-reject, not a
  * guarantee; a grounded bypass like `(a|a|a)*` passes it yet backtracks exponentially).
  * @param {GrepArgs} args
+ * @param {string[]} [providedFiles] - INTERNAL, never from tool args: the `canRead`-vetted file list
+ *   (passed by grep-worker.js from its own workerData key, set only by `grepPath`).
  */
-declare function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flags, noFollowSymlinks }: GrepArgs): Promise<{
+declare function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flags, noFollowSymlinks }: GrepArgs, providedFiles?: string[]): Promise<{
     hits: {
         file: string;
         line: number;

package/tools/shell.js

@@ -66,12 +66,14 @@ const os = require('node:os');
 const crypto = require('node:crypto');
 const { exec, execFile } = require('node:child_process');
 const { Worker } = require('node:worker_threads');
+const { HaltError, ValidationError } = require('../src/errors');
 
 const fsConstants = fs.constants;
 
 const DEFAULT_READ_MAX_BYTES = 256 * 1024;       // 256 KB
 const DEFAULT_WRITE_MAX_BYTES = 5 * 1024 * 1024; // 5 MB — a sanity ceiling on a single write (LLM-authored)
 const DEFAULT_GREP_MAX_MATCHES = 200;
+const MAX_TIMER_MS = 2_147_483_647;              // setTimeout's max delay; larger overflows to 1ms
 const DEFAULT_GREP_TIMEOUT_MS = 5_000;           // hard ceiling on a single grep — bounds ReDoS
 const DEFAULT_EXEC_TIMEOUT_MS = 30_000;
 const DEFAULT_EXEC_MAX_BUFFER = 1024 * 1024;     // 1 MB
@@ -583,12 +585,93 @@ function looksCatastrophic(pattern) {
  * @property {string} [flags]
  * @property {number} [timeout] - Hard wall-clock ceiling in ms (default 5000). The match runs in a
  *   worker thread; on overrun the worker is terminated and the call rejects, so a pattern that slips
- *   past `looksCatastrophic` can no longer hang the host event loop.
+ *   past `looksCatastrophic` can no longer hang the host event loop. When `canRead` is set it bounds
+ *   the WHOLE call, the canRead walk included. Values above 2^31-1 are clamped to 2^31-1 (Node's
+ *   timer max); non-finite, zero, negative or absent values use the default.
  * @property {boolean} [noFollowSymlinks] - When true, refuses a symlinked ROOT path (thrown, loud)
  *   and skips (silently, like any other read error) a file that is or becomes a symlink during the
  *   walk. Threaded into `workerData` so the worker thread's file reads honor it too.
  */
 
+/**
+ * @callback CanRead
+ * @param {string} absPath
+ * @param {{isDir: boolean, tool: string}} info
+ * @returns {Promise<boolean>|boolean}
+ */
+
+/**
+ * Ask the caller's `canRead` arbiter about one path. Fail-closed LOUD: a throw or any non-boolean
+ * (truthy objects, undefined, 1, a Promise resolving to 'yes') rejects the whole grep — a broken
+ * arbiter must never read as allow OR as a silent deny. HaltError propagates as-is. Error text names
+ * the tool, the path and the TYPE of a bad value only, never the value.
+ * The call is raced against the remaining whole-call `budget` so a slow or HUNG arbiter cannot
+ * outlive the grep `timeout`.
+ * @param {CanRead} canRead
+ * @param {string} abs
+ * @param {boolean} isDir
+ * @param {{deadline: number, budgetMs: number}} budget
+ * @returns {Promise<boolean>}
+ */
+async function askCanRead(canRead, abs, isDir, budget) {
+  let verdict;
+  /** @type {any} */
+  let timer;
+  try {
+    const remaining = budget.deadline - Date.now();
+    const exhausted = () => Object.assign(
+      new Error(`shell_grep: canRead walk exceeded ${budget.budgetMs}ms time budget — slow or hung canRead. Narrow the root or raise timeout.`),
+      { budgetExceeded: true },
+    );
+    if (remaining <= 0) throw exhausted();
+    verdict = await new Promise((resolve, reject) => {
+      // Ref'd on purpose: a pending call must keep the loop alive to fire the budget; cleared in `finally`.
+      timer = setTimeout(() => reject(exhausted()), remaining);
+      Promise.resolve(canRead(abs, { isDir, tool: 'shell_grep' })).then(resolve, reject);
+    });
+  } catch (/** @type {any} */ err) {
+    if (err instanceof HaltError) throw err;
+    if (err && err.budgetExceeded) throw err;
+    throw new Error(`shell_grep: canRead threw for ${abs} (${err && err.name ? err.name : typeof err})`);
+  } finally {
+    clearTimeout(timer);
+  }
+  if (verdict !== true && verdict !== false) {
+    throw new Error(`shell_grep: canRead returned a non-boolean (${verdict === null ? 'null' : typeof verdict}) for ${abs}`);
+  }
+  return verdict;
+}
+
+/**
+ * Main-thread, gate-vetted walk for `canRead` mode. Same semantics as `walk` (withFileTypes,
+ * symlinks neither dir nor file ⇒ skipped, readdir error ⇒ skip, `recursive:false` honoured) but
+ * each directory is checked BEFORE descent (false ⇒ subtree pruned, never listed) and each file
+ * BEFORE it is listed. The root is not checked (the caller's policy already gated it).
+ * @param {string} dir
+ * @param {boolean} recursive
+ * @param {CanRead} canRead
+ * @param {string[]} out
+ * @param {{deadline: number, budgetMs: number}} budget
+ */
+async function walkChecked(dir, recursive, canRead, out, budget) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!recursive) continue;
+      if (!(await askCanRead(canRead, full, true, budget))) continue;
+      await walkChecked(full, true, canRead, out, budget);
+    } else if (entry.isFile()) {
+      if (await askCanRead(canRead, full, false, budget)) out.push(full);
+    }
+  }
+}
+
 /**
  * The actual search: walk, skip binaries, regex-test each line. Runs in a worker thread (see
  * grep-worker.js) so a runaway regex is killable via `worker.terminate()`. JS RegExp has no
@@ -596,8 +679,10 @@ function looksCatastrophic(pattern) {
  * only sound bound (the static `looksCatastrophic` guard is a best-effort fast-reject, not a
  * guarantee; a grounded bypass like `(a|a|a)*` passes it yet backtracks exponentially).
  * @param {GrepArgs} args
+ * @param {string[]} [providedFiles] - INTERNAL, never from tool args: the `canRead`-vetted file list
+ *   (passed by grep-worker.js from its own workerData key, set only by `grepPath`).
  */
-async function _grepCore({ pattern, path: rawPath, recursive = true, maxMatches, flags = 'i', noFollowSymlinks = false }) {
+async function _grepCore({ pattern, path: rawPath, recursive = true, maxMatches, flags = 'i', noFollowSymlinks = false }, providedFiles) {
   const resolved = resolveToolPath(rawPath);
   const cap = maxMatches || DEFAULT_GREP_MAX_MATCHES;
   let re;
@@ -613,7 +698,10 @@ async function _grepCore({ pattern, path: rawPath, recursive = true, maxMatches,
   if (!stat) throw new Error(`shell_grep: path not found — ${rawPath}`);
 
   const files = [];
-  if (stat.isFile()) {
+  if (Array.isArray(providedFiles)) {
+    // `canRead` mode: the main thread already walked + vetted the tree; read ONLY this list.
+    files.push(...providedFiles);
+  } else if (stat.isFile()) {
     files.push(resolved);
   } else if (stat.isDirectory()) {
     for await (const f of walk(resolved, recursive)) files.push(f);
@@ -655,8 +743,10 @@ async function _grepCore({ pattern, path: rawPath, recursive = true, maxMatches,
  * worker is even spawned — the ONLY loud/thrown refusal in the grep path (per-file skips during
  * the walk happen inside the worker and stay silent, matching the existing read-error `continue`).
  * @param {GrepArgs} args
+ * @param {CanRead} [canRead] - opt-in path arbiter (see `createShellTools`); when set the walk runs here
+ *   on the main thread and the worker receives only the vetted file list.
  */
-async function grepPath(args) {
+async function grepPath(args, canRead) {
   const { pattern, flags = 'i', timeout, path: rawPath, noFollowSymlinks = false } = args;
   if (looksCatastrophic(pattern)) {
     throw new Error(
@@ -696,9 +786,38 @@ async function grepPath(args) {
     }
   }
 
-  const budgetMs = timeout && timeout > 0 ? timeout : DEFAULT_GREP_TIMEOUT_MS;
+  // Explicit allow-list: model-controlled tool args are NEVER spread into the worker payload.
+  const { recursive, maxMatches } = args;
+  const workerArgs = { pattern, path: rawPath, recursive, maxMatches, flags, timeout, noFollowSymlinks };
+  /** @type {string[]|undefined} */
+  let vettedFiles;
+  // ONE budget for the WHOLE call (canRead walk + worker): the deadline starts before the walk.
+  // Node clamps setTimeout delays > 2^31-1 (and NaN/Infinity) to 1ms, so clamp here, at the single source.
+  const budgetMs = typeof timeout === 'number' && Number.isFinite(timeout) && timeout > 0 ? Math.min(timeout, MAX_TIMER_MS) : DEFAULT_GREP_TIMEOUT_MS;
+  const callStart = Date.now();
+  const budget = { deadline: Date.now() + budgetMs, budgetMs };
+  if (canRead) {
+    // The gate cannot cross into the Worker, so the walk runs here. Only a directory root walks; a
+    // missing root / file root falls through to the worker unchanged (root is never passed to canRead).
+    const root = resolveToolPath(rawPath);
+    const st = await fs.stat(root).catch(() => null);
+    if (st && st.isDirectory()) {
+      /** @type {string[]} */
+      const files = [];
+      // Same truthiness as the unset path (`recursive = true` default: undefined => true, other falsy => false).
+      await walkChecked(root, args.recursive === undefined ? true : !!args.recursive, canRead, files, budget);
+      vettedFiles = files;
+    }
+  }
+
+  // The worker gets only what is LEFT of the budget; none left => reject without spawning.
+  const walkMs = Date.now() - callStart;
+  const workerBudgetMs = canRead ? budget.deadline - Date.now() : budgetMs;
+  if (workerBudgetMs <= 0) {
+    throw new Error(`shell_grep: canRead walk exceeded ${budgetMs}ms time budget — no time left to search. Narrow the root or raise timeout.`);
+  }
   return new Promise((resolve, reject) => {
-    const worker = new Worker(path.join(__dirname, 'grep-worker.js'), { workerData: args });
+    const worker = new Worker(path.join(__dirname, 'grep-worker.js'), { workerData: { args: workerArgs, files: vettedFiles } });
     let settled = false;
     const done = (fn, val) => {
       if (settled) return;
@@ -708,11 +827,13 @@ async function grepPath(args) {
       fn(val);
     };
     const timer = setTimeout(() => {
-      done(reject, new Error(
-        `shell_grep: pattern exceeded ${budgetMs}ms time budget — likely catastrophic backtracking. ` +
-        `Simplify the regex.`,
+      done(reject, new Error(canRead
+        ? `shell_grep: exceeded ${budgetMs}ms time budget (shared with the canRead walk, which used ${walkMs}ms) — ` +
+          `a slow canRead or a catastrophic regex; raise timeout or simplify the regex.`
+        : `shell_grep: pattern exceeded ${budgetMs}ms time budget — likely catastrophic backtracking. ` +
+          `Simplify the regex.`,
       ));
-    }, budgetMs);
+    }, workerBudgetMs);
     timer.unref?.();
     worker.once('message', (msg) => {
       if (msg && msg.ok) done(resolve, msg.result);
@@ -818,7 +939,7 @@ function execCommand({ command, cwd, timeout, maxBuffer, env }) {
  * Create the six shell tools. Configuration is mostly per-call via tool args; gating is the
  * caller's responsibility via `new Loop({ policy })`.
  *
- * @param {{noFollowSymlinks?: boolean}} [options] - `noFollowSymlinks` (default `false`, byte-
+ * @param {{noFollowSymlinks?: boolean, canRead?: CanRead}} [options] - `noFollowSymlinks` (default `false`, byte-
  *   identical to the pre-existing behavior when omitted): when `true`, `shell_read`, `shell_write`,
  *   `shell_edit`, and `shell_grep` refuse to open a path whose FINAL path component is a symlink
  *   (file, dir, or dangling) — THROWN, `err.code:'ELOOP'`, never a silently-followed link. Scope is
@@ -833,6 +954,20 @@ function execCommand({ command, cwd, timeout, maxBuffer, env }) {
  *   not a bug. Set per `createShellTools()` instance, not module-global — safe to mix a
  *   `noFollowSymlinks:true` toolset for one agent alongside a default toolset for another in the same
  *   process.
+ *   `canRead` (opt-in; unset => byte-identical to before): `async (absPath, {isDir, tool}) => boolean`,
+ *   consulted by `shell_grep` for EVERY directory (before descending; `false` prunes the whole subtree,
+ *   never listed) and file (`false` skips it silently) found under a directory root. Closes the
+ *   root-grep bypass of a gate's `fs.deny`: the Loop policy gates only the ROOT path, so a deny on
+ *   `<root>/.secret` is invisible to a grep of `<root>`. The root itself is NOT passed (already
+ *   policy-gated). Wire bareguard as `(p, {tool}) => gate.allows({type:'read', tool, path:p})`. When
+ *   set, the walk runs on the main thread (the gate can't cross into the Worker) and the worker
+ *   receives only the allowed list. Fail-closed LOUD: a throw or non-boolean return rejects the grep
+ *   (type only in the message); `HaltError` propagates as-is. A non-function `canRead` throws
+ *   `ValidationError` at creation. `shell_read` on a directory lists one dir's names and is gated on
+ *   its own path — unaffected. The grep `timeout` bounds the WHOLE call, the canRead walk included (a slow or
+ *   hung `canRead` rejects with a distinct `canRead walk exceeded` error). TOCTOU: `canRead` vets paths at WALK
+ *   time; a path swapped for a symlink between vetting and the worker's read is followed unless
+ *   `noFollowSymlinks:true` — pair `canRead` with `noFollowSymlinks:true`.
  * @returns {{tools: ToolDef[]}}
  * @when you want to give an agent shell/file tools (read, grep, write, edit, run, exec) — cross-platform, pure Node, zero deps
  * @fails never throws at creation; gating is the caller's via Loop({ policy }) and fs.writeScope, shell_edit refuses a non-unique anchor as a tool result (file untouched), and with noFollowSymlinks:true the four file tools throw ELOOP on a symlinked final path component.
@@ -842,7 +977,10 @@ function execCommand({ command, cwd, timeout, maxBuffer, env }) {
  *   const { tools: safeTools } = createShellTools({ noFollowSymlinks: true });
  */
 function createShellTools(options = {}) {
-  const { noFollowSymlinks = false } = options;
+  const { noFollowSymlinks = false, canRead } = options;
+  if (canRead !== undefined && typeof canRead !== 'function') {
+    throw new ValidationError(`createShellTools: canRead must be a function (got ${canRead === null ? 'null' : typeof canRead})`);
+  }
   /** @type {ToolDef[]} */
   const tools = [
     {
@@ -873,7 +1011,7 @@ function createShellTools(options = {}) {
         },
         required: ['pattern', 'path'],
       },
-      execute: async (/** @type {GrepArgs} */ args) => grepPath({ ...args, noFollowSymlinks }),
+      execute: async (/** @type {GrepArgs} */ args) => grepPath({ ...args, noFollowSymlinks }, canRead),
     },
     {
       name: 'shell_write',