1. The agentic loop
An agent is a model in a loop with tools. Nothing more mysterious than this:
┌──────────────────────────────────────────────┐
│ │
user ▼ │
request ──► call Claude (messages + tools) │
│ │
▼ │
read stop_reason ───── "tool_use" ──► execute tools│
│ append results
│ "end_turn" │
▼ └──────┘
return final answer
Per iteration:
- Send the conversation (
messages) plus tool definitions (tools).
- Claude responds. If it wants a tool, the response contains
tool_use content blocks and stop_reason == "tool_use".
- You (the harness) execute the tool(s), append the assistant turn and a user turn containing
tool_result blocks, and call again.
- Loop until
stop_reason is no longer "tool_use".
The exam repeatedly probes whether you know who does what: Claude decides which tool and with what input; your code executes it. Claude never runs anything itself via the plain API — tool execution, sandboxing, and permissioning are the harness's job (this is exactly the surface where hooks and allowedTools live).
📊 Diagram — “Flowchart of the agentic tool-use loop” (a version appears earlier on this page)
2. stop_reason — the field that drives everything
stop_reason |
Meaning |
Correct loop behavior |
end_turn |
Claude finished naturally |
Exit loop, return the answer |
tool_use |
Claude requests tool call(s) |
Execute tools, append tool_result(s), call again |
max_tokens |
Output hit your max_tokens cap |
Response is truncated — treat as incomplete; raise the cap or continue, never parse as final |
stop_sequence |
Hit one of your custom stop_sequences |
Intentional early stop; handle per your design |
pause_turn |
Server-side turn paused (long server-tool work) |
Re-send as-is to resume |
refusal |
Model declined for safety |
Surface to user; do not blind-retry |
Classic exam traps:
- A loop that only checks
end_turn/tool_use and treats max_tokens output as complete → silently truncated JSON that fails downstream. The reliable design checks for truncation explicitly.
- A loop written as
while stop_reason == "tool_use" with no iteration cap → a malformed tool can spin forever. Production loops carry a max-iteration guard.
📊 Diagram — “Map of all stop_reason values to correct loop behavior” (a version appears earlier on this page)
3. Building a complete tool-use loop
The canonical implementation — this exact shape (append assistant content → execute → append tool_result with matching tool_use_id → repeat) is what Domain 1 questions assume you know cold.
Three invariants the exam loves:
- Append the full assistant
response.content to history (it contains the tool_use blocks Claude needs to see echoed back).
- Every
tool_result must carry the tool_use_id of the request it answers — and all results for one turn go back in a single user message (splitting them across messages degrades parallel tool use).
- Cap iterations.
4. Single-agent vs multi-agent: the decision framework
The exam does not reward "more agents = better." The default is a single agent; you add agents only when the problem demands it.
| Choose |
When |
Why |
| Single agent |
Sequential steps, shared context throughout, one coherent task |
Simplest, cheapest, no coordination overhead, no context-handoff loss |
| Subagents (coordinator + workers) |
Independent parallelizable subtasks; work that would blow the main context window; specialized roles |
Parallelism; context isolation keeps the coordinator lean; each worker gets a focused toolset |
Decision test to apply on exam day:
- Can the subtasks run independently? If step B needs step A's output, parallel subagents buy nothing — sequential single-agent (or pipelined) wins.
- Would intermediate detail pollute the main context? Research over 50 documents → workers read documents and return summaries; coordinator context stays small.
- Is the added failure surface worth it? Every subagent adds error-propagation and result-merging concerns (Domain 5 overlap).
Trap: "The task is complex, so split it across multiple agents." Complexity alone is not the trigger — independence and context pressure are.
5. Coordinator/subagent patterns & context isolation
The single most-tested fact in this domain:
Subagents start with a fresh context. They inherit nothing from the coordinator — not the conversation, not earlier tool results, not the user's original phrasing.
Consequences the exam probes:
- The coordinator's delegation prompt must explicitly pass everything the subagent needs: the goal, relevant facts, constraints, output format, and what "done" looks like.
- A subagent asked to "continue the analysis" will fail — there is no "the analysis" in its context.
- Subagent results return to the coordinator as tool results (in the Claude Agent SDK, spawning happens via the Task tool). The coordinator's context receives the result, not the subagent's working transcript — that's the whole point (context isolation).
- Because results come back as data, make subagents return structured output (e.g. JSON with
findings, sources, confidence) so the coordinator can merge programmatically — and so failures are explicit rather than silent (Domain 2/5 overlap).
Anatomy of a good delegation prompt:
ROLE: You are a research subagent.
GOAL: Determine whether ACME Corp's 2025 revenue grew year-over-year.
CONTEXT YOU NEED (you have no other context):
- Parent task: due-diligence report for a client, deadline strict.
- ACME's fiscal year ends March 31.
TOOLS: web_search only.
RETURN FORMAT (JSON): {"answer": ..., "figures": [...], "sources": [urls], "confidence": 0-1}
If you cannot find reliable figures, say so explicitly in "answer" — do not guess.
Parallel vs sequential decomposition: fan out only truly independent subtasks; run dependent steps in sequence. A common exam option is "spawn a subagent per step of a dependent pipeline" — wrong, because each spawn re-pays context setup and the steps still serialize.
📊 Diagram — “Hub-and-spoke coordinator/subagent architecture” (a version appears earlier on this page)
allowedTools — least privilege for agents
In the Claude Agent SDK (and Claude Code), allowedTools restricts which tools an agent (or subagent) may use. The exam pattern:
- A subagent that only needs to read files gets
["Read", "Grep", "Glob"] — not Bash or Write.
- Why it matters: it's deterministic enforcement (the tool simply isn't available), unlike a prompt saying "please don't modify files" (probabilistic). Prompts guide; systems enforce.
- Minimal tool surface also improves tool selection: fewer, sharper options → fewer mis-picks (Domain 2 overlap).
6. Hooks: deterministic enforcement vs prompt guidance
Hooks are your code that the harness runs at fixed lifecycle points — before/after tool calls, at session events. Because they are code, they execute 100% of the time: they are the canonical answer to "how do I guarantee X happens?"
| Mechanism |
Nature |
Use for |
| System prompt instruction |
Probabilistic — usually followed |
Style, tone, approach, preferences |
Hook (e.g. PreToolUse, PostToolUse) |
Deterministic — always runs |
Policy, compliance, blocking, logging, validation |
Examples of hook-shaped exam answers:
- "The agent must never call the refund tool for amounts over $500 without approval" → a
PreToolUse hook that inspects the tool input and blocks/queues the call. Not a system-prompt rule.
- "Every file write must be logged for audit" →
PostToolUse hook. A prompt asking Claude to "mention when you write files" can be forgotten; the hook cannot.
- "Run the linter after every edit" →
PostToolUse hook on the Edit tool.
If the requirement contains must / never / always / compliance / audit, the answer is a hook (or schema/code check) — not a longer prompt. This single rule resolves several questions per exam.
📊 Diagram — “Deterministic hooks vs probabilistic prompts, with hook timeline” (a version appears earlier on this page)
7. Session management
Agent SDK / Claude Code sessions persist conversation state so work can span invocations.
| Concept |
What it does |
When it's the answer |
--resume / session resume |
Continue a previous session with its full context |
Long-running work interrupted (deploys, crashes, next morning) |
fork_session |
Branch a session: same history, divergent futures |
Explore two approaches from one shared starting point without cross-contamination |
/compact (Claude Code) |
Summarize the conversation to reclaim context budget |
Session still needed but context is nearly full (details in page 02 & 05) |
| Scratchpad files |
Persist working state to disk, outside the context window |
State that must survive compaction or session loss (Domain 5 overlap) |
Exam angle: session features are about continuity and recovery. If a scenario says "the pipeline may be interrupted and must pick up where it left off," the answer combines session resume with durable state written to files — not "keep everything in the conversation."
8. Escalation & human-in-the-loop
Reliable agents know when to stop. The exam rewards designs with explicit, pre-defined escalation triggers:
- Confidence-based: the agent reports confidence; below a threshold → route to a human. (Requires asking for confidence in the output schema — you can't threshold what you don't collect.)
- Attempt-based: N failed tool calls / N loop iterations → escalate. Never unbounded retry.
- Policy-based: certain actions (refund > $X, deleting data, contacting a customer) always require human approval — enforced via hooks or tool gating, not prompts.
- Ambiguity-based: request falls outside the defined scope → hand off with a structured summary of state so the human doesn't start from zero.
Anti-patterns (frequent wrong options):
- Retrying indefinitely "until it works".
- Letting the model decide for itself whether policy applies, when the scenario demanded a guarantee.
- Escalating with no context handoff (human gets a bare "agent failed").
11½. Official exam-guide addenda (v1.0)
Specifics from the official task statements (Exam Guide v1.0, July 2026) that sharpen or extend the sections above:
Loop termination (TS 1.1) — named anti-patterns. The primary stopping mechanism is stop_reason. The guide explicitly lists as anti-patterns: parsing natural-language signals to decide termination, checking assistant text for "done"-like content, and using an arbitrary iteration cap as the primary stopping mechanism. Keep the cap from §3 — but as a safety backstop, never the design.
Hub-and-spoke coordination (TS 1.2). All inter-subagent communication routes through the coordinator — for observability, consistent error handling, and controlled information flow (subagents never talk to each other directly). Two more tested ideas: the coordinator should select subagents dynamically per query (not always run the full pipeline), and beware overly narrow task decomposition — slicing a broad research topic too finely leaves coverage gaps. For synthesis quality, the guide endorses an iterative refinement loop: coordinator evaluates the synthesis for gaps → re-delegates targeted queries → re-synthesizes until coverage is sufficient.
Spawning mechanics (TS 1.3). Three concrete facts: (1) the coordinator's allowedTools must include "Task" or it cannot spawn subagents at all; (2) parallel subagents = multiple Task tool calls in a single coordinator response (not across separate turns); (3) each subagent type is configured via an AgentDefinition — description, system prompt, and tool restrictions. And delegation prompts should state goals and quality criteria, not step-by-step procedures — that's what lets subagents adapt.
Hooks for data normalization (TS 1.5). Beyond policy gates and audit logs, PostToolUse hooks are the tested answer for normalizing heterogeneous tool outputs — e.g., three MCP tools returning Unix timestamps, ISO 8601 strings, and numeric status codes get normalized to one format before the model processes them.
Decomposition patterns (TS 1.6). Two named strategies: prompt chaining (fixed sequential steps — right for predictable multi-aspect work like code review: per-file passes, then a cross-file integration pass to avoid attention dilution) vs dynamic adaptive decomposition (subtasks generated from what each step discovers — right for open-ended investigation).
Sessions (TS 1.7). Resumption is named: --resume <session-name>. Two reliability rules: when resuming after code changes, tell the agent which files changed so it re-analyzes only those; and when prior tool results have gone stale, start a fresh session seeded with a structured summary instead of resuming — stale context misleads more than it helps.
