Agentic Architecture & Orchestration

An agentic loop is the control flow that lets Claude execute a task autonomously across many tool calls. The lifecycle is: (1) send a Messages API request with your tools array; (2) inspect the response's stop_reason; (3) if it is "tool_use", execute each tool_use block your code received and append the outputs back as tool_result blocks; (4) send the updated message list and repeat. The loop terminates when stop_reason becomes "end_turn" (Claude produced a final answer with no tool calls). This is the canonical while stop_reason == "tool_use" pattern.

Tool results are appended to conversation history so the model can reason over new information on the next iteration. The assistant's tool_use content block (with its id, name, input) is added as an assistant turn, and the matching tool_result (referencing the same tool_use_id) is added as a user turn. Because context accumulates, Claude can chain dozens of tool calls, adjusting based on each result.

The critical distinction is model-driven decision-making vs pre-configured sequences. In a true agentic loop, Claude reasons about WHICH tool to call next from current context; you do not hardcode a decision tree. The Agent SDK wraps this same loop: it yields AssistantMessage and UserMessage objects per turn and a final ResultMessage; max_turns/maxTurns counts tool-use turns and exists as a safety cap, not the primary stop. Other stop reasons your loop must handle: max_tokens (retry with higher limit if a tool_use was truncated), pause_turn (server-tool iteration limit; resend the response as-is), refusal, and model_context_window_exceeded.

Coordinator-subagent orchestration is a hub-and-spoke (orchestrator-worker) architecture. A single coordinator (lead) agent owns task decomposition, delegation, result aggregation, and all inter-subagent communication, error handling, and information routing. Subagents are the spokes: they never talk to each other directly, and they run with isolated context windows. They do NOT automatically inherit the coordinator's conversation history, so the coordinator must hand each one a self-contained task description and output format.

The coordinator's first job is analyzing query requirements and dynamically selecting which subagents to invoke based on complexity, rather than always routing every query through the full pipeline. A simple lookup should not spin up five research agents; a broad research question should. Anthropic's own multi-agent research system embeds guidance to 'scale effort to query complexity' for exactly this reason.

To minimize duplicated work, the coordinator partitions scope: it assigns distinct subtopics or source types to each subagent (e.g., one covers historical sources, another current data). A documented failure mode from Anthropic's research system was poor division of labor, where multiple subagents redundantly investigated the same thing. The opposite risk is overly narrow decomposition, which leaves gaps in coverage for broad topics.

Mature coordinators run an iterative refinement loop: after synthesis, the coordinator evaluates the output for gaps, re-delegates targeted queries to search/analysis subagents, and re-invokes synthesis until coverage is sufficient (an evaluator-optimizer style loop). Routing all communication through the coordinator gives you observability, consistent error handling, and controlled information flow. In the SDK, SubagentStart/SubagentStop hooks let the coordinator track and aggregate parallel results.

In the Claude Agent SDK, subagents are spawned through the Task tool (renamed to Agent in Claude Code v2.1.63; Task still works as an alias and still appears in the system:init tools list). A coordinator can only spawn subagents if "Agent" (or "Task") is in its allowedTools/allowed_tools; otherwise invocations fall through to the permission callback or are denied. Subagents cannot spawn their own subagents, so you must NOT put Agent in a subagent's tools array.

You declare subagent types in the agents parameter, each an AgentDefinition with: description (required; tells Claude when to use it), prompt (required; its system prompt), tools (optional allowlist; omit to inherit all), and optionally model, disallowedTools, skills, mcpServers, maxTurns, and effort.

The crucial mechanic: subagent context must be provided explicitly in the prompt. A subagent starts fresh and the ONLY parent-to-child channel is the Agent tool's prompt string. It does receive its own system prompt, project CLAUDE.md (via settingSources), and tool definitions, but NOT the parent's conversation history or tool results. So to give a synthesis subagent the web-search results and document analysis from prior agents, you embed those findings directly in its prompt. Use structured data formats to keep content separate from metadata (source URLs, document names, page numbers) so attribution is preserved across the handoff.

Spawn subagents in parallel by emitting multiple Agent tool calls in a single coordinator response (not across separate turns). Write coordinator prompts that specify research goals and quality criteria rather than rigid step-by-step procedures, so subagents can adapt. For exploring divergent approaches from a shared baseline, fork-based session management (fork_session) branches a copy of the analyzed context.

Multi-step workflows must distinguish programmatic enforcement from prompt-based guidance. Prompt instructions ('always verify the customer before refunding') guide behavior but have a non-zero failure rate — the model can skip a step. When deterministic compliance is required (identity verification before financial operations, prerequisite ordering), you enforce it in code via hooks or prerequisite gates so a downstream tool simply cannot run until its precondition is met.

A prerequisite gate is typically a PreToolUse hook that blocks a tool call until a prior step has completed. For example, block process_refund until get_customer has returned a verified customer ID. The gate inspects accumulated state and returns permissionDecision: "deny" with a reason if the precondition isn't satisfied, redirecting the model rather than letting the unsafe action through. Because deny is deterministic, the ordering is guaranteed regardless of how the model phrases its plan.

