The Complete Claude Agent SDK Guide

This is part one of three. It covers everything you need to build a working agent with the Claude Agent SDK, not a demo. By the end you can install the SDK, run an agent that reads and edits real files, decide which tools it may use, approve or refuse each action from your own code, keep a conversation going across turns, give the agent a tool you wrote, read the cost of a run, and recognise the error messages behind most first-week frustration. Mid-level and Senior take the same material into production hosting, sandboxing and cost control.

Each section ends with a Try it task. Do them as you go: an agent that calls tools stays abstract until you have watched your own process print Read, then Edit, then a result line with a dollar figure on it.

Everything here is verified against TypeScript SDK 0.3.285 and Python SDK 0.2.162, both released 2026-09-29 and both bundling Claude Code CLI v2.1.285. Examples lead with Python and give the TypeScript equivalent where the difference matters.

What the Claude Agent SDK is, and the problem it solves

The Claude Agent SDK is a library, published for Python and TypeScript, that runs Claude Code as a subprocess and exposes its agent loop to your program. Anthropic's own framing is the clearest available: build production AI agents with Claude Code as a library. You import a function, pass it a prompt and some options, and get back a stream of messages describing what the agent thought, which tools it called, what those returned, and what it concluded.

To see why that is useful, look at what you have to build without it. Suppose you want a program that reads a Python file, finds a bug, and fixes it. Using the raw Messages API — the subject of the Claude API guide — you would define a read_file and a write_file tool with JSON schemas, send the first message, inspect the response for tool-use blocks, execute each one yourself, append the results as a user message, and repeat until the model stops asking for tools. Then come the parts nobody warns you about: a loop guard so a confused model cannot spin forever, a diff-based edit tool because rewriting whole files is slow and lossy, a decision about what happens when the model tries to edit /etc/passwd, token accounting, and conversation persistence across restarts. That hand-written loop is several hundred lines before it is trustworthy, and it is the same several hundred lines in every project.

The SDK is that loop, already written and hardened, because it is the exact loop powering the Claude Code CLI. The tools come with it: Read, Edit, Write, Glob, Grep, Bash, WebSearch, WebFetch, Agent, Skill, ToolSearch and AskUserQuestion. So does the permission system, including an AST parser that inspects bash commands against your rules rather than matching strings. So does session persistence, as JSONL transcripts on disk, along with hooks, subagents, MCP servers, skills and plugins.

Two words in that diagram deserve attention, because almost every first-week surprise traces back to them.

Subprocess. When you call query(), the SDK launches an actual claude process and talks to it over standard input and output using newline-delimited JSON plus a small control protocol. One session means one subprocess. That process owns a shell, a working directory and a transcript file on local disk, and it never listens on a network port. The consequences are concrete: environment variables matter, because the subprocess inherits them or does not; the working directory matters, because that is where Read and Edit resolve relative paths; and if you want an agent behind an HTTP endpoint, you write that server yourself.

Claude Code. The agent you are driving is the same one people use interactively. That is a feature — it is unusually well-tested at reading and modifying codebases — but it also means the SDK inherits Claude Code's settings files, memory files and project configuration, which you will sometimes want to switch off.

It helps to place the SDK against its neighbours, because Anthropic ships four overlapping things. The Claude Code CLI is the interactive terminal interface: a human sits in front of it. The client SDK (anthropic, @anthropic-ai/sdk) makes direct Messages API calls where you own the tool loop; choose it for narrow, predictable model calls. Managed Agents put the agent loop on Anthropic's infrastructure, with sessions in an Anthropic-hosted or self-hosted sandbox, driven over REST, the SDKs or the ant CLI. The Agent SDK is for when you want the full coding-agent loop inside your own process, with your own code deciding what it may do. In any other language, the documented route is to run claude -p --output-format json as a subprocess yourself.

The agent loop, and the four nouns

Four nouns carry the whole model: turn, message, session and tool. Learn them in that order and the API stops looking like a wall of options.

A run begins when you hand the SDK a prompt. Claude responds with text, tool calls, or both. If there are tool calls, the SDK executes them — reading the file, running the bash command, calling your function — and feeds the results back. Claude responds again. The cycle repeats until Claude replies with no tool calls at all, which is how the loop knows the work is finished. Then you get a final assistant message and a result message.

One trip around that cycle is a turn. Memorise that precisely, because maxTurns counts tool-use turns only. Setting maxTurns: 5 on a task that genuinely needs twelve file reads does not make the agent efficient; it makes it stop halfway and hand you an error_max_turns result.

A message is one item in the stream you iterate over. There are five core types and you will use all of them.

• SystemMessage carries session metadata. Its subtypes include init, which arrives first and is the single most useful diagnostic in the SDK; compact_boundary, emitted when history is summarised; plus informational and worker_shutting_down.
• AssistantMessage is Claude speaking. Each message holds one content block, and blocks that came from the same API response share a message ID.
• UserMessage carries tool results back into the conversation, along with anything you stream in yourself.
• StreamEvent carries raw token-level deltas, and only appears if you opt in with include_partial_messages.
• ResultMessage ends the run. It carries the final text, token usage, total_cost_usd, num_turns, session_id, a subtype, a stop_reason and a terminal_reason.

Beyond those five there are observability messages — rate-limit events, task progress notifications, hook events, mirror errors, conversation resets. You need not handle them, but you must not crash on them, so always fall through gracefully on an unrecognised type.

A session is the persisted conversation, written as JSONL to ~/.claude/projects/<encoded-cwd>/<id>.jsonl, or under $CLAUDE_CONFIG_DIR/projects/. The encoded working directory is the real path with every non-alphanumeric character replaced by a hyphen. The critical point is that a session persists the conversation, not the filesystem. Resume tomorrow and Claude remembers that it edited utils.py; it does not restore utils.py. File restoration is a separate opt-in feature called checkpointing.

A tool is a capability the agent can invoke. The built-in set covers reading, editing, writing, globbing, grepping, running bash, searching and fetching the web, spawning subagents through the Agent tool, invoking skills, and asking the user a question. Read-only tools, and MCP tools that declare the readOnlyHint annotation, may run in parallel; mutating tools run one at a time. Custom tools default to sequential unless you mark them read-only.

Installing the SDK and checking the setup

You need Node.js 18 or later for TypeScript, or Python 3.10 or later for Python, and an API key from an Anthropic Console account at platform.claude.com. You do not need to install Claude Code separately in the normal case, because both SDKs ship a native Claude Code binary with them. There are exceptions, and they are the single most common installation failure, so they get their own treatment below.

For Python on macOS or Linux, work inside a virtual environment:

python3 -m venv .venv && source .venv/bin/activate
pip install claude-agent-sdk

Or with uv, which is faster and manages the environment for you:

uv init && uv add claude-agent-sdk && uv run agent.py

If you skip the virtual environment on a recent Debian, Ubuntu or Homebrew Python, pip refuses with error: externally-managed-environment. That message is not a problem with the SDK; it is your system Python protecting itself. Use a venv or uv.

For TypeScript, the full setup for a fresh project is four lines:

npm init -y && npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx
npx tsx agent.ts

Setting type=module matters because it enables top-level await, which keeps the examples short. In an existing CommonJS project, leave the package type alone and name the file agent.mts instead.

The native binary arrives through per-platform optional dependencies: -darwin-arm64, -darwin-x64, -linux-x64, -linux-arm64, -linux-x64-musl, -linux-arm64-musl, -win32-x64 and -win32-arm64. If your Docker build or CI pipeline runs npm ci --omit=optional, which many do to shrink images, no binary is installed and the SDK fails at run time with Native CLI binary for <platform>-<arch> not found. Keep optional dependencies, or set pathToClaudeCodeExecutable to a binary you installed another way. Yarn 1 installs both the glibc and the musl package; from SDK 0.2.141 onwards the correct one is selected at run time, and you may delete the unused one from an image to save space.

Python's wheel coverage has two gaps that matter where Alpine base images and Windows laptops are common. There is no musllinux wheel, so on Alpine you get the source distribution, which bundles no CLI at all. And although the documentation states that the Windows x64 wheel bundles claude.exe, versions 0.2.160, 0.2.161 and 0.2.162 ship no win_amd64 wheel — the 0.2.160 changelog notes CI skipped wheels over PyPI's per-file size limit. On Windows x64 today, pip install claude-agent-sdk resolves to the sdist with no binary.

In either case, install Claude Code natively and let the SDK find it on PATH, or point cli_path at it:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

irm https://claude.ai/install.ps1 | iex

Homebrew (brew install --cask claude-code) and winget (winget install Anthropic.ClaudeCode) also work, though neither auto-updates. Pinning claude-agent-sdk==0.2.159 is the other Windows option. Check PyPI before you commit to either, because the wheel situation is a CI accident rather than a decision.

Authentication is one environment variable.

export ANTHROPIC_API_KEY=sk-ant-...

$env:ANTHROPIC_API_KEY = "sk-ant-..."

If your organisation routes model traffic through a provider, the SDK honours the Claude Code switches: CLAUDE_CODE_USE_BEDROCK=1 for Amazon Bedrock, CLAUDE_CODE_USE_VERTEX=1 for Google Cloud's Agent Platform, CLAUDE_CODE_USE_FOUNDRY=1 for Microsoft Foundry, and CLAUDE_CODE_USE_ANTHROPIC_AWS=1 with ANTHROPIC_AWS_WORKSPACE_ID for Claude Platform on AWS. Bedrock is what teams with data-residency requirements in the UAE and Saudi Arabia usually reach for, since the traffic stays inside an already-approved region; the AWS Bedrock guide covers that side. One policy point: unless Anthropic has approved it, third-party developers may not offer claude.ai login or subscription rate limits in their products. Use API-key authentication.

Verify in four steps. Confirm the package with pip show claude-agent-sdk or npm ls @anthropic-ai/claude-agent-sdk. Run a one-line agent and look for a result. Print the init system message, which lists the registered tools, every MCP server's status, the model, and apiKeySource — whose value will be ANTHROPIC_API_KEY, apiKeyHelper, /login managed key or, tellingly, none. And if you depend on a native install, run claude --version in the same environment as the service: IDE terminals, systemd units and container entrypoints routinely have a different PATH from your login shell.

Your first agent, step by step

Create a directory with one deliberately broken file in it, because an agent fixing a real bug teaches more than an agent summarising text.

def average(numbers):
    total = 0
    for n in numbers:
        total += n
    return total / len(numbers)

That function raises ZeroDivisionError on an empty list. Now the agent:

import asyncio
from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    AssistantMessage,
    TextBlock,
    ToolUseBlock,
    ResultMessage,
)

async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Glob"],
        permission_mode="acceptEdits",
    )
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=options,
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)
                elif isinstance(block, ToolUseBlock):
                    print(f"[tool] {block.name}")
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")
            if message.total_cost_usd is not None:
                print(f"Cost: ${message.total_cost_usd:.4f}")

asyncio.run(main())

Run it with python agent.py. The output interleaves Claude's reasoning with tool names, and ends with something close to:

[tool] Glob
[tool] Read
[tool] Edit
I found a crash in average(): dividing by len(numbers) raises
ZeroDivisionError when the list is empty. I added a guard that
returns 0.0 for an empty input.
Done: success
Cost: $0.0231

Open utils.py. It has changed on disk. That is the moment the SDK stops being abstract.

Four things in those twenty lines deserve a sentence each. The function is async, and query() is an async iterator, because the agent loop is a stream of events arriving over time; there is no synchronous version. allowed_tools names three tools, and the significance of that list is subtler than it looks. permission_mode="acceptEdits" is what allows the edit to happen without a human approving it. And the final block checks total_cost_usd is not None before formatting it, because in Python total_cost_usd, usage and model_usage are all Optional.

The TypeScript shape is the same idea with different spelling. TypeScript uses camelCase throughout, discriminates messages on a type string rather than with isinstance, and places assistant and user content at message.message.content — a nesting that trips up everyone exactly once:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const m of query({
  prompt: "Summarize the unfinished work marked in this repository",
  options: {
    model: "claude-sonnet-5",
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 8,
    cwd: "/path/to/repo",
  },
})) {
  if (m.type === "result" && m.subtype === "success" && !m.is_error) {
    console.log(m.result);
  }
}

Note the cwd option. It sets the working directory of the subprocess, which is what Read, Glob and Grep resolve paths against. Without it the agent works relative to wherever your program happens to have been started, which in a service is rarely where you think.

Reading the messages that come back

Your first agent printed text and tool names. A real program needs to know whether the run succeeded, and that is less obvious than it sounds.

The result message carries a subtype, and it is one of five values: success, error_max_turns, error_max_budget_usd, error_during_execution, or error_max_structured_output_retries. The final text lives in the result field, and that field only exists on success. Reading it unconditionally is the most common bug in beginner code, because it works perfectly until the day a run hits its turn cap and your handler raises AttributeError on a None.

There is a second, sharper rule that the documentation is explicit about and almost nobody discovers on their own: check terminal_reason before subtype. When the final request to the API fails, Claude Code can report subtype: "success" with terminal_reason: "api_error". If you trust subtype alone you will record a successful run that produced nothing. Alongside those, stop_reason tells you why the model stopped generating, and is typically end_turn, max_tokens or refusal.

from claude_agent_sdk import ResultMessage

def summarise(message: ResultMessage) -> str:
    if message.terminal_reason and message.terminal_reason != "success":
        return f"failed: terminal_reason={message.terminal_reason}"
    if message.subtype != "success":
        return f"failed: {message.subtype} after {message.num_turns} turns"
    return message.result or "(no text)"

Every result also carries a session_id, whether or not the run succeeded. Log it. It is the handle you need to resume the conversation, to find the JSONL transcript on disk, and to correlate the run with traces if you export telemetry.

The cost fields need care about meaning rather than precision. total_cost_usd and the per-model costUSD figures are client-side estimates from a price table bundled with the CLI. They are good for dashboards and for spotting a runaway loop; they are not billing data, and you must never invoice from them — the Usage and Cost API and the Console are authoritative. The fields count different things: usage covers the main loop only and excludes subagents, while total_cost_usd and model_usage include them. From CLI 2.1.277 a resumed or forked session's total_cost_usd continues from earlier turns rather than restarting at zero, so read the latest result instead of summing.

Two failure shapes are worth rehearsing. When a single-shot query() ends on an error result, the SDK yields that result and then raises, so a loop without a try/except surfaces the exception rather than your message. And if the process crashes mid-run the final result is error_during_execution, possibly with zeroed cost; treat missing cost as unknown rather than free.

Python's error hierarchy was tightened in 0.2.140. A run that ends on an error result now raises ResultError, a subclass of ProcessError, carrying structured fields. Because it is a subclass, the except ResultError clause must come before except ProcessError, or the specific handler never runs:

from claude_agent_sdk import query, ResultError, ProcessError, CLINotFoundError

try:
    async for message in query(prompt=task, options=options):
        handle(message)
except ResultError as exc:
    print("agent finished on an error result:", exc)
except ProcessError as exc:
    print("the CLI process itself failed:", exc)
except CLINotFoundError as exc:
    print("no claude binary:", exc)

Choosing tools, and what allowed_tools really means

This section exists because one option name misleads almost every newcomer, and the misunderstanding is a security problem rather than a style problem.

allowed_tools is an auto-approve list. It does not restrict which tools exist. Naming ["Read", "Edit", "Glob"] means those three run without asking. It does not remove Bash from the agent's awareness. Bash is still registered, Claude can still call it, and what happens then depends on your permission mode — in default mode it falls through to your approval callback and is denied if there is none, but in bypassPermissions it simply runs.

Three different options shape the tool surface, and they do different jobs.

tools sets the base set. Pass ["Read", "Edit", "Bash"] for exactly those; pass [] for no built-ins at all, which is the right choice for an agent that should only use your own custom tools; or pass {"type": "preset", "preset": "claude_code"} for the full default set.

disallowed_tools removes capability. A bare name takes the tool out of context entirely — the model never learns it exists. A scoped rule such as Bash(rm *) denies matching calls in every permission mode, including bypassPermissions, which makes it the right tool for hard prohibitions.

allowed_tools grants silent approval to specific names or scoped patterns.

Two sensible starting shapes follow from that. A read-only analyst agent, safe to point at any repository:

options = ClaudeAgentOptions(
    tools=["Read", "Glob", "Grep"],
    allowed_tools=["Read", "Glob", "Grep"],
    permission_mode="dontAsk",
)

And a locked-down worker that may edit inside one directory and nothing else:

options = ClaudeAgentOptions(
    cwd="/srv/workspace",
    allowed_tools=["Read", "Glob", "Grep", "Edit", "Write"],
    disallowed_tools=["Bash", "WebFetch"],
    permission_mode="acceptEdits",
    max_turns=20,
)

Two recent defaults will confuse you if nobody mentions them. From TS 0.3.162, on native builds SDK sessions default to embedded find and grep inside Bash rather than registering dedicated Grep and Glob tools; name them explicitly in tools or allowed_tools if you want them as real tools a hook can inspect. And the task-tracking tools (TaskCreate, TaskGet, TaskUpdate, TaskList, plus the older TodoWrite) are default tools only on Claude 3.x, Opus 4.0 through 4.7, Sonnet 4.0 through 4.6 and Haiku 4.5. On Opus 4.8, Sonnet 5, Fable 5, Mythos 5 and newer you must name them yourself or set CLAUDE_CODE_ENABLE_TODO_TOOLS=1. TodoWrite was itself replaced by the Task tools in SDK sessions in TS 0.3.142, and the Task tools accumulate by ID rather than replacing a list.

The model option takes an alias or a full ID; the documentation uses claude-sonnet-5, claude-opus-5 and claude-fable-5. Leave it unset and the session uses Claude Code's default. Pass a display name like "Sonnet5" and you get a pointed error: Model "Sonnet5" is not a recognized model id. Did you mean 'claude-sonnet-5'?

Finally, give every agent a budget. Both caps are off by default, which means an agent in a loop will spend until something else stops it. max_turns bounds tool-use turns, and max_turns=0 means unlimited. max_budget_usd bounds estimated spend, and 0 is rejected at startup rather than treated as unlimited.

Permissions without a human in the terminal

In the CLI a permission prompt is a dialog. In the SDK there is nobody to ask, so you get two mechanisms: a mode that sets the default posture, and a callback that decides case by case. Every tool call is evaluated in a fixed order, and the outcome is binary — allowed or denied:

The modes, in rough order of how much they let through:

• default — unapproved calls go to can_use_tool. With no callback, they are denied. This is the safe starting point.
• acceptEdits — auto-approves file edits and the shell commands mkdir, touch, rm, rmdir, mv, cp and sed inside the working directory or additional directories.
• plan — edits are never auto-approved, which suits an agent that should propose rather than act. As of TS 0.3.269, writes in plan mode route through can_use_tool even when allowDangerouslySkipPermissions is set.
• dontAsk — anything that would prompt is denied outright and can_use_tool is never called. For headless agents this is the recommended posture, paired with an explicit allowed_tools list.
• auto — a model classifier approves or denies.
• bypassPermissions — everything is approved except explicit ask rules, deny rules, hooks, user-interaction tools and critical-path rm/rmdir. TypeScript additionally requires allowDangerouslySkipPermissions: true. It refuses to run as root or under sudo outside a recognised sandbox on Linux and macOS.

The alias 'manual' has been accepted for 'default' since TS 0.3.200, so do not be surprised to see it in sample code.

The callback is where interesting policy lives. In Python it receives the tool name, the input, and a context, and returns either an allow or a deny:

from claude_agent_sdk import (
    ClaudeAgentOptions,
    PermissionResultAllow,
    PermissionResultDeny,
)

SAFE_PREFIXES = ("pytest", "ruff", "git status", "git diff")

async def gate(tool_name, input_data, context):
    if tool_name == "Bash":
        command = input_data.get("command", "")
        if not command.startswith(SAFE_PREFIXES):
            return PermissionResultDeny(message=f"command not on the allowlist: {command}")
    if tool_name in ("Write", "Edit"):
        path = input_data.get("file_path", "")
        if path.endswith((".env", ".pem")):
            return PermissionResultDeny(message="secrets are off limits")
    return PermissionResultAllow()

options = ClaudeAgentOptions(
    permission_mode="default",
    can_use_tool=gate,
    allowed_tools=["Read", "Glob", "Grep"],
)

PermissionResultAllow can also carry updated_input, which rewrites the call before it executes — clamping a path, adding --dry-run — and updated_permissions to adjust later decisions. PermissionResultDeny takes a message that goes back to the model, so write it as instruction rather than as a log line: "secrets are off limits, use the config loader instead" steers the next attempt where "denied" does not. It also accepts interrupt=True to stop the run.

TypeScript's equivalent is canUseTool(toolName, input, { signal, suggestions, ... }) returning { behavior: "allow", updatedInput } or { behavior: "deny", message }.

Hooks are the other half of the picture, and worth meeting at beginner level even if you use them later. A hook is a callback in your own process, fired at a lifecycle event — PreToolUse, PostToolUse, Stop, UserPromptSubmit, PreCompact and others — that can deny a call, modify its input, or add context. Hooks run outside the model's context, so they cost no tokens, and all hooks matching an event fire concurrently. Matchers are exact strings or regexes on the tool name:

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

async def protect_env_files(input_data, tool_use_id, context):
    if input_data["tool_input"].get("file_path", "").endswith(".env"):
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }
    return {}

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]}
)

Hook timeouts are set per matcher in seconds, and the defaults are 600 seconds for most events, 30 for UserPromptSubmit and the model-switch hooks, 10 for MessageDisplay and about 1.5 for SessionEnd. A hook that times out is discarded and the session continues, which is forgiving but means a slow hook can fail open.

Sessions: continuing, resuming and forking

By default each query() call in Python starts a fresh session with no memory of the last one. Three options change that.

Continue picks up the most recent session in the current working directory — continue_conversation=True in Python, continue: true in TypeScript. It is the right choice for a CLI-like tool where "the last conversation" is unambiguous.

Resume reopens a specific session by ID: resume="<session-id>". Because every result message carries session_id, the pattern is to store that ID with whatever your application calls a conversation, then resume it later. This is how you build a chat interface over the SDK.

Fork creates a new session ID starting from a copy of an existing history, leaving the original untouched: fork_session=True alongside resume. Forking is how you explore two approaches from the same context, or offer an "edit this message and retry" affordance without destroying the original thread.

first = None
async for message in query(prompt="Map the modules in this repo", options=options):
    if isinstance(message, ResultMessage):
        first = message.session_id

async for message in query(
    prompt="Now write a README section describing them",
    options=ClaudeAgentOptions(resume=first, allowed_tools=["Read", "Glob", "Write"]),
):
    ...

You can also supply your own session_id, but it must be a valid UUID, and it cannot be combined with continue or resume unless you also fork. Both SDKs ship session management helpers: list_sessions, get_session_messages, get_session_info, rename_session, tag_session, delete_session, fork_session, list_subagents and get_subagent_messages in Python, with camelCase equivalents in TypeScript. Naming and tagging sessions sounds cosmetic until you have a few hundred transcripts and need to find the one from the incident last Tuesday.

If you would rather nothing touched the disk, TypeScript offers persistSession: false to keep a session in memory only. Python has no such option; set CLAUDE_CODE_SKIP_PROMPT_HISTORY in env instead.

Two related features round this out. Compaction happens automatically as the conversation approaches the context limit: older history is summarised and a compact_boundary system message is emitted. You can trigger it by sending /compact as a prompt, and hook it with PreCompact (whose trigger is manual or auto). The practical lesson is where to put rules you need honoured all session: not in the first prompt, which may be summarised away, but in CLAUDE.md, which is re-injected on every request. File checkpointing is the answer to "my agent edited the wrong thing": enable enableFileCheckpointing and call rewindFiles(userMessageId) to restore files. It must be enabled on the original session and on any resumed session.

Streaming input and the long-lived client

So far every prompt has been a string. That is single message input: one shot, stateless, and the right shape for a Lambda handler or a CI job, with real limitations — no image attachments, no queueing mid-run, no real-time interrupts.

Streaming input is the mode the documentation recommends for everything else. You pass an AsyncIterable of message dictionaries instead of a string, and in exchange you get a long-lived session: messages can be queued while the agent works, images attached, the run interrupted, the model and permission mode changed mid-session, and permission prompts answered inside the loop.

In Python the ergonomic way to get all of that is ClaudeSDKClient, which keeps one session alive across calls:

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, ResultMessage

async def main():
    options = ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Which module handles authentication?")
        async for message in client.receive_response():
            if isinstance(message, ResultMessage):
                print(message.result)

        await client.query("Now list every function it exports.")
        async for message in client.receive_response():
            if isinstance(message, ResultMessage):
                print(message.result)

asyncio.run(main())

The async with block is not decoration. Calling a client method before connect() or after disconnect() raises Not connected. Call connect() first., and the context manager is how you never see it. receive_response() stops after the result message, which is what you want per turn; receive_messages() streams everything indefinitely, for a live view.

The client also exposes control methods that single-shot query() cannot offer: interrupt() to stop the agent mid-work, set_permission_mode() to tighten or loosen policy on the fly, set_model() (pass None to return to the default), rewind_files(id), get_mcp_status(), reconnect_mcp_server(), toggle_mcp_server(name, enabled), stop_task(id), get_server_info(), get_context_usage() and disconnect().

