Claude Code Migration Reference

What this reference tracks

This page is my working log of what changed in Claude Code and the Claude Opus model that powers it, scoped to the surfaces I ship on. Other vendor stacks (Codex, Cursor, the open-source CLI agents) are out of scope by design. I build on Anthropic's developer surface and publish here only what I have direct first-party experience running. Tracking everything would mean tracking nothing well.

The reason the page exists is that freshness is the incumbent failure mode for any vendor-AI reference. A page that hasn't been refreshed since the last model release is worse than no page, because it asserts currency on a surface that moves weekly. The fix is structural rather than editorial: this page carries role: freshness-reference with a freshness_window_days: 30 frontmatter override, and the site's spine-validator stack hard-fails the build 30 days after the last updatedDate. A stale entry cannot ship as fresh. The AI authoring trust chain framing applies to this page exactly the same way it applies to every other surface on the site: the things that have to hold every time are enforced by something that runs every time.

What follows, in reverse chronological order: the most recent Opus model release, the most recent Claude Code CLI releases, the documented behavioral changes that landed without a single dated announcement, and the upcoming model-retirement deadline that probably matters most to a manager reading this on a deadline.

Anthropic's own field guidance for the new model captures the practical shape of the migration in one sentence:

Start with the new xhigh effort level for coding and agentic use cases, and use a minimum of high effort for most intelligence-sensitive use cases. Anthropic, "What's new in Claude 4.7"

What changed in the latest Opus release?

2026-04-16: Claude Opus 4.7 GA. The largest single break on the dated log. The model ships with a new denser tokenizer that uses up to 1.35x as many tokens for the same input compared to prior Opus models, per Anthropic's release notes. Per-token pricing is unchanged, so the effective per-request cost rises proportionally; a long-running agentic loop on 4.7 is materially more expensive than the same loop on 4.6. An independent practitioner measurement by Simon Willison (2026-04-20) corroborated the upper bound on a standard system prompt and sometimes exceeded it.

Three request shapes break on 4.7 outright (HTTP 400). Adaptive thinking now replaces both of the removed shapes:

Two further changes are behavioral rather than API-breaking, but I have hit each one in practice. First, adaptive thinking is off by default on 4.7, so a request that previously ran with extended thinking under budget_tokens will now run with no thinking at all unless thinking: {type: "adaptive"} is set explicitly. Second, 4.7 spawns fewer subagents by default per the release notes (under behavior changes, not breaking changes); any orchestration that expects parallel fan-out needs to instruct it explicitly. The context window remains 1M tokens and the max output remains 128k. The full announcement of the release sits on Anthropic's news page from the same day.

What to do. I run a compatibility scan against the configuration surfaces a 4.6-era project depends on before flipping the model ID. My opus-compatibility-scanner case study describes the five configuration layers that the migration guide does not audit, the 70-pattern catalogue, and the 3 Critical findings the scanner returned against my own most-curated project. Audit max_tokens headroom for the new tokenizer's higher token counts. If a request still sets non-default sampling parameters or fixed budget_tokens, remove them before pointing the call at claude-opus-4-7.

Recent Claude Code CLI releases

2026-05-23: Claude Code v2.1.150. The current latest on the anthropics/claude-code GitHub releases page, published this morning UTC. The v2.1.143 through v2.1.150 cohort over the past eight days is what I currently run on. No breaking change observed against the prior cohort in this band; the entries are patch-level updates that fold into the running Claude Code web and CLI surface.

2026-05-15: Claude Code v2.1.143. The mid-month anchor of the current cohort. Useful as the version floor when a downstream skill needs to verify its host CLI carries the recent behavioral patches; teams pinning to a specific minor revision land here.

2026-05-02: Claude Code subagent ToolSearch bootstrap obsoleted. Native subagents declared with a tools: frontmatter line receive their declared tools on the first turn; the older ToolSearch(query: "select:…") bootstrap preamble used to load deferred tool schemas before the subagent could call them is no longer required, observed obsolete as of Claude Code 2.1.126 in my internal probe on that date (Anthropic has not published a dated announcement for this specific change, so the version is the floor, not a confirmed removal version). What to do: strip any residual ToolSearch-bootstrap prose from agent files on touch; the shared web-research protocol holds the current fallback handling for it.

Documented behavioral changes (verified 2026-05-23)