For multi-concern requests (a customer reports a billing error AND a shipping delay AND wants a discount), decompose into distinct items, investigate each in parallel using shared context, then synthesize one unified resolution rather than handling them in an ad hoc order.

Structured handoff protocols matter when escalating mid-process to a human who lacks the conversation transcript. The handoff summary must be self-contained: customer ID, root-cause analysis, the refund amount or action taken, and a recommended action. A human agent reading only that summary should be able to act without replaying the chat. The same applies to escalation triggered programmatically (e.g., a refund exceeding a policy threshold routes to human review with a compiled summary attached).

Agent SDK hooks are callbacks that fire at points in the agent loop, letting you intercept and transform tool activity deterministically. Two patterns matter most here. PostToolUse fires AFTER a tool returns; use it to normalize or transform results before the model processes them. PreToolUse fires BEFORE a tool executes; use it to inspect and block or modify outgoing tool calls.

For data normalization, a PostToolUse hook reconciles heterogeneous formats from different MCP tools — one tool returns Unix timestamps, another ISO 8601, another numeric status codes — into a single canonical shape so the agent reasons over consistent data. You set updatedToolOutput inside hookSpecificOutput to replace the tool's output before Claude sees it (this works for any tool in both SDKs; the older updatedMCPToolOutput is MCP-only and deprecated). You can also append with additionalContext instead of replacing.

For compliance enforcement, a PreToolUse hook intercepts the outgoing call and returns permissionDecision: "deny" with a permissionDecisionReason to block a policy-violating action (e.g., a refund exceeding $500) and redirect to an alternative workflow such as human escalation. When multiple hooks apply, deny wins over defer over ask over allow.

The exam's key conceptual point: choose hooks over prompt instructions when business rules require GUARANTEED compliance. A prompt nudge is probabilistic; a hook is a deterministic guarantee enforced in your process, outside the model's discretion. Hooks are registered under options.hooks keyed by event name, each with an optional matcher (tool-name pattern like "Write|Edit" or ^mcp__) and an array of callbacks. Hooks run in your process and don't consume context.

Task decomposition strategy is about choosing the right structure for breaking a complex job into subtasks. The primary axis is predictability. When the steps are known in advance, use a fixed sequential pipeline — prompt chaining — where each step's output feeds the next, with programmatic checkpoints between steps to keep the process on track. When you cannot predict the subtasks until you see intermediate findings, use dynamic adaptive decomposition (the orchestrator-workers pattern), where a central agent generates subtasks based on what it discovers at each step.

Prompt chaining shines for predictable multi-aspect work. A large code review is a strong example: decompose it into per-file local analysis passes (analyze each file individually), then run a separate cross-file integration pass. Splitting per-file work avoids attention dilution — a single mega-prompt covering many files spreads the model's focus thin and degrades quality on each file. The cross-file pass then catches interactions a per-file pass cannot see.

Dynamic decomposition fits open-ended investigation. For a task like 'add comprehensive tests to a legacy codebase,' you can't enumerate subtasks upfront. The adaptive approach first maps the structure, identifies high-impact areas, then creates a prioritized plan that adapts as dependencies are discovered — generating new subtasks from each step's findings rather than following a fixed list.

The exam wants you to match pattern to workflow: prompt chaining (predictable, sequential, multi-aspect reviews) versus dynamic decomposition (open-ended, exploratory tasks). Using a rigid fixed pipeline for an unpredictable task causes missed work; using fully dynamic decomposition for a simple predictable task adds needless overhead.

A session is the persisted conversation history (your prompt, every tool call, every tool result, every response) the SDK writes to disk so you can return to it. Managing session state across work sessions relies on three verbs: continue, resume, and fork.

Resume returns to a SPECIFIC session by ID or by name. In the CLI, claude --resume <name> (or -r) resumes a named session; you name a session with claude --name <name> (or -n), and --resume with no argument shows an interactive picker. --continue (-c) instead grabs the most recent session in the directory. In the SDK you capture session_id from the ResultMessage and pass resume=<id> on the next query(). Resuming restores full prior context — files already read, analysis already done.

Fork creates a new session that starts with a COPY of the original's history but diverges from that point; the original's ID and history stay unchanged. Use fork_session=True/forkSession: true (or CLI --fork-session) to explore divergent approaches from a shared analysis baseline — for example, comparing two refactoring or testing strategies that both build on the same codebase analysis.

The key judgment: choose resumption when prior context is mostly still valid; start fresh with an injected structured summary when prior tool results are stale (e.g., files were modified since). Resuming with stale tool results is less reliable than a clean session seeded with a current summary, because the model may reason over outdated file contents. When you do resume after code changes, inform the agent about the specific files that changed so it does targeted re-analysis instead of trusting cached results — or re-exploring everything.