@basein/runner 0.3.1 → 0.3.3

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,23 @@ 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;
+    /**
+     * Where this plan's last runner-side `Bash` step left its shell. The
+     * host's own semantics, which the recorded chain was written against: the
+     * working directory persists between Bash calls (variables and functions
+     * do not), so a chain of `cd sub` then `cat file` replays as it ran.
+     * Starts at {@link sessionCwd}; never read for `Read`/`Edit`/`Write`
+     * paths, which resolve against the project directory as the host's do.
+     */
+    bashCwd?: 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 +481,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 +800,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 +848,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, 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,48 @@ 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, state, deadline) {
+        const cwd = state.sessionCwd; // the caller executes only with one
+        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,
+                // The plan's Bash steps share a working directory, as the host's do.
+                bashCwd: state.bashCwd,
+                onBashCwd: (pwd) => {
+                    state.bashCwd = pwd;
+                },
+            });
+        }
+        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 +2292,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,27 @@ 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. Bash keeps the host's own semantics a
+recorded chain was written against: each call is a fresh `-l` shell (variables and functions do
+not persist), while the **working directory carries over** from the plan's previous Bash step —
+`cd sub` then `cat file` replays as it ran.
+
 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. 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 |
 | `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.3",
   "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. A plan's Bash steps share a working directory, as the host's do; variables do not persist, also as the host's. |
 | `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. |