On its own, Claude answers one request with one response. To act, such as looking up an order, it needs tools : functions in your code that you describe to Claude in the request. Claude does not run a tool you define. When it needs one, its response asks for the call, and your code runs the function and sends the result back. An agent is Claude, its tools and the code that keeps this exchange going.

That code is the agentic loop , the core execution cycle behind every Claude-based agent. It is deterministic control flow, defined in code, not a prompt trick, a retry loop or a chatbot turn. Your code sends a request, runs any tools Claude asks for, and sends the results back until Claude has finished. The stop_reason field in each response says whether to go round again. The other Domain 1 lessons, on orchestration, subagents, hooks and sessions, all build on this loop.

A glazier runs an agent that answers customer messages. When a customer asks for their fitting date, the agent must look up the order and check the fitting diary before it replies. An agent with a broken loop stops halfway through a task like this in production.

The loop has four steps, repeated until Claude has finished.

The glazier's agent gets "tool_use" for the order lookup and again for the diary check, then "end_turn" with the reply.

Step 3 is where loops break. Tool results must be appended to the conversation history. Otherwise the model never sees what the tool returned, so it has nothing new to reason about on the next iteration. The glazier's order details would never reach Claude.

Key Concept

The stop_reason field is the only reliable signal for loop control. It is deterministic and unambiguous. Never use natural language parsing, text content checks, or arbitrary iteration caps as your primary stopping mechanism.

In an agentic loop, Claude decides which tool to call from the current context. This is model-driven decision-making: the model reads the task, weighs the available tools and picks one. In a pre-configured decision tree or fixed tool sequence, the developer hard-codes which tool runs when.

Model-driven approaches flex. Claude adapts to situations the developer never mapped out, handles edge cases, and chains tools in orders nobody planned. A glazier's customer might ask about a cracked pane and a late fitting in one message.

The exception is business logic that demands deterministic compliance, such as financial operations, security checks and regulatory requirements. There, programmatic enforcement overrides that flexibility, so the glazier's refund rules sit in code. Task Statement 1.4 covers this.

Three anti-patterns recur for loop termination.

Anti-Pattern 1: Parsing natural language signals. The code checks whether Claude said "I'm done" or "task complete". Natural language is ambiguous. Claude might say "I've finished analysing the first file" while intending to continue with more files. stop_reason exists to remove that ambiguity.

Anti-Pattern 2: Arbitrary iteration caps as the primary stopping mechanism. The code stops after a fixed count, such as 10 loops. If a task needs 12 iterations, the cap cuts off useful work. If it finishes in 3, the cap runs unnecessary iterations. The model signals completion through stop_reason , so use that. A cap is acceptable as a safety net against runaway agents, never as the primary control.

Anti-Pattern 3: Checking for assistant text content as a completion indicator. The code uses response.content[0].type == "text" to decide the loop is finished. Claude can return text alongside tool_use blocks, such as "I'll now search for the customer's order history" followed by a tool call. Text presence does not tell you whether the agent is finished.

The glazier's agent works for simple queries but sometimes stops mid-task on complex ones. Its code checks if response.content[0].type == "text" to determine completion. Claude returns "Let me look up your order" alongside a tool_use block for lookup_order . The code sees text in position [0], concludes the agent is finished and returns the incomplete response.

The fix is to check stop_reason instead of the content type: continue on "tool_use" , terminate on "end_turn" . That works whatever content types the response holds.

Get this lifecycle right and most of Domain 1 falls into place. The keyed answer continues on "tool_use" , terminates on "end_turn" , and rejects all three anti-patterns. The exam favours model-driven tool selection because it flexes, except where deterministic compliance calls for programmatic enforcement.

Common Exam Distractor

The exam frequently presents iteration caps as a fix for premature termination. Reject these answers. Caps address runaway loops, not premature exits. The fix is always to check stop_reason correctly.

Current state: beyond the two exam values

The exam guide (v1.0) keys tool_use and end_turn , the two values a basic loop branches on. Current state (checked 6 October 2026): the Messages API also returns pause_turn , max_tokens , stop_sequence , refusal and model_context_window_exceeded , and a production loop must handle them. pause_turn means continue a long-running server-tool turn. refusal means Claude declined to respond; it is a normal HTTP 200 response, not an error. model_context_window_exceeded means the response filled the model's context window; handle it like max_tokens truncation. Treat any value other than end_turn as "not finished, check why" rather than assuming tool_use . Source: the Messages API stop-reason docs.

Multi-agent orchestration is several Claude agents working together on one complex task. A coordinator agent receives the task and splits it up. Subagents each handle one specialised task, such as web search, document analysis, synthesis or report generation. In the hub-and-spoke pattern, the coordinator is the hub and the subagents are the spokes. The coordinator's split of a task into subtopics is its decomposition .

A skip hire firm wants a report on what drives its costs. Its system has a coordinator and the four subagents above.

The coordinator receives the initial task and decomposes it. It decides which subagents to invoke and passes context to them. It aggregates their results, handles errors, and routes information between them. Each subagent receives instructions from the coordinator and returns results to it.

All communication flows through the coordinator. Subagents never communicate directly with each other, whether for efficiency, convenience or any other reason. The skip hire firm's web search subagent returns its findings to the coordinator, never straight to synthesis.

One hub gives three things that a direct message would bypass.

Key Concept

Routing all inter-subagent communication through the coordinator is the foundational architectural constraint of hub-and-spoke orchestration.

Isolation is the most misunderstood idea in multi-agent systems. Subagents do not automatically inherit the coordinator's conversation history. A new subagent starts with only what the coordinator explicitly includes in its prompt. It has no access to:

Subagents also do not share memory between invocations. If the coordinator calls the web search subagent twice, the second invocation knows nothing of the first.

So every piece of information a subagent needs goes in its prompt, explicitly. There is no shared store to look things up in. The skip hire firm's synthesis subagent needs the web search results, so the coordinator puts them in the synthesis prompt.

Exam Trap

When a multi-agent system produces incomplete or incorrect output, trace the failure to its origin. Check whether the coordinator gave the producing subagent the right input before blaming it.

The coordinator has four responsibilities.

1. Dynamic subagent selection. The coordinator analyses what a query requires and selects only the subagents it needs. A simple factual question might need only web search, not the full research-analysis-synthesis chain. Routing every query through every subagent wastes time and resources. If the owner asks for the landfill site's opening hours, the coordinator calls web search alone.

2. Research scope partitioning. The coordinator partitions the research scope to minimise duplication. It assigns each agent distinct subtopics or source types, such as academic papers for one and news articles for another. No two agents search the same sources. For the cost report, one subagent searches fuel price news while another analyses the firm's invoices.

3. Iterative refinement loops. The coordinator evaluates the synthesis output for gaps. If it is incomplete, the coordinator re-delegates to the search and analysis subagents with targeted queries. It re-invokes synthesis and repeats the cycle until coverage is sufficient. If the first draft has no tyre costs, the coordinator sends a targeted search for them and runs synthesis again.

4. Centralised communication routing. All subagent communication routes through the coordinator for observability, consistent error handling and controlled information flow.

Overly narrow task decomposition by the coordinator leads to incomplete coverage of broad research topics. Each subagent researches only what it is assigned. A subtopic nobody is assigned never gets researched.

The skip hire firm's coordinator splits "what drives our costs?" into fuel and lorry maintenance. Web search searches thoroughly for what it was assigned. Synthesis synthesises everything it receives. The report says nothing about landfill gate fees, staff wages or insurance, which no subagent was asked about.

When subagents execute their assigned tasks correctly but coverage is missing, the root cause is what the coordinator assigned them. The fault sits in the coordinator's decomposition, not any downstream agent. So when a report misses entire categories, check the decomposition before blaming the subagents. If output is incomplete in scope (not depth), the decomposition is almost always the root cause.

The fix is a decomposition that covers the full breadth of the topic. Better search queries would not fix it, and nor would a more capable synthesis agent. More subagents would receive equally narrow assignments.

The exam tests one orchestration pattern: hub-and-spoke, with a coordinator at the centre. It tests all four coordinator responsibilities. Direct subagent-to-subagent communication is the wrong answer, even when offered as an efficiency gain. The exam leans hard on the isolation confusion.

The exam guide's sample set includes a question (Question 7) where a coordinator decomposes "impact of AI on creative industries" into only visual arts subtopics. It misses music, writing and film entirely. The root cause is the coordinator's task decomposition. The exam expects you to trace the failure to its origin, not blame the subagents.

Current state

Checked 6 October 2026: in Claude Code a sub-agent can itself spawn sub-agents, up to three layers below the main conversation. So the strict "never" rule is an exam simplification rather than a hard product limit.

A coordinator is the agent that runs a multi-agent task and hands parts of it to subagents . Invocation is how it starts a subagent. Context passing is how it gives that subagent the information it needs. Task Statement 1.3 covers these mechanics: if 1.2 taught you the architecture, 1.3 teaches you the wiring.

Take a landscaping firm that drafts planting proposals for clients with a multi-agent system. Its coordinator spawns three subagents. A web search subagent finds plant and supplier information online and returns results with URLs and titles. A document analysis subagent reads the firm's supplier catalogues and returns analysis with page references. A synthesis subagent writes the proposal from both, and every claim in it should name its source.

The Task tool is how a coordinator spawns subagents. It is the API mechanism that makes multi-agent orchestration work in the Claude Agent SDK, so it is more than a naming convention. Current state (checked 6 October 2026): Claude Code renamed it Agent in v2.1.63. The name Task still works as an alias, and the Agent SDK emits Agent in tool-use blocks.

The coordinator's allowedTools must include "Task" (or "Agent" , its name in Claude Code since v2.1.63). This is a binary gate. With neither name on the list, the coordinator has no way to invoke subagents at all. The firm's coordinator could hold three well-defined subagents and start none of them.

Key Concept

Without "Task" (or "Agent" ) in its allowedTools , the coordinator cannot invoke any subagent, however the subagents are defined.

Each subagent is defined by an AgentDefinition , which specifies three things:

At the firm, the web search subagent's description says it finds plant and supplier information online. Its tools are limited to search, which is its whole role.

Subagents have isolated context, the principle from 1.2. A subagent receives only what the coordinator writes into its prompt. It does not see the coordinator's history or another subagent's output. Most multi-agent systems fall over here. Three rules follow.

Rule 1: Include complete findings from prior agents. A synthesis subagent cannot look up earlier results, because its prompt is its only input. If it needs web search results and document analysis output, the coordinator must pass both in full. At the firm, both go into the synthesis subagent's prompt.

Rule 2: Use structured data that separates content from metadata. Content is the claim, the fact or the analysis. Metadata says where it came from: source URL, document name, page number. A downstream agent can attribute a claim to a source only if that metadata travels with it. When a coordinator compresses findings for the next agent and drops the link between each claim and its source, the attribution is lost.

Rule 3: Specify goals, not procedures. A coordinator prompt should tell a subagent what to achieve and which quality criteria to meet, not give step-by-step instructions. A fixed procedure leaves the subagent no way to adjust its approach when it meets something unexpected. A goal lets it adapt. The firm's coordinator asks the web search subagent for suppliers on the planting list, each with a URL. It names no sites, so the subagent can look elsewhere when one site has nothing useful.

A practical format keeps content and metadata in separate fields, as in this example:

{ "findings" : [ { "claim" : "Solar panel efficiency has increased 25% in the last decade" , "source_url" : "https://example.com/solar-report" , "document_name" : "Annual Solar Industry Report 2024" , "page_number" : 14 , "confidence" : "high" , "retrieved_by" : "web_search_agent" } ] } Each finding carries its source attribution as metadata. A synthesis agent that receives findings in this shape has everything it needs to produce a properly cited report.

At the firm, both research subagents return well-sourced work: URLs and titles from web search, page references from the catalogue analysis. The coordinator passes the content of both to the synthesis subagent but strips the metadata: no source URLs, document names or page numbers. The synthesis subagent writes an excellent proposal with no source attribution.

Changing the synthesis subagent's prompt does not fix this, because it cannot cite sources it does not have. The coordinator must pass structured metadata alongside the content, keeping the source URL, document name and page number for every finding.

When a coordinator needs several subagents for independent tasks, it should emit multiple Task tool calls in a single response . Sequential spawning means one subagent per coordinator turn. The second subagent cannot start until the first has returned and the coordinator takes another turn. When the tasks are independent, that wait adds latency for nothing. The firm's web search and catalogue analysis do not depend on each other, so the coordinator spawns both in one response.

Key Concept

Spawn independent subagents in parallel by emitting multiple Task tool calls in a single coordinator response. This reduces latency compared to sequential invocation across separate turns.

fork_session creates independent branches from a shared analysis baseline . After an initial analysis, such as reading a codebase or understanding a problem, a coordinator can fork the session to explore divergent approaches. After the branching point, each fork works independently. Neither sees the other's results, and changes in one do not affect the other. A coordinator might fork after analysing a codebase to compare two testing strategies. The firm's coordinator forks after analysing a client's site survey to compare two planting plans.

Both are Claude Code session controls. --resume is a CLI flag, with a matching resume option in the Agent SDK. fork_session is the SDK option ( forkSession in TypeScript), and it is also on the CLI as --fork-session next to --resume .

fork_session is not the same as --resume. Resume continues a specific named session. Fork creates a new independent branch. Use fork for divergent exploration from a shared starting point, and resume to continue the same line of investigation, as the firm does to carry on with one proposal.

Exam guide v1.0 uses the name Task tool, so answer "Task tool" even where current code shows Agent . Exam guide v1.0 states the allowedTools rule as above, and that is the keyed answer.

One stem: a synthesis agent's report has unsourced claims, while the web search and document analysis subagents work correctly. The coordinator passed content without structured metadata, so the synthesis agent had no source information to include.

Exam Trap

When a synthesis agent produces unsourced claims, the exam expects you to identify the context passing failure: missing structured metadata. Do not blame the synthesis agent's prompt or propose giving it direct tool access.

The exam tests latency awareness. For independent subagent tasks, the correct answer involves parallel spawning. Options that mention "in a single response" or "simultaneously" signal it.

It also tests fork against resume. Exam guide v1.0 lists --resume and fork_session as two session controls, and that is how the exam frames them. Answer that way: resume to continue a session, fork to branch from it.

Current state

Current state (checked 6 October 2026): the Agent SDK docs describe allowedTools as an auto-approve list. Leaving Agent off it does not remove the tool. Every spawn goes through the permission callback instead, which denies it in an unattended run. Same outcome on the exam, different mechanism in production.

Current state

Current state (checked 6 October 2026): in the Agent SDK ( sessions guide ), fork is a modifier on resume, not an alternative to it. You pass both: ClaudeAgentOptions(resume=session_id, fork_session=True) . resume names the session to start from, and fork_session says to branch off it instead of appending to it. Leave fork_session off and the same call appends to the original. The CLI pairs them the same way: --fork-session only does anything alongside --resume or --continue . So the distinction is append versus branch, not one flag versus the other.

Some agent workflows have steps that must run in a set order. Prompt-based guidance sets that order with a system prompt instruction, such as "Always verify the customer's identity before processing a refund". Programmatic enforcement sets it in code: hooks, prerequisite gates or code-level checks that physically block downstream tools until their prerequisites complete. A prerequisite gate is a programmatic check that blocks a tool from executing until a prior condition is met. Task Statement 1.4 draws a hard line between the two.

Take a tree surgeon whose agent answers client enquiries and books work. Before it books a fell, it must check whether the tree is protected. Before it refunds a deposit, it must confirm the client's identity. It also lays out quote emails, where a slip costs nothing.

A prompt instruction works most of the time, perhaps in 90-95% of cases. It still has a non-zero failure rate, because the model is probabilistic. Sometimes it skips steps, reorders them or reads the instruction loosely. A stronger system prompt, firmer instructions and few-shot examples all improve accuracy. None of them gives a deterministic guarantee. For low-stakes operations, that failure rate is fine.

A gate works every time. It is code, not a prompt instruction, so it is deterministic. Whatever the model decides, the gate prevents the wrong execution order. Told by prompt to check protection first, the tree surgeon's agent could still skip it on the odd job. A gate on the booking tool cannot be skipped.

The choice depends on what a single failure costs.

For the tree surgeon, the deposit refund is financial, the identity check is security and the protection check is compliance. All three get gates. Quote layout is low stakes, so a prompt instruction is enough.

Key Concept

Prompt-based guidance is probabilistic. Programmatic enforcement is deterministic. The decision rule: if a single failure would cause financial loss, a security breach or a compliance violation, use programmatic enforcement.

Consider an agent with get_customer , lookup_order and process_refund tools. A gate on process_refund works like this.

The model cannot bypass the gate by deciding to skip verification. Even a direct call to process_refund is blocked, and the error forces the model to verify identity first.

Production data on such an agent shows it processing refunds without verifying account ownership in 8% of cases. Its system prompt instructs: "Always verify the customer's identity before processing any refund." The prompt works 92% of the time and fails 8% of the time. That 8% has already resulted in refunds processed on wrong accounts. This is a financial operation with real monetary consequences.

The fix is the programmatic prerequisite gate above. It eliminates the 8% failure rate entirely, without improving the prompt at all, by physically preventing the incorrect execution order.

The tree surgeon's booking tool works the same way. With no protection check result for the session, it returns an error naming the check. The agent runs it, then retries.

The Claude Agent SDK provides lifecycle hook events for subagent management. They complement the PreToolUse and PostToolUse hooks covered in Task Statement 1.5. They are useful background rather than tested material. Say the tree surgeon's coordinator spawns a quote-drafting subagent.

