[DOCS] Context Windows and Prompt Caching docs state thinking blocks are always stripped, but Claude Opus 4.5 preserves them by default

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://docs.anthropic.com/en/docs/build-with-claude/context-windows - https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching

Section/Topic

• Context Windows: "The context window with extended thinking" section - Prompt Caching: "Caching with thinking blocks" section

Current Documentation

Context Windows (context-windows.md)

Line 28:

However, previous thinking blocks are automatically stripped from the context window calculation by the Claude API and are not part of the conversation history that the model "sees" for subsequent turns, preserving token capacity for actual conversation content.

Line 34:

Stripping extended thinking: Extended thinking blocks (shown in dark gray) are generated during each turn's output phase, but are not carried forward as input tokens for subsequent turns.

Line 67:

Token calculation: Previous thinking tokens are automatically stripped from context window calculations.

Prompt Caching (prompt-caching.md)

Line 400:

Cache gets invalidated when non-tool-result user content is added, causing all previous thinking blocks to be stripped

Line 428:

When a non-tool-result user block is included, it designates a new assistant loop and all previous thinking blocks are removed from context.

What's Wrong or Missing?

These statements describe thinking block handling as a universal behavior, but Claude Opus 4.5 has different default behavior. The Extended Thinking documentation explicitly states:

Claude Opus 4.5 introduces a new default behavior: thinking blocks from previous assistant turns are preserved in model context by default. This differs from earlier models, which remove thinking blocks from prior turns. — extended-thinking.md, "Thinking block preservation in Claude Opus 4.5" section

And:

For Claude Opus 4.5 and later, all previous thinking blocks are kept by default. For older models, because a non-tool-result user block was included, all previous thinking blocks are ignored. — extended-thinking.md, line 939

This creates a direct contradiction between the Context Windows/Prompt Caching docs and the Extended Thinking doc. A developer reading the Context Windows page would incorrectly believe that thinking blocks are always stripped, even when using Claude Opus 4.5.

Key implications for developers:

1. Context window calculations differ for Opus 4.5 vs other models
2. Token budgeting advice is inaccurate for Opus 4.5 users
3. Caching behavior expectations are incorrect for Opus 4.5

Suggested Improvement

For Context Windows (context-windows.md)

Add a Note after line 28, similar to:

Note: Claude Opus 4.5 preserves thinking blocks by default. The stripping behavior described above applies to Claude Sonnet 4.5, Opus 4.1, and earlier models. When using Opus 4.5, thinking blocks from previous turns are retained in context, which impacts context window calculations. See Thinking block preservation in Claude Opus 4.5 for details.

The effective context window formula should also be updated to distinguish:

• For most models: context_window = (input_tokens - previous_thinking_tokens) + current_turn_tokens
• For Claude Opus 4.5: context_window = input_tokens + current_turn_tokens (thinking tokens are not stripped)

For Prompt Caching (prompt-caching.md)

Add a Note in the "Caching with thinking blocks" section after line 401:

Note: Claude Opus 4.5 preserves thinking blocks in context by default, even when non-tool-result user content is added. The cache invalidation behavior described here applies to earlier models. See Thinking block preservation for Opus 4.5-specific behavior.

Impact

High - Prevents users from using a feature

Additional Context

Affected Files

| File | Location | Specific Lines |
|------|----------|----------------|
| context-windows.md | platform-claude/docs/en/build-with-claude/ | 28, 34, 65, 67 |
| prompt-caching.md | platform-claude/docs/en/build-with-claude/ | 400, 424-425, 428 |

Source of Truth

The Extended Thinking documentation has the authoritative behavior description:

• extended-thinking.md lines 1880-1897: "Thinking block preservation in Claude Opus 4.5" section
• whats-new-claude-4-5.md line 42: Feature announcement with link to extended-thinking doc

Cross-References

• Current models reference: https://docs.anthropic.com/en/docs/about-claude/models
• Extended thinking guide: https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#thinking-block-preservation-in-claude-opus-4-5

Note on API Reference Files

SDK documentation files (e.g., api/python/beta.md) mention the thinking_block_retention parameter which allows configuring "Number of most recent assistant turns to keep thinking blocks for." This is correct SDK documentation for a configurable feature and is not affected by this issue—the issue is specifically about prose documentation making blanket claims without acknowledging model-specific defaults.