[BUG] Loading a tool for the first time mid-session (e.g. skill, MCP, tool-search) invalidates cache

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet (closest are #42309, #44045, #41930, but those are about --resume/billing-sentinel, not mid-session tool loading)
• [x] This is a single bug report
• [x] I am using the latest version of Claude Code

What's Wrong?

Every first-time tool load in a session = a full cache miss on the next turn.

The tools array is the first block in the request so it's right at the front of the cache prefix, which means the second it grows everything after it is invalid. I know tools load lazily, I just figured a new one gets tacked onto the end, not nuke the cache for the whole conversation.

Caught it with an MITM proxy on /v1/messages:

| Turn | Trigger | tools size | cache_read | cache_creation |
|---|---|---|---|---|
| ~37 | first TodoWrite use | 13 → 14 | 84,858 -> 0 | 120,845 |
| ~57 | invoked an MCP-backed skill (loaded 3 MCP tools) | 14 → 17 | 128,716 -> 0 | 150,796 |

That second row is ~150k tokens re-encoded in one turn, around $3 at Fable's cache-write rate.

What Should Happen?

Adding a tool mid-session shouldn't re-encode the whole conversation. Easiest fix is probably to just declare the deferred tools at session start so the array never grows. If that's not doable, warn the user before it invalidates the cache, the way the CLI already does when you resume a conversation past its TTL.

Error Messages/Logs

N/A

Steps to Reproduce

1. Use a config where tools load lazily (default in recent versions: deferred tool-search on, an MCP server or a skill installed).
2. Start a session and work until the conversation is large (e.g. ~100k+ tokens).
3. Trigger a first-time tool load this session, e.g. invoke a skill that pulls in MCP tools, or use an MCP / deferred tool you haven't used yet this session.
4. Inspect that single turn's API usage. cache_read_input_tokens will collapse to 0 while cache_creation_input_tokens will balloon to your conversation size for that turn.

Claude Model

The bug is model-independent

Is this a regression?

I don't know, this appears to be inherent to lazy tool loading, not a recent change.

Last Working Version

N/A

Claude Code Version

2.1.197, VS Code Extension

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

VS Code Extension

Additional Information

This is on Claude Code, not the API. It's growing the tools array lazily mid-session instead of declaring everything up front.

Not the same as the --resume stuff in #42309 / #44045 either, mine is one continuous session, no resume. #42309 says the deferred-tools/MCP/skill caching behavior is undocumented, so here's a real number for it.