SubagentStart fires when a subagent is spawned via the Task tool (renamed Agent in Claude Code v2.1.63). It receives the subagent's type and id, and it cannot block the spawn. It can add context. Return additionalContext in its JSON output, and that string is placed in the subagent's context before its first prompt. This is the documented way to hand a freshly spawned subagent a standing instruction. To enforce rules on spawning itself, such as rate limits or checking that the coordinator passed required context, attach a PreToolUse hook to the Agent tool. That hook can deny or rewrite the outgoing invocation before the subagent starts.

SubagentStop fires when a subagent finishes execution and returns its results to the coordinator. It receives the subagent's id and final message, so it can validate output and log completion for performance monitoring. Validation can fail, say because the output does not conform to the expected schema. The hook then exits with code 2, which keeps the subagent from stopping and sends it back to work. Exit code 2, or a top-level decision: "block" with a reason , keeps the subagent running. A quote draft missing a required field would go back to its subagent.

SubagentStop does not transform the returned output. The hooks reference documents no field on any event that rewrites a tool result in place. The coordinator reshapes output after the fact.

Both are configured like any other hook event, in settings.json or a subagent's frontmatter:

{ "hooks" : { "SubagentStart" : [ { "hooks" : [{ "type" : "command" , "command" : "echo \" subagent started $(date) \" >> .claude/spawns.log" }] } ], "SubagentStop" : [ { "hooks" : [{ "type" : "command" , "command" : ".claude/hooks/validate-subagent-output.sh" }] } ] } } The first script only appends a line. To add context instead, print JSON with an additionalContext field. The second reads the result on stdin and exits 2 if the schema check fails, one of SubagentStop's two levers.

Subagents can also define their own hooks in their frontmatter. All hook events are supported there, including PreToolUse and PostToolUse. They are scoped to the component's lifetime, so they only intercept tool calls made by that subagent, not the coordinator or other subagents. This enables per-subagent policy enforcement. A billing subagent might have a PreToolUse hook that blocks refunds above a threshold, while a technical support subagent has no such restriction.

Stop hooks in a subagent's frontmatter are automatically converted to SubagentStop events, because SubagentStop is the event that fires when a subagent completes. You can therefore define cleanup or validation logic in the subagent's own configuration and rely on it running at completion.

Key Concept

SubagentStart observes spawning, can add context and cannot block. SubagentStop gates completion with exit code 2. Neither rewrites subagent output. Subagents can define hooks in their own frontmatter, scoped to their execution, and Stop hooks there auto-convert to SubagentStop.

Customers often put several issues in one request, such as "I want to return my order, update my shipping address, and ask about my loyalty points". Handle it in three steps.

Handling the items sequentially in separate conversations is wrong. So is addressing only the first item and forgetting the rest. A tree surgeon's client might ask to move a felling date, query an invoice and check on stump grinding. The agent splits out the three, checks each against the client's account and sends one reply.

When an agent cannot resolve an issue and must escalate to a human agent, the handoff must follow a structured protocol. The human agent does not have access to the conversation transcript. They cannot scroll through the chat history. The handoff summary is the only information they receive, so it must be self-contained. It must include these fields.

If the summary is incomplete, the human agent must ask the customer to repeat everything, which is a poor experience. When the tree surgeon's agent cannot settle a disputed charge, its handoff carries all five fields, including the exact refund figure.

The exam tests the enforcement distinction repeatedly, with one decision rule across multiple scenarios. Getting it wrong on high-stakes scenarios will cost you marks. When the scenario involves money, security or compliance, the answer is always programmatic enforcement.

Exam Trap

The exam consistently presents "add stronger instructions to the system prompt" or "include few-shot examples showing the correct workflow" as distractors for high-stakes scenarios. Reject them. They improve probability but do not eliminate the failure rate. For financial, security, and compliance operations, only programmatic enforcement is correct.

The exam also tests how agents should handle compound requests.

Beyond the guide

Task Statement 1.4 covers programmatic enforcement, prerequisite gates and structured handoff. The guide's appendix scopes Agent SDK hooks to PostToolUse and tool-call interception. The subagent lifecycle events above are background reading, not exam content. Verified against the hooks reference on 16 September 2026.

An Agent SDK hook is code that intercepts a tool call or a tool result. A tool call is the model's request to run a tool; the tool result is what comes back. The model's choices are probabilistic. A hook is deterministic: it applies the same rule every time, inside an otherwise probabilistic system. Hooks sit at the boundary between the model's decisions and the real world, where they enforce business rules and normalise data. They build the programmatic side of the enforcement spectrum from 1.4.

Take a furniture shop whose support agent looks up customers, tracks deliveries, issues refunds and approves discounts. Some of its rules must hold every time. Its data arrives from three systems in three different shapes.

The Agent SDK provides hooks at two points in the tool execution lifecycle. A PostToolUse hook runs after a tool executes and before the model processes the result. It can transform the result, so the model receives clean, normalised data whichever tool produced it. A PreToolUse hook, sometimes described as tool-call interception, runs before a tool executes. It can block the outgoing call, modify it, or redirect it to an alternative workflow. A blocked tool never runs.

In the Agent SDK hooks guide (checked September 2026), a PreToolUse hook answers with a permissionDecision of allow , deny , ask or defer , and deny stops the tool call. An optional updatedInput rewrites the tool's arguments before it runs. A PostToolUse hook can set updatedToolOutput to replace what the model sees, for built-in and MCP tools alike. The older updatedMCPToolOutput covered MCP tools only; the docs say to prefer updatedToolOutput . By the time PostToolUse fires, the tool has already run. Blocking there stops the loop but does not undo the side effect. On the furniture shop's refund tool, it would fire after the money had gone.

Key Concept

PostToolUse hooks transform data after execution. PreToolUse hooks enforce policy before execution.

Different MCP tools return data in different formats. The furniture shop's agent uses three:

Without normalisation, the model interprets these mixed formats afresh on every iteration, so its readings vary. It might parse a Unix timestamp correctly once and misread it the next time. It might swap the day and month in "DD/MM/YYYY", or read "P" as "processed" instead of "pending".

A PostToolUse hook converts every result before the model processes it.

The interpretation errors then disappear entirely.

PreToolUse hooks implement the prerequisite gates described in 1.4. The hook checks an outgoing call against a business rule before the tool executes. A call that breaks the rule is blocked, so there is no side effect to undo.

Refund threshold. A hook intercepts all calls to process_refund . If the amount exceeds $500, it blocks the call and redirects to a human escalation workflow, and the refund tool never executes. At the furniture shop, a $900 refund on a returned dining table goes to staff.

Compliance prerequisite gate. A hook intercepts calls to transfer_funds . If the required anti-money laundering (AML) check has not been completed for this session, the hook blocks the call. Its error message directs the agent to complete the AML check first.

Manager approval. A hook intercepts calls to approve_discount for discounts above 20%. It pauses execution and routes the request to a manager approval queue. The tool executes only after a manager approves, so a 25% discount on a sofa waits for the shop manager.

Exam Trap

PostToolUse runs after execution, when the non-compliant action has already occurred, so it cannot stop that action. Use a PreToolUse hook to block an action before it happens.

If a single failure would lose the business money or expose it to legal risk, use a hook. For a formatting preference or style guideline, prompt-based guidance is fine. A prompt is probabilistic, so even a good one sometimes fails. The question is whether the consequence of one failure justifies a deterministic guarantee, not whether prompts are "good enough".

Refunds above $500. A prompt can say "For refunds above $500, escalate to a human agent". It works most of the time, but a single failure means a large refund processed without approval. The process_refund hook above blocks it 100% of the time.

International transfers must pass AML checks. A prompt can say "Always complete AML verification before processing international transfers". It works 95% of the time. The 5% failure rate means some transfers skip AML checks, which is a regulatory violation. A PreToolUse hook that blocks transfer_funds until aml_check returns a pass works 100% of the time. No transfer can execute without AML verification.

Markdown formatting. A prompt can say "Format all responses using markdown with headers and bullet points". It works most of the time, and an occasional plain-text reply to a furniture shop customer is not a business risk. A hook would be unnecessary overhead, because formatting preferences do not need deterministic enforcement.

The exam tests which direction each hook runs in. It presents PostToolUse hooks as a way to block policy-violating actions, which is wrong because the action has already happened. It also consistently offers prompt-based solutions as distractors for scenarios that need deterministic enforcement. For a 100% requirement, the keyed answer is a hook.

Beyond the guide

The guide scopes Task Statement 1.5 to PreToolUse and PostToolUse. Claude Code fires hooks at other points too, and the practice questions cover one of them, PreCompact. (Checked against the hooks reference, 16 September 2026.)

The same hook mechanism covers session events, not only tool calls. PreCompact runs immediately before Claude Code compacts the conversation, whether the user typed /compact (matcher manual ) or the context reached the auto-compact window (matcher auto ). The hook receives the transcript path, the trigger, and any custom instructions the user passed to /compact . It can therefore archive the full transcript to a log before the summary discards detail. Exit code 2, or "decision": "block" in its JSON output, blocks the compaction. A PostCompact event fires afterwards carrying the generated summary. The pattern matches the tool hooks: a Pre event can inspect and block, and a Post event can only observe what has already happened.

Task decomposition breaks complex work into pieces an agentic system can handle. A fixed sequential pipeline, also called prompt chaining, runs predetermined steps in order. Dynamic adaptive decomposition generates subtasks from what each step discovers. The wrong pattern makes the work suffer in predictable ways. Attention dilution is a failure mode that shows up when decomposition is too shallow.

A jeweller's agent has two jobs. It checks 40 new product listings before they go live, and finds out why the website's stock count keeps disagreeing with the shop's.

In a fixed pipeline, each step takes the previous step's output as input. The sequence does not change based on intermediate results.

Prompt chaining can break a code review into three sequential steps.

The jeweller's listing check has the same shape: check each listing, check the listings against each other, write one report.

Fixed pipelines suit predictable, structured tasks with known steps: code reviews, document processing, data extraction pipelines and compliance checks. The same input always follows the same path. That gives three advantages.

A fixed pipeline cannot adapt to unexpected findings. If the jeweller's Step 2 finds half the batch using the wrong size chart, Step 3 cannot change.

Key Concept

Prompt chaining suits predictable, structured tasks. It is consistent and reliable and cannot adapt to unexpected findings.

With dynamic decomposition, the plan evolves as the agent learns. The agent starts with a high-level goal, investigates and plans from what it finds. New information may change the remaining steps, and the agent adapts.

The stock mismatch needs this pattern. Nobody knows the cause at the start, so nobody can write the steps in advance. If the agent finds repairs logged as sales, its next steps follow that lead.

Adding tests to a legacy codebase runs the same way.

This pattern suits open-ended investigation where the full scope is unknown at the start: legacy system exploration, security audits, research projects and debugging unfamiliar codebases. It responds to unexpected complexity and gives more thorough results on open-ended tasks, because it does not force-fit a predetermined plan. It is less predictable: execution time varies with discoveries, so completion time and resource usage are harder to estimate, and debugging is harder.

Match the pattern to the task's characteristics. The jeweller's listing check has known steps: fixed pipeline. The stock mismatch has unknown scope: dynamic decomposition.

Attention dilution occurs when an agent processes too many items in a single pass. Depth becomes inconsistent: some items get thorough analysis, and others have obvious issues missed. The model allocates attention across all the items in its context, so each item gets less as the count grows. Early items get a disproportionate share, and later items get skimmed. Three symptoms show up.

Send the jeweller's 40 listings in one pass, and listing 3 is flagged for a missing hallmark while listing 31, with the same gap, passes. A wrong price in listing 35 goes unnoticed.

The fix is structural. A better model, a larger context window or a more detailed prompt still leaves every item in one pass. Multi-pass architecture splits the work into two layers. Per-item local analysis passes give each file, document or module its own pass, with the full attention budget on that item. After all local passes, a cross-item integration pass looks for cross-cutting concerns: data flow issues, inconsistent pattern usage and cross-file dependencies.

The per-item passes catch local issues consistently, because each item gets dedicated attention. The integration pass catches cross-item issues, because it focuses on the relationships between items instead of doing everything at once.

With 40 single-listing passes and one integration pass, listing 35's wrong price is caught in its own pass. The integration pass finds the hallmark gap judged two ways.

Exam Trap

A question may offer a fixed pipeline for an open-ended investigation task, or dynamic decomposition for a structured processing task. Match the pattern to the task characteristics, not to what sounds more sophisticated.

A version of the exam's sample question: a code review agent processes 14 files in a single pass.

Large code reviews are split into per-file local analysis passes plus a separate cross-file integration pass to avoid attention dilution. Here the keyed fix is 14 per-file passes and one integration pass checking data flow and pattern consistency across all files. The per-file passes catch the null pointer bugs in Files 10-14, because each file gets its own pass. The integration pass identifies the inconsistent forEach evaluation, because it checks cross-file pattern consistency.

A session is one conversation with an agent that you can come back to. Its conversation history holds the agent's reasoning and every tool result. A tool result is the output of a tool call, such as a file's contents when the agent read it. In long-running tasks, such as debugging a complex system, reviewing a large codebase or multi-day research, this history fills up with tool results, file analyses and reasoning chains. Session management determines how an agent keeps continuity across work sessions. Task Statement 1.7 covers how to manage that accumulated state: when to continue it, when to branch it and when to start fresh. A tool result is stale when the file it describes has changed since the agent read it.

Take a shoe repair shop whose owner uses Claude Code to review the shop's files: the price list, the repair-ticket template and the supplier order sheet. On day one the agent reads the files and finds three pricing errors. Overnight the owner fixes all three by editing those three files. On day two the owner wants to carry on.

The Agent SDK and Claude Code give you three approaches to session management. Each does a different job.

Resume continues a specific named session from where it left off. It restores the entire conversation history, including every tool result, analysis and line of reasoning. Use it when the prior context is mostly still valid. The files have not changed significantly since the last session, and you want to pick up exactly where you stopped.

Do not resume when the earlier tool results are stale. That happens when files have changed since the last session and much of what the history says about them no longer matches the codebase. If most of the context is still valid, resume and tell the agent which files changed. Otherwise you hit the stale context problem. Resume would suit the shop after a night when nobody touched the files. It does not suit day two, because the three files the day-one analysis was built on have changed.

Current state: how sessions get their names

--resume only resumes sessions that already exist. It accepts a session ID or name, or opens an interactive picker, but it never creates a session. Current state (checked 6 October 2026): you name a CLI session at start with --name / -n , or mid-session with /rename , and continue it later with claude --resume . There is also -c / --continue , which resumes the most recent conversation in the current directory without naming anything. (Source: the Claude Code CLI reference.)

Fork creates an independent branch from a shared analysis baseline. After the fork, each branch operates independently. Changes in one branch do not affect the other, and neither branch can see the other's results.

Current state (checked 6 October 2026): in the SDK you set fork_session beside resume , not instead of it. resume picks the session, and fork_session: true starts a new session from a copy of that history instead of appending to it. The CLI pairs --fork-session with --resume the same way. (Source: the Agent SDK sessions guide. Lesson 1.3 has the full note.)

Use fork when you have completed an initial analysis and want to explore divergent approaches from that shared starting point. For example, after analysing a codebase, you fork to compare two refactoring strategies. Each fork builds on the same initial understanding and takes a different direction. Do not fork when you simply want to continue the same line of investigation. Fork is for divergence. If you are not comparing alternatives, use resume. After day one, the shop could fork to compare two pricing fixes: a higher resoling price, or a charge for rush jobs. Both branches start from the same reading of the files, and neither sees what the other concludes.

Start a completely new session and inject a structured summary of the prior session's findings into its initial context. The new session has no stale tool results, only the curated summary you provide. Use it when tool results from the prior session are stale because files have changed, APIs have been updated or dependencies have shifted. Use it too when context has degraded over a long session, with too many irrelevant tool results cluttering the history. In both cases you need a clean baseline with preserved knowledge. If the prior context is still valid and you want the full conversation history, resume is more efficient. Fresh start is the right choice for the shop on day two.

Key Concept

Three session management options serve three distinct purposes: resume for continuation, fork for divergent exploration, and fresh start with summary injection for when prior tool results are stale.

The stale context problem is the central concept of this task statement. It occurs when an agent resumes a session after code or other files have been modified. The agent then reasons from cached tool results that no longer reflect the current state of those files.

When you resume a session, the entire conversation history is restored, including every tool result from the previous session. Suppose a file was read in the previous session and has been modified since. Its old contents stay in the conversation as a tool result. The model reasons from that stale data alongside any new data, and the two contradict each other. The symptom is contradictory advice about the modified files. The agent recommends changes that were already made, or refers to code that no longer exists.

On day two the owner resumes the session, and the agent recommends fixing the three errors fixed overnight. The tool results showing the old price list are still in the history. Asked about the current price list, it gives contradictory answers. Sometimes it quotes the old version from the stale tool result, and sometimes the new version from a fresh read.

The obvious fix is to resume and ask the agent to re-read the modified files. This is better than nothing, but the stale tool results remain in the conversation history. The model may still refer to old information from earlier in the context. This is most likely for tangential decisions that do not directly involve the modified files.

The correct fix is to start a fresh session with a structured summary of prior findings. Specify which files have changed, so the agent can run a targeted re-analysis of those files. The fresh session has no stale tool results. The injected summary keeps what the prior session learned, without the outdated data. For the shop, the new session reads the current files, verifies the three fixes and gives consistent advice.

When files have changed, the agent does not need to re-analyse everything. Re-reading 50 files because 3 of them changed is wasted time. Targeted re-analysis means telling the agent which files changed and letting it re-analyse only those. The summary from the prior session covers everything that has not changed.

