/claude-api

Model Migration Guide

If you arrived via /claude-api migrate: this is the right file. Execute the steps below in order - do not summarize them back to the user. Start with Step 0 (confirm scope) before touching any file.

How to move existing code to newer Claude models. Covers breaking changes, deprecated parameters, and drop-in replacements for retired models.

For the latest, authoritative version (with code samples in every supported language), WebFetch the Migration Guide URL from shared/live-sources.md. Use this file for the consolidated, skill-resident reference; fall back to the live docs whenever a model launch or breaking change may have shifted the picture.

This file is large. Use the section names below to jump (or Grep this file for the heading text). Read Step 0 and Step 1 first - they apply to every migration. Then read only the per-target section for the model you are migrating to.

TL;DR: Change the model ID string. If you were using budget_tokens, switch to thinking: {type: "adaptive"}. If you were using assistant prefills, they 400 on both Opus 4.6 and Sonnet 4.6 - switch to one of the prefill replacements (most often output_config.format; see the table in Breaking Changes by Source Model). If you're moving from Sonnet 4.5 to Sonnet 4.6, set effort explicitly - 4.6 defaults to high. Remove the effort-2025-11-24 and fine-grained-tool-streaming-2025-05-14 beta headers (GA on 4.6); remove interleaved-thinking-2025-05-14 once you're on adaptive thinking (keep it only while using the transitional budget_tokens escape hatch). Then drop back from client.beta.messages.create to client.messages.create. Dial back any aggressive "CRITICAL: YOU MUST" tool instructions; 4.6 follows the system prompt much more closely.

Step 0: Confirm the migration scope

Before any Write, Edit, or MultiEdit call, confirm the scope. If the user's request does not explicitly name a single file, a specific directory, or an explicit file list, ask first - do not start editing. This is non-negotiable: even imperative-sounding requests like "migrate my codebase", "move my project to X", "upgrade to Sonnet 4.6", or bare "migrate to Opus 4.7" leave the scope ambiguous and require a clarifying question. Phrases like "my project", "my code", "my codebase", "the whole thing", "everywhere", or "across the repo" are ambiguous, not directive - they tell you what to do but not where. Ask before doing.

Offer the common scopes explicitly and wait for the answer before touching any file:

1. The entire working directory
2. A specific subdirectory (e.g. src/, app/, services/billing/)
3. A specific file or a list of files

Surface this as a single clarifying question so the user can answer in one turn. Proceed without asking only when the scope is already unambiguous - the user named an exact file ("migrate extract.py to Sonnet 4.6"), pointed at a specific directory ("migrate everything under services/billing/ to Opus 4.6"), listed specific files ("update a.py and b.py"), or already answered the scope question in an earlier turn. If you can answer the question "which files is this change going to touch?" with a precise list from the prompt alone, proceed. If not, ask.

Worked example. If the user says "Move my project to Opus 4.6. I want adaptive thinking everywhere it makes sense." you do not know whether "my project" means the whole working directory, just src/, just the production code, or something else - the everywhere makes the intent clear (update every call site within scope) but the scope itself is still not defined. Do not start editing. Respond with:

Before I start editing, can you confirm the scope? I can migrate:

1. Every .py file in the working directory
2. Just the files under src/ (production code)
3. A specific subdirectory or list of files you name

Which one?

Then wait for the answer. The same applies to "Migrate to Opus 4.7" and bare "Help me upgrade to Sonnet 4.6" - ask before editing.

Sizing the scope question (large repos). Before asking, get a per-directory count so the user can pick concretely:

rg -l "<old-model-id>" --type-not md | cut -d/ -f1 | sort | uniq -c | sort -rn

Present the breakdown in your scope question (e.g. "Found 217 references across 3 directories: api/ (130), api-go/ (62), routing/ (25). Which to migrate?"). Also confirm git status is clean before surveying - unexpected modifications mean a concurrent process; stop and investigate before proceeding.

Step 1: Classify each file

Not every file that contains the old model ID is a caller of the API. Before editing, classify each file into one of these buckets - the right action differs:

Bucket 3 sub-cases - before swapping a string reference, check:

• Capability gate (e.g. if 'opus-4-6' in model_id: enables a feature) -> add the new ID alongside, don't replace. The old model is still served and still has the capability, so replacing would silently disable the feature for any old-model traffic that still flows through. If you know no old-model traffic will hit this gate (single-caller codebase fully migrating), replacing is fine; if unsure, add alongside.
• Registry-assert test (e.g. assert "claude-X" in supported_models, test_X_has_N_clusters) -> add an assertion for the new model alongside; keep the old one. The old model is still served, so its assertion stays valid - but the registry should also include the new model, so assert that too. Heuristic: if the test references multiple model versions in a list, it's a registry test; if one model in a struct compared only to itself, it's a generic fixture.
• Frozen / generated snapshot -> regenerate, don't hand-edit.
• Coupled to a definer (e.g. an integration test that passes model authorization via a shared conftest seed list, or asserts on a billing-tier / rate-limit-group enum or a generated SKU/pricing catalog) -> verify the definer has a new-model entry first. If not, add a seed entry (reusing the nearest existing tier as a placeholder); if you can't confidently do that, ask the user how to populate the definer. Do not skip the test. Swapping without populating the definer will make the test fail at runtime.

When migrating tests specifically: breaking parameters (temperature, top_p, budget_tokens) are usually absent - test fixtures rarely set sampling params on placeholder models. The breaking-change scan is still required, but expect mostly clean results.

Find intentionally-flagged sync points first. Many codebases tag spots that must change at every model launch with comment markers like MODEL LAUNCH, KEEP IN SYNC, @model-update, or similar. Grep for whatever convention the repo uses before the broad model-ID grep - those markers point at the load-bearing changes.

Per-SDK Syntax Reference

Code examples in this guide are Python. The same fields exist in every official Anthropic SDK - Stainless generates all 7 from the same OpenAPI spec, so JSON field names map 1:1 with only case-convention differences. Use the rows below to translate the Python examples to the SDK you are migrating.

Verify type and method names against the SDK source before writing them into customer code. WebFetch the relevant repository from the SDK source-code table in shared/live-sources.md (one row per SDK) and confirm the exact symbol - particularly for typed SDKs (Go, Java, C#) where union/builder names can differ from the JSON shape. Do not guess type names that aren't in the table below or in <lang>/claude-api/README.md.

thinking - budget_tokens -> adaptive

Sampling parameters - temperature / top_p / top_k

(Remove the field entirely on Opus 4.7; on Claude 4.x keep at most one of temperature or top_p.)

Prefill replacement - structured outputs via output_config.format

thinking.display - opt back into summarized reasoning (Opus 4.7)

For any field not in these tables, the JSON key in the Python example translates directly: snake_case for Python/TypeScript/Ruby, camelCase named args for PHP, PascalCase struct fields for Go/C#, camelCase builder methods for Java.

Explain every change you make

Migration edits often look arbitrary to a user who hasn't read the release notes - a removed temperature, a deleted prefill, a rewritten system-prompt sentence. For each edit, tell the user what you changed and why, tied to the specific API or behavioral change that motivates it. Do this in your summary as you work, not just at the end.

Be especially explicit about system-prompt edits. Users are rightly protective of their prompts, and prompt-tuning changes are judgment calls (not hard API requirements). For any prompt edit:

• Quote the before and after text.
• State the behavioral shift that motivates it (e.g. "Opus 4.7 calibrates response length to task complexity, so I added an explicit length instruction", or "4.6 follows instructions more literally, so 'CRITICAL: YOU MUST use the search tool' will now overtrigger - softened to 'Use the search tool when...'").
• Make clear which prompt edits are optional tuning (tone, length, subagent guidance) versus which code edits are required to avoid a 400 (sampling params, budget_tokens, prefills). Never present an optional prompt change as mandatory.

If you're applying several prompt-tuning edits at once, offer them as a short list the user can accept or decline item-by-item rather than silently rewriting their system prompt.

Before You Migrate

1. Confirm the target model ID. Use only the exact strings from shared/models.md - do not append date suffixes to aliases (claude-opus-4-6, not claude-opus-4-6-20251101). Guessing an ID will 404.
2. Check which features your code uses with this checklist:

• thinking: {type: "enabled", budget_tokens: N} -> migrate to adaptive thinking on Opus 4.6 / Sonnet 4.6 (still functional but deprecated)
• Assistant-turn prefills (messages ending with role: "assistant") -> must change on Opus 4.6 / Sonnet 4.6 (returns 400)
• output_format parameter on messages.create() -> must change on all models (deprecated API-wide)
• max_tokens > ~16000 -> must stream on any model (above ~16K risks SDK HTTP timeouts). When streaming, every current model reaches 128K except Haiku 4.5, which caps at 64K
• Beta headers effort-2025-11-24, fine-grained-tool-streaming-2025-05-14, interleaved-thinking-2025-05-14 -> GA on 4.6, remove them and switch from client.beta.messages.create to client.messages.create
• Moving Sonnet 4.5 -> Sonnet 4.6 with no effort set -> 4.6 defaults to high, which may change your latency/cost profile
• System prompts with CRITICAL, MUST, If in doubt, use X language -> likely to overtrigger on 4.6 (see Prompt-Behavior Changes)
• Coming from 3.x / 4.0 / 4.1: also check sampling params (temperature + top_p), tool versions (text_editor_20250728), refusal + model_context_window_exceeded stop reasons, trailing-newline tool-param handling

3. Test on a single request first. Run one call against the new model, inspect the response, then roll out.

Destination Models (recommended targets)

Default to the latest Opus (Claude Opus 5.5) for the caller's tier unless they explicitly chose otherwise. The Sonnet target is Claude Sonnet 5.5 (claude-sonnet-5-5). The Opus migrations layer: if you're on an older Opus, apply each version's section in order up to your target (e.g. 4.5 -> 4.8 means the 4.6, 4.7, and 4.8 sections in sequence). A 4.7 -> 4.8 move has no new breaking changes - see Migrating to Opus 4.8 below.

Retired Model Replacements

These models return 404 - update immediately:

Deprecated Models (retiring soon)

Breaking Changes by Source Model

Migrating from Sonnet 4.5 to Sonnet 4.6 (effort default change)

Sonnet 4.5 had no effort parameter; Sonnet 4.6 defaults to high. If you just switch the model string and do nothing else, you may see noticeably higher latency and token usage. Set effort explicitly.

Recommended starting points:

For non-thinking chat workloads specifically:

client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    thinking={"type": "disabled"},
    output_config={"effort": "low"},
    messages=[{"role": "user", "content": "..."}],
)

When to use Opus 4.6 instead: hardest and longest-horizon problems - large code migrations, deep research, extended autonomous work. Sonnet 4.6 wins on fast turnaround and cost efficiency.

Migrating to Opus 4.6 / Sonnet 4.6 (from any older model)

1. Manual extended thinking is deprecated - use adaptive thinking.

thinking: {type: "enabled", budget_tokens: N} (manual extended thinking with a fixed token budget) is deprecated on Opus 4.6 and Sonnet 4.6. Replace it with thinking: {type: "adaptive"}, which lets Claude decide when and how much to think. Adaptive thinking also enables interleaved thinking automatically (no beta header needed).

# Old (still works on older models, deprecated on 4.6)
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 8000},
    messages=[...]
)

# New (Opus 4.6 / Sonnet 4.6)
response = client.messages.create(
    model="claude-opus-4-6",  # or "claude-sonnet-4-6"
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # optional: low | medium | high | max
    messages=[...]
)

Adaptive thinking is the long-term target, and on internal evaluations it outperforms manual extended thinking. Move when you can.

Transitional escape hatch: manual extended thinking is still functional on Opus 4.6 and Sonnet 4.6 (deprecated, will be removed in a future release). If you need a hard ceiling while migrating - for example, to bound token spend on a runaway workload before you've tuned effort - you can keep budget_tokens around alongside an explicit effort value, then remove it in a follow-up. budget_tokens must be strictly less than max_tokens:

# Transitional only - deprecated, plan to remove
client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16384,
    thinking={"type": "enabled", "budget_tokens": 8192},  # must be < max_tokens
    output_config={"effort": "medium"},
    messages=[...],
)

If the user asks for a "thinking budget" on 4.6, the preferred answer is effort - use low, medium, high, or max rather than a token count.

2. Effort parameter (Opus 4.5, Opus 4.6, Sonnet 4.6 only).

Controls thinking depth and overall token spend. Goes inside output_config, not top-level. Default is high. max is supported on Fable 5, Opus 4.6 and later, Sonnet 5.5, Sonnet 5, and Sonnet 4.6 - it errors on Sonnet 4.5 and Haiku 4.5.

output_config={"effort": "medium"}  # often the best cost / quality balance

Migrating to the 4.6 family (Opus 4.6 and Sonnet 4.6)

3. Assistant-turn prefills return 400 (Opus 4.6 and Sonnet 4.6).

Prefilled responses on the final assistant turn are no longer supported on either Opus 4.6 or Sonnet 4.6 - both return a 400. Adding assistant messages elsewhere in the conversation (e.g., for few-shot examples) still works. Pick the replacement that matches what the prefill was doing:

# Old (fails on Opus 4.6 / Sonnet 4.6) - prefill forcing JSON shape
messages=[
    {"role": "user", "content": "Extract the name."},
    {"role": "assistant", "content": "{\"name\": \""},
]

# New - structured outputs replace the prefill
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    output_config={"format": {"type": "json_schema", "schema": {...}}},
    messages=[{"role": "user", "content": "Extract the name."}],
)

4. Stream for max_tokens > ~16K (all models); only Haiku 4.5 caps lower, at 64K.

Non-streaming requests hit SDK HTTP timeouts at high max_tokens, regardless of model - stream for anything above ~16K output. The streamable ceiling is 128K for every current model except Haiku 4.5, which caps at 64K.

with client.messages.stream(model="claude-opus-4-6", max_tokens=64000, ...) as stream:
    message = stream.get_final_message()

5. Tool-call JSON escaping may differ (Opus 4.6 and Sonnet 4.6).

Both 4.6 models can produce tool call input fields with Unicode or forward-slash escaping. Always parse with json.loads() / JSON.parse() - never raw-string-match the serialized input.

All models

6. output_format -> output_config.format (API-wide).

The old top-level output_format parameter on messages.create() is deprecated. Use output_config.format instead. This is not 4.6-specific - applies to every model.

Beta Headers to Remove on 4.6

Several beta headers that were required on 4.5 are now GA on 4.6 and should be removed. Leaving them in is harmless but misleading; removing them also lets you move from client.beta.messages.create(...) back to client.messages.create(...).

Once you remove all of these and finish moving to adaptive thinking, you can switch the SDK call site from the beta namespace back to the regular one:

# Before
response = client.beta.messages.create(
    model="claude-opus-4-5",
    betas=["interleaved-thinking-2025-05-14", "effort-2025-11-24"],
    ...
)

# After
response = client.messages.create(
    model="claude-opus-4-6",
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    ...
)

Additional Changes When Coming from 3.x / 4.0 / 4.1 -> 4.6

If you're jumping from Opus 4.1, Sonnet 4, Sonnet 3.7, or an older Claude 3.x model directly to 4.6, apply everything above plus the items in this section. Users already on Opus 4.5 / Sonnet 4.5 can skip this.

1. Sampling parameters: temperature OR top_p, not both.

Passing both will error on every Claude 4+ model:

# Old (3.x only - errors on 4+)
client.messages.create(temperature=0.7, top_p=0.9, ...)

# New
client.messages.create(temperature=0.7, ...)  # or top_p, not both

2. Update tool versions.

Legacy tool versions are not supported on 4+. Both the type and the name field change - text_editor_20250728 and str_replace_based_edit_tool are a pair; updating one without the other 400s. Also remove the undo_edit command from your text-editor integration:

# Before
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]

# After - BOTH fields change
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]

3. Handle the refusal stop reason.

Claude 4+ can return stop_reason: "refusal" on the response. If your code only handles end_turn / tool_use / max_tokens, add a branch:

if response.stop_reason == "refusal":
    # Surface the refusal to the user; do not retry with the same prompt
    ...

4. Handle the model_context_window_exceeded stop reason (4.5+).

Distinct from max_tokens: it means the model hit the context window limit, not the requested output cap. Handle both:

if response.stop_reason == "model_context_window_exceeded":
    # Context window exhausted - compact or split the conversation
    ...
elif response.stop_reason == "max_tokens":
    # Requested output cap hit - retry with higher max_tokens or stream
    ...

5. Trailing newlines preserved in tool call string parameters (4.5+).

4.5 and 4.6 preserve trailing newlines that older models stripped. If your tool implementations do exact string matching against tool-call input values (e.g., if name == "foo"), verify they still match when the model sends "foo\n". Normalizing with .rstrip() on the receiving side is usually the simplest fix.

6. Haiku: rate limits reset between generations.

Haiku 4.5 has its own rate-limit pool separate from Haiku 3 / 3.5. If you're ramping traffic as you migrate, check your tier's Haiku 4.5 limits at API rate limits - a quota that comfortably served Haiku 3.5 traffic may need a tier bump for the same volume on 4.5.

Prompt-Behavior Changes (Opus 4.5 / 4.6, Sonnet 4.6)

These don't break your code, but prompts that worked on 4.5-and-earlier may over- or under-trigger on 4.6. Tune as needed. For a standing, model-general audit of dated prompt text beyond this migration - skills and tool descriptions included - read shared/prompt-audit.md (or invoke /claude-api prompt-audit).

1. Aggressive instructions cause overtriggering. Opus 4.5 and 4.6 follow the system prompt much more closely than earlier models. Prompts written to overcome the old reluctance are now too aggressive:

If the model is now overtriggering a tool or skill, the fix is almost always to dial back the language, not to add more guardrails.

2. Overthinking and excessive exploration (Opus 4.6). At higher effort settings, Opus 4.6 explores more before answering. If that burns too many thinking tokens, lower effort first (medium is often the sweet spot) before adding prose instructions to constrain reasoning.

3. Overeager subagent spawning (Opus 4.6). Opus 4.6 has a strong preference for delegating to subagents. If you see it spawning a subagent for something a direct grep or read would solve, add guidance: "Use subagents only for parallel or independent workstreams. For single-file reads or sequential operations, work directly."

4. Overengineering (Opus 4.5 / 4.6). Both models may add extra files, abstractions, or defensive error handling beyond what was asked. If you want minimal changes, prompt for it explicitly: "Only make changes directly requested. Don't add helpers, abstractions, or error handling for scenarios that can't happen."

5. LaTeX math output (Opus 4.6). Opus 4.6 defaults to LaTeX (\frac{}{}, $...$) for math and technical content. If you need plain text, instruct it explicitly: "Format all math as plain text - no LaTeX, no $, no \frac{}{}. Use / for division and ^ for exponents."

6. Skipped verbal summaries (4.6 family). The 4.6 models are more concise and may skip the summary paragraph after a tool call, jumping straight to the next action. If you rely on those summaries for visibility, add: "After completing a task that involves tool use, provide a brief summary of what you did."

7. "Think" as a trigger word (Opus 4.5 with thinking disabled). When thinking is off, Opus 4.5 is particularly sensitive to the word think and may reason more than you want. Use consider, evaluate, or reason through instead.

Model-ID Rename Quick Reference

Older aliases (claude-opus-4-7, claude-opus-4-6, claude-opus-4-5, claude-sonnet-4-6, claude-sonnet-4-5, etc.) are still active and can be pinned if you need time before upgrading - see shared/models.md for the full legacy list.

Amazon Bedrock model IDs

If the code uses the AnthropicBedrockMantle client (Python anthropic[bedrock], TypeScript @anthropic-ai/bedrock-sdk, Java BedrockMantleBackend, Go bedrock.NewMantleClient, etc.) or targets https://bedrock-mantle.{region}.api.aws/anthropic, it is running on Claude in Amazon Bedrock. All breaking changes in this guide apply unchanged there - it serves the same Messages API shape - but model IDs carry an anthropic. provider prefix:

When migrating a Bedrock file, apply the same rename-table row as first-party, then keep/add the anthropic. prefix. Do not generate a first-party claude-* ID for a Bedrock client - it will 400.

Skip for Bedrock: the code_execution_* tool-version checklist item and the Task Budgets section - neither is available on Bedrock (see shared/platform-availability.md for the per-feature table). Everything else in this guide - effort, adaptive/extended thinking, output_config.format, thinking.display, token counting - is available on Bedrock; fine-grained tool streaming (eager_input_streaming) is available on Bedrock's newer serving stack only (see the per-model note in shared/platform-availability.md).

Out of scope: the legacy Amazon Bedrock integration (InvokeModel / Converse APIs with ARN-versioned IDs like anthropic.claude-3-5-sonnet-20241022-v2:0) uses a different request shape and model-ID format. This guide does not cover it; WebFetch the Bedrock page in shared/live-sources.md if the user is migrating between the two Bedrock integrations.

Claude Platform on AWS

