compaction-on-demand changedbuild-with-claude/compaction-on-demand
Recorded here
Lines+21added
Lines−18removed
From line
344
where the diff opens
First seen
21 Sep 2026
this site's first read of the page
Recorded edits23to this page, all time
The whole hunk
from line 344, old and new numbered
/
from line 344
344344The API puts the summary where the block stands and passes every later message to Claude unchanged. Follow these rules:
345345
346346* Put the block first in `messages`, either as an `assistant` message of its own or as the first content block of the first message, whether that is a `user` or `assistant` message.
347* Remove the summarized messages. If any remain in front of the block, the request returns a 400 error (`compaction_block_misplaced`).
348* Send exactly one `compaction` block in each request, on every later request.
347* Remove exactly the summarized messages. If any remain in front of the block, the request returns a 400 error (`compaction_block_misplaced`).
348* Send exactly one `compaction` block on every later request.
349349
350350<Warning>
351351 Two mistakes in the swap can pass without an error:
from line 352
352352
353353 * **The block is left out of a later request:** Claude gets no summary.
354354 * **Summarized messages stay after the block:** the API sends them to Claude again.
355
356 On models with [preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking), either mistake can also make thinking blocks in the request fail the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check).
357355</Warning>
358356
357On [models with preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#outcomes), each also [invalidates thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#mismatch-behavior):
358
359* **Block left out:** thinking since the swap, and earlier thinking unless you resend the full history.
360* **Summarized messages left in:** thinking already in them and after them.
361
359362Threshold compaction works the other way around: its block follows the messages it summarizes, and the API drops them for you. See [Passing compaction blocks back](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold#passing-compaction-blocks-back).
360363
361If you keep turns after the block and send their thinking blocks back, the conditions that keep that thinking valid are on [Compaction and preserved thinking](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks).
364For kept turns, see [Conditions for kept thinking to stay valid](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks#conditions-for-kept-thinking-to-stay-valid).
362365
363366### Compact again
364367
from line 779
776779
777780The SDK [tool runner](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner) can send the compaction request for you. When you decide to compact, call `compact_before_next_turn()` (ruby: `compact_before_next_turn`; typescript, java, php: `compactBeforeNextTurn()`; csharp, go: `CompactBeforeNextTurn()`) on the runner. Once the current turn and its tool calls complete, the runner sends the compaction request and replaces its history with the returned message. Create the runner with the `compact-2026-09-04` beta, because the runner doesn’t add it.
778781
779The runner builds the compaction request from its own parameters and leaves `context_management` out. It also leaves out `stop_sequences`, a `tool_choice` of type `any` or `tool`, and a structured-output `output_config.format`, which the API rejects on a compaction request. [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary) explains why. The runner sends them again on its later requests. SDK versions before Python 1.8.0, TypeScript 0.128.0, C# 12.50.0, Go 1.75.0, and Java 2.65.0 send them on the compaction request too. On those versions, a runner that sets any of these parameters gets a 400 error. The runner sends a [task budget](https://platform.claude.com/docs/en/build-with-claude/task-budgets) unchanged. If `output_config.task_budget` sets `remaining`, the compaction request returns a 400 error, so leave `remaining` unset, as [Limits and interactions with other features](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#how-it-fits-with-the-rest-of-the-api) says. The runner refuses to compact while its `context_management` has a compaction edit, so use one kind of compaction on a runner.
782The runner builds the compaction request from its own parameters and leaves `context_management` out. It also leaves out `stop_sequences`, a `tool_choice` of type `any` or `tool`, and a structured-output `output_config.format`, which the API rejects on a compaction request. [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary) explains why. The runner sends them again on its later requests. SDK versions before Python 1.8.0, TypeScript 0.128.0, C# 12.50.0, Go 1.75.0, and Java 2.65.0 send them on the compaction request too. On those versions, a runner that sets any of these parameters gets a 400 error. The runner sends a [task budget](https://platform.claude.com/docs/en/build-with-claude/task-budgets) unchanged. If `output_config.task_budget` sets `remaining`, the compaction request returns a 400 error, so leave `remaining` unset (see [Limits and interactions with other features](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#how-it-fits-with-the-rest-of-the-api)). The runner can’t compact while its `context_management` has a compaction edit, so use one kind of compaction on a runner.
780783
781784### When to compact
782785
from line 822
819822
820823A compaction request, or a request that carries a block, can also fail outright. Most 400 errors have a message that says what to remove or resend. Some also carry an `error.details.error_code` that starts with `compaction_`. Parameter errors, such as a field that can’t be combined with `compaction`, carry the message only.
821824
822| Error | Cause | What to do |
823| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
824| 529 `overloaded_error`, `error.details.error_code` `compaction_unavailable` | A transient server problem while producing a block, or while reading one you sent back. | Retry the request. |
825| 400 `compaction_block_misplaced` | Summarized messages remain in front of the block. | Remove them, so the block comes first in `messages`. |
826| 400 `compaction_signature_invalid` or `compaction_content_mismatch` | The block’s `signature` or `content` was changed after the API returned it. | Send the block exactly as returned, including its `signature`. |
827| 400 | The request carries more than one `compaction` block. | Send exactly one, the newest. |
828| 400 | The last `assistant` turn ends in a tool call with no result yet. | Send that turn’s tool results, then compact. |
829| 400 `compaction_nothing_to_summarize` | `messages` has no `user` or `assistant` content, for example an empty list. | Send at least one `user` or `assistant` message. |
830| 400 with a message that a thinking block is `bound to a different conversation` | On a model with preserved thinking, a thinking block in the compaction request failed the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check). | [Handle the error](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#handle-the-error-in-code), then compact. |
831| 400 on the compaction request, with a message that says the `compaction` parameter `requires anthropic-beta: compact-2026-09-04` | The compaction request left out the beta header. | Add the beta header; see [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary). |
832| 400 on a later request that carries the block: a validation error that says `compaction` is not one of the expected content block types. The message doesn’t mention the header. | That request left out the beta header. | Add the beta header to every request that carries the block; see [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary). |
833| 400 validation error, such as `messages.0.content.0.compaction.citations: Extra inputs are not permitted` | A block was sent back with fields the API didn’t return, such as `citations: null`. | Send the block exactly as returned; see [Continue from the summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#continue-from-the-summary). |
825| Error | Cause | What to do |
826| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
827| 529 `overloaded_error`, `error.details.error_code` `compaction_unavailable` | A transient server problem while producing a block, or while reading one you sent back. | Retry the request. |
828| 400 `compaction_block_misplaced` | Summarized messages remain in front of the block. | Remove them, so the block comes first in `messages`. |
829| 400 `compaction_signature_invalid` or `compaction_content_mismatch` | The block’s `signature` or `content` was changed after the API returned it. | Send the block exactly as returned, including its `signature`. |
830| 400 | The request carries more than one `compaction` block. | Send exactly one, the newest. |
831| 400 | The last `assistant` turn ends in a tool call with no result yet. | Send that turn’s tool results, then compact. |
832| 400 `compaction_nothing_to_summarize` | `messages` has no `user` or `assistant` content, for example an empty list. | Send at least one `user` or `assistant` message. |
833| 400 with a message that a thinking block is `bound to a different conversation` | On a [model with preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#outcomes), a thinking block in the compaction request failed the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check). | [Handle the error in code](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/fix-bound-to-a-different-conversation#handle-the-error-in-code), then compact. |
834| 400 on the compaction request, with a message that says the `compaction` parameter `requires anthropic-beta: compact-2026-09-04` | The compaction request left out the beta header. | Add the beta header; see [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary). |
835| 400 on a later request that carries the block: a validation error that says `compaction` is not one of the expected content block types. The message doesn’t mention the header. | That request left out the beta header. | Add the beta header to every request that carries the block; see [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary). |
836| 400 validation error, such as `messages.0.content.0.compaction.citations: Extra inputs are not permitted` | A block was sent back with fields the API didn’t return, such as `citations: null`. | Send the block exactly as returned; see [Continue from the summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#continue-from-the-summary). |
834837
835838## Count compaction usage
836839
No line in this hunk matches that.