Context Engineering and Long-Running Work

Everything Claude reads competes for the same limited attention, so long conversations, long-running agent tasks and multi-agent pipelines fail in predictable ways when nobody decides what stays in the context window. This page teaches those decisions: what fills the window, how critical facts survive summarization, how compaction, context editing and memory work on the Claude API and in Claude Code, how subagents isolate noisy work, how to explore a large codebase without flooding the window, what must cross each handoff between agents, and how findings keep their sources through synthesis. It is the depth reference for Domain 5 of the Architect, Foundations exam (weighted 15%), the Context Engineering skill of the Developer exam (3.8%), the context objectives of the Architect, Professional exam, and the Associate objective on context limits and memory; each section opens with the objectives it serves, and the Exam map collects them.

Why context is a budget

Tested in: CCAR-F 5.1 (5.1-K3, 5.1-K4), 1.6-S2, Appendix technology list ("Context window management"), sample question 12 · CCDV-F D6.1 Context Engineering, D5.1 LLM Fundamentals (context windows), D5.4 Cost and Token Management · CCAR-P 2.4, 3.8, 4.5, sample 2 · CCAO-F D3.4

Anthropic's engineering post Effective context engineering for AI agents defines context as "the set of tokens included when sampling from a large-language model (LLM)" and context engineering as "the set of strategies for curating and maintaining the optimal set of tokens (information) during LLM inference, including all the other information that may land there outside of the prompts." The API docs define the window itself as "all the text a language model can reference when generating a response, including the response itself" (Context windows).

More tokens, less attention

Three documented effects explain why the window is treated as a budget to spend, not a bucket to fill. The quotations come from the engineering post unless marked otherwise:

• Context rot. "as the number of tokens in the context window increases, the model’s ability to accurately recall information from that context decreases." The API's Context windows page uses the same name: "As token count grows, accuracy and recall degrade, a phenomenon known as context rot."
• An attention budget. "LLMs have an “attention budget” that they draw on when parsing large volumes of context. Every new token introduced depletes this budget by some amount". The architectural reason given is that every token can attend to every other token, which "results in n² pairwise relationships for n tokens."
• A gradient, not a cliff. "These factors create a performance gradient rather than a hard cliff: models remain highly capable at longer contexts but may show reduced precision for information retrieval and long-range reasoning".

The post adds that some models degrade more gently than others, but "this characteristic emerges across all models", and draws its conclusion: "Context, therefore, must be treated as a finite resource with diminishing marginal returns." Its guiding principle is "good context engineering means finding the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome." Smallest is not the same as shortest: "minimal does not necessarily mean short; you still need to give the agent sufficient information up front to ensure it adheres to the desired behavior."

Claude Code's documentation states the same constraint in working terms: "Most best practices are based on one constraint: Claude's context window fills up fast, and performance degrades as it fills." When the window is getting full, the same page warns, Claude may start "forgetting" earlier instructions or making more mistakes (Best practices for Claude Code).

A bigger window is not the fix

The Architect, Foundations exam tests this directly. In sample question 12 a single-pass review of a 14-file pull request gives detailed feedback on some files, superficial comments on others, missed bugs and contradictory verdicts. Option C, "Switch to a higher-tier model with a larger context window to give all 14 files adequate attention in one pass", is wrong, and Anthropic's rationale says why: "Option C misunderstands that larger context windows don't solve attention quality issues". Anthropic's context engineering cookbook gives the mechanism: "Context rot and prefill latency scale with how much is in the window, not with the window's limit". The engineering post expects that "for the foreseeable future, context windows of all sizes will be subject to context pollution and information relevance concerns", at least "for situations where the strongest agent performance is desired".

Decide (our rule, from the sample question 12 rationale). If an item describes missed details, uneven depth or contradictions on a large input, choose the option that shrinks, splits or restructures what is in the window: focused passes (CCAR-F 1.6-S2 splits reviews "to avoid attention dilution"), trimmed tool output, subagents or compaction. Do not choose an option that keeps the same input in one pass and only adds window size, even when it also offers a higher-tier model as option C does: the rationale says larger windows "don't solve attention quality issues", and the engineering post says the degradation "emerges across all models".

Where the tokens go

The first four rows come from the API's Context windows page (as of September 2026), the fifth from Using the Messages API, and the last from Claude Code's Extend Claude Code and the Agent SDK's How the agent loop works pages.

Because the API is stateless, CCAR-F 5.1-K4 expects you to know "The importance of passing complete conversation history in subsequent API requests to maintain conversational coherence." The price is that every turn re-sends everything before it. Claude Academy's tutorial How context affects Claude's performance and cost makes the same point for chat: "That's why a short question late in a long conversation may cost more than the same question in a fresh one, and why starting a new chat can be the cheapest and fastest way to get an answer." Agentic work multiplies the effect; in Anthropic's research-system measurements "agents typically use about 4× more tokens than chat interactions, and multi-agent systems use about 15× more tokens than chats" (How we built our multi-agent research system).

Tools are the other large consumer, twice over:

• Definitions load before any work. The Tool search tool docs describe a typical multiserver setup (GitHub, Slack, Sentry, Grafana and Splunk) that can consume about 55k tokens of definitions before Claude does any work, and note that "Tool search typically reduces this by over 85 percent". They also warn that Claude's ability to pick the right tool degrades once more than 30 to 50 tools are available.
• Results pile up. CCAR-F 5.1-K3 names "How tool results accumulate in context and consume tokens disproportionately to their relevance (e.g., 40+ fields per order lookup when only 5 are relevant)". Trimming before results accumulate is taught in Preserving critical information in long conversations; clearing them afterwards is in Compaction, context editing and memory; sizing the tool set itself is in Designing a tool set.

Model window sizes, output limits and token counting are in Tokens, context windows and counting. Two overflow behaviors matter here. If the input alone is larger than the window, the API returns a 400 invalid_request_error ("prompt is too long") on every model. On Claude 4.5 models and newer, a request whose input plus max_tokens exceeds the window is accepted, and if generation reaches the limit it stops with stop_reason: "model_context_window_exceeded", which the stop-reason reference says to "Treat the response as truncated." On earlier models the same request returns a validation error by default; the model-context-window-exceeded-2025-08-26 beta header opts them in to the model_context_window_exceeded behavior.

Up front or just in time

CCAR-P 3.8 asks you to "Evaluate progressive discovery vs. monolithic context strategy." Anthropic's engineering post describes both ends. Many AI-native applications "employ some form of embedding-based pre-inference time retrieval to surface important context for the agent to reason over." Agents built with the "just in time" approach instead "maintain lightweight identifiers (file paths, stored queries, web links, etc.) and use these references to dynamically load data into context at runtime using tools", which lets an agent incrementally discover relevant context through exploration.

In the table below, quoted cells are the post's words; unquoted Gains and Costs cells are our summary of the trade-off.

Progressive discovery shows up across the products:

• Agent Skills load in stages: name and description metadata at startup, the full SKILL.md when relevant, bundled files only as needed. Per Anthropic's Agent Skills post, that metadata "is the first level of progressive disclosure".
• Tool search (defer_loading: true) discovers tool definitions on demand. The Manage tool context page suggests adding it "once your toolset grows past roughly 20 tools or your baseline context usage becomes noticeable."
• Claude Code loads CLAUDE.md in full, and it costs context on every request; skills load only their descriptions until used; MCP servers load tool names, with full schemas deferred until a tool is needed; subagents run in a context isolated from the main session, fresh unless the subagent is a fork of the current conversation (Extend Claude Code).

Decide (our rule, from the sources cited). Content every request needs (role, policies, a style guide) goes up front, ordered before the dynamic content, and is cached. CCAR-P sample 2 rewards exactly that for a repeated 8,000-token system prompt and policy: "Place the static system prompt and policy before the dynamic content and enable prompt caching." See Prompt caching. Content that is large, changing or rarely needed (a codebase, a document store, a large tool catalog) is discovered just in time. When both apply, use the hybrid. In the passage that describes the hybrid, the engineering post also says "do the simplest thing that works" will likely remain Anthropic's best advice for teams building agents on top of Claude.

How Claude tracks its own budget

Some models see their remaining budget. Per the Context windows page (as of September 2026), Claude Sonnet 5, Sonnet 4.6, Sonnet 4.5 and Haiku 4.5 have context awareness: they track their remaining context window, which the docs call their "token budget", throughout a conversation. Nothing needs enabling, and you never send the tags yourself: "The API injects them." The injected formats, shown for a 200k-token window, are:

<budget:token_budget>200000</budget:token_budget>
<system_warning>Token usage: 35000/200000; 165000 remaining</system_warning>

The first tag goes in the system prompt of every request; the second arrives after each tool call, and image tokens are included in these budgets. Opus 4.7 and later Opus models, Fable 5.1, Mythos 5.1, Fable 5 and Mythos 5 "don't receive these injected tags." On those models the docs point to task budgets instead (beta, header task-budgets-2026-03-13), which tell Claude how many tokens it has for a whole agentic loop, including thinking, tool calls, tool results and output (Task budgets). The request body from the docs' example, sent with anthropic-beta: task-budgets-2026-03-13:

{
  "model": "claude-opus-5-5",
  "max_tokens": 128000,
  "stream": true,
  "messages": [{
    "role": "user",
    "content": "Review the codebase and propose a refactor plan."
  }],
  "output_config": {
    "effort": "high",
    "task_budget": {"type": "tokens", "total": 64000}
  }
}

Traps

• Choosing prompt caching to free up context. It does not: "Prompt caching doesn't reduce the number of tokens in context, but it reduces what you pay for them on subsequent requests" (Manage tool context). Caching is the right answer when the problem is the cost and latency of a repeated, stable prefix (CCAR-P sample 2), not when the window is full.
• Truncating content the task needs. CCAR-P sample 2's rationale rejects cutting the policy document because "Truncation (A) loses needed policy". Shrink what is irrelevant, not what is required.
• Sending only the latest message to save tokens. The API is stateless; dropping history breaks coherence (5.1-K4). Shrink history deliberately with compaction or a summary instead.
• Adding tools to make the agent more capable. Definitions cost tokens up front, and selection accuracy falls as the tool count grows.
• Buying a bigger window to fix missed details. See sample question 12 above.

Preserving critical information in long conversations

Tested in: CCAR-F 5.1 (5.1-K1, 5.1-K2, 5.1-S1 to 5.1-S4), 1.5-K1, Appendix in-scope topic "Context window optimization", Scenario 1 (Customer Support Resolution Agent) · CCDV-F D6.1 Context Engineering (context drift and bloat, tool output pruning) · CCAR-P 2.4 · CCAO-F D3.4

Long conversations get summarized, by you, by the API or by Claude Code, and summaries lose detail. The CCAR-F exam guide names the risk in 5.1-K1: "Progressive summarization risks: condensing numerical values, percentages, dates, and customer-stated expectations into vague summaries". Anthropic's own sources agree on what goes first:

• The context engineering cookbook: "The summary preserves key decisions and facts but may drop specific numbers or exact phrasing." In its probe, high-level facts central to the task usually survived, but "Obscure specifics (a single cell in an appendix table, a heterogeneity statistic) usually don't."
• Claude Code's How Claude Code works: "Your requests and key code snippets are preserved; detailed instructions from early in the conversation may be lost. Put persistent rules in CLAUDE.md rather than relying on conversation history."
• Claude Academy's How context affects Claude's performance and cost: compaction "is still a summary, and can still occasionally result in lost details."

Our rule for the whole section: anything that must be exact should not depend on a summary. Keep it somewhere that is re-sent or re-injected verbatim, and write summary instructions that name it.

Pin transactional facts outside the summary

CCAR-F 5.1-S1: "Extracting transactional facts (amounts, dates, order numbers, statuses) into a persistent "case facts" block included in each prompt, outside summarized history". For sessions that handle several issues, 5.1-S2 adds "Extracting and persisting structured issue data (order IDs, amounts, statuses) into a separate context layer for multi-issue sessions".

The exam guide's "case facts" block is a pattern you build yourself; the products supply the building blocks listed below. The mechanics are simple because the API is stateless: your code owns the request, so it can rebuild the facts block on every turn and keep it out of the range that gets compacted. That placement matters. On-demand compaction removes the summarized messages and puts one compaction block first in messages, and role: "system" messages inside the summarized range "are summarized too", so a fact that lives only in an old message ends up in the summary, where it can go vague. An illustrative block for Scenario 1's support agent (field names and values are ours):

<case_facts>
customer_id: C-4471 (verified by get_customer)
issue_1: order #12345, status: delivered damaged, refund requested: 89.99 USD
issue_2: order #12377, status: in transit, customer expects delivery by 2026-09-26
agreed_so_far: replacement offered for issue_1; customer declined and asked for a refund
</case_facts>

Each surface documents mechanisms that come closest to the case-facts block. Some re-send or re-inject exact text; others only steer what a summary keeps, and that summary is still lossy:

Write summary instructions that keep specifics

When you control the summarization prompt, name what must survive. Both server-side compaction kinds on the Messages API accept an instructions string, and in both it replaces the default summarization prompt completely instead of adding to it. For on-demand compaction (beta header compact-2026-09-04), the Compaction on demand page caps instructions at 16,384 characters and says to "say what the summary must retain and tell the model not to call tools." Its example:

{
  "compaction": {
    "type": "summarize",
    "instructions": "Summarize this recipe app design conversation. Preserve every entity and field name agreed so far, and the user's latest open request. Do not call tools; respond with the summary text only."
  }
}

The Prompting Claude Fable 5.1 guide notes that server-side compaction already tells the model what to retain, and publishes a summary instruction for client-side compaction that lists six things to preserve: difficulties and how they were handled; options raised, tried or set aside; anything asked for, decided, agreed or ruled out, stated exactly; where things stand now; what is still open; and hard-to-reconstruct details such as names, numbers, dates, exact wording and links, kept exactly. It weights the two voices differently: "keep what the user said, asked for, shared, or established carefully and close to their own words", while Claude's own explanations can be condensed.

Two tuning rules from the engineering post: "Start by maximizing recall to ensure your compaction prompt captures every relevant piece of information from the trace, then iterate to improve precision by eliminating superfluous content." And the reason for caution: "overly aggressive compaction can result in the loss of subtle but critical context whose importance only becomes apparent later." The Context editing page lists "Tasks requiring precise recall of early conversation details" and "Tasks that need to maintain exact state across many variables" as less ideal use cases for client-side SDK compaction (compaction_control, now deprecated; see the warning in Server-side compaction on the Claude API); those are exactly the facts to pin.

Trim tool output before it accumulates

CCAR-F 5.1-S3: "Trimming verbose tool outputs to only relevant fields before they accumulate in context (e.g., keeping only return-relevant fields from order lookups)". The guide's example is an order lookup that returns 40+ fields when 5 matter (5.1-K3). Trim at the point where the result is produced:

# Illustrative: a returns agent needs a handful of fields from a 40+ field order record.
RETURN_FIELDS = ("order_id", "status", "delivered_at", "total", "return_window_ends")

def trim_order(order: dict) -> dict:
    return {key: order[key] for key in RETURN_FIELDS if key in order}

The table draws on Anthropic's Writing effective tools for AI agents, Claude Code's Manage costs effectively and Environment variables pages, and the API's Manage tool context page.

Decide (our rule, from the sources cited). If you own the tool, trim in the tool. If you do not (a third-party MCP server), transform the result before the model sees it: CCAR-F 1.5-K1 names "Hook patterns (e.g., PostToolUse) that intercept tool results for transformation before the model processes them", and current Claude Code and Agent SDK docs let a PostToolUse hook replace any tool's output with updatedToolOutput (the Agent SDK docs call the older MCP-only updatedMCPToolOutput deprecated; the Claude Code reference says to prefer updatedToolOutput). The replacement only changes what Claude sees; the tool has already run. See Hooks in the SDK. If old results have already piled up and can be fetched again, clear them with context editing.

Order aggregated input for position effects

CCAR-F 5.1-K2 defines the effect the exam calls "lost in the middle": "models reliably process information at the beginning and end of long inputs but may omit findings from middle sections". The matching skill, 5.1-S4, is "Placing key findings summaries at the beginning of aggregated inputs and organizing detailed results with explicit section headers to mitigate position effects".

Anthropic's Prompting best practices give the documented layout for large documents or data-rich inputs (20k+ tokens): "Place your long documents and inputs near the top of your prompt, above your query, instructions, and examples." The page reports that "Queries at the end can improve response quality by up to 30 percent in tests, especially with complex, multidocument inputs," recommends wrapping each document in <document> tags with <document_content> and <source> subtags when using multiple documents, and suggests asking Claude to quote relevant parts first. An illustrative layout of our own that follows the docs' order (material first, query last) and the guide's skill (summary first, explicit sections):

<aggregated_findings>
  <key_findings_summary>
    The three findings that matter most, each with its source ID.
  </key_findings_summary>
  <section title="Pricing data">...</section>
  <section title="Regulatory news">...</section>
  <section title="Technical benchmarks">...</section>
</aggregated_findings>

Using only the findings above, recommend a Q3 focus and cite the source ID for each claim.

Full long-document prompting technique is in Long documents.

Traps

• Summarizing everything, including the numbers. 5.1-K1 is the trap itself: amounts, percentages, dates and what the customer was promised go vague. Pin them.
• Relying on an instruction given once, early in the chat. Claude Code's docs say such instructions can be lost at compaction; put standing rules in CLAUDE.md.
• Passing raw 40-field tool results "just in case". They crowd out what matters (5.1-K3). Trim first.
• Answering a position-effect item with a bigger window. The fix is ordering and structure (5.1-S4).

Compaction, context editing and memory

Tested in: CCAR-F 5.4-K2, 5.4-S2, 5.4-S5, Appendix technology list (/compact, /memory, "Context window management") · CCDV-F D6.1 Context Engineering (compaction, tool output pruning), D1.3 Agent Patterns and Frameworks (memory, context-window management), D3.1 Claude Code Operation (Agent Memory) · CCAR-P 2.4, 4.5 · CCAO-F D3.4