On day two, the shop's targeted re-analysis runs in four steps:

This is faster than full re-exploration and more reliable than resuming with stale context.

The exam tests your ability to select the right option for each scenario. Resume the session when prior context is mostly valid. Start fresh with an injected summary when prior tool results are stale. A typical stem describes a session resumed after files changed, and an agent giving contradictory advice. The keyed answer is a fresh session with a structured summary, plus targeted re-analysis of the changed files. Starting a new session with a structured summary is more reliable than resuming with stale tool results.

Exam Trap

The exam tests whether you recognise that resuming after file changes can lead to stale context. Simply resuming and asking the agent to re-read changed files is not the best answer. The stale results remain in history and can still influence reasoning. A fresh start with summary injection is more reliable.

A tool is a function an agent can call, with a name and a plain-language description. Tool descriptions are the primary mechanism LLMs use for tool selection. Given a set of tools, the model reads them to decide which one to call. They are not supplementary metadata. Minimal descriptions, such as "Retrieves customer information", leave the model no way to tell apart overlapping tools.

A tailor's booking agent has two tools, described as "Retrieves client information" and "Retrieves alteration details". Asked whether a hem is ready, the agent calls the client tool, because both descriptions fit.

A production-grade tool description includes five elements.

The tailor's alteration tool would name the ticket number it accepts and list "is my hem ready?" as a query.

Minimal (causes misrouting):

get_customer: "Retrieves customer information" lookup_order: "Retrieves order details" Production-grade (reliable selection):

get_customer: "Looks up a customer account by email address, phone number, or customer ID. Returns customer profile (name, contact details, account status, loyalty tier). Use this when you need to verify who the customer is. Do NOT use for order-specific queries — use lookup_order for those." lookup_order: "Retrieves order details by order number (format: #NNNNN) or tracking ID. Returns order status, items, shipping details, and refund eligibility. Use this when a customer asks about a specific order. Do NOT use for customer identity verification — use get_customer for that." The second version gives explicit disambiguation: which identifiers each tool accepts, what each returns, and when not to use each.

Two tools with overlapping or near-identical descriptions cause selection confusion. Both fit a request like the hem question, so nothing points the model to the right one. Expand both descriptions with the five elements.

Generic tools with broad responsibilities create ambiguity, because a broad description fits many requests. Split them into purpose-specific tools with defined input and output contracts, as a tailor might split one garment tool into fittings and alterations.

Before splitting:

analyze_document: "Analyses a document and returns results" After splitting:

extract_data_points: "Extracts structured data fields (dates, amounts, names) from a document" summarize_content: "Produces a concise summary of a document's key arguments and conclusions" verify_claim_against_source: "Checks whether a specific claim is supported by the source document, returning supporting/contradicting evidence" Each resulting tool does one narrow, clearly described job the model can match to the user's need.

When two tools have confusingly similar names, renaming fixes the overlap at the interface level. Rename analyze_content to extract_web_results with a web-specific description, and its purpose becomes unambiguous without touching its implementation. The tailor's tools could become find_client and find_alteration .

Keyword-sensitive instructions in system prompts can create unintended tool associations that override well-written descriptions. Told to "always check customer details before proceeding", the model may route any customer-related query to get_customer , whatever the descriptions say. The tailor's "always check client details first" could pull hem questions to the client tool. After updating descriptions, reread your system prompt for conflicts, a subtle failure mode.

In the exam guide's sample Question 2, get_customer and lookup_order have minimal descriptions, and the agent routes "check my order #12345" to the wrong tool. Pick the correct fix from four plausible options.

The exam consistently favours low-effort fixes with a large effect: better descriptions before routing classifiers, scoped access before full access, community servers before custom builds. System prompt conflicts are tested too.

Key Concept

When weak descriptions cause misrouting, improving them is the first fix.