If the code uses AnthropicAWS / AnthropicAws / anthropicaws.NewClient / AnthropicAwsClient (or targets https://aws-external-anthropic.{region}.api.aws), it is running on Claude Platform on AWS - Anthropic-operated, same-day API parity. Model IDs are bare first-party strings; apply the rename table above verbatim and every breaking-change section in this guide unchanged. There is nothing to skip. Do not add an anthropic. prefix (that's Amazon Bedrock, a separate offering). See shared/claude-platform-on-aws.md for client/auth details.

Migration Checklist

Every item is tagged: [BLOCKS] items cause a 400 error, infinite loop, silent timeout, or wrong tool selection if missed - apply these as code edits, not as suggestions. [TUNE] items are quality/cost adjustments.

For each file that calls messages.create() / equivalent SDK method:

• [BLOCKS] Update the model= string to the new alias
• [BLOCKS] Replace budget_tokens with thinking={"type": "adaptive"} (deprecated on Opus 4.6 / Sonnet 4.6)
• [BLOCKS] Move format from top-level output_format into output_config.format
• [BLOCKS] Remove any assistant-turn prefills if targeting Opus 4.6 or Sonnet 4.6 (see the prefill replacement table)
• [BLOCKS] Switch to streaming if max_tokens > ~16000 (otherwise SDK HTTP timeout)
• [TUNE] Verify tool-input handling parses JSON rather than raw-string-matching the serialized input (4.6 may escape Unicode / forward slashes differently; most SDKs already expose block.input as a parsed object)
• [TUNE] Set output_config={"effort": "..."} explicitly - especially when moving Sonnet 4.5 -> Sonnet 4.6 (4.6 defaults to high)
• [TUNE] Remove GA beta headers: effort-2025-11-24, fine-grained-tool-streaming-2025-05-14, token-efficient-tools-2025-02-19, output-128k-2025-02-19; remove interleaved-thinking-2025-05-14 once on adaptive thinking
• [TUNE] Switch client.beta.messages.create(...) -> client.messages.create(...) once all betas are removed
• [TUNE] Review system prompt for aggressive tool language (CRITICAL:, MUST, If in doubt) and dial it back

Extra items when coming from 3.x / 4.0 / 4.1:

• [BLOCKS] Remove either temperature or top_p (passing both 400s on Claude 4+)
• [BLOCKS] Update text-editor tool type to text_editor_20250728
• [BLOCKS] Update text-editor tool name to str_replace_based_edit_tool - changing only the type and keeping name: "str_replace_editor" returns a 400
• [BLOCKS] Update code-execution tool to code_execution_20260521
• [BLOCKS] Delete any undo_edit command call sites
• [TUNE] Add handling for stop_reason == "refusal"
• [TUNE] Add handling for stop_reason == "model_context_window_exceeded" (4.5+)
• [TUNE] Verify tool-param string matching tolerates trailing newlines (preserved on 4.5+)
• [TUNE] If moving to Haiku 4.5: review rate-limit tier (separate pool from Haiku 3.x)

Verification:

• Run one test request and inspect response.stop_reason, response.usage, and whether tool-use / thinking behavior matches expectations

For cached prompts: the render order and hash inputs did not change, so existing cache_control breakpoints keep working. However, changing the model string invalidates the existing cache - the first request on the new model will write the cache fresh.

Migrating to Opus 4.7

Model ID claude-opus-4-7 is authoritative as written here. When the user asks to migrate to Opus 4.7, write model="claude-opus-4-7" exactly. Do not WebFetch to verify - this guide is the source of truth for migration target IDs. The corresponding entry exists in shared/models.md.

Claude Opus 4.7 was Anthropic's most capable model at its launch and is now the previous-generation Opus (Opus 4.8 is current - see Migrating to Opus 4.8 below). It is highly autonomous and performs exceptionally well on long-horizon agentic work, knowledge work, vision tasks, and memory tasks. This section summarizes everything that was new at the 4.7 launch and remains the layered breaking-change path for callers coming from Opus 4.6 or older. It is layered on top of the 4.6 migration above - if the caller is jumping from Opus 4.5 or older, apply the 4.6 changes first, then this section, then the 4.8 section.

TL;DR for someone already on Opus 4.6: update the model ID to claude-opus-4-7, strip any remaining budget_tokens and sampling parameters (both 400 on Opus 4.7), give max_tokens extra headroom and re-baseline with count_tokens() against the new model, opt back into thinking.display: "summarized" if reasoning is surfaced to users, and re-tune effort - it matters more on 4.7 than on any prior Opus.

Breaking changes (will 400 on Opus 4.7)

Extended thinking removed.

thinking: {type: "enabled", budget_tokens: N} is no longer supported on Claude Opus 4.7 or later models and returns a 400 error. Switch to adaptive thinking (thinking: {type: "adaptive"}) and use the effort parameter to control thinking depth. Adaptive thinking is off by default on Claude Opus 4.7: requests with no thinking field run without thinking, matching Opus 4.6 behavior. Set thinking: {type: "adaptive"} explicitly to enable it.

# Before (Opus 4.6)
client.messages.create(
    model="claude-opus-4-6",
    max_tokens=64000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    messages=[{"role": "user", "content": "..."}],
)

# After (Opus 4.7)
client.messages.create(
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

If the caller wasn't using extended thinking, no change is required - thinking is off by default, or can be set explicitly with thinking={"type": "disabled"}.

Delete budget_tokens plumbing entirely. For the replacement effort value, see Choosing an effort level on Opus 4.7 below - there is no exact 1:1 mapping from budget_tokens.

Sampling parameters removed.

The temperature, top_p, and top_k parameters are no longer accepted on Claude Opus 4.7. Requests that include them return a 400 error. Remove these fields from your request payloads. Prompting is the recommended way to guide model behavior on Claude Opus 4.7. If you were using temperature = 0 for determinism, note that it never guaranteed identical outputs on prior models.

# Before - errors on Opus 4.7
client.messages.create(temperature=0.7, top_p=0.9, ...)

# After
client.messages.create(...)  # no sampling params

• If the intent was determinism - use effort: "low" with a tighter prompt.
• If the intent was creative variance - the prompt replacement depends on the use case; ask the user how they want variance elicited. If you can't ask, add a use-case-appropriate instruction along the lines of "choose something off-distribution and interesting" - e.g. for text generation, "Vary your phrasing and structure across responses"; for frontend/design, use the propose-4-directions approach under Design and frontend coding below.

Choosing an effort level on Opus 4.7

budget_tokens controlled how much to think; effort controls how much to think and act, so there is no exact 1:1 mapping. Use xhigh for best results in coding and agentic use cases, and a minimum of high for most intelligence-sensitive use cases. Experiment with other levels to further tune token usage and intelligence:

Silent default changes (no error, but behavior differs)

Thinking content omitted by default.

Thinking blocks still appear in the response stream on Claude Opus 4.7, but their thinking field is empty unless you explicitly opt in. This is a silent change from Claude Opus 4.6, where the default was to return summarized thinking text. To restore summarized thinking content on Claude Opus 4.7, set thinking.display to "summarized". The block-field name is unchanged - it is still block.thinking on a thinking-type block; do not rename it.

Detect this: any code that reads block.thinking (or equivalent) from a thinking-type block and renders it in a UI, log, or trace. The fix is the request parameter, not the response handling - add display: "summarized" to the thinking parameter:

thinking={"type": "adaptive", "display": "summarized"}  # "display" is new on Opus 4.7; values: "omitted" (default) | "summarized"

The default is "omitted" on Claude Opus 4.7. If thinking content was never surfaced anywhere, no change needed. If your product streams reasoning to users, the new default appears as a long pause before output begins; set display: "summarized" to restore visible progress during thinking.

Updated token counting.

Claude Opus 4.7 and Claude Opus 4.6 count tokens differently. The same input text produces a higher token count on Claude Opus 4.7 than on Claude Opus 4.6, and /v1/messages/count_tokens will return a different number of tokens for Claude Opus 4.7 than it did for Claude Opus 4.6. The token efficiency of Claude Opus 4.7 can vary by workload shape. Prompting interventions, task_budget, and effort can help control costs and ensure appropriate token usage. Keep in mind that these controls may trade off model intelligence. Update your max_tokens parameters to give additional headroom, including compaction triggers. Claude Opus 4.7 provides a 1M context window at standard API pricing with no long-context premium.

What else to check:

• Client-side token estimators (tiktoken-style approximations) calibrated against 4.6
• Cost calculators that multiply tokens by a fixed per-token rate
• Rate-limit retry thresholds keyed to measured token counts

Re-baseline by re-running client.messages.count_tokens() against claude-opus-4-7 on a representative sample of the caller's prompts. Do not apply a blanket multiplier. For cost-sensitive workloads, consider reducing effort by one level (e.g. high -> medium). For agentic loops, consider adopting Task Budgets (below).

New feature: Task Budgets (beta)

Opus 4.7 introduces task budgets - tell Claude how many tokens it has for a full agentic loop (thinking + tool calls + final output). The model sees a running countdown and uses it to prioritize work and wrap up gracefully as the budget is consumed.

This is a suggestion the model is aware of, not a hard cap. It is distinct from max_tokens, which remains the enforced per-response limit and is not surfaced to the model. Use task_budget when you want the model to self-moderate; use max_tokens as a hard ceiling to cap usage.

Requires beta header task-budgets-2026-03-13:

client.beta.messages.create(
    betas=["task-budgets-2026-03-13"],
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[...],
)

Set a generous budget for open-ended agentic tasks and tighten it for latency-sensitive ones. Minimum task_budget.total is 20,000 tokens. If the budget is too restrictive for the task, the model may complete it less thoroughly, referencing its budget as the constraint. Do not add task_budget during a migration unless you are sure the budget value is right - if you can run the workload and measure, do so; otherwise ask the user for the value rather than guessing. This is the primary lever for offsetting the token-counting shift on agentic workloads.

Capability improvements

High-resolution vision. Opus 4.7 is the first Claude model with high-resolution image support. Maximum image resolution is 2576 pixels on the long edge (up from 1568px on Opus 4.6 and prior). This unlocks gains on vision-heavy workloads, especially computer use and screenshot/artifact/document understanding. Coordinates returned by the model now map 1:1 to actual image pixels, so no scale-factor math is needed.

High-res support is automatic on Opus 4.7 - no beta header, no client-side opt-in required. The model accepts larger inputs and returns pixel-accurate coordinates out of the box.

Token cost. Full-resolution images on Opus 4.7 can use up to ~3× more image tokens than on prior models (up to ~4784 tokens per image, vs. the previous ~1,600-token cap). If the extra fidelity isn't needed, downsample client-side before sending to control cost - but do not add downsampling by default during a migration. If you're not sure whether the pipeline needs the fidelity, ask the user rather than guessing. Use count_tokens() on representative images on Opus 4.7 to re-baseline before reacting to any measured cost shift.

Beyond resolution, Opus 4.7 also improves on low-level perception (pointing, measuring, counting) and natural-image bounding-box localization and detection.

Knowledge work. Meaningful gains on tasks where the model visually verifies its own output - .docx redlining, .pptx editing, and programmatic chart/figure analysis (e.g. pixel-level data transcription via image-processing libraries). If prompts have scaffolding like "double-check the slide layout before returning", try removing it and re-baselining.

Memory. Opus 4.7 is better at writing and using file-system-based memory. If an agent maintains a scratchpad, notes file, or structured memory store across turns, that agent should improve at jotting down notes to itself and leveraging its notes in future tasks.

User-facing progress updates. Opus 4.7 provides more regular, higher-quality interim updates during long agentic traces. If the system prompt has scaffolding like "After every 3 tool calls, summarize progress", try removing it to avoid excessive user-facing text. If the length or contents of Opus 4.7's updates are not well-calibrated to your use case, explicitly describe what these updates should look like in the prompt and provide examples.

Real-time cybersecurity safeguards

Requests that involve prohibited or high-risk topics may lead to refusals.

Fast Mode: Claude Opus 5.5 / Claude Opus 5 / Opus 4.8 only

Fast mode is available on Claude Opus 5.5, Claude Opus 5, and Opus 4.8. Only surface this if the caller's code actually uses fast mode (e.g. model="claude-opus-4-6-fast", or speed="fast" on an unsupported model); if the word "fast" does not appear in the code, say nothing about Fast Mode.

When you see model="claude-opus-4-6-fast" (or any retired -fast model string), the migration edit is to move the fast-mode traffic onto Claude Opus 5.5, the current fast-capable default, at $8 / $40 per MTok (Claude Opus 5 and Opus 4.8 also work if the caller is staying on that tier):

# Request fast mode on Claude Opus 5.5.
client.beta.messages.create(
    model="claude-opus-5-5", max_tokens=4096,
    speed="fast", betas=["fast-mode-2026-02-01"],
    messages=[...],
)

That is: switch the model to Claude Opus 5.5 (or Claude Opus 5 or Opus 4.8) and request fast mode the supported way, using the beta client.beta.messages.... endpoint, the fast-mode-2026-02-01 beta flag, and speed="fast" as a top-level request parameter (per-language form in SKILL.md § Fast Mode). Opus 4.7 fast mode has also been removed, so do not land on Opus 4.7 either. Do not leave the code on a retired -fast model string - the failure mode differs by version: claude-opus-4-6-fast is retired and the API silently falls back to standard Opus 4.6 (no error - the caller loses fast-mode speed without noticing); claude-opus-4-7-fast and speed="fast" on Opus 4.7 instead return an API error (hard failure - requests break outright rather than degrading). Either way, migrate to a supported fast-mode model (Claude Opus 5.5 by default) now.

Behavioral shifts (prompt-tunable)

These don't break anything, but prompts tuned for Opus 4.6 may land differently. Opus 4.7 is more steerable than 4.6, so small prompt nudges usually close the gap.

More literal instruction following. Claude Opus 4.7 interprets prompts more literally and explicitly than Claude Opus 4.6, particularly at lower effort levels. It will not silently generalize an instruction from one item to another, and it will not infer requests you didn't make. The upside of this literalism is precision and less thrash. It generally performs better for API use cases with carefully tuned prompts, structured extraction, and pipelines where you want predictable behavior. A prompt and harness review may be especially helpful for migration to Claude Opus 4.7.

Verbosity calibrates to task complexity. Opus 4.7 scales response length to how complex it judges the task to be, rather than defaulting to a fixed verbosity - shorter answers on simple lookups, much longer on open-ended analysis. If the product depends on a particular length or style, tune the prompt explicitly. To reduce verbosity:

"Provide concise, focused responses. Skip non-essential context, and keep examples minimal."

If you see specific kinds of over-verbosity (e.g. over-explaining), add instructions targeting those. Positive examples showing the desired level of concision tend to be more effective than negative examples or instructions telling the model what not to do. Do not assume existing "be concise" instructions should be removed - test first.

Tone and writing style. Opus 4.7 is more direct and opinionated, with less validation-forward phrasing and fewer emoji than Opus 4.6's warmer style. As with any new model, prose style on long-form writing may shift. If the product relies on a specific voice, re-evaluate style prompts against the new baseline. If a warmer or more conversational voice is wanted, specify it:

"Use a warm, collaborative tone. Acknowledge the user's framing before answering."

effort matters more than on any prior Opus. Opus 4.7 respects effort levels more strictly, especially at the low end. At low and medium it scopes work to what was asked rather than going above and beyond - good for latency and cost, but on moderate tasks at low there is some risk of under-thinking.

• If shallow reasoning shows up on complex problems, raise effort to high or xhigh rather than prompting around it.
• If effort must stay low for latency, add targeted guidance: "This task involves multi-step reasoning. Think carefully through the problem before responding."
• At xhigh or max, set a large max_tokens so the model has room to think and act across tool calls and subagents. Start at 64K and tune from there. (xhigh is a new effort level on Opus 4.7, between high and max.)

Adaptive-thinking triggering is also steerable. If the model thinks more often than wanted - which can happen with large or complex system prompts - add: "Thinking adds latency and should only be used when it will meaningfully improve answer quality - typically for problems that require multi-step reasoning. When in doubt, respond directly."

Uses tools less often by default. Opus 4.7 tends to use tools less often than 4.6 and to use reasoning more. This produces better results in most cases, but for products that rely on tools (search/retrieval, function-calling, computer-use steps), it can drop tool-use rate. Two levers:

• Raise effort - high or xhigh show substantially more tool usage in agentic search and coding, and are especially useful for knowledge work.
• Prompt for it - be explicit in tool descriptions or the system prompt about when and how to use the tool, and encourage the model to err on the side of using it more often:

"When the answer depends on information not present in the conversation, you MUST call the search tool before answering - do not answer from prior knowledge."

Fewer subagents by default. Opus 4.7 tends to spawn fewer subagents than 4.6. This is steerable - give explicit guidance on when delegation is desirable. For a coding agent, for example:

"Do NOT spawn a subagent for work you can complete directly in a single response (e.g. refactoring a function you can already see). Spawn multiple subagents in the same turn when fanning out across items or reading multiple files."

Design and frontend coding. Opus 4.7 has stronger design instincts than 4.6, with a consistent default house style: warm cream/off-white backgrounds (around #F4F1EA), serif display type (Georgia, Fraunces, Playfair), italic word-accents, and a terracotta/amber accent. This reads well for editorial, hospitality, and portfolio briefs, but will feel off for dashboards, dev tools, fintech, healthcare, or enterprise apps - and it appears in slide decks as well as web UIs.

The default is persistent. Generic instructions ("don't use cream," "make it clean and minimal") tend to shift the model to a different fixed palette rather than producing variety. Two approaches work reliably:

1. Specify a concrete alternative. The model follows explicit specs precisely - give exact hex values, typefaces, and layout constraints.

2. Have the model propose options before building. This breaks the default and gives the user control:

   "Before building, propose 4 distinct visual directions tailored to this brief (each as: bg hex / accent hex / typeface - one-line rationale). Ask the user to pick one, then implement only that direction."

If the caller previously relied on temperature for design variety, use approach (2) - it produces meaningfully different directions across runs.

Opus 4.7 also requires less frontend-design prompting than previous models to avoid generic "AI slop" aesthetics. Where earlier models needed a lengthy anti-slop snippet, Opus 4.7 generates distinctive, creative frontends with a much shorter nudge. This snippet works well alongside the variety approaches above:

"NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white or dark backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. Use unique fonts, cohesive colors and themes, and animations for effects and micro-interactions."

Interactive coding products. Opus 4.7's token usage and behavior can differ between autonomous, asynchronous coding agents with a single user turn and interactive, synchronous coding agents with multiple user turns. Specifically, it tends to use more tokens in interactive settings, primarily because it reasons more after user turns. This can improve long-horizon coherence, instruction following, and coding capabilities in long interactive coding sessions, but also comes with more token usage. To maximize both performance and token efficiency in coding products, use effort: "xhigh" or "high", add autonomous features (like an auto mode), and reduce the number of human interactions required from users.

When limiting required user interactions, specify the task, intent, and relevant constraints upfront in the first human turn. Well-specified, clear, and accurate task descriptions upfront help maximize autonomy and intelligence while minimizing extra token usage after user turns - because Opus 4.7 is more autonomous than prior models, this usage pattern helps to maximize performance. In contrast, ambiguous or underspecified prompts conveyed progressively over multiple user turns tend to reduce token efficiency and sometimes performance.

Code review. Opus 4.7 is meaningfully better at finding bugs than prior models, with both higher recall and precision. However, if a code-review harness was tuned for an earlier model, it may initially show lower recall - this is likely a harness effect, not a capability regression. When a review prompt says "only report high-severity issues," "be conservative," or "don't nitpick," Opus 4.7 follows that instruction more faithfully than earlier models did: it investigates just as thoroughly, identifies the bugs, and then declines to report findings it judges to be below the stated bar. Precision rises, but measured recall can fall even though underlying bug-finding has improved.

Recommended prompt language:

"Report every issue you find, including ones you are uncertain about or consider low-severity. Do not filter for importance or confidence at this stage - a separate verification step will do that. Your goal here is coverage: it is better to surface a finding that later gets filtered out than to silently drop a bug. For each finding, include your confidence level and an estimated severity so a downstream filter can rank them."

This can be used without an actual second step, but moving confidence filtering out of the finding step often helps. If the harness has a separate verification/dedup/ranking stage, tell the model explicitly that its job at the finding stage is coverage, not filtering. If single-pass self-filtering is wanted, be concrete about the bar rather than using qualitative terms like "important" - e.g. "report any bugs that could cause incorrect behavior, a test failure, or a misleading result; only omit nits like pure style or naming preferences." Iterate on prompts against a subset of evals to validate recall or F1 gains.

Computer use. Computer use works across resolutions up to the new 2576px / 3.75MP maximum. Sending images at 1080p provides a good balance of performance and cost. For particularly cost-sensitive workloads, 720p or 1366×768 are lower-cost options with strong performance. Test to find the ideal settings for the use case; experimenting with effort can also help tune behavior.

Opus 4.7 Migration Checklist

Every item is tagged: [BLOCKS] items cause a 400 error, infinite loop, silent truncation, or empty output if missed - apply these as code edits, not as suggestions. [TUNE] items are quality/cost adjustments - surface them to the user as recommendations.

[BLOCKS] items prefixed with "If..." or "At..." are conditional. Before working through the list, scan the file for the conditions: does it surface thinking text to a UI/log? Does it set output_config.effort to "x-high" or "max"? Is it a security workload? Is it a multi-turn agentic loop? Apply only the items whose condition matches.

• [BLOCKS] Replace thinking: {type: "enabled", budget_tokens: N} with thinking: {type: "adaptive"} + output_config.effort; delete budget_tokens plumbing entirely
• [BLOCKS] Strip temperature, top_p, top_k from request construction
• [BLOCKS] If thinking content is surfaced to users or stored in logs: add thinking.display: "summarized" (otherwise the rendered text is empty)
• [BLOCKS] At output_config.effort of xhigh or max: set max_tokens >= 64000 (otherwise output truncates mid-thought)
• [TUNE] Give max_tokens and compaction triggers extra headroom; re-run count_tokens() against claude-opus-4-7 on representative prompts to re-baseline (no blanket multiplier)
• [TUNE] Re-baseline cost and rate-limit dashboards before reacting to measured shifts
• [TUNE] Re-evaluate effort per route - use xhigh for coding/agentic and a minimum of high for most intelligence-sensitive work; it matters more on 4.7 than any prior Opus
• [TUNE] Multi-turn agentic loops: adopt the API-native Task Budgets (output_config.task_budget, beta task-budgets-2026-03-13, minimum 20k tokens) - this is for capping cumulative spend across a loop; per-turn depth is effort
• [TUNE] Check for ambiguous or underspecified instructions that relied on 4.6 generalizing intent, and update them to be clearer or more precise - 4.7 follows them literally
• [TUNE] Tool-use workloads: add explicit when/how-to-use guidance to tool descriptions (4.7 reaches for tools less often)
• [TUNE] Verbosity: test existing length instructions before changing them - 4.7 calibrates length to task complexity, so tune for the desired output rather than assuming a direction
• [TUNE] Remove forced-progress-update scaffolding ("after every N tool calls...")
• [TUNE] Remove knowledge-work verification scaffolding ("double-check the slide layout...") and re-baseline
• [TUNE] Add tone instruction if a warmer / more conversational voice is needed; re-evaluate style prompts on writing-heavy routes
• [TUNE] Subagent tool present: add explicit spawn / don't-spawn guidance
• [TUNE] Frontend/design output: specify a concrete palette/typeface, or have the model propose 4 visual directions before building (the default cream/serif house style is persistent)
• [TUNE] Interactive coding products: use effort: "xhigh" or "high", add autonomous features (e.g. an auto mode) to reduce human interactions, and specify task/intent/constraints upfront in the first turn
• [TUNE] Code-review harnesses: remove or loosen "only report high-severity" / "be conservative" filters and have the model report every finding with confidence + severity; move filtering to a downstream step (4.7 follows severity filters more literally, which can depress measured recall)
• [TUNE] Vision-heavy pipelines (screenshots, charts, document understanding): leave images at native resolution up to 2576px long edge for the accuracy gain; remove any scale-factor math from coordinate handling (coords are now 1:1 with pixels). No beta header / opt-in needed - high-res is automatic on Opus 4.7.
• [TUNE] Computer-use pipelines: send screenshots at 1080p for a good performance/cost balance (720p or 1366×768 for cost-sensitive workloads); experiment with effort to tune behavior
• [TUNE] Cost-sensitive image pipelines: full-res images on 4.7 use up to ~4784 tokens vs ~1,600 on prior models (~3×). Downsampling client-side before upload avoids the increase, but do not downsample by default - if you're unsure whether fidelity is needed, ask the user. Re-baseline with count_tokens() on representative images before reacting to cost shifts.

Migrating to Opus 4.8

Model ID claude-opus-4-8 is authoritative as written here. When the user asks to migrate to Opus 4.8, write model="claude-opus-4-8" exactly. Do not WebFetch to verify - this guide is the source of truth for migration target IDs. The corresponding entry exists in shared/models.md.

Claude Opus 4.8 is our most capable Opus-tier model - highly autonomous, with state-of-the-art long-horizon agentic execution, knowledge work, and memory. It is layered on top of the Opus 4.7 migration above. If the caller is jumping from Opus 4.6 or older, apply the 4.6 and 4.7 sections first, then this one.

No new breaking changes. Opus 4.8 keeps the same request surface as Opus 4.7. The same calls that already work on 4.7 work unchanged on 4.8 - adaptive thinking only (thinking: {type: "enabled", budget_tokens: N} still 400s; use {type: "adaptive"}), sampling parameters (temperature, top_p, top_k) still rejected, last-assistant-turn prefills still 400, thinking.display still defaults to "omitted", and the low/medium/high/xhigh/max effort levels, Task Budgets (beta), and high-resolution vision all behave as on 4.7. A 4.7 -> 4.8 migration is therefore the model-ID swap plus prompt re-tuning - there is no required code edit beyond the model string.

TL;DR for someone already on Opus 4.7: swap the model ID to claude-opus-4-8. Nothing else is required to avoid an error. Then re-tune prompts for the behavioral shifts: 4.8 narrates more than 4.7 (add a silence-default if you want 4.7-like terseness), writes in a warmer, less hedged voice, is more deliberate and asks more often (add autonomy guidance to claw back ask-rate), and is more conservative about reaching for search, subagents, file-based memory, and custom tools (add explicit "when to use this" triggering). For long-horizon agentic work, give the full task specification up front in one well-specified turn and run at high effort.

No new API breaking changes (inherited from 4.7)

These all carry over from Opus 4.7 unchanged - apply them only if the caller is coming from Opus 4.6 or earlier (see the Migrating to Opus 4.7 section above for the before/after and the SDK-specific syntax):

• thinking: {type: "enabled", budget_tokens: N} -> 400. Use thinking: {type: "adaptive"} + output_config.effort.
• temperature, top_p, top_k -> 400. Remove them; steer with prompting.
• Last-assistant-turn prefills -> 400. Use output_config.format (structured outputs) or a system-prompt instruction.
• thinking.display defaults to "omitted"; set "summarized" if you surface reasoning to users.

If the caller is already on Opus 4.7 and these are clean, there is nothing to change here.

New API feature: mid-session system prompts

You can deliver trusted instructions partway through a session by placing {"role": "system", ...} entries directly in the messages array - without editing the top-level system prompt and invalidating your prompt cache. Use it for things the application learns mid-session: the user delivered async context, a mode toggled (auto-approve enabled), files changed on disk, the remaining token budget dropped.

messages=[
    {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "...", "content": "..."}]},
    {"role": "system", "content": "This project's codebase is Go. Write code in Go."},
]

Phrase these as context, not commands. State the fact and let Claude act on it; avoid override-style language ("ignore what the user said", "regardless of the user's request", "disregard the previous instruction"). Claude is trained to protect users from instructions that appear to work against them, and that protection applies to the system role too. No beta header is required; available on Claude Opus 4.8. For cache-placement details and the older-model <system-reminder> fallback, see shared/prompt-caching.md and shared/agent-design.md.

Capability improvements

Long-horizon agentic execution. Opus 4.8 is state-of-the-art at long, autonomous agentic work - complex refactors and overnight coding runs that complete without human correction. To get the most out of it, give the full task specification up front in a single well-specified initial turn and run at high effort (effort: "high" or "xhigh"). Its long-horizon coherence comes partly from reasoning more at each step; combined with a clear up-front goal, that more-intelligent planning often produces more efficient and more accurate output than prior frontier models. The "clear goal up front" principle maps to two product surfaces: in Claude Code, /goal sets direction for the run; with Managed Agents (CMA), state what "done" looks like via an Outcome (user.define_outcome with a gradeable rubric - the harness runs an iterate -> grade -> revise loop), see shared/managed-agents-outcomes.md.

Effort is a dimension to test, not a fixed setting. On prior models many reached for xhigh reflexively to maximize intelligence. Opus 4.8 has a higher intelligence ceiling, so start at high as the default and iterate rather than defaulting to xhigh. Sweep medium, high, and xhigh on your own eval set and weigh the intelligence <-> latency <-> cost tradeoff per route - the relationship isn't monotonic: higher effort up front often reduces turn count and total cost on agentic work, while for some tasks medium delivers equally good results in less time. Reserve max for extremely hard, latency-insensitive cases. The per-level effort table in the Migrating to Opus 4.7 section above applies unchanged on 4.8.

Writing voice and clarity. Testers consistently describe 4.8's prose as clearer, warmer, and less hedged than prior models, with fewer measurable AI vocal tics - especially at higher effort, where it approaches expert-level prose and structure. This is roughly the opposite direction from the 4.7 shift (4.7 was more clipped, direct, and less validation-forward). If you added style prompts to counter 4.7's terseness or to inject warmth, re-evaluate them against the new baseline before keeping them - they may now overcorrect. 4.8 is also a stronger thought partner: more thoughtful, more willing to push back, and more likely to infer the right answer from context.

Code review and debugging. Stronger real-bug finding and clearer explanations than 4.7 - one-shot fixes where 4.7 needed more, and correctly identifying intermittent flakes rather than declaring "fixed" after one clean run. The 4.7 caveat still applies: if a review harness says "only report high-severity issues" or "be conservative", 4.8 follows it literally and measured recall can drop even though underlying bug-finding improved. Tell the model to report everything and filter downstream (or review a second time) - see the Code review guidance in the 4.7 section for the recommended prompt.

Behavioral shifts (prompt-tunable)

None of these break code, but prompts tuned for Opus 4.7 may land differently. 4.8 follows instructions well, so small, explicit nudges close the gap.

Tool triggering is surface-dependent (search & knowledge). 4.8's tool-triggering is more surface-dependent than in prior models: with a system prompt present it is high-precision / low-recall - web search triggers slightly more often but runs fewer rounds per trigger, while knowledge-retrieval tools (Drive, project knowledge, connected files) trigger less often. It searches when it's confident search is needed and otherwise answers from context, which can lower research depth on tasks that need it. Recover should-search rate with an explicit search-first instruction:

<search_first>
For questions where current information would change the answer (recent events, current roles or prices, version-specific behavior, or anything the user flags as time-sensitive) search before answering rather than answering from memory. For open-ended research requests, begin searching immediately; do not ask a scoping question first unless the request is genuinely ambiguous about what to research.
</search_first>

Under-utilization of subagents, memory, and custom tools. Separately from search, 4.8 is conservative about reaching for capabilities that need an explicit "decide to use this" step - file-based memory, subagent delegation, custom tools. It won't reach for complex or expensive capabilities unless reasonably sure they're needed. This is steerable since 4.8 follows instructions well - say when each capability applies, not just that it exists:

"Before any task longer than a few turns, check your memory file for relevant prior context and write new findings to it as you go. When a task fans out across independent items (many files to read, many tests to run, many candidates to check), delegate to subagents rather than iterating serially."

The same lever works at the tool-description level, not just the system prompt: prescriptive descriptions that state when to call a tool (e.g. "Call this when the user asks about current prices or recent events") give meaningful lift on 4.8 over descriptions that only state what the tool does. Make the trigger condition part of each capability's own description.

More user-facing narration. 4.8 narrates more than 4.7 - more text between tool calls in long tool-calling sessions, and longer, more detailed end-of-task wrap-ups by default. If you previously added scaffolding to force interim status ("after every 3 tool calls, summarize progress"), remove it - 4.8 does this on its own. If the narration is too verbose for a coding agent, an explicit silence-default makes it behave like 4.7 with no loss of quality:

"Default to silence between tool calls. Only write text when you find something, change direction, or hit a blocker - one sentence each. Do not narrate routine actions ('Now I'll...', 'Let me check...', 'Looking at...'). When done: one or two sentences on the outcome. Do not recap every file or test - the user has been following along."

For knowledge-work deliverables (reports, analysis readouts), verbosity responds very well to instructions in user preferences or the user turn - expose a verbosity preference rather than hard-coding a length.

More deliberate - asks more often. 4.8 is more deliberate than prior Opus models. On minor decisions it would previously just make (a variable name, a default value, which of two equivalent approaches), it tends to pause and ask, and it often closes a completed task with "Want me to also...?" rather than doing the obvious next step or stopping cleanly. This is preferred for high-stakes or unfamiliar codebases, but bugs users when uncalibrated. Grant autonomy on the small stuff while keeping caution where it matters (in Claude Code testing this cut ask-rate by ~12 percentage points with no increase in over-reach):

"For minor choices (naming, formatting, default values, which approach among equivalents), pick a reasonable option and note it rather than asking. For scope changes or destructive actions, still ask first."

Verbose reasoning when thinking is disabled. With thinking: {type: "disabled"}, 4.8 occasionally writes longer explanations of its reasoning into the visible response, which reads as verbose when the user wants a fast, quick answer. The simplest fix is to leave adaptive thinking on - set thinking: {type: "adaptive"} (the recommended setting; it adjusts how much to think per task). Note adaptive is not on when the field is omitted - like Opus 4.7, a request with no thinking field runs without thinking, so set it explicitly. If you need thinking off for latency or cost, scope it in the system prompt:

"Respond only with your final answer. Do not include exploratory reasoning, intermediate drafts, diffs you considered but rejected, or meta-commentary about your process."

Opus 4.8 Migration Checklist

Every item is tagged: [BLOCKS] items cause a 400 error if missed; [TUNE] items are quality/cost adjustments - surface them to the user as recommendations.

For a caller already on Opus 4.7, only the first item is required; everything else is [TUNE]. The conditional [BLOCKS] item applies only when coming from Opus 4.6 or earlier.

• [BLOCKS] Update the model= string to claude-opus-4-8
• [BLOCKS] (only if coming from Opus 4.6 or earlier) Apply the Migrating to Opus 4.7 breaking changes first - budget_tokens -> adaptive thinking, strip temperature/top_p/top_k, remove last-assistant-turn prefills. These already 400 on 4.7 and continue to 400 on 4.8.
• [TUNE] Long-horizon / agentic work: put the full task spec in one well-specified first turn and run at high or xhigh effort (Claude Code: /goal; Managed Agents: an Outcome with a gradeable rubric)
• [TUNE] Effort: sweep medium / high / xhigh on your eval set and pick per route by the intelligence <-> latency <-> cost tradeoff (default high, xhigh for coding/agentic)
• [TUNE] Research depth & tool use: add a search-first instruction; add explicit triggering guidance for subagents, file-based memory, and custom tools (4.8 under-reaches for these by default) - in the system prompt and in each tool's own description (prescriptive "call this when..." descriptions give measurable lift)
• [TUNE] Narration: remove forced-progress scaffolding ("after every N tool calls..."); add a silence-default if a coding agent is too chatty
• [TUNE] Autonomy: add small-decisions-don't-ask guidance to cut ask-rate, while keeping caution on scope changes / destructive actions
• [TUNE] Writing voice: re-evaluate style prompts added to counter 4.7's directness - 4.8 is warmer and less hedged by default; re-baseline before keeping them
• [TUNE] Code-review harnesses: keep the report-everything-filter-downstream pattern (4.8 follows "only high-severity" / "be conservative" filters literally, which can depress measured recall)
• [TUNE] Thinking-disabled paths: add a final-answer-only instruction if reasoning leaks into the visible response
• [TUNE] Consider mid-session system messages (role:"system" in messages; no beta header) for context the app learns mid-session, instead of rebuilding the top-level system prompt and invalidating the cache

Migrating to Claude Opus 5

Model ID claude-opus-5 is authoritative as written here. When the user asks to migrate to Claude Opus 5, write model="claude-opus-5" exactly. Do not WebFetch to verify - this guide is the source of truth for migration target IDs. The corresponding entry exists in shared/models.md.

Claude Opus 5 is the successor to Claude Opus 4.8 in the Opus line, and is strongest on long-horizon agentic work and coding. It is layered on top of the Opus 4.8 migration above; if the caller is coming from Opus 4.7 or older, apply those sections first. Like Claude Fable 5.1, it ships with elevated cybersecurity safeguards, and its safety classifiers can decline a request: you get a normal HTTP 200 with stop_reason: "refusal" and a stop_details category, not an error. Benign security and life-sciences work occasionally trips them, so check stop_reason before reading response.content - code that indexes content[0] unconditionally breaks on a refusal. Cyber-category refusals route to Opus 4.8 as the recommended fallback, so a fallback strategy genuinely recovers the request rather than just relabelling the failure. The full refusal semantics (pre-output vs mid-stream billing, retry strategies, fallback credit) are in the Claude Fable 5.1 section below and apply here unchanged.

Existing prompts and evals should carry over with strong out-of-the-box performance. It is a drop-in upgrade at Opus 4.8's pricing - $5 per million input tokens, $25 per million output - with the same feature set: 1M context (default, no beta header), 128K max output, adaptive thinking, prompt caching, batch processing, the Files API, PDF support, vision, and the full server-side and client-side tool set. claude-opus-5 is a fixed ID with no date suffix, same scheme as claude-opus-4-8.

The migration is the model-ID swap plus prompt re-tuning, with two breaking changes covered below.

Availability at launch: Claude API (claude-opus-5), Amazon Bedrock (anthropic.claude-opus-5), Google Cloud (claude-opus-5), and Microsoft Foundry. Opus 4.8 stays available on all four.

Rate limits are a separate bucket. Opus 4.8/4.7/4.6/4.5 share one combined Opus limit; Claude Opus 5 does not draw from it. Shifting traffic over neither frees headroom on the old bucket nor inherits it - check your tier's Claude Opus 5 limits before moving volume.

TL;DR for someone already on Claude Opus 4.8: swap the model ID. Then re-tune: Claude Opus 5 writes longer user-facing responses and longer files on disk (add explicit conciseness and deliverable-length instructions - effort does not reliably shorten visible output), verifies its own work without being told (delete your verification instructions and harness verification steps), and can expand task scope (add a scope-discipline instruction). Run a fresh effort sweep - low and medium are unusually strong here and are the primary cost/latency lever.

Breaking change 1: thinking is on by default

A request that omits the thinking parameter thinks on Claude Opus 5, unlike Claude Opus 4.8 and Opus 4.7 where omitting it meant no thinking. thinking: {type: "adaptive"} remains valid and is equivalent to the default - the wire value didn't change, the default did.

This is a silent cost and truncation change, not just a behavior one: max_tokens is a hard cap on thinking plus response text. A workload that ran without thinking on Opus 4.8 and sized max_tokens tightly around its answer can now truncate mid-response. Revisit max_tokens on every route that never set thinking. To keep the old behavior, pass thinking: {type: "disabled"} - subject to the effort cap below.

Raw thinking tokens are never returned on Claude Opus 5; display defaults to "omitted", and display: "summarized" gets you a summary. This also means a fallback model cannot read Claude Opus 5's thinking.

Breaking change 2: disabling thinking is capped at high effort

Disabling thinking is available only at effort high or lower; thinking: {type: "disabled"} combined with xhigh or max returns a 400. Opus 4.8 accepts that combination, so audit any route that disables thinking before migrating.

The check is per request. Effort and thinking are validated independently on every call, so a later request that raises effort to xhigh while thinking is still disabled is rejected even though earlier requests in the same conversation succeeded.

# 400 on Claude Opus 5 - disabled thinking above `high`
client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    thinking={"type": "disabled"},
    output_config={"effort": "xhigh"},
    messages=[...],
)

