Claude Opus 5: What Breaks When You Migrate from Opus 4.8

Anthropic shipped Claude Opus 5 on 24 July, and the migration note is unusually short: change the model string. Pricing is flat, the context window is unchanged, and existing prompts carry over.

Then you read the two behavior changes and realize one of them fails silently.

I went through this on my own projects over the weekend. The model ID swap took thirty seconds. Working out why one route started returning truncated answers took considerably longer, and the answer turned out to be documented in a single sentence I had skimmed past. So here is the migration in the order it actually bites you.

What is Claude Opus 5 and what does it cost?

Claude Opus 5 is Anthropic's current Opus-tier model, released 24 July 2026 with the API model ID claude-opus-5. It costs $5 per million input tokens and $25 per million output tokens, identical to Claude Opus 4.8. There is no long-context premium and no date suffix on the ID.

The specs that matter:

That "default and maximum" detail on the context window is worth reading twice. There is no smaller context variant to opt into, which removes a config knob some teams were using to control cost.

On benchmarks, Anthropic reports Opus 5 landing within 0.5% of Claude Fable 5 on CursorBench 3.2 at half the price, roughly three times the next-best score on ARC-AGI 3, and about 1.5 times the next-best pass rate on Zapier's AutomationBench. Treat vendor benchmarks as vendor benchmarks. The claim I find more useful is the shape of the gains: deep reasoning, long agentic loops, and test-time compute scaling, meaning the model converts extra effort into better answers more reliably than earlier Opus versions did.

It is available on the Claude API as claude-opus-5, on Amazon Bedrock as anthropic.claude-opus-5, and on Google Cloud and Microsoft Foundry under the bare ID. Opus 4.8 stays available everywhere, so there is no forced cutover.

One operational detail that is easy to miss: Claude Opus 5 draws on a separate rate-limit bucket from the combined Opus 4.x pool. Moving traffic over does not free headroom on the old bucket and does not inherit it. Check your tier's Opus 5 limits before you shift real volume.

Why does thinking being on by default break your max_tokens?

Because max_tokens caps thinking plus reply text together, and on Opus 4.8 a request that omitted the thinking field produced no thinking at all. The same request on Opus 5 thinks. Your reply now shares a budget it used to own outright.

This is the change that cost me an afternoon. Nothing throws. The request returns HTTP 200, stop_reason comes back as "max_tokens", and the answer is cut mid-sentence. If you are logging only errors, you will not see it.

The wire format did not change. thinking: {"type": "adaptive"} is still valid and is exactly equivalent to the new default. What changed is what happens when you say nothing:

# Opus 4.8: no thinking field means no thinking.
# 4096 tokens was all reply text.
client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[{"role": "user", "content": prompt}],
)
 
# Opus 5: identical call, but thinking now runs and eats
# into the same 4096. Long answers get truncated.
client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": prompt}],
)

You have two honest fixes. Raise max_tokens to leave room for both, which is what I did on every route where the answer length varies. Or keep the old behavior explicitly:

client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    thinking={"type": "disabled"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": prompt}],
)

That second option comes with its own trap, which is the next section.

Audit target: every call site that never set a thinking field. Those are the ones that silently changed behavior. Routes that already passed {"type": "adaptive"} are unaffected.

Why does disabling thinking now return a 400 error?

Because on Claude Opus 5, thinking: {"type": "disabled"} is only accepted when effort is high or below. Pair it with xhigh or max and you get a 400. On Opus 4.8 the two settings were independent, so this is a genuine breaking change rather than a default shift.

The part that catches people is that validation runs per request. Effort and thinking are checked independently on every call. A conversation can run happily for twenty turns at high with thinking off, then fail the moment your code bumps effort to xhigh for a harder step. Earlier success in the same session buys you nothing.

# 400 invalid_request_error on Claude Opus 5
client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    thinking={"type": "disabled"},
    output_config={"effort": "xhigh"},   # <- rejected
    messages=[{"role": "user", "content": prompt}],
)

Pick one of two resolutions. Keep thinking off and cap effort at high, which costs you the top two tiers. Or delete the thinking field and keep the effort tier, which costs tokens and buys back quality.

My advice is the second one, and not just for compliance. Anthropic documents two real failure modes with thinking disabled on Opus 5: the model occasionally writes a tool call into its visible text instead of emitting a tool_use block, and it can leak internal XML tags into the response. The first is nastier than it sounds. The turn completes normally, no error is raised, and the tool never runs. In an agentic loop that phantom call then sits in the history and skews later turns.

If a route genuinely must keep thinking off, the documented mitigations are counterintuitive enough to be worth stating plainly:

• Give the model permission to talk first: "You may say a brief sentence before using a tool." The tool-call-as-text failure appears to come from suppressing the preamble it wants to write.
• Delete any instruction telling it not to think or not to reason. That kind of rule makes tag leakage worse, not better.
• Write the tag instruction generically. "Do not include internal or system XML tags in your response" works better than naming thinking tags explicitly.

For most teams, running at low or medium effort with thinking on is cheaper and better behaved than disabling thinking at high.

How should you pick an effort level on Claude Opus 5?

Start at high, which is the default, then sweep in both directions against your own evals. Effort carries more weight on Opus 5 than on any earlier Opus, because the model converts extra effort into better output more reliably.

Anthropic's published starting points and the model's measured behavior pull in slightly different directions, and both are useful:

• Start xhigh for coding and agentic work, high for other intelligence-sensitive workloads. max is the top tier for the deepest reasoning, though it can overthink simple tasks.
• Then sweep downward, because low and medium are unusually strong here. They deliver good quality at a fraction of the tokens and latency on plenty of workloads.

