claude-code - 💡(How to fix) Fix [DOCS] `/model` docs omit the uncached full-history warning for mid-conversation switches [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Setting your model / during-session /model switching guidance

Current Documentation

The model configuration page currently says:

You can configure your model in several ways, listed in order of priority:

1. During session - Use /model <alias|name> to switch models mid-session

The command reference says:

/model [model] | Select or change the AI model. For models that support it, use left/right arrows to adjust effort level. The change takes effect immediately without waiting for the current response to finish

The cost guide also recommends mid-session switching:

Sonnet handles most coding tasks well and costs less than Opus. Reserve Opus for complex architectural decisions or multi-step reasoning. Use /model to switch models mid-session, or set a default in /config.

What's Wrong or Missing?

Changelog v2.1.108 says:

Improved /model to warn before switching models mid-conversation, since the next response re-reads the full history uncached

The current docs never explain this user-visible behavior.

They do not tell users that switching models after a conversation already has history makes the next response resend the full conversation context uncached, which can increase token usage and latency. They also do not mention that Claude Code now warns before this happens.

Because model-config, commands, and costs all present /model switching as a normal mid-session workflow, users are missing the cautionary context that motivated the new warning in v2.1.108.

Suggested Improvement

Add a short note anywhere /model mid-session switching is introduced, especially on model-config and the /model command reference.

Suggested wording:

Switching models in the middle of an existing conversation can increase cost and latency on the next response, because Claude Code must resend the full conversation history uncached for the new model. Claude Code warns before this happens. If you know you'll need a different model, prefer selecting it at session start when possible.

The costs page should also stop recommending mid-session switching without this caveat.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Source: Changelog v2.1.108

Exact changelog entry:

Improved /model to warn before switching models mid-conversation, since the next response re-reads the full history uncached

Related documented precedent:

https://code.claude.com/docs/en/fast-mode already documents a similar cost/latency tradeoff for another mid-conversation mode switch:

When you switch into fast mode mid-conversation, you pay the full fast mode uncached input token price for the entire conversation context. This costs more than if you had enabled fast mode from the start.