Struct ClaudeAgentOptions 

pub struct ClaudeAgentOptions {

    pub tools: Option<ToolsOption>,
    pub allowed_tools: Vec<String>,
    pub system_prompt: Option<SystemPrompt>,
    pub mcp_servers: McpServersOption,
    pub permission_mode: Option<PermissionMode>,
    pub continue_conversation: bool,
    pub resume: Option<String>,
    pub max_turns: Option<i64>,
    pub max_budget_usd: Option<f64>,
    pub disallowed_tools: Vec<String>,
    pub model: Option<String>,
    pub fallback_model: Option<String>,
    pub betas: Vec<String>,
    pub permission_prompt_tool_name: Option<String>,
    pub cwd: Option<PathBuf>,
    pub cli_path: Option<PathBuf>,
    pub settings: Option<String>,
    pub add_dirs: Vec<PathBuf>,
    pub env: HashMap<String, String>,
    pub extra_args: HashMap<String, Option<String>>,
    pub max_buffer_size: Option<usize>,
    pub can_use_tool: Option<CanUseToolCallback>,
    pub hooks: Option<HashMap<String, Vec<HookMatcher>>>,
    pub user: Option<String>,
    pub include_partial_messages: bool,
    pub fork_session: bool,
    pub agents: Option<HashMap<String, AgentDefinition>>,
    pub setting_sources: Option<Vec<SettingSource>>,
    pub sandbox: Option<SandboxSettings>,
    pub strict_settings_merge: bool,
    pub plugins: Vec<SdkPluginConfig>,
    pub max_thinking_tokens: Option<i64>,
    pub thinking: Option<ThinkingConfig>,
    pub effort: Option<String>,
    pub output_format: Option<Value>,
    pub enable_file_checkpointing: bool,
    pub stderr: Option<StderrCallback>,
}

Main configuration for Claude Code queries and sessions.

This is the primary configuration struct passed to query() or ClaudeSdkClient::new(). All fields are optional and have sensible defaults.

Corresponds to the Python SDK’s ClaudeAgentOptions dataclass.

Fields

Field	Description
tools	Tools configuration — explicit list or preset
allowed_tools	List of allowed tool names
system_prompt	System prompt — custom text or preset
mcp_servers	MCP server configurations
permission_mode	Permission mode for tool usage
continue_conversation	Continue the most recent conversation
resume	Session ID to resume
max_turns	Maximum conversation turns
max_budget_usd	Maximum budget in USD for the session
disallowed_tools	List of disallowed tool names
model	Claude model to use
fallback_model	Fallback model if the primary fails
betas	Beta features to enable
permission_prompt_tool_name	MCP tool name for permission prompts
cwd	Current working directory
cli_path	Custom path to the Claude Code CLI executable
settings	Path to settings file or inline JSON
add_dirs	Additional directories Claude can access
env	Environment variables
extra_args	Additional CLI arguments
max_buffer_size	Maximum bytes when buffering CLI stdout
can_use_tool	Tool permission callback function
hooks	Hook configurations for intercepting events
user	User identifier
include_partial_messages	Include StreamEvent partial messages
fork_session	Fork to new session ID when resuming
agents	Programmatically defined subagents
setting_sources	Which filesystem settings to load
sandbox	Sandbox configuration
strict_settings_merge	Fail instead of warn when sandbox/settings JSON merge fails
plugins	Local plugins to load
max_thinking_tokens	Deprecated: use thinking instead
thinking	Extended thinking configuration
effort	Effort level ("low", "medium", "high", "max")
output_format	Structured output format (e.g., JSON schema)
enable_file_checkpointing	Enable file change tracking for rewinding

Fields

tools: Option<ToolsOption>

Tools configuration. Use ToolsOption::Preset with ToolsPreset::default() for Claude Code’s default tools.

allowed_tools: Vec<String>

List of allowed tool names.

system_prompt: Option<SystemPrompt>

System prompt configuration. Pass a string via SystemPrompt::Text for a custom prompt, or use SystemPrompt::Preset for Claude Code’s built-in system prompt.

mcp_servers: McpServersOption

MCP server configurations or path to config file.

permission_mode: Option<PermissionMode>

Permission mode for tool usage.

continue_conversation: bool

Continue the most recent conversation.

resume: Option<String>

Session ID to resume.

max_turns: Option<i64>

Maximum conversation turns.

max_budget_usd: Option<f64>

Maximum budget in USD for the session.

disallowed_tools: Vec<String>

List of disallowed tool names.

model: Option<String>

Claude model to use (e.g., "sonnet", "opus").

fallback_model: Option<String>

Fallback model to use if the primary model fails.

betas: Vec<String>

Beta features to enable.

permission_prompt_tool_name: Option<String>

MCP tool name for permission prompts. Mutually exclusive with can_use_tool.

cwd: Option<PathBuf>

Current working directory for the Claude Code process.

cli_path: Option<PathBuf>

Custom path to the Claude Code CLI executable.

settings: Option<String>

Path to settings file or inline JSON string.

add_dirs: Vec<PathBuf>

Additional directories Claude can access.

env: HashMap<String, String>

Environment variables to pass to the CLI process.

extra_args: HashMap<String, Option<String>>

Additional CLI arguments to pass directly to the CLI. Keys are flag names (without --), values are optional flag values.

max_buffer_size: Option<usize>

Maximum bytes when buffering CLI stdout. Defaults to 1MB.

can_use_tool: Option<CanUseToolCallback>

Custom tool permission callback function.

hooks: Option<HashMap<String, Vec<HookMatcher>>>

Hook configurations for intercepting events. Keys are hook event names (e.g., "PreToolUse", "PostToolUse", "UserPromptSubmit").

user: Option<String>

User identifier.

include_partial_messages: bool

Include partial message streaming events (StreamEvent).

fork_session: bool

When resuming with resume, fork to a new session ID instead of continuing the original session.

agents: Option<HashMap<String, AgentDefinition>>

Programmatically defined subagents.

setting_sources: Option<Vec<SettingSource>>

Control which filesystem settings to load. When omitted, no settings are loaded (SDK isolation).

sandbox: Option<SandboxSettings>

Sandbox configuration for command execution isolation.

strict_settings_merge: bool

When true, fail command construction if sandbox merge with settings fails. When false, merge failures emit a warning and fallback to sandbox-only settings.

plugins: Vec<SdkPluginConfig>

Local plugins to load.

max_thinking_tokens: Option<i64>

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

thinking: Option<ThinkingConfig>

Extended thinking configuration. Takes precedence over max_thinking_tokens.

effort: Option<String>

Effort level for thinking depth ("low", "medium", "high", "max").

output_format: Option<Value>

Output format for structured responses. Example: {"type": "json_schema", "schema": {...}}

enable_file_checkpointing: bool

Enable file change tracking for rewinding via ClaudeSdkClient::rewind_files().

stderr: Option<StderrCallback>

Optional callback for stderr output lines from the CLI process.

When set, stderr is piped and each non-empty line is passed to this callback. When None, stderr is still drained to prevent subprocess blocking, but lines are discarded.

Trait Implementations

impl Clone for ClaudeAgentOptions

fn clone(&self) -> ClaudeAgentOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for ClaudeAgentOptions

fn default() -> Self

Returns the “default value” for a type.