@basein/runner 0.3.9 → 0.3.11

package/docs/calculatedReplay.md

@@ -45,7 +45,7 @@ this design has a ladder whose cheapest rung is free — and the more of a stack
 |---|---|---|
 | Runs MCP tools itself | No (`replay.md` §12: *"rrepeat never executes tools — not even MCP"*) | **Yes**, on the connection it already owns |
 | Divergence fallback | A second Agent SDK session — the dominant cost | Direct `tools/call` through the proxies — **$0** |
-| Reaches built-ins (`Bash`, `Read`) | Only by steering the live session | `Read`, `Glob`, `Grep`, `Edit`, `Write` and `Bash` run on the runner itself, jailed to the project (`BIR_BUILTIN_TOOLS`, `BIR_BASH_ALLOW`); any other built-in is steered |
+| Reaches built-ins (`Bash`, `Read`) | Only by steering the live session | `Read`, `Glob`, `Grep`, `Edit`, `Write` and `Bash` run on the runner itself, jailed to the project (`BIR_BUILTIN_TOOLS`, `BIR_BASH_ALLOW`); any other built-in is steered. In a host that is not Claude Code a tool with one of these names is the application's own, and the runner runs none of them (§7.4) |
 | Needs `@anthropic-ai/*` at runtime | Yes | No (§16.3) |
 
 ---
@@ -131,6 +131,10 @@ Server-side, and worth stating because the threshold in §4 is a judgement about
   (`recordings/embeddings.ts`).
 - Candidates are **the caller's own canonical runs only** (`listUserRunEmbeddings(userId)`);
   duplicates and sub-threshold runs are excluded from the pool at record time.
+- **Inside one host** — on the service as built, which is not deployed yet. A run created with
+  `framework` `langchain` or `langchain:<scope>` (§7.4) is matched only against recordings and
+  plans of that same text. Everything else (`baseinstrunner`, `custom`, the built-ins) is Claude
+  Code's pool, as before.
 - The match is the single best cosine ≥ `SIMILARITY_THRESHOLD` (default **0.9**).
 - A matched run only carries a `scenarioId` when its scenario exists **and** is `state: 'ready'`.
 
@@ -191,7 +195,7 @@ Every gate that declines logs **one** `replay.decision` line carrying the reason
 | # | Gate | Declines when | Outcome floor |
 |---|---|---|---|
 | 1 | **A match arrived** | `getMatch()` resolved `null`, or the budget expired (§10) | (no report — nothing matched) |
-| 2 | **Replay enabled** | `BIR_REPLAY === "0"`, or, with it unset, the project's stored switch is off (`bir replay off`, or a `bir install` without `--replay`) | `not_steered` |
+| 2 | **Replay enabled** | `BIR_REPLAY === "0"`, or, with it unset, the project's stored switch is off (`bir replay off`, or a `bir install` without `--replay`). In a session of another host, also when the run's adapter asked for no plan with its prompt (`host_records_only`, §7.4) | `not_steered` |
 | 3 | **Scenario ready** | `scenario == null`, `state !== "ready"`, or `steps.length === 0` | `not_steered` |
 | 4 | ~~**Similarity**~~ | Retired: a match is the decision to use the scenario (below) | — |
 | 5 | **Tool coverage** | No step is executable anywhere (§5 → `mode: "none"`) | `not_steered` |
@@ -204,6 +208,9 @@ inside the prompt's budget (§10) is dropped (`match_timeout`, `arm_timeout`), a
 after the prompt was answered is retired unannounced (`match_late`, `arm_unannounced`). A `direct`
 plan is declined when no running `bir-scenario` has said it serves `run_scenario`
 (`no_delivery_tool`, §6.3). In plan mode (`permission_mode: "plan"`) nothing is announced at all.
+In a session of another host (§7.4) a plan that armed is taken back, before any step of it runs,
+when it names a tool the agent that asked does not hold (`host_tool_missing`): it is booked like
+any gate's decline, `not_steered`, with no step marked failed.
 
 Gate 4 is retired. Up to 0.3.6 it declined a match under `BIR_MIN_STEER_SIMILARITY` (0.92),
 above the server's 0.9, on the argument that the server only decided *"do not record this again"*