Anthropic's Effective context engineering for AI agents names three techniques for work that outgrows one window: "compaction, structured note-taking, and multi-agent architectures." Its context engineering cookbook adds clearing and gives one mental model for compaction, clearing and memory: "compaction compresses the whole window when it grows too large, clearing drops stale re-fetchable data inside the window, and memory moves information out of the window so it survives across sessions." Subagents are covered in Subagents as context isolation.

Server-side compaction on the Claude API

"Compaction replaces the older turns of a conversation with a summary that Claude writes on the server, so you need no summarization code of your own." The Context windows page calls server-side compaction "the primary strategy for context management" for long-running conversations and agentic workflows. There are two kinds, both in beta, and the compaction overview says: "Use on-demand compaction wherever it is available."

An on-demand request and the swap that follows it, combined from the request sample and the compaction loop in the on-demand compaction docs (history is your message list; send the same system prompt and tools as the rest of the conversation when you have them):

response = client.beta.messages.create(
    model="claude-opus-5-5",
    # max_tokens caps the whole call, including any thinking, so allow several thousand tokens.
    max_tokens=4096,
    betas=["compact-2026-09-04"],
    messages=history,
    compaction={"type": "summarize"},
)
if response.stop_reason == "compaction":
    history = [{"role": "assistant", "content": response.content}]

const response = await client.beta.messages.create({
  model: "claude-opus-5-5",
  // max_tokens caps the whole call, including any thinking, so allow several thousand tokens.
  max_tokens: 4096,
  betas: ["compact-2026-09-04"],
  messages: history,
  compaction: { type: "summarize" }
});
if (response.stop_reason === "compaction") {
  history = [{ role: "assistant", content: response.content }];
}

The response carries only the block, and the summarization tokens appear under usage.iterations:

{
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: ...",
      "signature": "EuYBCkQY..."
    }
  ],
  "stop_reason": "compaction",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "iterations": [{ "type": "compaction", "input_tokens": 144, "output_tokens": 276 }]
  }
}

Rules that production bugs turn on (current-docs material from Compaction on demand and Compaction at a token threshold; the guides test compaction only as a concept and as /compact):

• Compact early. "The conversation must still fit the model's context window, so compact before you outgrow it, not after."
• Check stop_reason first. A summary comes back only when the call ends normally; "Otherwise, the response is still a 200 with empty content, so check stop_reason before you look for the block."
• Swap carefully. "Send it in future requests exactly as it came," signature included; a changed signature or content returns a 400. Summarized messages left in front of the block return a 400 (compaction_block_misplaced), but "Two mistakes in the swap raise no error": summarized messages left after the block are sent to Claude again, and a later request that leaves the block out gives Claude no summary. Send the compact-2026-09-04 header on every request that carries the block.
• Restate what the summary cannot carry. "Images, documents, container_upload blocks, and fetched URLs inside the summarized messages are gone once the block replaces them." role: "system" messages inside the summarized range are summarized too, so restate instructions that must keep applying.
• One kind per request. "You can't combine compaction with context_management on one request."
• Same model. Both kinds summarize with the request's model; the threshold docs put it plainly: "There is no option to use a different (for example, cheaper) model for the summary."
• Tools during summarization. With tools defined, the model occasionally calls a tool instead of summarizing. Threshold compaction then yields a compaction block with content: null; an on-demand request returns empty content with stop_reason: "tool_use". In both cases, custom instructions that tell the model not to call tools are the documented fix.
• Billing. Compaction adds a sampling step that is billed and rate-limited; "To calculate total tokens consumed and billed for a request, sum across all entries in the usage.iterations array." Sending a block back on later requests adds no compaction cost.
• Caching. For threshold compaction, the docs advise: "To maximize cache hit rates, add a cache_control breakpoint at the end of your system prompt," so only the summary needs a new cache write. For on-demand compaction, "cache_control on the block places a breakpoint after the summary."

Variants on the on-demand loop: keep-tail compaction (Compaction that keeps recent turns) keeps the last few turns word for word, and "No parameter sets which turns are kept": you pick a cut point where no tool call is left open. Background (async) compaction lets the conversation continue on its full history while the summary is written, then swaps the block in. The SDK tool runners can do the request for you (Compaction on demand): "When you decide to compact, call compact_before_next_turn() on the runner" (compactBeforeNextTurn() in TypeScript and Java); create the runner with the compact-2026-09-04 beta, "because the runner doesn't add it."

With a task budget, the three compaction routes behave differently (Task budgets):

Context editing: clearing tool results and thinking

Context editing removes content server-side before the prompt reaches Claude, on the reasoning that "context is a finite resource with diminishing returns, and irrelevant content degrades model focus." It needs the beta header context-management-2025-06-27 and works on all supported Claude models. "Your client application maintains the full, unmodified conversation history," so there is nothing to sync. Current docs call server-side compaction the primary strategy for most cases and context editing the tool for finer-grained control.

The two strategies combined, as in the docs' example (request fields only; the call also sends the context-management-2025-06-27 beta header):

{
  "context_management": {
    "edits": [
      {"type": "clear_thinking_20251015", "keep": {"type": "thinking_turns", "value": 2}},
      {
        "type": "clear_tool_uses_20250919",
        "trigger": {"type": "input_tokens", "value": 50000},
        "keep": {"type": "tool_uses", "value": 5}
      }
    ]
  }
}

Per the context editing docs, cleared results are replaced with "placeholder text indicating to Claude that it was removed." clear_thinking_20251015 takes keep as {"type": "thinking_turns", "value": N} (N greater than 0) or "all"; its default is model-specific (all turns on Opus 4.5 and later, Sonnet 4.6 and later, and the Fable and Mythos models; the last turn only on earlier Opus and Sonnet models and all Haiku models). When both strategies are used, clear_thinking_20251015 "must be listed first in the edits array." The response's context_management.applied_edits reports what was applied (for example cleared_tool_uses, cleared_thinking_turns, cleared_input_tokens), in the final message_delta event when streaming. Tool result clearing invalidates cached prompt prefixes, which is why clear_at_least exists; kept thinking blocks preserve the cache, and cleared ones invalidate it at the clearing point. Combined with the memory tool, Claude "receives an automatic warning to preserve important information" as the clearing threshold approaches. In the launch post (Managing context on the Claude Developer Platform, September 29, 2025), context editing plus the memory tool improved Anthropic's internal agentic-search evaluation by 39% over baseline, and context editing alone by 29%.

The memory tool

The memory tool is how an API agent writes structured notes outside the window. "Claude can create, read, update, and delete files that persist between sessions, building up knowledge over time without keeping everything in the context window." It is client-side: "Claude requests file operations, and your application executes them." Setup is one tools entry, available on all Claude 4 and later models with no beta header for the tool itself (the SDK helpers live in beta namespaces):

{
  "tools": [{"type": "memory_20250818", "name": "memory"}]
}

import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool

client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")
runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Remember that customer Acme Corp prefers email follow-ups."}],
    tools=[memory],
)
final_message = runner.until_done()

For multi-session work the memory tool docs describe an initializer session that sets up "a progress log (tracking what has been done and what comes next), a feature checklist (defining the scope of work), and a reference to any startup or initialization script the project needs," with one rule for later sessions: "Mark a feature complete only after end-to-end verification confirms it works, not when the code is written." Do not confuse the memory tool with Managed Agents memory stores. A store is mounted as a directory in the session's sandbox, every change creates an immutable memory version, individual memories are capped at 100 kB (about 25k tokens), and "A store holds a maximum of 10,000 memories." When a store reaches that limit, writes to new memories fail while existing memories stay readable and editable, which is why the docs advise small, purpose-built stores.

Compaction in Claude Code and the Agent SDK

When the window fills, Claude Code "clears older tool outputs first, then summarizes the conversation if needed" (How Claude Code works). What that summary keeps and loses is quoted in Preserving critical information in long conversations; the short rule is that persistent rules belong in CLAUDE.md. Automatic compaction does not end the session. The commands that manage context:

CCDV-F D3.1 lists "Agent Memory" among Claude Code's core components. The closest match in current docs is the subagent memory field (the guide does not define the term), which "gives the subagent a persistent directory that survives across conversations"; it is covered in Subagent housekeeping.

Auto-compaction settings, from Model configuration and Environment variables:

What survives a compaction (Context window):

"If a rule must persist across compaction, drop the paths: frontmatter or move it to the project-root CLAUDE.md" (Context window). Three ways to control what the summary keeps:

1. A compact-instructions section in the CLAUDE.md at the project root, for example (from the costs docs):

   # Compact instructions
   
   When you are using compact, please focus on test output and code changes
   

2. A focus argument: /compact focus on the auth bug fix, run "before starting a long new task" (Context window).