Migrating: either enable thinking at xhigh/max, or lower effort to high or below. Given how well Claude Opus 5 performs at low and medium, a latency-sensitive route that previously ran xhigh + disabled thinking is usually better served by medium with thinking on than by keeping the disabled path.

Everything else from the Opus 4.7/4.8 request surface is unchanged: budget_tokens still 400s (use output_config.effort), sampling parameters (temperature, top_p, top_k) are still rejected, last-assistant-turn prefills still 400, and thinking.display still defaults to "omitted".

Two failure modes when thinking is disabled

Are you affected? Only if you explicitly set thinking: {type: "disabled"}. Thinking is on by default on Claude Opus 5 (see Breaking change 1 above), so an unmodified request never hits either of these - but code carrying a disabled-thinking setting forward from Opus 4.8, where it was the default behaviour, does.

Both are specific to thinking: {type: "disabled"} on Claude Opus 5, and for both the primary recommendation is the same: turn thinking back on and use a lower effort to control cost and verbosity instead. Disabling thinking is the more expensive lever in every sense - it is what triggers these, and low/medium effort already gets you most of the token and latency saving (see § Effort below).

1. Tool calls can arrive as plain text. The model occasionally writes a tool call into its user-facing text rather than emitting a structured tool_use block. The turn completes normally and the call never runs - there is no error and no tool_use block to catch, so a harness sees a successful turn that silently did nothing. Worse in an agentic loop: the bogus text stays in conversation history and skews later turns. Most common on tool-heavy workloads such as search.

2. <thinking> tags can leak into the visible response. The model may emit <thinking> or other internal XML in its user-facing output.

If you cannot enable thinking, one instruction covers both failure modes - give the model explicit permission to talk before a tool call (the tool-as-text failure appears to come from suppressing the preamble it wants to write), and forbid internal tags generically:

"When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing. Do not include internal or system XML tags in your response."

Two counterintuitive rules for that instruction:

• Delete any instruction telling the model not to think or not to reason. That kind of rule increases tag leakage rather than suppressing it.
• Do not name thinking tags in the prompt. Calling out <thinking> by name is measurably less effective than the generic "internal or system XML tags" wording above.

New API features

Two additions, each behind its own beta header. Both are optional - a migrated request works without them.

1. fallbacks: "default" - recommended for every caller. Claude Opus 5's safety classifiers can decline a request; the fallbacks parameter re-runs a declined request on another model server-side instead of returning the refusal to you. Previously you named the substitute yourself ("fallbacks": [{"model": "claude-opus-4-8"}]). The new "default" mode picks Anthropic's recommended fallback automatically, routed by refusal category - cyber-category refusals go to Claude Opus 4.8.

POST /v1/messages
anthropic-beta: server-side-fallback-2026-07-01

{"model": "claude-opus-5", "fallbacks": "default", "max_tokens": 1024,
 "messages": [{"role": "user", "content": "Say OK."}]}

Prefer "default" over pinning a model. Different fallback models carry different classifiers, so the right substitute depends on why the request was declined - and "default" removes the migration you would otherwise owe when a pinned fallback model is deprecated. Note the header is server-side-fallback-2026-07-01, distinct from the -2026-06-01 header that gates the array form; the array form's semantics (content blocks, usage.iterations, sticky routing) are unchanged and documented in the Claude Fable 5.1 refusal section below.

2. Mid-conversation tool changes (beta mid-conversation-tool-changes-2026-07-01). Change a conversation's tool set between turns without invalidating the prompt cache. Previously tools was fixed for the conversation's lifetime and any edit re-billed the whole prefix. Append a {"role": "system", "content": [...]} message carrying a tool_addition or tool_removal block:

messages = [
    {"role": "user", "content": "What tools do you have for weather in Paris?"},
    {"role": "system", "content": [
        {"type": "tool_addition", "tool": {"type": "tool_reference", "name": "get_forecast"}},
    ]},
]

The added tool must already be declared in tools[] with "defer_loading": True - declared up front, but not loaded into context until a tool_addition surfaces it. A tool_removal block must sit either immediately before an assistant message or at the end of messages. To change a tool's definition, remove the old one on one request, then send the updated entry in tools[] on the next. See shared/tool-use-concepts.md § Mid-conversation tool changes.

Warning: Earlier previews of this feature used a different beta header and different block shapes. Both are deprecated - if the code you're migrating carries anything other than mid-conversation-tool-changes-2026-07-01 with tool_addition / tool_removal / tool_reference, update the header and the shapes together.

SDK typings lag these blocks. Pass them as plain dicts in Python (the SDK forwards unknown keys unchanged) or add a @ts-expect-error in TypeScript until the types catch up. extra_body / extra_headers work on .stream() exactly as on .create().

Capability improvements

Agentic coding. Claude Opus 5 is a workhorse for agentic coding and is strongest on difficult tasks - multi-file features, larger refactors, end-to-end feature work. It completes tasks rather than leaving stubs or placeholders. The gap over prior models is smaller on easy single-turn edits, so evaluate it on the hard end of your workload. To get the most out of it, give the complete task specification up front and let it run; longer autonomous sessions with more parallel agents show the strongest results, short interactive edits the least.

Code review and bug-finding. High precision and high recall - a high rate of real bugs per pass, with the extra findings mostly real rather than false positives. It stays accurate at lower effort, which makes a cheap fast pass at review time plus a thorough pass later a practical pattern.

Effort: the full ladder, and where to start. Claude Opus 5 supports all five levels - low, medium, high, xhigh, max - with no beta header. The API default is high.

• Start at high (the API default), then sweep down. low and medium are unusually effective on this model - strong quality at a fraction of the tokens and latency on many workloads - so treat them as the primary cost/latency lever and reserve high and above for tasks where your evals show a quality difference. Effort defaults carried over from a prior model are usually not the right setting here; run a fresh sweep.
• xhigh and max are for measured wins, not a starting point. max is the top tier for the deepest reasoning and worth testing where capability matters more than spend, but it can show diminishing returns and overthink simpler tasks.

At xhigh or max, set a large max_tokens so the model has room to think and act across tool calls and subagents. Start at 64K and tune.

Lower prompt-cache minimum. The minimum cacheable prompt is 512 tokens on Claude Opus 5, down from 1024 on Opus 4.8. Prompts previously too short to cache now create entries with no code change - worth re-checking any prompt you'd written off as uncacheable. See shared/prompt-caching.md.

Fast mode. speed: "fast" (beta header fast-mode-2026-02-01) is supported on Claude Opus 5, priced at $10 / $50 per MTok. It is a research preview on the Claude API only - including Managed Agents - and is not available on Amazon Bedrock, Google Cloud, or Microsoft Foundry. Fast mode draws on dedicated rate limits separate from the standard Opus pools.

Vision - give it tools, not more thinking. Stronger on chart, document, and diagram understanding, and on UI and frontend visual replication. The highest-leverage change is giving it tools to iteratively analyze, crop, and visually verify its own work: on this model tool use is a markedly more cost-effective lever than raising thinking alone. Claude Opus 5 sits in the high-resolution tier alongside Opus 4.8 - 2576 px on the long edge, up to 4784 visual tokens per image - so coordinates map 1:1 to pixels and no scale-factor math is needed. Any prompt-side workaround you added for a prior model's vision limitations should be re-validated; several are now counterproductive.

Long context. 1M-token context window as both the default and the maximum. Instruction following, tool calling, and reasoning stay strong across the full window.

Office and document tasks. Generates and edits complex multi-sheet Excel files with non-trivial formulas, and visually strong PowerPoint decks that follow slide-design best practices. It can be prompted to adhere to a specific style or template when one is required.

Multi-agent coordination. Coordinates teams of subagents well - few cases of agents overwriting each other's work, and effective use of writer-verifier patterns. Workloads that benefit from multi-agent patterns are good fits. Cost-sensitive workloads should cap multi-agent usage - see the delegation section below, because this model reaches for subagents more readily than its predecessors.

Behavioral shifts (prompt-tunable)

Longer user-facing responses. Default response text is longer than on prior models. effort is not the lever here - changing it may move thinking volume without reliably changing visible output length. Prompting is: in testing, a short conciseness instruction cut user-facing response length by ~20%.

"Keep responses focused, brief, and concise to avoid overwhelming the person. Disclaimers and caveats are brief, with most of the response on the main answer; when asked to explain something, give a high-level summary unless an in-depth one is specifically requested."

For a long system prompt, pair that with a one-line reminder near the end:

<tone_preference>
Keep outputs reasonably concise.
</tone_preference>

More narration in agentic sessions (the lever runs both ways - the same explicit-description technique tunes narration up or restyles it, if your product wants more). Claude Opus 5 narrates what it is about to do, and its per-message output in agentic sessions is longer than prior models'. It responds well to explicit guidance on how to communicate during a task rather than just how much. For coding agents, this block calibrates it:

# Communicating with the user
Your text output is what the user reads between tool calls; they usually can't see your thinking or the raw tool results. Write it for a teammate who stepped away and is catching up, not for a log file: they don't know the codenames or shorthand you created along the way, and they didn't watch your process unfold. Before your first tool call, say in a sentence what you're about to do; while working, give brief updates when you find something load-bearing or change direction.

Lead with the outcome. Your first sentence after finishing should answer "what happened" or "what did you find" - the thing the user would ask for if they said "just give me the TLDR." Supporting detail and reasoning should come after, for readers who want them.

