Domain 1 – Facts

This is the dividing line in Anthropic's Building Effective Agents. Both can call tools, loop, and run things in parallel, so those features don't tell them apart. Choose by how well you know the path: known path, workflow; path found along the way, agent. The wrong answer just swaps the two definitions, which looks right if you read fast.

When the order is fixed, your code can just write it down as a chain, and a code check between steps catches bad output early. An orchestrator adds a model call to decide a split you already know. One agent with three tools makes the model rediscover the same order every run, and it may skip or reorder steps. For big volume, run the same chain in many parallel workers, not a planner.

Chaining is a fixed sequence. Routing sorts the input into a category and sends it to a specialised prompt or model. Parallelization either splits independent subtasks (sectioning) or runs the same task N times and combines the answers (voting). Orchestrator-workers lets a model split the work at runtime and then combine results; evaluator-optimizer loops a writer with a critic. A table may show six rows, but it is still five patterns. Each one answers a question: is the order known, does input fall into categories, are subtasks independent, can you predict them up front, is there a clear rubric to iterate against?

The orchestrator's extra model call pays off only when nobody can list the subtasks in advance: it reads the situation, decides what to look into, hands out work, then combines the results. "Why did checkout conversion drop?" is like that, because the next questions depend on what the first look finds. "This fixed job would be faster in parallel" is a parallelization problem; the harness (your code that runs the model) solves it with a worker pool. A planner there just re-creates a split you already wrote.

Volume is a throughput problem, and throughput is your code's job: put documents on a durable queue, run a limited number of workers that each run classify → extract → validate, and use the Batch API for work that can finish overnight. A model orchestrator would pay a call per invoice for a split that never changes. Later stages still need earlier results, so a batch design sends the classification jobs, saves the results, then sends the extraction jobs that qualify and validates them in code.

Adaptive means: first map the area, then make a prioritised plan that changes as you learn about dependencies and findings. Two things each point to it on their own: subtasks that only appear after early results, and a task with no existing map (full tests for an old codebase nobody has charted). If every run checks the same predictable things, or each step feeds the next in a stable order, a fixed pipeline fits and the adaptive setup is wasted.

Calling every specialist on every request means even a one-line answer pays the full time and token cost. A classification step at the start lets cheap questions take the cheap path. Two separate systems duplicate logic, a cache helps only when the exact same request repeats, and cutting each subagent's budget makes every answer worse while the unneeded work still runs.

A critic model scores the draft against an explicit rubric and sends it back for changes. This pays off for translation, writing, and research, where quality is a judgement. Checking that invoice totals add up is math your code can check exactly and for free; a model critic looping until the numbers match swaps a sure check for a slow, maybe-correct one.

A single agent loop is one model, one conversation, one set of tools, looping on tool_use until end_turn. It stays right as long as the instructions, tool results, and reasoning all fit in one context window with one coherent tool set. More agents add coordination code, handoff bugs, and cost; add them only when work is independent enough to run in parallel, or the raw material would overflow one context. Whether subagents exist, whether speed matters, or how big the deployment is does not decide it.

stop_reason is the API telling your code why the model stopped, so your harness must branch on it before using the content. max_tokens means the output hit the cap you set for this call, so the text is incomplete. stop_sequence means one of your custom stop strings matched, and your own protocol decides what that means. refusal means the model said no; retrying automatically is the wrong reflex.

The API's own signal is the real exit: keep going on tool_use, stop on end_turn. Searching the reply for a phrase or tag ties the stop to wording the model can change. A hard max_turns as the main stop can cut off work that needed one more step, or let a stuck loop waste eight turns before anyone notices. Keep the cap only to stop runaway cost; the structured stop reason is what controls the loop.

When output hits max_tokens the model stops mid-sentence; JSON cut at the right spot can even parse, just with fields missing. The clue is in the logs: every failed response has stop_reason: max_tokens, and a harness that never checks this field accepts it silently. Hallucination wouldn't line up with the stop reason, a strict schema rejects instead of cutting, temperature changes wording not length, and checkpoints don't touch the response. Fix: branch on stop_reason, then raise the budget or make the task smaller.

max_tokens says nothing about how big the messages array is. An input that's too large gets an error up front, not a response with a stop reason. So max_tokens as a stop reason means exactly one thing: generation reached the ceiling you set, and the text is incomplete.

The API is stateless (it remembers nothing between calls), so call 2 must tell the whole story in order: the assistant turn with its tool_use block and id, then the user message carrying the tool_result. Both go at the end because the array is in time order. Sending only the tool_result, or putting it before the assistant turn, leaves a result with nothing to pair with, and the API rejects it; putting things at the start scrambles the conversation.

Each tool_use block gets a fresh id like toolu_01A, made by the Claude API, not by your code and not written in the tool definition (which only has name, description, and input_schema). Your harness copies that id into the tool_result's tool_use_id so the API can match result to request. This is required even when there is only one tool call in the response.

