@basein/runner 0.3.26 → 0.3.27

package/dist/bin/investigate.d.ts

@@ -102,6 +102,19 @@ export interface Turn {
         of?: string;
         reason?: string;
     };
+    /**
+     * The plan was retired before any step ran (`replay.vetoed`): the model
+     * changed something itself first, or its `run_scenario` never reached the
+     * runner. `code` from runners after 0.3.26; the reason text always.
+     */
+    vetoed?: {
+        why?: string;
+        code?: string;
+    };
+    /** A direct plan waited through a call that only reads (`replay.direct_waits`, B2 is11.md). */
+    waited?: {
+        tool?: string;
+    };
     /** `replay.*_failed`, `replay.arm_failed`, `replay.diverge`, `replay.handover` … */
     incidents: JournalEntry[];
     events: JournalEntry[];

package/dist/bin/investigate.js

@@ -164,6 +164,12 @@ export function turnsFromJournal(entries) {
             case "run.repeat":
                 turn.repeat = { runId: str(e.run), of: str(e.of), reason: str(e.reason) };
                 break;
+            case "replay.vetoed":
+                turn.vetoed ??= { why: str(e.why), code: str(e.code) };
+                break;
+            case "replay.direct_waits":
+                turn.waited ??= { tool: str(e.tool) };
+                break;
             case "run.finish":
                 turn.finishedAt = e.at;
                 turn.finish = {
@@ -340,6 +346,46 @@ function readingDecline(code, why) {
     }
     return undefined;
 }
+/**
+ * Why a plan that armed ran no step (`replay.vetoed`). The recording page
+ * once said "the runner did not say why" of such a turn, and guessed wrong
+ * (B2 is11.md): the runner had said, here, and only here.
+ */
+function vetoFinding(turn, v) {
+    const why = (v.why ?? "").replace(/ — the plan is retired without running any step$/, "");
+    const scenarioId = turn.plan?.scenarioId ?? turn.matched?.scenarioId ?? "<scnId>";
+    if (v.code === "run_refused" || (!v.code && /\brun_scenario (was called|failed|answered)\b/.test(why))) {
+        return {
+            code: "vetoed_run_refused",
+            severity: "info",
+            title: `The plan was not run: ${why}.`,
+            cause: "run_scenario was refused — by the person, or by a deny rule — or it failed before it reached the runner. Refused means refused: the plan ran no step, and the agent did the task.",
+            fix: "nothing, if it was refused on purpose. If it failed: `bir doctor` shows whether the bir server runs here, and `bir setup` lets Claude Code run it without asking.",
+            evidence: { code: v.code ?? null },
+        };
+    }
+    const tool = /\bfirst call (?:that may change something )?was (\S+), not run_scenario\b/.exec(why)?.[1];
+    if (!v.code) {
+        // Runners up to 0.3.26: any first call retired the plan, and no reason
+        // went with the report.
+        return {
+            code: "vetoed_first_call",
+            severity: "warn",
+            title: `The plan armed, and was not run: ${why}.`,
+            cause: "this runner retires a direct plan at the agent's first call that is not run_scenario, whatever it is — a file read included. A careful agent looks before it runs a plan that writes, the more so when the note names the recording's values where this request has others (another person, another date), and the replay is lost for it: the steps would have taken this request's values.",
+            fix: `update the runner when a version after 0.3.26 is out (\`bir update\`): it keeps the plan through calls that only read, and its note names this request's values in place of the recording's. \`bir scenario show ${scenarioId}\` shows which values the steps read from the request.`,
+            evidence: { tool: tool ?? null },
+        };
+    }
+    return {
+        code: "vetoed_changed_first",
+        severity: "warn",
+        title: `The plan armed, and was not run: ${why}.`,
+        cause: `the agent changed something itself (${tool ?? "a call"}) before it called run_scenario. Run after that, the plan could do the same work twice, so it ran no step and the agent did the task. Calls that only read before it would have kept the plan.`,
+        fix: `nothing is wrong with the plan. Why the agent went its own way is in its first lines of the turn; \`bir scenario show ${scenarioId}\` shows which values the steps read from the request.`,
+        evidence: { code: v.code, tool: tool ?? null },
+    };
+}
 export const LOW_SAVING_PCT = 0.3;
 const usd = (v) => `$${v.toFixed(4)}`;
 const pct = (v) => `${(v * 100).toFixed(1)}%`;
@@ -385,6 +431,17 @@ export function localFindings(turn) {
             fix: "Check the incidents below and `bir doctor`; the service section says whether the scenario is ready.",
         });
     }