Being readable and being concise are different things, and readable matters more. If the user has to reread your summary or ask you to explain, any time saved by brevity is gone. The way to keep output short is to be selective about what you include (drop details that don't change what the reader would do next), not to compress the writing into fragments, abbreviations, arrow chains like `A -> B -> fails`, or jargon. What you do include, write in complete sentences with the technical terms spelled out. Don't make the reader cross-reference labels or numbering you invented earlier; say what you mean in place.

Match the response to the question: a simple question should be answered with a direct answer in prose, not headers and sections. Use tables only for short enumerable facts, with explanations in the surrounding prose rather than the cells. Calibrate to the user - a bit tighter for an expert, more explanatory for someone newer.

Write code that reads like the surrounding code: match its comment density, naming, and idiom.

Only write a code comment to state a constraint the code itself can't show - never to say where it came from, what the next line does, or why your change is correct; that's you talking to the reviewer, not the next reader, and it's noise the moment the PR merges.

Longer written deliverables. Separate from conversational verbosity: files Claude Opus 5 writes to disk - reports, Markdown documents, summaries - are often longer than on prior models. If your product ships Claude-authored documents, calibrate length explicitly:

"Match the length of written deliverables (especially Markdown files) to what the task needs: cover the substance, but do not pad documents with filler sections, redundant summaries, or boilerplate."

Self-check instructions are the same trap. Beyond harness scaffolding, per-prompt re-check phrasing - "double-check your answer", "re-verify before responding" - triggers the same extra work. Note this inverts a standard prompting best practice: "ask Claude to self-check" is generally sound advice and is wrong here, so a prompt library that applies it uniformly needs a carve-out for this model rather than a global rule.

Over-verification - delete your verification scaffolding. Claude Opus 5 verifies its own work without being asked. Instructions that tell it to verify ("include a final verification step for virtually any non-trivial task", "use a subagent to verify") now cause over-verification. Removing them reduces over-verification with no capability regression - this is a delete, not a rewrite. The same applies to harness-level scaffolding: separate verification steps carried over from prior models are likely redundant now.

Task scope expansion. It can add steps the user didn't request, or apply its own judgment about what the task should be without making that clear. In testing, this instruction reduced scope changes to nearly zero without producing excessive clarifying questions:

"Deliver what the user asked for, at the scope they intended. Interpret ambiguity the way a careful colleague would: make routine judgment calls yourself, and check in only when different readings would lead to materially different work. If you conclude the ask is mistaken or a better approach exists, say so in a sentence and keep going with the task as asked - don't quietly narrow, widen, or transform it. Finish the whole task, not just the easy part of it - only report completion when it's fully done. If you genuinely can't complete something, do the rest and state plainly what's missing and why. Stop short of actions or changes that are clearly beyond what the user's ask implies."

The revised wording adds a finish-the-whole-task clause - report completion only when the work is actually done, and if something genuinely can't be finished, do the rest and say plainly what is missing. That covers premature "done" claims, which scope-discipline wording alone did not.

Delegates to subagents more readily - the opposite of Opus 4.8. This is a direction change worth flagging: Opus 4.8 under-reached for subagents and needed prompting to delegate. Claude Opus 5 reaches for them freely, which multiplies cost and latency - each subagent re-establishes context, re-explores, reports back, and then the coordinator re-reads the report. If your harness supports subagents, any "delegate more" guidance you added for Opus 4.8 should come out, and you likely want an explicit cap. A deterministic ceiling on spawn count is the reliable lever; this block reduces delegation and token spend:

## Delegating to subagents
Subagents multiply cost and time: each one re-establishes context, re-explores, and reports back, and you then re-read its report. Delegate rarely and only when the payoff clearly exceeds that overhead.

Do use subagents for:
- Large tasks that are genuinely independent and parallelizable. For example, wide multi-file investigations.

Do NOT use subagents for:
- Work you could finish yourself in a handful of tool calls. For example: a few file reads, a handful of edits, a simple search task, relatively simple verification.
- Review, verification, or to double check your work. Verification belongs in your main agent loop.

Use of parallel or multiple subagents:
- Do not use multiple subagents on a single small task. Parallel subagents are for genuinely independent, sizeable tracks (unrelated modules, a wide multi-file investigation), not for splitting one modest job into pieces.
- If the task can be completed with one subagent, choose one subagent over multiple subagents. Keep spawn counts low.
- Never use more than 20 parallel agents unless the user explicitly requests it.

When delegating to subagents:
- Brief the subagent precisely the first time. Avoid launching, waiting, and re-briefing.
- If you delegate, commit to the delegation. Never redo the subagent's work and do not re-derive its findings once it reports back.
- If you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.

Note the interaction with over-verification below: "do not use subagents to verify" and "delete your verification scaffolding" are the same underlying fix seen from two angles.

Narrates self-corrections more than prior models. It flags and explains its own earlier mistakes at length, which reads as thrash in a user-facing product. Scope corrections to the ones that actually change the user's outcome:

# Corrections
Avoid unnecessary or excessive self-correction. Only correct an earlier statement in your user-facing text when the error would change the user's code, conclusions, or decisions. State corrections plainly and concisely, and continue the task; combine multiple corrections rather than enumerating them all. For slips that change nothing for the user, simply make the correction and move on - no need to note it explicitly. Don't add apologies or preambles, don't be overly self-critical, and don't ruminate or give a detailed account of the mistake or tally past errors. Sometimes, other agents will report incorrect or misleading results - don't always take them at face value immediately. If other agents correct your statements and they are right, then simply update your approach without narrating too much about the correction to the user. This instruction does not apply to thinking blocks.

A follow-up question about your earlier work is not, by itself, a signal that you got something wrong - answer what was asked. A statement that was accurate needs no correction: don't re-audit how you phrased it, how you verified it, or limits you already stated. When the user does point to a real error, correct it plainly as above.

The second paragraph matters as much as the first: a plain follow-up question can otherwise trigger a re-audit of work that was correct.

Time to first token (TTFT). Claude Opus 5 sometimes thinks before its first visible block, which raises TTFT - a problem for user-facing chat and voice, where the pause reads as latency. This one-line instruction reduces pre-first-block thinking significantly:

"Latency-sensitive; begin your visible answer immediately."

Apply it only where first-token latency is user-visible; on background and agentic routes the pre-answer thinking is usually worth keeping.

Severity filters still depress measured recall. Unchanged from 4.7/4.8: if a review harness says "only report high-severity issues" or "be conservative", Claude Opus 5 follows it literally. Ask it to report everything with confidence and severity, and filter in a separate pass - see the Code review guidance in the Opus 4.7 section for the recommended prompt.

Claude Opus 5 Migration Checklist

[BLOCKS] items cause a 400 error if missed; [TUNE] items are quality/cost adjustments - surface them to the user as recommendations.

• [BLOCKS] Update the model= string to claude-opus-5
• [BLOCKS] Any route combining thinking: {type: "disabled"} with effort of xhigh or max: enable thinking, or lower effort to high or below. Validated per request, so audit every call site, not just the first
• [BLOCKS] Every route that never set thinking: it now thinks, and max_tokens caps thinking + response text together. Raise max_tokens or pass thinking: {type: "disabled"} at effort high or below - otherwise responses truncate mid-answer
• [BLOCKS] (only if coming from Opus 4.7 or earlier) Apply the Migrating to Opus 4.7 breaking changes first - budget_tokens -> adaptive thinking, strip temperature/top_p/top_k, remove last-assistant-turn prefills
• [TUNE] Effort: start at high (the API default) and sweep down - low/medium are unusually strong on this model and are the primary cost/latency lever; reserve xhigh/max for tasks where you've measured a quality difference. Prior-model defaults rarely transfer. At xhigh/max, set max_tokens to at least 64K
• [TUNE] Re-check prompts you'd written off as uncacheable - the minimum drops to 512 tokens (from 1024 on Opus 4.8)
• [TUNE] Rate limits: Claude Opus 5 is a separate bucket from the combined Opus 4.x pool - confirm your tier's limits before shifting volume
• [TUNE] Fast mode (speed: "fast", fast-mode-2026-02-01, $10/$50) is Claude-API-only - drop it on Bedrock, Google Cloud, and Foundry routes
• [TUNE] Verbosity: add a conciseness instruction (and a <tone_preference> tag for long system prompts). Do not try to shorten output by lowering effort - it doesn't reliably work
• [TUNE] Agentic sessions: add a "Communicating with the user" block to calibrate inter-tool-call narration
• [TUNE] Claude-authored files: add a deliverable-length instruction
• [TUNE] Delete verification instructions from prompts and verification steps from the harness - including per-prompt "double-check your answer" phrasing, which inverts the usual self-check best practice on this model
• [TUNE] Add the scope-discipline instruction if the model expands task scope
• [TUNE] Vision pipelines: re-validate prompt-side workarounds written for a prior model's vision limitations
• [TUNE] Consider mid-conversation tool changes (mid-conversation-tool-changes-2026-07-01) - changes the tool set between turns without invalidating the prompt cache. Note per-turn effort / task_budget were not in this launch (per-message effort shipped later, beta mid-conversation-output-config-2026-07-01, and works on Claude Opus 5 too - see Migrating to Claude Fable 5.1 from Claude Fable 5 § New API features; task_budget stays request-level)
• [TUNE] Subagent-capable harnesses: this model delegates more readily than Opus 4.8 - remove any "delegate more" guidance you added for 4.8 and add an explicit cap
• [TUNE] User-facing products: add the corrections instruction if self-correction narration reads as thrash
• [TUNE] TTFT-sensitive routes (chat, voice): add "Latency-sensitive; begin your visible answer immediately" to reduce pre-first-block thinking; skip on background/agentic routes
• [TUNE] Any route running thinking: {type: "disabled"}: prefer turning thinking on at low/medium effort. Disabled thinking can emit tool calls as plain text (the call silently never runs) and leak <thinking> tags into output. If you must stay thinking-off, delete any don't-think/don't-reason rule and add the combined "When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing. Do not include internal or system XML tags in your response" - do not name <thinking> tags in the prompt
• [TUNE] Vision pipelines: give it crop/analyze/verify tools - cheaper and more effective than raising thinking
• [TUNE] Handle stop_reason: "refusal" before reading content, and opt into fallbacks: "default" (server-side-fallback-2026-07-01) rather than pinning a model - cyber-category refusals route to Claude Opus 4.8
• [TUNE] Long-horizon / agentic work: give the complete task spec up front in one turn rather than building it up across interactive turns

Migrating to Claude Sonnet 5

Model ID claude-sonnet-5 is authoritative as written here. When the user asks to migrate to Claude Sonnet 5, write model="claude-sonnet-5" exactly. Do not WebFetch to verify - this guide is the source of truth for migration target IDs. The corresponding entry exists in shared/models.md.

Claude Sonnet 5 substantially improves on Sonnet 4.6 for coding and agentic work, reaching what was previously Opus-tier quality on many tasks. Its API surface aligns with Opus 4.7/4.8: manual extended thinking is removed (adaptive or disabled only, adaptive is the default), and non-default sampling parameters are rejected. This section is layered on top of the Sonnet 4.6 migration above - if the caller is jumping from Sonnet 4.5 or older, apply the 4.6 changes first, then this one.

TL;DR for someone already on Sonnet 4.6: swap the model ID to claude-sonnet-5. Replace any remaining thinking: {type: "enabled", budget_tokens: N} with thinking: {type: "adaptive"} (the transitional escape hatch is gone - it now 400s), and note that omitting thinking now runs adaptive (4.6 ran thinking-off). Strip non-default temperature/top_p/top_k. Re-run count_tokens() against claude-sonnet-5 - the new tokenizer produces ~30% more tokens for the same text, so token-budgeted limits and cost baselines shift (per-token pricing is also lower than Sonnet 4.6: $2/$10 vs $3/$15 per MTok). effort defaults to high, the same as Sonnet 4.6 - raise to xhigh for the hardest coding and agentic tasks (Claude Sonnet 5 supports the full low/medium/high/xhigh/max range), and give max_tokens headroom at xhigh/max (the new tokenizer means a Sonnet-4.6-tuned max_tokens may truncate equivalent output). Then re-tune prompts: Claude Sonnet 5 interprets instructions more literally than 4.6 - holdover style/tone directives now apply at face value; it is more agentic by default and reaches for tools and self-verification loops more readily (with thinking disabled it is less tool-eager - add an explicit nudge); it gives better in-progress updates by default (drop forced "summarize every N tool calls" scaffolding); and code-review harnesses with conservative-reporting instructions may see lower recall (tell it to report everything and filter downstream).

Breaking changes (will 400 on Claude Sonnet 5)

These bring the Sonnet line onto the same request surface as Opus 4.7/4.8. See the Per-SDK Syntax Reference above for the language-specific spelling of each.

1. Extended thinking removed - adaptive only. thinking: {type: "enabled", budget_tokens: N} returns a 400. The transitional escape hatch that still worked on Sonnet 4.6 is gone. Use adaptive thinking with an effort hint:

# Before - deprecated on Sonnet 4.6, now errors on Claude Sonnet 5
thinking={"type": "enabled", "budget_tokens": 10000}

# After
thinking={"type": "adaptive"},
output_config={"effort": "high"},  # or "xhigh" for the hardest coding/agentic tasks

To turn thinking off entirely, set thinking: {type: "disabled"} - but see Adaptive vs. disabled below before doing so.

2. Sampling parameters rejected. Setting temperature, top_p, or top_k to a non-default value returns a 400; omitting the parameter, or passing its default, is still accepted. The safest migration is to omit them entirely and steer with prompting. If the caller was relying on temperature=0 for determinism, note in the migration comment that it never guaranteed identical outputs.

# Before
client.messages.create(model="claude-sonnet-4-6", temperature=0.2, ...)

# After - omit entirely
client.messages.create(model="claude-sonnet-5", ...)

3. Bedrock only: forced tool_choice requires thinking: {type: "disabled"}. On Amazon Bedrock, pass thinking: {type: "disabled"} alongside tool_choice: {type: "tool", name: ...} or tool_choice: {type: "any"}. The Claude API and Vertex AI do not require this.

Not a request-shape error, but handle it: cybersecurity safeguards. Claude Sonnet 5 is substantially more cyber-capable than Sonnet 4.6, so - like Opus 4.7/4.8 - requests touching prohibited or high-risk topics may be refused. Handle it as a content outcome (see the refusal stop-reason guidance in the Claude Fable 5.1 section if the caller needs a fallback path).

Unchanged from Sonnet 4.6: assistant-turn prefills still return a 400 (use output_config.format or a system-prompt instruction); the 1M-token context window, the 128k max-output ceiling, prompt caching, batch processing, the Files API, PDF support, vision, and the full server- and client-side tool set all carry over.

Silent default change: adaptive thinking on when thinking is omitted

On Sonnet 4.6, a request with no thinking field runs without thinking. On Claude Sonnet 5, the same request runs with adaptive thinking. This is not an error - but callers who never set thinking will now see thinking output (and spend thinking tokens) where they didn't before. max_tokens is a hard limit on total output (thinking + response text), so a workload that ran thinking-off on Sonnet 4.6 by omission may now truncate. Either set thinking: {type: "disabled"} explicitly to keep the old behavior, or revisit max_tokens to leave room for thinking.

Silent default change: thinking.display defaults to "omitted"

thinking.display defaults to "omitted" on Claude Sonnet 5 (matching Opus 4.7/4.8 and Claude Fable 5.1); on Sonnet 4.6 it defaulted to "summarized". With the default, thinking blocks stream with empty text - to a streaming UI this looks like a long pause before output. Combined with the adaptive-on-by-default change above, a Sonnet 4.6 caller who omits thinking entirely now gets adaptive thinking and empty-text thinking blocks. If you stream reasoning to users, set thinking: {type: "adaptive", display: "summarized"} explicitly. display controls visibility only - thinking happens and is billed the same under every setting.

New tokenizer (~30% more tokens)

Claude Sonnet 5 uses the same new tokenizer as Opus 4.7/4.8. The same input text produces approximately 30% more tokens than on Sonnet 4.6. No request/response shape changes and no code edits are required, but everything measured or budgeted in tokens shifts: usage fields and count_tokens() results for the same text are higher, the 1M context window holds less text, and a max_tokens limit tuned for Sonnet 4.6 may truncate equivalent output. Per-token pricing is $2/$10 per MTok (Sonnet 4.6 is $3/$15), so the cost of an equivalent request differs in both directions: more tokens at a lower rate. Re-run count_tokens() against claude-sonnet-5 rather than reusing counts measured against earlier models, and re-baseline cost dashboards before reacting to measured shifts.

Choosing an effort level on Claude Sonnet 5

effort defaults to high when not set (same as Sonnet 4.6 and Opus 4.8). Claude Sonnet 5 supports the full low/medium/high/xhigh/max range - the first Sonnet-tier model with xhigh. Keep the high default for most work and raise to xhigh for the hardest coding and agentic tasks:

As a rough cross-model mapping when migrating: Claude Sonnet 5 at medium is comparable in intelligence to Sonnet 4.6 at high, and Claude Sonnet 5 at high is comparable to Sonnet 4.6 at max. When benchmarking, match by observed thinking length rather than effort name.

Claude Sonnet 5 respects effort levels strictly, especially at the low end. At low and medium it scopes its work to what was asked rather than going above and beyond - good for latency and cost, but on moderately complex tasks at low there is some risk of under-thinking. If you observe shallow reasoning on complex problems, raise effort to high or xhigh rather than prompting around it. If you must keep effort at low for latency, add targeted guidance:

"This task involves multi-step reasoning. Think carefully through the problem before responding."

Leave max_tokens headroom at xhigh/max. Set a large output token budget (up to the 128k cap, unchanged from Sonnet 4.6) so the model has room for thinking and tool calls. On long tasks, adaptive thinking can use a large share of the budget; if the budget is tight you may see a response that is almost entirely thinking followed by a truncated answer and stop_reason: "max_tokens" - raise max_tokens or drop to medium. Because Claude Sonnet 5 uses the new tokenizer (~30% more tokens for the same text), max_tokens limits tuned for Sonnet 4.6 may truncate equivalent output.

Adaptive vs. disabled thinking

Leave adaptive thinking on. Claude Sonnet 5 calibrates thinking spend to task complexity; the small added latency is usually worth the quality gain. If the caller was running Sonnet 4.6 with thinking off, try adaptive + effort: "low" first rather than thinking: {type: "disabled"}.

The triggering behavior for adaptive thinking is steerable. If the model emits thinking blocks more often than wanted (which can happen with large or complex system prompts), prompt it directly - and measure the effect on quality:

"Thinking adds latency and should only be used when it will meaningfully improve answer quality, typically for problems that require multi-step reasoning. When in doubt, respond directly."

Conversely, if you're running hard workloads at medium and seeing under-thinking, the first lever is to raise effort; if you need finer control, prompt for it directly.

Capability improvements

Coding and agentic tasks. The largest gains over Sonnet 4.6 are in coding and agentic tasks. Claude Sonnet 5 performs well out of the box on existing Sonnet 4.6 prompts.

High-resolution vision. Claude Sonnet 5 is the first Sonnet-tier model with high-resolution image support: maximum 2576 pixels on the long edge (up from 1568px on Sonnet 4.6). High-res images can use up to ~3× more image tokens than on Sonnet 4.6 (4784 vs 1568 tokens per image at the limit) - if the added fidelity isn't needed, downsample before sending to control token costs. No beta header or opt-in required.

Computer use. Supports the computer_20251124 tool version (beta header computer-use-2025-11-24). Capability works across resolutions up to the 2576px / 3.75MP maximum; sending screenshots at 1080p provides a good balance of performance and cost. For particularly cost-sensitive workloads, 720p or 1366×768 are lower-cost options with strong performance. Test to find the ideal settings for the use case; experimenting with effort can also help tune behavior.

Behavioral shifts (prompt-tunable)

None of these break code, but prompts tuned for Sonnet 4.6 may land differently. Claude Sonnet 5 follows instructions closely, so small explicit directives close the gap.

Response length and verbosity. Claude Sonnet 5 calibrates response length to task complexity rather than defaulting to a fixed verbosity - usually shorter on simple lookups, longer on open-ended analysis. If a product depends on a particular verbosity, tune the prompt. To decrease verbosity:

"Provide concise, focused responses. Skip non-essential context, and keep examples minimal."

If you see specific kinds of verbosity (e.g. over-explaining), add targeted instructions to prevent them. Positive examples showing the desired concision tend to be more effective than telling the model what not to do.

Tool use triggering. Claude Sonnet 5 is more agentic than Sonnet 4.6 by default and will reach for tools and run self-verification loops more readily. With thinking disabled, the model is less likely to reach for tools or consider searching - if the harness relies on tool calls with thinking off, add an explicit nudge in the system prompt. effort is also a lever: high and xhigh show substantially more tool usage in agentic search and coding. For scenarios where you want more tool use, also explicitly instruct when and how to use the tools (e.g. if web-search is under-used, describe in the prompt why and how it should be called).

User-facing progress updates. Claude Sonnet 5 provides regular, higher-quality updates to the user throughout long agentic traces by default. If the harness has scaffolding to force interim status messages ("After every 3 tool calls, summarize progress"), try removing it. If the length or content of the updates isn't well-calibrated to the use case, describe what they should look like in the prompt and provide an example.

More literal instruction following. Claude Sonnet 5 interprets prompts literally and explicitly, particularly at lower effort levels. It does not silently generalize an instruction from one item to another, and it does not infer requests that weren't made. The upside is precision - better for carefully tuned prompts, structured extraction, and pipelines that need predictable behavior. If an instruction should apply broadly, state the scope explicitly ("Apply this formatting to every section, not just the first one"). The same literalism means style/tone directives carried over from Sonnet 4.6 may now over-apply - re-baseline holdover lines like "be concise" before keeping them.

Tone and writing style. Prose style on long-form writing may shift. If a product relies on a specific voice, re-evaluate style prompts against the new baseline. For a warmer or more conversational voice:

"Use a warm, collaborative tone. Acknowledge the user's framing before answering."

Because temperature/top_p/top_k are not accepted on Claude Sonnet 5, callers who previously relied on temperature for stylistic variety must use system-prompt instructions instead.

Code review harnesses. A review harness tuned for an earlier model may initially see lower recall on Claude Sonnet 5. This is likely a harness effect, not a capability regression: when a review prompt says "only report high-severity issues" / "be conservative" / "don't nitpick," Claude Sonnet 5 follows that instruction more faithfully than earlier models did - it investigates just as thoroughly, identifies the bugs, and then doesn't report findings it judges below the stated bar. Precision typically rises, but measured recall can fall even though underlying bug-finding ability has improved. Recommended prompt language:

"Report every issue you find, including ones you are uncertain about or consider low-severity. Do not filter for importance or confidence at this stage - a separate verification step will do that. Your goal here is coverage: it is better to surface a finding that later gets filtered out than to silently drop a real bug. For each finding, include your confidence level and an estimated severity so a downstream filter can rank them."

This works even without an actual second step, but moving confidence filtering out of the finding stage often helps. If you do want single-pass self-filtering, be concrete about where the bar is rather than using qualitative terms like "important" - e.g. "report any bugs that could cause incorrect behavior, a test failure, or a misleading result; only omit nits like pure style or naming preferences." Iterate against a subset of evals to validate recall/F1 gains.

Design and frontend defaults. Claude Sonnet 5 may settle into a consistent default visual style on open-ended frontend and design briefs. Generic instructions ("don't use that color," "make it clean and minimal") tend to shift it to a different fixed palette rather than producing variety. Two approaches work reliably: specify a concrete alternative (the model follows explicit specs precisely - give the palette, typography, layout, and spacing), or have the model propose options before building (e.g. "Before building, propose 4 distinct visual directions tailored to this brief - bg hex / accent hex / typeface plus a one-line rationale - ask the user to pick one, then implement only that direction"). Because temperature isn't accepted on Claude Sonnet 5, the propose-then-pick approach is the recommended way to get meaningfully different design directions across runs. To steer away from generic AI-aesthetic patterns, a short directive in the system prompt also helps:

"NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white or dark backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. Use unique fonts, cohesive colors and themes, and animations for effects and micro-interactions."

Interactive coding products. Token usage and behavior can differ between autonomous, asynchronous coding agents (single user turn) and interactive, synchronous coding agents (multiple user turns). To maximize both performance and token efficiency, use effort: "xhigh" or "high", add autonomous features like an auto mode, and reduce the number of human interactions required. Specify task, intent, and constraints upfront in the first turn - well-specified initial prompts maximize autonomy and intelligence while minimizing extra token usage after user turns; ambiguous or progressively-revealed prompts tend to reduce token efficiency and sometimes performance.

Claude Sonnet 5 Migration Checklist

Every item is tagged: [BLOCKS] items cause a 400 error or truncated output if missed; [TUNE] items are quality/cost adjustments - surface them to the user as recommendations.

• [BLOCKS] Update the model= string to claude-sonnet-5
• [BLOCKS] Replace thinking: {type: "enabled", budget_tokens: N} with thinking: {type: "adaptive"} + output_config.effort - the Sonnet 4.6 transitional escape hatch is gone
• [BLOCKS] Strip temperature, top_p, top_k from request construction (use system-prompt instructions for tone/variety instead)
• [BLOCKS] Bedrock only: pass thinking: {type: "disabled"} alongside forced tool_choice ({type: "tool"} / {type: "any"}) - not required on the Claude API or Vertex AI
• [BLOCKS] At effort: "xhigh" or "max": set a large max_tokens (up to 128k, unchanged from Sonnet 4.6) so the model has room for thinking and tool calls - Sonnet-4.6-tuned limits may truncate equivalent output under the new tokenizer (symptom: stop_reason: "max_tokens")
• [TUNE] Thinking-field omitted: adaptive is now the default (4.6 ran thinking-off) - either set thinking: {type: "disabled"} to preserve the old behavior, or revisit max_tokens for the added thinking spend
• [TUNE] thinking.display defaults to "omitted" (4.6 defaulted to "summarized"): if you stream reasoning to users, set thinking: {type: "adaptive", display: "summarized"} explicitly - the default streams empty-text thinking blocks (long pause before output)
• [TUNE] New tokenizer: re-run count_tokens() against claude-sonnet-5 (~30% more tokens for the same text); revisit max_tokens and compaction triggers sized close to expected output length; re-baseline cost dashboards before reacting (per-token pricing is lower than Sonnet 4.6: $2/$10 vs $3/$15 per MTok)
• [TUNE] Effort: keep the high default; raise to xhigh for the hardest coding/agentic tasks; medium is a cost-saving step-down (~ Sonnet 4.6 at high); reserve low for short, latency-sensitive, non-intelligence-sensitive tasks. If shallow reasoning shows up at low/medium, raise effort rather than prompting around it
• [TUNE] Thinking-off callers: try thinking: {type: "adaptive"} + effort: "low" instead of disabled; if disabled must stay, add an explicit tool-triggering nudge (the model is less tool-eager with thinking off)
• [TUNE] Tool usage: more agentic than 4.6 by default (reaches for tools and self-verification more readily) - effort is a lever (high/xhigh for more tool use); add explicit when/how triggering instructions for under-used tools
• [TUNE] Drop forced progress-update scaffolding ("after every N tool calls, summarize") - the default updates are higher quality; describe the desired update shape if it still needs tuning
• [TUNE] Re-baseline holdover style/tone/scope directives - instructions are followed literally; state the scope explicitly when one should apply broadly
• [TUNE] Verbosity-sensitive routes: tune response length via prompt (positive examples > "don't" instructions)
• [TUNE] Code-review harnesses with conservative-reporting instructions ("only high-severity", "don't nitpick"): switch to a coverage-first prompt (report everything with confidence + severity) and filter downstream - measured recall can otherwise fall even though bug-finding improved
• [TUNE] Open-ended frontend/design briefs: specify a concrete spec, or have the model propose 3-4 visual directions and pick one (the recommended substitute for temperature-driven variety)
• [TUNE] Interactive coding products: use effort: "xhigh"/"high", add autonomous features (e.g. auto mode), and put task/intent/constraints in the first turn
• [TUNE] Vision-heavy / computer-use pipelines: leave images at native resolution up to 2576px long edge for the accuracy gain (downsample to control image-token cost if fidelity isn't needed); for computer use, 1080p screenshots are a good performance/cost balance with computer_20251124
• [TUNE] Security workloads: add handling for safeguard refusals (cyber-capable topics may now be declined where Sonnet 4.6 answered)

Migrating to Claude Fable 5.1

Model IDs claude-fable-5-1 and claude-mythos-5-1 are authoritative as written here. When the user asks to migrate to Claude Fable 5.1, write model="claude-fable-5-1" exactly; a Mythos Preview migrator in Project Glasswing writes model="claude-mythos-5-1" (everyone else: claude-fable-5-1). Do not WebFetch to verify - this guide is the source of truth for migration target IDs. The corresponding entries exist in shared/models.md.

Claude Fable 5.1 is Anthropic's most capable widely released model - for the most demanding reasoning and long-horizon agentic work. Claude Mythos 5.1 (claude-mythos-5-1) offers the same capabilities and pricing through Project Glasswing (participation is the only way to access it), and succeeds the invitation-only Claude Mythos Preview (claude-mythos-preview). Everything in this section applies to both models except where § Claude Mythos 5.1 below says otherwise (the history-editing check, platform availability, and safeguards that depend on the access program). Mythos Preview migrators in Project Glasswing target claude-mythos-5-1; everyone else targets claude-fable-5-1. 1M token context window by default (the maximum is also the default), up to 128K output tokens per request.

Migrate to Claude Fable 5.1 only when the user explicitly chose it. It is not the default Opus upgrade path - pricing is above Opus-tier. For "upgrade to the latest model" requests, the target is claude-opus-5-5.

Breaking changes (vs Opus-tier and Mythos Preview)

Claude Fable 5.1 carries three further breaking changes introduced after Claude Fable 5: forced tool_choice (any / tool) returns a 400, thinking blocks are bound to the producing model, and editing earlier turns invalidates thinking blocks. They are covered in § Migrating to Claude Fable 5.1 from Claude Fable 5 below - apply that section on top of this one when coming from Opus-tier or older.

1. Thinking is always on - remove all thinking configuration. Adaptive thinking applies automatically whenever the thinking parameter is unset (an explicit {type: "adaptive"} is also accepted). Any other configuration is rejected: thinking: {type: "disabled"} and {type: "enabled", budget_tokens: N} both return a 400. budget_tokens has no replacement - the output_config.effort parameter is a separate output-level control, not a thinking budget.

   # Before (Mythos Preview / older models)
   client.messages.create(
       model="claude-mythos-preview",
       max_tokens=16000,
       thinking={"type": "enabled", "budget_tokens": 10000},
       messages=[...],
   )
   
   # After (Claude Fable 5.1) - no thinking field at all
   client.messages.create(
       model="claude-fable-5-1",
       max_tokens=16000,
       output_config={"effort": "high"},
       messages=[...],
   )

2. Assistant prefill is not supported. Replace last-assistant-turn prefills with structured outputs (output_config.format) or system prompt instructions - same replacement patterns as the 4.6-family prefill removal above. (One exception: the fallback-credit prefill claim - the server accepts the echoed assistant message when redeeming a credit; see the refusal section below.)

3. Interleaved scratchpad is not supported (Mythos Preview migrators only). Inter-tool reasoning is returned in thinking blocks instead, which adaptive thinking produces automatically between tool calls.

Thinking output on Claude Fable 5.1 and Claude Mythos 5.1

On Claude Fable 5.1 and Claude Mythos 5.1, the raw chain of thought is never returned. What you receive are regular thinking blocks, not encrypted blobs or redacted_thinking: display: "summarized" returns a readable summary of the reasoning, and with "omitted" - the default, same as Opus 4.8/4.7 - responses still include thinking blocks but the thinking field is an empty string. display controls visibility only; thinking happens and is billed the same under every setting. When continuing a conversation on the same model, pass thinking blocks back to the API unchanged (the standard multi-turn pattern; dropping or editing them breaks the turn).

When continuing on the same model, pass each thinking block back exactly as received - including blocks whose thinking text is empty. The API rejects blocks whose content has been modified, not blocks you have read; displaying the summary is fine, editing or reconstructing blocks is not.

Regular thinking blocks aren't origin-locked - they replay across models fine (the server renders them into the target model's prompt). Fable-tier thinking is the exception: a Claude Fable 5.1 / Claude Mythos 5.1 block is read only by that pair (apart from Claude Mythos 5.1, no other model can read a Claude Fable 5.1 block - see Migrating to Claude Fable 5.1 from Claude Fable 5), and a thinking block from Claude Fable 5/Claude Mythos 5 replayed to a different model is dropped from the prompt rather than rendered (except by Claude Fable 5.1 / Claude Mythos 5.1, which read these blocks) - typically silently (this behavior is still rolling out, so don't build logic that depends on the drop being silent). The drop happens before the prompt is priced, so a dropped block lowers usage.input_tokens - you aren't billed for it, and there's nothing to strip for cost. Don't strip regular thinking blocks either: removing them can trigger ordering/signature 400s. Two rules for replay bodies stand regardless: fallback-credit retries must echo the refused body unchanged, and fallback blocks from a mid-output fallback stay where they appeared.

Related: a request that tries to elicit the model's internal reasoning in the response text can be refused with stop_details.category: "reasoning_extraction" - applications needing reasoning visibility should read the summarized thinking blocks instead of prompting for reasoning.

Tokenizer - unchanged from Opus 4.8

Claude Fable 5.1 uses the same tokenizer as Claude Opus 4.8 (the tokenizer introduced with Opus 4.7). Token counts are roughly unchanged when migrating from Opus 4.7/4.8 or from claude-mythos-preview; per-token pricing differs.

• Coming from Opus 4.7/4.8 or claude-mythos-preview: token counts are roughly unchanged. Re-baseline cost and latency on your own workloads for the per-token price difference.
• Coming from Opus 4.6, Sonnet, Haiku, or older: the Opus 4.7 tokenizer tokenizes the same content to roughly 1×-1.35× as many tokens (varies by content and workload shape). Do not reuse token counts, context-window budgets, or max_tokens settings measured on the old model; re-baseline with count_tokens.

To measure the difference on your own prompts, call count_tokens once with your current model and once with model: "claude-fable-5-1", and compare the two input_tokens values.

refusal stop reason - handle before reading content

Claude Fable 5.1 runs safety classifiers on incoming requests, targeting research biology and most cybersecurity content (Claude Fable 5.1 is not intended for those domains); benign adjacent work - security tooling, life-sciences tasks - can occasionally trigger false positives, which is why the fallback patterns below matter even for legitimate workloads. (Most Claude consumer surfaces ship with built-in Opus 4.8 fallbacks; API callers configure their own.) A declined request returns a successful HTTP 200 with stop_reason: "refusal", plus a stop_details object with the policy category (values such as "cyber", "bio", "reasoning_extraction", "frontier_llm", or null - treat null as a permanent valid state; see the refusal category table in the public docs for the full set). Branch on stop_reason, never on stop_details - stop_details is informational and can be null even on a refusal, and explanation is not guaranteed present. Note that classifier blocks and ordinary model refusals (the model itself declining) both surface as stop_reason: "refusal"; stop_details.category tells you which class you're handling, and therefore whether retrying on a fallback model is the right response. The classifier can fire before any output (empty content array; counts against rate limits - for billing, see How refusals are billed) or mid-stream after partial output (input and already-streamed output are billed at normal rates - discard the partial output rather than treating it as complete). Code that reads response.content[0] unconditionally will break - check stop_reason first:

response = client.messages.create(model="claude-fable-5-1", max_tokens=1024, messages=[...])
if response.stop_reason == "refusal":
    # classifiers declined; content is empty (pre-output) or partial (mid-stream)
    handle_refusal()
else:
    print(response.content[0].text)

Default to opting in. Fallbacks are not automatic on the API - a request without them simply stops on a refusal. Migrated and new Claude Fable 5.1 code should ship with pattern 1 below (pattern 2 on providers without server-side support) from day one, not as a later hardening step: emit the opt-in in the code, tell the user it's there, and remove it only if they decline.

Three ways to retry a refused request on another model, in order of preference:

1. Server-side fallbacks parameter (beta; Claude API and Claude Platform on AWS) - preferred. One round trip, a plain client, no client-side logic. Name substitute models (the supported fallback targets are claude-opus-4-8 and claude-opus-5, expansion expected); on a policy decline the API runs the next model on the same request and returns its answer, with credit-style repricing applied automatically. A stop_reason: "refusal" on the final response means the whole chain refused.

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=1024,
    betas=["server-side-fallback-2026-06-01"],
    fallbacks=[{"model": "claude-opus-4-8"}],
    messages=[{"role": "user", "content": "Hello, Claude"}],
)

# Switch points: one fallback block per model that ran and declined this turn
for block in response.content:
    if block.type == "fallback":
        print(f"{block.from_.model} declined; {block.to.model} continued")

# Served-by signal: a fallback_message in usage.iterations means a fallback model
# ran; pair it with stop_reason to confirm the fallback served the response
# (a fallback model can also refuse). Covers sticky turns too.
fallback_ran = any(
    entry.type == "fallback_message" for entry in response.usage.iterations or []
)
if fallback_ran and response.stop_reason != "refusal":
    print(f"Served by {response.model}")

Key semantics:

• Header depends on the form you use. The array form (fallbacks: [{...}]) requires exactly server-side-fallback-2026-06-01 - other server-side-fallback-* values reject it with a 400, and that header carries the earliest date of the series (-2026-06-09 and -2026-06-02 were earlier previews), so do not "correct" it to a newer-looking date. The "default" scalar form uses server-side-fallback-2026-07-01 instead - see § New API features under Migrating to Claude Opus 5. Pairing either header with the other form 400s. Rejected on the Batches API; available on the Claude API and Claude Platform on AWS; not on Amazon Bedrock, Vertex AI, or Microsoft Foundry (use pattern 2 there - the SDK middleware). Entries may override max_tokens per hop (bounding that attempt's own output independently of the top-level max_tokens); thinking, output_config, and speed overrides are rolling out (speed additionally requires its beta) - until your requests accept them, include only model and max_tokens in each entry. Entries must be distinct and must be in the requested model's allowed_fallback_models (published on /v1/models when the server-side-fallback-2026-06-01 beta header is set - not yet visible under the fallback-credit-* header alone, and not exposed on Amazon Bedrock, Vertex AI, or Microsoft Foundry). The request with an entry's overrides merged in must be valid as a direct request to that entry's model.
• Triggers on policy declines only - rate limits, overloads, and server errors on the requested model are returned as-is, never falling back.
• Reading the response: a fallback content block ({"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}) marks each switch point in content; the served-by signal is a fallback_message entry in usage.iterations (don't rely on the block - sticky-served turns have none). Top-level model names the model that produced the message.
• Billing: usage.iterations is the per-attempt source of truth; top-level usage covers only the attempt that produced the returned message. Declined-before-output attempts are reported (for whether they're billed, see How refusals are billed); an attempt that declines mid-stream bills at normal rates, and fallback attempts bill at the fallback model's rates. Each attempt claims the rate limits of the model that ran it - if the fallback model is rate-limited or overloaded, the fallback attempt is not made and the preceding refusal is returned instead with stop_details.recommended_model naming a model to retry directly (the recommendation is a hint, not a guarantee, and is null when no recommendation is available) - size fallback-model limits for expected refusal volume.
• Sticky routing: once a conversation falls back, later requests with fallbacks (streaming and non-streaming - on a stream the decision is made before it opens, so message_start already names the fallback model) are served directly by the fallback model for ~1 hour (best-effort; org-scoped content-hash record, not message content; not recorded for ZDR orgs). Handle the requested model being tried again at any time.
• Echoing fallback turns back: after a mid-output fallback, omit thinking, redacted_thinking, and tool_use blocks - plus any server_tool_use block without its matching server_tool_result, and any other unrecognized model-internal block type - that appear before the final fallback block; text blocks, paired server-tool blocks, and everything after the boundary echo normally. The fallback block itself is an ignored audit marker (keep or drop). Streaming: the retry happens on the same stream and already-received content is never invalidated - a pre-output block is seamless (message_start names the fallback model; the fallback block arrives as an ordinary content_block_start, first in content - there is no special SSE event type; note message_start arrives only after the declined attempt, so time-to-first-byte includes it), and a mid-stream block keeps the partial, marks the boundary with the block, and continues - only the partial's text blocks are passed to the fallback model as continuation context (other block types stay in content but aren't part of it). Non-streaming mid-output declines omit the declined partial entirely.

2. SDK client-side middleware - for providers without server-side fallbacks (Amazon Bedrock, Vertex AI, Microsoft Foundry). Register it on the client and every client.beta.messages request (streaming included) retries refusals automatically, splicing the fallback model's events onto the open stream in the same wire shape as pattern 1 (a fallback content block at each boundary, per-hop usage.iterations). It is also a beta surface: the middleware sends the fallback-credit-2026-07-01 header by default (the earlier -2026-06-01 value is still accepted) so retries are repriced via credit tokens (override with its betas option). BetaFallbackState pins follow-up turns to the model that accepted (the client-side analog of sticky routing) - reuse one state object per conversation:

from anthropic import Anthropic, BetaFallbackState, BetaRefusalFallbackMiddleware

client = Anthropic(middleware=[BetaRefusalFallbackMiddleware([{"model": "claude-opus-4-8"}])])
state = BetaFallbackState()  # pins follow-ups to the model that accepted
with state:
    response = client.beta.messages.create(model="claude-fable-5-1", max_tokens=1024, messages=messages)

Create one state per conversation - it is the pinning scope; sharing one across conversations pins unrelated threads together, and a conversation without a state is never pinned. Per-language naming (from the GA SDK examples - don't improvise):

• TypeScript: betaRefusalFallbackMiddleware([...]) in the client's middleware array; pass { fallbackState: state } (a BetaFallbackState) as a request option.
• Go: option.WithMiddleware(betafallback.BetaRefusalFallbackMiddleware([]anthropic.BetaFallbackParam{{Model: ...}})) (package lib/betafallback); state via betafallback.WithBetaFallbackState(&betafallback.BetaFallbackState{}) passed as a request option. Server-side equivalents: Fallbacks: []anthropic.BetaFallbackParam{...} + anthropic.AnthropicBetaServerSideFallback2026_06_01.
• C#: it's a handler - new AnthropicClient { Handlers = [new BetaRefusalFallbackHandler { Fallbacks = [new(Model.ClaudeOpus4_8)] }] } (namespace Anthropic.Helpers); state via BetaFallbackState.Create() scoped per call with using (fallbackState.Use()) { ... }. Server-side equivalents: Fallbacks = [new(Model.ClaudeOpus4_8)] + AnthropicBeta.ServerSideFallback2026_06_01.

For languages not listed (Java, Ruby, PHP) - or for a full runnable program in any language - each public SDK repo ships a fallbacks example under examples/ (e.g. examples/fallbacks.py, examples/refusal-fallback/): WebFetch the repo from shared/live-sources.md § SDK Repositories rather than improvising the binding.

3. Hand-rolled retry + fallback credit (raw HTTP, or SDKs without the middleware). Detect the refusal via stop_reason and re-send the conversation as-is on a model with broader availability such as claude-opus-4-8 (no stripping required either way: Claude Fable 5's thinking blocks are silently ignored by models other than Claude Fable 5.1 / Claude Mythos 5.1, which read them, and Claude Fable 5.1's own blocks are dropped by the API for any other model - breaking change 2 in § Migrating to Claude Fable 5.1 from Claude Fable 5); keep using the fallback model for subsequent turns. Fallback credit (beta: Claude API, Claude Platform on AWS, Amazon Bedrock, Vertex AI, and Microsoft Foundry) makes those retries cheaper. Prompt caches are per-model, so a plain retry pays cold cache-writes on the new model. With the fallback-credit-2026-07-01 beta header (send it on both the original request and the retry; -2026-06-01 is still accepted, and server-side-fallback-2026-07-01 grants the same fields), a refusal's stop_details carries fallback_credit_token (opaque; null when unavailable) and fallback_has_prefill_claim. Echo the token as the top-level fallback_credit_token request parameter on the retry (typed in the GA SDKs; on a pre-GA SDK pass it via extra_body) and the previously-cached span bills at cache-read rates - the retry costs what it would have if the conversation had been on that model all along. Rules: the retry body must match the refused request exactly in every prompt-shaping field (system, messages, tools, tool_choice, thinking - do not strip thinking blocks when redeeming a credit - the server handles them); the retry model must be in the refused model's allowed_fallback_models; the token expires in 5 minutes; Batches results carry no tokens. If fallback_has_prefill_claim is true, append one assistant message echoing the refused response's content - the retry model continues from where the refused model stopped (and completed server-tool work isn't re-run). When echoing, strip trailing whitespace from a final text block (the prefill validator rejects it; the credit match tolerates that edit), after omitting any unpaired tool_use blocks. On a 400, fall back to the unchanged body with the token; on a 400 naming fallback_credit_token, retry without it (credit forfeited).

Migrating code built on the v1 preview. If the code you're editing carries any of these markers, it targets the discontinued preview surface - migrate it to the v2 shapes above, and ship the header and parameter changes together (the v1 parameter shape under the v2 header is a 400):

Data retention requirement

Claude Fable 5.1 requires 30-day data retention and is not available under zero data retention. Requests from an organization whose data-retention configuration doesn't meet the requirement return 400 invalid_request_error - if a migration suddenly 400s with no obvious request problem, check the org's retention configuration before debugging the payload. On Amazon Bedrock, Google Vertex AI, and Microsoft Foundry, data-retention requirements are set by each platform.

What carries over unchanged

Same Messages API and tool-use patterns as Opus-tier and Mythos Preview. Supported at launch: output_config.effort (low/medium/high/xhigh/max), Task Budgets (beta, task-budgets-2026-03-13 header - on Claude Fable 5.1 confirm at launch), compaction (beta, compact-2026-01-12 header), the memory tool, tool-call clearing via context editing, and high-resolution vision (no downscaling cap, as on Opus 4.7+).

Behavioral shifts (prompt-tunable)

None of these are API-breaking, but they're where migrated workloads feel different. Claude Fable 5.1's biggest gains are on work above what prior models could do (long-horizon autonomous runs, first-shot implementations of well-specified systems, end-to-end enterprise deliverables - financial analysis, spreadsheets, slides, docs - code review/debugging and repository-history search, vision on dense or degraded images - it's explicitly trained to use bash and crop tools on flipped/blurry/noisy inputs - navigating ambiguity, parallel sub-agent delegation and collaboration - it reliably sustains ongoing communications with long-running sub-agents and peer agents; note bug-finding gains exclude security-focused analysis, where the cyber classifiers apply) - don't evaluate it only on workloads older models already handled.

Longer turns by default - the biggest structural shift. Individual requests on hard tasks can run many minutes at higher effort (a 15-minute single request is normal when the task involves gathering context, building, and self-verifying). Before migrating, plan timeouts, streaming, and user-facing progress indicators; structure work so callers check in on runs asynchronously rather than blocking inside one request. On ambiguous tasks Claude Fable 5.1 may need a small nudge to avoid overplanning:

When you have enough information to act, act. Do not re-derive facts already established in the conversation, re-litigate a decision the user has already made, or narrate options you will not pursue in user-facing messages. If you are weighing a choice, give a recommendation, not an exhaustive survey. This does not apply to thinking blocks.

Consider all effort levels. output_config.effort is the primary intelligence/latency/cost control. Recommended defaults: high for most tasks, xhigh for the most capability-sensitive workloads, medium/low for routine work. Lower effort settings - including low - still perform very well on Claude Fable 5.1, often exceeding the xhigh or even max performance of previous models. Reduce effort if a task completes correctly but takes longer than necessary, or for a quicker interactive working style. At higher effort on routine work, Claude Fable 5.1 can gather context and deliberate beyond what the task needs (the flip side: higher effort buys excellent verification behavior and the most rigorous outputs). To prevent unrequested tidying or refactoring at higher effort:

Don't add features, refactor, or introduce abstractions beyond what the task requires. A bug fix doesn't need surrounding cleanup and a one-shot operation usually doesn't need a helper. Don't design for hypothetical future requirements - do the simplest thing that works well. Avoid premature abstraction. Avoid half-finished implementations either. Don't add error handling, fallbacks, or validation for scenarios that cannot happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use feature flags or backwards-compatibility shims when you can just change the code.

Instruction following is strong - use it. Claude Fable 5.1 is very responsive to explicit communication-style sections in system prompts; invest in them rather than fighting output style downstream. Un-steered - especially at higher effort - it can elaborate beyond what the task needs: heavily-structured PR descriptions, sections on alternatives that weren't chosen, comments narrating what the next line does. You don't need to enumerate these behaviors by name; a brief instruction is just as effective:

Lead with the outcome. Your first sentence after finishing should answer "what happened" or "what did you find" - the thing the user would ask for if they said "just give me the TLDR." Supporting detail and reasoning come after. Being readable and being concise are different things, and readability matters more. The way to keep output short is to be selective about what you include (drop details that don't change what the reader would do next), not to compress the writing into fragments, abbreviations, arrow chains like A -> B -> fails, or jargon.

Ground progress claims on long runs. Require progress claims to be audited against tool results - in testing this nearly eliminated fabricated status reports on tasks designed to elicit them:

Before reporting progress, audit each claim against a tool result from this session. Only report work you can point to evidence for; if something is not yet verified, say so explicitly. Report outcomes faithfully: if tests fail, say so with the output; if a step was skipped, say that; when something is done and verified, state it plainly without hedging.

State boundaries explicitly. Claude Fable 5.1 sometimes takes unrequested-but-adjacent actions (e.g. composing an email straight to drafts, creating backup git branches). Define what it should not do:

When the user is describing a problem, asking a question, or thinking out loud rather than requesting a change, the deliverable is your assessment. Report your findings and stop. Don't apply a fix until they ask for one. Before running a command that changes system state - restarts, deletes, config edits - check that the evidence actually supports that specific action. A signal that pattern-matches to a known failure may have a different cause.

Let it delegate - asynchronously. Parallel sub-agents are dependable on Claude Fable 5.1 - instead of suppressing delegation (a common prior-model guardrail), use sub-agents frequently and give explicit guidance on when delegation is desirable. Sub-agents that communicate asynchronously with the orchestrator outperform spawn-and-block: long-lived agents keep their context instead of re-establishing it per subtask (cache-read savings), the orchestrator isn't bottlenecked on the slowest sub-agent, and context persists across subtasks.

Delegate independent subtasks to sub-agents and keep working while they run. Intervene if a sub-agent goes off track or is missing relevant context.

Give it a memory surface. Claude Fable 5.1 performs notably better when it can write learnings somewhere for future reference - even a plain .md file. Tell it where, tell it to consult that file in future sessions, and give it a format:

Store one lesson per file with a one-line summary at the top. Record corrections and confirmed approaches alike, including why they mattered. Don't save what the repo or chat history already records; update an existing note rather than creating a duplicate; delete notes that turn out to be wrong.

Rare: early stopping. Deep into long sessions it can occasionally end a turn with a text-only statement of intent ("I'll now run X") without the tool call, or ask permission it doesn't need. A "continue" recovers it interactively; for autonomous pipelines add a system reminder:

You are operating autonomously. The user is not watching in real time and cannot answer questions mid-task, so asking 'Want me to...?' or 'Shall I...?' will block the work. For reversible actions that follow from the original request, proceed without asking. Offering follow-ups after the task is done is fine; asking permission after already discussing with the user before doing the work is not. Before ending your turn, check your last paragraph. If it is a plan, an analysis, a question, a list of next steps, or a promise about work you have not done ('I'll...', 'let me know when...'), do that work now with tool calls. End your turn only when the task is complete or you are blocked on input only the user can provide.

Rare: context anxiety. In very long sessions it can worry about running out of context - suggesting a new session or trimming its own work - most often when the harness surfaces a remaining-token countdown. Avoid showing explicit context-budget counts; if you must:

You have ample context remaining. Do not stop, summarize, or suggest a new session on account of context limits - continue the work.

Give the reason, not just the request. Claude Fable 5.1 performs better when it understands the intent behind a request - it connects the task to relevant information rather than inferring intent on its own. This matters most for long-running agents juggling context from disparate workstreams:

I'm working on [the larger task] for [who it's for]. They need [what the output enables]. With that in mind: [request].

Readability in long agentic sessions. Deep into extended conversations (many tool calls, large working context) Claude Fable 5.1 can produce text users find hard to follow - dense arrow-chain shorthand, implementation-level detail, references to thinking the user never saw. A communication-style addendum strongly mitigates this; adapt:

Terse shorthand is fine between tool calls (that's you thinking out loud, and brevity there is good). Your final summary is different: it's for a reader who didn't see any of that. If you've been working for a while without the user watching - overnight, across many tool calls, since they last spoke - your final message is their first look at any of it. Write it as a re-grounding, not a continuation of your working thread: the outcome first, then the one or two things you need from them, each explained as if new. The vocabulary you built up while working is yours, not theirs; leave it behind unless you re-introduce it. When you write the summary at the end, drop the working shorthand. Write complete sentences. Spell out terms instead of abbreviating them. Don't use arrow chains, hyphen-stacked compounds, or labels you made up earlier - the reader doesn't have the context to decode them. When you mention files, commits, flags, or other identifiers, give each one its own plain-language clause saying what it is or what changed - never pack several into one parenthesized run or slash-separated list. Open with the outcome: one sentence on what happened or what you found. Then the supporting detail. If you have to choose between short and clear, choose clear.

Long-running agent recommendations

• Make self-verification explicit. For long-running builds, instruct it to establish and run its own checking harness on a cadence ("Establish a method for checking your own work as you build; run it every [interval], verifying against the specification with sub-agents"). Separate fresh-context verifier sub-agents tend to outperform self-critique.
• De-prescribe migrated prompts and skills. Prompts and skills written for prior models are often too prescriptive for Claude Fable 5.1 and reduce output quality. After migrating, A/B the workload with older step-by-step scaffolding removed - prefer stating the goal and constraints over enumerating the steps. Claude Fable 5.1 is also good at updating skills on the fly from what it learns mid-task - let it.
• Start at the top of your difficulty range. The teams with the best outcomes gave it their hardest unsolved problems first - have it scope the problem, ask questions, then execute.
• Add a send_to_user tool for verbatim mid-task delivery. When an asynchronous agent must deliver something the user sees exactly as written mid-run (a deliverable, a progress update with specific numbers, a direct answer), give it a client-side tool whose input you render directly in the UI - tool inputs are never summarized, so content arrives intact. Return a simple acknowledgement as the tool result:

{
  "name": "send_to_user",
  "description": "Display a message directly to the user. Use this for progress updates, partial results, or content the user must see exactly as written before the task finishes.",
  "input_schema": {
    "type": "object",
    "properties": {
      "message": { "type": "string", "description": "The content to display to the user." }
    },
    "required": ["message"]
  }
}

For agents that only narrate routine progress, the model's default progress narration is typically adequate without this tool.

Claude Fable 5.1 Migration Checklist

• [BLOCKS] Also apply the Claude Fable 5.1 from Claude Fable 5 Migration Checklist below - it carries the three breaking changes introduced after Claude Fable 5 (forced tool_choice 400s, model-bound thinking blocks, the history-editing check), which this checklist predates
• [BLOCKS] Update the model= string to claude-fable-5-1 (claude-mythos-5-1 for Mythos Preview migrators in Project Glasswing)
• [BLOCKS] Remove thinking: {type: "disabled"} (errors on Claude Fable 5.1)
• [BLOCKS] Replace assistant prefill with structured outputs or system prompt instructions
• [BLOCKS] Confirm the org meets the 30-day data-retention requirement (ZDR orgs get 400 invalid_request_error on every request; ZDR only if expressly authorized by Anthropic, or enable 30-day retention for one workspace)
• [BLOCKS] Remove all other thinking configuration ({type: "enabled", budget_tokens: N} returns a 400, same as on Opus 4.7/4.8); control depth with output_config.effort instead
• [BLOCKS] If thinking content is surfaced to users or stored in logs: add thinking: {type: "adaptive", display: "summarized"} (the default is "omitted" - otherwise the rendered text is empty)
• [TUNE] Re-baseline cost and latency on your own workloads - token counts are roughly unchanged from Opus 4.7/4.8 and Mythos Preview (same tokenizer); per-token pricing differs. Coming from Opus 4.6, Sonnet, Haiku, or older, token counts differ - use count_tokens with each model to compare
• [TUNE] Add stop_reason == "refusal" handling before reading response.content (pre-output: empty, billing per How refusals are billed; mid-stream: billed at normal rates - discard the partial); opt into a fallback by default - server-side fallbacks (Claude API and Claude Platform on AWS: fallbacks: "default" with server-side-fallback-2026-07-01, or the array form with server-side-fallback-2026-06-01) where available, otherwise the SDK middleware or fallback credit (fallback-credit-2026-07-01, exact body); a bare client-side replay (history as-is; models other than Claude Fable 5.1 / Claude Mythos 5.1 drop Fable's thinking blocks) is the floor, not the recommendation
• [TUNE] If you surfaced thinking text to users, plan for the thinking output change - the raw chain of thought is never returned; render the display: "summarized" summary (per the [BLOCKS] item above); pass blocks back unchanged on the same model; other models drop them from the prompt (unbilled; Claude Mythos 5.1 instead reads them)
• [TUNE] Plan for minutes-long turns: timeouts, streaming, async check-ins, progress UX (see Behavior changes above)
• [TUNE] Run an effort sweep including low/medium for routine workloads; add the no-tidying instruction if higher effort produces unrequested refactors
• [TUNE] A/B with prior-model scaffolding removed - over-prescriptive prompts/skills reduce Claude Fable 5.1 output quality

Migrating to Claude Fable 5.1 from Claude Fable 5

Model IDs claude-fable-5-1 and claude-mythos-5-1 are authoritative as written here. When the user asks to migrate to Claude Fable 5.1, write model="claude-fable-5-1" exactly; a Project Glasswing participant migrating from Claude Mythos 5 writes model="claude-mythos-5-1". Do not WebFetch to verify - this guide is the source of truth for migration target IDs. The corresponding entries exist in shared/models.md.

Claude Fable 5.1 succeeds Claude Fable 5 in the same tier at the same per-token price, with stronger long-running agentic coding, multistep research, and document / spreadsheet / slide work. Claude Mythos 5.1 (claude-mythos-5-1) is the same model for Project Glasswing participants (see § Claude Mythos 5.1 below for how it differs). Same 1M token context window (default and maximum), same 128K max output, same tokenizer as Claude Fable 5 (token counts unchanged; coming from a pre-Opus-4.7 model, expect roughly 30% more tokens - follow the tokenizer guidance in § Migrating to Claude Fable 5.1 above). Available on the Claude API, Amazon Bedrock (anthropic.claude-fable-5-1), Claude Platform on AWS, Google Cloud, and Microsoft Foundry (Anthropic-hosted). Existing Claude Fable 5 prompts should perform well out of the box.

Migrate to Claude Fable 5.1 only when the user explicitly chose it - same rule as Claude Fable 5: it is not the default Opus upgrade path. For "upgrade to the latest model" requests, the target is claude-opus-5-5: the docs position Claude Opus 5.5 as the default for most work, including complex agentic coding, and Claude Fable 5.1 as the step up for the hardest long-running agentic and research tasks, or where evals on Claude Opus 5.5 at higher effort still fall short.

What changes, in one line: three breaking changes (forced tool choice 400s; thinking blocks are preserved only for the model that produced them or a newer one; thinking blocks are preserved only in the conversation that produced them - the docs group the last two as "preserved thinking"), five additions (per-message effort, turn-scoped system messages, progress updates between tool calls, a lower cache-read price, content provenance), and agent-loop behavior that differs in three prompt-tunable ways. Read the path that matches the source model: from Claude Fable 5, everything below applies directly; from Claude Opus 5, also read § Coming from Claude Opus 5; from Opus 4.8 or earlier, apply § Migrating to Claude Fable 5.1 above first (Opus 4.7 or earlier: the Claude Opus 5 section before that), then this one.

Breaking change 1: forced tool use is rejected

tool_choice: {"type": "any"} and tool_choice: {"type": "tool", "name": "..."} return a 400 invalid_request_error on Claude Fable 5.1 and Claude Mythos 5.1 - on the Messages API, the Message Batches API, and the token-counting endpoint:

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

This is a model-specific restriction, not a consequence of always-on thinking (Claude Fable 5 and Claude Opus 5 also think by default and still accept forced tool choice). {"type": "auto"} (the default) and {"type": "none"} are unchanged. disable_parallel_tool_use: true still works with auto but now means at most one call - the "exactly one tool" guarantee it gave in combination with any/tool is gone.

Migrate by intent:

• Steering toward a tool: keep tool_choice: {"type": "auto"} (or omit it) and state in the prompt when the tool applies ("Use the get_weather tool to answer"). Claude Fable 5.1 follows explicit tool instructions reliably, and thinking first improves the arguments it passes. If the application (not the user) requires a specific call on the current turn of a multi-turn conversation, append a role: "system" message after the latest user turn that names the tool, says the call is required for this turn, and tells Claude to open its response with it - and keep that message in the history on later requests.
• Guaranteeing schema-valid arguments: the argument-validity guarantee any gave you comes back with strict tool use - strict: true on the tool definition (with additionalProperties: false in the schema) under auto. (In a CMEK organization, structured outputs including strict: true aren't available on Fable models - rely on the instruction alone.)
• Extracting structured data: if the forced call existed only to get JSON back, replace it with structured outputs (output_config.format) - see the prefill-replacement table under Breaking Changes by Source Model for the messages.parse() / output_config.format shapes.
• Advisor tool: a Claude Fable 5.1 or Claude Mythos 5.1 executor rejects forced tool_choice too, so nudge the advisor call from the prompt instead (see shared/tool-use-concepts.md § Advisor).

# Before - 400 on Claude Fable 5.1
response = client.messages.create(
    model="claude-fable-5",
    max_tokens=4096,
    tools=[get_weather_tool],
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "Check Tokyo, then summarize."}],
)

# After - let it think, name the tool, keep the schema guarantee with strict tool use
get_weather_tool["strict"] = True   # schema must set additionalProperties: false
response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=4096,
    tools=[get_weather_tool],
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "Use the get_weather tool to check Tokyo, then summarize."}],
)

Breaking change 2: thinking blocks are preserved only for the model that produced them, or a newer one

Every thinking block records which model produced it. Claude Fable 5.1 and Claude Mythos 5.1 read each other's blocks and those from Claude Opus 5.5, Claude Opus 5, Claude Fable 5, Claude Mythos 5, and earlier models that don't encrypt their reasoning in the signature (Opus 4.8 and earlier Opus, Sonnet, Haiku 4.5) - so a conversation that moves onto claude-fable-5-1 keeps its earlier reasoning. They don't read Mythos Preview's blocks. The binding is one-way: apart from Claude Mythos 5.1, no other model can read a Claude Fable 5.1 block.

When a request carries a block the receiving model can't read - a router switch, a client-side retry on another model, a classifier refusal fallback (server-side or SDK middleware) - the API drops it before the model sees it: the request succeeds, the dropped block doesn't count toward input_tokens and isn't billed, and the target model re-plans without that reasoning (expect higher cost and latency on the first turn after a switch). A dropped block changes the cached prefix from its position onward on that request. Without the thinking-binding-controls-2026-08-01 beta header the drop is silent; with it, the response carries a top-level input_transformations array naming each dropped block with reason: "model_binding_mismatch" (shape below).

Keep passing thinking blocks back unchanged when you switch models - the API drops what the target can't read, unbilled, so there are no input tokens to save by stripping; removing blocks yourself can trigger ordering/signature 400s, and a fallback-credit retry must echo the refused body unchanged.

Breaking change 3: thinking blocks are preserved only in the conversation that produced them

The published docs file this and breaking change 2 together under preserved thinking ("pass blocks back unchanged and let the API decide which the model can use"); this one is the conversation check - editing earlier turns invalidates every later thinking block. The API field names for it say prefix_mismatch_behavior / prefix_binding_mismatch - the same check. Claude Mythos 5.1 does not run this check (breaking change 2, the model-binding check, still applies to it, and editing history still restarts the prompt cache).

To find and fix these edits in an existing harness - capture its requests, diff them, measure the drops, then one diff per cause - follow shared/preserved-thinking-migration.md (the preserved-thinking-migration subcommand). This section holds the rules that guide applies.

A Claude Fable 5.1 thinking block's signature also records the conversation prefix that produced it - the top-level system prompt, the set of tools in tools, and every message before the block (with server-side compaction, the prefix starts at the most recent compaction block) - plus a chain to the previous thinking block across turns (earlier thinking blocks aren't part of the prefix, but each block records the one before it, which is why blocks can be removed from the front of the history and not from the middle). When the transcript comes back, the API checks that this prefix is unchanged. Claude Code, claude.ai, Managed Agents, and the Agent SDK keep the prefix intact for you; if your code builds the messages array itself, check it before migrating (the three-step check is below). Who is enforced: new accounts created on or after August 31, 2026, on every platform. Enforcement scope is decided per model - Claude Opus 5.5 also enforces it for new accounts only - so make your application compatible regardless of your account's age: the same patterns keep the prompt cache warm, and you can test against the check from any account by sending prefix_mismatch_behavior. For accounts created earlier the API records the mismatch but acts on it only when the request sets thinking.block_binding.prefix_mismatch_behavior - any value, including "error", opts the request into enforcement, which is also how you test from an older organization (the beta header alone does not opt in: it lets you set the field and, on a request that leaves the field unset, lists each failing block in input_transformations as thinking_mismatch_allowed while the model still receives it). If you ship a tool or framework that people run with their own API key, test with the field set: your users on new organizations are enforced before you are. To see whether your own organization is enforced by default, send a request that edits history without the beta header - a 400 that names the header means it is. Platform note: the opt-in controls (the beta header, prefix_mismatch_behavior, input_transformations) are available under the same beta name on the Claude API, Claude Platform on AWS, Amazon Bedrock, and Google Cloud Vertex AI (Bedrock: the anthropic_beta body field; Vertex: the anthropic-beta HTTP header - the SDKs' betas parameter does the right thing on each); Microsoft Foundry is unconfirmed. Wherever an endpoint rejects the header or the beta name, the opt-in test path doesn't apply and recovery is strip-and-retry (shared/platform-availability.md has the matrix).

What invalidates every later thinking block:

• Editing, reordering, or removing an earlier turn while keeping later ones - including deleting old tool results (use server-side tool-result clearing instead).
• Injecting per-request text into an earlier turn (a reminder, a status line, a token count) that you remove or rebuild on the next request.
• Rebuilding the top-level system prompt or tools array between requests in the same conversation.
• Removing a thinking block from anywhere other than the start of the run (see below).
• An image or document URL in an earlier turn that serves different bytes on a later request - the bytes are bound, not the URL string, so a rotating signed URL for the same file is fine; for content referenced across turns, upload it once with the Files API and send the file_id, or send base64.

What keeps later blocks valid: append-only histories, including appended role: "system" messages and cleared turn-scoped (clear_at) messages or reminder text blocks left in place; removing a leading run of thinking blocks, oldest first (the first block in the conversation - or the first after the most recent compaction block - then the next, and so on); reordering tools without changing them (bound as a name-sorted set; confirm at launch) and adding a defer_loading: true tool nothing has referenced yet; changing any request parameter outside system / tools / messages (max_tokens, output_config incl. effort, tool_choice, metadata); adding, moving, or removing cache_control markers; a rotating signed URL that returns the same bytes; server-side compaction and context editing, including thinking-block clearing (they don't count as edits, because the check compares the conversation as you sent it, not the server's edited copy; after a compaction the checked prefix starts from the compaction block).

Where the check is enforced, a request that replays an invalidated block is rejected with a 400 invalid_request_error, decided before any output. Retrying the same body fails the same way; the token-counting endpoint runs the same check. (In the Message Batches API the unset default drops failing blocks instead of failing the item - set "error" explicitly if you want batch items to error.)

messages.5.content.0: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block". That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.

The last sentence appears only when the request didn't send the beta header; the message can end with one more sentence naming the first message that changed - the actionable diagnostic. (A tampered or undecryptable signature is a different failure: the same leading clause with no "bound to a different conversation" sentence, always a 400, and prefix_mismatch_behavior doesn't apply.) Two recoveries:

1. Strip every thinking and redacted_thinking block from the history (each turn's text and tool_use blocks stay), then retry once - the no-beta path. The model answers that turn without the reasoning those blocks carried. Dropping thinking once, at a boundary such as a compaction, has little effect; an integration that invalidates its own history on every request loses that reasoning and restarts the prompt cache each time, which can raise cost per task. Treat this as a one-time recovery, not a steady-state pattern.
2. Ask the API to drop instead of erroring:

POST /v1/messages
anthropic-beta: thinking-binding-controls-2026-08-01

{"model": "claude-fable-5-1", "max_tokens": 4096,
 "thinking": {"type": "adaptive", "block_binding": {"prefix_mismatch_behavior": "drop_block"}},
 "messages": [ ...full history with thinking blocks replayed verbatim... ]}

thinking.block_binding.prefix_mismatch_behavior takes "error" or "drop_block". On an enforced account the default is "error" with or without the header (the header only lets you set the field, and adds input_transformations to responses). On an account that isn't enforced, an unset field lets failing blocks through to the model, and with the header each one is listed in input_transformations as an entry of type thinking_mismatch_allowed. In the Message Batches API the unset default on an enforced account drops the failing blocks instead of failing the item; a Batches item fails as errored only with prefix_mismatch_behavior: "error" set. Set the field explicitly. With "drop_block" the API drops the first mismatched block and every thinking block after it (up to the next compaction block, if any - including blocks in an assistant turn whose tool_use is still waiting on its tool_result), the request proceeds, and each drop is reported in the response's top-level input_transformations array:

"input_transformations": [
  {"type": "thinking_dropped", "path": "messages.1.content.0", "reason": "prefix_binding_mismatch"}
]

The drop applies to that request only: keep sending "drop_block" for the rest of the session, or remove the failing blocks from the history yourself. On a "type": "thinking_dropped" entry, reason is "prefix_binding_mismatch" (your history changed) or "model_binding_mismatch" (the conversation switched models - not a bug in your code). The other entry type, thinking_mismatch_allowed (always reason: "prefix_binding_mismatch"), marks a block that failed the prefix check but still reached the model, on a request the API doesn't enforce. Ignore entries whose type or reason you don't recognize, because later checks add values. With the header, every response from a thinking-capable model carries the array (empty when no block was dropped and none failed the prefix check, never null); without it the field is absent. When streaming it arrives on the message object in message_start (and again in the final message_delta after a mid-stream server-side fallback). Sending block_binding without the header is a 400 ending in block_binding: Extra inputs are not permitted. The object is accepted alongside thinking.type: "adaptive" and "enabled", and models that don't enforce the conversation check accept it and report only model-check drops, so one request body works across models. The launch SDKs type it in the beta namespace (client.beta.messages.create(..., thinking={"type": "adaptive", "block_binding": {"prefix_mismatch_behavior": "drop_block"}}, betas=["thinking-binding-controls-2026-08-01"]); typed enum names such as PrefixMismatchBehavior are open at launch - fall back to extra_body / a cast if the field isn't typed yet). Some older tooling spells the field block_binding.mismatch_behavior - an undocumented alias; write the canonical name and never send both.

The three-step check for an existing integration:

1. Capture the exact request bodies it sends over a few normal turns, including a compaction or a tool change if the product has them. For each pair of consecutive requests, compare the system prompt, the tools array, and the shared prefix of messages - they should be byte-identical up to the newly appended turns.
2. Run a normal multi-turn session against claude-fable-5-1 with the thinking-binding-controls-2026-08-01 header and prefix_mismatch_behavior: "drop_block", and log input_transformations on every response. An empty array on every turn means the history is intact; a prefix_binding_mismatch entry means something before the block at path changed since the previous request; a model_binding_mismatch entry means the conversation switched models. This works from any organization wherever the controls beta is accepted (see the platform note above: if a partner endpoint rejects the beta name as unknown, use strip-and-retry; Foundry unconfirmed), because setting the field opts the request into enforcement. In CI, set "error" instead so an edit fails the run.
3. Choose a production setting and set it explicitly rather than relying on the default (see the defaults note above): "error" if a prefix mismatch can only mean a bug in your code, or "drop_block" to degrade instead of fail - and monitor the 400s or the input_transformations entries either way. On an account that isn't enforced (created before 2026-08-31), sending the header with the field unset is a way to monitor production traffic, not one of the two settings above: failing blocks still reach the model, and each one shows up only as a thinking_mismatch_allowed entry in input_transformations.

Making a harness compatible - replace each transcript edit with its append-only form:

Two client-side compaction shapes break under the check. Keep-tail compaction (summarize older turns, keep the most recent turns verbatim) fails on the retained turns: their thinking blocks were created with the full history present, so replaying them after the summary returns a 400 even though the retained turns are unchanged - strip the thinking blocks from the retained turns (text and tool calls can stay) or set "drop_block". Background (async) compaction (compact off the critical path and swap the summary in while the conversation continues) fails the same way but affects more of the transcript: by the time the summary lands, several newer turns exist above the swap point and all of their thinking blocks predate it - send "drop_block" on every request that still carries pre-swap thinking blocks (or strip those blocks yourself; input_transformations on the first response after the swap lists exactly which ones), or compact synchronously. The same applies to the compaction beta's pause_after_compaction flow if you re-insert assistant turns after the compaction block: remove their thinking blocks or send "drop_block". Snipping individual turns out of the middle of the transcript invalidates every later thinking block, and no client-side shape avoids it - use a mid-conversation system message for the instruction change you were making, or server-side context editing for selective removal.

What carries over unchanged from Claude Fable 5

The API surface, limits, per-token pricing, tokenizer, always-on adaptive thinking, refusal handling, and stop_details categories all match Claude Fable 5: no thinking config other than {type: "adaptive"} (disabled and budget_tokens both 400), display defaults to "omitted" and the raw chain of thought is never returned, interleaved thinking is automatic (no header), no assistant prefill, no non-default sampling parameters, 512-token minimum cacheable prompt, mid-conversation system messages and tool changes supported. The refusal stop reason must be handled before reading content - the classifiers cover the same categories as Claude Fable 5 (a broader set than Claude Opus 5's cyber-only classifiers), so expect stop_details.category values "bio" and "reasoning_extraction" as well as "cyber". Deltas:

• Fallbacks: server-side fallbacks ("default", or the array form) and the SDK middleware work as on Claude Fable 5; the permitted targets are claude-opus-4-8 and claude-opus-5, and per-category routing is applied server-side and not published (some categories decline with no fallback). The fallback model can't read Claude Fable 5.1's thinking blocks, so the API drops them (breaking change 2). Fallback credit works as on Claude Fable 5: Claude Fable 5.1 and Claude Mythos 5.1 both mint a fallback_credit_token on refusals (the token is null when no credit is available for a refusal, so always handle null), redeemable on either permitted target (pattern 3 of the refusal section in § Migrating to Claude Fable 5.1 above); the credit refunds the prompt-cache cost of switching models. A mid-stream refusal is billed at normal rates; for a refusal before any output, see How refusals are billed.
• Data retention: Claude Fable 5.1 and Claude Mythos 5.1 are Covered Models like Claude Fable 5 - 30-day retention required, not available under zero data retention unless expressly authorized by Anthropic. As on Claude Fable 5, a request from an organization or workspace without 30-day retention returns 400 invalid_request_error ("In order to access this model, your organization or workspace must have data retention enabled.") - check the retention configuration before debugging the payload. (An earlier draft of the launch docs described a 404 with the model hidden from /v1/models; the final wording is the 400. If you do see a 404 on the ID, check retention before anything else.) A ZDR organization that needs the model should contact its Anthropic account team (the "expressly authorized" path) or enable 30-day retention for one workspace; a ZDR org that can already reach the model has such an authorization, not proof the requirement is gone. (Earlier drafts of the launch docs described a time-bound enterprise exemption through 2026-12-31; that sentence was removed on Aug 28 - don't cite it.)
• Priority Tier: not supported on Claude Fable 5.1 or Claude Mythos 5.1 (Claude Fable 5 is). A Claude Fable 5 caller on Priority Tier loses it on migration.
• Rate limits: Claude Fable 5.1 shares one "Fable 5.x" pool with Claude Fable 5 (combined traffic; the Mythos models share a separate pool on the same terms) - re-baseline headroom if you run both during the migration.
• Pricing: $10 / $50 per MTok, 5-minute cache writes $12.50, 1-hour cache writes $20, batch $5 / $25 - all as Claude Fable 5 - except cache reads at $0.25 per MTok (0.025x base input; Claude Mythos 5.1 shares this rate, Claude Opus 5.5 reads at 0.05x, and every other model at 0.1x): a quarter of the Claude Fable 5 rate and half of Claude Opus 5's. Long agentic sessions that re-read a cached prefix get most of the saving; caching break-even math in shared/prompt-caching.md shifts accordingly - and because a miss is now much more expensive relative to a hit, keeping the cache warm matters more: per-message effort and turn-scoped system messages exist partly for that, and for idle gaps of 5-60 minutes a max_tokens: 0 keep-alive re-send on the default 5-minute TTL is usually cheaper than the 1-hour TTL (send it with stream off; not with structured outputs or Batches - see shared/prompt-caching.md § Choosing the TTL). Expect cost per task at or under the Claude Fable 5 figures in shared/cost-optimization.md.
• Tool surface: the same tool versions as Claude Fable 5 - code execution code_execution_20250825 / _20260120 / _20260521 (programmatic tool calling needs _20260120 or later), tool search (tool_search_tool_regex_20251119, _bm25_20251119), computer use computer_20251124, browser use, structured outputs, web fetch with dynamic filtering (web_fetch_20260318), and the advisor tool (as executor or advisor; Claude Fable 5.1 / Claude Mythos 5.1 advisors return the encrypted advisor_redacted_result). Task budgets: beta (task-budgets-2026-03-13, 20k minimum) - confirm at launch.
• Content provenance (new, no request change): text from Claude Fable 5.1 and Claude Mythos 5.1 carries Anthropic's statistical text watermark on every platform (no extra tokens or hidden characters, nothing about your org). Supported image, audio, and video files Claude produces in the code-execution sandbox carry signed C2PA Content Credentials when downloaded through the Files API on the Claude API - the manifest adds a few kilobytes, so the downloaded file's size and checksum differ from the file inside the container; text, PDF, and office files aren't signed. Platform scope beyond the Claude API is open at launch.
• 1M context on Bedrock / Google Cloud and the batch 300k-output beta: open at launch - confirm before promising either on a partner platform.

New API features

Three additions, each behind a beta header. All optional - a migrated request works without them - but the first two are how a harness stays cache-friendly and keeps its thinking preserved, so read them before touching an agent loop.

1. Per-message effort - beta mid-conversation-output-config-2026-07-01. On Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, and Claude Sonnet 5.5 (with thinking on) (Claude API and Google Cloud; Claude Platform on AWS / Bedrock / Foundry not confirmed, and Claude Opus 5 is excluded on Bedrock), a role: "system" message with empty content and output_config: {effort: ...} changes effort from that point on without invalidating the prompt cache - raise it for a hard step, lower it for routine ones:

POST /v1/messages
anthropic-beta: mid-conversation-output-config-2026-07-01

{"model": "claude-fable-5-1", "max_tokens": 4096,
 "output_config": {"effort": "high"},
 "messages": [
   {"role": "user", "content": "Plan the migration."},
   {"role": "assistant", "content": "Here's the plan: ..."},
   {"role": "system", "content": [], "output_config": {"effort": "low"}},
   {"role": "user", "content": "Now rename the config file."}
 ]}

Values are the level names (low, medium, high, xhigh, max). The new level takes effect from the next user turn and holds until a later role: "system" message changes it. An effort-only message carries no text, so the placement rules for mid-conversation system messages don't apply - it can sit anywhere in messages, including first or between an assistant turn and the next user turn. Lowering effort this way is reliable; raising works best for large jumps (e.g. low to xhigh). On Claude Fable 5.1 prefer this form over changing the top-level value between requests: a top-level change restarts the cache and steers the model less reliably (its earlier replies were written at the previous level and it tends to stay consistent with them) - though a top-level change does not invalidate thinking blocks. Unsupported models, Claude Fable 5 included, 400: output_config.effort requires a model that supports per-turn effort; this model does not. The older spellings mid-conversation-effort-2026-08-01 and per-turn-control-2026-07-01 still resolve to the same feature but are undocumented - don't write new code with them. The beta is open to any organization that sends the header. This supersedes the "per-turn effort is not in this launch" note in the Claude Opus 5 checklist.

2. Turn-scoped mid-conversation system messages - beta mid-conversation-system-clear-at-2026-08-21. A harness often needs to tell the model something that is only true for one turn ("check your inbox before running code", "the user can't see that tool output"). Injecting the reminder and deleting it next request is a history edit - it restarts the prompt cache and, on Claude Fable 5.1, invalidates every later thinking block. Instead give a role: "system" message clear_at: "next_user_message": its text carries system-prompt authority for the current turn, then stops rendering once a later user message exists. Keep sending it back verbatim - it stays in messages, so nothing earlier changes, the cache keeps matching, later thinking blocks stay valid, and a cleared message costs no input tokens.

POST /v1/messages
anthropic-beta: mid-conversation-system-clear-at-2026-08-21

{"model": "claude-fable-5-1", "max_tokens": 4096,
 "tools": [...],
 "messages": [
   {"role": "user", "content": "Run the analysis script."},
   {"role": "assistant", "content": [{"type": "tool_use", "id": "toolu_01", "name": "bash",
    "input": {"command": "python analyze.py"}}]},
   {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_01",
    "content": "Analysis complete; report written."}]},
   {"role": "system", "clear_at": "next_user_message",
    "content": "Results have landed in your inbox; check it before running more code."}
 ]}

The main use is a per-turn reminder in a tool loop: append the message after each tool_result user message you want it in view for, and leave every earlier copy where it is - a tool_result-only user message counts as the next user message, so the earlier copies are already cleared (rendering nothing, costing nothing, still part of the prefix the thinking is tied to) and the model reads only the newest one. Rules: clear_at takes "never" (the default) or "next_user_message"; a turn-scoped message is text-only (no tool_addition/tool_removal blocks, no output_config), takes no cache_control (put the breakpoint on the preceding user turn), and follows the normal placement rules - one followed directly by another user message is a 400, so put all of a tool round's results in one user message and the reminders after it. Deleting, rewording, rebuilding from current state, or changing the clear_at of a copy already sent is an edit like any other. Same models and platforms as mid-conversation system messages (on Bedrock and Google Cloud pass the beta value the way that platform passes betas); the launch SDKs may not type the field yet - send it via extra_body / a cast. Without the beta, append the reminder as a text block after the tool_result blocks in the same user message and leave earlier copies in place - the model acts on the newest one.

3. Progress updates between tool calls - thinking.display: "updates", beta thinking-display-updates-2026-08-18. Between tool calls, Claude Fable 5.1, Claude Mythos 5.1, and Claude Fable 5 write short progress updates - what it just found, what it will do next - each returned as its own thinking block with its own signature immediately before the tool call it introduces, separate from any reasoning block at the same point. Under the default display: "omitted" those blocks come back empty, like reasoning, which is why a long agentic turn can look silent for minutes. Request display: "updates" and the progress updates come back as text while reasoning stays hidden:

POST /v1/messages
anthropic-beta: thinking-display-updates-2026-08-18

{"model": "claude-fable-5-1", "max_tokens": 4096,
 "thinking": {"type": "adaptive", "display": "updates"},
 "tools": [...],
 "messages": [{"role": "user", "content": "Review the PRs open against our billing service."}]}

How to consume them: under "updates" any thinking block with non-empty text is a progress update (normally a sentence or two) - render it as a status line; render nothing for an empty block (a progress block can come back empty under any display value). When streaming, a progress block streams its text as thinking_delta events before the tool_use block it introduces - treat a block as a progress update as soon as a thinking_delta carries non-empty text; a pause of several seconds before the block opens is normal. A response can contain zero of them and the model can skip any gap, so build for zero-or-more. When a response stops on max_tokens, model_context_window_exceeded, or stop_sequence soon after a tool call or result, its last block can be a progress block standing in for unfinished work whose text is exactly This part of the response was interrupted before it finished. - to continue, pass the assistant turn back unchanged and append a new user message (with a tool_result for each tool_use in that turn). The update is billed at its full length in usage.output_tokens, not the summary's. Echo progress blocks back unchanged like any thinking block. "summarized" returns their text too, mixed with the reasoning summaries. Available on every platform - on Bedrock, Google Cloud, and Foundry pass the beta value the way that platform passes beta headers; without it "updates" is rejected as an unknown display value.

Coming from Claude Opus 5

Beyond the three breaking changes: thinking: {type: "disabled"} 400s at any effort (on Claude Opus 5 it was accepted at high or lower) - remove it, control spend with lower effort, and revisit max_tokens. Text the model wrote between tool calls on Claude Opus 5 came back as text blocks; on Claude Fable 5.1 it comes back as progress-update thinking blocks, empty under the default "omitted" - set display: "updates" (or "summarized") if your UI rendered that narration. The classifier set is broader (bio, reasoning_extraction in addition to cyber). ZDR is lost (Claude Opus 5 is available under ZDR). Pricing goes from $5 / $25 to $10 / $50 per MTok, with cache reads at half Claude Opus 5's rate; the 512-token cache minimum is unchanged. Per-message effort already works on Claude Opus 5, so an Claude Opus 5 harness that uses it needs no change there.

From Opus 4.8 or earlier: apply § Migrating to Claude Fable 5.1 above first (Opus 4.7 or earlier: the Claude Opus 5 section before that), then this one - and budget time for the history-editing check: integrations written for Opus 4.8 and earlier often truncate old turns, strip or rebuild earlier messages, or refresh the system prompt each request, and Opus 4.8 never objected. Review prompts near the 512-token caching minimum.

Claude Mythos 5.1

claude-mythos-5-1 is the same model as Claude Fable 5.1 - same capabilities, limits, and per-token pricing (including the $0.25/MTok cache-read rate), and the same API behavior except that it does not run the history-editing check (breaking change 3) - offered only to approved Project Glasswing customers, and the only model besides Claude Fable 5.1 that reads Claude Fable 5.1's thinking blocks (it also reads Claude Mythos 5's; not the reverse). Confirm the organization's access with the account team before switching IDs. Two differences from a Claude Mythos 5 migrator's point of view: Claude Mythos 5.1 runs safeguards that depend on the access program the organization is approved under (Claude Mythos 5 ran none) - handle stop_reason: "refusal", read stop_details.category, and set up fallback as on Claude Fable 5.1 (same targets, claude-opus-4-8 and claude-opus-5; it mints a fallback_credit_token on refusals as Claude Fable 5.1 does) - and it is not offered on Claude Platform on AWS (Claude API, Amazon Bedrock as anthropic.claude-mythos-5-1 in us-east-1 only and not publicly listed, Google Cloud, Microsoft Foundry). It shares the Mythos rate-limit pool with Claude Mythos 5. Whether Claude Mythos 5 access carries over automatically is open at launch.

