thinking-steering-and-cost changedbuild-with-claude/thinking-steering-and-cost
Recorded here
Lines+14added
Lines−14removed
From line
24
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits21to this page, all time
The whole hunk
from line 24, old and new numbered
/
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:
No line in this hunk matches that.