Yesterday’s Claude Code v2.1.221-222 changelog piece closed with an honest admission: a “mid-conversation tool-switching beta” had turned up in a research sweep, credited to Fable 5, Mythos 5, Opus 4.8, and Opus 5, but it wasn’t in the official Claude Code changelog and couldn’t be verified against any Anthropic primary source in that session. Rather than cite it anyway, it got logged as an unverified watch item. Today it’s resolved — the feature is real, officially documented, and it’s a genuinely useful piece of agentic-coding infrastructure. It just wasn’t where anyone was looking for it.
Where It Actually Lives#
The feature isn’t in code.claude.com/docs/en/changelog because it isn’t a Claude Code CLI feature — it’s a Claude API capability, documented at platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages under the heading “Mid-conversation tool changes.” That’s a meaningful distinction for anyone trying to track Anthropic’s release surface: the Claude Code changelog covers the terminal agent, but capabilities that ship at the model/API layer — this one included — get documented on the separate Developer Platform docs site instead. Two different products, two different changelogs, and a feature can be fully shipped and documented on one while being invisible on the other. That’s exactly the kind of fragmentation that makes verification work necessary rather than optional.
The Problem It Solves#
Anthropic’s prompt caching hashes the request prefix in a fixed order: tools, then system, then messages. A cache hit requires that entire prefix to match byte-for-byte up to the cache breakpoint. Anthropic’s mid-conversation system messages feature — generally available, not a beta — already fixes one half of that problem — appending a new system-role message at the end of the conversation instead of editing the top-level system field, so a late-discovered instruction doesn’t blow away the cached prefix that came before it.
But the tools array sits even earlier in that hashed prefix than system does. Editing it — adding a tool mid-session, or taking one away — invalidates the prompt cache for the entire conversation, not just the system portion. For a long agentic coding session that’s accumulated tens of thousands of cached tokens across dozens of turns, that’s an expensive tax to pay just because the agent now needs access to a linter it didn’t need three turns ago, or should lose access to a destructive deploy tool once a task is scoped down.
How Mid-Conversation Tool Changes Work#
The mechanism, introduced in beta with Claude Opus 5, keeps the tools array itself completely static for the life of the conversation. You declare the full tool set up front — everything the model might ever need in this session — and then use two new content-block types inside a role: "system" message to control what’s actually offered at any given point:
tool_removalwithdraws a tool from a specific point in the conversation onward, referencing it by name via atool_referenceblock rather than editingtools.tool_additionre-offers a previously withdrawn tool, or surfaces one that was declared withdefer_loading: trueand withheld from the start.
Because the tools array never changes, its contribution to the hashed prefix never changes either, and the cache stays intact. Anthropic’s own documentation example makes the mechanics concrete:
{
"role": "system",
"content": [
{
"type": "tool_removal",
"tool": {"type": "tool_reference", "name": "get_weather"}
}
]
}Requests need the mid-conversation-tool-changes-2026-07-01 beta header, and MCP tools get the same treatment — mcp_tool_reference targets a single tool on a connected MCP server, while mcp_toolset_reference can add or remove an entire server’s toolset in one block. The feature is available on Claude Fable 5, Mythos 5, Opus 4.8, and Opus 5, across the Claude API, Amazon Bedrock, and Google Cloud — but notably not on Claude Sonnet 5, which still requires the top-level tools field for any change.
Why This Matters for Agentic Coding Specifically#
This is squarely infrastructure for the kind of long-running, tool-heavy agentic sessions this blog covers constantly — a coding agent that starts with read/search/edit tools, later needs to spin up a deploy or migration tool once a task is scoped and approved, and should probably lose access to that same tool once the task is done. Before this beta, every one of those transitions meant editing tools and paying full price to reprocess the entire conversation history on the next request. Now the transition is a small system-role block appended at the natural boundary — after a tool result, before Claude’s next turn — and the accumulated cache from everything before it survives untouched.
It also slots cleanly next to a security detail worth calling out on a blog that’s spent the last two days covering Claude Code permission-bypass fixes: Anthropic’s own limitations section is explicit that tool_removal/tool_addition blocks are not a place for untrusted content. The blocks reference tools by name; they don’t carry arbitrary text from tool output or retrieved documents. That data still belongs in tool_result blocks, and the standard jailbreak/prompt-injection mitigations still apply. Anthropic drew that boundary deliberately rather than leaving it as an afterthought — a good sign for a feature explicitly aimed at agentic loops, which are exactly where injected instructions do the most damage.
The Placement Rules Are Strict, and That’s a Feature#
A mid-conversation system message — tool-change blocks included — can’t be the first entry in messages, can’t sit between an assistant tool_use block and its answering tool_result, and must immediately follow either a user turn or an assistant turn ending in a server tool result. Get the placement wrong and the API returns a 400 rather than silently accepting something malformed. For a mechanism whose entire purpose is precise surgical edits to an otherwise-frozen prompt structure, that rigidity is the right trade: a system that quietly accepted tool changes in arbitrary positions would make cache behavior far harder to reason about, trading a clear error for a subtle, hard-to-debug cache miss three turns later.
The Takeaway#
Nothing about this beta is flashy — it’s the unglamorous kind of infrastructure work that shows up as a line in an aggregator’s rumor mill months before anyone writes it up properly, because “Anthropic reduced prompt-cache invalidation for tool-list changes” doesn’t generate clicks the way a benchmark number does. But it’s a real, concrete improvement for anyone running production agentic coding sessions with dynamic tool access, and it’s a good reminder that Anthropic’s release surface spans more than the Claude Code changelog this blog checks daily. When a claim shows up on secondary sites with no primary-source backing, the right move isn’t to repeat it or to dismiss it — it’s to go find where Anthropic actually documented it, which is exactly what closed this watch item.