Claude Agent SDK Configuration Options Reference
A dense reference for the options you pass into a Claude Agent SDK run, in Python and TypeScript.
//
Search across all documentation pages
A dense reference for the options you pass into a Claude Agent SDK run, in Python and TypeScript.
Use this page to look up a specific option's name, type, and default rather than re-reading the conceptual pages each time.
AgentOptions(...); TypeScript examples use the equivalent options object passed to query().snake_case in Python, camelCase in TypeScript).| Option (Python) | Option (TypeScript) | Type | Description |
|---|---|---|---|
model | model | str | Which Claude model runs the loop's decide step, e.g. "claude-sonnet-5" |
cwd | cwd | str | Working directory root for file_edit and bash |
system_prompt | systemPrompt | str | Additional system-level instructions layered on top of the SDK defaults |
max_turns | maxTurns | int | Hard cap on tool-use loop iterations before it stops |
| Option (Python) | Option (TypeScript) | Type | Description |
|---|---|---|---|
allowed_tools | allowedTools | list[str] | Allowlist of built-in tool names the loop may call |
tool_config | toolConfig | dict | Per-tool scoping (allowed commands, paths, domains) |
mcp_servers | mcpServers | list | Registered stdio or HTTP MCP servers the loop can call tools on |
subagents | subagents | list | Named child agent configs, each with their own tool scope |
| Option (Python) | Option (TypeScript) | Type | Description |
|---|---|---|---|
permission_mode | permissionMode | str | Whether allowed tool calls still need human approval, e.g. "default", "bypass" |
checkpoint_hook | checkpointHook | callable | Function invoked before a flagged tool call, to approve/reject/modify it |
checkpoint_tools | checkpointTools | list[str] | Which tool names trigger a checkpoint pause |
| Option (Python) | Option (TypeScript) | Type | Description |
|---|---|---|---|
resume | resume | str | A prior session ID to resume conversation and tool-result history from |
session_store | sessionStore | object | Where session state is persisted (in-memory, file, or a custom backend) |
| Mode | Behavior | Typical Use |
|---|---|---|
default | Pauses before destructive/flagged tool calls for approval | Most production agents |
bypass | No approval gate; every allowed tool call executes immediately | Tightly scoped, low-risk automations |
Custom (via checkpoint_hook) | Your own logic decides approve/reject/modify per call | Fine-grained or conditional approval rules |
| Scope Shape | When to Use |
|---|---|
Single tool family (e.g. ["file_edit"]) | Task is narrowly one kind of action |
Multiple families, no tool_config restriction | Trusted environment, well-understood task |
Multiple families with tool_config restrictions | Production agents touching real data or systems |
| Empty list | Pure text generation, no need to act on anything |
The fields map one-to-one, but naming convention differs: Python uses snake_case (allowed_tools), TypeScript uses camelCase (allowedTools).
allowed_tools decides what the loop can reach at all. permission_mode decides whether a reachable, allowed call still needs a human to approve it before it executes.
No. max_turns bounds a single query() call's internal loop iterations. Sessions span multiple separate query() calls over time.
No, each subagent config carries its own allowed_tools and tool_config, independent of the parent's.
Behavior falls back to the SDK's default mode, which typically still gates destructive actions; check the current SDK release notes for the exact default, since safe defaults can be refined between releases.
Yes, mcp_servers accepts a list, and it can mix stdio (local) and HTTP (remote) server registrations in the same run.
The conversation history and tool-result history captured under that session ID, so the loop continues with that context already present rather than starting blank.
Not strictly, but omitting it means file_edit and bash fall back to the process's ambient working directory, which is fragile across environments. Set it explicitly for anything beyond a quick local test.
from claude_agent_sdk import AgentOptions
options = AgentOptions() # all defaults: default model, default tool set, no session resumeInclude web_search and/or web_fetch in allowed_tools; they're separate entries since search and single-URL fetch have different risk profiles.
checkpoint_tools names which tool calls trigger a pause; checkpoint_hook is the function that runs during that pause to decide the outcome. Using one without the other typically falls back to a default confirmation behavior rather than custom logic.
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the Claude Agent SDK (latest release, Python and TypeScript). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.
Reviewed by Chris St. John·Last updated Jul 16, 2026