3. A SessionStart hook with the compact matcher, which re-injects critical context after every automatic or manual compaction; Claude Code adds the text the command writes to stdout. The hooks guide's example for .claude/settings.json:

   {
     "hooks": {
       "SessionStart": [
         {
           "matcher": "compact",
           "hooks": [
             {
               "type": "command",
               "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
             }
           ]
         }
       ]
     }
   }
   

Two more hook events bracket compaction (Hooks reference): PreCompact runs before it, matches manual (/compact) or auto, and can block it ("Exit with code 2 to block compaction."; returning JSON with "decision": "block" also works); PostCompact receives compact_summary and has no decision control. Hook mechanics are in Hooks.

Failure mode: if one large file or output refills the window after each summary, "Claude Code stops auto-compacting after a few attempts and shows an error instead of looping" (How Claude Code works). The error begins Autocompact is thrashing: the context refilled to the limit.... Recovery, per the troubleshooting docs: read the file in smaller chunks, run /compact with a focus that drops the large output, move the work to a subagent, or /clear if the earlier conversation is no longer needed.

Cost notes: /compact on a large context is itself a large request, while "When you want a fresh start instead of continuity, /clear costs nothing" (Manage costs effectively). Compaction also invalidates the conversation layer of the prompt cache, "since the next request has a new, shorter history that doesn't share a prefix with the old one" (How Claude Code uses prompt caching).

The Agent SDK runs the same machinery (How the agent loop works). Its context window "does not reset between turns within a session"; near the limit it compacts automatically and emits a system message with subtype: "compact_boundary" (a SystemMessage in Python, an SDKCompactBoundaryMessage in TypeScript). Persistent rules belong in CLAUDE.md, loaded through settingSources, rather than in the initial prompt, "because CLAUDE.md content is re-injected on every request." The compactor reads CLAUDE.md, and "The compactor matches on intent, so the section header is free-form":

# 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 them

A PreCompact hook in the SDK receives trigger (manual or auto) and is the place to archive the full transcript before it is summarized; like every hook it runs in your process and costs no context (Where the tokens go). To compact on demand from the SDK, send /compact as the prompt string; commands sent this way are ordinary SDK inputs.

Long-running agents: notes, resets and harness files

Anthropic's Effective harnesses for long-running agents frames the core problem: "The core challenge of long-running agents is that they must work in discrete sessions, and each new session begins with no memory of what came before." Compaction alone was not enough; even Opus 4.5 on the Agent SDK "will fall short of building a production-quality web app if it’s only given a high-level prompt". Two failure modes: running out of context mid-feature, "leaving the next session to start with a feature half-implemented and undocumented", and a later instance that would "look around, see that progress had been made, and declare the job done."

The fix was structured note-taking in files the next session reads first:

{
  "category": "functional",
  "description": "New chat button creates a fresh conversation",
  "steps": [
    "Navigate to main interface",
    "Click the 'New Chat' button",
    "Verify a new conversation is created",
    "Check that chat area shows welcome state",
    "Verify conversation appears in sidebar"
  ],
  "passes": false
}

In the harness post, each coding session starts the same way: run pwd to see the working directory, "Read the git logs and progress files to get up to speed on what was recently worked on," then read the feature list and take the highest-priority unfinished feature, one at a time, committing with descriptive messages. The post also has the agent run a basic end-to-end test before implementing a new feature, and reports that, absent explicit prompting, Claude tended to mark a feature as complete without proper end-to-end testing. Anthropic's prompting guide generalizes the pattern: "Use the first context window to set up a framework (write tests, create setup scripts), then use future context windows to iterate on a todo-list"; track structured state in JSON (such as tests.json), progress notes as free text, and checkpoints in git ("Git provides a log of what's been done and checkpoints that can be restored."); and tell Claude "It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality."

If your harness compacts context or lets Claude save it to external files, say so in the prompt; "Otherwise, Claude may sometimes naturally try to wrap up work as it approaches the context limit." The prompting guide's example prompt:

Your context window will be automatically compacted as it approaches its limit, allowing
you to continue working indefinitely from where you left off. Therefore, do not stop
tasks early due to token budget concerns. As you approach your token budget limit, save
your current progress and state to memory before the context window refreshes. Always be
as persistent and autonomous as possible and complete tasks fully, even if the end of
your budget is approaching. Never artificially stop any task early regardless of the
context remaining.

Guidance for unattended runs on current models (as of September 2026): on Opus 5.5 (Prompting Claude Opus 5.5), "Treat a text-only end of turn as a report rather than as proof the task is done," and stop after two or three automatic continuations on the same task; on Fable 5 (Prompting Claude Fable 5), "Before reporting progress, audit each claim against a tool result from this session." On Fable 5.1 (Prompting Claude Fable 5.1), cheaper cache reads mean "compacting early to save cost may no longer be the right cost-intelligence tradeoff on Claude Fable 5.1, so experiment with later compaction points."

Restart, summarize or persist

The Associate exam asks the same question for everyday use: "Understand and manage context limitations and memory considerations (when to restart, summarize, or persist)" (CCAO-F D3.4). Claude Academy's How context affects Claude's performance and cost draws the line: "Compaction is how Claude can continue a single conversation beyond the context limit. Written memory is how Claude keeps important details in context across multiple conversations."

