@basein/runner 0.3.4 → 0.3.5

package/README.md

@@ -79,6 +79,8 @@ written; wraps an older install made there are put back. `--mcp-json` (or
 `BIR_WRAP_MCP_JSON=1`) is that old in-place shape, for a `.mcp.json` nobody
 commits. The hooks go into `.claude/settings.local.json` — your file, not the
 one a team commits; in a git repository it is added to `.git/info/exclude`.
+`bir setup` also puts `mcp__bir` in that file's `permissions.allow`, so Claude
+Code runs the `bir` server's tools without asking (a forced change still asks).
 Uninstall repairs `~/.claude.json` (and a `--config` file) entry by entry;
 `settings.local.json` it puts back byte-for-byte when nothing else has edited
 it since, and repairs entry by entry when something has. A project remembers
@@ -248,12 +250,18 @@ between the two is not guaranteed.
   `bir` server's `run_scenario` (only with `--replay`), and replay's own
   `[BaseInstRunner calculated replay]` notes when a prompt matches a scenario.
   The `bir` server's three tools that only read a scenario (`scenario_show`,
-  `scenario_edits`, `investigate`) are listed only after `bir scenario editing on`,
-  or with `BIR_SCENARIO_TOOLS=read` in its environment: their definitions ride
-  along with every request. The three for changing one (`scenario_check`,
-  `scenario_edit`, `scenario_undo`) appear only after `bir scenario editing on`
-  in that project (not yet released, see below). With the runner off it lists
-  no tools at all.
+  `scenario_edits`, `investigate`) and the three for changing one
+  (`scenario_check`, `scenario_edit`, `scenario_undo`) come with scenario
+  editing, which `bir setup` turns on. Setup also lets Claude Code run every
+  `bir` tool without asking: it adds `mcp__bir` to `permissions.allow` in
+  `.claude/settings.local.json`, and uninstall takes it out again. A change
+  forced past the scenario check (`force`) still asks the person first. Their
+  definitions ride along with every request, so `bir scenario editing off`
+  takes the six away, and a later setup leaves that off. A bare
+  `bir install --replay` lists `run_scenario` alone until
+  `bir scenario editing on` (or `BIR_SCENARIO_TOOLS=read` in the server's
+  environment, for the reading three). With the runner off it lists no tools
+  at all.
 - **Record its own `bir` calls** (next version, not yet released). A session
   that fixes a plan is not a task to replay. The `bir` server's tools other
   than `run_scenario`, and a `Bash` or `PowerShell` command made only of `bir`
@@ -331,9 +339,9 @@ copy — or on purpose, with `--force --note "why"`.** Only the owner can change
 a scenario. `bir scenario undo` takes changes back one at a time: run it again
 to go one further back. An undo is checked too, and is refused if it would
 break a later step or the final answer, unless you add `--force --note "why"`.
