Your Model Upgrade Is a Breaking Change: Contract-Testing the Model Layer After Claude Opus 5.5

LLM API breaking changes migration: the model layer stopped being drop-in

The dangerous upgrade failure is not always a 400: Opus 5.5 can return an empty thinking text block while a harness still reports success. The loud version is easier to spot—thinking.type.disabled—but both expose the same flaw: treating a model change as a drop-in swap rather than a distributed API migration.

The thesis is direct: every model upgrade should be managed as an API migration, with compatibility tests across request validation, response shape, conversation history, and serving platform. Opus 5.5 and GPT-6 Sol and Luna landed on 2026-09-22. The price story made headlines; the contract story broke harnesses built on assumptions of behavioral continuity. Anthropic documents the Opus changes in its platform documentation, while the OpenAI launch post provides the same-day comparison.

E-E-A-T: what this post is built on and what we did not verify

This analysis is derived from Anthropic’s platform documentation and model pages, fetched 2026-09-27, and the vendors’ launch posts — we did not run the models or call the APIs. This is a documentation-based account of compatibility risks, not hands-on verification. Vendor-reported numbers are vendor-run; no benchmark result here is presented as independently reproduced.

The load-bearing behavior comes from Anthropic’s Opus 5.5 change log, model overview, and model versioning documentation. This distinction matters operationally: documentation can establish what a client should probe, but it cannot establish how a particular agent harness handles those responses. The contract tests below are recommendations, not a report of executed tests.

Loud failures: the four changes that return 400

Four documented changes can reject requests rather than degrade gracefully: disabled or manually budgeted thinking, forced tool choice, incompatible thinking-block prefixes, and a platform-specific computer-use tool mismatch. Treat each as a negative contract test: verify the expected failure and verify that your production path does not depend on the rejected request shape.

Thinking controls. Opus 5 accepted thinking: {"type": "disabled"} at effort high or below. Opus 5.5 always uses adaptive thinking, so {"type": "disabled"} returns 400 with the message containing thinking.type.disabled. A manual budget such as {"type": "enabled", "budget_tokens": N} also returns 400. Control depth with output_config.effort; the documented default is medium.

Forced tool choice. Both tool_choice: {"type": "any"} and tool_choice: {"type": "tool", "name": "..."} return 400 with tool_choice: type "tool" and "any" are not supported. The same validation applies to token counting, so a counting-only CI path can fail before a generation path does. Documented alternatives include tool_choice: auto with strict: true, moving the schema to structured outputs, or prompting the model to call a tool when applicable.

Prefix integrity. If the system prompt, tools, or an earlier message changes before an Opus 5.5 thinking block, the API may reject the request with 400. The account-dependent behavior and the option to drop affected blocks are covered below; do not treat this as a universal validation rule across every account.

Computer use. Platform behavior diverges: computer_20251124 returns 400 on the Claude API and Google Cloud but continues to work on Amazon Bedrock for the same model ID generation. On the rejecting platforms, the error identifies computer_20251124 as unsupported. The documented migration is to remove the computer-use-2025-11-24 beta header, use {"type": "computer_toolset_20260801"}, and update the agent loop for member tool_use blocks, batched actions, and toolset_name on results.

The first three breaking changes also apply to Claude Fable 5.1. A fallback to that model is therefore not automatically a compatibility escape hatch.

Silent failures: empty thinking text and dropped reasoning blocks

Silent changes are harder to catch than validation errors because the request can succeed while the application loses progress text or reasoning continuity. Opus 5.5 returns empty text in thinking blocks at the default display: "omitted" setting, and an unreadable prior thinking block can be dropped before inference without a billing error.

At the default display setting, text between tool calls can arrive in thinking blocks whose text is empty. An application that streams this text as progress updates can go quiet between tool calls while the outer request continues to succeed. If users or orchestration logic depend on that progress stream, test the display configuration and the rendered behavior rather than treating an empty block as a transport failure.

Thinking blocks are also model-bound. Opus 5.5 can read blocks from Opus 5 and earlier Opus, Sonnet, and Haiku models, but not from Fable or Mythos. On the Claude API, Fable 5.1 and Mythos 5.1 can read Opus 5.5 blocks; other models cannot. When a target cannot read a block, the API drops it before the model sees it. The request succeeds, and dropped blocks aren’t billed. With the binding-controls beta, drops are reported in a top-level input_transformations array.

For response parsing, select content blocks by type, not position. Responses can begin with one or more thinking blocks, so positional assumptions can misclassify tool calls or user-facing text. In tool-use loops, pass thinking blocks back unmodified when they are part of the conversation being continued.

Environment-dependent behavior: your account’s birthday is now a compatibility flag

