@cruxy/cli 1.8.1 → 1.10.0

package/README.md

@@ -282,7 +282,7 @@ branch on them:
 | `10` | approval   | `CRUXY_E_APPROVAL_REQUIRED`, `CRUXY_E_PLAN_APPROVAL_REQUIRED`, `CRUXY_E_ROLLBACK_APPROVAL_REQUIRED`                                                                                                  |
 
 The LLM client is [`@cruxy/sdk`](https://www.npmjs.com/package/@cruxy/sdk) —
-provider-agnostic, built over `fetch`, with no vendor SDKs.
+cruxy's client for the cruxy gateway, built over `fetch`, with no vendor SDKs.
 
 ## License
 

package/dist/agent/loop.js

@@ -50,6 +50,21 @@ async function driveLoop(args, renderer,
 routed) {
     const { provider, registry, config, ctx } = args;
     const { logger } = ctx;
+    // THE ONE PER-TURN FIELD ON AN OTHERWISE SESSION-SCOPED CTX (cli#244).
+    //
+    // `spawn_subagent` needs to reach the collector of the turn that called it, so
+    // a child's requests land in that turn's usage record instead of vanishing —
+    // `/usage` counted a fan-out as zero while `/budget` counted it in full. The
+    // orchestrator is built once per session and the collector is built once per
+    // `send`, and this tool call is the only thing that crosses between them.
+    //
+    // COPIED, NEVER MUTATED. The session hands the same `ctx` object to every turn
+    // and every subagent; writing this turn's sink onto it would leave the field
+    // pointing at a finished turn's collector for the rest of the session, and
+    // entries would then be filed under a run that had already been written out.
+    const toolCtx = args.onRequestUsage
+        ? { ...ctx, onRequestUsage: args.onRequestUsage }
+        : ctx;
     // Work on a copy so we never mutate the caller's array as a side effect; the
     // extended history is returned for the caller to adopt. Reassigned wholesale
     // when the mid-loop compaction seam folds away an older prefix.
@@ -272,7 +287,7 @@ routed) {
                 toolResults.push(blocked);
                 continue;
             }
-            const result = await runToolCall(call, registry, ctx);
+            const result = await runToolCall(call, registry, toolCtx);
             renderer?.toolLifecycle({ event: "end", label, ok: !result.is_error });
             toolResults.push(result);
             // after-tool + on-file-change (C.19): fire once the action is done.

package/dist/agent/session.js

@@ -237,7 +237,10 @@ export class Session {
         // every real model request this turn drives — the main loop, compaction, and
         // (in plan mode) the propose + execution steps — so usage is captured exactly
         // where the provider reports it, honestly (unknown when it reports nothing).
-        const collector = new UsageCollector();
+        // `"turn"` is the DEFAULT origin, not a blanket label (cli#244): this same
+        // collector also receives every subagent this turn spawns, and those arrive
+        // already tagged `"subagent"` so they are not filed as things the user did.
+        const collector = new UsageCollector(undefined, "turn");
         const startedAt = new Date().toISOString();
         const onReq = (req) => collector.record(req);
         // Compact *before* the agent call so the turn runs against a bounded history.
@@ -326,13 +329,25 @@ export class Session {
         const record = collector.toRecord(randomUUID(), this.sessionId, startedAt);
         this.lastRun = record;
         this.args.onRunUsage?.(record);
-        // The budget draws down from the SAME record the usage store persists, so
-        // `/budget` and `/usage` can never report different spends for THIS turn's
-        // own requests. They can differ by a subagent's worth: the orchestrator
-        // folds each child's spend into the budget (cli#212 — an admission check
-        // whose own dispatches never move the numerator is not a check) and does not
-        // write child runs to the store. See the note at that call site.
-        this.args.budget?.record(record);
+        // THE STORE GETS EVERY ENTRY; THE BUDGET GETS ONLY THE TURN'S OWN.
+        //
+        // Since cli#244 this record also carries the requests of every subagent the
+        // turn spawned, which is what finally makes `/usage` and `/budget` agree for
+        // one scope. But the orchestrator ALREADY folded each child into the budget
+        // the moment that child finished — it has to, because the next admission
+        // check inside this same turn must see the spend (cli#212/#243), and end of
+        // turn is far too late for that. Handing the same entries over a second time
+        // here would count a fan-out twice and halve the effective session cap on
+        // exactly the turns most likely to need it.
+        //
+        // So the filter is not a detail: it is the seam between an immediate fold
+        // for admission and a deferred one for accounting. Anything that gets its
+        // own `budget.record` elsewhere — a subagent here, and a background job or a
+        // forced `/compact` in their own records — must be excluded from this one.
+        this.args.budget?.record({
+            ...record,
+            entries: record.entries.filter((e) => e.origin !== "subagent"),
+        });
         // after-run (C.19): advisory by default (a blocking after-run hook throws
         // and surfaces at the boundary). The turn already completed and its history
         // is adopted above — an advisory failure never rewrites it.
@@ -424,8 +439,46 @@ export class Session {
      * cut or the summary call failed.
      */
     async compact() {
-        const { messages, compacted } = await this.runCompaction(this.messages);
+        // A FORCED COMPACTION IS A REAL REQUEST, AND IT GETS A RECORD (cli#254).
+        //
+        // Every other compaction path already threads the caller's sink — the
+        // automatic threshold check, the mid-loop seam — and this one dropped it at
+        // the top, so the summarize call's tokens reached neither the store nor the
+        // budget. `Session.usage` did accumulate them (see `runCompaction`), but
+        // nothing reports off that field, so the spend was effectively invisible on
+        // a request the user explicitly asked for.
+        //
+        // IT CANNOT FOLLOW PLAN MODE'S PRECEDENT, which is why this is not the
+        // one-line fix it looks like. Plan mode threads `onRequestUsage` into the
+        // parent turn's collector because it runs INSIDE `send`, where that
+        // collector is a live local. `/compact` is a slash command dispatched
+        // between turns: there is no run in flight, so there is no collector to
+        // reach. It builds its own and publishes through the two sinks the session
+        // already holds — the same shape a background job needs, and for the same
+        // reason (no turn to belong to).
+        //
+        // Origin `"compact"` rather than `"turn"` or nothing. Not `"turn"`: it is
+        // not one, and `runCount` would then count a turn the user never took.
+        // Not unattributed either — absence means "written by a build before the
+        // field existed", and borrowing that bucket would make a current record
+        // indistinguishable from history (see `UsageEntry.origin`).
+        const collector = new UsageCollector(undefined, "compact");
+        const startedAt = new Date().toISOString();
+        const { messages, compacted } = await this.runCompaction(this.messages, (req) => collector.record(req));
         this.messages = messages;
+        // Nothing to publish when nothing was spent: `runCompaction` returns early
+        // when there is no clean cut, without calling the model at all. An empty
+        // record would pad `runCount` and shorten the store's retention window to
+        // say that a `/compact` did nothing.
+        if (collector.count > 0) {
+            const record = collector.toRecord(randomUUID(), this.sessionId, startedAt);
+            this.args.onRunUsage?.(record);
+            // Unfiltered, unlike the turn's fold: these entries are this record's own
+            // and nothing else has handed them over. `lastRun` is deliberately NOT
+            // moved — the one-shot prints it as the run's usage, and a compaction is
+            // not the run the user asked about.
+            this.args.budget?.record(record);
+        }
         return compacted;
     }
     /**

package/dist/approval/classify.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { captureExclusion } from "../checkpoint/coverage.js";
+import { ceilingExclusion } from "../checkpoint/coverage.js";
 /**
  * Classify a pending tool action into a {@link RiskTier} + a tight session
  * {@link Scope}. The cardinal rule: **anything unrecognized is `destructive`**
@@ -48,10 +48,9 @@ export function classify(action, cwd) {
  *
  *   • `capture.ts` enumerates with `git ls-files --cached --others
  *     --exclude-standard` — tracked + untracked-non-ignored files **under one
- *     root** — and then filters that list through
- *     {@link captureExclusion}. So: nothing outside a declared root, nothing
- *     gitignored, and nothing under `.git/`, `node_modules/`, `.cruxy/`, or the
- *     secrets denylist.
+ *     root** — and then filters that list through `captureExclusion`. So:
+ *     nothing outside a declared root, nothing gitignored, and nothing under
+ *     `.git/`, `node_modules/`, `.cruxy/`, or the secrets denylist.
  *   • Only file *content* and the executable bit ({@link CaptureFile.mode} is
  *     `100644` or `100755`). Not the rest of the permission word, not ownership,
  *     not flags. And regular files only — a symlink is skipped on capture and
@@ -74,6 +73,18 @@ export function classify(action, cwd) {
  * the capturer itself filters on, so the ceiling cannot drift from the snapshot
  * again.
  *
+ * ── Stricter than the snapshot, on purpose (cli#241, the narrow slice) ──
+ * The rules read {@link ceilingExclusion}, not `captureExclusion`. The two differ
+ * by `CEILING_ONLY`: a short list of filename classes the capturer should keep
+ * snapshotting when a repo tracks them, and auto-approve should stop assuming it
+ * can put back — Terraform state, a local database, a `*.local.*` config. Those
+ * are the paths that are usually gitignored (so in no snapshot AND in no commit)
+ * and whose contents no build, registry, or `.tf` file can reconstruct.
+ *
+ * It is asymmetric by design. Widening `captureExclusion` to cover them would
+ * make the *snapshot* skip a `dist/` or a `terraform.tfstate` that a repo tracks,
+ * closing a prompt by opening a hole. Widening the ceiling costs one prompt.
+ *
  * ── Braces and belt ──
  * The rules that fail *closed*, needing no list to be correct: an unprovable
  * command (any shell metacharacter); an argument resolving outside the root; an
@@ -83,16 +94,65 @@ export function classify(action, cwd) {
  *
  * {@link ESCAPES_ROOT} and {@link MUTATES_UNCAPTURED_STATE} are the belt: two
  * denylists of program names, and denylists lose — `node deploy.js` still
- * reaches the network (cli#194), and `install -m 000` still evades the
- * permission rule. A name is a prediction about what a program will do, so it
- * cannot fail closed by construction. The end of that argument is confinement
- * keyed on the *mode* rather than the program, which cli#194 tracks; these lists
- * are what holds until then, not a sandbox.
+ * reaches the network, and `install -m 000` still evades the permission rule. A
+ * name is a prediction about what a program will do, so it cannot fail closed by
+ * construction. Why the belt is still a denylist, and what the alternative
+ * would and would not have bought, is the cli#194 section at the end of this
+ * block.
+ *
+ * One residual is deliberate, named, and **accepted rather than pending**:
+ * generic **gitignored** paths (`rm -rf dist` in a repo that ignores `dist/`)
+ * cannot be decided from a path alone — it needs the repo's ignore files, and
+ * this classifier is pure and synchronous by design. cli#241 records why the
+ * remedies are worse than the residual, and why the permanent-loss subset was
+ * split out into `CEILING_ONLY` instead. The cost is paid in both directions and
+ * both were taken knowingly: `rm -rf dist` in a repo that ignores `dist/` still
+ * auto-runs (regenerable — that is the whole selection rule), and a
+ * `CEILING_ONLY` path the repo actually *tracks* — a committed
+ * `terraform.tfstate`, a `*.sqlite` test fixture — is in the snapshot and prompts
+ * anyway, because a path-only rule cannot tell that repo from the one that
+ * ignores it.
+ *
+ * ── Why the belt stays a denylist (cli#194, accepted, not built) ──
+ * The end of the denylists-lose argument is a rule keyed on the *mode* rather
+ * than the program: an auto-approving mode may only run what it can confine, so
+ * `node deploy.js` reaches no registry because there is no route — not because
+ * we recognised a name. That shape is right, for the reason every other rule
+ * here is right: it is a fact about our own configuration, decidable before a
+ * command is even read, and it fails closed by construction because an
+ * unconfigured sandbox means the mode is simply unavailable. It is not being
+ * built, and both reasons live here rather than in the issue, because this is
+ * the file that would have changed.
+ *
+ * **Confinement is not equivalent to the host.** `sandbox/policy.ts:36-40`
+ * bind-mounts the cwd read-write at its identical absolute path, so the
+ * container inherits the *host's* `node_modules`: darwin-arm64 `.node` binaries
+ * loaded under a linux/arm64 image, with `--network none` forbidding the
+ * reinstall that would fix them, a `--read-only` rootfs, and a 64m `/tmp`. This
+ * repo's own suite goes red in the box. cli#194's own argument then turns on
+ * it — a gate people read as noise is a gate they stop reading, and a mode that
+ * reddens your suite is a mode nobody arms.
+ *
+ * **And the rule would disarm the mode by default.** `sandbox.enabled` is
+ * `false` (`config/schema.ts:417`), so "no confinement, no auto-approval" makes
+ * auto-approve unavailable-by-default for every user on every platform until
+ * they stand up a container runtime. That is the product decision the issue was
+ * actually asking for, and the answer is no.
+ *
+ * What confinement WOULD have bought, stated precisely so the residual is not
+ * over-claimed: for the **shell + test execution surface only**, `ESCAPES_ROOT`
+ * stops being load-bearing on the auto-approve path. Nothing else. `ctx.sandbox`
+ * is consulted at `tools/shell/exec.ts:80` and `testing/run-tests-tool.ts:196`
+ * and nowhere else — `write_file`, `edit_file`, and `apply_patch` execute on the
+ * host in every mode, confined or not.
  *
- * One residual is deliberate and named: generic **gitignored** paths (`rm -rf
- * dist`) cannot be decided from a path alone — it needs the repo's ignore files,
- * and this classifier is pure and synchronous by design. See
- * {@link captureExclusion} for why that tail is the low-value one.
+ * Nor does the belt demote to a UX nicety even for that surface, because
+ * `irreversible` gates the GRANT path as well as the auto path:
+ * `SessionAllowlist.allows` refuses every irreversible request (cli#193), and
+ * manual mode is never confined. A `curl` misclassified as reversible would let
+ * "allow `curl` this session" cover every later `curl` — unprompted, on the
+ * host, for the rest of the session. These lists stay security-relevant on the
+ * grant path in every mode, sandbox or no sandbox.
  */
 /**
  * `git` subcommands that only read. Everything else `git` does is irreversible
@@ -256,10 +316,12 @@ function shellIrreversibility(command, root) {
  * Decidable from the SCOPE ALONE, which is the whole reason this can be a
  * function rather than a guess:
  *
- *   • `mcp-tool` — {@link mcpRequest} marks every MCP call irreversible
- *     unconditionally, so no request can clear the ceiling. Blocked, not dead
- *     code: the fix is #239's per-tool judgement, and on the day that lands
- *     these grants start working with no change here.
+ *   • `mcp-tool` — {@link mcpRequest} marks every MCP call irreversible, so no
+ *     request can clear the ceiling and no such grant can ever match. Settled
+ *     rather than pending (#239, closed as accepted): the arguments of any MCP
+ *     call reach a process no checkpoint reaches, which is as true of
+ *     `read_file_content` as of `slack_send_message`. Permanently inert by
+ *     design, not waiting on a fix.
  *   • `shell-exact` (a test grant) — the scope carries the exact command and
  *     root, and {@link testRequest} derives `irreversible` from those same two
  *     values through this same function. Same inputs, same verdict, every time:
@@ -278,7 +340,7 @@ function shellIrreversibility(command, root) {
  */
 export function deadGrantReason(scope) {
     if (scope.kind === "mcp-tool") {
-        return "every MCP call is classified irreversible, so the ceiling refuses this grant before it is ever matched (cli#239)";
+        return "every MCP call is irreversible — its arguments reach a process no checkpoint can reach — so the ceiling refuses this grant before it is ever matched";
     }
     if (scope.kind === "shell-exact") {
         return shellIrreversibility(scope.command, scope.root);
@@ -318,8 +380,10 @@ function argIrreversibility(arg, root) {
  * checkpoint could not restore `abs`, or `null` when it could. `label` is what
  * the message names — the token the user actually typed, for a shell argument.
  *
- * Three ways a path falls outside the snapshot, and the last two are cli#241:
- * being outside the root was never the only one.
+ * Four ways a path falls outside what a restore can put back, and the last three
+ * are cli#241: being outside the root was never the only one. The fourth is the
+ * ceiling being deliberately stricter than the snapshot — see
+ * {@link ceilingExclusion}.
  */
 function pathIrreversibility(abs, root, label = abs) {
     if (!isInside(root, abs)) {
@@ -332,10 +396,11 @@ function pathIrreversibility(abs, root, label = abs) {
         return `\`${label}\` names the workspace root itself, which contains paths the checkpoint does not capture (\`.git/\`, ignored output, secrets)`;
     }
     const rel = path.relative(root, abs).split(path.sep).join("/");
-    const excluded = captureExclusion(rel);
-    return excluded
-        ? `\`${label}\` is not captured by the checkpoint — ${excluded}`
-        : null;
+    // A predicate phrase, not a bare reason: the ceiling distinguishes "the
+    // snapshot never holds this" from "the snapshot may hold this and must not be
+    // relied on to", and only it knows which one fired.
+    const verdict = ceilingExclusion(rel);
+    return verdict ? `\`${label}\` ${verdict}` : null;
 }
 /**
  * Why the checkpoint cannot restore a file action, or `null` when it can.
@@ -500,12 +565,80 @@ function rollbackRequest(action, root) {
 const ROLLBACK_IRREVERSIBLE = "a rollback overwrites the working tree and is not itself checkpointed, so the current state would be unrecoverable";
 // ── mcp (call an external MCP server's tool, C.27) ──────────────────────────────
 /**
- * An MCP tool call. Always `destructive` — the tool is arbitrary code in a
- * trusted-but-external server, running UNSANDBOXED. Crucially, the classifier
- * NEVER consults the server's `readOnlyHint` (or any server-supplied
- * annotation): a server cannot mark its own tool low-risk, so this can only ever
- * be destructive. Grantable at the tightest scope — the exact server+tool pair —
- * so approving one MCP tool for the session never widens to any other tool.
+ * An MCP tool call. Always `destructive`, and always `irreversible`. The second
+ * of those was the contested one; #239 is where it was settled, and this is the
+ * argument, kept here rather than in a ticket because a closed ticket is not
+ * where the next person will look.
+ *
+ * WHY ONE VERDICT FOR EVERY TOOL IS THE ACCURATE ONE, NOT THE LAZY ONE. It reads
+ * like the classifier declining to judge: `slack_send_message` cannot be unsent
+ * and `read_file_content` changes nothing, yet both come back irreversible. But
+ * the question this field asks is not "does the tool mutate something" — it is
+ * "does the checkpoint taken before this action provably contain everything the
+ * action can damage" (see {@link ApprovalRequest.irreversible}). Every MCP call,
+ * read or write, hands its ARGUMENTS to a process cruxy neither controls nor can
+ * roll back: another machine for a `url` server, an unsandboxed child for stdio.
+ * Data that has left cannot be recalled and no checkpoint contains it. That
+ * effect is identical for every tool on every server, so a verdict identical for
+ * every tool is the one that matches the facts. The judgement is per-tool
+ * INVARIANT, which is not the same as absent.
+ *
+ * The honest limit: a stdio server doing pure local arithmetic exfiltrates
+ * nothing, and for that one the blanket verdict really is too strong. Telling it
+ * apart from the others is exactly what cannot be done from here — and this
+ * file's cardinal rule already says what to do with an action it cannot bound.
+ *
+ * WHY NOT THE SERVER'S OWN ANNOTATIONS. MCP defines `readOnlyHint`,
+ * `destructiveHint`, and `idempotentHint`. Cruxy reads none of them, at three
+ * layers: `McpClient`'s `RawToolSchema` accepts only name/description/inputSchema
+ * so zod strips `annotations` at the wire boundary, `mcp/adapter.ts` forwards no
+ * hint, and nothing carrying one reaches this function. Deliberate, pinned by
+ * test, and for four reasons that stack:
+ *
+ *   1. THE SPEC SAYS NOT TO. "Clients MUST consider tool annotations to be
+ *      untrusted unless they come from trusted servers."
+ *   2. CRUXY CANNOT PRODUCE A "TRUSTED SERVER" IN THE SENSE THAT CARVE-OUT
+ *      NEEDS. `fingerprintMcpServers` hashes the INVOCATION — server id,
+ *      `command`, `args`, `url`, `env`, `credentialRef`, header names — and not
+ *      the code. A trusted stdio server whose package auto-updates keeps an
+ *      identical fingerprint while running entirely different code, and
+ *      `mcp/types.ts` says the equivalent for a url server's behavior. Trust here
+ *      means "I accept running this", never "I have checked what it says about
+ *      itself".
+ *   3. IT WOULD MAKE THE TOOL LIST A PRIVILEGE-GRANTING CHANNEL. Today a lying
+ *      server gets its lie demarcated as untrusted data and nothing more. If one
+ *      boolean in that same list decided whether the ceiling applies, a server
+ *      could set `readOnlyHint: true`, collect a single "allow re-calls of this
+ *      tool", and run unprompted from then on — and `notifications/tools/
+ *      list_changed` lets it re-advertise mid-session. The party being gated
+ *      would control the gate.
+ *   4. EVEN AN HONEST ANNOTATION ANSWERS A DIFFERENT QUESTION. `readOnlyHint`
+ *      describes effects on the SERVER's state. It says nothing about the
+ *      arguments travelling to it, which is the effect above — and the spec names
+ *      that risk separately in its own client guidance: "Show tool inputs to the
+ *      user before calling the server, to avoid malicious or accidental data
+ *      exfiltration."
+ *
+ * WHAT WAS CONSIDERED INSTEAD. Tool-name heuristics are worse than the denylist
+ * residual tracked in #194, not merely as bad: there the program name comes from
+ * the user's own command, here the string is chosen by the untrusted server, so a
+ * server that wants a standing grant simply names its tool `read_status`. A
+ * user-declared per-tool reversibility list is the only option grounded in a user
+ * assertion rather than a server claim, but the user's evidence for the assertion
+ * is the server's own description of the tool, it would have to be user-scope
+ * only (a cloned repo must not ship its own reversibility assertions — the rule
+ * `headers` already lives under), and described plainly it is auto-approve in a
+ * different coat. A first-use "is this reversible?" prompt is worse again: a
+ * second prompt stacked on the approval prompt, asking a question the user cannot
+ * answer better than this function can, whose answer would have to be persisted —
+ * and `mcp-trust.json` is deliberately the ONLY persisted security decision in
+ * the product. The one approach that would actually hold is to stop predicting
+ * and start observing — sandbox stdio servers with egress denied — which is the
+ * same answer #194 reaches, and which does not apply to url servers at all.
+ *
+ * Grantable at the tightest scope — the exact server+tool pair — so approving one
+ * MCP tool never widens to any other. That scope is permanently inert as a
+ * consequence of the verdict above; {@link Scope} explains why it is kept anyway.
  */
 function mcpRequest(action, root) {
     const server = action.server ?? "";
@@ -520,15 +653,12 @@ function mcpRequest(action, root) {
         summary: `call MCP tool ${tool || "(unknown)"} on server ${server || "(unknown)"}`,
         targets: [],
         cwd: root,
-        // Same reasoning as the tier: the server cannot vouch for itself. A
-        // `readOnlyHint` is a claim by the thing being gated, and the checkpoint
-        // cannot reach whatever it did anyway.
-        //
-        // But it is unconditional, which is this classifier declining to judge —
-        // and since cli#193 (the ceiling outranks grants) that verdict is what makes
-        // the `mcp-tool` scope above unreachable. Tracked in #239; the fix is a
-        // per-tool judgement here, never a ceiling carve-out for MCP.
-        irreversible: "an MCP tool runs unsandboxed in an external server, so its effects are outside the checkpoint entirely",
+        // Per-tool INVARIANT, not per-tool absent: the arguments leave for a process
+        // the checkpoint cannot reach whatever the tool does with them afterwards.
+        // The reason names the arguments explicitly, because "it ran externally" is
+        // the half a user already assumed and the sent data is the half they may not
+        // have. Never a ceiling carve-out for MCP — see the block above.
+        irreversible: "an MCP tool runs unsandboxed in an external server, so its effects — including the arguments it was sent — are outside the checkpoint entirely",
     };
 }
 // ── file (write / edit / patch) ────────────────────────────────────────────────

package/dist/approval/prompt.js

@@ -4,6 +4,7 @@ import { renderActionPreview } from "../render/diff.js";
 import { resolveColumns } from "../render/capabilities.js";
 import { fitMiddle, reflow, visibleWidth } from "../render/layout.js";
 import { themeForColor } from "../theme/index.js";
+import { deadGrantReason } from "./classify.js";
 /**
  * Render the action, read one key, and map it to a {@link PromptChoice}. `n`/`t`
  * read a follow-up line (reason / instruction). Anything else — including EOF —
@@ -175,13 +176,58 @@ function detail(request, t, width) {
     }
     return renderActionPreview(request.action.preview, t, width);
 }
-/** The choices line, including a short label of what an `a` grant would cover. */
+/**
+ * The choices line, including a short label of what an `a` grant would cover —
+ * and, when it would cover nothing, saying so instead of offering it.
+ *
+ * THREE STATES, NOT TWO. A scope is unnameable (`none` — there is nothing to
+ * grant), or nameable and spendable, or nameable and **inert**: a grant the
+ * allowlist will happily record and {@link SessionAllowlist.allows} can never
+ * honor, because every action the scope could match is refused by the ceiling
+ * before any scope matching happens (cli#193). This line rendered the third
+ * exactly like the second, so the user consented to something that bought
+ * nothing and only found out at the NEXT prompt, from the #193 override line.
+ * That ordering is backwards: the override line explains a grant already given,
+ * and the place to decline a grant is the place it is asked for.
+ *
+ * THE PREDICATE IS {@link deadGrantReason}, NOT `request.irreversible`, and the
+ * difference is the whole correctness of this function. `irreversible` is about
+ * THIS action; a dead grant is about whether the SCOPE can ever match a
+ * reversible one. They part company on `shell-prefix`: `git push --force` is
+ * irreversible, so {@link whyAsking} fires — but a `git` grant still covers
+ * `git log`, so it is narrow, not dead, and must stay on offer. Gating this line
+ * on `irreversible` would withdraw a live grant every time the action in front
+ * of it happened to be one the grant could not have covered anyway.
+ *
+ * THE REASON IS NOT REPEATED HERE. A grant is inert only because its actions are
+ * irreversible, so `whyAsking` has already printed the concrete reason one line
+ * up. A second copy on the choices line would add no fact and spend the width
+ * that keeps this line readable at 80 columns.
+ */
 function choices(scope, t) {
-    const grant = scopeLabel(scope);
-    const a = grant === null
-        ? `${t.muted("[a] allow this kind (n/a here)")}`
-        : `[a] allow ${t.strong(grant)} this session`;
-    return `  ${t.muted(`[y] approve once ${t.glyph.sep}`)} ${a} ${t.muted(`${t.glyph.sep} [n] reject ${t.glyph.sep} [t] reject & instruct:`)}`;
+    return `  ${t.muted(`[y] approve once ${t.glyph.sep}`)} ${grantChoice(scope, t)} ${t.muted(`${t.glyph.sep} [n] reject ${t.glyph.sep} [t] reject & instruct:`)}`;
+}
+/**
+ * The `[a]` clause alone: a live offer, or a muted statement that there is none.
+ *
+ * An inert grant is still NAMED. "(n/a here)" is right for `none`, where there
+ * was never anything to describe, but a user looking at an MCP call or a `curl`
+ * is owed the specific thing being declined — otherwise the line reads as the
+ * prompt having no opinion rather than a considered "not this one". The label is
+ * {@link scopeLabel}'s, so the words match everywhere a grant is ever spoken of.
+ */
+function grantChoice(scope, t) {
+    const nothingToGrant = t.muted("[a] allow this kind (n/a here)");
+    if (scope.kind === "none")
+        return nothingToGrant;
+    const label = scopeLabel(scope);
+    // Unreachable — `scopeLabel` answers null only for `none` — but this is the
+    // narrowing that lets the compiler prove it, not a guess about behavior.
+    if (label === null)
+        return nothingToGrant;
+    if (deadGrantReason(scope) !== null)
+        return t.muted(`[a] allow ${label} (n/a — this always asks)`);
+    return `[a] allow ${t.strong(label)} this session`;
 }
 /**
  * Short human label for what a session grant covers, or null when a scope

package/dist/approval/service.js

@@ -1,19 +1,13 @@
 import { approvalRequired } from "../errors/index.js";
-import { shouldUseColor } from "../errors/index.js";
 import { classify } from "./classify.js";
-import { InteractivePolicy, SessionAllowlist } from "./policy.js";
-import { defaultPromptIO } from "./prompt.js";
 export class ApprovalService {
     cwd;
     interactive;
-    allowlist = new SessionAllowlist();
     policy;
     constructor(opts) {
         this.cwd = opts.cwd;
         this.interactive = opts.interactive;
-        this.policy =
-            opts.policy ??
-                new InteractivePolicy(this.allowlist, opts.io ?? defaultPromptIO(shouldUseColor()));
+        this.policy = opts.policy;
     }
     /**
      * Decide whether `action` may proceed. Read-only ⇒ allow. Non-interactive ⇒
@@ -30,8 +24,4 @@ export class ApprovalService {
         }
         return this.policy.decide(request);
     }
-    /** Clear all session grants (a fresh session). */
-    resetSession() {
-        this.allowlist.clear();
-    }
 }

package/dist/budget/session-budget.js

@@ -206,13 +206,22 @@ export class SessionBudget {
         // with its token cap cut to what the allowance covers — refusing outright
         // would leave a user with real headroom unable to ask anything at all. A
         // fan-out of many, though, is narrowed to exactly one.
+        //
+        // "RUN", NOT "TURN" (cli#245). `count: 1` used to mean a turn and the reason
+        // said so; it now also reaches here from a lone `spawn` and from a
+        // background job, and this is a SHARED decision object — one string handed
+        // to whoever asked. Naming the caller would make the sentence false for two
+        // of the three, and branching on which one asked would put caller knowledge
+        // inside the one place that deliberately has none. `run` is the word this
+        // module already uses for all three (see `AdmissionRequest.count`), and it
+        // is true of each.
         const cap = Math.max(1, Math.floor(allowance.weighted / multiplier));
         if (req.count === 1) {
             return {
                 kind: "narrowed",
                 count: 1,
                 maxTokens: cap,
-                reason: `capped this turn at ${compactTokens(cap)} tokens — ` +
+                reason: `capped this run at ${compactTokens(cap)} tokens — ` +
                     `${allowanceLabel(allowance)} leaves room for about that much on ${req.tier}`,
             };
         }