@basein/runner 0.3.19 → 0.3.21

package/dist/replay/controller.js

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

package/dist/replay/derive.d.ts

@@ -53,6 +53,16 @@ export interface DeriveContext {
      * into the session only after the prompt hook (issue 1212).
      */
     agentDay?: () => AgentDay | undefined;
+    /**
+     * A reading for a scenario that can follow a plan's decision, made while the
+     * agent decides (the service's offer1.md O4): the plan, and its decision
+     * step. With it the service reads this turn's results without a live call,
+     * and the prompt as the user's request. Only the service reads it.
+     */
+    atDecision?: {
+        scenarioId: string;
+        stepIndex: number;
+    };
 }
 /**
  * The service, which derives when this runner has no key of its own

package/dist/replay/derive.js

@@ -347,6 +347,9 @@ async function deriveViaService(opts, service, schema, keys) {
                 // 2023-11-30 …"), which the service turns into the day it reads from
                 // (issue 1212). Older services ignore it.
                 ...(opts.todaySaid ? { todaySaid: opts.todaySaid } : {}),
+                // A reading made at a plan's decision (offer1.md O4): the service then
+                // takes this turn's results with no live call. Older services ignore it.
+                ...(opts.atDecision ? { atDecision: opts.atDecision } : {}),
             }),
             signal: opts.signal ?? timeoutSignal(),
         });

package/dist/replay/reads-only.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Whether a tool call may change something, judged by its name alone — the
+ * runner's copy of the service's own rule (BaseIn src/scenarios/correctionCheck.ts,
+ * `readsOnly`, `commandReadsOnly`, `callMayChange`), kept word for word so the
+ * two never disagree about the same call.
+ *
+ * Used where a call after a plan's decision is the agent starting a way of its
+ * own (the service's offer1.md O7), and where a plan started after a call
+ * would make it a second time (O8). When in doubt, a call is a change: that
+ * only ends a set of scenarios early or keeps a plan from starting, never lets
+ * a second write through.
+ */
+/**
+ * A tool that only reads: Claude Code's read-only tools, then the name — a
+ * reading word and no writing word (`calendar_search_events`, `getJiraIssue`;
+ * `run_sql` no: `run` writes). A name with both (`get_or_create_contact`)
+ * changes something.
+ */
+export declare function readsOnly(toolName: string): boolean;
+/** Whether a shell command only looks: every part of it is a looking command, and nothing is written to a file. */
+export declare function commandReadsOnly(command: string): boolean;
+/**
+ * Whether one call may change something. A Bash call changes nothing only
+ * when its command is there and only looks; any other tool is a change unless
+ * {@link readsOnly} says it only reads — a tool it cannot tell about counts as
+ * a change. `input` is the call's arguments, as an object or as JSON text.
+ */
+export declare function callMayChange(toolName: string, input: unknown): boolean;
+//# sourceMappingURL=reads-only.d.ts.map

package/dist/replay/reads-only.js

