@basein/runner 0.3.3 → 0.3.5

package/dist/config/generate.js

@@ -823,6 +823,18 @@ export function setEditing(sidecar, cwd, on) {
         return undefined;
     return setProjectRecord(sidecar, cwd, { port: record.port, editing: on });
 }
+/**
+ * `bir setup`: scenario editing on for `cwd`, unless it was ever set — an
+ * `off` a person stored is theirs, and no setup turns it back on. Returns true
+ * when it was switched on now.
+ */
+export function settleEditing(sidecar, cwd) {
+    const record = projectRecord(sidecar, cwd);
+    if (!record || record.editing !== undefined)
+        return false;
+    setProjectRecord(sidecar, cwd, { port: record.port, editing: true });
+    return true;
+}
 /**
  * Keep this project's stored replay switch ({@link ReplayPolicy.enabled}) in
  * line with what the person asked for, so the recorder never steers — or runs

package/dist/control/server.js

@@ -225,6 +225,12 @@ function isHookRoute(route) {
 function isPlanMode(payload) {
     return payload.permission_mode === "plan";
 }
+/** The `bir` tools whose `force` saves (or undoes) what the scenario check refused. */
+const FORCEABLE_BIR_TOOLS = new Set(["scenario_edit", "scenario_undo"].map((tool) => `mcp__${SCENARIO_SERVER_KEY}__${tool}`));
+/** A `bir` call that forces a change past the check (see `onToolPre`). */
+function forcedBirChange(toolName, input) {
+    return FORCEABLE_BIR_TOOLS.has(toolName) && input?.force === true;
+}
 /**
  * Tool arguments as an older proxy reports them — redacted, long strings
  * clipped — for joining a report that carries no `argsFingerprint` of its own.
@@ -2266,6 +2272,20 @@ export class ControlServer {
             if (toolUseId)
                 (run.housekeepingUses ??= new Set()).add(toolUseId);
             logDetail("tool.pre.skipped", { run: run.runId, tool: toolName, why: "host housekeeping" });
+            // `bir setup` lets Claude Code run every `bir` tool without asking — but a
+            // change saved or taken back with `force`, past the check that refused
+            // it, is the person's decision (editSteps.md D3), so Claude Code asks
+            // whatever the allow rule says. Not where the person chose to be asked
+            // nothing at all.
+            if (forcedBirChange(toolName, modelArgs) && payload.permission_mode !== "bypassPermissions") {
+                return {
+                    hookSpecificOutput: {
+                        hookEventName: "PreToolUse",
+                        permissionDecision: "ask",
+                        permissionDecisionReason: "force saves what the scenario check refused — only for a recording that was itself wrong; you decide, not the model",
+                    },
+                };
+            }
             return {};
         }
         // What a cancelled direct run left this session to tell (see

package/docs/calculatedReplay.md

@@ -1456,15 +1456,17 @@ are where `bir` changes a scenario by hand, so the rules are strict:
 - Exit codes: `0` checked OK, saved or undone; `1` refused, not found, or a service error; `2`
   usage. `--json` prints the service's body unchanged.
 
-The same commands are tools on the `bir` MCP server, which by default lists only `run_scenario`:
-every tool definition rides along with every request of every session. `scenario_show` (`target`,
-`step`), `scenario_edits` (`target`) and `investigate` (`id`) only read; they are listed in a project
-where `bir scenario editing on` was run, or with `BIR_SCENARIO_TOOLS=read` in the `bir` server's
-environment, and answer a host that calls them unlisted all the same. `scenario_check` (`target`,
-`step`, `inputLogic`, `outputLogic`, `unfreeze`), `scenario_edit` (the same, plus `freeze`, `force`,
-`note`, `revision`) and `scenario_undo` (`target`, `edit` or `step`, `force`, `note`) are offered
-only in a project where `bir scenario editing on` was run, because that server runs in every session
-of every installed project. Each tool runs this package's own `bir … --json`, with logic bodies
+The same commands are tools on the `bir` MCP server. `scenario_show` (`target`, `step`),
+`scenario_edits` (`target`) and `investigate` (`id`) only read; `scenario_check` (`target`, `step`,
+`inputLogic`, `outputLogic`, `unfreeze`), `scenario_edit` (the same, plus `freeze`, `force`, `note`,
+`revision`) and `scenario_undo` (`target`, `edit` or `step`, `force`, `note`) change a scenario. All
+six are listed where scenario editing is on — `bir setup` turns it on, and adds `mcp__bir` to
+`permissions.allow` in `.claude/settings.local.json`, so Claude Code runs every `bir` tool without
+asking. Elsewhere — `bir scenario editing off`, which a later setup keeps, or a project wired by a
+bare `bir install` — the server lists `run_scenario` alone: it runs in every session of every
+installed project, and every listed tool's definition rides along with every request.
+`BIR_SCENARIO_TOOLS=read` in its environment lists the reading three there, and they answer a host
+that calls them unlisted all the same. Each tool runs this package's own `bir … --json`, with logic bodies
 passed through temporary files; a refusal comes back as an MCP error result carrying the report. A
 reading tool's answer is capped at 24 000 characters (`BIR_SCENARIO_MAX_OUTPUT_CHARS`) and gives up
 after `BIR_READ_TIMEOUT_MS` (15 s) plus 10 s; a changing tool gets 120 s. A call the host cancels, or

package/docs/calculatedReplayGuide.md

@@ -271,12 +271,14 @@ undoes both, leaving everything else as it is:
 - registers a first-party MCP server under the key **`bir`** in the local scope — `~/.claude.json`,
   under Claude Code's key for this project, never the `.mcp.json` a team commits (`--mcp-json` puts
   it there instead, pre-approved in `.claude/settings.local.json`, the older shape). It exposes
-  `mcp__bir__run_scenario` — the channel a fully-wrapped scenario's results come back through — and
-  by default nothing else. Three tools that only read a scenario (`scenario_show`,
-  `scenario_edits`, `investigate`) are listed after `bir scenario editing on`, or with
-  `BIR_SCENARIO_TOOLS=read` in the server's environment, and three for changing one
-  (`scenario_check` tries a change, `scenario_edit` saves it, `scenario_undo` takes it back) only
-  after `bir scenario editing on`. §9.2 lists them with their arguments; the editing it describes
+  `mcp__bir__run_scenario` — the channel a fully-wrapped scenario's results come back through. Three
+  tools that only read a scenario (`scenario_show`, `scenario_edits`, `investigate`) and three for
+  changing one (`scenario_check` tries a change, `scenario_edit` saves it, `scenario_undo` takes it
+  back) come with scenario editing: `bir setup` turns it on, and adds `mcp__bir` to
+  `permissions.allow` in `.claude/settings.local.json` so Claude Code runs every `bir` tool without
+  asking. A bare `bir install --replay` does neither: its server lists `run_scenario` alone until
+  `bir scenario editing on` (or `BIR_SCENARIO_TOOLS=read` in the server's environment, for the
+  reading three). §9.2 lists them with their arguments; the editing it describes
   is built but not yet released. From the next version, a call to any of them except
   `run_scenario` is never recorded. In a subdirectory or linked worktree of a git repository the
   server is not added — in the local scope it would apply to the whole repository — and replay
@@ -630,8 +632,9 @@ bir scenario show  <runId|scnId> [--step <n>]
 bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze]
 bir scenario edit  <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
                    [--freeze | --unfreeze] [--note "<why>"] [--force --note "<why>"] [--revision <n>]
+bir scenario edit  <runId|scnId> --param <name> --kind target|setting [--note "<why>"] [--revision <n>]
 bir scenario edits <runId|scnId>
-bir scenario undo  <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "<why>"]
+bir scenario undo  <runId|scnId> [--edit <sedit_id|pedit_id> | --step <n> | --param <name>] [--force --note "<why>"]
 bir scenario calc  <runId|scnId> [--force [--discard-edits]]
 bir scenario editing on|off|status
 ```
@@ -666,8 +669,9 @@ never take, is never reached in the check. A `fetch` inside a `try` fails in the
 code in its own process, with the global scope and only a time limit, where `fetch` and `process`
 do exist. So read every change before it is saved — yours and Claude's.
 
-**Only a step's code and its mark can be changed.** Not the parameters, not their sample values, not
-the logic that builds the final answer. Only tool steps: a sub-task call row belongs to the service.
+**Only a step's code and its mark can be changed — and a parameter's kind (below, *A value no prompt names*).**
+Not the parameters' sample values, not the logic that builds the final answer. Only tool steps: a
+sub-task call row belongs to the service.
 
 #### The fix, step by step
 
@@ -1024,13 +1028,17 @@ check.
 1. **In its terminal.** Claude runs `bir scenario …` like any other command. You see each command,
    and Claude Code asks you before it runs one, unless you allowed it. This works in every project.
 2. **As tools on the `bir` MCP server** — the server `bir setup` or `bir install --replay` adds
-   (§5.2). This is smoother for the model. **By default the server lists only `run_scenario`:
-   every tool definition rides along with every request of every session. The tools that read and
-   change a scenario come when you turn editing on, per project:**
+   (§5.2). This is smoother for the model. **`bir setup` turns scenario editing on, so the server
+   lists every tool below, and Claude Code runs them without asking (`mcp__bir` in
+   `permissions.allow`, `.claude/settings.local.json`) — except `scenario_edit` or `scenario_undo`
+   with `force`: the recorder's `PreToolUse` answers `ask` for those, so the person decides whether
+   a change goes past the check that refused it.** Every listed tool's definition rides along
+   with every request of every session, so the switch is per project, and an `off` is kept by
+   every later setup. A bare `bir install --replay` leaves it off: `run_scenario` alone.
 
 ```bash
 bir scenario editing on       # this project's `bir` server also offers the tools that read and change a scenario
-bir scenario editing off      # back to run_scenario alone
+bir scenario editing off      # back to run_scenario alone; a later `bir setup` keeps it off
 bir scenario editing status   # what is stored for this project
 ```
 
@@ -1043,12 +1051,12 @@ The tools, as the `bir` server defines them. **Bold** arguments are required.
 | Tool (`mcp__bir__…`) | Offered | Arguments | Runs |
 |---|---|---|---|
 | `run_scenario` | always, unless the runner is off | none | the plan armed for this turn (§6.1) |
-| `scenario_show` | after `bir scenario editing on`, or with `BIR_SCENARIO_TOOLS=read` | **`target`**, `step` | `bir scenario show` |
-| `scenario_edits` | after `bir scenario editing on`, or with `BIR_SCENARIO_TOOLS=read` | **`target`** | `bir scenario edits` |
-| `investigate` | after `bir scenario editing on`, or with `BIR_SCENARIO_TOOLS=read` | `id` — a `run_`, `scn_` or `sexec_` id; without it, the newest turn here | `bir investigate` |
-| `scenario_check` | after `bir scenario editing on` | **`target`**, **`step`**, `inputLogic`, `outputLogic`, `unfreeze` | `bir scenario check` |
-| `scenario_edit` | after `bir scenario editing on` | **`target`**, **`step`**, `inputLogic`, `outputLogic`, `freeze`, `unfreeze`, `force`, `note`, `revision` | `bir scenario edit` |
-| `scenario_undo` | after `bir scenario editing on` | **`target`**, `edit` or `step` (not both), `force`, `note` | `bir scenario undo` |
+| `scenario_show` | with scenario editing on (`bir setup` turns it on), or with `BIR_SCENARIO_TOOLS=read` | **`target`**, `step` | `bir scenario show` |
+| `scenario_edits` | with scenario editing on, or with `BIR_SCENARIO_TOOLS=read` | **`target`** | `bir scenario edits` |
+| `investigate` | with scenario editing on, or with `BIR_SCENARIO_TOOLS=read` | `id` — a `run_`, `scn_` or `sexec_` id; without it, the newest turn here | `bir investigate` |
+| `scenario_check` | with scenario editing on | **`target`**, **`step`**, `inputLogic`, `outputLogic`, `unfreeze` | `bir scenario check` |
+| `scenario_edit` | with scenario editing on | **`target`**, and **`step`** with `inputLogic`, `outputLogic`, `freeze`, `unfreeze`, `force` — or **`param`** with **`kind`**; `note`, `revision` | `bir scenario edit` |
+| `scenario_undo` | with scenario editing on | **`target`**, one of `edit`, `step` or `param`, `force`, `note` | `bir scenario undo` |
 
 - `target` is a `scn_` id, or the `run_` id of a whole-run scenario. `step` is the `stepIndex`.
 - `inputLogic` and `outputLogic` are the code itself, as text. The server writes them to temporary
@@ -1095,6 +1103,59 @@ For the hiring-year case, Claude's report would be: *step 4's code is a copy of
 so it was marked; the new code builds the query from `summary_table`; the check says it reproduces
 the recording, and the step will run by itself.*
 
+#### A value no prompt names — `--param <name> --kind setting`
+
+> Built 2026-09-28, **not yet released**: it needs the next service deploy, then the next
+> `@basein/runner` version. The design is `findoffer.md` and `editSteps.md` ("Parameter kinds") in
+> the BaseIn repository.
+
+Every parameter of a plan is one of two kinds:
+
+| Kind | Means | When the prompt does not name it |
+|---|---|---|
+| **target** | what the task acts on — a file, a table, a region | the plan is declined: `missing_target`. A target is never guessed |
+| **setting** | a value nobody states, the same every time — a database, a host, a working folder | the recorded value is used |
+
+A prompt that names a value always wins, whatever its kind. The calculation decides the kinds, and
+it can get one wrong. The hiring-year plan `scn_09dbd4e6` never ran: its `database` was a target,
+and the MCPMark prompt never names the database — it is simply the one the agent is connected to.
+`bir investigate` names such a target: `declined … missing_target (database not named in the
+prompt)`.
+
+**Do this.** Make it a setting, and say why:
+
+```bash
+bir scenario edit scn_09dbd4e6-… --param database --kind setting --note "The database is the connection; the prompt never names it."
+```
+
+**You should see:**
+
+```
+Parameter database: target → setting (revision 4). Undo: bir scenario undo scn_09dbd4e6-… --edit pedit_…
+  When a prompt names no database, the runner now uses its recorded value ("hys_trial"); a prompt that names one still wins.
+```
+
+- `--kind setting` needs `--note`: it is the one change that lets a replay use a recorded value.
+  `--kind target` does not.
+- No code runs, so nothing is checked. The revision goes up by one, as for a step edit.
+- **A recalculation keeps the kind** while the parameter keeps its name, so unlike a step edit it
+  does not hold a recalculation back. When a recalculation drops the parameter, the change is
+  history.
+- `bir scenario edits` lists it as `param database`, and `bir investigate` reports it on every run
+  (`param_kind_edited`).
+- `bir scenario undo … --param database` takes it back. A plain `bir scenario undo` takes back the
+  newest change, a step's or a parameter's.
+- The `scenario_edit` tool takes `param` and `kind` instead of `step`; `scenario_undo` takes `param`.
+
+**If it goes wrong:**
+
+| Symptom | Fix |
+|---|---|
+| `--kind setting needs --note "why" (note_required)` | Add `--note "why"` |
+| `Not saved (not_found): … has no parameter …` | Use a name that `bir scenario show <id>` lists under `parameters` |
+| `Nothing to change: database is already a setting.` | Nothing to do |
+| `A parameter's kind is not checked` | `check` runs code, and a kind has none. Use `bir scenario edit` |
+
 #### When it does not work
 
 | Symptom | Cause | Fix |
@@ -1119,8 +1180,9 @@ the recording, and the step will run by itself.*
 | `payload_too_large` | The whole request is larger than the service accepts (HTTP 413, over 256 kB) | A logic body may be at most 20 000 characters, and a note 500 |
 | `rate_limited` | More checks, edits and undos in a minute than the service allows (`SCENARIO_EDITS_PER_MINUTE`, 30 by default) | Wait a minute |
 | `not found` for a scenario you can see | It is not yours. **Only the owner can change a scenario** — an admin gets `not found` too | Ask the owner |
-| The `scenario_check`, `scenario_edit` and `scenario_undo` tools are missing | `bir scenario editing on` was not run in this project, or the session started before it | Run it here, then restart the session |
-| Only `run_scenario` is listed; `scenario_show`, `scenario_edits` and `investigate` are missing | That is the default: the reading tools come with `bir scenario editing on`, or with `BIR_SCENARIO_TOOLS=read` in the server's environment | Either one, then restart the session. Or run the `bir scenario …` commands in the terminal |
+| The `scenario_check`, `scenario_edit` and `scenario_undo` tools are missing | Scenario editing is off here: `bir scenario editing off` was run (a later setup keeps it off), the project was wired by `bir install` rather than `bir setup`, or the session started before the switch | `bir scenario editing on` here (or `bir setup`), then restart the session |
+| Only `run_scenario` is listed; `scenario_show`, `scenario_edits` and `investigate` are missing | The same: the reading tools come with scenario editing, or with `BIR_SCENARIO_TOOLS=read` in the server's environment | Either one, then restart the session. Or run the `bir scenario …` commands in the terminal |
+| Claude Code asks before each `bir` tool | No `mcp__bir` in `permissions.allow`: the project was wired by `bir install`, or the rule was taken out | `bir setup` here adds it (`bir doctor` says when it is missing) |
 | The `bir` server lists no tools at all | The runner is off here (`bir off`, `bir off --here`, or `BIR_OFF=1` where Claude Code started) | `bir on` (or `bir on --here`), and the server tells the open session its list changed. For `BIR_OFF=1`, start Claude Code without it |
 
 ---

package/docs/quickstart.md

@@ -75,7 +75,9 @@ if it is, it stops and asks you to `cd` to the project and paste again. Then:
 ==> Wiring the project
   + chrome-devtools → bir-proxy (local scope, over the .mcp.json entry; upstream: npx)
   + bir → bir-scenario (calculated replay; local scope)
+  + scenario editing on: the bir server offers investigate and the scenario tools too (`bir scenario editing off` takes them away)
   + hooks → C:\work\repo\.claude\settings.local.json (control server on http://127.0.0.1:53411; the recorder starts itself with each session)
+  + mcp__bir → permissions.allow in the same file (Claude Code runs the bir tools without asking)
   + .claude/settings.local.json is listed in C:\work\repo\.git\info\exclude
 
 Wrapped 1 server.
@@ -86,6 +88,7 @@ Done. Recording and replay are on for C:\work\repo
   account    you@example.com  (https://api.bi2202.com)
   wrapped    chrome-devtools
   replay     on — direct execution allowed for: all wrapped (narrow it with `bir replay allow chrome-devtools`)
+  tools      run_scenario, scenario_show, scenario_edits, investigate, scenario_check, scenario_edit, scenario_undo — Claude Code runs them without asking, except a forced change
   recorder   started in the background (pid 1234) — it starts itself with every Claude Code session
   log        C:\Users\you\.baseinstrunner\logs\3f9c1a2b7d4e5f60.log
 
@@ -104,8 +107,11 @@ is not changed;
 *replay* says which of them a calculated scenario may call unattended — narrow
 it with `bir replay allow <names>`, turn it off with `bir replay off`, and read
 [calculatedReplayGuide.md §5.1](calculatedReplayGuide.md) before leaving it wide
-anywhere that matters; *recorder* is the background process, and *log* is where
-its audit lines go.
+anywhere that matters; *tools* is what the `bir` MCP server gives Claude here —
+every tool, and Claude Code runs them without asking, except a change forced
+past the scenario check (`bir scenario editing off` leaves `run_scenario` alone,
+and a later setup keeps it that way); *recorder* is
+the background process, and *log* is where its audit lines go.
 
 A project with no MCP servers in any scope — none in `.mcp.json`, and none for
 this project or your user in `~/.claude.json` — shows `wrapped (no MCP servers
@@ -190,12 +196,12 @@ its prompt, its tool calls and its final answer.
 |---|---|
 | `~/.baseinstrunner/config.json` | the service address; `BIR_AUTH_URL` in the environment overrides it, and `bir setup` warns when the two differ |
 | `~/.baseinstrunner/credentials.json` | the cached session, bound to the service that issued it |
-| `~/.baseinstrunner/installed.json` | what `bir uninstall` needs to undo each change — the original text of the project files it rewrote, with their credential values left out — and each project's port, token and replay switches, and whether Claude's `bir` tools may change scenarios there (`bir scenario editing on`) |
+| `~/.baseinstrunner/installed.json` | what `bir uninstall` needs to undo each change — the original text of the project files it rewrote, with their credential values left out — and each project's port, token and replay switches, whether Claude's `bir` tools may change scenarios there (`bir setup` turns it on, `bir scenario editing off` turns it off), and the permission rule setup added |
 | `~/.baseinstrunner/logs/<key>.log` | the recorder's audit log, one file per project |
 | `~/.baseinstrunner/node/` | a private Node, only if the machine had no usable one; not on PATH |
 | `~/.baseinstrunner/npm/` | the runner package |
 | `~/.baseinstrunner/bin/` | the `bir` and `bir-hooks` launchers, first on your user PATH |
-| `<project>/.claude/settings.local.json` | Claude Code's hooks for this project. Yours, not the team's: it carries this project's token and an absolute Node path |
+| `<project>/.claude/settings.local.json` | Claude Code's hooks for this project, and `mcp__bir` in `permissions.allow` so the `bir` server's tools run without asking. Yours, not the team's: it carries this project's token and an absolute Node path |
 | `~/.claude.json` (`$CLAUDE_CONFIG_DIR/.claude.json` when that is set), this project's local scope | a copy of each MCP server it wraps, under the same name, running through `bir-proxy`; plus the `bir` scenario server. The copy takes precedence in this project only; `.mcp.json` and your user-scope servers are not changed |
 | `<project>/.git/info/exclude` | one line, `.claude/settings.local.json`, so it never shows in `git status` |
 
@@ -363,12 +369,16 @@ The saved code runs on your machine without asking you, like the code the
 calculation wrote. The check only tests what it sends for the recording's
 values. So read the code before it is saved, yours or Claude's.
 
-Claude can do this for you. Ask it in the session; it runs the same commands,
-and Claude Code asks you before each one, unless you allowed it. Or run
-`bir scenario editing on` in the project folder and restart Claude Code: the
-`bir` server then also offers the tools that read and change a scenario (by
-default it offers only `run_scenario`). These `bir` calls
-are never recorded as part of your task.
+Claude can do this for you. Ask it in the session: `bir setup` gave the `bir`
+server the tools that read and change a scenario, and Claude Code runs them
+without asking you. The service still refuses a change that breaks the
+recording, and a change Claude wants to force past that check (`force`) is
+still yours to approve: Claude Code asks you first. `bir scenario edits` shows
+what Claude changed; `bir scenario undo` takes it back. `bir scenario editing off` in the project
+folder takes those tools away (restart Claude Code after), and a later
+`bir setup` leaves them off; Claude can still run the same commands in its
+terminal, and Claude Code then asks you before each one. These `bir` calls are
+never recorded as part of your task.
 
 ---
 

package/package.json

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

@@ -635,7 +635,7 @@ Truncation is always marked with the original size.
 
 ### 6.8 The `bir` MCP server (`src/bin/bir-scenario.ts`, `scenario-liveness.ts`, `service-read.ts`)
 
-**Tools listed.** `tools/list` returns only `run_scenario` by default. The read tools come with `bir scenario editing on` or `BIR_SCENARIO_TOOLS=read`, because every listed tool's definition rides along with every request of every session.
+**Tools listed.** `tools/list` returns every tool where scenario editing is on, which `bir setup` turns on (it also adds `mcp__bir` to `permissions.allow` in `.claude/settings.local.json`, so Claude Code runs them without asking — except `scenario_edit` or `scenario_undo` with `force`, which the recorder's `PreToolUse` answers with `ask` unless the session is in `bypassPermissions` mode). Where it is off — `bir scenario editing off`, which a later setup keeps, or a project wired by a bare `bir install` — it returns only `run_scenario`, and the read tools come with `BIR_SCENARIO_TOOLS=read`, because every listed tool's definition rides along with every request of every session.
 
 **`run_scenario`.**
 
@@ -678,7 +678,7 @@ Truncation is always marked with the original size.
 | The direct plan budget is 100 s (was 120 s), and direct runs are clamped to 270 s. | Keeps a direct run under Claude Code's 2-minute auto-background of an MCP call, and inside `run_scenario`'s client timeout. | `BIR_REPLAY_PLAN_BUDGET_MS=120000` (or `BIR_REPLAY_BUDGET_MS`). |
 | The background recorder ignores an inherited `ANTHROPIC_API_KEY` for derivation. | That key is Claude Code's, so derivation billed the user's own account. | `BIR_DERIVE_API_KEY=<key>`, or `BIR_USE_ANTHROPIC_API_KEY=1`. A `bir-hooks` run by hand still uses the terminal's key. |
 | `run_scenario` never returns `isError`. | An error result makes the model retry or report a failure the user cannot act on. The reason is in `scenario.answered`. | `BIR_SCENARIO_DEBUG=1`. |
-| The `bir` server lists only `run_scenario`. | Tool definitions ride along with every request. | `BIR_SCENARIO_TOOLS=read`, or `bir scenario editing on`. |
+| A bare `bir install` leaves the `bir` server listing only `run_scenario`, and adds no permission rule. | Tool definitions ride along with every request, and a fleet wired by hand must not have its plans changed by an agent. `bir setup` turns both on. | `bir scenario editing on` (or `BIR_SCENARIO_TOOLS=read` for the read tools), and `mcp__bir` in `permissions.allow`. |
 | The `run_scenario` client timeout is 290 s (was 180 s). | It stays under Claude Code's 5-minute MCP idle timeout, above the direct-run worst case. | `BIR_SCENARIO_RUN_TIMEOUT_MS=180000`. |
 | `bir-proxy` exits when its upstream dies. | Claude Code then shows the server as failed and offers a reconnect, as unwrapped. Staying up left tools listed that only answered errors. | `BIR_PROXY_STAY_UP=1`. |
 | Proxy stderr is quiet: routine lines only with verbose logging. | Claude Code files every stderr line as a "Server stderr" error. | `BIR_VERBOSE=1`. |