[DOCS] [Fallback model chains] docs omit that compaction requests use the configured chain

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/model-config#fallback-model-chains

Section/Topic

"Fallback model chains" section in https://code.claude.com/docs/en/model-config, particularly the "switch lasts for the current turn only" sentence that scopes the documented behavior to normal turns without mentioning compaction.

Current Documentation

The "Fallback model chains" section in model-config.md currently says:

When the primary model is overloaded, unavailable, or returns another non-retryable server error, Claude Code can switch to a fallback model instead of failing the request. Authentication, billing, rate-limit, request-size, and transport errors never trigger a switch; those follow their normal retry and error handling. Configure one or more fallback models and Claude Code tries them in order, showing a notice when it switches. The switch lasts for the current turn only, so your next message tries the primary model first again. Chains are capped at three models after duplicate removal, and extra entries are ignored.

The "The context window" section in how-claude-code-works.md describes compaction:

Claude Code manages context automatically as you approach the limit. It clears older tool outputs first, then summarizes the conversation if needed.

Neither section says anything about which model is used when a compaction request hits an overloaded or unavailable primary model.

What's Wrong or Missing?

A. Fallback chain scope is documented as turn-only, but compaction is an out-of-band request that also uses it

The "switch lasts for the current turn only" sentence implies the fallback chain only covers the user's normal turn traffic. As of v2.1.178, compaction requests also walk the chain on overload or model-availability errors, but the docs do not mention this, so a user who configures --fallback-model (or fallbackModel in settings) has no way to learn that long-session compaction will degrade to the next model in their chain rather than fail.

B. No documentation of which model summarizes a compaction request

The "The context window" section in how-claude-code-works.md describes compaction behavior in user-facing terms ("Claude Code manages context automatically as you approach the limit. It clears older tool outputs first, then summarizes the conversation if needed.") but never states which model is used to produce the summary, nor what happens to that step when the configured primary model is overloaded. With v2.1.178 the summarization call now follows the same fallback chain the rest of the session does; users setting up --fallback-model for resilience will reasonably expect the chain to cover every model call in the session, and that should be made explicit.

C. Implication that compaction failures were unrelated to the fallback chain

A reader who hits "compaction failed" symptoms in a long session and looks up fallbackModel would not learn from the current docs that the chain now covers that request. This makes the configuration look less effective than it is, and pushes users toward ad-hoc workarounds (manual /compact, raising the auto-compact threshold, switching models outright) when the configured chain would already have handled the case.

Suggested Improvement

Add a note to the "Fallback model chains" section in model-config.md covering compaction, and a short callout from the "When context fills up" subsection in how-claude-code-works.md. Something like:

In model-config.md "Fallback model chains", after the "switch lasts for the current turn only" sentence, add:

Compaction requests also walk the configured chain. If a /compact call or an automatic auto-compact summary hits an overload or model-availability error on the primary model, Claude Code falls back to the next model in the chain for that summarization step. (Added in v2.1.178.)

In how-claude-code-works.md "When context fills up" section, after the line that ends "then summarizes the conversation if needed", add:

Compaction uses your active model, and follows the same fallbackModel chain as the rest of the session. If your primary model is overloaded, the summarization step falls back to the next configured model rather than failing the compact.

The two edits together make it clear that the chain covers the entire session, including the out-of-band summarization call, and they tie the long-context page to the model-config page via cross-links.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/model-config | 210-212 | "Fallback model chains" section: switches described as turn-only |
| https://code.claude.com/docs/en/how-claude-code-works | 125 | "When context fills up" subsection: summarization step does not mention which model is used or the fallback chain |

Total scope: 2 pages affected

Other useful context:

• Released in v2.1.178 per the changelog entry: "Fixed compaction not honoring --fallback-model: compaction now falls back to the configured fallback model chain on overload or model-availability errors."
• The whats-new/2026-w24.md digest already mentions --fallback-model "now applies to interactive sessions too", which is the v2.1.166 side of the same area. The v2.1.178 compaction behavior is the natural follow-on and should be reflected in the model-config page so users do not have to read the changelog to learn what their configured chain covers.
• The [DOCS] issue title is intended to be prefixed automatically by the submission script.