TypeScript has no client class. The Query object returned by query() carries the control methods instead — interrupt(), setPermissionMode(), setModel(), streamInput(), initializationResult(), supportedModels(), getContextUsage(), readFile(), reloadSkills() and more — and you keep continuity across calls with continue: true or resume. Four of those (interrupt, setPermissionMode, setModel, applyFlagSettings) require streaming input mode.

Giving the agent a tool you wrote

Built-in tools cover files and shell. Everything specific to your business — a customer lookup, a metrics query, a deployment trigger — you supply as a custom tool. The SDK implements these as an in-process MCP server: you write a Python function and the plumbing is handled. The MCP guide covers the protocol; here you need two helpers.

import asyncio
from claude_agent_sdk import (
    tool,
    create_sdk_mcp_server,
    query,
    ClaudeAgentOptions,
    ResultMessage,
)

@tool(
    "get_temperature",
    "Get the current temperature at a location",
    {"latitude": float, "longitude": float},
)
async def get_temperature(args):
    return {"content": [{"type": "text", "text": "Temperature: 61°F"}]}

server = create_sdk_mcp_server(
    name="weather",
    version="1.0.0",
    tools=[get_temperature],
)

async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"weather": server},
        allowed_tools=["mcp__weather__get_temperature"],
    )
    async for message in query(prompt="How warm is it in Cairo?", options=options):
        if isinstance(message, ResultMessage):
            print(message.result)

asyncio.run(main())

The naming rule is the part to memorise, because getting it wrong produces a silent failure rather than an error. Tool names are fully qualified as mcp__{server_key}__{tool_name}, where the server key is the key in the mcp_servers dictionary — not the name= passed to create_sdk_mcp_server. Here that gives mcp__weather__get_temperature. If the name is wrong, the tool appears in the agent's list, Claude calls it, and the permission flow denies it: the symptom is "my MCP tools are visible but never run". Allow either the exact name or the whole server with mcp__weather__*. An unanchored * or a bare mcp__* in an allow rule is ignored with a warning, although deny rules do accept those globs.

TypeScript's version is tool(name, description, zodSchema, handler, { annotations }) with createSdkMcpServer({ name, version, tools, timeout }), using Zod for the schema instead of a dictionary of types. Python supports typing.Annotated for per-parameter descriptions, which is worth using because the description is what the model reads when deciding whether the tool fits.

Four annotations shape how a tool is scheduled: readOnlyHint, destructiveHint, idempotentHint and openWorldHint. The first has a concrete effect — custom tools run sequentially by default, and marking one read-only lets it run in parallel. To signal failure from inside a tool, return is_error in the result rather than raising.

You can also connect external MCP servers to reach a database or a hosted service someone else maintains. Configure them in the same mcp_servers mapping: stdio as {command, args, env}, remote as {type: "http" | "sse", url, headers}, or a path to a config file. Since TS 0.3.142 they connect in the background by default, so your session starts immediately and a slow server shows status: "pending" in init. Pending is not a failure — the statuses are pending, connected, failed, needs-auth and disabled. Set MCP_CONNECTION_NONBLOCKING=0 to restore blocking startup, capped at five seconds, or mark a server alwaysLoad: true.

Structured output, for when you need JSON

Parsing prose with regular expressions is a habit the SDK lets you avoid. Ask for a JSON schema and you get a validated object.

schema = {
    "type": "object",
    "properties": {
        "severity": {"type": "string", "enum": ["low", "medium", "high"]},
        "files_changed": {"type": "array", "items": {"type": "string"}},
        "summary": {"type": "string"},
    },
    "required": ["severity", "files_changed", "summary"],
}

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],
    output_format={"type": "json_schema", "schema": schema},
)

async for message in query(prompt="Audit this repo for crash bugs", options=options):
    if isinstance(message, ResultMessage):
        if message.subtype == "success" and message.structured_output is not None:
            print(message.structured_output["severity"])
        else:
            print("structured output unavailable:", message.subtype)

TypeScript uses outputFormat: { type: "json_schema", schema }. In both languages you can generate the schema rather than hand-writing it — Pydantic in Python, Zod in TypeScript — which keeps one definition for validation and for the model.

The rule that saves you an incident: require both subtype == "success" and a non-null structured_output. A schema the model cannot satisfy produces a successful-looking result with no structured output, and there is a dedicated subtype, error_max_structured_output_retries, for repeated failures. Treat a missing object as a failure and simplify the schema — flat beats deeply nested. A related error, API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid, means a tool schema is malformed; schemas must be valid draft 2020-12 with property keys matching ^[a-zA-Z0-9_.-]{1,64}$.

Configuration, settings sources and the errors you will actually see

Two configuration surfaces cause more beginner confusion than all the others combined, and both concern things the SDK reads from your filesystem or environment without being asked.

Setting sources. Omitting setting_sources loads user, project and local filesystem settings exactly as the CLI does: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, CLAUDE.md, and the skills, agents and commands under .claude/. That is equivalent to ["user", "project", "local"]. Pass [] to isolate. The default has a confusing history — the 0.1.0 changelog announced "no filesystem settings by default", but that was reverted and the line is stale, so verify with the init message rather than trusting either document. Some sources are read regardless of the option: managed policy, ~/.claude.json, auto memory, claude.ai connectors and sandbox credential denies. So setting_sources=[] is strong isolation but not complete, which is why the Senior guide spends real time on multi-tenancy.

Two symptoms follow from this option. If skills are not found, either setting_sources excludes user or project, or your cwd is outside the repository holding .claude/skills/. And if your agent behaves differently on a colleague's machine, compare ~/.claude/settings.json and CLAUDE.md first.

Environment variables. The env option differs between the two SDKs in a way that is responsible for a remarkable share of first-day failures. In TypeScript, env replaces process.env for the subprocess. Set env: { MY_VAR: "x" } and you have just removed ANTHROPIC_API_KEY, PATH and everything else from the agent's environment, and you will get Not logged in · Please run /login or Invalid API key. Always spread:

const options = { env: { ...process.env, MY_VAR: "x" } };

In Python, env is merged over the inherited environment, so env={"MY_VAR": "x"} behaves as you would expect. The asymmetry is deliberate and documented; it is simply surprising.

A handful of other beginner-relevant options are worth knowing by name. cwd sets the subprocess working directory and add_dirs grants access outside it. settings takes a path or inline JSON. plugins loads local bundles, each {"type": "local", "path": ...}. effort takes low, medium, high, xhigh or max, and is separate from extended thinking, set with thinking={"type": "adaptive" | "enabled" | "disabled"}; max_thinking_tokens is deprecated in favour of thinking. Similarly 'Skill' in allowed_tools is deprecated in favour of the skills option, which takes "all" or a list of names and validates it strictly, so skills=["*"] now raises before the CLI starts.

Here is the error table to keep beside you for your first week. Each row is a message you will genuinely see.

Three of those deserve emphasis. The Error output: Check stderr output for details text is fixed boilerplate — people hunt for "the real stderr" for an hour before registering a callback. The TLS row matters wherever a managed inspection proxy is standard, which in practice means most Gulf enterprise networks; the cure is to point the runtime at the proxy's CA, never to disable verification. And status: "pending" is absent from the table because it is not an error.

Putting it all together: a reviewer that comments on a diff

One small end-to-end project that uses nearly everything above. The agent reads the working tree's diff, reviews it against the repository's own conventions, and returns structured findings. It may read and search, it may run exactly two git commands, it may not write, and it has a budget.

import asyncio
import json
from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    PermissionResultAllow,
    PermissionResultDeny,
    AssistantMessage,
    ToolUseBlock,
    ResultMessage,
    ResultError,
)

SCHEMA = {
    "type": "object",
    "properties": {
        "findings": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "file": {"type": "string"},
                    "severity": {"type": "string", "enum": ["low", "medium", "high"]},
                    "note": {"type": "string"},
                },
                "required": ["file", "severity", "note"],
            },
        },
        "verdict": {"type": "string", "enum": ["approve", "comment", "request-changes"]},
    },
    "required": ["findings", "verdict"],
}

ALLOWED_COMMANDS = ("git diff", "git status")

async def gate(tool_name, input_data, context):
    if tool_name == "Bash":
        command = input_data.get("command", "").strip()
        if not command.startswith(ALLOWED_COMMANDS):
            return PermissionResultDeny(
                message=f"Only {ALLOWED_COMMANDS} are permitted. Use Read or Grep instead."
            )
    return PermissionResultAllow()

PROMPT = """Review the uncommitted changes in this repository.
Read CLAUDE.md first if it exists, and judge the diff against the conventions it states.
Report only findings you can point at a specific file for."""

async def main():
    options = ClaudeAgentOptions(
        cwd=".",
        system_prompt={"type": "preset", "preset": "claude_code"},
        tools=["Read", "Glob", "Grep", "Bash"],
        allowed_tools=["Read", "Glob", "Grep"],
        disallowed_tools=["Write", "Edit", "WebFetch"],
        permission_mode="default",
        can_use_tool=gate,
        max_turns=25,
        max_budget_usd=0.50,
        output_format={"type": "json_schema", "schema": SCHEMA},
    )

    try:
        async for message in query(prompt=PROMPT, options=options):
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, ToolUseBlock):
                        print(f"  -> {block.name}")
            elif isinstance(message, ResultMessage):
                if message.terminal_reason and message.terminal_reason != "success":
                    raise SystemExit(f"terminal_reason={message.terminal_reason}")
                if message.subtype != "success" or message.structured_output is None:
                    raise SystemExit(f"review failed: {message.subtype}")
                print(json.dumps(message.structured_output, indent=2))
                print(f"session={message.session_id} cost=${message.total_cost_usd or 0:.4f}")
    except ResultError as exc:
        raise SystemExit(f"agent error result: {exc}")

asyncio.run(main())

Walk through the choices, because each is a decision you will make again. system_prompt restores Claude Code's preset, because reviewing a codebase is the task that prompt was written for. tools includes Bash so git is reachable, but allowed_tools deliberately omits it, so every bash call falls through to gate — the allowed_tools-is-not-a-restriction lesson used on purpose. disallowed_tools removes Write, Edit and WebFetch entirely, so a reviewer cannot modify the code it reviews. max_turns and max_budget_usd bound the run in both dimensions, and output_format gives a CI job something to act on. The result handler checks terminal_reason, then subtype, then structured_output, in that order, and the ResultError clause catches the raise that follows an error result in single-shot mode.

Run it in a repository with uncommitted changes and you get a JSON verdict, a resumable session ID, and a cost figure. From here the extensions are short: post the findings to a pull request, or wrap the whole thing in a container a CI pipeline can call — the Docker guide covers the packaging. Export OpenTelemetry and every run becomes a trace, which is where Langfuse or any OTLP backend fits; the CLI exports telemetry itself and the SDK passes the environment variables through, with one hard rule — never use the console exporter, because stdout is the SDK's message channel.

What you can now do, and what comes next

You can install the SDK on macOS, Linux or Windows and diagnose the failures specific to each. You can run an agent that reads and modifies real files, read the message stream, and tell a genuine success from an apparent one by checking terminal_reason before subtype. You can shape the tool surface with tools, disallowed_tools and allowed_tools, and explain why the third is not a restriction. You can set a permission mode, write an approval callback, and recognise when it is shadowed. You can continue, resume and fork sessions, and you know a session restores a conversation and not a filesystem. You can keep a client alive with ClaudeSDKClient and interrupt it, write a custom tool and name it correctly, and demand JSON and validate that you got it.

Three habits will serve you from here. Pin the SDK version, because that also pins the bundled CLI, then take patches continuously and read the changelog before any minor — the 0.2 to 0.3 TypeScript bump removed the entire V2 session API. Log session_id on every run. And set a budget on every agent, because both caps are off by default and the failure mode of an unbounded agent is financial.

What the Mid-level guide takes up: the agent loop in enough detail to predict its behaviour, subagents and the Agent tool, hooks across the full event list, external MCP servers and tool search, session storage adapters that mirror transcripts so another host can resume, the hosting patterns, and real cost control. The Senior guide covers sandboxing and the security model, multi-tenancy in a shared container, egress proxies that inject the API key so the agent never sees it, and where the SDK stops being the right tool.

Useful neighbours in this catalogue: Claude API for the layer underneath, MCP for the tool protocol, OpenAI Agents SDK and CrewAI for how other frameworks divide the same problem, Langfuse and OpenTelemetry for observability, AWS Bedrock for regional model hosting, and Docker for shipping any of it.

Sources

• Agent SDK overview
• Quickstart
• Migration guide
• Troubleshooting
• Configuration
• The agent loop
• Sessions
• Streaming vs single mode
• Structured outputs
• Custom tools
• MCP in the Agent SDK
• Permissions
• Hooks
• Modifying system prompts
• Cost tracking
• Observability
• TypeScript reference
• Python reference
• Errors
• Environment variables
• TypeScript SDK changelog
• Python SDK changelog

Interviewers asking about the Claude Agent SDK at junior level are not testing whether you have memorised an options table. They are testing three things: whether you understand that you are driving a subprocess rather than calling an API, whether you can describe the agent loop without hand-waving, and whether you would let an agent loose on a production repository without a guardrail. Everything below is organised around those three.

Verified against TypeScript SDK 0.3.285 and Python SDK 0.2.162, both bundling Claude Code CLI v2.1.285.

The thirty-second answer

The Claude Agent SDK is a Python and TypeScript library that runs Claude Code as a subprocess and exposes its agent loop to your program, so you get the built-in tools, the permission system, sessions, hooks, subagents and MCP support without writing the tool-use loop yourself. You pass a prompt and options to query() and iterate over a stream of messages describing what the agent did.

If the interviewer wants a second sentence, the useful one is the comparison: the client SDK (anthropic) is for direct Messages API calls where you own the loop; the Agent SDK is for when you want a full coding agent inside your own process with your own code deciding what it may do.

The model, in four nouns

Name the nouns and you have the architecture.

Turn. One tool-use round trip: the model emits tool calls, the SDK executes them, the results feed back. maxTurns counts tool-use turns only, not messages. A task needing twelve file reads will not finish inside five turns.

Message. What you iterate over. Five core types: SystemMessage (its init subtype is the single best diagnostic in the SDK), AssistantMessage (one content block each; blocks from the same API response share a message ID), UserMessage (tool results plus anything you stream in), StreamEvent (raw deltas, opt-in via include_partial_messages), and ResultMessage (final text, usage, cost, session_id, subtype, stop_reason, terminal_reason).

Session. The persisted conversation, written as JSONL under ~/.claude/projects/<encoded-cwd>/<id>.jsonl. Say the line that separates candidates: a session persists the conversation, not the filesystem. Resume it tomorrow and Claude remembers it edited utils.py; the file is wherever it was left. File restoration is a separate opt-in feature, enableFileCheckpointing plus rewindFiles().

Tool. A capability the agent can invoke. Built-ins are Read, Edit, Write, Glob, Grep, Bash, WebSearch, WebFetch, Agent, Skill, ToolSearch, AskUserQuestion, plus the Task tools on models where they are on by default. Read-only tools and MCP tools annotated readOnlyHint can run in parallel; mutating tools run sequentially, and custom tools are sequential unless you mark them read-only.

One more word earns its place: subprocess. query() spawns one claude process and talks NDJSON over stdio. One session is one subprocess. It owns a shell, a working directory and a transcript on local disk, and it never listens on the network, which is why putting an agent behind HTTP means writing that server yourself.

Commands and calls to have ready

Install, in both languages, without hesitating:

pip install claude-agent-sdk        # Python 3.10+
npm install @anthropic-ai/claude-agent-sdk   # Node 18+

Both bundle a native Claude Code binary, so no separate install is normally needed. Both read the key from ANTHROPIC_API_KEY in the process environment, and neither reads .env files.

The smallest complete Python agent:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, ResultMessage):
            print(message.subtype, message.total_cost_usd)

asyncio.run(main())

The TypeScript shape, including the nesting that catches people: content lives at message.message.content, and messages are discriminated on m.type.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const m of query({
  prompt: "Summarize the unfinished work markers",
  options: { model: "claude-sonnet-5", allowedTools: ["Read", "Glob", "Grep"], maxTurns: 8 },
})) {
  if (m.type === "result" && m.subtype === "success") console.log(m.result);
}

The multi-turn Python shape, because "how do you keep a conversation going?" is a near-certain question:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async with ClaudeSDKClient(options=ClaudeAgentOptions(allowed_tools=["Read"])) as client:
    await client.query("Which module handles auth?")
    async for m in client.receive_response():
        ...
    await client.query("List the functions it exports.")

And the custom tool, where the naming convention is the examinable part:

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions

@tool("get_temperature", "Get the current temperature at a location",
      {"latitude": float, "longitude": float})
async def get_temperature(args):
    return {"content": [{"type": "text", "text": "Temperature: 61°F"}]}

server = create_sdk_mcp_server(name="weather", version="1.0.0", tools=[get_temperature])
options = ClaudeAgentOptions(
    mcp_servers={"weather": server},
    allowed_tools=["mcp__weather__get_temperature"],
)

Tool names are mcp__{server_key}__{tool_name}, and the server key is the key in mcp_servers, not the name= argument.

The classic traps, and why they happen

These are the questions that separate someone who has read the docs from someone who has run the thing.

allowed_tools is not a restriction. It is an auto-approve list. Listing three tools does not remove Bash; Bash stays registered and whether a call succeeds depends on the permission mode. To actually remove capability, use disallowed_tools — a bare name strips the tool from context entirely, and a scoped rule like Bash(rm *) denies matching calls in every mode. This is the single most likely trap question, and the right answer names both halves.

The default system prompt is minimal. Since 0.1.0 the SDK no longer uses Claude Code's system prompt. Opt back in with system_prompt={"type": "preset", "preset": "claude_code"}. If someone reports "it is less thorough than the CLI", this is why.

can_use_tool fires only on fall-through. The callback never runs for a call already approved by an allow rule or by bypassPermissions. Setting both gives you policy that silently does nothing — TypeScript warns with CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. If you need to see every call, use a PreToolUse hook. The exception is AskUserQuestion, which always reaches the callback.

env behaves differently in the two SDKs. In TypeScript, env replaces process.env, so env: { FOO: "x" } deletes your API key and PATH; always spread { ...process.env, FOO: "x" }. In Python, env is merged over the inherited environment. Knowing this asymmetry is a strong signal you have debugged it.

result only exists on subtype == "success". And the sharper version: check terminal_reason before subtype, because a failed final API request can surface as subtype: "success" with terminal_reason: "api_error".

Cost numbers are estimates. total_cost_usd is computed client-side from a bundled price table. Fine for dashboards and budgets, never for billing — use the Usage and Cost API. And the fields differ: usage excludes subagents, while total_cost_usd and model_usage include them.

Budgets are off by default. Neither max_turns nor max_budget_usd is set unless you set it. max_turns=0 means unlimited; max_budget_usd=0 is rejected at startup.

Permissions are evaluated in a fixed order: hooks, deny rules, ask rules, permission mode, allow rules, then can_use_tool. Being able to recite that order answers half the permission questions before they are finished.

Common interview questions

"What is the Claude Agent SDK, and when would you use it over the Messages API?" Use the thirty-second answer, then the dividing line: the Messages API when you want one narrow model call and will write any tool loop yourself; the Agent SDK when the task is multi-step work over files or shell and you want a hardened loop, built-in tools, permissions and sessions. Mention that the Agent SDK is heavier — it spawns a process — so it is the wrong choice for a simple classification endpoint.

"Walk me through the agent loop." Prompt in. Claude responds with text and/or tool calls. The SDK executes the tool calls and feeds results back. Repeat until Claude responds with no tool calls, which is the termination condition. Then a final AssistantMessage, then a ResultMessage. Add that one round trip is a turn and that maxTurns bounds it, and you have covered everything they were listening for.

"How do you stop an agent doing something destructive?" Give defence in depth rather than one answer. Remove the capability with disallowed_tools. Scope the working directory with cwd and add_dirs. Choose a mode: dontAsk plus an explicit allowed_tools list for headless agents, plan for propose-only. Gate what is left with can_use_tool or, if you need to see every call, a PreToolUse hook. Cap the run with max_turns and max_budget_usd. Then add the honest caveats: the bash AST parser is a permission gate, not a sandbox, and allowed_tools does not constrain bypassPermissions.

"Your agent edited the wrong file. What now?" Resuming does not help, because a session restores the conversation and not the filesystem. The SDK's answer is enableFileCheckpointing plus rewindFiles(userMessageId), enabled on both the original and any resumed session. The real-world answer is also git: run agents on a branch with a clean tree so the diff is the audit trail.

"How do you keep context across several questions?" Three options with different shapes. continue_conversation resumes the most recent session in the cwd. resume="<id>" reopens a specific one, which is how you back a chat UI — store the session_id from every result. fork_session branches from a copy of the history, leaving the original untouched. In Python, ClaudeSDKClient keeps one session alive across calls and adds interrupt(); plain query() creates a new session each call.

"Why are your MCP tools visible but never called?" Because they were never pre-approved, so the permission flow denies them. Add mcp__server__tool, or the whole server with mcp__server__*, to allowed_tools. Note that an unanchored * or a bare mcp__* in an allow rule is ignored with a warning.

"A colleague's agent works locally and fails in the container. Where do you look?" Four places, in order. Was the binary installed — npm ci --omit=optional drops the platform optional dependency and gives Native CLI binary for <platform>-<arch> not found, and on Alpine there is no musllinux Python wheel at all. Is the key in the subprocess environment, remembering that nothing loads .env and that TypeScript's env replaces rather than merges. Is cwd what you think it is. And if you rely on a native install, does claude --version work in the service's environment rather than your login shell.

"What does init tell you?" The registered tools, every MCP server's status, the model, and apiKeySource — one of ANTHROPIC_API_KEY, apiKeyHelper, /login managed key or none. Add that MCP servers connect in the background by default since TS 0.3.142, so status: "pending" is normal rather than a failure; the real failures are failed and needs-auth.

"How do you get machine-readable output?" output_format={"type": "json_schema", "schema": ...}, generated from Pydantic or Zod, then read structured_output from the result — requiring both subtype == "success" and a non-null structured_output, because an unsatisfiable schema yields a successful-looking result with nothing in it. There is a dedicated subtype, error_max_structured_output_retries, for repeated failures.

"What is a hook, and when would you use one instead of a permission callback?" A hook is a callback in your own process fired at a lifecycle event — PreToolUse, PostToolUse, Stop, UserPromptSubmit, PreCompact and others. Two properties make it different from can_use_tool. First, hooks run outside the model's context, so they cost no tokens, which makes them cheap enough to attach to every call. Second, they sit at the top of the permission order, which means a hook sees calls that an allow rule would otherwise have approved silently. Use a hook when you need an audit trail of everything the agent attempted, or a prohibition that must hold regardless of what is on the allowlist; use can_use_tool when you want to make a judgement call on the subset that genuinely needs one. Matchers are exact strings or regexes on the tool name, all matching hooks for an event fire concurrently, and a hook that exceeds its timeout is discarded while the session continues — so a slow hook fails open, which is worth saying out loud when the interviewer is probing for security awareness.

"What is compaction, and where should persistent instructions live?" As the conversation approaches the context limit, older history is summarised automatically and a compact_boundary system message is emitted. You can trigger it on demand by sending /compact as a prompt, and intercept it with a PreCompact hook whose trigger is manual or auto. The consequence worth naming is where to put rules you need honoured for the whole session: not in the opening prompt, which may be summarised away, but in CLAUDE.md, which is re-injected on every request. Candidates who know this have debugged an agent that forgot its own constraints halfway through a long run.

"Streaming input or a single string prompt?" A string prompt is single message input: one shot, stateless, and the right shape for a Lambda handler or a CI job, at the cost of no image attachments, no queueing mid-run and no interrupts. Streaming input means passing an AsyncIterable instead, and it is what the documentation recommends for everything else: a long-lived session, queued messages, attachments, interrupt(), and mid-session set_model and set_permission_mode. In Python, ClaudeSDKClient is the ergonomic wrapper around it; in TypeScript there is no client class and the Query object returned by query() carries the control methods instead.

"Your streaming agent hangs with no output. Where do you look first?" Your own prompt generator, before the SDK. In TypeScript a generator that throws surfaces as Claude Code process aborted by user, sometimes behind a long minified line, which reads like an SDK fault and is not. In Python the exception is logged only at debug level and the session simply hangs with no error at all. Wrap the generator body in a try/except that logs loudly, and register a stderr callback while you are there — the Error output: Check stderr output for details text in ProcessError is fixed boilerplate rather than the real stderr, which you only get through that callback.

"How would you run this in CI without it being dangerous?" Name the layers rather than one setting. A fresh container per job, so there is no state to corrupt and nothing from a previous tenant. cwd pointed at the checkout and nothing else. tools set to the minimum base set, with disallowed_tools removing Write, Edit or WebFetch if the job is read-only. permission_mode="dontAsk" with an explicit allowed_tools list, which denies anything that would otherwise prompt rather than hoping a human is watching. max_turns and max_budget_usd so a confused run ends cheaply. The API key supplied from a secret manager into the process environment, never baked into an image. And session_id logged from every result so a failed job is traceable afterwards. If the interviewer pushes on isolation, be honest about the limit: setting_sources=[] stops user, project and local settings loading, but managed policy, ~/.claude.json and auto memory are read regardless, so the container boundary is doing the real work.

