Anthropic has added a beta feature to the Claude developer documentation: per-message effort. Developers can insert a special system message in the middle of a multi-turn conversation to move the reasoning level for later replies from high to low, or the other way around. The top-level effort setting on the request stays untouched, and the already-cached conversation prefix still gets a cache hit.
The syntax in the docs is short. Add a message to the messages array with role set to system and content set to an empty array, put the new value of output_config.effort inside it, and send the request with the header mid-conversation-output-config-2026-07-01. In the example, the top-level effort is set to high, and the model first uses the high level to plan a three-step migration from SQLite to PostgreSQL. A low-effort system message is then inserted, the user asks only for the plan to be squeezed into one sentence, and that turn is answered at the low level.
Which turn the new level applies to
When the change takes effect depends on where the message sits, and the rules are spelled out in some detail:
- If it comes right after a user message that carries new input, Claude answers that turn at the new level.
- If it is placed elsewhere, for example between an assistant reply and the next user message, the new level starts with the next user message that carries new input.
- A user message that holds only a tool_result does not count as new input, so several rounds of tool calls will not trigger a switch.
The new level stays in force until a later message changes it again. The documentation specifically warns that the message should go at the end of what has already been sent and be kept unchanged in every later request. It must not be inserted ahead of turns that were already sent, and it must not be moved or removed afterward. On models that support preserved thinking, any of these changes invalidates the thinking blocks in assistant turns after that message.
The error cases are also listed clearly. Writing output_config in a system message without the beta header returns a 400 with the message "Extra inputs are not permitted". Sending the header to a model that does not support the feature, such as Claude Fable 5, also returns a 400. Mid-conversation changes are likewise unavailable on Sonnet 5.5 with between_tools thinking enabled and on Haiku 5.5 with thinking turned off; the documentation suggests using adaptive thinking in those two cases.
What the old approach cost, and what goes away
Effort used to be a request-level parameter set at the top of the request. A developer who wanted the same conversation to think carefully early and answer quickly later could only change the top-level value between two requests. The documentation is blunt about the result: once the top-level value changes, prompt caching starts over from the beginning, and the long context built up so far is billed again as a cache miss.
"A per-message change leaves everything before it unchanged, so the cached prefix still matches."
The documentation also points out an easily overlooked detail. On Claude Fable 5.1, changing the top-level value is not a reliable way to steer the model in the first place, because the earlier replies were written at the old level and the model tends to stay consistent with its own previous style. Per-message switching writes "change gears from here" into the conversation itself, so the model can see the point where the change happens.
This is most useful for long-running agent loops. A coding agent can spend a high level reading the codebase and settling on a change plan, then run dozens of execution and confirmation turns at a low level while the context prefix stays the same and the cache hit rate is unaffected. Developers used to have to choose between flexible effort levels and cheap caching; now they can have both.
Customer support and Q&A apps can use it too. At the start of a conversation a user describes a complex fault and the model diagnoses it at a high level. Once the problem is pinned down and the user only asks a follow-up such as "where exactly do I click for step two", dropping to a low level makes the response noticeably faster. In the other direction, if a user in the middle of casual chat suddenly drops in a contract to be reviewed clause by clause, the app can raise the level temporarily. Switches like these used to mean either giving up the cache or not switching at all.
Supported models and platforms
On the model side, Fable 5.2, Mythos 5.2, Fable 5.1, Mythos 5.1, Opus 5.5, Opus 5, Sonnet 5.5 and Haiku 5.5 are all on the beta list, and the cloud platforms covered differ somewhat from model to model. On the platform side, the Claude API, Amazon Bedrock, Claude Platform on AWS, both managed options on Google Cloud, and Microsoft Foundry are all marked as beta. Developers using the Bedrock InvokeModel interface need to put the beta value in the anthropic_beta array in the request body rather than in a request header.
Managed Agents do not support the feature for now; the workaround in the documentation is to override the agent's model setting at the session level. The feature is still in beta, and the date in the beta header name is an API version identifier. The documentation does not say whether the naming will change once the feature reaches general availability.
Sources: Claude developer documentation, Per-message effort page (used to verify the beta header name, the model and platform lists, the placement rules and the error messages), CocoLoop, Claude developer documentation, effort parameter reference.