What you will be able to do
- Explain why a long session or agent loop loses accuracy as its context window fills, even well below the limit
- Work out where a session's tokens are going and pick the technique that targets that source
- Configure tool result clearing with context editing and predict its effect on the prompt cache
- Choose between subagent isolation, compaction and a fresh session for a given symptom
Key concept
Context rot — As more tokens enter the context window, the model gets worse at recalling and using what is in it. Context is therefore a budget to curate, not just a capacity to fill, and stale or irrelevant content costs accuracy as well as money.
1.Why long sessions degrade before they run out of room
A long-running session fails in two ways, and the window limit is the less common one. The more common failure is that output quality drops while there is still plenty of room. That happens because of context rot: as the token count grows, accuracy and recall degrade. The decline is gradual. Models stay highly capable at long lengths, but they become less precise at retrieval and long-range reasoning than they are on short contexts. So a 1M-token window tells you how much you can send. It does not tell you how much you should send.
Everything in the request counts against the window. That includes the system prompt, your tool definitions, every message in messages (including tool results, images and documents), and the output Claude generates, extended thinking included. In an agent loop the biggest of these is usually tool output. Every file read, grep result and log dump stays in the history and is re-sent on every later turn.
This produces two symptoms. Bloat means the window fills with material that has already done its job, such as file contents Claude read forty turns ago. Drift means old material is still shaping behaviour: the model keeps citing details from finished work because they are still in front of it. The cause is the same in both cases. Irrelevant content degrades model focus, so the fix is to remove or isolate that content, not to work around it with more instructions.
Checkpoint 1 of 9· Check yourself
An agent on a 1M-token model has used about 150k tokens. Its answers on the current task keep bringing in details from a task it finished earlier in the same session. Which response deals with the cause?
This is drift. Old material is still in front of the model and shaping what it does, and quality can drop well before the window is full. More room or more instructions leave that content in place, so the fix is to remove or isolate it.
“context is a finite resource with diminishing returns, and irrelevant content degrades model focus”Source: platform.claude.com
2.Match the technique to where the tokens are going
Before you pick a fix, find out which part of the context is growing. Tool definitions loaded at startup, long chains of tool round trips, and an ever-longer history of old results are three different problems, and each one has its own tool. Every response's usage field reports what the request consumed, so you can measure this before guessing.
| Approach | What it reduces | When it fits |
|---|---|---|
| Tool search | Tool definitions loaded upfront | Many tools (10+), most of which aren't needed every turn |
| Programmatic tool calling | tool_result roundtrips | Chains of tool calls that can run as a single script |
| Prompt caching | Token cost of repeated tool definitions | Stable tool definitions across many requests |
| Context editing | Old tool_result blocks in history | Long conversations where early results are no longer relevant |
One row in this table often gets misread. Prompt caching changes what you pay for tokens. It does not change how many tokens are in context. A cached prefix of stale file dumps is still a prefix of stale file dumps: it still uses up the window and still dilutes the model's attention. Caching is the right choice when a large set of tool definitions stays fixed, and it does nothing about bloat or drift. These approaches combine well. A high-volume agent might cache its tool definitions from the start, add tool search once it has ten or more tools, and add context editing once conversations run long enough that early results stop mattering.
Checkpoint 2 of 9· Match them up
Each scenario describes where an agent's tokens or costs are going. Match each one to the approach that targets it.
Tap a term, then the definition that fits it.
Each approach reduces a different thing: definitions loaded upfront, tool_result round trips, the price of repeated stable definitions, or old results in history. Only caching leaves the token count unchanged, so it fits the cost-only scenario and does nothing for bloat.
“Prompt caching doesn’t reduce the number of tokens in context, but it reduces what you pay for them on subsequent requests.”Source: platform.claude.com
Sources4
3.Prune stale tool output with context editing
Context editing is the Messages API feature for removing old tool output while leaving everything else in place. The clear_tool_uses_20250919 strategy starts once input passes a threshold you set. It clears the oldest tool results first and replaces each one with placeholder text telling Claude the result was removed. By default only the results are cleared, so Claude can still see which calls it made. The task instructions in the first user message and the recent turns are not touched. That makes it the least disruptive fix when early file reads and searches are stale and the rest of the conversation still matters.
The editing happens on the server, before the prompt reaches Claude. Your application keeps the full, unmodified history and keeps sending it as usual. There is nothing to sync. This is very different from a hand-rolled sliding window that sends only the last 20 messages. A sliding window has no idea which messages matter, so the first ones to go are the oldest, and the oldest usually include the task itself.
context_management={
"edits": [
{
"type": "clear_tool_uses_20250919",
# Trigger clearing when threshold is exceeded
"trigger": {"type": "input_tokens", "value": 30000},
# Number of tool uses to keep after clearing
"keep": {"type": "tool_uses", "value": 3},
# Optional: Clear at least this many tokens
"clear_at_least": {"type": "input_tokens", "value": 5000},
# Exclude these tools from being cleared
"exclude_tools": ["web_search"],
}
]
},| Option | Default | What it controls |
|---|---|---|
| trigger | 100,000 input tokens | When clearing starts; set in input_tokens or tool_uses |
| keep | 3 tool uses | How many recent tool use/result pairs survive a clearing pass |
| clear_at_least | None | Minimum tokens a pass must free, or the strategy is not applied |
| exclude_tools | None | Tools whose uses and results are never cleared |
| clear_tool_inputs | false | Whether the tool call parameters are cleared along with the results |
Clearing has a cost. Removing a tool result invalidates the cached prompt prefix from that point on, so each pass triggers a new cache write. clear_at_least makes sure a pass only runs when it frees enough tokens to be worth breaking the cache. A companion strategy, clear_thinking_20251015, does the same job for thinking blocks from earlier assistant turns. Its keep setting trades cache hits (keep more thinking) against window space (clear more).
Checkpoint 3 of 9· Check yourself
Your team replaces a hand-rolled window that sent only the last 20 messages with the clear_tool_uses_20250919 strategy. What should the client do with its stored history now, and what will Claude see?
Context editing runs on the server before the prompt reaches Claude. The client keeps and sends its full history with nothing to sync, and only old tool results become placeholders. The first user message and recent turns stay untouched, so this is not a sliding window. Clearing also invalidates the cache from that point on.
“Context editing is applied server-side before the prompt reaches Claude. Your client application maintains the full, unmodified conversation history.”Source: platform.claude.com
Checkpoint 4 of 9· Exam question
A coding agent built on the Messages API has run 60 turns of file reads and greps. Input is near 150k tokens, the early file dumps are no longer relevant, and the task instructions and recent reasoning must stay intact. Which technique restores headroom with the least disruption?
Correct answer: C — Configure context editing to clear older tool results, leaving placeholders once input passes a set token threshold.
- A. Incorrect: prompt caching lowers the cost and latency of resending a repeated prefix, but cached tokens still count toward the context window. The 150k tokens of stale file dumps would remain, so no headroom is restored.
- B. Incorrect: a fixed window of recent messages drops the task instructions once they fall outside it, and it cuts by position rather than relevance. The agent would lose the instructions that must stay intact.
- C. Correct: context editing can clear older tool results server-side and leave placeholders. The bulky early file reads are removed while the instructions and recent reasoning stay in place, so the agent keeps working with minimal change.
- D. Incorrect: token counting only measures the prompt and frees no space. Halting the loop near the limit ends the coding task instead of letting the agent continue with room to spare.
4.Keep bulky reads out of the main context with subagents
Context editing cleans up after material has already entered the conversation. Subagent isolation keeps it from entering at all. A subagent runs the research in its own context window, so the large reads stay out of the orchestrator's window. Only the summary and a small metadata trailer come back. In Claude Code's own token breakdown, a delegated research task costs the main conversation an 80-token call and a 420-token summary, while the reads behind it are spent elsewhere.
Isolation is the right shape when a job needs a lot of raw input and the caller needs only a short conclusion. Searching hundreds of log files for one root cause, surveying a codebase for one answer, and reading a long document set to pick out a few facts all fit this pattern. Telling the main agent to leave raw lines out of its replies does not help, because the tool results are already in messages and count toward the window whatever the reply says. Preloading the data into a cached system prompt does not help either: the tokens are cheaper, but they are all still in context.
Checkpoint 5 of 9· Check yourself
An orchestrator agent has to search about 300 log files to find the one root cause behind an outage. It needs only a short conclusion back. Which design keeps the log contents out of the orchestrator's context window?
A subagent reads the files in its own context window, so only its short summary reaches the orchestrator. Tool results the orchestrator reads itself stay in messages whatever its replies say. Caching makes tokens cheaper but leaves them in context, and a bigger window only lets more irrelevant material in.
“send research to a subagent so the file contents stay in its context window, not yours.”Source: code.claude.com
Checkpoint 6 of 9· Exam question
An agent investigating a production incident reads hundreds of log files to answer one question, and the orchestrating conversation only needs the root-cause conclusion. The main context is filling with raw log output. Which design change fits best?
Correct answer: D — Run the log analysis in a subagent with a separate context window, so only a short findings report returns to the orchestrator.
- A. Incorrect: prompt caching lowers the cost of repeated input tokens, but cached content still counts toward the context window. The log text would stay in the main conversation, so the problem of filling context is not solved.
- B. Incorrect: temperature only controls how random token sampling is. It does not decide how many files the agent opens, and whatever it does read still lands in the main context.
- C. Incorrect: the raw log output is already stored in the conversation as tool results when the files are read. Keeping quotes out of the agent's replies leaves that history, and the context pressure it causes, unchanged.
- D. Correct: the subagent reads the hundreds of files inside its own context window, and the orchestrator receives just the distilled findings. The verbose log output never enters the main conversation.
Sources5
5.Compact when the history still matters
Some long tasks really do need their past: decisions made, constraints found, approaches already ruled out. For those, compaction replaces the older turns with a summary that Claude writes on the server, so the task can continue inside the window with a smaller active context. On the Messages API, server-side compaction is the main strategy for long-running agentic work. The on-demand form, behind the compact-2026-09-04 beta header and the top-level compaction parameter, is the one to use wherever it is available.
| Question | 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 the trigger you set | You |
| Code you write | A compaction loop that requests the summary and swaps it in | One parameter on your ordinary requests | The summarization call, its prompt, and the history rewrite |
| Runs in the background | Yes | No: it runs inside the request that reaches the threshold | Yes, in your own code |
Claude Code compacts automatically before the window fills, and it gives you three controls. /compact focus on the auth bug fix steers the summary toward what you choose instead of what the automatic pass guesses is important. /autocompact 500k sets how full the window gets before the automatic pass runs. /rewind lets you summarize only part of the conversation. A summary is lossy, but not everything goes through it, because startup material is reloaded rather than summarized.
| Mechanism | After compaction |
|---|---|
| Project-root CLAUDE.md and unscoped rules | 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 |
| Background commands and background subagents | Keep running |
Checkpoint 7 of 9· Match them up
Three teams want to keep long-running agents inside the context window by summarizing old turns. Match each compaction approach to the team whose requirements it fits.
Tap a term, then the definition that fits it.
With on-demand compaction you decide when it runs, and it can run in the background. Threshold compaction is one parameter, and the API runs it inside the request that reaches the trigger. A custom summarizer means you write the call, the prompt and the history rewrite yourself.
“Who decides when | You, by sending a request | The API, when input tokens reach the trigger you set | You”Source: platform.claude.com
6.Start a fresh session when the task changes
The question that decides between compacting and starting fresh is whether the next task needs the old history at all. If it does, compact, ideally with a focus. If it does not, any summary still puts finished work back into the window, where it crowds out the files the new task needs and adds tokens to every message. In Claude Code, /clear is the move for switching to unrelated work. The new task does not start from nothing: CLAUDE.md, auto memory, MCP tool names and skill descriptions load before you type anything. Durable project rules belong in those places, not in conversation history.
A bigger window looks like a fix for drift and is not. More context isn't automatically better, and context rot means that keeping two tasks' history side by side gives the model more irrelevant material to be distracted by. Adding a note such as "the migration is done, ignore it" has the same weakness. The old details are still in context, and a prompt can ask the model to set them aside but cannot guarantee it will. When the subject of the work changes, removing the old context is the dependable fix.
When the new work builds on the old: for example, the next step of the same bug fix, where the constraints and decisions found so far still apply. Run /compact with a focus so the summary keeps those, and use /clear only when the work is unrelated.
Checkpoint 8 of 9· Check yourself
Before you run /clear to move from a finished database migration to an unrelated CSS refactor, you remember something. Earlier in the chat you told Claude a project-wide rule: always use the repo's design tokens for colours. The refactor needs that rule. What is the best way to keep it?
After /clear, CLAUDE.md still loads into the new session, so a lasting project rule belongs there and not in the conversation history. Compacting, adding an 'ignore it' note or pasting the old chat back in all keep the finished migration in context, where it can still cause drift.
“Before you type anything: CLAUDE.md, auto memory, MCP tool names, and skill descriptions all load into context.”Source: code.claude.com
Checkpoint 9 of 9· Exam question
During a three-hour Claude Code session on a payments service, you finish a database migration and now want to start an unrelated CSS refactor. Responses have started citing migration details that are irrelevant to the new work. What is the best move?
Correct answer: A — Run /clear before starting the refactor, so the session begins with an empty history and reloads only the CLAUDE.md project rules.
- A. Correct: the CSS work shares nothing with the migration, so resetting the history removes the noise at its source. Durable project rules are reloaded from CLAUDE.md, so nothing needed is lost.
- B. Incorrect: a larger window only gives the migration history more room. The migration details stay in context and keep surfacing in responses, and accuracy still degrades as noisy context builds up.
- C. Incorrect: compaction replaces the history with a summary, but that summary still describes the migration and is carried into the CSS work. The migration details remain in context and can still colour replies.
- D. Incorrect: a note in the prompt does not remove anything from context. The full migration history is still present and still draws attention, and the note adds tokens on top of it.
Sources
(6)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“every message in messages (including tool results, images, and documents), and your tool definitions”
↩︎ Why long sessions degrade before they run out of room“To estimate a request before you send it, use the token counting API.”
↩︎ Prune stale tool output with context editing“more context isn't automatically better”
↩︎ Start a fresh session when the task changes“As token count grows, accuracy and recall degrade, a phenomenon known as context rot.”
↩︎ Key concept“A larger context window allows the model to handle more complex and lengthy prompts, but more context isn't automatically better.”
↩︎ Exam trap 4 - 2.
“irrelevant content degrades model focus”
↩︎ Why long sessions degrade before they run out of room“The API replaces each cleared result with placeholder text indicating to Claude that it was removed.”
↩︎ Prune stale tool output with context editing“Your client application maintains the full, unmodified conversation history. You do not need to sync your client state with the edited version.”
↩︎ Prune stale tool output with context editing“Invalidates cached prompt prefixes when content is cleared.”
↩︎ Prune stale tool output with context editing“Your client application maintains the full, unmodified conversation history. You do not need to sync your client state with the edited version.”
↩︎ Exam trap 2“context is a finite resource with diminishing returns, and irrelevant content degrades model focus”
↩︎ Checkpoint“Context editing is applied server-side before the prompt reaches Claude. Your client application maintains the full, unmodified conversation history.”
↩︎ Checkpoint - 3.
“Context, therefore, must be treated as a finite resource with diminishing marginal returns.”
↩︎ Why long sessions degrade before they run out of room - 4.
“Pick the one that matches where your tokens are going.”
↩︎ Match the technique to where the tokens are going“Prompt caching doesn't reduce the number of tokens in context, but it reduces what you pay for them on subsequent requests.”
↩︎ Match the technique to where the tokens are going“Prompt caching doesn't reduce the number of tokens in context, but it reduces what you pay for them on subsequent requests.”
↩︎ Exam trap 1“Prompt caching doesn’t reduce the number of tokens in context, but it reduces what you pay for them on subsequent requests.”
↩︎ Checkpoint - 5.https://code.claude.com/docs/en/context-windowOfficial docs
“a subagent handles the research in its own separate context window, so the large file reads stay out of yours.”
↩︎ Keep bulky reads out of the main context with subagents“Only the summary and a small metadata trailer come back.”
↩︎ Keep bulky reads out of the main context with subagents“The summary keeps what you choose instead of what the automatic pass guesses is important.”
↩︎ Compact when the history still matters“run /clear when switching to unrelated work. Old conversation crowds out the files you need next and costs tokens on every message.”
↩︎ Start a fresh session when the task changes“Before you type anything: CLAUDE.md, auto memory, MCP tool names, and skill descriptions all load into context.”
↩︎ Start a fresh session when the task changes“run /clear when switching to unrelated work. Old conversation crowds out the files you need next and costs tokens on every message.”
↩︎ Exam trap 3“send research to a subagent so the file contents stay in its context window, not yours.”
↩︎ Checkpoint - 6.
“Compaction replaces the older turns of a conversation with a summary that Claude writes on the server”
↩︎ Compact when the history still matters“Use on-demand compaction wherever it is available.”
↩︎ Compact when the history still matters“Who decides when | You, by sending a request | The API, when input tokens reach the trigger you set | You”
↩︎ Checkpoint