What you will be able to do
- Choose between on-demand compaction, threshold compaction and your own summarizer for a given application
- Predict what survives compaction in Claude Code and the Agent SDK, and steer what the summary keeps
- Use subagents to keep intermediate work out of the main agent's context, and scope them with AgentDefinition fields
1.Compaction: summarizing older turns on the server
Pruning works well for content you can throw away, such as stale tool results or old thinking. A long conversation also builds up content that still matters but no longer needs to be kept word for word. Compaction handles that. It replaces older turns with a summary that Claude writes on the server, so you write no summarization code. The context windows guide calls server-side compaction the primary strategy for long-running conversations and agentic workflows. It keeps the task within the limit and keeps the active context small, because quality drops as the conversation grows. Compaction is in beta for Claude 4.6 and later models and Claude Mythos Preview.
| Aspect | Compaction on demand | Compaction at a token threshold | Your own summarizer |
|---|---|---|---|
| Who decides when | You, by sending a request | The API, when input tokens reach your trigger | You |
| What you send back | The returned block first in messages, replacing what it summarizes | The response, appended as usual; the API drops what came before the block | Your summary, as your own message |
| Runs in the background | Yes | No, it runs inside the request that reaches the threshold | Yes, in your code |
| Setup | compact-2026-09-04 beta and the top-level compaction parameter, plus a compaction loop | One parameter on ordinary requests | The summarization call, its prompt, and the history rewrite |
The docs give a clear default: use on-demand compaction wherever it is available. Threshold compaction fits when you want the API to manage context inside ordinary requests. On-demand compaction has optional variants. You can keep the last few turns word for word and summarize only the older ones, run the summary in the background while work continues, supply your own summarization prompt when the default summary drops something a later turn needs, and compact again when an already-compacted conversation grows long. The TypeScript and Ruby SDKs also offer client-side compaction through tool_runner, but server-side compaction is generally preferred.
Checkpoint 1 of 5· Check yourself
A voice agent can't freeze the conversation while a summary is generated, and the last few turns must reach Claude word for word. Which compaction option fits?
Threshold compaction runs inside the request that reaches the threshold, so the conversation pauses. On-demand compaction supports both background runs and keeping recent turns.
“Your application needs to control when compaction happens, can't pause while a summary is written, or must keep recent turns and their thinking”Source: platform.claude.com
2.What survives compaction in Claude Code and the Agent SDK
In Claude Code, /compact replaces the conversation with a structured summary. Most startup content reloads automatically. That difference matters: anything stored on disk comes back word for word, while anything that existed only in the conversation is reduced to whatever the summary kept.
| Mechanism | After compaction |
|---|---|
| System prompt and output style | Both still apply |
| Project-root CLAUDE.md, unscoped rules, auto memory | Re-injected from disk |
| Files Claude read or edited | Up to five re-read, most recently modified first |
| Invoked skill bodies | Re-injected, capped at 5,000 tokens per skill and 25,000 total |
| Context that hooks added earlier | Summarized with the rest of the conversation |
| SessionStart hooks matching the compact source | Run again; output added to the compacted context |
Checkpoint 2 of 5· Check yourself
During a session Claude has read or edited a dozen files. What happens to those files when compaction runs?
Claude Code re-reads a limited number of recent files after compaction. The rest are only in the summary.
“Claude Code re-reads up to five, most recently modified first”Source: code.claude.com
You can steer the summary in several ways. /compact focus on the auth bug fix makes the summary keep what you choose instead of what the automatic pass guesses is important. /autocompact 500k sets how full the window gets before automatic compaction runs. /clear is a different tool: use it when switching to unrelated work, so old conversation doesn't crowd out the files you need next. The Agent SDK works the same way. The compactor reads CLAUDE.md like any other context, so a section there can say what every summary must preserve. A PreCompact hook can run custom logic first, such as archiving the full transcript, and sending /compact as a prompt string triggers compaction on demand.
# Summary instructions
When summarizing this conversation, always preserve:
- The current task objective and acceptance criteria
- File paths that have been read or modified
- Test results and error messages
- Decisions made and the reasoning behind themCheckpoint 3 of 5· Exam question
An engineer is building a research agent that needs to read dozens of files across a large repository to answer one question, without letting all that file content pile up in the main conversation's context. Which design best achieves this?
Correct answer: A — Delegate the file exploration to a subagent, whose fresh context absorbs all the intermediate reads while only its final summary message returns to the parent
- A. Correct. A subagent runs in its own fresh conversation; intermediate tool calls and results stay inside the subagent, and only its final message returns to the parent, so the main context grows by a summary rather than every file read.
- B. Incorrect. Reading everything in the main loop still pays the full context cost of every file during exploration; manual compaction afterward summarizes history but doesn't prevent that cost from accumulating first, and it also risks losing detail the task still needs.
- C. Incorrect. The effort setting controls how much reasoning Claude applies per turn; it reduces token usage from reasoning, not the token cost of the file contents themselves being read into context.
- D. Incorrect. Combining file contents into one MCP resource still delivers that same total content into the main agent's context when fetched; it does not isolate it the way a subagent's separate conversation does.
3.Context isolation with subagents
Compaction shrinks history after it has built up. Isolation stops it building up at all. Each subagent runs in its own conversation, which starts fresh unless it is a fork. Its intermediate tool calls and results stay inside the subagent, and only its final message goes back to the parent as a tool result. The main agent's context grows by that summary, not by the whole transcript. That is why Claude Code's advice is to send large reads to a subagent: the file contents stay in its window instead of yours. Isolation brings other benefits too. Independent subagents can run in parallel. Each can have a specialised system prompt that would only be noise in the main agent's instructions. Each can be limited to the tools it needs, and that limit saves context, because every tool definition takes up space.
| Field | Effect on context |
|---|---|
| prompt (required) | The subagent's own system prompt |
| tools / disallowedTools | Limits the tool set; if tools is omitted, it inherits every tool available to subagents |
| skills | Preloads the listed skills at startup; unlisted skills remain invocable through the Skill tool |
| omitClaudeMd | Runs without user, project and local CLAUDE.md as a subagent (TypeScript SDK only) |
| maxTurns | Caps agentic turns; output is returned marked as partial and can be resumed |
| model | Model override such as 'sonnet', 'haiku', or 'inherit' |
Checkpoint 4 of 5· Check yourself
A parent agent hands a codebase investigation to a code-reviewer subagent, which makes dozens of Read and Grep calls. What is added to the parent's context?
Intermediate tool calls and results stay in the subagent's own conversation. The parent receives only the final message, as a tool result.
“intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”Source: code.claude.com
Checkpoint 5 of 5· Exam question
A code review workflow runs a style-checker subagent, a security-scanner subagent, and a test-coverage subagent for the same pull request. The team wants the review to finish as fast as possible while still keeping each subagent's exploration out of the main conversation. What should they do?
Correct answer: A — Invoke the three subagents so they run concurrently, since independent subtasks then finish in the time of the slowest one rather than the sum of all three
- A. Correct. Multiple subagents can run concurrently, so independent subtasks like style, security, and coverage checks finish in the time of the slowest one rather than sequentially, while each subagent's exploration still stays isolated from the main conversation.
- B. Incorrect. Subagents are not limited to one at a time; running them concurrently is a documented benefit for independent subtasks.
- C. Incorrect. Merging responsibilities into a single subagent removes the parallelization benefit and mixes specialized instructions that were meant to stay separate and focused.
- D. Incorrect. The main agent's own tool calls that modify state run sequentially, and running checks directly in the main loop would also pull all that exploration content into the main conversation's context, which is what subagents are meant to avoid.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.An instruction given once in an early user prompt stays in force after compaction, because compaction only removes tool output.Why is that wrong?
Compaction replaces the conversation with a summary. Content on disk, such as CLAUDE.md, is re-injected word for word, but a conversation-only instruction survives only if the summary happened to keep it.
Covered in What survives compaction in Claude Code and the Agent SDK
2.A subagent's file reads and tool results are merged into the parent's history once it finishes, so delegating doesn't save parent context.Why is that wrong?
The subagent's turns stay in its own conversation. The parent's context grows only by the subagent's final response.
Covered in Context isolation with subagents
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Compaction replaces the older turns of a conversation with a summary that Claude writes on the server”
↩︎ Compaction: summarizing older turns on the server“Use on-demand compaction wherever it is available.”
↩︎ Compaction: summarizing older turns on the server“Your application needs to control when compaction happens, can't pause while a summary is written, or must keep recent turns and their thinking”
↩︎ Checkpoint - 2.
“For long-running conversations and agentic workflows, server-side compaction is the primary strategy for context management.”
↩︎ Compaction: summarizing older turns on the server“It is available in beta for Claude 4.6 and later models and Claude Mythos Preview.”
↩︎ Compaction: summarizing older turns on the server - 3.
“server-side compaction is generally preferred”
↩︎ Compaction: summarizing older turns on the server - 4.https://code.claude.com/docs/en/context-windowOfficial docs
“Compact with a focus: run /compact with instructions, like /compact focus on the auth bug fix, before starting a long new task.”
↩︎ What survives compaction in Claude Code and the Agent SDK“run /autocompact with a token count, like /autocompact 500k, to set how full the context window gets before the automatic pass runs”
↩︎ What survives compaction in Claude Code and the Agent SDK“Clear between tasks: run /clear when switching to unrelated work.”
↩︎ What survives compaction in Claude Code and the Agent SDK“send research to a subagent so the file contents stay in its context window, not yours.”
↩︎ Context isolation with subagents“you run /compact, which replaces the conversation with a structured summary. Most startup content reloads automatically”
↩︎ Exam trap 1“Claude Code re-reads up to five, most recently modified first”
↩︎ Checkpoint - 5.https://code.claude.com/docs/en/agent-sdk/agent-loopOfficial docs
“The compactor reads your CLAUDE.md like any other context, so you can include a section telling it what to preserve when summarizing.”
↩︎ What survives compaction in Claude Code and the Agent SDK“PreCompact hook: Run custom logic before compaction occurs, for example to archive the full transcript.”
↩︎ What survives compaction in Claude Code and the Agent SDK“Send /compact as a prompt string to trigger compaction on demand.”
↩︎ What survives compaction in Claude Code and the Agent SDK“It does not see the parent’s turns, and only its final response returns to the parent as a tool result.”
↩︎ Context isolation with subagents“Every tool definition takes context space.”
↩︎ Context isolation with subagents“The main agent’s context grows by that summary, not by the full subtask transcript.”
↩︎ Exam trap 2 - 6.https://code.claude.com/docs/en/agent-sdk/subagentsOfficial docs
“Parallelization: multiple subagents can run concurrently”
↩︎ Context isolation with subagents“intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”
↩︎ Checkpoint