One read of Claude Developer Platformapi-20261111T173709Z
134 pages moved out of 901 read.
Pages moved
134
significant first
Pages read
901
in this capture
Captured
17:37 UTC
Corpus hash
1ddc0440424a
corpus-hash
What this read moved
51-75 of 134, page 3 of 6This capture is too large to show at once. Changes 51-75 of 134 are below, significant first; the rest are on the following screens.
build-with-claude/prompt-engineering/claude-prompting-best-practices Changed · +3 / -3 lines
from line 20
2020
2121| Model | Guide | What’s different |
2222| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
23| Claude Fable 5.2 and Claude Mythos 5.2 | [Prompting Claude Fable 5.2](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2) | Differences from earlier models: effort calibration, finishing long tasks, approvals, code ownership, user-facing progress updates, subagent delegation, caution that builds up, instructions written for earlier models, final reports, and safeguard refusals. |
23| Claude Fable 5.2 and Claude Mythos 5.2 | [Prompting Claude Fable 5.2](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2) | Differences from earlier models: effort calibration, finishing long tasks, approvals, code ownership, user-facing progress updates, subagent delegation, caution that builds up, prompts and harnesses designed for earlier models, final reports, and safeguard refusals. |
2424| Claude Fable 5.1 and Claude Mythos 5.1 | [Prompting Claude Fable 5.1](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1) | Differences from Claude Fable 5: effort levels, finishing long tasks, user-facing progress updates, passing thinking blocks back unchanged, tool-call batching in agent loops, search triggering at low effort, formatting, and writing density. |
2525| Claude Fable 5 and Claude Mythos 5 | [Prompting Claude Fable 5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5) | Differences from Claude Opus 4.8: effort levels, instruction following, long-run progress claims, memory systems, and the `reasoning_extraction` refusal category. |
2626| Claude Sonnet 5.5 | [Prompting Claude Sonnet 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5) | Differences from Claude Sonnet 5: effort calibration, initiative and scope, running without up-front thinking, JSON output on reasoning tasks, user-facing progress updates, tool use in chat, mid-turn user messages, verification on coding tasks, tool-call handling, complex visual inputs, and safeguard refusals. |
from line 1139
11391139
114011406. **Tune anti-laziness prompting:** If your prompts previously encouraged the model to be more thorough or use tools more aggressively, reduce that guidance. Claude 4.6 models are more proactive and might overtrigger on instructions that were needed for previous models.
11411141
11427. **Pass thinking blocks back unchanged and keep history append-only:** Append each assistant turn exactly as the API returned it, thinking blocks included. On Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, editing earlier messages, rebuilding `system` or `tools`, or summarizing older turns in place between requests [invalidates every later thinking block](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation). Move those changes to mid-conversation system messages and server-side context management. See [Keep the conversation history append-only](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#keep-the-conversation-history-append-only).
11427. **Pass thinking blocks back unchanged and keep history append-only:** Append each assistant turn exactly as the API returned it, thinking blocks included. On Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, editing earlier messages, rebuilding `system` or `tools`, or summarizing older turns in place between requests [invalidates every later thinking block already in the history](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation). Move those changes to mid-conversation system messages and server-side context management. See [Keep the conversation history append-only](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#keep-the-conversation-history-append-only).
11431143
11441144For detailed migration steps, see the [Migration guide](https://platform.claude.com/docs/en/about-claude/models/migration-guide).
11451145
from line 1151
11511151
11521152<CardGroup cols={2}>
11531153 <Card title="Prompting Claude Fable 5.2" icon="terminal" href="https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2">
1154 Behavioral differences and prompting patterns for Claude Fable 5.2, covering effort, finishing long tasks, approvals, code ownership, progress updates, subagents, caution that builds up, instructions written for earlier models, final reports, and safeguard refusals.
1154 Behavioral differences and prompting patterns for Claude Fable 5.2, covering effort, finishing long tasks, approvals, code ownership, progress updates, subagents, caution that builds up, prompts and harnesses designed for earlier models, final reports, and safeguard refusals.
11551155 </Card>
11561156
11571157 <Card title="Prompting Claude Fable 5.1" icon="terminal" href="https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1">
build-with-claude/prompt-engineering/prompting-claude-fable-5-2 Changed · +106 / -102 lines
### Modify your harness ### Signal intent ### Update system prompt instructions ## Review prompts and harnesses designed for earlier models ## Review instructions written for earlier models
from line 1
11---
22title: Prompting Claude Fable 5.2
33url: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2
4description: "Prompting patterns specific to Claude Fable 5.2 and Claude Mythos 5.2: effort, early stopping, approvals, code ownership, progress updates, subagents, caution that builds up, instructions written for earlier models, final reports, and refusals."
4description: "Prompting patterns specific to Claude Fable 5.2 and Claude Mythos 5.2: effort, early stopping, approvals, code ownership, progress updates, subagents, caution that builds up, prompts and harnesses designed for earlier models, final reports, and refusals."
55---
66
7This guide covers the prompting patterns specific to Claude Fable 5.2. For the model’s capabilities and API changes, see [What’s new in Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2). For techniques that apply across all current Claude models, see [Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices).
7This guide covers the prompting patterns specific to Claude Fable 5.2. For the model’s capabilities and API changes, see [What’s new in Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2) and the [Claude Fable 5.2 and Claude Mythos 5.2 migration guide](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide). For techniques that apply across all current Claude models, see [Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices).
88
9Claude Fable 5.2 behaves differently from earlier models in a few ways. Start with the section that matches what you observe:
9Claude Fable 5.2 has a handful of behavioral differences from earlier models that are worth knowing about. Start by exploring the section that matches what you observe:
1010
11* Unsure which effort level to run, or easy requests take too long: [Calibrate effort](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#calibrate-effort)
11* Unsure which effort level to run, or easy requests start slowly: [Calibrate effort](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#calibrate-effort)
1212* A turn ends before the work is done: [Finish the whole task](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#finish-the-whole-task)
13* You approve steps as the agent works, or your system prompt has approval rules: [Approvals](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#approvals)
14* A coding agent repeats existing code instead of merging it, or reports nearby problems without fixing them: [Say who owns the code](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#say-who-owns-the-code)
13* A coding agent copies existing code, or reports problems and leaves them: [Say who owns the code](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#say-who-owns-the-code)
1514* Long agentic turns look silent: [Keep users informed during long turns](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#keep-users-informed-during-long-turns)
1615* Agent sessions start more subagents than the task needs: [Set expectations for subagents](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#set-expectations-for-subagents)
17* Agents ask for approvals they don’t need, or hold back routine work: [Keep caution from piling up](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#keep-caution-from-piling-up)
18* You carry over a system prompt, skills, or a harness written for Claude Fable 5.1 or Claude Opus 5.5: [Review instructions written for earlier models](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#review-instructions-written-for-earlier-models)
16* Agents ask for approvals they don’t need, or hold routine work: [Keep caution from piling up](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#keep-caution-from-piling-up)
17* Your system prompt, skills, or harness was written for Claude Fable 5.1 or Claude Opus 5.5: [Review prompts and harnesses designed for earlier models](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#review-instructions-written-for-earlier-models)
1918* Your users read final reports or handoffs after long tasks: [Make reports easy to follow](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#make-reports-easy-to-follow)
2019* Requests return `stop_reason: "refusal"`: [Safeguard refusals](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#safeguard-refusals)
2120
2221<Note>
23 For the API changes when you migrate from an earlier model, see the [Claude Fable 5.2 and Claude Mythos 5.2 migration guide](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide). For the order in which to apply this guidance when you migrate, see [Where to start](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#where-to-start).
22 For the order in which to apply this guidance when you migrate, see [Where to start](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#where-to-start).
2423
2524 Several sections on this page suggest text to add to your system prompt, lines to remove from it or from the notes and rules your agents carry, or changes to a tool description. Make these changes in new conversations only. On Claude Fable 5.2, the API enforces the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check) for every account. A request that sends thinking blocks back after `system`, `tools`, or an earlier message changed can return a 400 error, so a stored conversation resumed with the new text can fail. To change instructions partway through a conversation, [put them in the newest turn](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#changing-context). Where [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) are available, you can instead [append a system message to the conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#new-instructions).
2625</Note>
from line 26
2726
2827## Calibrate effort
2928
30Start at `high`, the default on the Claude API. If your use case calls for it, move effort up or down, and test each change against your own evals. The [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level sets how much Claude Fable 5.2 thinks, how long a turn takes, and how many tokens it uses. Tune effort alongside your prompt, because the level also changes the way the model thinks and how many tool calls it makes.
29With Claude Fable 5.2, the [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level sets how much the model thinks, how many tool calls it makes, how long a turn takes, and how many tokens it uses. Tune the effort level alongside your prompt.
3130
32In general, effort levels run in the same order across Claude models, but the amount of thinking behind each level can differ from model to model. So rerun your effort sweep instead of carrying over a setting you tuned on Claude Fable 5.1 or Claude Opus 5.5.
31Start at `high`, the default for Claude Fable 5.2 on the Claude API. Depending on the use case, you might move effort up or down, testing against your own evals. Effort levels rank the same way across Claude models, but the amount of thinking at each level can differ. So, rerun your effort sweep rather than carrying over a setting you tuned on Claude Fable 5.1 or Claude Opus 5.5.
3332
34Choose a level by the kind of work:
35
36* `low` suits quick back-and-forth, well-specified tasks, and high-volume workloads, such as fast, intelligent subagents. In Anthropic’s testing, the model’s scores at `low` sat close to Claude Fable 5.1’s scores at higher effort levels.
33* `low` suits quick back-and-forth, well-specified tasks, and high-volume workloads (intelligent and fast subagents, for example). On coding evaluations, Claude Fable 5.2 performs better than past models at `low` effort. In Anthropic’s testing, it scored close to what Claude Fable 5.1 did at higher effort.
3734* `medium` suits interactive coding, chat, and everyday knowledge work.
3835* `high` suits hard coding, research, agentic work, and long unattended runs. Turns take noticeably longer to finish than at `medium`.
39* `xhigh` is for your hardest long-running coding and agentic work, where you’ve measured a gain. On Anthropic’s internal coding evaluations, it raised scores slightly and used many more tokens.
40* `max` is for measuring the model’s ceiling, or for the rare task where time and tokens don’t matter. It best suits open-ended problems, such as scientific discovery and mathematics. Turns are slow and use many more tokens than at `xhigh`.
36* `xhigh` is for your hardest long-running coding and agentic work where you’ve measured a gain. It raised scores slightly on Anthropic’s internal coding evaluations and used many more tokens.
37* `max` is for measuring the model’s ceiling or for the rare task where time and tokens don’t matter. It is most reasonable to use `max` for open-ended problems such as scientific discovery and mathematics. Turns are slow and use many more tokens than at `xhigh`.
4138
42Most of the gain in capability is already present at `high`. The step from `medium` to `high` raised scores on most of the coding and knowledge-work evaluations that Anthropic tracks. That step also uses more tokens and more time, so move down to `medium` wherever your evals show that quality holds. Above `high`, gains are uneven and depend on the task.
39You get most of the capability gain when using `high` effort. The step from `medium` to `high` raised scores on most of the coding and knowledge-work evaluations that Anthropic tracks. That step also uses more tokens and more time, so move down to `medium` wherever your evals hold. Above `high`, gains are uneven and task-dependent.
4340
44When you choose a level, note three behaviors:
41For agentic work at `low` or `medium`, add the text in [Finish the whole task](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#finish-the-whole-task). The model is more likely to stop early at lower effort levels.
4542
46* The model is more likely to stop early at lower effort levels. For agentic work at `low` or `medium`, add the text in [Finish the whole task](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#finish-the-whole-task).
47* At `high` and above, the model thinks before almost every reply, including a reply to a greeting. If easy requests take too long or cost too much, use a lower effort level for those turns. In Anthropic’s testing, an instruction to answer directly without deliberating didn’t stop the model from thinking at `medium` and above.
48* Effort barely changes how long the model’s replies are. To change the length and tone of a reply, use your prompt.
43At `high` and above, the model thinks before almost every reply, including a reply to a greeting. If you find basic requests taking a while or costing you more, use a lower effort for those turns. In Anthropic’s testing, an instruction to answer directly without deliberating didn’t stop the model from thinking at `medium` and above.
4944
50You can also mix levels in one workflow. For example, you might plan and iterate with the model at `medium`, then raise effort for the long, unattended part. To change levels within a conversation and keep the prompt cache, use a [per-message effort change](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) (beta, `mid-conversation-output-config-2026-07-01` header); that section lists the platforms where it’s available. A change holds until another one replaces it. Where per-message effort isn’t available, set a new top-level `effort` value on the next request, which starts the cache over.
45Effort has little effect on the length of assistant turn responses. Use prompting to change the length and tone of replies.
5146
47You can also mix levels in one workflow. For example, you might plan and iterate with the model at `medium`, then raise effort for the long, unattended part. To change levels within a conversation and keep the prompt cache, use [Per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) (beta, `mid-conversation-output-config-2026-07-01` header). That page lists the platforms where it’s available. A change holds until another one replaces it. Where per-message effort isn’t available, set a new top-level `effort` value on the next request, which starts the cache over.
48
5249## Finish the whole task
5350
54On long, multistep tasks, Claude Fable 5.2 sometimes ends a turn before the work is done. The turn closes with a list of what remains, an offer to continue, or a stop at an ordinary obstacle such as a timeout. This occurs more often at `low` and `medium` effort.
51On long, multistep tasks, Claude Fable 5.2 sometimes ends a turn before the work is done. It might end the turn by listing what’s left to be done, offering to continue, or stopping at an ordinary obstacle such as a timeout. This happens more often at `low` and `medium` effort.
5552
5653If you see these stops in your agent, add text like this to your system prompt:
5754
from line 63
6663If someone clearly decided something is a hard blocker, such as a file marked not to be touched, access that was intentionally withheld, or a safety guardrail, leave it alone, say plainly what you found, and look for another safe way to finish the task. Stopping before the task is complete is very rarely merited, as in when the task can't move forward without user input, or where the blocker is deliberate and should not be worked past. This does not override the need for confirmation on risky or destructive actions.
6764```
6865
69This text separates two kinds of obstacle. It tells the model to diagnose and work through ordinary obstacles, such as errors, timeouts, and failing tools. It tells the model to leave deliberate blockers alone, such as a file marked not to be touched, and to report them. Treat the text as a starting point, and keep that distinction when you adapt it to your application.
66This prompt tells Claude that ordinary obstacles, such as errors, timeouts, and failing tools, should be diagnosed and worked through. Deliberate blockers, such as a file marked not to be touched, are to be left alone and reported. Treat this as a starting point and adapt the prompt further for your use case.
7067
71Anthropic replayed recorded sessions from an agentic coding product at `medium` effort. With a version of this text, about half as many sessions ended with doable work left. The text removed most endings that ask permission or offer to continue, but not endings that list what remains and then stop. Output tokens rose by about 30 percent.
68In testing, Anthropic replayed recorded sessions from an agentic coding product at `medium`. With a version of this text, about half as many sessions ended with unfinished work that could have been continued. It removed most endings that ask permission or offer to continue, but not endings that list what remains and then stop. Output tokens rose by about 30 percent.
7269
7370Because the model asks less often with this text, keep your own confirmation step for risky or irreversible actions.
7471
7572### Approvals
7673
77When you tell the model to keep going, say clearly what you want from it instead of sending a bare “continue.” For example, reply “Yes, run the migration on the staging database” where you might have sent “go” or a thumbs-up.
74When you ask the model to keep going, say exactly what you want rather than sending a simple “continue.” For example, reply “Yes, run the migration on the staging database” where you might have sent a “go” or a thumbs-up.
7875
79If your system prompt has approval rules, name the exact actions they cover, because the model applies them as written. In Anthropic’s testing on simulated tasks with nobody there to approve, one rule listed “sending messages to people outside this conversation” among the steps that need approval. With that rule, the model held back roughly half of its routine requests to colleagues and other teams.
76If you also write approval rules into your system prompt, be specific about the actions you want double-checked. In Anthropic’s testing on simulated tasks where nobody was there to approve, a rule that listed “sending messages to people outside this conversation” among the steps that need approval led the model to hold back about half of its routine requests to colleagues and other teams.
8077
8178## Say who owns the code
8279
83Claude Fable 5.2 responds closely to what the prompt says about who owns the code it works on. In Anthropic’s testing on small coding tasks, when a prompt said nothing about ownership or presented the code base as someone else’s, the model tended to add to the existing structure, even when that repeated existing code. It also tended to report nearby problems instead of fixing them. When the prompt says the code base is the model’s own, the model often merges repeated code and makes related fixes without being asked.
80Claude Fable 5.2 pays close attention to who owns the code it works on. In Anthropic’s testing on small coding tasks, the model tended to add to the existing structure when the prompt said nothing about ownership or presented the code base as someone else’s, even when that duplicated existing code. When the prompt said the code base was the model’s own, it often consolidated duplicated code and sometimes made related fixes without being asked.
8481
8582If you want the model to improve the structure as it works, say that the code is its own:
8683
8784```text wrap
88This codebase is yours: what it's for and how it's built are your call, and you'll keep building on it.
85You are the owner and long-term maintainer of this codebase, and its design is up to you.
8986```
9087
91In Anthropic’s testing on small coding tasks, the model merged repeated code in about half of the tries with this sentence, and in under a tenth of the tries without it. The rate varied by task. The result held when the sentence stood inside a long system prompt. The requested feature worked in nearly every try either way.
88The ownership sentence makes the model much more likely to consolidate duplicated code into one shared function. In Anthropic’s testing on small coding tasks, the model consolidated duplicated code in under 10 percent of runs without the sentence and in about 75 percent of runs with it.
9289
93In the same testing, the model also used about 1.5 times the output tokens with the sentence and made several changes that nobody had asked for, many of them new tests and documentation. Apart from bug fixes, it changed how an existing feature behaves in one try in six to ten, and more often at higher effort. Its closing summary named the larger changes but often left out small ones, so review the diff and not only the summary.
90When using this prompt, output tokens rose by about 70 to 80 percent and the model made changes nobody had asked for, many of them new tests and documentation. In some runs, it also changed how an existing feature behaves. A closing PR summary from Claude Fable 5.2 often left out small changes, so review the reported diff and the summary.
9491
95Leave the ownership sentence out where the user owns the code and wants it changed as little as possible. A rule elsewhere in the prompt that limits scope doesn’t cancel the ownership sentence. In Anthropic’s testing, with “No drive-by refactors, renames or cleanups” earlier in the same prompt, the model still merged repeated code in about a third of the tries.
92Leave the ownership sentence out where the user owns the code and wants it changed as little as possible. A rule that limits scope doesn’t cancel it. In Anthropic’s testing, the model still consolidated duplicated code in more than half of runs when “No drive-by refactors, renames or cleanups” appeared earlier in the same prompt.
9693
9794## Keep users informed during long turns
9895
99Claude Fable 5.2 sometimes writes little user-facing text during long runs of tool calls. The model might also make its first tool call without saying what it’s about to do.
96Sometimes Claude Fable 5.2 writes little user-facing text during long runs of tool calls. Additionally, the model might make its first tool call without saying what it’s about to do.
10097
10198First, check that your client receives the model’s updates. On Claude Fable 5.2, the updates the model writes between tool calls come back as [progress-update `thinking` blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates). These updates say what the model found and what it’s doing next. Their text is empty at the default `thinking.display` of `"omitted"`. So a client that renders only `text` blocks can look silent during a long agentic turn. Set `display: "updates"` (beta, `thinking-display-updates-2026-08-18` header) to receive a short summary of each update, or `"summarized"` to receive the updates along with summarized reasoning. Then render the non-empty `thinking` blocks between tool calls.
10299
103Frequent updates matter most when a user watches the work in real time, as in interactive coding. If your users watch the work and still get too few updates, use one or more of these options.
100Frequent updates matter most in interactive settings. If that is your use case, try the following:
104101
105If you can change your harness, an effective option is to have it count consecutive tool-calling steps that give the user nothing to read: no `text` block and no `thinking` block with text. Count with `display` set to `"updates"` or `"summarized"`, because at `"omitted"` every `thinking` block is empty. This option works where your platform supports [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages). After several such steps in a row, have the harness append this reminder after the latest tool results as a [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) (`clear_at: "next_user_message"`, beta, `mid-conversation-system-clear-at-2026-08-21` header):
102### Modify your harness
106103
104An effective way to encourage communication is to count consecutive tool-calling steps that give the user nothing to read: no `text` block and no `thinking` block with text. Count with `display` set to `"updates"` or `"summarized"`, because at `"omitted"` every `thinking` block is empty. This option works where your platform supports [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages). When several pass in a row, you can append this reminder after the latest tool results as a [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) (`clear_at: "next_user_message"`, beta, `mid-conversation-system-clear-at-2026-08-21` header):
105
107106```text wrap
108107The user hasn't heard from you in a while: say in a few words what you're doing, then continue.
109108```
110109
111In Anthropic’s testing on multi-turn coding tasks, the reminder roughly halved the longest silent stretch, with no noticeable increase in tokens or time.
110In Anthropic’s testing on multi-turn coding tasks, the reminder roughly halved the longest silent stretch without a noticeable increase in tokens or time.
112111
113112Leave each reminder in `messages` on later requests. Removing or rewording one edits an earlier turn, which invalidates the thinking blocks after it. See [Send per-turn reminders as turn-scoped system messages](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#per-turn-reminders).
114113
115To also get an opening line before the first tool call, brief updates, and a closing recap, add this text to your system prompt:
114### Signal intent
116115
116To receive an opening line before the first tool call, brief updates, and a closing recap, you can also add this text to your system prompt:
117
117118```text wrap
118119Before 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.
119120```
120121
121In Anthropic’s testing on coding tasks, the model spoke before its first tool call every time with this text. The text also raised output tokens per task by roughly 20 percent. Use this text where a human is directly in the loop. To get the most updates, pair it with the reminder that your harness appends.
122With this text, the model wrote a message before its first tool call in every run of the coding tasks. Note that output tokens per task increased by roughly 20 percent as a result.
122123
123If you can’t change the harness, or your platform has no mid-conversation system messages, add this sentence to your system prompt:
124Use this text where a human is directly in the loop. To increase interactive updates, use this text together with the earlier reminder.
124125
126### Update system prompt instructions
127
128If you can’t add the reminder in your harness, or your platform has no mid-conversation system messages, add this sentence to your system prompt instead:
129
125130```text wrap
126131Every few tool calls, give the user a one-line update on where things stand.
127132```
128133
129In Anthropic’s testing on workflow automation tasks, this sentence cut most long silent stretches.
134In Anthropic’s testing, this sentence cut most long silent stretches on workflow automation tasks. Expect runs of several tool calls between updates even when you use the reminder together with the opening and recap text. Claude Fable 5.2 works well on long-running asynchronous tasks, so Anthropic recommends the model for work where nobody needs frequent updates.
130135
131Even with the reminder and the opening and recap text together, expect runs of several tool calls between updates. Claude Fable 5.2 works well on long-running asynchronous tasks, where the user comes back for the result instead of watching each step. Gaps between updates matter less there.
132
133136## Set expectations for subagents
134137
135How much work Claude Fable 5.2 delegates to subagents depends on your harness and tasks. In Anthropic’s testing on short tasks with a minimal tool for starting subagents, it rarely started one. In an agentic coding product whose prompts invite delegation, it delegates readily.
138How much Claude Fable 5.2 delegates depends on your harness and tasks. In Anthropic’s testing on short tasks with a minimal subagent tool, it rarely started a subagent. In an agentic coding product whose prompts invite delegation, it delegated readily.
136139
137If your system prompt, skills, or agent files tell the model to delegate, review those lines first. Change the description of the tool that starts subagents only if Claude Fable 5.2 still starts more subagents than your tasks need. If the tool has a plain description and nothing else in your prompts asks for delegation, you likely don’t need a new description.
140At higher effort levels such as `xhigh` and `max`, Anthropic saw Claude Fable 5.2 use subagents in an agentic coding product to review its own work, which Claude Fable 5.1 didn’t do on the same tasks.
138141
139In the new description, state what a subagent adds to the cost of a session, say when delegation is worth it and when it isn’t, and tell the model how to brief a subagent that it starts. The description that Anthropic tested does these three things and puts cost first. A description of this kind is most useful when your harness already invites delegation and subagents make up a large share of your token usage.
142Early testers had good results with Claude Fable 5.2 as the planner and orchestrator for other models. Delegation can speed up work that runs well in parallel. However, subagents can account for a large part of what a session costs, so check which model your subagents use by default.
140143
141In Anthropic’s testing on short tasks, the model delegated about a third less often with the tested description than with one that mostly listed reasons to delegate. Task success was the same.
144Change your subagent tool’s description only if Claude Fable 5.2 starts more subagents than your tasks need. A new description is most useful in a harness that already invites delegation and where subagents make up a large share of your token use. If your subagent tool has a plain description and nothing else in your prompts asks for delegation, you likely don’t need one. If your system prompt, skills, or agent files tell the model to delegate, review those lines first.
142145
143In the tested description, the opening sentences on cost hold delegation back. Say less about cost if the model delegates too little. If it still delegates too much, say more about what a subagent costs in your harness, and test the change.
146In the new tool description, state what a subagent adds to the cost of a session, say when delegation is worth it and when it isn’t, and tell the model how to brief a subagent that it starts.
144147
145Anthropic also observed Claude Fable 5.2 using subagents to review its own work in an agentic coding product at higher effort levels, such as `xhigh` and `max`. Claude Fable 5.1 didn’t do this on the same tasks. Early testers had good results with Claude Fable 5.2 as the planner and orchestrator for other models. Delegation can speed up work that runs well in parallel. However, subagents can account for a large part of what a session costs, so check which model your harness runs subagents on by default.
148If the model delegates too much, say more about what a subagent costs in your harness, and test the change. In Anthropic’s testing at `high` effort, a longer description focused on this roughly halved the number of subagents compared to a shorter version.
146149
150Adapt your description to your requirements and adjust when it tells the model to delegate.
151
147152## Keep caution from piling up
148153
149Cautious instructions build up wherever context carries over: memory, notes, instruction files, and messages between agents. Claude Fable 5.2 follows these instructions closely, so it might ask for approvals it doesn’t need or hold back routine work. A few early testers saw this behavior, mostly where several agents work together. Earlier models follow such instructions too, but in one of the setups described here only Claude Fable 5.2 held back.
154Cautious instructions can build up from past sessions through memory, notes, and instruction files. This can be counterproductive when Claude Fable 5.2 follows the instructions closely and asks for unnecessary approval. In early testing, Anthropic saw this mostly when several agents worked together.
150155
151If you see this behavior, clean up what your agents carry:
156If you see this, remove outdated instructions from your agent’s context:
152157
153* **Remove notes you no longer need.** In Anthropic’s testing on simulated tasks, one of a dozen notes from earlier sessions said never to retry. With those notes in context, and with nothing in the prompt that allowed retries, the model retried after a tool was busy in about four in ten tries, down from nearly all without those notes.
154* **Name the steps that need no approval.** In Anthropic’s testing on simulated tasks, the context held “never” rules, notes, and a reviewer’s conditions. A line at the end of the rules that listed retries among the steps that need no approval raised retries from almost none to about half of the tries. In the same setup, a general instruction to act more freely changed nothing. Name retries only for calls that are safe to repeat.
155* **Check what reviewer agents attach.** In Anthropic’s testing on simulated tasks, one setup had a line in the prompt that listed retries among the steps that need no approval, and a reviewer’s “stop at the first error” in context. Claude Fable 5.2 didn’t retry in about a third of the tries. Claude Fable 5.1 and Claude Opus 5.5 retried.
156* **Write the exception into the rule.** In Anthropic’s testing on simulated tasks, the person in charge had approved a step. Under a “never” rule, the model took that step in about one try in ten. A separate line that said an approved step has its go-ahead didn’t change that rate much. When the rule itself said to get a go-ahead first, the model took the step in about nine tries in ten. See [Approvals](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#approvals).
158* **Remove notes you no longer need.** Memory can contain old instructions such as “never retry” that the model keeps following, so delete these instructions once they stop being relevant.
159* **Name the steps that need no approval.** Telling the model to act more freely is too vague, so list the routine steps that it can take on its own.
160* **Check your validation steps.** A condition such as “stop and review at the first error” can block autonomous work, so remove or narrow the stopping conditions that you don’t need.
161* **Be explicit about exceptions.** The model treats an instruction that contains “never” as absolute. For example, write “ask for approval before deleting files” instead of “never delete files” if you want the model to keep responsibility over an action. See [Approvals](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#approvals).
157162
158Also keep your own confirmation step for risky or irreversible actions.
163Keep your own confirmation step for risky or irreversible actions.
159164
160## Review instructions written for earlier models
165## Review prompts and harnesses designed for earlier models
161166
162When you migrate to Claude Fable 5.2, review your prompts. In Anthropic’s testing, some instructions written for earlier models raised cost, caused side effects, or no longer had an effect. Reconsider these instructions:
167As you migrate to Claude Fable 5.2, review your prompts and harnesses. In Anthropic’s testing, some instructions and interventions designed for earlier models raised cost, caused side effects, or no longer had an effect. Here are the practices to reconsider:
163168
164* **Standing instructions to delegate:** Lines that push work to subagents can sit in system prompts, skills, and agent files. Read those files before you migrate. If, in your tests, the model starts more subagents than your tasks need, remove the lines you no longer need. See [Set expectations for subagents](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#set-expectations-for-subagents).
165* **A token budget that your harness writes into the prompt:** Some harnesses tell the model in the prompt how many tokens the task may use and how many are left. The size of that budget changes how much Claude Fable 5.2 spends. In Anthropic’s testing on coding tasks at `high` and `xhigh` effort, removing a large budget lowered cost, with equivalent performance. Test your tasks without the budget. This finding is about text in the prompt, not the API’s [task budgets](https://platform.claude.com/docs/en/build-with-claude/task-budgets), a beta feature that the testing didn’t cover.
169* **Standing instructions to delegate:** Lines that tell the model to delegate can sit in system prompts, skills, and agent files. Read those files before you migrate and remove the lines you no longer need if the model delegates too much in testing. See [Set expectations for subagents](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#set-expectations-for-subagents).
170* **A token budget shown to the model:** Some harnesses show the model a token budget for the task and how much of it is left. The size of that budget changes how much Claude Fable 5.2 spends. In Anthropic’s testing on coding tasks at `high` and `xhigh` effort, removing a large budget lowered cost, with equivalent performance. Test your tasks without it. This finding is about text in the prompt, not the API’s [task budgets](https://platform.claude.com/docs/en/build-with-claude/task-budgets), a beta feature that the testing didn’t cover.
166171* **Harness code that edits earlier turns:** Claude Fable 5.2 uses [preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking). If your harness changes the system prompt, the tools, or an earlier message between requests, the thinking blocks that follow the changed point in the history become invalid. By default, the Messages API then rejects the request, and the Message Batches API drops those blocks. To shorten the history without this error, use [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing), or [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) that keeps no earlier turns after the summary. To have the Messages API drop the blocks too, set `thinking.block_binding.prefix_mismatch_behavior` to `"drop_block"` (beta, `thinking-binding-controls-2026-08-01` header). In Anthropic’s testing, when earlier thinking was dropped on every turn, the model thought again and used more output tokens. That is the worst case, and the increase depends on how often your harness edits earlier turns. Apart from compaction and context editing, keep the history append-only. That keeps the cache hit rate high, and no thinking is dropped. Measure output tokens on your own tasks before you rely on `"drop_block"`. See [What the API does with an invalid block](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#mismatch-behavior) and [Make changes without editing the prefix](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#replace-prefix-edits).
167* **The “treat that answer as done” lines:** [Prompting Claude Opus 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#thinking-instructions-in-chat-system-prompts) offers two sentences for chat system prompts. They tell the model to treat an earlier answer as done and to focus its thinking on the new message. In Anthropic’s testing at `high` effort, these sentences reduced Claude Fable 5.2’s thinking on follow-up questions, but the model also became far less likely to point out mistakes in its earlier answers. Leave these lines out where you want the model to keep re-examining its earlier answers. Elsewhere, test whether the model still points out its own mistakes before you adopt the lines.
168* **Instructions to think less:** Claude Fable 5.1 usually follows a line such as “answer directly without deliberating.” In Anthropic’s testing, such a line didn’t stop Claude Fable 5.2 from thinking at `medium` and above. Remove these lines and lower the effort level, as described in [Calibrate effort](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#calibrate-effort).
169* **Style rules for writing:** Claude Fable 5.2 follows style rules closely, so a hard limit such as “one instruction per sentence, in 20 words or fewer” can make its prose choppy. Remove the rules you no longer need before you add the text in [Make reports easy to follow](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#make-reports-easy-to-follow).
170* **Rules, notes, and memories that have built up:** Memory files, notes, and instruction files collect cautions over time, and the model might have written some of them itself. Before you migrate, delete the cautions whose reason no longer holds, and rewrite absolute rules so that they state their scope and reason. If a system is already stuck, consider restarting it with its memory and notes trimmed, and keep a copy of the originals. See [Keep caution from piling up](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#keep-caution-from-piling-up).
172* **The “treat that answer as done” lines:** [Prompting Claude Opus 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#thinking-instructions-in-chat-system-prompts) offers two sentences for chat system prompts. They tell the model to treat an earlier answer as done and to focus its thinking on the new message. In Anthropic’s testing at `high` effort, these instructions reduced Claude Fable 5.2’s thinking on follow-up questions. The model also became far less likely to point out mistakes in its earlier answers. Leave these lines out where you want the model to keep re-examining its earlier answers. Elsewhere, test whether the model still points out its own mistakes before you adopt the lines.
173* **Instructions to think less:** Claude Fable 5.1 usually followed a line such as “answer directly without deliberating.” On Claude Fable 5.2, this addition doesn’t stop the model from thinking at `medium` and above. Remove such lines and lower the effort level, as described in [Calibrate effort](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#calibrate-effort).
174* **Style rules for writing:** Claude Fable 5.2 follows them closely, so a hard limit such as “one instruction per sentence, in 20 words or fewer” can make its prose choppy. Remove the rules you no longer need before you add the text in [Make reports easy to follow](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#make-reports-easy-to-follow).
175* **Rules, notes, and memories that have built up:** Memory files, notes, and instruction files collect cautions over time, and the model might have written some of them itself. Before you migrate, delete cautions whose reason no longer holds, and rewrite absolute rules with their scope and reason. If a system is already stuck, consider restarting it with its memory and notes trimmed. See [Keep caution from piling up](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#keep-caution-from-piling-up).
171176
172177## Make reports easy to follow
173178
174After long agentic work, the people who read Claude Fable 5.2’s final report usually haven’t seen the tool calls or files behind it. The report needs to make sense on its own.
179Early testers rated Claude Fable 5.2’s writing above Claude Fable 5.1’s and similar in clarity to Claude Opus 5.5’s. After long agentic work, however, the people who read Claude Fable 5.2’s final report usually haven’t seen the tool calls or files behind it, so the report needs to make sense on its own.
175180
176181If you ask Claude Fable 5.2 to write final reports or handoffs, add this text to your system prompt, and adjust it to your readers and your product:
177182
from line 187
182187Use plain words, and write in clear, understandable full sentences. Do not use a term or abbreviation that you made up during the work. Say what the thing is in a way any reader would understand. Write mostly in the style of ASD-STE100 Simplified Technical English: short sentences, one idea per sentence, active voice, and consistently using the same word for the same thing. Use a paragraph of flowing prose where ideas connect, and keep bullets for lists of separate items. Leave out unnecessary details unless the reader asks and practice concision, but do ensure that your messages have the key context. Aim to make your user-facing text as human-readable and clear as possible.
183188```
184189
185In Anthropic’s testing on agentic tasks, this text made final reports less dense, with fewer semicolons. On workflow automation tasks, it also made sentences shorter. You might also add instructions about length or ask the model to include specific details.
190In Anthropic’s testing on agentic tasks, the text made final reports less dense and reduced the number of semicolons. It also shortened sentences on workflow automation tasks. Depending on your use case, you might want to add instructions about length or ask the model to include specific details.
186191
187192## Safeguard refusals
188193
from line 195
190195
191196* `cyber`: the request could enable cyber harm, such as malware or exploit development.
192197* `bio`: the request could enable biological harm, such as dangerous lab methods.
193* `frontier_llm`: the request could help with the development of competing AI models.
198* `frontier_llm`: the request could assist the development of competing AI models.
194199* `reasoning_extraction`: the request asks the model to reproduce its internal reasoning in the response text.
195200* `general_harms`: the request falls under another usage-policy area.
201* `null`: the refusal doesn’t map to a named category.
196202
197Benign cybersecurity and life sciences work can also trigger the `cyber` and `bio` classifiers. If they block your organization’s legitimate work, see Anthropic’s [Cyber Verification Program](https://support.claude.com/en/articles/14604842) and [Life Sciences Verification Program](https://www.anthropic.com/news/life-sciences-verification-program). [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview) offers the same capabilities as Claude Fable 5.2 only to organizations verified through these programs.
203Benign cybersecurity and life sciences work can also trigger the `cyber` and `bio` classifiers. If that blocks your organization’s legitimate work, see Anthropic’s [Cyber Verification Program](https://support.claude.com/en/articles/14604842) and [Life Sciences Verification Program](https://www.anthropic.com/news/life-sciences-verification-program). [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview) offers the same capabilities as Claude Fable 5.2 only to organizations verified through these programs.
198204
199If your prompts, skills, or tool descriptions ask the model to write its reasoning in the response, remove those instructions. To see how the model reasoned, set `display: "summarized"` and read the thinking blocks. See [Keep reasoning in thinking blocks](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks).
205If your prompts, skills, or tool descriptions ask the model to write out its reasoning in the response, remove those instructions. To see how the model reasoned, set `display: "summarized"` and read the thinking blocks. See [Keep reasoning in thinking blocks](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks).
200206
201207To retry a declined request on another model, see [Refusals, fallback, and billing](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2#refusals-fallback-and-billing).
202208
203209## Where to start
204210
205When you migrate, work through these steps in order:
206
2072111. Set `effort` to `high` explicitly, then run your evals at `medium` and `xhigh` as well.
2082. Read the system prompts, skills, agent files, memory files, notes, and harness text you carry over. Remove or test the instructions listed in [Review instructions written for earlier models](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#review-instructions-written-for-earlier-models).
2093. Run your longest agentic tasks. Note where the model stops early, asks for approvals it doesn’t need, goes quiet, delegates more than the task needs, or adds to existing code where you wanted it restructured.
2104. Apply the guidance for each behavior you observed, one at a time, and measure its effect and its token cost on your own tasks.
2122. Read the system prompts, skills, agent files, memory files, notes, and harness text you carry over, and remove or test what [Review prompts and harnesses designed for earlier models](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#review-instructions-written-for-earlier-models) describes.
2133. Run your longest agentic tasks, and note where the model stops early, asks for approvals it doesn’t need, goes quiet, delegates more than the task needs, or adds to existing code where you wanted it restructured.
2144. Add the text or follow the advice for each behavior you observed, one at a time, and measure its effect and its token cost on your own tasks.
211215
build-with-claude/prompt-engineering/prompting-claude-haiku-5-5 Changed · +5 / -5 lines
from line 19
1919* Requests return `stop_reason: "refusal"`: [Safeguard refusals](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#safeguard-refusals)
2020
2121<Note>
22 For the breaking API changes when migrating from Claude Haiku 4.5, see the [migration guide](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide).
22 For the breaking API changes when migrating from Claude Haiku 4.5, see the [Claude Haiku 5.5 migration guide](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide).
2323
2424 Several sections on this page suggest text to add to your system prompt. Add it to new conversations only. A request that sends thinking blocks back after `system` changed can return a 400 error, so a stored conversation resumed with the new system prompt can fail. To change instructions partway through a conversation, [put them in the newest turn](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#changing-context). On the Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), and Claude Models on Google Cloud (Google managed), you can instead [append a system message to the conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#new-instructions).
2525</Note>
from line 38
3838* Thinking is on by default and counts toward `max_tokens`, which can go up to 128,000. A `max_tokens` value sized for Claude Haiku 4.5 requests that ran without thinking can cut the reply off, so leave room for thinking.
3939* To get less thinking, lower the effort level. In Anthropic’s testing, telling the model in the prompt to answer directly didn’t stop it from thinking. You can also turn thinking off with `thinking: {"type": "disabled"}`. This works at `low`, `medium`, and `high` only. At `xhigh` and `max`, the request returns a 400 error.
4040* At `xhigh` effort in multi-turn chats, the model sometimes writes its whole answer in its thinking and ends the turn with no visible text. If you see this behavior, check each response for an empty reply.
41* Changing the top-level `effort` value between requests invalidates the prompt cache for the conversation’s messages. Where your platform supports it, you can change the level partway through a conversation with a [per-message effort change](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) (beta), which keeps the cache. A change holds for every later turn until another one replaces it. It needs the `mid-conversation-output-config-2026-07-01` beta header and adaptive thinking, which is the default. With thinking off, a per-message effort change returns a 400 error.
41* Changing the top-level `effort` value between requests invalidates the prompt cache for the conversation’s messages. Where your platform supports it, you can change the level partway through a conversation with a [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) change, which keeps the cache. A change holds for every later turn until another one replaces it. It needs the `mid-conversation-output-config-2026-07-01` beta header and adaptive thinking, which is the default. With thinking off, a per-message effort change returns a 400 error.
4242
4343## Accurate search results
4444
from line 53
5353The model also sometimes needs an extra nudge to search. This occurs most at `low` effort and with long system prompts. To fix it, add this text directly after the date:
5454
5555```text wrap
56Your training data ends well before today's date. Records, office holders, prices, versions, rules and anything "latest" may have changed since then, so search for those before you answer, even when you feel sure. Facts that can't change need no search. When the answer depends on where the user is, put the user's country or region in the search query.
56Your training data ends well before today's date. Records, office holders, prices, versions, rules, and anything "latest" may have changed since then, so search for those before you answer, even when you feel sure. Facts that can't change need no search. When the answer depends on where the user is, put the user's country or region in the search query.
5757```
5858
5959In Anthropic’s testing, this text raised the search rate on questions whose answers had changed. On prompts that need no search, it added searches in only 0–3 percent of tries.
from line 94
9494At `low` and `medium` effort, Claude Haiku 5.5 sometimes reports a code change as done without running a check. If you see the model report results without checking its work, add this paragraph, or one like it, to your system prompt:
9595
9696```text wrap
97When 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 and lockfile (e.g. npm install, pip install -r requirements.txt), never via sudo or the system package manager, 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.
97When 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 and lockfile (for example, npm install or pip install -r requirements.txt), never through sudo or the system package manager, 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.
9898```
9999
100100In Anthropic’s testing, the model checked its changes more often with this text, and its performance improved, at the cost of more tokens.
from line 134
134134
135135If you’re moving from Claude Haiku 4.5, these refusals are new.
136136
137Claude Haiku 5.5 has no [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback) (beta). If a request is declined, handle `stop_reason: "refusal"` in your client. Sending the same request to Claude Haiku 5.5 again usually returns another refusal.
137Claude Haiku 5.5 has no [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback). If a request is declined, handle `stop_reason: "refusal"` in your client. Sending the same request to Claude Haiku 5.5 again usually returns another refusal.
138138
build-with-claude/prompt-engineering/prompting-claude-opus-5-5 Changed · +5 / -5 lines
from line 21
2121* Frontend output looks generic: [Frontend design defaults](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#frontend-design-defaults)
2222
2323<Note>
24 For the four breaking API changes when migrating from Claude Opus 5, see the [migration guide](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-5).
24 For the four breaking API changes when migrating from Claude Opus 5, see the [Claude Opus 5.5 migration guide](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-5).
2525</Note>
2626
2727## Capabilities relevant to prompting
from line 43
4343* Reserve `xhigh` and `max` for work where you’ve measured a quality gain.
4444* To get less thinking, lower the effort level first. Lowering effort reduces thinking, and with it cost and latency, more reliably than prompt instructions do.
4545
46Changing the top-level `effort` value between requests invalidates the prompt cache. To change the level partway through a conversation, use a [per-message effort change](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) (beta) instead, which keeps the cache. A change holds for every later turn until another one replaces it.
46Changing the top-level `effort` value between requests invalidates the prompt cache. To change the level partway through a conversation, use a [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) change instead, which keeps the cache. Per-message effort is in beta. A change holds for every later turn until another one replaces it.
4747
4848## Prompts written for thinking disabled
4949
from line 94
9494
9595Third, if you want more frequent or predictable updates, such as a one-line statement of intent before the first tool call and a short recap at the end, say so in the system prompt; the model is responsive to such instructions. This helps most in human-in-the-loop work.
9696
97Fourth, if long tool-calling turns still go quiet for longer than you want, have your harness ask for an update. With `display: "updates"` set (the first lever), count consecutive tool-calling steps that give the user nothing to read: no `text` block and no progress-update text. After several in a row (five, for example), append a reminder such as the following one after the latest tool results, as a [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) (`clear_at: "next_user_message"`, in beta with the `mid-conversation-system-clear-at-2026-08-21` header). If the turn stays quiet, stop after two or three reminders rather than sending more. Because each reminder is appended and left in place, rather than inserted for one request and deleted on the next, the prompt cache keeps matching and the [thinking blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#per-turn-reminders) that follow it stay valid. In Anthropic’s testing on agentic coding tasks, this roughly halved the share of tasks with a long silent stretch, with no measurable change in cost.
97Fourth, if long tool-calling turns still go quiet for longer than you want, have your harness ask for an update. With `display: "updates"` set (the first lever), count consecutive tool-calling steps that give the user nothing to read: no `text` block and no progress-update text. After several in a row (five, for example), append a reminder such as the following one after the latest tool results, as a [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) (`clear_at: "next_user_message"`, in beta with the `mid-conversation-system-clear-at-2026-08-21` header). If the turn stays quiet, stop after two or three reminders rather than sending more. Because each reminder is appended and left in place, rather than inserted for one request and deleted on the next, the prompt cache keeps matching and the thinking blocks that follow it stay valid (see [Send per-turn reminders as turn-scoped system messages](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#per-turn-reminders)). In Anthropic’s testing on agentic coding tasks, this roughly halved the share of tasks with a long silent stretch, with no measurable change in cost.
9898
9999```text wrap
100The user hasn't heard from you in a while — say in a few words what you're doing, then continue.
100The user hasn't heard from you in a while: say in a few words what you're doing, then continue.
101101```
102102
103103## Explore context in multiapp workflows
from line 105
105105In workflow automation across several connected apps, such as email, documents, spreadsheets, and CRM records, the information a task depends on often sits somewhere the request doesn’t explicitly mention: for example, a policy in an old email thread, a rule on another spreadsheet tab, or a note on a customer record. Claude Opus 5.5 tends to get to work quickly, and on loosely specified tasks it helps to tell the model to look through the relevant sources before acting. If your agent works across several apps on tasks like these, one sentence in the system prompt makes it look around before it changes anything:
106106
107107```text wrap
108Before taking any action, explore broadly with tool calls: list and open the emails, documents, spreadsheet tabs and records across the available apps that could be relevant to this task, including ones the task does not explicitly mention, and use what you find.
108Before taking any action, explore broadly with tool calls: list and open the emails, documents, spreadsheet tabs, and records across the available apps that could be relevant to this task, including ones the task does not explicitly mention, and use what you find.
109109```
110110
111111In Anthropic’s testing on multiapp automation tasks, Claude Opus 5.5 completed noticeably more of them correctly with this instruction, at both `medium` and `max` effort, at the cost of slightly more tool calls and tokens. Because it tells the model to act on what it finds, keep untrusted content out of the records it searches.
build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5 Changed · +11 / -11 lines
from line 21
2121* Requests return `stop_reason: "refusal"`: [Safeguard refusals](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#safeguard-refusals)
2222
2323<Note>
24 For the five breaking API changes when migrating from Claude Sonnet 5, see the [migration guide](https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide#migrating-from-claude-sonnet-5).
24 For the five breaking API changes when migrating from Claude Sonnet 5, see the [Claude Sonnet 5.5 migration guide](https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide#migrating-from-claude-sonnet-5).
2525</Note>
2626
2727## Calibrate effort
from line 36
3636* Reserve `xhigh` and `max` for work where you’ve measured a quality gain, because thinking and replies get much longer there. At those levels, `between_tools` isn’t accepted, so up-front thinking can’t be turned off.
3737* To get less thinking, lower the effort level. Asking the model in the system prompt to think less doesn’t reliably reduce its thinking.
3838
39Changing the top-level `effort` value between requests invalidates the prompt cache. To change the level partway through a conversation, use a [per-message effort change](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) (beta) instead, which keeps the cache. A change holds for every later turn until another one replaces it. For example, in an interactive session at `low`, add a change to `high` before the user’s hard problem, and a change back to `low` after Claude answers it. Per-message effort changes need adaptive thinking. With `between_tools`, they return a 400 error, as [Running without up-front thinking](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#running-without-up-front-thinking) explains.
39Changing the top-level `effort` value between requests invalidates the prompt cache. To change the level partway through a conversation, use a [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) change instead, which keeps the cache. Per-message effort is in beta. A change holds for every later turn until another one replaces it. For example, in an interactive session at `low`, add a change to `high` before the user’s hard problem, and a change back to `low` after Claude answers it. Per-message effort changes need adaptive thinking. With `between_tools`, they return a 400 error, as [Running without up-front thinking](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#running-without-up-front-thinking) explains.
4040
4141## Steer initiative and scope
4242
from line 47
4747```text wrap
4848Keep working until everything the user asked for is done, and only stop to ask when you can't go on without the user or before a risky step.
4949
50When the work the user asked for is done and checked, stop and report. Don't add features, tests, files, docs or refactors that weren't asked for. If you think one would help, mention it at the end instead of doing it.
50When the work the user asked for is done and checked, stop and report. Don't add features, tests, files, docs, or refactors that weren't asked for. If you think one would help, mention it at the end instead of doing it.
5151```
5252
5353With this prompt, the model carries more of the work through at `low` and `medium` effort, so sessions at those levels run longer and cost more. The prompt doesn’t replace your own rules about risky or irreversible actions. Keep those rules in your system prompt.
from line 57
5757**Thoroughness at `xhigh` and `max` effort.** At these levels the model is especially thorough. After it completes a task, it can start its own rounds of review and verification, sometimes with subagents if your harness provides them. It can also make related fixes it noticed along the way. This takes more time and tokens, so run routine work at `high` or below, where it’s rare. If you do want that extra thoroughness of these effort levels, but want to direct it to the task itself, add this to your system prompt:
5858
5959```text wrap
60When the work the user asked for is done and its checks pass, stop and report. Don't start extra rounds of review or hardening on your own, and don't launch reviewer sub-agents unless the user asked for a review. If you think a deeper review is worth doing, say so at the end.
60When the work the user asked for is done and its checks pass, stop and report. Don't start extra rounds of review or hardening on your own, and don't launch reviewer subagents unless the user asked for a review. If you think a deeper review is worth doing, say so at the end.
6161```
6262
6363In testing on coding tasks at `max` effort, this stopped the model from launching reviewer subagents and cut session cost by about a third, with no change in quality. It makes self-started review rounds by the main agent less frequent but doesn’t remove them entirely.
from line 65
6565**Open-ended requests.** When a request is open-ended, for example “show me what you can do with this,” the model can start building a presentation, report, or video when you only wanted ideas. If you want ideas or a plan first, say so in the request, or add this to your system prompt:
6666
6767```text wrap
68When the user asks for ideas, options or a plan, give them that and stop. Don't start building or changing anything until they say to go ahead.
68When the user asks for ideas, options, or a plan, give them that and stop. Don't start building or changing anything until they say to go ahead.
6969```
7070
7171## Running without up-front thinking
from line 110
110110
111111Next, remove older instructions such as “hold all findings for the final response.” If you then want updates at predictable points, for example a line on what the model is about to do before its first tool call and a short recap at the end, say so in the system prompt. The model follows instructions like this. Updates at set points help most in human-in-the-loop work.
112112
113If long tool-calling turns still go quiet for longer than you want, your harness can prompt an update. Have it count consecutive tool-calling steps that send the user no text or progress update. After several in a row, for example five, append a one-turn reminder after the latest tool results. Send it as a [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) (beta), with text such as the following:
113If long tool-calling turns still go quiet for longer than you want, your harness can prompt an update. Have it count consecutive tool-calling steps that send the user no text or progress update. After several in a row, for example five, append a one-turn reminder after the latest tool results. Send it as a [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) (in beta), with text such as the following:
114114
115115```text wrap
116The user hasn't heard from you in a while — say in a few words what you're doing, then continue.
116The user hasn't heard from you in a while: say in a few words what you're doing, then continue.
117117```
118118
119119If the turn stays quiet, stop sending reminders after the second or third. Frequent harness text after tool results can lead the model to treat that text as a possible prompt injection, as [Mid-turn user messages](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#mid-turn-user-messages-and-task-budgets) explains. Leave each reminder in `messages` on later requests. Because the reminder is appended rather than inserted and later deleted, the prompt cache and [preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking) stay intact. At `high` effort, with a tool for sending the user a message available, the reminder leads the model to update the user more often and shortens its longest silent stretches, with no measurable change in task quality.
from line 125
125125First, check your prompt for language that discourages tool use, such as “only use tools when strictly necessary” or “minimize tool calls,” and remove it. Then, if your product gives the model a search tool, add this to your system prompt:
126126
127127```text wrap
128Use 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.
128Use 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.
129129```
130130
131131This matters most for research and support products, where answers depend on current details.
from line 139
139139* Never put user text inside a `tool_result` block. The model misreads that placement most often.
140140* Deliver mid-turn user input as a user turn. Append the user’s words as a text block in the user message that carries the `tool_result` blocks, after the last `tool_result`.
141141* Keep harness notices, such as reminders, in a separate mid-conversation system message after the user’s words. Never put a notice and the user’s words in the same block.
142* In interactive sessions where users can type mid-turn, don’t add your own token or budget countdown after tool results. [Task budgets](https://platform.claude.com/docs/en/build-with-claude/task-budgets) (beta) add a similar countdown, but they haven’t been seen to cause this misread. If you see the misread while a task budget is set, try the session without one.
142* In interactive sessions where users can type mid-turn, don’t add your own token or budget countdown after tool results. [Task budgets](https://platform.claude.com/docs/en/build-with-claude/task-budgets) (in beta) add a similar countdown, but they haven’t been seen to cause this misread. If you see the misread while a task budget is set, try the session without one.
143143
144144## Verification on coding tasks
145145
from line 148
148148If you see changes reported as complete without test or build output in the transcript, add this paragraph, or one like it, to the system prompt. At `low` effort, it makes skipped or superficial checks rare, with no measurable change in task quality and only a slightly higher cost per task:
149149
150150```text wrap
151When 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 and lockfile (e.g. npm install, pip install -r requirements.txt), never via sudo or the system package manager, 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.
151When 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 and lockfile (for example, npm install or pip install -r requirements.txt), never through sudo or the system package manager, 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.
152152```
153153
154154## Tolerant tool-call handling
from line 174
174174
175175If the `cyber` classifier blocks your organization’s legitimate security work, you can apply to the [Cyber Verification Program](https://support.claude.com/en/articles/14604842). If the `bio` classifier blocks your organization’s life sciences work, you can apply to the [Life Sciences Verification Program](https://www.anthropic.com/news/life-sciences-verification-program).
176176
177If you turn on [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback) (beta), it retries `cyber` and `frontier_llm` declines on Claude Sonnet 5. It doesn’t retry `bio`, `reasoning_extraction`, or `general_harms` declines. See [Refusals, fallback, and billing](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5#refusals-fallback-and-billing).
177If you turn on [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback) (in beta), it retries `cyber` and `frontier_llm` declines on Claude Sonnet 5. It doesn’t retry `bio`, `reasoning_extraction`, or `general_harms` declines. See [Refusals, fallback, and billing](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5#refusals-fallback-and-billing).
178178
179179If your prompts ask the model to include its reasoning in the response, remove those instructions, because they invite `reasoning_extraction` declines. With adaptive thinking, read the reasoning from [summarized thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#summarized-thinking) blocks instead (`display: "summarized"`). You can still ask for a short explanation of the answer or a summary of the actions taken; see [Keep reasoning in thinking blocks](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks).
180180
build-with-claude/refusals-and-fallback Changed · +5 / -4 lines
from line 15
1515 - claude-haiku-5-5
1616 supportedPlatforms:
1717 Claude API: stable
18 Amazon Bedrock: stable
19 Amazon Bedrock (bedrock-runtime): stable
1820 Claude Platform on AWS: stable
1921 Claude Models on Google Cloud (Anthropic managed): stable
20 Amazon Bedrock: stable
2122 Claude Models on Google Cloud (Google managed): stable
2223 Microsoft Foundry: stable
2324---
from line 781
780781
781782<CodeGroup exclude="shell">
782783 <CodeGroupItem language="cURL">
783 The refusal-fallback middleware is part of the Claude SDK, so a cURL request can’t use it. To fall back within a single request, use [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback). To write the retry yourself, see [Fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit).
784 The refusal-fallback middleware is part of the Anthropic SDK, so a cURL request can’t use it. To fall back within a single request, use [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback). To write the retry yourself, see [Fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit).
784785 </CodeGroupItem>
785786
786787 <CodeGroupItem language="CLI">
from line 1126
11251126
11261127* Retries walk your fallback list in order. A fallback model that itself refuses passes the request to the next entry.
11271128* When every model in the list has declined, the middleware returns the final refusal (the last model’s refusal response) rather than raising an error.
1128* Thinking blocks from Claude Fable 5.2, Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5, or Claude Fable 5 pass through unchanged. Each retry re-sends your original request body, and the only blocks the middleware removes from conversation history on later requests are the `fallback` boundary blocks it added itself. Apart from Claude Mythos 5.2, no other model reads Claude Fable 5.2 blocks. Only Claude Fable 5.1, Claude Mythos 5.1, and, on the Claude API, Claude Fable 5.2 and Claude Mythos 5.2 [read Claude Fable 5.1 blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models). The API drops any Claude Fable 5.2 or Claude Fable 5.1 block that the fallback model can’t read. The API also drops any Claude Opus 5.5 or Claude Sonnet 5.5 block that the fallback model can’t read (see [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). Claude Opus 5.5 and Claude Sonnet 5.5 read Claude Haiku 5.5 blocks on the Claude API and Claude Models on Google Cloud (Google managed), as do Claude Fable 5.2 and Claude Mythos 5.2 on the Claude API, and the API drops them for a fallback model that can’t read them. On Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 read the same blocks as on the Claude API.
1129* Thinking blocks from Claude Fable 5.2, Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5, or Claude Fable 5 pass through unchanged. Each retry re-sends your original request body, and the only blocks the middleware removes from conversation history on later requests are the `fallback` boundary blocks it added itself. Apart from Claude Mythos 5.2, no other model reads Claude Fable 5.2 blocks. Claude Fable 5.1 and Claude Mythos 5.1 [read Claude Fable 5.1 blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models), and so do Claude Fable 5.2 and Claude Mythos 5.2 on the Claude API and Claude Models on Google Cloud (Google managed). No other model reads them. The API drops any Claude Fable 5.2 or Claude Fable 5.1 block that the fallback model can’t read. The API also drops any Claude Opus 5.5 or Claude Sonnet 5.5 block that the fallback model can’t read (see [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). On the Claude API and Claude Models on Google Cloud (Google managed), Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2, and Claude Mythos 5.2 read Claude Haiku 5.5 blocks. The API drops them for a fallback model that can’t read them.
11291130* Responses served through the middleware include a `fallback` content block at each model boundary, the same as server-side fallback responses. The middleware manages those blocks for you on later requests.
11301131* The model that accepted is recorded in `BetaFallbackState` (go: `betafallback.BetaFallbackState`), so follow-up requests that share the state stay pinned to it rather than re-asking a model that refused.
11311132
from line 1146
11451146 <Step title="Re-send on a fallback model">
11461147 Send the same request with `model` set to a fallback model, such as Claude Opus 4.8. If the refused request sent `thinking: {"type": "between_tools"}`, change `thinking` first: only Claude Sonnet 5.5 accepts that value, so omit `thinking` or set a value the fallback model accepts. [Server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback) under the `2026-07-01` header makes this change for you when it falls back to Claude Sonnet 5. Another model can normally serve a request that Claude Fable 5.2, Claude Fable 5.1, or Claude Fable 5 declines. How you handle the conversation history depends on whether you redeem a [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit):
11471148
1148 * **Not redeeming a credit:** you can leave the earlier `thinking` and `redacted_thinking` blocks in place or strip them to save input tokens. The fallback model normally can’t use them either way. Apart from Claude Mythos 5.2, no other model reads Claude Fable 5.2 blocks. Only Claude Fable 5.1, Claude Mythos 5.1, and, on the Claude API, Claude Fable 5.2 and Claude Mythos 5.2 [read Claude Fable 5.1 blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models). Only those four models, Claude Fable 5, and Claude Mythos 5 read Claude Fable 5 blocks. The API drops any of these blocks that the fallback model can’t read. It also drops any Claude Opus 5.5 or Claude Sonnet 5.5 block that the fallback model can’t read (see [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). A retry after a Claude Haiku 5.5 refusal is always in this case. Claude Opus 5.5 and Claude Sonnet 5.5 read Claude Haiku 5.5 blocks on the Claude API and Claude Models on Google Cloud (Google managed), as do Claude Fable 5.2 and Claude Mythos 5.2 on the Claude API, so leave those blocks in place when you fall back to one of those models there. For a fallback model that can’t read them, the API drops them without billing them. On Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 read the same blocks as on the Claude API.
1149 * **Not redeeming a credit:** you can leave the earlier `thinking` and `redacted_thinking` blocks in place or strip them to save input tokens. The fallback model normally can’t use them either way. Apart from Claude Mythos 5.2, no other model reads Claude Fable 5.2 blocks. Claude Fable 5.1 and Claude Mythos 5.1 [read Claude Fable 5.1 blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models), and so do Claude Fable 5.2 and Claude Mythos 5.2 on the Claude API and Claude Models on Google Cloud (Google managed). No other model reads them. Only those four models, Claude Fable 5, and Claude Mythos 5 read Claude Fable 5 blocks. The API drops any of these blocks that the fallback model can’t read. It also drops any Claude Opus 5.5 or Claude Sonnet 5.5 block that the fallback model can’t read (see [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). A retry after a Claude Haiku 5.5 refusal is always in this case. On the Claude API and Claude Models on Google Cloud (Google managed), Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2, and Claude Mythos 5.2 read Claude Haiku 5.5 blocks, so leave those blocks in place when you fall back to one of those models there. For a fallback model that can’t read them, the API drops them without billing them.
11491150 * **Redeeming a credit:** send the body unchanged, because redemption requires an exact match. The server handles the earlier model’s thinking blocks on a redemption, so do not strip them (see [Fields that must match the refused request](https://platform.claude.com/docs/en/build-with-claude/fallback-credit#reference)).
11501151 </Step>
11511152
build-with-claude/search-results Changed · +7 / -7 lines
from line 29
2929 - claude-sonnet-4-5-20250929
3030 supportedPlatforms:
3131 Claude API: stable
32 Claude Platform on AWS: stable
3332 Amazon Bedrock: stable
34 Amazon Bedrock (InvokeModel): stable
33 Amazon Bedrock (bedrock-runtime): stable
34 Claude Platform on AWS: stable
3535 Claude Models on Google Cloud (Google managed): stable
3636 Microsoft Foundry: stable
3737---
from line 106
106106
107107<CodeGroup exclude="shell">
108108 <CodeGroupItem language="cURL">
109 The tool-calling flow needs search logic in your application, which needs more than a single shell command. Use the Claude SDK for the full flow. For the raw request shape of a tool conversation with search results, see [Combining both methods](https://platform.claude.com/docs/en/build-with-claude/search-results#combining-both-methods). To provide search results directly in user messages, see [Method 2: Search results as top-level content](https://platform.claude.com/docs/en/build-with-claude/search-results#method-2-search-results-as-top-level-content).
109 The tool-calling flow needs search logic in your application, which needs more than a single shell command. Use the Anthropic SDK for the full flow. For the raw request shape of a tool conversation with search results, see [Combining both methods](https://platform.claude.com/docs/en/build-with-claude/search-results#combining-both-methods). To provide search results directly in user messages, see [Method 2: Search results as top-level content](https://platform.claude.com/docs/en/build-with-claude/search-results#method-2-search-results-as-top-level-content).
110110 </CodeGroupItem>
111111
112112 <CodeGroupItem language="CLI">
113 The tool-calling flow needs search logic in your application, which needs more than a single shell command. Use the Claude SDK for the full flow. For the raw request shape of a tool conversation with search results, see [Combining both methods](https://platform.claude.com/docs/en/build-with-claude/search-results#combining-both-methods). To provide search results directly in user messages, see [Method 2: Search results as top-level content](https://platform.claude.com/docs/en/build-with-claude/search-results#method-2-search-results-as-top-level-content).
113 The tool-calling flow needs search logic in your application, which needs more than a single shell command. Use the Anthropic SDK for the full flow. For the raw request shape of a tool conversation with search results, see [Combining both methods](https://platform.claude.com/docs/en/build-with-claude/search-results#combining-both-methods). To provide search results directly in user messages, see [Method 2: Search results as top-level content](https://platform.claude.com/docs/en/build-with-claude/search-results#method-2-search-results-as-top-level-content).
114114 </CodeGroupItem>
115115
116116 ```python Python
from line 2220
22202220* Availability: Available
22212221* Usage: Send `search_result` blocks in a tool result or directly in a user message.
22222222
2223| Status | Cloud platforms |
2224| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2225| Available | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (InvokeModel)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) |
2223| Status | Cloud platforms |
2224| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2225| Available | Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (bedrock-runtime)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) |
22262226
22272227#### [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)
22282228
build-with-claude/skills-guide Changed · +8 / -8 lines
from line 318
318318
319319<CodeGroup exclude="shell:cURL, shell:CLI">
320320 <CodeGroupItem language="cURL">
321 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
321 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
322322 </CodeGroupItem>
323323
324324 <CodeGroupItem language="CLI">
325 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
325 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
326326 </CodeGroupItem>
327327
328328 ```python Python
from line 869
869869
870870<CodeGroup exclude="shell:cURL, shell:CLI">
871871 <CodeGroupItem language="cURL">
872 Multi-turn container reuse needs more logic than a single shell command, so use the Claude SDK for it. To build the requests yourself, capture `container.id` from the first response. Then pass it in the next request as `"container": {"id": "...", "skills": [...]}`, together with the conversation history.
872 Multi-turn container reuse needs more logic than a single shell command, so use the Anthropic SDK for it. To build the requests yourself, capture `container.id` from the first response. Then pass it in the next request as `"container": {"id": "...", "skills": [...]}`, together with the conversation history.
873873 </CodeGroupItem>
874874
875875 <CodeGroupItem language="CLI">
876 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
876 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
877877 </CodeGroupItem>
878878
879879 ```python Python
from line 1238
12381238
12391239<CodeGroup exclude="shell:cURL, shell:CLI">
12401240 <CodeGroupItem language="cURL">
1241 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
1241 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
12421242 </CodeGroupItem>
12431243
12441244 <CodeGroupItem language="CLI">
1245 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
1245 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
12461246 </CodeGroupItem>
12471247
12481248 ```python Python
from line 4263
42634263
42644264<CodeGroup exclude="shell:cURL, shell:CLI">
42654265 <CodeGroupItem language="cURL">
4266 This error-handling flow needs more logic than a single shell command, so use the Claude SDK for it. A request that fails because of a Skill problem returns HTTP 400. The `error.message` field in the JSON response body describes the problem.
4266 This error-handling flow needs more logic than a single shell command, so use the Anthropic SDK for it. A request that fails because of a Skill problem returns HTTP 400. The `error.message` field in the JSON response body describes the problem.
42674267 </CodeGroupItem>
42684268
42694269 <CodeGroupItem language="CLI">
4270 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
4270 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
42714271 </CodeGroupItem>
42724272
42734273 ```python Python
build-with-claude/streaming Changed · +8 / -8 lines
from line 26
2626 - claude-sonnet-4-5-20250929
2727 supportedPlatforms:
2828 Claude API: stable
29 Claude Platform on AWS: stable
30 Claude Models on Google Cloud (Anthropic managed): stable
3129 Amazon Bedrock: stable
32 Amazon Bedrock (InvokeModel):
30 Amazon Bedrock (bedrock-runtime):
3331 availability: stable
34 note: The older Amazon Bedrock InvokeModel integration does not stream plain server-sent events.
32 note: Amazon Bedrock's `bedrock-runtime` endpoint does not stream plain server-sent events.
33 Claude Platform on AWS: stable
34 Claude Models on Google Cloud (Anthropic managed): stable
3535 Claude Models on Google Cloud (Google managed): stable
3636 Microsoft Foundry: stable
3737---
from line 1575
15751575
15761576| Status | Cloud platforms |
15771577| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1578| Available | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) |
1579| Available<sup>1</sup> | [Amazon Bedrock (InvokeModel)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) |
1578| Available | Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) |
1579| Available<sup>1</sup> | [Amazon Bedrock (bedrock-runtime)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) |
15801580
15811. The older Amazon Bedrock InvokeModel integration does not stream plain server-sent events.
15811. Amazon Bedrock’s `bedrock-runtime` endpoint does not stream plain server-sent events.
15821582
build-with-claude/thinking Changed · +23 / -15 lines
from line 29
2929 - claude-sonnet-4-5-20250929
3030 supportedPlatforms:
3131 Claude API: stable
32 Amazon Bedrock: stable
33 Amazon Bedrock (bedrock-runtime): stable
3234 Claude Platform on AWS: stable
3335 Claude Models on Google Cloud (Anthropic managed): stable
34 Amazon Bedrock: stable
35 Amazon Bedrock (InvokeModel): stable
3636 Claude Models on Google Cloud (Google managed): stable
3737 Microsoft Foundry: stable
3838---
from line 496
496496
497497Claude Sonnet 5.5 also has thinking on by default, and it rejects `thinking: {type: "disabled"}` with a 400 error. To turn off up-front thinking, send `thinking: {type: "between_tools"}` instead. It’s the lowest thinking setting on Claude Sonnet 5.5, and it’s accepted at [effort](https://platform.claude.com/docs/en/build-with-claude/effort) `high` or below. The model still returns its [progress updates between tool calls](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates). Without tools, the response contains only text, as with `disabled` on Claude Sonnet 5. See [Running without up-front thinking](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#running-without-up-front-thinking) for prompting guidance.
498498
499Claude Haiku 5.5 also has thinking on by default and accepts `thinking: {type: "disabled"}` at [effort](https://platform.claude.com/docs/en/build-with-claude/effort) `high` or below. At `xhigh` or `max` effort, that combination returns a 400 error. To get less thinking, lower the effort level first. With thinking off, the model can skip a tool call it needs when you also request JSON output. A [per-message `output_config.effort`](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) that differs from the level in effect also returns a 400 error while thinking is off. See [Use effort to control thinking](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking) and [Use adaptive thinking with JSON output and your own tools](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#json-output-with-your-own-tools).
499Claude Haiku 5.5 also has thinking on by default and accepts `thinking: {type: "disabled"}` at [effort](https://platform.claude.com/docs/en/build-with-claude/effort) `high` or below. At `xhigh` or `max` effort, that combination returns a 400 error. To get less thinking, lower the effort level first. With thinking off, the model can skip a tool call it needs when you also request JSON output. A [per-message `output_config.effort`](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) that differs from the level in effect also returns a 400 error while thinking is off. See [Use effort to control thinking](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking) and [Use adaptive thinking with JSON output and your own tools](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#json-output-with-your-own-tools).
500500
501501Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, and Claude Mythos Preview reject `thinking: {type: "disabled"}`. Thinking can’t be turned off on these models.
502502
from line 894
894894data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}
895895```
896896
897With `display: "updates"` (beta), reasoning blocks stream as they do under `"omitted"`. Each [progress-update block](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates) streams its text as `thinking_delta` events before the `tool_use` block it introduces. A pause of several seconds before the progress-update block opens is normal:
897With `display: "updates"` (in beta), reasoning blocks stream as they do under `"omitted"`. Each [progress-update block](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates) streams its text as `thinking_delta` events before the `tool_use` block it introduces. A pause of several seconds before the progress-update block opens is normal:
898898
899899```sse Output
900900event: content_block_start
from line 940
940940
941941Thinking works alongside [tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview), letting Claude reason through tool selection and process tool results. Two constraints apply:
942942
9431. **Tool choice limitation (manual mode):** tool use with manual extended thinking (`thinking: {type: "enabled"}`) only supports `tool_choice: {"type": "auto"}` (the default) or `tool_choice: {"type": "none"}`. Using `tool_choice: {"type": "any"}` or `tool_choice: {"type": "tool", "name": "..."}` results in an error because these options force tool use, which is incompatible with manual extended thinking. Adaptive thinking, including on models where thinking is on by default, supports forced tool use, except on Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, and Claude Mythos 5.1 (see [Response prefill and forced tool use](https://platform.claude.com/docs/en/build-with-claude/thinking#limits-and-feature-compatibility)). Where forced tool use is accepted, the response starts with the tool call and has no `thinking` block.
9431. **Tool choice limitation (manual mode):** tool use with manual extended thinking (`thinking: {type: "enabled"}`) only supports `tool_choice: {"type": "auto"}` (the default) or `tool_choice: {"type": "none"}`. Using `tool_choice: {"type": "any"}` or `tool_choice: {"type": "tool", "name": "..."}` results in an error because these options force tool use, which is incompatible with manual extended thinking. Adaptive thinking, including on models where thinking is on by default, supports forced tool use, except on Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, and Claude Mythos 5.1 (see [Response prefill and forced tool use](https://platform.claude.com/docs/en/build-with-claude/thinking#response-prefill-and-forced-tool-use)). Where forced tool use is accepted, the response starts with the tool call and has no `thinking` block.
9449442. **Preserving thinking blocks:** when you return tool results, you must pass the thinking blocks from the assistant message back to the API, complete and unmodified. See [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks).
945945
946946**A tool-use loop is one assistant turn.** From the model’s perspective, an assistant turn ends only when Claude completes its full response, which might include multiple tool calls and results. This whole sequence is a single assistant turn:
from line 1004
10041004 Consecutive tool calls do not require interleaved thinking. Claude can chain tool calls with or without interleaved thinking. Interleaving changes where thinking blocks appear between tool calls, not whether tool calls can chain.
10051005</Note>
10061006
1007With adaptive thinking, interleaved thinking is automatic on every model that supports adaptive thinking. No beta header is needed. On Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Opus 4.8, and Claude Opus 4.7, reasoning between tool calls always appears in thinking blocks. Claude Haiku 4.5 does not support interleaved thinking. On models using manual extended thinking, interleaving requires a beta header and changes how the thinking budget is counted. [Interleaved thinking in manual mode](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) covers the per-model rules and platform-specific header behavior.
1007With adaptive thinking, interleaved thinking is automatic on every model that supports adaptive thinking. On Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Opus 4.8, and Claude Opus 4.7, reasoning between tool calls always appears in thinking blocks. Claude Haiku 4.5 does not support interleaved thinking. On models using manual extended thinking, interleaving requires a beta header and changes how the thinking budget is counted. [Interleaved thinking in manual mode](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) covers the per-model rules and platform-specific header behavior.
10081008
10091009With interleaved thinking, the thinking allocation can span the entire assistant turn rather than a single response. Interleaved thinking is only supported for [tools used through the Messages API](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview).
10101010
from line 1022
10221022| `"updates"` (beta) | Empty `thinking` field | Summary text |
10231023| `"summarized"` | Summary text | Summary text, not distinguishable from a reasoning block |
10241024
1025On Claude Sonnet 5.5, the lowest thinking setting is `thinking: {type: "between_tools"}`. It turns off up-front thinking, and each progress update comes back with its summary text, as it would under `display: "updates"`. `between_tools` is accepted only at [effort](https://platform.claude.com/docs/en/build-with-claude/effort) `high` or below. At `xhigh` or `max`, a request with it returns a 400 error. `between_tools` takes no other field: `display`, `budget_tokens`, or `block_binding` sent with it returns a 400 error. The setting needs no beta header and works on every platform that offers Claude Sonnet 5.5. Pass the blocks back unchanged: a progress-update block you send back gives the model the full note it wrote, not the summary.
1025On Claude Sonnet 5.5, the lowest thinking setting is `thinking: {type: "between_tools"}`. It turns off up-front thinking, and each progress update comes back with its summary text, as it would under `display: "updates"`. `between_tools` is accepted only at [effort](https://platform.claude.com/docs/en/build-with-claude/effort) `high` or below. At `xhigh` or `max`, a request with it returns a 400 error. `between_tools` takes no other field: `display`, `budget_tokens`, or `block_binding` sent with it returns a 400 error. The setting works on every platform that offers Claude Sonnet 5.5. Pass the blocks back unchanged: a progress-update block you send back gives the model the full note it wrote, not the summary.
10261026
10271027Use `display: "updates"` for an agent interface that keeps reasoning hidden and shows the user a status line at each step. Under it, any `thinking` block with non-empty text is a progress update, so render those and nothing else. It’s in beta and requires the beta header `thinking-display-updates-2026-08-18` (to send it on Amazon Bedrock, Claude Models on Google Cloud (Google managed), or Microsoft Foundry, see [Beta features on other platforms](https://platform.claude.com/docs/en/api/beta-headers#beta-features-on-other-platforms)). Without it, the value is rejected with the same 400 `invalid_request_error` as an unknown `display` value.
10281028
from line 1085
10851085* The text you receive is a summary of the progress update, normally a sentence or two. Don’t rely on its length. The progress update counts toward `usage.output_tokens` at its full length, not the summary’s.
10861086* A progress-update block can come back with an empty `thinking` field under any `display` value. Render nothing for an empty block. Under `"updates"` it looks the same as an empty reasoning block and needs no separate handling.
10871087* When a response stops on `max_tokens`, `model_context_window_exceeded`, or `stop_sequence` soon after a tool call or tool result, its last block can be a progress-update block standing in for the work the model hadn’t completed. Under `"updates"` and `"summarized"` its text is exactly `This part of the response was interrupted before it finished.` and you can show it like any other update. Under `"omitted"` it’s empty. To continue, pass the assistant turn back unchanged and append a new `user` message (with a `tool_result` for each `tool_use` block in that turn).
1088* When [streaming](https://platform.claude.com/docs/en/build-with-claude/thinking#streaming-thinking), expect a pause of several seconds before a progress-update block opens. See the `"updates"` trace in [Streaming thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#streaming-thinking).
1088* When streaming, expect a pause of several seconds before a progress-update block opens. See the `"updates"` trace in [Streaming thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#streaming-thinking).
10891089* These models write fewer progress updates at higher [effort](https://platform.claude.com/docs/en/build-with-claude/effort) and in long tool chains. If your interface depends on them, see [Ask for user-facing progress updates](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#ask-for-user-facing-progress-updates). For Claude Opus 5.5 and Claude Sonnet 5.5, see User-facing progress updates in [Prompting Claude Opus 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates) or [Prompting Claude Sonnet 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#user-facing-progress-updates). For Claude Fable 5.2, see [Keep users informed during long turns](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#keep-users-informed-during-long-turns).
10901090
10911091### Thinking block preservation by model
from line 1100
11001100* **Cache optimization:** preserved thinking blocks allow cache hits during tool use, as they are passed back with tool results and cached incrementally across the assistant turn, resulting in token savings in multistep workflows.
11011101* **No intelligence impact:** preserving thinking blocks has no negative effect on model performance.
11021102
1103The tradeoff is context usage: long conversations consume more context space on keep-all models, because retained thinking blocks count as input like any other conversation history (see [Thinking and the context window](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-the-context-window)). The behavior is automatic in both regimes. No code changes or beta headers are required, and you should keep passing complete, unmodified thinking blocks back as described in [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks). To override the default in either direction, use [thinking block clearing](https://platform.claude.com/docs/en/build-with-claude/context-editing#thinking-block-clearing).
1103The tradeoff is context usage: long conversations consume more context space on keep-all models, because retained thinking blocks count as input like any other conversation history (see [Thinking and the context window](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-the-context-window)). The behavior is automatic in both regimes. Keep passing complete, unmodified thinking blocks back, as described in [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks). To override the default in either direction, use [thinking block clearing](https://platform.claude.com/docs/en/build-with-claude/context-editing#thinking-block-clearing).
11041104
1105**Switching models mid-conversation.** Keep passing thinking blocks back unchanged when you switch models, for example after a [classifier refusal fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback). A thinking block is readable only by the model that produced it and certain other models, and the API ignores or drops the blocks the target model can’t read. On Claude Fable 5.1 and Claude Mythos 5.1 the direction matters: they read earlier models’ thinking blocks, and only they and, on the Claude API, Claude Fable 5.2 and Claude Mythos 5.2 read those two models’ blocks, so switching to them keeps the conversation’s reasoning and switching from them to any model outside that group drops it (see [how dropped blocks are billed and reported](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). Claude Opus 5.5 reads Claude Opus 5’s thinking blocks and those of earlier Opus, Sonnet, and Haiku models, and, on the Claude API and Claude Models on Google Cloud (Google managed), of Claude Sonnet 5.5 and Claude Haiku 5.5, but not those of the Claude Fable and Claude Mythos models; on the Claude API, Claude Fable 5.1 and Claude Mythos 5.1 read Claude Opus 5.5’s blocks. A switch from Claude Opus 5.5 up to Claude Fable 5.1 on the Claude API keeps the earlier turns’ reasoning; a switch from Claude Fable 5.1 to Claude Opus 5.5 drops it. On the Claude API, Claude Fable 5.2 and Claude Mythos 5.2 read each other’s thinking blocks and those from other models, including Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5. No other model reads their blocks, so a switch from either of them to any other model drops the earlier turns’ reasoning. On Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 read the same blocks as on the Claude API. Claude Sonnet 5.5 reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models, and, on the Claude API and Claude Models on Google Cloud (Google managed), from Claude Haiku 5.5, but not from Claude Opus 5, Claude Opus 5.5, or any Claude Fable or Claude Mythos model. On those two platforms, Claude Opus 5.5 reads Claude Sonnet 5.5’s blocks, as do Claude Fable 5.2 and Claude Mythos 5.2 on the Claude API, and no other model does: a switch from Claude Sonnet 5.5 up to Claude Opus 5.5 there, or to Claude Fable 5.2 or Claude Mythos 5.2 where they read Claude Sonnet 5.5 blocks, keeps the earlier turns’ reasoning, and any other switch away from Claude Sonnet 5.5 drops it. Claude Haiku 5.5 reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models, but not from Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, or any Claude Fable or Claude Mythos model. On the Claude API and Claude Models on Google Cloud (Google managed), Claude Opus 5.5 and Claude Sonnet 5.5 read Claude Haiku 5.5’s blocks, as do Claude Fable 5.2 and Claude Mythos 5.2 on the Claude API, and no other model does. Strip prior `thinking` and `redacted_thinking` blocks yourself only to save input tokens on models that ignore rather than drop them, and never when redeeming a [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit), which requires the body unchanged.
1105**Switching models mid-conversation.** Keep passing thinking blocks back unchanged when you switch models, for example after a [classifier refusal fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback). A thinking block is readable only by the model that produced it and certain other models. The API ignores or drops the blocks that the target model can’t read (see [how dropped blocks are billed and reported](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). The following list says, for each model in it, what the model reads and which models read its blocks:
11061106
1107* **Claude Fable 5.2 and Claude Mythos 5.2:** On the Claude API and Claude Models on Google Cloud (Google managed), they read each other’s thinking blocks. There, they also read blocks from other models, including Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5. No other model reads Claude Fable 5.2 or Claude Mythos 5.2 blocks. So a switch from either to a model outside this pair drops the earlier turns’ reasoning.
1108* **Claude Fable 5.1 and Claude Mythos 5.1:** They read each other’s thinking blocks and those of earlier models, except Claude Mythos Preview’s. On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 also read their blocks. No other model does. A switch to Claude Fable 5.1 or Claude Mythos 5.1 from a model whose blocks they read keeps the conversation’s reasoning. A switch from either to a model that can’t read their blocks drops it.
1109* **Claude Opus 5.5:** It reads thinking blocks from Claude Opus 5 and from earlier Opus, Sonnet, and Haiku models. On the Claude API and Claude Models on Google Cloud (Google managed), it also reads them from Claude Sonnet 5.5 and Claude Haiku 5.5. It doesn’t read them from the Claude Fable and Claude Mythos models. On the Claude API, Claude Fable 5.1 and Claude Mythos 5.1 read Claude Opus 5.5’s blocks. On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 also read them. A switch from Claude Opus 5.5 up to Claude Fable 5.1 on the Claude API keeps the earlier turns’ reasoning. A switch from Claude Fable 5.1 to Claude Opus 5.5 drops it.
1110* **Claude Sonnet 5.5:** It reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models. On the Claude API and Claude Models on Google Cloud (Google managed), it also reads them from Claude Haiku 5.5. It doesn’t read them from Claude Opus 5, Claude Opus 5.5, or any Claude Fable or Claude Mythos model. On those two platforms, Claude Opus 5.5, Claude Fable 5.2, and Claude Mythos 5.2 read Claude Sonnet 5.5’s blocks. No other model does. A switch from Claude Sonnet 5.5 up to one of those three models there keeps the earlier turns’ reasoning. Any other switch away from Claude Sonnet 5.5 drops it.
1111* **Claude Haiku 5.5:** It reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models. It doesn’t read them from Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, or any Claude Fable or Claude Mythos model. Four models read Claude Haiku 5.5’s blocks: Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2, and Claude Mythos 5.2. They do so on the Claude API and Claude Models on Google Cloud (Google managed). No other model does.
1112
1113Strip prior `thinking` and `redacted_thinking` blocks yourself only to save input tokens on models that ignore rather than drop them. Never strip them when redeeming a [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit), which requires the body unchanged.
1114
11071115## Preserved thinking
11081116
11091117[Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking) determines whether the model can use a thinking block that you send back from an earlier turn. The API checks the `signature` of every `thinking` or `redacted_thinking` block in a request for two things:
11101118
11111119* **The model that produced it.** Each model reads its own thinking blocks and those of a fixed set of other models. Claude Fable 5.1 reads blocks from Claude Opus 5 and, on the Claude API, from Claude Opus 5.5; neither Claude Opus 5 nor Claude Opus 5.5 reads blocks from Claude Fable 5.1. The API drops a block the current model can’t read, without an error and without billing it. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
1112* **Everything sent before it.** A block stays valid only while the top-level `system` prompt, the `tools`, and the messages before it are unchanged. If any of them changes, that block and every later thinking block fail the prefix check. See [Keeping the prefix unchanged](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check).
1120* **Everything sent before it.** A block stays valid only while the top-level `system` prompt, the `tools`, and the messages before it are unchanged. If any of them changes, that block and every later thinking block already in the history fail the prefix check. See [Keeping the prefix unchanged](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check).
11131121
11141122Thinking blocks from Claude Sonnet 5.5, Claude Haiku 5.5, Claude Fable 5.2, and Claude Mythos 5.2 are also tied to the account that produced them. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking) for where this applies.
11151123
from line 1134
11261134
11271135[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) interacts with thinking in a few specific ways. The following rules apply in both thinking modes.
11281136
1129**Configuration changes invalidate caching.** The thinking configuration and the resolved [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) level are rendered into the prompt itself, so changing any of them starts a new cache prefix. Switching between `adaptive`, `enabled`, and `disabled`, changing `budget_tokens`, and changing the effort value all invalidate cache breakpoints: message-level breakpoints always miss, and tool and system-prompt breakpoints can miss too, depending on where the model renders the configuration. Treat any thinking or top-level effort change as starting the cache over. On models that support [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta), an effort change carried in a `role: "system"` message inside `messages` leaves the cached prefix intact. Consecutive requests that keep the same configuration preserve the cache, and setting a parameter explicitly to its default value is equivalent to omitting it. A thinking block the API drops under any [preserved-thinking condition](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking) changes the cached prefix from that block’s position onward. Blocks passed back unchanged keep the cache intact. A worked demonstration with usage output is on the [Steering thinking](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#prompt-caching) page.
1137**Configuration changes invalidate caching.** The thinking configuration and the resolved [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) level are rendered into the prompt itself, so changing any of them starts a new cache prefix. Switching between `adaptive`, `enabled`, and `disabled`, changing `budget_tokens`, and changing the effort value all invalidate cache breakpoints: message-level breakpoints always miss, and tool and system-prompt breakpoints can miss too, depending on where the model renders the configuration. Treat any thinking or top-level effort change as starting the cache over. On models that support [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message), an effort change carried in a `role: "system"` message inside `messages` leaves the cached prefix intact. Consecutive requests that keep the same configuration preserve the cache, and setting a parameter explicitly to its default value is equivalent to omitting it. A thinking block the API drops under any [preserved-thinking condition](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking) changes the cached prefix from that block’s position onward. Blocks passed back unchanged keep the cache intact. A worked demonstration with usage output is on the [Steering thinking](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#prompt-caching) page.
11301138
11311139**Thinking blocks are cached with tool results.** During a tool-use loop, caching occurs when you make a follow-up request that includes tool results. At that point the previous conversation history, including its thinking blocks, can be cached, and those cached thinking blocks count as input tokens in your usage metrics when read from the cache. This occurs automatically, even without explicit `cache_control` markers, and behaves the same for regular and interleaved thinking. The tradeoff: thinking blocks you never see again in responses still contribute to input token usage when read from cache.
11321140
from line 1168
11601168
11611169## Thinking and the context window
11621170
1163`max_tokens`, which includes all thinking Claude generates in the current turn, is enforced as a strict limit. On Claude 4.5 models and newer, if input tokens plus `max_tokens` exceeds the context window size, the API accepts the request. If generation then reaches the context window limit, it stops with `stop_reason: "model_context_window_exceeded"` instead of returning an error. On earlier models, the API returns a validation error instead. See [Handling stop reasons](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons).
1171`max_tokens`, which includes all thinking Claude generates in the current turn, is enforced as a strict limit. On Claude 4.5 models and newer, if input tokens plus `max_tokens` exceeds the context window size, the API accepts the request. If generation then reaches the context window limit, it stops with `stop_reason: "model_context_window_exceeded"` instead of returning an error. On earlier models, the API returns a validation error instead. See [Stop reasons and fallback](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons).
11641172
11651173How thinking counts against the window depends on when it was generated:
11661174
from line 1205
11971205* When [streaming responses](https://platform.claude.com/docs/en/build-with-claude/thinking#streaming-thinking), the signature arrives as a `signature_delta` inside a `content_block_delta` event just before the `content_block_stop` event.
11981206* `signature` values are significantly longer in Claude 4 and later models than in previous models.
11991207* The `signature` field is opaque: don’t interpret or parse it.
1200* `signature` values are compatible across platforms, including the Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), and [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed). Values generated on one platform work on another, except that thinking blocks from Claude Sonnet 5.5, Claude Haiku 5.5, Claude Fable 5.2, and Claude Mythos 5.2 work only in the account that produced them or in an account linked to it. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
1208* `signature` values are compatible across platforms, including the Claude API, [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), and [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed). Values generated on one platform work on another, except that thinking blocks from Claude Sonnet 5.5, Claude Haiku 5.5, Claude Fable 5.2, and Claude Mythos 5.2 work only in the account that produced them or in an account linked to it. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
12011209
12021210## Redacted thinking blocks
12031211
build-with-claude/thinking-steering-and-cost Changed · +14 / -14 lines
from line 24
2424
2525If you want Claude to think less often, lower the effort level before reaching for prompt-based steering.
2626
27Thinking also interleaves with tool use automatically: Claude can think between tool calls, evaluating each tool result before determining what to do next ([interleaved thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#interleaved-thinking)). You don’t need a beta header or any additional configuration for this.
27Thinking also interleaves with tool use automatically: Claude can think between tool calls, evaluating each tool result before determining what to do next ([interleaved thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#interleaved-thinking)).
2828
2929For full details on how the thinking configuration and the effort parameter interact, see [Thinking and effort](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-effort).
3030
from line 96
9696
9797Per-message steering is useful when only some requests in a conversation warrant extended reasoning. An agent harness, for example, can append the encouraging phrase on planning steps and the discouraging phrase on routine confirmations, without touching the system prompt or changing any request parameters between turns.
9898
99On Claude Haiku 5.5, the discouraging phrase doesn’t reliably reduce thinking. Where your platform supports it, run routine turns on that model with less thinking by using a [per-message effort change](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) (beta) instead, which also keeps the prompt cache. The same holds for Claude Fable 5.2. In Anthropic’s testing, the discouraging phrase didn’t stop the model from thinking at `medium` effort and above. Where your platform supports it, use a per-message effort change for those turns.
99On Claude Haiku 5.5 and Claude Fable 5.2, the discouraging phrase doesn’t reliably reduce thinking. In Anthropic’s testing, it didn’t stop Claude Fable 5.2 from thinking at `medium` effort and above. Where your platform supports it, run routine turns on these models with less thinking by using a [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) change instead. This beta feature also keeps the prompt cache.
100100
101101### Verify steering on your workload
102102
from line 114
114114
115115Assistant turns don’t need to start with a thinking block. (Models using a legacy manual thinking budget enforce that the final assistant turn of a thinking-enabled request starts with one; see [Turn structure in manual mode](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#turn-structure-in-manual-mode).)
116116
117For multi-turn applications, this means you can pass back conversation history in whatever shape you have it:
117For multi-turn applications, this means you can pass back conversation history in any of these shapes:
118118
119119* Assistant turns that Claude produced without thinking are valid history as-is.
120120* You can resume a conversation that started without thinking, or that used a different thinking configuration, without rewriting its history.
121121* History assembled from mixed sources doesn’t need thinking blocks reinserted at the start of each assistant turn to pass validation.
122122
123The relaxation is about validation, not about what you should send. When you have thinking blocks, pass them back unmodified, particularly during tool use, where they carry the reasoning behind Claude’s tool calls. See the [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) overview for the full rules.
123This rule is about validation, not about what you should send. When you have thinking blocks, pass them back unmodified, particularly during tool use, where they carry the reasoning behind Claude’s tool calls. See the [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) overview for the full rules.
124124
125125### Prompt caching
126126
127127Consecutive requests that keep the same thinking configuration and effort level preserve prompt caching; see [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching) for the full rules. The resolved effort value is rendered into the prompt, so changing it between requests invalidates cache breakpoints, just as changing the legacy [`budget_tokens`](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#extended-thinking-with-prompt-caching) parameter does on models that use it. Setting `effort` explicitly to the model’s default is equivalent to omitting it and does not break the cache.
128128
129The practical consequence: pick a thinking configuration and a top-level effort level for each conversation and keep them. If some turns need more or less thinking, use a [per-message effort change](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) (beta) on models that support it, or steer with [per-message prompting](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#tuning-thinking-behavior). Both leave earlier cache breakpoints intact, where a change to the thinking configuration or the top-level effort level does not.
129The practical consequence: pick a thinking configuration and a top-level effort level for each conversation and keep them. If some turns need more or less thinking, use a [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) change, which is in beta, on models that support it, or steer with [per-message prompting](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#tuning-thinking-behavior). Both leave earlier cache breakpoints intact, where a change to the thinking configuration or the top-level effort level does not.
130130
131131The following example demonstrates the invalidation with a multi-turn script you can run yourself:
132132
from line 133
133133<Accordion title="Effort changes invalidate the prompt cache">
134134 <CodeGroup exclude="shell:cURL, shell:CLI">
135135 <CodeGroupItem language="cURL">
136 This workflow needs more logic than a single shell command. Use the Claude SDK to run it; per-turn HTTP requests follow the examples on the [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) page.
136 This workflow needs more logic than a single shell command. Use the Anthropic SDK to run it; per-turn HTTP requests follow the examples on the [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) page.
137137 </CodeGroupItem>
138138
139139 <CodeGroupItem language="CLI">
140 This workflow needs more logic than a single shell command. Use the Claude SDK to run it; per-turn CLI commands follow the examples on the [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) page.
140 This workflow needs more logic than a single shell command. Use the Anthropic SDK to run it; per-turn CLI commands follow the examples on the [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) page.
141141 </CodeGroupItem>
142142
143143 ```python Python
from line 621
621621 ]
622622 ]
623623 ]],
624 model: 'claude-opus-5-5',
624 model: Model::CLAUDE_OPUS_5_5,
625625 thinking: ['type' => 'adaptive'],
626626 );
627627
from line 654
654654 'content' => 'Analyze the characters in this passage.'
655655 ]
656656 ],
657 model: 'claude-opus-5-5',
657 model: Model::CLAUDE_OPUS_5_5,
658658 thinking: ['type' => 'adaptive'],
659659 );
660660
from line 695
695695 'content' => 'Analyze the setting in this passage.'
696696 ]
697697 ],
698 model: 'claude-opus-5-5',
698 model: Model::CLAUDE_OPUS_5_5,
699699 thinking: ['type' => 'adaptive'],
700700 outputConfig: ['effort' => 'low'],
701701 );
from line 724
724724
725725 puts "First request - establishing cache"
726726 response1 = client.messages.create(
727 model: "claude-opus-5-5",
727 model: Anthropic::Model::CLAUDE_OPUS_5_5,
728728 max_tokens: 16000,
729729 thinking: {
730730 type: "adaptive"
from line 749
749749
750750 puts "\nSecond request - same configuration (cache hit expected)"
751751 response2 = client.messages.create(
752 model: "claude-opus-5-5",
752 model: Anthropic::Model::CLAUDE_OPUS_5_5,
753753 max_tokens: 16000,
754754 thinking: {
755755 type: "adaptive"
from line 784
784784
785785 puts "\nThird request - different effort level (cache miss expected)"
786786 response3 = client.messages.create(
787 model: "claude-opus-5-5",
787 model: Anthropic::Model::CLAUDE_OPUS_5_5,
788788 max_tokens: 16000,
789789 thinking: {
790790 type: "adaptive"
from line 871
871871* Standard text output tokens
872872
873873<Note>
874 When thinking is active, a specialized system prompt is automatically included to support this feature.
874 When thinking is active, the API automatically includes a specialized system prompt to support this feature.
875875</Note>
876876
877877What you’re billed for is the same regardless of the `display` setting; only what you see changes:
build-with-claude/thinking-tool-workflows Changed · +11 / -3 lines
from line 14
1414
1515Each link leads to the full statement on the Thinking page:
1616
17* [Limit tool choice to `auto` or `none` in manual mode](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use): `tool_choice` options that force tool use return an error with manual extended thinking (`thinking: {type: "enabled"}`). Adaptive thinking supports forced tool use, with exceptions. Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, and Claude Mythos 5.1 return a 400 error instead. Where forced tool use is accepted, it skips thinking: the response starts with the tool call.
17* [Limit tool choice to `auto` or `none` in manual mode](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use): with manual extended thinking (`thinking: {type: "enabled"}`), `tool_choice` options that force tool use return an error.
18
19* [Check forced tool use on your model in adaptive mode](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use): with adaptive thinking, the result depends on the model:
20
21 * **Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, and Claude Mythos 5.1:** Forced tool use returns a 400 error.
22 * **Other models:** Forced tool use is accepted, and it skips thinking. The response starts with the tool call.
23
1824* [Keep one thinking configuration per assistant turn](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use): a tool-use loop is one assistant turn, so change the configuration only between turns.
25
1926* [Pass thinking blocks back complete and unmodified](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks): when you return a tool result, the thinking blocks from the assistant message must come back with it.
27
2028* [Echo the assistant message exactly as received](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks): rebuilding the message or filtering out `redacted_thinking` blocks triggers a 400 error.
2129
2230The samples use adaptive thinking; on models that support only extended thinking, substitute `thinking: {type: "enabled", budget_tokens: N}`. The round-trip rules are identical.
from line 323
315323
316324 <CodeGroup exclude="shell:cURL, shell:CLI">
317325 <CodeGroupItem language="cURL">
318 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
326 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
319327 </CodeGroupItem>
320328
321329 <CodeGroupItem language="CLI">
322 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
330 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
323331 </CodeGroupItem>
324332
325333 ```python Python
build-with-claude/thinking-troubleshooting Changed · +13 / -13 lines
from line 56
5656"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
5757```
5858
59This occurs because the model you requested has removed extended thinking (see the [per-model configuration table](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#rejected-configurations)).
59This occurs because the model you requested doesn’t support extended thinking (see the [per-model configuration table](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#rejected-configurations)).
6060
6161Switch the request to `thinking: {type: "adaptive"}` and steer thinking depth with `effort` instead of `budget_tokens`. [Migrating to adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#migrating-to-adaptive-thinking) walks through the conversion.
6262
6363## A 400 error after sending `thinking: {type: "disabled"}`
6464
65The request fails with a 400 error. On Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Opus 5.5, and Claude Mythos 5, the message reads:
65The request fails with a 400 error. On Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, and Claude Opus 5.5, the message reads:
6666
6767```text wrap
6868"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
from line 116
116116
117117## A 400 error says effort cannot change when thinking is disabled
118118
119On Claude Sonnet 5.5, a request with `thinking: {type: "between_tools"}` whose [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) changes the level fails with a 400 error whose message reads:
119On Claude Sonnet 5.5, a request with `thinking: {type: "between_tools"}` whose [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) changes the level fails with a 400 error whose message reads:
120120
121121```text wrap
122122messages.N: output_config.effort 'low' differs from the 'high' in effect before it; effort cannot change when thinking is disabled on this model. Use effort 'high', or enable thinking.
from line 148
148148`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified
149149```
150150
151In multi-turn and tool-use conversations you send previous assistant messages, including their `thinking` and `redacted_thinking` blocks, back to the API, and the API verifies they arrive unmodified. This error occurs when the assistant message you send back differs from the one the API returned, most often because your code filters content blocks by type and drops `redacted_thinking` blocks, or rebuilds the assistant message instead of echoing it.
151In multi-turn and tool-use conversations, you send previous assistant messages back to the API, including their `thinking` and `redacted_thinking` blocks. The API verifies that they arrive unmodified. This error occurs when the assistant message you send back differs from the one the API returned. The most common causes are code that filters content blocks by type and drops `redacted_thinking` blocks, and code that rebuilds the assistant message instead of echoing it.
152152
153153Echo the assistant turn back verbatim, thinking blocks included. See [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks) for the rules, and the worked round trip in [Thinking in tool and multi-turn workflows](https://platform.claude.com/docs/en/build-with-claude/thinking-tool-workflows#two-turn-tool-use-round-trip) for correct code in every SDK.
154154
from line 164
164164
165165The message usually ends with a sentence naming what changed: the `system` prompt, the `tools` list, the first message or block that differs, content that is missing or new, or an earlier thinking block that is missing or out of order. That sentence is for people and logs. Its wording can change, so don’t match on it in code.
166166
167If the message stops after ``Invalid `signature` in `thinking` block``, the signature itself didn’t verify: it was truncated, altered, or sent back empty, and `prefix_mismatch_behavior` doesn’t apply. Edited thinking text returns a different error. See [A 400 error says thinking blocks cannot be modified](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified).
167If the message stops after ``Invalid `signature` in `thinking` block``, the signature itself didn’t verify: it was truncated, altered, or sent back empty, and `prefix_mismatch_behavior` doesn’t apply.
168168
169These models accept a replayed thinking block only while the `system` prompt, `tools`, and messages that preceded it are unchanged. See [Keeping the prefix unchanged](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check). The error means something earlier in the conversation changed between requests. Common causes include the following:
169A replayed thinking block passes the prefix check only while the `system` prompt, `tools`, and messages that preceded it are unchanged. See [Keeping the prefix unchanged](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check). The error means something earlier in the conversation changed between requests. Common causes include the following:
170170
171171* An edited, reordered, or removed turn
172172* A per-turn reminder that was injected and later removed
from line 175
175175
176176Server-side [compaction at a token threshold](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold) and [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) never trigger this error. With [on-demand compaction](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand), thinking in the turns you keep after the summary triggers it when one of the [conditions for kept thinking](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks#conditions-for-kept-thinking-to-stay-valid) doesn’t hold. For requests that don’t set `thinking.block_binding.prefix_mismatch_behavior`, see [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement).
177177
178Retrying the same request body doesn’t clear the error. Neither does fixing your code, because the stored history holds the edit. To continue the conversation, do one of the following:
178Retrying the same request body doesn’t clear the error. Neither does fixing your code, if the stored history holds the edit. To continue the conversation, do one of the following:
179179
180180* Send the `thinking-binding-controls-2026-08-01` beta header and set `thinking.block_binding.prefix_mismatch_behavior` to `"drop_block"` on the retry and every later request. The request then succeeds without the invalidated reasoning. On Claude Sonnet 5.5 and Claude Haiku 5.5, `block_binding` works only with `thinking: {"type": "adaptive"}`. With any other thinking setting on those models, you can’t send `block_binding`, so use the next option.
181* Strip the block the error names and every later `thinking` and `redacted_thinking` block, leaving each turn’s other blocks in place, then retry once.
181* Strip the block the error names and every later `thinking` and `redacted_thinking` block, leaving each turn’s other blocks in place. Retry, and leave the stripped blocks out of later requests.
182182
183183Then fix the cause so that new conversations don’t hit the error. Keep the history append-only: pass earlier turns back exactly as sent and received, add instructions with a [mid-conversation system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) instead of editing `system` or `tools`, and let server-side [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) or [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) do any trimming.
184184
from line 188
188188
189189The response contains `thinking` blocks, but their `thinking` field is an empty string and only the `signature` field is populated.
190190
191This occurs because `display` defaults to `"omitted"` on newer models, which returns thinking blocks without their text.
191This occurs because `display` defaults to `"omitted"` on some models (see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display)), which returns thinking blocks without their text.
192192
193Set `display: "summarized"` in your thinking configuration to receive the summarized thinking text. See [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display) for each model’s default. If you only want the short status lines some models write between tool calls, and not the reasoning, set `display: "updates"` (beta) instead. See [Progress updates between tool calls](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates).
193Set `display: "summarized"` in your thinking configuration to receive the summarized thinking text. See [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display) for each model’s default. If you only want the short status lines some models write between tool calls, and not the reasoning, set `display: "updates"`, which is in beta, instead. See [Progress updates between tool calls](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates).
194194
195195A block whose `thinking` field is empty is still complete: the `signature` holds the reasoning. Send it back with the turn like any other. See [Send assistant turns back exactly as returned](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#append-assistant-turns-exactly-as-returned).
196196
from line 224
224224
225225`cache_read_input_tokens` falls to zero on requests that previously hit the cache.
226226
227This happens because the thinking configuration and the effort level (or its default) are part of the cached prompt prefix, so changing any of them starts a new prefix: switching thinking modes, changing the effort value, and changing `budget_tokens` all invalidate message cache breakpoints, and can invalidate tool and system-prompt breakpoints too, depending on where the model renders the configuration.
227This occurs because the thinking configuration and the effort level (or its default) are part of the cached prompt prefix, so changing any of them starts a new prefix. Switching thinking modes, changing the effort value, and changing `budget_tokens` all invalidate message cache breakpoints. They can invalidate tool and system-prompt breakpoints too, depending on where the model renders the configuration.
228228
229229Keep the thinking configuration and effort level constant across requests that share a conversation; setting a parameter explicitly to its default is equivalent to omitting it and does not invalidate. See [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching).
230230
build-with-claude/vision Changed · +4 / -4 lines
from line 26
2626 - claude-sonnet-4-5-20250929
2727 supportedPlatforms:
2828 Claude API: stable
29 Claude Platform on AWS: stable
30 Claude Models on Google Cloud (Anthropic managed): stable
3129 Amazon Bedrock:
3230 availability: stable
3331 note: Only base64 image sources; per-image limit 5 MB (base64-encoded) and a lower total request size.
34 Amazon Bedrock (InvokeModel):
32 Amazon Bedrock (bedrock-runtime):
3533 availability: stable
3634 note: Only base64 image sources; per-image limit 5 MB (base64-encoded) and a lower total request size.
35 Claude Platform on AWS: stable
36 Claude Models on Google Cloud (Anthropic managed): stable
3737 Claude Models on Google Cloud (Google managed):
3838 availability: stable
3939 note: Only base64 image sources; per-image limit 5 MB (base64-encoded) and a lower total request size.
from line 1431
14311431| Status | Cloud platforms |
14321432| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14331433| Available | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) |
1434| Available<sup>1</sup> | [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (InvokeModel)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed) |
1434| Available<sup>1</sup> | [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (bedrock-runtime)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed) |
14351435
143614361. Only base64 image sources; per-image limit 5 MB (base64-encoded) and a lower total request size.
14371437
build-with-claude/working-with-messages Changed · +7 / -7 lines
from line 29
2929 - claude-sonnet-4-5-20250929
3030 supportedPlatforms:
3131 Claude API: stable
32 Amazon Bedrock: stable
33 Amazon Bedrock (bedrock-runtime): stable
3234 Claude Platform on AWS: stable
3335 Claude Models on Google Cloud (Anthropic managed): stable
34 Amazon Bedrock: stable
35 Amazon Bedrock (InvokeModel): stable
3636 Claude Models on Google Cloud (Google managed): stable
3737 Microsoft Foundry: stable
3838---
from line 183
183183}
184184```
185185
186Refusal responses (`stop_reason: "refusal"`) also include a `stop_details` object identifying the policy category that triggered the refusal, on every model. See [Handling stop reasons](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response) for the field reference and example handling code.
186Refusal responses (`stop_reason: "refusal"`) also include a `stop_details` object identifying the policy category that triggered the refusal, on every model. See [What a refusal looks like](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response) for the field reference and example handling code.
187187
188188## Multiple conversational turns
189189
from line 354
354354
355355### System role in messages
356356
357You can include messages with `"role": "system"` after a user turn to add a new system instruction partway through a conversation, subject to [placement rules](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations). This works on Claude Fable 5.2, [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Opus 5.5, Claude Opus 4.8, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5. A `system` message that carries content cannot be the first entry in `messages`. Use the top-level `system` field for instructions that apply from the start.
357To add a new system instruction partway through a conversation, include a message with `"role": "system"` right after a user turn. That message can’t be the first entry in `messages`. This works on Claude Fable 5.2, [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5.5, and Claude Haiku 5.5. See the full [placement rules](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations).
358358
359359A mid-conversation system message has the same authority as the top-level `system` field, but because it is appended to the end of the message history, it does not invalidate any cached prefix that came before it. Use the top-level `system` field for instructions that should apply from the very first turn, and a mid-conversation system message for instructions that only become relevant later.
360360
361See [Mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) for the complete guide, including how to combine it with [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).
361See [Mid-conversation system messages and tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) for the complete guide, including how to combine it with [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).
362362
363363## Prefilling Claude’s response
364364
365You can prefill part of Claude’s response in the last position of the input messages list. Use this technique to shape Claude’s response. The following example uses `"max_tokens": 1` to get a single multiple choice answer from Claude.
365You can prefill part of Claude’s response in the last position of the input messages list. Use this technique to shape Claude’s response. The following example uses `"max_tokens": 1` to get a single multiple-choice answer from Claude.
366366
367367<Warning>
368 Prefilling is not supported on Claude 4.6 and later models and [Claude Mythos Preview](https://anthropic.com/glasswing). Requests using prefill with these models return a 400 error. Use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) on models that support it, or system prompt instructions, instead. See the [migration guide](https://platform.claude.com/docs/en/about-claude/models/migration-guide) for migration patterns.
368 Prefilling is not supported on Claude 4.6 and later models and [Claude Mythos Preview](https://anthropic.com/glasswing). Requests using prefill with these models return a 400 error. Use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) on models that support it, or system prompt instructions, instead. See [Migration guides](https://platform.claude.com/docs/en/about-claude/models/migration-guide) for migration patterns.
369369</Warning>
370370
371371<CodeGroup>
cli-sdks-libraries/libraries/openai-sdk Changed · +30 / -30 lines
from line 178
178178 ```
179179
180180 <CodeGroupItem language="PHP">
181 OpenAI has no official PHP SDK. To use Claude from PHP, use the [Claude SDK for PHP](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/php) instead.
181 OpenAI has no official PHP SDK. To use Claude from PHP, use the [Anthropic SDK for PHP](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/php) instead.
182182 </CodeGroupItem>
183183
184184 ```ruby Ruby
from line 296
296296 ```
297297
298298 <CodeGroupItem language="PHP">
299 OpenAI has no official PHP SDK. To use Claude from PHP, use the [Claude SDK for PHP](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/php) instead.
299 OpenAI has no official PHP SDK. To use Claude from PHP, use the [Anthropic SDK for PHP](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/php) instead.
300300 </CodeGroupItem>
301301
302302 ```ruby Ruby
from line 318
318318
319319#### Simple fields
320320
321| Field | Support status |
322| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
323| `model` | Use Claude model names |
324| `max_tokens` | Fully supported |
325| `max_completion_tokens` | Fully supported |
326| `stream` | Fully supported |
327| `stream_options` | Fully supported |
328| `top_p` | Passed through to the model. Claude 4.7 and later models and Claude Mythos Preview return a 400 error for any value other than `0.99`, the default, so omit it. A request that sets both `temperature` and `top_p` also returns a 400 error. See [Using the Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). |
329| `parallel_tool_calls` | Fully supported |
330| `tool_choice` | Supported with limits. `"required"` and a named function force a tool call. Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and Claude Mythos 5.1 don’t support forced tool use and return a 400 error, so use `"auto"` on those models. See [Forcing tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools#forcing-tool-use). |
331| `stop` | All non-whitespace stop sequences work |
332| `temperature` | Between 0 and 1 (inclusive). Values greater than 1 are capped at 1. On Claude 4.7 and later models and Claude Mythos Preview, any value below 1 returns a 400 error, so omit it. See [Using the Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). |
333| `n` | Must be exactly 1. Any other value returns a 400 error. |
334| `response_format` | Supported with limits. Only `json_schema` with `strict: true` is accepted, and the structured outputs [JSON Schema limitations](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#json-schema-limitations) apply. Any other value, including `json_object` and `text`, returns a 400 error. |
335| `logprobs` | Ignored |
336| `metadata` | Ignored |
337| `prediction` | Ignored |
338| `presence_penalty` | Ignored |
339| `frequency_penalty` | Ignored |
340| `seed` | Ignored |
341| `service_tier` | Ignored |
342| `audio` | Ignored |
343| `logit_bias` | Ignored |
344| `store` | Ignored |
345| `user` | Ignored |
346| `modalities` | Ignored |
347| `top_logprobs` | Ignored |
348| `reasoning_effort` | Ignored |
321| Field | Support status |
322| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
323| `model` | Use Claude model names |
324| `max_tokens` | Fully supported |
325| `max_completion_tokens` | Fully supported |
326| `stream` | Fully supported |
327| `stream_options` | Fully supported |
328| `top_p` | Passed through to the model. Claude 4.7 and later models and Claude Mythos Preview return a 400 error for any value other than `0.99`, the default, so omit it. A request that sets both `temperature` and `top_p` also returns a 400 error. See [Using the Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). |
329| `parallel_tool_calls` | Fully supported |
330| `tool_choice` | Supported with limits. `"required"` and a named function force a tool call. Some models return a 400 error for forced tool use: Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and Claude Mythos 5.1. Use `"auto"` on those models. See [Forcing tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools#forcing-tool-use). |
331| `stop` | All non-whitespace stop sequences work |
332| `temperature` | Between 0 and 1 (inclusive). Values greater than 1 are capped at 1. On Claude 4.7 and later models and Claude Mythos Preview, any value below 1 returns a 400 error, so omit it. See [Using the Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). |
333| `n` | Must be exactly 1. Any other value returns a 400 error. |
334| `response_format` | Supported with limits. Only `json_schema` with `strict: true` is accepted, and the structured outputs [JSON Schema limitations](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#json-schema-limitations) apply. Any other value, including `json_object` and `text`, returns a 400 error. |
335| `logprobs` | Ignored |
336| `metadata` | Ignored |
337| `prediction` | Ignored |
338| `presence_penalty` | Ignored |
339| `frequency_penalty` | Ignored |
340| `seed` | Ignored |
341| `service_tier` | Ignored |
342| `audio` | Ignored |
343| `logit_bias` | Ignored |
344| `store` | Ignored |
345| `user` | Ignored |
346| `modalities` | Ignored |
347| `top_logprobs` | Ignored |
348| `reasoning_effort` | Ignored |
349349
350350#### `tools` / `functions` fields
351351
cli-sdks-libraries/middleware Changed · +4 / -4 lines
from line 25
2525 - claude-sonnet-4-5-20250929
2626 supportedPlatforms:
2727 Claude API: stable
28 Amazon Bedrock: stable
29 Amazon Bedrock (bedrock-runtime): stable
2830 Claude Platform on AWS: stable
2931 Claude Models on Google Cloud (Anthropic managed): stable
30 Amazon Bedrock: stable
31 Amazon Bedrock (InvokeModel): stable
3232 Claude Models on Google Cloud (Google managed): stable
3333 Microsoft Foundry: stable
3434---
3535
36The Claude SDK provides a middleware (or interceptor) hook that lets you run code before a request is sent and after the response is received. Use middleware for cross-cutting concerns such as logging, custom retries, request annotation, and refusal fallback handling.
36The Anthropic SDK provides a middleware (or interceptor) hook that runs your code before the SDK sends a request and after it receives the response. Use middleware for cross-cutting concerns such as logging, custom retries, request annotation, and retrying a declined request on a [fallback model](https://platform.claude.com/docs/en/cli-sdks-libraries/middleware#built-in-middleware).
3737
3838```mermaid
3939sequenceDiagram
from line 202
202202
203203When you register multiple middleware, they apply in the order given: the first middleware’s “before” code runs first, and its “after” code runs last. Middleware registered on the client runs before middleware passed as a per-request option.
204204
205In the Go SDK, repeated `option.WithMiddleware` calls concatenate (client first, then method). In the other SDKs, pass an array; later entries wrap inner.
205To register more than one middleware, pass them all, as in `middleware=[first, second]` (typescript, ruby: `middleware: [first, second]`; csharp: `Handlers = [first, second]`; go: `option.WithMiddleware(first, second)`; java: `.addInterceptor(first).addInterceptor(second)`; php: `'middleware' => [$first, $second]`).
206206
207207## Replacing the HTTP client
208208
cli-sdks-libraries/sdks/csharp Changed · +10 / -6 lines
from line 408
408408
409409### OpenTelemetry tracing
410410
411When your application adds the SDK’s sources to its OpenTelemetry tracer provider with `AddSource("com.anthropic.sdk.csharp*")`, the SDK emits a span for each request that it sends. To send the spans to your observability platform, see [Set up OpenTelemetry with the Claude SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
411When your application adds the SDK’s sources to its OpenTelemetry tracer provider with `AddSource("com.anthropic.sdk.csharp*")`, the SDK emits a span for each request that it sends. To send the spans to your observability platform, see [Set up OpenTelemetry with the Anthropic SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
412412
413413### Undocumented API functionality
414414
from line 419
419419<Note>
420420 For detailed platform setup guides with code examples, see:
421421
422 * [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock)
423 * [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)
422 * [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock)
423 * [Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)
424424 * [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws)
425425 * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed)
426426 * [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry)
from line 431
431431The C# SDK supports the following platforms through separate NuGet packages:
432432
433433* **Claude Models on Google Cloud (Google managed):** `Anthropic.Vertex`. See [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed) for client setup.
434* **Bedrock:** `Anthropic.Bedrock`. Use `AnthropicBedrockMantleClient` for the Messages-API Bedrock endpoint, or `AnthropicBedrockClient` (`bedrock-runtime` path). `AnthropicBedrockMantleClient` takes an optional `MantleAwsClientOptions` config object; `AnthropicBedrockClient` accepts `AnthropicBedrockCredentialsHelper.FromEnv()` or explicit credentials.
434
435* **Bedrock:** `Anthropic.Bedrock`. Which client you use depends on the endpoint:
436
437 * **`bedrock-mantle`:** `AnthropicBedrockMantleClient`. It takes an optional `MantleAwsClientOptions` config object.
438 * **`bedrock-runtime`:** `AnthropicBedrockClient`, for the `InvokeModel` API. It accepts `AnthropicBedrockCredentialsHelper.FromEnv()` or explicit credentials.
439
435440* **Claude Platform on AWS:** `Anthropic.Aws`. Use `AnthropicAwsClient`; set `WorkspaceId` on the client or the `ANTHROPIC_AWS_WORKSPACE_ID` environment variable (see [Workspaces](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#workspaces)). Available in beta.
436* **Foundry:** `Anthropic.Foundry`. Use `AnthropicFoundryClient` with `DefaultAnthropicFoundryCredentials.FromEnv()` or explicit credentials.
437441
438Use `AnthropicBedrockMantleClient` for new projects; `AnthropicBedrockClient` remains for existing applications using the Bedrock `InvokeModel` API.
442* **Foundry:** `Anthropic.Foundry`. Use `AnthropicFoundryClient` with `DefaultAnthropicFoundryCredentials.FromEnv()` or explicit credentials.
439443
440444The C# SDK also supports Claude Models on Google Cloud (Anthropic managed) through `AnthropicGoogleCloudClient`, from the `Anthropic.GoogleCloud` package. This client is in beta. Set `WorkspaceId` on an optional `GoogleCloudClientOptions` value, or set the `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID` environment variable. See [Project, location, and workspace resolution](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution).
441445
cli-sdks-libraries/sdks/go Changed · +10 / -6 lines
from line 625
625625<Note>
626626 For detailed platform setup guides with code examples, see:
627627
628 * [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock)
629 * [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)
628 * [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock)
629 * [Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)
630630 * [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws)
631631 * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed)
632632 * [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry)
from line 637
637637The Go SDK supports the following platforms:
638638
639639* **Claude Models on Google Cloud (Google managed):** `import "github.com/anthropics/anthropic-sdk-go/v2/vertex"`. Use `vertex.WithGoogleAuth(ctx, region, projectID)` or `vertex.WithCredentials(ctx, region, projectID, creds)`.
640* **Bedrock:** `import "github.com/anthropics/anthropic-sdk-go/v2/bedrock"`. Use `bedrock.NewMantleClient` for the Messages-API Bedrock endpoint (streams over SSE), or `bedrock.WithLoadDefaultConfig(ctx)` / `bedrock.WithConfig(cfg)` (`bedrock-runtime` path). Importing the `bedrock` package globally registers a decoder for `application/vnd.amazon.eventstream` with the SDK’s streaming layer (through package `init()`). This applies whether you use the `bedrock-runtime` `WithConfig`/`WithLoadDefaultConfig` path or `NewMantleClient`.
640
641* **Bedrock:** `import "github.com/anthropics/anthropic-sdk-go/v2/bedrock"`. What you use depends on the endpoint:
642
643 * **`bedrock-mantle`:** `bedrock.NewMantleClient`. It streams over SSE.
644 * **`bedrock-runtime`:** `bedrock.WithLoadDefaultConfig(ctx)` or `bedrock.WithConfig(cfg)`, for the `InvokeModel` API.
645
641646* **Claude Platform on AWS:** `import anthropicaws "github.com/anthropics/anthropic-sdk-go/v2/aws"`. Use `anthropicaws.NewClient(ctx, cfg)` with an `anthropicaws.ClientConfig` value to construct a client; set `WorkspaceID` on the config or the `ANTHROPIC_AWS_WORKSPACE_ID` environment variable. The `anthropicaws` import alias avoids a name collision with `github.com/aws/aws-sdk-go-v2/aws` when both are imported. Available in beta.
647
642648* **Foundry:** `import "github.com/anthropics/anthropic-sdk-go/v2/foundry"`. Use `foundry.NewClient(cfg)` with a `foundry.ClientConfig` value to construct a client; set `APIKey` (or `AzureADTokenProvider` for Microsoft Entra ID) and `Resource` on the config, or the `ANTHROPIC_FOUNDRY_API_KEY` and `ANTHROPIC_FOUNDRY_RESOURCE` environment variables.
643649
644Use `bedrock.NewMantleClient` for new projects; `bedrock.WithLoadDefaultConfig`/`WithConfig` remain for existing applications using the Bedrock `InvokeModel` API.
645
646650The Go SDK also supports Claude Models on Google Cloud (Anthropic managed) through the `github.com/anthropics/anthropic-sdk-go/v2/googlecloud` package. To construct a client, call `googlecloud.NewClient(ctx, cfg)` with a `googlecloud.ClientConfig` value. This client is in beta. Set `WorkspaceID` on the config or set the `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID` environment variable. See [Project, location, and workspace resolution](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution) for how the client resolves the workspace ID.
647651
648652## Advanced usage
from line 680
676680
677681### OpenTelemetry tracing
678682
679When your application registers an OpenTelemetry tracer provider, the SDK emits a span for each request that it sends. To send the spans to your observability platform, see [Set up OpenTelemetry with the Claude SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
683When your application registers an OpenTelemetry tracer provider, the SDK emits a span for each request that it sends. To send the spans to your observability platform, see [Set up OpenTelemetry with the Anthropic SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
680684
681685### Making custom/undocumented requests
682686
cli-sdks-libraries/sdks/java Changed · +4 / -6 lines
from line 1115
11151115<Note>
11161116 For detailed platform setup guides with code examples, see:
11171117
1118 * [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock)
1119 * [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)
1118 * [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock)
1119 * [Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)
11201120 * [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws)
11211121 * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed)
11221122 * [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry)
from line 1127
11271127The Java SDK supports the following platforms through separate dependencies that provide platform-specific `Backend` implementations:
11281128
11291129* **Claude Models on Google Cloud (Google managed):** `com.anthropic:anthropic-java-vertex`: Use `VertexBackend.builder()` or `VertexBackend.fromEnv()`. `fromEnv()` reads `CLOUD_ML_REGION` and `ANTHROPIC_VERTEX_PROJECT_ID` and uses Application Default Credentials.
1130* **Bedrock:** `com.anthropic:anthropic-java-bedrock`: Use `BedrockMantleBackend.fromEnv()` or `BedrockMantleBackend.builder()` for the Messages-API Bedrock endpoint, or `BedrockBackend.fromEnv()` / `BedrockBackend.builder()` (`bedrock-runtime` path).
1130* **Bedrock:** `com.anthropic:anthropic-java-bedrock`: Use `BedrockMantleBackend.fromEnv()` or `BedrockMantleBackend.builder()` for the `bedrock-mantle` endpoint, or `BedrockBackend.fromEnv()` or `BedrockBackend.builder()` for the `InvokeModel` API on the `bedrock-runtime` endpoint.
11311131* **Claude Platform on AWS:** `com.anthropic:anthropic-java-aws`: Use `AwsBackend.fromEnv()` (reads `ANTHROPIC_AWS_WORKSPACE_ID` and the AWS default region/credential chain) or `AwsBackend.builder()`. Available in beta.
11321132* **Foundry:** `com.anthropic:anthropic-java-foundry`: Use `FoundryBackend.fromEnv()` or `FoundryBackend.builder()`.
11331133
1134Use `BedrockMantleBackend` for new projects; `BedrockBackend` remains for existing applications using the Bedrock `InvokeModel` API.
1135
11361134The Java SDK also supports Claude Models on Google Cloud (Anthropic managed) through `GoogleCloudBackend`, from the `com.anthropic:anthropic-java-google-cloud` dependency. This backend is in beta. Create it with `GoogleCloudBackend.builder()` or `GoogleCloudBackend.fromEnv()`. `fromEnv()` reads `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID`, `ANTHROPIC_GOOGLE_CLOUD_PROJECT`, and Google Application Default Credentials. See [Project, location, and workspace resolution](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution).
11371135
11381136Install each platform artifact alongside the base `anthropic-java` dependency, as shown in [Add-ons](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/java#add-ons). Each `Backend` implementation is passed to the client with `.backend()` on `AnthropicOkHttpClient.builder()`.
from line 1211
12131211
12141212### OpenTelemetry tracing
12151213
1216When your application registers an OpenTelemetry tracer provider, the SDK emits a span for each request that it sends. To send the spans to your observability platform, see [Set up OpenTelemetry with the Claude SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
1214When your application registers an OpenTelemetry tracer provider, the SDK emits a span for each request that it sends. To send the spans to your observability platform, see [Set up OpenTelemetry with the Anthropic SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
12171215
12181216### Undocumented API functionality
12191217
cli-sdks-libraries/sdks/php Changed · +5 / -7 lines
from line 169
169169
170170### OpenTelemetry tracing
171171
172When your application registers an OpenTelemetry tracer provider, the SDK emits a span for each request that it sends. To send the spans to your observability platform, see [Set up OpenTelemetry with the Claude SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
172When your application registers an OpenTelemetry tracer provider, the SDK emits a span for each request that it sends. To send the spans to your observability platform, see [Set up OpenTelemetry with the Anthropic SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
173173
174174### Undocumented properties
175175
from line 255
255255<Note>
256256 For detailed platform setup guides with code examples, see:
257257
258 * [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock)
259 * [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)
258 * [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock)
259 * [Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)
260260 * [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws)
261261 * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed)
262262 * [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry)
from line 267
267267The PHP SDK supports the following platforms:
268268
269269* **Claude Models on Google Cloud (Google managed):** `Anthropic\Vertex\Client`. Use `::fromEnvironment()`.
270* **Bedrock:** `Anthropic\Bedrock\MantleClient`. Use `new MantleClient(awsRegion: ...)`.
271* **Bedrock (legacy):** `Anthropic\Bedrock\Client`. Use `::fromEnvironment()` or `::withCredentials()`.
270* **Amazon Bedrock (`bedrock-mantle`):** `Anthropic\Bedrock\MantleClient`. Use `new MantleClient(awsRegion: ...)`.
271* **Amazon Bedrock (`bedrock-runtime`):** `Anthropic\Bedrock\Client`, for the `InvokeModel` API. Use `::fromEnvironment()` or `::withCredentials()`.
272272* **Claude Platform on AWS:** `Anthropic\Aws\Client` (requires `aws/aws-sdk-php` as a soft dependency). Use `new Anthropic\Aws\Client(workspaceId: ...)` or set `ANTHROPIC_AWS_WORKSPACE_ID`. Available in beta.
273273* **Foundry:** `Anthropic\Foundry\Client`. Use `::withCredentials()`.
274
275Use `MantleClient` for new projects; `Anthropic\Bedrock\Client` remains for existing applications using the Bedrock `InvokeModel` API.
276274
277275The PHP SDK also supports Claude Models on Google Cloud (Anthropic managed) through `Anthropic\GoogleCloud\Client`. This client is in beta. `Anthropic\GoogleCloud\Client` requires `google/auth` as a soft dependency. Use `new Anthropic\GoogleCloud\Client(workspaceId: ...)` or set the `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID` environment variable. See [Project, location, and workspace resolution](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution).
278276
cli-sdks-libraries/sdks/python Changed · +4 / -4 lines
from line 645
645645
646646### OpenTelemetry tracing
647647
648When your application registers an OpenTelemetry tracer provider, the SDK emits a span for each request that it sends. To send the spans to your observability platform, see [Set up OpenTelemetry with the Claude SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
648When your application registers an OpenTelemetry tracer provider, the SDK emits a span for each request that it sends. To send the spans to your observability platform, see [Set up OpenTelemetry with the Anthropic SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
649649
650650### Making custom/undocumented requests
651651
from line 744
744744<Note>
745745 For detailed platform setup guides with code examples, see:
746746
747 * [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock)
748 * [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)
747 * [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock)
748 * [Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)
749749 * [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws)
750750 * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed)
751751 * [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry)
from line 766
766766
767767The `AnthropicAWS` client is in beta. Pass `workspace_id` to the constructor or set the `ANTHROPIC_AWS_WORKSPACE_ID` environment variable. The `AnthropicGoogleCloud` client is also in beta. Pass `workspace_id` to the constructor or set the `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID` environment variable. See [Project, location, and workspace resolution](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution) for how the client resolves the workspace ID.
768768
769Use `AnthropicBedrockMantle` for new projects; `AnthropicBedrock` remains for existing applications using the Bedrock `InvokeModel` API.
769Use `AnthropicBedrockMantle` with the `bedrock-mantle` endpoint, and `AnthropicBedrock` with the `InvokeModel` API on the `bedrock-runtime` endpoint.
770770
771771## Semantic versioning
772772
cli-sdks-libraries/sdks/ruby Changed · +4 / -4 lines
from line 343
343343
344344## OpenTelemetry tracing
345345
346When your application registers an OpenTelemetry tracer provider, the SDK emits a span for each request that it sends. To send the spans to your observability platform, see [Set up OpenTelemetry with the Claude SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
346When your application registers an OpenTelemetry tracer provider, the SDK emits a span for each request that it sends. To send the spans to your observability platform, see [Set up OpenTelemetry with the Anthropic SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
347347
348348## Making custom or undocumented requests
349349
from line 396
396396<Note>
397397 For detailed platform setup guides with code examples, see:
398398
399 * [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock)
400 * [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)
399 * [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock)
400 * [Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)
401401 * [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws)
402402 * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed)
403403 * [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry)
from line 412
412412* **Claude Platform on AWS:** Part of the main `anthropic` gem (requires the `aws-sdk-core` gem). Provides `Anthropic::AWSClient`. Pass `workspace_id:` to the constructor or set the `ANTHROPIC_AWS_WORKSPACE_ID` environment variable (see [Workspaces](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#workspaces)). Available in beta.
413413* **Foundry:** Part of the main `anthropic` gem. Provides `Anthropic::FoundryClient`. Pass `resource:` and `api_key:` (or `azure_ad_token_provider:` for Microsoft Entra ID) to the constructor, or set the `ANTHROPIC_FOUNDRY_RESOURCE` and `ANTHROPIC_FOUNDRY_API_KEY` environment variables.
414414
415Use `Anthropic::BedrockMantleClient` for new projects; `Anthropic::BedrockClient` remains for existing applications using the Bedrock `InvokeModel` API.
415Use `Anthropic::BedrockMantleClient` with the `bedrock-mantle` endpoint, and `Anthropic::BedrockClient` with the `InvokeModel` API on the `bedrock-runtime` endpoint.
416416
417417The Ruby SDK also supports Claude Models on Google Cloud (Anthropic managed) through `Anthropic::GoogleCloudClient`. This client is in beta. It ships in the main `anthropic` gem and needs the `googleauth` gem. Pass `workspace_id:` to the constructor or set the `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID` environment variable. See [Project, location, and workspace resolution](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution) for how the client resolves the workspace ID.
418418
cli-sdks-libraries/sdks/typescript Changed · +4 / -4 lines
from line 626
626626
627627### OpenTelemetry tracing
628628
629When your application registers an OpenTelemetry tracer provider, the SDK emits a span for each request that it sends. To send the spans to your observability platform, see [Set up OpenTelemetry with the Claude SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
629When your application registers an OpenTelemetry tracer provider, the SDK emits a span for each request that it sends. To send the spans to your observability platform, see [Set up OpenTelemetry with the Anthropic SDK](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk).
630630
631631### Making custom/undocumented requests
632632
from line 775
775775<Note>
776776 For detailed platform setup guides with code examples, see:
777777
778 * [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock)
779 * [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)
778 * [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock)
779 * [Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)
780780 * [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws)
781781 * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed)
782782 * [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry)
from line 791
791791* **Claude Platform on AWS:** `npm install @anthropic-ai/aws-sdk`: Provides `AnthropicAws` client. Pass `workspaceId` to the constructor or set the `ANTHROPIC_AWS_WORKSPACE_ID` environment variable. Available in beta.
792792* **Foundry:** `npm install @anthropic-ai/foundry-sdk`: Provides `AnthropicFoundry` client
793793
794Use `AnthropicBedrockMantle` for new projects; `AnthropicBedrock` remains for existing applications using the Bedrock `InvokeModel` API.
794Use `AnthropicBedrockMantle` with the `bedrock-mantle` endpoint, and `AnthropicBedrock` with the `InvokeModel` API on the `bedrock-runtime` endpoint.
795795
796796The TypeScript SDK also supports Claude Models on Google Cloud (Anthropic managed) through the `AnthropicGoogleCloud` client. This client is in beta. To install it, run `npm install @anthropic-ai/google-cloud-sdk`. Pass `workspaceId` to the constructor or set the `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID` environment variable. See [Project, location, and workspace resolution](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution) for how the client resolves the workspace ID.
797797
manage-claude/claude-tag-api Changed · +5 / -4 lines
from line 247
247247| `enabled` | boolean | Whether Claude is on. |
248248| `instructions` | string | Standing guidance Claude reads in every session. At most 8,192 characters after leading and trailing white space is trimmed. Blank text clears the setting. |
249249| `model` | string | The model new sessions start on: a [model ID](https://platform.claude.com/docs/en/models/overview) your organization can use with Claude Tag. At most 128 characters. |
250| `environment_id` | string | The cloud environment sessions run in, prefixed `env_`. It must be active and belong to your organization. |
250| `environment_id` | string | The environment sessions run in: an active environment of your organization, prefixed `env_`, or a self-hosted runner pool of your organization that every member may use, prefixed `ccpool_`. |
251251| `guest_policy` | object | What Claude does in a channel while a Slack guest is in it, for everyone in the channel: `{"type": "allow"}` (Claude answers), `{"type": "restrict"}` (Claude does not answer), or `{"type": "channel_only"}` (Claude answers with only the Bundles attached to the channel itself; if `channel_only` is not available to your organization, a request that sets it returns `400`). See [Restrict guest channels](https://claude.com/docs/claude-tag/admins/restrict-access#restrict-guest-channels) for what it means in channels shared through Slack Connect or across an Enterprise Grid. |
252252
253253`model` and `environment_id` are checked when you write them and not again: if the model or environment later changes, responses keep returning the stored value.
254254
255If an organization owner has put a settings level on a self-hosted runner pool in claude.ai, its `environment_id` returns the pool’s ID, which starts with `ccpool_`. This API cannot set a runner pool, and returns `400` for a request that changes or clears `environment_id` on a settings level that stores one.
255A runner pool that only some members may use (a restricted pool) is chosen by an organization owner in claude.ai, and a read of a settings level on one returns its `ccpool_` ID like any other. A request that would put a settings level on one, or that changes or clears `environment_id` on a settings level that stores one, returns `400` with `error_code: "runner_pool_restricted"`. A pool your organization does not have returns the same `404` as an unknown environment.
256256
257257### Stored and inherited values
258258
from line 1246
12461246* To keep Claude out of a channel, keep it set up with `enabled` set to `false` rather than remove it, or make sure that what it would inherit, which removal does not touch, keeps Claude off.
12471247* To have a channel store nothing and keep its sessions and memory, clear each setting and detach each Bundle instead.
12481248
1249Two kinds of channel cannot be removed here at all, whether Claude is on or off in them, and return `400` with no `error_code`: a [group direct message](https://platform.claude.com/docs/en/manage-claude/claude-tag-api#group-direct-messages), and a channel that holds configuration this API does not manage, such as a runner pool or a setting that only claude.ai has. These are checked before `enabled` is, so turning Claude off does not help; an organization owner removes the second kind in claude.ai.
1249Two kinds of channel cannot be removed here at all, whether Claude is on or off in them, and return `400` with no `error_code`: a [group direct message](https://platform.claude.com/docs/en/manage-claude/claude-tag-api#group-direct-messages), and a channel that holds configuration this API does not manage, such as a restricted runner pool or a setting that only claude.ai has. These are checked before `enabled` is, so turning Claude off does not help; an organization owner removes the second kind in claude.ai.
12501250
12511251<CodeGroup>
12521252 ```bash cURL
from line 2493
24932493| `api_key_scope_missing` | 403 | The key lacks `read:claude_tag` or `write:claude_tag`, whichever the endpoint requires. |
24942494| `claude_tag_writes_not_enabled` | 403 | Your organization can read through this API but is not enabled for changes. |
24952495| `compliance_configuration_restricted` | 403 | Your organization has a compliance configuration under which Claude Tag stores nothing new, such as zero data retention. Setting a channel up, updating settings (even to clear them), and attaching a Bundle are refused. Detaching a Bundle and removing a channel are not, and such an organization can [remove](https://platform.claude.com/docs/en/manage-claude/claude-tag-api#remove-a-channel) a channel even while Claude is on in it. |
2496| `environment_not_found` | 404 | `environment_id` names no environment your organization can use here. The `id` in the path is fine. |
2496| `environment_not_found` | 404 | `environment_id` names no environment or runner pool your organization can use here. The `id` in the path is fine. |
24972497| `environment_archived` | 400 | `environment_id` names an archived environment. |
2498| `runner_pool_restricted` | 400 | The request would put a settings level on a restricted runner pool, or changes or clears `environment_id` on a settings level that stores one. An organization owner makes that change in claude.ai. See [Settings](https://platform.claude.com/docs/en/manage-claude/claude-tag-api#settings). |
24982499| `slack_channel_set_up_settings_refused` | 400 | The request set the channel up, then `settings` was refused. `details.slack_channel_id` is the channel. See [Set up a channel](https://platform.claude.com/docs/en/manage-claude/claude-tag-api#set-up-a-channel). |
24992500| `slack_channel_set_up_environment_not_found` | 404 | The request set the channel up, then `environment_id` was not found. `details.slack_channel_id` is the channel. See [Set up a channel](https://platform.claude.com/docs/en/manage-claude/claude-tag-api#set-up-a-channel). |
25002501| `slack_channel_set_up_settings_conflict` | 409 | The request set the channel up, then another change overlapped `settings`. Nothing of `settings` was stored. `details.slack_channel_id` is the channel. See [Set up a channel](https://platform.claude.com/docs/en/manage-claude/claude-tag-api#set-up-a-channel). |