@basein/runner 0.3.19 → 0.3.21

package/README.md

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

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

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

package/dist/bin/bir-hooks.js

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

package/dist/bin/investigate.js

@@ -246,6 +246,11 @@ export const DECLINES = {
         cause: "the plan was not ready before the hook that would have announced it had to answer: the prompt hook waits 7.5 s in all, match included, and a tool call that starts a plan mid-task waits 1.5 s. What arming waits for is the reading of the prompt's values (the derivation). A plan that was not announced is never run.",
         fix: "run the prompt again. If it keeps happening the reading is slow: the recorder's log (`bir status` names the file) shows when its `replay.derived` line landed, and a dry replay shows what the service's reading took, under `reading` (`bir scenario replay <scnId> --prompt \"…\" --dry --json`). BIR_HOOK_DERIVE_BUDGET_MS does not help here, because the hook's own limit was reached first. To read values on this machine instead of asking the service, set BIR_DERIVE_API_KEY where Claude Code starts.",
     },
+    // Nor this one: the control server's own rule (the service's offer1.md O8).
+    would_repeat: {
+        cause: "a plan the intent check matched would have started after the agent's call, not in its place, and its steps call that same tool: it would have made the call a second time — an e-mail sent twice (issue fx2). Never twice: it was not started, and the agent went on.",
+        fix: "nothing to fix in the plan. A scenario starts in the call's place only when the agent's call is its first step, value for value; one recorded in the order the agent works in (the agent's own run after a decision becomes one) is what starts there.",
+    },
     // Nor is this one: the match itself was late, so nothing was armed at all.
     match_late: {
         cause: "the service's answer to the match landed too late: after the prompt hook had stopped waiting for it (3 s, BIR_MATCH_BUDGET_MS); while prompts were not waiting on the match at all — after one slow answer they stop waiting for a few minutes (`replay.match_gate state=holding`); or with the hook not waiting from the start, because a failure to reach the service was still on record (a `service.degraded` line, perhaps hours before, and no `service.recovered` until after this prompt) or the match request's first attempt failed. The agent did the task itself.",
@@ -408,7 +413,7 @@ export function localFindings(turn) {
             const elsewhere = names.filter((n) => !EXECUTABLE_BUILTINS.has(n));
             const fixes = [];
             if (offList.length > 0) {
-                fixes.push(`The runner runs ${offList.join(", ")} itself when ${offList.length === 1 ? "it is" : "they are"} on \`BIR_BUILTIN_TOOLS\` (unset means all six, from runner 0.3.8) and, for Bash, \`BIR_BASH_ALLOW\` is not \`none\`: fix those where the recorder starts, then \`bir up --restart\`.`);
+                fixes.push(`The runner runs ${offList.join(", ")} itself when ${offList.length === 1 ? "it is" : "they are"} on \`BIR_BUILTIN_TOOLS\` (unset means all six, from runner 0.3.8) and, for Bash, \`BIR_BASH_ALLOW\` is not \`none\` (for the file tools, \`BIR_PATH_ALLOW\`): fix those where the recorder starts, then \`bir up --restart\`.`);
             }
             if (elsewhere.length > 0) {
                 fixes.push(`Put the data ${elsewhere.join(", ")} ${elsewhere.length === 1 ? "reaches" : "reach"} behind an MCP server, wrap it (\`bir install --server <name>\`), and record the prompt again so its steps are MCP calls.`);

package/dist/control/recorder-main.js

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

package/dist/control/server.d.ts

@@ -1202,6 +1202,70 @@ export declare class ControlServer {
      * computed is "no" — the directive then rides on the call's PostToolUse.
      */
     private isFirstStep;
+    /**
+     * The agent's call against `state`'s first step, value for value (the
+     * service's offer1.md O5): `hit` when every argument is the step's own,
+     * `missing` when the only differences are values the plan does not have
+     * (a target the reading left empty, which the agent's call may hold), and
+     * `other` otherwise.
+     */
+    private firstStepVerdict;
+    /**
+     * Whether `state`'s plan calls `toolName` in a step it would run: what makes
+     * a plan started after a call of that tool make it a second time (the
+     * service's offer1.md O8). A tool that only reads never counts — reading
+     * twice changes nothing — by the service's own rule ({@link readsOnly}): a
+     * `crm_search_customers` mid-task never keeps a plan that searches later from
+     * starting.
+     */
+    private planCallsTool;
+    /**
+     * A plan of this turn stopped at its decision: ask the service, once per
+     * plan, which calculated scenarios can follow it, and arm each in the
+     * background while the agent reads the note and decides (offer1.md O3, O4).
+     * Called wherever a hand-over is first seen; a second call for the same plan
+     * does nothing.
+     */
+    private noteDecision;
+    /**
+     * Ask for a decision's next scenarios (offer1.md O3): each is checkable as
+     * soon as the service answers, and armed in the background, each on its own
+     * (O4). Resolves when the service has answered, not when the arms have.
+     * Never rejects.
+     */
+    private fetchNext;
+    /**
+     * Arm one next scenario in the background (offer1.md O4): its values read
+     * from the turn's request and its results so far — or, once more, with the
+     * agent's own call (O5) — and settled, so a call is compared with the first
+     * step as it would really run. Never rejects.
+     */
+    private armNext;
+    /**
+     * The agent's call after a decision, against the scenarios that can follow
+     * it (offer1.md O5, O6). A hit — the call is a scenario's first step, value
+     * for value — is answered in the call's place with that scenario's directive:
+     * the agent calls `run_scenario`, and the scenario runs every step, this one
+     * included, once. Undefined otherwise: the call runs as the agent wrote it.
+     */
+    private tryNextScenarios;
+    /** A next scenario's hit: bookkeeping as for any plan armed mid-task, then its directive in the call's place. */
+    private nextHit;
+    /**
+     * A next scenario hit after the agent's own calls — looks — opened the
+     * fragment of its work after the decision: the fragment ends here, with what
+     * the agent did itself, and nothing more of this turn is recorded into it.
+     * The scenario's own calls, pinned in steer mode or run in direct mode, are
+     * not the agent's work, and would make the fragment a copy of that scenario
+     * (offer1.md O7). A fragment still due is dropped instead
+     * ({@link dropDecisionFragment}).
+     */
+    private closeDecisionFragment;
+    /**
+     * End this turn's next scenarios (offer1.md O6): every one but the hit is
+     * never announced, so never runs and is never reported.
+     */
+    private endNext;
     /**
      * Whether an intent probe may arm a plan in its own `PreToolUse` — and so
      * whether that hook waits for it. See {@link ControlServerOptions.intentArm}.