Claude Opus 4.6 to 4.7 Migration: Breaking Changes

The Claude Opus 4.6 to 4.7 migration looks like a routine version bump on the release notes and behaves like a four-axis breaking change in production. Prompt-cache keys change shape, the tool-use schema gains structured outputs plus parallel calls, 1M context arrives with a new economic envelope, and a built-in compaction API quietly retires every hand-rolled conversation summarizer your team has ever shipped.

None of those are listed as breaking changes in the headline release notes. All four are breaking in the sense that matters — they change observable behavior in production code, they change the cost curve, and they change the patterns your agents were written against. Treat 4.7 as a minor version at your peril; treat it as a migration and the work gets predictable.

This guide is the playbook we run for clients moving from Opus 4.6 to 4.7 across agent stacks, RAG pipelines, and production chat. Seven sections cover what shipped, what broke under the hood, how to decide which workloads jump to 1M, when to adopt the compaction API, and the four pitfalls every migration we have audited hits in the first 72 hours. The brief is short: phased beats big-bang, shadow before cut over, and the playbook matters more than the version bump.

Opus 4.7 is the first Claude release in the 4.x line that is simultaneously a capability bump, an infrastructure refactor, and a primitives expansion. The capability story is the one the release notes lead with — improved coding, longer planning horizons, better tool-use reliability. The other three stories are the ones that decide whether your migration is clean.

Frame the four axes deliberately, because each one has a different blast radius and a different rollout strategy. Capability is backward-compatible by definition — your prompts still work, they just work better. Cache is silent and infrastructural — wrong, and you only notice on the invoice. Tools is interface-level — the schema looks similar but agentic code written for 4.6 will misbehave. Compaction is purely additive — adopting it deletes code, but ignoring it leaves you running fragile hand-rolled summarizers in production.

One framing note worth getting right early: 4.7 is not a strict superset of 4.6 in every dimension. On a small number of narrow evals — particularly highly-rehearsed prompt patterns that were tuned to 4.6 quirks — 4.6 still edges out. Run your own evals before cut over. The aggregate trend is clearly up; the per-prompt picture is occasionally messier.

Prompt caching is the single highest-leverage cost lever Anthropic ships, and the 4.7 release changes how it works under the hood in three ways that matter. First, cache-key derivation includes new model-version components, so 4.6 cache entries are effectively invalidated for 4.7 traffic. Second, TTL semantics are extended — the default 5-minute window is joined by a longer-lived tier for workloads with stable system prompts. Third, the cache-miss patterns themselves change shape: a miss in 4.7 is more often a partial miss with a shorter re-encode, rather than a full re-encode.

The practical implications stack. If your workload was caching a stable 50K-token system prompt on 4.6 and seeing 90%+ hit rates, day one on 4.7 is a 0% hit rate until traffic warms the new cache. For high-QPS workloads, that's a meaningful day-one spend spike — measurable, transient, but visible on the invoice. The fix is to pre-warm via shadow traffic, or to time the cut over for a low-traffic window so the warm-up cost is absorbed at off-peak rates.

One subtle behavior to test for: cache-key derivation in 4.7 is more sensitive to ordering and whitespace in the system prompt than the 4.6 implementation was. If your prompt-assembly code occasionally produces semantically-identical-but-byte-different outputs — say, a JSON serializer that doesn't pin key order — you'll see lower hit rates than expected. Pin the byte representation of the cached portion of your prompt deterministically.

For workloads where prompt caching is doing real economic work, the migration is a good moment to also audit which portions of your prompt are actually cache-eligible. Anthropic's cache granularity has tightened over time; some patterns that worked on 4.5 and earlier are sub-optimal on 4.7. If you want a structured audit of your stack's prompt-cache hit rate plus recommendations on partitioning, our AI transformation engagements include exactly that as part of the migration scope.

The tool-use surface in 4.7 changes in two ways that matter for anyone running agents. First, structured outputs gain strict-schema adherence — when you provide a JSON schema, 4.7 produces output that conforms by construction, not by best-effort. Second, and more consequentially, a single model turn can now emit multiple tool_use blocks. The 4.6 pattern of one tool call per turn becomes one or more tool calls per turn, with the model deciding when parallelism is appropriate.

Parallel tool calls are a strict capability improvement — but only if your orchestration loop knows how to handle them. The patterns we have seen break in the first week of cut over are consistent enough to be worth listing.

The three orchestration anti-patterns

• Drop-the-second-call. The loop reads the first tool_use block, dispatches it, and ignores subsequent blocks in the same response. Symptom: the agent silently drops half its work. The model thinks it called five tools; you returned results for one.
• Serialize-what-should-be-parallel. The loop detects multiple tool_use blocks and dispatches them sequentially. Symptom: latency that should be parallel-bounded becomes additive. The agent works, just slowly — and the latency-improvement story that justified the migration evaporates.
• Lose-tool-ordering. The loop dispatches parallel calls correctly but returns the tool_result blocks in the wrong order. The model handled them but is now reasoning over scrambled context. Symptom: subtle quality drops that don't show up on aggregate evals.

