What breaks when migrating from Claude Opus 5 to Opus 5.5?

Four request patterns that worked on Opus 5 return a 400 invalid_request_error on Opus 5.5: thinking set to disabled or a manual budget_tokens (thinking is always adaptive; control depth with output_config.effort), tool_choice set to any or a named tool (only auto and none are accepted), replaying a thinking block after the system prompt, tools or an earlier message changed (enforced by default for accounts created on or after August 31, 2026), and on the Claude API and Google Cloud the legacy computer_20251124 tool, which must become computer_toolset_20260801. The first three also apply on Claude Fable 5.1.

Why did my Claude Opus 5.5 agent stop showing progress between tool calls?

Opus 5.5 returns the short notes it writes between tool calls as progress-update thinking blocks instead of text blocks. At the default thinking display setting of omitted, those blocks arrive with empty text, so a UI that streamed them goes quiet between tool calls with no error. Set thinking.display to a value that returns the text, select content blocks by their type field rather than by position, and pass thinking blocks back unmodified in your tool-use loop.

Do I need to change my effort setting for Claude Opus 5.5?

Yes. The default effort on Opus 5.5 is medium, whereas Opus 5 defaulted to high, so a request that omits effort now runs cheaper and shallower. At the same effort level Opus 5.5 also thinks more per turn than Opus 5, most of all at xhigh and max; Artificial Analysis measured about 119,000 output tokens per Intelligence Index task at max versus 73,000 for Opus 5, and independent testers hit the 128,000 max_tokens ceiling mid-reasoning at max. Re-run your effort sweep, set effort explicitly, and leave room in max_tokens for thinking.

How do I handle Claude Opus 5.5 safeguard refusals?

Opus 5.5 runs cybersecurity and biology classifiers and can decline requests that try to extract its internal reasoning under a reasoning_extraction category. A declined request returns HTTP 200 with stop_reason refusal and a stop_details object naming the policy area. Configure fallback: the beta server-side option fallbacks: 'default' retries on the model Anthropic recommends for that category (Opus 4.8 for cyber, Opus 5 for biology), or use the SDK middleware or your own retry. Vetted organizations can apply to the Life Sciences Verification Program, and the Cyber Verification Program is expanding to Opus 5.5.

Quick Answer

How to Migrate to Claude Opus 5.5 from Opus 5 (2026 Guide)

Published: September 23, 2026

The short answer

Migrating to Claude Opus 5.5 is a one-line model-ID change for most Opus 5 code, plus four fixes for patterns the new model rejects and one for a silent change in how it streams progress. Released September 22, 2026 at $4/$20 per million tokens (20% under Opus 5) with $0.20 cache reads (60% under), it is worth the hour of work. This guide walks through the changes in the order they will bite, then a rollout plan. It applies to the Claude API, Amazon Bedrock, Google Cloud and Microsoft Foundry.

Step 0: Know what changed

Change	Effect on Opus 5 code	Fix
Thinking always on	`thinking: disabled` or `budget_tokens` → 400	Remove; use `output_config.effort`
No forced tool use	`tool_choice: any` / `tool` → 400	`auto` + `strict: true`, or structured outputs
Thinking blocks bound to model + conversation	Replaying blocks after editing history → 400 (new accounts)	Append-only conversations; mid-conversation system messages
Legacy computer-use tool rejected (API, GCP)	`computer_20251124` → 400	`computer_toolset_20260801`
Inter-tool text in thinking blocks	Progress UI goes silent (no error)	Set `thinking.display`; select blocks by `type`
Default effort medium (was high)	Cheaper, shallower unless set	Set `effort` explicitly
More thinking per effort level	Higher output tokens at xhigh/max	Re-sweep effort; raise `max_tokens`
New safeguard categories	`stop_reason: refusal` on cyber/bio/reasoning extraction	Configure fallbacks

Step 1: Switch the model ID on one route

Use claude-opus-5-5 on the Claude API, Google Cloud, Microsoft Foundry and Claude Platform on AWS; anthropic.claude-opus-5-5 on Amazon Bedrock. Pick a non-critical, well-logged route first. Done when: requests return 200 and you can see model: claude-opus-5-5 in responses.

Step 2: Delete thinking overrides, set effort

Search your codebase for "type": "disabled" and budget_tokens. Both now return:

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

Omit thinking entirely or send {"type": "adaptive"}. Where you previously disabled thinking for cheap calls, set effort: "low". Where you relied on Opus 5’s default, set effort: "high" explicitly, because the new default is medium. Done when: no request carries disabled or budget_tokens, and every request sets effort.

Step 3: Replace forced tool use

tool_choice: {"type": "any"} and {"type": "tool", "name": "..."} return:

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

Options, in order of preference:

