[FEATURE] Budget-aware subagent orchestration: premium-model fan-out burned ~70% of a weekly Fable 5.1 allowance, mostly on subagents killed by the rate limit

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet (closest related: #81759, which is about limit accounting, not orchestration behavior)
• [x] This is a single feature request (not multiple features)

Problem Statement

Summary: the orchestrating model has no budget awareness and defaults every subagent to the parent's (premium) model. On a document-synthesis task this burned ~70% of a weekly Fable 5.1 allowance, most of it wasted on subagents that were killed mid-flight by the rate limit. The same prompt in a single-thread run on a competing product consumed ~7% of that product's allowance and produced output of comparable quality.

Environment: Claude Code desktop app (macOS), model claude-fable-5-1, Max plan, default permission settings, no CLAUDE_CODE_SUBAGENT_MODEL set.

The task (a realistic "knowledge work" prompt, not a coding task):

• Input: two PDFs (a 409-page study summary and a 373-page collection of 11 past board exams, ~1,100 questions).
• Ask: analyze the exams, classify every question by topic, and produce a ~150-200 page study summary prioritized by what the exams actually test.

What the model did (all defaults, no user instruction about agents):

1. Spawned 12 parallel subagents to classify the exams (one per year). Each ran on Fable 5.1 (inherited from the parent). Reported usage: ~2.0M tokens (155k-225k each).
2. Spawned 20 parallel subagents (the concurrency cap) to write the chapters, again on Fable. Each subagent re-read the style guide, the briefing, its 10k-45k-token source excerpt and the classification file — the same material read 20+ times.
3. The session hit the rate limit (HTTP 429) mid-run. All in-flight subagents were killed. Most had finished reading (60k-150k tokens each) but not yet written anything, so that work was lost entirely.
4. After the reset the model relaunched them; the limit hit again, killing another wave. Total: 27 subagent invocations died without producing output.
5. Only after the user manually switched the session to Opus 5 did the remaining work complete.

Measured cost: 2.0M (classification) + 3.6M (completed writers) + an estimated 1.6-4.0M (killed subagents) ≈ 7-10M tokens in subagents alone, on the most expensive model, for a task whose actual output is ~85k words. A single-thread sequential approach on Sonnet/Opus would plausibly have cost 5-8x less with the same result.

Why this is a product problem and not just user error:

• The model cannot see remaining quota, so it cannot plan within a budget. It optimizes for wall-clock time (max fan-out) when the user's actual constraint is tokens.
• Subagents silently inherit the parent's premium model. Nothing nudges bulk workers (classification, extraction, drafting) toward Sonnet/Haiku.
• A 429 kills subagents instead of pausing them, so partial work is lost and the natural recovery (relaunch) doubles the waste.
• The concurrency cap (20) acts as a target rather than a ceiling.

This matches many public reports since the Fable 5.1 launch ("5-hour window gone in 30 minutes / from a single prompt because of the sub-agent design"), so it is likely systematic.

Proposed Solution

Any subset of these would have prevented most of the waste:

1. Budget-aware orchestration. Expose remaining session/weekly allowance (even coarsely: "~30% left, resets in 2h") in the model's context so it can size fan-out and pick models accordingly, and warn the user before an expensive plan.
2. Sensible subagent model defaults. When the parent is a premium model (Fable/Mythos), default subagents to Sonnet (or Opus) unless the model parameter is set explicitly. At minimum, make the Agent tool's default model for general-purpose workers Sonnet, and reserve premium models for the planner/reviewer.
3. Pause instead of kill on 429. When the rate limit is hit, queue/suspend in-flight subagents and resume them after the reset instead of terminating them. If termination is unavoidable, persist the subagent's transcript so a resume does not re-read everything.
4. Cost estimate and confirmation before large fan-outs. Before spawning more than N (e.g. 5) subagents, or when the estimated spend exceeds a threshold, show "about to launch 20 agents on Fable 5.1, est. 4-6M tokens (~X% of your weekly limit). Proceed / use Sonnet workers / run sequentially?".
5. A budget/economy mode (setting or flag) that caps concurrency (e.g. 4), forces Sonnet workers and prefers single-thread execution for document synthesis tasks.
6. Post-task usage report in the transcript: tokens per phase, per subagent, and how many subagents died — so users can calibrate.

Alternative Solutions

• Users can set CLAUDE_CODE_SUBAGENT_MODEL=sonnet and write CLAUDE.md rules ("max 4 concurrent subagents, never premium model for workers, stop on 429"). This is what I have now done, but it requires the user to first lose most of a weekly allowance to discover the problem, and it depends on the model honoring prose rules under pressure.
• Manually switching the session to Opus mid-task (what fixed it here) also works, but the damage is already done by then.
• Passing model: "sonnet" on every Agent call works when the user drives the orchestration themselves, but not when the model decides autonomously, which is the common case in the desktop app.

Priority

High - Significant impact on productivity (and on cost: a single autonomous run can consume most of a weekly premium allowance)