Subagents are capped at 8000 output tokens while the main loop is not — high effort exhausts the budget on thinking alone, killing the agent before it emits anything

Version: 2.1.212 (also reproduced on every version back to 2.0.76)
Platform: macOS 15 (darwin arm64), M4 Max
Model: reproduced on claude-sonnet-5, claude-opus-4-8, claude-fable-5

Summary

Agents launched via the Agent/Task tool receive max_tokens: 8000, while the
main loop and claude -p on the same machine and model receive substantially more
(measured: 15,656 output tokens in a single response, no cap hit).

Because extended-thinking tokens count against max_tokens, a subagent running at
--effort xhigh can consume the entire 8000-token budget on thinking and die
with an API error before producing any output at all. The failure looks like the
agent crashing for no reason on its first response.

CLAUDE_CODE_MAX_OUTPUT_TOKENS does not apply (consistent with #25569), and the
error message misleadingly instructs the user to set the variable they already set.

Evidence

1. The subagent cap is exactly 8000 and is real

Across 640,330 assistant responses in local transcripts (2026-01-03 → 2026-07-17,
CC 2.0.76 → 2.1.212), output_tokens at a stop_reason: max_tokens never exceeds

1. Distinct observed values at the stop:

[86, 256, 1583, 2275, 2318, 2361, 2404, 3635, 7996, 7997, 7998, 7999, 8000]
max = 8000   (n = 2,626 max_tokens stops)

claude-sonnet-5: 25,191 responses, max output_tokens = 8000, never once higher,
299 max_tokens stops.

2. The main loop is NOT capped at 8000

Same machine, same model, same minute:

$ claude -p "<hard reasoning task>" --model sonnet --effort xhigh --output-format json
  stop_reason: end_turn
  output_tokens: 15656          # ← nearly 2x the subagent cap, no error

3. CLAUDE_CODE_MAX_OUTPUT_TOKENS has no effect (A/B)

A: CLAUDE_CODE_MAX_OUTPUT_TOKENS=128000 → stop=end_turn, out_tokens=11,122
B: variable unset                       → stop=end_turn, out_tokens=11,198

4. High effort exhausts the budget on thinking alone

Identical prompt and model, only --effort varies:

| effort | output_tokens | answer text (chars) | vs 8000 cap |
|---|---|---|---|
| xhigh (run 1) | 15,656 | 11,760 | 195% — cannot complete |
| xhigh (run 2) | 10,012 | 5,258 | 125% — cannot complete |
| low (run 1) | 3,778 | 10,876 | 47% — completes |
| low (run 2) | 3,386 | 9,922 | 42% — completes |

At xhigh the great majority of the budget is thinking, and the request exceeds
8000 while still thinking — so a subagent dies having emitted nothing. The same
prompt at low finishes well inside the cap.

This is not an argument that effort is unnecessary. A blind judge scored the xhigh
answer higher than the low answer (36 vs 32 across correctness/depth/rigor). The
point is that a subagent currently cannot use high effort at all on a hard task:
the cap converts a better answer into no answer. Users are forced to trade reasoning
quality for the agent simply completing.

Reproduction

In a session with "effortLevel": "xhigh" in settings.json:

Agent(
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: "Design a distributed rate limiter giving exact per-key limits under
           network partition. Analyze at least five distinct failure modes, the CAP
           tradeoff each forces, and reconcile them. Be rigorous and complete."
)

Result:

Agent terminated early due to an API error: API Error: Claude's response exceeded
the 8000 output token maximum. To configure this behavior, set the
CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable.

The same prompt via claude -p --effort xhigh succeeds at 15,656 output tokens.

A second, simpler reproduction (count from 1 to 20000, one per line, no tools) also
dies at 8000 after one silent auto-recovery.

Impact

This is not a niche limit. Any subagent doing genuinely hard work at default effort
is liable to die before emitting a token, and the error gives the user no indication
that effort/thinking is what consumed the budget. In our fleet, six of eight
production subagents hit this at least once. The only agents that survived were ones
given prompts terse enough to suppress thinking, which is a workaround that costs
reasoning quality.

Notably, every public report of this error cites 32000, not 8000 — so the
8000 figure may be a regression or an unreported rollout.

Requests

1. Apply CLAUDE_CODE_MAX_OUTPUT_TOKENS to Agent/Task requests, or add

CLAUDE_CODE_SUBAGENT_MAX_OUTPUT_TOKENS.

1. Allow effort in agent frontmatter so a subagent's thinking budget can be

tuned independently of the session.

1. Reserve thinking budget against max_tokens so an agent cannot spend 100% of

its output allowance thinking and emit nothing.

1. Fix the error message: it should not instruct the user to set a variable that

is ignored on this code path, and should name effort/thinking as the consumer.

Related

• #25569 — CLAUDE_CODE_MAX_OUTPUT_TOKENS not applied to subagent (Task tool) API calls
• #24055 — error fires during extended thinking
• #8775 — agent output-limit handoffs (closed as duplicate)

await agent(prompt, {
  thinking: { type: 'enabled', budget_tokens: 3000 },
  label: 'subagent-name'
})