App-specific facts (as of September 2026), from the context window help article: "Code execution must be enabled for automatic context management to work," and "Longer conversations that trigger automatic context management use more of your usage limit." Projects "use retrieval-augmented generation (RAG)", loading only relevant content. From the projects help article: "Context is not shared across chats within a project unless the information is added into the project knowledge base." Each project has its own memory space and summary; memory is on by default on Free, Pro and Max plans, while on Team and Enterprise plans "memory is off by default and can be turned on by an owner" (Use Claude's chat search and memory); incognito chats are not saved to memory or history. The app features are taught in Projects and Memory, styles and personalization; Claude Code's CLAUDE.md and auto memory in CLAUDE.md and the memory hierarchy.

Traps

• Treating compaction as lossless. It is a summary that can drop numbers and exact phrasing (first table above); pin exact facts or write them to memory.
• Avoiding clearing because it loses data. Not if the tool can be called again; Anthropic's engineering post calls tool result clearing "One of the safest lightest touch forms of compaction".
• Expecting a path-scoped rule to survive compaction. It reloads only when a matching file is read again; a rule that must persist belongs in the project-root CLAUDE.md, which is re-injected (the same fix as for early instructions, a trap in Preserving critical information in long conversations).
• Combining compaction and context_management in one call. The API rejects it.
• Keeping key findings only in the conversation. CCAR-F 5.4-K2 and 5.4-S2 answer with a scratchpad file the agent records findings in and refers back to (see Keep a scratchpad file).
• Using a deprecated mechanism in new code. compaction_control is deprecated in the TypeScript and Ruby SDKs and gone from the Python SDK; server-side compaction is the recommended route.

Subagents as context isolation

Tested in: CCAR-F 1.2-K2, 1.3-K1, 1.3-K2, 3.2-K3, 3.2-S2, 3.4-K4, 3.4-S3, 5.4-K3, 5.4-S1, Appendix technology list (Explore subagent, subagent spawning via Task tool) · CCDV-F D6.1 Context Engineering ("context isolation through subagents or multi-step agentic workflows"), D1.1 Agent Architecture (role of subagents), D1.3 Agent Patterns and Frameworks · CCAR-P 1.4, 3.8

A subagent protects the main context window because it spends its own window instead of yours. Anthropic's Effective context engineering for AI agents describes the trade: "Each subagent might explore extensively, using tens of thousands of tokens or more, but returns only a condensed, distilled summary of its work (often 1,000-2,000 tokens)." The multi-agent research system relies on the same effect: subagents "facilitate compression by operating in parallel with their own context windows". CCAR-F 5.4-K3 puts it in exam terms: "Subagent delegation for isolating verbose exploration output while the main agent coordinates high-level understanding".

The shape of one delegation (the file count and token figure are illustrative):

Main conversation (coordinator)                 Subagent (fresh window)
------------------------------                  -----------------------
goal, decisions, key findings                   prompt string from the coordinator
        |                                               |
        |---- Agent tool call: task + context --------->|  reads 40 files, runs grep,
        |                                               |  runs tests, 60k tokens of output
        |<--- final message only (a short summary) -----|
        |
grows by the summary, not the transcript

The mechanics, in one line each (configuration is taught in Subagents in the SDK and Subagents):

• In: "The only content you pass from parent to subagent is the Agent tool's prompt string, so include any file paths, error messages, or decisions the subagent needs directly in that prompt" (Subagents in the SDK). A non-fork subagent does not see the parent's conversation history, tool results or system prompt (Agent SDK docs; CCAR-F 1.2-K2 and 1.3-K2 state the conversation-history part).
• Out: per the same page, "intermediate tool calls and results stay inside the subagent; only its final message returns to the parent." The parent "may summarize it in its own response", so ask for verbatim output if you need it.
• Project rules reach most subagents, not all. Per the Claude Code subagents docs, a non-fork Claude Code subagent loads the same CLAUDE.md hierarchy as the main conversation, but the built-in Explore and Plan agents skip CLAUDE.md, and a definition with omitClaudeMd loads only managed policy files (or none). The main conversation still applies its full CLAUDE.md when it reads their results; if a rule must reach one of these subagents (the docs' example is ignoring the vendor/ directory), restate it in the delegation prompt.

Kinds of isolation

What each mechanism starts with and returns (from the Claude Code subagents docs unless a row links another page):

CCAR-F 3.4-K4 and 3.4-S3 name the Explore subagent specifically: it isolates "verbose discovery output" and returns summaries "to preserve main conversation context", and it is the tool "for verbose discovery phases to prevent context window exhaustion during multi-phase tasks." CCAR-F 3.2-K3 describes the skill option in the same terms: context: fork is "for running skills in an isolated sub-agent context, preventing skill outputs from polluting the main conversation", and 3.2-S2 applies it to "skills that produce verbose output (e.g., codebase analysis)". Skill configuration is taught in Agent Skills.

When to isolate and when not to

The Claude Code subagents docs give the split:

Limits on the other side of the ledger:

• Isolation is not free. "Running many subagents that each return detailed results can consume significant context" (Claude Code subagents docs), and multi-agent work multiplies token use; Anthropic's measured multipliers are in Where the tokens go.
• Shared-context work fits badly. Anthropic's multi-agent research post: "some domains that require all agents to share the same context or involve many dependencies between agents are not a good fit for multi-agent systems today."
• Over-delegation. Anthropic's prompting guide says Claude Opus 4.6 "may spawn subagents for code exploration when a direct grep call is faster and sufficient", and the Agent SDK subagent docs note that Claude Opus 5 "delegates to subagents more readily than earlier models". The prompting guide's remedy is explicit guidance in the prompt (below).
• For a question about what is already in context, /btw fits better than a subagent: it sees the full context but has no tool access, and the answer is not added to history.
• For a reusable prompt or workflow that should run in the main conversation, the Claude Code docs point to Skills instead of a subagent.

The prompting guide's sample prompt for excessive subagent use:

Use subagents when tasks can run in parallel, require isolated context, or involve
independent workstreams that don't need to share state. For simple tasks, sequential
operations, single-file edits, or tasks where you need to maintain context across steps,
work directly rather than delegating.

Decide. If the work would flood the main window with output you will not reread (file reads, test logs, search results), isolate it and ask for a bounded summary. If the next step depends on the details the work produces, or the user needs to steer each step, keep it in the main conversation. If the task is a single lookup, run the lookup.

Delegation prompts that keep the return small

CCAR-F 5.4-S1 frames delegation as "Spawning subagents to investigate specific questions (e.g., "find all test files," "trace refund flow dependencies") while the main agent preserves high-level coordination". The Claude Code docs' own examples ask a specific question and request only what the parent needs:

Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

Use a subagent to run the test suite and report only the failing tests with their error messages

What to put in the prompt string (objective, output format, tool guidance, boundaries, complete prior findings) is taught in Multi-agent orchestration; what the return should look like when the parent's budget is tight is in Up: subagent to coordinator.

Isolation for judgment, not only for tokens

A fresh window also removes the author's bias. Claude Code's best practices note that a reviewer running in a fresh subagent context "sees only the diff and the criteria you give it, not the reasoning that produced the change". Anthropic's harness design post found that agents tend to praise their own output, and that "Separating the agent doing the work from the agent judging it proves to be a strong lever to address this issue." Managed Agents applies the same idea to outcome grading: "The grader uses a separate context window to avoid being influenced by the main agent's implementation choices." Multi-pass review design is taught in Multi-instance and multi-pass review.

Subagent housekeeping

From the Claude Code subagents docs:

• Compaction. Subagents "support automatic compaction using the same logic as the main conversation", and their transcripts are stored in separate files, so "when the main conversation compacts, subagent transcripts are unaffected."
• Agent memory. A Claude Code subagent's memory frontmatter field "gives the subagent a persistent directory that survives across conversations": user scope at ~/.claude/agent-memory/<name-of-agent>/, project at .claude/agent-memory/<name-of-agent>/ (shareable via version control), local at .claude/agent-memory-local/<name-of-agent>/; "project is the recommended default scope." It is part of auto memory, so turning auto memory off makes the field have no effect.
• Growth caps (as of September 2026). Nesting defaults to three layers below the main conversation (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH), and spawning fails with Concurrent subagent limit reached once 20 subagents are running (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS; Claude Code v2.1.217 or later, and not enforced in sessions with ultracode active); there is no limit on the total spawned over a session. Configuration is in Subagents.

Traps

• Assuming the subagent can see what the coordinator found. Not unless it is in the prompt string (1.3-K2). Forks are the exception.
• Returning everything so nothing is lost. Verbose returns re-flood the coordinator; ask for summaries or structured findings.
• Delegating every exploration. Quick, targeted lookups and tightly coupled phases belong in the main conversation.
• Reading context: fork as a conversation fork. It runs the skill in an isolated subagent that does not see the history.
• Assuming Explore follows your CLAUDE.md. Explore and Plan skip it; restate any rule they must follow in the delegation prompt.
• Treating "Task" and "Agent" as different tools. They are the same subagent-spawning tool under its old and current names.

Exploring large codebases

Tested in: CCAR-F 5.4 (5.4-K1 to 5.4-S5), 2.5-S4, 1.7-K3, 1.7-K4, 1.7-S3, 1.7-S4, Scenario 2 (Code Generation with Claude Code) and Scenario 4 (Developer Productivity with Claude) · CCDV-F D3.1 Claude Code Operation (session management), D2.5 Claude Application Design (session hygiene) · CCAR-P 7.1, 7.2

CCAR-F Task 5.4 is "Manage context effectively in large codebase exploration". Codebase work fills context quickly: every file read, grep result and test log lands in the window. The guide describes the symptom precisely in 5.4-K1: "Context degradation in extended sessions: models start giving inconsistent answers and referencing "typical patterns" rather than specific classes discovered earlier". When an agent that named a specific class an hour ago starts describing generic patterns instead, that is the degradation the guide describes, and the same drift Claude Code's best practices warn about as the window fills (More tokens, less attention). Our reading, for the reason given in A bigger window is not the fix: the remedy is less and better-organized context, not more.

The CCAR-F guide's five skills for this task form one workflow:

Explore incrementally, not all at once

CCAR-F 2.5-S4: "Building codebase understanding incrementally: starting with Grep to find entry points, then using Read to follow imports and trace flows, rather than reading all files upfront". This is the just-in-time strategy from Up front or just in time applied to code; Anthropic's Effective context engineering for AI agents gives Claude Code's glob and grep retrieval as its example of loading files just in time. Answer exam items with the guide's grep-then-read pattern. Related documented advice includes the common-workflows tip "Start with broad questions, then narrow down to specific areas". The anti-pattern has a name in the best practices, "The infinite exploration": you ask Claude to investigate without scoping it, and "Claude reads hundreds of files, filling the context." The fix: "Scope investigations narrowly or use subagents so the exploration doesn't consume your main context."

Ways to cut the cost of each lookup, from the large codebases docs (as of September 2026):

• Code intelligence. "In a large codebase, finding where a symbol is defined or used can cost many file reads and grep calls." A code intelligence plugin gives Claude "go to definition" and "find references" navigation (Common workflows) through the LSP tool, which stays inactive until such a plugin is installed (and stays inactive in cloud sessions, where plugin language servers are not started).
• An existing index. If your organization runs code search or a RAG index, "expose it as an MCP tool so Claude queries it instead of reading files directly".
• Keep generated and vendored code out. Read deny rules in .claude/settings.json block Claude from opening checked-in generated and vendored files (Claude's content searches respect .gitignore, so gitignored paths such as dist/ and build/ already stay out of content-search results). A Bash search such as grep -r or find over a directory that contains denied files still includes them in its output. The directory patterns end with /**/* rather than /**, so each rule covers everything inside the directory but not the directory itself, and Claude can still list it or change into it:

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)",
      "Read(./**/*.generated.*)",
      "Read(./**/vendor/**/*)"
    ]
  }
}

Monorepo configuration (where to start Claude, layered CLAUDE.md files, worktrees) is taught in Managing context in large codebases.

Keep a scratchpad file

CCAR-F 5.4-K2 names "The role of scratchpad files for persisting key findings across context boundaries". A scratchpad is structured note-taking applied to exploration: the findings live on disk, so compaction or a fresh session cannot blur them. Anthropic's examples include "your custom agent maintaining a NOTES.md file" (Effective context engineering for AI agents), a Managed Agents cookbook system prompt that says "Write notes to /tmp/NOTES.md as you go.", and, in the C compiler project, instructions "to maintain extensive READMEs and progress files that should be updated frequently with the current status." An illustrative scratchpad for a refund-flow investigation:

**Refund flow investigation (scratchpad)**

### Confirmed
- Entry point: api/refunds.py -> RefundService.create() (services/refund_service.py:41)
- RefundService calls PaymentGateway.reverse() only after OrderRepo.lock() succeeds
- Tests: tests/services/test_refund_service.py covers the happy path only

