@basein/runner 0.3.3 → 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,19 @@ 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
+parameter is a *target* (a prompt must name it, or the plan is declined:
+`missing_target`) or a *setting* (its recorded value is used when a prompt
+names none). When the calculation made a database, a host or a working folder a
+target, the plan never runs. Make it a setting, with a note; a recalculation
+keeps the change ([the guide's §9.2](docs/calculatedReplayGuide.md)):
+
+```bash
+bir scenario edit  scn_… --param database --kind setting --note "why"   # use the recorded database when a prompt names none
+bir scenario undo  scn_… --param database                  # take that back
 ```
 
 ---
@@ -427,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`).
@@ -442,6 +443,31 @@ function note(args) {
         throw new BadArguments("`note` must be a string");
     return ["--note", value];
 }
+/** `--revision <n>`, the chainRevision a change was made against. */
+function revision(args) {
+    const value = args.revision;
+    if (value === undefined || value === null)
+        return [];
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        throw new BadArguments("`revision` must be a whole number from 1");
+    }
+    return ["--revision", String(value)];
+}
+const PARAM = {
+    type: "string",
+    description: "A parameter's name, as scenario_show lists it under `parameters` (for example `database`).",
+};
+/** A parameter's name: one argv element after `--param`, so it cannot read as a flag. */
+function param(args) {
+    const value = args.param;
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string" || value.length === 0 || value.length > 200 || /[\u0000-\u001f\u007f]/.test(value)) {
+        throw new BadArguments("`param` must be a parameter's name, as scenario_show lists it");
+    }
+    return value;
+}
+const given = (value) => value !== undefined && value !== null && value !== false;
 const SCENARIO_TOOLS = [
     {
         name: "scenario_show",
@@ -462,8 +488,8 @@ const SCENARIO_TOOLS = [
         name: "scenario_edits",
         changes: false,
         service: true,
-        description: "List a calculated scenario's hand edits, newest first: step, note, revision, and whether each was forced, " +
-            "undone or replaced by a recalculation.",
+        description: "List a calculated scenario's hand edits, newest first — step edits and parameter kind changes: step or " +
+            "parameter, note, revision, and whether each was forced, undone or replaced by a recalculation.",
         inputSchema: {
             type: "object",
             properties: { target: TARGET },
@@ -532,12 +558,24 @@ const SCENARIO_TOOLS = [
             "meanwhile is not overwritten. " +
             "`force` saves what the check refused and is only for a recording that was itself wrong — never a way past a " +
             "failing check. A save can be taken back with scenario_undo, which the service checks too: it refuses an undo " +
-            "that would break a later step, and a recalculation with --discard-edits replaces edits for good.",
+            "that would break a later step, and a recalculation with --discard-edits replaces edits for good. " +
+            "Instead of `step`, `param` with `kind` changes what a prompt must name: a target must be named or the plan is " +
+            "declined (missing_target); a setting uses its recorded value when a prompt names none — for a value that is the " +
+            "same every time, such as a database, a host or a working folder. Making one a setting needs `note`.",
         inputSchema: {
             type: "object",
             properties: {
                 target: TARGET,
                 step: STEP,
+                param: {
+                    ...PARAM,
+                    description: `${PARAM.description} Changes that parameter's kind (with \`kind\`) instead of a step. Not with \`step\`.`,
+                },
+                kind: {
+                    type: "string",
+                    enum: ["target", "setting"],
+                    description: "With `param`: target (a prompt must name it) or setting (its recorded value is used when a prompt names none; needs `note`).",
+                },
                 inputLogic: INPUT_LOGIC,
                 outputLogic: OUTPUT_LOGIC,
                 freeze: {
@@ -549,17 +587,34 @@ const SCENARIO_TOOLS = [
                     type: "boolean",
                     description: "Save although the check refused it. Needs `note`. Only when the recording itself was wrong.",
                 },
-                note: { type: "string", description: "Why the step is changed; kept in the history. Required with `force`." },
+                note: {
+                    type: "string",
+                    description: "Why the step (or the parameter's kind) is changed; kept in the history. Required with `force`, and to make a parameter a setting.",
+                },
                 revision: {
                     type: "integer",
                     minimum: 1,
                     description: "The chainRevision the change was made against — at the top of a scenario_show answer with `step`; the save is refused if the plan moved on.",
                 },
             },
-            required: ["target", "step"],
+            // `step`, or `param` with `kind`: which one is checked below, in words.
+            required: ["target"],
             additionalProperties: false,
         },
         plan: (a) => {
+            const name = param(a);
+            if (name !== undefined || given(a.kind)) {
+                // A parameter's kind (findoffer.md): nothing runs, so nothing of a step's belongs here.
+                if (name === undefined)
+                    throw new BadArguments("`kind` needs `param`: the parameter to change");
+                if (a.kind !== "target" && a.kind !== "setting")
+                    throw new BadArguments("`kind` must be target or setting");
+                for (const key of ["step", "inputLogic", "outputLogic", "freeze", "unfreeze", "force"]) {
+                    if (given(a[key]))
+                        throw new BadArguments(`\`param\` changes only a parameter's kind; \`${key}\` belongs to a step`);
+                }
+                return { argv: ["scenario", "edit", target(a), "--param", name, "--kind", a.kind, ...note(a), ...revision(a)] };
+            }
             if (a.freeze === true && a.unfreeze === true)
                 throw new BadArguments("`freeze` and `unfreeze` ask for opposite things");
             const argv = [
@@ -571,13 +626,7 @@ const SCENARIO_TOOLS = [
                 ...flag(a, "unfreeze", "--unfreeze"),
                 ...flag(a, "force", "--force"),
             ];
-            argv.push(...note(a));
-            if (a.revision !== undefined && a.revision !== null) {
-                if (typeof a.revision !== "number" || !Number.isInteger(a.revision) || a.revision < 1) {
-                    throw new BadArguments("`revision` must be a whole number from 1");
-                }
-                argv.push("--revision", String(a.revision));
-            }
+            argv.push(...note(a), ...revision(a));
             return { argv, inputLogic: logic(a, "inputLogic"), outputLogic: logic(a, "outputLogic") };
         },
     },