@@ -277,6 +284,12 @@ A **mixed** scenario in `steer` mode still gets direct execution for its wrapped
 diverges (§8), so coverage is not all-or-nothing at the divergence boundary — only at the arm-time
 mode choice.
 
+**None of this applies in a session of another host.** When a session's requests name a host that
+is not Claude Code (§7.4), a tool's name carries no Claude Code meaning: `Bash`, `Read` or an
+`mcp__` prefix name the application's own tools, no proxy of this folder sees their calls, and the
+runner runs none of them, whatever `BIR_BUILTIN_TOOLS` lists. Every step is `live`, so the mode is
+always `steer`.
+
 ---
 
 ## 6. Mode A — direct execution
@@ -423,7 +436,9 @@ another way. Divergence (§8) is for steer plans only.
 The mixed rung. Ported from RRepeat's `replay.md` §3/§12, which is the right design and is already
 proven: the model chooses *which* tool and *when*; the control server overrides the *arguments* and
 threads state between steps. The session never leaves the model's hands, so every
-`tool_use`/`tool_result` in the transcript is genuine and continuation is automatic.
+`tool_use`/`tool_result` in the transcript is genuine and continuation is automatic. That is Claude
+Code. In a host that is not Claude Code the same mode is stepped through by the host's adapter, in
+the model's place, and a call the model makes itself is never pinned (§7.4).
 
 **Arm** at `UserPromptSubmit` — plan on `run.plan`, `run.planToolUse = new Set()`, directive via
 `additionalContext`, **no `decision`** so the prompt still reaches the model:
@@ -589,15 +604,91 @@ In [`HOOK_ROUTES`](../src/config/adapters/claude-code.ts) neither `PreToolUse` n
 carries `async: true`, so this already holds — **and must never be relaxed**. Add it to the comment
 block there, next to the `SessionEnd` note that records the same class of lesson.
 
