@cruxy/cli 1.7.1 → 1.8.0

package/dist/limits/reduce.js

@@ -144,15 +144,26 @@ export function reduceLimits(res, readAt = Date.now()) {
         readAt,
     };
 }
+/**
+ * TWO SELECTORS, TWO QUESTIONS. {@link bindingWindow} answers *which window will
+ * stop you first*; {@link scarcestWindow} answers *how much may you actually
+ * spend right now*. They are not the same question and they do not always pick
+ * the same window, so merging them would make one of the two answers wrong —
+ * see each function for which.
+ */
 /**
  * The window that will stop this user FIRST — the one the gate itself calls
  * binding: whichever of monthly/burst has the smaller REMAINING fraction
  * (`internal/budget/decide.go`).
  *
- * This is what earns the single bar the rail has room for. Drawing the month
- * because it is the bigger number would routinely show a comfortable 6% while
- * the trailing-12h window — a quarter of the month's cap on every self-serve
- * tier — is the one about to refuse the next request.
+ * FOR DISPLAY. This is what earns the single bar the rail has room for. Drawing
+ * the month because it is the bigger number would routinely show a comfortable
+ * 6% while the trailing-12h window — a quarter of the month's cap on every
+ * self-serve tier — is the one about to refuse the next request.
+ *
+ * The fraction is right HERE because a bar is a fraction: the pixels state
+ * proportion, so the window drawn must be the one whose proportion is the
+ * warning. It is wrong for admission, and {@link scarcestWindow} says why.
  */
 export function bindingWindow(monthly, burst) {
     if (!monthly)
@@ -164,6 +175,37 @@ export function bindingWindow(monthly, burst) {
         ? { window: burst, name: "burst" }
         : { window: monthly, name: "month" };
 }
+/**
+ * The window with the least ABSOLUTE remaining — the ceiling an admission check
+ * must respect (cli#212).
+ *
+ * FOR ADMISSION. BOTH windows gate every request, so a draw of D is admitted
+ * only when `D ≤ monthly.remaining` AND `D ≤ burst.remaining` — which makes the
+ * spendable allowance exactly `min(remaining)`, a number of tokens rather than
+ * a proportion.
+ *
+ * WHY {@link bindingWindow} CANNOT SERVE HERE, concretely: a Core user 5% into
+ * the month (700k of 14M left) whose burst is at 14% (500k of 3.5M left). The
+ * fraction rule names the month, correctly — 5% is the figure worth showing.
+ * But handing 700k to an admission check authorises a batch the burst will
+ * refuse at 500k, and it refuses it AFTER the tokens are spent, against a
+ * sliding window that refills only by trickle over twelve hours. The two rules
+ * disagree exactly when the caps differ by 4×, which is to say on every
+ * self-serve tier, in the ordinary case rather than a corner one.
+ *
+ * The error is one-directional, which is why it is worth two functions: erring
+ * toward the smaller remainder narrows a fan-out that might have fitted, and
+ * erring toward the larger one spends a window that cannot be un-spent.
+ */
+export function scarcestWindow(monthly, burst) {
+    if (!monthly)
+        return burst ? { window: burst, name: "burst" } : undefined;
+    if (!burst)
+        return { window: monthly, name: "month" };
+    return burst.remaining < monthly.remaining
+        ? { window: burst, name: "burst" }
+        : { window: monthly, name: "month" };
+}
 /** The fraction of a cap consumed, clamped to [0,1] for display. */
 export function usedFraction(w) {
     if (!usableCap(w.cap))

package/dist/mcp/bounds.js

@@ -1,3 +1,4 @@
+import { MAX_SCHEMA_DEPTH, schemaDepth } from "../tools/schema-depth.js";
 const PERMISSIVE_SCHEMA = {
     type: "object",
     additionalProperties: true,
@@ -5,9 +6,16 @@ const PERMISSIVE_SCHEMA = {
 /**
  * Apply the bounds to a raw `tools/list`. Over the count cap → keep the first N
  * (by advertised order) and report `droppedCount`. Per tool: an over-long
- * description is truncated with a marker; an over-size input schema is replaced
- * with a permissive `object` schema and a note (we never forward an unbounded
- * schema, but we also never claim the args are constrained when we dropped it).
+ * description is truncated with a marker; an over-size OR over-deep input schema
+ * is replaced with a permissive `object` schema and a note (we never forward an
+ * unbounded or unsendable schema, but we also never claim the args are
+ * constrained when we dropped it).
+ *
+ * Degrading beats dying, and it is the same trade the byte cap already makes: an
+ * over-deep tool stays callable with unconstrained args and a visible note,
+ * rather than taking the session down with it. Nothing is lost locally by the
+ * swap — the adapter delegates arg validation to the server either way
+ * (`PASSTHROUGH`), and the approval gate is untouched.
  */
 export function boundToolList(tools, bounds) {
     const kept = tools.slice(0, bounds.maxTools);
@@ -30,6 +38,16 @@ export function boundToolList(tools, bounds) {
             inputSchema = { ...PERMISSIVE_SCHEMA };
             notes.push(`input schema (${schemaBytes} bytes) exceeded the ${bounds.maxSchemaBytes}-byte cap and was replaced with a permissive one`);
         }
+        // ORDER MATTERS: depth is measured on the POST-byte-cap value. A schema the
+        // byte cap already replaced is permissive (depth 1) and passes trivially, so
+        // the only schema this counter ever walks is one that fit `maxSchemaBytes` —
+        // which is what bounds the walk. Measuring the raw schema first would hand a
+        // hostile server an unbounded one.
+        const depth = schemaDepth(inputSchema);
+        if (depth >= MAX_SCHEMA_DEPTH) {
+            inputSchema = { ...PERMISSIVE_SCHEMA };
+            notes.push(`input schema nests ${depth} levels deep, at or over the ${MAX_SCHEMA_DEPTH}-level provider limit, and was replaced with a permissive one`);
+        }
         return { name: t.name, description, inputSchema, notes };
     });
     return { tools: bounded, droppedCount };

package/dist/plan/policy.js

@@ -5,11 +5,23 @@
  * for the rest of the run, recording the real scope in the shared
  * {@link SessionAllowlist} so U.3's own scoping (`scopeCovers`) governs reuse.
  *
- * What it deliberately does NOT do — the two-tier boundary:
+ * What it deliberately does NOT do — the boundary, in three parts:
  *   • **destructive** actions always fall through to the base policy (prompt);
  *   • **ungrantable** actions (`scope:"none"`) always fall through (prompt),
  *     even if the tier is `mutate` — because `SessionAllowlist.grant` is a no-op
- *     on `none`, an ungrantable action can never be pre-approved.
+ *     on `none`, an ungrantable action can never be pre-approved;
+ *   • **irreversible** actions always fall through (prompt), even if the tier is
+ *     `mutate` AND the scope is grantable (cli#193). This is the only one of the
+ *     three that `tier` cannot express: a write to `/etc/passwd` is tier
+ *     `mutate` with a perfectly good exact-file scope, and the checkpoint still
+ *     cannot restore it. Without this clause, "approve + allow safe steps"
+ *     silently authorized exactly that for the rest of the run.
+ *
+ * That last clause is why it is checked HERE rather than left to the allowlist.
+ * The ceiling in `SessionAllowlist.allows` covers grants being *spent*; this
+ * branch never asks `allows()` — it is pre-consent, so it *writes* a grant. It
+ * is the one path into the allowlist that the chokepoint cannot defend, so it
+ * carries its own copy of the same rule.
  *
  * So approving a plan (even with "allow safe steps") never consents to a
  * destructive or irreversible action; those re-confirm at execution time.
@@ -27,14 +39,18 @@ export class PlanExecutionPolicy {
         this.safeStepGrants = true;
     }
     async decide(request) {
-        // Already covered by a prior session grant (scoped, tier-keyed) → allow.
+        // Already covered by a prior session grant (scoped, tier-keyed, and — since
+        // cli#193 — reversible; `allows` enforces the ceiling itself) → allow.
         if (this.allowlist.allows(request))
             return { allow: true };
-        // The one plan-mode shortcut: a grantable mutate action, pre-consented by
-        // the "allow safe steps" choice. Record its concrete scope, then allow.
+        // The one plan-mode shortcut: a grantable, REVERSIBLE mutate action,
+        // pre-consented by the "allow safe steps" choice. Record its concrete scope,
+        // then allow. `!request.irreversible` is load-bearing, not defensive — see
+        // the third bullet in this class's doc comment.
         if (this.safeStepGrants &&
             request.tier === "mutate" &&
-            request.scope.kind !== "none") {
+            request.scope.kind !== "none" &&
+            !request.irreversible) {
             this.allowlist.grant(request);
             return { allow: true };
         }

package/dist/render/permissions-view.js

@@ -0,0 +1,88 @@
+import { fit, reflow, visibleWidth } from "./layout.js";
+/**
+ * The ceiling, in one line.
+ *
+ * Stated as an ABSOLUTE, because since cli#193 it is one: `allows()` checks
+ * `irreversible` before it matches any scope, so there is no longer a "unless
+ * you granted it" clause to add. #196 asked this screen to be honest about the
+ * asymmetry; the honest version today is that the asymmetry is closed, and the
+ * cost — a granted `git` not covering `git commit` — is what the inert marks
+ * and the re-prompt copy explain.
+ */
+const CEILING = "irreversible actions always ask — in every mode, and no session grant outranks it";
+/**
+ * How wide the label column may grow. A grant label is usually short (`git
+ * commands`, `changes under src/`), but an exact-file grant or a test grant
+ * carries a path or a whole command, and one long row must not cost every other
+ * row its tier and root.
+ */
+const LABEL_MAX_COLS = 34;
+/** `key  value`, on the same gutter `/status` uses so the two screens align. */
+function row(key, value, t) {
+    return `  ${t.muted(key.padEnd(11))} ${value}`;
+}
+/** `2 standing · 1 inert`, or what an empty/unwired list has to say instead. */
+function grantSummary(grants, t) {
+    if (!grants)
+        return t.muted("not tracked in this session");
+    if (grants.length === 0) {
+        return t.muted("none — every action has been decided one at a time");
+    }
+    const dead = grants.filter((g) => g.dead).length;
+    const live = grants.length - dead;
+    const head = `${live} standing`;
+    return dead === 0
+        ? head
+        : `${head} ${t.warning(`${t.glyph.sep} ${dead} inert`)}`;
+}
+/** The full `/permissions` block as lines to print. */
+export function permissionsReportLines(report, t, width = Infinity) {
+    const lines = [t.heading("permissions")];
+    lines.push(row("mode", `${t.strong(report.mode)} ${t.muted(`— ${report.modeDescription}`)}`, t));
+    // The ceiling is the one row that is the same in every session, and it is here
+    // for exactly that reason: a screen listing what runs without asking has to
+    // state what asks anyway, next to it, or the list reads as the whole answer.
+    lines.push(row("ceiling", report.autoApproves ? t.warning(CEILING) : t.muted(CEILING), t));
+    lines.push(row("grants", grantSummary(report.grants, t), t));
+    if (report.grants && report.grants.length > 0) {
+        lines.push("");
+        // One label column, sized to the longest label the list actually holds and
+        // capped so a pathological grant (a long exact path, a long test command)
+        // cannot push the tier and the root off a normal terminal. Padded on the
+        // VISIBLE width, because a coloured label carries escape bytes that
+        // `padEnd` would count and the terminal would not.
+        const labelCols = Math.min(LABEL_MAX_COLS, Math.max(...report.grants.map((g) => visibleWidth(g.label))));
+        for (const g of report.grants) {
+            const n = t.muted(`${g.n}`.padStart(2));
+            const text = fit(g.label, labelCols, t.glyph.ellipsis);
+            const pad = " ".repeat(Math.max(0, labelCols - visibleWidth(text)));
+            const label = g.dead ? t.muted(text) : t.strong(text);
+            lines.push(`  ${n}  ${label}${pad}  ${t.muted(`${g.tier} ${t.glyph.sep} ${g.where}`)}`);
+            if (!g.dead)
+                continue;
+            // Why it can never match, on its own rows so the reason survives a narrow
+            // terminal intact — an inert grant the user cannot read the reason for is
+            // the same puzzle as an unmarked one.
+            const indent = "      ";
+            const room = Number.isFinite(width)
+                ? Math.max(20, width - indent.length)
+                : Infinity;
+            const reason = `inert — ${g.dead}`;
+            const wrapped = Number.isFinite(room) ? reflow(reason, room) : [reason];
+            for (const line of wrapped)
+                lines.push(`${indent}${t.warning(line)}`);
+        }
+    }
+    lines.push("");
+    // THE SCOPE OF THE SCREEN. Every background job builds its own
+    // ApprovalService with its own allowlist, so a job's grants are neither
+    // listed here nor revoked by anything typed here. A permissions screen that
+    // implied otherwise would be understating what the session can still do.
+    lines.push(t.muted("this is the foreground session only — each background job keeps its own grants"));
+    if (report.grants && report.grants.length > 0) {
+        lines.push(t.muted("/permissions revoke <n> drops one — actions already decided keep their decision"));
+    }
+    return Number.isFinite(width)
+        ? lines.map((l) => fit(l, width, t.glyph.ellipsis))
+        : lines;
+}

package/dist/render/state.js

@@ -43,9 +43,28 @@ export function describePhase(phase, glyph = UNICODE_GLYPHS) {
             const base = t && t.input + t.output > 0
                 ? `thinking${e} ${glyph.sep} tokens ${glyph.caretUp}${formatTokens(t.input)} ${glyph.caretDown}${formatTokens(t.output)}`
                 : `thinking${e}`;
-            // The real routing tier (C.30), appended honestly when present — same
-            // ` · ` joiner as the token counts.
-            return phase.tier ? `${base} ${glyph.sep} ${phase.tier}` : base;
+            // The real routing tier (C.30) and the effort the gateway says it applied,
+            // appended honestly when present — same ` · ` joiner as the token counts.
+            //
+            // Order matters under truncation. `fitStatusLine`'s last resort clips the
+            // TAIL, so what is appended last is shed first: effort goes before the
+            // tier, which goes before the token counts, which go before "thinking…".
+            // That is the intended priority — the tier answers "what ran", effort only
+            // refines it.
+            //
+            // Effort is labelled rather than shown bare. `kavi · none` beside a tier
+            // name reads as a second tier; `kavi · effort none` cannot. The label
+            // costs seven columns and buys the line's only defence against being
+            // misread, which is worth more here than seven columns are.
+            const parts = [base];
+            if (phase.tier)
+                parts.push(phase.tier);
+            // A present `none` is the gateway SAYING no reasoning ran — a real answer
+            // to "what actually ran", and the one this readout exists to make
+            // visible. Absent stays absent; see ServedRouting.reasoningEffort.
+            if (phase.effort)
+                parts.push(`effort ${phase.effort}`);
+            return parts.join(` ${glyph.sep} `);
         }
         case "calling-tool":
             return `${phase.label}${e}`;

package/dist/subagent/orchestrator.js

@@ -1,6 +1,8 @@
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { runAgent } from "../agent/loop.js";
-import { CruxyError, ErrorCode, messageOf, sessionBudgetExhausted, subagentDepthExceeded, subagentScopeOverlap, } from "../errors/index.js";
+import { classifyProviderError, CruxyError, ErrorCode, messageOf, sessionBudgetExhausted, subagentDepthExceeded, subagentScopeOverlap, } from "../errors/index.js";
+import { UsageCollector } from "../usage/index.js";
 import { UNRESOLVED_TIER, } from "../budget/index.js";
 import { resolveTaskModel } from "../routing/index.js";
 import { Workspace } from "../workspace/index.js";
@@ -52,10 +54,12 @@ export class SubagentOrchestrator {
      * withheld at the cap, so this throw is the fail-loud backstop.
      *
      * Never rejects on a *child* failure — provider or tool crashes come back as
-     * `status: "failed"` for the parent to reason over. The two exceptions that
-     * do propagate: the depth cap (above) and `CRUXY_E_APPROVAL_REQUIRED`
+     * `status: "failed"` for the parent to reason over. The three exceptions that
+     * do propagate: the depth cap (above), `CRUXY_E_APPROVAL_REQUIRED`
      * (non-interactive default-deny must reach the boundary, U.3 — a subagent is
-     * not a way to swallow it).
+     * not a way to swallow it), and `CRUXY_E_BUDGET_EXHAUSTED` (the weighted pool
+     * refused this child — see the catch block for why that one is not a partial
+     * result).
      */
     async spawn(spec, parentDepth, opts = {}) {
         const { deps } = this;
@@ -110,6 +114,57 @@ export class SubagentOrchestrator {
         // parent's messages are never in scope here, and this array dies with the
         // spawn — only the structured result below leaves this function.
         const messages = [{ role: "user", content: spec.task }];
+        // Per-request usage for THIS child, collected exactly as the parent's turn
+        // collects its own (`agent/session.ts`) — the loop reports one entry per
+        // completed request, with the tier that served it. Two things need it and
+        // neither can be got from `AgentResult.usage`: the weighted-pool arithmetic
+        // is per-tier, and a run that THREW has no `AgentResult` at all while still
+        // having spent whatever it spent before it died.
+        const usage = new UsageCollector();
+        const startedAt = new Date().toISOString();
+        try {
+            return await this.runChild({
+                spec,
+                opts,
+                messages,
+                registry,
+                budget,
+                ctx,
+                artifacts,
+                label,
+                noun,
+                tag,
+                usage,
+            });
+        }
+        finally {
+            // CHILD SPEND IS SESSION SPEND (cli#212). `budget.record` had exactly one
+            // call site — the parent's own turn — so a fan-out drew on the pool and
+            // left the numerator where it found it. The next admission check then
+            // divided by an allowance that had already been spent, which made the
+            // bound weakest at the moment it mattered most: the second fan-out of a
+            // session that had just dispatched three children.
+            //
+            // In the `finally` because the tokens are spent on every path out of here,
+            // including the two that throw. A child that died mid-run, or that a
+            // sibling's pool denial cancelled, still drew whatever it drew before it
+            // stopped, and the record is what it reported.
+            //
+            // NOT ALSO WRITTEN TO THE USAGE STORE. Child requests have never appeared
+            // in `/usage` and this does not change that — `/budget` now counts them
+            // and `/usage` still does not, so the two figures can differ by a
+            // fan-out's worth. That gap is real and pre-dates this; closing it means
+            // persisting child runs, which is a change to what is on disk and belongs
+            // in its own right rather than smuggled in behind an admission fix.
+            this.deps.budget?.record(usage.toRecord(randomUUID(), undefined, startedAt));
+        }
+    }
+    /** One child's run, from dispatch to structured result. Split out only so the
+     * usage fold above can be a `finally` over every path this can leave by. */
+    async runChild(args) {
+        const { deps } = this;
+        const { spec, opts, messages, registry, budget, ctx, artifacts } = args;
+        const { label, noun, tag, usage } = args;
         let run;
         try {
             run = await runAgent({
@@ -128,6 +183,7 @@ export class SubagentOrchestrator {
                 router: deps.router,
                 taskClass: spec.taskClass ?? "subagent",
                 signal: opts.signal,
+                onRequestUsage: (req) => usage.record(req),
             });
         }
         catch (err) {
@@ -136,6 +192,26 @@ export class SubagentOrchestrator {
                 deps.renderer?.setPhase(null);
                 throw err;
             }
+            // THE WEIGHTED POOL REFUSED THIS CHILD (429 `budget_exhausted`), and that
+            // is not a per-child outcome (cli#212). The pool is one denominator shared
+            // by every sibling, every other surface on the account, and the parent's
+            // own next request: nothing that is about to run can succeed, so folding
+            // this into a `failed` result would let each sibling walk into its own
+            // refusal — N denials for one fact, each after its tokens were spent.
+            //
+            // Rethrown as the TYPED error rather than the raw one so `code`,
+            // `window`, `resetAt` and `miraAvailable` survive to the boundary. The
+            // last of those is the only step that unblocks the user now rather than
+            // telling them when to come back, and flattening it into a message string
+            // is exactly how it used to be lost.
+            const denial = poolDenial(err);
+            if (denial) {
+                if (deps.renderer) {
+                    deps.renderer.note(`${deps.renderer.theme.glyph.failure} ${noun} stopped — ${denial.title}`);
+                }
+                deps.renderer?.setPhase(null);
+                throw denial;
+            }
             if (deps.renderer) {
                 deps.renderer.note(`${deps.renderer.theme.glyph.failure} ${noun} failed: ${label}`);
             }
@@ -146,13 +222,20 @@ export class SubagentOrchestrator {
                 ...artifactsField(artifacts),
                 error: `${ErrorCode.SubagentFailed}: ${messageOf(err) ?? "unknown error"}`,
                 iterations: 0,
-                usage: { input_tokens: 0, output_tokens: 0 },
+                // WHAT IT ACTUALLY SPENT, which is not zero and was reported as zero
+                // until now. A child that failed on its third request had two requests'
+                // tokens deducted from a pool the parent then went on to fan out
+                // against; a fabricated 0 put that spend nowhere. When NOTHING reported
+                // usage — the request died before the provider said anything — the
+                // field is absent, which the parent reads as unknown. Zero is reserved
+                // for a child that genuinely drew nothing.
+                ...usageField(usage),
             };
         }
         deps.renderer?.setPhase(null);
         const result = this.toResult(run, artifacts, label, noun);
         deps.logger.debug(`${noun} ${result.status}: ${result.iterations} turn(s), tokens in/out ` +
-            `${result.usage.input_tokens}/${result.usage.output_tokens} — ${label}`);
+            `${describeUsage(result.usage)} — ${label}`);
         return result;
     }
     /**
@@ -168,11 +251,18 @@ export class SubagentOrchestrator {
      *
      * Cancellation: children share one {@link AbortController}. A child returning a
      * `failed`/`budget-exceeded` result is a normal PARTIAL outcome — siblings run
-     * on. But a *fatal* throw from any child (non-interactive default-deny) or an
-     * abort on `opts.signal` (Ctrl-C) aborts the controller: every sibling stops at
-     * its next turn boundary and its in-flight shell child is kill-tree'd, so the
-     * fan-out leaves no orphan. All children are awaited to settle before a fatal
-     * throw propagates — never a detached, still-running sibling.
+     * on. But a *fatal* throw from any child (non-interactive default-deny, or a
+     * weighted-pool denial) or an abort on `opts.signal` (Ctrl-C) aborts the
+     * controller: every sibling stops at its next turn boundary and its in-flight
+     * shell child is kill-tree'd, so the fan-out leaves no orphan. All children are
+     * awaited to settle before a fatal throw propagates — never a detached,
+     * still-running sibling.
+     *
+     * THE POOL DENIAL IS THE ONE WORTH NAMING (cli#212). `budget_exhausted` is a
+     * statement about a denominator every sibling shares, so the first 429 is the
+     * whole batch's answer: without the abort, each remaining child walks into its
+     * own refusal and the parent gets N reports of one fact — each one arriving
+     * after that child had already spent what it spent getting there.
      */
     async spawnMany(specs, parentDepth, opts = {}) {
         const { maxDepth } = this.deps.config.subagent;
@@ -230,8 +320,11 @@ export class SubagentOrchestrator {
                     });
                 }
                 catch (err) {
-                    // A fatal throw (non-interactive default-deny) cancels the whole
-                    // fan-out — no sibling is left running — then propagates.
+                    // A fatal throw (non-interactive default-deny, or a weighted-pool
+                    // denial) cancels the whole fan-out — no sibling is left running —
+                    // then propagates. The abort is what makes the FIRST 429 the
+                    // batch's answer: siblings stop at their next turn boundary rather
+                    // than each spending its way into the same refusal.
                     controller.abort();
                     throw err;
                 }
@@ -396,6 +489,57 @@ function taskLabel(task) {
 function isWriter(spec) {
     return (spec.tools ?? []).some((t) => SUBAGENT_WRITE_TOOLS.has(t));
 }
+/**
+ * The typed pool denial behind an error, or `null` if it is not one.
+ *
+ * Two shapes reach here and both are the same fact: the raw SDK
+ * `BudgetExhaustedError` from this child's own request, and — when a child that
+ * itself spawned re-throws — the `CruxyError` a nested `spawn` already
+ * converted. Mapping goes through `classifyProviderError` so there is still ONE
+ * place that knows which SDK class means what.
+ */
+function poolDenial(err) {
+    if (CruxyError.is(err)) {
+        return err.code === ErrorCode.BudgetExhausted ? err : null;
+    }
+    const typed = classifyProviderError(err);
+    return typed?.code === ErrorCode.BudgetExhausted ? typed : null;
+}
+/**
+ * The tokens a child is KNOWN to have spent, or `undefined` when no request
+ * reported any.
+ *
+ * The loop fires `onRequestUsage` only for a request that COMPLETED, and when
+ * it does the provider's counts arrive as a pair or not at all — so an entry
+ * carries both figures or neither, and summing the ones that have them is a
+ * real measurement rather than a partial one. No entry at all is the genuinely
+ * unknown case: the request died before the provider reported anything, which
+ * does NOT mean the gateway metered nothing for it.
+ */
+function usageField(collected) {
+    const entries = collected.toRecord("", undefined, "").entries;
+    const total = sumReported(entries);
+    return total ? { usage: total } : {};
+}
+function sumReported(entries) {
+    let input = 0;
+    let output = 0;
+    let reported = false;
+    for (const e of entries) {
+        if (e.inputTokens === undefined && e.outputTokens === undefined)
+            continue;
+        input += e.inputTokens ?? 0;
+        output += e.outputTokens ?? 0;
+        reported = true;
+    }
+    return reported ? { input_tokens: input, output_tokens: output } : undefined;
+}
+/** `in/out`, or the word for an absent figure — never a stand-in `0/0`. */
+function describeUsage(usage) {
+    return usage
+        ? `${usage.input_tokens}/${usage.output_tokens}`
+        : "unknown (nothing reported)";
+}
 /** The honest result for a child cancelled before it could produce anything —
  * used when a fatal sibling / Ctrl-C fired before this slot even dispatched. */
 function cancelledResult() {

package/dist/subagent/spawn-tool.js

@@ -8,6 +8,26 @@ import { SPAWN_SUBAGENT_TOOL_NAME, SPAWN_SUBAGENTS_TOOL_NAME, } from "./registry
  * on structurally encodes how much deeper nesting may go: at the configured
  * cap the tool simply isn't registered.
  */
+/**
+ * Errors a spawn tool must NOT convert into a tool result.
+ *
+ * A tool error is an invitation to the model to try again differently, so this
+ * set is exactly the errors for which trying again differently is not a thing
+ * the model can do:
+ *
+ *  - `APPROVAL_REQUIRED` — non-interactive default-deny (U.3). There is no
+ *    variation of the call that would be approved; the boundary reports it.
+ *  - `BUDGET_EXHAUSTED` — the weighted pool refused (cli#212). Retrying, in any
+ *    shape, is a request to a gate that will refuse again, and the parent's own
+ *    next request would hit the same 429 regardless. Propagating it means the
+ *    user reads what the gateway actually said — which window, when it recovers,
+ *    and whether mira is still open — instead of the model narrating a tool
+ *    failure and reaching for another spawn.
+ */
+const PROPAGATE = new Set([
+    ErrorCode.ApprovalRequired,
+    ErrorCode.BudgetExhausted,
+]);
 const parameters = z.object({
     task: z
         .string()
@@ -42,10 +62,12 @@ function resultPayload(result) {
         ...(result.artifacts ? { artifacts: result.artifacts } : {}),
         ...(result.error ? { error: result.error } : {}),
         iterations: result.iterations,
-        tokens: {
-            input: result.usage.input_tokens,
-            output: result.usage.output_tokens,
-        },
+        // `"unknown"` rather than an omitted field or a `0/0` pair: the parent model
+        // reasons about what a child cost, and a missing key reads as nothing spent
+        // to anything skimming the payload. See `SubagentResult.usage`.
+        tokens: result.usage
+            ? { input: result.usage.input_tokens, output: result.usage.output_tokens }
+            : "unknown",
     };
 }
 /** The compact wire shape fed back to the parent model. */
@@ -84,10 +106,10 @@ export function makeSpawnSubagentTool(orchestrator, depth) {
             }
             catch (err) {
                 // Non-interactive default-deny propagates to the boundary (U.3) —
-                // same behavior as every other gated tool.
-                if (CruxyError.is(err) && err.code === ErrorCode.ApprovalRequired) {
+                // same behavior as every other gated tool. So does a weighted-pool
+                // denial (cli#212): see `PROPAGATE`.
+                if (CruxyError.is(err) && PROPAGATE.has(err.code))
                     throw err;
-                }
                 // Depth-exceed and scope violations are the model's to correct: feed
                 // the coded, actionable message back as a tool error.
                 return { ok: false, error: toolErrorMessage(err) };
@@ -171,9 +193,8 @@ export function makeSpawnSubagentsTool(orchestrator, depth) {
             }
             catch (err) {
                 // Non-interactive default-deny propagates to the boundary (U.3).
-                if (CruxyError.is(err) && err.code === ErrorCode.ApprovalRequired) {
+                if (CruxyError.is(err) && PROPAGATE.has(err.code))
                     throw err;
-                }
                 // Scope overlap / depth-exceed are the model's to correct — coded error.
                 return { ok: false, error: toolErrorMessage(err) };
             }

package/dist/tools/index.js

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export * from "./registry.js";
+export * from "./schema-depth.js";
 export * from "./list-files.js";
 export * from "./git-status.js";
 export * from "./search-codebase.js";