Claude Agent SDK Configuration Options Reference
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.
How to Use This List
- Options are grouped by what they control: model/identity, tool access, permissions, and session/subagent behavior.
- Python examples use
AgentOptions(...); TypeScript examples use the equivalent options object passed toquery(). - Field names are consistent across both languages; casing follows each language's convention (
snake_casein Python,camelCasein TypeScript). - Cross-reference the linked pages below for the reasoning behind each option, not just its shape.
Model & Identity Options
| 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 |
Tool Access Options
| 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 |
Permission Options
| 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 |
Session Options
| 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) |
Permission Modes at a Glance
| 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 |
Choosing Tool Allowlist Scope
| 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 |
FAQs
Are the Python and TypeScript option names identical?
The fields map one-to-one, but naming convention differs: Python uses snake_case (allowed_tools), TypeScript uses camelCase (allowedTools).
What's the difference between allowed_tools and permission_mode?
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.
Is max_turns the same as a session limit?
No. max_turns bounds a single query() call's internal loop iterations. Sessions span multiple separate query() calls over time.
Do subagents inherit the parent's allowed_tools?
No, each subagent config carries its own allowed_tools and tool_config, independent of the parent's.
What happens if I don't set permission_mode?
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.
Can I register more than one MCP server?
Yes, mcp_servers accepts a list, and it can mix stdio (local) and HTTP (remote) server registrations in the same run.
What does resume actually restore?
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.
Is cwd required for every run?
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.
What's the simplest valid AgentOptions?
from claude_agent_sdk import AgentOptions
options = AgentOptions() # all defaults: default model, default tool set, no session resumeWhich option controls whether the loop can browse the web?
Include web_search and/or web_fetch in allowed_tools; they're separate entries since search and single-URL fetch have different risk profiles.
Do checkpoint_tools and checkpoint_hook have to be used together?
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.
Related
- The Claude Agent SDK Mental Model - the concepts behind these options
- Enabling File Edit, Bash, and Web Tools in the Agent SDK - tool access options in depth
- Adding Human-in-the-Loop Checkpoints to an Agent SDK Workflow - permission mode and checkpoint options in depth
- Persisting Sessions Across Runs with the Claude Agent SDK - session options in depth
- Delegating Work to Subagents in the Claude Agent SDK - subagent configuration in depth
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.