Structured outputs are the gentler half of the schema story. Strict-schema adherence means you can trust the JSON shape coming back — no more defensive parsers, no more retry-on-malformed logic. For teams that built elaborate validation layers around 4.6 outputs, the migration is also a deletion opportunity. Keep the schema validation as a safety net, delete the retry-on-parse fallback loops.

For the deeper context on how to write tool definitions that play well with the new parallel-call behavior, our piece on building Claude Code custom subagents covers the same tool-allowlist discipline applied to the subagent surface — the lessons port directly to plain API tool definitions.

Opus 4.7 ships with a 1M-token context window as a configurable tier. The capability is real, the pricing is non-trivial, and the right answer is almost always per-workload selective adoption rather than turning it on everywhere. The economics flip at different points for different workload classes — the chart below sketches the rough break-evens.

The framing question is simple: at what input-token count does the marginal cost of the longer context window stop being amortized by the marginal capability lift? For most chat traffic, the answer is "never" — chat messages don't approach 1M tokens, so you pay the long-context overhead with no benefit. For full-codebase analysis, RAG pipelines over large corpora, and multi-document reasoning, the answer flips the other way and 1M becomes economically dominant.

Read the chart two ways. The bars on the right are the workloads where staying on the 200K tier is fine and 1M is overhead. The bars on the left are workloads where 1M unlocks behavior that was either impossible (cross-file refactor reasoning) or required elaborate chunking workarounds (long-document RAG). The middle band — mid-context agents — is the one that takes per-workload measurement.

One pattern that has worked well in client migrations: route within a single deployment based on input length. A simple length-based router that sends short requests to the 200K tier and long requests to 1M captures the economic upside without forcing a single-tier decision on every workload. The downside is the routing layer becomes part of your migration scope — another reason phased rollout matters.

Every production agent stack ships with a hand-rolled conversation summarizer. The pattern is universal because the problem is universal — long-running agents accumulate context that eventually exceeds budget, and the only way to keep running is to summarize older turns into a compressed form. The code that does this in every stack we have audited is the most fragile, least-tested, most-likely-to-silently-lose-information code in the agent. Opus 4.7's compaction API replaces all of it.

The primitive is the right one. Pass in the conversation, get back a structured summary that preserves the information the model itself judges relevant for continued reasoning. The model doing the compaction is the same model that produced the conversation, so it knows which threads it was tracking, which entities matter, and what state it had built up internally. The hand-rolled equivalent — using a separate cheap model to summarize, or asking the same model to re-summarize from scratch on every call — never had that context.

Three adoption patterns are worth knowing. The first is the drop-in replacement — wherever you currently call your hand-rolled summarizer, call the compaction API instead. This is the lowest-risk path and produces immediate quality lift on most workloads. The second is the threshold-triggered pattern — compact only when the conversation approaches a configurable budget, rather than on every turn. This minimizes compaction cost while preserving budget headroom. The third is the opportunistic pattern — compact during natural turn boundaries (user idle, system events) so compaction latency never appears on the critical path.

One adoption note: the compaction API output is a structured summary, not a raw text blob. Code that previously stitched a summary string into the prompt will need to handle the structured shape. The shape is stable and well-documented in the Anthropic SDK release notes, but it's not a one-line substitution — budget a few hours per agent for the integration.

Big-bang migrations look efficient on a sprint plan and burn the most engineering time in the rollback. Phased rollout looks slower on paper and ends up faster end-to-end because the surprises surface during the shadow phase rather than in production. The four phases below are the rhythm we run across client migrations.

Each phase has a clear entry and exit criterion, a defined duration, and a specific class of work that happens during it. Skipping a phase doesn't make the migration faster — it just shifts which phase eats the surprises.

Two phase-level rules earn their keep. First, the shadow phase exits only when 72 hours of duplicated traffic have produced no regressions — anything shorter and you haven't seen the workload's full cycle (the report that runs daily, the batch job that runs Sunday night, the campaign that fires Monday morning). Second, the cut-over phase has explicit rollback criteria documented before the first slice goes — not invented under pressure when an alert fires at 3am.

For broader context on how Anthropic SDK changes interact with the migration — and the specific SDK upgrade path that needs to happen in parallel — our companion guide on the Anthropic SDK v2 to v3 migration walks through the TypeScript-specific deltas. For most teams, the SDK upgrade lands at the same time as the model migration and the two are best planned together.

Across the migrations we have audited, four pitfalls show up often enough to be worth naming explicitly. None of them are exotic — all of them are easy to miss if the migration is run as a version bump rather than a four-axis change.

One meta-pitfall worth naming: assuming the migration is done when traffic is on 4.7. Phase 4 — retirement — is where the migration actually pays back. Code paths that linger past the cut-over date accumulate drift, get accidentally re-exercised by unrelated changes, and confuse the next engineer who joins the team. Schedule the retirement work explicitly. The migration ends when the 4.6 code is gone, not when the 4.7 code is live.