Migrating: Opus 4.8 to Opus 5.5

Skipping Opus 5, and what that skip means

The migration guide sends code on Opus 4.8 straight to Opus 5.5, applying Opus 5's changes and then Opus 5.5's on top. Doing both at once is sensible — the second step replaces parts of the first — but it means two generations of change land together, and the biggest one is not in the request shape.

Thinking goes from opt-in to always-on

On Opus 4.8, omitting the thinking field runs without thinking. On Opus 5.5 thinking always runs and cannot be disabled, at any effort. So the first thing to re-size is max_tokens: thinking draws from the same output budget as the answer, and a limit tuned for a thinking-off route will truncate replies after the reasoning. Anthropic suggests a large ceiling for long agentic turns. Any prompt that asked the model to write its reasoning into the answer, standing in for thinking, should go — on Opus 5.5 that pattern invites a reasoning-extraction decline.

Effort, cost and caching all move

Opus 4.8 defaults effort to high; Opus 5.5 defaults to medium. The per-token price falls, cache reads get much cheaper, and the minimum cacheable prefix drops, so prompts that never cached on Opus 4.8 may now cache with no code change. The tokenizer does not change between the two.

What becomes an error

Forced tool choice, a disabled thinking configuration, and — on the Claude API and Google Cloud — the older computer-use tool version all return a 400 on Opus 5.5. Thinking blocks become bound to their conversation, so harnesses that trim or rewrite earlier turns need the append-only treatment.

Worth knowing in reverse

Opus 4.8 is one of the fallback targets when Opus 5.5 declines a request. A fallback runs without Opus 5.5's thinking blocks, and on Opus 4.8 without thinking at all unless the request asks for it.

Related

See migrating: Opus 5 to Opus 5.5 and claude-opus-4-8.