@basein/runner 0.3.0 → 0.3.2

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";
@@ -57,7 +58,7 @@ export const DEFAULT_BUDGETS = {
     // task; a match that has not answered by then is a turn run normally. The
     // control server stops waiting at all for a while after one that answered
     // slowly (`BIR_MATCH_SLOW_MS`). `BIR_MATCH_BUDGET_MS` in the recorder.
-    matchMs: 1_500,
+    matchMs: 3_000,
     deriveMs: 8_000,
     planMs: 100_000,
     stepMs: 60_000,
@@ -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.
@@ -760,7 +769,7 @@ The hook is on the user's critical path. Every await here is a stall the user wa
 
 | Moment | Route | Hook timeout | Answered by | What may be awaited | Budget |
 |---|---|---|---|---|---|
-| `UserPromptSubmit` | `/session/prompt` | 10 s | 7 s | the match; for a scenario with a target, its derivation; a steer plan's argument preview | match `BIR_MATCH_BUDGET_MS` = **1500**; match and arming together ≤ **6 s**; derivation ≤ `BIR_HOOK_DERIVE_BUDGET_MS` = **4000** |
+| `UserPromptSubmit` | `/session/prompt` | 10 s | 7 s | the match; for a scenario with a target, its derivation; a steer plan's argument preview | match `BIR_MATCH_BUDGET_MS` = **3000**; match and arming together ≤ **6 s**; derivation ≤ `BIR_HOOK_DERIVE_BUDGET_MS` = **4000** |
 | `PreToolUse` | `/tool/pre` | 15 s | 12 s | `plan.ready()` (derivation); on a divergence, the remaining steps | derivation ≤ min(`BIR_DERIVE_BUDGET_MS`, `BIR_HOOK_DERIVE_BUDGET_MS`) = **4000**; all replay work ≤ `BIR_PRETOOL_REPLAY_BUDGET_MS` = **9000** (held at ≤ 10 000) |
 | `run_scenario` | `/scenario/run` | `bir-scenario`'s own, **290 s** (`BIR_SCENARIO_RUN_TIMEOUT_MS`) | — | `ready()` + N steps | derivation `BIR_DERIVE_BUDGET_MS` = **8000**; plan `BIR_REPLAY_PLAN_BUDGET_MS` = **100000** (`BIR_REPLAY_BUDGET_MS` overrides it where set); per step `BIR_STEP_TIMEOUT_MS` = **60000**, clipped to what the plan has left |
 | `PostToolUse` | `/tool/post` | 5 s | 2 s | nothing | — |
@@ -794,9 +803,9 @@ minutes, while its steps keep starting. `bir replay` is not held to the ceiling.
 
 **Budget expiry is never an error.** Match budget expired → no plan, ordinary turn, one
 `replay.decision` line (`match_timeout`). **The match gate:** a match that answered slower than
-`BIR_MATCH_SLOW_MS` (**800**), or not at all, also makes prompts stop waiting on the match for 5
+`BIR_MATCH_SLOW_MS` (**2000**), or not at all, also makes prompts stop waiting on the match for 5
 minutes, doubling up to 30 while the service stays slow; a fast match ends the hold
-(`replay.match_gate`). A healthy service answers in 300–450 ms, so past 800 ms waiting would add
+(`replay.match_gate`). A healthy service answers in 300–450 ms, so past 2 s waiting would add
 that much to every prompt. The match is still asked meanwhile, so a hit still stops the recording. Derivation budget expired →
 settings take their recorded `sampleValue`s and targets stay `null`, never `{}`; a plan that needs a
 missing target, or whose `paramsLogic` throws, hands over instead of running (in steer mode the

package/docs/calculatedReplayGuide.md

@@ -345,14 +345,16 @@ so there is exactly one switch and it cannot get out of step with itself.
 | `BIR_MIN_STEER_SIMILARITY` | `0.92` | Below this a match is detected but not replayed (§8) |
 | `BIR_DERIVE_API_KEY` | *(unset)* | **Not required.** Derivation — reading what this request acts on — is done by the service on its key for a signed-in runner. Set this to keep the reading on this machine instead: the prompt then never leaves it, and it is one round trip faster. Signed out *and* unset, only a scenario with nothing to work out replays. A recorder running in the background (started by the SessionStart hook, `bir up` or `bir setup`) ignores `ANTHROPIC_API_KEY` (usually Claude Code's own, and billed) unless `BIR_USE_ANTHROPIC_API_KEY=1`; a `bir-hooks` you run in a terminal uses it |
 | `BIR_DERIVE_MODEL` | `claude-haiku-4-5-20251001` | The derivation model, when this machine does the reading |
-| `BIR_MATCH_BUDGET_MS` | `1500` | How long the prompt hook waits for a match before giving up. After a match slower than `BIR_MATCH_SLOW_MS` (`800`), prompts stop waiting for one for 5 minutes, doubling up to 30 while the service stays slow |
+| `BIR_MATCH_BUDGET_MS` | `3000` | How long the prompt hook waits for a match before giving up. After a match slower than `BIR_MATCH_SLOW_MS` (`2000`), prompts stop waiting for one for 5 minutes, doubling up to 30 while the service stays slow |
 | `BIR_DERIVE_BUDGET_MS` | `8000` | How long `run_scenario` waits for parameters |
 | `BIR_HOOK_DERIVE_BUDGET_MS` | `4000` | How long a hook waits for them: the prompt, for a scenario with a target, and the first `PreToolUse` (never longer than `BIR_DERIVE_BUDGET_MS`) |
 | `BIR_PRETOOL_REPLAY_BUDGET_MS` | `9000` | All replay work inside one `PreToolUse`, a divergence's steps included. At most 10 000 |
 | `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 |
 
@@ -548,12 +550,12 @@ first prompt that states the task plainly.
 |---|---|---|
 | No `run.matched`, ever | Prompt below the server's `SIMILARITY_THRESHOLD` | Rephrase closer, or lower it server-side. Confirm the original run is in the list — a sub-`RECORDING_MIN_ACTIONS` run is never embedded |
 | `run.matched` but no `plan.armed` | A gate declined | Read the `replay.decision` line's `why=`. Ranked by frequency: replay off — `bir replay off`, `BIR_REPLAY=0`, or never switched on here (a `bir install` without `--replay`; `bir replay status` says which) · scenario not `ready` · similarity below threshold · no step is executable |
-| `replay.decision … code=match_timeout` or `code=service_unhealthy` on many prompts | The service answered the match slower than `BIR_MATCH_BUDGET_MS` (1.5 s), or is failing and in its cool-down | Nothing breaks: those turns run normally, and after a slow match prompts stop waiting on it for a while by themselves (`replay.match_gate`). `bir doctor` shows the service's state. Raise `BIR_MATCH_BUDGET_MS` only if the service is reliably just over it — every prompt pays it |
+| `replay.decision … code=match_timeout` or `code=service_unhealthy` on many prompts | The service answered the match slower than `BIR_MATCH_BUDGET_MS` (3 s), or is failing and in its cool-down | Nothing breaks: those turns run normally, and after a slow match prompts stop waiting on it for a while by themselves (`replay.match_gate`). `bir doctor` shows the service's state. Raise `BIR_MATCH_BUDGET_MS` only if the service is reliably just over it — every prompt pays it |
 | `replay.decision … code=no_delivery_tool` | A direct plan, and no running `bir` server has told the recorder it serves `run_scenario`: the server is missing, disabled or failed in `/mcp`, was not added (a subdirectory or worktree of a repository), or the session was started with `BIR_OFF=1` | `/mcp` shows whether `bir` is connected. `bir install --replay` adds it, in the project's own directory; then start a new session |
 | `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.0",
+  "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",