Claude Opus 5.5 Migration Guide: 4 Breaking Changes (2026)

Full Claude Opus 5.5 migration guide with fixes for the four breaking changes: thinking, tool_choice, thinking blocks, and computer_20251124.

By Muhammad Moeed ·September 23, 2026 ·17 min read

Anthropic shipped Claude Opus 5.5 on September 22, 2026. It is 20% cheaper on base tokens, 60% cheaper on cache reads, and now the default Opus model everywhere: Claude Code, the Claude app, and Cowork. The catch: it has four breaking API changes that will 400-error your Agent SDK code and your custom Messages API loops the first time you upgrade.

This guide walks through each of the four breaking changes in plain English. For every one you get: the exact error text, why it happens, a before-and-after code snippet, and the fix. Also included: the safe rollback path if you need to stay on Opus 5 for a few weeks.

If you have never touched the Anthropic API and only use Claude Code, jump to “What changed for Claude Code users” first. If you build with the Agent SDK or the raw Messages API, the four breaking changes below are what you actually need.

Quick answer

Release date: September 22, 2026
Model IDs: claude-opus-5-5 on Claude API, Vertex, Foundry, and Claude Platform on AWS. anthropic.claude-opus-5-5 on Bedrock (on the current Messages API for both Global and Regional endpoints; the legacy global.anthropic.claude-opus-5-5 CRIS profile is InvokeModel/Converse only).
Pricing: $4 input / $20 output per million tokens. Cache reads $0.20 per million. About 20% cheaper on base tokens and 60% cheaper on cache reads than Opus 5.
Context window: 1M tokens (unchanged). Max output 128k (unchanged).
Claude Code default: now Opus 5.5 on Pro, Team Standard, Max, Team Premium, and Enterprise plans. Requires Claude Code v2.1.280 or newer.
The 4 breaking changes:
1. Extended thinking is always on. thinking: {type: "disabled"} returns 400.
2. Forced tool_choice is not supported. Only auto and none work.
3. Thinking blocks are bound to the model and the exact conversation prefix. Editing the system prompt, tools, or earlier messages mid-conversation returns 400.
4. On the Claude API and Google Cloud Vertex, the old computer_20251124 tool is rejected. You must use computer_toolset_20260801. Bedrock still accepts the old one.
Rollback: pin to Opus 5 with --model claude-opus-5 or ANTHROPIC_MODEL=claude-opus-5. Opus 5 is still “Active (legacy)” with retirement not sooner than 2027-07-24.

What changed for Claude Code users

If you only use the Claude Code CLI (not the raw API), here is what shifted on September 22:

The default model flipped to Opus 5.5. On Pro and Team Standard plans, Claude Code v2.1.280 changed the default from Sonnet to Opus 5.5. Max, Team Premium, and Enterprise already defaulted to Opus, so they now automatically use Opus 5.5 instead of Opus 5.

The default effort level dropped. Opus 5 defaulted to high effort. Opus 5.5 defaults to medium. If your workflow relied on the deeper “high” reasoning by default, your outputs may feel shallower until you set effort explicitly with the /effort command.

Your saved effort level does not carry over. Any /effort setting you had before it became per-model does not apply to Opus 5.5. Every new model starts at its own default until you pick a level again.

Rate limits got bigger. Anthropic increased or removed the five-hour usage limits on Pro, Max, Team, and seat-based Enterprise plans, and added a saveable rate-limit reset you can trigger on demand. This softens the September 14 weekly-limit cut we covered in our weekly-limit guide.

How to switch back to Opus 5 (if you want to wait a week for the migration dust to settle):

In a live session: /model claude-opus-5
On launch: claude --model claude-opus-5
Hard override, session-wide: export ANTHROPIC_MODEL=claude-opus-5
Soft default for new sessions: export ANTHROPIC_DEFAULT_MODEL=claude-opus-5
Persistent, per-user: add {"model": "claude-opus-5"} to ~/.claude/settings.json

Pin the friendly opus alias to Opus 5 with ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5.

Beginner glossary (skip if you know these terms)

