Opus 5 migration, when thinking becomes the default

Opus 5 arrived on July 24, 2026. If you did the 4.8 migration, you remember a relaxed playbook: swap the model field, done, zero breaking changes. This time is different. The name swap is still one line, but behind it sit two real behaviour changes, one of which comes back as a hard 400 error, and a third that makes your existing prompts worse rather than better.

The good news first: pricing stays at 5 dollars per million input tokens and 25 per million output, exactly like 4.8. You pay the same for a substantially stronger model. This playbook is for you if you have API code, run Claude Code as a daily driver, or operate agents that used to run on 4.8.

Step 1, the name swap

Find the model string in your codebase and swap it.

grep -rn "claude-opus-4-8" src/
# switch every hit to claude-opus-5

The ID is claude-opus-5, no date suffix, same scheme as claude-opus-4-8 and claude-sonnet-5. One thing is new: there is no separate 1M variant anymore. On 4.8 you had to write claude-opus-4-8[1m] if you wanted the large context window. On Opus 5, 1 million tokens is both the default and the maximum, there simply is nothing smaller. If you have a [1m] spelling anywhere, it goes.

Max output is 128k tokens. The model is available on the Claude API, Amazon Bedrock (as anthropic.claude-opus-5), Google Cloud and Microsoft Foundry. Opus 4.8 stays reachable everywhere, so nobody force-migrates you.

In Claude Code you need at least v2.1.219. On Max, Team Premium, Enterprise pay-as-you-go and the API, Opus 5 is already the default Opus. If your version is older, run claude update and then /model to check.

Step 2, thinking now always runs

This is the actual migration, and it happens without you changing a single line.

On Opus 4.8 a request ran without thinking unless you explicitly set thinking: {"type": "adaptive"}. On Opus 5 the same request runs with thinking. The model decides when and how deeply to think, controlled through the effort parameter. The old value stays valid, thinking: {"type": "adaptive"} is now simply identical to the default.

The catch sits elsewhere: max_tokens is a hard ceiling on total output, thinking plus visible answer. Thinking tokens are not exempt from that limit. If you ran max_tokens: 16000 on 4.8 and that was enough without thinking, two consumers now share the same budget. Worst case the model thinks and the answer gets truncated.

# Opus 4.8, ran without thinking
client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "..."}],
)

# Opus 5, same request, thinking runs
# and counts against the same 16000
client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "..."}],
)

Walk through the workloads that used to run without thinking and raise max_tokens. As a rough number, budget 30 to 50 percent above what you previously needed for the answer alone, then measure instead of guessing.

Step 3, the 400 you need to know

thinking: {"type": "disabled"} still exists, but only up to effort level high. Combine it with xhigh or max and you get a 400 error back. On Opus 4.8 those were two independent switches, here it is one.

This is why the migration does not run through blind. If you disable thinking somewhere and run high effort at the same time, the request breaks. Not subtly, not slower, but immediately.

Two clean ways out. Either you leave thinking off and take effort down to high or below. Or you keep the high effort and simply remove the thinking field, which lets the default take over.

# Rejected
thinking={"type": "disabled"},
output_config={"effort": "xhigh"},

# Option A, thinking stays off, effort comes down
thinking={"type": "disabled"},
output_config={"effort": "high"},

# Option B, effort stays high, thinking field goes
output_config={"effort": "xhigh"},

Anthropic recommends option B, and there is a practical reason. With thinking disabled, Opus 5 occasionally writes a tool call as plain text into the response instead of emitting a clean tool_use block, or internal XML tags slip into the visible output. If your pipeline parses tool calls, that is exactly the class of bug you only notice in production. Keeping thinking on and controlling cost through lower effort is the stabler path.

Step 4, effort is the new main dial

The ladder is complete: low, medium, high, xhigh, max. Default is high. What is new is how much it matters. Opus 5 converts additional effort into better results more reliably than any Opus before it, which means the level you pick carries more weight than it used to.

Anthropic's advice: start at high and adjust in both directions based on your own evals. Down where quality holds, which saves tokens and latency. Up for the genuinely hard work. If you go to xhigh or max, set max_tokens generously, 64k is a usable starting point, so the model has room to think and act across multiple tool calls.

