Chapter 03

Claude Agent SDK

The agentic loop, hub-and-spoke, and why hooks beat prompts for anything that costs money.

D1guide part i

3.1

The agentic loop

Model-driven, not a decision tree. Claude picks the next tool from what the last tool returned.

One structured field — stop_reason — decides whether to go around again.

Model-driven

The next action depends on the previous result. Handles branches nobody enumerated in advance.

Hard-coded tree

Fixed sequence. Fine when the workflow really is fixed — and the wrong answer whenever the scenario says "depends on what it finds".

3.2

AgentDefinition

Identity, instructions, and a tool allowlist. The allowlist is where least privilege lives.

nameidentifier

descriptionwhat this agent handles — how a coordinator decides to pick it

system_promptinstructions, constraints, escalation rules

allowed_toolsleast privilege — a refund agent gets process_refund, a research agent does not

A coordinator's allowlist must include Task — otherwise it cannot delegate at all.

AgentDefinition(
    name="customer_support",
    description="Handles returns and order issues",
    system_prompt="You are a customer support agent…",
    allowed_tools=["get_customer", "lookup_order",
                   "process_refund", "escalate_to_human"],
)

# coordinator:
allowed_tools=["Task", "get_customer", …]

3.3

Hub-and-spoke

One coordinator, isolated subagents, no lateral traffic. Everything flows through the hub — that's what makes it observable.

Subagents inherit nothing. Empty context on every spawn, no memory across calls.

Coordinator owns

Decomposition, dynamic subagent selection, delegation, aggregation and validation, retries, the final answer.

Consequence

Any fact a subagent needs but was not handed will simply be absent — and it will guess instead of asking.

3.4

Task: context passing is mandatory

A subagent prompt is not a message in a thread. It is the subagent's entire universe.

No context

Task: "Analyze the document"

Which document? Found by whom? Output shape? All missing.

Self-contained

Task: "Analyze the following document.
Document: [full text]
Prior search results: [results]
Output format: [schema]"

Everything needed, inline, in the prompt.

3.4b

Parallel spawning

Multiple Task calls in one coordinator response run concurrently. Sequential turns do not.

Independent subtasks → one response, many Tasks. Dependent subtasks must stay sequential.

3.5

Hooks: deterministic control

Code in the lifecycle, not a request in a prompt. Use them wherever >90% is not good enough.

PreToolUse can block or redirect before the call happens; PostToolUse rewrites the result before the model ever reads it.

	Hooks	Prompt instructions
guarantee	deterministic — 100%	probabilistic — >90%, never 100%
use for	financial, legal, compliance, safety	preferences, tone, formatting
example	block refunds over $500	"try to solve before escalating"

Recall in 60 seconds

Agentic loop = send → check stop_reason → execute → append → repeat. Model-driven.
Completion is end_turn. Iteration caps are safety nets, not stop conditions.
allowed_tools = least privilege. A coordinator needs Task in it.
Subagents get zero inherited context and no memory across calls.
All traffic through the coordinator — that is where observability and retries live.
Many Task calls in one response = parallel. Across responses = sequential.
PreToolUse blocks/redirects; PostToolUse normalises results before the model sees them.
Money, law, or safety on the line → hook, never a prompt instruction.