### Open questions
- Where are partial refunds rounded? (not in RefundService; check money/utils.py)

### Next
- Trace PaymentGateway.reverse() error handling

Two habits make scratchpads and logs searchable instead of noisy. From Building a C compiler with a team of parallel Claudes: "The test harness should not print thousands of useless bytes. At most, it should print a few lines of output and log all important information to a file so Claude can find it when needed." And: "if there are errors, Claude should write ERROR and put the reason on the same line so grep will find it."

Delegate, summarize between phases, compact

• Delegate the reading. "Exploring a large codebase fills your context with file reads. Delegate the exploration so only the findings come back" (Common workflows). Isolation mechanics are in Subagents as context isolation.
• Carry phase summaries forward. Before the next wave of subagents, condense what the last wave found and put it in their initial prompts (5.4-S3); the handoff itself is taught in Down: coordinator to subagent.
• Compact with a focus. /compact focus on the auth bug fix style instructions keep what the next step needs (mechanics in Compaction in Claude Code and the Agent SDK); a plan written in plan mode is re-injected after each compaction, "so the plan survives where conversation history may not" (large codebases docs). Use /context to see what is consuming the window.
• Clear between unrelated tasks. The best practices' fix for the "kitchen sink session" is "/clear between unrelated tasks."

A worked sequence for the guide's example question, "trace refund flow dependencies" (illustrative):

1. Plan mode or a read-only start; ask a scoped question, not investigate the payments code.
2. Delegate with a scoped prompt such as Use a subagent to find every caller of RefundService.create and report file paths and line numbers only.
3. Record the returned findings in the scratchpad file.
4. Delegate the next phase with the scratchpad's confirmed findings pasted into the prompt.
5. When /context shows the window filling with discovery output, run /compact with a focus on the confirmed findings and the open questions.
6. Answer later questions from the scratchpad, not from memory of earlier turns.

Resuming after the code changed

Exploration can span several sessions. CCAR-F 1.7-K3 stresses "informing the agent about changes to previously analyzed files when resuming sessions after code modifications", and 1.7-K4 asks "Why starting a new session with a structured summary is more reliable than resuming with stale tool results". In the Agent SDK sessions docs' words, "Sessions persist the conversation, not the filesystem", so a resumed session carries its earlier tool results exactly as they were read. Claude Code's checkpoints do not reliably capture outside edits either: "Manual changes you make to files outside of Claude Code and edits from other concurrent sessions are normally not captured, unless they happen to modify the same files as the current session." Switching branches changes the files Claude sees, "but your conversation history stays the same" (How Claude Code works). The safety net is partial: when Claude edits a file that changed on disk since its last read, the tools reference says "the result notes that the file carries other changes so Claude re-reads it before edits that depend on surrounding content", but that happens only when an edit is attempted, not when Claude reasons from an earlier read. Telling the agent what changed stays your job.

Claude Code builds a version of this choice into resuming (as of September 2026; sessions docs). On a Pro or Max plan, resuming a session that has been inactive for more than about an hour and is over 100,000 tokens opens a dialog: Resume from summary runs /compact immediately and keeps the summary, your most recent exchanges and up to five recently read files, while resuming as-is "keeps every detail of the conversation available, at a per-request cost that scales with the conversation's size." The dialog trades detail against cost; it is not a check for changed files. Our reading: when files changed, still name them (1.7-S4) or start fresh with a summary (1.7-S3).

Session commands (--resume, --fork-session, /rewind) are in Sessions: continue, resume, fork and rewind.

Traps

• Reading everything up front "for completeness". 2.5-S4 rejects it: find entry points first, then follow the flow.
• Trusting the model's memory of turn 5 at turn 80. Degradation shows as generic answers (5.4-K1); reference the scratchpad instead.
• Delegating without the previous phase's findings. The next subagent starts blind (5.4-S3, 1.3-K2).
• Resuming a week-old session after a refactor without saying what changed. Tell the agent, or start fresh with a summary (1.7-K3, 1.7-K4).

Multi-agent handoffs

Tested in: CCAR-F 1.3-K2, 1.3-S1, 1.3-S2, 1.4-K3, 1.4-S3, 1.7-K4, 5.1-S5, 5.1-S6, 5.4-K4, 5.4-S3, 5.4-S4, Appendix in-scope topic "Subagent context management", Exercise 4 steps 1 and 3 · CCDV-F D1.1 Agent Architecture, D1.3 Agent Patterns and Frameworks · CCAR-P 1.4, 1.5

A handoff is any point where work crosses a context boundary: coordinator to subagent, subagent back to coordinator, one phase to the next, one session to the next, a crashed run to its restart, or an agent to a human. The receiver sees only what is handed over, so the question behind each crossing is the same (our framing of the guide objectives below): what must cross, in what shape, and where does it live if the receiver cannot hold it all?

Down: coordinator to subagent

The mechanism and what to write in the delegation prompt are taught in Multi-agent orchestration. The rule in one line: "subagents do not automatically inherit parent context or share memory between invocations" (1.3-K2), so 1.3-S1 asks for "Including complete findings from prior agents directly in the subagent's prompt (e.g., passing web search results and document analysis outputs to the synthesis subagent)". CCAR-F Exercise 4 step 1 asks you to ensure that "each subagent receives its research findings directly in its prompt rather than relying on automatic context inheritance."

Current Agent SDK subagent docs (as of September 2026) agree that the prompt string is the only content passed from parent to subagent, and add one exception the guide does not mention: a fork inherits the parent conversation, while any other subagent's "context window starts fresh, with no parent conversation, but isn't empty." What that fresh window holds, forks, and the renaming of Task to Agent are covered in Subagents as context isolation; on the exam, answer in the guide's terms (context is passed explicitly in the prompt).

Between phases, send the distilled state, not the transcript. 5.4-S3: "Summarizing key findings from one exploration phase before spawning sub-agents for the next phase, injecting summaries into initial context". Anthropic's multi-agent research post lists the same pattern among its tips for long-horizon conversation management: "We implemented patterns where agents summarize completed work phases and store essential information in external memory before proceeding to new tasks." And near the limit: "When context limits approach, agents can spawn fresh subagents with clean contexts while maintaining continuity through careful handoffs."

Up: subagent to coordinator

Two CCAR-F 5.1 skills define the return shape:

• 5.1-S5: "Requiring subagents to include metadata (dates, source locations, methodological context) in structured outputs to support accurate downstream synthesis"
• 5.1-S6: "Modifying upstream agents to return structured data (key facts, citations, relevance scores) instead of verbose content and reasoning chains when downstream agents have limited context budgets"

And 1.3-S2 keeps content and metadata apart: "Using structured data formats to separate content from metadata (source URLs, document names, page numbers) when passing context between agents to preserve attribution". Exercise 4 step 3 names the fields: "each finding should include a claim, evidence excerpt, source URL/document name, and publication date". An illustrative return that meets all three skills and the exercise (field names and values are ours):

{
  "subtask": "EU retail pricing trends, 2025 to 2026",
  "findings": [
    {
      "claim": "Average basket prices rose in 2025.",
      "evidence_excerpt": "verbatim sentence from the source",
      "relevance": 0.9,
      "source": {
        "url": "https://example.org/report.pdf",
        "document_name": "Retail Price Monitor 2025",
        "page": 14,
        "publication_date": "2026-02-10",
        "method": "survey of retailers"
      }
    }
  ],
  "gaps": [{"topic": "2026 Q2 data", "status": "source unavailable", "detail": "statistics portal timed out twice (access failure, not an empty result)"}],
  "conflicts": []
}

The gaps and conflicts fields are there for synthesis: coverage gaps feed the coverage annotations of 5.3-S4, and conflicting values travel annotated rather than resolved, as 5.6-S3 asks. Both are taught in Provenance and uncertainty in synthesis.