"Which version are you on, and how do you upgrade?" TypeScript 0.3.285, Python 0.2.162, both bundling CLI v2.1.285. Pin the SDK, because pinning the SDK pins the CLI. Take patches continuously and read the changelog before a minor: the 0.2 to 0.3 TypeScript bump removed the entire V2 session API (unstable_v2_createSession and friends) and replaced TodoWrite with the Task tools.

Sixty-second self-test

Answer out loud. Any hesitation is where to go back.

1. What is a turn, and what does maxTurns count?
2. Name the five core message types and the one field that only exists on success.
3. Which field do you check before subtype, and why?
4. Does allowed_tools restrict which tools exist? What does?
5. In which order are permissions evaluated?
6. When does can_use_tool not fire?
7. What does env do differently in TypeScript versus Python?
8. Does resuming a session restore your files? What does?
9. What is the fully qualified name of a tool lookup on a server keyed crm?
10. Why is total_cost_usd unsuitable for billing, and what includes subagent spend?
11. What are the two Python-specific install failures — one on Alpine, one on Windows?
12. How do you restore Claude Code's system prompt, and why is it not the default?

If you can answer all twelve without looking, you know this better than most people who list it on a CV. Where you stumbled, the matching section of the detailed guide is the place to go, and the tips file covers the mistakes that produce those stumbles in real work.

Everything here comes from the way the Claude Agent SDK actually fails in a beginner's first week, not from a list of best practices. Each mistake gets its symptom, its cause and its fix, because the symptom is what you will see and the cause is what you will not.

Verified against TypeScript SDK 0.3.285 and Python SDK 0.2.162, both bundling Claude Code CLI v2.1.285.

The mistakes beginners actually make

Treating allowed_tools as a sandbox

Symptom. You list ["Read", "Edit", "Glob"], feel safe, and later find the agent ran a shell command.

Cause. allowed_tools is an auto-approve list, not a restriction. Bash is still registered and Claude can still call it. What happens next depends on the permission mode: in default the call falls through to can_use_tool and is denied if you have no callback, but under bypassPermissions it simply runs.

Fix. Separate the three jobs. Use tools to set the base set — ["Read", "Glob", "Grep"], or [] for no built-ins at all. Use disallowed_tools to remove capability, where a bare name strips the tool from context entirely and a scoped rule like Bash(rm *) denies matching calls in every mode. Use allowed_tools only for what should run without being asked.

Expecting Claude Code's behaviour by default

Symptom. The same prompt that works beautifully in the CLI produces a shallow, incurious answer through the SDK.

Cause. Since 0.1.0 the SDK sends a minimal system prompt rather than Claude Code's.

Fix. system_prompt={"type": "preset", "preset": "claude_code"} in Python, or systemPrompt: { type: "preset", preset: "claude_code" } in TypeScript. Do this whenever the task is codebase work, which is what that prompt was written for.

Writing a permission callback that never runs

Symptom. Your can_use_tool function has a logging line that never prints, and the agent does whatever it likes.

Cause. The callback fires only when the permission flow falls through to a prompt. A call already approved by an allow rule, or running under bypassPermissions, never reaches it. TypeScript warns with CLAUDE_SDK_CAN_USE_TOOL_SHADOWED; Python emits a runtime warning that is easy to miss.

Fix. Keep allowed_tools to the calls you genuinely do not want to inspect, and move anything you must see to a PreToolUse hook, which sits at the top of the permission order and sees everything. Remember AskUserQuestion is the one tool that always reaches the callback.

Clobbering the environment in TypeScript

Symptom. You add one environment variable and immediately get Not logged in · Please run /login or Invalid API key.

Cause. In TypeScript, options.env replaces process.env for the subprocess. Setting env: { MY_VAR: "x" } removes ANTHROPIC_API_KEY, PATH and everything else.

Fix. Always spread: env: { ...process.env, MY_VAR: "x" }. Python merges instead, so the same mistake is impossible there — which is exactly why it catches people moving between the two.

Expecting .env to be loaded

Symptom. A .env file plainly contains a valid key and the SDK insists it is invalid.

Cause. The SDK does not read .env files. Nothing does it for you.

Fix. Load it yourself with python-dotenv or dotenv before calling query(), or export the variable in the shell or container that starts the process.

Reading result without checking the subtype

Symptom. Code that works for weeks raises AttributeError or prints undefined the first time a run hits its turn cap.

Cause. The result field exists only when subtype == "success". The other subtypes are error_max_turns, error_max_budget_usd, error_during_execution and error_max_structured_output_retries.

Fix. Check the subtype first — and check terminal_reason before it, because a failed final API request can appear as subtype: "success" with terminal_reason: "api_error". Also wrap the loop: a single-shot query() that ends on an error result yields the result and then raises.

Formatting Optional cost fields

Symptom. TypeError: unsupported format string passed to NoneType.__format__.

Cause. In Python, total_cost_usd, usage and model_usage are all Optional.

Fix. Guard every read: message.total_cost_usd or 0. And treat a missing cost as unknown rather than free — after a crash the result is error_during_execution, sometimes with zeroed cost.

Running without a budget

Symptom. A console bill, or a run that is still going an hour later.

Cause. Both caps are off by default.

Fix. Set max_turns and max_budget_usd on every agent from the first commit. max_turns=0 means unlimited rather than zero; max_budget_usd=0 is rejected at startup. Set them generously rather than tightly — a cap that fires on normal work teaches you to raise it reflexively, which defeats the point.

Mis-naming a custom tool

Symptom. Your tool appears in the agent's tool list, Claude calls it, and nothing happens.

Cause. It was not pre-approved, so the permission flow denied it. The fully qualified name is mcp__{server_key}__{tool_name}, where the server key is the key in the mcp_servers dictionary — not the name= you passed to create_sdk_mcp_server.

Fix. Add the exact name, or the whole server with mcp__weather__*, to allowed_tools. An unanchored * or a bare mcp__* in an allow rule is ignored with a warning, although deny rules accept those globs.

Expecting a session to restore files

Symptom. You resume a session after a bad edit, expecting the file to come back.

Cause. A session persists the conversation, not the filesystem.

Fix. Use git. Run agents on a branch with a clean working tree so the diff is your audit trail and git checkout is your undo. If you need SDK-level undo, enable enableFileCheckpointing on both the original and any resumed session, then call rewindFiles(userMessageId).

Installing without the binary

Symptom. Native CLI binary for <platform>-<arch> not found in TypeScript, or Claude Code not found at: ... in Python.

Cause. In TypeScript, the platform binary ships as an optional dependency, and npm ci --omit=optional skips it. In Python there is no musllinux wheel, so Alpine gets a source distribution with no binary, and versions 0.2.160 to 0.2.162 publish no win_amd64 wheel either, so Windows x64 also gets the sdist.

Fix. Keep optional dependencies in Node installs. On Alpine or Windows, install Claude Code natively (curl -fsSL https://claude.ai/install.sh | bash, or irm https://claude.ai/install.ps1 | iex) and let the SDK find it on PATH, or pin claude-agent-sdk==0.2.159 on Windows. Never point cli_path at npm's claude.cmd — since Python 0.2.124 the SDK refuses batch shims outright.

Trusting the "Error output" line

Symptom. Command failed with exit code 1 followed by Error output: Check stderr output for details, and no stderr anywhere.

Cause. That text is fixed boilerplate, not the real stderr.

Fix. Register a stderr callback and log whatever it gives you. Python's debug_stderr is ignored, so the callback is the only route.

Catching ProcessError before ResultError

Symptom. Your specific handler for agent error results never runs.

Cause. Since Python 0.2.140, ResultError is a subclass of ProcessError, so a ProcessError clause placed first swallows it.

Fix. Order the clauses specific to general: except ResultError, then except ProcessError, then except CLINotFoundError.

Debugging the SDK when the bug is in your generator

Symptom. A streaming agent hangs with no output, or TypeScript reports Claude Code process aborted by user.

Cause. Your prompt generator threw. In TypeScript it surfaces as that misleading message; in Python it is logged at debug level only and the session hangs silently.

Fix. Wrap the generator body in a try/except that logs loudly before anything else.

Setting max_turns too low and calling the agent incapable

Symptom. Every run ends with error_max_turns and a half-finished job, so you conclude the agent cannot do the task.

Cause. max_turns counts tool-use turns, not messages. An agent that globs, reads six files, greps twice, edits one and then explains itself has spent a dozen turns on work you would describe as a single step.

Fix. Measure before you cap. Run once with a generous limit, read num_turns from the result, and set the cap at roughly twice that. Treat the cap as a runaway guard, not a performance target.

Losing skills, agents or CLAUDE.md without realising

Symptom. A skill you can see on disk reports Skill <name> is not in this session's skills allowlist, or simply never loads.

Cause. Two different things. Either setting_sources excludes user or project, so .claude/ was never read, or cwd points outside the repository that contains .claude/skills/. The default — omitting setting_sources entirely — loads user, project and local settings just as the CLI does, so this usually means someone passed [] for isolation and forgot the side effect.

Fix. Check the init message, which lists what actually loaded, then fix setting_sources or cwd. For an individual skill, either name it in the skills option or dispatch it explicitly as /<name>.

Assuming task tracking still works after a model upgrade

Symptom. Progress tracking silently stops after you switch models, with no error.

Cause. TaskCreate, TaskGet, TaskUpdate, TaskList and the older TodoWrite are default tools only on Claude 3.x, Opus 4.0 through 4.7, Sonnet 4.0 through 4.6 and Haiku 4.5. On Opus 4.8, Sonnet 5, Fable 5, Mythos 5 and newer they are off unless you ask for them.

Fix. Name them in tools or allowed_tools, or set CLAUDE_CODE_ENABLE_TODO_TOOLS=1. While you are there, note that Task tools accumulate by ID rather than replacing a snapshot list, so a consumer written against TodoWrite needs to merge rather than overwrite.

Trusting a successful-looking structured output

Symptom. Your code indexes structured_output and crashes on None, on a run that reported success.

Cause. A schema the model cannot satisfy produces a success result with no structured output at all. There is a separate subtype, error_max_structured_output_retries, for the case where it tried and gave up.

Fix. Require both subtype == "success" and a non-null structured_output, and treat anything else as failure. If it happens often, flatten the schema — deeply nested objects with many required fields are far harder to satisfy.

Hitting 429s by fanning out

Symptom. API Error: Request rejected (429) under load, or intermittently in CI.

Cause. Rate limits apply to the key or project, and a wide parallel fan-out of subagents is the fastest way to reach them.

Fix. Lower concurrency, batch the work rather than launching everything at once, and set fallback_model so a 529 capacity error degrades instead of failing. A 529 does not count against your quota; a 429 does.

Habits worth adopting on day one

Print the init message until it is boring. It lists the registered tools, every MCP server's status, the model, and apiKeySource. Most "why is my agent behaving strangely" questions are answered there in ten seconds. And learn to read status: "pending" as normal — since TS 0.3.142, MCP servers connect in the background, so pending means slow, while failed and needs-auth mean broken.

Log session_id from every result. It is the handle for resuming the conversation, finding the JSONL transcript under ~/.claude/projects/, and correlating a run with traces later. It costs one line and it is the difference between investigating an incident and guessing about it.

Work on a branch with a clean tree. Agents edit files. Git is your checkpoint, your diff and your undo, and it works regardless of which SDK options you remembered.

Put durable rules in CLAUDE.md, not the first prompt. CLAUDE.md is re-injected on every request; the opening prompt can be summarised away when compaction fires near the context limit. If your agent forgets a constraint halfway through a long run, this is almost always why.

Start in default mode and loosen deliberately. With no callback, default denies anything unapproved, which is a safe place to learn what your agent actually wants to do. Promote to acceptEdits once you know, and reach for dontAsk plus an explicit allowed_tools list for anything headless. Keep bypassPermissions for isolated containers only, and remember allowed_tools does not constrain it — use disallowed_tools or hooks there.

Set cwd explicitly, always. It is what Read, Glob and Grep resolve relative paths against. Relying on the process's inherited working directory works on your laptop and surprises you in a service.

Pin the SDK and read changelogs. Pinning the SDK pins the bundled CLI, which is the whole agent. Take patch releases continuously; read the changelog before a minor, because minors have removed APIs — the TypeScript 0.2 to 0.3 bump deleted the V2 session API and replaced TodoWrite with the Task tools.

Prefer skills="all" over a wildcard list. Skill names are validated strictly now, and skills=["*"] or ["plugin:*"] raises before the CLI even starts.

Never use the console OpenTelemetry exporter. Stdout is the SDK's message channel. A console exporter corrupts it. Use OTLP, and set CLAUDE_CODE_OTEL_DIAG_STDERR=1 if exports seem to vanish, because export failures are otherwise silent.

Treat cost numbers as estimates. total_cost_usd is computed client-side from a bundled price table. Excellent for dashboards and for spotting a runaway loop; never for invoicing. And know what each field counts: usage excludes subagents, while total_cost_usd and model_usage include them.

Give deny messages that steer. The message on a deny goes back to the model as an explanation. "Secrets are off limits, read config via the loader instead" changes the next attempt; "denied" produces another attempt at the same thing. The same applies to updated_input on an allow, which lets you quietly add a --dry-run or clamp a path rather than refusing outright.

Mark read-only custom tools as read-only. Custom tools run sequentially by default. A readOnlyHint annotation lets them run in parallel with other read-only calls, which is free latency on any agent that does several lookups per turn.

Keep one named transcript per real conversation. rename_session and tag_session feel cosmetic until you have a few hundred JSONL files and need the one from last Tuesday's incident. Name them as you create them.

The checklist

Before you let an agent run unattended, confirm each line.

• ANTHROPIC_API_KEY is in the subprocess environment, and TypeScript env spreads process.env.
• cwd is set explicitly to the directory the agent should work in.
• tools is the minimum base set the task needs.
• disallowed_tools removes everything the task must never do.
• allowed_tools covers only calls you are content to see run unasked.
• A permission mode is chosen deliberately, and it is not bypassPermissions outside a container.
• can_use_tool or a PreToolUse hook is in place, and you have verified it actually fires.
• max_turns and max_budget_usd are both set.
• The result handler checks terminal_reason, then subtype, then the field it wants.
• ResultError is caught before ProcessError, and a stderr callback is registered.
• session_id is logged.
• The working tree is clean and on a branch, or checkpointing is enabled.
• The SDK version is pinned in the lockfile, and optional dependencies are not being skipped in the image build.

Work through that list once by hand and the shape of it will stay with you. Nearly every item on it corresponds to a specific failure above, which is the point: these are not style preferences, they are the things that actually go wrong.

This is part two of three. It picks up where Beginner ended and takes every topic from there further, then adds the machinery you have not met yet: the control surface of a live session, hooks, subagents, cost accounting, telemetry, and what it takes to run an agent as a service other people depend on.

Where this picks up

The versions this level is written against are the TypeScript SDK 0.3.285 and the Python SDK 0.2.162, both released on 29 September 2026, both bundling Claude Code CLI 2.1.285. The two packages are versioned independently, and the SDK version pins the CLI binary, so upgrading the SDK is how you upgrade the CLI. Most sections end with a Try it you can run against a real repository in a few minutes.

The subprocess model, precisely

Beginner told you the SDK "runs Claude Code for you". The precise statement is worth internalising, because almost every production surprise follows from it: query() spawns one claude command-line process and talks to it over standard input and output using newline-delimited JSON plus a small control protocol. One session means one subprocess. That subprocess owns the shell it runs commands in, the working directory, and the conversation transcript it writes to local disk. It never listens on the network.

Three consequences fall straight out of that.

Your process is not the agent's process. The model's Bash calls run in the subprocess, inheriting its environment and working directory, not your request handler's. Change your own process's environment after the session starts and the subprocess never sees it.

Environment variables are the real configuration channel for Claude Code's own behaviour. Many knobs — timeouts, retry counts, telemetry, subagent caps — are not SDK options at all. They are environment variables read by the CLI, and you pass them through the env option. This is where the single most common bug at this level lives: in TypeScript, env replaces process.env for the subprocess, so passing env: { MY_VAR: "x" } strips ANTHROPIC_API_KEY and you get Not logged in · Please run /login or Invalid API key. In Python, env is merged over the inherited environment. Write the TypeScript spread every time.

import { query } from "@anthropic-ai/claude-agent-sdk";

const q = query({
  prompt: "Summarise what changed in the last commit.",
  options: {
    cwd: "/srv/checkouts/payments-api",
    model: "claude-sonnet-5",
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 12,
    // env REPLACES process.env in TypeScript — always spread it
    env: { ...process.env, API_TIMEOUT_MS: "120000", CLAUDE_CODE_MAX_RETRIES: "4" },
  },
});

for await (const m of q) {
  if (m.type === "result") console.log(m.subtype, m.terminal_reason, m.total_cost_usd);
}

Nothing about a session is portable by default. The transcript lives at ~/.claude/projects/<encoded-cwd>/<id>.jsonl, where the encoded working directory is the path with every non-alphanumeric character replaced by -, and the root can be moved with CLAUDE_CONFIG_DIR. A session persists the conversation, not the filesystem. Resume it on a different container and the history is gone unless you mirrored it; resume it in a different working tree and the conversation will talk confidently about files that are not there.

The flip side is that you get the whole of Claude Code — its tools, permission engine, skills and plugin loading, compaction — without reimplementing any of it. That is why it is not interchangeable with the client SDK (anthropic / @anthropic-ai/sdk), where you write the tool loop yourself. If you want the loop hosted by Anthropic instead, Managed Agents is the third option; the Agent SDK is the middle path, where the loop runs on your infrastructure but you did not write it.

The agent loop and the message stream

The loop itself is four steps that repeat: the prompt goes in; Claude answers with text, tool calls, or both; the SDK executes the tools; the results feed back. The cycle ends when Claude replies with no tool calls, and you then get a final AssistantMessage followed by a ResultMessage. A turn is one round trip of that cycle, and maxTurns counts tool-use turns only — it is not a wall-clock limit and not a token limit.

What you iterate is a union of message types, and handling it properly is the difference between an agent you can debug and one that fails opaquely. The five core members:

• SystemMessage, whose init subtype arrives first and is your best diagnostic: it lists the registered tools, every MCP server's status, the model, and apiKeySource (ANTHROPIC_API_KEY, apiKeyHelper, /login managed key or none). Other subtypes include compact_boundary, informational and worker_shutting_down; in TypeScript the non-init subtypes are separate union members such as SDKCompactBoundaryMessage.
• AssistantMessage, one content block per message, with blocks from the same API response sharing a message ID.
• UserMessage, which carries tool results as well as anything you stream in.
• StreamEvent, the raw deltas, emitted only when includePartialMessages (include_partial_messages in Python) is on.
• ResultMessage, with the final text, usage, total_cost_usd, num_turns, session_id, subtype, stop_reason and terminal_reason.

Beyond those come observability messages: rate-limit events, task progress, hook events, mirror_error when a session-store write fails, and conversation resets. Python discriminates with isinstance; TypeScript with msg.type === "result", where assistant and user content sits at message.message.content, one level deeper than people expect.

Reading the result correctly has two rules that cost people hours. First, result (the text) exists only when subtype is success — the other subtypes are error_max_turns, error_max_budget_usd, error_during_execution and error_max_structured_output_retries. Second, check terminal_reason before subtype, because when the final request fails with an API error the CLI still reports subtype: "success" with terminal_reason: "api_error". An agent that only looks at subtype will cheerfully return an empty answer as a successful one.

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage

async def run(prompt: str) -> str:
    async for msg in query(prompt=prompt, options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"], max_turns=12, permission_mode="dontAsk",
    )):
        if isinstance(msg, SystemMessage) and msg.subtype == "init":
            log.info("tools=%s mcp=%s key=%s", msg.data.get("tools"),
                     msg.data.get("mcp_servers"), msg.data.get("apiKeySource"))
        if isinstance(msg, ResultMessage):
            if msg.terminal_reason not in (None, "success"):
                raise RuntimeError(f"terminated: {msg.terminal_reason}")
            if msg.subtype != "success":
                raise RuntimeError(f"failed: {msg.subtype}")
            return msg.result
    raise RuntimeError("stream ended with no result")

Note the last line. Some trailing system events can arrive after the result, so iterate to completion rather than breaking out early; but equally, do not assume a result always arrives. And in Python, total_cost_usd, usage and model_usage are optional fields, so guard for None before arithmetic.

Tool surface: what exists, what is approved, what is gone

Three options sound similar and do different jobs. Getting them straight removes a whole class of "the model ignored my restriction" confusion.

tools defines the base set that exists in the session. Pass an explicit array like ["Read", "Edit", "Bash"] for exactly those, [] for no built-ins at all, or { type: "preset", preset: "claude_code" } for the full default set. allowedTools is an auto-approve list; it does not restrict what exists, it says which calls skip the permission prompt. disallowedTools removes a tool from context entirely when you give a bare name, and denies matching calls in every mode when you give a scoped rule such as Bash(rm *).

So a read-only analyst is tools: ["Read", "Glob", "Grep"], and a locked-down headless worker is an explicit allowedTools list plus permissionMode: "dontAsk" — anything that would otherwise prompt is denied instead of hanging.

Two recent defaults will catch you if you learned this surface a year ago. Task-tracking tools are off by default on newer models: TaskCreate, TaskGet, TaskUpdate, TaskList and the older TodoWrite are default tools only on Claude 3.x, Opus 4.0 to 4.7, Sonnet 4.0 to 4.6 and Haiku 4.5. On Opus 4.8, Sonnet 5, Fable 5, Mythos 5 and newer you must name them in tools or allowedTools, or set CLAUDE_CODE_ENABLE_TODO_TOOLS=1. These Task tools replaced TodoWrite in headless and SDK sessions, so accumulate tasks by ID rather than replacing a snapshot list. Grep and Glob are also no longer registered as dedicated tools on native builds; searching happens through embedded find and grep inside Bash. If you intercept searches in canUseTool or a hook, name Grep and Glob in tools or allowedTools to get the dedicated tools back.

The remaining built-ins are Read, Edit, Write, Bash, WebSearch, WebFetch, ToolSearch, Agent, Skill and AskUserQuestion. Read-only tools, and MCP tools annotated readOnlyHint, may run in parallel; mutating tools run sequentially. Your own custom tools default to sequential, and you opt into parallelism by annotating them readOnlyHint.

The other option that silently changes behaviour is settingSources. Omitting it loads user, project and local filesystem settings exactly as the CLI does — ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, CLAUDE.md, and the skills, agents and commands under .claude/ — equivalent to ["user", "project", "local"]. Pass [] to isolate the session from the host, which is what you want for anything multi-tenant. Managed policy settings, ~/.claude.json, auto memory, claude.ai connectors and sandbox credential denies are read regardless, so [] is isolation of the ordinary layers, not a vacuum.

Finally, the system prompt. The SDK does not use Claude Code's prompt by default; it sends a minimal one. If your agent should behave like Claude Code — the coding conventions, the file-editing discipline — ask for it explicitly with systemPrompt: { type: "preset", preset: "claude_code" } (system_prompt={"type": "preset", "preset": "claude_code"} in Python). You can append to the preset, or supply a custom prompt; a mid-session change only takes effect at the next compaction, unless you pass snapshot: false to rebuild it on every request.

Sessions: continue, resume, fork

A session is the persisted conversation, and there are three ways back into one. Continue picks up the most recent session in the working directory (continue: true in TypeScript, continue_conversation=True in Python). Resume takes a specific ID, with resume: "<id>". Fork creates a new ID starting from a copy of the history, leaving the original untouched — forkSession / fork_session. Forking is the right primitive for "try this two different ways from the same context", and for anything user-facing where the original branch must stay reproducible.

You can also supply your own sessionId / session_id, which must be a UUID and cannot be combined with continue or resume unless you also fork. In TypeScript, persistSession: false keeps a session in memory with nothing written to disk; Python has no such option, so set CLAUDE_CODE_SKIP_PROMPT_HISTORY in env instead.

Both SDKs ship session helpers so you do not have to parse JSONL yourself: listSessions, getSessionMessages, getSessionInfo, renameSession, tagSession, deleteSession and getSubagentMessages in TypeScript, with snake_case equivalents plus list_subagents in Python. Tagging is more useful than it sounds: where sessions belong to tickets or tenants, a tag is how you find them again without a side table.

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def follow_up(session_id: str, prompt: str):
    opts = ClaudeAgentOptions(resume=session_id, fork_session=True, max_turns=8)
    async for msg in query(prompt=prompt, options=opts):
        if isinstance(msg, ResultMessage):
            # Since CLI 2.1.277 a resumed session's totals CONTINUE from earlier turns.
            return msg.session_id, msg.total_cost_usd

That comment matters for billing dashboards. Since CLI 2.1.277, a resumed or forked session's total_cost_usd and modelUsage continue from earlier turns rather than restarting at zero. So you read the latest result; you do not sum results across resumes, or you will double-count.