+### 7.4 A host that is not Claude Code
+
+Everything above assumes Claude Code: its hooks report the turn, and its model makes the plan's
+calls. The recorder's local protocol also serves a host that has neither. Today that is a
+LangChain application: a Python program whose agent is built with LangChain's `create_agent` and
+the package `langchain-basic2202`, a LangChain middleware that talks to the recorder over that
+protocol. The package is *the adapter* below, and it is not on PyPI yet. Claude Code's hooks are
+unchanged, and every new field is optional. A session whose requests carry
+`host: { app, version?, adapter?, scope? }` with an `app` other than `claude-code` is a session of
+another host ([`control/server.ts`](../src/control/server.ts)). The fields named below are what
+such an adapter adds to the hook routes of the control plane
+([BaseInstRunner.md](BaseInstRunner.md), Phase 5). `hostFields` in `/health` tells an adapter how
+much of this a recorder understands: with 1 it records, and from 2 on it may also ask for a plan
+and step through it.
+
+For such a session:
+
+- **The run names its host.** It is created with `framework` = the app, or `app:scope`
+  (`langchain`, `langchain:billing`), and `metadata.host`. A Claude Code run is created as before
+  (`framework: "baseinstrunner"`).
+- **Only `/session/prompt` opens a run.** Any other hook that finds no open run opens none and
+  records nothing: it is answered `{}`, or `{ noPlan: true }` when it asked for a step.
+- **A plan starts only for a prompt that said `replay: true`.** Otherwise the match is declined at
+  gate 2 with `host_records_only` (§4). The prompt's answer carries the armed plan as data too
+  (`plan: { scenarioId, mode, steps: [{ stepIndex, toolName }], stopAt? }`): the directive beside
+  it is a text written for a model.
+- **The mode is always `steer`, and the runner runs no step itself.** The host runs its own tools.
+  Tool names carry no Claude Code meaning: `Bash`, `Read`, `TodoWrite`, `ToolSearch`… are the
+  application's own tools, and nothing is skipped as housekeeping except the `bir` server's own
+  tools. So there is no direct mode there, and no divergence recovery (§8): nothing can be executed
+  here in the host's place.
+- **The adapter asks for each step**, with a `/tool/pre` that says `scripted: true`, and the host
+  runs its own tool. The answer is the step's arguments (`hookSpecificOutput.updatedInput`), or
+  `{ noPlan: true }` when the recorder holds no live plan, or `{ declined: "host_tool_missing" }`
+  when the plan names a tool that is not in `tools` (the agent's tools, sent with the first such
+  request of a run), or a refusal whose reason is the hand-over note when the plan stopped in that
+  very request. The step's output is threaded from the `/tool/post` that follows: every step is
+  `live` (§7.2).
+- **The model's own call is never pinned.** A `/tool/pre` without `scripted` is the model's own
+  call, and it is never given the plan's arguments. When a plan is live it is handed over (§8): the
+  call runs as the model wrote it, and the hand-over note comes with that call's `/tool/post`.
+- **The host may stop a step itself**, and says so with the step's `/tool/post`.
+  `host_stop: "rejected"` means a person said no, or answered in the tool's place, or a call limit
+  blocked the call; `"edited"` means a person changed the call. Either way the step's verdict is
+  `skipped`, not `failed`, nothing is counted against the plan, and the plan hands over (§8). §11.1
+  has what the report says.
+- **There is no transcript.** What Claude Code's transcript gives comes with the requests instead:
+  with a `/tool/pre`, what the model wrote and reasoned before the call (`context`, `thinking`);
+  with `/session/stop`, the answer and the tokens (`final_answer`, `usage`). The cost comes from
+  that `usage` (§11.4). The conversation's earlier tool results do not come with the prompt: a new
+  prompt's values are read from the prompt alone, here as in Claude Code (§16.3), and a
+  `recent_results` an adapter still sends is not read.
+- **A run can end without an ordinary stop.** With `/session/stop`, `failed` closes the run with
+  that text as its `error` (cleaned of secrets, cut) and no final answer, and `incomplete` marks
+  the finish `incomplete: { lostSteps, lossy }`. A run sealed after two hours of silence is closed
+  with `error: "turn ended early: idle"`. A run that is closed while its plan is still live has the
+  plan handed over first, so its report says what happened (§11.1). On the service as built (not
+  deployed yet), a run with an `error` or with that mark is never picked for automatic calculation
+  and no longer catches its prompt, unless its owner preferred it or it already has a plan. Only a
+  run of another host sends either today: a Claude Code run that was interrupted or lost steps is
+  finished as before.
+- **A value that a plan reads from the prompt is checked against the host's own sinks** before it
+  goes into a tool: the `sinks` the host declared with its prompt (§13.2, mitigation 6).
+- **The switch is the same.** `bir setup --host langchain` stores replay on for the folder
+  (`--no-replay` stores it off), and `bir replay on` and `bir replay off` work there as anywhere.
+- **The audit lines name the host**: `run.start … host=langchain`,
+  `plan.armed … mode=steer host=langchain`, and `run.finish … ended=<reason>` when the run did not
+  end with an ordinary stop. `run.incomplete` and `run.host_failed` are what the host said with its
+  stop.
+
+The how-to for a LangChain developer — setting up the folder, the two lines of Python, what to do
+when something is wrong — is `langChainGuide.md` in the root of the runner's repository (it is not
+in the npm package), and is not repeated here. The design guide with every decision is
+`integratioLangChane.md` in the service's repository.
+
 ---
 
 ## 8. Divergence
 
 In a steer plan, the model called a tool the plan did not expect, or the call had no `tool_use_id`.
-(A direct plan never diverges, §6.4. A `toolInputLogic` that throws is not a divergence either:
-re-executing would start at that same step and throw again, so the step is recorded as failed and
-the task is handed to the model, with a note in place of the call.) Three tiers, tried in order.
-Here is where the §0 asymmetry pays.
+(A direct plan never diverges, §6.4. Nor does a plan in a host that is not Claude Code, §7.4: only
+the host can run its tools, so the plan is handed over and nothing is executed in its place. A
+`toolInputLogic` that throws is not a divergence either: re-executing would start at that same step
+and throw again, so the step is recorded as failed and the task is handed to the model, with a note
+in place of the call.) Three tiers, tried in order. Here is where the §0 asymmetry pays.
 
 **Tier 1 — direct-execute the remainder (new; the common case).**
 Take every not-yet-run step, execute it, and hand the composed result back. This happens inside the
