@basein/runner 0.3.1 → 0.3.2

package/README.md

@@ -413,6 +413,8 @@ 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 `Read,Glob,Grep` (read-only). Add `Edit,Write,Bash` only deliberately: a runner-side step never reaches Claude Code's permission prompts. `none` turns it off, and a built-in step hands the turn back as before. |
+| `BIR_BASH_ALLOW` | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset, `Bash` never executes on the runner, even when `BIR_BUILTIN_TOOLS` lists it. |
 | `BIR_MIN_STEER_SIMILARITY` | Minimum match similarity to replay (default `0.92`, above the service's own `0.9` detection threshold). |
 | `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. |

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

@@ -61,6 +61,18 @@
  *                             mode; every other tool call is asked as usual.
  *   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 Read,Glob,Grep —
+ *                             the read-only set. Add Edit,Write,Bash only
+ *                             deliberately: a runner-side step never reaches
+ *                             the host's permission prompts. `none` turns
+ *                             built-ins off, and then a built-in step hands
+ *                             the turn back, as before
+ *   BIR_BASH_ALLOW            command prefixes a runner-side Bash step may run
+ *                             (`*` for all). Unset, Bash never executes on the
+ *                             runner even when BIR_BUILTIN_TOOLS lists it
  *   BIR_MIN_STEER_SIMILARITY  minimum match similarity to replay (default 0.92)
  *   BIR_DERIVE_API_KEY        OPTIONAL. Derivation — reading what this turn acts
  *                             on — is done by the service for a signed-in

package/dist/bin/bir-hooks.js

@@ -61,6 +61,18 @@
  *                             mode; every other tool call is asked as usual.
  *   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 Read,Glob,Grep —
+ *                             the read-only set. Add Edit,Write,Bash only
+ *                             deliberately: a runner-side step never reaches
+ *                             the host's permission prompts. `none` turns
+ *                             built-ins off, and then a built-in step hands
+ *                             the turn back, as before
+ *   BIR_BASH_ALLOW            command prefixes a runner-side Bash step may run
+ *                             (`*` for all). Unset, Bash never executes on the
+ *                             runner even when BIR_BUILTIN_TOOLS lists it
  *   BIR_MIN_STEER_SIMILARITY  minimum match similarity to replay (default 0.92)
  *   BIR_DERIVE_API_KEY        OPTIONAL. Derivation — reading what this turn acts
  *                             on — is done by the service for a signed-in

package/dist/control/recorder-main.js

@@ -26,6 +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 { parseAllowList } from "../replay/coverage.js";
 import { sweepDeliveries } from "../replay/bash-channel.js";
 import { exemptLoopbackFromProxy, isWrapped, projectRecord, projectToken, readSidecar, } from "../config/generate.js";
@@ -177,10 +178,18 @@ function buildReplayOptions(keeper, policy, key) {
             ? parseAllowList(policy.allowServers.join(","))
             : undefined;
     const minSimilarity = Number.isFinite(envMin) ? envMin : (policy?.minSimilarity ?? 0.92);
+    // Which built-ins the runner may execute itself (replay/builtins.ts):
+    // read-only by default, `BIR_BUILTIN_TOOLS` to change, `BIR_BASH_ALLOW`
+    // before a `Bash` step may run at all. 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 opts = {
         enabled,
         minSimilarity,
         allowServers,
+        builtinTools,
+        bashAllow,
         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.
@@ -237,6 +246,10 @@ function buildReplayOptions(keeper, policy, key) {
         logLine("replay.enabled", {
             minSimilarity: opts.minSimilarity,
             allowServers: allowServers ? [...allowServers].join(",") : "(all wrapped)",
+            // Which built-ins may run on the runner itself, and whether Bash may at
+            // all — loud for the same reason as the rest of this line.
+            builtins: builtinTools.size > 0 ? [...builtinTools].join(",") : "(none)",
+            bashAllow: builtinTools.has("Bash") ? (bashAllow ? bashAllow.join(",") : "(unset — Bash never runs here)") : 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

@@ -1546,6 +1546,10 @@ export class ControlServer {
             return undefined;
         }
         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.
+        state.sessionCwd = session.cwd ?? this.opts.cwd;
         this.declineWithoutDeliveryTool(state);
         // A steer plan with a shell or file-write step can only be followed if the
         // directive shows its computed arguments (the pin guard holds those steps
@@ -1643,6 +1647,10 @@ export class ControlServer {
             return undefined;
         }
         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.
+        state.sessionCwd = session.cwd ?? this.opts.cwd;
         run.replay = state;
         run.replays.push(state);
         return undefined;
@@ -3014,6 +3022,10 @@ export class ControlServer {
             return undefined;
         }
         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.
+        state.sessionCwd = session.cwd ?? this.opts.cwd;
         this.declineWithoutDeliveryTool(state);
         if (!state.plan) {
             // A declined intent hit reports nothing: the turn's cost is not a

package/dist/replay/builtins.d.ts

@@ -0,0 +1,120 @@
+/**
+ * builtins — running a scenario's built-in steps (`Read`, `Glob`, `Grep`,
+ * `Edit`, `Write`, `Bash`) on the runner itself (docs/calculatedReplay.md §5).
+ *
+ * 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*,
+ * 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:
+ *
+ *   - **Default deny beyond read-only.** Which built-ins may run at all is
+ *     `BIR_BUILTIN_TOOLS` ({@link parseBuiltinTools}), and its default is the
+ *     read-only set (`Read,Glob,Grep`). `Edit`, `Write` and `Bash` are an
+ *     explicit, per-environment opt-in — a recorded `rm` must never run
+ *     because a prompt looked similar.
+ *   - **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).
+ *   - **Bash runs nothing unless `BIR_BASH_ALLOW` says so.** A command must
+ *     match one of its prefixes ({@link bashAllowed}); unset means `Bash`
+ *     never executes here, even when allow-listed.
+ *   - **Same failure contract as an MCP step.** A step that *cannot* run here
+ *     throws {@link BuiltinNotRunnable} (→ `not_run`: the session can still do
+ *     it, or a recorded output may stand in under
+ *     `BIR_REPLAY_RECORDED_OUTPUTS=1`). One that ran out of time throws
+ *     {@link BuiltinTimeout} (→ `uncertain`). Any other throw is a step that
+ *     ran and failed (→ `failed`), never silently threaded as a success.
+ *
+ * Outputs mimic the **hook view** of each tool — Claude Code's `tool_response`
+ * as `PostToolUse` reports it — because that is exactly what the recorder
+ * stored for built-in steps (control/server.ts, `onToolPost`) and therefore
+ * what each step's `toolOutputLogic` was authored against. The shapes are a
+ * best effort and may drift from a future host's, the same caveat the
+ * hook-view threading fallback already carries ("shapes may differ").
+ */
+/**
+ * The built-ins bir may stand in for or execute when `BIR_BUILTIN_TOOLS` is
+ * unset: the read-only set. Reading a file the session itself would read
+ * without a prompt is the risk floor; anything that writes or runs is not.
+ */
+export declare const DEFAULT_BUILTIN_TOOLS: readonly string[];
+/** The built-ins {@link runBuiltin} actually implements. */
+export declare const EXECUTABLE_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
+ * entirely. Unlike `BIR_REPLAY_ALLOW_SERVERS`, an explicit empty list is
+ * honoured: there is a non-empty default to fall back from, so emptiness here
+ * is a choice, not an accident.
+ */
+export declare function parseBuiltinTools(value: string | undefined): ReadonlySet<string>;
+/**
+ * Parse `BIR_BASH_ALLOW`: comma-separated command prefixes, `*` for
+ * everything. Undefined (unset or blank) means `Bash` never executes on the
+ * runner — the flag is the opt-in, exactly like the tool list itself.
+ */
+export declare function parseBashAllow(value: string | undefined): readonly string[] | undefined;
+/**
+ * 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
+ * `git`, never `gitk` — an operator who wrote `git` meant git, and the
+ * trimming in {@link parseBashAllow} must not widen that.
+ */
+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
+ * session may still do it, a recorded output may stand in.
+ */
+export declare class BuiltinNotRunnable extends Error {
+    constructor(message: string);
+}
+/**
+ * The step started and was cut off by its clock. For `Bash` the command may
+ * have done part of its work; for a walk there is simply no result. Either
+ * way nothing may be asserted, which is `uncertain` — the same word an MCP
+ * step's timeout gets.
+ */
+export declare class BuiltinTimeout extends Error {
+    constructor(message: string);
+}
+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
+     * daemon's own cwd is never a substitute.
+     */
+    cwd: string;
+    /** The step's clock, the same budget an MCP dispatch would get. */
+    timeoutMs?: number;
+    /** Parsed `BIR_BASH_ALLOW` ({@link parseBashAllow}). */
+    bashAllow?: readonly string[];
+}
+/**
+ * Execute one built-in step and return its hook-shaped result (an object; the
+ * caller serializes). Throws per the failure contract above.
+ */
+export declare function runBuiltin(toolName: string, input: Record<string, unknown>, ctx: BuiltinContext): Promise<unknown>;
+/**
+ * Which `bash` a runner-side step uses. On Windows the host's own Bash tool
+ * is Git Bash, which is rarely on the daemon's PATH — so the standard
+ * Git-for-Windows locations are preferred over PATH, where `bash.exe` may
+ * even be the WSL stub (a different filesystem view entirely). Resolved once.
+ */
+export declare function bashExecutable(): string;
+/**
+ * A glob pattern as a RegExp over `/`-separated relative paths: `**` crosses
+ * directories, `*` and `?` stay inside one, `{a,b}` alternates, `[…]` passes
+ * through as a character class. Matched against the whole relative path, as
+ * the host's Glob does — a bare `*.ts` is the top level only (Grep's filter
+ * widens a bare pattern itself, ripgrep-style). Enough for the patterns
+ * Claude Code writes; a pattern beyond it simply matches nothing it should
+ * not.
+ */
+export declare function globToRegExp(pattern: string): RegExp;
+//# sourceMappingURL=builtins.d.ts.map

package/dist/replay/builtins.js

@@ -0,0 +1,641 @@
+/**
+ * builtins — running a scenario's built-in steps (`Read`, `Glob`, `Grep`,
+ * `Edit`, `Write`, `Bash`) on the runner itself (docs/calculatedReplay.md §5).
+ *
+ * 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*,
+ * 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:
+ *
+ *   - **Default deny beyond read-only.** Which built-ins may run at all is
+ *     `BIR_BUILTIN_TOOLS` ({@link parseBuiltinTools}), and its default is the
+ *     read-only set (`Read,Glob,Grep`). `Edit`, `Write` and `Bash` are an
+ *     explicit, per-environment opt-in — a recorded `rm` must never run
+ *     because a prompt looked similar.
+ *   - **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).
+ *   - **Bash runs nothing unless `BIR_BASH_ALLOW` says so.** A command must
+ *     match one of its prefixes ({@link bashAllowed}); unset means `Bash`
+ *     never executes here, even when allow-listed.
+ *   - **Same failure contract as an MCP step.** A step that *cannot* run here
+ *     throws {@link BuiltinNotRunnable} (→ `not_run`: the session can still do
+ *     it, or a recorded output may stand in under
+ *     `BIR_REPLAY_RECORDED_OUTPUTS=1`). One that ran out of time throws
+ *     {@link BuiltinTimeout} (→ `uncertain`). Any other throw is a step that
+ *     ran and failed (→ `failed`), never silently threaded as a success.
+ *
+ * Outputs mimic the **hook view** of each tool — Claude Code's `tool_response`
+ * as `PostToolUse` reports it — because that is exactly what the recorder
+ * stored for built-in steps (control/server.ts, `onToolPost`) and therefore
+ * what each step's `toolOutputLogic` was authored against. The shapes are a
+ * best effort and may drift from a future host's, the same caveat the
+ * hook-view threading fallback already carries ("shapes may differ").
+ */
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+// ── configuration ────────────────────────────────────────────────────────────
+/**
+ * The built-ins bir may stand in for or execute when `BIR_BUILTIN_TOOLS` is
+ * unset: the read-only set. Reading a file the session itself would read
+ * without a prompt is the risk floor; anything that writes or runs is not.
+ */
+export const DEFAULT_BUILTIN_TOOLS = ["Read", "Glob", "Grep"];
+/** The built-ins {@link runBuiltin} actually implements. */
+export const EXECUTABLE_BUILTINS = new Set([
+    "Read",
+    "Glob",
+    "Grep",
+    "Edit",
+    "Write",
+    "Bash",
+]);
+/** `read` → `Read`: the vocabulary is small enough to forgive casing. */
+const CANONICAL_BUILTIN = new Map([...EXECUTABLE_BUILTINS].map((name) => [name.toLowerCase(), name]));
+/**
+ * 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
+ * entirely. Unlike `BIR_REPLAY_ALLOW_SERVERS`, an explicit empty list is
+ * honoured: there is a non-empty default to fall back from, so emptiness here
+ * is a choice, not an accident.
+ */
+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);
+}
+/**
+ * Parse `BIR_BASH_ALLOW`: comma-separated command prefixes, `*` for
+ * everything. Undefined (unset or blank) means `Bash` never executes on the
+ * runner — the flag is the opt-in, exactly like the tool list itself.
+ */
+export function parseBashAllow(value) {
+    const prefixes = (value ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return prefixes.length > 0 ? prefixes : undefined;
+}
+/**
+ * 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
+ * `git`, never `gitk` — an operator who wrote `git` meant git, and the
+ * trimming in {@link parseBashAllow} must not widen that.
+ */
+export function bashAllowed(command, allow) {
+    if (!allow)
+        return false;
+    const trimmed = command.trimStart();
+    const word = /[A-Za-z0-9_-]/;
+    return allow.some((prefix) => {
+        if (prefix === "*")
+            return true;
+        if (!trimmed.startsWith(prefix))
+            return false;
+        const next = trimmed.charAt(prefix.length);
+        return next === "" || !word.test(next) || !word.test(prefix.charAt(prefix.length - 1));
+    });
+}
+// ── 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
+ * session may still do it, a recorded output may stand in.
+ */
+export class BuiltinNotRunnable extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BuiltinNotRunnable";
+    }
+}
+/**
+ * The step started and was cut off by its clock. For `Bash` the command may
+ * have done part of its work; for a walk there is simply no result. Either
+ * way nothing may be asserted, which is `uncertain` — the same word an MCP
+ * step's timeout gets.
+ */
+export class BuiltinTimeout extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BuiltinTimeout";
+    }
+}
+// ── size caps ────────────────────────────────────────────────────────────────
+// The results flow through the same `serializeCapped(redact(...))` as every
+// recorded payload, so these caps are about the daemon's memory and time, not
+// about what reaches the service.
+/** The most of one file a `Read`/`Edit` loads. */
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+/** `Read` line clamp, matching the host's own rendering limit. */
+const MAX_LINE_CHARS = 2_000;
+/** `Read` default line count, matching the host's. */
+const DEFAULT_READ_LINES = 2_000;
+/** Bash stdout/stderr cap. */
+const MAX_BASH_BUFFER = 8 * 1024 * 1024;
+/** The most files a Glob answers, oldest dropped first (mtime order). */
+const MAX_GLOB_RESULTS = 100;
+/** The most directory entries a walk visits before it reports `truncated`. */
+const MAX_WALK_ENTRIES = 50_000;
+/** The most files a Grep opens, and the most of each it reads. */
+const MAX_GREP_FILES = 5_000;
+const MAX_GREP_FILE_BYTES = 4 * 1024 * 1024;
+/** The most matching lines a Grep's `content` mode returns. */
+const DEFAULT_GREP_HEAD = 250;
+// ── the executor ─────────────────────────────────────────────────────────────
+/**
+ * Execute one built-in step and return its hook-shaped result (an object; the
+ * caller serializes). Throws per the failure contract above.
+ */
+export async function runBuiltin(toolName, input, ctx) {
+    const deadline = ctx.timeoutMs !== undefined ? Date.now() + ctx.timeoutMs : undefined;
+    switch (toolName) {
+        case "Read":
+            return runRead(input, ctx);
+        case "Glob":
+            return runGlob(input, ctx, deadline);
+        case "Grep":
+            return runGrep(input, ctx, deadline);
+        case "Edit":
+            return runEdit(input, ctx);
+        case "Write":
+            return runWrite(input, ctx);
+        case "Bash":
+            return runBash(input, ctx);
+        default:
+            // Allow-listed but not implemented (`TodoWrite`, a tool this version
+            // does not know): the session runs it, or its recording stands in.
+            throw new BuiltinNotRunnable(`no runner-side implementation for ${toolName}`);
+    }
+}
+// ── the path jail ────────────────────────────────────────────────────────────
+/** 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;
+}
+function underRoot(root, abs) {
+    const prefix = root.endsWith(sep) ? root : root + sep;
+    return (samePath(abs, root) ||
+        (process.platform === "win32"
+            ? abs.toLowerCase().startsWith(prefix.toLowerCase())
+            : 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.
+ */
+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.
+    let probe = abs;
+    let real;
+    for (;;) {
+        try {
+            real = await realpath(probe);
+            break;
+        }
+        catch {
+            const parent = dirname(probe);
+            if (samePath(parent, probe))
+                break; // hit the filesystem root: nothing exists
+            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();
+    }
+    return abs;
+}
+// ── Read ─────────────────────────────────────────────────────────────────────
+async function runRead(input, ctx) {
+    const filePath = await jailed(ctx.cwd, 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`);
+    }
+    const text = await readFile(filePath, "utf8");
+    const all = text.split(/\r?\n/);
+    // `offset` is 1-based, as the host's Read documents it; 0 reads as 1.
+    const offset = Math.max(1, numberOr(input.offset, 1));
+    const limit = Math.max(1, numberOr(input.limit, DEFAULT_READ_LINES));
+    const lines = all
+        .slice(offset - 1, offset - 1 + limit)
+        .map((l) => (l.length > MAX_LINE_CHARS ? l.slice(0, MAX_LINE_CHARS) : l));
+    return {
+        type: "text",
+        file: {
+            filePath,
+            content: lines.join("\n"),
+            numLines: lines.length,
+            startLine: offset,
+            totalLines: all.length,
+        },
+    };
+}
+// ── Glob ─────────────────────────────────────────────────────────────────────
+async function runGlob(input, ctx, deadline) {
+    const pattern = input.pattern;
+    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 startedAt = Date.now();
+    const re = globToRegExp(pattern);
+    const found = [];
+    const truncated = await walk(root, deadline, (rel, abs, mtime) => {
+        if (re.test(rel))
+            found.push({ path: abs, mtime });
+        return true;
+    });
+    found.sort((a, b) => b.mtime - a.mtime);
+    const filenames = found.slice(0, MAX_GLOB_RESULTS).map((f) => f.path);
+    return {
+        filenames,
+        durationMs: Date.now() - startedAt,
+        numFiles: filenames.length,
+        truncated: truncated || found.length > MAX_GLOB_RESULTS,
+    };
+}
+// ── Grep ─────────────────────────────────────────────────────────────────────
+/** Grep inputs this executor honours; anything else is the session's job. */
+const GREP_KNOWN_KEYS = new Set([
+    "pattern",
+    "path",
+    "glob",
+    "output_mode",
+    "-i",
+    "-n",
+    "head_limit",
+]);
+async function runGrep(input, ctx, deadline) {
+    const pattern = input.pattern;
+    if (typeof pattern !== "string" || pattern === "") {
+        throw new BuiltinNotRunnable("pattern is required");
+    }
+    // Context lines, multiline mode, type filters, offsets: a stand-in that
+    // silently ignored them would thread the *wrong* output. Decline instead —
+    // the step still runs in the session, or its recording stands in.
+    const exotic = Object.keys(input).filter((k) => !GREP_KNOWN_KEYS.has(k) && input[k] !== undefined && input[k] !== null);
+    if (exotic.length > 0) {
+        throw new BuiltinNotRunnable(`this runner does not support Grep's ${exotic.join(", ")}`);
+    }
+    let re;
+    try {
+        re = new RegExp(pattern, input["-i"] === true ? "i" : "");
+    }
+    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");
+    // 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
+        ? globToRegExp(input.glob.includes("/") ? input.glob : `**/${input.glob}`)
+        : undefined;
+    const mode = typeof input.output_mode === "string" ? input.output_mode : "files_with_matches";
+    const headLimit = Math.max(1, numberOr(input.head_limit, DEFAULT_GREP_HEAD));
+    // One file, or a walk — the host's Grep takes both.
+    const files = [];
+    const st = await stat(target).catch(() => undefined);
+    let truncated = false;
+    if (st?.isFile()) {
+        files.push({ path: target, mtime: st.mtimeMs });
+    }
+    else {
+        truncated = await walk(target, deadline, (rel, abs, mtime) => {
+            if (!globRe || globRe.test(rel))
+                files.push({ path: abs, mtime });
+            return files.length < MAX_GREP_FILES;
+        });
+    }
+    const mtimes = new Map(files.map((f) => [f.path, f.mtime]));
+    const matches = [];
+    for (const f of files) {
+        if (deadline !== undefined && Date.now() > deadline) {
+            throw new BuiltinTimeout(`Grep ran out of time after ${files.length} candidate files`);
+        }
+        const lines = await matchFile(f.path, re, mode === "files_with_matches");
+        if (lines)
+            matches.push({ path: f.path, lines });
+    }
+    matches.sort((a, b) => (mtimes.get(b.path) ?? 0) - (mtimes.get(a.path) ?? 0));
+    if (mode === "count") {
+        const shown = matches.slice(0, headLimit);
+        return {
+            mode: "count",
+            content: shown.map((m) => `${m.path}:${m.lines.length}`).join("\n"),
+            numFiles: matches.length,
+            numMatches: matches.reduce((n, m) => n + m.lines.length, 0),
+            truncated: truncated || matches.length > shown.length,
+        };
+    }
+    if (mode === "content") {
+        const numbered = input["-n"] !== false;
+        const out = [];
+        for (const m of matches) {
+            for (const line of m.lines) {
+                out.push(numbered ? `${m.path}:${line.n}:${line.text}` : `${m.path}:${line.text}`);
+                if (out.length >= headLimit)
+                    break;
+            }
+            if (out.length >= headLimit)
+                break;
+        }
+        return { mode: "content", content: out.join("\n"), numLines: out.length, truncated };
+    }
+    const filenames = matches.slice(0, headLimit).map((m) => m.path);
+    return {
+        mode: "files_with_matches",
+        filenames,
+        numFiles: filenames.length,
+        truncated: truncated || matches.length > filenames.length,
+    };
+}
+/** The matching lines of one file, or undefined when none (or not text). */
+async function matchFile(path, re, firstOnly) {
+    let buf;
+    try {
+        const st = await stat(path);
+        if (!st.isFile() || st.size > MAX_GREP_FILE_BYTES)
+            return undefined;
+        buf = await readFile(path);
+    }
+    catch {
+        return undefined; // unreadable is not a match
+    }
+    // A NUL near the start is the classic binary sniff, same as grep's own.
+    if (buf.subarray(0, 4096).includes(0))
+        return undefined;
+    const lines = buf.toString("utf8").split(/\r?\n/);
+    const out = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        if (re.test(lines[i])) {
+            out.push({ n: i + 1, text: lines[i].slice(0, MAX_LINE_CHARS) });
+            if (firstOnly)
+                return out;
+        }
+    }
+    return out.length > 0 ? out : undefined;
+}
+// ── Edit / Write ─────────────────────────────────────────────────────────────
+async function runEdit(input, ctx) {
+    const filePath = await jailed(ctx.cwd, input.file_path);
+    const oldString = input.old_string;
+    const newString = input.new_string;
+    if (typeof oldString !== "string" || oldString === "") {
+        throw new BuiltinNotRunnable("old_string is required");
+    }
+    if (typeof newString !== "string")
+        throw new BuiltinNotRunnable("new_string is required");
+    const replaceAll = input.replace_all === true;
+    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 edits`);
+    }
+    const current = await readFile(filePath, "utf8");
+    const occurrences = current.split(oldString).length - 1;
+    if (occurrences === 0)
+        throw new Error(`old_string was not found in ${filePath}`);
+    if (!replaceAll && occurrences > 1) {
+        throw new Error(`old_string appears ${occurrences} times in ${filePath}; it must be unique`);
+    }
+    const next = replaceAll
+        ? current.split(oldString).join(newString)
+        : current.replace(oldString, newString);
+    await writeFile(filePath, next, "utf8");
+    return {
+        filePath,
+        oldString,
+        newString,
+        originalFile: current,
+        structuredPatch: [],
+        userModified: false,
+        replaceAll,
+    };
+}
+async function runWrite(input, ctx) {
+    const filePath = await jailed(ctx.cwd, input.file_path);
+    const content = input.content;
+    if (typeof content !== "string")
+        throw new BuiltinNotRunnable("content is required");
+    const existed = await stat(filePath).then((s) => s.isFile(), () => false);
+    // No mkdir: the host's Write does not invent directories, so neither does
+    // the stand-in — a missing parent is a divergence, not a wish.
+    await writeFile(filePath, content, "utf8");
+    return {
+        type: existed ? "update" : "create",
+        filePath,
+        content,
+        structuredPatch: [],
+    };
+}
+// ── Bash ─────────────────────────────────────────────────────────────────────
+/**
+ * Which `bash` a runner-side step uses. On Windows the host's own Bash tool
+ * is Git Bash, which is rarely on the daemon's PATH — so the standard
+ * Git-for-Windows locations are preferred over PATH, where `bash.exe` may
+ * even be the WSL stub (a different filesystem view entirely). Resolved once.
+ */
+export function bashExecutable() {
+    if (process.platform !== "win32")
+        return "bash";
+    for (const candidate of [
+        join(process.env.ProgramFiles ?? "C:\\Program Files", "Git", "bin", "bash.exe"),
+        join(process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)", "Git", "bin", "bash.exe"),
+    ]) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return "bash.exe";
+}
+async function runBash(input, ctx) {
+    const command = input.command;
+    if (typeof command !== "string" || command.trim() === "") {
+        throw new BuiltinNotRunnable("command is required");
+    }
+    if (!ctx.bashAllow) {
+        throw new BuiltinNotRunnable("BIR_BASH_ALLOW is not set, so bir runs no Bash command unattended");
+    }
+    if (!bashAllowed(command, ctx.bashAllow)) {
+        throw new BuiltinNotRunnable("the command does not match BIR_BASH_ALLOW, so bir does not run it unattended");
+    }
+    const timeoutMs = ctx.timeoutMs ?? 120_000;
+    return new Promise((resolvePromise, rejectPromise) => {
+        execFile(bashExecutable(), ["-lc", command], {
+            cwd: resolve(ctx.cwd),
+            timeout: timeoutMs,
+            maxBuffer: MAX_BASH_BUFFER,
+            windowsHide: true,
+        }, (err, stdout, stderr) => {
+            if (err) {
+                const e = err;
+                if (e.code === "ENOENT") {
+                    // No bash on this machine (a Windows runner without Git Bash):
+                    // the step is the session's, exactly as before.
+                    rejectPromise(new BuiltinNotRunnable("no `bash` on the runner's PATH"));
+                    return;
+                }
+                if (e.killed || e.signal === "SIGTERM") {
+                    rejectPromise(new BuiltinTimeout(`the command was stopped after ${timeoutMs}ms and may have done part of its work`));
+                    return;
+                }
+                const code = typeof e.code === "number" ? e.code : 1;
+                const detail = String(stderr || stdout || "").trim().slice(0, 500);
+                rejectPromise(new Error(`the command exited with code ${code}${detail ? `: ${detail}` : ""}`));
+                return;
+            }
+            resolvePromise({
+                stdout: String(stdout ?? ""),
+                stderr: String(stderr ?? ""),
+                interrupted: false,
+                isImage: false,
+            });
+        });
+    });
+}
+// ── shared walking and matching ─────────────────────────────────────────────
+/** Directories no scenario's step means to scan. */
+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).
+ */
+async function walk(root, deadline, visit) {
+    let seen = 0;
+    const queue = [root];
+    while (queue.length > 0) {
+        if (deadline !== undefined && Date.now() > deadline) {
+            throw new BuiltinTimeout(`the walk ran out of time after ${seen} entries`);
+        }
+        const dir = queue.shift();
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // unreadable directory: skip, as the host's own tools do
+        }
+        for (const entry of entries) {
+            seen += 1;
+            if (seen > MAX_WALK_ENTRIES)
+                return true;
+            const abs = resolve(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name))
+                    queue.push(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue; // symlinks and specials stay unfollowed
+            let mtime = 0;
+            try {
+                mtime = (await stat(abs)).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            const rel = abs.slice(resolve(root).length + 1).split(sep).join("/");
+            if (!visit(rel, abs, mtime))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * A glob pattern as a RegExp over `/`-separated relative paths: `**` crosses
+ * directories, `*` and `?` stay inside one, `{a,b}` alternates, `[…]` passes
+ * through as a character class. Matched against the whole relative path, as
+ * the host's Glob does — a bare `*.ts` is the top level only (Grep's filter
+ * widens a bare pattern itself, ripgrep-style). Enough for the patterns
+ * Claude Code writes; a pattern beyond it simply matches nothing it should
+ * not.
+ */
+export function globToRegExp(pattern) {
+    let p = pattern.replace(/\\/g, "/");
+    if (p.startsWith("./"))
+        p = p.slice(2);
+    let out = "";
+    for (let i = 0; i < p.length; i += 1) {
+        const c = p[i];
+        if (c === "*") {
+            if (p[i + 1] === "*") {
+                // `**/` may match nothing at all; a trailing `**` matches the rest.
+                out += p[i + 2] === "/" ? "(?:[^/]+/)*" : ".*";
+                i += p[i + 2] === "/" ? 2 : 1;
+            }
+            else {
+                out += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            out += "[^/]";
+        }
+        else if (c === "{") {
+            const end = p.indexOf("}", i);
+            if (end === -1) {
+                out += "\\{";
+            }
+            else {
+                out += `(?:${p
+                    .slice(i + 1, end)
+                    .split(",")
+                    .map((s) => s.replace(/[.+^$()|\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]"))
+                    .join("|")})`;
+                i = end;
+            }
+        }
+        else if (c === "[") {
+            const end = p.indexOf("]", i + (p[i + 1] === "!" || p[i + 1] === "^" ? 2 : 1) + 1);
+            if (end === -1) {
+                out += "\\[";
+            }
+            else {
+                const body = p.slice(i + 1, end).replace(/^!/, "^");
+                out += `[${body}]`;
+                i = end;
+            }
+        }
+        else {
+            out += /[.+^$()|\\]/.test(c) ? `\\${c}` : c;
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+function numberOr(value, fallback) {
+    const n = typeof value === "string" ? Number(value) : value;
+    return typeof n === "number" && Number.isFinite(n) ? Math.floor(n) : fallback;
+}
+//# sourceMappingURL=builtins.js.map

package/dist/replay/controller.d.ts

@@ -196,6 +196,23 @@ export interface ReplayOptions {
     segmentArm?: boolean;
     /** `BIR_REPLAY_ALLOW_SERVERS`; undefined means every wrapped server. */
     allowServers?: ReadonlySet<string>;
+    /**
+     * `BIR_BUILTIN_TOOLS` — the built-ins the runner may execute itself, from
+     * the session's own project directory (replay/builtins.ts), or stand in
+     * for with a recorded output under `BIR_REPLAY_RECORDED_OUTPUTS=1`.
+     * Omitted, the environment decides; the default is the read-only set
+     * (`Read,Glob,Grep`). `Edit`, `Write` and `Bash` run only when listed
+     * explicitly — and `Bash` additionally only for commands matching
+     * {@link ReplayOptions.bashAllow}.
+     */
+    builtinTools?: ReadonlySet<string>;
+    /**
+     * `BIR_BASH_ALLOW` — command prefixes a runner-side `Bash` step may run
+     * (`*` for all). Undefined means `Bash` never executes here, even when
+     * allow-listed: runner-side execution bypasses the host's permission
+     * prompts, so the shell needs its own explicit opt-in.
+     */
+    bashAllow?: readonly string[];
     budgets?: Partial<ReplayBudgets>;
     /**
      * The service: the lazy source-run fetch, and the parameter derivation this
@@ -331,6 +348,14 @@ export interface ReplayState {
      * replay`, which has no session and takes the newest proxy.
      */
     sessionId?: string;
+    /**
+     * 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 —
+     * no built-in executes: the step is `not_run`, exactly as before.
+     */
+    sessionCwd?: string;
     /**
      * Which kind of row was handed out (segmented.md R-OUT-7). A `segment` is a
      * named sub-task of a recording rather than a whole task, and it is judged
@@ -447,6 +472,10 @@ export declare class ReplayController {
     private readonly opts;
     /** See {@link ReplayOptions.recordedFallback}. */
     private readonly recordedFallback;
+    /** See {@link ReplayOptions.builtinTools}. */
+    private readonly builtinTools;
+    /** See {@link ReplayOptions.bashAllow}. */
+    private readonly bashAllow?;
     /** Calls waiting for a plan's pins to change (see `awaitPins`). */
     private readonly pinWaiters;
     /**
@@ -762,6 +791,19 @@ export declare class ReplayController {
      * asked for by id and which the allowlist does not gate.
      */
     private executeStep;
+    /**
+     * Run one allow-listed built-in step on the runner, inside `cwd`.
+     *
+     * The result mimics the hook's view of the tool, because that is what was
+     * recorded for built-in steps and what their `toolOutputLogic` was authored
+     * against (control/server.ts, `onToolPost`) — and it is serialized and
+     * redacted through the exact pipeline every recorded payload takes, so
+     * `Bash` output cannot carry a secret the recording would have stripped.
+     *
+     * Failures keep {@link ExecuteStep}'s contract: policy (`not_run`), a step
+     * cut off by its clock (`uncertain`), a step that ran and broke (`failed`).
+     */
+    private executeBuiltin;
     /** Where recorded outputs come from, when they may stand in at all. */
     private recordedSource;
     /**
@@ -797,6 +839,11 @@ export declare class ReplayController {
      * wrapped server the allowlist excludes is still proxied, still reported, and
      * still recorded in the proxy's serialization. Threading such a step from the
      * hook's differently-shaped view would derive nothing at all.
+     *
+     * The built-in allow-list is deliberately NOT passed here for the same
+     * reason in the other direction: a *steered* built-in is never proxied,
+     * whatever `BIR_BUILTIN_TOOLS` says, so its output can only ever arrive
+     * from the hook.
      */
     private reachFor;
     /**

package/dist/replay/controller.js

@@ -18,6 +18,7 @@ import { serializeCapped } from "../record/truncate.js";
 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 { BASH_CHANNEL_MAX, MAX_REPLAY_REASON, truncate } from "./bundle.js";
 import { coverageOf, modeFor, reachOf } from "./coverage.js";
 import { deriveParameters, } from "./derive.js";
@@ -185,6 +186,10 @@ export class ReplayController {
     opts;
     /** See {@link ReplayOptions.recordedFallback}. */
     recordedFallback;
+    /** See {@link ReplayOptions.builtinTools}. */
+    builtinTools;
+    /** See {@link ReplayOptions.bashAllow}. */
+    bashAllow;
     /** Calls waiting for a plan's pins to change (see `awaitPins`). */
     pinWaiters = new WeakMap();
     /**
@@ -245,6 +250,8 @@ export class ReplayController {
         this.intentMatch = { ...DEFAULT_INTENT_MATCH, ...(opts.intentMatch ?? {}) };
         this.recordedFallback =
             opts.recordedFallback ?? process.env.BIR_REPLAY_RECORDED_OUTPUTS === "1";
+        this.builtinTools = opts.builtinTools ?? parseBuiltinTools(process.env.BIR_BUILTIN_TOOLS);
+        this.bashAllow = opts.bashAllow ?? parseBashAllow(process.env.BIR_BASH_ALLOW);
     }
     /**
      * Whether a handed-out segment may actually arm (segmented.md R-OUT-10).
@@ -423,8 +430,11 @@ export class ReplayController {
                     : "known_bad_first_step");
         }
         const planned = stopAt === undefined ? entries : entries.slice(0, stopAt);
-        // Gate 6 — tool coverage, over the steps that will actually run.
-        const mode = modeFor(planned.map((e) => e.step), wrapped, this.opts.allowServers);
+        // Gate 6 — tool coverage, over the steps that will actually run. A
+        // built-in on `BIR_BUILTIN_TOOLS` counts as reachable: the runner
+        // executes it itself (replay/builtins.ts), so a chain that starts with a
+        // `Read` no longer forces steer mode.
+        const mode = modeFor(planned.map((e) => e.step), wrapped, this.opts.allowServers, this.builtinTools);
         if (mode === "none")
             return decline("no step is executable", "coverage");
         // Tool results feed derivation as context, and they are whatever the agent
@@ -598,7 +608,7 @@ export class ReplayController {
             unusable: flat.stopReason?.reason,
             // Which steps the service told this plan to stop in front of, and why.
             stops: stopLines(entries),
-            coverage: coverageOf(entries.map((e) => e.step), wrapped, this.opts.allowServers).join(","),
+            coverage: coverageOf(entries.map((e) => e.step), wrapped, this.opts.allowServers, this.builtinTools).join(","),
             tools: entries.map((e) => e.step.toolName ?? "").join(","),
         });
         return state;
@@ -1565,7 +1575,7 @@ export class ReplayController {
         }
         if (flat.entries.length === 0)
             return { ok: false, why: "the chain has no runnable step" };
-        const mode = modeFor(flat.entries.map((e) => e.step), wrapped, this.opts.allowServers);
+        const mode = modeFor(flat.entries.map((e) => e.step), wrapped, this.opts.allowServers, this.builtinTools);
         if (mode === "none")
             return { ok: false, why: "no step is executable" };
         const state = {
@@ -1636,7 +1646,7 @@ export class ReplayController {
             scenario: scenario.id,
             mode,
             steps: scenario.steps.length,
-            coverage: coverageOf(scenario.steps, wrapped, this.opts.allowServers).join(","),
+            coverage: coverageOf(scenario.steps, wrapped, this.opts.allowServers, this.builtinTools).join(","),
             why: "bir replay — no match, an operator asked for it",
         });
         // An operator's run keeps its own contract (R-CALL-37): out of time, the
@@ -2066,6 +2076,16 @@ export class ReplayController {
             const name = step.toolName ?? "";
             const mcp = parseQualifiedName(name);
             if (!mcp) {
+                // An allow-listed built-in runs *here*, against 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, `Bash`
+                // without `BIR_BASH_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) {
+                    return this.executeBuiltin(name, input, state.sessionCwd, opts.deadline);
+                }
                 throw new StepRunError(`${name || "this step"} is a built-in tool, which only runs in the session`, "not_run");
             }
             // `BIR_REPLAY_ALLOW_SERVERS` is about exactly this: a call bir makes by
@@ -2098,6 +2118,38 @@ export class ReplayController {
             return serializeCapped(redact(result));
         };
     }
+    /**
+     * Run one allow-listed built-in step on the runner, inside `cwd`.
+     *
+     * The result mimics the hook's view of the tool, because that is what was
+     * recorded for built-in steps and what their `toolOutputLogic` was authored
+     * against (control/server.ts, `onToolPost`) — and it is serialized and
+     * redacted through the exact pipeline every recorded payload takes, so
+     * `Bash` output cannot carry a secret the recording would have stripped.
+     *
+     * Failures keep {@link ExecuteStep}'s contract: policy (`not_run`), a step
+     * cut off by its clock (`uncertain`), a step that ran and broke (`failed`).
+     */
+    async executeBuiltin(name, input, cwd, deadline) {
+        const left = deadline !== undefined ? deadline - Date.now() : Number.POSITIVE_INFINITY;
+        const timeoutMs = Math.max(MIN_STEP_MS, Math.min(this.budgets.stepMs, left));
+        // The audit line precedes the action, always (§13.2, mitigation 4).
+        logDetail("replay.builtin", { tool: name, cwd });
+        let result;
+        try {
+            result = await runBuiltin(name, input, { cwd, timeoutMs, bashAllow: this.bashAllow });
+        }
+        catch (err) {
+            if (err instanceof BuiltinNotRunnable)
+                throw new StepRunError(err.message, "not_run");
+            if (err instanceof BuiltinTimeout)
+                throw new StepRunError(err.message, "uncertain");
+            // It ran and broke — a missing file, a non-unique `old_string`, a
+            // non-zero exit. The step failed here, now; never threaded as success.
+            throw new StepRunError(errText(err), "failed");
+        }
+        return serializeCapped(redact(result));
+    }
     /** Where recorded outputs come from, when they may stand in at all. */
     recordedSource(state, force = false) {
         if (!force && !this.recordedFallback)
@@ -2230,6 +2282,11 @@ export class ReplayController {
      * wrapped server the allowlist excludes is still proxied, still reported, and
      * still recorded in the proxy's serialization. Threading such a step from the
      * hook's differently-shaped view would derive nothing at all.
+     *
+     * The built-in allow-list is deliberately NOT passed here for the same
+     * reason in the other direction: a *steered* built-in is never proxied,
+     * whatever `BIR_BUILTIN_TOOLS` says, so its output can only ever arrive
+     * from the hook.
      */
     reachFor(state, step) {
         return reachOf(step.toolName ?? "", state.wrapped);

package/dist/replay/coverage.d.ts

@@ -8,9 +8,17 @@
  * only happen inside the live session.
  *
  * `live` covers three genuinely different cases and treats them identically,
- * correctly: a built-in (`Bash`, `Read`, `Edit`, …), an MCP server the user chose
- * not to wrap, and `claude-in-chrome` — which is `scope: "dynamic"`, appears in
- * no config file, and therefore can never be wrapped at all.
+ * correctly: a built-in (`Bash`, `Read`, `Edit`, …) outside the built-in
+ * allow-list, an MCP server the user chose not to wrap, and `claude-in-chrome`
+ * — which is `scope: "dynamic"`, appears in no config file, and therefore can
+ * never be wrapped at all.
+ *
+ * A built-in *on* the allow-list (`BIR_BUILTIN_TOOLS`, default `Read,Glob,
+ * Grep`) is `direct`: the runner executes it itself (replay/builtins.ts), or —
+ * under `BIR_REPLAY_RECORDED_OUTPUTS=1` — serves its recorded output. The
+ * callers that ask a *different* question, "will a proxy report this call"
+ * (`ReplayController.reachFor`), deliberately pass no allow-list: a built-in
+ * is never proxied, whoever executes it.
  */
 import type { SerializedScenarioStep } from "./types.js";
 /** Where a step's tool can actually be executed. */
@@ -19,18 +27,23 @@ export type StepReach = "direct" | "live";
 export type ReplayMode = "direct" | "steer" | "none";
 /**
  * `direct` when the tool is `mcp__<server>__<tool>` for a server this control
- * plane has a proxy for; `live` otherwise.
+ * plane has a proxy for, or a built-in on `builtins`; `live` otherwise.
  *
  * `allow` is the `BIR_REPLAY_ALLOW_SERVERS` allowlist (§13.2, mitigation 2): a
  * wrapped server outside it is deliberately demoted to `live`, so it can still be
  * steered inside the session — where the user's own permission rules apply — but
  * is never called unattended by us.
+ *
+ * `builtins` is the `BIR_BUILTIN_TOOLS` allow-list (replay/builtins.ts): the
+ * built-ins the runner may execute itself, or stand in for with a recorded
+ * output. Omitted means none — the old contract — which is what every caller
+ * that is not the mode decision wants.
  */
-export declare function reachOf(toolName: string, wrapped: ReadonlySet<string>, allow?: ReadonlySet<string>): StepReach;
+export declare function reachOf(toolName: string, wrapped: ReadonlySet<string>, allow?: ReadonlySet<string>, builtins?: ReadonlySet<string>): StepReach;
 /** The mode for a whole scenario: `direct` only when *every* step is reachable. */
-export declare function modeFor(steps: readonly SerializedScenarioStep[], wrapped: ReadonlySet<string>, allow?: ReadonlySet<string>): ReplayMode;
+export declare function modeFor(steps: readonly SerializedScenarioStep[], wrapped: ReadonlySet<string>, allow?: ReadonlySet<string>, builtins?: ReadonlySet<string>): ReplayMode;
 /** Per-step reach, in step order — what `plan.armed` logs and `bir doctor` shows. */
-export declare function coverageOf(steps: readonly SerializedScenarioStep[], wrapped: ReadonlySet<string>, allow?: ReadonlySet<string>): StepReach[];
+export declare function coverageOf(steps: readonly SerializedScenarioStep[], wrapped: ReadonlySet<string>, allow?: ReadonlySet<string>, builtins?: ReadonlySet<string>): StepReach[];
 /**
  * Parse `BIR_REPLAY_ALLOW_SERVERS`. Unset (or empty) means *every wrapped
  * server*, which is why the return is `undefined` rather than an empty set — an

package/dist/replay/coverage.js

@@ -8,37 +8,54 @@
  * only happen inside the live session.
  *
  * `live` covers three genuinely different cases and treats them identically,
- * correctly: a built-in (`Bash`, `Read`, `Edit`, …), an MCP server the user chose
- * not to wrap, and `claude-in-chrome` — which is `scope: "dynamic"`, appears in
- * no config file, and therefore can never be wrapped at all.
+ * correctly: a built-in (`Bash`, `Read`, `Edit`, …) outside the built-in
+ * allow-list, an MCP server the user chose not to wrap, and `claude-in-chrome`
+ * — which is `scope: "dynamic"`, appears in no config file, and therefore can
+ * never be wrapped at all.
+ *
+ * A built-in *on* the allow-list (`BIR_BUILTIN_TOOLS`, default `Read,Glob,
+ * Grep`) is `direct`: the runner executes it itself (replay/builtins.ts), or —
+ * under `BIR_REPLAY_RECORDED_OUTPUTS=1` — serves its recorded output. The
+ * callers that ask a *different* question, "will a proxy report this call"
+ * (`ReplayController.reachFor`), deliberately pass no allow-list: a built-in
+ * is never proxied, whoever executes it.
  */
 import { parseQualifiedName } from "../control/correlation.js";
 /**
  * `direct` when the tool is `mcp__<server>__<tool>` for a server this control
- * plane has a proxy for; `live` otherwise.
+ * plane has a proxy for, or a built-in on `builtins`; `live` otherwise.
  *
  * `allow` is the `BIR_REPLAY_ALLOW_SERVERS` allowlist (§13.2, mitigation 2): a
  * wrapped server outside it is deliberately demoted to `live`, so it can still be
  * steered inside the session — where the user's own permission rules apply — but
  * is never called unattended by us.
+ *
+ * `builtins` is the `BIR_BUILTIN_TOOLS` allow-list (replay/builtins.ts): the
+ * built-ins the runner may execute itself, or stand in for with a recorded
+ * output. Omitted means none — the old contract — which is what every caller
+ * that is not the mode decision wants.
  */
-export function reachOf(toolName, wrapped, allow) {
+export function reachOf(toolName, wrapped, allow, builtins) {
     const mcp = parseQualifiedName(toolName);
-    if (!mcp || !wrapped.has(mcp.serverName))
+    if (!mcp)
+        return builtins?.has(toolName) ? "direct" : "live";
+    if (!wrapped.has(mcp.serverName))
         return "live";
     if (allow && !allow.has(mcp.serverName))
         return "live";
     return "direct";
 }
 /** The mode for a whole scenario: `direct` only when *every* step is reachable. */
-export function modeFor(steps, wrapped, allow) {
+export function modeFor(steps, wrapped, allow, builtins) {
     if (steps.length === 0)
         return "none";
-    return steps.every((s) => reachOf(s.toolName ?? "", wrapped, allow) === "direct") ? "direct" : "steer";
+    return steps.every((s) => reachOf(s.toolName ?? "", wrapped, allow, builtins) === "direct")
+        ? "direct"
+        : "steer";
 }
 /** Per-step reach, in step order — what `plan.armed` logs and `bir doctor` shows. */
-export function coverageOf(steps, wrapped, allow) {
-    return steps.map((s) => reachOf(s.toolName ?? "", wrapped, allow));
+export function coverageOf(steps, wrapped, allow, builtins) {
+    return steps.map((s) => reachOf(s.toolName ?? "", wrapped, allow, builtins));
 }
 /**
  * Parse `BIR_REPLAY_ALLOW_SERVERS`. Unset (or empty) means *every wrapped

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 | Same — only by steering the live session |
+| Reaches built-ins (`Bash`, `Read`) | Only by steering the live session | Read-only ones (`Read`, `Glob`, `Grep`) run on the runner itself, jailed to the project (`BIR_BUILTIN_TOOLS`); `Edit`/`Write`/`Bash` opt-in, else steered |
 | Needs `@anthropic-ai/*` at runtime | Yes | No (§16.3) |
 
 ---
@@ -243,15 +243,24 @@ export function modeFor(steps: SerializedScenarioStep[], wrapped: ReadonlySet<st
 
 | Every step | Mode | Where the tools run | Model spend |
 |---|---|---|---|
-| a wrapped MCP tool | **`direct`** (§6) | The proxies, on connections already open | 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, jailed to 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 |
 
 `live` covers three genuinely different cases and treats them identically, correctly: a built-in
-(`Bash`, `Read`, `Edit`, `Grep`, `Task`, `WebFetch`), an MCP server the user chose not to wrap, and
+off the `BIR_BUILTIN_TOOLS` allow-list (by default everything but `Read`, `Glob`, `Grep` — so
+`Bash`, `Edit`, `Write`, `Task`, `WebFetch`), an MCP server the user chose not to wrap, and
 `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` needs a second opt-in on top (`BIR_BASH_ALLOW`,
+command prefixes), 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.
+
 A **mixed** scenario in `steer` mode still gets direct execution for its wrapped steps once it
 diverges (§8), so coverage is not all-or-nothing at the divergence boundary — only at the arm-time
 mode choice.

package/docs/calculatedReplayGuide.md

@@ -352,7 +352,9 @@ so there is exactly one switch and it cannot get out of step with itself.
 | `BIR_REPLAY_PLAN_BUDGET_MS` | `100000` | Whole-plan ceiling for direct execution; `BIR_REPLAY_BUDGET_MS`, where set, overrides it. Past about 110 000 a long run may be moved to the background by Claude Code. Derivation plus plan is held under 270 s |
 | `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, 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_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` | 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`. Add `Edit,Write,Bash` only deliberately — a runner-side step never reaches the host's permission prompts. `none` restores the old behaviour: every built-in hands the turn back |
+| `BIR_BASH_ALLOW` | *(unset)* | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset, `Bash` never executes on the runner, even when `BIR_BUILTIN_TOOLS` lists it |
 | `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; unset follows `BIR_SEGMENT_ARM` |
 | `BIR_VERBOSE` | *(unset)* | `1` adds per-step `replay.*` detail lines |
 
@@ -553,7 +555,7 @@ first prompt that states the task plainly.
 | `replay.vetoed … the model's first call was …, not run_scenario` | A direct plan, and the model reached for another tool first — usually because it has no `run_scenario` | As for `no_delivery_tool`. Nothing ran; the model did the task |
 | `replay.pin_declined` on most steered turns | The model's calls to the expected tool are not the step — another command, another file — so nothing is pinned; if it then moves on, `replay.pin_abandoned` retires the plan | Harmless for those calls, which ran as the model wrote them. Persistent declines on one step usually mean its arguments cannot be shown in the directive (they depend on an earlier step's output, or the command runs to several lines), and the model writes its own |
 | `why="no step is executable"` | None of the scenario's tools is a wrapped MCP server and none is a built-in reachable in this session | Wrap the servers the scenario uses (`bir install --server …`) and recalculate |
-| `plan.armed mode=steer` where you expected `direct` | At least one step is a built-in, an unwrapped MCP server, or `claude-in-chrome` | `bir status` shows what is wrapped. `claude-in-chrome` is `scope: "dynamic"` and can never be wrapped |
+| `plan.armed mode=steer` where you expected `direct` | At least one step is a built-in off `BIR_BUILTIN_TOOLS` (default `Read,Glob,Grep` — so usually `Edit`, `Write` or `Bash`), an unwrapped MCP server, or `claude-in-chrome` | `bir status` shows what is wrapped; the `plan.armed` line's `coverage=` names the `live` step. Widen `BIR_BUILTIN_TOOLS` (and `BIR_BASH_ALLOW`) only deliberately. `claude-in-chrome` is `scope: "dynamic"` and can never be wrapped |
 | Model ignores the directive and diverges every turn | Steering is advisory — the model chooses; `bir` only pins arguments | Expected occasionally. Persistent divergence usually means the scenario's tools do not fit the live task; check `intent` |
 | A `replay.thread` line with no `emitted=` (under `BIR_VERBOSE=1`) | `toolOutputLogic` derived nothing — usually the output shape changed since recording | Dry-replay (§3.1). If the dry run emits and the live run does not, the tool's output shape has drifted; recalculate |
 | `replay.thread_fallback` on a wrapped step | The proxy did not report within the grace window | Check that proxy is alive (`bir doctor`). Repeats mean a slow or dying upstream |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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

@@ -992,6 +992,8 @@ 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` | Built-ins the runner executes itself during a replay, in the session's project directory and confined to it. Add `Edit,Write,Bash` deliberately — runner-side steps bypass the host's permission prompts. `none` turns it off. |
+| `BIR_BASH_ALLOW` | recorder | unset | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset, `Bash` never executes on the runner even when listed. |
 | `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. |
 | `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. |