Do run the sweep. Effort defaults inherited from Opus 4.8 or 4.7 are rarely the right setting on this model, and I would not trust a number carried over from a previous migration. If you kept effort notes from the Opus 4.7 release, re-run them rather than reusing them.

At xhigh or max, set a large max_tokens so the model has room to think and act across tool calls and subagents. Start at 64000 and tune down. And stream anything that large, or you will hit SDK HTTP timeouts before the model finishes:

with client.messages.stream(
    model="claude-opus-5",
    max_tokens=64000,
    output_config={"effort": "max"},
    messages=[{"role": "user", "content": prompt}],
) as stream:
    response = stream.get_final_message()

What new API features ship with Claude Opus 5?

Three, and two of them are behind beta headers. None are required to migrate.

Mid-conversation tool changes (beta mid-conversation-tool-changes-2026-07-01) let you add or remove tools between turns without invalidating the prompt cache. Previously the tool list was fixed for a conversation's lifetime and any edit re-billed the entire prefix, because tools render at position zero. You declare the tool up front with "defer_loading": true, then surface it later with a tool_addition block on a system message. This is the control-plane counterpart to tool search: tool search is for discovery, this is for when your application knows the tool set changed.

Default fallbacks mode (beta server-side-fallback-2026-07-01) is the one I would turn on for everyone. Opus 5 ships with stricter cybersecurity safeguards, and its classifiers can decline a request. A decline is an HTTP 200 with stop_reason: "refusal", not an error, so code that reads response.content[0] unconditionally breaks on it. The fallbacks parameter re-runs a declined request on another model server-side:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    betas=["server-side-fallback-2026-07-01"],
    fallbacks="default",
    messages=[{"role": "user", "content": prompt}],
)
 
if response.stop_reason == "refusal":
    handle_refusal(response.stop_details)

Prefer "default" over pinning a model. It routes by refusal category, and it saves you a migration the next time a pinned fallback gets deprecated. Cyber-category refusals route to Opus 4.8. Note this is Claude API only, so on Bedrock, Google Cloud, or Foundry you need the SDK's client-side fallback middleware instead.

A lower prompt cache minimum, at 512 tokens, down from 1024 on Opus 4.8. No code change, but it is worth re-checking prompts you previously wrote off as too short to cache. Anything between 512 and 1024 tokens now creates cache entries for free.

Which prompt instructions should you delete after migrating?

The verification ones. Claude Opus 5 verifies its own work without being asked, so instructions like "include a final verification step" or "use a subagent to verify" now cause over-verification rather than preventing errors.

This inverts a standard prompting rule. "Ask the model to double-check itself" is generally sound advice and it is wrong here. If you keep a shared prompt library, that needs a carve-out for this model rather than a global rule. The same applies to framework-level scaffolding. Separate verification passes carried over from earlier models are likely redundant now.

Three other behavior shifts are worth tuning for, all documented by Anthropic:

Responses run longer. Both conversational output and files the model writes to disk. Lowering effort does not reliably shorten visible output, so this is a prompting fix, not a config one. A short conciseness instruction is the lever.

It narrates progress more in agentic sessions. If you added scaffolding to force interim status updates ("after every three tool calls, summarize"), remove it. Opus 5 does this on its own, and the combination is noisy.

It delegates to subagents more readily. This is a direction change worth flagging, because Opus 4.8 under-reached for subagents and needed prompting to delegate at all. If you added "delegate more" guidance for 4.8, take it out, and consider an explicit cap. Each subagent re-establishes context, re-explores, reports back, and then the coordinator re-reads the report. That multiplies both cost and latency.

It can also expand task scope, adding steps you did not request. A short scope-discipline instruction handles it: deliver what was asked at the scope intended, flag a concern in a sentence if the ask looks wrong, and keep going rather than quietly widening the work.

Should you migrate to Claude Opus 5 today?

If you are on Opus 4.8, yes, and the cost case makes it easy: identical pricing, better output. The two breaking changes are both mechanical and both findable with a grep.

Here is the checklist I actually used:

1. Swap the model ID to claude-opus-5.
2. Grep for call sites with no thinking field. Raise max_tokens on each, or set {"type": "disabled"} deliberately.
3. Grep for "disabled" paired with xhigh or max effort. Fix both sides of the pair.
4. Re-run your effort sweep from scratch. Do not reuse 4.8 numbers.
5. Add a stop_reason == "refusal" branch before reading content, and turn on fallbacks: "default".
6. Delete verification instructions and forced progress-update scaffolding from your prompts.
7. Confirm your rate-limit headroom on the new bucket before shifting volume.

Steps 1 to 3 are required. The rest is the difference between a migration that works and one that works well.

The thing I keep coming back to is step 6. We spent two years writing prompts that compensated for models which did not check their own work, did not narrate progress, and would not delegate. Those instructions are now actively counterproductive. Migrating to a better model is turning out to be less about adding capability and more about deleting the scaffolding you built for the last one, which is a strange and slightly humbling way to upgrade.

For the full specification, see Anthropic's What's new in Claude Opus 5, the Claude Opus 5 announcement, and the model migration guide.

Keep Reading

• Claude Opus 4.7: Pricing, Benchmarks & Breaking Changes. The previous Opus migration, where adaptive thinking and the removal of sampling parameters first landed.
• Claude Mythos and Project Glasswing: Anthropic's Locked-Down AI Model. Where the Fable and Mythos tier sits relative to Opus, and why Opus 5 at half the price matters.
• 10 Best Claude Skills for Developers in 2026. Skills that pair well with the longer agentic runs Opus 5 is built for.