@@ -0,0 +1,261 @@
+/**
+ * Whether a tool call may change something, judged by its name alone — the
+ * runner's copy of the service's own rule (BaseIn src/scenarios/correctionCheck.ts,
+ * `readsOnly`, `commandReadsOnly`, `callMayChange`), kept word for word so the
+ * two never disagree about the same call.
+ *
+ * Used where a call after a plan's decision is the agent starting a way of its
+ * own (the service's offer1.md O7), and where a plan started after a call
+ * would make it a second time (O8). When in doubt, a call is a change: that
+ * only ends a set of scenarios early or keeps a plan from starting, never lets
+ * a second write through.
+ */
+/** Built-in tools that only read (Claude Code's). */
+const READ_TOOLS = new Set([
+    "Read",
+    "Grep",
+    "Glob",
+    "LS",
+    "WebFetch",
+    "WebSearch",
+    "NotebookRead",
+    "TodoWrite",
+    "TaskOutput",
+    "BashOutput",
+]);
+/** Built-in tools that change files or run commands (Claude Code's). */
+const CHANGING_BUILTINS = new Set([
+    "Write",
+    "Edit",
+    "MultiEdit",
+    "NotebookEdit",
+    "Bash",
+    "KillShell",
+]);
+// Not `query`, `select` or `check`: a database query, a selected option, a
+// check-in can change something.
+const READ_WORDS = new Set([
+    "list",
+    "get",
+    "search",
+    "find",
+    "read",
+    "fetch",
+    "lookup",
+    "count",
+    "view",
+    "show",
+    "describe",
+    "retrieve",
+    "browse",
+    "peek",
+    "inspect",
+    "snapshot",
+]);
+/**
+ * A word that may change something: a name holding one writes, whatever else
+ * it says (`get_or_create_contact`, `find_and_replace`).
+ */
+const WRITE_WORDS = new Set([
+    "create",
+    "add",
+    "set",
+    "update",
+    "upsert",
+    "insert",
+    "put",
+    "post",
+    "send",
+    "delete",
+    "remove",
+    "mark",
+    "replace",
+    "archive",
+    "move",
+    "assign",
+    "book",
+    "cancel",
+    "write",
+    "edit",
+    "modify",
+    "save",
+    "submit",
+    "approve",
+    "reject",
+    "close",
+    "open",
+    "merge",
+    "push",
+    "publish",
+    "upload",
+    "invite",
+    "schedule",
+    "reply",
+    "forward",
+    "transfer",
+    "pay",
+    "refund",
+    "notify",
+    "run",
+    "execute",
+    "exec",
+    "apply",
+    "reset",
+    "start",
+    "stop",
+    "kill",
+    "enable",
+    "disable",
+    "grant",
+    "revoke",
+    "rename",
+    "tag",
+    "label",
+    "comment",
+]);
+/** A tool name's words: `getJiraIssue` → get, jira, issue; `calendar_search_events` → calendar, search, events. */
+function nameWords(name) {
+    return name
+        .replace(/([a-z\d])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z\d]+/)
+        .filter(Boolean);
+}
+/**
+ * A tool that only reads: Claude Code's read-only tools, then the name — a
+ * reading word and no writing word (`calendar_search_events`, `getJiraIssue`;
+ * `run_sql` no: `run` writes). A name with both (`get_or_create_contact`)
+ * changes something.
+ */
+export function readsOnly(toolName) {
+    if (READ_TOOLS.has(toolName))
+        return true;
+    if (CHANGING_BUILTINS.has(toolName))
+        return false;
+    const words = nameWords(toolName.replace(/^mcp__.+?__/, ""));
+    if (words.some((w) => WRITE_WORDS.has(w)))
+        return false;
+    return words.some((w) => READ_WORDS.has(w));
+}
+/** Commands that only look (`ls`, `git status`, `grep …`). */
+const READ_COMMANDS = new Set([
+    "ls",
+    "dir",
+    "cat",
+    "type",
+    "head",
+    "tail",
+    "less",
+    "more",
+    "grep",
+    "rg",
+    "egrep",
+    "fgrep",
+    "find",
+    "wc",
+    "pwd",
+    "echo",
+    "printf",
+    "date",
+    "whoami",
+    "which",
+    "where",
+    "env",
+    "printenv",
+    "stat",
+    "file",
+    "du",
+    "df",
+    "tree",
+    "jq",
+    "sort",
+    "uniq",
+    "cut",
+    "awk",
+    "diff",
+    "cmp",
+    "basename",
+    "dirname",
+    "realpath",
+    "readlink",
+    "true",
+    "false",
+    "test",
+    "sleep",
+    "ps",
+    "uname",
+    "hostname",
+    "id",
+    "nproc",
+    "free",
+    "uptime",
+    "node --version",
+    "npm --version",
+]);
+const READ_GIT = new Set([
+    "status",
+    "log",
+    "diff",
+    "show",
+    "branch",
+    "rev-parse",
+    "ls-files",
+    "blame",
+    "remote",
+    "describe",
+    "config --get",
+    "grep",
+    "shortlog",
+    "tag --list",
+]);
+/** Whether a shell command only looks: every part of it is a looking command, and nothing is written to a file. */
+export function commandReadsOnly(command) {
+    const text = command.trim();
+    if (!text)
+        return true;
+    // A redirect into a file (not into /dev/null, not 2>&1), tee, or an in-place edit changes something.
+    if (/(^|[^0-9&])>{1,2}\s*(?!&|\/dev\/null)\S/.test(text) || /\btee\b/.test(text) || /\bsed\b[^|;&]*\s-i\b/.test(text)) {
+        return false;
+    }
+    if (/\bfind\b[^|;&]*\s-(delete|exec|execdir|ok)\b/.test(text))
+        return false;
+    const parts = text
+        .split(/\|\||&&|[|;\n]/)
+        .map((p) => p.trim())
+        .filter(Boolean);
+    return parts.every((part) => {
+        const words = part.replace(/^(\w+=\S+\s+)+/, "").split(/\s+/);
+        const cmd = (words[0] ?? "").replace(/^.*[\\/]/, "");
+        if (cmd === "git")
+            return READ_GIT.has(words[1] ?? "") || READ_GIT.has(`${words[1] ?? ""} ${words[2] ?? ""}`);
+        if (cmd === "sed" || cmd === "awk")
+            return !/\s-i\b/.test(part);
+        return READ_COMMANDS.has(cmd) || READ_COMMANDS.has(`${cmd} ${words[1] ?? ""}`);
+    });
+}
+/**
+ * Whether one call may change something. A Bash call changes nothing only
+ * when its command is there and only looks; any other tool is a change unless
+ * {@link readsOnly} says it only reads — a tool it cannot tell about counts as
+ * a change. `input` is the call's arguments, as an object or as JSON text.
+ */
+export function callMayChange(toolName, input) {
+    if (toolName === "Bash") {
+        let value = input;
+        if (typeof value === "string") {
+            try {
+                value = JSON.parse(value);
+            }
+            catch {
+                value = undefined;
+            }
+        }
+        const command = value && typeof value === "object" && typeof value.command === "string"
+            ? value.command
+            : "";
+        return command.trim() === "" || !commandReadsOnly(command);
+    }
+    return !readsOnly(toolName);
+}
+//# sourceMappingURL=reads-only.js.map