@@ -636,6 +727,12 @@ about it:
 - beside a pin still in flight: *"… was not run by the scenario: another of its calls was still in
   flight, and a scenario runs one call at a time."*, and the pin itself *"was started and has not
   reported back"*.
+- stopped by its host, in a session of another host (§7.4): *"… was not run by the host. The result
+  above was written by the host, not by the tool. Do not run the step again unless the user asks."*
+  (`host_rejected`), or *"… ran with arguments a person chose, not the scenario's. Its result above
+  is real and its side effects are in place. Do not run it again."* (`host_edited`). When no step
+  ran before it, the note says *"No step of the scenario ran as it was planned."* instead of *"No
+  step … ran"*. The report's `fallbackKind` stays `step_failed`.
 
 It ends with the remaining planned steps and the parameters derived for this request, within 4 000
 characters.
@@ -781,8 +878,8 @@ The hook is on the user's critical path. Every await here is a stall the user wa
 
 | Moment | Route | Hook timeout | Answered by | What may be awaited | Budget |
 |---|---|---|---|---|---|
-| `UserPromptSubmit` | `/session/prompt` | 10 s | 7 s | the match; for a scenario with a target, its derivation; a steer plan's argument preview | match `BIR_MATCH_BUDGET_MS` = **3000**; match and arming together ≤ **6 s**; derivation ≤ `BIR_HOOK_DERIVE_BUDGET_MS` = **4000** |
-| `PreToolUse` | `/tool/pre` | 15 s | 12 s | `plan.ready()` (derivation); on a divergence, the remaining steps | derivation ≤ min(`BIR_DERIVE_BUDGET_MS`, `BIR_HOOK_DERIVE_BUDGET_MS`) = **4000**; all replay work ≤ `BIR_PRETOOL_REPLAY_BUDGET_MS` = **9000** (held at ≤ 10 000) |
+| `UserPromptSubmit` | `/session/prompt` | 10 s | 8.5 s | the match; for a scenario with a target, its derivation; a steer plan's argument preview | match `BIR_MATCH_BUDGET_MS` = **3000**; match and arming together ≤ **7.5 s**; derivation ≤ `BIR_HOOK_DERIVE_BUDGET_MS` = **8000**, cut short by the 7.5 s |
+| `PreToolUse` | `/tool/pre` | 15 s | 12 s | `plan.ready()` (derivation); on a divergence, the remaining steps | derivation ≤ min(`BIR_DERIVE_BUDGET_MS`, `BIR_HOOK_DERIVE_BUDGET_MS`) = **8000**; all replay work ≤ `BIR_PRETOOL_REPLAY_BUDGET_MS` = **9000** (held at ≤ 10 000) |
 | `run_scenario` | `/scenario/run` | `bir-scenario`'s own, **290 s** (`BIR_SCENARIO_RUN_TIMEOUT_MS`) | — | `ready()` + N steps | derivation `BIR_DERIVE_BUDGET_MS` = **8000**; plan `BIR_REPLAY_PLAN_BUDGET_MS` = **100000** (`BIR_REPLAY_BUDGET_MS` overrides it where set); per step `BIR_STEP_TIMEOUT_MS` = **60000**, clipped to what the plan has left |
 | `PostToolUse` | `/tool/post` | 5 s | 2 s | nothing | — |
 | `Stop` | `/session/stop` | 5 s | 2 s | nothing (report is queued) | — |