Why not return prose? The receiver has its own budget. A coordinator that collects ten verbose reports has recreated the context problem that delegation was meant to solve (our reasoning; Claude Code's subagent docs give the same warning, quoted in When to isolate and when not to). Keep reasoning chains inside the subagent, and send facts, citations and scores up (5.1-S6). How findings then survive synthesis is in Provenance and uncertainty in synthesis; how failures are reported (failure type, attempted query, partial results, alternative approaches) is in Error propagation in multi-agent systems.

By value or by reference

1.3-S1 says to pass complete findings in the prompt. The appendix of Anthropic's multi-agent research post, a list of "additional miscellaneous tips for multi-agent systems", recommends a second channel for some outputs: "Subagents call tools to store their work in external systems, then pass lightweight references back to the coordinator." The post's tip opens with "Subagent output to a filesystem to minimize the ‘game of telephone.’" and says the pattern "prevents information loss during multi-stage processing and reduces token overhead from copying large outputs through conversation history." It names where it fits: "The pattern works particularly well for structured outputs like code, reports, or data visualizations where the subagent's specialized prompt produces better results than filtering through a general coordinator." In Anthropic's three-agent harness (planner, generator, evaluator), the generator and evaluator negotiated each sprint contract through files: "Communication was handled via files: one agent would write a file, another agent would read it and respond either within that file or with a new file that the previous agent would read in turn."

Decide (our rule, built from the sources above). Pass by value (in the prompt) when the receiver needs the content to reason with: findings, decisions, error messages, file paths. Pass by reference (a path or ID plus a short summary) when the output is large or is itself the deliverable, such as code, a report or a data visualization. Either way the receiver gets enough in its prompt to know what the reference contains; a bare path is not a handoff. For exam items about what the synthesis subagent receives, the guide's answer is by value: complete findings directly in its prompt (1.3-S1).

Crash recovery: state exports and a manifest

CCAR-F 5.4-K4: "Structured state persistence for crash recovery: each agent exports state to a known location, and the coordinator loads a manifest on resume". 5.4-S4 completes it: "Designing crash recovery using structured agent state exports (manifests) that the coordinator loads on resume and injects into agent prompts". "Manifest" as a crash-recovery artifact is the guide's term, and none of the posts or docs in this table uses the word in that sense. They describe related ways to keep state outside a single context window or process (product details as of September 2026):

An illustrative manifest (field names are ours):

{
  "run_id": "research-2026-09-23-a",
  "phase": "analysis",
  "agents": [
    {"name": "web_search", "status": "completed", "state_file": "state/web_search.json"},
    {"name": "doc_analysis", "status": "failed", "state_file": "state/doc_analysis.json", "last_error": "timeout"},
    {"name": "synthesis", "status": "not_started"}
  ]
}

On resume the coordinator loads the manifest and injects the exported state into agent prompts, which is what 5.4-S4 describes; skipping completed agents and restarting only the failed one is this example's design, not the guide's wording. (Claude Code workflows replay less selectively: a completed agent returns its saved result only if its prompt and every earlier agent's prompt are unchanged, and a failed agent "runs again, and so does every agent that started after it, even ones that completed.") Keep state files structured, in JSON as Anthropic's long-running harness does, for the reason quoted in Long-running agents. One product caveat: an Agent SDK SessionStore mirrors transcripts only, "not CLAUDE.md memory files or other working-directory artifacts"; the hosting docs say to "Mount a shared volume or sync those separately."

Session to session: resets with a structured handoff

A context reset is a deliberate handoff to a fresh agent. Anthropic's harness design post describes it as clearing the window entirely and starting a fresh agent, "combined with a structured handoff that carries the previous agent's state and the next steps". The trade-off against compaction, and how it changed between model generations, is in the warning in Long-running agents. The price of a reset: "A reset provides a clean slate, at the cost of the handoff artifact having enough state for the next agent to pick up the work cleanly." The same post notes that resets add "orchestration complexity, token overhead, and latency to each harness run."

The exam frames the same choice at the session level: 1.7-K4 prefers a new session with a structured summary over resuming with stale tool results, and the Agent SDK gives matching advice for work that moves between hosts (crash-recovery table above). When to resume and when to start fresh (1.7-S3) is decided in Resuming after the code changed. A good session handoff reads like the harness files (our summary): what is done and verified, what is in progress, what is next, and where the evidence lives. Anthropic's prompting guide gives this example of free-text progress notes:

// Progress notes (progress.txt)
Session 3 progress:
- Fixed authentication token validation
- Updated user model to handle edge cases
- Next: investigate user_management test failures (test #2)
- Note: Do not remove tests as this could lead to missing functionality

Agent to human

A human who takes over an escalation has not seen the transcript. CCAR-F 1.4-K3 asks for "Structured handoff protocols for mid-process escalation that include customer details, root cause analysis, and recommended actions", and 1.4-S3 names the fields: "Compiling structured handoff summaries (customer ID, root cause, refund amount, recommended action) when escalating to human agents who lack access to the conversation transcript". That four-field schema is the guide's own; the closest first-party structure is Anthropic's customer-escalation skill, which packages an issue into "a structured escalation brief for engineering, product, or leadership", with a section for what has been tried ("Any troubleshooting or workarounds attempted") and the rule "Always quantify impact". When to escalate, and how the guide's fields map onto that brief, are in Escalation and ambiguity.

Traps

• Assuming the synthesis agent can look up what the search agent found. It sees only what you pass in its prompt (1.3-K2, Exercise 4 step 1).
• Returning verbose content and reasoning chains to a budget-limited coordinator. 5.1-S6 says return structured data: key facts, citations, relevance scores.
• Flattening metadata into prose. Keep source URLs, document names and page numbers separate from content to preserve attribution (1.3-S2), and include dates and methodological context (5.1-S5).
• Restarting a crashed pipeline from zero. Each agent exports state to a known location, and the coordinator resumes from a manifest (5.4-K4, 5.4-S4).
• Escalating with a pointer to the conversation. The human lacks access to the transcript; send the structured summary (1.4-S3).

Provenance and uncertainty in synthesis

Tested in: CCAR-F 5.6 (5.6-K1 to 5.6-S5), 5.3-S4, 5.5-S4, 1.3-S2, Appendix in-scope topic "Information provenance", Exercise 4 steps 3 to 5, sample question 8, Scenario 3 (Multi-Agent Research System) · CCDV-F D6.3 Output Handling ("skepticism toward confident output") · CCAR-P 4.4 (sample 3), 5.3 · CCAO-F D2.1, D2.3 (sample 1)

CCAR-F Task 5.6 is "Preserve information provenance and handle uncertainty in multi-source synthesis". The failure it guards against is in 5.6-K1: "How source attribution is lost during summarization steps when findings are compressed without preserving claim-source mappings". Every compression step in Multi-agent handoffs is a chance to drop the link between a claim and its evidence; once dropped, it can be rebuilt only by going back to the source documents (our reasoning; that is the job Anthropic gives a separate citations agent, below). The guide's Appendix in-scope topic list names four parts: "Information provenance: claim-source mappings, temporal data handling, conflict annotation, coverage gap reporting".

Rule 1: every claim keeps its source, through every step

5.6-S1: "Requiring subagents to output structured claim-source mappings (source URLs, document names, relevant excerpts) that downstream agents preserve through synthesis". 5.6-K2 adds that the synthesis agent "must preserve and merge" those mappings when combining findings. Exercise 4 asks you to "Verify that the synthesis subagent preserves source attribution when combining findings." The record shape is in Up: subagent to coordinator. Anthropic's open-source research subagent prompt asks for the same bookkeeping at the source: "For important facts, especially numbers and dates:" it says to "Keep track of findings and sources".

Anthropic's multi-agent research system shows one production answer: once enough information is gathered, the system exits the research loop and "passes all findings to a CitationAgent, which processes the documents and research report to identify specific locations for citations." The post points readers to "the open-source prompts in our Cookbook for example prompts from our system", and those prompts (lead agent, citations agent) make the division explicit:

• Lead agent: "Do not include ANY Markdown citations, a separate agent will be responsible for citations."
• Citations agent: "ONLY add citations where the source documents directly support claims in the text"
• Citations agent: "Do NOT modify the <synthesized_text> in any way - keep all content 100% identical, only add citations"

The research system's LLM-judge rubric checked both directions: "factual accuracy (do claims match sources?), citation accuracy (do the cited sources match the claims?)".

API features that carry provenance. The Citations feature returns "the exact passages that support each claim", and "citations are guaranteed to contain valid pointers to the provided documents." search_result blocks let Claude cite your own retrieval results with the source and title you supply. Both are taught in Files, citations and search results. Three constraints matter for pipeline design (the consequences column is our reading):

Rule 2: annotate conflicts; do not pick a winner

5.6-K3: "How to handle conflicting statistics from credible sources: annotating conflicts with source attribution rather than arbitrarily selecting one value". 5.6-S3 sets who decides: "Completing document analysis with conflicting values included and explicitly annotated, letting the coordinator decide how to reconcile before passing to synthesis". Exercise 4 tests it with "two credible sources with different statistics" and checks that synthesis "preserves both values with source attribution rather than arbitrarily selecting one".

Anthropic's own prompts differ from the guide on who reconciles first. The cookbook research subagent reconciles on its own (recency, consistency, source quality) and hands the conflict up only if it cannot: "When encountering conflicting information, prioritize based on recency, consistency with other facts, the quality of the sources used, and use your best judgment and reasoning. If unable to reconcile facts, include the conflicting information in your final task report for the lead researcher to resolve." 5.6-S3, by contrast, has document analysis include and annotate the conflicting values and leave reconciliation to the coordinator. On the exam, a subagent that settles the conflict itself by silently keeping the newer value is the first trap below. The lead agent is told to "Note any discrepancies you observe between sources or issues with the quality of sources." The next line of its prompt has it resolve them: "When encountering conflicting information, prioritize based on recency, consistency with other facts, and use best judgment." So in Anthropic's system the coordinator reconciles whatever reaches it, which is the part that matches 5.6-S3 ("letting the coordinator decide how to reconcile"). For the exam, the synthesis output still keeps both values with source attribution (Exercise 4 step 5). Anthropic's knowledge-synthesis skill (enterprise-search plugin) states the rule flatly: "Always surface conflicts rather than silently picking one version."

An illustrative annotation (field names are ours):

{
  "metric": "2025 market growth",
  "values": [
    {"value": "12%", "source": "Industry Association annual report", "published": "2026-01-15", "method": "member survey"},
    {"value": "8%", "source": "National statistics office release", "published": "2026-03-02", "method": "census of firms"}
  ],
  "conflict": true,
  "possible_explanation": "different methods and populations",
  "status": "unresolved; passed to coordinator"
}

Rule 3: dates prevent false contradictions

5.6-K4: "Temporal data: requiring publication/collection dates in structured outputs to prevent temporal differences from being misinterpreted as contradictions". Two figures a year apart may both be right. 5.6-S4 makes it a subagent requirement: "Requiring subagents to include publication or data collection dates in structured outputs to enable correct temporal interpretation". The required date field is the guide's prescription; no other Anthropic doc, post or prompt cited on this page requires subagents to output one. Anthropic's own material supports the same habit: the cookbook research prompts (subagent, lead agent) inject the current date ("The current date is {{.CurrentDate}}."), the lead agent is told to "Note any temporal or contextual constraints on the question.", the knowledge-synthesis skill's attribution rules say "Include the date or relative time" and it keeps items separate rather than deduplicating them when "Different time periods are represented", and web search results carry page_age, "When the site was last updated" (as of September 2026).

Rule 4: separate the established from the contested

5.6-S2: "Structuring reports with explicit sections distinguishing well-established findings from contested ones, preserving original source characterizations and methodological context". In practice (our reading), "preserving original source characterizations" means a source that said "may" stays "may". The cookbook subagent prompt makes the same demand for speculation (predictions, "could" or "may" language, financial projections): "you should make sure to note this explicitly in the final report, rather than accepting these events as having happened", and asks subagents to "flag these issues when returning your report to the lead researcher rather than blindly presenting all results as established facts."

Rule 5: report coverage gaps

5.3-S4: "Structuring synthesis output with coverage annotations indicating which findings are well-supported versus which topic areas have gaps due to unavailable sources". In Exercise 4 the coordinator must "proceed with partial results and annotate the final output with coverage gaps" after a simulated subagent timeout. This depends on errors arriving as structured context rather than as empty success. In sample question 8 the correct design returns "structured error context to the coordinator including the failure type, the attempted query, any partial results, and potential alternative approaches", and the rationale rejects the empty-result option because it "suppresses the error by marking failure as success, which prevents any recovery and risks incomplete research outputs." Error reporting itself is taught in Error propagation in multi-agent systems.

"Coverage annotation" is the guide's term. Closest product behavior (as of September 2026): Claude Code's bundled /deep-research workflow "votes on each claim, and returns a cited report with claims that didn't survive cross-checking filtered out", and "When the verifier agents can't check a claim, such as after a rate limit or API error, the report lists that claim as unverified instead of counting it as refuted." Unverified and refuted are different statuses. So are no source found and source unavailable: the guide separates "access failures (timeouts needing retry decisions)" from "valid empty results (successful queries with no matches)" (5.3-K2). Anthropic's customer-research skill gives its research brief a "Gaps & Unknowns" section (what could not be confirmed, and what might need verification from a subject matter expert), and Anthropic's legal summarization guide tells Claude to note information that is not explicitly stated as "Not specified".

Rule 6: render each content type in its own form

5.6-S5: "Rendering different content types appropriately in synthesis outputs" (financial data as tables, news as prose, technical findings as structured lists) "rather than converting everything to a uniform format". The pairing of content types with formats is the guide's; the Anthropic sources cited here do not spell it out. Anthropic's cookbook lead agent asks the same underlying question: "Would it need to be a detailed report, a list of entities, an analysis of different perspectives, a visual report, or something else?"

Putting the rules together, an illustrative report skeleton:

### Summary (key findings first, each with source IDs)
### Well-established findings
### Contested findings (both values, sources, dates, methods)
### Coverage gaps (topics with no data, sources that were unavailable)
### Financial data (table)
### Sources (ID, title, URL, publication date)

Uncertainty that should reach a human

When sources contradict each other and the pipeline cannot reconcile them, the decision may not belong to a model at all. CCAR-F 5.5-S4: "Routing extractions with low model confidence or ambiguous/contradictory source documents to human review, prioritizing limited reviewer capacity". Review design (sampling, calibration) is in Human review and confidence calibration.

Be careful with the "low model confidence" half. The guide calls "self-reported confidence scores" "unreliable proxies for actual case complexity" (5.2-K3), and two official rationales reject raw self-rating: CCAR-F sample question 3 ("LLM self-reported confidence is poorly calibrated") and CCAO-F sample 1 ("Self-reported confidence (A, C) is not a reliable accuracy signal"). Two other objectives route on confidence, and only one says how to calibrate: 4.6-S3 has the model self-report confidence "alongside each finding to enable calibrated review routing", while 5.5-S3 calibrates first: "Having models output field-level confidence scores, then calibrating review thresholds using labeled validation sets". The consistent reading (ours): confidence is a routing signal only after it has been checked against labeled outcomes for your task, and it never replaces checking claims against sources.

Prompt-level techniques that keep synthesis honest, from Anthropic's Reduce hallucinations page:

• "Explicitly give Claude permission to admit uncertainty."
• For long documents (over 20k tokens), extract word-for-word quotes first, then do the task.
• Verify with citations: find a supporting quote for each claim; "If it can't find a quote, it must retract the claim."
• "Explicitly instruct Claude to only use information from provided documents and not its general knowledge."

For research-style work the prompting guide adds "Ask Claude to verify information across multiple sources.", and its sample prompt for complex research asks Claude to "develop several competing hypotheses" and "Track your confidence levels in your progress notes to improve calibration." More in Reducing hallucinations.

Bad sources produce confident errors too. The Architect, Professional exam's sample 3 (tagged to Domain 4; in our mapping it exercises objective 4.4, "Diagnose system issues (prompt failure, hallucinations, model mismatch)") describes a RAG system that "suddenly returns confident but incorrect answers after a document refresh"; the answer points to "retrieval feeding the model poor context, for example a broken re-index or mismatched embeddings."

For business users (CCAO-F). The same discipline applies in the Claude apps: "Evaluate Claude-generated outputs for accuracy and completeness" (D2.1) and "Apply fact-checking and validation techniques" (D2.3). The Associate exam's sample 1 tests it: Claude produces a confident summary of a new regulation that cites a specific subsection number, and the answer is "Verify the cited subsection against the official regulation text before sharing." The rationale: "Language models can fabricate specific-looking details such as citation numbers, a hallucination." Claude Academy's tutorial Why do AI models hallucinate? gives a practical check: "If you have an answer you're unsure about, start a new chat and ask the AI to find errors in the answer, and to confirm that the sources support the statements." See Verifying Claude's output.

Traps

• Silently keeping one of two conflicting values (the newest, or the one from the more official-looking source). 5.6-K3 and 5.6-S3: include both, annotate them with their sources, and let the coordinator decide how to reconcile.
• Treating a year-apart difference as a contradiction. Require publication or collection dates (5.6-K4, 5.6-S4).
• A polished summary with the sources stripped out. This is how attribution is lost (5.6-K1); keep claim-source mappings through every step (5.6-S1).
• Returning an empty result as success when a source failed. Sample question 8's rationale: it "prevents any recovery and risks incomplete research outputs", and the gap never reaches the coverage annotations (5.3-S4).
• Trusting a confident answer or a high self-rating. Self-reported confidence "is not a reliable accuracy signal" (CCAO-F sample 1) and is an unreliable proxy for case complexity (5.2-K3); verify claims against sources.
• Converting every content type to one format. 5.6-S5 rejects a uniform format.

Exam map

Which objective of which exam each section serves, taken from the four exam guides (each Version 1.0, effective July 2026); the section-to-objective mapping is ours. The CCAR-F guide numbers its task statements (5.1 is "Task Statement 5.1") but not the bullets under them, so in IDs such as 5.1-K3 the suffix is our numbering: the third "Knowledge of" bullet (S for "Skills in"), counted in the order the guide prints them. The CCDV-F guide lists its skills as unnumbered headings under each domain, and the CCAR-P and CCAO-F guides list their objectives as unnumbered bullets, so IDs such as D6.1, 2.4 and D3.4 are also our numbering, in printed order. Appendix topics and exercises are named as the CCAR-F guide names them.

The objectives referenced above, by exam:

CCAR-F Domain 5, "Context Management & Reliability", carries 15% of that exam; its other task statements are taught mainly on the reliability page: 5.2 in Escalation and ambiguity, 5.3 in Error propagation in multi-agent systems and 5.5 in Human review and confidence calibration. CCDV-F's Context Engineering skill sits in Domain 6, "Prompt and Context Engineering" (11.0%). CCAR-P objective 2.4 sits in Domain 2, "Claude Models, Prompting & Context Engineering" (13%), and 3.8 in Domain 3, "Integration" (19%). CCAO-F D3.4 sits in Domain 3, "Product and Model Selection" (12%).