Extended thinking (adaptive thinking): a mode where Claude spends internal tokens reasoning before it answers. On Opus 5.5 this is always on. You control how much it thinks by setting an effort level (low, medium, high, xhigh, max).
Effort (output_config.effort): a dial that tells Opus 5.5 how hard to think. Default is medium. Set it inside output_config, not at the top level.
tool_choice: a request parameter that tells Claude how to pick a tool. auto lets Claude decide. none blocks tool use. On Opus 5 you could also force a call with any or tool. On Opus 5.5, any and tool return 400.
Computer use tool: a tool that lets Claude drive a screen (click, type, scroll, take screenshots). The old version was computer_20251124. Opus 5.5 on Claude API and Vertex requires computer_toolset_20260801, a bundle of 17 sub-tools.
System prompt: the top-level instructions you send with every request (role, rules, style). On Opus 5.5 do not rebuild this between turns. Doing so invalidates the thinking blocks the model already produced.
Prompt caching / cache read: a way to reuse the same prompt prefix cheaply on repeat calls. Cache reads on Opus 5.5 cost $0.20 per million tokens, five percent of the input price.
Breaking change: a change that makes code that worked before stop working. Opus 5.5 has four. Most show up as an HTTP 400 invalid_request_error the first time you call the new model with old parameters.

Breaking change 1: thinking cannot be disabled

Exact error text:

"thinking.type.disabled" is not supported for this model.
Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Root cause: on Opus 5.5, adaptive thinking is always on. The only knob is output_config.effort. Both thinking: {type: "disabled"} and the old manual thinking: {type: "enabled", budget_tokens: N} are rejected.

Before (Opus 5):

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

After (Opus 5.5):

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    output_config={"effort": "low"},  # thinking is always on; effort is the control
    messages=[{"role": "user", "content": "..."}],
)

Fix steps:

Remove the thinking field from your request entirely. Adaptive thinking is on by default and does not need a type value.
Add output_config={"effort": "low"} where you used to disable thinking to save tokens. Use medium, high, xhigh, or max for deeper work.
Remember the default effort dropped from high (Opus 5) to medium (Opus 5.5). Set effort explicitly and re-run your evals before shipping.
Update your tool-use loops. Every response can now begin with thinking blocks. Select content blocks by type, and pass thinking blocks back unmodified.
Do NOT set thinking: {type: "enabled", budget_tokens: N} either. That returns a parallel 400 error: "thinking.type.enabled" is not supported for this model.
Make sure you are on anthropic-sdk-python version that supports output_config (added around Claude 4.6). Upgrade if you are on an older SDK.

Who is affected: plain Anthropic Messages API callers, Agent SDK users, LangChain ChatAnthropic, and any framework that hardcoded thinking: {type: "disabled"} for latency or cost control. Claude Code, claude.ai, and Claude Managed Agents already comply.

Breaking change 2: forced tool_choice is not supported

Exact error text:

tool_choice: type "tool" and "any" are not supported for this model.

Root cause: Opus 5.5 rejects tool_choice values that force a specific tool. Only auto and none are accepted, on both the Messages endpoint and the token counting endpoint.

Before (Opus 5):

client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

After (Opus 5.5):

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    # strict tool use: every call matches the tool's input_schema
    tools=[{**tool, "strict": True} for tool in tools],
    tool_choice={"type": "auto"},
    messages=[
        {
            "role": "user",
            "content": "What's the weather in Paris? Use the get_weather tool.",
        }
    ],
)

Fix steps:

Change tool_choice to {"type": "auto"} everywhere. This is the default.
For schema-valid JSON, mark each tool with strict: true so every call matches the tool’s input_schema.
If you need JSON that is not a tool call, move the schema to structured outputs instead of a forced tool_choice.
Tell the model in the prompt when the tool applies (for example, “Use the get_weather tool.”).
Audit your token counting calls too. The same validation runs there and will 400.

Who is affected: any framework that binds tools with a required or named choice. Vercel AI SDK, LangChain and langchain-aws, CrewAI, Arize Phoenix, LiveKit agents, LangChain deepagents’ RubricMiddleware, lobehub, and many others have open issues on this. The same restriction applies to Fable 5.1, so any cross-model code hits it too.