Both halves of that condition are tested. Descriptions are the fix when the agent has a workable number of tools and cannot tell two apart. They are not the fix when the toolkit itself is the problem. With a large tool set (the guide's example is 18 against 4-5), selection degrades on decision complexity alone. Rewriting 22 descriptions leaves that untouched. Diagnose which case you face first. Task Statement 2.3 covers the overload threshold and what to do instead.

Current state (checked 6 October 2026): Anthropic's tool search docs say selection degrades once an agent has more than 30 to 50 tools. On the exam, stick with the guide's 18-versus-4-5 example.

A structured error response is the result an MCP tool returns when a call fails. Its metadata tells the agent the error's category, whether a retry can work, and how to recover. The MCP protocol provides the isError flag to report the failure to the agent. With it set, the model knows the execution failed and reasons about recovery, instead of reading the error text as a normal successful result. This response decides whether the agent recovers intelligently or fails blindly. A generic message such as "Operation failed" is useless to an LLM, because it says nothing about what went wrong, whether to retry, or what to try instead.

A picture framer's agent handles orders through three MCP tools: a stock tool for a moulding supplier's catalogue, a jobs tool for job references, and a refund tool.

The MCP specification reports tool failures through two separate channels. Recovery design starts with knowing which one a failure belongs to.

Protocol errors are standard JSON-RPC error responses. The server sends one when the request itself is malformed. The tool name does not exist, the arguments fail the input schema, or the server hits an internal fault. There is no result object, only an error with a code and a message . The host application handles these. The model never sees a tool result, because no tool ran. A misspelt tool name from the framer's agent would fail here. Below is a generic example.

{ "jsonrpc" : "2.0" , "id" : 3 , "error" : { "code" : -32602 , "message" : "Unknown tool: invalid_tool_name" } } Tool execution errors are results. The tool was found, the arguments were valid and the tool ran. Then something went wrong inside it: an upstream API failed, the input data was wrong, or a business rule rejected the request. The server returns a normal result with isError: true and the detail in content . The model reads it and decides what to do next. A failed stock check at the framer would be one. Below is a generic example.

{ "jsonrpc" : "2.0" , "id" : 4 , "result" : { "content" : [{ "type" : "text" , "text" : "Failed to fetch weather data: API rate limit exceeded" }], "isError" : true } } The four categories, isRetryable and the recovery guidance all describe execution errors, because that is the layer the agent reasons about. A protocol error means the call was built wrong. The fix belongs in the tool schema or the client, not in the agent's recovery loop.

Every tool failure falls into one of four categories. Each needs a different recovery strategy, and the agent needs structured metadata to tell them apart.

The fields errorCategory , isRetryable and description are an application-level convention, not part of the MCP envelope. The protocol's CallToolResult defines only content , structuredContent and isError . The examples below carry the metadata in structuredContent , which is where structured data belongs.

1. Transient Errors Timeouts, service unavailability, rate limits. The underlying system is briefly unreachable, but the request is valid. Recovery: retry after a short delay.

{ "isError" : true , "content" : [{ "type" : "text" , "text" : "Service temporarily unavailable" }], "structuredContent" : { "errorCategory" : "transient" , "isRetryable" : true , "description" : "The order database is experiencing high load. The request is valid and should succeed on retry." } } At the framer, a supplier catalogue timing out under load is transient.

2. Validation Errors Invalid input format, missing required fields, out-of-range values. The request itself is malformed. Recovery: fix the input, then send a corrected call.

{ "isError" : true , "content" : [{ "type" : "text" , "text" : "Invalid order ID format" }], "structuredContent" : { "errorCategory" : "validation" , "isRetryable" : false , "description" : "Order ID must be in format #NNNNN (e.g. #12345). Received: 'order-abc'. Reformat the ID and call again." } } Here isRetryable: false does not mean "give up". It means resending this call is pointless, because order-abc fails the same format check every time. The agent still recovers by correcting the input first, and the description tells it how. The boolean says whether to resend. errorCategory says what to do instead. At the framer, a job reference in the wrong format is a validation error, which the agent fixes and resends.

3. Business Errors Policy violations, limit exceedances, business rule conflicts. The request is technically valid but breaks a business constraint. Recovery: do not retry. The agent needs an alternative workflow.

{ "isError" : true , "content" : [{ "type" : "text" , "text" : "Refund exceeds policy limit" }], "structuredContent" : { "errorCategory" : "business" , "isRetryable" : false , "description" : "Refund amount of £750 exceeds the £500 automatic refund limit. This requires manager approval. Please escalate to a human agent with the refund details." } } Business errors carry isRetryable: false because the same policy violation applies every time, so retrying never resolves them. The agent has to take a different path, usually escalation. A customer-friendly explanation in the description lets it tell the customer why. At the framer, a refund above the automatic limit is a business error, so it goes to a person.

4. Permission Errors Access denied, insufficient credentials, authorisation failures. The tool cannot run because the caller lacks the required permissions. Recovery: escalate or use different credentials.

{ "isError" : true , "content" : [{ "type" : "text" , "text" : "Access denied" }], "structuredContent" : { "errorCategory" : "permission" , "isRetryable" : false , "description" : "The current service account does not have permission to access financial records. Escalate to a senior agent with financial system access." } } At the framer, records the agent has no rights to read raise a permission error.

isRetryable answers one narrow question: will resending this exact request work? Only transient errors get true , because the call was valid and the system was briefly unavailable. Every other category gets false , because something has to change first: the input (validation), the request itself (business) or the caller (permission).

Read isRetryable to decide whether to resend as-is. Then read errorCategory to decide what to do when you cannot.

The distinction that counts most is between the three false rows. Validation is recoverable by the agent alone. Business and permission are not. A policy limit applies however the request is worded. A permission error needs a different account, not a better call. So false means "not this call again", not "stop".

Current state: where this table comes from

Exam guide v1.0 states retriable: false for business rule violations and never assigns a value to validation. The false for validation above is the wider ecosystem's convention: gRPC treats INVALID_ARGUMENT as non-retryable, and AWS-style retry metadata does the same. The table applies it to a gap the guide leaves open. (Verified against the exam guide, August 2026.)

An access failure means the tool could not reach the data source. A timeout occurred, authentication failed, or the service was down. The data might exist, but the tool could not check.

A valid empty result means the tool queried the data source successfully and found no matches. The query ran correctly, and no data matches the criteria. The agent should not retry. The answer is "no results found".

A tool should distinguish the two: an access failure needs a retry decision, and a valid empty result is a successful query with no matches. Confusing them breaks recovery logic.

Say the framer's agent asks the stock tool for a moulding the supplier has never made. The query runs and finds nothing. Its response does not separate "I could not reach the catalogue" from "I reached it and found nothing". So the agent treats the empty answer as a failure, retries three times and hands it to a person. The tool had succeeded.

The fix is to structure tool responses so a successful query with no results looks nothing like a failed query. Here is a generic pair.

// Valid empty result — NOT an error { "isError" : false , "content" : [{ "type" : "text" , "text" : "No customer found matching email 'john@example.com'. The query executed successfully but returned no matches." }], "structuredContent" : { "resultCount" : 0 } } // Access failure — IS an error { "isError" : true , "content" : [{ "type" : "text" , "text" : "Could not reach customer database" }], "structuredContent" : { "errorCategory" : "transient" , "isRetryable" : true , "description" : "Connection to the customer database timed out after 5 seconds. The query did not execute." } } Error Propagation in Multi-Agent Systems In multi-agent systems, error handling follows a principle of local recovery with selective propagation. Say the framer's coordinator sends a subagent to compare moulding prices from five suppliers.

This prevents two anti-patterns: silently suppressing errors by returning empty results as success, and ending an entire workflow on a single failure. Both leave the coordinator making decisions blind.

Access failure against valid empty result is the distinction to nail in this domain. The exam tests it directly.

The exam guide names the four categories and the isRetryable boolean, so know them by name, even though the MCP specification does not define them. Expect questions on which category a failure belongs to and what recovery it needs, which the guide specifies. If a question turns on the boolean for validation, ask whether resending this exact call would work. You will land on false .

Key Concept

Access failures and valid empty results need different handling. Confusing the two causes wasted retries and incorrect escalations.

An agent's tools are the functions it can call. Tool selection is the model's choice of which one to call. Tool distribution is the choice of which agent in a multi-agent system holds which tools. The number of tools an agent holds directly affects how reliably it selects the right one. So distribution is an architectural decision that determines whether a multi-agent system works in production.

Take a print shop run by a small team of agents. An order agent handles orders and customer messages, and an artwork agent prepares files for the press. A quoting agent prices jobs, a stock agent tracks paper, and a coordinator hands work between them.

Giving a single agent 18 tools degrades selection reliability. Every additional tool adds decision complexity, so error rates climb as the toolkit grows. Keep each agent's set small and scoped to its role. In the print shop, each agent weighs only the few tools its role needs.

Relevance matters as much as quantity. An agent given tools outside its specialisation tends to misuse them. With a search tool, it may run its own searches instead of using the results already handed to it. That duplicates work and wastes context. The print shop's quoting agent, given a search tool, may search the orders again rather than pricing the job it was handed. Each agent gets only the tools its defined role needs.

Splitting by role is the wrong fix when the tools all do the same kind of work. Take a server with 22 tools: three query tools, one per data source, and 19 transformations such as pivot_table , calculate_percentile and normalise_currency . Split by role, a transformation agent gets 19 tools. The original problem has moved one level down, and the agent still cannot choose reliably.

The 19 share a shape: data in, an operation, data out. So they collapse into one tool whose parameter names the operation:

{ "name" : "transform_data" , "description" : "Apply a transformation to a dataset. Use transform_type to select the operation." , "input_schema" : { "type" : "object" , "properties" : { "dataset" : { "type" : "string" }, "transform_type" : { "type" : "string" , "enum" : [ "pivot" , "percentile" , "normalise_currency" , "..." ] }, "options" : { "type" : "object" } }, "required" : [ "dataset" , "transform_type" ] } } Twenty-two tools become four, and nothing is lost. Each transformation is now an enum value the model picks inside a single call, not a tool to find among nineteen near-identical descriptions. Selection accuracy improves because the hard choice got smaller, while the capability stayed the same.

The print shop's artwork operations share a shape too: resizing, adding bleed and converting to CMYK each take a file in and give a file out. One artwork tool with an operation parameter replaces them.

To pick the fix:

Task Statement 2.1 teaches sharper descriptions as the fix for misrouting. That is right when the toolkit is small enough to reason about. If the print shop's order agent holds five tools and picks get_customer when it needed lookup_order , that is a description problem. The same symptom from a set of 22 is not. At that size, no description quality rescues selection, and rewriting all 22 leaves the decision complexity where it was. Count the tools before you pick the remedy.

Moving tools onto a second MCP server is no fix. A client hands the model every tool from every connected server as one flat list. Server boundaries are invisible to the model, so 22 tools on two servers are still 22 tools.

A fetch_url tool can fetch anything from anywhere. A load_document tool validates document URLs and accepts those only. Giving a subagent load_document instead:

This is least privilege applied to tool design. Each tool does exactly what the agent needs and nothing more. The print shop's artwork agent needs customer files, so load_document is enough.

Consolidation reduces how many tools an agent chooses between. Constraining reduces what any one tool can reach. Collapsing 19 transformations into transform_data gives the agent no new powers, so it does not undo least privilege. Replacing fetch_url with load_document does the opposite job.

Sometimes an agent needs occasional access to a capability that belongs to another role. The naive approach routes every such request through the coordinator, which delegates, waits for the result and passes it back. That adds 2-3 round trips per request and can increase latency by 40% or more. For simple lookups that take milliseconds, the round trip is waste.

A scoped cross-role tool is a constrained version of the capability, given directly to the agent that needs it. High-frequency simple requests use it. Complex cases, which need multiple sources, cross-referencing or real judgement, still route through the coordinator. The print shop's quoting agent checks paper stock for nearly every quote, so it gets a scoped check_stock tool for simple lookups. Harder checks still go through the coordinator to the stock agent.

The scope lives in the tool's input schema. A field the schema leaves out is a request the agent cannot make.

{ "name" : "check_stock" , "description" : "Check how many sheets of one paper stock are in the warehouse. Takes a single stock code. For substitutions, supplier lead times or anything that needs judgement, ask the coordinator." , "strict" : true , "input_schema" : { "type" : "object" , "properties" : { "stock_code" : { "type" : "string" , "pattern" : "^PS-[0-9]{4}$" } }, "required" : [ "stock_code" ], "additionalProperties" : false } } This schema accepts one stock code and nothing else. It has no free-text query, no supplier field and no list of codes, so the quoting agent cannot use it to browse the stock agent's data. The description names what the tool does not do and where those requests go. With strict: true , the API constrains Claude's tool inputs to the schema, so every call carries exactly one code in the right format.

Build the limit into the shape of the schema. Strict tool use supports enum , pattern and an array minItems of 0 or 1. The API rejects maxItems , maxLength , minimum and maximum with a 400 error when the schema reaches it unchanged. So "one stock code per call" is a single string field, not an array with maxItems: 1 . A limit the schema cannot express, such as how many checks the agent may run for one quote, goes in the code that runs the tool.

The tool_choice parameter controls how the model interacts with the tools available. Each of its three settings has its own job.

"auto" (default) The model decides whether to call a tool or return text. Use it for general operation, where the model needs flexibility to respond conversationally when no tool call is appropriate. The print shop's order agent fits: some messages need a lookup, some only a reply.

{ "tool_choice" : { "type" : "auto" } } "any" The model must call a tool but chooses which one. Use it when you need guaranteed structured output from one of multiple schemas. The model always produces a tool call, never plain text.

{ "tool_choice" : { "type" : "any" } } Extraction pipelines are the usual case. With one schema each for invoices, receipts and contracts, and an unknown document type, "any" guarantees the model picks one and produces structured output, not a conversational response. The print shop's order agent needs this when an order could be for business cards, posters or banners.

Forced selection The model must call one specific named tool. Use it to enforce a mandatory first step: the model cannot skip or reorder the required operation.

{ "tool_choice" : { "type" : "tool" , "name" : "extract_metadata" } } This enforces workflow ordering. If metadata extraction must happen before any enrichment tools run, forcing extract_metadata guarantees it, and the model cannot jump straight to enrichment. After the forced call completes, later turns can use "auto" . The print shop's artwork agent could force a file check first in the same way.

Current state

Exam guide v1.0 names all three modes and tests "any" and forced selection for those jobs. Current state (checked 6 October 2026): the define-tools page says Claude Opus 5.5, Sonnet 5.5, Fable 5.1 and Mythos 5.1 reject {"type": "any"} and {"type": "tool"} with a 400 error. Manual extended thinking rejects both on any model. On those, the documented route is "auto" with strict tool use for schema-valid inputs, and the prompt steers which tool gets picked. The claude-sonnet-5 model in this lesson's code isn't on that list, so the code runs as written. On the exam, answer with "any" and forced selection.

The guide sets 18 tools against 4-5 per agent. That is an illustration, not a hard limit.

The first row of the fix table is where candidates trip. The exam also likes the tension between consolidation and constraint, which can both be right in the same system.

The guide's sample Question 9 tests scoped cross-role tools directly. In it, a synthesis agent sends every fact verification through the coordinator, and 85% of them are simple lookups. For frequent simple fact checks, the synthesis agent gets a scoped verify_fact tool. Complex verifications, the other 15%, still go to the web search agent through the coordinator. The guide's reasoning is least privilege: the synthesis agent gets only what the 85% case needs. Scope verify_fact the way check_stock is scoped: one claim in, a verdict out, and no query or URL field that would let it run its own searches.

In a multi-agent research system, the synthesis agent should not have web search tools, or it might run its own searches. The web search agent should not have document analysis tools. A well-designed layout:

The coordinator holds no domain-specific tools itself.

Key Concept

Keep each agent's tools few and scoped to its role. Scoped cross-role tools spare high-frequency simple operations the coordinator round trip.

Current state (checked 6 October 2026): Anthropic's tool search docs say Claude's ability to pick the right tool degrades once you exceed 30 to 50 available tools. On the exam, stick with the guide's 18-versus-4-5 framing.

An MCP (Model Context Protocol) server extends Claude by connecting it to an external system: a database, an API, a development tool or an issue tracker. How the servers are configured decides whether a team shares one consistent toolset or descends into configuration chaos.

Two developers at a toy shop use Claude Code on the shop's online store. Both need Claude to reach its GitHub repository and stock database. One also wants to trial a code search server alone.

Configuration lives at two levels, and most setup problems start when they get mixed up.

Project level: .mcp.json . It sits in the project repository root and is version-controlled, so every team member who clones or pulls gets it. Use it for servers the whole team needs: a Jira integration, GitHub tools, internal API connectors. The toy shop's GitHub and stock database servers go here.

{ "mcpServers" : { "github" : { "type" : "http" , "url" : "https://api.githubcopilot.com/mcp/" }, "atlassian" : { "type" : "http" , "url" : "https://mcp.atlassian.com/v1/mcp/authv2" }, "filesystem" : { "command" : "npx" , "args" : [ "-y" , "@modelcontextprotocol/server-filesystem" , "${WORKSPACE_ROOT:-.}" ] } } } The example shows two entry shapes. A remote server declares "type": "http" and a url . A local server declares a command and args , and speaks over stdio. An entry with a url but no type is a configuration error. Claude Code reads it as a stdio server, skips it, and tells you to add the type .

User level: ~/.claude.json . It sits in the user's home directory and is personal: not version-controlled, not shared with teammates. Use it for experimental servers, personal integrations, or servers you are testing before proposing them to the team. The toy shop's trial search server goes here.

Current state

Exam guide v1.0 describes two configuration levels, project and user, and that is the expected exam answer. Current state (checked 6 October 2026): the MCP documentation documents three scopes, local (the default), project and user , selected with -s / --scope . ~/.claude.json holds the local and user entries.

All tools from all configured servers, project and user level, are discovered at connection time and available simultaneously. There is no manual activation step. If a server is configured and reachable, its tools appear in the agent's toolkit. The trial developer's Claude sees all three servers' tools.

.mcp.json supports ${VARIABLE_NAME} syntax for environment variable expansion. This keeps credentials out of version control whilst the server configuration stays shared.

{ "env" : { "GITHUB_TOKEN" : "${GITHUB_TOKEN}" , "DATABASE_URL" : "${DATABASE_URL}" } } The file references variable names, not values. Each developer sets their own tokens locally, in a shell profile, a .env file or a secrets manager. Each toy shop developer uses their own GitHub token. This means:

A second form, ${VAR:-default} , expands to VAR when set and falls back to default when not. Use it for machine-specific paths with a sensible fallback, like ${WORKSPACE_ROOT:-.} above. Current state (checked 6 October 2026): an unset variable with no default does not stop the rest of the configuration loading. Claude Code warns and carries on, so do not rely on a missing token failing loudly.

An MCP resource exposes a content catalogue to an agent upfront, so it needs no exploratory tool calls to discover what data exists. This is exam guide v1.0's framing and the keyed answer.

Current state (checked 6 October 2026): the MCP specification says resources are application-driven. The server lists them, but the client decides when to attach one to the model's context. So the agent sees a resource only when the host surfaces it. Claude Code does that through @server:resource mentions and a resource-listing tool.

What to expose as resources:

The payoff is fewer wasted calls. Without resources, an agent might call list_tables , then describe_table for every table, to get its bearings. With a database schema resource, it knows immediately. For the toy shop, that resource is its stock database schema.

Resources show agents what data is available. Tools let them act on it.

A team integrating with an external system can build a custom MCP server or use a community one. This choice comes up constantly, in the exam and in real work.

Use community servers for standard integrations:

Build custom servers only when:

The toy shop uses a community GitHub server. Its stock database is internal, so if no community server covers it, that connector is worth building.

Built-in tools such as Grep have rich, detailed descriptions, so the model has better context about them. When an MCP tool has a sparse description, the agent may prefer the built-in tool even when the MCP tool is more capable.

The fix is a description that explains capabilities and outputs in detail. Instead of:

search_codebase: "Searches code" Write:

search_codebase: "Performs semantic code search across the entire repository using AST-aware indexing. Returns matching functions, classes, and methods with full context including file path, line numbers, and surrounding code. More accurate than text-based grep for finding code by intent rather than exact string match. Use this instead of Grep when searching for code by what it does rather than what it contains." The detailed description gives the model enough context to prefer the MCP tool when it is more capable than the built-in alternative. The toy shop's trial search server needs the same, or Claude may keep using Grep.

On build-vs-use questions, the exam consistently favours the pragmatic choice. "Evaluate community servers first" is always correct when a standard integration is involved. "Build custom" is only correct when the scenario explicitly describes team-specific requirements that community servers cannot meet.

Both GitHub and Atlassian ship official remote servers now, so neither is an npx line in the first example.

Key Concept

Project-level .mcp.json is version-controlled and shared. User-level ~/.claude.json is personal. ${ENV_VAR} syntax keeps credentials out of version control.

Claude Code provides six built-in tools for working with codebases: Read, Write, Edit, Bash, Grep and Glob. Read loads a file's full contents, Write saves a complete file, and Edit replaces exact text in a file. Grep searches what files contain. Glob matches file paths. Every file read into context costs tokens, and the context window has a limit. Each tool has a specific purpose, and the wrong tool wastes time, context tokens or both.

Take a sports shop that sells kit online. Its developer uses Claude Code on the shop's codebase: order handling, refunds and their tests. Finding code, changing it and tracing its use each need a different tool.

Grep searches file contents for patterns. Use it to find function callers, error messages, import statements and variable assignments. For every file in the shop's codebase that calls processLegacyOrder , the developer uses Grep, because a function call is text inside a file.

// Find all files that call processLegacyOrder() Grep: "processLegacyOrder" // Find all error messages containing "timeout" Grep: "timeout" // Find all files that import a specific module Grep: "import.*from 'utils/auth'" Glob matches file paths by naming patterns: name, extension or directory structure. Use it for test files, configuration files, or all TypeScript files in one directory. For every test file in the shop's codebase, the developer uses Glob, because test files share a naming pattern.

// Find all test files Glob: "**/*.test.tsx" // Find all configuration files Glob: "**/config.*" // Find all MDX files in the domains directory Glob: "content/domains/**/*.mdx" Grep finds what is inside files. Glob finds files by their names. So Glob cannot find function callers, because a file's path says nothing about what it calls. Grep can find test files by naming pattern in a technical sense, by searching for "test" in filenames via content. It is still the wrong tool for paths.

These three tools handle file operations, each optimised for a different use case. Edit makes targeted changes using unique text matching. You give it the exact text to find and its replacement. It is fast and precise because it touches only that text, as in the edit below.

Edit: old_string: "function processOrder(id: string)" new_string: "function processOrder(id: string, validate: boolean = true)" Edit needs that text to be unique in the file. If it appears in several places, Edit cannot tell which occurrence you mean, so it fails. This is a safety mechanism: it stops you changing text you never meant to touch. Say the shop's checkout file calls processOrder(orderId) three times. An Edit on that short anchor fails.

One way forward is Read + Write: read the full file, then write the complete modified version back. It works every time, because Edit no longer has to guess. It also spends a file's worth of tokens on what was usually a one-line change. That is why it is the fallback, not the default.

Current state (checked 6 October 2026): the Edit tool docs give a cheaper move first. Widen old_string with more surrounding context until it pins down one location, or set replace_all: true to update every occurrence. Both keep you on Edit and cost almost no extra context. In the checkout file, adding the enclosing function's first line to the anchor gives one match. The order in real work has three steps.

Do not default to Read + Write for every modification. It burns context tokens.

How you explore a codebase matters as much as which tools you use. Reading every file upfront, before you know what you need, is the costliest exploration mistake. A 200-file codebase read in full fills your entire context window, mostly with files unrelated to the task. Incremental discovery starts narrow and expands only as needed.

At the sports shop, a refund bug starts from an error message. The developer Greps for it, reads the file it points to, then follows the imports. That is minimal context for maximum understanding: tokens go only on files that matter.

A common pattern is a function defined in one module, re-exported through a wrapper, and consumed through the wrapper's name. A Grep for the original name misses every consumer that imports through the wrapper, because those files never contain that name. The trace has four steps.

In the sports shop's codebase, processOrder is defined in orders.ts . The barrel utils/index.ts re-exports it as submitOrder , and three of its five consumers import submitOrder from utils . A Grep for processOrder finds the definition, the barrel line and the two consumers that import the original name. It cannot find the other three, because the string processOrder never appears in their files. Read the barrel, spot the rename, Grep for submitOrder , and the three turn up. The multi-step trace catches indirect consumers a single Grep would miss.

To find every file that calls a deprecated function and the test files that exercise it, run three steps in order.

A test that reaches the function through its source module may never contain the function's name, so Grep misses it. Its path follows the source file's name, so Glob finds it.

Say the sports shop deprecates processLegacyOrder , and Grep shows that OrderProcessor.ts and RefundHandler.ts call it. Glob for **/OrderProcessor.test.* and **/RefundHandler.test.* to pull in their sibling test files. If either source file wraps the function under a new name, Grep for that wrapper to catch any remaining tests.

The exam deliberately presents scenarios where a developer confuses these tools. Grep against Glob is the distinction that matters most in this task statement. Glob for function callers fails, because Glob does not search contents. Grep for test files by naming pattern works technically, but the exam expects you to pick Glob.

The guide names one fallback when Edit cannot find a unique anchor: Read + Write. The exam's ordering has two steps, Edit first and Read + Write when Edit fails, and agrees with the real-work ordering on the first. The exam penalises defaulting to Read + Write, because it burns context tokens.

The deprecation question turns up constantly in exam prep. The correct sequence is Grep, then Glob, then Grep again. Glob first is wrong.

Key Concept

Grep searches file contents. Glob matches file paths. Edit is the default for modifications, and on a non-unique match the exam's answer is Read + Write. Never read all files upfront.

Current state

Exam guide v1.0 frames Read + Write as the documented fallback. Its words are "Using Read to load full file contents followed by Write when Edit cannot find unique anchor text". Current state (checked 6 October 2026): the Edit tool reference documents widening old_string or setting replace_all: true as the behaviour on a non-unique match. On the exam, answer Read + Write. In real work, widen the anchor first, because it is cheaper.

Current state

Exam guide v1.0 lists Grep and Glob among the built-in tools: "Select and apply built-in tools (Read, Write, Edit, Bash, Grep, Glob)". Current state (checked 14 October 2026): the tools reference says "On macOS, Linux, and WSL, Claude Code leaves Glob and Grep out of the default tool set, and Claude searches with find and grep through the Bash tool instead." Naming them in --tools or --allowedTools when the session starts brings them back. On the exam, treat Grep and Glob as built-in tools.

A CLAUDE.md file is a Markdown file of instructions for Claude Code. Claude Code reads these files at three levels: user (one person), project (the whole team) and directory (one folder). @ path imports and the .claude/rules/ directory split instructions across several files.

Take an osteopath practice whose two developers use Claude Code on its booking website. Every session should follow the practice's naming rules and testing requirements. One developer likes short answers. The booking API package has its own REST conventions.

User-level: ~/.claude/CLAUDE.md

This file applies only to you. It lives in your home directory, outside any repository. So it isn't version-controlled and never travels through git. A new teammate who clones the repo won't get these instructions. Keep this level for strictly personal preferences: verbosity settings, a preferred output style, your own shortcuts. The developer who likes short answers says so here.

Project-level: .claude/CLAUDE.md or root CLAUDE.md

This file applies to everyone on the project. It lives in the repository and is version-controlled. Every developer who clones or pulls the repo gets these instructions automatically. Team-wide standards belong here: naming conventions, error handling patterns, testing requirements, architecture decisions, code review checklists. Both .claude/CLAUDE.md (inside the .claude directory) and a CLAUDE.md at the repository root are valid project-level locations. The practice's naming rules go here.

Directory-level: subdirectory CLAUDE.md files

These apply when you're working in that specific directory. Use them for package-specific conventions that differ from the project root. A /packages/api/CLAUDE.md , say, might hold REST conventions that the frontend package never needs. The booking API's REST conventions go in that package's CLAUDE.md.

The Anthropic memory docs are explicit: "All discovered files are concatenated into context rather than overriding each other". Every applicable file loads into the same context window.

CLAUDE.md files aren't a strict-precedence config: the docs describe a load order. Files run from broadest scope to most specific, so a project instruction appears after a user instruction. Across the directory tree, "content is ordered from the filesystem root down to your working directory". So "instructions closer to where you launched Claude are read last". Start a session in the booking API package and Claude reads the user, project, then package files.

Reading last does not win a conflict: nothing marks one file as the winner. The docs are blunt: "if two rules contradict each other, Claude may pick one arbitrarily". CLAUDE.md is delivered as a user message, not as part of the system prompt. Anthropic says "there's no guarantee of strict compliance". Treat CLAUDE.md as guidance the model usually follows, not as a configuration layer with deterministic overrides.

So don't lean on CLAUDE.md scoping for a rule that must hold on every run, such as a blocked tool, a required formatter or a permission policy. Put it in settings.json , which the client enforces regardless of what Claude decides. Or use a hook, which fires at a fixed lifecycle event. The docs say so directly: "Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude's behavior but are not a hard enforcement layer". A tool the practice must always block goes in settings.json .

Don't confuse CLAUDE.md with settings.json

settings.json has a strict precedence chain (managed policy > local > project > user, with managed always winning). CLAUDE.md does not: files are concatenated and conflicts may resolve arbitrarily. For "which CLAUDE.md wins on a conflict?", the docs-honest answer is "neither is guaranteed to; move the rule to settings.json or a hook". Watch for distractors claiming "more specific scope wins" or "user-level overrides project-level". The official docs say neither.

Past a few hundred lines, one CLAUDE.md becomes a slog to maintain. The @ syntax lets you split it across files and reference them from the main one. The directive is just @ followed by a path. There is no @import keyword, even though half the docs online write it that way.

For example:

# .claude/CLAUDE.md Coding standards: @./standards/naming-conventions.md @./standards/error-handling.md @./standards/testing-requirements.md Each @ line gets that file inlined into the CLAUDE.md at load time. Per-package CLAUDE.md files can import only the standards that apply to them. The API package pulls in API conventions and the frontend pulls in component rules, with no duplication. The practice's booking API does the same.

The docs say imported files load alongside the CLAUDE.md that references them. The file is inlined the moment Claude reads your CLAUDE.md, as if you'd pasted it in. Splitting a 600-line CLAUDE.md into six 100-line imports makes the source nicer to work in, but the context stays the same size. To shrink per-session context, use .claude/rules/ with path-scoped frontmatter (Task Statement 3.3). Those files only load when Claude is working in matching paths.

CLAUDE.local.md lives next to CLAUDE.md at any level in the hierarchy and loads the same way. Three small differences set it apart.

CLAUDE.local.md is a project-scoped version of ~/.claude/CLAUDE.md . A team rule belongs in CLAUDE.md instead. A practice developer's scratchpad path fits here; the testing requirements do not.

Instead of a single CLAUDE.md, the .claude/rules/ directory can hold topic-specific rule files.

Each file can optionally include YAML frontmatter with path scoping (Task Statement 3.3). Without frontmatter, rules files load for all sessions, so the practice's testing.md would load in every session.

When /compact summarises a long session, project-root CLAUDE.md comes back intact. Its location gives it no special status. Claude re-reads it from disk after compaction and re-injects it. Your instructions were never part of the conversation history, so the summariser has nothing there to compress.

Two things don't come back automatically: nested CLAUDE.md files in subdirectories, and .claude/rules/ files with paths: frontmatter. Both load on demand, so they return when Claude next reads a matching file, not when compaction ends. When an instruction seems to vanish after /compact , that's usually why. The other candidate is an instruction that only ever existed in conversation, which compaction is free to summarise. A naming rule typed only into a chat at the practice has no file to come back from.

When behaviour drifts between sessions or developers, check which memory files each session loaded. If Claude Code follows the conventions for one practice developer and ignores them for the other, that check settles it.

Current state (checked 6 October 2026): Claude Code splits the job across two commands. /memory lists your CLAUDE.md, CLAUDE.local.md and auto-memory locations, and opens any of them in your editor. /context reports what loaded at launch, under Memory files . To confirm a file is live, run /context and read that list. The docs say: "check the list under Memory files to verify the CLAUDE.md and CLAUDE.local.md files that should load at launch". Two kinds of file load on demand, so they are not on that list. They are a CLAUDE.md in a subdirectory of your working directory and a rule with paths frontmatter (Task Statement 3.3). When one loads, a Loaded line with its path appears in the terminal.

Key Concept

Neither command loads anything. They reveal which files are already loaded; configuration loads automatically based on its level and location. Use them to diagnose, not to activate.

Which level applies where, and spotting the wrong level, comes up again and again. Either project-level path may appear.

The favourite trap for Task Statement 3.1 is a new team member not receiving instructions. For months, Claude Code has followed the team's conventions for one teammate. A new teammate clones the repository and gets inconsistent results that ignore them. The root cause is always a configuration hierarchy problem. The conventions sit in the first teammate's user-level config ( ~/.claude/CLAUDE.md ), not the project-level config. User-level config is not shared via git, so the new teammate never received them. The fix is to move them to project-level configuration. At the practice, the naming rules would have sat in one developer's home directory.

Diagnose it on sight: when a stem pairs "new team member" with "inconsistent behaviour", check where the configuration lives.

The exam also tests that the diagnostic commands load nothing.

On the exam, answer /memory

The exam guide (v1.0) predates the split and treats /memory as the command that shows which files are loaded. Give /memory as the keyed answer. Run /context at your actual keyboard.

Source for the /memory and /context details: Claude Code memory docs .

A skill is a named, reusable set of instructions that Claude Code loads on demand. It is a Markdown file that tells Claude how to carry out one specific workflow. It can have supporting files and optional YAML frontmatter, a block of settings between --- lines at the top. You run a skill by typing its name as a slash command ( /deploy ). Claude also loads it itself when a request matches its description. CLAUDE.md is different: it loads every session, while a skill's instructions enter the conversation only when it runs.

Take a care home whose two developers maintain the app carers use to log medication rounds. They want a shared /meds-check skill for the checks before a medication change ships. One developer also runs long exploratory analyses of the rota code, for herself alone.

Custom commands and skills have been merged into one unified system, the Skills system. Two locations create slash commands that behave the same way. Their file structures differ.

Because SKILL.md is the required entrypoint, a flat file placed directly inside .claude/skills/ does not create a command. The .claude/skills/ path is the canonical location. .claude/commands/ still works for backward compatibility. Both paths produce the same /command , so existing .claude/commands/ files keep working unchanged. A command file accepts the same YAML frontmatter as a skill except name and paths . The skills path is recommended because it adds three features the commands alias lacks.

So the care home puts /meds-check in .claude/skills/meds-check/SKILL.md , with its checklist beside it as a supporting file. If a .claude/commands/meds-check.md remains, the skill wins.

Project scope means .claude/skills/ (canonical) or .claude/commands/ (alias) inside your repository. Both are version-controlled and shared via git. Every developer who clones or pulls the repository gets these commands automatically, so a committed skill is shared with everyone who works there. Use it for team-wide workflows.

User scope means ~/.claude/skills/ (canonical) or ~/.claude/commands/ (alias). These are personal, not version-controlled and not shared. A skill saved under the home directory loads in every project. Use it for individual productivity workflows that other team members do not need.

The care home's /meds-check goes in the project path, so both developers have it. The rota analysis is personal, so it goes under ~/.claude/skills/ .

A project command can also be one flat file in .claude/commands/ . This one gives the care home team a /review command:

Review the staged changes against our team checklist: 1. Check error handling patterns 2. Verify test coverage for new functions 3. Confirm API naming conventions 4. Flag any hardcoded credentials or secrets Key Concept

The scoping pattern is consistent across Claude Code: project-level ( .claude/ ) is shared via git; user-level ( ~/.claude/ ) is personal. This applies to CLAUDE.md, commands and skills, and rules. Memorise this pattern, because it appears throughout Domain 3. Keep the file shapes straight too: skills are directories with a SKILL.md inside; commands are flat .md files.

The objective names three frontmatter options: context: fork , allowed-tools and argument-hint . .claude/skills/ is the canonical location for configured skills.

context: fork

context: fork runs the skill in an isolated sub-agent context. The verbose output stays contained in the fork, and the main conversation stays clean. Without it, skill output flows into the main conversation and consumes context window tokens. For verbose skills, this degrades the quality of later responses. It suits three kinds of task.

The care home's rota analysis is codebase analysis, so its skill gets context: fork . If its owner names it /analyse-feature , the frontmatter sits at the top of ~/.claude/skills/analyse-feature/SKILL.md :

--- description : "Analyse a feature area of the codebase and report structure, patterns and risks" context : fork allowed-tools : - Read - Grep - Glob argument-hint : "Provide a feature description or area of the codebase to analyse" --- The description line is not one of the three the objective names. Leave it out of a real skill and Claude has nothing to match your request against. The skill then fires only when you type /analyse-feature yourself.

allowed-tools

allowed-tools pre-approves the listed tools, so Claude can use them without a permission prompt while the skill is active. It does not restrict which tools are available. Every other tool remains callable, and your normal permission settings still govern anything not listed. Use it to let a trusted workflow run without stopping to ask on each call, such as the rota analysis reading code.

Current state

Current state (checked 6 October 2026): this pre-approval behaviour is what Claude Code does. Exam guide v1.0 describes the field differently. On the exam, answer with the guide's wording, given at the end of this section.

--- allowed-tools : - Read - Grep - Glob --- To remove tools from Claude's pool while a skill runs, list them in disallowed-tools , or add deny rules in your permission settings. That is the actual security boundary.

argument-hint

argument-hint is a hint shown during autocomplete to indicate the arguments the skill expects. It improves the developer experience: the inputs are explicit, so nobody has to remember them. It is a label, not an interactive prompt: invoking the skill with no arguments does not stop and ask for them. For /meds-check , the hint could name the module path.

Current state

Current state (checked 6 October 2026): the skills frontmatter reference defines it as a "Hint shown during autocomplete to indicate expected arguments". Exam guide v1.0 describes it differently, and the keyed answer at the end of this section follows that wording.

--- argument-hint : "Specify the module path to analyse (e.g., src/api/auth)" --- Current state: description is the field that does the most work

Current state (checked 6 October 2026): the live field list is much longer, and the one you'll reach for first is description . It's what Claude reads to decide whether a skill applies to what you just asked. A skill without a useful one only ever runs when you type /name yourself. The docs mark it Recommended rather than required. Leave it out and Claude Code falls back to the first non-empty line of the skill body. That is usually a worse summary than one you'd write. Also live: disallowed-tools , disable-model-invocation , model , effort and when_to_use . (Source: Claude Code skills docs .)

Skills are on-demand, task-specific workflows. Their descriptions are always in context so Claude knows they exist, but the full body loads only when invoked. Invocation is explicit ( /skill-name ) or automatic. Claude picks up skills whose description matches the user's intent, or skills with a paths field when you're working on matching files. Skills with disable-model-invocation: true require explicit user invocation. CLAUDE.md holds always-loaded, universal standards, applied to every session with no invocation step.

So do not put task-specific procedures in CLAUDE.md, where they would load every session. Do not put always-on reference material in skills, where it would be absent until invoked. API naming conventions for every code generation task belong in CLAUDE.md (or .claude/rules/ ). A multi-step codebase analysis workflow run occasionally belongs in a skill. Conventions for one file type, such as test files, fit path-scoped .claude/rules/ best: they load as always-on context alongside matching files. So the care home's naming conventions go in CLAUDE.md.

Create personal variants in ~/.claude/skills/ (or ~/.claude/commands/ ) with different names, so teammates are not affected. A personal skill with its own name does not override or conflict with the team version. A care home developer who wants a more verbose /meds-check creates /deep-meds-check there.

The core distinction here is on-demand workflow versus persistent configuration, and the skills versus CLAUDE.md split is tested directly. Conventions for every edit mean CLAUDE.md or .claude/rules/ . Verbose output cluttering the main conversation means context: fork .

The exam guide (v1.0) names three frontmatter options, and a question will key on those; description is not on its list. For two of them, the keyed answer follows the guide, not the current product.

On the exam, answer with the guide's wording for both fields. The build exercise below uses current Claude Code behaviour.

Root CLAUDE.md loads for every session. A directory-level CLAUDE.md applies to files in that one directory. A path-specific rule loads its conventions only when you edit files matching its glob patterns. It covers what neither CLAUDE.md handles well: one file type scattered across many directories.

A catering firm's ordering system has team-wide standards, Terraform hosting files, and test files beside source files in many folders.

Rule files live in .claude/rules/ . Each starts with YAML frontmatter whose paths field lists glob patterns. The rules load only when you edit a matching file.

--- paths : [ "terraform/**/*" ] --- # Terraform Conventions - Use snake_case for all resource names - Tag every resource with environment and team labels - Never hardcode AMI IDs — use data sources - All modules must have a variables.tf, outputs.tf, and README.md Edit a file matching terraform/**/* and these rules load automatically. Edit a React component or an API handler and they don't. The catering firm's hosting conventions stay out of context while someone edits the menu pages.

In a glob, ** matches across directory levels. So **/*.test.tsx catches every test file in the codebase, wherever it sits. Take a typical project structure:

src/ components/ Button.tsx Button.test.tsx api/ auth.ts auth.test.ts utils/ format.ts format.test.ts pages/ dashboard/ Dashboard.tsx Dashboard.test.tsx Test files sit next to their source files across four directories. A rule with paths: ["**/*.test.tsx", "**/*.test.ts"] applies the same test conventions to every one of them, automatically.

A directory-level CLAUDE.md covers only its own directory. Test files across 50+ directories would need a CLAUDE.md in each. That means:

One rule file and one pattern avoid all four. The catering firm changes a test convention by editing one file.

Root CLAUDE.md loads in every session, whichever files you edit. Terraform conventions there use tokens while you edit React components. Test conventions there load while you write API handlers. The catering firm's hosting conventions would fill context during a menu fix.

Key Concept

Path-scoped rules are more token-efficient than root CLAUDE.md because they load only when you edit matching files. Less irrelevant context keeps the model focused on conventions that apply to the current work. In large projects with many convention categories, the saving is substantial.

--- paths : [ "**/*.test.ts" , "**/*.test.tsx" , "**/*.spec.ts" , "**/*.spec.tsx" ] --- # Test Conventions - Use describe/it blocks with descriptive names that read as sentences - Each test file must have at least one happy path and one error case - Use factory functions for test data, not inline object literals - Mock external services at the module boundary, not individual functions - Assert behaviour, not implementation details API conventions for any route handler yaml Copy yaml code --- paths : [ "src/api/**/*" , "**/routes/**/*" , "**/*.controller.ts" ] --- # API Conventions - All endpoints return { data, error, metadata } response shape - Use Zod schemas for request validation at the handler boundary - Log request ID on every error response - Rate limiting configuration must be explicit, not inherited from defaults Infrastructure-as-code conventions yaml Copy yaml code --- paths : [ "terraform/**/*" , "**/*.tf" , "infrastructure/**/*" ] --- # Infrastructure Conventions - State files must reference remote backends, never local - Use workspaces for environment separation - Every module must be versioned with a CHANGELOG When to Use Each Approach Scenario Best approach Universal team standards that apply to all code Root CLAUDE.md Conventions for one specific package directory Directory-level CLAUDE.md Conventions for a file type spread across many directories Path-specific rules with glob patterns Task-specific workflows invoked on demand Skills in .claude/skills/ The catering firm puts team-wide standards in root CLAUDE.md, and its test and Terraform conventions in path-specific rules.

The exam frequently presents test files co-located with source files across many directories. The answer is always path-specific rules with glob patterns. Wrong options use root CLAUDE.md or a CLAUDE.md in every directory.

Path-specific rules are one of Domain 3's six task statements. As of 2026, Anthropic has no standalone Claude Code certification , and no other exam tests Claude Code as heavily as this one.

Claude Code works in two main modes. In plan mode, Claude reads the codebase, analyses dependencies and proposes an approach without modifying any files. In direct execution, Claude skips the planning phase and makes changes straight away. Clear criteria decide which mode fits a task.

A wedding venue's booking system has four jobs. Two are small: a date bug with a clear stack trace and a deposit rate change. Two are bigger: a payment provider with two possible connections and a 30-file logging library swap.

Plan mode is for complex tasks where you need to explore the codebase, evaluate multiple approaches and design a strategy before making changes. Each needs the existing code understood before the first edit. Use it when:

At the venue, that means the payment job and the logging swap.

You switch into plan mode rather than ask for it. Three routes:

Claude then writes nothing to disk until you approve the plan. Writing "in plan mode" into the body of a prompt does nothing; /plan at the start of it does.

Direct execution is for well-understood changes with clear, limited scope. Use it when:

A plan settles design decisions. A simple, well-defined task has none, so planning adds nothing. The venue's date bug and deposit rate qualify: each fix is known.

Key Concept

The decision is about ambiguity, not difficulty. A difficult but well-defined bug fix (clear stack trace, single function, known cause) is direct execution. A seemingly simple feature request that could be implemented three different ways and affects multiple modules is plan mode.

The Explore subagent keeps verbose discovery output out of the main conversation. On multi-phase tasks, exploring produces file listings, dependency graphs, code excerpts and analysis notes. Left in the main conversation, that output fills the context window and degrades later responses.

The Explore subagent:

Use it when discovery is verbose but implementation needs focused context. Mapping the venue files that import the old logging library is one such discovery.

Plan mode for investigation, then direct execution for implementation, is a common combination. The pattern:

Deciding the pattern once gives every file the same change. The venue's 30-file logging migration splits like this:

Do not start in direct execution and wait for complexity to show up. When the requirements already say the task is complex, such as "restructure the monolith into microservices", choose plan mode straight away. That complexity will not emerge later; it is already in the task description. A venue request to split the booking system into separate services is that case.

The exam tests whether you can pick the right mode for a given task. The plan-then-execute hybrid is common, and the exam expects you to spot it: plan then direct, not plan or direct. A common trap is the late switch from direct execution to plan mode.

Plan mode falls under Domain 3, which carries 20% of the marks. No other Anthropic exam gives Claude Code that much weight, so this exam is the closest thing to a Claude Code certification .

Iterative refinement is steering Claude Code towards the right result over several rounds, since the first output is rarely the final one. It uses five techniques:

Take a guest house whose developer uses Claude Code on its booking website. Each situation below comes up there.

The techniques are not equal. They have a clear pecking order.

1. Concrete input/output examples (most effective for inconsistent interpretation). They are the most effective way to communicate an expected transformation when a prose description is interpreted inconsistently. The guest house developer describes a code change in prose, and Claude Code applies it differently each time. More precise prose still relies on interpretation, so more prose will not fix this. Provide 2-3 examples showing the exact input and the exact expected output:

Input: getUserData(userId: string): Promise Expected output: getUserData(userId: string): Promise> text Copy text code Input: fetchOrders(customerId: string): Promise Expected output: fetchOrders(customerId: string): Promise> The model generalises from examples more reliably than from any prose description. Two or three set the pattern, and the model applies it to new cases. It is the first technique to reach for when interpretation is inconsistent.

2. Test-driven iteration (most effective for complex transformations). Write the tests first. They define the expected behaviour, covering:

The guest house developer does this before migrating old booking records, then shares the failures with Claude Code. Each failure is concrete, unambiguous feedback: "Expected X, got Y" leaves no room for interpretation. The failure below tells Claude Code exactly what to fix, with no prose explanation:

FAIL: testMigrationHandlesNullValues Expected: null preserved in output JSON Actual: null replaced with empty string "" 3. Interview pattern (most effective for unfamiliar domains). In a domain where you lack expertise, have Claude ask questions before implementing, to surface considerations you would otherwise miss. The guest house developer has never built a cache, and the booking site needs one. Instead of prescribing a solution:

"Build me a caching layer for the API"

Use the interview pattern:

"I need a caching layer for the API. Before implementing, ask me questions about the requirements, edge cases, and constraints I should consider."

Claude might ask about cache invalidation strategies, TTL policies, consistency requirements and failure modes. An expert would know to address these, and the developer might overlook them.

Key Concept

The interview pattern is for unfamiliar domains, where the developer might miss considerations. Concrete examples are for when the developer knows the exact transformation but the model interprets it inconsistently. Do not confuse the two: they solve different problems.

How you deliver feedback depends on whether the fixes interact.

Single message (batch) when fixes interact with each other. Suppose changing the booking site's error handling pattern also affects its logging format and response structure. Send all three in one message. The model needs to see all the interacting constraints at once to produce a coherent fix:

Three changes needed (they interact with each other): 1. Error responses must include an error code field 2. Logging must include the error code in structured format 3. The client SDK type definitions must reflect the new error code field Sequential iteration when issues are independent. If a naming convention issue and an indentation issue do not affect each other, fix them one at a time. Batching independent issues can confuse the model about which feedback applies to which part of the code.

First iteration: "Fix the function naming — use camelCase throughout" [Wait for result] Second iteration: "Now update the indentation to use 2 spaces" Switching From Prose to Examples When prose descriptions produce inconsistent results, the switch to examples follows four steps:

Two or three well-chosen examples, covering the standard case and the main edge case, are enough. The model generalises the pattern, so it does not need every possible case.

The exam checks which technique you reach for first in each situation. The keyed answer follows this table:

These techniques belong to Domain 3, Claude Code Configuration & Workflows. The Claude Code certification explainer compares how heavily each of Anthropic's four exams tests Claude Code.

Claude Code is normally an interactive developer tool. In interactive mode it expects keyboard input and shows a conversational interface. A CI/CD pipeline is an automated job that runs when triggered, for example by a code change. A run with no person present is called headless. In a pipeline, Claude Code becomes an automated review and generation engine.

Take an off-licence chain with an online shop. Each pull request (PR) on the shop's code starts a pipeline, and the team wants Claude Code to review it there.

A CI pipeline has no keyboard. Without the -p flag, the job hangs forever, waiting for input that never comes. The off-licence's first review job hung this way.

# WRONG — hangs in CI claude "Analyse this pull request for security issues" # CORRECT — runs non-interactively claude -p "Analyse this pull request for security issues" The -p flag (also --print ) switches Claude Code to print mode. Claude Code processes the prompt, writes the result to stdout and exits, without waiting for user input. Running Claude Code in CI with -p prevents interactive input hangs. The off-licence adds -p , and its job finishes.

Key Concept

For CLI calls in CI, use claude -p . Logs showing Claude waiting for input mean the flag is missing.

In CI, no human reads the output. Automated systems process it to post inline PR comments, update dashboards or trigger downstream workflows, so it has to be machine-parseable. The off-licence wants each finding posted on the exact line it refers to. Two flags work together.

claude -p \ --output-format json \ --json-schema '{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"line":{"type":"integer"},"severity":{"type":"string"},"message":{"type":"string"}}}}}}' \ "Review this PR for security issues" The data that matches the schema lands in the envelope's structured_output field. Extract it with jq '.structured_output' , not from the top level. The validated findings can be used four ways.

When Claude writes code in a session, it builds up reasoning context: why it chose this approach, which trade-offs it considered, which alternatives it rejected. A review in the same session keeps all of that, so it is less likely to question decisions it already justified to itself. That makes the generating session less effective at reviewing its own changes, and the effect is measurable.

The fix is a separate Claude Code invocation for review, with no access to the generation session's reasoning context. It judges the code on its own merits, without the bias of prior justification. At the off-licence, one claude -p call writes a new age check for checkout and a second, independent call reviews it.

# Step 1: Generate code (session A) claude -p "Implement the authentication middleware" # Step 2: Review code (session B — independent, no shared context) claude -p "Review the authentication middleware for security issues, error handling gaps, and edge cases" This connects to Domain 4 (multi-instance review architectures) and Domain 5 (context management).

Automated reviews run on every push. Without context about earlier reviews, each run analyses the whole PR from scratch and re-derives the same findings. A fixed issue drops out on its own, because the changed code no longer triggers it. What keeps coming back are the issues the developer saw and chose not to change. A re-scan with no context cannot tell those apart from new problems, so it flags them on every push.

Say an off-licence developer keeps a hard-coded postcode list on purpose. Every review flags it again. The fix is to include prior findings in context and tell Claude to report only new or still-unaddressed issues.

claude -p \ --output-format json \ "Review this PR. Here are the findings from the previous review: ${ PREVIOUS_FINDINGS } Report ONLY: 1. New issues not in the previous findings 2. Issues from the previous findings that are still present Do NOT re-report previous findings the developer has already reviewed and chosen not to act on." Duplicate comments erode developer trust. If every push brings the same five comments whether or not the issues were fixed, developers stop reading them. Incremental review context preserves the signal-to-noise ratio.

In CI, Claude Code reads the project's CLAUDE.md files exactly as it does interactively. So CLAUDE.md is how you give a CI run project-specific context.

Without this context, CI test generation produces low-value boilerplate. With it, generated tests follow the team's patterns and add genuine coverage. If the off-licence's CLAUDE.md names its test factories, CI runs use them.

# .claude/CLAUDE.md — CI-relevant section ## Testing Standards - Tests must use the factory pattern from test/factories/ for data creation - Integration tests connect to the test database via test/setup/db.ts - Do not test private implementation details — test public API contracts - Coverage target: 80% branch coverage for new code - Available fixtures: test/fixtures/users.json, test/fixtures/orders.json CLI Flags Reference Beyond -p , other flags shape a headless run: how output is formatted, which system prompt is used, and how permissions and tools are scoped. They work with claude -p in CI and with the interactive claude command.

System prompt flags. Claude Code has four.

The default system prompt holds Claude Code's tool guidance, safety instructions and coding conventions. Appending keeps all of that, so you only supply what differs. Use it when Claude should stay a coding assistant that also follows your extra rules. Replacing drops the entire default prompt, so you own everything the task still needs. Use it when the identity or permission model differs from Claude Code's, such as a non-coding agent in a pipeline no human watches. The off-licence's reviewer stays a coding assistant, so it appends.

Headless output and limits (print mode).

Permissions, tools, and context.

Session and start-up. -c / --continue resumes the most recent conversation in the current directory, and -r / --resume resumes a specific session. --bare is minimal mode. It skips auto-discovery of hooks, skills, plugins, MCP servers, auto memory and CLAUDE.md, so scripted calls start faster. Claude keeps only the Bash and file read/edit tools. Use it for a fast, predictable scripted run that needs no project configuration. The off-licence's review needs its CLAUDE.md, so it skips --bare .

Beyond the guide

Task Statement 3.6 describes CI/CD integration through the -p flag, output formats and session isolation. It never names GitHub Actions. Verified against the GitHub Actions page of the Claude Code docs on 16 September 2026.

Anthropic's pipeline integration is a GitHub Action, anthropics/claude-code-action@v1 , that runs Claude Code non-interactively inside a workflow job. It is built on the Agent SDK and accepts the same CLI flags as a headless claude -p run. Two settings decide how a workflow behaves.

Mode follows the prompt input. With no prompt , the action runs in interactive mode. It waits for the trigger phrase ( @claude by default) in an issue or PR comment and answers there. With a prompt , it runs in automation mode on whatever event fired the workflow, such as a PR opening or a cron schedule, without waiting for a mention. It writes its result to the workflow run log, unless the prompt tells it to post somewhere and it has a tool that can. With a plain-text prompt, Claude has no shell or GitHub API access until the workflow grants the tools it needs. It grants them with --allowedTools in claude_args or a permissions.allow rule in the settings input. The off-licence wants a review on every new PR, so it sets a prompt that asks for comments and grants a tool that can post them.

CLI flags go through claude_args . There is no separate action input for the system prompt, the tool allowlist or the turn cap. You pass the flags from the reference tables as one string: --append-system-prompt , --allowedTools , --max-turns , --model , --mcp-config . So adding review criteria without replacing the default behaviour is --append-system-prompt inside claude_args , as on the command line. Of the pre-v1 inputs, custom_instructions became --append-system-prompt and direct_prompt became prompt . mode went away because the action now infers it.

name : Claude Code on : issue_comment : types : [ created ] pull_request_review_comment : types : [ created ] jobs : claude : if : contains(github.event.comment.body, '@claude') runs-on : ubuntu-latest permissions : contents : write pull-requests : write issues : write id-token : write actions : read steps : - uses : actions/checkout@v6 with : fetch-depth : 1 - uses : anthropics/claude-code-action@v1 with : anthropic_api_key : ${{ secrets.ANTHROPIC_API_KEY }} claude_args : | --append-system-prompt "Review against the checklist in CLAUDE.md. Report only critical findings." --allowedTools "Read,Grep,Glob,Bash(git diff *)" --max-turns 10 How files reach Claude: actions/checkout puts the repository on the runner, so without that step there is nothing on disk to read. Claude reads the PR itself through the GitHub tools the action provides. The permissions block bounds what it can write back. id-token: write is required for the action's default GitHub App authentication. actions: read lets it see CI results on the PR. The credential is a repository secret, never a literal in the file: anthropic_api_key for an API key or claude_code_oauth_token for a subscription token.

Beyond the guide

Verified against the worktrees page of the Claude Code docs on 16 September 2026.

A git worktree is a second working directory for the same repository, on its own branch, sharing the same history. Run each Claude Code session in its own worktree and edits in one session never touch files in another. So three instances can extract three services from one monolith at the same time and commit to the same repository without colliding. Each session also gets its own full context budget. The off-licence could split its shop this way into stock, orders and payments, one session each.

claude --worktree creates one under .claude/worktrees// on a branch called worktree- and starts the session inside it. git worktree add ../project-feature -b feature does the same by hand, with a path and branch of your choosing.

Nothing locks a shared file. Sessions coordinate by sequence: the first session merges, and the second rebases onto the result before touching it. A custom subagent can run in its own worktree with isolation: worktree in its frontmatter, so parallel subagent edits do not collide either.

When test generation runs in CI, include the existing test files in context. Without them, Claude Code may suggest tests that already exist, wasting developer review time. With them, Claude can find coverage gaps instead of duplicating existing scenarios. If the off-licence already tests its basket totals, the run looks for gaps elsewhere.

The Message Batches API offers 50% cost savings, but processing takes up to 24 hours with no guaranteed latency SLA. That creates a clear decision boundary.

Pre-merge checks are blocking workflows: developers cannot merge until the check completes. The Batch API gives no latency guarantee, so it is unsuitable for them. The off-licence's PR review runs in real time, while its weekly code audit can use the Batch API.

The exam tests five concepts under Task Statement 3.6. The -p flag is the single most directly tested fact in Domain 3. It is Question 10 in the official sample questions. The stem shows a CI job hanging with Claude waiting for input and asks for the fix. The answer is always -p : pure memorisation. CLAUDE_HEADLESS=true and --batch do not exist. Stdin redirection from /dev/null does not properly address Claude Code's interactive mode.

Session isolation is tested in CI/CD scenarios specifically. The exam also expects familiarity with the headless flags, and it tests append versus replace. Sample Question 11 tests the batch boundary directly.

GitHub Actions and worktrees go beyond the guide but are worth knowing. Three readers who sat the exam report four or five questions on GitHub Actions. The guide does not mention worktrees, but large refactors run on parallel Claude Code instances, so the practice questions include them.

A system prompt holds the standing instructions Claude follows for every input. In a review task, explicit categorical criteria define precisely what the model should flag and what it should skip. A false positive is a finding that is wrong. Vague instructions, such as "be conservative", "only report high-confidence findings" or "use your best judgement", define neither. Relying on them is the single biggest mistake in production prompt engineering.

A delicatessen uses Claude to check product labels against recipe cards. Its prompt says to be conservative. Staff get real allergen errors mixed with wrong flags on wording.

Vague instructions give the model no actionable decision boundary. "Conservative" means different things in different contexts. "High-confidence" is a subjective threshold the model cannot calibrate.

The prompt below gives the model no criteria to apply.

Review this code. Be conservative. Only report high-confidence findings. This one gives concrete categories.

Flag comments only when claimed behaviour contradicts actual code behaviour. Report bugs and security vulnerabilities. Skip minor style preferences and local patterns. It names what to report (bugs, security), what to skip (style, local patterns) and a specific trigger for comment flags: claimed behaviour contradicting actual behaviour. The delicatessen's version: flag labels missing a recipe-card allergen; skip wording.

High false positive rates in one category destroy developer trust in every category, including accurate ones. Trust spreads across the whole output. If the delicatessen's wording flags are wrong 40% of the time, staff stop reading its allergen flags too, even at 98% accuracy.

The fix is to temporarily disable the high false positive categories while you rework their prompts. With the wrong flags gone, trust in the working categories returns straight away. Iterate on the broken category with concrete code examples, and switch it back on only once precision improves. The delicatessen pauses its wording flags. System-wide trust comes ahead of category completeness.

A severity level ranks how serious a finding is. Defining severity levels requires concrete code examples, not prose descriptions.

This prose description is insufficient.

Critical: Issues that could cause system failures or data loss Minor: Issues that affect code readability but not functionality This code example approach is correct.

Critical — Unsanitised user input in SQL query: query = f"SELECT * FROM users WHERE id = {user_input}" Minor — Inconsistent variable naming: userName vs user_name in the same module The prose forces the model to interpret what "could cause system failures" means. The code example removes that ambiguity. When the model sees actual code patterns classified at each severity level, it classifies consistently across invocations. The delicatessen would show a sample label per level.

Key Concept

Explicit categorical criteria always outperform vague instructions and confidence-based filtering.

LLM self-reported confidence is poorly calibrated. The model is often sure about wrong findings and hesitant about right ones. Confidence scores are useful for routing low-confidence findings to human review (Task Statement 4.6). They are no substitute for explicit criteria that define what counts as a valid finding. The order is explicit criteria first, confidence-based routing second. Never skip the first step. The delicatessen writes its allergen criteria, then routes low-confidence flags to a person.

Vague instructions sound reasonable, which is why the exam uses them as distractors. The exam frequently offers "only report high-confidence findings" as a tempting answer, because keeping only strong signals sounds like good engineering. It also leans hard on the trust problem.

Few-shot prompting means putting a few worked examples in the prompt, each an input and the output you want, ideally with the reasoning behind it. They are the most effective technique for consistent, well-formatted output from Claude. More instructions, confidence thresholds and temperature adjustments all do less. When output is inconsistent, reach for them first.

Take a fishmonger that uses Claude to write its price board, sort customer messages and read supplier invoices.

1. Detailed instructions alone produce inconsistent formatting. The prompt specifies the format in detail, yet the structure changes between runs: a bulleted list, then a table, then prose. More instructions rarely fix this. A few examples showing the exact format are the most effective fix. Two price boards in the fishmonger's layout show the model what to copy.

2. The model makes inconsistent judgement calls on ambiguous cases. A code review tool flags variable shadowing as "critical" in one file and "minor" in another. A tool selection agent routes "check my order" to different tools depending on phrasing. The fishmonger's sorter does the same with "where is my salmon?" These ambiguous cases need examples showing the correct judgement, with reasoning.

3. Extraction tasks return empty or null fields for information the document contains. The information is there in an unexpected format: inside narrative text instead of a structured table, or split across several paragraphs. Few-shot examples showing extraction from varied document structures address this. A supplier to the fishmonger writes "twelve kilos of hake at nine pounds a kilo" in a sentence, and its invoices come back with the price field empty.

Use 2 to 4 targeted examples. Fewer than 2 does not establish a pattern. More than 4 wastes tokens without proportional benefit. Aim them at the specific ambiguous cases causing problems.

Each example must show reasoning. Beyond the input and output, it says why one action was chosen over plausible alternatives. The reasoning teaches the model to generalise its judgement to novel patterns, instead of only matching the cases in your examples.

Example: Tool selection for "check my order #12345" Input: "check my order #12345" Selected tool: lookup_order Reasoning: The user provides an order number (#12345), indicating they want order-specific information. Even though this could be interpreted as a general customer query, the specific order identifier makes lookup_order the correct choice over get_customer. Without the reasoning, the model learns only "queries mentioning order numbers go to lookup_order." With it, the model learns the general principle: specific identifiers route to specific lookup tools. The fishmonger's sorter learns that an order number means the order lookup.

Cover the failing cases. If extraction works on tables but fails on narrative text, show correct narrative extraction. If code review is inconsistent on variable shadowing, classify shadowing cases at different severity levels, with reasoning.

Few-shot examples also cut hallucination in extraction tasks. The model sees correct extraction from varied structures: inline citations and bibliographies, narrative descriptions and structured tables, headers and embedded text. From those it learns to handle structural variety without inventing data.

This matters most for documents with inconsistent formatting. A financial report might list expenses in a table on one page and in a paragraph on the next. Without examples, the model often gets the table right but returns empty fields for the narrative section, or fabricates values. Show it both structures and extraction quality improves. The fishmonger's invoices need an example of each kind.

In code review and analysis, few-shot examples show what to flag and what to ignore. Examples separating acceptable patterns from genuine issues cut false positives and still catch real problems.

Example: Variable shadowing assessment Code: function process(items) { const result = items.map(item => { const result = transform(item); // shadows outer 'result' return result; }); return result; } Severity: minor Reasoning: The inner 'result' shadows the outer variable but within a limited scope (arrow function). The code is still readable and the shadow does not cause a bug. This is a style preference, not a defect. Flag as minor only if style consistency is in scope. This example teaches the model to tell genuine bugs from benign patterns. False positives fall, and the model can still generalise to shadowing that is a real problem. The fishmonger's sorter can use the same approach, with examples of routine questions and real complaints showing it what to flag and what to ignore.

Key Concept

Few-shot examples are the most effective technique for consistency. Use 2 to 4 targeted examples, with reasoning, when instructions alone give inconsistent results, ambiguous judgements, or empty fields for data that exists.

The exam presents scenarios where detailed instructions produce inconsistent results and asks whether you would "add more instructions" or "add few-shot examples." The answer is almost always the latter. It also tests whether you can tell when another technique applies instead:

Structured output is a reply whose fields and types match a fixed shape. A JSON schema defines that shape: fields, types and which are required. With tool_use , Claude replies by calling a tool whose arguments fill its schema. Prompt-based JSON asks for JSON in a text response.

Take a bookkeeping firm whose ledger software imports fields from client invoices, receipts and contracts. An unparseable reply stops the import; a wrong value posts a wrong entry.

For guaranteed schema-compliant output there is a two-tier reliability hierarchy: tool_use with JSON schemas, then prompt-based JSON. With tool use, the tool's JSON schema constrains the shape of what Claude returns. That eliminates syntax errors such as missing brackets, trailing commas and unquoted keys. Prompt-based JSON is plain text with no structural guarantees. The model can produce malformed JSON and periodically will in production, failing the firm's import. The separate tool_choice parameter is what forces the model to call the tool at all.

tool_choice controls whether and how the model calls tools, in three modes.

"auto" (default): The model decides whether to call a tool or return text. It may answer in text instead of calling the extraction tool, say for the firm's faded receipt. Use this when the model legitimately needs the option to respond conversationally.

"any" : The model must call a tool but chooses which one. Use this when there are multiple extraction schemas (e.g., extract_invoice , extract_receipt , extract_contract ) and the document type is unknown, as with the firm's unsorted post. The model picks the appropriate tool: guaranteed structured output, flexible tool selection.

{"type": "tool", "name": "extract_metadata"} : The model must call the specific named tool. Use this to force a mandatory first step, such as metadata extraction before enrichment steps. No flexibility, maximum control.

extract_metadata is your own tool; the name is arbitrary. tool_choice applies per request, not per conversation. Once the forced call returns, send the next request with auto or omit the parameter; otherwise the model must call the same tool again and you loop.

// Force guaranteed structured output with unknown document type const response = await client.messages. create ({ model: "claude-sonnet-5" , max_tokens: 4096 , tool_choice: { type: "any" }, tools: [extractInvoiceTool, extractReceiptTool, extractContractTool], messages: [{ role: "user" , content: documentText }] }); // Force a specific extraction step const response = await client.messages. create ({ model: "claude-sonnet-5" , max_tokens: 4096 , tool_choice: { type: "tool" , name: "extract_metadata" }, tools: [extractMetadataTool], messages: [{ role: "user" , content: documentText }] }); What tool_use Does NOT Prevent tool_use with JSON schemas eliminates syntax errors but does not prevent semantic errors, where valid JSON holds wrong content.

All three pass the schema and land in the firm's ledger, because the schema guarantees structure, not correctness. Semantic validation needs additional logic, covered in Task Statement 4.4.

Good schema design prevents entire classes of errors at the structural level.

Optional/nullable fields. When a source document may lack some information, make those fields optional or nullable. This is the primary defence against fabrication. A required field pressures the model to produce a value even when the source has none. A nullable one lets it honestly return null . Many of the firm's receipts have no purchase order; requiring that field invites an invented one.

{ "type" : "object" , "properties" : { "invoice_number" : { "type" : "string" }, "vendor_name" : { "type" : "string" }, "payment_terms" : { "type" : [ "string" , "null" ] }, "purchase_order" : { "type" : [ "string" , "null" ] } }, "required" : [ "invoice_number" , "vendor_name" ] } "unclear" enum value. Add an explicit "unclear" option to enum fields for genuinely unclear sources. Otherwise the model must force a classification, as with a torn scan that could be a receipt or an invoice.

"other" + detail string. For extensible categorisation, pair an "other" enum value with a freeform detail string field. It captures edge cases your predefined categories do not cover, such as a client's bank statement.

{ "category" : { "type" : "string" , "enum" : [ "invoice" , "receipt" , "contract" , "unclear" , "other" ] }, "category_detail" : { "type" : [ "string" , "null" ], "description" : "Freeform detail when category is 'other'" } } Format normalisation rules. Put format normalisation instructions in the prompt alongside the schema. The schema enforces structure. The prompt enforces formatting consistency, such as "All dates in ISO 8601 format" or "All currency amounts as decimal numbers without currency symbols".

Key Concept

tool_use with a JSON schema stops syntax errors, not semantic ones. Optional or nullable fields stop fabrication when a source may lack information. tool_choice "any" guarantees structured output for unknown document types.

The exam builds on the two-tier hierarchy and the three tool_choice modes; answer with them even where the API has moved on (note below). Guaranteed structured output for an unknown document type means any . The usual trap is believing tool_use prevents all extraction errors.

Current state

Exam guide v1.0 frames the hierarchy as the two tiers above. Current state (checked 6 October 2026): the API adds two controls the guide predates. strict: true on a tool definition is one; the guide's appendix names it "strict mode for syntax error elimination". output_config.format is the other; it constrains the response itself rather than a tool call. The docs list a fourth tool_choice mode, {"type": "none"} , which blocks tool calls and is the default when you pass no tools. The guide names three, so answer three.

As of 6 October 2026, the define-tools page says Claude Opus 5.5, Sonnet 5.5, Fable 5.1 and Mythos 5.1 reject forced {"type": "any"} and {"type": "tool"} with a 400 error. Manual extended thinking rejects both on any model. On those, the documented route is "auto" with strict: true , or output_config.format when the response itself needs a fixed JSON shape. The claude-sonnet-5 model in the code above isn't on that list.

An extraction pipeline asks Claude to turn a document into structured fields. Validation checks them against rules; a retry asks the model again. Production extraction systems fail: documents arrive in unexpected formats, numbers do not add up, fields land in the wrong places. A validation-retry loop turns those failures into a self-correcting workflow.

Take a solicitors' firm extracting supplier invoices. Each extraction holds line items, a stated total and a matter reference. One expert's invoice has line items summing to less than its stated total. Another names no matter reference at all.

Schema syntax errors are malformed JSON, missing required fields and wrong data types. tool_use with JSON schemas eliminates them when strict: true is set (Task Statement 4.3). Semantic validation errors have correct structure but incorrect values: line items that do not sum, dates in the wrong order, values in wrong fields. A schema cannot say that two numbers must agree, so these errors need validation logic outside it and are the focus of retry loops. The expert's invoice is one.

The correct retry pattern sends three pieces of information back to the model.

// Retry with error feedback const retryMessages = [ { role: "user" , content: `Original document: \n ${ originalDocument } \n\n ` + `Your extraction: \n ${ JSON . stringify ( failedExtraction )} \n\n ` + `Validation error: Line items sum to £450 but stated_total is £500. ` + `Please re-extract, ensuring all line items are captured.` } ]; This beats a naive retry by a wide margin. Without the specific error, the model has no guidance and usually repeats the mistake. With it, the model can re-examine the document for missed line items, check field placement or recalculate the total. Told the expert's items fall short, it looks for the missed line.

A retry only lets the model look again at what it was given. Retries are effective for four kinds of error.

They are not effective in three cases.

If a value is genuinely absent, no amount of retrying will produce a correct one. Flag the extraction for human review, or return null if the schema allows it. The expert's invoice is fixable: the missing line is on the page. The unreferenced invoice goes to a person.

You can also build self-correction into the schema itself.

calculated_total vs stated_total : extract both the model's sum of the line items and the document's stated total. When they differ, you have a discrepancy flag without external logic. The expert's invoice would arrive flagged.

{ "line_items" : [ { "description" : "Widget A" , "amount" : 150.00 }, { "description" : "Widget B" , "amount" : 300.00 } ], "calculated_total" : 450.00 , "stated_total" : 500.00 , "total_discrepancy" : true } conflict_detected booleans: add booleans that flag contradictory information in the source document. One section might say "payment due: 30 days" and another "payment terms: net 60". The model should extract both and set conflict_detected: true rather than silently pick one. A counsel's fee note with two payment terms would arrive flagged.

For code review and analysis pipelines, add detected_pattern fields to structured findings. Each records which specific code construct triggered the finding.

{ "finding" : "Potential SQL injection vulnerability" , "severity" : "critical" , "detected_pattern" : "string concatenation in SQL query" , "file" : "user_service.py" , "line" : 42 } You can then analyse dismissed findings by detected_pattern . A pattern developers consistently dismiss, such as "variable shadowing in nested scope", likely needs prompt refinement. That gives a systematic improvement loop: extract, validate, collect dismissal data, refine prompts, repeat.

In a Python pipeline, Pydantic turns "validation failed" into the specific, per-field error messages the retry loop needs. A Pydantic model does two jobs. Parsing enforces structure: types, required fields, enums. Validators enforce semantics, the rules a JSON schema cannot express, such as cross-field arithmetic or date ordering. Both failure kinds surface through one ValidationError , whose machine-readable errors name the field and the broken rule. The validator below is the check the expert's invoice fails.

import json from pydantic import BaseModel, ValidationError, model_validator class LineItem ( BaseModel ): description: str amount: float class Invoice ( BaseModel ): line_items: list[LineItem] stated_total: float @model_validator ( mode = "after" ) def totals_must_match (self): calculated = round ( sum (i.amount for i in self .line_items), 2 ) if abs (calculated - self .stated_total) > 0.01 : raise ValueError ( f "line items sum to { calculated } but stated_total is { self .stated_total } " ) return self try : invoice = Invoice.model_validate(tool_input) # the tool_use input from the response except ValidationError as e: errors = " \n " .join( f " { '.' .join( map ( str , err[ 'loc' ])) or 'invoice' } : { err[ 'msg' ] } " for err in e.errors() ) retry_message = ( f "Original document: \n{ original_document }\n\n " f "Your extraction: \n{ json.dumps(tool_input) }\n\n " f "Validation errors: \n{ errors }\n\n " f "Please re-extract, fixing the identified errors." ) The except branch is retry-with-error-feedback, with Pydantic supplying the specific error ready to format into the prompt. The boundary still applies: a validator failing on information absent from the source means human review, not a retry.

Key Concept

Retry-with-error-feedback sends the original document, the failed extraction and the specific validation error. Retries fix format and structural errors but cannot create absent information. Identify whether a failure is fixable before retrying.

The retry effectiveness boundary is the concept the exam tests most aggressively in this task statement. It presents both kinds of failure and expects you to identify which is fixable. It also tests that tool_use solves schema syntax errors but not semantic ones. The overlap with Task Statement 4.3 is intentional. The exam guide names Pydantic alongside JSON Schema in its hands-on exercise for this task statement. It reads: "when Pydantic or JSON schema validation fails, send a follow-up request including the document, the failed extraction, and the specific validation error".

Current state: SDK-level parsing and strict tool use

Current state (checked 6 October 2026): the Python SDK's client.messages.parse(..., output_format=Invoice) returns validated Pydantic instances via parsed_output . As of the same check, strict: true on a tool definition guarantees schema-conformant inputs server-side ( Structured Outputs ). Neither removes the semantic layer. The platform enforces the schema, your validators enforce the business rules, and the retry loop consumes whichever one fails.

The Message Batches API takes many requests in one submission and returns the results later. It is a cost optimisation tool with hard constraints. A synchronous call sends one request and waits for its answer. A blocking workflow has someone or something waiting for the result. A latency-tolerant workflow consumes its results later.

Take an insurance broker. Staff on the phone need a policy summary while the client holds: that is blocking. Overnight extraction of cover details from renewal documents, read by the team next morning, is latency-tolerant.

Use the synchronous API for blocking workflows and the batch API for latency-tolerant ones. A batch has no latency guarantee and can take 24 hours, so anyone waiting could wait all day. An overnight job loses nothing by waiting, and costs half as much.

Blocking workflows include:

Latency-tolerant workflows include:

The broker keeps phone summaries synchronous, because a client is holding, and batches the renewal extraction.

The first call below is synchronous; the second is a batch.

// Synchronous — developer is waiting for this const preMergeReview = await client.messages. create ({ model: "claude-sonnet-5-5" , max_tokens: 4096 , messages: [{ role: "user" , content: prDiffContent }] }); // Batch — results consumed tomorrow morning const batchRequest = await client.messages.batches. create ({ requests: technicalDebtDocuments. map (( doc , i ) => ({ custom_id: `debt-report-${ i }` , params: { model: "claude-sonnet-5-5" , max_tokens: 4096 , messages: [{ role: "user" , content: doc }] } })) }); Multi-Turn Tool Calling Limitation The batch API does not support multi-turn tool calling within a single request. You cannot:

A workflow that needs tool execution mid-processing must use the synchronous API for that step. If the broker's overnight job queried its rates database mid-document, that step would run synchronously.

Plan batch schedules for the full 24 hours: it is a maximum window, not a delivery guarantee. A batch that does not finish inside it comes back expired . Size the schedule against that worst case, and treat an expired batch as a resubmission.

Say the broker promises renewal summaries within 30 hours. Work backwards:

A document arriving just after a submission waits for the next batch. On a 6-hour cadence it can wait 6 hours, then take 24 to process, using all 30.

Not all documents in a batch succeed. The correct failure handling has three steps.

1. Identify failures by custom_id . Each request has a unique identifier. Parse the batch results to find which custom_id values failed.

2. Resubmit only failures with modifications. Resubmitting the entire batch pays again for documents that already succeeded. Common modifications include:

3. Refine prompts on a sample set before batch processing. This proactive step maximises first-pass success and reduces resubmission costs.

The handler below retries only failed and expired results.

// Poll until the batch has finished before reading results let batch = await client.messages.batches. retrieve (batchId); while (batch.processing_status !== "ended" ) { await new Promise ( r => setTimeout (r, 60_000 )); batch = await client.messages.batches. retrieve (batchId); } // results() returns a JSONL async iterable, not an array — accumulate it. // Treat `expired` as a failure too: that is what an overrun batch returns. const failedIds : string [] = []; for await ( const result of client.messages.batches. results (batchId)) { if (result.result.type === "errored" || result.result.type === "expired" ) { failedIds. push (result.custom_id); } } // Resubmit only failures with modifications const retryRequests = failedIds. map ( id => { const originalDoc = documentsById[id]; return { custom_id: `${ id }-retry-1` , params: { model: "claude-sonnet-5-5" , max_tokens: 8192 , // increased for oversized docs messages: [{ role: "user" , content: chunkIfNeeded (originalDoc) }] } }; }); Prompt Optimisation Before Batch Submission The most cost-effective batch strategy is to refine prompts before submitting large volumes. The broker's sample would cover renewal documents from several insurers.

Every failed document costs a retry, so this workflow cuts total cost. A 90% first-pass success rate on 1,000 documents means only 100 retries. A 60% rate means 400 retries: four times the resubmission cost, plus the batch processing cost for those retries.

Key Concept

Batch only latency-tolerant work. Keep blocking work synchronous. Refine prompts on a sample set first.

The matching rule is the single most tested concept in this task statement. In Question 11 of the sample questions, a manager proposes switching everything to batch for the saving. The correct answer keeps blocking workflows synchronous and batches only latency-tolerant ones.

The tool limitation is a direct test point: a batch workflow that calls external tools during processing needs the synchronous API for that step. A scheduling question may work backwards from an SLA to a submission frequency.

Current state

Exam guide v1.0 states the limitation exactly as above, and that is the keyed answer. Current state (checked 6 October 2026): Anthropic's batch processing docs split it by tool type. Server tools (web search, web fetch, code execution, MCP connectors, advisor and tool search) run the same server-side agentic loop in a batch request as they do synchronously. A batch result can return stop_reason: "pause_turn" , which you continue in a follow-up request. Client tools, which your own code executes, still cannot complete a loop inside a batch item. The request ends at tool_use ; you run the tool after retrieving the result, then submit a follow-up. For a tool your own code runs (an internal lookup, a database query), the guide and the docs agree. On the exam, answer per the guide.

Self-review means a model checking its own output in the same conversation session. An independent instance is a separate Claude invocation without that prior reasoning context. Attention dilution is uneven attention when one pass reviews too much at once. A confidence score is the model's own report of its certainty about a finding.

A mortgage broker has Claude extract income and outgoings from a client's application pack: payslips, bank statements, a credit report and a valuation. Claude then reviews its own extraction.

In self-review, the model retains its original reasoning chain. It already "knows" why it chose each approach, classified each finding at a particular severity, or selected certain values. So it tends to confirm those decisions rather than challenge them. This is how self-review works in one session; design around it. If Claude counted a large transfer as salary, a same-session review still holds that reason and is likely to pass the figure again.

An independent instance judges the output on what it sees alone, without the bias of "I chose this because...". That makes it much better at catching subtle issues.

// Anti-pattern: self-review in the same session const generation = await client.messages. create ({ messages: [ { role: "user" , content: "Write a function to process orders" }, { role: "assistant" , content: generatedCode }, { role: "user" , content: "Now review your code for bugs" } // Model retains its reasoning — less likely to find its own mistakes ] }); // Correct: independent review instance const review = await client.messages. create ({ messages: [ { role: "user" , content: `Review this code for bugs, security issues, and edge cases: \n\n ${ generatedCode }` } // Fresh instance — no prior reasoning context ] }); Multi-Pass Review Architecture Large reviews (multi-file PRs, complex extraction pipelines, broad code audits) suffer from attention dilution in a single pass. The symptoms:

One pass over the broker's pack might check the first payslip line by line, skim the third statement, and flag a transfer it approves elsewhere. The fix is to split the review into focused passes.

Pass 1: Per-file local analysis. Each invocation reviews one file with a focused prompt, so that file gets full attention and every file gets consistent depth.

Pass 2: Cross-file integration. Once every file is done, a separate pass receives all the per-file findings. It checks data flow between modules, consistent API usage across services, dependency conflicts, and contradictions in the per-file findings themselves. It catches cross-file issues that no single-file review would identify, such as payslip salary that differs from the statement credits. Keeping the passes separate stops contradictory findings appearing in the same output.

// Pass 1: Per-file analysis const perFileFindings = await Promise . all ( files. map ( file => client.messages. create ({ messages: [{ role: "user" , content: `Review this file for local issues (bugs, security, logic errors): \n\n ${ file . content }` }] }) ) ); // Pass 2: Cross-file integration const integrationReview = await client.messages. create ({ messages: [{ role: "user" , content: `Given these per-file findings, identify cross-file issues: \n ` + `- Data flow inconsistencies between modules \n ` + `- Contradictory patterns flagged in different files \n ` + `- API contract violations across service boundaries \n\n ` + `Findings: \n ${ JSON . stringify ( perFileFindings )}` }] }); Why Larger Context Windows Do Not Fix This A bigger context window holds the broker's whole pack, but the model still spreads its attention unevenly across files. The problem is attention quality, not context size. Only focused per-file passes give consistent depth.

For uncertain findings, the model can self-report confidence alongside each finding. The score is the model's read on its own certainty, not self-reported accuracy. It allows routing:

A broker finding such as "may be a one-off bonus" at low confidence goes to an adviser.

{ "finding" : "Potential race condition in order processing" , "severity" : "major" , "confidence" : 0.65 , "reasoning" : "The lock acquisition pattern appears correct but the unlock timing depends on an async callback whose ordering I cannot fully verify." , "route" : "human_review" } A raw score is uncalibrated, so it is unreliable for automated decisions. Calibrate it by running labelled examples (where you already know the answer, such as the broker's past packs) through the system. Measure how reported confidence tracks actual accuracy, then adjust routing thresholds from that data. A threshold validated against labelled sets is suitable for routing. Using uncalibrated confidence for automated decisions is an anti-pattern.

Key Concept

Use independent instances for review, because same-session review keeps its reasoning. Split large reviews into per-file local passes plus a cross-file integration pass. Calibrate confidence thresholds on labelled validation sets before routing on them.

A production review architecture combines all three concepts:

For the broker, that is one extraction, a check per document, one cross-document check and an adviser for doubtful findings.

The exam tests this directly: to improve review quality, the correct answer uses a separate model instance. Adding "please review carefully" instructions to the same session is wrong, and so is relying on extended thinking within the generating session. Both leave the original reasoning in context.

For large multi-file reviews, one specific distractor reads "switch to a higher-tier model with a larger context window". The exam also distinguishes raw confidence scores (uncalibrated, unreliable for automated decisions) from calibrated confidence thresholds (validated against labelled sets, suitable for routing).

This architecture is more expensive than single-pass review. It is worth it when review quality directly affects production reliability: CI/CD pipelines, financial extraction like the broker's, compliance analysis, and any system where missed issues have downstream consequences.

The context window is everything Claude reads on one request: instructions, the conversation so far, tool results and documents. Context window management is choosing what goes in. Multi-turn conversations, multi-agent pipelines and long-document extraction all depend on it, as does any reliable Claude-based system. When it goes wrong, support agents forget refund amounts, research pipelines drop citations, and extraction systems lose precision on the fields that matter most.

A travel agency runs its booking assistant on Claude. Over a long session, a customer gives a deposit amount, departure dates, a booking reference and the hotel's promise of a sea view. Three research subagents check flights, hotels and transfers for a synthesis agent.

Progressive summarisation, a common strategy in long conversations, replaces earlier turns with a shorter summary to free token budget. It systematically destroys the most critical information in customer-facing and data-processing systems: numerical values, dates, percentages and customer-stated expectations. By default, a summary of transactional data keeps the gist and drops the specifics.

Take turn 3 of a refund conversation.

Turn 3: "I'd like a refund of $247.83 for order #8891 placed on March 3rd" After summarisation, it becomes this.

Summary: "Customer wants a refund for a recent order" The amount, order number and date are gone, and the agent needs all three to process the refund. The agency's summary would lose its deposit, dates, reference and sea view too.

The fix is a persistent case facts block . Extract transactional facts (amounts, dates, order numbers, statuses) into a structured block included in every prompt, outside the summarised history. The block is never summarised, so it persists across every turn whatever happens to the history. For the agency, it would hold the deposit, dates, reference and status. This example shows the shape.

{ "caseFactsBlock" : { "customerId" : "C-4421" , "issues" : [ { "orderId" : "#8891" , "orderDate" : "2024-03-03" , "refundAmount" : "$247.83" , "status" : "pending_refund" , "itemDescription" : "Wireless headphones — defective" } ] } } When a customer raises several problems in one session, extract and persist structured issue data into a separate context layer. Each issue gets its own entry with order IDs, amounts and statuses, which prevents cross-contamination between issues during summarisation. A second agency booking with a misspelt name gets its own entry.

Models process information at the beginning and end of long inputs reliably. Findings buried in the middle of a long context may be missed or given less weight. This well-documented phenomenon in large language models shapes how you structure aggregated inputs.

The fix is structural, not prompt-based. Put a summary of the main findings at the start of the aggregated input, with detailed results under explicit section headers. A reminder to read everything leaves each finding where it sits. The agency's synthesis agent should get a "Key Findings Summary" first, then each supplier report under its own header. This layout shows the pattern.

## Key Findings Summary - Source A: 12% market growth in renewable sector (2023) - Source B: Patent filings increased 34% year-on-year - Source C: Regulatory framework delayed until Q3 2025 ## Detailed Findings ### Source A: Market Analysis Report [Full details here...] ### Source B: Patent Database Analysis [Full details here...] ### Source C: Regulatory Review [Full details here...] Tool Result Trimming Tool results use context budget unnoticed. An order lookup might return 40+ fields, such as internal audit timestamps, warehouse codes, shipping carrier IDs and fulfilment centre identifiers, most irrelevant to a refund request. You need 5. The other 35 consume tokens in every subsequent turn as the history grows. The agency's booking lookup has the same problem.

Trim verbose tool outputs to only the relevant fields before they accumulate in context. Trimming is required; otherwise stale output piles up turn after turn. This function keeps a refund workflow's fields.

def trim_order_result (raw_result, relevant_fields = None ): if relevant_fields is None : relevant_fields = [ "order_id" , "order_date" , "total_amount" , "return_eligible" , "item_description" ] return {k: v for k, v in raw_result.items() if k in relevant_fields} Do the trimming in a PostToolUse hook or in the tool implementation itself, before the result enters the conversation history. Once verbose data is in the context, it stays there for every subsequent turn.

The Claude API is stateless. There is no server-side session state, so each request must include the complete conversation history. Omit earlier messages and the model loses conversational coherence. The agency's assistant resends the whole planning session each time.

That creates a tension with context limits: coherence needs the full history, and the history grows every turn. The persistent case facts block resolves it by separating critical facts from summarisable narrative, so the agency can summarise the planning and keep every transactional detail.

In multi-agent systems, upstream agents often return verbose reasoning chains and raw content that downstream agents do not need. A synthesis agent with a limited context budget that receives a research subagent's full thought process wastes tokens on reasoning it cannot use.

Modify upstream agents to return structured data (main facts, citations, relevance scores) instead. Require metadata such as dates, source locations and methodological context in those outputs, to support accurate downstream synthesis. The agency's hotel subagent returns findings with source and date, without its search steps.

{ "findings" : [ { "claim" : "Renewable energy investment grew 12% in 2023" , "source" : "IEA World Energy Report 2024" , "sourceUrl" : "https://example.com/report" , "relevanceScore" : 0.92 , "publicationDate" : "2024-01-15" } ] } Structured outputs also let downstream agents process findings without re-parsing verbose prose.

Key Concept

The persistent case facts block is the single most important pattern in context window management: transactional facts in every prompt, never summarised. It fixes progressive summarisation and underpins reliable multi-turn systems.

Prompt caching is the other half of context economics. Instead of trimming what the model sees, you avoid paying to reprocess the parts that don't change. Mark a stable prefix with a cache_control breakpoint. The API stores the processed prefix and reuses it on the next request, charging a fraction of the input cost for cached tokens.

Caching matches from the start of the prompt, prefix by prefix, so layout decides whether you get a hit. Put constant content first: system instructions, tool definitions, long reference documents. Place the cache_control breakpoint at the end of that static block. Put volatile content after it: the user's latest message and anything that changes per request. The agency puts instructions, tools and booking terms first and the customer's newest message last.

The static block belongs in the top-level system parameter, not in messages . The cache reads the prompt in the order tools , system , messages , so the instructions in system sit ahead of every turn that changes.

response = client.messages.create( model = "claude-sonnet-5-5" , max_tokens = 4096 , system = [ { "type" : "text" , "text" : LONG_STATIC_INSTRUCTIONS }, { "type" : "text" , "text" : REFERENCE_DOC , "cache_control" : { "type" : "ephemeral" }}, ], messages = [ { "role" : "user" , "content" : dynamic_user_message}, ], ) If dynamic content sits before the static block, the prefix changes on every request. Nothing matches, and every call pays full price. An ephemeral breakpoint lasts about five minutes since last use. A {"type": "ephemeral", "ttl": "1h"} breakpoint lasts an hour at a higher write cost. A request may carry at most four breakpoints.

A typical stem shows an agent losing amounts or dates after summarisation. The keyed fix is the persistent case facts block. Traps include telling the model to attend to everything and keeping full tool results just in case. Selective truncation is another, because the stateless API needs the whole history.

Scope

The guide's out-of-scope list excludes "prompt caching implementation details (beyond knowing it exists)", so nothing beyond the existence and purpose of caching is tested. The mechanics above are for real work.

Escalation means a support agent hands a conversation to a human. A trigger is the condition that causes it. Calibration is how well the agent chooses when. Miscalibrated escalation directly destroys first-contact resolution rates, so calibration is make-or-break for customer support agents.

Take a building firm whose support agent answers homeowners. Each message raises one decision: resolve it, or hand it to staff.

There are exactly three valid triggers for escalating to a human.

1. The customer explicitly requests a human. "I want to speak to a person" or "Transfer me to a human agent" is a clear request. Honour it immediately. Do not attempt to resolve the issue first, or say "Let me see if I can help you with that first." This is an absolute rule with no exceptions. A homeowner who asks the firm's agent for a person is handed over in that reply.

2. Policy exceptions or gaps. The request falls outside documented policy. The agent cannot make policy on the fly, so a human judges whether to make an exception. A homeowner asks the firm to match a competitor's price, but its policy only covers adjusting its own prices. That goes to staff.

A gap differs from a violation. A violation has a documented answer: a refund requested outside the return window gets "no". A gap means the policy is silent on the situation. Gaps require escalation; violations do not. The firm's agent declines an out-of-window refund itself and escalates the price match.

3. Inability to make meaningful progress. The agent has tried and cannot advance. Perhaps tools returned errors that local retry logic cannot resolve, the case needs system access the agent lacks, or a bug needs engineering intervention. This trigger covers everything else, but only after a genuine attempt. "I might not be able to handle this" isn't sufficient; the agent has to show it tried and failed. The firm's booking tool failing after every retry qualifies.

Sentiment-based escalation fires on frustration detection or a negative sentiment score. Sentiment measures emotional state, and frustration does not correlate with case complexity. A homeowner furious about a late tile delivery has a simple case: apologise, offer compensation, reship. A calm, polite homeowner asking for the price match needs human judgement on a policy gap.

Self-reported confidence scores have the model rate itself from 1 to 10 and escalate below a threshold. LLM self-reported confidence is poorly calibrated. The model is often incorrectly confident on hard cases, because it does not know what it does not know. It is often unnecessarily uncertain on straightforward cases where the answer is clear. The firm's agent would then send the late tiles to staff and keep the price match.

Frustration alone does not decide the response.

The angry homeowner gets the reship, unless they ask again for a person.

A tool may return several matches for one search, such as three "John Smith" records. The agent must then ask for additional identifiers: email address, phone number, order number or other disambiguating information. It must never pick one itself.

Picking the wrong customer risks a privacy violation (exposing one customer's data to another) or an incorrect action (a refund on the wrong account). Asking for clarification is the only safe response. The firm's agent asks for an email address before opening any account.

The most effective way to calibrate escalation is to add explicit escalation criteria with few-shot examples to the system prompt. They fix the root cause of poor calibration, which is unclear decision boundaries. The examples should demonstrate three things.

The firm's examples would be the request for a person, the angry homeowner and the price match handoff. This is the proportionate first response, before adding infrastructure like classifier models or sentiment analysis. Prompt optimisation should always precede architectural changes.

The exam tests when to escalate, when to resolve autonomously, and which commonly proposed triggers are unreliable. It tests whether you can identify both unreliable triggers as anti-patterns. Its scenario describes exactly this confidence failure mode: the agent escalates simple cases while attempting complex ones.

Key Concept

Valid escalation triggers: explicit human request (honour immediately), policy gaps (not violations) and inability to progress. Unreliable triggers: sentiment, which does not correlate with complexity, and self-reported confidence, which is poorly calibrated.

In a multi-agent system, a coordinator hands tasks to subagents and combines their results. Error propagation is how a subagent's failure (a timeout, a permission error, an invalid query) flows back to the coordinator. That flow decides whether the system recovers gracefully or fails silently. An access failure means a tool never reached its data. A valid empty result means the tool reached the data, ran the query and found nothing.

A bricklaying firm uses a multi-agent system to prepare quotes. Five subagents look up brick prices, mortar and sand prices, the job calendar, past jobs with similar walls, and the customer's order history. The brick price subagent times out.

A failing subagent must return structured error context with four elements, because the coordinator can only make an intelligent recovery decision from what it is told.

1. Failure type. Transient failures (a timeout, a rate limit) may succeed on retry. Validation failures (bad input) need the query fixed. Business failures (a rule violation) need escalation or an alternative. Permission failures (access denied) cannot be retried without authorisation changes. The brick timeout is transient.

2. What was attempted. Give the specific query, parameters and target system. The coordinator cannot adjust a query it cannot see. "Searched the merchant's price list for 'red facing brick', June delivery" is actionable. "Search failed" is not.

3. Partial results gathered before failure. If the subagent retrieved three of five sources before timing out, those three are still useful. Discarding them because the operation failed is wasteful.

4. Potential alternative approaches. The subagent knows its domain, so it can suggest a different source, broader search terms or cached results: a second merchant, say, or last week's prices. These suggestions help the coordinator choose a recovery strategy.

{ "status" : "partial_failure" , "failureType" : "transient" , "attemptedAction" : { "tool" : "search_academic_db" , "query" : "renewable energy policy" , "dateRange" : "2022-2024" }, "partialResults" : [ { "title" : "EU Renewable Energy Directive 2023" , "source" : "EUR-Lex" , "retrieved" : true } ], "alternativeApproaches" : [ "Retry with narrower date range (2023-2024)" , "Search alternative database: government_publications" , "Use cached results from previous research session" ] } After a subagent timeout, this structure gives the coordinator what it needs to decide: retry the same query, try an alternative, proceed with partial results or escalate. The bricklayer's coordinator could use its three brick prices and retry the rest.

Both are catastrophic, in different ways.

Silent suppression: returning empty results marked as success. This is the worst anti-pattern. The subagent times out but returns { "results": [], "status": "success" } . The coordinator believes the search ran and found nothing, so it won't retry or try alternatives. Its synthesis silently omits an entire area. The output looks complete but is missing critical content: the bricklayer's quote goes out with no brick cost.

Silent suppression is especially dangerous because it's invisible: nobody can detect the gaps. In customer support, the firm's agent may report "no orders found" while the order lookup is down, then tell the customer they have no account.

Workflow termination: killing the entire pipeline on a single failure. One subagent times out and the whole pipeline crashes. The other four completed successfully, but their results are thrown away. This disproportionate response wastes completed work and gives no recovery path. The bricklayer loses four finished lookups to one slow merchant.

The middle ground is structured error propagation: the subagent reports what happened, the coordinator assesses the damage, and the system continues with partial results or targeted recovery.

Access failure: The tool could not reach the data source, through a timeout, a connection error or a permission denial. The search did not execute. Consider retrying with the same or modified parameters.

Valid empty result: The tool reached the source, executed the query and found no matches. That is the answer, and no retry is needed because the system worked correctly. No curved garden walls in the past-jobs records means the firm has not built one.

Conflating the two causes two problems.

# Access failure — consider retry { "status" : "error" , "failureType" : "transient" , "message" : "Connection timeout after 30s" , "shouldRetry" : True } # Valid empty result — no retry needed { "status" : "success" , "results" : [], "message" : "Query executed successfully. No matching records found." , "shouldRetry" : False } Coverage Annotations When a synthesis agent combines subagent findings, the output should note which topic areas are well supported and which have gaps. If the brick subagent failed, the quote summary should say so.

"Section on brick costs is limited because the merchant price list was unavailable."

This is far better than silently omitting the topic. Coverage annotations tell the consumer what is fully covered and where the known limitations are. Without them, a gap looks like an irrelevant topic, not an unavailable source.

Subagents should recover locally from transient failures (retry logic, fallback sources, degraded responses) before propagating errors. Only propagate errors the subagent can't resolve locally, and always include what was attempted and any partial results.

This reduces coordinator complexity. Each subagent handles its own transient failures and escalates only persistent ones, so the coordinator need not manage retry logic for every subagent. The brick subagent retries the merchant, tries a second one, and reports only if both fail.

The exam tests structured error context, the two anti-patterns (explicitly) and access failures versus valid empty results (directly). Most developers get that last distinction wrong. When a stem describes a subagent timeout, the keyed answer returns structured error context so the coordinator can decide how to recover.

Key Concept

Structured error context enables intelligent coordinator recovery. Avoid silent suppression and workflow termination. Access failures need retry consideration; valid empty results do not.