For anything that needs to resume on a different machine, local disk is not enough and you want a SessionStore: an adapter you provide that mirrors transcripts to S3, Redis, Postgres or similar. It has two required methods, append and load, and optional listSessions, listSessionSummaries, delete and listSubkeys. Flushing is "batched" or "eager". Reference adapters exist for all three backends, and there is a conformance suite at claude_agent_sdk.testing.run_session_store_conformance you should run against your own adapter before trusting it. Two caveats: the store is a mirror (a dual write), not a replacement for local disk; and mirror writes are best-effort, so a failed batch is dropped and the only sign is a mirror_error message. Alert on it.

Finally, rewinding. resumeSessionAt / resume_session_at together with resumeDropsTurn / resume_drops_turn gives you a safe "go back to before that last prompt" — the primitive behind a usable undo in a chat interface. File rewind is separate, needs enableFileCheckpointing on both the original and resumed session, and is called as rewindFiles(userMessageId) (TypeScript accepts { dryRun }). Call it after resuming with an empty prompt; calling it once the stream has ended gives you ProcessTransport is not ready for writing.

Streaming input and the live control surface

Passing a string as the prompt gives you a one-shot session: fine for a Lambda, a cron job, or a CI step, with no image attachments, no queueing, and no interrupts. Passing an AsyncIterable instead puts you in streaming-input mode, which the docs recommend and which is what you want for anything interactive. You get a long-lived session, the ability to queue messages while a turn is running, image attachments, real interrupts, and permission prompts handled in the loop rather than pre-decided.

The two SDKs differ in shape here. Python has a client class: async with ClaudeSDKClient(options=...) as client:, then await client.query(...) and async for m in client.receive_response():. receive_response() stops after the ResultMessage; receive_messages() streams everything. The client keeps one session across calls and exposes connect(), interrupt(), set_permission_mode(), set_model() (pass None for the default), rewind_files(id), get_mcp_status(), reconnect_mcp_server(), toggle_mcp_server(name, enabled), stop_task(id), get_server_info(), get_context_usage() and disconnect(). Calling a method before connecting gives you the clear Not connected. Call connect() first., which is reason enough to always use the context manager.

TypeScript has no client class. The Query object that query() returns carries the control methods, and you keep continuity across calls with continue: true or resume. Streaming-only methods are interrupt(), setPermissionMode(), setModel() and applyFlagSettings(). Introspection covers initializationResult(), supportedModels(), supportedAgents(), accountInfo() and getContextUsage({ detail: 'summary' | 'full' }); MCP control covers mcpServerStatus(), reconnectMcpServer(), toggleMcpServer() and setMcpServers(). There are also rewindFiles(), readFile(), reloadSkills(), updateSettings('localSettings' | 'userSettings', …), streamInput(), stopTask() and close().

applyFlagSettings() deserves its own note, because its timing is not uniform. effortLevel, ultracode, permissions, hooks, skillOverrides, fastMode and agent apply from the next turn. model applies in the current turn. The system prompt has no effect mid-session. Successive calls shallow-merge top-level keys, so a second call that omits hooks leaves the earlier hooks in place.

import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";

async function* inbox(): AsyncIterable<SDKUserMessage> {
  for await (const text of userMessages()) {
    yield { type: "user", message: { role: "user", content: text },
            parent_tool_use_id: null, session_id: "" };
  }
}

const q = query({ prompt: inbox(), options: { permissionMode: "default", maxTurns: 0 } });

// elsewhere, on a cancel button:
await q.interrupt();
// escalate trust once the user has reviewed the plan:
await q.setPermissionMode("acceptEdits");

One trap with streaming input is worth spelling out. If your generator throws — a missing file, a closed queue — TypeScript surfaces it as Claude Code process aborted by user, often preceded by a long minified line, which sends people hunting for a cancellation that never happened. In Python the generator exception is logged at debug level and the session simply hangs. Wrap the generator body in its own try/except and log there.

Note also maxTurns: 0 above: zero means unlimited, not "no turns". The analogous budget option behaves differently — maxBudgetUsd: 0 is rejected at startup rather than treated as unlimited. Both caps are off by default.

Custom tools and MCP, in process and out

The cleanest way to give an agent an organisation-specific capability is a custom tool, which under the hood is an in-process MCP server. No subprocess, no socket, no transport to debug — it is a function in your application with a schema.

from typing import Annotated
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions

@tool("open_incidents", "List open incidents for a service", {
    "service": Annotated[str, "Service name as it appears in the registry"],
})
async def open_incidents(args):
    rows = await incidents.query(service=args["service"], state="open")
    if rows is None:
        return {"content": [{"type": "text", "text": "registry unavailable"}], "is_error": True}
    return {"content": [{"type": "text", "text": "\n".join(r.summary for r in rows)}]}

ops = create_sdk_mcp_server(name="ops", version="1.0.0", tools=[open_incidents])
options = ClaudeAgentOptions(
    mcp_servers={"ops": ops},
    allowed_tools=["mcp__ops__open_incidents"],
)

Two details carry most of the weight. Names are fully qualified as mcp__{server_key}__{tool_name}, where the server key is the key in mcpServers — rename it and every allow rule breaks. And returning is_error is how you tell the model a tool failed, rather than returning a sentence that reads like success. TypeScript's equivalents are tool(name, description, zodSchema, handler, { annotations }) and createSdkMcpServer({ name, version, tools, timeout }); the annotations are readOnlyHint, destructiveHint, idempotentHint and openWorldHint, and the first is what buys you parallel execution.

External MCP servers go in the same mcpServers map, as stdio { command, args, env }, remote { type: "http" | "sse", url, headers }, or a path to a config file (Python accepts str or Path). Server status in init is one of pending, connected, failed, needs-auth or disabled. Since TypeScript 0.3.142, MCP servers connect in the background by default, so a session starts immediately and a slow server reports pending — which is not a failure, and a dashboard that treats it as one will page you constantly. Set MCP_CONNECTION_NONBLOCKING=0 to restore blocking startup (capped at five seconds by default), or alwaysLoad: true on the individual server you cannot proceed without.

The failure most people hit is quieter: MCP tools that are visible and never called. They are in the tool list, the model tries them, and the permission flow denies them because nothing pre-approved them. Add mcp__server__tool, or mcp__server__* for the whole server. Unanchored globs like * or mcp__* in an allow rule are ignored with a warning, though deny rules do accept them.

In a service you also want strictMcpConfig / strict_mcp_config, which ignores .mcp.json, user settings, plugin servers and claude.ai connectors — without it, a developer's local connector can end up in a production session's tool list. The related mechanism is tool search: MCP tool schemas are deferred by default and loaded on demand, which keeps context small when you have dozens of tools; where it is unsupported, everything loads up front. For debugging, the knobs are MCP_TIMEOUT (30 s to connect), MCP_TOOL_TIMEOUT, CLAUDE_CODE_MCP_STARTUP_WAIT_MS, MCP_CONNECT_TIMEOUT_MS, and MAX_MCP_OUTPUT_TOKENS, which defaults to 25,000 tokens and spills larger output to a file.

Permissions, in evaluation order

The permission engine is the main safety boundary, and it is a fixed six-step pipeline whose result is always either allowed or denied:

Order explains behaviour you would otherwise find arbitrary. Hooks run first, so a hook can deny what an allow rule would have permitted. The canUseTool callback runs last, so it fires only when the flow falls through to a prompt — never for an auto-approved call. Set it alongside bypassPermissions or bare allowedTools entries and it never runs for those tools; TypeScript warns with CLAUDE_SDK_CAN_USE_TOOL_SHADOWED, Python emits a runtime warning. To see every call, use a PreToolUse hook. The one exception is AskUserQuestion, which always reaches the callback.

The modes, in rough order of trust:

For a headless worker, dontAsk plus an explicit allowedTools list is the right default: it fails closed and never hangs waiting for an answer nobody is there to give. bypassPermissions belongs only in an isolated container or CI job, needs allowDangerouslySkipPermissions: true in TypeScript, refuses to run as root or under sudo outside a recognised sandbox on Linux and macOS, and — crucially — is not constrained by allowedTools. To narrow it, use disallowedTools or hooks. Subagents inherit bypassPermissions from the parent, so one permissive parent opens the whole tree. As of TypeScript 0.3.269, writes in plan mode route through canUseTool even when allowDangerouslySkipPermissions is set.

from claude_agent_sdk import PermissionResultAllow, PermissionResultDeny

async def can_use_tool(tool_name, input_data, context):
    if tool_name == "Bash" and "--force" in input_data.get("command", ""):
        return PermissionResultDeny(message="forced operations need a human", interrupt=False)
    if tool_name == "Write":
        safe = redact(input_data)
        return PermissionResultAllow(updated_input=safe)
    return PermissionResultAllow()

Note that the callback can rewrite the input, not just vote on it. TypeScript's equivalent is canUseTool(toolName, input, { signal, suggestions, … }) returning { behavior: "allow", updatedInput } or { behavior: "deny", message }.

Underneath, the Bash gate parses commands into an AST and matches them against your rules, and eval always asks. Treat that as a permission gate and not a sandbox: it constrains which commands are approved, not what an approved command can reach. Real isolation is a container, a sandbox runtime, or a microVM, and that is Senior's territory.

Hooks: deterministic control outside the model's context

Hooks are callbacks in your process that fire at lifecycle events. Their defining property is that they run outside the model's context, so they cost no tokens and the model cannot argue with them. They can deny a call, rewrite its input, rewrite its output, or inject extra context.

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

async def protect_env_files(input_data, tool_use_id, context):
    path = input_data["tool_input"].get("file_path", "")
    if path.endswith(".env") or "/secrets/" in path:
        return {"hookSpecificOutput": {
            "hookEventName": input_data["hook_event_name"],
            "permissionDecision": "deny",
            "permissionDecisionReason": "Cannot modify .env or secrets files",
        }}
    return {}

options = ClaudeAgentOptions(hooks={
    "PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])],
})

Matchers are regexes or exact strings on the tool name (or the event target), and all matching hooks for an event fire concurrently — so do not write two hooks that expect to run in a particular order against the same event.

Python's events are PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStart, SubagentStop, PreCompact, PermissionRequest and Notification. TypeScript adds a longer list, including PostToolBatch, PostCompact, PreModelSwitch, PermissionDenied, TaskCreated, TaskCompleted, ConfigChange, CwdChanged and FileChanged. SessionStart and SessionEnd are TypeScript-only, which is a real portability cliff if you planned your audit trail around them.

The outputs a hook can return are permissionDecision (allow, deny, ask or defer), updatedInput, additionalContext, updatedToolOutput, systemMessage, continue and stopReason. In Python, async_ and continue_ are auto-converted to the wire names. If you are migrating older code, updatedMCPToolOutput in PostToolUse output was deprecated in TypeScript 0.2.121 in favour of updatedToolOutput, which works for every tool, not just MCP ones.

Timeouts are per-matcher, set in seconds on HookMatcher.timeout. The defaults are 600 s for most events, 30 s for UserPromptSubmit and the model-switch hooks, 10 s for MessageDisplay, and about 1.5 s for SessionEnd. A hook that times out is discarded and the session continues — which is the right default for availability and the wrong one for a compliance gate, so if a hook must not be skipped, keep it fast and local rather than calling a remote service inside it. Be aware too that shell hooks declared in settings files also run when the matching setting source is loaded, which is another argument for settingSources: [] in production.

The three patterns worth having in your toolkit: a PreToolUse deny gate for paths and commands you never want touched; a PostToolUse hook that redacts tool output before it re-enters the context; and a PreCompact hook (whose trigger is manual or auto) that records what the context looked like before summarisation, which is otherwise unrecoverable when you are debugging a long session that lost the plot.

Subagents, skills and plugins

A subagent is a separate agent spawned through the Agent tool. Its value is context isolation: it gets a fresh context, only the Agent tool's prompt string goes in, and only its final response comes back. That makes it the correct tool for work that would otherwise flood the parent's window — reading forty files to answer one question, or running a long search.

Define them with the agents option, or as Markdown files in .claude/agents/. Programmatic definitions override filesystem ones with the same name, which is how you keep a service's behaviour fixed regardless of what is in the checkout.

const options = {
  agents: {
    "test-runner": {
      description: "Runs the test suite and reports only failures",
      prompt: "Run the tests. Report failing test names and the assertion messages. Do not fix anything.",
      tools: ["Bash", "Read", "Glob"],
      model: "haiku",
      maxTurns: 15,
      background: true,
    },
  },
};

Each AgentDefinition can carry description, prompt, tools, disallowedTools, model, skills, memory, mcpServers, initialPrompt, maxTurns, background, effort, permissionMode and (TypeScript only) omitClaudeMd. Model aliases are fable, opus, sonnet, haiku and inherit — a cheaper model for mechanical subagent work is one of the easiest savings available. Subagents run in the background by default, and general-purpose is built in; CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 removes it, after which omitting the type gives subagent_type is required.

The caps are CLI environment variables. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS defaults to 20, and CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH defaults to 3 (set 1 for no nesting). Exceeding either appears as Concurrent subagent limit reached or Budget limit reached in tool-result text, not as an exception. There is no per-subagent wall-clock deadline, so bound them with AgentDefinition.maxTurns and the stall watchdog CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS. Wide parallel fan-outs are also the fastest way to hit a rate limit: API Error: Request rejected (429) usually means "you fanned out too far", not "raise the tier".

Skills are SKILL.md directories under .claude/skills/. Only their descriptions load at session start; the full content loads when the skill is invoked, which is what makes a large library affordable. Control them with the skills option, which takes "all" or a list of names; putting 'Skill' in allowedTools is deprecated. Names are validated before the CLI starts — parentheses, commas, control characters, wildcards such as * or :*, a leading slash, or surrounding whitespace are rejected — so skills=["*"] must become skills="all" or you get Invalid skill name at connect time. A missing skill usually means settingSources excludes user or project, or cwd points outside the repository holding .claude/skills/. Skill <name> is not in this session's skills allowlist means adding it to skills, or dispatching it as /<name>.

Plugins bundle skills, agents, hooks and MCP servers, and load by local path with plugins: [{ type: "local", path }]. They are the packaging unit when several services should share one set of conventions.

Structured output, budgets and context control

If an agent's answer feeds another system, free text is a liability. Set outputFormat: { type: "json_schema", schema } in TypeScript or output_format={"type": "json_schema", "schema": schema} in Python, generating the schema from Zod or Pydantic. Then read structured_output on the result — and require both subtype == "success" and a non-null structured_output, because a schema the model cannot satisfy produces a success result with a null payload. Repeated failures surface as the error_max_structured_output_retries subtype. If you see null often, simplify the schema; deeply nested unions are the usual culprit. An invalid schema fails earlier and louder, as API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid — it must be valid draft 2020-12 with property keys matching ^[a-zA-Z0-9_.-]{1,64}$.

Budgets are the other guardrail. maxTurns bounds tool-use rounds; maxBudgetUsd bounds estimated spend, including subagents. Both are off by default. On a single-shot query(), the SDK yields the error result and then raises or throws, so a loop without a try/except will surface Reached maximum number of turns as an unhandled exception after you have already seen the result.

Context is the resource that quietly runs out. Compaction happens automatically near the limit: older history is summarised and a compact_boundary message is emitted. You can force it by sending /compact as a prompt, which is worth doing deliberately before a long final step rather than letting it land mid-step. excludeDynamicSections: true on the preset moves per-user context out of the system prompt, enabling cache hits across users. Prompt is too long means the window is exceeded outright: compact, push work into subagents, or trim tool output.

Two cost-accounting facts matter, because dashboards get built on the wrong ones. First, total_cost_usd and costUSD are client-side estimates from a bundled price table (or from modelPricing), with ×1.1 applied for inference_geo: "us" data residency. Never bill customers from them; use the Usage and Cost API or the Console. Second, the fields count different things: usage covers the main loop only and excludes subagents, while total_cost_usd and modelUsage / model_usage include them. Deduplicate per-step usage by message ID, and read output tokens from the result, because the per-step output_tokens is a placeholder. In streaming mode each turn emits a result and total_cost_usd is the running total; /clear, /reset and /new reset totals and budget, and /clear issues a new session_id.

The practical cost levers, roughly in order of effect: maxBudgetUsd as a hard stop; effort: "low" for mechanical tasks (effort is low, medium, high, xhigh or max, and is separate from extended thinking, set with thinking: { type: "adaptive" | "enabled" | "disabled" }); cheaper models for subagents; tool search; excludeDynamicSections for cache hits; and avoiding mid-session model switches, since each model has its own cache. maxThinkingTokens / max_thinking_tokens is deprecated in favour of thinking.

Observability: telemetry from the CLI, not from you

The CLI exports OpenTelemetry itself. The SDK only passes environment variables through, which means your instrumentation is configuration, not code. The baseline is CLAUDE_CODE_ENABLE_TELEMETRY=1, the three exporters set to otlp (OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER, OTEL_TRACES_EXPORTER), CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 for traces, OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf and OTEL_EXPORTER_OTLP_ENDPOINT pointing at your collector.

options = ClaudeAgentOptions(env={
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://otel-collector.observability:4318",
    "OTEL_SERVICE_NAME": "support-agent",
    "OTEL_RESOURCE_ATTRIBUTES": "deployment.environment=prod,tenant.id=acme",
    "OTEL_METRIC_EXPORT_INTERVAL": "10000",
    "CLAUDE_CODE_OTEL_DIAG_STDERR": "1",
})

Two further operational details. Export intervals default to 60 s for metrics and 5 s for traces and logs, far too slow for short-lived runs that exit before the first flush — lower them. And export failures are silent: set CLAUDE_CODE_OTEL_DIAG_STDERR=1 to see them.

The span structure mirrors the loop. claude_code.interaction is the root, containing claude_code.llm_request, claude_code.tool (which carries tool.blocked_on_user and tool.execution, separating "waiting for a human" from "actually running"), and claude_code.hook spans, which need detailed beta tracing to appear. Subagent spans nest under the parent's tool span, so a fan-out reads as a tree. Every span carries session.id, the join key between your logs and the agent's. The SDK also auto-propagates W3C TRACEPARENT and TRACESTATE into the CLI and onward into Bash commands; Python needs the [otel] extra for this (pip install "claude-agent-sdk[otel]").

Content is off by default, which is the right default. Opt in selectively with OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS, OTEL_LOG_TOOL_CONTENT (truncated at 60 KB) and OTEL_LOG_RAW_API_BODIES. For teams in the Gulf and Egypt with data-residency commitments, this is the setting to think hardest about: prompts and tool content are the payloads most likely to contain personal data, and they land wherever your collector ships them. Percent-encode end-user and tenant IDs in resource attributes, and route the tool_decision, tool_result, mcp_server_connection and permission_mode_changed events to a SIEM. If you use a SessionStore, alert on mirror_error too. Because the exporter is plain OTLP, any OTLP backend works — point it at Langfuse and the agent's spans join your existing LLM traces.

Testing an agent you cannot make deterministic

The model is not deterministic, so the instinct to assert on its output leads to a suite nobody trusts. Test the parts you own, and assert on behaviour rather than wording.

Custom tools are ordinary functions. Call the handler directly with an args dict and assert on the returned content and is_error. This is where most of your coverage should be, because this is where your business logic lives.

Hooks are ordinary functions too. Call protect_env_files({"tool_input": {"file_path": "/app/.env"}, "hook_event_name": "PreToolUse"}, None, None) and assert the decision is deny. A table of paths and expected decisions is a genuinely valuable test, and it is fast.

Permission policy is testable as a matrix. Feed canUseTool the tool names and inputs you care about and assert allow or deny. Remember the shadowing rule when you interpret the result: if production has the tool in allowedTools, the callback will not run there, so a passing unit test proves nothing about production. Test what production actually uses.

For the loop itself, assert on the message stream. Did the agent call Edit at all? Did it ever attempt a denied path? Did the result come back success with a non-null structured_output? Did it finish inside maxTurns? Those assertions are stable across runs in a way that "the summary mentions the migration" is not. Structured output is your friend here: a schema turns a prose assertion into a field check.

Run the real thing in CI against a fixture repository. A throwaway working directory, settingSources: [] so no developer's settings leak in, strictMcpConfig: true, an explicit allowedTools, dontAsk, and a maxBudgetUsd so a loop cannot cost real money. Keep that suite small: it is a smoke test, not a regression grid.

Two environment traps. The SDK does not read .env files — load them yourself before the session starts. And in TypeScript before 0.3.261, runtimes without Symbol.dispose (the Jest node environment, vitest's vmThreads, Node below 18.18) throw Object not disposable; upgrading fixes it.

Running it as a service

The deployment shape follows from the subprocess model. Your own HTTP or WebSocket server sits in front; the subprocess never listens on a port. Three patterns cover almost everything.

Ephemeral: one container per task. A TASK_PROMPT environment variable, a maxTurns ceiling, exit when done. Simple, isolated, and the natural fit for CI and queue workers. Session continuity needs a store.

Long-running: many sessions per container. TypeScript uses streamInput() plus startup({ options, initializeTimeoutMs }) to pre-spawn a process, and the alpha prewarm() to hold a spare you claim() later. Python uses ClaudeSDKClient.

Hybrid: ephemeral containers plus a required SessionStore, so any container can pick up any session. This is the shape most user-facing products converge on.

Size from a measured floor: 1 GiB RAM, 5 GiB disk and 1 CPU per agent, and treat it as a floor, because memory grows with session length. Agents per host is (host RAM − overhead) / measured per-session peak RSS, measured on your own workload. Because memory grows, recycle subprocesses on a turn or age threshold. There is no top-level session timeout, so maxTurns is your bound.

Horizontally, the constraint is that a session's state is on one host's disk. Load-balance with consistent hashing on sessionId so each session pins to one container, or commit fully to a SessionStore and treat containers as interchangeable. Half-doing either gives you sessions that resume empty.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: support-agent
spec:
  replicas: 4
  template:
    spec:
      containers:
        - name: agent
          image: registry.example.com/support-agent:0.3.285
          resources:
            requests: { memory: "1Gi", cpu: "1" }
            limits: { memory: "2Gi", cpu: "2" }
          env:
            - name: ANTHROPIC_BASE_URL
              value: "http://llm-gateway.platform.svc:4000"
            - name: CLAUDE_CONFIG_DIR
              value: "/var/agent/config"
            - name: API_TIMEOUT_MS
              value: "600000"
          volumeMounts:
            - { name: state, mountPath: /var/agent }
      volumes:
        - name: state
          emptyDir: { sizeLimit: 5Gi }

Networking needs egress to api.anthropic.com — or your Bedrock or Vertex regional endpoint — plus your MCP endpoints, through a proxy with a domain allowlist, credential injection and logging. One Node gotcha: fetch() ignores HTTP_PROXY unless NODE_USE_ENV_PROXY=1 on Node 24 or later.

On secrets, the strongest pattern is that the agent never sees the key. Point ANTHROPIC_BASE_URL at a gateway that injects it — LiteLLM, Envoy, mitmproxy and Squid are the documented options — so a prompt injection cannot exfiltrate a credential that is not in the process. Keep tool credentials outside the agent too, behind a custom tool or MCP server that calls a service beyond the boundary, and authenticate inbound users at your gateway rather than in the agent. Two gateway caveats: it must forward the anthropic-beta header, or you get API Error: 400 ... Extra inputs are not permitted ... context_management (workaround: CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1), and a TLS-inspecting proxy produces SELF_SIGNED_CERT_IN_CHAIN or UNABLE_TO_GET_ISSUER_CERT_LOCALLY, fixed by pointing NODE_EXTRA_CA_CERTS at the CA bundle. That error has not been retried since CLI v2.1.199, so it fails fast.

Serving several tenants from shared containers, the isolation set is: settingSources: [], CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, a per-tenant CLAUDE_CONFIG_DIR (optionally with CLAUDE_CODE_PROJECT_DIR_NAME), a per-tenant cwd on every call, strictMcpConfig: true, and per-tenant egress rules at the proxy. Managed settings and ~/.claude.json are always read, so do not rely on default options for isolation.

For images, build inside the target architecture. The TypeScript SDK ships the CLI as per-platform optional dependencies, so npm ci --omit=optional produces Native CLI binary for <platform>-<arch> not found. Python has wheels for macOS 11+ and manylinux_2_17, but no musllinux wheel, so on Alpine you get the source distribution with no bundled CLI and must install Claude Code natively (curl -fsSL https://claude.ai/install.sh | bash), then let the SDK find it on PATH or point cli_path at it. A mismatched architecture or a lost execute bit shows up as Failed to start Claude Code: <os error>. And if you depend on a native install, verify claude --version in the same environment as the service, because service managers routinely have a different PATH from your shell.

Debugging beyond the stack trace

Most failures at this level are diagnosable from four places, in this order.

The init message. It names the registered tools, every MCP server's status, the model and apiKeySource. "The model won't use my tool" and "it ignored my restriction" are usually answered here in one line. Remember that pending MCP status is not a failure, while failed and needs-auth mean missing environment, missing packages, a 30-second MCP_TIMEOUT or a network block.

Standard error. In Python, the generic ProcessError text Command failed with exit code 1 (exit code: 1) with Error output: Check stderr output for details is a fixed string, not the real stderr — that only reaches you through a stderr= callback, so set one in every long-running service (debug_stderr is ignored). TypeScript throws Claude Code process exited with code 1. stderr: <tail> or Claude Code process terminated by signal <name> as plain errors, so wrap the for await in try/catch and set the stderr option; debug and debugFile exist too.

The result message's error fields. An error result raises ResultError in Python, a subclass of ProcessError with structured fields, so except ResultError must come before except ProcessError. Read terminal_reason, subtype, errors and api_error_status. The API-level messages differ in meaning: 429 is your own rate limit (fan out less), Repeated 529 Overloaded errors is API capacity and does not count against your quota (retry, or set fallbackModel, a comma-separated chain that in TypeScript must not equal model), 500 is server-side, and Credit balance is too low means Console credits are exhausted.

The transcript. The JSONL under ~/.claude/projects/ is the ground truth for what the model actually saw. When behaviour drifts in a long session, look for the compact_boundary and read what survived the summary; that is usually the explanation. getSessionMessages / get_session_messages saves you parsing it by hand.

A handful of specific messages map to specific mistakes. Model "Sonnet5" is not a recognized model id. Did you mean 'claude-sonnet-5'? means a display name reached setModel — use an alias or a model ID, and note that a nonexistent model reports error: 'model_not_found' on the result. No file checkpoint found for this message means checkpointing was missing on one of the two sessions. Stream closed on follow-up turns with background subagents was fixed in Python 0.2.160 and TypeScript 0.3.284. On Windows, Refusing to execute batch script 'C:\...\npm\claude.cmd' is deliberate: since Python 0.2.124 the SDK refuses to spawn .bat or .cmd CLIs as a defence against the BatBadBut class of bug (CVE-2024-27980), so point at claude.exe or install natively. Watch the Python Windows wheel gap too: 0.2.160 through 0.2.162 publish no win_amd64 wheel, so pip install claude-agent-sdk resolves to the sdist with no bundled CLI; install Claude Code natively or pin claude-agent-sdk==0.2.159.

Putting it all together

Here is a review agent with every mid-level mechanism in it: an explicit tool set, a hook that cannot be argued with, a custom tool for internal data, structured output so the result is machine-readable, bounded turns and spend, telemetry, and error handling that distinguishes the failure modes.

import asyncio, logging
from claude_agent_sdk import (
    ClaudeSDKClient, ClaudeAgentOptions, HookMatcher, ResultMessage,
    ResultError, ProcessError, tool, create_sdk_mcp_server,
)

log = logging.getLogger("review-agent")

@tool("owning_team", "Find the team that owns a path in this repo", {"path": str})
async def owning_team(args):
    team = codeowners.lookup(args["path"])
    if not team:
        return {"content": [{"type": "text", "text": "no owner"}], "is_error": True}
    return {"content": [{"type": "text", "text": team}]}

async def block_sensitive_paths(input_data, tool_use_id, context):
    path = input_data["tool_input"].get("file_path", "")
    if "/secrets/" in path or path.endswith((".env", ".pem")):
        return {"hookSpecificOutput": {
            "hookEventName": input_data["hook_event_name"],
            "permissionDecision": "deny",
            "permissionDecisionReason": "sensitive path",
        }}
    return {}

SCHEMA = {
    "type": "object",
    "properties": {
        "verdict": {"type": "string", "enum": ["approve", "changes_requested"]},
        "findings": {"type": "array", "items": {"type": "object", "properties": {
            "file": {"type": "string"}, "line": {"type": "integer"},
            "issue": {"type": "string"}, "owner": {"type": "string"},
        }, "required": ["file", "issue"]}},
    },
    "required": ["verdict", "findings"],
}

def build_options(repo: str) -> ClaudeAgentOptions:
    return ClaudeAgentOptions(
        cwd=repo,
        system_prompt={"type": "preset", "preset": "claude_code", "append":
                       "Review for correctness only. Do not edit files."},
        tools=["Read", "Glob", "Grep", "Agent"],
        allowed_tools=["Read", "Glob", "Grep", "mcp__repo__owning_team"],
        permission_mode="dontAsk",
        setting_sources=[],
        strict_mcp_config=True,
        mcp_servers={"repo": create_sdk_mcp_server(
            name="repo", version="1.0.0", tools=[owning_team])},
        hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit",
                                          hooks=[block_sensitive_paths],
                                          timeout=10)]},
        agents={"history": {
            "description": "Summarises a file's recent change history",
            "prompt": "Use git log to summarise recent changes. Report findings only.",
            "tools": ["Bash", "Read"], "model": "haiku", "maxTurns": 10,
        }},
        output_format={"type": "json_schema", "schema": SCHEMA},
        max_turns=30,
        max_budget_usd=2.0,
        effort="medium",
        stderr=lambda line: log.warning("cli: %s", line),
        env={"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
             "OTEL_METRICS_EXPORTER": "otlp",
             "OTEL_TRACES_EXPORTER": "otlp",
             "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
             "OTEL_EXPORTER_OTLP_ENDPOINT": "http://otel-collector:4318",
             "OTEL_SERVICE_NAME": "review-agent",
             "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1"},
    )