Breaking change 3: thinking blocks are bound to the model and the conversation

Exact error text:

messages.1.content.0: Invalid `signature` in `thinking` block.
The block is bound to a different conversation.
Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".
That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.

Root cause: every Opus 5.5 thinking block is cryptographically signed against the exact prefix (system prompt, tools array, and earlier messages) that produced it. If you edit any of those before replay, the signature check fails and the API hard-errors with 400. This is enforced by default for accounts created on or after 2026-08-31 00:00 UTC. Older accounts can opt in with a beta header.

Before (Opus 5):

# Opus 5 pattern: rebuild the system prompt each turn to inject today's date
system_prompt = f"You are a coding assistant. Today is {today()}."
response = client.messages.create(
    model="claude-opus-5",
    system=system_prompt,
    tools=tools,
    messages=history,  # earlier turns kept, including prior thinking blocks
)

After (Opus 5.5):

# Opus 5.5 pattern: keep the top-level system prompt stable, and
# push changing context in as a mid-conversation system message.
response = client.messages.create(
    model="claude-opus-5-5",
    system="You are a coding assistant.",  # stable across turns
    tools=tools,                             # stable across turns
    messages=history + [
        {"role": "system", "content": f"Today is {today()}."},
        {"role": "user", "content": user_msg},
    ],
)

Fix steps:

Keep the conversation append-only. Do not edit the system prompt, tools array, or earlier messages mid-conversation.
Move changing context (date, mode flags, memory) into a mid-conversation system message inside messages. No beta header needed.
For a reminder that should disappear after the next user turn, add clear_at: "next_user_message" with the beta header mid-conversation-system-clear-at-2026-08-21.
To add or remove tools mid-conversation without editing the tools array, use tool_addition and tool_removal blocks with the beta header inline-tools-2026-09-15.
If you must edit the prefix, opt in to silent drops: beta header thinking-binding-controls-2026-08-01 and set thinking.block_binding.prefix_mismatch_behavior to "drop_block".
Replace client-side history compaction with server-side compaction (beta compact-2026-09-04) or context editing (context-management-2025-06-27 rule clear_tool_uses_20250919).

Who is affected: hand-rolled Messages API loops that rebuild system, tools, or earlier messages per turn. Enforcement is default on accounts created on or after 2026-08-31 UTC, and opt-in on older accounts. Claude Code, claude.ai, Claude Managed Agents, and the Claude Agent SDK already run append-only, so they are not affected.

Breaking change 4: `computer_20251124` is not supported (Claude API and Google Cloud)

Exact error text:

'claude-opus-5-5' does not support tool types: computer_20251124.

Root cause: on the Claude API and Google Cloud Vertex, Opus 5.5 accepts only the new computer_toolset_20260801 toolset. Declaring the legacy computer_20251124 tool returns 400. Amazon Bedrock still accepts computer_20251124 unchanged.

Before (Opus 5, computer use):

client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["computer-use-2025-11-24"],
    tools=[{
        "type": "computer_20251124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
    }],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

After (Opus 5.5, computer use):

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    # no beta header; the toolset entry takes no name or display size
    tools=[{"type": "computer_toolset_20260801"}],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

Fix steps:

Drop the computer-use-2025-11-24 beta header.
Replace your computer_20251124 tool entry with a single {"type": "computer_toolset_20260801"} entry. No name, no display_width_px, no display_height_px, no strict: true.
Update the agent loop. Each member tool call arrives as a tool_use block whose action is the block’s name (not input.action). One turn can carry several member calls (batched actions).
Echo toolset_name on every tool_result you send back.
Amazon Bedrock users are safe: the legacy computer_20251124 tool declaration still runs on Opus 5.5 there without any code change.
On Claude Platform on AWS and Microsoft Foundry, computer_toolset_20260801 is currently beta. Only earlier beta tool versions are GA on those platforms today.

Who is affected: any computer-use agent on the Claude API or Google Cloud Vertex that declared computer_20251124. Bedrock users are not affected. Fable 5.1 and Mythos 5.1 never accepted computer_20251124 at all, so any cross-model code should move to the toolset regardless.