Keep tool_choice: {"type": "auto"} and set strict: true on the tool so the schema is enforced when the model does call it.
Move the schema to structured outputs if you only wanted valid JSON.
State in the prompt when the tool applies (“Always call lookup_order before answering order questions”).

The same validation applies to the token-counting endpoint. Done when: a grep for "type": "any" and "type": "tool" under tool_choice returns nothing.

Step 4: Make conversations append-only

Every Opus 5.5 thinking block records the model that produced it and is checked against everything before it. Two consequences:

Cross-model reads. Opus 5.5 reads blocks from Opus 5 and earlier Opus/Sonnet/Haiku models, not from Fable or Mythos. On the Claude API, Fable 5.1 and Mythos 5.1 read Opus 5.5’s blocks; no other model does. Unreadable blocks are dropped silently and not billed, so an Opus 5 → Opus 5.5 handoff keeps its reasoning while Opus 5.5 → Sonnet 5 loses it. Add the thinking-binding-controls-2026-08-01 beta header to get drops reported in input_transformations.
Prefix mismatch. For accounts created on or after August 31, 2026 00:00 UTC, replaying a block after the system prompt, tools or an earlier message changed returns 400. Either keep history immutable and use mid-conversation system messages for new instructions, or set thinking.block_binding.prefix_mismatch_behavior: "drop_block" with the beta header to drop rather than fail. Older accounts can opt in with the same field.

Done when: your agent loop never mutates prior turns, tools or system prompt in place.

Step 5: Move computer use to the toolset

On the Claude API and Google Cloud, computer_20251124 returns 'claude-opus-5-5' does not support tool types: computer_20251124. Drop the computer-use-2025-11-24 beta header, replace the tool entry with {"type": "computer_toolset_20260801"}, and update the loop for member tool_use blocks, batch actions and toolset_name on results. Bedrock still accepts the old tool; the browser-use tool needs no change. Done when: a computer-use smoke test completes on the toolset.

Step 6: Fix silent progress streams

Notes the model writes between tool calls now arrive as progress-update thinking blocks. At the default display: "omitted", their text is empty, so streaming UIs go quiet. Set thinking.display to a value that returns the text, select content blocks by type (a response may start with several thinking blocks), and pass thinking blocks back unmodified. Done when: users see progress text between tool calls again.

Step 7: Re-sweep effort and max_tokens

Opus 5.5 thinks more per turn than Opus 5 at the same effort, most of all at xhigh and max. Artificial Analysis measured ~119K output tokens per Intelligence Index task at max versus ~73K for Opus 5; Simon Willison twice hit the 128K output cap mid-reasoning at max, at $2.56 per failed attempt. Run your evaluation set at low, medium, high and xhigh, record quality and cost per task, and pick the lowest level that clears your bar. Deloitte reported low effort catching 72% of known bugs in code review versus Opus 5’s 56% at high. Leave headroom in max_tokens. Done when: you have a per-route effort table with measured cost.

Step 8: Configure refusals and fallback

Opus 5.5 ships with Fable-class classifiers. Declines come back as HTTP 200 with stop_reason: "refusal" and a stop_details object naming the policy area (cybersecurity, biology, reasoning_extraction). Set fallbacks: "default" (beta) to retry on Anthropic’s recommended model for that category, use the SDK middleware, or write your own retry. If your product is security or life-sciences work, apply to the Cyber or Life Sciences Verification Program. Done when: a refusal in staging triggers a fallback rather than an unhandled error.

Step 9: Check caching and platform features

Prompt caching minimum is 512 tokens; cache reads are $0.20 per MTok (5% of input), 5-minute writes $5, 1-hour writes $8. Keep tool definitions and system prompts stable so prefixes stay cacheable.
Batch API is 50% off and supports 300K output with the output-300k-2026-03-24 beta header.
Fast mode (speed: "fast", fast-mode-2026-02-01 header) is Claude API only, $8/$40, up to 2.5x speed; not on Bedrock, Google Cloud or Foundry.
Per-message effort (beta), task budgets and mid-conversation system messages are all supported.

Step 10: Roll out

Shadow 5–10% of traffic to Opus 5.5 with Opus 5 still serving; compare quality, latency and cost per task for at least a few days.
Promote routes one at a time, coding agents first (largest measured gains: Terminal-Bench 4.0 52.3% → 66.4%).
Keep Opus 5 in the router as fallback for two weeks; no deprecation has been announced as of September 23, 2026.
Re-baseline budgets: expect roughly 25–40% lower cost at medium/high effort, roughly flat at max.

For the decision itself see Opus 5.5 vs Opus 5: should you upgrade?; for coming from OpenAI, see Opus 5.5 vs GPT-6 Sol.

Last verified: September 23, 2026.