The Claude API keeps no conversation between calls, so a 40-turn conversation is a 40-turn array sent every time. system and tools travel next to it as separate fields, so they stay byte-identical and prompt caching can reuse them while messages grows. For the model, tool results are news from the outside world, and the outside world always speaks as user.

A tool_use block is a request, not an action: the model writes the tool name and arguments as data and stops. Everything after that is your harness: validate the arguments against input_schema, check this agent may do this action with these values, run the tool, and look at the result before appending it. Strict tool inputs can shape the argument structure, but they never approve a shipment or prove a business value is right.

The tools list only tells the model what it may call. strict: true controls the shape of the arguments, but it doesn't pick the right business task, check permission, or force one call before another. If step B must never run before step A, put that rule in your harness: check the state before running the tool.

A subagent starts blank: it sees only what the coordinator writes into its prompt, not the coordinator's conversation and not what sibling agents found. So every input is carried by hand: the findings a synthesis step must cite, the paths and schema mappings a test agent needs, the code to test, the revision to read. If a later agent acts like an earlier result never existed, first check whether the prompt ever included it.

Check the coordinator's logs stage by stage. If no worker was ever given the topic, the plan was too narrow; the workers did their jobs. If a worker finished it but the output never reached the next prompt, collecting results or the handoff is broken. Only if the content was passed in and still disappeared from the report is the synthesis step to blame.

Every worker finished cleanly, yet only the first module shows up: the coordinator took one result and moved on. Subagents return output to the coordinator, but the coordinator must collect all of them and pass them on together; nothing does this automatically. A max_turns or rate-limit failure would show up as an error or an incomplete result, which contradicts "all returned successfully, no tool errors".

In hub-and-spoke (all messages go through the coordinator), the coordinator is the only channel, so it must put the migration agent's output (the schema mapping and the revision) into the test agent's prompt. Running the two agents one after the other changes timing but still passes nothing. A shared message bus lets workers talk directly, which breaks the hub-and-spoke model and adds complexity. Letting the test agent dig through migration files works around a problem the coordinator owns.

A handoff can break in three places, and "done" covers none of them. Ready: the earlier change must really be complete enough to build on. Context: the next prompt must carry the concrete result and the acceptance criteria. Files: the next agent must be able to read that exact revision, which isn't automatic when agents work in separate worktrees, and old tool results don't refresh by themselves.

That's the point of a worker: it reads and digests the 12K-token page in its own context window and returns only a small summary with sources, so the coordinator's context stays small enough to combine many workers. Sending back the raw transcript would blow the coordinator's budget. All findings go up to the coordinator and, if needed, down in the next prompt. Summaries lose detail, so check they're complete; isolation doesn't guarantee quality.

In the Agent SDK and Claude Code, the coordinator must emit several Task (now Agent) tool calls in a single response; calls spread over separate turns run one after another. max_tokens only changes output length, a shorter timeout just cuts research short, and merging jobs into one prompt brings back the single-agent bottleneck. For independent work, total time drops to about the slowest worker.

Delegating costs something: writing the context, starting the agent, collecting the result. It's worth it when the task is big or needs focus. A rename across 60 files would crowd the coordinator, so a subagent takes it; a one-file health-check endpoint is tiny, so the coordinator just does it. Delegating both wastes overhead on the small task, doing both pulls 60 files through the coordinator, and swapping them sends each task the wrong way.

The more tools an agent sees, the less reliably it picks the right one, and an agent that sees summarise and sentiment_analysis will call them sometime, even if its job is only fetching raw data. The sure fix is to cut its list to the four or five fetching tools. A prompt reminder is probabilistic (it may or may not work) and has already failed; a PreToolUse hook that blocks the calls is over-built and still shows tools the model shouldn't consider. Removing tools doesn't stop the model writing a summary in plain text, so still check the output to keep the handoff raw evidence.

The coordinator looks at what's missing, sends narrow follow-up searches and analysis for exactly those gaps, then combines again with the extra evidence. Starting over throws away good work and may repeat the same gaps. Filling holes from the model's own knowledge creates claims with no source. Accepting the report to save budget ships known problems.

The loop only gets closer to passing if each round starts from the last attempt, so the worker edits instead of starting over. Without that, each round writes fresh code that fails in new ways, so the number of rounds doesn't matter. A Read tool doesn't help either: the last attempt lives in a finished context, not in a file the worker can find.

The check is simple math your harness does on the tool_use block's input before running it: $600 is over $100, so the run parks, and the pending block plus a handoff packet go to the approval queue for a human. Running first and getting sign-off later, or flagging for audit afterwards, both ship before permission exists; an idempotency key stops duplicates but is not permission. Asking the model to check with the customer gives the decision to the wrong person.

A prompt, an example refusal, or a CLAUDE.md line can describe the $50 rule, but the model can still propose a $75 credit; text guides behaviour, it doesn't control the payment system. The rule holds only if backend code checks the amount before issuing the credit and, above the limit, saves the request for an authorised human. Also, CLAUDE.md is a Claude Code memory file; a plain Messages API loop never loads it.