Capability improvements versus Claude Fable 5

The gap is widest at higher effort levels. Six areas: agentic coding over long sessions (multi-file features, large refactors and migrations, debugging, code review across sessions that run for hours); knowledge work with documents, spreadsheets, and slides (from a first question to a finished document, live-formula spreadsheet, or deck built from a blank page); research and search (multistep web research that follows up on what it finds); vision (dense charts, filings, and tables nested in PDFs - strongest when it has tools to crop and zoom); long-context retrieval deep in the 1M window; and computer use (operating a browser and desktop applications more reliably, recovering from failed steps). Multilingual performance is on par with Claude Fable 5. Held pending confirmation at launch: that it expands a request's scope partway through less often, and that an instruction given once at the start of a long session persists better - if the latter holds, remove instruction repetition inserted every few turns for Claude Fable 5 and re-test (the per-turn batching nudge below is a separate case: it targets one behavior on the next turn, so keep it where measurements show it helps).

Behavioral shifts (prompt-tunable)

None of these are API-breaking. The behavioral guidance in § Migrating to Claude Fable 5.1 above (longer turns, grounding progress claims, stating boundaries, delegation, memory surfaces, the readability addendum) still applies; these are the Claude Fable 5.1-specific deltas. Three of them show up without any code change: it batches implied tool calls less, narrates less between tool calls, and answers from memory more at low effort.