These landed in Anthropic's continuously-updated docs without a single dated announcement. Each is current as of the most recent probe and carries a per-entry "as of" date so the next refresh cycle can spot drift.

MCP connector traffic now routes through Anthropic's servers (as of 2026-05-23). Per the current Claude Code on the web docs, enabled connectors work without adding their hosts to the session's allowed-domain list. The earlier behavior (only "type": "sdk" MCP servers bypassed the egress proxy; everything else needed an allowlist entry) is superseded; any enabled connector is reachable through the Anthropic-bound channel. The security implication is to minimize the connectors enabled per session or routine, since each is a tool surface Claude can reach. The data-residency implication is worth flagging for teams with strict egress requirements: traffic to a connector that previously left through a directly-allowlisted host now traverses Anthropic infrastructure.

Web search is activated by tool type, not by a beta header (as of 2026-05-23). Per the current web-search tool docs, two tool versions coexist: web_search_20260209 (latest; supports dynamic filtering when paired with the code-execution tool) and web_search_20250305 (previous; no dynamic filtering). Activation is by the tool's type field; a separate beta header is not the activation mechanism. Earlier internal references to a code-execution-web-tools-2026-02-09 header as the activation gate are superseded.

1M context is no longer an Opus-exclusive lever (as of 2026-05-23). Per the current models overview, Sonnet 4.6 also carries a 1M-token context window, at $3 input / $15 output per million tokens versus Opus 4.7 at $5 input / $25 output. A corpus-ingestion subagent that does not need Opus-tier reasoning can run on Sonnet 4.6 at roughly 60 percent of Opus input cost with the same context budget. Opus 4.7's 1M token window holds roughly 555k English words against Sonnet 4.6's roughly 750k words at the same nominal 1M, because of the new denser tokenizer.

Upcoming: model retirement on 2026-06-15

2026-06-15: Claude Sonnet 4 and Claude Opus 4 retire. Per the models overview lifecycle table, the model IDs claude-sonnet-4-20250514 and claude-opus-4-20250514 are deprecated and reach end-of-life on the date above. Migration targets: Sonnet 4.6 (claude-sonnet-4-6) or Opus 4.7 (claude-opus-4-7).

What happens after the cutoff. Per Anthropic's deprecation policy, a deprecated model ID returns an error after its retirement date; call sites pinned to a retired ID start failing rather than degrading gracefully. There is no automatic fallback to a successor model; the responsibility for routing live traffic onto a supported ID sits with the caller. The Claude Code IDE plugins, the Claude API SDK call sites, any background job that still hard-codes the deprecated IDs, and any internal eval harness pinned to those IDs all break at the same moment. What to do: inventory every code path that holds a literal claude-sonnet-4-20250514 or claude-opus-4-20250514 string and swap to the successor ID, with the compatibility considerations in the Opus 4.7 GA entry above for any 4.6-or-earlier projects making the jump to 4.7. Run the swap and a validation pass at least a week before the deadline so an unexpected break has runway to recover.

If you're migrating right now

Three short pointers. The full treatment is in the linked artifacts.

• Run a compatibility scan first. My opus-compatibility-scanner case study covers what a 70-pattern audit across the five configuration layers (root and nested instructions files, agent definitions, hook scripts, skill bodies, SDK call sites) catches that the model-card migration guide does not.
• Audit max_tokens headroom and re-run count_tokens before committing to cost projections. The 1.35x tokenizer inflation compounds on long agentic loops; a v1.0-era cost estimate is understated by construction.
• Read the Anthropic source for whatever you are migrating. Every dated entry above links the Anthropic doc that records the change. That doc, not this page, is the moving authority.

How this reference stays current

The page is a freshness-reference role under the site's spine, gated by a 30-day window on updatedDate. The build fails closed when the window expires, so a stale entry cannot ship as fresh. Each Tier 1-2 source listed in the sibling sources file carries a publication date in a Published column, so a reader (or a retrieval LLM) can judge per-source freshness without re-fetching the page's history.

The gate's failure mode worth naming: it catches updatedDate staleness, not content drift inside the window. An Anthropic doc whose URL stays the same but whose body silently changes mid-window is invisible to the gate. The mitigation lives outside the gate, in the refresh cadence: I re-pull every Tier 1 vendor source on each refresh pass and reconcile any delta into the body, not only on entries whose source URL changed.