One trap specific to Claude Code that is easy to miss. For Fable 5, Opus 4.8 and Opus 4.7, Claude Code enforces the model's own default effort on first run, even if you once set something different for another model. Opus 5 does not do that. A level you set earlier carries over. So if you ran /effort low months ago and forgot about it, your Opus 5 runs on low and you wonder why the celebrated model answers so flatly. Typing /effort once to check costs five seconds.

Step 5, delete the verification sentence from your prompts

This is the point most people miss, because it has nothing to do with the API.

Opus 5 verifies its own work without being asked. Anthropic says so explicitly: remove verification instructions you wrote for older models. Sentences like "include a final verification step" or "use a subagent to verify" made sense on 4.8 and cause over-verification on Opus 5. The model then checks twice, burns more tokens and gets slower without getting better.

Search your system prompts, CLAUDE.md files and agent definitions for exactly those phrasings and cut them. It is the rare case where less prompt measurably buys more result.

Three more behaviour changes you will notice without touching code. Answers and written deliverables run longer than on 4.8. In agentic sessions the model narrates what it is doing more often. And in multi-agent setups it delegates to subagents more readily. None of that is a fault, but if your pipeline relies on short answers or a specific output shape, run your most important paths through once.

Step 6, the smaller additions

The prompt cache minimum drops from 1,024 to 512 tokens. Prompts that were too short to cache on 4.8 now create cache entries without you changing anything. If you run many short, recurring system prompts, that is silent savings.

Fast mode exists for Opus 5 too, as a research preview and on the Claude API only, not on Bedrock, Google Cloud or Microsoft Foundry. Price is 10 dollars input, 50 dollars output per million, so double the standard price for roughly two and a half times the speed. Same maths as on 4.8: only worth it where latency costs real money or real UX.

Two beta features, in case you need them. Tool lists can now be changed mid-conversation without losing the prompt cache, via beta header mid-conversation-tool-changes-2026-07-01. And the fallbacks parameter has a new "default" mode that uses Anthropic's recommended fallback models instead of a list you maintain yourself, via header server-side-fallback-2026-07-01.

What does not work on Opus 5

Manual extended thinking with budget_tokens is gone, only adaptive thinking through the effort parameter remains. Prefill through a prepared assistant message is unsupported, use system prompt instructions instead. The web fetch tool is not available. Priority Tier does not exist for Opus 5, Opus 4.8 keeps it. And as on 4.8, temperature, top_p and top_k throw a 400 as soon as you set them to anything but the default, so remove them entirely.

Migration checklist, seven points

One, switch the model field from claude-opus-4-8 to claude-opus-5 and drop every [1m] spelling while you are there.

Two, find all workloads that ran without a thinking field and raise max_tokens, because thinking tokens now count.

Three, search for the combination thinking: {"type": "disabled"} plus effort xhigh or max and resolve it, otherwise 400.

Four, remove temperature, top_p, top_k from all requests if you have not already.

Five, cut verification instructions from system prompts and agent definitions, they now cause over-verification.

Six, move to at least Claude Code v2.1.219 and check /effort once, because Opus 5 carries over an old level instead of setting the default.

Seven, re-measure cost and latency on your real workloads. Your 4.8 effort settings are no longer a good starting point.

Should you migrate

Yes. Same price, substantially stronger model, and Opus 4.8 stays available as a way back. The improvements sit exactly where agent operation hurts: staying on task across long tool-use loops, multistep reasoning, code review with few false positives, and coordinating several subagents without them overwriting each other.

But do not wave it through. The three things that can actually bite you are max_tokens now counting thinking, the 400 when thinking is disabled at high effort, and the old verification sentences in your prompts. You will find all three in ten minutes with grep.

What next

If you are coming from 4.7 or earlier, do the Opus 4.8 migration first and the Opus 4.7 migration before that, the old breaking changes live there. If you want to know how to catch model releases at all instead of discovering them by accident, Track model availability shows the setup. For the cost side of the new effort ladder, Claude Code cost controls for daily drivers has the measuring workflow. And before you take a migration to production, build yourself a small test set, Agent eval in 60 minutes covers that.

Source

• Anthropic, Claude Opus 5: https://www.anthropic.com/news/claude-opus-5
• What's new in Claude Opus 5: https://platform.claude.com/docs/en/about-claude/models/whats-new-opus-5
• Migration Guide: https://platform.claude.com/docs/en/about-claude/models/migration-guide
• Prompting Claude Opus 5: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5
• Claude Code Model Configuration: https://code.claude.com/docs/en/model-config