One extra thing to know: text between tool calls returns as thinking blocks

This is not a breaking change, but it will surprise you. On Opus 5.5, the narration Claude used to write between tool calls now returns as progress-update thinking blocks, not as text blocks. At the default display level they show as empty (label: “omitted”).

To restore visible progress updates, add the beta header thinking-display-updates-2026-08-18 and set display to "updates" or "summarized".

Safe rollback: pin to Opus 5

If your migration needs more than 48 hours, pin Opus 5 while you fix things:

On the Claude API:

client.messages.create(
    model="claude-opus-5",  # legacy model ID, still Active (legacy)
    ...
)

The model parameter is authoritative per request. There is no env var override for the raw Messages API itself.

On Claude Code: use any of the five methods listed under “What changed for Claude Code users” above. Precedence, highest to lowest: --model flag, ANTHROPIC_MODEL env var, settings.json model field, ANTHROPIC_DEFAULT_MODEL env var, account default.

Model IDs for the older version by platform:

Claude API: claude-opus-5
Amazon Bedrock: anthropic.claude-opus-5
Google Cloud Vertex: claude-opus-5
Microsoft Foundry: claude-opus-5

Gotchas:

Opus 5 is more expensive: $5 / $25 per MTok versus $4 / $20 on Opus 5.5, and cache reads are $0.50 vs $0.20. Pinning to Opus 5 is roughly a 20% base cost premium (and about 40% higher on typical workloads per Anthropic’s own numbers).
Opus 5 is not deprecated. It is “Active (legacy)” with retirement not sooner than 2027-07-24. Anthropic guarantees at least 60 days notice before retirement, but plan a migration window anyway.
Google Cloud sets its own retirement dates independent of Anthropic.
On Bedrock, Opus 5.5 also requires Claude Code v2.1.280 or newer.
Switching model IDs mid-conversation: Opus 5.5 can read thinking blocks from Opus 5 and earlier Opus, Sonnet, and Haiku, but not from Fable or Mythos. Going the other way, only Fable 5.1 and Mythos 5.1 can read Opus 5.5 thinking blocks.

FAQs

Can I disable thinking on Claude Opus 5.5?

No. Adaptive thinking is always on. The only control is the effort field inside output_config, with values low, medium, high, xhigh, and max. Default is medium. If your old code sent thinking: {type: "disabled"}, remove it (or set thinking: {type: "adaptive"}) and add output_config: {effort: "low"} to save tokens.

Why does my request return “thinking.type.disabled is not supported for this model”?

You are calling Opus 5.5 with the old thinking parameter that used to work on Opus 5. Opus 5.5 rejects both {type: "disabled"} and {type: "enabled", budget_tokens: N}. Fix: remove the thinking field and set output_config: {effort: "low"} if you want to save tokens.

How do I force a tool call on Opus 5.5?

You cannot with tool_choice. {type: "any"} and {type: "tool", name: "..."} both return 400. Two alternatives: (1) use tool_choice: {type: "auto"} with strict: true on your tool schemas so any call matches the input schema, or (2) tell the model in the prompt when the tool applies (for example, “Use the get_weather tool for this request.”).

What is the default effort on Opus 5.5?

medium. Opus 5 defaulted to high. If your workflow depended on the deeper reasoning by default, your outputs may feel shallower until you set effort explicitly. In Claude Code, use /effort high (or any level). In the API, add output_config: {effort: "high"} to the request.

What is the Bedrock model ID for Opus 5.5?

anthropic.claude-opus-5-5 on the current Messages API for both Global and Regional endpoints. The legacy global.anthropic.claude-opus-5-5 CRIS profile still exists for InvokeModel/Converse callers. Regional endpoints in US, EU, AU, and JP carry a +10% premium over the Global one.

Does my `computer_20251124` integration still work on Opus 5.5?

Depends on the platform. Amazon Bedrock callers are unaffected. The legacy computer_20251124 tool declaration still runs untouched on Opus 5.5 there. On the Claude API and Google Cloud Vertex you must switch to computer_toolset_20260801, otherwise every request 400s. On Claude Platform on AWS and Microsoft Foundry, computer_toolset_20260801 is currently in beta, so only older beta tool versions are GA on those two platforms today.