async def review(repo: str, diff: str) -> dict:
    async with ClaudeSDKClient(options=build_options(repo)) as client:
        await client.query(f"Review this diff:\n\n{diff}")
        try:
            async for msg in client.receive_response():
                if isinstance(msg, ResultMessage):
                    if msg.terminal_reason not in (None, "success"):
                        raise RuntimeError(f"terminated: {msg.terminal_reason}")
                    if msg.subtype != "success" or msg.structured_output is None:
                        raise RuntimeError(f"no structured result: {msg.subtype}")
                    log.info("session=%s turns=%s cost=%s",
                             msg.session_id, msg.num_turns, msg.total_cost_usd)
                    return msg.structured_output
        except ResultError as e:          # must precede ProcessError
            log.error("error result: %s", e); raise
        except ProcessError as e:
            log.error("process failed: %s", e); raise
    raise RuntimeError("stream ended with no result")

Read that configuration as a set of decisions rather than boilerplate. tools fixes what exists while allowed_tools fixes what runs without asking, and dontAsk makes anything else fail closed instead of hanging in a job with no human attached. setting_sources=[] and strict_mcp_config=True mean the behaviour does not change because someone's checkout has a .claude/ directory or a local connector. The hook, not can_use_tool, is the gate on sensitive paths, because the hook always fires. The subagent keeps git log output out of the parent's context and runs on a cheaper model. The schema makes the result something your pull-request bot can act on, and the null check treats an unsatisfiable schema as the failure it is. max_turns and max_budget_usd bound the blast radius, and the stderr callback is the only way the CLI's real complaint reaches your logs.

To take it further: wrap it in a FastAPI endpoint, run it on Kubernetes with consistent hashing on session_id, send the OTLP stream to Langfuse or Grafana, front it with LiteLLM so the key never enters the pod, and if you are composing several agents, compare this harness against LangGraph and the OpenAI Agents SDK first.

Where you are now

You can predict what the subprocess does, read the message stream correctly, tell tools from allowedTools from disallowedTools, resume and fork sessions without double-counting cost, drive a live session's control surface, add tools and MCP servers that actually get called, reason about the permission pipeline in order, place a gate that cannot be bypassed, isolate context with subagents, bound spend, get telemetry out of the CLI, test the parts you own, and deploy the thing where other people's work depends on it.

Senior takes every one of these further, with a security, scale and ownership dimension. The threat model in full, and what prompt injection can actually reach. Isolation from weakest to strongest: sandbox-runtime, hardened Docker, gVisor, Firecracker microVMs, and what each costs in latency. Egress architecture with credential injection. Multi-tenancy you can defend in an audit. Which component breaks first under load. Cost governance, spawnClaudeCodeProcess for running the CLI elsewhere, session-store adapters you own, upgrade discipline across a surface that changes daily, and the incident playbook for an agent that did something nobody authorised.

Sources

• Agent SDK overview
• Migration guide
• Configuration reference
• The agent loop
• Sessions
• Session storage
• Streaming vs single mode
• Structured outputs
• Custom tools
• MCP
• Permissions
• Hooks
• Subagents
• Skills
• Modifying system prompts
• File checkpointing
• Cost tracking
• Observability
• Hosting
• Secure deployment
• Troubleshooting
• TypeScript reference
• Python reference
• Environment variables
• TypeScript SDK changelog
• Python SDK changelog

At this level, interviewers stop asking what the Claude Agent SDK is and start asking what you would do when it misbehaves. The questions below are the ones that actually get asked for roles that run agents in production: scenarios, trade-offs, and a few where the interesting part is what a weak answer leaves out. Versions assumed throughout: TypeScript SDK 0.3.285, Python SDK 0.2.162, both bundling Claude Code CLI 2.1.285.

The thirty-second framing

"The Agent SDK runs Claude Code as a subprocess and exposes its agent loop as a library: built-in tools, a permission engine, sessions, hooks, subagents, MCP and skills, all driven from your code. One session is one claude process with state on local disk, so my job as an engineer is mostly about what I let that process do, how I bound it, and how I observe it."

That framing earns you the follow-ups, because it names the subprocess model up front. Most weak answers describe it as "a wrapper around the Claude API", which is wrong in a way that invalidates everything downstream: you cannot reason about working directories, local transcripts, environment variables or memory growth if you think you are making HTTP calls.

Scenario: the agent runs fine locally and fails in the container

A strong answer works through the environment in a fixed order, because almost all of these failures are environmental rather than behavioural.

First, did the CLI binary make it into the image? The TypeScript SDK ships the CLI as per-platform optional dependencies, so a npm ci --omit=optional in the Dockerfile produces Native CLI binary for <platform>-<arch> not found. Python has wheels for macOS and manylinux but no musllinux wheel, so an Alpine base gets the source distribution with no bundled binary and you see Claude Code not found at: …. The fix is to build inside the target architecture, or install Claude Code natively and point cli_path at it.

Second, is the key in the subprocess's environment? In TypeScript, env replaces process.env, so env: { LOG_LEVEL: "debug" } silently removes ANTHROPIC_API_KEY and you get Not logged in · Please run /login. Spread it: env: { ...process.env, … }. In Python it merges. And the SDK does not read .env files, so a container that worked locally because of dotenv will fail without it.

Third, is the error actually reaching you? In Python the generic ProcessError message Command failed with exit code 1 with Error output: Check stderr output for details is a fixed string, not the real stderr. Pass a stderr= callback and you usually get the answer in one line.

Fourth, read the init message, which reports the tools registered, every MCP server's status and apiKeySource. If apiKeySource is none, you have an auth problem; if an MCP server is failed or needs-auth, you have a config problem; if it is pending, that is not a failure at all.

A weak answer goes straight to "add retries" or "increase the timeout". A strong one establishes whether the process even started before touching anything model-related.

Scenario: the agent is slow and nobody knows where the time goes

The useful first move is to separate the three places time hides: model latency, tool execution, and waiting for a human.

Turn on telemetry — CLAUDE_CODE_ENABLE_TELEMETRY=1, the OTLP exporters, and CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 for traces — and read the span tree. claude_code.interaction is the root, with claude_code.llm_request and claude_code.tool beneath it, and the tool span carries both tool.blocked_on_user and tool.execution. That distinction is the whole answer in many cases: an "agent" that takes four minutes is often a tool waiting on an approval nobody was there to give. Subagent spans nest under the parent's tool span, so a fan-out is visible as a tree rather than a mystery gap.

Two gotchas worth naming, because they show you have actually done this. The default export intervals are 60 seconds for metrics and 5 for traces and logs, so a short run exits before the first flush and you conclude telemetry is broken. And you must never use the console exporter, because standard output is the SDK's own message channel.

Once you can see it, the levers are ordinary: effort: "low" for mechanical work, cheaper models for subagents, fewer turns through a tighter prompt, and tool search so dozens of MCP schemas are not loaded up front. If the latency is in your own custom tools, that is a normal profiling problem in your own process.

Scenario: the model ignored your tool restriction

This is the question that separates people who have read the permission docs from people who have guessed. The expected answer names the distinction: allowedTools is an auto-approve list, not a restriction. It says which calls skip the prompt; it does not change which tools exist. The restriction options are tools, which defines the base set that exists, and disallowedTools, where a bare name removes the tool from context entirely and a scoped rule like Bash(rm *) denies matching calls in every mode.

The second half of a strong answer is the evaluation order — hooks, deny rules, ask rules, permission mode, allow rules, then canUseTool — and what follows from it. Because canUseTool is last, it fires only when the flow falls through to a prompt. Pair it with bypassPermissions or with bare allowedTools entries and it never runs for those tools; TypeScript warns with CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. If you need a gate that always fires, it has to be a PreToolUse hook.

The third half, which almost nobody offers unprompted: bypassPermissions is not constrained by allowedTools at all, and subagents inherit it from the parent. So one permissive parent opens the whole tree, and narrowing it means disallowedTools or hooks.

Scenario: an MCP tool is in the list and never gets called

Expected answer: it was never pre-approved, so the permission flow denies it. Add mcp__server__tool, or mcp__server__* for the whole server, remembering that tool names are fully qualified as mcp__{server_key}__{tool_name} where the key is the one you used in mcpServers. Unanchored globs such as * or mcp__* in an allow rule are ignored with a warning, though deny rules accept them.

A good follow-up to volunteer: since TypeScript 0.3.142, MCP servers connect in the background by default, so a session starts immediately and a slow server reports status: "pending" in init. Treating pending as a failure is a common monitoring bug. If a particular server is genuinely required before the first turn, set alwaysLoad: true on it or MCP_CONNECTION_NONBLOCKING=0 to restore blocking startup.

Scenario: a long session starts ignoring its instructions

The mechanism to name is compaction. Near the context limit, older history is summarised and a compact_boundary system message is emitted — and whatever was only in your opening prompt can be summarised away. The fix is structural: put durable rules in CLAUDE.md, which is re-injected on every request, rather than in the first message. You can also compact deliberately with a /compact prompt before a long final step, and record pre-compaction state with a PreCompact hook so the next incident is debuggable.

The second half: if the session is drowning in tool output rather than history, move the heavy reading into a subagent. A subagent gets a fresh context; only the Agent tool's prompt string goes in, and only its final response comes back. That is the correct tool for "read forty files and tell me one thing".

Scenario: the cost dashboard does not match the invoice

The expected answer is blunt: total_cost_usd and costUSD are client-side estimates from a bundled price table, with a ×1.1 multiplier applied for inference_geo: "us" data residency. They are for guardrails, not billing. Bill from the Usage and Cost API or the Console.

Then the accounting details, which is where strong candidates separate themselves. usage covers the main loop only and excludes subagents, while total_cost_usd and model_usage include them — so a dashboard built on usage under-reports every fan-out. Deduplicate per-step usage by message ID, and read output tokens from the result, because per-step output_tokens is a placeholder. And since CLI 2.1.277, a resumed or forked session's totals continue from earlier turns rather than restarting at zero, so you read the latest result instead of summing across resumes. Summing is how you get a dashboard that is wrong by exactly the amount of your resume traffic.

Trade-off: streaming input or a single prompt

Single-message input is one-shot: no image attachments, no queueing, no real interrupts. It suits stateless environments — a Lambda, a queue worker, a CI step — and it is the simpler thing to operate.

Streaming input, where you pass an AsyncIterable, is what the docs recommend and what anything interactive needs: a long-lived session, messages queued while a turn runs, interrupts, and mid-session setModel and setPermissionMode. The cost is that you now own a long-lived process, and memory grows with session length, so you need recycling and a plan for what happens when the container moves.

A strong answer picks per workload rather than globally, and names the trap: if your prompt generator throws, TypeScript reports Claude Code process aborted by user, which sends people hunting for a cancellation that never happened, while Python logs it at debug level and the session hangs. Wrap the generator body in its own error handling.

Trade-off: how do you bound an agent you cannot supervise?

The layered answer, strongest first. tools for what exists. allowedTools plus permissionMode: "dontAsk" so anything unapproved is denied rather than hanging. A PreToolUse hook for the gates that must not be bypassed, since hooks run first and cost no tokens. maxTurns for rounds and maxBudgetUsd for spend — both off by default, and note that maxTurns: 0 means unlimited while maxBudgetUsd: 0 is rejected at startup. settingSources: [] and strictMcpConfig: true so the behaviour does not change because someone's checkout has a .claude/ directory. And verbatimPrompts when you interpolate untrusted text, which skips @path expansion and slash-command dispatch.

What a weak answer misses: that the Bash permission gate parses commands into an AST and matches rules, but is a permission gate, not a sandbox. It constrains which commands are approved, not what an approved command can reach. Real isolation is a container, sandbox-runtime, gVisor or a microVM. Saying "we allowlist bash commands, so we're sandboxed" is the single most quotable wrong answer in this space.

Trade-off: Agent SDK, client SDK, or Managed Agents?

Use the client SDK (anthropic / @anthropic-ai/sdk) when you want a tight, auditable loop you wrote yourself: a classifier, an extraction pipeline, anything where the agent loop is three lines and you want no surprises. Use the Agent SDK when you want Claude Code's whole harness — file tools, bash, permissions, skills, subagents, compaction — running on your infrastructure. Use Managed Agents when you would rather Anthropic hosted the loop and the sandbox.

The honest cost of the Agent SDK, and the thing to say out loud: you inherit a subprocess with local state and a release cadence of roughly daily. The SDK version pins the CLI binary, so upgrading the SDK is how you upgrade the CLI, and the 0.2 to 0.3 minor bump removed the entire V2 session API. That is a real operational commitment, and "we pin the SDK, take patches continuously, and read the changelog before a minor" is the answer that shows you understand it.

Trade-off: session affinity or a session store?

A session's transcript is JSONL on one host's disk, under ~/.claude/projects/<encoded-cwd>/. So either you pin sessions to hosts — a load balancer doing consistent hashing on sessionId — or you mirror transcripts to shared storage with a SessionStore and treat containers as interchangeable.

Affinity is simpler and gives up graceful failover: lose the host, lose the session. A store buys portability at the cost of an adapter you must operate — and candidates who have actually done it mention three things. It is a mirror, a dual write, not a replacement for local disk. Mirror writes are best-effort, so a failed batch is dropped and the only signal is a mirror_error message, which you should alert on. And there is a conformance suite, claude_agent_sdk.testing.run_session_store_conformance, which you run against your adapter before trusting it.

The point to close on either way: resuming restores the conversation, not the filesystem. If the agent edited twelve files and the container was replaced, those edits are gone. File restoration is a separate feature — enableFileCheckpointing plus rewindFiles(userMessageId) — and it must be enabled on both the original and the resumed session.

Scenario: how would you test this?

The expected shape is "test what you own, assert on behaviour, not wording".

Custom tools are ordinary functions: call the handler with an args dict and assert on the content and is_error. Hooks are ordinary functions too, and a table of paths against expected permissionDecision values is a genuinely good test. Permission policy is a matrix — though remember that if production has the tool in allowedTools, canUseTool never runs there, so test what production actually uses.

For the loop itself, assert on the message stream: did it call Edit at all, did it ever attempt a denied path, did it finish inside maxTurns, did the result come back success with a non-null structured_output. Structured output is the lever that turns a prose assertion into a field check: set output_format to a JSON schema, then require both subtype == "success" and a non-null payload, because an unsatisfiable schema yields a success result with nothing in it.

And keep one small smoke test that runs the real thing in CI against a fixture repository with settingSources: [], strictMcpConfig: true, dontAsk and a maxBudgetUsd, so a runaway loop cannot cost real money.

The question behind the questions

Across all of these, interviewers are checking one thing: do you treat the agent as a process you operate, or as a magic box you prompt? The answers that land name a mechanism and a consequence in the same breath — "canUseTool is last, so it cannot see auto-approved calls, so the gate has to be a hook" — and they volunteer the failure mode before being asked for it.

Sixty-second self-test

Answer out loud, in one sentence each:

1. Why does env behave differently in the two SDKs, and what does that break?
2. Which result field do you check before subtype, and why?
3. What does allowedTools not do?
4. What happens if you omit settingSources?
5. Why might canUseTool never fire, and what do you use instead?
6. What does a resumed session fail to restore?
7. Which usage field excludes subagents?
8. Why must you never bill a customer from total_cost_usd?
9. Which OpenTelemetry exporter breaks the SDK, and why?
10. Is the Bash permission gate a sandbox?

If any of those took longer than a sentence, that is the section of the detailed guide to reread.

These are the mistakes that cost mid-level teams real time with the Claude Agent SDK, the practices that pay back most, and a set of recipes you can lift into a service. Written against TypeScript SDK 0.3.285 and Python SDK 0.2.162, both bundling Claude Code CLI 2.1.285.

The errors that actually happen at this level

env in TypeScript wipes your API key

Symptom: the agent works locally, then Not logged in · Please run /login or Invalid API key the moment you add one environment variable.

Cause: in TypeScript, env replaces process.env for the subprocess. In Python it merges. This asymmetry is the most frequently hit bug in the whole SDK.

Fix: always spread. env: { ...process.env, API_TIMEOUT_MS: "120000" }. Make it a lint rule if you can: any env: literal in your codebase that does not begin with a spread is a bug waiting for a deploy.

Treating allowedTools as a restriction

Symptom: "we restricted it to Read and Glob, and it ran a bash command."

Cause: allowedTools is an auto-approve list. It never changes which tools exist.

Fix: use tools for the base set that exists (["Read", "Glob", "Grep"] for a read-only analyst, [] for no built-ins), and disallowedTools to remove a tool from context by bare name or deny a pattern like Bash(rm *) in every mode. Keep allowedTools for what you are happy to run unattended.

A canUseTool callback that never fires

Symptom: your approval callback logs nothing, and calls sail through.

Cause: permissions evaluate in a fixed order — hooks, deny rules, ask rules, permission mode, allow rules, canUseTool — and the callback is last. It only fires when the flow falls through to a prompt. With bypassPermissions or bare allowedTools entries, it is shadowed; TypeScript warns with CLAUDE_SDK_CAN_USE_TOOL_SHADOWED.

Fix: if the gate must always fire, make it a PreToolUse hook. Hooks run first, cost no tokens, and the model cannot route around them.

Reading subtype and missing the API error

Symptom: a successful result with empty or nonsense output, and no error anywhere in your logs.

Cause: when the final request fails with an API error, Claude Code reports subtype: "success" with terminal_reason: "api_error".

Fix: check terminal_reason before subtype, then check subtype == "success" before reading result — the text field only exists on success. The other subtypes are error_max_turns, error_max_budget_usd, error_during_execution and error_max_structured_output_retries.

MCP tools that are visible and never called

Symptom: the server is connected in init, the tools appear, and the model's attempts go nowhere.

Cause: nothing pre-approved them, so the permission flow denies them.

Fix: add mcp__server__tool or mcp__server__* to allowedTools. Names are fully qualified as mcp__{server_key}__{tool_name}, so renaming the key in mcpServers breaks every rule that referenced it. Note that unanchored * or mcp__* in an allow rule is ignored with a warning, while deny rules accept those globs.

Alerting on pending MCP servers

Symptom: a flood of pages after upgrading past TypeScript 0.3.142.

Cause: MCP servers now connect in the background by default, so sessions start immediately and slow servers report status: "pending" in init. That is not a failure.

Fix: alert on failed and needs-auth, not pending. If a server genuinely must be up before the first turn, set alwaysLoad: true on it, or MCP_CONNECTION_NONBLOCKING=0 to restore blocking startup.

The console OTLP exporter

Symptom: enabling telemetry corrupts the session in ways that look like a protocol bug.

Cause: standard output is the SDK's message channel, and a console exporter writes into it.

Fix: always otlp. And because export failures are otherwise silent, set CLAUDE_CODE_OTEL_DIAG_STDERR=1 while wiring it up.

Billing from total_cost_usd

Symptom: finance finds a discrepancy, usually on the fan-out-heavy workloads.

Cause: total_cost_usd and costUSD are client-side estimates from a bundled price table, with ×1.1 applied for inference_geo: "us" data residency. Separately, usage covers the main loop only and excludes subagents, while total_cost_usd and model_usage include them.

Fix: use these fields for guardrails, and bill from the Usage and Cost API or the Console. Deduplicate per-step usage by message ID, read output tokens from the result rather than per step, and do not sum across resumes — since CLI 2.1.277 a resumed session's totals continue from earlier turns.

Expecting a resumed session to restore files

Symptom: "we resumed it and all the edits are gone."

Cause: a session persists the conversation, not the filesystem.

Fix: enableFileCheckpointing plus rewindFiles(userMessageId), enabled on both the original and the resumed session. Resume with an empty prompt, then call rewind; calling it after the stream ends gives ProcessTransport is not ready for writing.

The error message that is not the error

Symptom: Command failed with exit code 1 (exit code: 1) and Error output: Check stderr output for details.

Cause: that second string is fixed text, not your subprocess's stderr.

Fix: pass a stderr= callback (Python; debug_stderr is ignored) or the stderr option plus debug/debugFile (TypeScript). In Python, remember that except ResultError must come before except ProcessError, since ResultError is a subclass.

Container images without the CLI

Symptom: Native CLI binary for <platform>-<arch> not found, or Claude Code not found at: ….

Cause: npm ci --omit=optional skips the per-platform CLI packages; Python has no musllinux wheel, so Alpine gets the source distribution with no binary. Python 0.2.160–0.2.162 also publish no win_amd64 wheel.

Fix: install with optional dependencies inside the target architecture; on Alpine or Windows install Claude Code natively and let the SDK find it on PATH or point cli_path at it. Never point at npm's claude.cmd — since Python 0.2.124 the SDK refuses batch shims as a CVE-2024-27980 defence. And verify claude --version in the service's environment, not your shell's.

