@basein/runner 0.3.20 → 0.3.21

package/README.md

@@ -360,13 +360,13 @@ same command, the same file, the same kind of arguments); any other call runs as
 written and is asked about as usual. A *directly executed* step never reaches the
 permission system at all — it is dispatched to a `bir-proxy` and called on a
 connection that is already open, or, for Claude Code's own `Read`, `Glob`,
-`Grep`, `Edit`, `Write` and `Bash`, run by the recorder itself in the project
-folder — and `run_scenario`, the call that starts the
+`Grep`, `Edit`, `Write` and `Bash`, run by the recorder itself from the project
+folder, on any file the agent could reach — and `run_scenario`, the call that starts the
 run, is answered `allow` while the recorder has announced the plan. In plan mode
 nothing is announced and nothing is approved. Set `BIR_REPLAY_ALLOW_SERVERS` to
 the servers you are content to have called unattended (it also covers a steered
-plan's recovery), `BIR_BUILTIN_TOOLS` and `BIR_BASH_ALLOW` to the built-ins and
-commands, and read [the guide's §5.1](docs/calculatedReplayGuide.md)
+plan's recovery), `BIR_BUILTIN_TOOLS`, `BIR_PATH_ALLOW` and `BIR_BASH_ALLOW` to
+the built-ins, folders and commands, and read [the guide's §5.1](docs/calculatedReplayGuide.md)
 before enabling it anywhere that matters.
 
 What it buys: on a scenario whose every step is a wrapped MCP tool or one of
@@ -489,8 +489,9 @@ what to do when they register, so there is one switch and no second copy of it:
 |---|---|
 | `BIR_REPLAY` | `0` turns replay off and any other value on, over the project's stored switch (`bir replay on` / `off`; a first plain `bir install` stores off). Nothing below matters while it is off. |
 | `BIR_REPLAY_ALLOW_SERVERS` | Server keys bir may call unattended: **direct** execution, and a steered plan's recovery. Unset means the list `bir replay allow` stored for the project, else every wrapped server; narrowing it is the recommendation. |
-| `BIR_BUILTIN_TOOLS` | Built-in tools bir may execute itself during a replay — in the session's own project directory, and confined to it. Default all six: `Read,Glob,Grep,Edit,Write,Bash` (up to 0.3.7 only the read-only `Read,Glob,Grep`). A runner-side step never reaches Claude Code's permission prompts, so leave off the list any tool you want the model to call itself. `none` turns it off, and built-in steps are steered in the session. |
+| `BIR_BUILTIN_TOOLS` | Built-in tools bir may execute itself during a replay — from the session's own project directory; which folders the file tools may touch is `BIR_PATH_ALLOW`. Default all six: `Read,Glob,Grep,Edit,Write,Bash` (up to 0.3.7 only the read-only `Read,Glob,Grep`). A runner-side step never reaches Claude Code's permission prompts, so leave off the list any tool you want the model to call itself. `none` turns it off, and built-in steps are steered in the session. |
 | `BIR_BASH_ALLOW` | Command prefixes a runner-side `Bash` step may run. Unset means any command (`*`); a list such as `git,npm test` narrows it; `none` allows no command, and `Bash` steps are then steered in the session. A plan's Bash steps share a working directory, as Claude Code's do (variables and functions do not persist, also as in Claude Code). |
+| `BIR_PATH_ALLOW` | Folders a runner-side `Read`, `Glob`, `Grep`, `Edit` or `Write` may touch. Unset means any folder (`*`), as the agent's own tools: a plan that reads the agent's memory file under `~/.claude` runs (from 0.3.21; up to 0.3.20 only the project directory). `project` keeps them inside the session's project directory; add folders after a comma, `~` for your home folder: `project,~/.claude`. `none` allows no folder, and file steps are then steered in the session. |
 | `BIR_DERIVE_API_KEY` | **Optional.** Working out what a new request is about — which fleet, which file, which date — is done for you by the service on its own key, as long as you are signed in. Set this (an Anthropic key) only to keep that reading on your machine, on your key. Signed out *and* unset, a scenario whose values change between requests is declined rather than replayed on stale ones. |
 | `ANTHROPIC_API_KEY` | Not used by the background recorder, which has Claude Code's environment and would bill your own key — unless `BIR_USE_ANTHROPIC_API_KEY=1`. A `bir-hooks` run by hand in a terminal uses that terminal's key. |
 | `BIR_DERIVE_MODEL` | Derivation model, when you set a key of your own (default `claude-haiku-4-5-20251001`). |

package/dist/bin/bir-hooks.d.ts

@@ -62,9 +62,9 @@
  *   BIR_REPLAY_ALLOW_SERVERS  comma-separated server keys eligible for *direct*
  *                             execution. Unset means every wrapped server
  *   BIR_BUILTIN_TOOLS         comma-separated built-ins the runner may execute
- *                             itself during a replay, in the session's own
- *                             project directory and confined to it
- *                             (replay/builtins.ts). Default all six:
+ *                             itself during a replay, from the session's own
+ *                             project directory (replay/builtins.ts; which
+ *                             folders: BIR_PATH_ALLOW). Default all six:
  *                             Read,Glob,Grep,Edit,Write,Bash. A runner-side
  *                             step never reaches the host's permission
  *                             prompts; Read,Glob,Grep is the read-only set
@@ -73,6 +73,13 @@
  *   BIR_BASH_ALLOW            command prefixes a runner-side Bash step may run
  *                             (`*` for all). Unset means `*`; `none` means no
  *                             command, and Bash steps are steered
+ *   BIR_PATH_ALLOW            folders a runner-side Read, Glob, Grep, Edit or
+ *                             Write may touch (`*` for any). Unset means `*`:
+ *                             any path, as the agent's own tools (up to 0.3.20
+ *                             the project directory alone). `project` is the
+ *                             session's project directory, `~` the home
+ *                             folder: `project,~/.claude`. `none` means no
+ *                             folder, and the file steps are steered
  *   BIR_DERIVE_API_KEY        OPTIONAL. Derivation — reading what this turn acts
  *                             on — is done by the service for a signed-in
  *                             runner. Set this (an Anthropic key) only to keep

package/dist/bin/bir-hooks.js

@@ -62,9 +62,9 @@
  *   BIR_REPLAY_ALLOW_SERVERS  comma-separated server keys eligible for *direct*
  *                             execution. Unset means every wrapped server
  *   BIR_BUILTIN_TOOLS         comma-separated built-ins the runner may execute
- *                             itself during a replay, in the session's own
- *                             project directory and confined to it
- *                             (replay/builtins.ts). Default all six:
+ *                             itself during a replay, from the session's own
+ *                             project directory (replay/builtins.ts; which
+ *                             folders: BIR_PATH_ALLOW). Default all six:
  *                             Read,Glob,Grep,Edit,Write,Bash. A runner-side
  *                             step never reaches the host's permission
  *                             prompts; Read,Glob,Grep is the read-only set
@@ -73,6 +73,13 @@
  *   BIR_BASH_ALLOW            command prefixes a runner-side Bash step may run
  *                             (`*` for all). Unset means `*`; `none` means no
  *                             command, and Bash steps are steered
+ *   BIR_PATH_ALLOW            folders a runner-side Read, Glob, Grep, Edit or
+ *                             Write may touch (`*` for any). Unset means `*`:
+ *                             any path, as the agent's own tools (up to 0.3.20
+ *                             the project directory alone). `project` is the
+ *                             session's project directory, `~` the home
+ *                             folder: `project,~/.claude`. `none` means no
+ *                             folder, and the file steps are steered
  *   BIR_DERIVE_API_KEY        OPTIONAL. Derivation — reading what this turn acts
  *                             on — is done by the service for a signed-in
  *                             runner. Set this (an Anthropic key) only to keep

package/dist/bin/investigate.js

@@ -413,7 +413,7 @@ export function localFindings(turn) {
             const elsewhere = names.filter((n) => !EXECUTABLE_BUILTINS.has(n));
             const fixes = [];
             if (offList.length > 0) {
-                fixes.push(`The runner runs ${offList.join(", ")} itself when ${offList.length === 1 ? "it is" : "they are"} on \`BIR_BUILTIN_TOOLS\` (unset means all six, from runner 0.3.8) and, for Bash, \`BIR_BASH_ALLOW\` is not \`none\`: fix those where the recorder starts, then \`bir up --restart\`.`);
+                fixes.push(`The runner runs ${offList.join(", ")} itself when ${offList.length === 1 ? "it is" : "they are"} on \`BIR_BUILTIN_TOOLS\` (unset means all six, from runner 0.3.8) and, for Bash, \`BIR_BASH_ALLOW\` is not \`none\` (for the file tools, \`BIR_PATH_ALLOW\`): fix those where the recorder starts, then \`bir up --restart\`.`);
             }
             if (elsewhere.length > 0) {
                 fixes.push(`Put the data ${elsewhere.join(", ")} ${elsewhere.length === 1 ? "reaches" : "reach"} behind an MCP server, wrap it (\`bir install --server <name>\`), and record the prompt again so its steps are MCP calls.`);

package/dist/control/recorder-main.js

@@ -26,7 +26,7 @@ import { DISCOVERY_CHECK_MS, HEARTBEAT_MS, pidAlive, readDiscovery, removeDiscov
 import { DAEMON_CWD_ENV, DAEMON_ENV, DAEMON_LOG_ENV, DERIVE_KEY_ENV, DaemonLog, USE_API_KEY_ENV, clearPortProblem, compareVersions, probeHealth, projectEndpoint, rediscover, validPort, writePortProblem, } from "./daemon.js";
 import { configDir, normalizePath, supersededLogPath } from "./paths.js";
 import { RecorderKeeper } from "./recorder-keeper.js";
-import { parseBashAllow, parseBuiltinTools } from "../replay/builtins.js";
+import { FILE_BUILTINS, parseBashAllow, parseBuiltinTools, parsePathAllow } from "../replay/builtins.js";
 import { parseAllowList } from "../replay/coverage.js";
 import { sweepDeliveries } from "../replay/bash-channel.js";
 import { exemptLoopbackFromProxy, isWrapped, projectRecord, projectToken, readSidecar, } from "../config/generate.js";
@@ -197,15 +197,18 @@ function buildReplayOptions(keeper, policy, key) {
             : undefined;
     // Which built-ins the runner may execute itself (replay/builtins.ts):
     // all six by default, `BIR_BUILTIN_TOOLS` to narrow them, `BIR_BASH_ALLOW`
-    // to narrow the commands a `Bash` step may run. Environment-only knobs,
-    // like `BIR_REPLAY_RECORDED_OUTPUTS`.
+    // to narrow the commands a `Bash` step may run, `BIR_PATH_ALLOW` the
+    // folders a file step may touch (unset: any, as the agent's own tools).
+    // Environment-only knobs, like `BIR_REPLAY_RECORDED_OUTPUTS`.
     const builtinTools = parseBuiltinTools(process.env.BIR_BUILTIN_TOOLS);
     const bashAllow = parseBashAllow(process.env.BIR_BASH_ALLOW);
+    const pathAllow = parsePathAllow(process.env.BIR_PATH_ALLOW);
     const opts = {
         enabled,
         allowServers,
         builtinTools,
         bashAllow,
+        pathAllow,
         budgets: {
             // What a prompt may wait for its match (K5). Past it the prompt goes on
             // without one; a service slower than this must not cost every prompt.
@@ -263,6 +266,15 @@ function buildReplayOptions(keeper, policy, key) {
             // all — loud for the same reason as the rest of this line.
             builtins: builtinTools.size > 0 ? [...builtinTools].join(",") : "(none)",
             bashAllow: builtinTools.has("Bash") ? (bashAllow.length > 0 ? bashAllow.join(",") : "(none — Bash steps are steered)") : undefined,
+            // Where the file tools may reach: anywhere, as the agent's own, unless
+            // BIR_PATH_ALLOW names folders (up to 0.3.20 the project alone).
+            pathAllow: [...builtinTools].some((name) => FILE_BUILTINS.has(name))
+                ? pathAllow.includes("*")
+                    ? "(any folder)"
+                    : pathAllow.length > 0
+                        ? pathAllow.join(",")
+                        : "(none — file steps are steered)"
+                : undefined,
             // Who reads what this turn acts on (segmented.md R-PARAM-5). Named at
             // startup because the third state is a replay that silently never runs.
             derive: key.source ??

package/dist/control/server.js

@@ -2212,8 +2212,8 @@ export class ControlServer {
         }
         state.sessionId = session.sessionId;
         // The project directory an allow-listed built-in step executes in, and
-        // the jail it may not leave (replay/builtins.ts). The session's own cwd
-        // from the hook payloads, never the daemon's.
+        // what its relative paths resolve against (replay/builtins.ts). The
+        // session's own cwd from the hook payloads, never the daemon's.
         state.sessionCwd = session.cwd ?? this.opts.cwd;
         // The service offered to record this turn as the recording's newest run:
         // should the agent redo the task after the plan, the plan's own calls go
@@ -2372,8 +2372,8 @@ export class ControlServer {
         }
         state.sessionId = session.sessionId;
         // The project directory an allow-listed built-in step executes in, and
-        // the jail it may not leave (replay/builtins.ts). The session's own cwd
-        // from the hook payloads, never the daemon's.
+        // what its relative paths resolve against (replay/builtins.ts). The
+        // session's own cwd from the hook payloads, never the daemon's.
         state.sessionCwd = session.cwd ?? this.opts.cwd;
         run.replay = state;
         run.replays.push(state);
@@ -4715,8 +4715,8 @@ export class ControlServer {
         }
         state.sessionId = session.sessionId;
         // The project directory an allow-listed built-in step executes in, and
-        // the jail it may not leave (replay/builtins.ts). The session's own cwd
-        // from the hook payloads, never the daemon's.
+        // what its relative paths resolve against (replay/builtins.ts). The
+        // session's own cwd from the hook payloads, never the daemon's.
         state.sessionCwd = session.cwd ?? this.opts.cwd;
         // The request this plan serves, for a note at its decision (SB-18): the
         // turn's prompt. `arm` was given this step's intent instead.

package/dist/replay/builtins.d.ts

@@ -5,7 +5,7 @@
  * A built-in lives inside the host session, not behind any MCP server, so there
  * is no proxy to relay it to: historically every built-in step threw `not_run`
  * and the plan handed the task back to the model. This module is the other
- * option: execute the step here, against the *session's own project directory*,
+ * option: execute the step here, from the *session's own project directory*,
  * so a chain that starts with a `Read` no longer costs a hand-over.
  *
  * THE RULES, because this bypasses the host's permission prompts entirely:
@@ -17,10 +17,17 @@
  *     already has — its pinned call is answered `allow` too. What running it
  *     here changes is that no model sees the call before it runs, so an
  *     operator who wants one in the loop takes the tool off the list.
- *   - **Path jail.** Every path is resolved against, and confined to, the
- *     session's project directory ({@link jailed}), symlinks included. The
- *     daemon's own cwd is never used: it is `~/.baseinstrunner`, not the
- *     project (§5.1 of the change plan).
+ *   - **Any path the agent could reach, unless `BIR_PATH_ALLOW` narrows it.**
+ *     A relative path resolves against the session's project directory, as
+ *     the host's tools resolve it; the daemon's own cwd is never used: it is
+ *     `~/.baseinstrunner`, not the project (§5.1 of the change plan). An
+ *     absolute path is taken as it is, inside the project or not: the agent's
+ *     own tools reach any folder its session allows — the recorded call was
+ *     one of them — and a runner-side `Bash` reaches any folder already. Up
+ *     to 0.3.20 every path was confined to the project directory;
+ *     `BIR_PATH_ALLOW=project` brings that back, and a list of folders
+ *     ({@link parsePathAllow}) confines the file tools to those, symlinks
+ *     included ({@link allowedPath}).
  *   - **Bash runs any command unless `BIR_BASH_ALLOW` narrows it.** Set, a
  *     command must match one of its prefixes ({@link bashAllowed}); `none`
  *     allows no command, and then `Bash` counts as off the list, so its steps
@@ -48,6 +55,12 @@ export declare const EXECUTABLE_BUILTINS: ReadonlySet<string>;
  * set (`Read,Glob,Grep`).
  */
 export declare const DEFAULT_BUILTIN_TOOLS: readonly string[];
+/**
+ * The built-ins that reach files by a path, the ones `BIR_PATH_ALLOW`
+ * governs. `Bash` is not among them: what a command touches is
+ * `BIR_BASH_ALLOW`'s business.
+ */
+export declare const FILE_BUILTINS: ReadonlySet<string>;
 /**
  * Parse `BIR_BUILTIN_TOOLS`. Unset means {@link DEFAULT_BUILTIN_TOOLS}; set,
  * it is the whole list — `none` (or an empty value) turns built-ins off
@@ -63,6 +76,19 @@ export declare function parseBuiltinTools(value: string | undefined): ReadonlySe
  * value) allows no command.
  */
 export declare function parseBashAllow(value: string | undefined): readonly string[];
+/**
+ * Parse `BIR_PATH_ALLOW`: the folders a runner-side `Read`, `Glob`, `Grep`,
+ * `Edit` or `Write` may touch, comma-separated, `*` for anywhere. Unset means
+ * anywhere, as the agent's own tools reach any folder its session allows (up
+ * to 0.3.20 it was the project directory alone). In a list, `project` is the
+ * session's project directory, `~` the home folder (`~/.claude` a folder in
+ * it), and any other relative folder resolves against the project directory.
+ * Set, it is the whole list, as `BIR_BASH_ALLOW` is: `none` (or an empty
+ * value) allows no folder, and the file tools then count as off
+ * `BIR_BUILTIN_TOOLS`, so their steps are steered in the session
+ * (controller.ts).
+ */
+export declare function parsePathAllow(value: string | undefined): readonly string[];
 /**
  * Whether `command` matches the `BIR_BASH_ALLOW` prefixes. A prefix that ends
  * mid-word must end the command's word too: `git` allows `git status` and
@@ -72,8 +98,9 @@ export declare function parseBashAllow(value: string | undefined): readonly stri
 export declare function bashAllowed(command: string, allow: readonly string[] | undefined): boolean;
 /**
  * The step cannot run here — policy, not breakage: the tool is not
- * implemented, its path leaves the project, `Bash` is not allowed, or the
- * input is not even the right shape. Maps to `not_run`: nothing happened, the
+ * implemented, its path is outside the folders `BIR_PATH_ALLOW` names, the
+ * command is not one `BIR_BASH_ALLOW` allows, or the input is not even the
+ * right shape. Maps to `not_run`: nothing happened, the
  * session may still do it, a recorded output may stand in.
  */
 export declare class BuiltinNotRunnable extends Error {
@@ -90,8 +117,9 @@ export declare class BuiltinTimeout extends Error {
 }
 export interface BuiltinContext {
     /**
-     * The session's project directory — the jail every path resolves against.
-     * The caller (controller.ts) refuses to execute at all without one; the
+     * The session's project directory — what a relative path resolves
+     * against, and the folder `project` names in {@link pathAllow}. The
+     * caller (controller.ts) refuses to execute at all without one; the
      * daemon's own cwd is never a substitute.
      */
     cwd: string;
@@ -99,6 +127,14 @@ export interface BuiltinContext {
     timeoutMs?: number;
     /** Parsed `BIR_BASH_ALLOW` ({@link parseBashAllow}). Absent or empty, no command runs. */
     bashAllow?: readonly string[];
+    /**
+     * Parsed `BIR_PATH_ALLOW` ({@link parsePathAllow}): the folders a file
+     * step may touch, `*` for any. Absent means the project directory alone —
+     * a caller that says nothing gets the narrow answer, as with
+     * {@link bashAllow}; the controller always passes the environment's, which
+     * is `*` when the variable is unset. Empty, no file step runs.
+     */
+    pathAllow?: readonly string[];
     /**
      * Where this plan's *previous* `Bash` step left its shell — the host's own
      * semantics, which a recorded chain was written against: the working

package/dist/replay/builtins.js

@@ -5,7 +5,7 @@
  * A built-in lives inside the host session, not behind any MCP server, so there
  * is no proxy to relay it to: historically every built-in step threw `not_run`
  * and the plan handed the task back to the model. This module is the other
- * option: execute the step here, against the *session's own project directory*,
+ * option: execute the step here, from the *session's own project directory*,
  * so a chain that starts with a `Read` no longer costs a hand-over.
  *
  * THE RULES, because this bypasses the host's permission prompts entirely:
@@ -17,10 +17,17 @@
  *     already has — its pinned call is answered `allow` too. What running it
  *     here changes is that no model sees the call before it runs, so an
  *     operator who wants one in the loop takes the tool off the list.
- *   - **Path jail.** Every path is resolved against, and confined to, the
- *     session's project directory ({@link jailed}), symlinks included. The
- *     daemon's own cwd is never used: it is `~/.baseinstrunner`, not the
- *     project (§5.1 of the change plan).
+ *   - **Any path the agent could reach, unless `BIR_PATH_ALLOW` narrows it.**
+ *     A relative path resolves against the session's project directory, as
+ *     the host's tools resolve it; the daemon's own cwd is never used: it is
+ *     `~/.baseinstrunner`, not the project (§5.1 of the change plan). An
+ *     absolute path is taken as it is, inside the project or not: the agent's
+ *     own tools reach any folder its session allows — the recorded call was
+ *     one of them — and a runner-side `Bash` reaches any folder already. Up
+ *     to 0.3.20 every path was confined to the project directory;
+ *     `BIR_PATH_ALLOW=project` brings that back, and a list of folders
+ *     ({@link parsePathAllow}) confines the file tools to those, symlinks
+ *     included ({@link allowedPath}).
  *   - **Bash runs any command unless `BIR_BASH_ALLOW` narrows it.** Set, a
  *     command must match one of its prefixes ({@link bashAllowed}); `none`
  *     allows no command, and then `Bash` counts as off the list, so its steps
@@ -43,7 +50,8 @@ import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
 import { readdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
-import { dirname, join, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 // ── configuration ────────────────────────────────────────────────────────────
 /** The built-ins {@link runBuiltin} actually implements. */
 export const EXECUTABLE_BUILTINS = new Set([
@@ -61,8 +69,24 @@ export const EXECUTABLE_BUILTINS = new Set([
  * set (`Read,Glob,Grep`).
  */
 export const DEFAULT_BUILTIN_TOOLS = [...EXECUTABLE_BUILTINS];
+/**
+ * The built-ins that reach files by a path, the ones `BIR_PATH_ALLOW`
+ * governs. `Bash` is not among them: what a command touches is
+ * `BIR_BASH_ALLOW`'s business.
+ */
+export const FILE_BUILTINS = new Set(["Read", "Glob", "Grep", "Edit", "Write"]);
 /** `read` → `Read`: the vocabulary is small enough to forgive casing. */
 const CANONICAL_BUILTIN = new Map([...EXECUTABLE_BUILTINS].map((name) => [name.toLowerCase(), name]));
+/**
+ * A switch's list once it is set: comma-separated, trimmed, empty entries
+ * dropped, and `none` / `off` / `0` meaning nothing at all.
+ */
+function parseList(value) {
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0 && !["none", "off", "0"].includes(s.toLowerCase()));
+}
 /**
  * Parse `BIR_BUILTIN_TOOLS`. Unset means {@link DEFAULT_BUILTIN_TOOLS}; set,
  * it is the whole list — `none` (or an empty value) turns built-ins off
@@ -73,12 +97,7 @@ const CANONICAL_BUILTIN = new Map([...EXECUTABLE_BUILTINS].map((name) => [name.t
 export function parseBuiltinTools(value) {
     if (value === undefined)
         return new Set(DEFAULT_BUILTIN_TOOLS);
-    const names = value
-        .split(",")
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0 && !["none", "off", "0"].includes(s.toLowerCase()))
-        .map((s) => CANONICAL_BUILTIN.get(s.toLowerCase()) ?? s);
-    return new Set(names);
+    return new Set(parseList(value).map((s) => CANONICAL_BUILTIN.get(s.toLowerCase()) ?? s));
 }
 /**
  * Parse `BIR_BASH_ALLOW`: comma-separated command prefixes, `*` for
@@ -89,10 +108,24 @@ export function parseBuiltinTools(value) {
 export function parseBashAllow(value) {
     if (value === undefined)
         return ["*"];
-    return value
-        .split(",")
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0 && !["none", "off", "0"].includes(s.toLowerCase()));
+    return parseList(value);
+}
+/**
+ * Parse `BIR_PATH_ALLOW`: the folders a runner-side `Read`, `Glob`, `Grep`,
+ * `Edit` or `Write` may touch, comma-separated, `*` for anywhere. Unset means
+ * anywhere, as the agent's own tools reach any folder its session allows (up
+ * to 0.3.20 it was the project directory alone). In a list, `project` is the
+ * session's project directory, `~` the home folder (`~/.claude` a folder in
+ * it), and any other relative folder resolves against the project directory.
+ * Set, it is the whole list, as `BIR_BASH_ALLOW` is: `none` (or an empty
+ * value) allows no folder, and the file tools then count as off
+ * `BIR_BUILTIN_TOOLS`, so their steps are steered in the session
+ * (controller.ts).
+ */
+export function parsePathAllow(value) {
+    if (value === undefined)
+        return ["*"];
+    return parseList(value);
 }
 /**
  * Whether `command` matches the `BIR_BASH_ALLOW` prefixes. A prefix that ends
@@ -117,8 +150,9 @@ export function bashAllowed(command, allow) {
 // ── the failure contract ─────────────────────────────────────────────────────
 /**
  * The step cannot run here — policy, not breakage: the tool is not
- * implemented, its path leaves the project, `Bash` is not allowed, or the
- * input is not even the right shape. Maps to `not_run`: nothing happened, the
+ * implemented, its path is outside the folders `BIR_PATH_ALLOW` names, the
+ * command is not one `BIR_BASH_ALLOW` allows, or the input is not even the
+ * right shape. Maps to `not_run`: nothing happened, the
  * session may still do it, a recorded output may stand in.
  */
 export class BuiltinNotRunnable extends Error {
@@ -186,7 +220,9 @@ export async function runBuiltin(toolName, input, ctx) {
             throw new BuiltinNotRunnable(`no runner-side implementation for ${toolName}`);
     }
 }
-// ── the path jail ────────────────────────────────────────────────────────────
+// ── which paths a file step may touch ────────────────────────────────────────
+/** The word in `BIR_PATH_ALLOW` that stands for the session's project directory. */
+const PROJECT_WORD = "project";
 /** Case-blind on Windows, where `C:\Repo` and `c:\repo` are one directory. */
 function samePath(a, b) {
     return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
@@ -199,54 +235,87 @@ function underRoot(root, abs) {
             : abs.startsWith(prefix)));
 }
 /**
- * Resolve `p` against the session root and refuse anything outside it — first
- * textually, then through `realpath` so a symlink inside the project cannot
- * point the step at a file beyond it. The nearest existing ancestor is what
- * gets resolved, so a `Write` to a new file is judged by its real directory.
+ * The folders the context's `BIR_PATH_ALLOW` list names, as absolute paths,
+ * or `anywhere` for `*`. `project` is the session's project directory, `~`
+ * the home folder, and any other relative entry resolves against the project.
  */
-async function jailed(root, p, what = "file_path") {
-    if (typeof p !== "string" || p.trim() === "") {
-        throw new BuiltinNotRunnable(`${what} is required`);
-    }
-    const r = resolve(root);
-    const abs = resolve(r, p);
-    const outside = () => {
-        throw new BuiltinNotRunnable(`${p} is outside the session's project directory, so bir does not touch it unattended`);
-    };
-    if (!underRoot(r, abs))
-        outside();
-    // The textual check passed; now the physical one. Walk up to what exists,
-    // realpath it, and require *that* to sit under the root's own realpath.
+function allowedFolders(ctx) {
+    const allow = ctx.pathAllow ?? [PROJECT_WORD];
+    if (allow.includes("*"))
+        return "anywhere";
+    const project = resolve(ctx.cwd);
+    return allow.map((entry) => {
+        if (entry.toLowerCase() === PROJECT_WORD)
+            return project;
+        if (entry === "~")
+            return homedir();
+        if (entry.startsWith("~/") || entry.startsWith("~\\"))
+            return resolve(homedir(), entry.slice(2));
+        return resolve(project, entry);
+    });
+}
+/** Why a path was refused, naming the switch that refused it. */
+function outsideMessage(p, allow) {
+    return allow.length === 1 && allow[0].toLowerCase() === PROJECT_WORD
+        ? `${p} is outside the session's project directory, and BIR_PATH_ALLOW=project keeps bir inside it`
+        : `${p} is outside the folders BIR_PATH_ALLOW names (${allow.join(", ")}), so bir does not touch it unattended`;
+}
+/**
+ * `abs` as it is on disk: its longest existing ancestor replaced by that
+ * ancestor's realpath (symlinks resolved, and on macOS `/var` read as
+ * `/private/var`), the rest kept as written. A path none of which exists
+ * comes back as it is.
+ */
+async function physical(abs) {
     let probe = abs;
-    let real;
+    const rest = [];
     for (;;) {
         try {
-            real = await realpath(probe);
-            break;
+            const real = await realpath(probe);
+            return rest.length > 0 ? join(real, ...rest.reverse()) : real;
         }
         catch {
             const parent = dirname(probe);
             if (samePath(parent, probe))
-                break; // hit the filesystem root: nothing exists
+                return abs; // the filesystem root: nothing exists
+            rest.push(basename(probe));
             probe = parent;
         }
     }
-    if (real !== undefined) {
-        let realRoot;
-        try {
-            realRoot = await realpath(r);
-        }
-        catch {
-            throw new BuiltinNotRunnable(`the session's project directory does not exist: ${root}`);
-        }
-        if (!underRoot(realRoot, real))
-            outside();
+}
+/**
+ * Resolve `p` as the host does — against the session's project directory
+ * when it is relative — and allow it anywhere, as the agent's own tools
+ * would, unless `BIR_PATH_ALLOW` names folders. Then anything outside them is
+ * refused: first as written, then physically ({@link physical}, both sides),
+ * so a symlink inside an allowed folder cannot point the step at a file
+ * beyond it, and a `Write` to a new file is judged by its real folder.
+ */
+async function allowedPath(ctx, p, what = "file_path") {
+    if (typeof p !== "string" || p.trim() === "") {
+        throw new BuiltinNotRunnable(`${what} is required`);
     }
+    const abs = resolve(ctx.cwd, p);
+    const folders = allowedFolders(ctx);
+    if (folders === "anywhere")
+        return abs;
+    if (folders.length === 0) {
+        throw new BuiltinNotRunnable("BIR_PATH_ALLOW allows no folder, so bir touches no file unattended");
+    }
+    const outside = () => {
+        throw new BuiltinNotRunnable(outsideMessage(p, ctx.pathAllow ?? [PROJECT_WORD]));
+    };
+    if (!folders.some((folder) => underRoot(folder, abs)))
+        outside();
+    const real = await physical(abs);
+    const realFolders = await Promise.all(folders.map(physical));
+    if (!realFolders.some((folder) => underRoot(folder, real)))
+        outside();
     return abs;
 }
 // ── Read ─────────────────────────────────────────────────────────────────────
 async function runRead(input, ctx) {
-    const filePath = await jailed(ctx.cwd, input.file_path);
+    const filePath = await allowedPath(ctx, input.file_path);
     const size = (await stat(filePath)).size;
     if (size > MAX_FILE_BYTES) {
         throw new Error(`file is ${size} bytes, more than the ${MAX_FILE_BYTES} this runner reads`);
@@ -276,7 +345,7 @@ async function runGlob(input, ctx, deadline) {
     if (typeof pattern !== "string" || pattern.trim() === "") {
         throw new BuiltinNotRunnable("pattern is required");
     }
-    const root = await jailed(ctx.cwd, typeof input.path === "string" ? input.path : ".", "path");
+    const root = await allowedPath(ctx, typeof input.path === "string" ? input.path : ".", "path");
     const startedAt = Date.now();
     const re = globToRegExp(pattern);
     const found = [];
@@ -324,7 +393,7 @@ async function runGrep(input, ctx, deadline) {
     catch (err) {
         throw new BuiltinNotRunnable(`the pattern is not a regular expression this runner can run: ${err.message}`);
     }
-    const target = await jailed(ctx.cwd, typeof input.path === "string" ? input.path : ".", "path");
+    const target = await allowedPath(ctx, typeof input.path === "string" ? input.path : ".", "path");
     // ripgrep's `-g '*.ts'` matches the basename at any depth; only a pattern
     // with a `/` in it speaks about the path.
     const globRe = typeof input.glob === "string" && input.glob
@@ -417,7 +486,7 @@ async function matchFile(path, re, firstOnly) {
 }
 // ── Edit / Write ─────────────────────────────────────────────────────────────
 async function runEdit(input, ctx) {
-    const filePath = await jailed(ctx.cwd, input.file_path);
+    const filePath = await allowedPath(ctx, input.file_path);
     const oldString = input.old_string;
     const newString = input.new_string;
     if (typeof oldString !== "string" || oldString === "") {
@@ -452,7 +521,7 @@ async function runEdit(input, ctx) {
     };
 }
 async function runWrite(input, ctx) {
-    const filePath = await jailed(ctx.cwd, input.file_path);
+    const filePath = await allowedPath(ctx, input.file_path);
     const content = input.content;
     if (typeof content !== "string")
         throw new BuiltinNotRunnable("content is required");
@@ -579,9 +648,10 @@ function takePwdMarker(stderr, mark) {
 const SKIP_DIRS = new Set([".git", "node_modules", ".hg", ".svn"]);
 /**
  * Walk `root`, calling `visit(relativePath, absolutePath, mtimeMs)` for every
- * regular file. Never follows directory symlinks — the jail was checked at
- * the root, and a link out of it must not re-open the door. Returns whether
- * the walk was cut short (entry cap, deadline, or `visit` saying stop).
+ * regular file. Never follows directory symlinks — the folder was checked at
+ * the root, and under a `BIR_PATH_ALLOW` list a link out of it must not
+ * re-open the door (nor may a link loop the walk). Returns whether the walk
+ * was cut short (entry cap, deadline, or `visit` saying stop).
  */
 async function walk(root, deadline, visit) {
     let seen = 0;
@@ -617,7 +687,9 @@ async function walk(root, deadline, visit) {
             catch {
                 continue;
             }
-            const rel = abs.slice(resolve(root).length + 1).split(sep).join("/");
+            // `relative`, not a slice: a walk may now start at a drive's or the
+            // disk's root (`C:\`, `/`), which already ends in a separator.
+            const rel = relative(root, abs).split(sep).join("/");
             if (!visit(rel, abs, mtime))
                 return true;
         }

package/dist/replay/controller.d.ts

@@ -266,6 +266,16 @@ export interface ReplayOptions {
      * rather than armed `direct` and stopped at the first one.
      */
     bashAllow?: readonly string[];
+    /**
+     * `BIR_PATH_ALLOW` — the folders a runner-side `Read`, `Glob`, `Grep`,
+     * `Edit` or `Write` may touch (`*` for any; `project` is the session's
+     * project directory). Omitted, the environment decides; the default is
+     * `*`, any path the agent's own tools could reach (up to 0.3.20 the
+     * project directory alone). Empty allows no folder, and then the file tools
+     * count as off {@link ReplayOptions.builtinTools}, as `Bash` does under an
+     * empty {@link ReplayOptions.bashAllow}.
+     */
+    pathAllow?: readonly string[];
     budgets?: Partial<ReplayBudgets>;
     /**
      * The service: the lazy source-run fetch, and the parameter derivation this
@@ -418,8 +428,9 @@ export interface ReplayState {
     /**
      * That session's project directory, set by the control server from the
      * hook payloads — never the daemon's own cwd, which is `~/.baseinstrunner`.
-     * It is where an allow-listed built-in step executes and the jail it may
-     * not leave (replay/builtins.ts). Absent — `bir replay`, an older server —
+     * It is where an allow-listed built-in step executes and what its relative
+     * paths resolve against (replay/builtins.ts; `BIR_PATH_ALLOW=project`
+     * confines the file tools to it). Absent — `bir replay`, an older server —
      * no built-in executes: the step is `not_run`, exactly as before.
      */
     sessionCwd?: string;
@@ -689,6 +700,8 @@ export declare class ReplayController {
     private readonly builtinTools;
     /** See {@link ReplayOptions.bashAllow}. */
     private readonly bashAllow;
+    /** See {@link ReplayOptions.pathAllow}. */
+    private readonly pathAllow;
     /** Calls waiting for a plan's pins to change (see `awaitPins`). */
     private readonly pinWaiters;
     /**

package/dist/replay/controller.js

@@ -18,7 +18,7 @@ import { capText, DEFAULT_MAX_PAYLOAD_BYTES, REPORT_PAYLOAD_MAX_BYTES, serialize
 import { logDetail, logLine, errText } from "../util/log.js";
 import { serviceHealth, serviceTimeoutMs, timeoutSignal, } from "../util/service-health.js";
 import { bashCommandFor } from "./bash-channel.js";
-import { BuiltinNotRunnable, BuiltinTimeout, parseBashAllow, parseBuiltinTools, runBuiltin, } from "./builtins.js";
+import { BuiltinNotRunnable, BuiltinTimeout, FILE_BUILTINS, parseBashAllow, parseBuiltinTools, parsePathAllow, runBuiltin, } from "./builtins.js";
 import { BASH_CHANNEL_MAX, MAX_REPLAY_REASON, testWords, truncate } from "./bundle.js";
 import { coverageOf, modeFor, reachOf } from "./coverage.js";
 import { deriveParameters, localDay, } from "./derive.js";
@@ -216,6 +216,8 @@ export class ReplayController {
     builtinTools;
     /** See {@link ReplayOptions.bashAllow}. */
     bashAllow;
+    /** See {@link ReplayOptions.pathAllow}. */
+    pathAllow;
     /** Calls waiting for a plan's pins to change (see `awaitPins`). */
     pinWaiters = new WeakMap();
     /**
@@ -277,13 +279,17 @@ export class ReplayController {
         this.recordedFallback =
             opts.recordedFallback ?? process.env.BIR_REPLAY_RECORDED_OUTPUTS === "1";
         this.bashAllow = opts.bashAllow ?? parseBashAllow(process.env.BIR_BASH_ALLOW);
+        this.pathAllow = opts.pathAllow ?? parsePathAllow(process.env.BIR_PATH_ALLOW);
         const builtins = opts.builtinTools ?? parseBuiltinTools(process.env.BIR_BUILTIN_TOOLS);
-        // A `Bash` that may run no command is not reachable here. Left on the
-        // list, a chain of Bash steps would arm `direct` and stop at its first.
-        this.builtinTools =
-            this.bashAllow.length > 0 || !builtins.has("Bash")
-                ? builtins
-                : new Set([...builtins].filter((name) => name !== "Bash"));
+        // A `Bash` that may run no command, or a file tool that may touch no
+        // folder, is not reachable here. Left on the list, a chain of such steps
+        // would arm `direct` and stop at its first.
+        const reachable = (name) => name === "Bash"
+            ? this.bashAllow.length > 0
+            : !FILE_BUILTINS.has(name) || this.pathAllow.length > 0;
+        this.builtinTools = [...builtins].every(reachable)
+            ? builtins
+            : new Set([...builtins].filter(reachable));
     }
     /**
      * Whether a handed-out segment may actually arm (segmented.md R-OUT-10).
@@ -2873,11 +2879,12 @@ export class ReplayController {
             }
             const mcp = parseQualifiedName(name);
             if (!mcp) {
-                // An allow-listed built-in runs *here*, against the session's own
+                // An allow-listed built-in runs *here*, from the session's own
                 // project directory (replay/builtins.ts). Everything else about it —
                 // no session cwd (`bir replay`, an older server), off the list, no
-                // runner-side implementation, a path that leaves the project, a `Bash`
-                // command `BIR_BASH_ALLOW` does not allow — stays the old contract:
+                // runner-side implementation, a path outside the folders
+                // `BIR_PATH_ALLOW` names, a `Bash` command `BIR_BASH_ALLOW` does not
+                // allow — stays the old contract:
                 // `not_run`, so the session can do the step itself or its recorded
                 // output can stand in (`BIR_REPLAY_RECORDED_OUTPUTS=1`).
                 if (this.builtinTools.has(name) && state.sessionCwd) {
@@ -2939,6 +2946,9 @@ export class ReplayController {
                 cwd,
                 timeoutMs,
                 bashAllow: this.bashAllow,
+                // Any folder unless `BIR_PATH_ALLOW` names some, as the agent's own
+                // tools would reach it (up to 0.3.20, the project directory alone).
+                pathAllow: this.pathAllow,
                 // The plan's Bash steps share a working directory, as the host's do.
                 bashCwd: state.bashCwd,
                 onBashCwd: (pwd) => {

package/docs/calculatedReplay.md

@@ -45,7 +45,7 @@ this design has a ladder whose cheapest rung is free — and the more of a stack
 |---|---|---|
 | Runs MCP tools itself | No (`replay.md` §12: *"rrepeat never executes tools — not even MCP"*) | **Yes**, on the connection it already owns |
 | Divergence fallback | A second Agent SDK session — the dominant cost | Direct `tools/call` through the proxies — **$0** |
-| Reaches built-ins (`Bash`, `Read`) | Only by steering the live session | `Read`, `Glob`, `Grep`, `Edit`, `Write` and `Bash` run on the runner itself, jailed to the project (`BIR_BUILTIN_TOOLS`, `BIR_BASH_ALLOW`); any other built-in is steered. In a host that is not Claude Code a tool with one of these names is the application's own, and the runner runs none of them (§7.4) |
+| Reaches built-ins (`Bash`, `Read`) | Only by steering the live session | `Read`, `Glob`, `Grep`, `Edit`, `Write` and `Bash` run on the runner itself, on any path the agent could reach unless `BIR_PATH_ALLOW` names folders (`BIR_BUILTIN_TOOLS`, `BIR_BASH_ALLOW`, `BIR_PATH_ALLOW`); any other built-in is steered. In a host that is not Claude Code a tool with one of these names is the application's own, and the runner runs none of them (§7.4) |
 | Needs `@anthropic-ai/*` at runtime | Yes | No (§16.3) |
 
 ---
@@ -265,7 +265,7 @@ export function modeFor(steps: SerializedScenarioStep[], wrapped: ReadonlySet<st
 
 | Every step | Mode | Where the tools run | Model spend |
 |---|---|---|---|
-| a wrapped MCP tool, or a built-in on `BIR_BUILTIN_TOOLS` | **`direct`** (§6) | The proxies, on connections already open; allow-listed built-ins on the runner itself, jailed to the session's project directory (replay/builtins.ts) | one Haiku derivation + one turn that reads the results |
+| a wrapped MCP tool, or a built-in on `BIR_BUILTIN_TOOLS` | **`direct`** (§6) | The proxies, on connections already open; allow-listed built-ins on the runner itself, from the session's project directory (replay/builtins.ts) | one Haiku derivation + one turn that reads the results |
 | anything else, or mixed | **`steer`** (§7) | The live session, inputs pinned | one Haiku derivation + the live turn |
 | — | `none` | nowhere | declines at gate 5 |
 
@@ -275,11 +275,17 @@ so `Task`, `WebFetch`; up to 0.3.7 also `Bash`, `Edit`, `Write`), an MCP server
 `claude-in-chrome` — which is `scope: "dynamic"`, appears in no config file, and therefore can never
 be wrapped (v1 design §1). None of them can be reached except through the session.
 
-A built-in **on** the allow-list runs on the runner, in the session's own project directory and
-confined to it — a path that resolves outside the project, symlinks included, is refused and the
-step is `not_run`, the clean hand-over. `Bash` has a second switch on top (`BIR_BASH_ALLOW`,
-command prefixes; unset means any command, `none` keeps `Bash` in the session), because a
-runner-side step never reaches the host's permission prompts. The
+A built-in **on** the allow-list runs on the runner, from the session's own project directory: a
+relative path resolves against it, as the host's tools resolve it, and an absolute path is taken
+as it is, inside the project or not — the agent's own tools reach any folder its session allows,
+and the recorded call was one of them (up to 0.3.20 every path was confined to the project, and a
+plan that read the agent's memory file under `~/.claude` handed the whole task back). The file
+tools have a switch of their own (`BIR_PATH_ALLOW`, folders; unset means any, `project` brings
+back the confinement, `project,~/.claude` adds a folder, `none` keeps them in the session); under
+a list, a path outside it, symlinks included, is refused and the step is `not_run`, the clean
+hand-over. `Bash` has its switch too (`BIR_BASH_ALLOW`, command prefixes; unset means any command,
+`none` keeps `Bash` in the session), because a runner-side step never reaches the host's
+permission prompts. The
 results mimic the hook's view of each tool, which is what the recorder stored for built-in steps
 and what their `toolOutputLogic` was authored against; they pass through the same
 `serializeCapped(redact(…))` as every recorded payload. Bash keeps the host's own semantics a

package/docs/calculatedReplayGuide.md

@@ -241,8 +241,10 @@ When replay arms:
   §7) — and never in plan mode.
 - **Direct steps are not visible to the permission system at all.** They are dispatched straight to a
   `bir-proxy`, which calls the upstream on a connection it already holds — or, for Claude Code's own
-  `Read`, `Glob`, `Grep`, `Edit`, `Write` and `Bash`, run by the recorder itself in the project
-  folder, any `Bash` command included (`BIR_BUILTIN_TOOLS`, `BIR_BASH_ALLOW`; up to 0.3.7 only the
+  `Read`, `Glob`, `Grep`, `Edit`, `Write` and `Bash`, run by the recorder itself from the project
+  folder, on any file the agent could reach (from 0.3.21; up to 0.3.20 only files inside the
+  project) and any `Bash` command included (`BIR_BUILTIN_TOOLS`, `BIR_PATH_ALLOW`,
+  `BIR_BASH_ALLOW`; up to 0.3.7 only the
   first three). Claude Code never sees them.
   The `run_scenario` call that starts them is answered `allow` too, while the runner has announced a
   direct plan; your own deny or ask rules for it still apply.
@@ -253,7 +255,8 @@ That is what makes replay fast, and it is the whole risk. Two things follow:
 2. Run `bir replay allow <servers>` (§5.3). An allowlist of the servers you are comfortable having
    called unattended is cheap insurance, and it is the difference between "replay reads a dashboard"
    and "replay can do anything any wrapped server can do". The same goes for built-ins:
-   `BIR_BUILTIN_TOOLS=Read,Glob,Grep` keeps writes and commands with the model, and
+   `BIR_BUILTIN_TOOLS=Read,Glob,Grep` keeps writes and commands with the model,
+   `BIR_PATH_ALLOW=project` keeps the file tools inside the project folder, and
    `BIR_BASH_ALLOW=git,npm test` (for example) limits the commands the recorder runs itself.
 
 Nothing else is approved on your behalf. Outside a matched scenario's own steps, a wrapped MCP call
@@ -368,8 +371,9 @@ so there is exactly one switch and it cannot get out of step with itself.
 | `BIR_STEP_TIMEOUT_MS` | `60000` | Per-step ceiling for one direct `tools/call`, clipped to what the plan has left |
 | `BIR_LOGIC_TIMEOUT_MS` | `1000` | How long one scenario logic body may run before it is stopped. At most 10 000 |
 | `BIR_REPLAY_RECORDED_OUTPUTS` | *(unset)* | `1` lets a step that could not be sent (a built-in off `BIR_BUILTIN_TOOLS`, no proxy, a server off the allowlist) stand on its recorded output instead of stopping the plan. Never for a timeout or an upstream error |
-| `BIR_BUILTIN_TOOLS` | `Read,Glob,Grep,Edit,Write,Bash` | Built-ins the runner executes itself during a replay, in the session's own project directory and confined to it. A chain whose only non-MCP steps are on this list arms `direct`. A runner-side step never reaches the host's permission prompts, so leave off any tool you want the model to call itself; `Read,Glob,Grep` is the read-only set (the default up to 0.3.7). `none`: every built-in step is steered in the session. Claude Code sessions only: in a LangChain application a tool with one of these names is the application's own, and the runner runs none (§6.5) |
+| `BIR_BUILTIN_TOOLS` | `Read,Glob,Grep,Edit,Write,Bash` | Built-ins the runner executes itself during a replay, from the session's own project directory (which folders the file tools may touch: `BIR_PATH_ALLOW`). A chain whose only non-MCP steps are on this list arms `direct`. A runner-side step never reaches the host's permission prompts, so leave off any tool you want the model to call itself; `Read,Glob,Grep` is the read-only set (the default up to 0.3.7). `none`: every built-in step is steered in the session. Claude Code sessions only: in a LangChain application a tool with one of these names is the application's own, and the runner runs none (§6.5) |
 | `BIR_BASH_ALLOW` | *(unset: any command)* | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset means any command; `none` means no command, and `Bash` steps are steered in the session. A plan's Bash steps share a working directory, exactly as the host's own Bash tool does — variables and functions do not persist, also as the host's. A call with `run_in_background`, or with its own `timeout` longer than the step's clock (`BIR_STEP_TIMEOUT_MS`), is never started on the runner: the plan hands over in front of it |
+| `BIR_PATH_ALLOW` | *(unset: any folder, from 0.3.21)* | Folders a runner-side `Read`, `Glob`, `Grep`, `Edit` or `Write` may touch (`*` for all). Unset means any path, as the agent's own tools reach it — a plan that reads the agent's memory file under `~/.claude` runs. `project` is the session's project folder alone (the rule up to 0.3.20); add folders after a comma, `~` for the home folder: `project,~/.claude`. Under a list, a path outside it, symlinks included, is refused and the plan hands over in front of it. `none` means no folder, and the file steps are steered in the session. `Bash` is `BIR_BASH_ALLOW`'s |
 | `BIR_SEGMENT_ARM` | *(unset: on, from 0.3.19)* | A segment the service hands out runs mid-task: a recurring sub-task, or a half of a task after a plan's decision. `0` is observe-only: what would have armed is logged (`replay.segment_would_arm`) and nothing is replaced. Up to 0.3.18 observe-only was the default. A recorder started before an update keeps its old default until `bir up --restart` |
 | `BIR_INTENT_ARM` | *(unset)* | `1` lets a match found mid-turn arm a plan in the calling tool's place, which means waiting for it (`BIR_INTENT_ARM_BUDGET_MS`, 500); `0` never waits, and then nothing starts mid-task, segments included: what would have armed is logged; unset follows `BIR_SEGMENT_ARM`, so from 0.3.19 it is on unless `BIR_SEGMENT_ARM=0` |
 | `BIR_VERBOSE` | *(unset)* | `1` adds per-step `replay.*` detail lines |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.3.20",
+  "version": "0.3.21",
   "description": "A recording MCP proxy: sits between any MCP client and its MCP servers, executes each call on the client's behalf, and records the run as a reusable BaseIn scenario.",
   "type": "module",
   "license": "MIT",

package/production.md

@@ -1071,8 +1071,9 @@ Defaults were checked in `src/`.
 | `BIR_STEP_TIMEOUT_MS` | recorder | 60000 | One direct `tools/call`. |
 | `BIR_LOGIC_TIMEOUT_MS` | recorder | 1000 (capped at 10000) | Synchronous time limit for one scenario logic body. |
 | `BIR_REPLAY_RECORDED_OUTPUTS` | recorder | unset | `1`: a step that could not be sent may use its recorded output, labelled as such. |
-| `BIR_BUILTIN_TOOLS` | recorder | `Read,Glob,Grep,Edit,Write,Bash` | Built-ins the runner executes itself during a replay, in the session's project directory and confined to it (up to 0.3.7 the default was `Read,Glob,Grep`). Runner-side steps bypass the host's permission prompts; leave a tool off to have the model call it. `none` turns it off. Not in a session of another host (§3.2): the runner runs no step itself there, whatever a tool is named. |
+| `BIR_BUILTIN_TOOLS` | recorder | `Read,Glob,Grep,Edit,Write,Bash` | Built-ins the runner executes itself during a replay, from the session's project directory; which folders the file tools may touch is `BIR_PATH_ALLOW` (up to 0.3.7 the default was `Read,Glob,Grep`). Runner-side steps bypass the host's permission prompts; leave a tool off to have the model call it. `none` turns it off. Not in a session of another host (§3.2): the runner runs no step itself there, whatever a tool is named. |
 | `BIR_BASH_ALLOW` | recorder | unset (any command) | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset means any command; `none` means no command, and `Bash` steps are steered. A plan's Bash steps share a working directory, as the host's do; variables do not persist, also as the host's. |
+| `BIR_PATH_ALLOW` | recorder | unset (any folder) | Folders a runner-side `Read`, `Glob`, `Grep`, `Edit` or `Write` may touch (`*` for all). Unset means any path, as the agent's own tools (from 0.3.21; up to 0.3.20 the project directory alone). `project` is the session's project directory, `~` the home folder: `project,~/.claude`. Under a list, a path outside it, symlinks included, is `not_run` (hand-over). `none` means no folder, and file steps are steered. |
 | `BIR_DERIVE_RECENT_RESULTS` | recorder | 5 | How many of this prompt's tool results derivation may read (`0`: none). Never for plans with a command sink, and never for a plan started at the prompt: a prompt just submitted has no results yet, and an earlier prompt's are not its own. So in a session of another host, where a plan starts at the prompt only, none are read. |
 | `BIR_INTENT_MATCH` | recorder | on | `0` turns mid-turn intent probes off. |
 | `BIR_INTENT_MATCH_BUDGET_MS` | recorder | 4000 | One probe's own ceiling. It is not a hook wait. |