@@ -863,6 +960,25 @@ beside a pinned one hands over as `fell_back` or `failed` (§7). A direct run ca
 (Esc, or `bir-scenario`'s own timeout) books `fell_back` or `failed` with `measured: false`, never
 `diverged`: that turn's cost says nothing about what the task costs.
 
+A host that is not Claude Code (§7.4) adds three endings, and none of them is counted against the
+plan. The report says so with two fields: `measured`, and `baselineEligible: false`, which keeps
+the turn's cost out of the baseline samples (absent, the turn is eligible).
+
+- **A person's "no".** A step the host did not run (`host_stop: "rejected"`: a person said no, or
+  answered in the tool's place, or a call limit blocked the call) is recorded `skipped`, never
+  `failed`, and the plan hands over: `fell_back` when a step ran before it, `failed` when none did.
+  The report says `measured: false` and `baselineEligible: false`: the task ended early, so the
+  turn's cost is no measure of it.
+- **A changed call.** A step that ran with arguments a person chose (`"edited"`) is `skipped` too,
+  and the plan hands over the same way. The cost stays measured, with `baselineEligible: false`.
+- **A run closed with its plan live.** The plan is handed over first, so the report says
+  `fell_back` (a step ran) or `failed` (none ran), never `not_steered`, with `measured: false` and
+  `baselineEligible: false`. A run that ended early for any other reason (it failed, or went
+  silent) reports the same two fields.
+
+A plan taken back before any step ran (`host_tool_missing`, §4) is a decline like any other:
+`not_steered`.
+
 Direct mode reports `steered_full`. BaseIn's zod enum
 (mirrored in [`replay/types.ts`](../src/replay/types.ts)) has no `direct` member, and `steered_full`
 means exactly what happened: every planned step executed under the scenario's control and the
@@ -887,6 +1003,11 @@ POST /scenarios/:scenarioId/executions
 An **unredeemed** ticket leaves no execution row at all. That asymmetry is intentional and worth
 preserving: silence loses a saving; it never invents one.
 
+**How late a report may arrive.** The deployed service redeems a ticket for one hour after its plan
+was handed out, and answers a later report `409 invalid_ticket`. The service as built (not deployed
+yet) redeems it for 24 hours. It also answers a report whose write failed `503 report_not_booked`,
+and the recorder sends that report once more.
+
 ### 11.2a What each step did (the service's errorshandling.md)
 
 The last five fields are the diagnosis, and none of the money depends on them. The service's
@@ -922,14 +1043,19 @@ a replay that sent 3600.
   are read on a page, never parsed, and with its marker a cut payload still fits the 4,000
   characters the service keeps of each — so the page shows this cut and its sizes, not a second one.
   The recorder redacts once more as it sends.
-- **Inside one small request.** The service reads `POST /scenarios/:id/executions` with its 100 kB
-  JSON parser (only `/recordings` has the 5 MB one) and answers a larger body 413, which would lose
-  the turn's cost with it. So the recorder holds the whole report to 96 KiB (`REPORT_MAX_BYTES`):
-  it writes the costs and the verdicts first, then adds payloads while they fit — the failed steps'
-  first, then every step's input, then the outputs, in the order the steps ran. A payload that does
-  not fit is left out, and its step keeps its verdict.
+- **Inside one small request.** The deployed service reads `POST /scenarios/:id/executions` with
+  its 100 kB JSON parser (only `/recordings` has the 5 MB one) and answers a larger body 413, which
+  would lose the turn's cost with it. So the recorder holds the whole report to 96 KiB
+  (`REPORT_MAX_BYTES`): it writes the costs and the verdicts first, then adds payloads while they
+  fit — the failed steps' first, then every step's input, then the outputs, in the order the steps
+  ran. A payload that does not fit is left out, and its step keeps its verdict. The service as
+  built (not deployed yet) accepts 1 MB on this route and on `/scenarios/:id/derive`, and cuts a
+  report's `prompt` at 10,000 characters where the deployed one refuses the whole report with 400.
+  The recorder keeps its report under 100 kB all the same: older services have that limit.
 - **Absent where there was none.** A step whose input logic threw has no input. A `skipped` step
-  has no output, and neither has a call the host says failed without a result.
+  has no output, and neither has a call the host says failed without a result. The exception is a
+  step its host stopped itself (§7.4): its verdict keeps what the host handed back, and after a
+  changed call it has no input, because only the host knows the arguments that call ran with.
 - **Only for the reported scenario's own steps.** A step inside a called segment is reported with
   its verdict and its `scenarioId`, without payloads: the console still files verdicts by step
   number alone (the service's plan-services.md, W1.9), and a called segment numbers its steps from
@@ -938,9 +1064,11 @@ a replay that sent 3600.
 `ok` and `recorded` are passes (`recorded` with an asterisk: the values came from the source run,
 which happens only with `BIR_REPLAY_RECORDED_OUTPUTS=1` and in `bir replay`). `skipped` produced no
 result here: its call could not be sent (a built-in outside the session, no proxy for its server,
-only another open session's proxy), or it was sent and timed out or was refused. The plan stops at
-a `skipped` step. **`failed` is the only one that means the scenario is broken** rather than
-the environment — it is the scenario's own logic throwing, and it is what `Recalculate` fixes.
+only another open session's proxy), or it was sent and timed out or was refused. A step that its
+host stopped itself, in a host that is not Claude Code, is `skipped` as well: a person refused it,
+or changed its call (§7.4). The plan stops at a `skipped` step.
+**`failed` is the only one that means the scenario is broken** rather than the environment — it is
+the scenario's own logic throwing, and it is what `Recalculate` fixes.
 
 Three rules this must keep:
 
@@ -969,7 +1097,7 @@ service's matching `202 { recorded: false }`): it now *is* worth sending when a
 | Component | Source | Notes |
 |---|---|---|
 | `deriveCostUsd` | our own Haiku call's `usage`, priced locally | the only tokens replay itself spends |
-| `sessionCostUsd` | transcript usage **delta** for this run (§11.4) | the live turn: prompt, tool calls, answer |
+| `sessionCostUsd` | transcript usage **delta** for this run (§11.4); in a host that is not Claude Code, the `usage` its adapter sends with `/session/stop` | the live turn: prompt, tool calls, answer |
 | `fallbackCostUsd` | **0.00** | direct execution spends no tokens (§8) |
 
 > ### ⚠ Verify the pricing table before copying it
@@ -1010,9 +1138,23 @@ rather than to a negative cost. A run with **no mark** (one opened lazily by a p
 prompt) reports `measured: false` — better to say "unmeasured" than to hand the ledger an inflated
 baseline.
 
-`measured` is `true` only when a mark existed **and** `pricingVersion` matches the server's. The
-server enforces the second half itself and stores a mismatched report as unmeasured rather than
-trusting it.
+`measured` is `true` only when a mark existed, tokens were found since it, **and** every model of
+the turn has a price in the runner's table (`priceUsage` and `hasModelPricing`,
+[`control/server.ts`](../src/control/server.ts)). A model outside the table used to cost $0, and
+that zero was called measured: a saving nobody made. Now such a turn is not measured, in every
+host. A `run.unmeasured` line says why, with `why=`, when the run had no mark or when a model has
+no price (then with `models=`). A turn whose transcript held no tokens since the mark is not
+measured either, and writes no such line. No price table and no `PRICING_VERSION` changed with this.
+
+The server judges a report again. It stores one whose `pricingVersion` differs from its own as
+unmeasured rather than trusting it. As built (not deployed yet) it does the same with a report that
+says `measured: true` with a session cost of $0, and a finish with a cost of 0 stores no cost.
+
+**A host that is not Claude Code has no transcript, and no mark** (§7.4). Its cost comes from the
+`usage` its adapter sends with `/session/stop`, and is measured only when at least one entry has
+tokens and every model in the list has a price; with no usage at all, the line says
+`why="the host sent no usage"`. Such a host hands over one number for the whole run, so with more
+than one plan in one run none of them is measured.
 
 ---
 
@@ -1049,10 +1191,11 @@ bir replay --scenario scn_… --prompt "…" --dry
 
 Runs the same plan through the same executor, against the same live proxies, printing the per-step
 input/output and the response model. It is how you test a scenario without a session, how a Tier 2
-or non-Claude-Code client gets any replay at all, and the first thing to reach for when a steered
-turn behaves oddly. The operator named the scenario, so it keeps its own contract: a step it cannot
-send stands on its recorded output, the allowlist does not gate it, and it is not held to the 270 s
-direct-run ceiling (§10).
+client — or one that is neither Claude Code nor a host whose adapter steps through plans (§7.4) —
+gets any replay at all, and the first thing to reach for when a steered turn behaves oddly. The
+operator named the scenario, so it keeps its own contract: a step it cannot send stands on its
+recorded output, the allowlist does not gate it, and it is not held to the 270 s direct-run ceiling
+(§10).
 
 ---
 
@@ -1090,6 +1233,15 @@ What actually constrains it:
   and a `bir install` without it stores replay off in a project that never asked for it. A
   compromised or misconfigured `BIR_AUTH_URL` therefore cannot start executing logic on a machine
   whose operator never asked for replay.
+- **A small environment in an application's folder.** A recorder started for a folder that is set
+  up for another host and not for Claude Code (`bir setup --host langchain`, `bir up`) gets a small
+  environment, not the whole environment of the window that started it: `PATH`, the home and temp
+  variables, what the system needs to start a process, the proxy and certificate variables, and
+  every `BIR_*` variable (`smallEnv`, [`control/daemon.ts`](../src/control/daemon.ts)). Step code
+  runs inside the recorder with no sandbox, so a model key or a database password of the
+  application must not reach it. A folder that is set up for Claude Code too keeps the whole
+  environment, because Claude Code's own steps may need it. Nothing changes for a Claude Code
+  project.
 
 If that is not enough for a deployment, the mitigation is a real one and is out of scope here:
 evaluate the logic in a separate `node:vm` context with a frozen, minimal global. Filed as §20 question 3.
@@ -1152,6 +1304,9 @@ This is the sharpest edge in the whole design, and it must not be buried.
   answered `allow` while the runner has announced a direct plan, so it brings no surprise prompt
   (and no denial under `claude -p`); the user's own deny or ask rules for it still apply.
 - **Plan mode** (`permission_mode: "plan"`) gets none of it: no directive, no pin, no `allow`.
+- **A host that is not Claude Code** (§7.4) is neither mode as written here: the runner runs no
+  step. It hands the host's adapter each step's arguments, the host runs its own tool, and the
+  adapter reports a step that a person refused or changed (`host_stop`).
 
 So a scenario is, in effect, a **pre-approved list of tool calls with computed arguments**. That is
 precisely what makes it valuable, and precisely what makes it dangerous. Six mitigations, all
@@ -1159,7 +1314,8 @@ required:
 
 1. `--replay` is a distinct flag: `bir setup` passes it, and a `bir install` without it leaves
    replay off in a project that never asked for it. `bir replay off` or `BIR_REPLAY=0` turns it off
-   once installed, and `bir off` takes the whole runner out of the way.
+   once installed — the recorder reads either when it starts, so `bir up --restart` applies it — and
+   `bir off` takes the whole runner out of the way.
 2. `BIR_REPLAY_ALLOW_SERVERS` — a comma-separated allowlist of the server keys bir may call by
    itself: **direct** runs and divergence recovery (§8), though not `bir replay`, which an operator
    runs by hand. Unset means *all wrapped servers*; the guide (§5 of `calculatedReplayGuide.md`)
@@ -1178,7 +1334,11 @@ required:
    have), or the plan hands over; found at arm time, it declines as `missing_target`. A plan whose
    only such steps write files (`Edit`, `MultiEdit`, `Write`, `NotebookEdit`) rejects only line
    breaks and NUL. Plans with a step whose input is run do not send recent tool results to
-   derivation, and the derivation prompt is redacted before it leaves the machine.
+   derivation, and the derivation prompt is redacted before it leaves the machine. In a session of
+   another host (§7.4) the tool names are the host's own, and Claude Code's lists of built-ins are
+   not read: a value that a plan reads from the prompt is checked before it goes into a tool the
+   host declared in `sinks` with its prompt (`command`, `write`), or whose plain name has a command
+   word (sql, query, exec, shell, command, script, eval).
 
 ### 13.3 The control plane
 
@@ -1222,7 +1382,13 @@ fail because of BaseInstRunner.**
 | `run_scenario` pending in two sessions and the request names neither | Nothing runs (`replay.run_ambiguous`); each model does its own task |
 | The runner is off (`bir off`, or `BIR_OFF=1` for a session) | Hooks answer `{}` and nothing arms; the `bir` server lists no tools |
 | Plan mode | Nothing is announced, pinned or approved |
-| Ticket redemption fails (offline, 409) | Logged; the turn is unaffected. An unredeemed ticket books nothing |
+| Another host (§7.4): the run's adapter asked for no plan with its prompt | Declined at gate 2 (`host_records_only`), `not_steered`; the model does the task |
+| Another host: the plan names a tool the agent that asked does not hold | Taken back before any step runs (`host_tool_missing`), `not_steered`; the model does the task |
+| Another host: the model makes a call of its own while the plan is live | The plan is handed over. The call runs as the model wrote it, never with the plan's arguments, and the note comes with its `/tool/post` |
+| Another host: a person refuses a step, or changes its call | The step is `skipped`, never `failed`, and the plan hands over; `baselineEligible: false`, and after a refusal `measured: false` (§11.1) |
+| Another host: the run fails, goes silent for two hours, or is closed with its plan still live | A live plan is handed over first: `fell_back` or `failed`. The report says `measured: false` and `baselineEligible: false`. A run that ended early is finished with an `error` and no final answer |
+| The service answers `429`: an account over one of its limits (built on the service, not deployed yet) | A create, a step or a report is sent once more, at most 2 s later, then dropped (`recorder.send_failed` with `HTTP 429`). A dropped step is a hole in its recording, and a run whose create got the 429 runs without its plan. A 429 that the second try did not cure counts as the service being unwell: for 5 to 60 s no prompt of that recorder waits for a match. An intent probe over its own limit is answered `200` with no match, never `429` |
+| Ticket redemption fails (offline, 409) | Logged; the turn is unaffected. An unredeemed ticket books nothing. A `503 report_not_booked` (the service as built; not deployed yet) is sent once more |
 | Two reports for one ticket (retry, `Stop` racing `SessionEnd`) | Server books once, answers `200 { duplicate: true }` |
 | Replay off (`BIR_REPLAY=0`, `bir replay off`, or never installed with `--replay`) | Exactly v1: stop recording on a match, do nothing else, and no prompt waits for the match |
 
@@ -1291,6 +1457,11 @@ POST /proxy/result    { workId: string, result?: unknown, error?: string }
   → 200 { ok: true }
 ```
 
+The hook routes ([BaseInstRunner.md](BaseInstRunner.md), Phase 5) carry more for a host that is not
+Claude Code: optional fields that its adapter adds to `/session/prompt`, `/tool/pre`, `/tool/post`
+and `/session/stop`, and `hostFields` in `/health`. §7.4 names them, and says what they mean for a
+plan.
+
 ### 16.2 The direct executor
 
 ```ts
@@ -1393,7 +1564,11 @@ same parameters from the same prompt:
   live call, recent results) and a bearer token, `derived` as the service answered. This is the
   ordinary path: nearly every session runs inside Claude Code on a subscription and has no key of
   its own (segmented.md R-PARAM-5). The answer is re-normalised here against this runner's own copy