Effort. Start with high (the default) and re-run your effort sweep even if you ran one on Claude Fable 5 - level names don't correspond to the same amount of thinking across models. The gains over Claude Fable 5 show up across levels and are largest at the higher settings; at medium, results roughly match Claude Fable 5 at lower cost, so step down to medium or low where your evals show quality holds. At high and above set a large max_tokens - it is a hard limit on total output (thinking plus response). At low, Claude Fable 5.1 is often competitive with Opus and Sonnet on cost per task while performing better - evaluate low Fable effort against below-frontier usage before reaching for a cheaper model. Per-message effort (addition 1) lets one conversation mix levels without a cache reset.

Long deliverables at xhigh and max. At xhigh, and especially max, the model thinks more before it starts writing. When one request asks for a long deliverable - a full rewrite of a long document, a large table, a complete code file - it may draft much of it in its thinking and then write it out again as the reply: a longer wait and roughly double the output tokens. Simplest fix: run those requests at high (the recommended start anyway) and move up only where you've measured a quality gain. If you do run them at xhigh/max, set max_tokens to leave room for the thinking and the reply, and append this to the end of the user message - it makes the thinking much shorter on prose and code requests (replace the bracket with the request's actual max_tokens, e.g. 64,000). Like every appended per-request note on this model (addition 2 above), leave each earlier copy in place byte-for-byte on later requests, each keeping the value it was sent with - removing or rebuilding one is a history edit that invalidates the thinking blocks after it:

Everything Claude produces in one reply, including any reasoning or drafting it does before the reply, counts toward a single limit of about [max_tokens] tokens. If that limit is reached before the reply is finished, the person receives a cut-off response and has to start over. Composing an entire output or deliverable in full as reasoning and then again as a reply would double the length of the turn without improving the result, so Claude doesn't do that. Instead, when the person has asked for a long or effort-intensive deliverable such as a multi-section document, a large table or dataset, or a complete code file, Claude spends extra effort on understanding the request, checking the inputs Claude's answer depends on, settling the structure and other difficult decisions, and otherwise using the reasoning space to reason and the output space to write an output. If Claude plans well then it should not need to draft its output multiple times (and Claude is pretty good at planning, so this should not be an issue).

Batch independent tool calls in agent loops. When a request explicitly names several things to fetch, Claude Fable 5.1 issues those calls in parallel; standard function calling is unaffected. In long agent loops where the next independent reads are only implied (custom coding agents, bash-and-editor harnesses, computer use) it may issue one call per turn where Claude Fable 5 batched several - same answers, more round trips and wall-clock. Measure first: track the share of assistant turns with more than one tool call, and add the nudge only if that share is low (over-batching shows up as calls issued before results they depend on). Placement matters more than wording - one sentence near the end of the current request moves the number far more than the same text in the system prompt or a tool description. Each time you send tool results back, append the sentence after that user message as a turn-scoped system message (clear_at: "next_user_message", addition 2) - or, without that beta, as a text block after the tool_result blocks in the same user message - appending a fresh copy each turn and leaving the earlier copies in place byte-for-byte; rewriting earlier turns to remove them restarts the cache and, on this model, invalidates the thinking blocks after them. Keep the word "privately" - without it the model sometimes answers the reminder ("nothing further is needed") instead of the user in its final reply:

First privately list what you need next; then request every item that doesn't depend on another's result in this one response.

User-facing progress updates. Claude Fable 5.1 writes fewer user-facing updates during long tool-calling turns than Claude Fable 5 - more so at higher effort and in longer tool chains. Users see the agent go quiet for minutes, or a final message that describes only the last step; its agentic coding summaries are shorter too. In order: (1) request display: "updates" (addition 3) - if you aren't, the model's between-tool notes aren't reaching you; (2) remove prompt text written for update-eager older models ("hold all findings for the final response", "don't narrate") before adding anything; (3) if you still want more - pair programming, human-in-the-loop - add a short, specific system-prompt line saying when you want user-facing text:

Before you start, say in a line what you're about to do; brief updates while you work help the user follow along. Close with a short recap that stands on its own - what you found, what you did, and what's next - so a reader who only sees the last message has the full picture.

Relatedly, if the harness collapses or hides tool output, tell the model - otherwise Claude Fable 5.1 may run commands to "show" the user output they cannot see. Deliver it as a turn-scoped system message (clear_at: "next_user_message", addition 2), or without the beta alongside the tool results in the same user message, left in place on later requests:

Only you see that command's output - the user's terminal shows at most a few lines of it. If the user needs to read any of it, put it in your reply.

Writing density. Claude Fable 5.1's writing is generally preferred, but prose can be denser than Claude Fable 5's - longer sentences, fewer paragraph breaks. Defining "mannered prose" as an anti-pattern has helped; style instructions placed in the first user turn of a session hold better than the same text in the system prompt:

Mannered prose substitutes metaphor and flourish for direct statement. Instead of "a parameter worth varying," the mannered writer produces "a dial worth turning." Instead of "this point still matters," they write "this point earns its keep." The phrases exist to display the writer, not to convey the idea, and readers can tell. That is why mannered prose irritates: it makes the reader work harder so the writer can perform. It is also imprecise. Metaphors drag in connotations the writer did not choose and cannot control. The fix is to say what you mean. When a literal phrase is available, use it.

The short form - "Please remove all mannered prose." - also tends to work.

Formatting. Where earlier models over-used bullets and bold in chat, Claude Fable 5.1 does the opposite: less bold, fewer headers, lists, and quotation marks. If the prompt contains anti-formatting language, remove it or replace it with a rule that says when formatting is appropriate:

Use lists and bullet points when asked to, or when the content is multifaceted enough that they help with clarity. If the person explicitly requests minimal formatting, always format your responses without bullet points, headers, lists, or bold emphasis, as requested. In conversational, personal, or emotional exchanges, keep to plain prose.

When summarizing documents, Claude Fable 5.1 is more likely than Claude Fable 5 to reproduce passages of source text without marking them as quotations. The fix is one complete example of a correct response in the system prompt - the user's request, the response, and a sentence saying why the response is correct. Replace the two [web_search: ...] lines with your own tool name so the model reads them as templated tool output, not as literal desired output:

<example>
<user>look up how the Riverton Ledger and the Coast Dispatch each covered the Harbor Bridge closure and compare their reporting</user>
<response>
[web_search: Harbor Bridge closure Riverton Ledger]
[web_search: Harbor Bridge closure Coast Dispatch]
Both outlets agree on the basics: the bridge closed on March 3 after inspectors found cracked welds, and the state expects repairs to take about eight months. Where they differ is emphasis. The Ledger treats it as a local-economy story. The Dispatch frames it as a funding failure; its editorial calls the closure "entirely foreseeable." Read together, the Ledger explains who is affected now and the Dispatch explains how it came to this - neither account alone gives the whole picture.
</response>
<rationale>CORRECT: The response is organized around where the two outlets agree and differ, not as a walk through either article. Each outlet's reporting is conveyed in one or two sentences of the assistant's own indirect speech. One short marked phrase from one source; every other claim is reworded. The response is still specific and complete.</rationale>
</example>

Maximizing long-horizon execution. Claude Fable 5.1 is capable of very long autonomous runs, but on complex asynchronous workloads it needs a nudge not to stop at describing the next step ("Next, I'll ...") or asking permission for a step the request already covered ("Shall I apply this?"). Users experience it as having to reply "continue" - fine for pair programming, but it caps the model's long-horizon capability. Two system-prompt additions together mitigated this; apply both unless context is tight, in which case the first keeps most of the effect. The opening sentence of the first ("The user is not watching") is load-bearing - keep it as written; if the product needs stops for specific confirmations, add a sentence listing them. This prompt can make the model less likely to clarify ambiguous requests. With either block the model writes slightly more code - mostly extra tests in files it's already editing - so pair them with the "ground progress claims" audit instruction in § Migrating to Claude Fable 5.1 above and the test-coverage line below. If your existing prompt asks the model to test or check its work before reporting, keep it when migrating - the Claude Opus 5 guidance to delete verification instructions doesn't apply here (tentative: rests on a small number of reports).

You are operating autonomously. The user is not watching in real time and cannot answer questions mid-task, so asking 'Want me to...?' or 'Shall I...?' will block the work. For reversible actions that follow from the original request, proceed without asking. Stop only for destructive actions or genuine scope changes the user must decide. Offering follow-ups after the task is done is fine; asking permission before doing the work is not.

Exception: when the user is describing a problem, asking a question, or thinking out loud rather than requesting a change, the deliverable is your assessment. Report your findings and stop. Don't apply a fix until they ask for one.

Before ending your turn, check your last paragraph. If it is a plan, an analysis, a question, a list of next steps, or a promise about work you have not done ('I'll...', 'let me know when...'), do that work now with tool calls. That includes retrying after errors and gathering missing information yourself. Do not stop because the context or session is long. End your turn only when the task is complete or you are blocked on input only the user can provide.

Before running a command that changes system state (such as restarts, deletes, or config edits), check that the evidence actually supports that specific action. A signal that pattern-matches to a known failure may have a different cause.

The second tells it to hold the scope the user set:

# Delivering work The user's request - or the plan they approved - sets the scope, and the scope is the deliverable: don't quietly narrow, widen, or swap it. Read ambiguity the way a careful colleague would: make routine judgment calls yourself, and check in only when different readings would lead to materially different work. If you see a real problem with the task as specified, say so in a sentence or two and keep building under stated assumptions; if the user hears the concern and reaffirms, that is their decision, so deliver the full request.

If a question comes up partway, first do everything that doesn't depend on the answer; then state the assumption you made, or - when going ahead on a wrong guess would be unsafe or would make the work useless - put the question at the end of a turn that also delivers that progress. If one part turns out to be blocked, complete every other part in full and say exactly what you left out and why - the whole task is the deliverable, and scaling it down is the user's call, not yours. A step you have decided on is something to run, not to announce: describing the next step and ending the turn leaves it undone until the user replies.

Keep changes to what the request needs. Something else you notice worth doing - cleanup or documentation the task didn't call for, a change to a file the task didn't require - is a suggestion to make at the end, not a change to make; actions clearly beyond what the ask implies, and risky or destructive ones, still need the user's go-ahead.

(The published snippets use em dashes and ellipsis characters where this file has hyphens and three periods; the bundled skill is ASCII-only, and the difference has no effect on the model.)

Scope and test coverage. Asked to implement an open-ended feature, Claude Fable 5.1 delivers what was asked and sometimes more - fixing nearby code, writing extra tests, committing scratch checks as permanent test files. It responds well to explicit instructions about what to leave out; with this prompt the guide's authors saw far fewer unrequested additions and much less committed test code with no measurable change in task success (an earlier, shorter form - "keep verification scripts outside the repository, e.g. under /tmp, and delete any you did add" - still works if you only care about test sprawl):

If, while working or testing, you find a pre-existing bug, a performance concern, or behavior the task doesn't mention, don't fix, optimize or extend it in this change unless the requested behavior cannot work without it; report it as a follow-up in your summary. Where the task is ambiguous, implement the reading its wording and the surrounding code most directly support, state that assumption in your summary, and don't build for the other readings as well. Verify your work however you like; scratch scripts and quick checks need not be kept. Commit tests only where the task asks for them or this repository already keeps tests for this kind of change, sized like the neighboring test files - roughly one focused test per stated behavior - and don't turn scratch checks into additional permanent test files. This is about extras only: implement every behavior the task asks for, completely.

Search triggering at low effort. At low effort, Claude Fable 5.1 calls a search or retrieval tool less often than Claude Fable 5 and answers from memory more - most visibly for named products, models, and tools it recognizes but has out-of-date knowledge of. Raising effort for those turns (per-message effort, feature 1) is often the simplest fix. Otherwise tell it in the system prompt that recognizing a name is not the same as knowing its current state, and that such names should be searched as the user wrote them:

When a query centers on a name you do not confidently recognize, or recognize from a fast-moving area like AI models and developer tools where the landscape shifts within months, the name itself is the thing to verify: search before answering, and include the name as the user wrote it in at least one query alongside any reformulations. This holds even when you have some background on it - partial background is exactly what makes an out-of-date answer sound authoritative, so familiarity is not a reason to skip the search.

Vision: let it crop, zoom, and verify. Claude Fable 5.1's pure vision is better out of the box, and it is best when it can iteratively analyze, crop, and visually verify its own work. For complex inputs - dense charts, filings, tables nested in PDFs, video - run it as an agent with a container that holds the raw images/videos and basic image-processing libraries (PIL, OpenCV) preinstalled. If a container is too much overhead, most of the uplift comes from a single crop tool that takes a bounding box and returns that region cropped and enlarged (the recipe is in the Claude Opus 5 section's vision guidance) - this scales test-time compute with image tokens instead of effort. At low effort the model may answer from an overall impression without calling it, so check the logs for the call and raise effort on image turns if it's missing.

Safeguard false positives. The classifiers produce fewer false positives than Claude Fable 5's did at launch, and finding vulnerabilities in source code is permitted; a blocked request still returns stop_reason: "refusal", so keep the refusal handling and fallbacks in place. Three situations make false positives more likely: compile-check phrasing (ask "Are there any bugs in this program?" rather than "Does this program compile without errors?"); lesser-known programming languages (give the model context on what the language is and how it works, e.g. its docs); and tools that return base64-encoded data into the model's context (remove them).

Whole-file rewrites. Claude Fable 5.1 is more likely than Claude Fable 5 to rewrite an entire file where a targeted edit would do - same result, more output tokens and time. Appending this to the system prompt (or the first user message - equally effective) restored targeted edits for small and medium changes:

The number of tokens used to edit files is best minimized, all else being equal. Therefore, when it will not affect the end result, try to surgically edit a file rather than rewrite the entire thing.

Summarization prompt for client-side compaction. Claude Fable 5.1 responds well to being told explicitly what to retain in a compaction summary. Server-side compaction already does this; if you compact on the client (the simple-compaction shape under breaking change 3), this summarization instruction has been effective. The final sentence is load-bearing when the summarization request still carries the conversation's tools (breaking change 3 means you can't drop them for one request): without it the model occasionally calls a tool instead of writing the summary.

Summarize the transcript inside <summary></summary> tags. Include relevant information in the summary such that this conversation will be continued by a new context window without needing to redo work or be reprovided with relevant constraints or context. Be sure to preserve: (1) any difficulties or problems that came up, and how they were handled or resolved; (2) any possibilities, options, or approaches that were raised, tried, or set aside, and why; (3) anything that was asked for, decided, agreed, ruled out, or established as a preference, constraint, or boundary - stated exactly; (4) exactly where things stand now - what has been covered, settled, or completed so far; (5) anything still open, unresolved, promised, or expected to happen next; (6) specific details that would be hard to reconstruct - names, numbers, dates, exact wording, links or references - kept exactly. Be complete on these even at the cost of length; keep everything else concise. Weight the two voices differently: keep what the user said, asked for, shared, or established carefully and close to their own words; your own explanations and reasoning can be condensed much further, to what they concluded or produced - as long as nothing in the six items above is dropped. Do not call any tools while writing this summary; respond with text only.

Non-blocking sub-agents in coding. If the coding agent delegates to sub-agents, Claude Fable 5.1 finishes sooner when the lead is not forced to stop and wait for each one - lower average time to completion at similar quality, token usage, and cost. Have the tool that starts a sub-agent return immediately and deliver the sub-agent's result to the lead in a later user message when ready; the model will still often choose to wait, so also give it a separate tool that waits for its sub-agents. The time savings come from the cases where the lead carries on with other work. (This extends the asynchronous-delegation guidance in § Migrating to Claude Fable 5.1 above.)

Claude Fable 5.1 from Claude Fable 5 Migration Checklist