-Claude can do all of this: in its terminal, or with the `bir` server's tools
-once `bir scenario editing on` was run in the project. Step by step, with real
-output:
+Claude can do all of this: in its terminal, or with the `bir` server's tools,
+which `bir setup` turns on (`bir scenario editing on` in a project wired by
+`bir install`). Step by step, with real output:
 [the guide's §9.2](docs/calculatedReplayGuide.md).
 
 ```bash
@@ -344,7 +352,7 @@ bir scenario edits scn_…                                   # the history, newe
 bir scenario undo  scn_…                                   # take back the newest edit; again to go further back
 bir scenario undo  scn_… --step 3                          # take back step 3's newest edit only
 bir scenario calc  scn_… --force --discard-edits           # recalculate this plan, dropping its hand edits
-bir scenario editing on                                    # let Claude's `bir` tools change scenarios here
+bir scenario editing on                                    # let Claude's `bir` tools change scenarios here (setup did)
 ```
 
 **A value no prompt names.** Built 2026-09-28, not yet released. Every
@@ -439,7 +447,7 @@ what to do when they register, so there is one switch and no second copy of it:
 | `BIR_REPLAY_RECORDED_OUTPUTS=1` | Let a step's recorded output stand in when the step could not be sent. Unset, the plan stops at that step and hands the task back. |
 
 The `bir` server reads its own: `BIR_SCENARIO_TOOLS=read` lists its three reading
-tools without `bir scenario editing on`, and `BIR_SCENARIO_RUN_TIMEOUT_MS` is how
+tools where scenario editing is off, and `BIR_SCENARIO_RUN_TIMEOUT_MS` is how
 long `run_scenario` waits for a run (default `290000`). Everything else — remote
 upstreams, the recorder's backlog, service timeouts, the `bir` server's output
 caps — is in [production.md](production.md).

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

@@ -61,14 +61,15 @@
  * WHICH TOOLS ARE OFFERED. `run_scenario`, always — unless the runner is
  * switched off (`bir off`), when nothing is: an inert runner adds nothing to
  * the model's context, and a call from a list taken before the switch starts
- * nothing and asks nobody. The reading tools come with `bir scenario editing on`
- * (or `BIR_SCENARIO_TOOLS=read` in this server's environment): their
- * definitions ride along with every request of every session, and only
- * somebody working on a scenario ever calls them. The tools that CHANGE a
- * scenario are offered only where a person ran `bir scenario editing on` (D2):
- * this server runs in every session of every installed project, a fleet
- * included, and a plan must not change because some agent there decided it
- * should. The switch is read when the host lists the tools, and again on every
+ * nothing and asks nobody. The rest come with scenario editing, which
+ * `bir setup` turns on (a person's `bir scenario editing off` is kept): the
+ * reading tools — also with `BIR_SCENARIO_TOOLS=read` in this server's
+ * environment — and the tools that CHANGE a scenario (D2). A project wired by
+ * a bare `bir install` (a fleet, say) offers `run_scenario` alone until a
+ * person runs `bir scenario editing on`: this server runs in every session
+ * there, each listed tool's definition rides along with every request, and a
+ * plan must not change because some agent there decided it should. The
+ * switch is read when the host lists the tools, and again on every
  * call, so a call to a tool that was never offered — or was offered before the
  * switch went off — is refused rather than run. Turning the runner off or on
  * mid-session tells the host its list changed (`notifications/tools/list_changed`).

package/dist/bin/bir-scenario.js

@@ -61,14 +61,15 @@
  * WHICH TOOLS ARE OFFERED. `run_scenario`, always — unless the runner is
  * switched off (`bir off`), when nothing is: an inert runner adds nothing to
  * the model's context, and a call from a list taken before the switch starts
- * nothing and asks nobody. The reading tools come with `bir scenario editing on`
- * (or `BIR_SCENARIO_TOOLS=read` in this server's environment): their
- * definitions ride along with every request of every session, and only
- * somebody working on a scenario ever calls them. The tools that CHANGE a
- * scenario are offered only where a person ran `bir scenario editing on` (D2):
- * this server runs in every session of every installed project, a fleet
- * included, and a plan must not change because some agent there decided it
- * should. The switch is read when the host lists the tools, and again on every
+ * nothing and asks nobody. The rest come with scenario editing, which
+ * `bir setup` turns on (a person's `bir scenario editing off` is kept): the
+ * reading tools — also with `BIR_SCENARIO_TOOLS=read` in this server's
+ * environment — and the tools that CHANGE a scenario (D2). A project wired by
+ * a bare `bir install` (a fleet, say) offers `run_scenario` alone until a
+ * person runs `bir scenario editing on`: this server runs in every session
+ * there, each listed tool's definition rides along with every request, and a
+ * plan must not change because some agent there decided it should. The
+ * switch is read when the host lists the tools, and again on every
  * call, so a call to a tool that was never offered — or was offered before the
  * switch went off — is refused rather than run. Turning the runner off or on
  * mid-session tells the host its list changed (`notifications/tools/list_changed`).

package/dist/bin/bir.js

@@ -46,14 +46,14 @@ import * as daemonApi from "../control/daemon.js";
 import { activeSessions, daemonStatus, ensureDaemon, probeHealth, readPortProblem, stopDaemon, } from "../control/daemon.js";
 import { configDir, controlDir, controlKey, discoveryPath, installedPath, normalizePath } from "../control/paths.js";
 import { offFlagPath, offSource, projectOffFlagPath, setRunnerOff } from "../util/off-switch.js";
-import { allocateFreeProjectPort, backupIsCreation, backupOriginalText, configSha, envProxyHint, exemptLoopbackFromProxy, isNpxEntry, isScenarioServer, isWrapped, nodeFlagsToCarry, normaliseRecordKeys, npxHookInvocation, protectBackupText, recordKey, sameServerConfig, PACKAGE_NAME, projectRecord, readSidecar, redactSecrets, restoreSecrets, remoteWrapBlocker, scenarioEntry, setProjectRecord, settleReplaySwitch, sidecarKey, unwrapEntry, UPSTREAM_HEADERS_ENV, wrapEntry, writeSidecar, SCENARIO_SERVER_KEY, } from "../config/generate.js";
+import { allocateFreeProjectPort, backupIsCreation, backupOriginalText, configSha, envProxyHint, exemptLoopbackFromProxy, isNpxEntry, isScenarioServer, isWrapped, nodeFlagsToCarry, normaliseRecordKeys, npxHookInvocation, protectBackupText, recordKey, sameServerConfig, PACKAGE_NAME, projectRecord, readSidecar, redactSecrets, restoreSecrets, remoteWrapBlocker, scenarioEntry, editingEnabled, setProjectRecord, settleEditing, settleReplaySwitch, sidecarKey, unwrapEntry, UPSTREAM_HEADERS_ENV, wrapEntry, writeSidecar, SCENARIO_SERVER_KEY, } from "../config/generate.js";
 import { chooseNodePath } from "../config/node-path.js";
-import { managedMcpPolicyBlocker, mcpjsonApprovals } from "../config/mcp-approval.js";
+import { claudeUserSettingsPath, managedMcpPolicyBlocker, mcpjsonApprovals } from "../config/mcp-approval.js";
 import { checkOverrides, recordServerName } from "../config/overrides.js";
 import { awaitWithin, isUnhealthyStatus, serviceHealth, serviceTimeoutMs, timeoutSignal } from "../util/service-health.js";
 import { runSetup } from "./setup.js";
 import { claudeConfigHome, claudeProjectKey, claudeProjectRoot, isRemote, linkedWorktrees, parseJsonFile, projectKeyFor, projectKeysFor, projectScope, resolveServers, } from "../config/resolve.js";
-import { assertEditableJson, buildHooksBlock, claudeCodePaths, disableMcpjsonServers, enableMcpjsonServers, ENSURE_ARG, ensureGitExcludeLine, hasBirHooks, installHooks, isBirHook, LOCAL_SETTINGS_EXCLUDE, readTextOrNull, removeGitExclude, setLocalEntries, setServerEntry, sha256, uninstallHooks, } from "../config/adapters/claude-code.js";
+import { addAllowRules, allowRules, assertEditableJson, BIR_TOOLS_RULE, buildHooksBlock, claudeCodePaths, disableMcpjsonServers, enableMcpjsonServers, ENSURE_ARG, ensureGitExcludeLine, hasBirHooks, installHooks, isBirHook, LOCAL_SETTINGS_EXCLUDE, readTextOrNull, removeAllowRules, removeGitExclude, setLocalEntries, setServerEntry, sha256, uninstallHooks, } from "../config/adapters/claude-code.js";
 import { writeFileAtomic } from "../util/atomic-write.js";
 import { readGenericServers, setGenericServerEntry } from "../config/adapters/generic.js";
 import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, clearCredentials, deviceLogin, describeAuthService, legacyPasswordLogin, tokenLogin, normalizeAuthUrl, rememberAuthUrl, resolveAuthUrl, } from "../auth/client.js";
@@ -80,7 +80,8 @@ function usage(code = 0) {
     out(`bir ${VERSION} — a recording MCP proxy
 
 Commands:
-  setup       the one command: sign in, wire this project, start the recorder
+  setup       the one command: sign in, wire this project, start the recorder, and give
+              Claude Code every bir tool (run_scenario, investigate, scenario_*) with no prompt
   up          start the recorder for this project in the background (--restart: replace it)
   down        stop it (open sessions here then show a hook error until they restart;
               \`bir off --here\` is the quiet way to take it out of the way)
@@ -119,7 +120,8 @@ Commands:
                                     take back the newest edit (of step n, or parameter name);
                                     run it again to go one further back; undo an undo's id to redo
   scenario editing on|off|status    whether this project's bir MCP server offers the tools
-                                    that change a scenario (restart Claude Code after)
+                                    that read and change a scenario (restart Claude Code after);
+                                    \`bir setup\` turns it on, and an off stays off
   scenario replay <scnId> --prompt "…" [--dry]
   replay --scenario <scnId> --prompt "…" [--dry]
   replay status | on | off | allow <a,b> | allow all
@@ -770,6 +772,15 @@ async function installWriting(args, cwd, sidecar, plan) {
             ? "  - calculated replay is off here (--no-replay); `bir replay on` turns it on"
             : "  - calculated replay is off here: it was not asked for (`bir install --replay` adds it)");
     }
+    // EVERY `bir` TOOL, for `bir setup`: investigate and the scenario tools are
+    // offered as well as run_scenario (scenario editing on — an `off` a person
+    // stored stays off), and Claude Code runs them without asking (below, with
+    // the hooks). Only where `bir` is the scenario server: a `bir` server of the
+    // person's own gets neither.
+    const birToolsHere = args.birTools === true && scenarioServerHere(args, cwd);
+    if (birToolsHere && settleEditing(sidecar, cwd)) {
+        out("  + scenario editing on: the bir server offers investigate and the scenario tools too (`bir scenario editing off` takes them away)");
+    }
     // SessionStart starts the recorder itself when this directory has none
     // (control/ensure-hook.ts). Every invocation gets it — an npx one through
     // npx, once per session — because without it nothing starts the recorder,
@@ -814,9 +825,35 @@ async function installWriting(args, cwd, sidecar, plan) {
             // never asks about; an older install's pre-approval has nothing to approve.
             text = disableMcpjsonServers(paths.settingsLocal, [SCENARIO_SERVER_KEY]) ?? text;
         }
+        let allowLine;
+        if (args.birTools) {
+            // A prompt for a tool the person never named reads as the runner getting
+            // in the way, and under `claude -p` it is a refusal. `run_scenario` runs
+            // only a plan the recorder armed, the reading tools only read, and a
+            // change must reproduce the recording or be saved on purpose with a note
+            // (editSteps.md D3) — and `scenario_undo` takes it back.
+            const granted = projectRecord(sidecar, cwd)?.allowRules ?? [];
+            if (birToolsHere) {
+                const allowed = addAllowRules(paths.settingsLocal, [BIR_TOOLS_RULE]);
+                text = allowed.text;
+                if (allowed.added.length > 0) {
+                    setProjectRecord(sidecar, cwd, { port, allowRules: [...new Set([...granted, ...allowed.added])] });
+                    allowLine = `  + ${BIR_TOOLS_RULE} → permissions.allow in the same file (Claude Code runs the bir tools without asking)`;
+                }
+            }
+            else if (granted.length > 0) {
+                // `bir` here is not the scenario server any more: the rule an earlier
+                // setup added must not approve another server's tools by its name.
+                text = removeAllowRules(paths.settingsLocal, granted) ?? text;
+                setProjectRecord(sidecar, cwd, { port, allowRules: undefined });
+                allowLine = `  - ${granted.join(", ")} — taken out of permissions.allow there: \`${SCENARIO_SERVER_KEY}\` here is not the scenario server`;
+            }
+        }
         noteWritten(sidecar, paths.settingsLocal, text, claudeJson);
         sidecar.hookFiles = [...new Set([...(sidecar.hookFiles ?? []), paths.settingsLocal])];
         out(`  + hooks → ${paths.settingsLocal} (control server on ${controlUrl}; the recorder starts itself with each session${invocation === "npx" ? ", through npx" : ""})`);
+        if (allowLine)
+            out(allowLine);
         const exclude = ensureGitExcludeLine(cwd);
         if (exclude) {
             out(`  + ${LOCAL_SETTINGS_EXCLUDE} is listed in ${exclude.path}`);
@@ -1847,6 +1884,22 @@ function uninstallProject(cwd, sidecar, opts) {
             }
         }
     }
+    // 4b. The rule `bir setup` added so the `bir` server's tools run without a
+    // prompt: only the rules it added, and once that server is gone — so a `bir`
+    // server of the person's own never inherits it. `--replay` takes it too.
+    const projectRec = projectRecord(sidecar, cwd);
+    const granted = projectRec?.allowRules ?? [];
+    if (projectRec && granted.length > 0 && wanted(SCENARIO_SERVER_KEY) && !remaining.has(SCENARIO_SERVER_KEY)) {
+        try {
+            if (removeAllowRules(paths.settingsLocal, granted) !== undefined) {
+                out(`  ← ${granted.join(", ")} — taken out of ${paths.settingsLocal} (permissions.allow)`);
+            }
+            setProjectRecord(sidecar, cwd, { port: projectRec.port, allowRules: undefined });
+        }
+        catch (err) {
+            remaining.set(`allow:${normalizePath(paths.settingsLocal)}`, `${granted.join(", ")} in ${paths.settingsLocal} — ${errText(err)}`);
+        }
+    }
     // 5. Read it back: what would a session here spawn now — in this
     // environment, and in any other profile the install wrote to?
     const after = runnerLeftovers(cwd, sidecar, opts.configPath, otherClaude);
@@ -3163,6 +3216,18 @@ async function doctor(args) {
         notes.push("the bir scenario server starts via npx, which can take longer than the first tool call " +
             "of a turn — run `bir setup` (or `bir install --replay --global`) to pin it to the installed copy");
     }
+    // WHICH `bir` TOOLS A SESSION HERE IS GIVEN. `bir setup` offers every one and
+    // lets Claude Code run them without asking; said only when that is not so.
+    if (scenarioEntry && isScenarioServer(scenarioEntry.config)) {
+        if (!editingEnabled(sidecar, cwd)) {
+            notes.push("the bir MCP server offers run_scenario only: scenario editing is off here — `bir scenario editing on` " +
+                "adds investigate and the scenario tools (restart Claude Code after)");
+        }
+        else if (![claudeUserSettingsPath(), paths.settings, paths.settingsLocal].some((file) => allowRules(file).some((rule) => rule === BIR_TOOLS_RULE || rule === `${BIR_TOOLS_RULE}__*`))) {
+            notes.push("Claude Code asks before investigate and the scenario tools run here — `bir setup` allows every bir tool " +
+                `(${BIR_TOOLS_RULE} in ${paths.settingsLocal})`);
+        }
+    }
     // THE PORT. The hooks' own URLs are the ground truth — they are what every
     // hook posts to — checked against the recorder actually answering here. Not
     // the machine-wide "last port any install wrote", which named another
@@ -3761,6 +3826,7 @@ async function main() {
                     npx: false,
                     forceInvocation: invocation,
                     replay,
+                    birTools: true,
                     hooks: true,
                     servers: [],
                 }),

package/dist/bin/setup.d.ts

@@ -10,7 +10,11 @@
  *   2. the sign-in — a setup token from the console, a cached session, or the
  *      browser flow — stored the way `bir login` stores it;
  *   3. the project: MCP servers wrapped, hooks wired, the scenario server added
- *      and pre-approved (`bir install --global --replay`);
+ *      and pre-approved (`bir install --global --replay`) — and every one of
+ *      its tools with it: investigate and the scenario tools are offered as
+ *      well as run_scenario, and Claude Code runs them without asking (Eran,
+ *      2026-09-28: after setup, every `bir` tool works). A person's
+ *      `bir scenario editing off` is kept;
  *   4. the recorder, started in the background and from now on started by the
  *      SessionStart hook whenever it is missing;
  *   5. a summary that names the account, the servers, the recorder's log, and

package/dist/bin/setup.js

@@ -10,7 +10,11 @@
  *   2. the sign-in — a setup token from the console, a cached session, or the
  *      browser flow — stored the way `bir login` stores it;
  *   3. the project: MCP servers wrapped, hooks wired, the scenario server added
- *      and pre-approved (`bir install --global --replay`);
+ *      and pre-approved (`bir install --global --replay`) — and every one of
+ *      its tools with it: investigate and the scenario tools are offered as
+ *      well as run_scenario, and Claude Code runs them without asking (Eran,
+ *      2026-09-28: after setup, every `bir` tool works). A person's
+ *      `bir scenario editing off` is kept;
  *   4. the recorder, started in the background and from now on started by the
  *      SessionStart hook whenever it is missing;
  *   5. a summary that names the account, the servers, the recorder's log, and
@@ -35,8 +39,10 @@ import { pidAlive, readDiscovery } from "../control/discovery.js";
 import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, describeAuthService, deviceLogin, loadStoredConfig, normalizeAuthUrl, rememberAuthUrl, tokenLogin, } from "../auth/client.js";
 import { activeSessions, compareVersions, ensureDaemon, SETUP_TOKEN_ENV, stopDaemon, } from "../control/daemon.js";
 import { normalizePath } from "../control/paths.js";
-import { allocateReplacementPort, isScenarioServer, isWrapped, LOOPBACK_NO_PROXY, probeFreePort, proxyConfigured, projectRecord, readSidecar, SCENARIO_SERVER_KEY, setProjectRecord, writeSidecar, allocateFreeProjectPort, } from "../config/generate.js";
+import { allowRules, BIR_TOOLS_RULE, claudeCodePaths } from "../config/adapters/claude-code.js";
+import { allocateReplacementPort, editingEnabled, isScenarioServer, isWrapped, LOOPBACK_NO_PROXY, probeFreePort, proxyConfigured, projectRecord, readSidecar, SCENARIO_SERVER_KEY, setProjectRecord, writeSidecar, allocateFreeProjectPort, } from "../config/generate.js";
 import { resolveServers } from "../config/resolve.js";
+import { EDIT_TOOLS, READ_TOOLS } from "./scenario-edit.js";
 import { errText } from "../util/log.js";
 import { offSource } from "../util/off-switch.js";
 import { packageVersion } from "../util/version.js";
@@ -368,6 +374,14 @@ export async function runSetup(args, deps) {
     else {
         out(`  replay     on — direct execution allowed for: ${allow?.length ? allow.join(", ") : `all wrapped (narrow it with \`bir replay allow ${wrapped[0]}\`)`}`);
     }
+    // What the `bir` server gives a session here, and whether Claude Code asks
+    // before each call — both set by install for setup (bir.ts, installWriting).
+    if (resolveServers(project).some((s) => s.name === SCENARIO_SERVER_KEY && isScenarioServer(s.config))) {
+        const asks = !allowRules(claudeCodePaths(project).settingsLocal).includes(BIR_TOOLS_RULE);
+        out(editingEnabled(readSidecar(), project)
+            ? `  tools      ${["run_scenario", ...READ_TOOLS, ...EDIT_TOOLS].join(", ")} — ${asks ? "Claude Code asks before each" : "Claude Code runs them without asking, except a forced change"}`
+            : "  tools      run_scenario only — scenario editing is off here (`bir scenario editing on` adds investigate and the scenario tools)");
+    }
     if (ensured) {
         const { info, health: h } = ensured.status;
         const theirs = String(h.hooksVersion ?? info.version ?? "");

package/dist/config/adapters/claude-code.d.ts

@@ -77,6 +77,33 @@ export declare function removeGitExclude(dir: string, line?: string): string | u
 export declare function enableMcpjsonServers(settingsPath: string, names: string[]): string;
 /** Undo {@link enableMcpjsonServers} for `names`; drops the key when empty. */
 export declare function disableMcpjsonServers(settingsPath: string, names: string[]): string | undefined;
+/**
+ * The rule that lets Claude Code run the runner's own `bir` server's tools
+ * without asking. In Claude Code's permission syntax `mcp__<server>` matches
+ * every tool that server offers, so it also covers the tools `bir scenario
+ * editing on` brings, and any a later runner adds.
+ *
+ * `bir setup` writes it (bir.ts, installWriting), into the person's own
+ * `.claude/settings.local.json` only, and only where `bir` IS the runner's
+ * scenario server: the rule matches a server by name, and a server of the
+ * person's own that is called `bir` must keep its prompts.
+ */
+export declare const BIR_TOOLS_RULE = "mcp__bir";
+/** The `permissions.allow` rules in a settings file; none when it is missing or unreadable. */
+export declare function allowRules(settingsPath: string): string[];
+/**
+ * Add `rules` to `permissions.allow`, leaving every other rule and key alone.
+ * Returns the file's new text and the rules that were not there before — the
+ * only ones {@link removeAllowRules} may take out again. A `permissions` or
+ * `allow` of the wrong shape is left as it is (nothing added): it is the
+ * person's to fix, and Claude Code reads neither.
+ */
+export declare function addAllowRules(settingsPath: string, rules: string[]): {
+    text: string;
+    added: string[];
+};
+/** Undo {@link addAllowRules} for `rules`; drops `allow`, then `permissions`, when left empty. */
+export declare function removeAllowRules(settingsPath: string, rules: string[]): string | undefined;
 /** True when `settingsPath` holds any hook of ours. */
 export declare function hasBirHooks(settingsPath: string): boolean;
 /** Which file holds a given scope's `mcpServers` for this cwd. */

package/dist/config/adapters/claude-code.js

@@ -24,7 +24,7 @@ import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, parse as parsePath, resolve as resolvePath } from "node:path";
 import { writeFileAtomic } from "../../util/atomic-write.js";
-import { FIRST_PROJECT_PORT, PACKAGE_NAME } from "../generate.js";
+import { FIRST_PROJECT_PORT, PACKAGE_NAME, SCENARIO_SERVER_KEY } from "../generate.js";
 import { claudeJsonPath, parseJsonFile, parseJsonText, projectKeyFor, } from "../resolve.js";
 export function claudeCodePaths(cwd, claudeJsonOverride) {
     return {
@@ -176,6 +176,74 @@ export function disableMcpjsonServers(settingsPath, names) {
             fresh.enabledMcpjsonServers = kept;
     });
 }
+// ── permission rules ───────────────────────────────────────────────────────
+/**
+ * The rule that lets Claude Code run the runner's own `bir` server's tools
+ * without asking. In Claude Code's permission syntax `mcp__<server>` matches
+ * every tool that server offers, so it also covers the tools `bir scenario
+ * editing on` brings, and any a later runner adds.
+ *
+ * `bir setup` writes it (bir.ts, installWriting), into the person's own
+ * `.claude/settings.local.json` only, and only where `bir` IS the runner's
+ * scenario server: the rule matches a server by name, and a server of the
+ * person's own that is called `bir` must keep its prompts.
+ */
+export const BIR_TOOLS_RULE = `mcp__${SCENARIO_SERVER_KEY}`;
+/** The `permissions.allow` rules in a settings file; none when it is missing or unreadable. */
+export function allowRules(settingsPath) {
+    let parsed;
+    try {
+        parsed = parseJsonFile(settingsPath);
+    }
+    catch {
+        return [];
+    }
+    const allow = parsed?.permissions?.allow;
+    return Array.isArray(allow) ? allow.filter((r) => typeof r === "string") : [];
+}
+const plainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Add `rules` to `permissions.allow`, leaving every other rule and key alone.
+ * Returns the file's new text and the rules that were not there before — the
+ * only ones {@link removeAllowRules} may take out again. A `permissions` or
+ * `allow` of the wrong shape is left as it is (nothing added): it is the
+ * person's to fix, and Claude Code reads neither.
+ */
+export function addAllowRules(settingsPath, rules) {
+    let added = [];
+    const text = editJson(settingsPath, (parsed) => {
+        added = [];
+        if (parsed.permissions !== undefined && !plainObject(parsed.permissions))
+            return;
+        const permissions = { ...(parsed.permissions ?? {}) };
+        if (permissions.allow !== undefined && !Array.isArray(permissions.allow))
+            return;
+        const allow = [...(permissions.allow ?? [])];
+        added = rules.filter((rule) => !allow.includes(rule));
+        if (added.length === 0)
+            return;
+        permissions.allow = [...allow, ...added];
+        parsed.permissions = permissions;
+    });
+    return { text, added };
+}
+/** Undo {@link addAllowRules} for `rules`; drops `allow`, then `permissions`, when left empty. */
+export function removeAllowRules(settingsPath, rules) {
+    if (!allowRules(settingsPath).some((rule) => rules.includes(rule)))
+        return undefined;
+    return editJson(settingsPath, (parsed) => {
+        const permissions = parsed.permissions;
+        if (!plainObject(permissions) || !Array.isArray(permissions.allow))
+            return;
+        const kept = permissions.allow.filter((rule) => !(typeof rule === "string" && rules.includes(rule)));
+        if (kept.length > 0)
+            permissions.allow = kept;
+        else
+            delete permissions.allow;
+        if (Object.keys(permissions).length === 0)
+            delete parsed.permissions;
+    });
+}
 /** True when `settingsPath` holds any hook of ours. */
 export function hasBirHooks(settingsPath) {
     let parsed;

package/dist/config/generate.d.ts

@@ -455,12 +455,23 @@ export interface ProjectRecord {
      * environment: their definitions ride along with every request of every
      * session, and only somebody working on a scenario calls them.
      *
-     * Per project, and off by default, because the `bir` server runs in every
-     * session of every installed project — a fleet included — and a plan must
-     * not change because some agent there decided it should. The `bir scenario`
-     * commands ignore it: a person in a terminal is asked before each one.
+     * Per project. `bir setup` turns it on (Eran, 2026-09-28: setup leaves every
+     * `bir` tool offered and working), except where a person turned it off —
+     * that `false` is kept by every later setup (see {@link settleEditing}). A
+     * bare `bir install` leaves it as it is, so a fleet wired by hand keeps the
+     * old default: the `bir` server runs in every session of every installed
+     * project, and there a plan must not change because some agent decided it
+     * should. The `bir scenario` commands ignore it: a person in a terminal is
+     * asked before each one.
      */
     editing?: boolean;
+    /**
+     * The `permissions.allow` rules `bir setup` added to this project's
+     * `.claude/settings.local.json` so Claude Code runs the `bir` server's tools
+     * without asking (adapters/claude-code.ts, BIR_TOOLS_RULE). Uninstall takes
+     * out only these: a rule that was there before is the person's own.
+     */
+    allowRules?: string[];
     /**
      * Every `.claude.json` an install for this project wrote local-scope entries
      * to. Claude Code reads `$CLAUDE_CONFIG_DIR/.claude.json` when that is set,
@@ -588,6 +599,12 @@ export declare function editingEnabled(sidecar: InstalledSidecar, cwd: string):
  * inventing a record would invent a port the hooks do not use.
  */
 export declare function setEditing(sidecar: InstalledSidecar, cwd: string, on: boolean): ProjectRecord | undefined;
+/**
+ * `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 declare function settleEditing(sidecar: InstalledSidecar, cwd: string): boolean;
 /**
  * What an install or uninstall said about calculated replay:
  *

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
@@ -1026,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
 ```
 
@@ -1045,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`**, and **`step`** with `inputLogic`, `outputLogic`, `freeze`, `unfreeze`, `force` — or **`param`** with **`kind`**; `note`, `revision` | `bir scenario edit` |
-| `scenario_undo` | after `bir scenario editing on` | **`target`**, one of `edit`, `step` or `param`, `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
@@ -1174,8 +1180,9 @@ Parameter database: target → setting (revision 4). Undo: bir scenario undo scn
 | `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.4",
+  "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`. |