@@ -585,19 +634,27 @@ const SCENARIO_TOOLS = [
         name: "scenario_undo",
         changes: true,
         service: true,
-        description: "Take back a hand edit of a calculated scenario: its step goes back as it was before that edit. Without `edit`, " +
-            "the newest edit that can be undone (of `step`, when given); calling it again goes one further back. The service " +
-            "checks the undo like a save and refuses it when a later step or the final answer would break — `force` with a " +
-            "`note` undoes it anyway. To redo, undo the undo: pass its sedit_ id as `edit` (the answer names it).",
+        description: "Take back a hand edit of a calculated scenario: its step (or a parameter's kind) goes back as it was before that " +
+            "edit. Without `edit`, the newest edit that can be undone (of `step` or `param`, when given); calling it again goes " +
+            "one further back. The service checks a step's undo like a save and refuses it when a later step or the final " +
+            "answer would break — `force` with a `note` undoes it anyway. To redo, undo the undo: pass its id as `edit` (the " +
+            "answer names it).",
         inputSchema: {
             type: "object",
             properties: {
                 target: TARGET,
-                edit: { type: "string", description: "The sedit_ id to undo, as scenario_edits lists it. Not with `step`." },
+                edit: {
+                    type: "string",
+                    description: "The sedit_ or pedit_ id to undo, as scenario_edits lists it. Not with `step` or `param`.",
+                },
                 step: {
                     ...STEP,
                     description: "Undo the newest edit of this step (its stepIndex, as scenario_show prints it). Not with `edit`.",
                 },
+                param: {
+                    ...PARAM,
+                    description: `${PARAM.description} Undo the newest kind change of this parameter. Not with \`edit\` or \`step\`.`,
+                },
                 force: {
                     type: "boolean",
                     description: "Undo although the check refused it (a later step or the answer would break). Needs `note`.",
@@ -609,15 +666,21 @@ const SCENARIO_TOOLS = [
         },
         plan: (a) => {
             const argv = ["scenario", "undo", target(a)];
+            const name = param(a);
+            if (name !== undefined && (given(a.edit) || given(a.step))) {
+                throw new BadArguments("`edit`, `step` and `param` each pick what to undo; give one of them");
+            }
             if (a.edit !== undefined && a.edit !== null) {
-                if (typeof a.edit !== "string" || !/^sedit_[\w-]+$/.test(a.edit)) {
-                    throw new BadArguments("`edit` must be a sedit_… id");
+                if (typeof a.edit !== "string" || !/^(sedit|pedit)_[\w-]+$/.test(a.edit)) {
+                    throw new BadArguments("`edit` must be a sedit_… or pedit_… id");
                 }
                 if (a.step !== undefined && a.step !== null) {
                     throw new BadArguments("`edit` names one entry and `step` picks one; give one of them");
                 }
                 argv.push("--edit", a.edit);
             }
+            if (name !== undefined)
+                argv.push("--param", name);
             argv.push(...step(a, false), ...flag(a, "force", "--force"), ...note(a));
             return { argv };
         },

package/dist/bin/bir.d.ts

@@ -15,7 +15,8 @@
  *
  *   bir scenario list | show <runId|scnId> [--step <n>] | calc <runId|scnId> [--force [--discard-edits]]
  *   bir scenario check|edit <runId|scnId> --step <n> --input-logic <file|-> …   ← fix one step
- *   bir scenario edits | undo <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
+ *   bir scenario edit <runId|scnId> --param <name> --kind target|setting …      ← what a prompt must name
+ *   bir scenario edits | undo <runId|scnId> [--edit <id> | --step <n> | --param <name>] [--force --note "why"]
  *   bir scenario editing on|off|status   ← may this project's `bir` MCP server change a scenario?
  *   bir scenario replay <scnId> --prompt "…" [--dry]  |  bir replay status|on|off|allow …
  *   bir investigate [<id>] | list | executions

package/dist/bin/bir.js

@@ -15,7 +15,8 @@
  *
  *   bir scenario list | show <runId|scnId> [--step <n>] | calc <runId|scnId> [--force [--discard-edits]]
  *   bir scenario check|edit <runId|scnId> --step <n> --input-logic <file|-> …   ← fix one step
- *   bir scenario edits | undo <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
+ *   bir scenario edit <runId|scnId> --param <name> --kind target|setting …      ← what a prompt must name
+ *   bir scenario edits | undo <runId|scnId> [--edit <id> | --step <n> | --param <name>] [--force --note "why"]
  *   bir scenario editing on|off|status   ← may this project's `bir` MCP server change a scenario?
  *   bir scenario replay <scnId> --prompt "…" [--dry]  |  bir replay status|on|off|allow …
  *   bir investigate [<id>] | list | executions
@@ -45,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";
@@ -79,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)
@@ -109,12 +111,17 @@ Commands:
   scenario edit <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
                 [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>]
                                     the same check, and save the change if it passes
+  scenario edit <runId|scnId> --param <name> --kind target|setting [--note "why"]
+                                    a target must be named by the prompt or the plan is
+                                    declined; a setting uses its recorded value when the
+                                    prompt names none (needs --note)
   scenario edits <runId|scnId>      a scenario's hand edits, newest first
-  scenario undo <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
-                                    take back the newest edit (of step n); run it again to go
-                                    one further back; undo an undo's sedit_ id to redo
+  scenario undo <runId|scnId> [--edit <id> | --step <n> | --param <name>] [--force --note "why"]
+                                    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
@@ -156,7 +163,10 @@ Options:
   --unfreeze        scenario check|edit: ask to remove that mark; the check decides
   --note <text>     scenario edit|undo: why, kept in the history (required with --force)
   --revision <n>    scenario edit|undo: only if the plan is still at this chainRevision
-  --edit <id>       scenario undo: the sedit_ id to undo (default: the newest edit that can be)
+  --edit <id>       scenario undo: the sedit_ or pedit_ id to undo (default: the newest that can be)
+  --param <name>    scenario edit: the parameter whose kind changes · scenario undo: its newest change
+  --kind <kind>     scenario edit --param: target (a prompt must name it) or setting (its
+                    recorded value is used when a prompt names none; needs --note)
   --discard-edits   scenario calc --force: recalculate a plan with hand edits, replacing them
   --no-browser      login: print the link and code, open nothing (SSH, headless)
   --token <value>   login: redeem a one-time setup token from the console (no browser)
@@ -355,6 +365,18 @@ function parseArgs(argv) {
             case "--discard-edits":
                 args.discardEdits = true;
                 break;
+            case "--param":
+                // A value flag, like --note: the name is whatever follows, and
+                // scenario-edit.ts says what is wrong with it in words.
+                args.param = argv[++i];
+                if (!args.param)
+                    usage(2);
+                break;
+            case "--kind":
+                args.kind = argv[++i];
+                if (!args.kind)
+                    usage(2);
+                break;
             case "--here":
                 args.here = true;
                 break;
@@ -750,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,
@@ -794,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}`);
@@ -1827,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);
@@ -3143,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
@@ -3374,6 +3459,8 @@ async function scenarioCommand(args) {
             edit: args.edit,
             revision: args.revision,
             discardEdits: args.discardEdits,
+            param: args.param,
+            kind: args.kind,
         }, {
             cwd: process.cwd(),
             out,
@@ -3739,6 +3826,7 @@ async function main() {
                     npx: false,
                     forceInvocation: invocation,
                     replay,
+                    birTools: true,
                     hooks: true,
                     servers: [],
                 }),

package/dist/bin/investigate.js

@@ -191,8 +191,8 @@ export const DECLINES = {
         fix: "enable or recalculate that sub-task, or recalculate this scenario.",
     },
     missing_target: {
-        cause: "the prompt names a target the runner could not find where the recording had it.",
-        fix: "run from the recording's directory, or name the target as the recording did.",
+        cause: "the plan needs a target — a value a prompt must name, such as a file, a table or a region — and the prompt did not name it. A replay never takes a target from the recording.",
+        fix: 'name it in the prompt. If the value is the same every time — a database, a host, a working folder — it is a setting, not a target: `bir scenario edit <scnId> --param <name> --kind setting --note "why"` lets the runner use its recorded value when a prompt names none (`bir scenario show <scnId>` lists the parameters and their kinds).',
     },
     no_derive_key: {
         cause: "the scenario has parameters and the runner had no way to derive them: no service session and no ANTHROPIC_API_KEY.",
@@ -203,6 +203,22 @@ export const DECLINES = {
         fix: "recalculate the scenario.",
     },
 };
+/**
+ * The `missing_target` fix with what this turn knows put in: the scenario, and
+ * the target the gate named (`target database not found`). The code alone once
+ * sent a reader after a lookup that failed, when the prompt had simply not
+ * named the value.
+ */
+function missingTargetFix(fix, turn) {
+    let text = fix;
+    const scenarioId = turn.matched?.scenarioId ?? turn.plan?.scenarioId;
+    if (scenarioId)
+        text = text.replaceAll("<scnId>", scenarioId);
+    const name = /\btarget (\S+) not found/.exec(turn.decision?.why ?? "")?.[1];
+    if (name)
+        text = text.replaceAll("<name>", name);
+    return text;
+}
 export const LOW_SAVING_PCT = 0.3;
 const usd = (v) => `$${v.toFixed(4)}`;
 const pct = (v) => `${(v * 100).toFixed(1)}%`;
@@ -225,7 +241,7 @@ export function localFindings(turn) {
             severity: code === "not_ready" && !turn.matched.scenarioId ? "info" : "problem",
             title: `Matched ${turn.matched.runId} but declined to steer: ${turn.decision.why ?? code}.`,
             cause: known?.cause ?? "the runner's log line carries the reason text.",
-            fix: known?.fix ??
+            fix: (known && code === "missing_target" ? missingTargetFix(known.fix, turn) : known?.fix) ??
                 (turn.matched.scenarioId
                     ? "read the `replay.decision` line above."
                     : "the matched recording has no scenario yet — calculate it, or let the service pick it up after enough hits."),