Domain 1 · 27% of exam

Agentic Architecture & Orchestration glossary

67 terms drawn from this domain’s 7 lessons and the sources they cite. A term that matters in more than one domain appears on each of their pages.

The full glossary is searchable across all five domains, and the domain curriculum explains where each term is used.

--continue: The flag (`-c`) that resumes the most recent session in the current directory without any ID tracking. Use `--resume` instead when a script juggles multiple conversations and must target a specific one. code.claude.com › headless
--resume: The flag that continues a specific existing session by ID or name, restoring the full conversation history, model, agent, permission mode, goals, and unexpired scheduled tasks — except `plan` and `bypassPermissions`, which are never restored. It never creates a session, and lookup is scoped to the current project directory and its git worktrees. Running it from a different directory than the session was created in is the most common cause of getting a fresh session instead. code.claude.com › sessions
Agent tool: The built-in tool that spawns subagents, renamed from `Task` in Claude Code v2.1.63 and emitted as `Agent` in `tool_use` blocks. Include `Agent` in `allowedTools` to auto-approve subagent invocations without a permission prompt. code.claude.com › subagents
AgentDefinition: The SDK configuration object for a subagent. `description` (when to use the agent) and `prompt` (its system prompt) are required; `tools` and `model` are optional. Omitting `tools` gives the subagent every tool available to subagents, while listing them restricts it to exactly those. Note the field is named `prompt`, not `systemPrompt`. code.claude.com › subagents
Agentic loop: The core execution cycle behind a Claude-based agent: send a request to the Messages API, inspect `stop_reason`, execute any requested tools, append the results to conversation history, and repeat. It is deterministic control flow defined in code, not a prompt trick or a retry loop. platform.claude.com › how-tool-use-works
Attention dilution: The failure mode where an agent processing too many items in one pass gives thorough analysis to the first few and skims the rest, flagging a pattern in one file while approving identical code in another. The fix is a multi-pass architecture — a dedicated local analysis pass per item so each gets the full attention budget, then a separate cross-item integration pass — not a bigger context window, because the problem is attention quality rather than context capacity.
canUseTool: The permission callback that fires only when the evaluation flow falls through to a prompt. Tools auto-approved by `acceptEdits`, `bypassPermissions`, or an allow rule never reach it — so for a check that must run on every call, use a `PreToolUse` hook instead. code.claude.com › permissions
Checkpointing: The separate mechanism that snapshots and reverts file changes, creating one checkpoint per user prompt. Its blind spot is that it tracks only edits made through Claude's own file-editing tools, not changes made via Bash commands. code.claude.com › checkpointing
Coordinator agent: The hub of a hub-and-spoke system. It decomposes the task, dynamically selects which subagents to invoke, partitions research scope to minimise duplication, passes context explicitly, aggregates results, runs iterative refinement loops when coverage is short, and handles errors.
Deny rule: A permission rule that blocks a matching tool call even in `bypassPermissions` mode. A hook returning `allow` does not skip deny and ask rules — those are evaluated regardless of the hook result. code.claude.com › permissions
disable_parallel_tool_use: The boolean that restricts Claude to a single tool call per response. It lives **inside** the `tool_choice` object, not at the top level: with `auto` it means at most one tool call, with `any` or `tool` exactly one. platform.claude.com › parallel-tool-use
disallowed_tools: The deny lever with two distinct forms: a bare entry such as `"Bash"` removes the tool definition from the request entirely so Claude cannot see or attempt it, while a scoped entry such as `"Bash(rm *)"` keeps the tool visible and denies only matching calls, in every permission mode. code.claude.com › permissions
Duplicated-work failure: The delegation failure where vague per-subagent task descriptions cause two agents to research the same topic while another goes uncovered. The fix is to give each subagent an objective, an output format, guidance on tools and sources, and clear task boundaries. anthropic.com › multi-agent-research-system
Dynamic adaptive decomposition: Generating subtasks from what is discovered at each step rather than planning them up front, so the plan evolves as the agent learns. It suits open-ended investigation — legacy exploration, security audits, debugging — where the scope is not known at the start.
Effort scaling: The rule that a coordinator should scale subagent count and tool calls to query complexity: roughly one agent with 3-10 tool calls for simple fact-finding, 2-4 subagents with 10-15 calls each for direct comparisons, and more than 10 subagents for complex research. anthropic.com › multi-agent-research-system
end_turn: The `stop_reason` value meaning the model reached a natural stopping point. The agentic loop terminates and the response is used as the final answer. platform.claude.com › handling-stop-reasons
Evaluator-optimizer: The workflow pattern where one LLM call generates a response while another evaluates it and gives feedback, in a loop. It fits best when evaluation criteria are clear and iterative refinement provides measurable value. anthropic.com › building-effective-agents
fork_session: The boolean option (`forkSession` in TypeScript, default false) used with `resume` to fork to a new session ID instead of continuing the original. The fork starts from a copy of the history up to that point; the original's ID and history are unchanged, leaving two independently resumable sessions. code.claude.com › sessions
Fresh start with summary injection: Starting a new session and injecting a structured summary of the prior session’s findings, naming the files that changed so the agent performs targeted re-analysis of only those. It is the correct response to stale context or a long, cluttered history: no stale tool results survive, the prior knowledge does, and nothing is re-explored needlessly.
general-purpose subagent: The built-in subagent Claude can invoke at any time, alongside the two authored routes of programmatic definition via the `agents` option and filesystem definition in `.claude/agents/`. On a name clash, the programmatic definition wins over the filesystem one. code.claude.com › subagents
Ground truth (adaptive decomposition): Real feedback from the environment at each step — tool results, test runs, actual file contents — that an adaptive plan must adapt to instead of reasoning from its own prior assumptions. anthropic.com › building-effective-agents
Hook decision priority: When multiple hooks or permission rules disagree, `deny` beats `defer`, which beats `ask`, which beats `allow`. If any hook returns `deny` the operation is blocked regardless of what the others returned. code.claude.com › hooks
Hook events: The SDK's callback points on agent events. Available in both Python and TypeScript: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `UserPromptSubmit`, `Stop`, `SubagentStart`, `SubagentStop`, `PreCompact`, `PermissionRequest`, `Notification`. `SessionStart` and `SessionEnd` are TypeScript-only. code.claude.com › hooks
HookMatcher: The matcher configuration that scopes a hook to particular events. Its `matcher` field is tested against the event's target — usually the tool name — and accepts alternations such as `Write|Edit` or regexes such as `^mcp__`; a hook with no matcher runs for every event of that type. code.claude.com › hooks
Hub-and-spoke architecture: The multi-agent shape the exam tests: a coordinator at the centre and specialised subagents as spokes, with all inter-subagent communication flowing through the coordinator. Centralisation buys observability, consistent error handling, and controlled information flow.
is_error: The optional boolean on a `tool_result` block that signals a client-tool execution failure; return the error text as `content` with `"is_error": true` and Claude incorporates it into its response. Server-tool errors are handled transparently by Anthropic's infrastructure and are not your responsibility. platform.claude.com › handle-tool-calls
Iteration cap: A maximum number of loop iterations, used as a safety bound to maintain control over cost and compounding errors. It is acceptable as a backstop but never as the primary stopping mechanism, and it does not fix premature termination. anthropic.com › building-effective-agents
Malformed-call retry: Claude's own model-level behaviour: when its tool call is invalid or missing required parameters, it retries 2-3 times with corrections before apologising to the user. This is a separate mechanism from `isRetryable`, which applies after your tool has run and failed. platform.claude.com › handle-tool-calls
max_tokens: An absolute ceiling on generated output, not a target — the model may stop earlier, so a short result is not evidence that your criteria suppressed output. Exceeding it produces `stop_reason: "max_tokens"`, handled by raising the limit or continuing the response. platform.claude.com › messages
max_turns: The Agent SDK option (`maxTurns` in TypeScript) documented as the maximum agentic turns, meaning tool-use round trips. It bounds the loop as a safety measure but never signals that the task finished — completion is still `stop_reason`. code.claude.com › typescript
model_context_window_exceeded: The `stop_reason` returned when the response filled the model's context window; treat it as truncation, the same way you would `max_tokens`. On 4.5-and-later models a request whose input plus `max_tokens` exceeds the window is accepted and stops this way rather than erroring. platform.claude.com › context-windows
Model-driven decision-making: Letting Claude reason about which tool to call next from the current context, rather than hard-coding the sequence in a pre-configured decision tree or fixed tool sequence. It is favoured because the model adapts to situations the developer never mapped out — except where business logic demands deterministic compliance.
Multi-agent token premium: The measured cost of orchestration: agents use roughly 4x more tokens than chat interactions and multi-agent systems roughly 15x more. Multi-agent architecture is only economically viable when the task's value exceeds that premium. anthropic.com › multi-agent-research-system
Narrow decomposition failure: The coordinator failure where whole categories of a broad topic are never assigned to any subagent, so the final report is incomplete in scope rather than depth. The root cause is the coordinator's decomposition, never the downstream subagents.
Orchestrator-workers: Anthropic's formal name for the hub-and-spoke coordinator-subagent pattern: a central LLM dynamically breaks down tasks, delegates them to worker LLMs, and synthesises their results. Its defining trait versus parallelization is that subtasks are determined by the orchestrator rather than pre-defined. anthropic.com › building-effective-agents
Parallel subagent spawning: Emitting multiple Task/Agent tool calls in a single coordinator response rather than one per turn, so independent subtasks finish in the time of the slowest one rather than the sum. Isolated context windows are what make the concurrency safe. code.claude.com › subagents
Parallel tool use: Claude may call several tools in a single response, and Claude 4 and later do so by default when it helps. Return one `tool_result` per `tool_use` block, all in one user message with no text before them; splitting results across messages teaches the model to stop calling tools in parallel. platform.claude.com › parallel-tool-use
Parallelization (workflow pattern): The named workflow pattern with two sub-variants: sectioning, which breaks a task into independent subtasks run in parallel, and voting, which runs the same task several times for diverse outputs. Its subtasks are pre-defined, which distinguishes it from orchestrator-workers. anthropic.com › building-effective-agents
pause_turn: The `stop_reason` returned when a long-running server-tool turn is paused, typically because a server-tool loop hit its internal iteration limit. Handle it by appending the assistant response to `messages` and re-requesting unchanged — never by treating the turn as done. platform.claude.com › handling-stop-reasons
Permission evaluation order: The strict sequence the SDK applies to every tool request: hooks, then deny rules, then ask rules, then permission mode, then allow rules, then the `canUseTool` callback. Prompt-based guidance appears nowhere in this list, which is why it is not enforcement. code.claude.com › permissions
permissionDecision: The `PreToolUse` hook output field whose four values are `allow`, `deny`, `ask`, and `defer`. `defer` does not fall through to the next permission step — it ends the query so you can resume it later, and any `updatedInput` returned with it is ignored. code.claude.com › hooks
PostToolUse: The hook event that runs after a tool executes but before the model processes the result, used to normalise heterogeneous tool output into a consistent format. It cannot block a policy-violating action, because by the time it fires the action has already happened. code.claude.com › hooks
PostToolUse output fields: `additionalContext` appends information to a tool result while leaving the original intact; `updatedToolOutput` replaces the tool’s output before Claude sees it and works for any tool in both SDKs. For normalising heterogeneous tool output, `updatedToolOutput` is the closer match, since it substitutes the normalised result rather than adding a note beside raw data. code.claude.com › hooks
Premature termination: The failure mode where an agent stops mid-task, classically caused by checking `response.content[0].type == "text"` for completion when Claude returned explanatory text alongside a `tool_use` block. The fix is always a correct `stop_reason` check, never an iteration cap.
Prerequisite gate: A programmatic check that blocks a tool from executing until a prior condition is met — for example refusing `process_refund` until `get_customer` has returned a verified customer ID in the session. It is code, so the model cannot bypass it by deciding to skip a step.
PreToolUse: The hook event that runs before a tool executes, able to block, modify, or redirect the outgoing call — the implementation mechanism for prerequisite gates. Hooks run before every other permission step and a hook deny applies even in `bypassPermissions` mode. code.claude.com › hooks
Programmatic enforcement: Hooks, prerequisite gates, or code-level checks that physically block a tool until its prerequisites complete. It is deterministic — it works every time regardless of what the model decides — and is the required answer for financial, security, and compliance operations.
Prompt chaining: Anthropic’s formal name for a fixed sequential pipeline: a task decomposed into predetermined steps, each LLM call processing the previous one’s output. The point is to trade latency for higher accuracy by making each call an easier task. Chains can carry “gates” — programmatic checks on intermediate output that catch a malformed result before it propagates. anthropic.com › building-effective-agents
Prompt-based guidance: Putting workflow rules in the system prompt. It is probabilistic: it works most of the time but carries a non-zero failure rate, which is acceptable for formatting and style but not where a single failure means financial loss, a security breach, or a compliance violation.
refusal: The `stop_reason` returned when streaming classifiers intervene over a potential policy violation; current models can decline on an otherwise-normal HTTP 200 response. Documented handling is to read `stop_details` and retry on a fallback model. platform.claude.com › handling-stop-reasons
Routing (workflow pattern): The workflow pattern that classifies an input and directs it to a specialised follow-up task — for example sending cheap, common cases to a smaller model and hard ones to a more capable model. anthropic.com › building-effective-agents
Session: The conversation history the SDK accumulates while an agent works — the prompt, every tool call, every tool result, and every response — written to disk as JSONL under `~/.claude/projects/<encoded-cwd>/*.jsonl`, where the encoded directory is the working directory with every non-alphanumeric character replaced by `-`. Sessions persist the conversation, not the filesystem. code.claude.com › sessions
session_id: The identifier a headless run reports in its JSON result, captured in scripts with `claude -p "..." --output-format json | jq -r '.session_id'` so a later step can pass it to `--resume`. code.claude.com › headless
Stale context problem: Resuming a session after files have changed means the old tool results are still in history, so the agent reasons from code that no longer exists and gives contradictory advice. Asking it to re-read the changed files is not enough — the stale results stay in the conversation.
stop_reason: The response field that says why generation stopped, and the only reliable signal for agentic loop control. It is deterministic and unambiguous, arrives in the body of a successful HTTP 200 response (errors are 4xx/5xx instead), and should be branched on rather than natural-language cues, text checks, or iteration counts. platform.claude.com › messages
stop_sequence (stop reason): The `stop_reason` returned when one of your custom `stop_sequences` was generated. Read the response's `stop_sequence` field to see which one fired. platform.claude.com › handling-stop-reasons
Structured handoff protocol: The self-contained summary an agent must produce when escalating to a human, who does not have access to the conversation transcript. It carries the customer ID, a conversation summary, root cause analysis, the amount where relevant, and a recommended action.
Subagent: A specialised agent invoked by a coordinator that runs in its own fresh context window. It does not inherit the coordinator's conversation history or system prompt, shares no memory between invocations, and returns only its final distilled message to the parent. code.claude.com › subagents
Subagent context isolation: A subagent's context window starts fresh with no parent conversation; the only content crossing the boundary is the Agent tool's prompt string. Intermediate tool calls and results stay inside the subagent, so heavy exploration never accumulates in the coordinator's context. code.claude.com › subagents
Subagent lifecycle hooks: `SubagentStart` fires when a subagent is spawned and is observational — it receives the subagent’s type and id and can log or inject context, but cannot block or modify the invocation. `SubagentStop` fires when the subagent finishes and can return `decision: "block"` with a reason to send it back to work, but does not transform the output. To block a spawn use a PreToolUse hook on the Agent tool; to reshape returned output use PostToolUse.
Task tool: The exam guide's name for the mechanism a coordinator uses to spawn subagents; `"Task"` must appear in the coordinator's `allowedTools` or it cannot invoke subagents at all. Current Claude Code renamed it `Agent`, though `Task` still appears in the `system:init` tools list. code.claude.com › subagents
tool_result block: The block that returns a tool's output to Claude, carrying `tool_use_id` (matching the request's `id`), optional `content`, and optional `is_error`. It is sent in a **user**-role message — there is no `tool` or `function` role in the Messages API. platform.claude.com › handle-tool-calls
tool_result placement rules: Two hard formatting rules: the tool result message must immediately follow the corresponding `tool_use` message with nothing in between, and all `tool_result` blocks must come first in that message's content array, before any text. Breaking either produces a 400 rather than degraded behaviour. platform.claude.com › handle-tool-calls
tool_use (stop reason): The `stop_reason` value meaning the model invoked one or more tools. It is the only value that continues the loop by executing tools and returning their results; treat every other value as "not finished, check why". platform.claude.com › handling-stop-reasons
tool_use block: The assistant-role content block in which Claude requests a tool call. It carries three fields: `id` (unique, used to match the result later), `name`, and `input` conforming to the tool's `input_schema`. platform.claude.com › handle-tool-calls
tool_use_id: The field on a `tool_result` block that matches it to the `id` of the originating `tool_use` block. Results are matched by this ID, which is what makes parallel tool calls in one iteration unambiguous. platform.claude.com › handle-tool-calls
updatedInput: The `PreToolUse` output field that rewrites a tool call's input rather than blocking it. Paired with `permissionDecision: "allow"` it auto-approves the modified input; with `"ask"` it shows the modification to the user; omitted, the modified input still applies and flows through normal permission evaluation. code.claude.com › hooks