After running /model mid-session, a Claude Code turn is slow and costly; which mid-session actions invalidate its prompt cache, and which do not?
answer
- exact prefix, rarely-changing content first
- each model has its own cache
- tool definitions live in the system prompt
- tool search freezes the tool list
- CLAUDE.md read once at start
basics
~20 sEach model has its own cache, so /model makes the next request reprocess the whole history. Turning on fast mode, compaction and changed tool definitions also invalidate it; editing files or CLAUDE.md, switching permission mode, invoking skills and spawning subagents keep it.
solid answer
~40 sClaude Code caches automatically by exact prefix, ordering each request as system prompt with tool definitions, then project context (CLAUDE.md, auto memory, unscoped rules), then the conversation. Anything that changes an early layer recomputes everything after it, costing one slow, full-price turn. Invalidators: switching models (including plan-mode toggles under `opusplan` and a skill whose frontmatter names another `model`), effort changes on most models, the first fast-mode turn, compaction, and tool-definition changes such as an MCP server connecting — but only when tools load upfront, since with tool search, the default, the first request's tool list is kept. Cache-safe: editing repository files, changing permission mode or output style, invoking skills, `/rewind` and spawning subagents. A CLAUDE.md edit keeps the cache because it does not apply until `/clear`, `/compact` or a restart.
go deeper
Recall that a model switch makes the next turn slow and costly because each model has its own cache, and that editing CLAUDE.md does not apply until /clear, /compact or a restart.
Explain the three request layers and the exact-prefix rule, and use them to say why tool-definition changes and compaction invalidate the cache while skills and file edits do not.
Show the conditions that flip an answer: tool search keeping MCP changes cache-safe, opusplan turning plan toggles into model switches, effort changes that keep the cache only on some models and providers.
Turn the rules into team habits and defaults: settle model and effort per task, schedule compaction at breaks, standardise MCP servers at session start, and check gateways forward cache markers.
## How Claude Code lays out a request for caching Claude Code caches **automatically**: you do not place cache markers yourself. Every turn re-sends the full context — system prompt, project context, every earlier message and tool result, and the new message — and the API reuses whatever **prefix** of that request exactly matches content it processed recently. The match is exact: a change anywhere in the prefix recomputes **everything after it**. There is no per-file or per-segment caching. To make that work, Claude Code orders each request so the content that changes least comes first: | Layer | Content | Changes when | | - | - | - | | System prompt | Core instructions, **tool definitions** | The set of loaded tool definitions changes | | Project context | CLAUDE.md, auto memory, unscoped rules | Session start, `/clear`, `/compact` | | Conversation | Messages, responses, tool results | Every turn | Two things sit outside the table but still decide what stays cached: the **model** (each model has its own cache) and, on most models, the **effort level**. A miss is not an error. You get **one slower, more expensive turn** while the new prefix is written, and then caching resumes. The cost is that turn, multiplied by how big the context has grown. ## Actions that invalidate the cache - **Switching models.** `/model` makes the next request read the whole history with no cache hits, even though the content is identical. The same applies to toggling plan mode under the `opusplan` setting (Opus while planning, Sonnet while executing), to a skill or command whose frontmatter names a different `model` for its turn, and to automatic model fallback. - **Changing effort** on most models. On Opus 5.5, Sonnet 5.5 and Fable 5.1 with an API key or a Claude subscription the cache survives an effort change; on Bedrock, Google Cloud's Agent Platform or a Claude apps gateway it does not. - **Turning on fast mode** — once per conversation, because its request header is part of the cache key. - **Changing tool definitions** — connecting or removing an MCP server, enabling a plugin that provides MCP servers, or denying a whole tool such as bare `Bash` — **when tools load upfront**. With **tool search** deferring MCP tools, the default on supported models, Claude Code keeps the first request's tool list for the whole conversation and new servers' tools arrive deferred, so the cache survives. - **Compacting.** `/compact` and auto-compaction replace history with a summary, so the conversation layer is rebuilt by design. - **Accumulating many images.** When Claude Code drops a batch of old images to stay under request limits, the conversation reprocesses from the earliest changed message. - **Upgrading Claude Code.** A new version usually changes the system prompt, so the first session after the upgrade starts cold. ## Actions that keep the cache - **Editing repository files.** Earlier reads stay in history unchanged; Claude Code appends a notice that the file changed. - **Editing CLAUDE.md mid-session.** The project-root and user-level files are read once at session start and held in memory, so an edit neither busts the cache nor applies. It loads on the next `/clear`, `/compact` or restart. A nested CLAUDE.md or a path-scoped rule that has not loaded yet does pick up an edit when it first loads. - **Changing permission mode** — except plan mode under `opusplan`, which is a model switch. - **Changing output style** — delivered as a message in the conversation. - **Invoking skills and commands** — their instructions are appended as user messages. - **`/rewind`** — truncates back to a prefix that is already cached. - **Spawning a subagent** — its call and result append to the parent's conversation; the subagent builds its own separate cache. ## Why a CLAUDE.md edit waits Applying an edit to CLAUDE.md mid-session would change the **project-context layer**, which sits before the whole conversation, and every later token would be recomputed. Claude Code chooses the cheaper behaviour: keep the version loaded at start, keep the cache, and pick up the edit at the next natural rebuild point (`/clear`, `/compact`, restart). If a rule must be followed now, say it in the conversation; to enforce it, use a permission rule or a hook rather than an instruction file. ## Practical habits 1. Choose model and effort at the start of a session, not mid-task. 2. Run `/compact` at natural breaks instead of letting auto-compaction fire mid-task, and `/clear` between unrelated tasks. 3. Use `/rewind` rather than `/compact` to abandon a dead end — it lands on a cached prefix. 4. When a turn is unexpectedly slow, check the `Prompt cache (main)` line in `/usage` for the miss and its likely cause.
- Why does toggling plan mode bust the cache for one developer but not another?Changing permission mode does not touch the system prompt or tool definitions, so it is cache-safe. The exception is the `opusplan` model setting, which runs Opus in plan mode and Sonnet outside it. For that developer every plan-mode toggle is a model switch, and each model has its own cache, so the next request re-reads the whole conversation.
- A gateway behind `ANTHROPIC_BASE_URL` strips the cache markers Claude Code sends. What does that cost?Claude Code places cache markers itself; a gateway that removes them while returning success makes the whole conversation bill as uncached input on every turn. One that rejects a marked request with a 400 naming `cache_control` is handled: Claude Code moves the marker to the last conversation message and the conversation stays cached.
- Why is `/rewind` cheaper than `/compact` when you abandon a dead end?`/rewind` truncates the conversation back to an earlier turn, which is exactly a prefix the cache already holds, and every later turn kept that entry warm. `/compact` replaces history with a new summary, so the conversation layer must be written again from scratch.
A cached session is a long recording you can extend for free at the end; change anything early and everything after that point must be re-recorded, and a different model is a different tape altogether.
- Editing CLAUDE.md mid-session invalidates the cache and applies on the next turn.
- Switching models keeps the cache because the conversation content is identical.
- Connecting any MCP server mid-session always invalidates the whole cache.
- Spawning a subagent wipes the parent conversation's cached prefix.
- Changing permission mode always forces an uncached turn.
- Claude Code caches each file separately, so an edit re-caches only that file.