ClaudeAgentOptions

Configuration dataclass for customizing Claude Agent SDK behavior. Used with both query() and ClaudeSDKClient to control models, tools, permissions, hooks, and more.

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-20250514",
    tools=["Bash", "Read", "Write"],
    permission_mode="default",
    max_turns=10
)

Fields

tools

list[str] | ToolsPreset | None

default:"None"

List of tool names to enable, or a preset configuration.Example: ["Bash", "Read", "Write"] or {"type": "preset", "preset": "claude_code"}

allowed_tools

list[str]

default:"[]"

Additional tools to allow beyond the default set.

disallowed_tools

list[str]

default:"[]"

Tools to explicitly disallow.

system_prompt

str | SystemPromptPreset | None

default:"None"

Custom system prompt or preset configuration.Example: "You are a helpful coding assistant" or {"type": "preset", "preset": "claude_code", "append": "Additional instructions"}

mcp_servers

dict[str, McpServerConfig] | str | Path

default:"{}"

MCP server configurations. Can be a dictionary of server configs, or a path to a config file.See MCP Types for configuration details.

permission_mode

PermissionMode | None

default:"None"

Permission mode for tool usage.

"default" - Prompt for permission on potentially dangerous operations
"acceptEdits" - Auto-approve file edits
"plan" - Review agent’s plan before execution
"bypassPermissions" - Skip all permission checks (use with caution)

model

str | None

default:"None"

Claude model to use (e.g., "claude-sonnet-4-20250514", "claude-opus-4-20250514").

fallback_model

str | None

default:"None"

Fallback model if the primary model is unavailable.

betas

list[SdkBeta]

default:"[]"

Beta features to enable. See Anthropic API beta headers.Available: ["context-1m-2025-08-07"]

max_turns

int | None

default:"None"

Maximum number of conversation turns before stopping.

max_budget_usd

float | None

default:"None"

Maximum budget in USD for the session.

continue_conversation

bool

default:"False"

Whether to continue an existing conversation session.

resume

str | None

default:"None"

Session ID to resume from.

fork_session

bool

default:"False"

When true, resumed sessions will fork to a new session ID rather than continuing the previous session.

cwd

str | Path | None

default:"None"

Working directory for the session.

cli_path

str | Path | None

default:"None"

Custom path to the Claude Code CLI executable.

settings

str | None

default:"None"

Path to settings file.

setting_sources

list[SettingSource] | None

default:"None"

Setting sources to load: ["user", "project", "local"]

add_dirs

list[str | Path]

default:"[]"

Additional directories to add to the workspace context.

env

dict[str, str]

default:"{}"

Environment variables for the CLI process.

extra_args

dict[str, str | None]

default:"{}"

Arbitrary CLI flags to pass through.

can_use_tool

CanUseTool | None

default:"None"

Callback function for tool permission requests.

async def permission_callback(
    tool_name: str,
    input: dict[str, Any],
    context: ToolPermissionContext
) -> PermissionResult:
    # Custom permission logic
    return PermissionResultAllow()

hooks

dict[HookEvent, list[HookMatcher]] | None

default:"None"

Hook configurations for lifecycle events.See Hook Types for details.

agents

dict[str, AgentDefinition] | None

default:"None"

Custom agent definitions.

agents={
    "code-reviewer": AgentDefinition(
        description="Reviews code for quality",
        prompt="You are a code reviewer...",
        tools=["Read"],
        model="sonnet"
    )
}

user

str | None

default:"None"

User identifier for the session.

include_partial_messages

bool

default:"False"

Enable streaming of partial message updates via StreamEvent messages.

max_buffer_size

int | None

default:"None"

Maximum bytes when buffering CLI stdout.

stderr

Callable[[str], None] | None

default:"None"

Callback for stderr output from CLI.

def handle_stderr(line: str):
    print(f"CLI stderr: {line}")

options = ClaudeAgentOptions(stderr=handle_stderr)

permission_prompt_tool_name

str | None

default:"None"

Tool name to use for permission prompts.

sandbox

SandboxSettings | None

default:"None"

Sandbox configuration for bash command isolation.

sandbox = {
    "enabled": True,
    "autoAllowBashIfSandboxed": True,
    "excludedCommands": ["docker"],
    "network": {
        "allowUnixSockets": ["/var/run/docker.sock"]
    }
}

Show SandboxSettings fields

enabled

bool

Enable bash sandboxing (macOS/Linux only).

autoAllowBashIfSandboxed

bool

Auto-approve bash commands when sandboxed.

excludedCommands

list[str]

Commands that run outside the sandbox (e.g., ["git", "docker"]).

allowUnsandboxedCommands

bool

Allow commands to bypass sandbox. When False, all commands must run sandboxed.

network

SandboxNetworkConfig

Network configuration.

allowUnixSockets: Unix socket paths accessible in sandbox
allowAllUnixSockets: Allow all Unix sockets (less secure)
allowLocalBinding: Allow binding to localhost ports (macOS only)
httpProxyPort: HTTP proxy port
socksProxyPort: SOCKS5 proxy port

ignoreViolations

SandboxIgnoreViolations

Violations to ignore.

file: File paths to ignore
network: Network hosts to ignore

enableWeakerNestedSandbox

bool

Enable weaker sandbox for unprivileged Docker (Linux only). Reduces security.

plugins

list[SdkPluginConfig]

default:"[]"

Plugin configurations.

plugins=[{"type": "local", "path": "/path/to/plugin"}]

thinking

ThinkingConfig | None

default:"None"

Extended thinking configuration.

{"type": "adaptive"} - Adaptive thinking budget
{"type": "enabled", "budget_tokens": 10000} - Fixed token budget
{"type": "disabled"} - Disable extended thinking

max_thinking_tokens

int | None

default:"None"

Deprecated: Use thinking instead. Maximum tokens for thinking blocks.

effort

Literal['low', 'medium', 'high', 'max'] | None

default:"None"

Effort level for thinking depth.

output_format

dict[str, Any] | None

default:"None"

Output format for structured outputs (matches Messages API structure).

output_format={
    "type": "json_schema",
    "schema": {
        "type": "object",
        "properties": {
            "result": {"type": "string"}
        }
    }
}

enable_file_checkpointing

bool

default:"False"

Enable file checkpointing to track file changes. When enabled, files can be rewound to their state at any user message using ClaudeSDKClient.rewind_files().

PermissionMode - "default" | "acceptEdits" | "plan" | "bypassPermissions"
SdkBeta - "context-1m-2025-08-07"
SettingSource - "user" | "project" | "local"
ToolsPreset - {"type": "preset", "preset": "claude_code"}
SystemPromptPreset - {"type": "preset", "preset": "claude_code", "append": "..."}

Example Usage

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-20250514",
    tools=["Bash", "Read", "Write", "Edit"],
    permission_mode="acceptEdits",
    max_turns=20,
    max_budget_usd=1.0,
    cwd="/path/to/project",
    sandbox={
        "enabled": True,
        "autoAllowBashIfSandboxed": True
    },
    thinking={"type": "adaptive"},
    effort="high"
)

client = ClaudeSDKClient(options)

Core Functions

MCP Tools

Types

ClaudeAgentOptions