CCAR-F Glossary — 219 Terms, Config Keys and API Fields

Flags & symbols

--allowedTools: The CLI flag listing tools, in permission-rule syntax, that run without a permission prompt. It pre-approves rather than restricts — to restrict which tools exist at all, use --tools.
--bare: Minimal mode: it skips auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md so scripted runs start fast and reproduce across machines. It is the recommended mode for scripted and SDK calls and is slated to become the -p default — at the cost of the CLAUDE.md context CI reviews otherwise rely on.
--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.
--disallowedTools: The CLI flag with two behaviours: a bare tool name such as "Edit" (or "*") removes the tool from Claude's context entirely, while a scoped rule such as Bash(rm *) leaves the tool available and denies only matching calls.
--fork-session: The CLI flag combined with --continue or --resume to create a new session ID instead of reusing the original, so two divergent fixes can be compared without losing the baseline conversation. /branch does the same in-session.
--json-schema: The print-mode-only flag that validates the agent's final output against a JSON Schema. With --output-format json the conforming data lands in the envelope's structured_output field — extract it with jq -r '.structured_output', not from the top level. An invalid schema now exits with an explicit error rather than silently falling back to text.
--output-format: The flag choosing the shape of a print-mode run's output: text (default), json (a machine-parseable envelope with result text, session ID, usage, total_cost_usd and a per-model cost breakdown), or stream-json (NDJSON in real time, whose last line is always a result message).
--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.
--tools: The CLI flag that restricts which tools are available to the agent at all, as opposed to --allowedTools, which only skips the permission prompt. In the SDK the equivalent tools option keeps only the listed built-ins, and tools: [] removes every built-in while leaving MCP tools unaffected.
-p (--print): The flag that switches Claude Code to non-interactive print mode: it processes the prompt, writes the result to stdout, and exits. Without it a CI job hangs forever waiting for keyboard input. It is the single most directly tested fact in Domain 3.
.claude/rules/: The directory of topic-specific rule files, discovered recursively so subdirectories are included. A rule file with no paths frontmatter loads at launch with the same priority as .claude/CLAUDE.md; personal rules in ~/.claude/rules/ apply to every project and load before project rules, giving project rules higher priority on conflict.
.mcp.json: The project-scope MCP configuration file in the repository root. It is checked into version control and shared with every teammate, which is why credentials belong in ${VAR} references rather than literal values.
@ path import: The directive that inlines another file into a CLAUDE.md — a bare @ immediately before a path on its own line, such as @./standards/naming.md. There is no @import keyword in current docs. Imports recurse to a maximum depth of four hops, and paths inside code spans or fenced code blocks are never parsed as imports.
/clear: The command that starts fresh with an empty context while Claude Code saves the previous conversation, so it stays resumable via /resume. Best practice is to use it frequently between tasks; /compact is the alternative when you want a summary of the current work to survive.
/compact: The command that replaces conversation history with a summary. /compact <instructions> focuses that summary — for example /compact Focus on the API changes — so what survives is the part still relevant to the current iteration rather than a generic recap.
/init: The command that generates a starting CLAUDE.md by analysing the codebase, capturing build commands, test instructions, and discovered conventions. If a CLAUDE.md already exists it suggests improvements rather than overwriting.
/memory: The diagnostic command that shows which memory files are loaded in the current session. It reveals loading, it never triggers it — use it to work out why behaviour differs between sessions or teammates.
/rewind: The command (also Esc-Esc on an empty prompt) that opens the rewind menu, offering to restore code, conversation, or both from the automatic per-prompt checkpoints. It is local undo that complements rather than replaces git, and it cannot revert changes made by Bash commands.
~/.claude.json: The personal, non-version-controlled file storing both local-scoped MCP servers (nested under the project's path) and user-scoped ones. It is a different thing entirely from .claude/settings.local.json, which holds local settings inside the project directory.
$ARGUMENTS: The placeholder expanding to all arguments passed when a skill or command is invoked. If it appears nowhere in the body, Claude Code appends the arguments automatically as ARGUMENTS: <value> so they are never silently dropped. Positional access uses $N (shorthand for $ARGUMENTS[N]) with 0-based indexing, so $0 is the first argument.
2KB description limit: Claude Code truncates tool descriptions and MCP server instructions at 2KB each. Keep them concise and put critical details — especially boundary statements — near the start, or they may never reach the model.

A

Access failure vs valid empty result: An access failure means the tool could not reach the data source, so it is isError: true and a retry candidate. A valid empty result means the tool reached the source and found nothing, so it is isError: false with resultCount: 0 and is the answer, not a failure. Confusing the two causes wasted retries and wrong escalations.
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.
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.
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.
Aggregate metrics trap: A 97% overall accuracy figure can hide 40-60% error rates on specific document types, because high-volume easy segments dominate the average. The rule is to validate accuracy by document type and field segment before automating, then follow the sequence: measure by segment, calibrate confidence, set thresholds, add stratified sampling, and only then reduce human review.
allowed-tools: The skill frontmatter field the exam guide describes as restricting tool access during skill execution. Current docs define it as pre-approving the listed tools for the invoking turn so they run without a permission prompt — every other tool stays available and the grant clears on your next message.
Ambiguous customer matching: When a lookup returns several possible customer records, the agent must ask for an additional identifier — email, phone, order number. Never select by recency, activity, or any other heuristic: the wrong pick risks exposing one customer's data to another or acting on the wrong account.
Artifact/filesystem output pattern: Having subagents write large results to an artefact or file that bypasses the coordinator, preserving fidelity and cutting token overhead through a multi-stage pipeline. Rendering should also stay content-appropriate rather than uniform: financial data as tables, news as prose, technical findings as structured lists.
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.

B

Bash prefix matching: Bash permission rules match on a command prefix, and the trailing space is load-bearing: Bash(git diff *) matches any command starting with git diff, whereas Bash(git diff*) would also wrongly match git diff-index.
Batch lifecycle: A batch begins processing immediately and its processing_status moves through in_progress, canceling, and ended; poll until it ends. Every request then resolves to one of four result types — succeeded, errored, canceled, or expired — and only succeeded is billed, so a stalled or cancelled batch costs nothing for work that never ran.
Batch request constraints: A batch is capped at 100,000 requests or 256 MB, whichever comes first, with an oversized batch returning 413 request_too_large. Almost any Messages API request can be batched, but stream: true and the stateful Threads parameters store/previous_thread_event_id are rejected. Parameter validation is asynchronous, surfacing only after the batch ends — so dry-run one request against the synchronous API first.
Batch results retrieval: Results appear as a .jsonl file at results_url, populated only once the batch has ended, in no guaranteed order. Stream them rather than bulk-downloading, and note the 29-day availability window runs from created_at, not from ended_at.
Batch SLA calculation: Work backwards from the 24-hour maximum: a 30-hour SLA leaves 6 hours of buffer, so the final batch must be submitted at least 30 hours before the deadline and batches submitted every few hours keep one always in flight.
Batch tool-calling limitation: A batch request cannot execute a client tool and continue the same logical turn, because threads are stateful and batch requests are not. Server tools do run their full agentic loop inside the batch worker, but a result returning pause_turn needs a new follow-up request to continue. Anything needing mid-turn client tool execution belongs on the synchronous API.
Batch vs sequential feedback: Deliver interacting fixes in a single message so the model sees all the constraints at once; deliver independent fixes one at a time, since batching unrelated issues confuses which feedback applies where.
Batch vs synchronous: Blocking workflows — pre-merge CI checks, real-time review feedback, anything a developer waits on — stay on the synchronous API. Latency-tolerant workflows — overnight technical debt reports, weekly audits, nightly test generation — move to the Batch API for the 50% saving. Moving everything to batch for the savings is the exam's classic wrong answer.
Bloated tool sets: Anthropic's named failure mode: tool sets covering too much functionality or creating ambiguous decision points about which tool to use. Each extra overlapping tool costs both decision complexity and context budget, making tool scoping a context-engineering discipline as well as a routing one.
Build-vs-use decision: Evaluate maintained community MCP servers first for standard integrations such as Jira, GitHub, Slack, Linear, or Notion; build a custom server only for team-specific workflows, custom business logic in the tool layer, or proprietary internal systems with no community equivalent.
Built-in tools: The tools Claude Code ships with. This task statement names six — Read, Write, Edit, Bash, Grep, Glob — while the documented roster is larger: Bash, Read, Write, Edit, Glob, Grep, WebFetch, Agent, "and others".

C

Calibration: Mapping reported confidence to actual accuracy by running labelled validation sets — data where the answer is already known — through the system, then setting routing thresholds from the result. Judge whether the correct final state was reached rather than whether a specific process was followed, and keep manual testing, which catches edge cases evals miss.
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.
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.
CitationAgent: A dedicated post-synthesis pipeline stage whose sole job is locating citations for the synthesised text, rather than trusting the synthesis step to carry attribution through on its own.
claude mcp add: The CLI command with two shapes: claude mcp add --transport http <name> <url> for a remote server, and claude mcp add [options] <name> -- <command> [args...] for a local stdio server, where the -- separator is required so everything after it reaches the server process untouched. claude mcp add-json <name> '<json>' adds one from a JSON blob.
CLAUDE.local.md: A personal memory file sitting next to CLAUDE.md at any level, loaded after it so it has the last word at that level. It is gitignored by convention and scoped to a single working-tree checkout, so sharing preferences across git worktrees means importing a file from your home directory instead.
CLAUDE.md: The memory file Claude Code loads automatically each session, at three authored levels: user (~/.claude/CLAUDE.md, personal, never shared via git), project (.claude/CLAUDE.md or a root CLAUDE.md, version-controlled and shared), and directory (a subdirectory CLAUDE.md that loads on demand when Claude reads files there). Docs recommend keeping each file under 200 lines.
CLAUDE.md load order: All discovered CLAUDE.md files are concatenated into context rather than overriding each other, ordered broadest scope first so instructions closest to the launch directory are read last, with CLAUDE.local.md appended after CLAUDE.md at the same level. It is not a precedence chain: if two rules contradict, Claude may pick one arbitrarily.
Compaction: Taking a conversation nearing the context limit, summarising it, and reinitiating a new window with that summary — one of three long-horizon techniques alongside structured note-taking and sub-agent architectures. Its named risk is losing subtle but critical context whose importance only emerges later. Tool result clearing is the lightest-touch form, and a beta server-side compaction on Claude 4.6+ summarises earlier turns automatically.
Confidence-based routing: Reporting high-confidence findings directly and routing low-confidence ones to human review. Raw self-reported confidence is uncalibrated — a form of the model judging itself — so it is unfit for automated decisions until thresholds are calibrated, and it is never a substitute for explicit criteria defining what counts as a valid finding.
Conflict handling: When two credible sources report different values, annotate both with full attribution and let the consumer decide — never arbitrarily select one, average them, or prefer the more authoritative publisher. Different publication dates often explain the difference as a trend rather than a contradiction, which is why temporal context must be preserved through synthesis, and a conflict_detected boolean marks a value genuinely in conflict as distinct from one that is simply absent.
Constrained tool alternative: Least privilege applied to tool design: give a subagent load_document, which validates document URLs only, rather than a generic fetch_url. The narrower tool prevents misuse, clarifies purpose, and reduces unintended side effects.
Context awareness: The built-in ability of Sonnet 5, Sonnet 4.6, Sonnet 4.5, and Haiku 4.5 to track their own remaining token budget through a conversation via budget tags the API injects automatically. There is nothing to enable, and it lets the model factor remaining room into its own decisions.
Context degradation: The observable symptom of a long exploration session: the model starts referencing "typical patterns" instead of the specific classes, methods, and dependency chains it discovered earlier, as verbose discovery output buries the precise findings. It is not a token-limit problem, so a larger context window does not fix it.
Context rot: The documented phenomenon that accuracy and recall degrade as token count grows, which makes curating what is in context as important as how much space there is. Context is a finite resource with diminishing marginal returns — the model draws on a limited attention budget that every added token depletes.
Context window: All the text a model can reference when generating a response, including the response itself. Fable 5, Opus 5, and Sonnet 5 ship a 1,000,000-token window by default with no beta header; Haiku 4.5 ships 200,000. Maximum output is 128k tokens for the 1M-window models (300k via a Batches API beta on Opus and Sonnet).
Context window overflow: If the input alone exceeds the window, every model returns a 400 invalid_request_error ("prompt is too long") — there is no silent truncation. On Claude 4.5 and later, input plus max_tokens exceeding the window is accepted instead and stops with model_context_window_exceeded. The token counting API, POST /v1/messages/count_tokens, estimates usage beforehand and is free with its own separate rate limit.
context: fork: The skill frontmatter setting that runs the skill in an isolated subagent context, with the skill content becoming the subagent's prompt and no access to the parent conversation. It keeps verbose output out of the main context. The companion agent field picks the subagent type — Explore, Plan, general-purpose (the default), or a custom one from .claude/agents/.
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.
Coverage annotations: Explicitly marking synthesis gaps — "section on geothermal energy is limited due to unavailable journal access during research" — rather than silently omitting a topic. Without them a gap reads as the topic being irrelevant rather than the source being unavailable.
custom_id: The per-request identifier in a batch, matching ^[a-zA-Z0-9_-]{1,64}$. Results can come back in any order, so always match results to requests by custom_id and never by position.

D

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.
detected_pattern: A field on a structured finding that tags which specific construct triggered it, so dismissal rates can be analysed by pattern. When one pattern is dismissed consistently the documented fix is a formal rule or prompt refinement for that pattern — not another retry.
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.
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.
disallowed-tools: The real access boundary for a skill in current docs: a bare tool name removes the tool from Claude's context entirely, as do deny rules in permission settings.
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.
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.
Dynamic context injection: The ` !<command> ` syntax in a skill or command body, which runs a shell command before the content is sent and substitutes the output for the placeholder — so Claude receives actual data such as a git diff rather than the command text.

E

Edit: The built-in tool for targeted file modification via a unique old_string match. It fails when the anchor text is not unique — a safety mechanism, not a bug — and Read + Write is the last-resort fallback only when the anchor cannot be disambiguated.
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.
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.
enum: The JSON Schema field restricting a value to a fixed set of labels. For classification tasks the documented advice is to use a tool with an enum field of valid labels, or structured outputs, rather than asking for a category in prose — few-shot examples teach which label is right, the enum guarantees only defined labels can be emitted.
Error propagation anti-patterns: Two failure modes: silent suppression, returning empty results marked as success so the coordinator never retries and the final output has invisible gaps — the worst of the two; and workflow termination, killing an entire pipeline on one subagent failure and discarding work that succeeded. The correct middle ground is local retry, then structured propagation, then resuming from the last good state.
Evaluation rubric: The criteria an LLM judge scores against, in Anthropic's documented case factual accuracy, citation accuracy, completeness, source quality, and tool efficiency. The shape that proved most consistent was a single call with a single prompt outputting a 0.0-1.0 score plus a pass/fail grade, run against roughly 20 representative queries — enough to see the impact of a change.
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.
Examples with reasoning: Each few-shot example must show the input, the output, and why that decision was chosen over plausible alternatives. Examples without reasoning teach literal pattern-matching; examples with reasoning teach the generalisable decision principle.
Explicit categorical criteria: Prompt criteria that state precisely what to flag and what to skip — bugs and security vulnerabilities in, minor style preferences out — instead of vague instructions such as "be conservative" or "only report high-confidence findings". Severity levels must be defined with concrete code examples per level, never prose descriptions, or the model has to interpret what the level means.
Explore → Plan → Implement → Commit: The recommended four-phase Claude Code workflow, and the scaffold iterative refinement hangs off: exploration and planning precede the first draft, so refinement happens during Implement against a plan that already accounted for constraints. Skip the planning phase when you could describe the diff in one sentence.
Explore subagent: A built-in, fast, read-only agent optimised for searching and analysing codebases, with Write and Edit explicitly denied. It is invoked with a thoroughness level — quick, medium, or very thorough — and, uniquely alongside the Plan subagent, skips CLAUDE.md files and the parent session's git status; every other subagent loads both.

F

False-positive trust problem: A high false-positive rate in one finding category destroys developer trust in every category, even ones running at high accuracy. The counter-intuitive fix is to temporarily disable the noisy category, refine it against concrete examples, and re-enable it once precision improves — putting system-wide trust ahead of category completeness.
Few-shot examples: The most effective technique for consistent output, and the right answer when detailed instructions still produce inconsistent formatting, inconsistent judgement on ambiguous cases, or empty fields for data that is present in an unusual format. Use 2-4 targeted, diverse examples: fewer than two establishes no pattern, more than four wastes tokens and risks context rot.
Forced tool_choice and extended thinking: Manual extended thinking (thinking: {type: "enabled"}) supports only tool_choice auto and none; any and tool return an error. Adaptive thinking, including on models where thinking is on by default, does support forced tool use.
Forced-selection prefill: With tool_choice set to any or tool, the API prefills the assistant message to force a tool call, so the model emits no natural-language response or explanation before the tool_use blocks even if explicitly asked. Any field logging Claude's pre-call reasoning will be empty.
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.
Four error categories: Every tool failure falls into one of four categories, each with its own recovery: transient (timeouts, unavailability, rate limits — retry after a delay), validation (bad input format or missing fields — fix the input and retry), business (policy violations and limit exceedances — never retry, escalate or take an alternative workflow), and permission (access denied or insufficient credentials — escalate or use different credentials).
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.

G

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.
GitHub Actions integration: Claude Code in CI triggered by an @claude mention in a PR or issue (the default trigger_phrase), built on the Claude Agent SDK. The GitHub App needs read and write on Contents, Issues, and Pull requests, and --max-turns defaults to 10 inside claude_args.
Glob: The built-in tool that matches file paths by naming pattern, such as **/*.test.tsx or **/config.*. It finds files by their names; it cannot find what files contain.
Grep: The built-in tool that searches file contents for patterns — function callers, error messages, import statements. It is the right tool whenever you are looking for what is inside files.
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.

H

Headless operational limits: Piped stdin into claude -p is capped at 10MB; exceeding it errors with a non-zero exit. SIGTERM on a -p run aborts the in-progress turn, terminates any running Bash process tree, runs SessionEnd hooks, and exits with code 143.
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.
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.
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.
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.

I

Incremental discovery: The documented exploration order: Grep for entry points, Read to trace flows and follow imports, Grep again for wrapper or barrel names, and Read only what the previous step justified. Reading every file up front is the costliest exploration mistake.
Incremental review context: Feeding prior review findings into an automated CI review and instructing Claude to report only new or still-unaddressed issues. Without it, every push re-derives the same comments — including ones the developer deliberately chose not to act on — and duplicate comments erode trust in the review.
Independent review instance: A separate Claude invocation with no access to the generating session's reasoning, so it judges the output on what it sees alone. A reviewer in a fresh context sees only the diff and the criteria, never the justification that produced the change — the strongest form goes further and tries to refute the result rather than re-confirm it.
input_schema: The JSON Schema object on a Messages API tool definition that describes the tool's expected parameters. It is one of three required client-tool fields alongside name and description, with input_examples optional.
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.
isError: The MCP flag returned inside an otherwise-successful tool result to signal that tool execution failed, so the model reasons about recovery instead of treating the text as a normal result. It maps directly onto is_error in a Messages API tool_result and mcp_tool_result.
isRetryable: The structured error field answering one question: can a retry ever succeed? It is true for transient and validation errors and false for business and permission errors. Read it first, then read errorCategory to learn how — resend, self-correct, escalate, or take an alternative route.
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.

L

Local recovery with selective propagation: The multi-agent error pattern: subagents retry transient failures themselves, propagate only what they cannot resolve, and include partial results plus what was attempted. It prevents both silent suppression and terminating a whole workflow on one failure.
Lost in the middle: Models process the beginning and end of long inputs reliably while findings buried in the middle may be missed or under-weighted. The fix is structural rather than prompt-based: put a key findings summary at the start of an aggregated input, then the detailed results under explicit section headers.

M

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.
Managed policy CLAUDE.md: The fourth CLAUDE.md scope: an organisation-deployed file at an OS-specific system path (for example /etc/claude-code/CLAUDE.md). It applies to every session on the machine and cannot be excluded by any individual setting.
MAX_MCP_OUTPUT_TOKENS: The setting that raises Claude Code's MCP tool output ceiling. By default Claude Code warns above 10,000 tokens of tool output and caps it at 25,000.
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.
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.
MCP (Model Context Protocol): The protocol by which servers extend Claude's capabilities with external systems — databases, APIs, development tools, issue trackers — exposing tools, resources, and prompts. All tools from all configured servers are discovered at connection time and available simultaneously, with no manual activation step.
MCP annotations: Optional properties describing tool behaviour, used to disclose which tools need open-world access or make destructive changes. The spec warns that clients MUST treat annotations as untrusted unless they come from trusted servers.
MCP environment variable expansion: .mcp.json supports ${VAR}, which expands to the environment variable's value, and ${VAR:-default}, which falls back when unset. Expansion works in command, args, env, url, and headers, keeping credentials out of version control.
MCP error mechanisms: MCP separates two channels: protocol errors, which are standard JSON-RPC errors for unknown tools, invalid arguments, and server faults; and tool execution errors, reported inside a successful result with isError: true. All four error categories are tool execution errors, never protocol errors.
MCP human-in-the-loop principle: The specification's guidance that there SHOULD always be a human in the loop with the ability to deny tool invocations. It is the protocol-level reason permission errors are treated as escalate-only rather than something to route around.
MCP prompt slash command: A prompt exposed by a connected MCP server becomes a slash command in the form /mcp__servername__promptname, taking space-separated arguments; its result is injected directly into the conversation.
MCP resources: Content catalogues an MCP server exposes so an agent knows what data exists without exploratory tool calls — issue summaries, documentation hierarchies, database schemas. Reference one with @server:protocol://resource/path and it is fetched and attached automatically. Resources show what data is available; tools act on it.
MCP scope precedence: When a server name appears at more than one scope, Claude Code uses the whole entry from the highest-precedence source and does not merge fields: local, then project, then user, then plugin-provided servers, then claude.ai connectors.
MCP server management commands: claude mcp list, claude mcp get <name>, and claude mcp remove <name> manage configured servers; /mcp checks status in-session and starts OAuth 2.0 authentication for remote servers (as does claude mcp login <name>), with tokens stored and refreshed automatically. Project-scoped servers are approved before first use, cleared with claude mcp reset-project-choices. claude mcp serve runs Claude Code itself as a stdio MCP server.
MCP server scopes: Three scopes, not two: local (the default — current project only, private, stored in ~/.claude.json under that project's path), project (team-shared via .mcp.json), and user (all your projects, private, in ~/.claude.json). Older versions called local "project" and user "global".
MCP tool definition: An MCP tool carries name, description, and inputSchema, plus optional title, outputSchema, and annotations. Clients discover tools with tools/list and execute them with tools/call. Where the Messages API constrains only the input, MCP lets you pin the output structure too.
MCP transports: The specification defines two standard transports: stdio, where the client launches the server as a subprocess and exchanges JSON-RPC over stdin/stdout (clients SHOULD support it wherever possible), and Streamable HTTP, for servers running independently and serving multiple clients over HTTP POST/GET with optional SSE streaming. The standalone SSE transport is deprecated in Claude Code, and streamable-http is a configuration alias for http.
mcp__ naming pattern: MCP tools are addressed as mcp__<server-name>__<tool-name> — for example mcp__github__list_issues. Permission rules can target a whole server (mcp__server), every tool on it (mcp__server__*), or a single tool (mcp__server__tool).
Message Batches API: The asynchronous API charging 50% of standard prices unconditionally. Most batches finish in under an hour but the maximum processing window is a hard 24 hours with no latency guarantee — processing slows under demand — so design for the worst case, not the common one.
Mistake-proofing the schema: Designing the tool interface so the error is impossible rather than merely discouraged: naming parameters unambiguously (user_id, not user) and, in Anthropic's own example, always requiring absolute filepaths so relative-path errors disappear entirely.
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.
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.

N

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.

O

Optimal tools per agent: 4-5 tools, scoped to the agent's role. Selection reliability degrades as the toolkit grows — 18 tools on one agent is the exam's illustration — and relevance matters as much as count: a synthesis agent given web search will run its own searches instead of using results already handed to it.
Optional/nullable fields: The primary schema-level defence against fabrication: if a field is required, the model is pressured to invent a value when the source has none; if it is nullable, it can honestly return null. Related patterns are an explicit "unclear" enum value for genuinely ambiguous sources, and an "other" value paired with a freeform detail string.
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.
outputSchema: The optional MCP field declaring the expected output structure. Once declared, the server MUST provide structured results conforming to it and the client SHOULD validate against it — which is how you guarantee every error response actually carries its error fields.

P

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.
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.
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.
paths frontmatter: The YAML array of glob patterns on a rule file that makes it conditional: the rule loads only when Claude works on matching files. It accepts standard globs such as **/*.ts plus brace expansion such as src/**/*.{ts,tsx}, which is what lets one file cover a file type scattered across many directories at a fraction of root CLAUDE.md's token cost.
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.
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.
Permission modes: The escalating set of modes governing what runs without asking: default (reads only), acceptEdits (reads, edits, common filesystem commands), plan, auto (everything with safety checks), dontAsk (only pre-approved tools — the recommendation for locked-down CI), and bypassPermissions (everything, no prompts).
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.
Persistent case facts block: The fix for the progressive summarisation trap: extract transactional facts — customer ID, order IDs, amounts, dates, statuses — into a structured block included in every prompt and never summarised, sitting outside the summarisable narrative history. For multi-issue sessions each issue gets its own entry to prevent cross-contamination.
Plan mode: The mode in which Claude researches and proposes changes without making them — reads and read-only exploration only, with edits blocked until the plan is approved. Enter it with Shift+Tab, a /plan prefix, or claude --permission-mode plan; permissions.defaultMode: "plan" in .claude/settings.json makes it the project default. Shift+Tab again leaves without approving, and Ctrl+G opens the plan in your editor.
plugin_errors / mcp_server_errors: Fields on the stream-json format's system/init event whose keys are omitted entirely when there are no errors, so a CI gate can simply fail the job when either is non-empty.
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.
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.
Prefill: The retired workaround of pre-writing part of the assistant turn to force JSON or YAML output. Its documented successor is the Structured Outputs feature, and from Claude 4.6 and Mythos Preview a prefilled last assistant turn returns a 400 error. The API's own prefill under tool_choice any/tool is a different mechanism and still active.
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.
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.
Progressive summarisation trap: Summarising earlier turns to free budget systematically destroys exactly the information transactional systems need — amounts, dates, order numbers, and customer-stated expectations. "I'd like a refund of $247.83 for order #8891" becomes "customer wants a refund for a recent order", and the agent can no longer act.
Prompt caching: Marking a stable prefix with a cache_control breakpoint so the API reuses that processed prefix at a fraction of the input cost. Caching matches prefix by prefix from the start of the prompt, so static content — system instructions, tool definitions, reference documents — must come first and volatile content after the breakpoint, or nothing matches. An ephemeral breakpoint lasts about five minutes from last use.
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.
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.

R

Refinement technique hierarchy: The order to reach for when steering Claude Code: concrete input/output examples (2-3 pairs) when prose is interpreted differently each run; test-driven iteration, sharing test failures, for complex transformations with many edge cases; and the interview pattern — asking Claude to question you first — for unfamiliar domains where you might miss considerations.
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.
replace_all: The Edit option that replaces every occurrence of a non-unique old_string. Together with widening the anchor, it is the documented response to a non-unique match — jumping straight to Read + Write burns a file's worth of tokens on a one-line change.
Retry effectiveness boundary: Retries fix format mismatches, structural errors, misplaced values, and missed line items — anything the model can correct by re-examining information it already has. They cannot produce information genuinely absent from the source document; that extraction is flagged for human review or returned as null, not retried again.
Retry-with-error-feedback: The correct retry shape: send back the original document, the failed extraction, and the specific validation error — for example "line items sum to £450 but stated_total is £500". A naive retry without the specific error usually reproduces the same mistake.
Reviewer capacity prioritisation: Route the highest-uncertainty items to human reviewers first — low-confidence fields, ambiguous or contradictory sources, document types with historically poor accuracy — and reorder the queue dynamically. Never spread limited reviewer capacity evenly across all extractions.
Right altitude: The Goldilocks zone criteria should sit in, between two named failure modes: hardcoded brittle if/else logic, which creates fragility and maintenance cost, and vague high-level guidance, which gives the model no concrete signal. The goal is the minimal set of information that fully outlines expected behaviour — good heuristics plus explicit guardrails, not a laundry list of edge cases.
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.
Rules-based feedback: The documented best form of feedback: clearly defined rules for an output, plus which rule failed and why — code linting is the canonical example. The documented weakest is LLM-as-judge, described as "generally not a very robust method" with heavy latency tradeoffs.

S

Scoped cross-role tool: A constrained version of another role's capability given directly to the agent that needs it, so the high-frequency simple case is handled locally while complex cases still route through the coordinator. It avoids the 2-3 round trips a coordinator hop would add to every request.
Self-correction schema fields: Schema fields that make discrepancies visible without external logic: calculated_total alongside stated_total with a total_discrepancy flag when they differ, and conflict_detected booleans marking a source that contradicts itself rather than silently picking one value.
Semantic errors vs syntax errors: tool_use with JSON schemas eliminates syntax errors — malformed JSON, missing fields, wrong types — but not semantic ones: line items that do not sum to the stated total, values placed in the wrong fields, or fabricated values. Semantic errors need validation logic and retry loops outside the schema.
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.
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.
settings.json: The configuration file the client enforces regardless of what Claude decides, unlike CLAUDE.md. It resolves through a strict precedence chain — managed (enterprise, always wins) > CLI arguments > local > project > user — with locations at ~/.claude/settings.json, .claude/settings.json (shared), .claude/settings.local.json (personal), and an OS-specific enterprise managed-settings.json path.
Skill invocation control: Two frontmatter switches: disable-model-invocation: true makes a skill user-only and keeps its description out of context, while user-invocable: false makes it Claude-only and hides it from the / menu.
SKILL.md frontmatter: The optional YAML block at the top of a skill. All fields are optional but description is recommended, since it drives model-invoked triggering. Fields include name, description, argument-hint (autocomplete hint for expected arguments), allowed-tools, model, context, and agent.
Skills system: The unified system behind custom /commands. A skill is a directory containing SKILL.md (.claude/skills/<name>/SKILL.md, the canonical location); a command is a flat Markdown file (.claude/commands/<name>.md, kept for backward compatibility). Both produce the same command, a skill wins over a same-named command, and locations resolve enterprise > personal (~/.claude/skills/) > project > bundled, with nested clashes qualified as apps/web:deploy.
Skills vs CLAUDE.md: Skills are on-demand, task-specific workflows whose bodies load only on invocation; CLAUDE.md is always-loaded universal standards applied to every session with no invocation step. Do not put task-specific procedures in CLAUDE.md, or always-on reference material in skills.
Source quality heuristics: Prompt-level guardrails that stop low-quality sources — SEO content farms outranking authoritative publications — from dominating synthesis.
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.
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.
Stratified random sampling: Sampling from each stratum — document type, confidence band, field type — for human verification. Critically it must include high-confidence extractions that are already automated: those are the blind spot, and a novel error pattern there goes undetected without sampling.
strict: true: The tool-definition flag enabling schema validation of tool inputs. tool_choice: "any" alone guarantees only that a tool is called; combining it with strict: true guarantees both that a tool is called and that its input strictly follows your schema.
Structured claim-source mapping: The five fields every finding must carry so provenance survives a pipeline: the claim, the source URL, the document name, the relevant excerpt, and the publication date. Attribution most commonly dies at step 3, synthesis, where compression and paraphrasing drop the mappings unless downstream agents are explicitly instructed to preserve and merge them.
Structured error context: The four elements a failing subagent must return so the coordinator can decide intelligently: the failure type, what was attempted (the specific query, parameters, and target system), any partial results gathered before the failure, and potential alternative approaches. "Search failed" gives the coordinator nothing to act on.
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.
Structured note-taking: Anthropic's official name for scratchpad files, also called agentic memory: the agent regularly writes notes persisted outside the context window and re-reads them instead of trusting a filling context. It excels for iterative work with clear milestones, and should be instructed from the start of an exploration rather than deployed once degradation appears.
Structured output reliability hierarchy: tool_use with JSON schemas above prompt-based JSON. The tool's schema constrains the shape of what Claude returns, eliminating syntax errors such as missing brackets, trailing commas, and unquoted keys; asking for JSON in a text response gives no structural guarantee and will periodically produce unparseable output.
Structured Outputs feature: A separate, newer mechanism from tool use: output_config.format constrains a plain JSON response through constrained decoding, with no tool call needed. It is generally available on Claude 4.5 and later. The first use of a schema costs extra latency while the grammar compiles; compiled grammars are cached for 24 hours from last use, and the feature adds a hidden system prompt that slightly raises input tokens on every call.
Structured state manifest: The crash-recovery mechanism for long explorations: each agent exports its state — what has been explored, key findings, current phase and next steps, unresolved questions — to a known file the coordinator reloads on resume. It persists exploration findings across sessions, which is a different job from checkpoints, which undo code changes within one.
Structured-output schema constraints: The constrained-decoding grammar supports the basic types plus enum (strings, numbers, booleans, nulls only), required, and additionalProperties, which must be set to false for objects — any other value is rejected. Not supported: recursive schemas, external $ref, numerical constraints (minimum, maximum, multipleOf), and string constraints (minLength, maxLength).
structuredContent: The MCP result field carrying a JSON object of structured tool output, the first-class place for fields such as errorCategory and isRetryable. For backwards compatibility, serialise the same JSON into a text block alongside it.
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.
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.
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.
system (parameter): The top-level request parameter where a system prompt lives, alongside model, messages, and max_tokens. There is no "system" role in the Messages API, and appending criteria as an extra user message does not create the separation you might expect — consecutive same-role messages are combined into a single turn rather than rejected.
System prompt flags: Four flags with an append-versus-replace distinction: --system-prompt and --system-prompt-file replace the entire default prompt, while --append-system-prompt and --append-system-prompt-file add to it. Append to keep the default tool guidance and safety instructions; replace only when the agent's identity differs from Claude Code's.

T

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.
temperature: The amount of randomness injected into the response: default 1.0, range 0.0–1.0, with values closer to 0.0 for analytical work. Even at 0.0 results are not fully deterministic, so it is not a precision control — lowering it cannot invent a decision boundary the prompt never defined.
Tool description: The free-text field on a tool definition and the primary mechanism an LLM uses for tool selection — Anthropic calls it by far the most important factor in tool performance. A production-grade one states what the tool does, its inputs with formats, example queries, edge cases and limits, and explicit boundaries against similar tools. When misrouting occurs, expanding descriptions is the first fix.
Tool misrouting: The failure where two tools with overlapping or near-identical descriptions cause the model to select the wrong one — for example routing an order query to get_customer. The root cause is description quality, not model capability.
Tool name regex: A Messages API tool name must match ^[a-zA-Z0-9_-]{1,64}$.
Tool namespacing: Delineating tools that must coexist by prefixing or suffixing them, either by service (asana_search, jira_search) or by resource (asana_projects_search). Anthropic found the choice between prefix- and suffix-based namespacing to have non-trivial effects on tool-use evaluations.
Tool search: The Claude Code behaviour, enabled by default, that defers MCP tool definitions rather than loading them all into context up front; Claude searches for relevant tools and only those it uses enter context. Because the search is text-driven, server instructions should describe what category of tasks the tools handle.
Tool splitting: Replacing a generic tool with broad responsibilities (analyze_document) with purpose-specific tools that each have one narrow job and a defined input/output contract (extract_data_points, summarize_content, verify_claim_against_source).
tool_choice: The parameter controlling how the model interacts with tools, with four documented types: auto (model decides; default when tools are provided), any (must call some tool, chooses which), tool (must call the named tool), and none (may not call any tool; default when no tools are provided).
tool_choice and prompt caching: Changing tool_choice between turns invalidates cached message blocks; tool definitions and system prompts stay cached but message content must be reprocessed. It is the hidden cost of a forced-then-auto workflow.
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.
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.
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".
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.
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.

U

Unreliable escalation triggers: Two the exam tests as anti-patterns: sentiment or frustration detection, because emotional state does not correlate with case complexity, and self-reported confidence scores, because the model is often confident on hard cases and hedges on easy ones — producing exactly the symptom of escalating simple cases while attempting complex ones.
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.

V

Valid escalation triggers: Exactly three: an explicit customer request for a human (honoured immediately, with zero investigation first), a policy exception or gap where the policy is silent rather than merely restrictive, and a genuine inability to make progress after a real attempt. A policy violation has a documented answer and does not require escalation.

W

WebFetch domain rule: WebFetch uses its own permission-rule shape, a domain: prefix matched against the hostname. WebFetch(domain:example.com) matches that host; WebFetch(domain:*.example.com) matches subdomains at any depth but not the apex domain.
What counts toward the context window: The system prompt, every message in messages including tool results, images, and documents, the tool definitions, and the model's own output for the turn including extended thinking. Cached prefixes still occupy the window — caching changes cost, not usage — which is why untrimmed verbose tool results are a budget problem even when cheap to reprocess.
Workflow tools: Tools built around a high-impact user workflow rather than wrapping an API endpoint — schedule_event instead of list_users/list_events/create_event, get_customer_context instead of three separate lookups, search_logs instead of read_logs. Merely wrapping existing endpoints is a named common error.
Writer/Reviewer pattern: Session A implements, a second independent session reviews, and Session A then addresses the feedback. The same split works for tests, with one Claude writing tests and another writing code to pass them. Its documented basis: a fresh context improves code review since Claude will not be biased toward code it just wrote.