CCDV-F 6.1 — Context engineering

What is actually in the window

assembled in this order on every request

System promptrole, rules, stable context
Tool definitionsschemas cost tokens even unused
Retrieved documentswhatever you loaded up front
Message historyevery turn so far
Tool resultsusually the fastest-growing part

Everything here is re-sent on every request, because the API is stateless. Only the bottom two layers grow on their own — which is why they are where every fix is aimed.

Why a full window is worse than a small one

The naive model of a context window is a bucket: it holds a certain number of tokens, and trouble starts only when you overflow it. That is not how it behaves. Anthropic's engineering write-up on context engineering describes an attention budget that depletes as tokens accumulate, and names the resulting degradation context rot: performance falls off well before the hard limit, because a transformer has to relate every token to every other token, and that ability gets stretched thin as the sequence grows.

So there are two distinct failure modes, and the exam separates them. Bloat is the token count itself — cost, latency, and eventually an error when the request no longer fits. Drift is the quality problem: the instruction that mattered is now twelve thousand tokens above a wall of tool output, and the agent starts optimising for the most recent, loudest thing in its context instead of the task. Bloat is measurable from usage; drift shows up as an agent that was sharp for ten turns and is meandering by turn thirty.

The same write-up gives the design principle worth memorising: aim for the smallest set of high-signal tokens that maximises the likelihood of the desired outcome. Not the most context you can afford — the least you can get away with. Every technique below is an implementation of that one sentence.

Three levers, in the order you should reach for them

The window is filling up. What do you do?

Old tool output is dead weight
Prune itdrop results you no longer need
The whole history is long
Compact itreplace old turns with a summary
A sub-task is self-contained
Isolate itsubagent returns only a summary
You only need it sometimes
Don't load itfetch just in time by reference

Pruning and just-in-time loading are free; compaction and isolation each cost extra model calls. Reach left to right.

Pruning: clear tool output you no longer need

In an agentic loop, tool results are almost always the largest and least durable part of the context. A file listing, a page of search results, a 40 KB API response — each mattered for exactly one turn, and then sat in history being re-sent and re-charged forever. Pruning removes them.

You can do this yourself in your own loop, and many teams do: keep the last few tool results verbatim and replace older ones with a short placeholder. The Claude Developer Platform also offers it server-side as context editing, currently behind the context-management-2025-06-27 beta header. You pass a context_management object with an edits array; the clear_tool_uses_20250919 strategy clears old tool results once the conversation crosses a threshold.

Server-side pruning of old tool resultspython

resp = client.beta.messages.create(
    model=MODEL_ID,
    max_tokens=4096,
    tools=TOOLS,
    messages=messages,
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [{
            "type": "clear_tool_uses_20250919",
            # start clearing once input crosses this many tokens
            "trigger": {"type": "input_tokens", "value": 30000},
            # always keep the three most recent tool uses verbatim
            "keep": {"type": "tool_uses", "value": 3},
            # don't bother unless it frees at least this much
            "clear_at_least": {"type": "input_tokens", "value": 5000},
            # results from these tools are never cleared
            "exclude_tools": ["web_search"],
        }]
    },
)
print(resp.context_management)   # applied_edits: what was actually cleared

Three details carry the marks. The clearing happens server-side, before the prompt reaches the model — your client keeps the full, unedited history, so there is no state to synchronise. By default only the results are cleared, not the calls that produced them; set clear_tool_inputs if you want both gone. And because clearing changes the prompt prefix, it invalidates the prompt cache at that point — which is exactly what clear_at_least is for: it stops the system from paying a cache write to reclaim a trivial number of tokens. Caching itself is 5.4's territory; the interaction is the part that belongs here.

Compaction: summarise the history and carry on

Pruning removes whole blocks by rule. Compaction does something different: it takes a conversation approaching the limit, summarises what happened, and restarts the window from that summary plus the most recent turns. Nothing is thrown away blindly — decisions, constraints and open threads are carried forward in compressed form while the raw transcript that produced them is dropped. It is the difference between clearing your desk and writing a handover note.

The platform offers this in two shapes, both in beta. Compaction on demand (compact-2026-09-04) is driven by your application: you ask for a summary and swap the returned block into your messages, and recent turns can be preserved word for word. Compaction at a token threshold is driven by the API: you configure a trigger, and compaction runs inside whichever request crosses it. On-demand is the one to reach for first, because you control the timing — you can compact between tasks rather than in the middle of one.

Pruning and compaction are not the same move

Pruning · context editing

Removes blocks by rule — old tool results, thinking
No summarisation, no extra model call
Keeps the last N tool uses verbatim
Best when results are bulky and short-lived

Compaction

Replaces old turns with a generated summary
Costs a model call to produce the summary
Recent turns can be kept word for word
Best when the reasoning so far still matters

Both shrink the window. Only one of them preserves what the dropped turns meant — which is why compaction costs a model call and pruning does not.

The judgement call in compaction is always the same one: what to keep and what to discard. A summary that drops the customer's account number, or the constraint that the migration must not touch production, has not saved you anything — it has produced an agent that confidently continues on a false premise. If a fact must survive, do not trust it to a summary; have the agent write it somewhere durable.

Worked example · A migration agent that gets vaguer as it goes

An internal platform team runs an agent that migrates services from one deployment system to another. It reads config files, runs validation commands and edits manifests. On small services it is excellent. On a service with ninety files it starts re-reading files it has already read, and by the end it has forgotten a constraint stated in the first message.

