Moving to Claude Opus 5.5: Five Breaking Changes Behind the Model ID

One string, five surprises

Picture the Friday after the release announcement. Anthropic has shipped Claude Opus 5.5 (September 22, 2026), described as Fable-level on most work, around 40% cheaper on a typical run, with list pricing of $4 input and $20 output per million tokens. Everyone is excited about the discount, while your production harness is still shaped for Opus 5 and only a model string stands in the way. You change model to claude-opus-5-5.

The first canary doesn't look smarter. It fails with an HTTP 400 over thinking you believed was off, or over a tool_choice your loop forces on every turn. Or the request goes through, tool chips keep appearing, and the narration between tools that your progress UI used to stream goes silent. No error, no brighter agent, and ops starts wondering whether the job hung.

This is a pre-flight gate and not a launch recap. Five things wait behind the new model ID: always-on thinking, forced tool use, thinking blocks tied to their model, a retired computer-use tool, and a change in stream shape that never produces a 400. Swapping the string is easy. Surviving the next request is the real work.

What the coverage said and what the docs say

Press coverage centered on price. The announcement and the articles around it pushed the Fable-level claims, the cyber safeguards and a cheaper Opus. Anthropic's figures back that up: Fable 5.1-class results on most tasks, roughly 40% lower spend on a typical run, $4 / $20 versus $5 / $25 for Opus 5, and output more than 30% quicker. A $0.20 cache-read rate is one line in the pricing list and isn't the headline.

The documentation says less, but it's precise. Its platform overview names four breaking changes for code that already runs on Opus 5. Thinking can't be turned off. Forced tool use errors. Thinking blocks are pinned to a model and conversation. And the older computer_20251124 tool isn't accepted on the Claude API or Google Cloud.

The risk lands on custom Messages API agent loops, multi-model routers, workflows that force a tool and computer-use agents on the Claude API or GCP, because all of them still send Opus 5 request shapes. Some setups are safer. Claude Managed Agents need only the new model name, and Claude Code and the Agent SDK append to conversations, which lowers exposure to thinking binding. Claiming that everything breaks would be inaccurate. Still, the upgrade deserves adopting, and the damage is real for anyone who treats a launch post as a ship gate. Prices dropped while the request rules tightened, so this isn't a drop-in string swap.

The five items are:

1. Adaptive thinking is always on. Both thinking.type.disabled and enabled with budget_tokens return a 400.
2. Forced tool_choice of any or tool returns a 400.
3. Thinking blocks are bound to the model that wrote them, so routers lose unreadable reasoning while the request still succeeds.
4. computer_20251124 is rejected on the Claude API and GCP (Bedrock still accepts it).
5. Narration between tools moves into thinking blocks that are empty under the default display: "omitted", and this never raises a 400.

Four of these paths fail loudly with a 400. The quiet stream doesn't, which is how a progress UI dies behind a 200. Default effort moved as well: Opus 5 used high and 5.5 uses medium, so a naive flip alters behavior even with no error. A cheaper Opus that rejects your harness is downtime with a press release.

Break one: thinking can't be switched off

On Opus 5, sending thinking: {"type": "disabled"} at effort high or lower worked, and so did manual enabled with budget_tokens. Opus 5.5 ignores what your latency path used to do. The docs say adaptive thinking is always on and depth is controlled through the effort parameter.

Send thinking.type.disabled and the API replies with an HTTP 400 pointing at thinking.type.adaptive and output_config.effort. The enabled form fails the same way. Chat routes tuned for latency and cheap tool loops that turned thinking off to save tokens break first, on the first call after the flip. Code that expects the first content block to be text fails as well, since responses may open with thinking blocks whose text is empty under the default display: "omitted".

Fixes:

• Omit thinking, or send {"type": "adaptive"}.
• Set depth with output_config.effort, remembering the default is medium. Where you once disabled thinking, pick low.
• Select content blocks by type, and echo thinking back unmodified in tool loops.
• Leave headroom in max_tokens for thinking you can no longer turn off.

Always-on doesn't mean always-more, since effort is the dial. A fast mode (about 2.5x speed at $8 / $40) exists on the Claude API only, for cases where latency is the true constraint, and not on Bedrock or GCP. thinking: disabled isn't merely deprecated. It's a 400.

Break two: no more forced tool use

Opus 5.5 doesn't support forced tool use, which is a behavior change and not a soft deprecation. A tool_choice of {"type": "any"} or {"type": "tool", "name": "..."} returns a 400 stating that the tool and any types aren't supported for this model. auto (the default) and none still work.

Agents that force a tool each turn, such as weather lookups, database calls or an "always call search_codebase" rule, break here, as does schema enforcement that relied on naming a tool. CI preflights that hit the token-count endpoint with a forced choice fail too, so a canary can die in billing math before the Messages call even happens. From the outside the outage reads as "we only changed the model," while the stack trace shows you're still sending an Opus 5 control plane.

Fixes:

• Use tool_choice: {"type": "auto"}.
• Add strict: true to tools, or use structured outputs.
• Spell out in the prompt when each tool should be used, for example "call the get_X tool when...", which works better than a forced selection that the API now rejects.
• Run every count_tokens call again if it still passes any or tool.

This fails before the model runs, and there's no soft fallback where it mostly calls the tool. An "always call search" policy has turned into a deploy blocker.

Break three: thinking blocks tied to a model

Each thinking block is stamped with the model that wrote it, and a model can interpret its own blocks plus a limited set from other models. Opus 5.5 handles thinking from Opus 5 and older Opus, Sonnet and Haiku releases. Fable and Mythos output is outside that set. Going the other direction, only Fable 5.1 and Mythos 5.1 (on the Claude API) can interpret what Opus 5.5 wrote.