Task tools and dedicated search quietly disappeared

Symptom: an agent that used to track its work in a task list stops doing so after a model change, or a hook that intercepted searches stops seeing any.

Cause: two default changes. TaskCreate, TaskGet, TaskUpdate, TaskList and the older TodoWrite are default tools only on Claude 3.x, Opus 4.0 to 4.7, Sonnet 4.0 to 4.6 and Haiku 4.5 — on Opus 4.8, Sonnet 5, Fable 5, Mythos 5 and newer they are off unless requested. Separately, native builds no longer register dedicated Grep and Glob tools, routing searches through embedded find and grep inside Bash instead.

Fix: name whichever you need in tools or allowedTools, or set CLAUDE_CODE_ENABLE_TODO_TOOLS=1. If you consume task state, accumulate tasks by ID rather than replacing a snapshot list each time, which is how the older TodoWrite worked.

A streaming generator that throws

Symptom: TypeScript reports Claude Code process aborted by user, often after a long minified line, and nobody cancelled anything. In Python, the session simply hangs with nothing in the logs.

Cause: your prompt generator raised. The SDK surfaces it as an abort in TypeScript and logs it at debug level in Python.

Fix: wrap the generator body in its own try/except and log there. This is worth doing before you have the bug, because the Python version of this failure is genuinely silent.

Wildcards in skills

Symptom: Invalid skill name, or a ValueError at connect, in code that worked on an older SDK.

Cause: skill names are now validated before the CLI starts. Parentheses, commas, control characters, wildcards such as * or :*, a leading slash and surrounding whitespace are all rejected.

Fix: replace skills=["*"] or ["plugin:*"] with skills="all". If instead a skill is simply not found, check that settingSources includes user or project and that cwd sits inside the repository holding .claude/skills/.

The practices that pay off, in order of leverage

1. Make tools, allowedTools and permissionMode an explicit, reviewed triple. Every headless agent should be tools for what exists, allowedTools for what runs unattended, and dontAsk so anything else fails closed instead of hanging. This one decision prevents more incidents than everything below it combined.

2. Put the non-negotiable gates in PreToolUse hooks. Sensitive paths, destructive commands, anything a compliance reviewer would ask about. Hooks run before every other step, run outside the model's context so they cost no tokens, and cannot be argued with. Keep them fast and local: a hook that times out is discarded and the session continues, which is the right default for availability and the wrong one for a gate.

3. Isolate the session from the host. settingSources: [] and strictMcpConfig: true mean your service behaves the same on a laptop, in CI, and in production. Without them, a developer's .claude/settings.local.json, a CLAUDE.md in a parent directory, or a claude.ai connector can change what your agent does. Managed settings and ~/.claude.json are read regardless, so this is isolation of the ordinary layers, not a vacuum.

4. Set both budget caps, every time. maxTurns for rounds, maxBudgetUsd for spend including subagents. Both are off by default, which is how a retry loop becomes a four-figure invoice. Note maxTurns: 0 means unlimited, and maxBudgetUsd: 0 is rejected at startup.

5. Turn on telemetry before you need it. CLAUDE_CODE_ENABLE_TELEMETRY=1, OTLP exporters, CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1, and lower the intervals from 60 s (metrics) and 5 s (traces and logs) for short-lived runs. The claude_code.tool span's split between tool.blocked_on_user and tool.execution answers "why is it slow" faster than any amount of logging you will write yourself.

6. Use structured output wherever a machine consumes the answer. A JSON schema turns an unpredictable paragraph into a field check, and makes your tests stable. Require both subtype == "success" and a non-null structured_output.

7. Push context-heavy work into subagents on cheaper models. A subagent gets a fresh context, takes only the Agent tool's prompt string in, and returns only its final response. Set model: "haiku" and a maxTurns on the definition. This is simultaneously a context fix and a cost fix.

8. Keep the API key out of the agent. Point ANTHROPIC_BASE_URL at a gateway that injects it — LiteLLM, Envoy, mitmproxy or Squid — so a prompt injection cannot exfiltrate a credential that is not in the process. Keep tool credentials behind a custom tool or MCP server that calls a service beyond the boundary.

9. Put durable rules in CLAUDE.md, not the opening prompt. CLAUDE.md is re-injected on every request and survives compaction. Anything stated only in the first message can be summarised away in a long session.

10. Pin the SDK and read the changelog before a minor. The release cadence is roughly daily, the SDK version pins the CLI binary, and the 0.2 to 0.3 bump removed the whole V2 session API. Take patches continuously; treat minors as a change. The specific things to watch on an upgrade are the Message union widening, which breaks exhaustive match or switch statements; env semantics; tool-surface defaults such as the Task tools and dedicated search; and MCP non-blocking startup.

11. Recycle long-lived subprocesses on a measured threshold. Memory grows with session length and there is no top-level session timeout, so a container that holds sessions indefinitely will eventually be killed rather than degrade. Measure your own per-session peak RSS, derive a turn or age limit from it, and start from the documented floor of 1 GiB RAM, 5 GiB disk and 1 CPU per agent.

Practice cards

Card 1 — the shadowed callback. Run an agent with allowedTools: ["Bash"] and a canUseTool that logs every call. Observe silence. Replace with a PreToolUse hook and watch every call appear. You have internalised it when you can predict which of the two fires for a given config without running it.

Card 2 — the unapproved tool. Add a custom tool via create_sdk_mcp_server, leave it out of allowed_tools, watch it be denied, then add the fully qualified mcp__server__tool name. You have it when "visible but never called" is instantly a permissions thought, not a schema thought.

Card 3 — the compaction boundary. Run a session long enough to compact. Find the compact_boundary message, then check whether a rule from your opening prompt is still being obeyed. Move it to CLAUDE.md and repeat. You have it when you can explain drift in a long session without guessing.

Card 4 — the cost ledger. Run a task that fans out to subagents. Compare usage against model_usage and total_cost_usd. Resume the session and confirm the totals continued rather than resetting. You have it when you can say which field a dashboard should read and why.

Card 5 — the recycle threshold. Containerise one agent at a 1 GiB request, run a long streaming session, and watch RSS. Find the turn count at which memory doubles. That number is your subprocess recycle policy; write it down.

Card 6 — the failure matrix. Deliberately break four things and record the exact message for each: a wrong cli_path, a missing MCP command, a maxTurns set one below the real requirement, and a maxBudgetUsd set just under the measured cost. You have it when you can go from message to cause without searching.

Operational recipes

Locked-down headless worker

options = ClaudeAgentOptions(
    cwd=workdir,
    tools=["Read", "Glob", "Grep", "Edit"],
    allowed_tools=["Read", "Glob", "Grep"],
    permission_mode="dontAsk",
    setting_sources=[],
    strict_mcp_config=True,
    verbatim_prompts=True,          # untrusted text in the prompt
    max_turns=20,
    max_budget_usd=1.50,
    stderr=lambda line: log.warning("cli: %s", line),
)

Edit exists but is not auto-approved, so every write falls through to your gate. dontAsk means a job with no human attached fails instead of hanging. verbatim_prompts skips @path expansion and slash-command dispatch for interpolated text.

A gate that cannot be bypassed

DENIED = ("/secrets/", "/.ssh/", "/.aws/")

async def gate(input_data, tool_use_id, context):
    path = input_data["tool_input"].get("file_path", "")
    if any(seg in path for seg in DENIED) or path.endswith((".env", ".pem")):
        return {"hookSpecificOutput": {
            "hookEventName": input_data["hook_event_name"],
            "permissionDecision": "deny",
            "permissionDecisionReason": "protected path",
        }}
    return {}