Measure before changing anything. usage.input_tokens on the last request is 160,000, of which roughly 120,000 is tool results — mostly whole files read once and never referenced again.
Prune first. Context editing with a 30,000-token trigger and keep of three tool uses cuts the steady-state window by about two thirds. The re-reading stops being expensive, though it does not stop.
Move the constraint out of the transcript. The rule “never modify anything under prod/” moves from the first user message into the system prompt, where it is re-sent on every request and cannot age out of view.
Compact between phases. The agent works in phases — survey, plan, edit, verify. At each phase boundary the app compacts on demand, so the plan survives as a summary and the hundred file reads that produced it do not.
Isolate the survey. The survey phase is read-only and self-contained, so it becomes a subagent with read tools only. It returns a one-page inventory instead of ninety file contents.
Result. Same model, same task, no prompt rewrite. The agent finishes long migrations because the window now holds the plan and the last few actions rather than an archaeological record.

Takeaway: The fix was never “tell it to remember better”. It was three separate mechanical reductions, applied in order of cost: prune, then compact, then isolate.

Isolation: give the sub-task its own window

Pruning and compaction shrink one window. Isolation avoids putting the tokens in that window at all. A subagent runs with its own context — its own system prompt, its own tools, and no sight of the parent conversation — does the work, and returns a condensed result. Anthropic's engineering guidance describes sub-agents returning a distilled summary, often on the order of one to two thousand tokens, while the intermediate exploration that produced it stays in the subagent's window and is discarded with it.

Claude Code's implementation makes the mechanics concrete: a subagent is a Markdown file with YAML frontmatter — name and description required, with optional tools, model and more — stored in .claude/agents/ for a project or ~/.claude/agents/ for a user. It starts fresh: the conversation history does not load, and only a summary comes back. That is the whole point. Restricting tools also narrows what the sub-task can do, which makes isolation a security pattern as well as a context one — 7.2 covers that side.

What crosses the boundary

Coordinatorholds the plan and the results

Search agentreads 40 pages, returns 1
Code readerread-only tools
Verifierruns checks, reports pass/fail

The arrows in are task briefs; the arrows back are summaries. The raw searching and reading never reaches the coordinator's window at all.

Isolation does not require subagents, though. A multi-step agentic workflow achieves the same thing with ordinary code: split the job into stages, and start each stage with a fresh conversation seeded only with the previous stage's output. Extraction, then classification, then drafting — three short windows instead of one enormous one. It is cheaper and far more debuggable, and when the stages are known in advance it is usually the better design. Choosing between a fixed workflow and a model-driven agent is 1.1's subject; here the point is that either shape can be used to keep windows small.

Loading less in the first place

The techniques above are all remedial. The cheapest context engineering happens before the first request. Just-in-time retrieval is the pattern: rather than pre-loading every document the agent might want, give it lightweight identifiers — file paths, record ids, stored queries — and tools to fetch the full thing when it decides it needs it. Anthropic's guidance calls the effect progressive disclosure: the agent discovers what matters by exploring, and the context ends up containing the three documents that were relevant instead of the three hundred that might have been.

When you do put a long document in the window, placement matters. The documentation's long-context guidance is specific: put long inputs near the top, above the query, instructions and examples, and keep the question at the end — in their tests, placing queries at the end improved response quality by up to 30 percent on complex multi-document inputs. Wrap each document in XML tags with its metadata so the model can tell them apart, and for extraction tasks ask it to quote the relevant passages before answering, so its reasoning is anchored to the source rather than to a vague recollection of it.

Worked example · A legal-research assistant that loads the whole matter

A law firm's research tool answers questions about an active matter. Its first version loaded every document in the matter — often 300,000 tokens — into the system prompt at session start, so that Claude would “have everything”. Answers were slow, expensive, and oddly inconsistent on details that were plainly in the files.

Diagnose. Cost per question is enormous, and accuracy is worse than on a small matter. That combination is the signature of context rot, not of a missing document.
Replace the dump with an index. The session now starts with a one-line-per-document manifest: id, title, date, type. A few thousand tokens instead of three hundred thousand.
Give it a fetch tool. get_document(id) returns the full text. The assistant pulls in the two or three documents a question actually turns on.
Structure what does get loaded. Each fetched document arrives wrapped in <document> tags with <source> metadata, placed above the question rather than below it.
Ask for quotes first. The prompt instructs it to quote the passages it is relying on before answering, which makes wrong answers visibly wrong to the associate reviewing them.
Result. Median cost per question falls by more than an order of magnitude, and the answers cite where they came from — which the firm values more than the speed.

Takeaway: “Give the model everything” feels safe and is the most common cause of both bills and drift. An index plus a fetch tool beats a dump, almost every time.

Traps the wrong answers are built from

Tempting but wrong	Do this instead
Front-loading every document the agent might need, to be safe	Load an index and fetch by reference just in time; pre-loading buys context rot and cost, not reliability.
Treating the context limit as the only constraint	Watch quality as well as token count — drift starts well before the window is full.
Fixing a forgetful agent by adding more instructions	Remove tokens instead: prune tool results, compact history, and put durable rules in the system prompt.
Truncating the oldest messages blindly when the window fills	Compact them into a summary, or write the facts that must survive to storage before they are dropped.
Splitting a task across subagents when the parts need shared judgement	Isolate only self-contained work, since the coordinator sees nothing but the returned summary.

You should now be able to

Explain context rot and distinguish context bloat from context drift from a scenario's symptoms.
Configure tool-result pruning with a trigger, a keep window and an exclusion list, and say what it does to the prompt cache.
Choose between pruning, compaction, isolation and just-in-time loading for a given failure.
Design a subagent or a multi-step workflow that keeps bulky intermediate work out of the main window.
Place long documents, metadata and the query correctly within a prompt.
Identify which facts must be written to durable storage before history is compacted away.

Context engineering