If a router or fallback sends a conversation from claude-opus-5-5 to Sonnet, GPT or another model, the API discards blocks the target can't read. The request still succeeds, and the discarded blocks aren't billed. What follows is a silent drop in quality, with no 400, shallower reasoning and a dashboard that stays green.

Altering system, tools or earlier turns partway through a conversation may invalidate blocks too. Accounts opened on or after August 31, 2026 (00:00 UTC) get a 400 by default when a thinking block is replayed after a prefix edit. The beta thinking-binding-controls-2026-08-01 allows prefix_mismatch_behavior: "drop_block" instead. Claude Code, claude.ai, Managed Agents and the Agent SDK already append only, which keeps their exposure low.

Fixes:

• Keep conversations append-only.
• Change instructions with mid-conversation system messages and not by rewriting the prefix.
• Count a model switch as a reset of reasoning unless the docs promise otherwise.
• Return thinking blocks as they came, and don't assume each Claude model can follow 5.5's reasoning after a handoff.

A fallback that "succeeds" can still discard the reasoning that made the turn work.

Break four: the old computer-use tool

Opus 5 took both computer_toolset_20260801 and, under a beta, computer_20251124. On the Claude API and Google Cloud, Opus 5.5 takes only the toolset, and declaring computer_20251124 returns a 400 that begins by saying claude-opus-5-5 doesn't support that tool type. Amazon Bedrock still accepts it, so nothing changes there. The model family is the same while the platform matrix differs, so Bedrock-only teammates shouldn't be pushed into a rewrite they don't need.

Desktop and browser agents on the Claude API or GCP that still declare the old type and send the computer-use-2025-11-24 beta header fail at the first tool declaration. Swapping the type alone doesn't finish the job, since loops that read input.action break too. Member tool_use blocks put the action in the block name, one turn can hold several tool uses, and each result needs toolset_name: "computer" echoed back.

Fixes:

• Remove the beta header.
• Send tools=[{"type": "computer_toolset_20260801"}], leaving out name and display dimensions on the declaration.
• Update the agent loop so it uses member names and toolset_name.

Capability went up (a company-reported OSWorld 2.0 score of 81.8%, flagged as partial), and the integration footgun arrived along with it.

Break five: the stream goes quiet

Under Opus 5, the chatter between tool calls came through as text blocks, so the UI could print something like "Checking migrations..." and ops stayed calm. Opus 5.5 shares Fable 5.1's shape, and there that chatter shows up as progress-update thinking blocks, one at most before each tool call. Since thinking.display defaults to "omitted", the thinking field arrives empty. The docs warn that a UI streaming those lines as progress goes silent between tool calls until a display value is chosen that returns the text.

No request fails and the status is 200. Tool chips still show, but the chatter between them is gone, and users decide the agent hung.

Fixes:

• Choose display: "updates" (needs the beta thinking-display-updates-2026-08-18) for progress text without the reasoning, or "summarized" for both, and render any non-empty thinking before the tool_use that follows. Hand blocks back untouched.

The four hard breaks shout with a 400, and this one never does, which is how progress UIs die on a canary that looks successful. The nastiest migration bug is the one that returns 200.

The ship or no-ship checklist

Treat the flip as a canary gate and not a Friday config tweak. Before claude-opus-5-5 sees traffic:

• Update the model ID to claude-opus-5-5, using the platform-specific ID on Bedrock, GCP or Azure.
• Remove thinking: disabled and enabled with budget_tokens, then set output_config.effort explicitly, since the default is medium.
• Replace tool_choice of any or tool with auto, plus strict tools or structured outputs and a prompt instruction.
• For computer use on the Claude API or GCP, move to computer_toolset_20260801 and update the agent loop. Bedrock may keep computer_20251124.
• In routers, expect lost thinking when leaving 5.5, except for Fable or Mythos 5.1 on the Claude API.
• Select content by type and echo thinking blocks unmodified.
• In progress UIs, set display to "updates" or "summarized".
• Keep conversations append-only, and follow the preserved-thinking guidance if prefixes get edited, especially on accounts created from August 31, 2026.
• Re-baseline cost and latency at the effort you actually want, and test in development before production traffic.
• Optionally, run the Claude Code /claude-api migrate skill.

Only Claude Managed Agents can flip with the name alone, and the docs say nothing beyond the model name needs updating there. Custom Messages API harnesses aren't in that group, and they keep Opus 5 request shapes until the list is green. The migrate skill can catch stale shapes before the flip, but routers and progress UIs still need your own testing, because it doesn't replace a canary. The default effort fell from Opus 5's high to 5.5's medium, so don't carry old high-effort assumptions into a medium default.

Take the upgrade on purpose

Opus 5.5 is worth adopting deliberately, for Fable-class claims, roughly 40% lower cost per typical run and faster output. Migrate because the model is better, and not because a launch announcement felt like a ship gate. The request shape is what matters now, and four documented breaks plus the quiet stream make up the gate. Coverage doesn't list them beside the price cut.

Hard 400s are loud, while router drops and display: "omitted" are quiet, so instrument both or you'll only catch failures that shout. Platform differences count: Bedrock still accepts computer_20251124 and the Claude API and GCP don't. Managed Agents need a name change, but a custom Messages API harness gets no such free pass. Effort replaced the off switch, so cost and latency need a fresh baseline, and disabled-thinking economics shouldn't be assumed to carry over.

Changing the string costs nothing, while migrating does. The upgrade is genuine and the drop-in story is fiction. Work down the checklist, re-baseline effort and only then route traffic to claude-opus-5-5.