-  of the schema, so the gate reads a `missing` computed from what will actually run.
+  of the schema, so the gate reads a `missing` computed from what will actually run. The service as
+  built (not deployed yet) cuts the prompt it reads new values from at 20,000 characters, and keeps
+  the last five tool results. A plan started at the prompt sends no tool results, in any host: the
+  transcript does not hold the new prompt yet, so its results would be an earlier prompt's, read as
+  this task's (segmented.md R-PARAM-2a). A plan started at a tool call sends this prompt's.
 - **Neither → return every key's recorded `sampleValue`**, `costUsd: 0`, `derived: false`. Settings
   stand on their samples; a scenario with a target declines rather than run on a stale one.
 - With an `apiKey`, `POST https://api.anthropic.com/v1/messages` with the same extraction prompt,
@@ -1523,7 +1698,9 @@ is refused.
 `bir` invocations (and a plain `cd`), are host housekeeping, like `ToolSearch`
 ([housekeeping.ts](../src/record/housekeeping.ts)). They are never recorded as steps, and never
 count as divergence from a plan. A session that fixes a plan must not become a plan that edits
-plans when it is replayed. The operator's walk-through is
+plans when it is replayed. In a session of another host (§7.4) only the `bir` server's own tools
+are housekeeping: a tool the application names `Bash`, `ToolSearch` or `TodoWrite` is its own work,
+and is recorded like any other. The operator's walk-through is
 [calculatedReplayGuide.md](calculatedReplayGuide.md) §9.2.
 
 `--dry` maps to BaseIn's `POST /scenarios/:id/replay`, which evaluates the stored logic against the