An agent run is only alive during a model call or a tool run. So a parked approval is free: your harness saves the messages array through the assistant turn holding the pending tool_use, that block's id, and the handoff packet (who, what, why, amount) to a queue or store. Days later a worker loads the same run_id and continues. No request is open, so nothing times out on the API side.

The pending tool_use is still waiting for its answer. If approved, your harness runs the tool now with an idempotency key (a unique id so a repeat does nothing twice) and reports the real result, like a replacement id or refund status. If denied, the tool_result says so and the model explains it to the customer next turn. A new model turn asking for the refund again wastes a turn and might produce a different action. "Approved" is permission, not proof the money moved.

After a timeout your code doesn't know if the action happened, and a simple retry does it again. The fix is where the action hits the outside system: give each operation a stable key, save its result in an effects ledger, and a retry with the same key returns the saved result instead of acting again. Checkpointing resumes progress but can't tell whether an uncertain external write happened. HITL thresholds, turn budgets, temperature, timeouts, and prompts all work on the model side and can't stop a duplicate backend call.

The approval path is normal code with a person deciding: queue row, notification, approval UI, and an endpoint that continues the same run_id. A second model judging the first model's action is like a student grading their own homework and defeats the gate; it may summarise or suggest, never decide. Approve-and-train keeps the gate as code but lets it improve: each decision is logged and later, offline and with review, turned into new gate rules.

Build escalation into the design from the start, not as an error handler added later. The triggers are concrete: confidence under the set floor, a request type outside the agent's charter, a dependency like the order-lookup tool being down, the user asking for a human, or a gate blocking the action. Each ends the same way: a ticket, a handoff packet (conversation summary, evidence, actions tried), and an honest message about what happens next.

Save the state after every finished step; then a crash after step 7 restarts at step 8 with earlier work kept. Don't blindly repeat a step with side effects: if step 7's result is unclear, check its status or rely on idempotency before repeating it. Rerunning everything repeats seven real actions, a bigger model doesn't stop crashes, and emailing an admin isn't recovery.

A durable agent keeps the function call separate from the real task. On a pending approval the controller sets the phase to WAITING_FOR_APPROVAL, saves, and returns: the call is over, the task isn't. WAITING_FOR_RETRY works the same, with a next_retry_at. Only COMPLETED (or a failure end state) closes the task. On resume, load the run_id, check phase and pending work first, and continue; never start a new conversation or replay the first prompt.

You can only enforce a budget if the run saves both the ceiling and the usage, so 20 turns remain after resume however long the approval took. A human approval unblocks one pending tool; it doesn't reset the counter. When any budget (model turns, tool calls, cost) runs out, the run goes to an end state like BUDGET_EXHAUSTED for a person to review. A warning that lets the loop continue is not a budget.

A timeout or 503 gets a limited retry with backoff and jitter (waiting longer each time, with some randomness), or the run parks; retrying the tool uses no model turn. Bad arguments are the model's mistake, so send an error tool_result and let it try again next turn. A permission denial won't change, so never retry it. When attempts run out, the run moves to DEAD_LETTER for human review instead of looping forever.

fork_session copies the live session so each strategy starts from the same baseline without affecting the other. Exporting findings to a markdown file and opening new sessions loses detail and is manual, and telling the model "forget strategy A" doesn't erase context. When early file reads are out of date because a colleague pushed changes, start fresh with a verified summary of findings and decisions, then re-read the changed files. A fork would copy the stale reads, and staying in the old session keeps conflicting content in context.

Two forks editing the same files would clash, so give each editing experiment its own git worktree. Exporting a session gives you a document that misses the real state's nuance. Compaction shortens history in place and makes no branch. Because a fork copies everything, it copies old tool results too, which is why recovering from stale context uses a fresh session.

The 1.8 seconds is a projection, and the merged prompt's accuracy was never measured. Putting classification, extraction, and validation into one prompt splits the model's attention three ways, and focused chain steps with checks between them do better than multi-task prompts. Using the merge only for low-risk types creates two inconsistent pipelines; the 68% contract accuracy is a separate problem, and adding more context per step doesn't fix a focus problem.

Your harness catches rate limits, timeouts, and bad JSON exactly. A summary sentence that sounds fine but misstates the source is invisible to code, so you need an independent model judge whose scores are checked against human-labeled examples. You don't need a different model family, and a judge is no guarantee; the calibration is what makes the score mean something.

In Claude Code and the Agent SDK, the coordinator starts a subagent by calling Task (now named Agent). Without it in allowedTools, the model can't delegate, so it quietly does everything itself and no error appears. A harness built directly on the Messages API has no such built-in tool; it delegates through its own worker function, or a delegation tool you design. Whether the tool exists and whether it's permitted are two separate checks.