hooks = {"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[gate], timeout=10)]}

Matchers are regexes or exact strings on the tool name, and all matching hooks for an event fire concurrently — so never write two hooks for one event that assume an order.

Telemetry block to paste into every service

CLAUDE_CODE_ENABLE_TELEMETRY=1
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_SERVICE_NAME=review-agent
OTEL_METRIC_EXPORT_INTERVAL=10000
CLAUDE_CODE_OTEL_DIAG_STDERR=1

Content logging (OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS, OTEL_LOG_TOOL_CONTENT, OTEL_LOG_RAW_API_BODIES) is off by default. For teams in the Gulf and Egypt with data-residency commitments, leave it off unless you have decided deliberately where your collector ships prompts and tool output.

Multi-tenant isolation set

options = ClaudeAgentOptions(
    cwd=f"/srv/tenants/{tenant}/work",
    setting_sources=[],
    strict_mcp_config=True,
    env={**os.environ,
         "CLAUDE_CONFIG_DIR": f"/srv/tenants/{tenant}/claude",
         "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1"},
)

Plus per-tenant egress rules at your proxy. Do not rely on default options for isolation: managed settings and ~/.claude.json are always read, and in anything high-stakes consider one filesystem per tenant.

Bounding a fan-out

CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=8
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1
CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS=300000

Defaults are 20 concurrent and depth 3. Lower both when you share a key across services: a wide fan-out is the fastest route to API Error: Request rejected (429), which means "you fanned out too far" far more often than it means "raise the tier". There is no per-subagent wall-clock deadline, so pair these with maxTurns on each AgentDefinition.

Timeout and retry envelope

API_TIMEOUT_MS=600000
CLAUDE_CODE_MAX_RETRIES=4
CLAUDE_CODE_RETRY_WATCHDOG=1
MCP_TIMEOUT=45000
MAX_MCP_OUTPUT_TOKENS=25000

CLAUDE_CODE_MAX_RETRIES defaults to 10 and is capped at 15, so the worst case is roughly API_TIMEOUT_MS × (retries + 1) — do the multiplication against your own request deadline before accepting the defaults.

The checklist

Before an agent goes anywhere near production:

• tools, allowedTools and permissionMode are explicit and reviewed; dontAsk for anything unattended
• A PreToolUse hook guards every path and command you would not want to explain in an incident review
• settingSources: [] and strictMcpConfig: true
• maxTurns and maxBudgetUsd both set
• terminal_reason checked before subtype; subtype checked before reading result
• A stderr callback wired into your normal logger
• TypeScript env literals all begin with ...process.env
• Telemetry on, OTLP only, intervals lowered, content logging decided deliberately
• The API key injected at a gateway, not present in the agent's environment
• Session continuity settled: consistent hashing on sessionId, or a SessionStore with mirror_error alerting
• A measured per-session peak RSS, and a subprocess recycle threshold derived from it
• The SDK pinned, with a changelog read scheduled before any minor bump
• claude --version verified in the service's own environment if you rely on a native install

This is part three of three. Beginner and Mid were about getting an agent to do useful work. This level is about owning the SDK as a platform: other teams ship agents on top of what you run, and you are the person who answers for the bill, the blast radius and the 3 a.m. page.

The shift is sharper here than with most tools, because the Claude Agent SDK is not a library that runs inside your process. It spawns the Claude Code CLI as a child process, hands it a shell, a working directory and a filesystem, and lets a language model decide what to do with them. Everything in this part follows from that one sentence.

Where this picks up

The versions this part was verified against are TypeScript @anthropic-ai/claude-agent-sdk 0.3.285 and Python claude-agent-sdk 0.2.162, both released 2026-09-29, both bundling Claude Code CLI v2.1.285. The two packages are versioned independently and the TypeScript patch number tracks the bundled CLI; the Python one does not, so you read the Python changelog to learn which CLI you got.

I start with the architecture, because every security, cost and scaling decision below is a consequence of it.

The architecture you are actually operating

Mid-level taught you that query() returns an async iterator of messages. What it did not dwell on is where those messages come from. The SDK spawns one claude process per session and talks to it over stdio using newline-delimited JSON plus a control protocol layered on top. One session is one subprocess. That is the single most load-bearing fact in this guide.

Two consequences follow immediately, and a third is the division of labour: the subprocess never opens a socket, so the HTTP or WebSocket service that authenticates callers, maps them to tenants and streams messages back is yours to write.

State is local and perishable. The conversation lives as JSONL at ~/.claude/projects/<encoded-cwd>/<id>.jsonl, where the encoded cwd is the working directory with every non-alphanumeric character replaced by -. Set CLAUDE_CONFIG_DIR and it moves under that directory instead. Nothing about it survives a pod restart or a reschedule unless you arrange it. Worse, the session persists the conversation, not the filesystem: resume a session on a fresh container and Claude remembers editing utils.py while the file is back to its original content, which produces some of the most confusing agent behaviour you will ever debug.

Process lifetime is your lever. There is no top-level session timeout in the SDK. A session that nothing stops will sit there, and its memory footprint grows with the transcript. maxTurns and maxBudgetUsd are the only built-in stops, both off by default, and maxTurns: 0 means unlimited while maxBudgetUsd: 0 is rejected at startup rather than treated as zero budget.

In TypeScript you get real process-management primitives. startup({ options, initializeTimeoutMs }) returns a WarmQuery with the subprocess already spawned, which removes cold-start latency from the first user-visible request. prewarm() goes further and returns a SpareProcess you claim() later; it is alpha, each spare holds roughly 230 to 260 MB, and hooks, MCP servers and systemPrompt are fixed at prewarm time. spawnClaudeCodeProcess lets you replace the spawn entirely and run the CLI in a VM, a container or on a remote host.

import { startup, type WarmQuery } from "@anthropic-ai/claude-agent-sdk";

const warm = await startup({
  options: {
    model: "claude-sonnet-5",
    systemPrompt: { type: "preset", preset: "claude_code" },
    settingSources: [],
    maxTurns: 24,
    maxBudgetUsd: 2.5,
    env: { ...process.env, API_TIMEOUT_MS: "120000", CLAUDE_CODE_MAX_RETRIES: "4" },
  },
  initializeTimeoutMs: 60_000,
});

export function take(): WarmQuery {
  return warm;
}

Note env: { ...process.env, ... }. In TypeScript, options.env replaces the subprocess environment rather than extending it, a breaking change in 0.2.113 that silently removes ANTHROPIC_API_KEY and gives you Not logged in · Please run /login from a service that was working yesterday. Python merges env over the inherited environment instead. Platform owners write this spread into the shared wrapper so no team has to remember it.

Where it breaks first

Platform ownership is mostly knowing which thing gives way under pressure, in order. For the Agent SDK the order is unusually predictable, because the failures are not throughput failures. Nothing here is CPU-bound; the subprocess spends almost all its wall-clock time waiting on the API.

Memory goes first. The documented floor is 1 GiB RAM, 5 GiB disk and 1 CPU per agent, and it is explicitly a floor because memory grows with session length. The planning formula is blunt: agents per host equals host RAM minus overhead, divided by your measured per-session peak RSS. Measure it with your real prompts, your real MCP servers and your real transcript lengths, because a session that reads large files and fans out subagents behaves nothing like a quickstart. Then recycle subprocesses on a schedule, because the growth does not plateau.

Rate limits go second, and they go in a way that looks like a bug. Wide parallel subagent fan-outs are the usual trigger. The concurrency cap defaults to 20 (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS) and spawn depth defaults to 3 (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH; set it to 1 for no nesting at all). Twenty concurrent subagents, each able to spawn two more levels, is a lot of simultaneous API traffic from one session, and the symptom is API Error: Request rejected (429) · this may be a temporary capacity issue. Distinguish it from API Error: Repeated 529 Overloaded errors, which is capacity on Anthropic's side and does not count against your quota; 429 is yours to fix by lowering concurrency, batching fan-outs or raising the tier, while 529 wants a retry and a fallbackModel.

Disk goes third, quietly. Transcripts, working directories and spilled MCP output all accumulate: MAX_MCP_OUTPUT_TOKENS defaults to 25,000 tokens and larger output is written to a file rather than truncated. An agent container with no retention policy fills its volume in days.

Then the long tail of timeouts. These all ride on env, and the defaults assume an interactive human rather than a service with an SLO. API_TIMEOUT_MS defaults to 600000 and CLAUDE_CODE_MAX_RETRIES defaults to 10, capped at 15. Multiply them: worst-case wall clock is roughly API_TIMEOUT_MS × (retries + 1), well over an hour at the defaults. If your gateway times out at 60 seconds, that request is orphaned and still burning tokens.

import os

AGENT_ENV = {
    "API_TIMEOUT_MS": "120000",
    "CLAUDE_CODE_MAX_RETRIES": "4",
    "CLAUDE_CODE_RETRY_WATCHDOG": "1",
    "CLAUDE_ENABLE_STREAM_WATCHDOG": "1",
    "CLAUDE_STREAM_IDLE_TIMEOUT_MS": "300000",
    "CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS": "600000",
    "MCP_TIMEOUT": "30000",
    "MAX_MCP_OUTPUT_TOKENS": "25000",
    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "8",
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1",
}

CLAUDE_STREAM_IDLE_TIMEOUT_MS defaults to 300000 and that is also its minimum, so you cannot tighten it below five minutes; the watchdog exists to catch a stream that has gone silent, not to enforce a latency budget. CLAUDE_CODE_RETRY_WATCHDOG=1 is for unattended long waits, which describes every production agent.

Scaling: the component that gives way

Horizontal scaling is simple to state and easy to get wrong. Because a session's state is the local filesystem of one container, a session must return to the container that owns it. The documented approach is a load balancer doing consistent hashing on sessionId, which gives you session affinity without a shared store and degrades gracefully when the fleet changes size: a scaling event moves a fraction of sessions, not all of them.

That choice splits your deployment into three recognisable patterns, and picking the wrong one is the most expensive architecture mistake available here.

Ephemeral: one container per task. The task arrives, you start a container with the prompt in an environment variable and a maxTurns cap, it does the work, it exits, the volume goes away. No affinity, no session storage, no recycling policy. This is the correct default for batch work, CI jobs and anything triggered by a queue, and it is the cheapest to operate because every failure mode is "the pod died, retry it".

Long-running: many sessions per container. You keep a warm process and serve interactive traffic. TypeScript gives you streamInput() for queued messages on a live session, plus startup() and prewarm() to hide spawn latency; Python gives you ClaudeSDKClient as async with, which holds one session across multiple client.query() calls and exposes interrupt(), set_model(), set_permission_mode() and get_context_usage(). This pattern buys you interactivity and costs you affinity, memory discipline and a recycling story.

Hybrid: ephemeral containers plus a required SessionStore. This is where most platforms end up once a product wants conversation continuity but the platform wants stateless pods. The word "required" is doing real work in that sentence: without a store, an ephemeral container's transcript dies with it, and resume silently has nothing to resume from.

A fourth shape, the multi-agent container, gives several agents in one process a separate cwd and separate settings isolation each. It saves memory and concentrates risk; treat it as a tenancy design and read the multi-tenancy section first.

Session durability and the SessionStore

A SessionStore is an adapter you implement that mirrors transcripts to somewhere durable: S3, Redis, Postgres, anything you can append to. It has two required methods, append and load, plus optional listSessions, listSessionSummaries, delete and listSubkeys. You wire it with sessionStore / session_store, control write batching with sessionStoreFlush / session_store_flush ("batched" or "eager") and bound the read with loadTimeoutMs.

The critical property, and the one people miss, is that it is a mirror, not a replacement. The subprocess still writes to local disk; the store is a dual-write alongside it. That has two implications you must design around. First, local disk is still on the critical path, so a read-only filesystem or a full volume still breaks the session. Second, mirror writes are best-effort: a failed batch is dropped, and the SDK tells you by emitting a mirror_error message into the message stream. If you do not watch for that message, your durability guarantee quietly becomes a durability hope.

from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, ResultMessage

options = ClaudeAgentOptions(
    session_store=S3SessionStore(bucket="agents-transcripts", prefix="prod/"),
    session_store_flush="eager",
    setting_sources=[],
    env=AGENT_ENV,
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Summarise the failing tests in this repo.")
    async for msg in client.receive_response():
        if getattr(msg, "subtype", None) == "mirror_error":
            alert("session mirror write dropped", session=msg)
        if isinstance(msg, ResultMessage):
            record_result(msg)

"eager" flushing costs a round trip per append and narrows the window in which a pod loss loses turns; "batched" is cheaper and loses more. Pick per workload, not per platform: a long autonomous refactor can tolerate batched writes, an interactive assistant that users expect to resume cannot.

Reference adapters exist for S3, Redis and Postgres, and — this is the part to actually use — there is a conformance suite at claude_agent_sdk.testing.run_session_store_conformance. Run it against your adapter in CI. A store that passes conformance and fails in production is rare; a store that was never tested and corrupts transcripts on concurrent append is not. importSessionToStore / import_session_to_store migrates existing local sessions into a store, which is how you adopt one without abandoning in-flight conversations.

The trust model

The threat is not a hostile model. It is prompt injection and ordinary model error leading to actions you did not intend, performed with the credentials your container happens to hold. A web page the agent fetched, a GitHub issue it read, a file in the repo — any of them can contain text that reads as an instruction. Defence in depth is the only strategy that survives this, and the SDK's permission system is one layer of it rather than the answer.

Permissions evaluate in a fixed order, and the result is binary — allowed or denied:

1. hooks
2. deny rules
3. ask rules
4. permission mode
5. allow rules
6. the canUseTool callback

Read that list as a platform owner and two things jump out. Hooks are first, which makes them the only control a team's own options cannot route around. And canUseTool is last, which means it fires only when everything above it falls through to a prompt — never for an auto-approved call. That is the single most common security misunderstanding at this level: an engineer writes a careful canUseTool that audits every tool call, adds allowedTools: ["Bash"] for convenience, and the callback stops firing for Bash entirely. The SDK will even tell you, with warning code CLAUDE_SDK_CAN_USE_TOOL_SHADOWED in TypeScript and a runtime warning in Python, when canUseTool is combined with bypassPermissions or bare allowedTools entries. If you need to see every call, use a PreToolUse hook.

The modes matter as much as the order. default sends unapproved calls to canUseTool, and denies them if there is no callback. acceptEdits auto-approves edits and mkdir, touch, rm, rmdir, mv, cp and sed inside the cwd or additional directories. plan never auto-approves edits, and since 0.3.269 routes writes through canUseTool even when allowDangerouslySkipPermissions is set. dontAsk denies anything that would prompt and never calls canUseTool. auto lets a model classifier decide. bypassPermissions approves everything except explicit ask rules, deny rules, hooks, user-interaction tools and critical-path rm/rmdir; in TypeScript it also requires allowDangerouslySkipPermissions: true, and it refuses to run as root or under sudo outside a recognised sandbox on Linux and macOS.

For a headless platform agent the documented recommendation is dontAsk plus an explicit allowedTools list, and it is the right default to hand teams. It fails closed: anything you did not enumerate is denied rather than queued for a prompt that nobody will answer.

Hooks are where a platform encodes policy it will not negotiate. They run in your process, outside the model's context, so they cost no tokens, and they can deny a call, rewrite its input or inject context. Matchers are regexes or exact strings on the tool name. Two semantics to internalise: all matching hooks for an event fire concurrently, so they cannot depend on each other's ordering, and a hook that exceeds its timeout is discarded while the session continues. Timeouts are per matcher in seconds, defaulting to 600 for most events, 30 for UserPromptSubmit and the model-switch hooks, 10 for MessageDisplay, and about 1.5 seconds for SessionEnd — far too little for a network call, so your audit flush belongs in a background queue.

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

SECRET_PATHS = (".env", "id_rsa", "credentials", ".npmrc")

async def block_secret_reads(input_data, tool_use_id, context):
    path = input_data["tool_input"].get("file_path", "")
    if any(p in path for p in SECRET_PATHS):
        return {"hookSpecificOutput": {
            "hookEventName": input_data["hook_event_name"],
            "permissionDecision": "deny",
            "permissionDecisionReason": f"Platform policy: {path} is not readable by agents",
        }}
    audit_queue.put_nowait({"tool": input_data["tool_name"], "input": input_data["tool_input"]})
    return {}

options = ClaudeAgentOptions(
    permission_mode="dontAsk",
    allowed_tools=["Read", "Glob", "Grep", "mcp__tickets__search"],
    hooks={"PreToolUse": [HookMatcher(matcher="Read|Edit|Write|Bash", hooks=[block_secret_reads], timeout=10)]},
)

untrusted text you interpolate into a prompt yourself, turn on verbatimPrompts / verbatim_prompts (TS 0.3.280, Python 0.2.158, CLI 2.1.248 or later): it skips @path expansion and slash-command dispatch, so a user who types /compact or @~/.ssh/id_rsa into your text box gets a string rather than a command.

Isolation and the sandbox ladder

Permissions decide what the agent is asked to do. Isolation decides what it can do when the permission layer is wrong. You need both, and as a platform owner you need a documented ladder so teams can choose a rung instead of inventing one.

The SDK's own sandbox mode uses bubblewrap on Linux and Seatbelt (sandbox-exec) on macOS, configured through sandbox: SandboxSettings. The settings that matter for a platform are the network controls — allowedDomains, deniedDomains, allowManagedDomainsOnly — and failIfUnavailable. Since TS 0.2.91, sandbox: { enabled: true } defaults failIfUnavailable: true, so if the sandbox dependencies are missing query() emits an error result and exits rather than running unsandboxed. That default is correct and you should not change it; setting failIfUnavailable: false to "degrade gracefully" degrades straight through your security boundary.

Above that, the rungs in increasing strength:

Hardened Docker is where most platforms should live, and "hardened" is a specific list rather than a feeling: --cap-drop ALL, --security-opt no-new-privileges, a seccomp profile, --read-only with a tmpfs /tmp, --network none plus a Unix-socket proxy for egress, --memory 2g, --pids-limit 100, --user 1000:1000, and read-only mounts for anything the agent genuinely needs. The prohibition is as important as the list: never mount ~/.ssh, ~/.aws or ~/.config into an agent container. Those three mounts are how a prompt injection becomes a cloud incident.

The gVisor numbers deserve a second look before you adopt it. Two times slower on syscalls is survivable; ten to two hundred times slower on heavy file open and close is not, and an agent grepping a large repository does exactly that. For file-heavy workloads Firecracker is both stronger and faster than gVisor, which is counter-intuitive enough to be worth measuring.

Secrets and the egress proxy

The default secret posture is that the subprocess reads ANTHROPIC_API_KEY from its environment. That works, and it means the key is readable by any Bash command the agent runs, which is to say by anything that successfully injects a prompt. The SDK does not read .env files, by the way — if your team's local workflow depends on one, they load it themselves with dotenv and will be confused exactly once when the service does not.

The better posture is to set ANTHROPIC_BASE_URL to a proxy that injects the key, so the agent never holds it. LiteLLM, Envoy, mitmproxy and Squid are the documented options; see LiteLLM for the routing side. One requirement bites people: the proxy must forward the anthropic-beta header. A gateway that strips unknown headers produces API Error: 400 ... Extra inputs are not permitted ... context_management, which looks like an SDK bug. If you cannot fix the proxy, CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 is the escape hatch.

The same principle extends past the model key. Keep tool credentials outside the agent. An MCP server or custom tool that calls a service on the far side of your boundary, with the credential held by that service, is strictly safer than handing the agent a token and trusting the permission layer. Where you need the agent to make authenticated calls directly, a TLS-terminating proxy with its CA installed in the agent image lets the proxy attach credentials the agent never sees. And inbound: authenticate users at your gateway. The agent should not be validating user tokens, because an agent that can validate a token is an agent that can be talked into minting one.

Multi-tenancy

If several tenants share a container, the defaults are against you. Settings load from the filesystem, memory loads from CLAUDE.md, connectors load from the user's claude.ai account, and none of that is tenant-aware. The documented isolation set is short and you should treat every line as mandatory rather than advisory:

• settingSources: [] — omitting it loads user, project and local, exactly like the CLI: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, CLAUDE.md and .claude/ skills, agents and commands. Passing [] isolates. The 0.1.0 changelog claims "no filesystem settings by default", which is stale and has misled a lot of people.
• CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 — auto memory is read regardless of settingSources.
• A per-tenant CLAUDE_CONFIG_DIR, optionally with CLAUDE_CODE_PROJECT_DIR_NAME (TS 0.3.234 or later, Python 0.2.140 or later), so transcripts never share a directory.
• A per-tenant cwd on every call, not just the first.
• Per-tenant egress rules at the proxy.
• strictMcpConfig: true, so project .mcp.json, user settings, plugin servers and claude.ai connectors cannot leak in.

import { query } from "@anthropic-ai/claude-agent-sdk";

function tenantOptions(tenant: string) {
  return {
    cwd: `/workspaces/${tenant}`,
    settingSources: [] as const,
    strictMcpConfig: true,
    permissionMode: "dontAsk" as const,
    allowedTools: ["Read", "Glob", "Grep"],
    env: {
      ...process.env,
      CLAUDE_CONFIG_DIR: `/var/lib/agents/${tenant}`,
      CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
      OTEL_RESOURCE_ATTRIBUTES: `tenant.id=${encodeURIComponent(tenant)}`,
    },
  };
}

Then the sentence that should end any debate about whether this is enough: managed and server-managed settings and ~/.claude.json are always read, no matter what you pass. Managed policy sits at the top of the settings precedence chain — managed policy, then programmatic settings (the flag layer), then local, then project, then user — so a host-level policy you did not write can change behaviour inside a tenant's session. The documentation's own guidance is not to rely on default options for isolation, and to consider one filesystem per tenant. In practice that means: if your tenants are different customers rather than different teams inside one company, give each one its own container. The option set above is for soft multi-tenancy between teams you already trust; it is not a security boundary between strangers.

managedSettings in TypeScript lets the host supply policy-tier settings programmatically, which is the clean way for a platform to pin controls that tenant code cannot override. Combine it with toolAliases — for example { Bash: 'mcp__workspace__bash' } — and you can redirect a built-in tool to your own audited implementation without every team opting in.

Cost ownership

Token spend dominates infrastructure here by a wide margin: a container costs roughly $0.05 per hour, while one long session can cost dollars. That ratio reframes capacity planning — you are not optimising compute, you are optimising conversations.

The field everyone reaches for is the trap. total_cost_usd and costUSD are client-side estimates, computed from a bundled price table or from modelPricing. They are good enough for budget caps and dashboards and you must never bill customers from them. The billable truth lives in the Usage and Cost API and the Console. Publish that distinction loudly, because a team that builds chargeback on total_cost_usd will build it convincingly and be wrong by a margin nobody can reconcile later.

Know exactly what each field counts:

• usage covers the main loop only and excludes subagents.
• total_cost_usd and modelUsage / model_usage include subagents.
• Deduplicate per-step usage by message ID, because blocks from the same API response share one.
• Per-step output_tokens is a placeholder; read output tokens from the result.

Streaming mode adds its own arithmetic. Each turn emits a result, and total_cost_usd is the running total for that call rather than the delta — so you read the latest value, you do not sum them. The slash commands reset state: /clear, /reset and /new all reset totals and the budget, and /clear issues a new session_id. And since CLI 2.1.277, a resumed or forked session's total_cost_usd and modelUsage continue from earlier turns rather than starting at zero. Any accounting code written against the pre-2.1.277 behaviour now double-counts, which is a quiet and expensive upgrade hazard.

from claude_agent_sdk import ResultMessage

def record_result(msg: ResultMessage) -> None:
    if msg.total_cost_usd is None:          # Optional in Python: always check
        return
    emit_gauge("agent.cost_estimate_usd", msg.total_cost_usd,
               tags={"session": msg.session_id, "subtype": msg.subtype,
                     "terminal_reason": msg.terminal_reason})

The levers, roughly in order of return on effort: maxBudgetUsd as a hard stop, which covers subagent spend too; effort: "low" for tasks that need no deliberation, since effort runs low, medium, high, xhigh, max and most routine work does not need the top; smaller models for subagents via the fable, opus, sonnet, haiku and inherit aliases; tool search, to keep schemas out of context; and prompt caching through excludeDynamicSections: true on the preset, which moves per-user context out of the system prompt and so enables cache hits across users (TS 0.2.98 or later, Python 0.1.58 or later). That last one is the biggest single win available to a platform, because a platform is exactly where many users share a system prompt. One anti-lever: avoid mid-session model switches, since each model has its own cache.

Observability and incident playbooks

The division of labour is unusual and worth stating plainly: the CLI exports OpenTelemetry itself; the SDK only passes environment variables through. You do not instrument the agent from your code. You configure the subprocess and collect what it sends. See OpenTelemetry for the collector side and Langfuse if you want LLM-shaped traces on top.

CLAUDE_CODE_ENABLE_TELEMETRY=1
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_TRACES_EXPORTER=otlp
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.observability:4318
OTEL_SERVICE_NAME=agent-platform
OTEL_METRIC_EXPORT_INTERVAL=10000
CLAUDE_CODE_OTEL_DIAG_STDERR=1

Three configuration facts will save you an afternoon each. Never use the console exporter: stdout is the SDK's message channel, and an exporter writing to it corrupts the protocol — the symptom is a session that fails to parse its own messages, which looks nothing like a telemetry problem. Default export intervals are 60 seconds for metrics and 5 seconds for traces and logs, which means a 20-second agent run exports no metrics at all unless you lower the interval. And export failures are silent by default; CLAUDE_CODE_OTEL_DIAG_STDERR=1 is how you find out your collector endpoint is wrong.

The span tree mirrors the agent loop, which makes it readable: claude_code.interaction at the top, containing claude_code.llm_request, claude_code.tool (with tool.blocked_on_user and tool.execution as separate phases, so waiting-on-a-human is distinguishable from running) and claude_code.hook, where hook spans need detailed beta tracing. Subagent spans nest under the parent's tool span, so a fan-out is visible as a shape. Every span carries session.id, and the SDK auto-propagates W3C TRACEPARENT and TRACESTATE into the CLI and onward into Bash commands; Python needs the [otel] extra for that.

The SDK auto-propagates W3C TRACEPARENT and TRACESTATE into the CLI and onward into Bash commands, so a trace that starts at your gateway continues through the agent and into whatever scripts it runs. Python needs the [otel] extra for this (pip install "claude-agent-sdk[otel]").

For security monitoring, route tool_decision, tool_result, mcp_server_connection and permission_mode_changed to a SIEM. That last one deserves a hair-trigger alert: a permission mode changing mid-session is either deliberate or something you need to know about now. Tag everything with OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES, and percent-encode end-user and tenant IDs, because unencoded values break the attribute format. Content logging is off by default and opts in per category — OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS, OTEL_LOG_TOOL_CONTENT (truncated at 60 KB) and OTEL_LOG_RAW_API_BODIES — so treat it as a retention decision, not a debugging convenience.

Now the playbooks. These are the four pages I would pin in a runbook.

"The agent stopped mid-task." Read terminal_reason before subtype, because when the final request fails with an API error Claude Code reports subtype: "success" with terminal_reason: "api_error". A monitor that only checks subtype reports a healthy success rate through an outage. Then check subtype for error_max_turns, error_max_budget_usd, error_during_execution or error_max_structured_output_retries, and stop_reason for end_turn, max_tokens or refusal.

"Sessions die silently in Python." The classic cause is a prompt generator that throws. In TypeScript that surfaces as Claude Code process aborted by user, a genuinely misleading message; in Python a generator exception is logged at debug level and the session hangs. Related: Python's ProcessError text Error output: Check stderr output for details is a fixed string, not the real stderr, so always pass a stderr= callback (debug_stderr is ignored), and catch ResultError before ProcessError, since 0.2.140 made the former a subclass of the latter.

"MCP tools are visible but never called." They are not pre-approved, so the permission flow denies them. Add mcp__server__tool or mcp__server__* to allowedTools. Note that an unanchored * or bare mcp__* in an allow rule is ignored with a warning, though deny rules do accept those globs. Separately: status: "pending" in init is not a failure. Since TS 0.3.142 MCP servers connect in the background by default, so a slow server reports pending while the session proceeds. MCP_CONNECTION_NONBLOCKING=0 restores blocking (capped at 5 seconds by default), or set alwaysLoad: true on the server that must be ready.

"It worked in CI and not in the image." Almost always the native binary. TypeScript reports Native CLI binary for <platform>-<arch> not found when optional dependencies were skipped, usually by npm ci --omit=optional. Python reports Claude Code not found at: /your/configured/path as CLINotFoundError when the sdist shipped without a binary or the service PATH differs from yours. Check claude --version in the same environment as the service.

Upgrades and migrations

Pin the SDK. Because the bundled CLI binary is pinned to the SDK version, updating the SDK is how you update the CLI — there is no separate CLI upgrade to schedule, and no way to take a CLI fix without moving the SDK. Release cadence is roughly daily and most patch releases only bump the bundled CLI, so the documented advice is to take patches continuously and read the changelog before taking a minor.

Read that advice with the TypeScript 0.2 to 0.3 history in mind, because 0.3.142 is the cautionary tale. It removed the V2 session API outright — unstable_v2_createSession, unstable_v2_resumeSession, unstable_v2_prompt, SDKSession and SDKSessionOptions, deprecated since 0.2.133 — in favour of query() with an AsyncIterable<SDKUserMessage> for multi-turn, or options.resume. The same release made MCP servers connect in the background by default and replaced TodoWrite with the Task tools (TaskCreate, TaskUpdate, TaskGet, TaskList) in headless and SDK sessions, so consumers must accumulate task state by ID rather than replacing a snapshot list.

The upgrade hazards to put on a checklist, because each one has caught real teams:

• The Message union widens. ConversationResetMessage arrived in Python 0.2.137 and broke exhaustive matches. If you use assert_never or an exhaustive switch, a new message type is a compile error at best and a runtime crash at worst. Handle unknown types as a default branch.
• env semantics differ by language. TypeScript replaces, Python merges. Already covered, still the most common bug.
• Tool-surface defaults move. Task-tracking tools are default tools only on Claude 3.x, Opus 4.0 to 4.7, Sonnet 4.0 to 4.6 and Haiku 4.5. On Opus 4.8, Sonnet 5, Fable 5, Mythos 5 and newer, you must name TaskCreate, TaskGet, TaskUpdate, TaskList or TodoWrite in tools or allowedTools, or set CLAUDE_CODE_ENABLE_TODO_TOOLS=1. Similarly, since TS 0.3.162 native builds default to embedded find/grep inside Bash instead of registering dedicated Grep and Glob tools — so if your canUseTool or hooks intercept searches, you must name Grep and Glob explicitly to keep them interceptable. A model upgrade can therefore silently change which tools your guardrails can see.
• MCP non-blocking startup. Code that treated a non-connected status in init as fatal now fails on healthy slow servers.
• Packaging. Since TS 0.3.143, @anthropic-ai/sdk and @modelcontextprotocol/sdk are peerDependencies, with current peer ranges zod ^4.0.0, @anthropic-ai/sdk >=0.93.0 and @modelcontextprotocol/sdk ^1.29.0. Yarn classic users must add them explicitly. Python's mcp range widened to mcp>=1.23.0,<3.0.0 in 0.2.140.

The older rename still shows up in legacy code: at 0.1.0 claude_code_sdk became claude_agent_sdk, Python's ClaudeCodeOptions became ClaudeAgentOptions, and custom_system_prompt plus append_system_prompt merged into one system_prompt. The same release stopped using Claude Code's system prompt by default in favour of a minimal one, so systemPrompt: { type: "preset", preset: "claude_code" } restores the old behaviour — a migration where nothing errors and the agent simply becomes less capable, which is the hardest kind to notice.

Deprecated-but-accepted items to sweep out of your shared wrapper: maxThinkingTokens / max_thinking_tokens in favour of thinking (a ThinkingConfig with type of adaptive, enabled or disabled); 'Skill' in allowedTools in favour of the skills option; and updatedMCPToolOutput in PostToolUse output in favour of updatedToolOutput. Skill names are also validated before the CLI starts (Python 0.2.129, TS 0.3.221), so skills=["*"] becomes skills="all".

Governance

Governance for an agent platform is mostly about making one decision explicit: who is allowed to give an agent which capability, and what evidence exists afterwards.

Start with a capability tier model, because "which tools" is the question teams actually ask. Tier one is read-only: tools: ["Read", "Glob", "Grep"], permissionMode: "dontAsk", no Bash, no MCP write tools, and it is self-service. Tier two adds writes within a workspace and a PreToolUse hook that denies paths outside it. Tier three adds Bash or network-capable MCP servers and requires a review, because that is the tier where prompt injection becomes a production change. Writing the tiers down converts an unbounded security conversation into a form with three options.

Then the MCP supply chain, which is the part most platforms under-govern. Every MCP server is third-party code with a tool description the model will read and act on. A malicious or merely careless description is an injection vector, and a stdio server runs as a child process of your agent with its environment. strictMcpConfig / strict_mcp_config is the control that matters: it ignores .mcp.json, user settings, plugin servers and claude.ai connectors, so the set of MCP servers is exactly what your code passed. Review new servers like dependencies, pin their versions, and prefer in-process SDK MCP servers you wrote — built with tool() and createSdkMcpServer() in TypeScript or @tool and create_sdk_mcp_server() in Python — over remote ones, because an in-process tool has no transport to compromise. Tool names are fully qualified as mcp__{server_key}__{tool_name}, where the server key is the key in mcpServers, which is also how your allow rules stay readable. MCP covers the protocol itself.

Set tool annotations deliberately, because they have an execution effect rather than being documentation. Read-only tools, and MCP tools marked readOnlyHint, may run in parallel; mutating tools run sequentially, and custom tools default to sequential. Marking a mutating tool readOnlyHint is how you get concurrent writes you never designed for.

Skills and plugins need the same treatment. Skills are SKILL.md directories under .claude/skills/; only their descriptions load at session start, which means a skill's description is a prompt your model reads every session. Plugins bundle skills, agents, hooks and MCP servers and load by local path through plugins: [{ type: "local", path }] — so a plugin can install a hook, which is a lot of trust for a directory. Review them as code and load them from a path your pipeline controls.

Where the Claude Agent SDK stops

Owning a tool includes knowing its edges, and recommending something else without ceremony when a workload is on the wrong side of one.

It is not a thin API wrapper, and you should not use it as one. If what you want is a Messages API call with a tool loop you control, use the client SDK — anthropic or @anthropic-ai/sdk — and write the loop, or use its beta tool runner. Spawning a CLI subprocess to do one classification is a lot of machinery for no benefit, and you inherit every operational concern in this guide for free. Claude API is the right stop for that shape of work.

If you do not want to run the agent loop at all, use Managed Agents. Anthropic hosts the loop, with sessions in an Anthropic cloud sandbox or a self-hosted sandbox, driven by the REST API, the SDKs or the ant CLI. The trade is the obvious one: you give up control of the filesystem, the shell and the process, and you give up the operational burden that comes with them. For a team that wants agents but does not want to own containers, that is a good trade and you should say so rather than defending your platform.

If you need orchestration rather than an agent, this is the wrong layer. Branching, retries, human approval steps, durable state machines across days: those are workflow concerns, and LangGraph or a general workflow engine models them directly. The Agent SDK's loop is deliberately a loop.

If you need hard per-request latency guarantees, a loop whose length the model decides is a poor fit: you can cap turns and budget, but not thinking.

And a fair comparison with the neighbours in this catalogue: if your team is already deep in OpenAI Agents SDK, a migration recipe exists in the Claude Cookbook, but the question to ask first is whether you need the thing the Agent SDK uniquely gives you — a real shell, real file editing, a permission engine and a transcript — or whether you are migrating for model access, which a gateway solves without changing your agent framework.

Running it as a platform for other teams

Everything above becomes a platform when you package it so a team can ship an agent without learning any of it. Four artifacts do most of the work.

A shared options factory, not a document. One function that returns the options object, with env: {...process.env, ...} spread correctly, timeouts and retries set, settingSources: [], strictMcpConfig: true, telemetry variables configured, maxTurns and maxBudgetUsd populated from the capability tier, and the platform's PreToolUse hooks already attached. Teams pass a prompt, a tool list and a tier. Every fact in this guide that a team could get wrong is a fact they never see.

A golden container image. Hardened per the Docker list, with the SDK pinned, the native binary verified for the target architecture at build time, and a startup check that runs claude --version. Build the SDK inside the image for the target architecture rather than copying node_modules from a laptop — that mismatch produces Claude Code executable at <path> exists but failed to launch. The official cookbook has Docker, Modal and Kubernetes examples at anthropics/claude-cookbooks/claude_agent_sdk/hosting; start there. Docker and Kubernetes cover the hosting side.

A gateway with tenancy built in. It authenticates the caller, maps them to a tenant, picks a pod by consistent hash on sessionId, enforces a request deadline the agent's timeouts respect, and streams messages back. It also owns the egress proxy relationship, so the agent never holds a key.

A dashboard and four alerts. The dashboard: sessions by state, per-session peak RSS, cost estimate per tenant, turns per session, and the gap between your estimate and the Cost API. The alerts: terminal_reason: "api_error" rate (not success rate, for the reason given above), mirror_error occurrences, 429 rate as a fan-out signal, and permission_mode_changed events. Prometheus and Grafana are the usual home for the first two.

Then the parts that are not technical. Publish a supported version floor and a deprecation window, because teams will pin and you will need to move them. Publish the capability tiers and who approves tier three. Publish what you log and for how long. And run a shared regression suite — the init-assertion test above, plus one end-to-end agent per tier — on every SDK bump, so "we upgraded and something changed" is a CI failure on your side rather than a support ticket from theirs.

The review checklist

What I actually look for in a pull request or design document that touches an agent.

Process and configuration. Is env spread from process.env in TypeScript? Are API_TIMEOUT_MS and CLAUDE_CODE_MAX_RETRIES set, and does their product fit inside the caller's deadline? Is the SDK version pinned, and does the pin satisfy the published floor? Is maxTurns set, given there is no session timeout? Is maxBudgetUsd set, given it also covers subagents?

Permissions. Is permissionMode explicit rather than defaulted? If canUseTool exists, does anything in allowedTools or bypassPermissions shadow it? Are platform guardrails in PreToolUse hooks rather than in canUseTool? Does disallowedTools cover what allowedTools cannot, especially under bypassPermissions? Is bypassPermissions present at all, and if so, is it inside a container with --cap-drop ALL and no credential mounts?

Isolation and tenancy. Is settingSources: [] set? Is CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 set? Is CLAUDE_CONFIG_DIR per tenant? Is cwd per tenant on every call, not just the first? Is strictMcpConfig: true set? Does the container mount ~/.ssh, ~/.aws or ~/.config? (That last one is a block, not a comment.)

State. If sessions resume, is there a SessionStore, and does the adapter pass the conformance suite? Is mirror_error handled? Does the load balancer hash on sessionId? Does anything assume the filesystem resumes with the session, when only the conversation does?

Results and cost. Is terminal_reason checked before subtype? Is subtype checked before reading result? Are Python's total_cost_usd, usage and model_usage checked for None? Does any code sum total_cost_usd across turns instead of reading the latest? Does anything bill a customer from it?

Errors. Is the for await or async for inside try/except, given a single-shot query() yields the error result and then raises? Is there a stderr callback in Python? Does except ResultError come before except ProcessError? Is the prompt generator itself exception-safe, given a throw hangs a Python session silently?

Observability. Is the exporter anything other than console? Are export intervals lowered for short runs? Is CLAUDE_CODE_OTEL_DIAG_STDERR=1 on? Are tenant and user IDs percent-encoded in resource attributes? Is content logging off unless a retention decision says otherwise?

Supply chain. Are MCP servers pinned and reviewed, have their tool descriptions been read as prompts, are annotations honest (particularly readOnlyHint on anything that mutates), and do skills and plugins come from a path the pipeline controls?

The complete picture

Put the three parts together and the shape is clear. The Claude Agent SDK gives you Claude Code as a library: an agent loop with a shell, a filesystem, built-in tools, a permission engine, sessions, hooks, subagents, MCP, skills and plugins, all running in a subprocess you own. Beginner was about driving that loop. Mid was about predicting it. This part was about standing behind it.

The through-line is the subprocess. It is why state is local and perishable, which is why you need a SessionStore and consistent hashing; why memory breaks first, which is why you recycle; why the agent holds your credentials, which is why the egress proxy earns its place; why isolation is a container question rather than a library question; and why hooks beat canUseTool for policy, because a hook runs in your process, first, unconditionally.

The three numbers to leave with: 1 GiB, 1 CPU and 5 GiB of disk per agent as a measured floor; concurrency 20 and spawn depth 3 as the subagent defaults that decide whether you meet a rate limit; and total_cost_usd is an estimate while the Cost API is the truth. Everything else you can look up.

Where the series leaves you

You can design an agent platform now: pick the session pattern, size the fleet from measurement rather than guesswork, place the trust boundary, choose a rung on the isolation ladder with the performance cost in mind, isolate tenants knowing which settings you cannot isolate, and account for spend in a way that survives an audit. You can read a stuck session's result fields in the right order, tell a 429 from a 529, and recognise a packaging failure from its exact message.

Next steps depend on which direction your platform is growing. In traffic: Kubernetes and Docker hold the hosting patterns. In scrutiny: OpenTelemetry and Langfuse make the span tree readable, and Vault formalises secret handling. In model variety: LiteLLM puts one base URL in front of several providers. And if what you keep hitting is orchestration rather than agency, LangGraph is the honest answer.

Keep the init-assertion test green, read the changelog before every minor, and re-measure peak RSS whenever the prompt or the MCP set changes. Those three habits cover most of what goes wrong after launch.

Sources

• Agent SDK overview
• Hosting the Agent SDK
• Secure deployment
• Permissions
• Hooks
• Sessions
• Session storage
• Cost tracking
• Observability
• Subagents
• MCP in the Agent SDK
• Tool search
• Custom tools
• Skills
• Plugins
• File checkpointing
• Structured outputs
• Streaming vs single mode
• Migration guide
• Troubleshooting
• Configuration
• TypeScript reference
• Python reference
• Environment variables
• Errors
• TypeScript SDK changelog
• Python SDK changelog
• Hosting cookbook
• sandbox-runtime

Senior interviews about the Claude Agent SDK are rarely about the API surface. The interviewer wants to know whether you can design a platform around a language model that has a shell, defend a security boundary to someone who does not care about agents, and debug a stuck session at 3 a.m. with only a result message to go on. These are the prompts that come up, and what separates a strong answer from a correct one.

The thirty-second framing

Before any design question, have this ready, because almost every follow-up hangs off it: the Claude Agent SDK runs Claude Code as a subprocess. One session is one claude process, talking NDJSON over stdio, owning a shell, a working directory and a JSONL transcript on local disk. It never listens on the network, so you supply the front door. Everything hard about operating it — durability, isolation, memory, cost — follows from that sentence.

Say the version you verified against, too. TypeScript @anthropic-ai/claude-agent-sdk 0.3.285 and Python claude-agent-sdk 0.2.162, both bundling Claude Code CLI v2.1.285. Naming a version signals you have actually read the changelog, which is where most of the senior-level content lives.

System design: a code-review agent for forty teams

The prompt. "Design a service where any team in the company can point an agent at a pull request and get a review. Forty teams, maybe a few hundred reviews a day. Walk me through it."

Start with the session pattern, not the architecture diagram. Reviews are batch-shaped: a webhook arrives, work happens, a comment is posted, nothing resumes. That is the ephemeral pattern — one container per task, the prompt in an environment variable, maxTurns capped, the container exits and its volume goes away. Saying this early is worth a lot, because it removes session storage, affinity and recycling from the design, and a candidate who reaches for SessionStore and consistent hashing on a stateless batch workload has mistaken complexity for seniority.

Then the trust boundary, because a pull request is untrusted input. The diff, the issue text and the files all come from outside and all reach the model. Prompt injection is the live threat, not a theoretical one. So: permissionMode: "dontAsk" with an explicit allowedTools list, tools limited to ["Read", "Glob", "Grep"], no Bash, and a PreToolUse hook that denies reads outside the checkout. Hooks rather than canUseTool, and you should explain why: permissions evaluate hooks first, deny rules, ask rules, mode, allow rules, then canUseTool last — so canUseTool fires only when the flow falls through to a prompt, never for an auto-approved call. Put a bare name in allowedTools and your careful callback stops firing for that tool, which the SDK warns about with CLAUDE_SDK_CAN_USE_TOOL_SHADOWED.

Sizing. Start from 1 GiB RAM, 1 CPU and 5 GiB disk per agent as the documented floor, then say the sentence that matters: it is a floor, because memory grows with session length, and pods per node comes from measured peak RSS with your real prompts and MCP servers. A few hundred reviews a day is not a scale problem; it is a concurrency-at-peak problem, so size for the burst and let the queue absorb the rest.

Cost. maxBudgetUsd per review as a hard stop, effort: "low" for small diffs, a cheaper model for subagents via the haiku or sonnet aliases, and excludeDynamicSections: true on the preset so forty teams sharing one system prompt actually share a prompt cache. Then the caveat that separates seniors: total_cost_usd is a client-side estimate from a bundled price table. Use it for caps and dashboards; reconcile chargeback against the Usage and Cost API.

Where a strong answer goes further. It names what it is not building: no orchestration engine, because the loop is a loop and branching with approvals belongs in a workflow tool; and no custom agent framework, because if the review did not need a filesystem it should have been a plain Messages API call with the client SDK instead.

System design: a multi-tenant agent for external customers

The prompt. "Same SDK, but now the agent runs against each customer's own data, and the customers are different companies."

The answer starts by refusing the premise. The documented isolation set exists and you should recite it — settingSources: [], CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, a per-tenant CLAUDE_CONFIG_DIR, a per-tenant cwd on every call, per-tenant egress rules at the proxy, strictMcpConfig: true — and then say why it is not enough: managed and server-managed settings and ~/.claude.json are read regardless of what you pass, and managed policy sits at the top of the settings precedence chain. The docs themselves say not to rely on default options for isolation and to consider one filesystem per tenant. So for different companies the answer is a container per tenant, and the option set above is the belt that goes with those braces.

The detail that shows you have done this. settingSources omitted means loaded, equivalent to ["user","project","local"]: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, CLAUDE.md and .claude/ skills, agents and commands. The 0.1.0 changelog says "no filesystem settings by default" and that line is stale. A candidate who knows the changelog is wrong about this has read both the changelog and the current docs, which is exactly the habit the job needs.

Isolation strength. Have the ladder ready with its costs. sandbox-runtime is cheap, shares the kernel and does no TLS inspection, so domain fronting is possible. Hardened Docker is the sensible default: --cap-drop ALL, --security-opt no-new-privileges, seccomp, --read-only with tmpfs /tmp, --network none plus a Unix-socket proxy, --memory 2g, --pids-limit 100, --user 1000:1000, and never a mount of ~/.ssh, ~/.aws or ~/.config. gVisor costs roughly 2× on syscalls and 10 to 200× on heavy file open and close, which is a disqualifier for an agent that greps repositories. Firecracker boots in under 125 ms with under 5 MiB overhead. Quoting the gVisor file-I/O number is the single most persuasive fact you can bring to this question, because it shows you chose a rung on evidence rather than on reputation.

Data residency, if the role is regional. Say plainly that the model call is the part that leaves the VPC, so pinning the agent to a Gulf or Egyptian region does nothing about where inference happens. Residency means Bedrock (CLAUDE_CODE_USE_BEDROCK=1) or Vertex (CLAUDE_CODE_USE_VERTEX=1) in a permitted region and a provider conversation, not a subnet change.

System design: conversation continuity on stateless pods

The prompt. "Product wants users to resume yesterday's conversation. Platform wants pods to be disposable. Reconcile it."

This is the hybrid pattern, and the documented phrasing is "ephemeral containers plus a required SessionStore". Explain what a store is: an adapter you write with append and load required, plus optional listSessions, listSessionSummaries, delete and listSubkeys, wired through sessionStore / session_store with sessionStoreFlush of "batched" or "eager".

Then the three things interviewers are listening for.

It is a mirror, not a replacement. The subprocess still writes local disk; the store is a dual-write alongside it. So local disk stays on the critical path and a read-only filesystem still breaks the session.

Mirror writes are best-effort. A failed batch is dropped, and the SDK tells you with a mirror_error message in the stream. If nobody watches for it, your durability guarantee is a hope. Alert on it.

A session persists the conversation, not the filesystem. Resume on a fresh container and the model remembers editing a file that is back to its original content. This is the answer to "what breaks when the pod moves", and it is the one most candidates miss. File state needs enableFileCheckpointing and rewindFiles(userMessageId), enabled on both the original and resumed session.

Close with routing. Even with a store, put consistent hashing on sessionId in front, so the store is a safety net for pod loss rather than the hot path. Round-robin plus a store works and pays a full transcript load every turn. And mention claude_agent_sdk.testing.run_session_store_conformance — running the conformance suite against your adapter in CI is the kind of concrete rigour that ends this question well.

Incident response: "the agents are hanging"

The prompt. "Half your agent sessions have been running for ninety minutes. Nothing is erroring. Go."

First, know that there is no session timeout. The SDK has no top-level wall-clock limit; maxTurns and maxBudgetUsd are the only built-in stops and both are off by default. So "running for ninety minutes" may be entirely expected behaviour from a configuration nobody set.

Second, do the timeout arithmetic out loud. API_TIMEOUT_MS defaults to 600000 and CLAUDE_CODE_MAX_RETRIES defaults to 10, capped at 15. Worst case is roughly API_TIMEOUT_MS × (retries + 1), so a single request can legitimately occupy over an hour while your gateway timed out at sixty seconds and orphaned it. That is the most common root cause of this exact symptom, and naming the formula is a strong signal.

Third, split the population. If it is Python and there is no output at all, suspect the prompt generator: a generator exception is logged at debug level and the session hangs silently, where TypeScript at least gives you the misleading Claude Code process aborted by user. If it is subagent-heavy, look for Concurrent subagent limit reached in tool-result text — concurrency caps at 20 and spawn depth at 3, and the limit arrives as a tool result rather than an exception, so it reads as the model behaving oddly. If it is MCP-related, remember status: "pending" in init is not a failure since MCP servers connect in the background by default; MCP_CONNECTION_NONBLOCKING=0 restores blocking behaviour.

Fourth, the fix you ship afterwards. Explicit API_TIMEOUT_MS and CLAUDE_CODE_MAX_RETRIES whose product fits the caller's deadline, CLAUDE_CODE_RETRY_WATCHDOG=1, maxTurns and maxBudgetUsd populated from a capability tier, and a stderr callback in Python so the next incident has evidence.

Incident response: "success rate looks fine, users are complaining"

This is my favourite question to ask, because it has one answer and knowing it is almost pure experience. Check terminal_reason before subtype. When the final request fails with an API error, Claude Code reports subtype: "success" with terminal_reason: "api_error". A monitor that only reads subtype reports health straight through an outage.

The full field order for a senior answer: terminal_reason first, then subtype (success, error_max_turns, error_max_budget_usd, error_during_execution, error_max_structured_output_retries), then stop_reason (end_turn, max_tokens, refusal). Read result only on success. And if structured output is in play, require both subtype == "success" and a non-null structured_output, because an unsatisfiable schema gives you success with nothing in it.

Two adjacent traps worth volunteering: in Python total_cost_usd, usage and model_usage are Optional, so unguarded arithmetic throws; and after a crash the result is error_during_execution, possibly with zeroed cost and stop_reason: null, so a billing pipeline that treats missing cost as zero makes crashes free in your dashboards and expensive on the invoice.

Arguing a trade-off to leadership

"Why does each customer need their own container? That's three times the infrastructure."

The winning move is to reframe the comparison, because the infrastructure number is real and small while the risk it buys down is real and large. A container costs about $0.05 per hour; one long agent session can cost dollars in tokens. So container-per-tenant is a rounding error against the token bill you are already paying, and the alternative is relying for isolation on options the vendor's own documentation says not to rely on, in a product where managed settings and ~/.claude.json are read no matter what you pass. Frame it as "the cheapest line item protects the most expensive failure", give the actual numbers, and offer the fallback you would accept: soft isolation between internal teams you already trust, hard isolation between customers.

"Why can't we just give the agent admin credentials and let it work?"

Do not answer with principle; answer with mechanism. The threat is prompt injection, and the agent reads text from pull requests, web pages and files. The AST-based Bash command parsing is a permission gate, not a sandbox. bypassPermissions ignores allowedTools entirely, and subagents inherit it from the parent. So the credentials you grant are the credentials an injected instruction has. Then offer the alternative that costs leadership nothing: put the key behind a proxy via ANTHROPIC_BASE_URL so the agent never holds it, and keep tool credentials in services on the far side of the boundary. You are not asking for less capability, you are asking for the same capability with the secret somewhere else.

"The agent platform costs too much. Cut it."

Come with levers ranked by return, not with a refusal: maxBudgetUsd caps, effort: "low" on routine work, smaller models for subagents, tool search to keep MCP schemas out of context, and excludeDynamicSections: true for cross-user cache hits. Then tell them where the number they are looking at came from — a client-side estimate, not a bill — and propose monthly reconciliation against the Cost API so the next conversation runs on real figures.

What a strong answer has that a correct one does not

A correct answer describes the SDK. A strong answer keeps returning to the subprocess: state is local because of it, memory is the first failure because of it, the egress proxy matters because of it, hooks beat canUseTool because a hook runs in your process first.

A strong answer also names the thing it would not build. Managed Agents exist, where Anthropic hosts the loop in a cloud or self-hosted sandbox; the client SDK exists for work that needs no shell; a workflow engine exists for branching and approvals. Volunteering that you would move a workload off your own platform is the clearest possible signal that you own the platform rather than defend it.

And a strong answer carries three numbers without being asked: 1 GiB, 1 CPU, 5 GiB disk per agent as a measured floor; concurrency 20, spawn depth 3 as the subagent defaults that decide whether you meet a rate limit; and total_cost_usd is an estimate while the Cost API is the truth.

The ninety-second self-test

Answer these out loud. Any hesitation is a page to reread.

In what order do permissions evaluate, and which stage never fires for an auto-approved call? What does omitting settingSources load, and which changelog line is wrong about it? What does options.env do in TypeScript versus Python, and what error does getting it wrong produce? What does a SessionStore not replace, and which message tells you a write was dropped? Which field do you read before subtype, and why? Which two things does a session persist and not persist? What is the worst-case wall clock for one request at default timeout and retry settings? What are the subagent concurrency and spawn-depth defaults? Why is gVisor the wrong sandbox for a repository-grepping agent? And what is total_cost_usd good for, and what must you never do with it?

These are the things that only hurt once you are the owner: the traps that need production traffic or a second tenant to appear, the habits that make a platform maintainable, and the checklists I actually run over a pull request or a design document before signing it off. Verified against TypeScript @anthropic-ai/claude-agent-sdk 0.3.285 and Python claude-agent-sdk 0.2.162, both bundling Claude Code CLI v2.1.285.

Traps that only appear at scale

options.env replaces the environment in TypeScript. Since 0.2.113, env does not extend process.env, it replaces it for the subprocess. The symptom is Not logged in · Please run /login or Invalid API key from a service that worked yesterday and whose key is definitely set. Always env: { ...process.env, MY_VAR: "x" }. Python merges instead, which means the same code reviewed by the same person behaves differently in the two languages. Put the spread in a shared options factory so nobody meets this twice.

Memory grows and never plateaus. The 1 GiB floor is a floor. Per-session peak RSS rises with transcript length, file reads and MCP output, so a pod that held eight sessions at launch holds four by the afternoon and starts getting OOM-killed by the evening. Recycle subprocesses on a schedule — a turn count, a wall-clock age, or an RSS threshold — and derive pods per node from measured peak RSS rather than the documented floor.

Fan-out meets the rate limit, and the limit arrives as a tool result. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS defaults to 20 and CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH to 3, which is a great deal of simultaneous API traffic from one session. You see Concurrent subagent limit reached or Budget limit reached in tool-result text, not as an exception, so it reads as the model behaving strangely. Separately, learn to tell API Error: Request rejected (429) — yours to fix by lowering concurrency or raising the tier — from API Error: Repeated 529 Overloaded errors, which is capacity on Anthropic's side and does not count against quota.

canUseTool goes silent the moment you add a bare allowedTools entry. Permissions evaluate hooks, deny rules, ask rules, mode, allow rules, then canUseTool, and the callback fires only when the flow falls through to a prompt. An auto-approved call never reaches it, and bypassPermissions never reaches it. The SDK warns with CLAUDE_SDK_CAN_USE_TOOL_SHADOWED in TypeScript and a runtime warning in Python, but the warning is easy to miss in a log. Platform guardrails belong in a PreToolUse hook.

Hooks fire concurrently, and the short timeouts are shorter than you think. All matching hooks for an event run at once, so none can depend on another's result. Timeouts default to 600 seconds for most events, 30 for UserPromptSubmit and the model-switch hooks, 10 for MessageDisplay, and about 1.5 seconds for SessionEnd. A hook that times out is discarded and the session continues — so an audit write in a SessionEnd hook silently loses records. Enqueue, do not call out.

allowedTools is not a restriction. It is an auto-approve list and does not control which tools exist. Remove a tool with tools for an exact base set, or a bare name in disallowedTools to strip it from context. A scoped rule such as Bash(rm *) denies matching calls in every mode. And allowedTools does not constrain bypassPermissions at all, so there you need disallowedTools or hooks.

A model upgrade can change which tools your guardrails can see. Task-tracking tools are default tools only on Claude 3.x, Opus 4.0 to 4.7, Sonnet 4.0 to 4.6 and Haiku 4.5; on Opus 4.8, Sonnet 5, Fable 5, Mythos 5 and newer you must name TaskCreate, TaskGet, TaskUpdate, TaskList or TodoWrite in tools or allowedTools, or set CLAUDE_CODE_ENABLE_TODO_TOOLS=1. And since TS 0.3.162, native builds default to embedded find/grep inside Bash instead of registering dedicated Grep and Glob tools, so hooks that intercepted searches stop seeing them unless you name Grep and Glob explicitly.

Resumed cost totals changed under everyone. Since CLI 2.1.277, a resumed or forked session's total_cost_usd and modelUsage continue from earlier turns instead of restarting at zero. Accounting code written before that now double-counts. Read the latest result; never sum across turns.

Your observability exporter can corrupt the message channel. stdout is how the SDK talks to the subprocess, so the OTel console exporter breaks the protocol, and the symptom looks like an SDK parsing bug. Also: default export intervals are 60 seconds for metrics and 5 for traces and logs, so short runs export no metrics at all, and export failures are silent unless you set CLAUDE_CODE_OTEL_DIAG_STDERR=1.

SessionStore mirror writes are best-effort. A failed batch is dropped and you get a mirror_error message in the stream. If you do not alert on it, the difference between durability and hope is invisible. And remember the store is a mirror alongside local disk, not a replacement for it.

A session persists the conversation, not the filesystem. Resume on a fresh container and the model confidently remembers edits that are not there. Pair resume with enableFileCheckpointing and rewindFiles(userMessageId) — enabled on both the original and resumed session — or scope your agents so resumed file state does not matter.

Packaging bites in the image, not on the laptop. npm ci --omit=optional gives Native CLI binary for <platform>-<arch> not found. There is no musllinux wheel for Python, so Alpine gets the sdist with no bundled binary. Python 0.2.160 to 0.2.162 ship no Windows wheel, so Windows x64 also resolves to the sdist — install Claude Code natively or pin claude-agent-sdk==0.2.159, and re-check PyPI before publishing a base image. And never point cli_path at npm's claude.cmd: since Python 0.2.124 the SDK refuses batch shims as a defence against the BatBadBut class of bug.

Python hides generator exceptions. If your prompt generator throws, TypeScript reports the misleading Claude Code process aborted by user while Python logs at debug level and the session hangs with no output. Any Python session that hangs silently: suspect the generator first.

Your gateway strips the header the API needs. A proxy at ANTHROPIC_BASE_URL that drops unknown headers produces API Error: 400 ... Extra inputs are not permitted ... context_management, because anthropic-beta never arrived. Forward it, or set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

Spilled MCP output fills your volume. MAX_MCP_OUTPUT_TOKENS defaults to 25,000 tokens, and anything larger is written to a file rather than truncated. Combine that with accumulating transcripts and working directories and a long-lived agent container with no retention policy runs out of disk in days, which presents as tool calls failing for reasons that have nothing to do with the model. Give the volume a cleanup job and alert on free space, not just on memory.

Platform-ownership habits

Own the options factory, not the documentation. One function returns the options object with env spread, timeouts set, settingSources: [], strictMcpConfig: true, telemetry configured, budgets populated from a capability tier and the platform's PreToolUse hooks attached. Teams pass a prompt, a tool list and a tier. Every fact above that a team could get wrong becomes a fact they never see. Then periodically grep the organisation for ClaudeAgentOptions( and query({ to find the call sites that bypassed it.

Publish capability tiers instead of answering security questions ad hoc. Tier one: tools: ["Read","Glob","Grep"], permissionMode: "dontAsk", self-service. Tier two: writes inside a workspace, with a hook denying paths outside it. Tier three: Bash or network-capable MCP servers, review required. Three options on a form beats an unbounded conversation every time.

Assert on init in CI. One test that checks the tool list, MCP statuses, model and apiKeySource catches almost every default-change in the SDK in a few seconds. Run it on every version bump. It is the cheapest upgrade insurance available, and it is how "we upgraded and something changed" becomes your CI failure instead of a team's support ticket.

Measure peak RSS, re-measure after every change to prompts or MCP servers. Capacity planning here is one division — host memory minus overhead, over measured peak RSS — and the denominator moves whenever the workload does.

Make the proxy the only route out. --network none plus a Unix-socket proxy gives you credential injection, a domain allowlist and an audit trail from one component. The agent never holds ANTHROPIC_API_KEY, so prompt injection cannot exfiltrate it.

Alert on four things, not forty. The terminal_reason: "api_error" rate rather than the success rate; mirror_error occurrences; the 429 rate as a fan-out signal; and permission_mode_changed events, which are either deliberate or urgent.

Treat MCP servers as dependencies with opinions. Every server is third-party code whose tool descriptions the model reads and acts on, and a stdio server runs as a child of your agent with its environment. Pin versions, review new ones, set strictMcpConfig: true so .mcp.json, user settings, plugin servers and claude.ai connectors cannot leak in, and prefer in-process SDK MCP servers you wrote. Read every new server's tool descriptions as prompts, because that is what they are.

Set annotations honestly. Read-only tools and MCP tools marked readOnlyHint may run in parallel; mutating tools run sequentially, and custom tools default to sequential. readOnlyHint on something that mutates buys you concurrent writes you never designed for.

Publish a version floor and a deprecation window. Updating the SDK is how you update the CLI, since the bundled binary is pinned to the SDK version, so there is no way to take a CLI fix without moving the SDK. Patches land roughly daily and mostly bump the CLI; read the changelog before a minor, and remember that TS 0.3.142 removed the whole V2 session API.

Decide the retention question before a customer asks it. Transcripts contain whatever the agent read. If OTEL_LOG_USER_PROMPTS or OTEL_LOG_TOOL_CONTENT is on, that content is also in your observability stack under its rules. For regulated workloads in the Gulf and Egypt this is usually the control that gets audited, not the model configuration.

Keep one honest exit. Know which workloads should leave your platform: anything with no need for a shell belongs on the client SDK, anything that needs branching and approvals belongs in a workflow engine, and anything whose team does not want to own containers belongs on Managed Agents. Recommending the exit is what ownership looks like.

Pull-request review checklist

Process and configuration. Is env spread from process.env in TypeScript? Are API_TIMEOUT_MS and CLAUDE_CODE_MAX_RETRIES set, and does their product fit the caller's deadline? Is the SDK pinned at or above the published floor? Is maxTurns set, given there is no session timeout? Is maxBudgetUsd set, given it also covers subagents?

Permissions. Is permissionMode explicit? If canUseTool exists, does any allowedTools entry or bypassPermissions shadow it? Are platform guardrails in PreToolUse hooks? Does disallowedTools cover what allowedTools cannot? If bypassPermissions appears at all, is it inside a container with --cap-drop ALL and no credential mounts?

Isolation. settingSources: []? CLAUDE_CODE_DISABLE_AUTO_MEMORY=1? A per-tenant CLAUDE_CONFIG_DIR? A per-tenant cwd on every call rather than only the first? strictMcpConfig: true? Any mount of ~/.ssh, ~/.aws or ~/.config is a block, not a comment.

State. If sessions resume, is there a SessionStore, and does the adapter pass claude_agent_sdk.testing.run_session_store_conformance in CI? Is mirror_error handled? Does anything assume the filesystem resumes along with the conversation?

Results and cost. Is terminal_reason read before subtype, and subtype before result? Are Python's total_cost_usd, usage and model_usage checked for None? Does anything sum total_cost_usd across turns rather than reading the latest? Does anything bill a customer from it?

Errors. Is the for await or async for wrapped, given a single-shot query() yields the error result and then raises? Is there a stderr callback in Python? Does except ResultError precede except ProcessError? Is the prompt generator exception-safe?

Observability. Is the exporter anything other than console? Are export intervals lowered for short runs? Is CLAUDE_CODE_OTEL_DIAG_STDERR=1 set? Are tenant and user IDs percent-encoded in resource attributes? Is content logging off unless a retention decision says otherwise?

Deprecations. Any maxThinkingTokens or max_thinking_tokens left, rather than thinking? Any 'Skill' in allowedTools rather than the skills option? Any updatedMCPToolOutput rather than updatedToolOutput? Any skills=["*"], which is now rejected before the CLI starts in favour of skills="all"?

Design-document review checklist

Does it name the session pattern? Ephemeral, long-running, hybrid with a required SessionStore, or multi-agent container. A document that does not pick one has not made its most consequential decision, and a document that picks hybrid for stateless batch work has added a store it does not need.

Does it say who supplies the front door? The subprocess never listens on the network. Authentication, tenancy mapping, session routing and streaming are the author's work, and the design should say which component does each.

Is the routing consistent with the state? If sessions are local and the balancer is round-robin, the design is wrong. Consistent hashing on sessionId or a documented reason it does not matter.

Is the threat model prompt injection? Not a hostile model, not a rogue employee: untrusted text reaching a model that holds credentials. If the document does not name it, the controls that follow will be the wrong ones.

Does it choose a rung on the isolation ladder with its cost? sandbox-runtime, hardened Docker, gVisor or Firecracker, with the performance consequence stated. gVisor's 10 to 200× penalty on heavy file open and close disqualifies it for file-heavy agents, and a document that picked it without that number picked it on reputation.

Does sandbox.failIfUnavailable stay true? Since TS 0.2.91 it defaults true, so a missing sandbox dependency ends the run rather than running unsandboxed. Setting it false to "degrade gracefully" degrades through the boundary.

Where do the secrets live? ANTHROPIC_BASE_URL pointing at an injecting proxy beats the key in the agent's environment. Tool credentials should sit in services beyond the boundary. Inbound user tokens are validated at the gateway, not by the agent.

Are tenants containers or options? Options for internal teams you already trust; containers for different customers. The document should say which, and acknowledge that managed settings and ~/.claude.json are read regardless.

Does the capacity number come from measurement? Pods per node from measured peak RSS, not from the 1 GiB floor, with a note on when it will be re-measured.

Is there a recycling policy? Memory grows with session length. A long-running design without a recycle trigger has an OOM scheduled for a date nobody wrote down.

Is the cost section honest about the estimate? Caps and dashboards from total_cost_usd, chargeback from the Usage and Cost API, monthly reconciliation, and an explicit note that error_during_execution can report zeroed cost after a crash.

Does it say what the platform will not do? The workloads that belong on the client SDK, on Managed Agents or in a workflow engine. A design document that claims every agent-shaped problem is a weaker document than one that draws its own edges.