package/docs/calculatedReplay.md

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

package/docs/calculatedReplayGuide.md

@@ -241,8 +241,10 @@ When replay arms:
   §7) — and never in plan mode.
 - **Direct steps are not visible to the permission system at all.** They are dispatched straight to a
   `bir-proxy`, which calls the upstream on a connection it already holds — or, for Claude Code's own
-  `Read`, `Glob`, `Grep`, `Edit`, `Write` and `Bash`, run by the recorder itself in the project
-  folder, any `Bash` command included (`BIR_BUILTIN_TOOLS`, `BIR_BASH_ALLOW`; up to 0.3.7 only the
+  `Read`, `Glob`, `Grep`, `Edit`, `Write` and `Bash`, run by the recorder itself from the project
+  folder, on any file the agent could reach (from 0.3.21; up to 0.3.20 only files inside the
+  project) and any `Bash` command included (`BIR_BUILTIN_TOOLS`, `BIR_PATH_ALLOW`,
+  `BIR_BASH_ALLOW`; up to 0.3.7 only the
   first three). Claude Code never sees them.
   The `run_scenario` call that starts them is answered `allow` too, while the runner has announced a
   direct plan; your own deny or ask rules for it still apply.
@@ -253,7 +255,8 @@ That is what makes replay fast, and it is the whole risk. Two things follow:
 2. Run `bir replay allow <servers>` (§5.3). An allowlist of the servers you are comfortable having
    called unattended is cheap insurance, and it is the difference between "replay reads a dashboard"
    and "replay can do anything any wrapped server can do". The same goes for built-ins:
-   `BIR_BUILTIN_TOOLS=Read,Glob,Grep` keeps writes and commands with the model, and
+   `BIR_BUILTIN_TOOLS=Read,Glob,Grep` keeps writes and commands with the model,
+   `BIR_PATH_ALLOW=project` keeps the file tools inside the project folder, and
    `BIR_BASH_ALLOW=git,npm test` (for example) limits the commands the recorder runs itself.
 
 Nothing else is approved on your behalf. Outside a matched scenario's own steps, a wrapped MCP call
@@ -368,8 +371,9 @@ so there is exactly one switch and it cannot get out of step with itself.
 | `BIR_STEP_TIMEOUT_MS` | `60000` | Per-step ceiling for one direct `tools/call`, clipped to what the plan has left |
 | `BIR_LOGIC_TIMEOUT_MS` | `1000` | How long one scenario logic body may run before it is stopped. At most 10 000 |
 | `BIR_REPLAY_RECORDED_OUTPUTS` | *(unset)* | `1` lets a step that could not be sent (a built-in off `BIR_BUILTIN_TOOLS`, no proxy, a server off the allowlist) stand on its recorded output instead of stopping the plan. Never for a timeout or an upstream error |
-| `BIR_BUILTIN_TOOLS` | `Read,Glob,Grep,Edit,Write,Bash` | Built-ins the runner executes itself during a replay, in the session's own project directory and confined to it. A chain whose only non-MCP steps are on this list arms `direct`. A runner-side step never reaches the host's permission prompts, so leave off any tool you want the model to call itself; `Read,Glob,Grep` is the read-only set (the default up to 0.3.7). `none`: every built-in step is steered in the session. Claude Code sessions only: in a LangChain application a tool with one of these names is the application's own, and the runner runs none (§6.5) |
+| `BIR_BUILTIN_TOOLS` | `Read,Glob,Grep,Edit,Write,Bash` | Built-ins the runner executes itself during a replay, from the session's own project directory (which folders the file tools may touch: `BIR_PATH_ALLOW`). A chain whose only non-MCP steps are on this list arms `direct`. A runner-side step never reaches the host's permission prompts, so leave off any tool you want the model to call itself; `Read,Glob,Grep` is the read-only set (the default up to 0.3.7). `none`: every built-in step is steered in the session. Claude Code sessions only: in a LangChain application a tool with one of these names is the application's own, and the runner runs none (§6.5) |
 | `BIR_BASH_ALLOW` | *(unset: any command)* | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset means any command; `none` means no command, and `Bash` steps are steered in the session. A plan's Bash steps share a working directory, exactly as the host's own Bash tool does — variables and functions do not persist, also as the host's. A call with `run_in_background`, or with its own `timeout` longer than the step's clock (`BIR_STEP_TIMEOUT_MS`), is never started on the runner: the plan hands over in front of it |
+| `BIR_PATH_ALLOW` | *(unset: any folder, from 0.3.21)* | Folders a runner-side `Read`, `Glob`, `Grep`, `Edit` or `Write` may touch (`*` for all). Unset means any path, as the agent's own tools reach it — a plan that reads the agent's memory file under `~/.claude` runs. `project` is the session's project folder alone (the rule up to 0.3.20); add folders after a comma, `~` for the home folder: `project,~/.claude`. Under a list, a path outside it, symlinks included, is refused and the plan hands over in front of it. `none` means no folder, and the file steps are steered in the session. `Bash` is `BIR_BASH_ALLOW`'s |
 | `BIR_SEGMENT_ARM` | *(unset: on, from 0.3.19)* | A segment the service hands out runs mid-task: a recurring sub-task, or a half of a task after a plan's decision. `0` is observe-only: what would have armed is logged (`replay.segment_would_arm`) and nothing is replaced. Up to 0.3.18 observe-only was the default. A recorder started before an update keeps its old default until `bir up --restart` |
 | `BIR_INTENT_ARM` | *(unset)* | `1` lets a match found mid-turn arm a plan in the calling tool's place, which means waiting for it (`BIR_INTENT_ARM_BUDGET_MS`, 500); `0` never waits, and then nothing starts mid-task, segments included: what would have armed is logged; unset follows `BIR_SEGMENT_ARM`, so from 0.3.19 it is on unless `BIR_SEGMENT_ARM=0` |
 | `BIR_VERBOSE` | *(unset)* | `1` adds per-step `replay.*` detail lines |
@@ -495,7 +499,10 @@ Everything replay decides is one line. `grep` for these:
 | `replay.step_not_taken` | A step's test said this request does not need it, and nothing was sent for it ([calculatedReplay.md](calculatedReplay.md) §9.2). `plan.armed … tests=` lists the tested steps by their place in the plan: `4:hand_over,11:skip` |
 | `replay.diverge` / `replay.compose` | Off-script, and the recovery |
 | `replay.handover` | The plan stopped and handed the rest of the task to the model; `kind=` and `step=` say where. `kind=decision` (0.3.19) is a plan that ran the steps before its decision and stopped there, as planned (`via=divergence` when a divergence's bundle ran up to it) |
-| `run.fragment … decision=true` / `run.fragment_dropped` | After a plan's decision: the agent's own work from its next call is recorded as a fragment, from which the service makes the other half / a plan the intent check armed took that call instead, so nothing is recorded as the other half |
+| `run.fragment … decision=true` / `run.fragment_dropped` | After a plan's decision: the agent's own work from its next call is recorded as a fragment, from which the service makes a calculated scenario of that way / a plan the intent check armed, or a next scenario, took that call instead, so nothing is recorded as the agent's own |
+| `replay.next_ready` / `replay.next_hit` / `replay.next_miss` | 0.3.20: the calculated scenarios that can follow a plan's decision, armed while the agent decided / the agent's call was one's first step, value for value, so it runs in the call's place / none was used: `reason=other_values` (the same first tool with other values), `own_way` (a call that may change something and starts none of them), `not_ready` (the one that starts with that tool was not armed in time), `calls_limit` (5 calls started none), `turn_ended`. A call that only reads ends nothing |
+| `run.fragment_closed` | 0.3.20: a scenario that follows the decision took over after the agent's own looks had opened the fragment; the fragment ends there, with what the agent did itself |
+| `replay.decision … code=would_repeat` | 0.3.20: a plan an intent match armed after the agent's call would have made that call again (the same tool that may change something, or for a shell the same command), so it was not started (never twice) |
 | `replay.vetoed` | A direct plan retired without running anything: `run_scenario` was not the first call, or never arrived |
 | `replay.run_ambiguous` | Two sessions had `run_scenario` pending and the request named neither; nothing ran |
 | `replay.cancelled` / `replay.note_kept` | A direct run's caller went away (Esc); no further step started, and the note is kept for the model's next call |

package/package.json

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

package/production.md

@@ -601,11 +601,24 @@ Truncation is always marked with the original size.
 - A plan whose chain has a decision keeps these protections when it stops earlier for another reason (a parked or failed step, a judgement, the budget). Its note has no intent line and no parameters, and lists the remaining steps only up to the decision. Its directive leaves the intent out. An agent sent on to the recorded half's steps would start that half's segment, and the plan would have decided after all.
 - The report is `fell_back` (or `failed` when no step ran) with `fallbackKind: "decision"` and `fallbackStepIndex` the decision step. The decision step gets no verdict, so nothing is counted against it.
 - When a step ran, the hand-over takes the plan's usage mark: the plan is billed up to the stop, and the agent's decision and the half it took are not on its bill. This holds for a plan the prompt started and for one an intent match started. Every other hand-over still takes no mark.
-- The agent's own next call opens the fragment, marked `metadata.decisionOf = {scenarioId, stepIndex}`: the service makes the other half of the task from it. When a plan the intent check armed takes that call instead (a segment of one half), the fragment is dropped (`run.fragment_dropped`): what follows is not the other half.
+- The agent's own next call opens the fragment, marked `metadata.decisionOf = {scenarioId, stepIndex, request}` (`request`, the turn's prompt, redacted and cut to 4,000 characters, from 0.3.20): the service makes a calculated scenario of that way from it, calculated with the request (the service's offer1.md O2). When a plan the intent check armed, or a next scenario (below), takes that call instead, the fragment is dropped (`run.fragment_dropped`).
 - `ranThrough` sends one entry per plan, with the plan's own position (the decision step itself for a decision). The service maps it onto the recording.
 - `bir replay` stops in front of a decision and says so (`stopped     before step N …: the plan's decision`).
 - A runner up to 0.3.18 reads the unknown kind as `known_bad_step`: it stops there too, but its note and report name a failure.
 
+**What can follow a decision (0.3.20, the service's offer1.md).** The first time a way is taken after a decision, the agent does it and its fragment becomes a calculated scenario of that decision. The next time:
+
+- When a plan stops at its decision, the runner asks the service once, in the background, which calculated scenarios can follow it (`POST /scenarios/:planId/next`, body `{turnId, supportsCalls}`; at most 4, each handed out with its own ticket and `key: "decision"`). An older service, a 404 or any failure is "none". It arms each one while the agent reads the note and decides: its values are read from the turn's request and this turn's results (the reading carries `atDecision: {scenarioId, stepIndex}`), and settled. `replay.next_ready` says how many are ready.
+- The agent's next calls are checked against them before the intent probe. A call that is a next scenario's first step, **value for value** (every argument the step's own; the pin guard's "plausibly the step" is not enough), is a hit: it is answered in its place with that scenario's directive (`replay.next_hit`), the agent calls `run_scenario`, and the scenario runs every step, that one included, once. It is booked on its own ticket. A scenario whose first step is inside a sub-task (a call row) can never be the agent's call in place: it is never compared.
+- Each scenario is checkable as soon as the service answers; its arm runs on its own. A call waits only for the arm of a scenario that starts with the call's own tool (at most 6 s, `BIR_NEXT_HIT_WAIT_MS`), and not at all for the others. While the service has not answered yet, a call waits for that answer only, at most 1 s.
+- When the background reading left a value of the first step empty, the call waits while it is read once more with the agent's call as `liveCall`; the service fills such a value from the call. A value read differently is never read again: an e-mail to carlos is never the recorded e-mail to olga.
+- **A call that only reads keeps the set** (by the service's own rule, mirrored in `src/replay/reads-only.ts`: Claude Code's read tools, a name with a reading word and no writing word, a Bash command that only looks). The set ends unused (`replay.next_miss`) at the agent's first call that may change something and is no hit: `other_values` when the call has a scenario's first tool with other values, `own_way` when it starts none of them — the agent is doing a way of its own, and no scenario may start in the middle of it — and `not_ready` when the scenario that starts with that tool was not armed in time. It also ends after 5 calls that start none (`calls_limit`), or at the turn's end. A scenario not armed in time for a call that only reads misses that call only. Unused ones never run and are never reported; the agent's own work is recorded as the fragment, as before.
+- A later decision in the same turn starts a new set: what could follow the earlier one is dropped, never checked again.
+- A hit after the agent's own looks had opened the fragment ends that fragment there (`run.fragment_closed`, finished with what the agent did itself): the scenario's own calls, pinned in steer mode, are never recorded into it.
+- `/health` shows the set per session: `next: {entries, armed, calls, ended}`.
+
+**Never twice (0.3.20, offer1.md O8).** A plan an intent match arms after the agent's call — not in its place — whose steps call the same tool is not started: it would make that call a second time (issue fx2: the agent's e-mail, then the plan's own). `replay.decision code=would_repeat`. A tool that only reads, by the same rule as above (`crm_search_customers`, `Read`), may repeat. For Bash and PowerShell the call is its command: only a step that would run that very command counts.
+
 **Measured cost.**
 
 - A turn's cost is measured only when tokens were found and every model of the turn has a price in the runner's table. This holds for every host, Claude Code too. A model outside the table used to cost $0, and that zero was called measured.
@@ -1058,8 +1071,9 @@ Defaults were checked in `src/`.
 | `BIR_STEP_TIMEOUT_MS` | recorder | 60000 | One direct `tools/call`. |
 | `BIR_LOGIC_TIMEOUT_MS` | recorder | 1000 (capped at 10000) | Synchronous time limit for one scenario logic body. |
 | `BIR_REPLAY_RECORDED_OUTPUTS` | recorder | unset | `1`: a step that could not be sent may use its recorded output, labelled as such. |
-| `BIR_BUILTIN_TOOLS` | recorder | `Read,Glob,Grep,Edit,Write,Bash` | Built-ins the runner executes itself during a replay, in the session's project directory and confined to it (up to 0.3.7 the default was `Read,Glob,Grep`). Runner-side steps bypass the host's permission prompts; leave a tool off to have the model call it. `none` turns it off. Not in a session of another host (§3.2): the runner runs no step itself there, whatever a tool is named. |
+| `BIR_BUILTIN_TOOLS` | recorder | `Read,Glob,Grep,Edit,Write,Bash` | Built-ins the runner executes itself during a replay, from the session's project directory; which folders the file tools may touch is `BIR_PATH_ALLOW` (up to 0.3.7 the default was `Read,Glob,Grep`). Runner-side steps bypass the host's permission prompts; leave a tool off to have the model call it. `none` turns it off. Not in a session of another host (§3.2): the runner runs no step itself there, whatever a tool is named. |
 | `BIR_BASH_ALLOW` | recorder | unset (any command) | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset means any command; `none` means no command, and `Bash` steps are steered. A plan's Bash steps share a working directory, as the host's do; variables do not persist, also as the host's. |
+| `BIR_PATH_ALLOW` | recorder | unset (any folder) | Folders a runner-side `Read`, `Glob`, `Grep`, `Edit` or `Write` may touch (`*` for all). Unset means any path, as the agent's own tools (from 0.3.21; up to 0.3.20 the project directory alone). `project` is the session's project directory, `~` the home folder: `project,~/.claude`. Under a list, a path outside it, symlinks included, is `not_run` (hand-over). `none` means no folder, and file steps are steered. |
 | `BIR_DERIVE_RECENT_RESULTS` | recorder | 5 | How many of this prompt's tool results derivation may read (`0`: none). Never for plans with a command sink, and never for a plan started at the prompt: a prompt just submitted has no results yet, and an earlier prompt's are not its own. So in a session of another host, where a plan starts at the prompt only, none are read. |
 | `BIR_INTENT_MATCH` | recorder | on | `0` turns mid-turn intent probes off. |
 | `BIR_INTENT_MATCH_BUDGET_MS` | recorder | 4000 | One probe's own ceiling. It is not a hook wait. |