+    if (turn.vetoed)
+        out.push(vetoFinding(turn, turn.vetoed));
+    else if (turn.waited) {
+        out.push({
+            code: "direct_waited",
+            severity: "info",
+            title: `The agent's first call only read (${turn.waited.tool ?? "a read"}), and the plan waited for run_scenario.`,
+            cause: "A call that only reads does not retire a direct plan: it ran as the agent wrote it, and the agent was told once that the plan was still ready.",
+            fix: "",
+        });
+    }
     if (turn.plan) {
         const coverage = turn.plan.coverage ?? [];
         const tools = turn.plan.tools ?? [];
@@ -419,10 +476,16 @@ export function localFindings(turn) {
             });
         }
         if (turn.plan.mode === "direct") {
+            const steps = turn.plan.steps ?? coverage.length;
+            // A plan that armed ran nothing when it was retired first, or the turn
+            // reported it not steered: "28 steps ran" of such a turn was false.
+            const ranNone = turn.vetoed !== undefined || turn.reported?.outcome === "not_steered";
             out.push({
                 code: "direct_mode",
                 severity: "info",
-                title: `The plan armed in direct mode: ${turn.plan.steps ?? coverage.length} steps ran on the proxies and the runner, no model in the loop.`,
+                title: ranNone
+                    ? `The plan armed in direct mode, ${steps} steps on the proxies and the runner, and none of them ran.`
+                    : `The plan armed in direct mode: ${steps} steps ran on the proxies and the runner, no model in the loop.`,
                 cause: "Every step is a wrapped MCP tool this session has a proxy for, or a built-in the runner runs itself.",
                 fix: "",
             });
@@ -814,7 +877,9 @@ export async function investigateCommand(args, deps) {
                 : t.decision?.verdict === "no-steer"
                     ? `declined ${t.decision.code ?? ""}`.trim()
                     : t.plan
-                        ? `${t.plan.mode} ${t.done?.outcome ?? t.reported?.outcome ?? "armed"}`
+                        ? `${t.plan.mode} ${t.done?.outcome ?? t.reported?.outcome ?? "armed"}${
+                        // Retired before any step ran: the reason, where the runner gave one.
+                        t.vetoed ? ` (${t.vetoed.code ?? "not run"})` : ""}`
                         : "matched";
             const p = savedPct(t);
             const saved = t.reported?.savedUsd != null ? `  saved ${usd(t.reported.savedUsd)}${p != null ? ` (${pct(p)})` : ""}` : "";

package/dist/control/server.d.ts

@@ -788,6 +788,13 @@ export declare class ControlServer {
      * whether the service took it (null while the send is on its way).
      */
     private readonly toolListsSent;
+    /**
+     * What each wrapped server says of its tools (MCP `annotations`), by the
+     * name the agent calls them: whether a call only looks, for a direct plan
+     * waiting through it (B2 is11.md). A server's word beats any guess from the
+     * name (replay/reads-only.ts). Kept from the lists proxies report.
+     */
+    private readonly toolHints;
     /**
      * `POST /proxy/tools` — a proxy's server listed its tools (`tools/list`;
      * the service's autocorrect.md AC12). Its names, descriptions, input
@@ -1139,8 +1146,11 @@ export declare class ControlServer {
     private hasDirectCall;
     /**
      * Retire `state` without running anything: the model's `run_scenario` was
-     * refused or failed. Books a baseline sample (`not_steered`) — the agent did
-     * the task — never a divergence.
+     * refused or failed, or the model changed something itself first. Books a
+     * baseline sample (`not_steered`) — the agent did the task — never a
+     * divergence. `code` goes with the report, so the recording page can say
+     * why the plan did not run (B2 is11.md: it said "the runner did not say
+     * why", and guessed wrong).
      */
     private vetoPlan;
     /**

package/dist/control/server.js

@@ -33,6 +33,7 @@ import { pidAlive } from "./discovery.js";
 import { pinCompatible } from "./pin-guard.js";
 import { agentDayOf, answerBeforePrompt, contextForToolUse, intentForToolUse, markTranscriptUsage, promptCount, recentToolResults, sessionTranscriptPath, settledLastAssistantText, settledTextAfterToolUse, settledTurnEnd, thinkingForToolUse, usageBetween, usageSince, } from "./transcript.js";
 import { isHousekeepingCall } from "../record/housekeeping.js";
+import { readsOnlyCall } from "../replay/reads-only.js";
 import { asSent, userText } from "../record/prompt-text.js";
 import { redact, redactText } from "../record/redact.js";
 import { DEFAULT_MAX_STRING_BYTES, serializeCapped, truncateString, truncateStrings, } from "../record/truncate.js";
@@ -458,6 +459,24 @@ const HEALTH_SESSIONS_MAX = 50;
 const HANDBACK_NOTE = "[BaseInstRunner calculated replay] The recorded sequence is no longer being supplied: carry on with the task yourself, choosing each tool call's arguments from what you have seen so far.";
 /** What the model hears once a direct plan it never asked to run is retired. */
 const DIRECT_SKIPPED_NOTE = "[BaseInstRunner calculated replay] The recorded scenario is not being run for this request: carry on with the task yourself.";
+/**
+ * What the model hears, once, after its first call that only looks while a
+ * direct plan waits for `run_scenario` (B2 is11.md): the call did not cancel
+ * the plan, the steps take this request's values — named, where the reading
+ * named them — and a change made first would. In is11 the model had checked
+ * its notes because the note named the recording's person.
+ */
+function directWaitingNote(values) {
+    return [
+        "[BaseInstRunner calculated replay] The recorded sequence is still ready for this request:",
+        "a call that only reads does not cancel it.",
+        values
+            ? `Its steps take this request's values, not the recording's: ${values}.`
+            : "Its steps take this request's values, not the recording's.",
+        "Call mcp__bir__run_scenario next, before any call that changes something:",
+        "after a change of your own it is not run.",
+    ].join("\n");
+}
 /** What a second `run_scenario` for a plan that is already running is told. */
 const ALREADY_RUNNING = "this scenario is already running for this turn — its results come back on the first run_scenario call; do not call it again or repeat its steps";
 /** Request bodies past this are read and discarded, never buffered. */
@@ -2511,6 +2530,13 @@ export class ControlServer {
      * whether the service took it (null while the send is on its way).
      */
     toolListsSent = new Map();
+    /**
+     * What each wrapped server says of its tools (MCP `annotations`), by the
+     * name the agent calls them: whether a call only looks, for a direct plan
+     * waiting through it (B2 is11.md). A server's word beats any guess from the
+     * name (replay/reads-only.ts). Kept from the lists proxies report.
+     */
+    toolHints = new Map();
     /**
      * `POST /proxy/tools` — a proxy's server listed its tools (`tools/list`;
      * the service's autocorrect.md AC12). Its names, descriptions, input
@@ -2530,12 +2556,26 @@ export class ControlServer {
         if (this.isSessionOff(boundTo))
             return { ok: true, off: true };
         const serverName = typeof body.serverName === "string" ? body.serverName.trim().slice(0, 200) : "";
-        if (!serverName || !Array.isArray(body.tools) || !isToolListReporter(this.recorder))
+        if (!serverName || !Array.isArray(body.tools))
             return { ok: true };
         const tools = toolListForService(serverName, body.tools);
         // A server still starting may list nothing: that replaces no list.
         if (tools.length === 0)
             return { ok: true };
+        for (const t of tools) {
+            if (t.annotations)
+                this.toolHints.set(t.qualifiedName, t.annotations);
+            else
+                this.toolHints.delete(t.qualifiedName);
+        }
+        while (this.toolHints.size > 4_096) {
+            const oldest = this.toolHints.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.toolHints.delete(oldest);
+        }
+        if (!isToolListReporter(this.recorder))
+            return { ok: true };
         const project = this.projectKeyHere();
         const key = `${accountOf(this.recorder) ?? ""}\u0000${project}\u0000${serverName}`;
         const hash = createHash("sha256").update(JSON.stringify(tools)).digest("hex");
@@ -3837,6 +3877,8 @@ export class ControlServer {
         const live = this.livePlan(run);
         /** `run_scenario` for this session's own announced direct plan: allowed, see below. */
         let allowDirect = false;
+        /** A call that only looks, which a direct plan waits through (B2 is11.md): it runs as written. */
+        let waitedRead = false;
         if (this.replay.isDirectTool(toolName)) {
             // `run_scenario` with no live plan does nothing but answer "no scenario
             // is armed". Recorded, that answer is a failed tool call, and a recording
@@ -3865,19 +3907,43 @@ export class ControlServer {
             // refused (the user said no, or a rule denied it) or it failed on the way.
             // Refused means refused. The plan retires without running anything — it
             // must not come back as a divergence that runs every step unattended.
-            this.vetoPlan(run, live, "run_scenario was called but never reached the runner — refused or failed");
+            this.vetoPlan(run, live, "run_scenario was called but never reached the runner — refused or failed", "run_refused");
         }
         else if (live?.mode === "direct" && !live.directRequested && !live.running && !this.runningPlans.has(live)) {
-            // A direct plan whose first call is not `run_scenario`, and which never
-            // asked for it. The likeliest reason is that the model has no such tool
-            // — the bir server failed to start, was disabled in /mcp, or lists
-            // nothing — and a divergence would then execute every step, writes
-            // included, inside this hook with no permission prompt, and deny the
+            // A direct plan whose next call is not `run_scenario`, and which never
+            // asked for it. Nothing of the plan ever runs in this hook in its place:
+            // when the model has no such tool — the bir server failed to start, was
+            // disabled in /mcp, or lists nothing — a divergence would execute every
+            // step, writes included, with no permission prompt, and deny the
             // model's call: a broken delivery tool turned into an unattended run.
-            // The plan retires running nothing; this call runs as written, and the
-            // model hears on its PostToolUse that the task is its own.
-            this.vetoPlan(run, live, `the model's first call was ${toolName}, not run_scenario`);
-            run.handback = DIRECT_SKIPPED_NOTE;
+            //
+            // A call that only looks does not retire the plan (B2 is11.md): it runs
+            // as written, and the plan waits for `run_scenario`, told to the model
+            // once on this call's PostToolUse. In is11 the model checked its own
+            // notes first, because the note named the recording's person, and
+            // losing the plan there cost a whole agent run for a value the steps
+            // take from the request anyway. The first call that may change
+            // something retires it, running nothing: run after the model's own
+            // change, the plan could do the same work twice. That call runs as
+            // written, and the model hears on its PostToolUse that the task is its
+            // own.
+            if (readsOnlyCall(toolName, modelArgs, this.toolHints.get(toolName))) {
+                waitedRead = true;
+                live.readsWaited = (live.readsWaited ?? 0) + 1;
+                if (live.readsWaited === 1) {
+                    run.handback = directWaitingNote(live.plan?.requestValues());
+                    logLine("replay.direct_waits", {
+                        run: run.runId,
+                        scenario: live.scenarioId ?? undefined,
+                        tool: toolName,
+                        why: "the model's first call only reads — it runs as written, and the plan waits for run_scenario",
+                    });
+                }
+            }
+            else {
+                this.vetoPlan(run, live, `the model's first call that may change something was ${toolName}, not run_scenario${live.readsWaited ? ` (after ${live.readsWaited} that only read)` : ""}`, "changed_first");
+                run.handback = DIRECT_SKIPPED_NOTE;
+            }
         }
         const agentId = payload.agent_id ?? session.agentId;
         // The real intent, read from every line sharing this message's id
@@ -3928,6 +3994,7 @@ export class ControlServer {
             });
             const action = await this.replay.preTool(steering, toolName, toolUseId, modelArgs, {
                 signal: answeredLate.signal,
+                readsOnly: waitedRead && steering === live,
             });
             if (overran) {
                 // The host already has its answer. A divergence was answered with its
@@ -4469,20 +4536,28 @@ export class ControlServer {
     }
     /**
      * Retire `state` without running anything: the model's `run_scenario` was
-     * refused or failed. Books a baseline sample (`not_steered`) — the agent did
-     * the task — never a divergence.
+     * refused or failed, or the model changed something itself first. Books a
+     * baseline sample (`not_steered`) — the agent did the task — never a
+     * divergence. `code` goes with the report, so the recording page can say
+     * why the plan did not run (B2 is11.md: it said "the runner did not say
+     * why", and guessed wrong).
      */
-    vetoPlan(run, state, why) {
+    vetoPlan(run, state, why, code) {
         if (state.retired)
             return;
         state.retired = true;
         state.retiredAt = Date.now();
         state.pinned.clear();
         state.skipNote = undefined;
+        // A continuation has a reason of its own for this, `not_taken`, which the
+        // page words for a plan that follows a hand-over (restoreParkedFragment).
+        if (code && !state.declined && !state.continuation)
+            state.declined = code;
         this.directCalls = this.directCalls.filter((c) => c.state !== state);
         logLine("replay.vetoed", {
             run: run.runId,
             scenario: state.scenarioId ?? undefined,
+            code,
             why: `${why} — the plan is retired without running any step`,
         });
     }
@@ -5643,7 +5718,7 @@ export class ControlServer {
                 if (!this.runningPlans.has(waiting.state)) {
                     this.vetoPlan(waiting.run, waiting.state, failed
                         ? "run_scenario failed before it reached the runner"
-                        : "run_scenario answered without ever reaching the runner");
+                        : "run_scenario answered without ever reaching the runner", "run_refused");
                 }
             }
         }

package/dist/replay/controller.d.ts

@@ -92,6 +92,13 @@ export interface PreToolOptions {
      * route's deadline guard spoke first. No further step is started.
      */
     signal?: AbortSignal;
+    /**
+     * The call only looks and changes nothing (replay/reads-only.ts), as the
+     * control server judged it with what the tool's server says of it. A direct
+     * plan the model has not asked for yet lets such a call through and waits
+     * for `run_scenario` (B2 is11.md); nothing runs in its place.
+     */
+    readsOnly?: boolean;
 }
 /**
  * What the caller knows about how a pinned call ended, beyond its error text
@@ -514,6 +521,12 @@ export interface ReplayState {
     running?: Promise<RunArmedResult>;
     /** The model called `run_scenario` for this plan (its `PreToolUse` was seen). */
     directRequested?: boolean;
+    /**
+     * Calls that only look, made while this direct plan waited for
+     * `run_scenario` (B2 is11.md): each ran as the model wrote it, and the plan
+     * stayed announced. The first is told the plan still waits, once.
+     */
+    readsWaited?: number;
     /**
      * The direct run's caller went away mid-run — Esc on `run_scenario`, or its
      * client timing out. The turn it cut short is no measurement of the task, so
@@ -677,7 +690,23 @@ export type DeclineCode = "replay_disabled" | "not_ready" | "known_bad_first_ste
  * failed on this request, so none of its steps could be computed. Set by
  * the control server.
  */
- | "params_failed";
+ | "params_failed"
+/**
+ * A direct plan announced to the model, which made a call that may change
+ * something before it called `run_scenario`: the plan retired running
+ * nothing, because run after the model's own change it could do the same
+ * work twice. Calls that only look before it do not count (B2 is11.md).
+ * Set by the control server (runners after 0.3.26; up to it, such a plan
+ * was retired at any first call, and reported no reason).
+ */
+ | "changed_first"
+/**
+ * A direct plan whose `run_scenario` call never reached the runner: the
+ * person refused it, a rule denied it, or it failed on the way. Refused
+ * means refused: the plan retired running nothing. Set by the control
+ * server (runners after 0.3.26; up to it, reported with no reason).
+ */
+ | "run_refused";
 /**
  * What a continuation continues (the service's fallbk.md Part 3): the plan
  * that handed over, the step it stopped in front of, and the recording of the

package/dist/replay/controller.js

@@ -700,21 +700,24 @@ export class ReplayController {
             stopAt,
             subTask: isSubTask(state),
         });
-        if (mode === "steer") {
-            // A steer directive shows the arguments the steps will run with, so the
-            // call the model writes is one the pin guard accepts (plan.ts,
-            // `steeringDirective`). That needs the parameters settled — which costs
-            // nothing when the derivation has already answered: gate 7 waited for
-            // it, or there was nothing to derive. One turn of the loop lets an answer
-            // that is already in hand through; one still on its way is not waited
-            // for here, and the directive simply leaves the arguments to the system,
-            // as it always did. A `paramsLogic` that throws is not judged here: the
-            // first call that needs the parameters meets the same failure, as before.
-            if (!deriveAnswered)
-                await new Promise((resolve) => setImmediate(resolve));
-            if (deriveAnswered)
-                await state.plan.ready().catch(() => undefined);
-        }
+        // A steer directive shows the arguments the steps will run with, so the
+        // call the model writes is one the pin guard accepts (plan.ts,
+        // `steeringDirective`). A direct one says which of this request's values
+        // the steps take, and puts this request's values where the recording's
+        // stand in its intent (B2 is11.md): "set Olga up" under a request for
+        // Carlos made a careful model check first, and that check retired the
+        // plan. Both need the parameters settled — which costs nothing when the
+        // derivation has already answered: gate 7 waited for it, or there was
+        // nothing to derive. One turn of the loop lets an answer that is already
+        // in hand through; one still on its way is not waited for here, and the
+        // directive leaves the values out (a direct one names each recorded value
+        // by its role instead). A `paramsLogic` that throws is not judged here:
+        // the first call that needs the parameters meets the same failure, as
+        // before.
+        if (!deriveAnswered)
+            await new Promise((resolve) => setImmediate(resolve));
+        if (deriveAnswered)
+            await state.plan.ready().catch(() => undefined);
         state.mode = mode;
         state.stepsPlanned = steps.length;
         // The chain this plan was served at: what its own calls are marked with
@@ -1055,6 +1058,16 @@ export class ReplayController {
             });
             return { kind: "passthrough" };
         }
+        // A CALL THAT ONLY LOOKS DOES NOT END A DIRECT PLAN (B2 is11.md). Asked
+        // for `run_scenario` first, the model looked at something first instead —
+        // in is11 its own notes, after the note had named another request's
+        // person. Read as a divergence, this call would run every step here,
+        // unattended; read as the model leaving the plan, it retired a plan that
+        // would have done the task right. It is neither: it runs as written,
+        // nothing runs in its place, and the plan waits for `run_scenario`. The
+        // control server retires it at the first call that may change something.
+        if (state.mode === "direct" && hook.readsOnly === true)
+            return { kind: "passthrough" };
         // Everything below — the wait for the parameters, and a divergence that
         // executes the rest of the plan — happens inside this one hook, which the
         // host waits on for a bounded time. One deadline covers all of it — and

package/dist/replay/plan.d.ts

@@ -514,6 +514,47 @@ export declare class ScenarioReplayPlan {
      * body gets at most `bodyMs` ({@link PREVIEW_LOGIC_MS}) of it.
      */
     private previewArguments;
+    /**
+     * This request's value of `key`, as a directive may show it, or undefined
+     * (B2 is11.md): once the reading has settled, a plain value the reading
+     * took from the request — never a mark, and never a value a step works out
+     * (`from: "step"`): before the run nobody has that one, and the recorded one
+     * is another request's (issue 1212).
+     */
+    private shownValueOf;
+    /**
+     * A text written from the recording — the intent, a step's reasoning — put
+     * right for this request, for a directive to show (B2 is11.md).
+     *
+     * Both name the recording's values: "set Olga up", "moves each lead to
+     * Olga". Shown beside a request for Carlos, the name tells the model the
+     * plan is for someone else. A careful model then checks before it runs
+     * anything, and a direct plan's first call that was not `run_scenario`
+     * retired it — so the replay was lost on exactly the turn replay is for: the
+     * same task with a new value. The steps never read the text: they take
+     * Carlos from the request.
+     *
+     * Each recorded value of a parameter found in the text, as a whole word, is
+     * replaced by this request's own value where the plan has one it may show
+     * ({@link shownValueOf}), and else by the parameter's role (`<assignee
+     * name>`): a target the request did not name, a value a step works out, or
+     * any value while the reading has not settled. A value the same as the
+     * recorded one stays as it is. One pass, longest value first, so nothing put
+     * in is replaced again.
+     */
+    forThisRequest(text: string): string;
+    /** {@link forThisRequest} as one function, built once for a directive's many texts. */
+    private rewriter;
+    /**
+     * This request's own values, for the direct directive's line that says the
+     * steps take them (B2 is11.md): what the reading took from the request.
+     * The values the request names in words come first — a name, a title: what
+     * a reader holds the note against — those unlike the recording's first;
+     * then the values worked out from the day ("tomorrow" as a date). Targets
+     * only: never a setting, never a value a step works out, never a mark.
+     * Undefined until the reading has settled, or when it named none.
+     */
+    requestValues(): string | undefined;
     /**
      * The directive injected via `UserPromptSubmit`'s `additionalContext`.
      *

package/dist/replay/plan.js

@@ -132,6 +132,47 @@ function clipReasoning(reasoning) {
     const first = (reasoning ?? "").trim().split(/\r?\n/, 1)[0]?.trim() ?? "";
     return first.length > MAX_REASONING_CHARS ? `${first.slice(0, MAX_REASONING_CHARS)}…` : first;
 }
+// ── the recording's values in a directive's text (B2 is11.md) ────────────────
+/**
+ * A recorded value as a text may name it: a string or a number at least this
+ * long — a one-character sample ("5", "a") is found in too many words — and
+ * no longer than a name or a title is.
+ */
+const RECORDED_VALUE_MIN = 2;
+const RECORDED_VALUE_MAX = 200;
+/** One of this request's values, as a directive shows it: this long at most. */
+const SHOWN_VALUE_MAX = 60;
+/** This many of this request's values at most on a direct directive's values line… */
+const SHOWN_VALUES = 4;
+/** …and this long at most, all of them. */
+const SHOWN_VALUES_CHARS = 200;
+/** The recorded value `value` as a text may name it, or undefined. */
+function recordedText(value) {
+    const text = typeof value === "number" && Number.isFinite(value)
+        ? String(value)
+        : typeof value === "string"
+            ? value.trim()
+            : undefined;
+    return text !== undefined && text.length >= RECORDED_VALUE_MIN && text.length <= RECORDED_VALUE_MAX ? text : undefined;
+}
+/** A value of this request's as plain text — never a mark — or undefined. */
+function valueText(value) {
+    let text;
+    if (typeof value === "boolean")
+        text = String(value);
+    else if (typeof value === "number" && Number.isFinite(value))
+        text = String(value);
+    else if (typeof value === "string")
+        text = value.replace(/\s+/g, " ").trim();
+    if (!text || markedKey(text) !== undefined)
+        return undefined;
+    return text;
+}
+const clipValue = (text) => text.length > SHOWN_VALUE_MAX ? `${text.slice(0, SHOWN_VALUE_MAX)}…` : text;
+const sameText = (a, b) => a.toLowerCase() === b.toLowerCase();
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** A parameter's role, for a value a text must not name: `assignee_name` → `<assignee name>`. */
+const roleOf = (key) => `<${key.replace(/[_-]+/g, " ").trim() || key}>`;
 /** A step's computed arguments, as a steer directive shows them: this long at most. */
 const MAX_DIRECTIVE_ARGS_CHARS = 240;
 /**
@@ -854,6 +895,120 @@ export class ScenarioReplayPlan {
         }
         return out;
     }
+    /**
+     * This request's value of `key`, as a directive may show it, or undefined
+     * (B2 is11.md): once the reading has settled, a plain value the reading
+     * took from the request — never a mark, and never a value a step works out
+     * (`from: "step"`): before the run nobody has that one, and the recorded one
+     * is another request's (issue 1212).
+     */
+    shownValueOf(key, p) {
+        if (!this.paramsSettled || p?.from === "step")
+            return undefined;
+        return valueText(this.derivedParams[key]);
+    }
+    /**
+     * A text written from the recording — the intent, a step's reasoning — put
+     * right for this request, for a directive to show (B2 is11.md).
+     *
+     * Both name the recording's values: "set Olga up", "moves each lead to
+     * Olga". Shown beside a request for Carlos, the name tells the model the
+     * plan is for someone else. A careful model then checks before it runs
+     * anything, and a direct plan's first call that was not `run_scenario`
+     * retired it — so the replay was lost on exactly the turn replay is for: the
+     * same task with a new value. The steps never read the text: they take
+     * Carlos from the request.
+     *
+     * Each recorded value of a parameter found in the text, as a whole word, is
+     * replaced by this request's own value where the plan has one it may show
+     * ({@link shownValueOf}), and else by the parameter's role (`<assignee
+     * name>`): a target the request did not name, a value a step works out, or
+     * any value while the reading has not settled. A value the same as the
+     * recorded one stays as it is. One pass, longest value first, so nothing put
+     * in is replaced again.
+     */
+    forThisRequest(text) {
+        return this.rewriter()(text);
+    }
+    /** {@link forThisRequest} as one function, built once for a directive's many texts. */
+    rewriter() {
+        const schema = this.scenario.paramsObject;
+        if (!schema || typeof schema !== "object")
+            return (text) => text;
+        /** Recorded value (lower case) → what goes in its place; null where it stays. */
+        const swaps = new Map();
+        for (const [key, p] of Object.entries(schema)) {
+            const recorded = recordedText(p?.sampleValue);
+            if (!recorded)
+                continue;
+            const now = this.shownValueOf(key, p);
+            const swap = now !== undefined && sameText(now, recorded) ? null : now !== undefined ? clipValue(now) : roleOf(key);
+            const k = recorded.toLowerCase();
+            // Two parameters recorded with one value: a change wins over "stays".
+            if (!swaps.has(k) || swaps.get(k) === null)
+                swaps.set(k, swap);
+        }
+        const found = [...swaps.entries()].filter(([, swap]) => swap !== null).map(([k]) => k);
+        if (found.length === 0)
+            return (text) => text;
+        found.sort((a, b) => b.length - a.length);
+        let pattern;
+        try {
+            pattern = new RegExp(`(?<![\\p{L}\\p{N}_])(?:${found.map(escapeRegExp).join("|")})(?![\\p{L}\\p{N}_])`, "giu");
+        }
+        catch {
+            return (text) => text;
+        }
+        return (text) => (text ? text.replace(pattern, (m) => swaps.get(m.toLowerCase()) ?? m) : text);
+    }
+    /**
+     * This request's own values, for the direct directive's line that says the
+     * steps take them (B2 is11.md): what the reading took from the request.
+     * The values the request names in words come first — a name, a title: what
+     * a reader holds the note against — those unlike the recording's first;
+     * then the values worked out from the day ("tomorrow" as a date). Targets
+     * only: never a setting, never a value a step works out, never a mark.
+     * Undefined until the reading has settled, or when it named none.
+     */
+    requestValues() {
+        if (!this.paramsSettled)
+            return undefined;
+        const schema = this.scenario.paramsObject;
+        if (!schema || typeof schema !== "object")
+            return undefined;
+        const items = [];
+        let order = 0;
+        for (const [key, p] of Object.entries(schema)) {
+            order += 1;
+            if (p?.kind === "setting")
+                continue;
+            const now = this.shownValueOf(key, p);
+            if (now === undefined)
+                continue;
+            const recorded = recordedText(p?.sampleValue);
+            items.push({
+                key,
+                text: clipValue(now),
+                // Named in the request's own words; an older service sends no `from`.
+                said: p?.from === undefined || p.from === "prompt",
+                differs: recorded !== undefined && !sameText(now, recorded),
+                order,
+            });
+        }
+        items.sort((a, b) => Number(b.said) - Number(a.said) || Number(b.differs) - Number(a.differs) || a.order - b.order);
+        const parts = [];
+        let chars = 0;
+        for (const item of items) {
+            if (parts.length >= SHOWN_VALUES)
+                break;
+            const part = `${item.key} ${JSON.stringify(item.text)}`;
+            if (parts.length > 0 && chars + part.length > SHOWN_VALUES_CHARS)
+                break;
+            parts.push(part);
+            chars += part.length + 2;
+        }
+        return parts.length > 0 ? parts.join(", ") : undefined;
+    }
     /**
      * The directive injected via `UserPromptSubmit`'s `additionalContext`.
      *
@@ -880,9 +1035,14 @@ export class ScenarioReplayPlan {
         // A sub-task plan (armed mid-task) never tells the agent to stop calling
         // tools: the steps below are a part of the task it is already doing.
         const subTask = opts?.subTask ?? this.subTask;
+        // The intent and each step's reasoning were written from the recording,
+        // so they name its values ("set Olga up"); shown here, they say this
+        // request's — or the value's role — never another request's (B2 is11.md).
+        const fix = this.rewriter();
         // The intent is a paragraph the analyser wrote; it is context, not an
         // instruction, so it is clipped rather than dumped whole into the prompt.
-        const intent = this.intent.length > 240 ? `${this.intent.slice(0, 240)}…` : this.intent;
+        const written = fix(this.intent);
+        const intent = written.length > 240 ? `${written.slice(0, 240)}…` : written;
         if (this.mode === "direct") {
             // The steps are not listed. The model does not call them, and what the
             // tool returns names every call and says whether the run was whole or
@@ -890,9 +1050,17 @@ export class ScenarioReplayPlan {
             // cost the agent up to 2,000 characters in the first call of every turn
             // a plan was armed for (docs/calculatedReplay.md, "How a bundle reads"),
             // and the tool's result shows an operator watching the session what ran.
+            //
+            // One line says where the steps' values come from, with this request's
+            // own: a model that met another request's value in the note used to
+            // stop to check, and its check retired the plan (B2 is11.md).
+            const values = this.requestValues();
             return [
                 "[BaseInstRunner calculated replay] A known-good tool sequence was recorded",
-                `for this request${intent ? ` (intent: ${intent})` : ""}.`,
+                `for a request like this one${intent ? ` (intent: ${intent})` : ""}.`,
+                values
+                    ? `Its steps take this request's values, not the recording's: ${values}.`
+                    : "Its steps take this request's values, not the recording's.",
                 "",
                 `Call ${directToolName} once, with no arguments, before any other tool. It runs the`,
                 "sequence and returns what each call did.",
@@ -924,7 +1092,7 @@ export class ScenarioReplayPlan {
             return ` (only when ${t.text ?? "this request needs it"})`;
         };
         const listing = (withWhy, argsBefore) => planned.map((s, i) => {
-            const why = withWhy ? clipReasoning(s.reasoning) : "";
+            const why = withWhy ? clipReasoning(fix(s.reasoning ?? "")) : "";
             const head = `  ${i + 1}. ${s.toolName}${onlyWhen(i)}${why ? ` — ${why}` : ""}`;
             const shown = i < argsBefore ? args[i] : undefined;
             return shown ? `${head}\n     ${shown}` : head;

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

@@ -0,0 +1,48 @@
+/**
+ * reads-only — whether one call of the agent's only looks, and changes nothing.
+ *
+ * WHY THE RUNNER ASKS (B2 is11.md, 2026-11-11). A direct plan is announced
+ * with "call run_scenario before any other tool", and a first call that is
+ * not `run_scenario` used to retire it on the spot (control/server.ts). The
+ * rule is there for one danger: a model that has no `run_scenario` makes its
+ * own calls, and a divergence would then run every step, writes included,
+ * inside a hook nobody approves. But the call that retired the plan in is11
+ * was the agent reading its own notes file: it had seen another person's name
+ * in the note (Olga, the recording's; the request said Carlos) and checked
+ * first. The plan would have done the task right — its steps take the person
+ * from the request — and the turn cost a full agent run.
+ *
+ * So a call that only looks no longer retires a direct plan: it runs as the
+ * agent wrote it, and the plan waits, still announced, for `run_scenario`.
+ * The first call that may change something still retires it, running nothing
+ * (and nothing ever runs in a hook in its place): a plan run after the agent
+ * changed something itself could do the same work twice.
+ *
+ * WHEN IN DOUBT, IT IS A CHANGE. A call judged "only looks" that does change
+ * something leaves a plan armed that could then repeat that change; a change
+ * judged a change only ends a replay early, as every call did before. So:
+ *
+ *  - Claude Code's built-ins by name: the reading ones only look, every other
+ *    built-in (a sub-agent, an edit, an unknown new tool) is a change;
+ *  - `Bash` by its command ({@link commandReadsOnly}), and `PowerShell` never;
+ *  - an MCP tool by what its own server says of it (`annotations`), else by
+ *    its name: a reading word and no writing word.
+ *
+ * The same rule as the service's `readsOnly` (correctionCheck.ts, AC13), kept
+ * in step by hand, stricter where a wrong "only looks" costs more here: a
+ * command substitution, a process substitution or an `awk` `system(` makes a
+ * command a change.
+ */
+import type { ToolAnnotations } from "../record/recorder.js";
+/**
+ * Whether this call only looks. `toolInput` is the hook's `tool_input` (only a
+ * `Bash` call's `command` is read from it); `hints` is what the tool's own
+ * server listed for it, when it listed anything.
+ */
+export declare function readsOnlyCall(toolName: string, toolInput?: unknown, hints?: ToolAnnotations): boolean;
+/**
+ * Whether a shell command only looks: every part of it is a looking command,
+ * nothing is written to a file, and nothing runs code it does not show.
+ */
+export declare function commandReadsOnly(command: string): boolean;
+//# sourceMappingURL=reads-only.d.ts.map

package/dist/replay/reads-only.js

@@ -0,0 +1,161 @@
+/**
+ * reads-only — whether one call of the agent's only looks, and changes nothing.
+ *
+ * WHY THE RUNNER ASKS (B2 is11.md, 2026-11-11). A direct plan is announced
+ * with "call run_scenario before any other tool", and a first call that is
+ * not `run_scenario` used to retire it on the spot (control/server.ts). The
+ * rule is there for one danger: a model that has no `run_scenario` makes its
+ * own calls, and a divergence would then run every step, writes included,
+ * inside a hook nobody approves. But the call that retired the plan in is11
+ * was the agent reading its own notes file: it had seen another person's name
+ * in the note (Olga, the recording's; the request said Carlos) and checked
+ * first. The plan would have done the task right — its steps take the person
+ * from the request — and the turn cost a full agent run.
+ *
+ * So a call that only looks no longer retires a direct plan: it runs as the
+ * agent wrote it, and the plan waits, still announced, for `run_scenario`.
+ * The first call that may change something still retires it, running nothing
+ * (and nothing ever runs in a hook in its place): a plan run after the agent
+ * changed something itself could do the same work twice.
+ *
+ * WHEN IN DOUBT, IT IS A CHANGE. A call judged "only looks" that does change
+ * something leaves a plan armed that could then repeat that change; a change
+ * judged a change only ends a replay early, as every call did before. So:
+ *
+ *  - Claude Code's built-ins by name: the reading ones only look, every other
+ *    built-in (a sub-agent, an edit, an unknown new tool) is a change;
+ *  - `Bash` by its command ({@link commandReadsOnly}), and `PowerShell` never;
+ *  - an MCP tool by what its own server says of it (`annotations`), else by
+ *    its name: a reading word and no writing word.
+ *
+ * The same rule as the service's `readsOnly` (correctionCheck.ts, AC13), kept
+ * in step by hand, stricter where a wrong "only looks" costs more here: a
+ * command substitution, a process substitution or an `awk` `system(` makes a
+ * command a change.
+ */
+/** Claude Code's built-ins that only read. `ToolSearch` and `TodoWrite` are housekeeping (record/housekeeping.ts). */
+const READ_BUILTINS = new Set([
+    "Read",
+    "Grep",
+    "Glob",
+    "LS",
+    "WebFetch",
+    "WebSearch",
+    "NotebookRead",
+    "TaskOutput",
+    "BashOutput",
+    // The conversation's own: a question to the person, plan mode in or out.
+    // Nothing outside the conversation changes, and the plan may still be
+    // what the person says yes to.
+    "AskUserQuestion",
+    "EnterPlanMode",
+    "ExitPlanMode",
+]);
+// Not `query`, `select` or `check`: a database query, a selected option, a
+// check-in can change something.
+const READ_WORDS = new Set([
+    "list", "get", "search", "find", "read", "fetch", "lookup", "count", "view", "show",
+    "describe", "retrieve", "browse", "peek", "inspect", "snapshot",
+]);
+/**
+ * A word that may change something: a name holding one writes, whatever else
+ * it says (`get_or_create_contact`, `find_and_replace`). Some are nouns too
+ * (`get_schedule`): such a look is then taken for a change, which only ends a
+ * replay early, never lets a change through.
+ */
+const WRITE_WORDS = new Set([
+    "create", "add", "set", "update", "upsert", "insert", "put", "post", "send", "delete",
+    "remove", "mark", "replace", "archive", "move", "assign", "book", "cancel", "write",
+    "edit", "modify", "save", "submit", "approve", "reject", "close", "open", "merge",
+    "push", "publish", "upload", "invite", "schedule", "reply", "forward", "transfer",
+    "pay", "refund", "notify", "run", "execute", "exec", "apply", "reset", "start", "stop",
+    "kill", "enable", "disable", "grant", "revoke", "rename", "tag", "label", "comment",
+]);
+/** A tool name's words: `getJiraIssue` → get, jira, issue; `calendar_search_events` → calendar, search, events. */
+function nameWords(name) {
+    return name
+        .replace(/([a-z\d])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z\d]+/)
+        .filter(Boolean);
+}
+/**
+ * Whether this call only looks. `toolInput` is the hook's `tool_input` (only a
+ * `Bash` call's `command` is read from it); `hints` is what the tool's own
+ * server listed for it, when it listed anything.
+ */
+export function readsOnlyCall(toolName, toolInput, hints) {
+    if (toolName === "Bash") {
+        const command = toolInput?.command;
+        return typeof command === "string" && commandReadsOnly(command);
+    }
+    if (READ_BUILTINS.has(toolName))
+        return true;
+    // Every other built-in — Write, Edit, PowerShell, a sub-agent, one added
+    // after this list was written — may change something.
+    if (!toolName.startsWith("mcp__"))
+        return false;
+    // A server's word beats any guess from the name.
+    if (hints?.readOnlyHint === false || hints?.destructiveHint === true)
+        return false;
+    if (hints?.readOnlyHint === true)
+        return true;
+    const words = nameWords(toolName.replace(/^mcp__.+?__/, ""));
+    if (words.some((w) => WRITE_WORDS.has(w)))
+        return false;
+    return words.some((w) => READ_WORDS.has(w));
+}
+/** Commands that only look (`ls`, `cat`, `grep …`). */
+const READ_COMMANDS = new Set([
+    "ls", "dir", "cat", "type", "head", "tail", "less", "more", "grep", "rg", "egrep", "fgrep",
+    "find", "wc", "pwd", "echo", "printf", "date", "whoami", "which", "where", "stat", "file",
+    "du", "df", "tree", "jq", "sort", "uniq", "cut", "awk", "diff", "cmp", "basename", "dirname",
+    "realpath", "readlink", "true", "false", "test", "ps", "uname", "hostname", "id", "nproc",
+    "free", "uptime", "node --version", "npm --version",
+]);
+const READ_GIT = new Set([
+    "status", "log", "diff", "show", "branch", "rev-parse", "ls-files", "blame", "remote",
+    "describe", "config --get", "grep", "shortlog", "tag --list",
+]);
+/**
+ * Whether a shell command only looks: every part of it is a looking command,
+ * nothing is written to a file, and nothing runs code it does not show.
+ */
+export function commandReadsOnly(command) {
+    const text = command.trim();
+    if (!text)
+        return false;
+    // Code that runs out of sight: a substitution (`$(…)`, backticks), a
+    // process substitution, awk's `system(`.
+    if (/`|\$\(|<\(|>\(|\bsystem\s*\(/.test(text))
+        return false;
+    // A redirect into a file (not into /dev/null, not 2>&1), tee, or an in-place edit changes something.
+    if (/(^|[^0-9&])>{1,2}\s*(?!&|\/dev\/null)\S/.test(text) ||
+        /&>{1,2}\s*(?!\/dev\/null)\S/.test(text) ||
+        /\btee\b/.test(text) ||
+        /\bsed\b[^|;&]*\s(-i|--in-place)/.test(text)) {
+        return false;
+    }
+    if (/\bfind\b[^|;&]*\s-(delete|exec|execdir|ok|okdir|fprint|fprintf|fls)\b/.test(text))
+        return false;
+    // A job sent to the background (`cmd &`): not something this reads.
+    if (/(?<![>&])&(?![>&])/.test(text.replace(/&&/g, "")))
+        return false;
+    const parts = text
+        .split(/\|\||&&|[|;\n]/)
+        .map((p) => p.trim())
+        .filter(Boolean);
+    if (parts.length === 0)
+        return false;
+    return parts.every((part) => {
+        const words = part.replace(/^(\w+=\S+\s+)+/, "").split(/\s+/);
+        const cmd = (words[0] ?? "").replace(/^.*[\\/]/, "");
+        if (cmd === "git")
+            return READ_GIT.has(words[1] ?? "") || READ_GIT.has(`${words[1] ?? ""} ${words[2] ?? ""}`);
+        if (cmd === "sed")
+            return !/\s(-i|--in-place)/.test(part);
+        return READ_COMMANDS.has(cmd) || READ_COMMANDS.has(`${cmd} ${words[1] ?? ""}`);
+    });
+}
+//# sourceMappingURL=reads-only.js.map

package/package.json

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