Prefix-integrity enforcement makes account creation time part of the effective API contract: for accounts created on or after 2026-08-31 00:00 UTC, a changed prefix before an Opus 5.5 thinking block returns 400 by default. Older accounts can opt into the same enforcement, so a shared client may see different results across credentials.

The preserved-thinking rule is a security control, not merely a formatting detail. Anthropic describes it as preventing API users from editing Claude’s prior context to extract reasoning. That purpose does not make the behavior less operationally significant: edited system prompts, tool definitions, or earlier messages can invalidate a block already in a conversation.

To drop affected blocks instead of returning 400, send the beta header thinking-binding-controls-2026-08-01 and set thinking.block_binding.prefix_mismatch_behavior to "drop_block". On older accounts, setting either value opts the request into this behavior. A drop avoids the prefix-mismatch error but still means the target model proceeds without the affected reasoning.

Keep conversations append-only. Change instructions and tools through mid-conversation system messages rather than editing earlier content. That preserves the prefix against which prior thinking blocks were produced and gives the agent harness a stable conversation history to replay.

What pinning actually pins

A dateless model ID is a pinned snapshot, not an evergreen pointer: Anthropic says it does not update the weights or configuration behind an existing ID. Pinning therefore helps control one source of change, but it does not freeze every observable response property across platforms or over time.

For the 4.6 generation and later, a dateless ID such as claude-opus-5-5 names a fixed snapshot; an updated version ships under a new ID. Pre-4.6 aliases can instead resolve to the latest dated snapshot for their minor version. See Anthropic’s model ID and versioning guidance for the distinction.

Fixed weights do not mean fixed serving behavior. The request router, safety classifiers, and sampling logic can change, producing minor observable differences while an ID and its weights remain unchanged. Opus 5.5 was released on 2026-09-22, with retirement not sooner than 2027-09-22. Platform-specific IDs also differ: for example, the Bedrock ID is anthropic.claude-opus-5-5, while the Claude API and Google Cloud use claude-opus-5-5.

Build the migration harness

A useful migration harness tests expected rejection, successful-but-degraded responses, and platform differences as separate outcomes. Run it against the exact credentials, endpoint, model ID, and tool configuration used by each deployment; a green test on one surface does not establish compatibility on another.

Before flipping production traffic, make the contract explicit:

• Assert 400 on thinking.type.disabled.
• Assert 400 on tool_choice: {"type":"any"}.
• Assert 400 on computer_20251124 on the Claude API but 200 on Bedrock.
• Replay an Opus 5 thinking block into Opus 5.5 and verify the supported continuation path.
• Replay an Opus 5.5 thinking block into Fable 5.1 and verify the documented readability behavior.
• Strip tool text and verify empty thinking blocks at display: "omitted" do not break progress handling.
• Call the token-counting endpoint with forced tool choice and assert the documented rejection.
• Assert a dropped-block request succeeds and dropped blocks are unbilled.
• Probe prefix integrity with credentials representing the account-age behavior your deployment uses.
• Verify parsing selects blocks by type and preserves thinking blocks in tool-use loops.
• Run the computer-use probe separately on the Claude API and Bedrock, and validate the replacement tool loop.

Keep failures actionable: store the request shape, platform, and credential cohort with each result, while redacting secrets and sensitive conversation content. Then gate rollout on the contract that matters to your harness, not on a single successful text response.

FAQ

Pinned IDs reduce drift in model weights and configuration, but they do not guarantee identical observable behavior across serving infrastructure, platforms, or request shapes. A migration still needs tests for validation, response blocks, and the conversation history your agent replays.

Do pinned model IDs prevent this?

No. A dateless ID pins a snapshot, but infrastructure surrounding the model can change, and platform surfaces can behave differently. Pin the ID and contract-test the API behavior your application depends on.

Does a fallback chain preserve reasoning?

Not necessarily. Reasoning blocks are readable only by particular model families and versions; when the target cannot read one, it can be dropped while the request succeeds. Treat fallback as a change in conversation semantics, and test the exact source-to-target pair.

What do I do today if I’m on Opus 5?

Remove assumptions that disabled thinking, manual budgets, or forced tool selection will transfer unchanged. Add the probes above, keep conversations append-only, and validate tool and reasoning behavior on the endpoint and account configuration you will deploy.

Operational takeaway: gate every model flip on contract tests for errors, response shape, conversation continuity, and platform-specific behavior.

📖 Related Reads

• NoCode Insider — AI workflow automation with no-code tools, agents, and APIs
• NiteAgent — AI agent development, frameworks, and production patterns
• Hermes Tutorials — Hermes Agent setup, configuration, and advanced workflows

Cross-links automatically generated from CodeIntel Log.