bare-agent 0.46.6 → 0.47.0

package/bareagent.context.md

@@ -19,7 +19,7 @@ Eight entry points:
 - `require('bare-agent/providers')` — OpenAI, Anthropic, Ollama, CLIPipe, Fallback (the canonical short names; `*Provider` aliases — `OpenAIProvider`, `AnthropicProvider`, etc. — are also exported and match the class names, so either destructure works, v0.12.1+)
 - `require('bare-agent/stores')` — SQLite (FTS5), JsonFile
 - `require('bare-agent/transports')` — JsonlTransport
-- `require('bare-agent/tools')` — createBrowsingTools, createMobileTools, createShellTools, createSpawnTool, createDeferTool, spawnChild, readDeferQueue, liteCtxMcpBridgeConfig
+- `require('bare-agent/tools')` — createBrowsingTools, createMobileTools, createShellTools, resolveToolPath, createSpawnTool, createDeferTool, spawnChild, readDeferQueue, liteCtxMcpBridgeConfig
 - `require('bare-agent/mcp')` — createMCPBridge (returns `tools` + `metaTools`), discoverServers, buildMetaTools
 - `require('bare-agent/bareguard')` — wireGate (one-line bareguard Gate integration), defaultActionTranslator
 
@@ -526,6 +526,8 @@ const { policy, onToolResult } = wireGate(gate, {
 
 `onLlmResult` always uses `{type:'llm'}` regardless of the translator (so budget rules match without translator collusion). `defaultActionTranslator` is exported for composition. **A tool is NOT auto-gated by the fs/bash primitives without this translator** — e.g. `shell_write` runs the write but `fs.writeScope` only enforces once `shell_write` → `{type:'write', path}`; the default `{type:'shell_write'}` matches `tools.allow/denylist` only. Verified live: with the translator, `gate.check` ALLOWs `shell_run ["ls","/tmp"]` and DENYs `shell_read /etc/passwd` (`[deny: fs.readScope]`), and an out-of-scope `shell_write` is denied **before** `execute` (nothing touches disk).
 
+> **Canonicalize the path before the gate sees it.** bareguard's `fs` primitive checks the path you hand it WITHOUT canonicalizing it — a `~`-prefixed or relative `args.path` reads `fs.readScope`/`fs.writeScope` differently than the absolute path the tool actually opens. Call `resolveToolPath` (exported from `bare-agent/tools` alongside `createShellTools`) on `args.path` in the translator — either put the result in an explicit `path` field (as the snippet above's sibling example, `examples/with-bareguard.mjs`, does) or, if relying on bareguard reading `args.path` directly, replace `args.path` with the canonicalized value before returning. Same string in, same string opened.
+
 **Bounding tool rounds — use `limits.maxToolRounds` (bareguard 0.4.2+), not doubled `maxTurns`.** `limits.maxTurns` ticks on every `gate.record` (LLM + tool), so an "N LLM-tool round" cap is `maxTurns: N*2`. `limits.maxToolRounds: N` ticks only on non-`llm` records and gives the natural semantic — pairs cleanly with our split `onLlmResult` / `onToolResult` (the LLM side writes `{type:'llm'}` records which the counter skips). Halt severity, same shape as `maxTurns`, rebuilt from audit on cold-start.
 
 **`HaltError` reachable from the public API (v0.10.1+).** `require('bare-agent').HaltError`, `require('bare-agent/errors').HaltError`. Adopters whose policy shim throws `HaltError` get identity-equal class across module boundaries — Loop's `instanceof HaltError` catches it cleanly.
@@ -1414,6 +1416,12 @@ Mobile tools follow the observe-act pattern: action tools auto-return a fresh sn
 
 **Zero baked-in allowlist.** The library ships the primitives; gating is bareguard's job via the standard `wireGate(gate)` wiring.
 
+> **Path canonicalization + symlink refusal, together.** bareguard's own resolved-path (symlink) containment check is planned for an upcoming release, not yet published; until then the gate matches paths lexically, so a symlinked parent dir is NOT contained even when the link sits inside an allowed scope. bare-agent canonicalizes the path (`~` + resolve, via `resolveToolPath`) before the gate check and opens that same path — this closes a *different* gap (the gate judging a `~`/relative path in a different form than the one the tool opens), not the lexical-match gap above. `noFollowSymlinks` refuses a symlinked final path *component* at open time. Together they narrow but do not close the check-then-open window, and neither covers hardlinks.
+>
+> **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.
+>
+> **`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.
 
 > **`shell_edit` — the surgical write (BA-13).** Changing one line of an 800-line file with `shell_write` forces the model to re-emit **all 800 lines** as tool-call JSON: an output-token tax ∝ file size (output is the expensive token class), paid on every revision, and the maximal broken-tree surface (a truncated rewrite mangles the lines it never meant to touch — the BA-4/BA-6 class). `shell_edit({path, oldText, newText})` emits only the anchor + replacement. Semantics worth knowing: `oldText` must match **exactly once** (a 0/2+ match is a refusal *returned as the tool result*, so the loop continues and the model widens the anchor — not a throw, so a repeated-identical miss is bounded by maxTurns/budget, not the spin guard); missing/empty `oldText` or missing/non-string `newText` **throw** (BA-4 guards; `newText:""` is a legal deletion); the write is **atomic** (sibling temp + rename, mode preserved) so an fs failure never leaves a partial file; and `newText` is a **literal splice** (a `$&`/`$1` in it lands verbatim, unlike `String.replace`). Gate it exactly like `shell_write` but as `{type:'edit'}` — **bareguard gates `edit` by the same `fs.writeScope` as `write` with zero config** (its FS primitive's `FS_TYPES` already includes `edit`).

package/examples/with-bareguard.mjs

@@ -21,7 +21,7 @@ import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const { Loop, wireGate } = require('bare-agent');
 const { OpenAI } = require('bare-agent/providers');
-const { createShellTools } = require('bare-agent/tools');
+const { createShellTools, resolveToolPath } = require('bare-agent/tools');
 
 // 1. Build the gate. Every primitive is optional with sensible defaults.
 const gate = new Gate({
@@ -50,18 +50,25 @@ await gate.init();
 //    primitives: those fire only on `action.type ∈ {bash, read, write, edit}` and read `action.cmd`/`action.path`.
 //    So to make the `bash.allow` + `fs.readScope` config above actually enforce, we MUST translate the shell
 //    tools into those primitive shapes — otherwise the caps are silently dead (relayfact F7/BA-3).
+//
+//    `path` below is `resolveToolPath(args.path)`, not the raw arg: bareguard's fs primitive checks the
+//    path you hand it WITHOUT canonicalizing it, so a `~`-prefixed or relative path would be judged
+//    against `fs.readScope`/`fs.writeScope` in a different form than the one the tool actually opens —
+//    gate string and opened string must be the SAME string. `resolveToolPath` is the one canonicalizer
+//    (expand `~` via os.homedir(), then path.resolve) every shell file tool already applies internally
+//    before opening; calling it here too means the gate sees exactly what gets opened.
 const actionTranslator = (toolName, args, ctx) => {
   switch (toolName) {
     // shell_run is argv (no shell); bareguard's bash.allow matches `cmd.startsWith(prefix)`, so join argv[0..].
     case 'shell_run':  return { type: 'bash', cmd: (args?.argv || []).join(' '), args, _ctx: ctx ?? null };
     case 'shell_exec': return { type: 'bash', cmd: args?.command, args, _ctx: ctx ?? null };
-    // shell_read / shell_grep are reads — gate them through fs.readScope.
+    // shell_read / shell_grep are reads — gate them through fs.readScope, on the canonicalized path.
     case 'shell_read':
-    case 'shell_grep': return { type: 'read', path: args?.path, args, _ctx: ctx ?? null };
+    case 'shell_grep': return { type: 'read', path: resolveToolPath(args?.path), args, _ctx: ctx ?? null };
     // shell_write is a write — gate it through fs.writeScope (add writeScope to the Gate config to enforce).
-    case 'shell_write': return { type: 'write', path: args?.path, args, _ctx: ctx ?? null };
+    case 'shell_write': return { type: 'write', path: resolveToolPath(args?.path), args, _ctx: ctx ?? null };
     // shell_edit is an anchored edit — bareguard gates {type:'edit'} by the SAME fs.writeScope as write.
-    case 'shell_edit':  return { type: 'edit',  path: args?.path, args, _ctx: ctx ?? null };
+    case 'shell_edit':  return { type: 'edit',  path: resolveToolPath(args?.path), args, _ctx: ctx ?? null };
     default:           return { type: toolName, args, _ctx: ctx ?? null };
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.46.6",
+  "version": "0.47.0",
   "files": [
     "index.js",
     "index.d.ts",
@@ -95,7 +95,7 @@
     }
   },
   "scripts": {
-    "test": "node --test test/**/*.test.js",
+    "test": "node --test test/**/*.test.js test/**/*.test.mjs",
     "test:unit": "node --test \"test/!(integration*|*mcp*|spawn*).test.js\"",
     "typecheck": "tsc --noEmit",
     "prebuild:types": "node scripts/clean-types.js",

package/primitives.json

@@ -141,9 +141,9 @@
       "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() => {tools: ToolDef[]}",
-      "fails": "never throws at creation; gating is the caller's via Loop({ policy }) and fs.writeScope, and shell_edit refuses a non-unique anchor as a tool result (file untouched).",
-      "example": "const { tools } = createShellTools();\nconst loop = new Loop({ provider, tools, policy });"
+      "signature": "createShellTools(options?: {noFollowSymlinks?: boolean}) => {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 });"
     },
     {
       "name": "createSpawnTool",
@@ -361,10 +361,19 @@
       "fails": "skips empty spans and never fabricates; a provider HaltError propagates clean. Each pass forwards usage via onLlmResult; a fact counts once via ctx.recordMemoryOp.",
       "example": "const { facts } = await remember(spans, { provider, store });\nconsole.log(`consolidated ${facts.length} durable facts`);"
     },
+    {
+      "name": "resolveToolPath",
+      "category": "tools",
+      "when": "you gate shell file tools — canonicalize the tool's path once with this, put it in the action you pass to `gate.check`, so the gate judges exactly the path the tool opens",
+      "import": "import { resolveToolPath } from 'bare-agent/tools'",
+      "signature": "resolveToolPath(p: string) => string",
+      "fails": "throws on a non-string or empty path, and on a `~` path when no home directory can be determined — never turns `~/x` into `/x` or an empty path into cwd",
+      "example": "const resolved = resolveToolPath('~/notes.txt');"
+    },
     {
       "name": "Retry",
       "category": "resilience",
-      "when": "you want backoff-with-jitter around a flaky async call (a provider request, a plan step) — the retry seam Loop and runPlan wrap providers with",
+      "when": "you want backoff-with-jitter around a flaky async call (a provider request, a plan step) — the retry seam that Loop and runPlan wrap around providers",
       "import": "import { Retry } from 'bare-agent'",
       "signature": "new Retry(options?: RetryOptions)",
       "fails": "rethrows the last error once attempts are exhausted; by default only transient errors (429/5xx/ECONNRESET/ETIMEDOUT) are retried.",

package/src/retry.d.ts

@@ -23,7 +23,7 @@ export type RetryOptions = {
 export class Retry {
     /**
      * @param {RetryOptions} [options={}]
-     * @when you want backoff-with-jitter around a flaky async call (a provider request, a plan step) — the retry seam Loop and runPlan wrap providers with
+     * @when you want backoff-with-jitter around a flaky async call (a provider request, a plan step) — the retry seam that Loop and runPlan wrap around providers
      * @fails rethrows the last error once attempts are exhausted; by default only transient errors (429/5xx/ECONNRESET/ETIMEDOUT) are retried.
      * @example
      *   const retry = new Retry({ maxAttempts: 3, jitter: true });

package/src/retry.js

@@ -25,7 +25,7 @@ const DEFAULT_RETRY_ON = (err) => {
 class Retry {
   /**
    * @param {RetryOptions} [options={}]
-   * @when you want backoff-with-jitter around a flaky async call (a provider request, a plan step) — the retry seam Loop and runPlan wrap providers with
+   * @when you want backoff-with-jitter around a flaky async call (a provider request, a plan step) — the retry seam that Loop and runPlan wrap around providers
    * @fails rethrows the last error once attempts are exhausted; by default only transient errors (429/5xx/ECONNRESET/ETIMEDOUT) are retried.
    * @example
    *   const retry = new Retry({ maxAttempts: 3, jitter: true });

package/src/tools.d.ts

@@ -1,9 +1,10 @@
 import { createBrowsingTools } from "../tools/browse";
 import { createMobileTools } from "../tools/mobile";
 import { createShellTools } from "../tools/shell";
+import { resolveToolPath } from "../tools/shell";
 import { createSpawnTool } from "../tools/spawn";
 import { spawnChild } from "../tools/spawn";
 import { createDeferTool } from "../tools/defer";
 import { readQueue as readDeferQueue } from "../tools/defer";
 import { liteCtxMcpBridgeConfig } from "../tools/litectx-mcp";
-export { createBrowsingTools, createMobileTools, createShellTools, createSpawnTool, spawnChild, createDeferTool, readDeferQueue, liteCtxMcpBridgeConfig };
+export { createBrowsingTools, createMobileTools, createShellTools, resolveToolPath, createSpawnTool, spawnChild, createDeferTool, readDeferQueue, liteCtxMcpBridgeConfig };

package/src/tools.js

@@ -2,7 +2,7 @@
 
 const { createBrowsingTools } = require('../tools/browse');
 const { createMobileTools } = require('../tools/mobile');
-const { createShellTools } = require('../tools/shell');
+const { createShellTools, resolveToolPath } = require('../tools/shell');
 const { createSpawnTool, spawnChild } = require('../tools/spawn');
 const { createDeferTool, readQueue: readDeferQueue } = require('../tools/defer');
 const { liteCtxMcpBridgeConfig } = require('../tools/litectx-mcp');
@@ -11,6 +11,7 @@ module.exports = {
   createBrowsingTools,
   createMobileTools,
   createShellTools,
+  resolveToolPath,
   createSpawnTool,
   spawnChild,
   createDeferTool,

package/tools/shell.d.ts

@@ -3,9 +3,13 @@ declare namespace _exports {
 }
 declare namespace _exports {
     export { createShellTools };
+    export { resolveToolPath };
     export { _grepCore };
     export { writeFile as _writeFile };
     export { editFile as _editFile };
+    export { openFile as _openFile };
+    export { assertDirStillMatchesHandle as _assertDirStillMatchesHandle };
+    export { expandHome as _expandHome };
 }
 export = _exports;
 type GrepArgs = {
@@ -20,6 +24,12 @@ type GrepArgs = {
      * past `looksCatastrophic` can no longer hang the host event loop.
      */
     timeout?: number | undefined;
+    /**
+     * - 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.
+     */
+    noFollowSymlinks?: boolean | undefined;
 };
 type RunArgvArgs = {
     argv: string[];
@@ -37,19 +47,60 @@ type ExecCommandArgs = {
 };
 type ToolDef = import("../types").ToolDef;
 /**
- * Create the three shell tools. No options — configuration is per-call via tool args,
- * gating is the caller's responsibility via `new Loop({ policy })`.
+ * 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-
+ *   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
+ *   the final component ONLY — a symlinked PARENT directory is NOT refused (bareguard's own
+ *   resolved-path containment check for that is planned for an upcoming release, not yet published;
+ *   until then the gate matches paths lexically, so a symlinked parent dir is not contained there
+ *   either — see the top-of-file CAVEAT). The `cwd` option of `shell_run`/`shell_exec` is a separate,
+ *   NARROWER gap: it only gets `~` expansion, never this flag or `resolveToolPath`'s full
+ *   canonicalization, so a symlinked `cwd` is always followed. On Windows (`fs.constants.O_NOFOLLOW`
+ *   is undefined there) the guard falls back to a non-atomic `fs.lstat`-then-open check — a symlink
+ *   planted in the gap between the two calls slips through; this is a documented platform limitation,
+ *   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.
  * @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, and shell_edit refuses a non-unique anchor as a tool result (file untouched).
+ * @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();
  *   const loop = new Loop({ provider, tools, policy });
+ *   const { tools: safeTools } = createShellTools({ noFollowSymlinks: true });
  */
-declare function createShellTools(): {
+declare function createShellTools(options?: {
+    noFollowSymlinks?: boolean;
+}): {
     tools: ToolDef[];
 };
+/**
+ * THE canonicalizer every shell file tool uses before opening a path — and the same canonicalization
+ * an adopter should apply before `gate.check` so the string it judges is the string that gets opened
+ * (see the top-of-file CAVEAT). Expands `~`/`~/…` via `os.homedir()` (throwing rather than silently
+ * degrading — see `expandHome`), then resolves against `process.cwd()` — matching how bareguard's own
+ * config-side path handling expects `~` and relative paths to be canonicalized before it judges them.
+ *
+ * Idempotent: `resolveToolPath(resolveToolPath(p)) === resolveToolPath(p)` — an already-absolute,
+ * already-`~`-free path passed back in is returned unchanged (`path.resolve` on an absolute path is
+ * a no-op; there is no `~` left to expand).
+ * REJECTS a non-string or empty `p` outright (thrown, before any expansion/resolution runs) —
+ * every file tool routes through this function, so a model-authored call that omits `path` or sends
+ * `""` must not silently resolve to `process.cwd()` (an assumed default a gate would judge and a tool
+ * would then read/list, for input that named no path at all). The rejection message names only the
+ * TYPE/category of the bad value (`describeBadPath`), never the value itself.
+ * @param {string} p
+ * @returns {string}
+ * @when you gate shell file tools — canonicalize the tool's path once with this, put it in the action you pass to `gate.check`, so the gate judges exactly the path the tool opens
+ * @fails throws on a non-string or empty path, and on a `~` path when no home directory can be determined — never turns `~/x` into `/x` or an empty path into cwd
+ * @example
+ *   const resolved = resolveToolPath('~/notes.txt');
+ */
+declare function resolveToolPath(p: string): string;
 /**
  * @typedef {object} GrepArgs
  * @property {string} pattern
@@ -60,6 +111,9 @@ declare function createShellTools(): {
  * @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
@@ -69,7 +123,7 @@ declare function createShellTools(): {
  * guarantee; a grounded bypass like `(a|a|a)*` passes it yet backtracks exponentially).
  * @param {GrepArgs} args
  */
-declare function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flags }: GrepArgs): Promise<{
+declare function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flags, noFollowSymlinks }: GrepArgs): Promise<{
     hits: {
         file: string;
         line: number;
@@ -95,6 +149,7 @@ declare function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flag
  * feeds this UNTRUSTED model-authored args (that is the boundary BA-4 was breached at, and where types buy
  * nothing).
  * @param {{path: string, content: string, append?: boolean, maxBytes?: number}} args
+ * @param {{noFollowSymlinks?: boolean}} [options]
  * @returns {Promise<string>}
  */
 declare function writeFile({ path: rawPath, content, append, maxBytes }: {
@@ -102,6 +157,8 @@ declare function writeFile({ path: rawPath, content, append, maxBytes }: {
     content: string;
     append?: boolean;
     maxBytes?: number;
+}, options?: {
+    noFollowSymlinks?: boolean;
 }): Promise<string>;
 /**
  * Anchored exact-string replace (BA-13) — the surgical counterpart to the whole-file `shell_write`.
@@ -117,7 +174,9 @@ declare function writeFile({ path: rawPath, content, append, maxBytes }: {
  *     guard, so a model that repeats the byte-identical wrong anchor is bounded only by maxTurns/budget, not
  *     short-circuited. A widened anchor is a different call and recovers naturally; the exact-repeat spin is
  *     the rare degenerate case. This matches the ask's "refusal, not a throw" contract.)
- *   - fs-layer errors (missing file, a directory) and BA-4 param-guard violations THROW at the tool boundary.
+ *   - fs-layer errors (missing file, a directory), BA-4 param-guard violations, and a SOURCE file larger
+ *     than the `maxBytes` cap (read bounded via `readBounded`, never fully loaded to find out) THROW at
+ *     the tool boundary, before any edit is computed — no change made.
  *
  * BA-4 param guards (guarded from birth this time — cf. `shell_write` zeroing files on an absent arg):
  * `oldText` a required NON-EMPTY string, `newText` a required string — both THROW when absent/wrong-type (an
@@ -133,6 +192,7 @@ declare function writeFile({ path: rawPath, content, append, maxBytes }: {
  * `newText` and would corrupt any edit whose replacement contains a `$`. We index + slice, so every byte of
  * `newText` lands verbatim.
  * @param {{path: string, oldText: string, newText: string, maxBytes?: number}} args
+ * @param {{noFollowSymlinks?: boolean}} [options]
  * @returns {Promise<string>}
  */
 declare function editFile({ path: rawPath, oldText, newText, maxBytes }: {
@@ -140,4 +200,74 @@ declare function editFile({ path: rawPath, oldText, newText, maxBytes }: {
     oldText: string;
     newText: string;
     maxBytes?: number;
+}, options?: {
+    noFollowSymlinks?: boolean;
 }): Promise<string>;
+/**
+ * ONE shared open path for every file-open site in this module (`shell_read`, `shell_write`,
+ * `shell_edit`, and `shell_grep`'s root check + per-file reads). With `noFollowSymlinks` off this
+ * is a plain `fs.open` — the caller's `flags` decide read/write/create semantics, byte-identical to
+ * this module's pre-existing behavior. With it on, refuses to follow a symlink at the FINAL path
+ * component (opt-in — never covers a symlinked PARENT directory; see the top-of-file CAVEAT for
+ * bareguard's resolved-path containment side of that, upcoming but not yet published).
+ *
+ * Two implementations when the flag is on, selected by whether the platform exposes `O_NOFOLLOW`
+ * (present on linux/macOS, `undefined` on Windows):
+ *   - Native: pass `O_NOFOLLOW` straight to the kernel via `fs.open`. Atomic — there is no window
+ *     between checking and opening. A symlink at the final component (file, dir, or DANGLING)
+ *     makes the open fail with `ELOOP` before anything is created or read, which we translate to
+ *     `symlinkRefusalError`. Any other error (ENOENT, EACCES, …) passes through unchanged.
+ *   - Fallback (`O_NOFOLLOW` undefined): `fs.lstat` the path first and refuse if it is a symlink,
+ *     then `fs.open` normally. This is NOT atomic — a symlink planted between the `lstat` and the
+ *     `open` slips through (TOCTOU) — documented as a known Windows limitation, not a bug: Windows
+ *     has no `O_NOFOLLOW`-equivalent open flag reachable from Node. `lstat` throwing `ENOENT` means
+ *     "nothing there yet," which is fine for a write/create call — the open below still runs and
+ *     either creates the file or throws its own ENOENT for a read.
+ * @param {string} toolName
+ * @param {string} resolvedPath
+ * @param {number} flags
+ * @param {number} [mode]
+ * @param {{noFollowSymlinks?: boolean, constants?: {O_NOFOLLOW?: number}}} [options] - `constants` is
+ *   an injectable override, used by tests to force the Windows fallback branch on a non-Windows CI
+ *   box without monkeypatching `fs.constants` globally.
+ */
+declare function openFile(toolName: string, resolvedPath: string, flags: number, mode?: number, options?: {
+    noFollowSymlinks?: boolean;
+    constants?: {
+        O_NOFOLLOW?: number;
+    };
+}): Promise<fs.FileHandle>;
+/**
+ * Narrows (does not close) the directory-listing race: after opening a directory by FD we still
+ * have to list it by PATH — Node's `fs/promises` exposes no `fdopendir` — so a directory or symlink
+ * swapped in at that path between the open and the `readdir` could make us list a DIFFERENT
+ * directory's NAMES. This never leaks file CONTENTS (every content read in this module goes through
+ * the already-open fd, never re-opened by path), only which names are reported for a listing.
+ *
+ * Re-`lstat`s the path right after the read and refuses (throws, `ELOOP`) unless its `dev`+`ino`
+ * still match the handle that was opened — catching both a swap-to-a-symlink (whose own inode won't
+ * match the real directory's) and a swap-to-a-different-real-directory (a different inode).
+ *
+ * RESIDUAL, documented not closed: a swap-and-swap-back that lands back on the original dev+ino
+ * before this check runs is undetectable — any check that must re-consult the path shares this
+ * limit. Only called when `noFollowSymlinks` is on; the recheck is inert otherwise.
+ * @param {string} toolName
+ * @param {string} resolvedPath
+ * @param {import('node:fs').Stats} handleStat
+ */
+declare function assertDirStillMatchesHandle(toolName: string, resolvedPath: string, handleStat: import("node:fs").Stats): Promise<void>;
+/**
+ * Expand a leading `~`/`~/…` to the real home directory via `os.homedir()` — matching how bareguard's
+ * own config-side `~` expansion works, so the SAME string means the same absolute path on both sides
+ * of a gate check. Throws a clear error rather than ever silently degrading `~/x` to `/x`:
+ * the previous `process.env.HOME || process.env.USERPROFILE || ''` fallback did exactly that when
+ * `HOME` was unset or empty — a `~`-rooted path would resolve to the FILESYSTEM ROOT, not "no home,"
+ * an under-modeled-boundary bug (an ambiguous case rounding toward "works" instead of surfacing).
+ * @param {string} p
+ * @param {() => string} [homedirFn] - Injectable override, used ONLY by tests to force the
+ *   empty/throwing-homedir case deterministically, without monkeypatching `os.homedir` globally
+ *   (which would affect every other test in this process). Production call sites never pass this.
+ * @returns {string}
+ */
+declare function expandHome(p: string, homedirFn?: () => string): string;
+import fs = require("node:fs/promises");

package/tools/shell.js

@@ -19,27 +19,56 @@
  * `fs`/`bash` primitives — those need `action.type ∈ {read,write,edit,bash}` with `action.path`/`action.cmd`.
  * To gate `shell_write`/`shell_edit` by `fs.writeScope` (so a write outside the allowed root is denied BEFORE it
  * touches disk), translate it at the gate — see `examples/with-bareguard.mjs` for the `wireGate(gate, { actionTranslator })`
- * mapping (`shell_write` → `{ type:'write', path }`, `shell_edit` → `{ type:'edit', path }`, `shell_read`/`shell_grep`
- * → `{ type:'read', path }`, `shell_run`/`shell_exec` → `{ type:'bash', cmd }`). bareguard gates `edit` by
+ * mapping (`shell_write` → `{ type:'write', path: resolveToolPath(path) }`, `shell_edit` → `{ type:'edit', path: resolveToolPath(path) }`,
+ * `shell_read`/`shell_grep` → `{ type:'read', path: resolveToolPath(path) }`, `shell_run`/`shell_exec` → `{ type:'bash', cmd }`) —
+ * canonicalize with `resolveToolPath` (exported alongside `createShellTools`) before the gate check, so the string
+ * the gate judges is the string the tool actually opens (see the CAVEAT below). bareguard gates `edit` by
  * `fs.writeScope` identically to `write` (its FS primitive's `FS_TYPES` includes `edit`), so a consumer that
  * fences `write` gets `edit` fenced by the same scope with ZERO extra config. A write/edit tool alone is NOT
  * auto-gated — validated by poc/ba2-write-tool-gate.mjs (without the translator the out-of-scope write leaks).
  *
- * CAVEAT (applies to read AND write scopes): bareguard's `fs` primitive matches paths LEXICALLY (no
- * `realpath`/symlink resolution), so a symlink that lives INSIDE the allowed scope but points OUTSIDE it is
- * not caught — a `shell_write` through such a link can escape the scope. If untrusted input can create
- * symlinks under your scope, canonicalize (`fs.realpath`) before the gate, or keep the scope on a root with
- * no attacker-writable symlinks. This is bareguard's documented lexical-match contract, not specific to this tool.
+ * CAVEAT (applies to read AND write scopes): bareguard's `fs` primitive matches paths LEXICALLY TODAY
+ * (no symlink resolution) — a resolved-path (symlink) containment check is planned for an upcoming
+ * bareguard release, not yet published; until it ships, a symlinked PARENT directory is NOT contained
+ * even when the link itself sits inside an allowed scope. bare-agent canonicalizes the path (`~` +
+ * resolve, via `resolveToolPath`) before the gate check and opens that same path — this closes a
+ * DIFFERENT gap (the gate judging a `~`/relative path in a different form than the one the tool
+ * actually opens), not the lexical-match gap above. `noFollowSymlinks` refuses a symlinked FINAL path
+ * component at open time (opt-in, below). None of this covers hardlinks.
+ *
+ * OPT-IN SYMLINK REFUSAL: `createShellTools({ noFollowSymlinks: true })` closes the specific case above
+ * where the symlink itself is the FINAL path component the tool opens (`shell_read`/`shell_write`/`shell_edit`
+ * on the path directly, `shell_grep`'s root and per-file reads) — that open now refuses (throws, `ELOOP`)
+ * instead of following the link, whether it points inside or outside any configured scope. Three things
+ * this does NOT cover, by design: (1) a symlinked PARENT directory (e.g. `/scope/linked-dir/file.txt`
+ * where `linked-dir` itself is the link) — that's the lexical-match gap above, unrelated to this flag;
+ * (2) on Windows, where `fs.constants.O_NOFOLLOW` doesn't exist, the check falls back to a non-atomic
+ * `fs.lstat`-then-open — a symlink planted in the gap between the two calls slips through; and (3) the
+ * `cwd` option of `shell_run`/`shell_exec` — it only gets `~` expansion, never `noFollowSymlinks` or
+ * `resolveToolPath`'s full canonicalization, so a symlinked `cwd` is followed. Default is `false`
+ * (identical behavior to before this option existed).
+ *
+ * DIRECTORY-LISTING RACE (narrowed, not closed): a directory listing (`shell_read` on a dir,
+ * `shell_grep`'s root when it's a dir) opens by FD then still has to list by PATH — Node's
+ * `fs/promises` has no `fdopendir` — so a directory swapped in at that path between the open and the
+ * listing could report a DIFFERENT directory's NAMES (never contents; every content read goes through
+ * the already-open fd, never re-opened by path). With `noFollowSymlinks` on, a `dev`+`ino` recheck
+ * runs immediately after the listing and refuses (`ELOOP`) on a mismatch — this narrows the window to
+ * essentially nothing but does not close it: a swap-and-swap-back that lands on the original `dev`+
+ * `ino` before the recheck runs is undetectable by any check that must re-consult the path.
  */
 
 /** @typedef {import('../types').ToolDef} ToolDef */
 
 const fs = require('node:fs/promises');
 const path = require('node:path');
+const os = require('node:os');
 const crypto = require('node:crypto');
 const { exec, execFile } = require('node:child_process');
 const { Worker } = require('node:worker_threads');
 
+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;
@@ -48,45 +77,256 @@ const DEFAULT_EXEC_TIMEOUT_MS = 30_000;
 const DEFAULT_EXEC_MAX_BUFFER = 1024 * 1024;     // 1 MB
 
 /**
+ * Type-only description of a bad path arg for an error message — NEVER the value itself (repo rule:
+ * an unexpected value must never leak into an error/audit log, only its type/category). `p` here is
+ * untrusted, model-authored tool-call input, so this is the boundary that rule protects.
+ * @param {unknown} p
+ * @returns {string}
+ */
+function describeBadPath(p) {
+  if (p === undefined) return 'undefined';
+  if (p === null) return 'null';
+  if (p === '') return 'empty string';
+  return typeof p;
+}
+
+/**
+ * Expand a leading `~`/`~/…` to the real home directory via `os.homedir()` — matching how bareguard's
+ * own config-side `~` expansion works, so the SAME string means the same absolute path on both sides
+ * of a gate check. Throws a clear error rather than ever silently degrading `~/x` to `/x`:
+ * the previous `process.env.HOME || process.env.USERPROFILE || ''` fallback did exactly that when
+ * `HOME` was unset or empty — a `~`-rooted path would resolve to the FILESYSTEM ROOT, not "no home,"
+ * an under-modeled-boundary bug (an ambiguous case rounding toward "works" instead of surfacing).
  * @param {string} p
+ * @param {() => string} [homedirFn] - Injectable override, used ONLY by tests to force the
+ *   empty/throwing-homedir case deterministically, without monkeypatching `os.homedir` globally
+ *   (which would affect every other test in this process). Production call sites never pass this.
  * @returns {string}
  */
-function expandHome(p) {
+function expandHome(p, homedirFn = os.homedir) {
+  if (typeof p !== 'string') {
+    throw new Error(`expandHome: path must be a string (got ${describeBadPath(p)})`);
+  }
   if (!p) return p;
   if (p.startsWith('~/') || p === '~') {
-    const home = process.env.HOME || process.env.USERPROFILE || '';
+    let home;
+    try {
+      home = homedirFn();
+    } catch (/** @type {any} */ err) {
+      throw new Error(`cannot expand ~: no home directory (${err && err.message ? err.message : String(err)})`);
+    }
+    if (!home) {
+      throw new Error('cannot expand ~: no home directory');
+    }
     return path.join(home, p.slice(1));
   }
   return p;
 }
 
+/**
+ * THE canonicalizer every shell file tool uses before opening a path — and the same canonicalization
+ * an adopter should apply before `gate.check` so the string it judges is the string that gets opened
+ * (see the top-of-file CAVEAT). Expands `~`/`~/…` via `os.homedir()` (throwing rather than silently
+ * degrading — see `expandHome`), then resolves against `process.cwd()` — matching how bareguard's own
+ * config-side path handling expects `~` and relative paths to be canonicalized before it judges them.
+ *
+ * Idempotent: `resolveToolPath(resolveToolPath(p)) === resolveToolPath(p)` — an already-absolute,
+ * already-`~`-free path passed back in is returned unchanged (`path.resolve` on an absolute path is
+ * a no-op; there is no `~` left to expand).
+ * REJECTS a non-string or empty `p` outright (thrown, before any expansion/resolution runs) —
+ * every file tool routes through this function, so a model-authored call that omits `path` or sends
+ * `""` must not silently resolve to `process.cwd()` (an assumed default a gate would judge and a tool
+ * would then read/list, for input that named no path at all). The rejection message names only the
+ * TYPE/category of the bad value (`describeBadPath`), never the value itself.
+ * @param {string} p
+ * @returns {string}
+ * @when you gate shell file tools — canonicalize the tool's path once with this, put it in the action you pass to `gate.check`, so the gate judges exactly the path the tool opens
+ * @fails throws on a non-string or empty path, and on a `~` path when no home directory can be determined — never turns `~/x` into `/x` or an empty path into cwd
+ * @example
+ *   const resolved = resolveToolPath('~/notes.txt');
+ */
+function resolveToolPath(p) {
+  if (typeof p !== 'string' || p.length === 0) {
+    throw new Error(`resolveToolPath: path must be a non-empty string (got ${describeBadPath(p)})`);
+  }
+  return path.resolve(expandHome(p));
+}
+
+/**
+ * Build the standard refusal thrown by every symlink-refusing site (BA-nofollow). Deliberately a
+ * plain `Error` (not a subclass) so it crosses the Loop's tool-error boundary like any other tool
+ * failure and feeds the BA-12 identical-error spin guard; `code:'ELOOP'` mirrors the kernel errno
+ * that `O_NOFOLLOW` itself raises, so callers can switch on ONE field regardless of which of the
+ * two code paths (native flag vs the Windows lstat fallback) produced it.
+ * @param {string} toolName
+ * @param {string} resolvedPath
+ * @returns {Error}
+ */
+function symlinkRefusalError(toolName, resolvedPath) {
+  const err = /** @type {any} */ (new Error(
+    `${toolName}: refusing to follow symlink at ${resolvedPath} (noFollowSymlinks is on)`,
+  ));
+  err.code = 'ELOOP';
+  return err;
+}
+
+/**
+ * ONE shared open path for every file-open site in this module (`shell_read`, `shell_write`,
+ * `shell_edit`, and `shell_grep`'s root check + per-file reads). With `noFollowSymlinks` off this
+ * is a plain `fs.open` — the caller's `flags` decide read/write/create semantics, byte-identical to
+ * this module's pre-existing behavior. With it on, refuses to follow a symlink at the FINAL path
+ * component (opt-in — never covers a symlinked PARENT directory; see the top-of-file CAVEAT for
+ * bareguard's resolved-path containment side of that, upcoming but not yet published).
+ *
+ * Two implementations when the flag is on, selected by whether the platform exposes `O_NOFOLLOW`
+ * (present on linux/macOS, `undefined` on Windows):
+ *   - Native: pass `O_NOFOLLOW` straight to the kernel via `fs.open`. Atomic — there is no window
+ *     between checking and opening. A symlink at the final component (file, dir, or DANGLING)
+ *     makes the open fail with `ELOOP` before anything is created or read, which we translate to
+ *     `symlinkRefusalError`. Any other error (ENOENT, EACCES, …) passes through unchanged.
+ *   - Fallback (`O_NOFOLLOW` undefined): `fs.lstat` the path first and refuse if it is a symlink,
+ *     then `fs.open` normally. This is NOT atomic — a symlink planted between the `lstat` and the
+ *     `open` slips through (TOCTOU) — documented as a known Windows limitation, not a bug: Windows
+ *     has no `O_NOFOLLOW`-equivalent open flag reachable from Node. `lstat` throwing `ENOENT` means
+ *     "nothing there yet," which is fine for a write/create call — the open below still runs and
+ *     either creates the file or throws its own ENOENT for a read.
+ * @param {string} toolName
+ * @param {string} resolvedPath
+ * @param {number} flags
+ * @param {number} [mode]
+ * @param {{noFollowSymlinks?: boolean, constants?: {O_NOFOLLOW?: number}}} [options] - `constants` is
+ *   an injectable override, used by tests to force the Windows fallback branch on a non-Windows CI
+ *   box without monkeypatching `fs.constants` globally.
+ */
+async function openFile(toolName, resolvedPath, flags, mode, options = {}) {
+  const { noFollowSymlinks = false, constants = fsConstants } = options;
+  if (!noFollowSymlinks) {
+    return fs.open(resolvedPath, flags, mode);
+  }
+  const oNoFollow = constants.O_NOFOLLOW;
+  if (typeof oNoFollow === 'number') {
+    try {
+      return await fs.open(resolvedPath, flags | oNoFollow, mode);
+    } catch (/** @type {any} */ err) {
+      if (err && err.code === 'ELOOP') throw symlinkRefusalError(toolName, resolvedPath);
+      throw err;
+    }
+  }
+  // Windows fallback: non-atomic lstat-then-open.
+  let lst = null;
+  try {
+    lst = await fs.lstat(resolvedPath);
+  } catch (/** @type {any} */ err) {
+    if (err && err.code !== 'ENOENT') throw err;
+  }
+  if (lst && lst.isSymbolicLink()) throw symlinkRefusalError(toolName, resolvedPath);
+  return fs.open(resolvedPath, flags, mode);
+}
+
+/**
+ * Narrows (does not close) the directory-listing race: after opening a directory by FD we still
+ * have to list it by PATH — Node's `fs/promises` exposes no `fdopendir` — so a directory or symlink
+ * swapped in at that path between the open and the `readdir` could make us list a DIFFERENT
+ * directory's NAMES. This never leaks file CONTENTS (every content read in this module goes through
+ * the already-open fd, never re-opened by path), only which names are reported for a listing.
+ *
+ * Re-`lstat`s the path right after the read and refuses (throws, `ELOOP`) unless its `dev`+`ino`
+ * still match the handle that was opened — catching both a swap-to-a-symlink (whose own inode won't
+ * match the real directory's) and a swap-to-a-different-real-directory (a different inode).
+ *
+ * RESIDUAL, documented not closed: a swap-and-swap-back that lands back on the original dev+ino
+ * before this check runs is undetectable — any check that must re-consult the path shares this
+ * limit. Only called when `noFollowSymlinks` is on; the recheck is inert otherwise.
+ * @param {string} toolName
+ * @param {string} resolvedPath
+ * @param {import('node:fs').Stats} handleStat
+ */
+async function assertDirStillMatchesHandle(toolName, resolvedPath, handleStat) {
+  const current = await fs.lstat(resolvedPath).catch(() => null);
+  if (!current || current.dev !== handleStat.dev || current.ino !== handleStat.ino) {
+    throw symlinkRefusalError(toolName, resolvedPath);
+  }
+}
+
+const READ_BOUNDED_CHUNK_SIZE = 64 * 1024;
+
+/**
+ * Read from an open file handle in chunks, stopping at EOF or once `limit + 1` bytes have been
+ * read — NEVER more, regardless of what `stat.size` claims. This is the fix for a real OOM: a
+ * device file like `/dev/zero` has no EOF at all, so an unbounded `fh.readFile()` grows without
+ * bound until the process dies (observed: `shell_read({path:'/dev/zero'})` killed the whole agent
+ * with a FATAL heap OOM, exit 134). A `stat.size`-lying file (e.g. `/proc/kallsyms`, `size:0` but
+ * actually ~20MB) is a lesser version of the same problem — fully read then discarded down to the
+ * cap. `readBounded` reads AT MOST `limit + 1` bytes either way: the `+1` exists only so the caller
+ * can distinguish "exactly `limit` bytes, then real EOF" (`hitLimit:false`) from "there was more"
+ * (`hitLimit:true`) without a second read.
+ *
+ * Reads at `position: null` (the fd's own advancing cursor, not a caller-tracked offset) — this is
+ * what makes it correct uniformly across regular files, procfs/sysfs (offset-readable despite a
+ * lying size), and character devices (which generally ignore any offset argument regardless).
+ * @param {import('node:fs/promises').FileHandle} fh
+ * @param {number} limit
+ * @returns {Promise<{buf: Buffer, hitLimit: boolean}>}
+ */
+async function readBounded(fh, limit) {
+  const chunks = [];
+  let total = 0;
+  while (total <= limit) {
+    const wantBytes = Math.min(READ_BOUNDED_CHUNK_SIZE, limit + 1 - total);
+    const chunk = Buffer.alloc(wantBytes);
+    const { bytesRead } = await fh.read(chunk, 0, wantBytes, null);
+    if (bytesRead === 0) break; // real EOF
+    chunks.push(bytesRead === chunk.length ? chunk : chunk.subarray(0, bytesRead));
+    total += bytesRead;
+  }
+  return { buf: Buffer.concat(chunks, total), hitLimit: total > limit };
+}
+
 /**
  * @param {string} rawPath
  * @param {number} [maxBytes]
+ * @param {{noFollowSymlinks?: boolean}} [options]
  */
-async function readEntry(rawPath, maxBytes) {
-  const resolved = path.resolve(expandHome(rawPath));
-  const stat = await fs.stat(resolved);
-  if (stat.isDirectory()) {
-    const entries = await fs.readdir(resolved, { withFileTypes: true });
-    const lines = entries.map(e => {
-      const kind = e.isDirectory() ? 'dir' : e.isSymbolicLink() ? 'link' : 'file';
-      return `${kind}\t${e.name}`;
-    });
-    return `dir ${resolved}\n${lines.join('\n')}`;
-  }
+async function readEntry(rawPath, maxBytes, options = {}) {
+  const resolved = resolveToolPath(rawPath);
   const cap = maxBytes || DEFAULT_READ_MAX_BYTES;
-  if (stat.size > cap) {
-    const fh = await fs.open(resolved, 'r');
-    try {
+
+  const fh = await openFile('shell_read', resolved, fsConstants.O_RDONLY, undefined, options);
+  try {
+    const stat = await fh.stat();
+    if (stat.isDirectory()) {
+      const entries = await fs.readdir(resolved, { withFileTypes: true });
+      // Directory-listing race (item 3): the listing above still goes by PATH, not the fd we just
+      // opened (no fdopendir in fs/promises) — recheck right after, narrowing the swap window.
+      if (options.noFollowSymlinks) await assertDirStillMatchesHandle('shell_read', resolved, stat);
+      const lines = entries.map(e => {
+        const kind = e.isDirectory() ? 'dir' : e.isSymbolicLink() ? 'link' : 'file';
+        return `${kind}\t${e.name}`;
+      });
+      return `dir ${resolved}\n${lines.join('\n')}`;
+    }
+    if (stat.size > cap) {
+      // Known-large regular file: stat.size is trustworthy here, so a fixed cap-byte read from
+      // offset 0 is the fast path — no need to read the whole thing just to discard the tail.
       const buf = Buffer.alloc(cap);
       await fh.read(buf, 0, cap, 0);
       return buf.toString('utf8') + `\n\n[truncated: ${stat.size - cap} more bytes not shown]`;
-    } finally {
-      await fh.close();
     }
+    // stat.size is <= cap here, but NOT trustworthy: procfs/sysfs files (e.g. /proc/self/status,
+    // /proc/kallsyms) commonly report a size that has nothing to do with their real content, and a
+    // device file like /dev/zero has no EOF at all. readBounded caps the read at cap+1 bytes no
+    // matter what — never the unbounded `fh.readFile()` this module used to call here (that OOM'd
+    // the whole process on /dev/zero, exit 134).
+    const { buf, hitLimit } = await readBounded(fh, cap);
+    if (hitLimit) {
+      // We only know we read cap+1+ bytes, not the real total (stat.size lied) — never invent a
+      // "more bytes not shown" count for a size we don't actually know.
+      return buf.subarray(0, cap).toString('utf8') + `\n\n[truncated at ${cap} bytes: file size unknown]`;
+    }
+    return buf.toString('utf8');
+  } finally {
+    await fh.close().catch(() => {});
   }
-  return fs.readFile(resolved, 'utf8');
 }
 
 /**
@@ -106,9 +346,10 @@ async function readEntry(rawPath, maxBytes) {
  * feeds this UNTRUSTED model-authored args (that is the boundary BA-4 was breached at, and where types buy
  * nothing).
  * @param {{path: string, content: string, append?: boolean, maxBytes?: number}} args
+ * @param {{noFollowSymlinks?: boolean}} [options]
  * @returns {Promise<string>}
  */
-async function writeFile({ path: rawPath, content, append = false, maxBytes }) {
+async function writeFile({ path: rawPath, content, append = false, maxBytes }, options = {}) {
   if (typeof rawPath !== 'string' || rawPath.length === 0) {
     throw new Error('shell_write requires a non-empty "path" string');
   }
@@ -124,10 +365,20 @@ async function writeFile({ path: rawPath, content, append = false, maxBytes }) {
   if (bytes > cap) {
     throw new Error(`shell_write content is ${bytes} bytes, over the ${cap}-byte cap (pass maxBytes to raise it)`);
   }
-  const resolved = path.resolve(expandHome(rawPath));
+  const resolved = resolveToolPath(rawPath);
   await fs.mkdir(path.dirname(resolved), { recursive: true });
-  if (append) await fs.appendFile(resolved, content, 'utf8');
-  else await fs.writeFile(resolved, content, 'utf8');
+
+  // O_TRUNC/O_APPEND + O_CREAT, mode 0o666 (subject to umask) — the same semantics `fs.writeFile`/
+  // `fs.appendFile` use under the hood. With `noFollowSymlinks` on, O_NOFOLLOW refuses at the kernel
+  // if the final component is a symlink (dangling or not) — the link's target is NEVER created or
+  // touched, because the open call fails before that.
+  const flags = fsConstants.O_WRONLY | fsConstants.O_CREAT | (append ? fsConstants.O_APPEND : fsConstants.O_TRUNC);
+  const fh = await openFile('shell_write', resolved, flags, 0o666, options);
+  try {
+    await fh.writeFile(content, 'utf8');
+  } finally {
+    await fh.close().catch(() => {});
+  }
   return `${append ? 'appended' : 'wrote'} ${bytes} bytes to ${resolved}`;
 }
 
@@ -145,7 +396,9 @@ async function writeFile({ path: rawPath, content, append = false, maxBytes }) {
  *     guard, so a model that repeats the byte-identical wrong anchor is bounded only by maxTurns/budget, not
  *     short-circuited. A widened anchor is a different call and recovers naturally; the exact-repeat spin is
  *     the rare degenerate case. This matches the ask's "refusal, not a throw" contract.)
- *   - fs-layer errors (missing file, a directory) and BA-4 param-guard violations THROW at the tool boundary.
+ *   - fs-layer errors (missing file, a directory), BA-4 param-guard violations, and a SOURCE file larger
+ *     than the `maxBytes` cap (read bounded via `readBounded`, never fully loaded to find out) THROW at
+ *     the tool boundary, before any edit is computed — no change made.
  *
  * BA-4 param guards (guarded from birth this time — cf. `shell_write` zeroing files on an absent arg):
  * `oldText` a required NON-EMPTY string, `newText` a required string — both THROW when absent/wrong-type (an
@@ -161,9 +414,10 @@ async function writeFile({ path: rawPath, content, append = false, maxBytes }) {
  * `newText` and would corrupt any edit whose replacement contains a `$`. We index + slice, so every byte of
  * `newText` lands verbatim.
  * @param {{path: string, oldText: string, newText: string, maxBytes?: number}} args
+ * @param {{noFollowSymlinks?: boolean}} [options]
  * @returns {Promise<string>}
  */
-async function editFile({ path: rawPath, oldText, newText, maxBytes }) {
+async function editFile({ path: rawPath, oldText, newText, maxBytes }, options = {}) {
   if (typeof rawPath !== 'string' || rawPath.length === 0) {
     throw new Error('shell_edit requires a non-empty "path" string');
   }
@@ -181,9 +435,31 @@ async function editFile({ path: rawPath, oldText, newText, maxBytes }) {
     );
   }
 
-  const resolved = path.resolve(expandHome(rawPath));
+  const resolved = resolveToolPath(rawPath);
+  // Hoisted above the read (previously computed only after) — readBounded needs a limit up front.
+  const cap = maxBytes || DEFAULT_WRITE_MAX_BYTES;
+
+  // The read (and, when noFollowSymlinks is on, the symlink refusal) happens BEFORE any temp file
+  // or rename — a refusal must leave both the target and a would-be link's target untouched.
   // fs-layer errors (ENOENT for a missing file, EISDIR for a directory) throw — same surface as shell_read.
-  const content = await fs.readFile(resolved, 'utf8');
+  let content;
+  let stat;
+  const fh = await openFile('shell_edit', resolved, fsConstants.O_RDONLY, undefined, options);
+  try {
+    stat = await fh.stat();
+    // Bounded read, same reasoning as readEntry: stat.size is untrustworthy (procfs/sysfs) and a
+    // device file like /dev/zero has no EOF at all — an unbounded fh.readFile() here OOM'd the
+    // whole process (exit 134). `stat` is still kept, for the mode preserved on the rewritten temp
+    // file below. Capped at the SAME cap the patched-result size is checked against below — a file
+    // already at or over the cap can never produce an in-cap edit anyway.
+    const { buf, hitLimit } = await readBounded(fh, cap);
+    if (hitLimit) {
+      throw new Error(`shell_edit: file is larger than the ${cap}-byte cap (pass maxBytes to raise it) — no change made`);
+    }
+    content = buf.toString('utf8');
+  } finally {
+    await fh.close().catch(() => {});
+  }
 
   // Literal, non-overlapping occurrence count (split on a string does no regex interpretation).
   const occurrences = content.split(oldText).length - 1;
@@ -199,14 +475,14 @@ async function editFile({ path: rawPath, oldText, newText, maxBytes }) {
   const idx = content.indexOf(oldText);
   const patched = content.slice(0, idx) + newText + content.slice(idx + oldText.length);
 
-  const cap = maxBytes || DEFAULT_WRITE_MAX_BYTES;
+  // `cap` was hoisted above the read (readBounded needed it); reused here unchanged.
   const bytes = Buffer.byteLength(patched, 'utf8');
   if (bytes > cap) {
     throw new Error(`shell_edit result is ${bytes} bytes, over the ${cap}-byte cap (pass maxBytes to raise it)`);
   }
 
-  // Atomic replace: a sibling temp (same dir → same filesystem → rename is atomic) with the original's mode.
-  const stat = await fs.stat(resolved);
+  // Atomic replace: a sibling temp (same dir → same filesystem → rename is atomic) with the original's
+  // mode. `stat` is already the handle's stat from the read above — no second `fs.stat` call needed.
   const tmp = `${resolved}.shell_edit-${crypto.randomBytes(9).toString('hex')}.tmp`;
   try {
     // flag 'wx' (O_CREAT|O_EXCL) — never follow or clobber a pre-planted file/symlink at the temp path; a
@@ -226,11 +502,18 @@ async function editFile({ path: rawPath, oldText, newText, maxBytes }) {
   return `edited ${resolved}: 1 replacement (-${removed}/+${added} lines)`;
 }
 
-// Probe the first 1KB for NUL bytes to skip binary files in grep walks.
-/** @param {string} filePath */
-async function isProbablyText(filePath) {
+// Probe the first 1KB for NUL bytes to skip binary files in grep walks. Per-file grep opens go
+// through the shared `openFile` helper like every other open site; unlike read/write/edit, a
+// symlink refusal here is caught and swallowed (SILENT skip), not surfaced — per the design, only
+// the grep ROOT refusal (in `grepPath`) is a loud tool error. A file that turns into a link between
+// `readdir` and open is skipped like any other read error (ENOENT, EACCES, …) already is.
+/**
+ * @param {string} filePath
+ * @param {boolean} [noFollowSymlinks]
+ */
+async function isProbablyText(filePath, noFollowSymlinks = false) {
   try {
-    const fh = await fs.open(filePath, 'r');
+    const fh = await openFile('shell_grep', filePath, fsConstants.O_RDONLY, undefined, { noFollowSymlinks });
     try {
       const buf = Buffer.alloc(1024);
       const { bytesRead } = await fh.read(buf, 0, 1024, 0);
@@ -301,6 +584,9 @@ function looksCatastrophic(pattern) {
  * @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.
  */
 
 /**
@@ -311,8 +597,8 @@ function looksCatastrophic(pattern) {
  * guarantee; a grounded bypass like `(a|a|a)*` passes it yet backtracks exponentially).
  * @param {GrepArgs} args
  */
-async function _grepCore({ pattern, path: rawPath, recursive = true, maxMatches, flags = 'i' }) {
-  const resolved = path.resolve(expandHome(rawPath));
+async function _grepCore({ pattern, path: rawPath, recursive = true, maxMatches, flags = 'i', noFollowSymlinks = false }) {
+  const resolved = resolveToolPath(rawPath);
   const cap = maxMatches || DEFAULT_GREP_MAX_MATCHES;
   let re;
   try {
@@ -335,10 +621,15 @@ async function _grepCore({ pattern, path: rawPath, recursive = true, maxMatches,
 
   for (const file of files) {
     if (hits.length >= cap) break;
-    if (!(await isProbablyText(file))) continue;
+    if (!(await isProbablyText(file, noFollowSymlinks))) continue;
     let content;
     try {
-      content = await fs.readFile(file, 'utf8');
+      const fh = await openFile('shell_grep', file, fsConstants.O_RDONLY, undefined, { noFollowSymlinks });
+      try {
+        content = (await fh.readFile()).toString('utf8');
+      } finally {
+        await fh.close();
+      }
     } catch {
       continue;
     }
@@ -359,21 +650,50 @@ async function _grepCore({ pattern, path: rawPath, recursive = true, maxMatches,
  * Public grep entry. Fast-rejects obviously catastrophic patterns without paying for a worker,
  * then runs the search in a worker thread bounded by a hard timeout — so even a pattern that
  * defeats the static guard degrades to a bounded rejection instead of an event-loop hang.
+ *
+ * The ROOT symlink refusal (opt-in `noFollowSymlinks`) runs HERE, on the main thread, before the
+ * 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
  */
-function grepPath(args) {
-  const { pattern, flags = 'i', timeout } = args;
+async function grepPath(args) {
+  const { pattern, flags = 'i', timeout, path: rawPath, noFollowSymlinks = false } = args;
   if (looksCatastrophic(pattern)) {
-    return Promise.reject(new Error(
+    throw new Error(
       `shell_grep: pattern rejected — nested unbounded quantifier (e.g. "(a+)+") risks catastrophic ` +
       `backtracking that would block the process. Simplify the regex.`,
-    ));
+    );
   }
   // Cheap up-front validation so a syntactically invalid regex fails clearly without a worker spin-up.
   try {
     new RegExp(pattern, flags);
   } catch (/** @type {any} */ err) {
-    return Promise.reject(new Error(`shell_grep: invalid regex — ${err.message}`));
+    throw new Error(`shell_grep: invalid regex — ${err.message}`);
+  }
+
+  if (noFollowSymlinks) {
+    // Atomic root check through the SAME shared helper every other open site uses (item 2) — O_RDONLY
+    // opens either a file or a directory on Linux/macOS, so one open covers both root shapes. A
+    // missing root is left to the worker's own "path not found" error (same message either flag
+    // state); any other open failure, including the ELOOP symlink refusal, surfaces here, loud, before
+    // the worker is spawned.
+    const resolvedRoot = resolveToolPath(rawPath);
+    let fh = null;
+    try {
+      fh = await openFile('shell_grep', resolvedRoot, fsConstants.O_RDONLY, undefined, { noFollowSymlinks: true });
+    } catch (/** @type {any} */ err) {
+      if (!(err && err.code === 'ENOENT')) throw err;
+    }
+    if (fh) {
+      try {
+        const stat = await fh.stat();
+        // Directory-listing race (item 3): the worker's own walk() re-reads this root by PATH, so
+        // recheck the root's identity here too, narrowing the swap window the same way shell_read does.
+        if (stat.isDirectory()) await assertDirStillMatchesHandle('shell_grep', resolvedRoot, stat);
+      } finally {
+        await fh.close().catch(() => {});
+      }
+    }
   }
 
   const budgetMs = timeout && timeout > 0 ? timeout : DEFAULT_GREP_TIMEOUT_MS;
@@ -495,17 +815,34 @@ function execCommand({ command, cwd, timeout, maxBuffer, env }) {
 }
 
 /**
- * Create the three shell tools. No options — configuration is per-call via tool args,
- * gating is the caller's responsibility via `new Loop({ policy })`.
+ * 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-
+ *   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
+ *   the final component ONLY — a symlinked PARENT directory is NOT refused (bareguard's own
+ *   resolved-path containment check for that is planned for an upcoming release, not yet published;
+ *   until then the gate matches paths lexically, so a symlinked parent dir is not contained there
+ *   either — see the top-of-file CAVEAT). The `cwd` option of `shell_run`/`shell_exec` is a separate,
+ *   NARROWER gap: it only gets `~` expansion, never this flag or `resolveToolPath`'s full
+ *   canonicalization, so a symlinked `cwd` is always followed. On Windows (`fs.constants.O_NOFOLLOW`
+ *   is undefined there) the guard falls back to a non-atomic `fs.lstat`-then-open check — a symlink
+ *   planted in the gap between the two calls slips through; this is a documented platform limitation,
+ *   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.
  * @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, and shell_edit refuses a non-unique anchor as a tool result (file untouched).
+ * @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();
  *   const loop = new Loop({ provider, tools, policy });
+ *   const { tools: safeTools } = createShellTools({ noFollowSymlinks: true });
  */
-function createShellTools() {
+function createShellTools(options = {}) {
+  const { noFollowSymlinks = false } = options;
   /** @type {ToolDef[]} */
   const tools = [
     {
@@ -519,7 +856,8 @@ function createShellTools() {
         },
         required: ['path'],
       },
-      execute: async (/** @type {{path: string, maxBytes?: number}} */ { path: p, maxBytes }) => readEntry(p, maxBytes),
+      execute: async (/** @type {{path: string, maxBytes?: number}} */ { path: p, maxBytes }) =>
+        readEntry(p, maxBytes, { noFollowSymlinks }),
     },
     {
       name: 'shell_grep',
@@ -535,7 +873,7 @@ function createShellTools() {
         },
         required: ['pattern', 'path'],
       },
-      execute: async (/** @type {GrepArgs} */ args) => grepPath(args),
+      execute: async (/** @type {GrepArgs} */ args) => grepPath({ ...args, noFollowSymlinks }),
     },
     {
       name: 'shell_write',
@@ -555,7 +893,7 @@ function createShellTools() {
       // The args are model-authored and UNTRUSTED — `content` may be absent (an output-token-capped
       // generation), so the boundary type stays loose and `writeFile` enforces the contract at runtime (BA-4).
       execute: async (/** @type {{path: string, content?: string, append?: boolean, maxBytes?: number}} */ args) =>
-        writeFile(/** @type {any} */ (args)),
+        writeFile(/** @type {any} */ (args), { noFollowSymlinks }),
     },
     {
       name: 'shell_edit',
@@ -579,7 +917,7 @@ function createShellTools() {
       // The args are model-authored and UNTRUSTED — oldText/newText may be absent (an output-token-capped
       // generation), so the boundary type stays loose and editFile enforces the BA-4 contract at runtime.
       execute: async (/** @type {{path: string, oldText?: string, newText?: string, maxBytes?: number}} */ args) =>
-        editFile(/** @type {any} */ (args)),
+        editFile(/** @type {any} */ (args), { noFollowSymlinks }),
     },
     {
       name: 'shell_run',
@@ -621,4 +959,13 @@ function createShellTools() {
   return { tools };
 }
 
-module.exports = { createShellTools, _grepCore, _writeFile: writeFile, _editFile: editFile };
+module.exports = {
+  createShellTools,
+  resolveToolPath,
+  _grepCore,
+  _writeFile: writeFile,
+  _editFile: editFile,
+  _openFile: openFile,
+  _assertDirStillMatchesHandle: assertDirStillMatchesHandle,
+  _expandHome: expandHome,
+};