[Feature Request] Allow configurable max_output_tokens reservation for effective context window calculation

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

After upgrading to v2.1.7, the effective context window for Opus 4.5 was reduced from ~200k to ~136k tokens due to the fix that now correctly reserves space for max_output_tokens (64k for Opus 4.5).

While I understand this fix prevents API errors when the context is truly full, the 64k reservation is excessive for many use cases. Most interactions don't require anywhere near 64k output tokens, yet users lose 32% of usable context window.

Current behavior:

• Opus 4.5: 200k - 64k = 136k effective context
• Sonnet 4.5: 200k - 64k = 136k effective context

Impact:

• Complex multi-file refactoring tasks require more frequent /compact cycles
• Long debugging sessions are interrupted prematurely
• Significant productivity loss for context-heavy workflows

Proposed Solution

Allow users to configure the max_output_tokens reservation via:

1. Environment variable (extend existing behavior):

``bash
CLAUDE_CODE_MAX_OUTPUT_TOKENS=32000 # Reserve 32k instead of 64k
``

1. Settings.json option:

``json
{
"contextWindow": {
"maxOutputTokensReservation": 32000
}
}
``

1. CLI flag:

``bash
claude --max-output-tokens=32000
``

Example impact with 32k reservation:

• Effective context: 200k - 32k = 168k tokens
• Gain: +32k usable context (24% improvement)

Alternative Solutions

1. Dynamic reservation based on task type: Reserve less for read-heavy tasks, more for generation-heavy tasks

1. Warning instead of blocking: Show a warning at 136k but allow continuing to 168k-180k with user acknowledgment

1. Per-session override: Allow /config max-output 32000 to adjust mid-session

Priority

High - Significantly impacts daily productivity for power users

Feature Category

Configuration and settings

Use Case Example

Scenario: Refactoring authentication across multiple files

1. Start session with ~46k system overhead (tools, memory files, agents)
2. Read 5-6 files for context (~30k tokens)
3. Discuss approach and review existing patterns (~20k tokens)
4. Hit "Context limit reached" at ~96k message tokens
5. Forced to /compact or /clear, losing valuable context
6. Repeat the file reading and context building

With configurable reservation (32k instead of 64k):

• Would have ~122k for messages instead of ~90k
• Could complete the refactoring in one session

Additional Context

Related Issues:

• #8136 - Root cause analysis that led to v2.1.7 fix
• #6543 - User reports "Context Window Overflow Despite Reported Available Space"
• #8381 - Feature request for 1M context (related workaround)
• #9365 - CLAUDE_CODE_MAX_OUTPUT_TOKENS validation issues

Technical Note:
The current CLAUDE_CODE_MAX_OUTPUT_TOKENS env var controls the actual API max_tokens parameter but doesn't appear to affect the context window blocking calculation. The request is to have the blocking calculation respect a user-configurable reservation amount.