Swap Claude's Tools Mid-Conversation Without Busting the Cache

Add or remove Claude's tools between turns — without re-billing the entire cached prefix — using one beta header: a new pattern for agentic workloads that progressively expose or retire tools.

Every production agent faces a tension: give Claude a small, safe toolbox and you limit capability; give it the full toolbox upfront and you expose write surfaces before you need them. The mid-conversation-tool-changes-2026-07-01 beta, introduced with Claude Opus 5, resolves this.

The problem

Before this beta, changing the tool list invalidated the cached prefix — meaning a large system prompt or long conversation history was re-billed at full price on every tool-set change.

The fix: one beta header

Include the header on every request in the session:

import anthropic

client = anthropic.Anthropic()

# Turn 1 — read-only exploration
r1 = client.messages.create(
    model="claude-opus-5-20260724",
    max_tokens=1024,
    betas=["mid-conversation-tool-changes-2026-07-01"],
    tools=[search_tool, read_file_tool],
    messages=[{"role": "user", "content": "Explore the codebase and draft a plan."}],
)

# Turn 2 — user approves; add write access
r2 = client.messages.create(
    model="claude-opus-5-20260724",
    max_tokens=1024,
    betas=["mid-conversation-tool-changes-2026-07-01"],
    tools=[search_tool, read_file_tool, edit_file_tool],  # unlocked
    messages=[
        *prior_messages,
        {"role": "assistant", "content": r1.content},
        {"role": "user", "content": "Looks good — go ahead."},
    ],
)

The system prompt and prior turns stay cached across both calls. Only the delta (the changed tool definition) is re-billed.

Progressive access pattern

A clean four-phase flow for multi-step agentic tasks:

1. Explore — read-only tools (search, grep, read)
2. Plan and approve — same tools; user confirms before anything mutates
3. Execute — narrow write tools added (edit, create, run)
4. Verify — write tools retired; test and lint tools take over

This keeps Claude's exposure minimal at every stage, which matters for both cost (smaller tool definitions = cheaper cached prefix) and safety (no write surface during exploration).

Available on Fable 5, Mythos 5, Opus 4.8, and Opus 5. Mid-conversation system message changes (GA, no beta header needed) work the same way and also preserve the cache.

Sources: Mid-conversation system messages and tool changes · What's new in Claude Opus 5 · Introducing Claude Opus 5