How much cheaper is Opus 5.5 than Opus 5?

Base tokens: 20% cheaper. Input drops from $5 to $4 per million. Output drops from $25 to $20 per million. Cache reads: 60% cheaper, from $0.50 to $0.20 per million. Anthropic claims Opus 5.5 costs about 40% less than Opus 5 on typical workloads and generates output more than 30% faster.

What accounts are affected by the thinking-block enforcement date?

Accounts created on or after 2026-08-31 00:00 UTC have the thinking-block signature enforcement on by default. If you edit the system prompt, tools, or earlier messages before replay, you get a 400. Older accounts can opt in with the beta header thinking-binding-controls-2026-08-01.

Can I switch from Opus 5.5 back to Opus 5 mid-conversation?

Yes, but with a caveat about thinking blocks. Opus 5.5 can read Opus 5 thinking blocks, but Opus 5 cannot read Opus 5.5 thinking blocks. Only Fable 5.1 and Mythos 5.1 can. If you send a conversation with Opus 5.5 thinking blocks to Opus 5, the model will simply ignore them (or you can strip them yourself before switching).

Does Opus 5.5 keep the 1M token context window?

Yes. The context window is unchanged at 1M tokens, and max output stays at 128k tokens.

What we still do not know

The exact rate-limit percentage change. Anthropic’s docs say “increasing five-hour usage limits” and press reports say “scraps five-hour usage caps,” but a specific percentage was not confirmed in the primary sources we could verify. Treat any “25% further” figure as unverified until Anthropic publishes numbers.
When Fast mode will reach Bedrock, Vertex, and Foundry. Currently Claude API only, and still labelled research preview.
Whether max effort is safe for production. Simon Willison reported Opus 5.5 at max exhausting the 128k output-token budget on trivial prompts. That is one developer’s report, not an Anthropic-confirmed limitation, but worth flagging.
Formal Opus 5 retirement date. No notice as of 2026-09-23. Anthropic’s policy is at least 60 days notice before retirement.

Where to go next

Claude Code Weekly Limit Cut Sept 14: the earlier limit change that Opus 5.5’s rate-limit expansion partially offsets.
Claude Agent SDK Credit Pool: how Agent SDK billing sits alongside the model-choice decision.
Claude Code Skills vs MCP vs Hooks vs Plugins: the primitive that switches models cleanly (Skills) versus the one that does not (Hooks).
MCP Server Not Connecting Fix Guide: if MCP tool calls started failing after your Opus 5.5 upgrade, check this before assuming the model.
Claude Code Auto Mode + Containment Escape: the classifier model that is now free on API, Bedrock, and Vertex (Sept 19 change).

Last updated: September 23, 2026. I will re-check this page when Anthropic publishes the exact rate-limit numbers, when Opus 5 gets a formal retirement date, or when the next Opus 5.5 point release ships.

Quick answer

What changed for Claude Code users

Beginner glossary (skip if you know these terms)

Breaking change 1: thinking cannot be disabled

Breaking change 2: forced tool_choice is not supported

Breaking change 3: thinking blocks are bound to the model and the conversation

Breaking change 4: computer_20251124 is not supported (Claude API and Google Cloud)

One extra thing to know: text between tool calls returns as thinking blocks

Safe rollback: pin to Opus 5

FAQs

Can I disable thinking on Claude Opus 5.5?

Why does my request return “thinking.type.disabled is not supported for this model”?

How do I force a tool call on Opus 5.5?

What is the default effort on Opus 5.5?

What is the Bedrock model ID for Opus 5.5?

Does my computer_20251124 integration still work on Opus 5.5?

How much cheaper is Opus 5.5 than Opus 5?

What accounts are affected by the thinking-block enforcement date?

Can I switch from Opus 5.5 back to Opus 5 mid-conversation?

Does Opus 5.5 keep the 1M token context window?

What we still do not know

Where to go next

Breaking change 4: `computer_20251124` is not supported (Claude API and Google Cloud)

Does my `computer_20251124` integration still work on Opus 5.5?