• [BLOCKS] Update the model= string to claude-fable-5-1 (claude-mythos-5-1 for Project Glasswing participants coming from Claude Mythos 5; confirm access first)
• [BLOCKS] Remove tool_choice: {type: "any"} and {type: "tool", name: ...} (400, also on count_tokens and Batches) - auto plus the instruction in the user turn (or an appended role: "system" message when the application requires the call), strict: true for schema-valid arguments, structured outputs for JSON extraction; delete any retry-on-missing-tool loop that depended on forcing
• [BLOCKS] Coming from an Opus-tier or older model (not from Claude Fable 5): apply the Claude Fable 5.1 Migration Checklist above (the Opus-tier -> Fable migration) first, plus § Coming from Claude Opus 5 - thinking: {type: "disabled"} now 400s at any effort, between-tool narration moves into thinking blocks, ZDR is lost, price doubles
• [BLOCKS] Data retention: 30-day retention required (Covered Model; ZDR only if expressly authorized by Anthropic) - a ZDR org gets 400 invalid_request_error on every request, as on Claude Fable 5; check the retention configuration before debugging the payload
• [BLOCKS] Keep passing thinking blocks back unchanged on every turn, including empty ones and redacted_thinking - the history-editing check rejects edited history
• [BLOCKS] Preserved thinking / the history-editing check (new accounts created on/after 2026-08-31 on every platform, and any request that sets prefix_mismatch_behavior; enforcement scope is decided per model, and Claude Opus 5.5 also enforces it for new accounts only; Claude Mythos 5.1 doesn't run it): stop editing history between requests - freeze the top-level system, use role: "system" messages for mid-session instructions, tool_addition/tool_removal for tool changes, turn-scoped (clear_at) system messages - or, without that beta, retained user-message text blocks - appended after the tool results and never deleted, for per-turn reminders, server-side context editing / compaction (summary-only if client-side) for trimming, file_id for cross-turn files. Run the three-step check (prefix_mismatch_behavior: "drop_block" + log input_transformations; fix every prefix_binding_mismatch, model_binding_mismatch after a model switch is expected; "error" in CI; the controls beta is also available on Claude Platform on AWS, Bedrock and Vertex, Foundry unconfirmed - shared/platform-availability.md), then pick a production setting and monitor it. If you ship a tool others run with their own key, test with the field set. Keep-tail and background compaction need "drop_block" (per request - keep sending it) or stripped thinking on the retained turns; never compact mid tool round
• [TUNE] Fallbacks: keep server-side fallbacks (targets claude-opus-4-8 / claude-opus-5; routing unpublished) or the SDK middleware; the fallback model can't read 5.1 thinking blocks (dropped, unbilled); fallback credit works as on Claude Fable 5 for both Claude Fable 5.1 and Claude Mythos 5.1 (handle a null token)
• [TUNE] Adopt thinking: {type: "adaptive", display: "updates"} with thinking-display-updates-2026-08-18 (all platforms) if users watch long tool-calling turns; render non-empty thinking blocks as status lines, handle the interrupted-response sentinel, echo them back unchanged
• [TUNE] Adopt per-message effort (mid-conversation-output-config-2026-07-01; also on Claude Opus 5 and Claude Opus 5.5) where a loop mixes hard and routine steps - lowering is reliable, raising wants a big jump; re-run the effort sweep (high default; medium as cost control; xhigh/max only for capability-sensitive work; low often beats below-frontier models on cost per task); size max_tokens for high+
• [TUNE] Agent loops: measure the share of multi-tool-call turns and add the "privately list what you need next" nudge (fresh copy each turn, earlier copies kept) if it's low; remove "hold findings for the final response" / anti-narration text and anti-formatting rules before adding the progress-update and formatting snippets
• [TUNE] Add the autonomy + scope prompts for unattended runs; the hidden-tool-output note if the harness collapses tool output; the targeted-edit and scope/test-coverage prompts for coding agents; the long-deliverable note (with the real max_tokens) for xhigh/max requests; the compaction summarization prompt if you summarize client-side; the mannered-prose instruction for prose-heavy work; the name-verification line for search products; a crop tool (or an image-processing container) for vision
• [TUNE] Priority Tier is not supported on Claude Fable 5.1; rate limits share the Fable 5.x pool with Claude Fable 5 - re-baseline headroom; cache reads cost a quarter of the Claude Fable 5 rate (re-check caching break-even; for 5-60 minute idle gaps a max_tokens: 0 keep-alive on the 5-minute TTL usually beats the 1-hour TTL - sent with stream off; not with structured outputs or Batches); tokenizer unchanged from Claude Fable 5, so re-baseline token counts only if you weren't on Claude Fable 5
• [TUNE] Supported image, audio, and video files produced in the code-execution sandbox carry a C2PA manifest when downloaded through the Files API on the Claude API - size and checksum differ from the in-container file (text, PDF, and office files aren't signed; platform scope beyond the Claude API open at launch); adjust integrity checks for signed media only

Migrating to Claude Opus 5.5

Model ID claude-opus-5-5 is authoritative as written here. When the user asks to migrate to Claude Opus 5.5, write model="claude-opus-5-5" exactly. Do not WebFetch to verify - this guide is the source of truth for migration target IDs. The corresponding entry exists in shared/models.md.

Claude Opus 5.5 succeeds Claude Opus 5 in the Opus line for long-running agentic coding and knowledge work, at a lower price - $4 / $20 per MTok input / output against Claude Opus 5's $5 / $25. Same 1M token context window (default and maximum), same 128K max output, same tokenizer as Claude Opus 5 (token counts unchanged; coming from a pre-Opus-4.7 model, follow the tokenizer guidance in the Claude Opus 5 section). Knowledge cutoff June 2026. Available at launch on the Claude API (claude-opus-5-5), Amazon Bedrock (anthropic.claude-opus-5-5), Claude Platform on AWS, Google Cloud, and Microsoft Foundry (all as claude-opus-5-5; on Foundry under both hosting options, "Hosted on Anthropic" and "Hosted on Azure"); Claude Opus 5 stays available on all of them. Existing Claude Opus 5 prompts should perform well out of the box; the Claude Opus 5 prompting patterns below remain a reasonable starting point.

Claude Opus 5.5 is the default Opus migration target. This section is layered on top of the Claude Opus 5 migration above - a caller coming from Opus 4.8 or older applies § Migrating to Claude Opus 5 first (Opus 4.7 or older: the sections before that), with two exceptions to what that section (and the earlier ones) say: Claude Opus 5's "thinking can be disabled at high or below" does not carry over, and neither does the acceptance of the earlier computer_20251124 tool outside Amazon Bedrock (breaking change 4 below). Coming from Claude Sonnet 5: the request surface already matches (adaptive thinking, no sampling parameters, no prefill) - apply this section on top of the Claude Sonnet 5 code, re-baselining for Opus-tier pricing and rate limits.

What changes, in one line: four breaking changes for code running on Claude Opus 5 (thinking can't be disabled; forced tool_choice 400s; thinking blocks are tied to the model and the conversation - "preserved thinking"; on the Claude API and Google Cloud the computer_20251124 tool 400s - use the computer toolset), one response-shape change that fails no request (text between tool calls comes back in thinking blocks), a default effort of medium where Claude Opus 5's is high, and a broader safety-classifier set (bio and reasoning_extraction join cyber). The first three breaking changes are the same mechanisms Claude Fable 5.1 introduced - the sections below give the Claude Opus 5.5 specifics and point at § Migrating to Claude Fable 5.1 from Claude Fable 5 for the shared mechanics rather than repeating them. Everything else in the Claude Opus 5 request surface carries over: mid-conversation system messages and per-message effort (which some of the tips below use), mid-conversation tool changes, task budgets, compaction, the 512-token minimum cacheable prompt, batch, the Files API, PDF support, vision, and the server-side and client-side tools.

Breaking change 1: thinking can't be disabled

On Claude Opus 5, thinking is on by default and thinking: {type: "disabled"} is accepted at effort high or below. On Claude Opus 5.5 thinking is always on: {"type": "disabled"} and {"type": "enabled", "budget_tokens": N} both return a 400 invalid_request_error at every effort level, with no beta header involved:

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

("thinking.type.enabled" is not supported for this model. ... for the budget form.) Omit the thinking field or send {type: "adaptive"}, which is equivalent. Effort is now the control for how much the model thinks, and therefore for latency and cost (§ Choosing an effort level below). Migrate a route that disables thinking or sets a budget as follows:

1. Remove the thinking field (or set it to {type: "adaptive"}).
2. If time to first token matters, set output_config.effort to low. At low the model keeps its thinking short; how often it skips thinking altogether depends on the prompts. Measure, and move to medium if quality drops. A system-prompt line such as "Answer directly without deliberating." can reduce thinking further (and with it TTFT and cost) - measure quality on your own use case before keeping it, since less thinking can cost accuracy.
3. Size max_tokens for the thinking as well as the reply. Thinking counts toward max_tokens even though its text isn't returned under the default display, so a limit sized for a no-thinking route cuts replies off. For long agentic coding turns, 64K has worked well.
4. Read the response by block type, not position. A response can begin with one or more thinking blocks; under the default display: "omitted" they come back with an empty thinking string. Set display: "summarized" for a readable summary of the reasoning. Pass thinking blocks back unmodified in tool-use loops.

# Before - accepted on Claude Opus 5, 400 on Claude Opus 5.5
client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "..."}],
)

# After - thinking is always on; effort is the control
client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    output_config={"effort": "low"},
    messages=[{"role": "user", "content": "..."}],
)

Prompts written for thinking disabled. Three follow-ups if the Claude Opus 5 integration ran with thinking off: (a) start at low and measure, as above; (b) remove instructions that stood in for thinking - a prompt that asked the model to write its reasoning into the response text as a substitute for thinking should go, and the reasoning read from display: "summarized" blocks instead; a prompt that pushes the model to reproduce its internal reasoning in the response can be declined with stop_details.category: "reasoning_extraction"; (c) re-test the two thinking-disabled mitigations from § Two failure modes when thinking is disabled under Claude Opus 5 - both address artifacts that appeared only with thinking off, so check whether the combined "brief sentence before a tool call / say so if no tool fits / no internal XML tags" instruction is still needed, and delete any rule telling the model not to think either way (it can't comply, and such rules increase tag leakage).

Breaking change 2: forced tool use is rejected

As on Claude Fable 5.1: tool_choice: {"type": "any"} and {"type": "tool", "name": "..."} return a 400 invalid_request_error (tool_choice: type "tool" and "any" are not supported for this model.) on the Messages API, the Message Batches API, and the token-counting endpoint, where Claude Opus 5 accepts both. {"type": "auto"} (the default) and {"type": "none"} are unchanged; disable_parallel_tool_use: true still works with auto but now means at most one call. Migrate by intent - the full patterns (steering from the prompt, strict: true for schema-valid arguments, structured outputs for extraction, the advisor tool) are under § Breaking change 1: forced tool use is rejected in § Migrating to Claude Fable 5.1 from Claude Fable 5. The two most common:

• Steering toward a tool: tool_choice: {"type": "auto"} plus the expectation in the prompt ("Use the get_weather tool to answer"), with strict: true on the tool definition (schema sets additionalProperties: false) so the arguments match the schema. Because auto does not guarantee a call, check that one was made and retry if it wasn't.
• Extracting structured data: if the forced call existed only to get JSON back, replace it with structured outputs (output_config.format).

# Before - 400 on Claude Opus 5.5
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

# After - auto + strict tool use, steering in the prompt, and a check that the call happened
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[{**tool, "strict": True} for tool in tools],
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "What's the weather in Paris? Use the get_weather tool."}],
)
if not any(block.type == "tool_use" for block in response.content):
    ...  # retry, or fall back to a text answer

Breaking change 3: thinking blocks are tied to the model and the conversation

Both halves of "preserved thinking" from Claude Fable 5.1 apply to Claude Opus 5.5; the mechanics (what invalidates a block, the drop_block request shape, input_transformations, the three-step audit, the append-only replacements table, which client-side compaction shapes break) are under § Breaking change 2 and § Breaking change 3 in § Migrating to Claude Fable 5.1 from Claude Fable 5 and apply verbatim. What is specific to Claude Opus 5.5:

• Model binding - who reads whose blocks. Claude Opus 5.5 reads thinking blocks from Claude Opus 5 and earlier Opus, Sonnet, and Haiku models - a conversation that moves onto claude-opus-5-5 keeps its reasoning - but not from any Fable or Mythos model. In the other direction, on the Claude API only Claude Fable 5.1 and Claude Mythos 5.1 read a Claude Opus 5.5 block; no other model does - so a router switch, a client-side retry on another model, or a classifier-refusal fallback (server-side or SDK middleware) to Claude Opus 5 / Claude Opus 4.8 runs the turns after the switch without Claude Opus 5.5's reasoning. The API drops what the target can't read before the model sees it: the request succeeds, dropped blocks aren't billed, and with the thinking-binding-controls-2026-08-01 header the drop is reported in input_transformations with reason: "model_binding_mismatch". Whether Claude Fable 5.1 / Claude Mythos 5.1 also read Claude Opus 5.5's blocks on Amazon Bedrock and Google Cloud is not documented - the docs state it for the Claude API only. Keep passing blocks back unchanged when you switch models; don't strip them yourself.
• Conversation binding - who is enforced. Same posture as Claude Fable 5.1: on every platform the prefix check (the system prompt, the tools array, and every earlier message must be byte-identical to when the block was produced) is enforced by default for accounts created on or after August 31, 2026, 00:00 UTC - a replayed block after such an edit is a 400. Older accounts opt in by setting thinking.block_binding.prefix_mismatch_behavior ("error" or "drop_block", beta thinking-binding-controls-2026-08-01). Claude Code, claude.ai, Managed Agents, and the Agent SDK keep the prefix intact; if your code builds messages itself, run the three-step check before migrating - and do it now even on an exempt account, because it also raises prompt-cache hit rates. The three edits that break the prefix and their append-only replacements: a per-turn reminder injected and later deleted, or a system prompt changed mid-session (append a mid-conversation role: "system" message instead; for a one-turn reminder the clear_at: "next_user_message" form under beta mid-conversation-system-clear-at-2026-08-21 is a limited beta - without it, append the reminder as a text block after the tool_result blocks and leave earlier copies in place); tools added or removed mid-session (declare the full set at session start and send tool_addition / tool_removal blocks, beta mid-conversation-tool-changes-2026-07-01); and compaction that summarizes older turns while replaying newer ones with their thinking blocks (use server-side compaction or context editing - the on-demand compaction parameter under beta compact-2026-09-04, offered on the Claude API, Claude Platform on AWS, Google Cloud, and Microsoft Foundry but not yet Amazon Bedrock, is designed to keep the retained turns' blocks valid after the swap - or client-side simple compaction that replaces the whole history with a summary and replays no earlier thinking, or set drop_block). Two compaction details that follow Claude Fable 5.1: a threshold-compaction request with custom instructions summarizes from the visible conversation only - earlier thinking blocks are not part of the summarizer's input, so tell it what the summary must retain (on-demand compaction's summarizer reads earlier thinking with or without instructions); and any assistant turn you re-insert after a compaction block needs its thinking / redacted_thinking blocks removed, or drop_block set.

POST /v1/messages
anthropic-beta: thinking-binding-controls-2026-08-01

{"model": "claude-opus-5-5", "max_tokens": 64000,
 "thinking": {"type": "adaptive", "block_binding": {"prefix_mismatch_behavior": "drop_block"}},
 "messages": [ ...full history with thinking blocks replayed verbatim... ]}

Breaking change 4: computer use only through the computer toolset

Re-check before promising computer use on a partner platform. Which platforms offer the toolset can change - WebFetch the Computer Use page from shared/live-sources.md and read its Compatibility section.

Claude Opus 5 accepts computer use both as the computer_toolset_20260801 toolset and, with the computer-use-2025-11-24 beta header, as the earlier computer_20251124 tool. On the Claude API and Google Cloud, Claude Opus 5.5 accepts only the toolset: a tools entry of type computer_20251124 returns a 400 invalid_request_error that names the rejected type and then lists the accepted ones after Did you mean one of (it begins 'claude-opus-5-5' does not support tool types: computer_20251124.). The toolset is GA on the Claude API and Google Cloud with no beta header. On Amazon Bedrock, Claude Opus 5.5 still accepts computer_20251124 (with its beta header), as Claude Opus 5 does - keep that version there. For other platforms, check the computer use tool's Compatibility section (shared/tool-use-concepts.md § Computer Use has the toolset summary). This is more than a tools-entry swap, so make and test the change on Claude Opus 5 first (it accepts both forms):

• Request: drop the beta header and the beta client namespace; the entry is {"type": "computer_toolset_20260801"} with no name and no display_width_px / display_height_px; an optional configs map turns individual member tools on or off ({"zoom": {"enabled": false}}). All 17 members, zoom included, are on by default. The entry can't share a request with a computer_20251124 entry or another tool named computer.
• Agent loop: Claude's calls are tool_use blocks whose name is the member (screenshot, left_click, type, zoom, ...) - the action is the block's name, not input.action - carrying "toolset_name": "computer", and there can be several per turn (a batch action), each its own block. Return one tool_result per tool_use, matched by tool_use_id, all in the next user message, every one echoing "toolset_name": "computer" (a result that omits it is rejected); only screenshot and zoom results need an image, a short OK is enough for the rest. Coordinates are in the pixel space of the full screenshots you return, also after a zoom. Screenshots must already fit the model's image limits (the toolset takes no display dimensions and the API doesn't downscale for you).

# Before - 400 on Claude Opus 5.5
client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["computer-use-2025-11-24"],
    tools=[{"type": "computer_20251124", "name": "computer",
            "display_width_px": 1024, "display_height_px": 768}],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

# After - no beta header; the toolset entry takes no name or display size
client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    tools=[{"type": "computer_toolset_20260801"}],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

Integrations already on the toolset, and the browser use toolset (browser_toolset_20260801), need no change.

Text between tool calls comes back in thinking blocks

On Claude Opus 5, the short notes the model writes between tool calls (what it just found, what it's doing next) come back as text blocks. On Claude Opus 5.5, as on Claude Fable 5.1, notes longer than a sentence or two come back as progress-update thinking blocks, at most one before each tool call, and under the default display: "omitted" their text is empty - no request fails, but a client that renders only text blocks goes quiet for the length of a long agentic turn. Fix: set thinking.display: "updates" (beta thinking-display-updates-2026-08-18) to get a short summary of each note as text while reasoning stays hidden ("summarized" returns both, mixed), render each non-empty thinking block ahead of the tool_use it precedes, and pass the blocks back unchanged - the consumption rules (streaming thinking_delta, the interrupted-work sentinel, zero-or-more per response) are under addition 3 in § New API features of § Migrating to Claude Fable 5.1 from Claude Fable 5:

POST /v1/messages
anthropic-beta: thinking-display-updates-2026-08-18

{"model": "claude-opus-5-5", "max_tokens": 64000,
 "thinking": {"type": "adaptive", "display": "updates"},
 "tools": [...],
 "messages": [{"role": "user", "content": "Review the PRs open against our billing service."}]}

Three levers on what users see:

1. Receive them - display: "updates" as above (a "summarized" display returns them too, mixed with the reasoning summaries).
2. If the model may need to hand the user something verbatim partway through a long turn - a code snippet, an exact value - give it a simple tool for sending the user a message and tell it to reserve the tool for that content. Declare the tool in tools from the first request of the session: adding it later edits the conversation's prefix and invalidates earlier thinking blocks (breaking change 3).
3. For more frequent or predictable updates - a one-line statement of intent before the first tool call and a short recap at the end - say so in the system prompt: when you want user-facing text and what it should contain. The model follows such instructions reasonably well; this helps most in pair programming and other human-in-the-loop work.

Choosing an effort level - the default is medium, and the levels don't map 1:1 from Claude Opus 5

Effort is the main control for how much Claude Opus 5.5 thinks, and with adaptive-only thinking it is the first setting to adjust when trading off intelligence, latency, and cost. Two things change from Claude Opus 5:

• The API default is medium (Claude Opus 5 and earlier Opus models default to high), so a request that omits effort now runs one level lower than it did. Set effort explicitly and re-run the sweep rather than carrying the Claude Opus 5 setting over. Effort names don't mean the same amount of thinking across models: in Anthropic's testing, Claude Opus 5.5 at medium exceeds Claude Opus 5 at high on coding and knowledge-work evaluations, and on several coding evaluations low comes close to it at much lower cost. Start at medium and test the neighboring levels; reserve xhigh and max for work where you have measured a quality gain (all five levels are supported; max is uncapped).
• At a given level, Claude Opus 5.5 tends to think more per turn than Claude Opus 5, especially at xhigh and max. If you keep the effort value you set for Claude Opus 5, expect longer turns and more output tokens. To get less thinking, lower the effort level before adding "think less" instructions - lowering effort reduces thinking, cost, and latency more reliably than prompting does. Set max_tokens with room for the thinking as well as the reply (thinking counts toward it even though the text isn't returned - a limit sized for Claude Opus 5 with thinking off can cut replies off; 64K is a reasonable starting point for long agentic coding turns).

Change effort for individual turns without invalidating the prompt cache with a per-message effort change (beta mid-conversation-output-config-2026-07-01; the request shape is addition 1 under § New API features of § Migrating to Claude Fable 5.1 from Claude Fable 5, and Claude Opus 5 already supports it). Changing the top-level effort between requests does invalidate the prompt cache.

Safeguards - a broader classifier set than Claude Opus 5

Claude Opus 5.5 runs cybersecurity and biology safety classifiers similar to Claude Fable 5.1's; coming from Claude Opus 5, the biology classifier is new. Everyday health and educational questions are unaffected, but requests the classifier treats as dual-use biology research (virology, toxicology, molecular design) are declined; on the cybersecurity side, finding vulnerabilities in source code is allowed. Separately - also new relative to Claude Opus 5 - a request that tries to get the model to reproduce its internal reasoning in the response text can be declined with stop_details.category: "reasoning_extraction"; if a prompt does this (for example, to get visible reasoning with thinking off), remove the instruction, set display: "summarized", and read the thinking blocks. reasoning_extraction declines are not retried on a fallback model.

A classifier decline arrives as a normal HTTP 200 with stop_reason: "refusal" and a stop_details object naming the category ("cyber", "bio", "reasoning_extraction", ...; branch on stop_reason, treat stop_details as informational - the full handling is § refusal stop reason under § Migrating to Claude Fable 5.1). A refusal before any output still counts against your rate limits; for whether it is billed, see How refusals are billed. Retry on another model with server-side fallbacks - fallbacks: "default" under beta server-side-fallback-2026-07-01 retries on the model Anthropic recommends for that category, the array form under server-side-fallback-2026-06-01 names your own targets (§ New API features under § Migrating to Claude Opus 5 has both shapes; read Claude Opus 5.5's permitted targets from allowed_fallback_models on its /v1/models entry, as § refusal stop reason describes - expect Claude Opus 5 / claude-opus-4-8), the SDK middleware on platforms without server-side fallback, or your own retry. A fallback model runs without Claude Opus 5.5's thinking blocks (breaking change 3). Ship the opt-in from day one, as the Claude Fable 5.1 section says.

The classifiers can still flag benign requests - the fallback opt-in is what keeps a false positive from becoming an outage. (The docs give no prompt change that avoids Claude Opus 5.5's false positives; the Safeguard false positives tips under § Migrating to Claude Fable 5.1 from Claude Fable 5 are documented for Claude Fable 5.1 only - do not offer them for Claude Opus 5.5.)

What carries over unchanged from Claude Opus 5 - and what to re-check

• Feature set: per-message effort (beta), mid-conversation system messages (no header) and tool changes (beta), task budgets, compaction (including the on-demand compaction parameter, beta compact-2026-09-04, which has its own docs), prompt caching with the 512-token minimum, batch processing (up to 300K output tokens with the output-300k-2026-03-24 beta), the Files API, PDF support, vision, structured outputs, strict tool use, and the same server-side and client-side tools - except computer use, which needs the toolset (breaking change 4). Programmatic tool calling lists the model.
• Pricing: $4 / $20 per MTok; 5-minute cache writes $5 and 1-hour cache writes $8; cache reads $0.20 per MTok (0.05x base input); batch $2 / $10. The cache-read discount is deeper than Claude Opus 5's, so long agentic sessions that re-read a cached prefix save more, and a miss costs relatively more - keeping the cache warm (per-message effort, append-only histories, the keep-alive patterns in shared/prompt-caching.md) matters more.
• Rate limits: a separate pool from Claude Opus 5's, with its own per-tier numbers. Re-check your tier's Claude Opus 5.5 limits before moving volume.
• Priority Tier: not supported (as Claude Opus 5).
• Fast mode: research preview on the Claude API only (not Bedrock, Claude Platform on AWS, Google Cloud, or Foundry), speed: "fast" under beta fast-mode-2026-02-01, at $8 / $40 per MTok (2x the standard price, the same multiple as Claude Opus 5's $10 / $50).
• Data retention / ZDR: nothing new is documented - treat Claude Opus 5.5 as Claude Opus 5 here.
• SDK constants: Model.ClaudeOpus5_5 (C#), anthropic.ModelClaudeOpus5_5 (Go), Model.CLAUDE_OPUS_5_5 (Java, PHP), Anthropic::Model::CLAUDE_OPUS_5_5 (Ruby) - published with each SDK's launch release; the bare string "claude-opus-5-5" works everywhere before then.

Capability improvements versus Claude Opus 5

Cheaper per solved task, not just per token. On many coding, analysis, and vision tasks, Claude Opus 5.5 at its default effort matched or beat Claude Opus 5 while using fewer tokens, and its price per token is 20% lower than Claude Opus 5's (60% lower for cache reads) - so expect the cost per solved task to be significantly lower for most tasks, and re-baseline shared/cost-optimization.md's Claude Opus 5 figures rather than scaling them by the list price alone.

• Agentic coding and code review: the largest measured gains are on multistep work in a real codebase (carrying a change through a large repository until its tests pass) - in Anthropic's testing, at its default medium effort it matched or beat Claude Opus 5's high-effort results on such tasks, in fewer steps and with about half the tokens - and on code review, where it catches more bugs with fewer false alarms. It explains its changes in plain language, which makes its work easier to review and trust. It tends to finish the same task with fewer tokens.
• Knowledge work: a more reliable analyst - much less likely than Claude Opus 5 to state a figure or cite a source the inputs don't support (citations pointed at the right source much more often in one customer's measurement); at medium it produced better long analytical deliverables than Claude Opus 5 at high with roughly 40% fewer output tokens; better at building and auditing financial models; more detail-oriented on large inputs (a date in a long thread that falls on the wrong weekday, a chart in a deck that doesn't match the figures) without more false-positive flags.
• Communication and writing: clearer prose, most noticeably in how it reports on agentic work - its updates while it works and its summary when it finishes say plainly what it did, what it found, and what it needs from you, with less jargon and fewer stock phrases.
• Charts, diagrams, screenshots, and computer use: reads visual material more accurately at every effort level without extra tooling - in Anthropic's testing, even at low it read charts more accurately than Claude Opus 5 at its highest effort, at roughly a tenth of the output tokens per chart (Claude Opus 5 read charts well only by running code to crop, zoom, and measure) - values on dense charts, and meaning that depends on position rather than text (which boxes an arrow connects, what changed between two diagram versions, exactly when a meeting starts and ends in a calendar screenshot). Also more reliable at multistep computer use from screenshots: at its default effort it matched the success rate Claude Opus 5 reached only at a much higher effort setting, in fewer steps and with roughly 40% fewer tokens.

Behavioral shifts (prompt-tunable)

• Re-evaluate Claude Opus 5-specific instructions. Instructions tuned for Claude Opus 5's behavior (the verbosity, over-verification, and scope prompts under § Behavioral shifts of § Migrating to Claude Opus 5) may no longer be needed - keep them as the starting point, then re-test each on your own evals rather than carrying them over untouched.

• Progress updates: covered above - render the thinking blocks, and ask in the system prompt for the cadence you want.

• Frontend design defaults: asked for frontend work without design direction, it falls back on a few default styles, and a general instruction such as "avoid a generic AI look" mostly swaps one default for another. It responds well to instructions that name specific patterns to avoid. Work iteratively - look at which styles the first result used instead, and extend the list:

  "Output a vanilla HTML/CSS personal website with placeholder data. Do not use a cream or off-white background, italic accent words in headlines, numbered "01/02/03" section labels, monospace labels, or pill-shaped buttons."

• Ingesting complex visual inputs: it reads charts, diagrams, and screenshots considerably more precisely out of the box, so harness scaffolding built for visual inputs on earlier models may no longer be needed - re-test it. For the densest inputs, two things still add accuracy: higher-resolution images (most of all for technical drawings), and image-processing tools - run it as an agent with a container holding the raw images and libraries such as PIL and OpenCV so it can crop, zoom, measure, and verify; if a container is too much overhead, a cropping tool alone still helps. It uses these tools more effectively at higher effort levels; without tools, raising effort improves its reading of technical drawings but does little for charts.

• Long turns: at xhigh / max, turns run longer than on Claude Opus 5 - plan timeouts, streaming, and progress UX accordingly, and lower effort before prompting for brevity.

Claude Opus 5.5 Migration Checklist

• [BLOCKS] Model ID -> claude-opus-5-5 (Bedrock: anthropic.claude-opus-5-5). Coming from Opus 4.8 or older, the Claude Opus 5 checklist first - except that disabling thinking is not an option.
• [BLOCKS] Remove thinking: {type: "disabled"} and {type: "enabled", budget_tokens} on every route - both 400 at every effort level. Choose an effort level instead; size max_tokens for thinking plus the reply; read content blocks by type; pass thinking blocks back unmodified.
• [BLOCKS] Replace tool_choice any / tool with auto plus strict: true (steering in the prompt, and a check that the call happened) or structured outputs - on count_tokens and Batches too.
• [BLOCKS] Computer use on the Claude API and Google Cloud: declare {"type": "computer_toolset_20260801"} (no beta header, no name / display size) instead of computer_20251124 (Amazon Bedrock still accepts computer_20251124), and update the agent loop for member tool_use blocks (action = block name), batch actions, and toolset_name on every result; confirm the toolset is offered on your platform. Test on Claude Opus 5 first.
• [BLOCKS] If the harness builds messages itself: run the preserved-thinking three-step check (§ Migrating to Claude Fable 5.1 from Claude Fable 5) - accounts created on or after 2026-08-31 are enforced by default on every platform; set prefix_mismatch_behavior explicitly under thinking-binding-controls-2026-08-01 and replace every history edit with its append-only form. Declare from the first request any tool the session may need later.
• [BLOCKS] Handle stop_reason: "refusal" before reading content (new bio and reasoning_extraction categories) and ship a fallback opt-in; reasoning_extraction is not retried on a fallback.
• [TUNE] Set effort explicitly - the default is medium, one level below Claude Opus 5's high - and re-run the sweep including low / medium; lower effort before adding "think less" prompts; reserve xhigh / max for measured gains; use per-message effort (beta) to vary it without a cache reset.
• [TUNE] If the UI showed text between tool calls: display: "updates" (beta) or "summarized", render non-empty thinking blocks; give the model a send-message tool (declared at session start) for verbatim mid-turn content; ask in the system prompt for the update cadence you want.
• [TUNE] If a router or fallback can move the conversation to another model, expect it to run without Claude Opus 5.5's thinking blocks (only Claude Fable 5.1 / Claude Mythos 5.1 on the Claude API keep them).
• [TUNE] If thinking was disabled on Claude Opus 5: start at low, remove reasoning-in-the-response instructions, re-test the thinking-disabled mitigation instruction, delete any "don't think" rule.
• [TUNE] Re-test visual-input scaffolding (may be unnecessary now); for frontend work, name the specific default patterns to avoid rather than asking for "no generic look"; re-evaluate Claude Opus 5-specific verbosity / verification / scope instructions.
• [TUNE] Re-baseline cost and latency at the chosen effort level: $4 / $20, cache reads $0.20 per MTok; separate rate-limit pool; no Priority Tier; fast mode is Claude API only at $8 / $40.

Migrating to Claude Sonnet 5.5

Model ID claude-sonnet-5-5 is authoritative as written here. When the user asks to migrate to Claude Sonnet 5.5, write model="claude-sonnet-5-5" exactly (no date suffix; anthropic.claude-sonnet-5-5 on Amazon Bedrock). Do not WebFetch to verify - this guide is the source of truth for migration target IDs. The corresponding entry exists in shared/models.md.

Claude Sonnet 5.5 succeeds Claude Sonnet 5 in the Sonnet line at the same prices - $2 / $10 per MTok input / output, 5-minute cache writes $2.50, 1-hour cache writes $4, cache reads $0.20, and Claude Sonnet 5's batch rates. Same tokenizer as Claude Sonnet 5 (token counts unchanged), 1M token context window, 128K max output (up to 300K on the Message Batches API with the output-300k-2026-03-24 beta header). Available at launch on the Claude API (claude-sonnet-5-5), Amazon Bedrock (anthropic.claude-sonnet-5-5), Claude Platform on AWS, Google Cloud, and Microsoft Foundry (all three as claude-sonnet-5-5). On Foundry it is hosted on Azure only, with Global Standard deployments only, so the features Foundry doesn't offer when hosted on Azure are unavailable for it there - code execution, programmatic tool calling, Agent Skills, the Files API, and the newer web search and web fetch versions (shared/platform-availability.md). The SDK constants listed below may be missing from the SDK version a project pins; the bare string "claude-sonnet-5-5" works in every SDK (with the anthropic. prefix on Amazon Bedrock). Existing Claude Sonnet 5 prompts should perform well without changes; for the hardest long-horizon work, an Opus model is the better choice.

Claude Sonnet 5.5 is the default Sonnet migration target. It is layered on top of the Claude Sonnet 5 migration above - a caller coming from Sonnet 4.6 or earlier applies § Migrating to Claude Sonnet 5 first (and, from Sonnet 4.5 or earlier, the older sections it points to), except these parts of it, which this section replaces: its thinking: {type: "disabled"} route (breaking change 1 below); its Bedrock-only forced tool_choice with thinking disabled, both halves of which 400 here (breaking changes 1 and 2); its computer_20251124 tool version, which 400s on the Claude API and Google Cloud (breaking change 4); and all of its effort advice - including the high default with xhigh for the hardest work, the level mapping against Sonnet 4.6, the effort suggestions in its behavioral notes, and the prompts to make the model think more or less - because the levels are recalibrated here (§ Choosing an effort level). A caller coming from Claude Haiku 4.5 applies the same sections, including the Sonnet 4.5-or-earlier changes (prefill, explicit effort, beta headers, output_format, parsing tool input with a JSON parser) but not the Sonnet 4-or-earlier ones, then replaces claude-haiku-4-5-20251001 or its alias, re-baselines cost at the higher price per token, and reviews prompts that were too short to cache on Claude Haiku 4.5.

What changes: five breaking changes for code running on Claude Sonnet 5 (disabled thinking 400s - turn thinking off with between_tools instead; forced tool_choice 400s; thinking blocks are tied to the model and the conversation - "preserved thinking"; on the Claude API and Google Cloud the computer_20251124 tool 400s - use the computer toolset; the advisor tool rejects Claude Opus 4.8, Claude Opus 4.7, and Claude Sonnet 5 advisors), one response-shape change that fails no request (text between tool calls comes back in thinking blocks), recalibrated effort levels (the default stays high, but a level no longer produces the same amount of thinking as on Claude Sonnet 5), and safety classifiers that decline in five categories. Breaking changes 2 and 3 are the same mechanisms Claude Fable 5.1 and Claude Opus 5.5 introduced - the shared mechanics are under § Migrating to Claude Fable 5.1 from Claude Fable 5, and this section gives the Claude Sonnet 5.5 specifics.

Breaking change 1: disabled thinking returns a 400 - turn thinking off with between_tools

On Claude Sonnet 5, thinking is on by default and thinking: {type: "disabled"} turns it off. On Claude Sonnet 5.5, {"type": "disabled"} returns a 400 invalid_request_error:

"thinking.type.disabled" is not supported for this model. Use "thinking.type.between_tools" for the lowest thinking setting, or "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

thinking: {"type": "between_tools"} is the lowest thinking setting on this model: the model does no extended thinking, and the short progress updates it writes between tool calls come back as thinking blocks with their summary text. It needs no beta header and works on every platform that offers the model. Its limits, each a 400 invalid_request_error when crossed:

• Effort high or below only. At xhigh or max, use adaptive thinking (omit thinking or send {"type": "adaptive"}). The error reads output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking. - "enable thinking" in this and the next error means adaptive thinking; {"type": "enabled"} is itself a 400.
• No other field inside thinking. display, budget_tokens, or block_binding sent with between_tools is rejected, and manual budgets ({"type": "enabled", "budget_tokens": N}) return a 400 as well.
• Effort can't change mid-conversation. A per-message output_config.effort that differs from the level in effect is rejected (messages.N: output_config.effort 'low' differs from the 'high' in effect before it; ...). To vary effort per turn, use adaptive thinking.
• Claude Sonnet 5.5 only. Any other model rejects it: "thinking.type.between_tools" is not supported for this model. - so client-side code that re-sends the same body to another model (a router or a retry) must drop the field first.

Migrate a route that disables thinking in this order:

1. Try adaptive thinking at low effort first. At low the model keeps its thinking short and skips it on most simple requests. Measure time to first token at the median and the 95th percentile on the caller's own traffic, and compare quality.
2. Otherwise send between_tools at high effort or below. Remove any instruction that tells the model not to think - such instructions make it more likely to write internal XML tags in its visible output.
3. Read the response by block type, not position. With adaptive thinking, a response can begin with a thinking block whose thinking field is empty under the default display: "omitted".
4. Pass thinking blocks back unchanged with the rest of the assistant turn, including the progress-update blocks between_tools returns - a block sent back gives the model the full note it wrote, not the summary.
5. Size max_tokens for thinking as well as the reply. Thinking counts toward max_tokens even when its text isn't returned; for long agentic coding turns, 64,000 is a reasonable starting point.

# Before - accepted on Claude Sonnet 5, 400 on Claude Sonnet 5.5
client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "..."}],
)

# After, preferred - adaptive thinking (the default) at low effort; measure latency and quality
client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    output_config={"effort": "low"},
    messages=[{"role": "user", "content": "..."}],
)

# After, when the route must stay thinking-off - the lowest thinking setting, at high effort or below
client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "between_tools"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

In Python, TypeScript, PHP, and Ruby, write between_tools as a plain value in the thinking object (Ruby: type: :between_tools). In the typed SDKs, send the thinking object as a raw override until their types include between_tools: C# Thinking = new ThinkingConfigParam(JsonSerializer.SerializeToElement(new { type = "between_tools" })); Go params.SetExtraFields(map[string]any{"thinking": map[string]any{"type": "between_tools"}}) on the MessageNewParams value; Java .putAdditionalBodyProperty("thinking", JsonValue.from(Map.of("type", "between_tools"))).

Breaking change 2: forced tool use is rejected

As on Claude Fable 5.1 and Claude Opus 5.5: tool_choice: {"type": "any"} and {"type": "tool", "name": "..."} return a 400 invalid_request_error (tool_choice: type "tool" and "any" are not supported for this model.), including on the token-counting endpoint, where Claude Sonnet 5 accepts both. {"type": "auto"} (the default) and {"type": "none"} are unchanged. Migrate by intent - the patterns are under § Breaking change 1: forced tool use is rejected in § Migrating to Claude Fable 5.1 from Claude Fable 5:

• Steering toward a tool: tool_choice: {"type": "auto"} plus a prompt that says when the tool applies, with strict: true on the tool definition for schema-valid arguments. Because auto does not guarantee a call, check that one was made and retry if it wasn't.
• Extracting structured data: if the forced call existed only to get JSON back, use structured outputs (output_config.format).

Breaking change 3: thinking blocks are tied to the model and the conversation

• Model binding - who reads whose blocks. Claude Sonnet 5.5 reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models - a conversation that moves from Claude Sonnet 5 onto claude-sonnet-5-5 keeps its reasoning - but not from Claude Opus 5, Claude Opus 5.5, or any Claude Fable or Claude Mythos model. No other model reads Claude Sonnet 5.5 blocks, so a router switch, a retry on another model, or a refusal fallback runs the turns after the switch without its reasoning. The API drops what the target can't read before the model sees it: the request succeeds, dropped blocks aren't billed, and with the thinking-binding-controls-2026-08-01 beta header the drop is reported in a top-level input_transformations array. Keep passing blocks back unchanged; don't strip them yourself.
• Conversation binding - the history-editing check. The API checks that the system prompt, the tools, and every earlier message are unchanged since a block was produced. It is enforced by default for accounts created on or after August 31, 2026, 00:00 UTC, on the Claude API and Amazon Bedrock (Google Cloud is not confirmed - check the preserved thinking docs before promising either way): on those accounts a request that replays a block after such an edit is a 400. To drop the affected blocks instead, send the thinking-binding-controls-2026-08-01 beta header and set thinking.block_binding.prefix_mismatch_behavior: "drop_block"; on older accounts, setting that field to either value opts the request in. block_binding works only with thinking: {"type": "adaptive"} - with between_tools, keep the history append-only, or strip the thinking blocks from the edited turn on. The append-only replacements (mid-conversation role: "system" messages, which Claude Sonnet 5.5 supports and Claude Sonnet 5 doesn't; tool_addition / tool_removal; turn-scoped reminders; server-side compaction or context editing) and the three-step check are in § Migrating to Claude Fable 5.1 from Claude Fable 5. With threshold compaction, thinking blocks from before a compaction block aren't carried forward, so the summary is all the model has of that earlier work - if you write your own instructions, say what the summary must retain - and remove the thinking and redacted_thinking blocks from any assistant turn you re-insert after a compaction block (or set drop_block). On-demand compaction (beta compact-2026-09-04) can keep the kept turns' blocks valid after you replace the summarized turns with the returned compaction block.
• Account binding. On Amazon Bedrock and Google Cloud at launch, a block Claude Sonnet 5.5 produced works only in the account that produced it, or in an account linked to it; another account's blocks are dropped and the request succeeds (on Google Cloud, with the thinking-binding-controls-2026-08-01 header, each drop is listed in input_transformations with reason: "organization_binding_mismatch"). Blocks from earlier models aren't affected.

Breaking change 4: computer use needs the toolset on the Claude API and Google Cloud

On the Claude API and Google Cloud, Claude Sonnet 5.5 accepts computer use only as the computer_toolset_20260801 toolset; computer_20251124 returns a 400 (on the Claude API the message begins 'claude-sonnet-5-5' does not support tool types: computer_20251124.). On Amazon Bedrock it still accepts computer_20251124. No platform accepts computer_20250124.

The toolset's request shape and agent-loop changes (no beta header, no name or display size, the action is the member tool_use block's name, several calls per turn, "toolset_name": "computer" echoed on every result) are in shared/tool-use-concepts.md § Computer Use and § Migrating to Claude Opus 5.5 -> Breaking change 4. Code that already sends the toolset needs no change. Two more things to check in the agent loop: don't prune old screenshots on the client - removing an earlier screenshot invalidates every later thinking block (breaking change 3), so resize screenshots to 2000 px or less per side and use server-side tool result clearing instead, or, with adaptive thinking, keep prefix_mismatch_behavior: "drop_block" set from the first prune on; and replace the fine-grained-tool-streaming-2025-05-14 header with eager_input_streaming: true on each tool that needs it - the header returns a 400 alongside a computer use or browser use toolset entry.

Breaking change 5: the advisor tool accepts fewer advisors

With the advisor tool (beta), a Claude Sonnet 5.5 executor needs one of these advisors: Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5, Claude Fable 5.1, Claude Mythos 5, or Claude Mythos 5.1. Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, and Sonnet 4.6 advisors return a 400. Every accepted advisor returns its advice encrypted, as an advisor_redacted_result block, so the advice text isn't readable in the response. Because the executor rejects forced tool_choice, nudge a consult from the prompt rather than forcing the advisor tool.

Text between tool calls comes back in thinking blocks

On Claude Sonnet 5, text the model writes between tool calls comes back as text blocks. On Claude Sonnet 5.5, notes longer than a sentence or two come back as progress-update thinking blocks, empty under the default display: "omitted"; shorter remarks stay text. No request fails, but a client that renders only text blocks goes quiet between tool calls. With adaptive thinking, set thinking.display: "updates" (beta thinking-display-updates-2026-08-18) to get the updates alone, or "summarized" to get them mixed with reasoning summaries; render each non-empty thinking block before the tool_use block that follows it, and pass the blocks back unchanged. With between_tools, the notes come back with their text and no display field is needed (or allowed).

If the interface doesn't render thinking blocks and the model may need to show the user something word for word mid-turn (a code snippet, a question), give it a simple tool for sending the user a message, tell it to reserve that tool for such content, and declare it in the first request of the session so the tools list doesn't change later (breaking change 3). Remove older instructions such as "hold all findings for the final response"; if updates are then wanted at predictable points, add a line that says when user-facing text is wanted and what it should contain - the model follows it - for example:

"Before you start, say in a line what you're about to do; brief updates while you work help the user follow along. Close with a short recap that stands on its own so a reader who only sees the last message has the full picture."

If long tool-calling turns still go quiet for too long, the harness can prompt an update: count consecutive tool-calling steps with no user-facing text or progress update, and after several in a row (for example five) append a one-turn reminder after the latest tool results as a turn-scoped system message (clear_at: "next_user_message", beta mid-conversation-system-clear-at-2026-08-21 - § Migrating to Claude Fable 5.1 from Claude Fable 5). If the turn stays quiet, stop after two or three reminders; text after every tool result can make the model suspect a prompt injection (§ Behavioral shifts -> Mid-turn user messages). Because the reminder is appended, never inserted and later deleted, the cache and preserved thinking stay intact. In Anthropic's testing at high effort, with a send-message tool available, it made the model update the user more often and shortened its longest silent stretches, with no measurable change in task quality:

"The user hasn't heard from you in a while - say in a few words what you're doing, then continue."

Choosing an effort level - recalibrated levels, default still high

Claude Sonnet 5.5 supports low, medium, high, xhigh, and max; the Claude API default is high. The levels are recalibrated: a level doesn't produce the same amount of thinking as the same level on Claude Sonnet 5, so re-run the effort sweep against the caller's own evals rather than carrying the Claude Sonnet 5 setting over, and set output_config.effort explicitly.

• Starting points: medium for agentic coding and multistep tool use; low for chat, content generation, classification, extraction, and search. Reserve xhigh and max for work with a measured quality gain - at those levels thinking can't be turned off. At low, on long agentic tasks the model is more likely than at higher levels to stop and check in with the user before finishing, or to skip verifying a change (§ Behavioral shifts -> Verification on coding tasks).
• Judge cost per completed task, not per token. In Anthropic's testing it finishes agentic coding and multistep tool-use work in far fewer model requests than Claude Sonnet 5, and generates output faster. On most agentic coding evals it scored higher at medium than Claude Sonnet 5 did at high, typically at under a fifth of the cost; on computer use at high it completed substantially more tasks than Claude Sonnet 5 at its highest effort, with under a third of the tokens.
• To get less thinking, lower the effort level. From medium up, the model thinks briefly before almost every reply, even a greeting, which adds to the time before the first visible token, and a system-prompt request to think less has almost no effect at those levels. At low, it skips thinking on most simple requests.
• Keep the cache warm when varying effort. Changing the top-level effort between requests invalidates the prompt cache; a per-message effort change (beta mid-conversation-output-config-2026-07-01; request shape under § New API features of § Migrating to Claude Fable 5.1 from Claude Fable 5) keeps it - for example, run an interactive session at low and raise effort to high for a hard problem. Per-message effort needs adaptive thinking; with between_tools it is a 400.

Safeguards and fallback

Claude Sonnet 5.5 declines in more categories than Claude Sonnet 5. A decline is a normal HTTP 200 with stop_reason: "refusal" and a stop_details category: "cyber" (could enable cyber harm, such as malware or exploit development - finding vulnerabilities in source code is allowed), "bio" (could enable biological harm), "frontier_llm" (could assist the development of competing AI models), "reasoning_extraction" (asks the model to reproduce its internal reasoning in the response text), and "general_harms" (another usage-policy area - benign work can also trigger it). Branch on stop_reason before reading content (handling: § refusal stop reason under § Migrating to Claude Fable 5.1). Server-side fallback (fallbacks: "default", beta server-side-fallback-2026-07-01, Claude API only) retries "cyber" and "frontier_llm" declines on Claude Sonnet 5; it doesn't retry "bio", "reasoning_extraction", or "general_harms" declines. The SDK middleware or your own retry are the alternatives; a fallback model runs without Claude Sonnet 5.5's thinking blocks (breaking change 3), and a client-side retry must drop between_tools (breaking change 1); with server-side fallback, a between_tools request that falls back to Claude Sonnet 5 runs there with thinking: {"type": "disabled"}. Whether a refusal that arrives before any output is billed depends on its refusal category, and it counts against rate limits either way. Real-time cyber safeguards are new for code coming from Sonnet 4.6, Sonnet 4.5, and Haiku 4.5 - for legitimate security work, point the user to the Cyber Verification Program. The biology safeguards are the same as Claude Sonnet 5's and leave everyday health and educational questions unaffected; if the bio classifier gets in the way of an organization's life-sciences work, it can apply to the Life Sciences Verification Program. If a prompt asks the model to write out its reasoning as a substitute for thinking, remove that instruction (it invites reasoning_extraction declines) and read display: "summarized" blocks instead.

What carries over, and what is new versus Claude Sonnet 5

• New on Claude Sonnet 5.5: mid-conversation system messages (no beta header), mid-conversation tool changes (beta), per-message effort (beta), task budgets (beta task-budgets-2026-03-13 - but see § Behavioral shifts on interactive sessions), and tool definitions inside a mid-conversation message (beta inline-tools-2026-09-15) - none is available on Claude Sonnet 5.
• Prompt caching: the minimum cacheable prompt is 512 tokens, down from 1,024 on Claude Sonnet 5 (check the prompt caching docs before quoting the exact value).
• Carries over: batch processing, the Files API, PDF support, vision, structured outputs, strict tool use, threshold compaction, compaction on demand (beta compact-2026-09-04), and the server-side and client-side tools (computer use as in breaking change 4; on Microsoft Foundry, only what it offers when hosted on Azure).
• Rate limits and tiers: its own rate-limit pool, separate from Claude Sonnet 5's and from the combined Sonnet 4.x pool - re-check the tier's Claude Sonnet 5.5 limits before moving volume. Priority Tier is not supported (as on Claude Sonnet 5).
• SDK constants (where the pinned SDK has them; the bare string always works): Model.ClaudeSonnet5_5 (C#), anthropic.ModelClaudeSonnet5_5 (Go), Model.CLAUDE_SONNET_5_5 (Java), Model::CLAUDE_SONNET_5_5 (PHP), Anthropic::Model::CLAUDE_SONNET_5_5 (Ruby).

Behavioral shifts (prompt-tunable)

None of these break code. Re-evaluate Claude Sonnet 5-specific prompt instructions against them after the effort sweep:

• Remove workarounds for what got better. The model is strongest on multistep agentic coding in a real repository, uses connected tools more reliably in agentic workflows, declines fewer benign requests, and holds a system-prompt role more reliably when a user pastes in a competing persona. If the Claude Sonnet 5 prompts carry workarounds for these - refusal steering, tool-call retry shims, instructions like "do not be lazy" - remove them and re-run the evals before tuning anything else.
• Tool use in chat and knowledge work. On chat and knowledge-work tasks the model sometimes answers from its own knowledge or from public web results when a connected tool, skill, or internal search would serve better, and can hold off on tools until asked directly. Remove language that discourages tool use ("only use tools when strictly necessary", "minimize tool calls" - it follows these literally). Where the product should prefer connected sources (enterprise search, account research, support agents), add: "Use the search tool to check specifics that may have changed since your training, such as what is allowed, required or charged, even when you feel confident. For researched work such as a report or a comparison, gather current sources rather than writing from your training knowledge."
• Mid-turn user messages and task budgets. The model pays close attention to where text sits relative to a tool result: a message the user typed mid-task that arrives as a mid-conversation system message placed directly after a tool result, or inside a tool_result block, can be read as a prompt-injection attempt (the model says so and usually ignores it or waits for confirmation). Task budgets can cause this, because the budget countdown arrives as a system message after every tool result, and so can any harness text added after the tool results on every step (a token countdown, per-step instructions or context); an occasional one-turn reminder arrives far less often - if one draws this reaction, send it less often. Deliver mid-turn user input as a user turn - a text block in the user message that carries the tool_result blocks, after the last tool_result; keep harness notices (budget countdowns, background-task completions, reminders) in a separate mid-conversation system message that follows, never in the same block as the user's words; never put user text inside a tool_result block; and on interactive sessions don't use a task budget (control cost with effort and max_tokens; keep task budgets for unattended agentic loops).
• Verification on coding tasks. Mostly at low effort, the model sometimes reports a code change as done without a check that exercises it (no npm install, so the tests and type-checker never ran; only a syntax check; stopping silently when a build tool is missing). If a coding agent runs at low, or changes are reported complete without test or build output, add to the system prompt: "When you change code that can be run, built, or type-checked, run a real check that exercises the change before reporting it done: the project's tests, type-checker, or build, or the changed command itself. A syntax-only check, or a check command that failed to start, does not count; if all that is missing is the project's declared dependencies, install them with its own package manager (e.g. npm install, pip install -r requirements.txt) unless told not to. Only if no real check can run here, say which one you did not run and why instead of reporting the change as done."
• Tolerant tool-call handling. The model occasionally calls a declared tool by a name that differs only in letter case (bash for Bash), or passes a known parameter under a slightly different name. Don't treat that as fatal: accept the call when the match is unambiguous, or return a tool_result with is_error: true that states the exact expected name - the model usually corrects the call on its next turn.
• Dense charts and technical drawings. Give the model a way to crop, zoom, or run code on the image; it reads them markedly more accurately with such tools. On charts the tools help at every effort level and more than raising effort does (with tools at high it read charts more accurately than without them at max, at a fraction of the cost); on technical drawings they help only from high up, most at xhigh and max.
• Follow-up turns in multi-turn chat. If the model should treat its earlier answers as settled rather than going back over them when it thinks about a new message, add at the end of the system prompt: "Once Claude has answered something, Claude treats that answer as done. On later turns Claude's thinking goes to what the person is asking now, and Claude doesn't go back over an earlier answer unless the person asks about it or points out a problem with it." Leave it out where earlier work should keep being re-examined - long analyses, or agentic tasks where a later step can reveal a mistake in an earlier one.

Claude Sonnet 5.5 Migration Checklist

• [BLOCKS] Update the model= string to claude-sonnet-5-5 (anthropic.claude-sonnet-5-5 on Amazon Bedrock); no date suffix.
• [BLOCKS] Replace thinking: {type: "disabled"}: try adaptive thinking at low effort first; where the route must stay thinking-off, send {type: "between_tools"} at effort high or below, with no other field in thinking and no per-message effort change; drop it from any request client-side code re-sends to another model.
• [BLOCKS] Coming from Sonnet 4.6 or earlier or from Haiku 4.5: replace budget_tokens with an effort level and remove non-default temperature / top_p / top_k; from Sonnet 4.5 or earlier or Haiku 4.5, also replace assistant prefills.
• [BLOCKS] Read content blocks by type (a response can begin with thinking blocks) and pass thinking blocks back unchanged; size max_tokens for thinking plus the reply.
• [BLOCKS] Replace tool_choice any / tool with auto plus strict: true (steering in the prompt, and a check that the call happened) or structured outputs - on count_tokens too.
• [BLOCKS] If the harness builds messages itself: keep it append-only and run the preserved-thinking three-step check (§ Migrating to Claude Fable 5.1 from Claude Fable 5) - new accounts are enforced by default on the Claude API and Amazon Bedrock; block_binding needs adaptive thinking.
• [BLOCKS] On the Claude API and Google Cloud, move computer use to computer_toolset_20260801 and update the agent loop; on Amazon Bedrock send computer_20251124.
• [BLOCKS] Advisor tool: pair the executor with an accepted advisor (not Claude Opus 4.8 / 4.7 / 4.6, Claude Sonnet 5, or Sonnet 4.6) and expect encrypted advisor_redacted_result advice.
• [BLOCKS] Handle stop_reason: "refusal" before reading content (five categories) and configure fallback; only cyber and frontier_llm declines are retried by server-side fallback.
• [TUNE] Re-run the effort sweep and set effort explicitly (start at medium for agentic coding, low for chat); lower effort rather than prompting for less thinking; use per-message effort to vary it without losing the cache.
• [TUNE] If the UI showed text between tool calls: display: "updates" (beta) or "summarized" with adaptive thinking, render non-empty thinking blocks; declare any send-message tool at session start; remove "hold all findings" instructions; if turns still go quiet, a turn-scoped reminder after about five silent steps, at most two or three times.
• [TUNE] Prompts: remove workarounds (refusal steering, tool-call retry shims, "do not be lazy") and tool-discouraging language; deliver mid-turn user input as a user turn and drop task budgets on interactive sessions; add the verification paragraph for low-effort coding agents; accept or correct near-miss tool names instead of failing; give crop/zoom/code tools for dense charts and drawings; the settled-answers line for multi-turn chat where it fits.
• [TUNE] Re-baseline cost and latency at the chosen effort level (same prices as Claude Sonnet 5; own rate-limit pool; no Priority Tier).

Verify the Migration

After updating, spot-check that the new model is actually being used. Replace YOUR_TARGET_MODEL with the model string you migrated to (e.g. claude-fable-5-1, claude-opus-5-5, claude-opus-5, claude-opus-4-8, claude-opus-4-7, claude-sonnet-5-5, claude-sonnet-5, claude-sonnet-4-6, claude-haiku-4-5) and keep the assertion prefix in sync:

YOUR_TARGET_MODEL = "claude-opus-5-5"  # or "claude-opus-5", "claude-opus-4-7", "claude-sonnet-5-5", "claude-sonnet-5", "claude-sonnet-4-6", "claude-haiku-4-5"
response = client.messages.create(model=YOUR_TARGET_MODEL, max_tokens=64, messages=[...])
assert response.model.startswith(YOUR_TARGET_MODEL), response.model

Prefix collision: claude-opus-5-5 starts with claude-opus-5, so when your target is claude-opus-5, also assert not response.model.startswith("claude-opus-5-5"). The same holds for Sonnet: claude-sonnet-5-5 starts with claude-sonnet-5, so a claude-sonnet-5 check also asserts not response.model.startswith("claude-sonnet-5-5").

For rate-limit headroom changes, pricing, or capability deltas (vision, structured outputs, effort support), query the Models API:

m = client.models.retrieve(YOUR_TARGET_MODEL)
m.max_input_tokens, m.max_tokens
m.capabilities["effort"]["max"]["supported"]

See shared/models.md for the full capability lookup pattern.

Ground the migration with an eval

A spot-check confirms the new model answers; it doesn't confirm the app still behaves the way the user wants. When the user reports a behavioral regression on the new model - e.g. "it refuses things the old one handled fine", "tool calls dropped off after the swap", "responses got twice as long" - don't tune the prompt by feel. Read shared/evals/build-eval.md and build a small eval that captures the regression, then read shared/evals/eval-hillclimb.md to iterate the prompt or harness against that eval until the score moves. Grounding the fix in an eval keeps the migration decision honest and leaves the user with a regression test for the next model swap.