Struct ClaudeCodeOptions 

pub struct ClaudeCodeOptions {

    pub system_prompt_v2: Option<SystemPrompt>,
    pub system_prompt: Option<String>,
    pub append_system_prompt: Option<String>,
    pub allowed_tools: Vec<String>,
    pub disallowed_tools: Vec<String>,
    pub permission_mode: PermissionMode,
    pub mcp_servers: HashMap<String, McpServerConfig>,
    pub mcp_tools: Vec<String>,
    pub max_turns: Option<i32>,
    pub max_thinking_tokens: i32,
    pub max_output_tokens: Option<u32>,
    pub model: Option<String>,
    pub cwd: Option<PathBuf>,
    pub continue_conversation: bool,
    pub resume: Option<String>,
    pub permission_prompt_tool_name: Option<String>,
    pub settings: Option<String>,
    pub add_dirs: Vec<PathBuf>,
    pub extra_args: HashMap<String, Option<String>>,
    pub env: HashMap<String, String>,
    pub debug_stderr: Option<Arc<Mutex<dyn Write + Send + Sync>>>,
    pub include_partial_messages: bool,
    pub can_use_tool: Option<Arc<dyn CanUseTool>>,
    pub hooks: Option<HashMap<String, Vec<HookMatcher>>>,
    pub control_protocol_format: ControlProtocolFormat,
    pub setting_sources: Option<Vec<SettingSource>>,
    pub fork_session: bool,
    pub agents: Option<HashMap<String, AgentDefinition>>,
    pub cli_channel_buffer_size: Option<usize>,
    pub tools: Option<ToolsConfig>,
    pub betas: Vec<SdkBeta>,
    pub max_budget_usd: Option<f64>,
    pub fallback_model: Option<String>,
    pub output_format: Option<Value>,
    pub enable_file_checkpointing: bool,
    pub sandbox: Option<SandboxSettings>,
    pub plugins: Vec<SdkPluginConfig>,
    pub user: Option<String>,
    pub stderr_callback: Option<Arc<dyn Fn(&str) + Send + Sync>>,
    pub auto_download_cli: bool,
}

Configuration options for Claude Code SDK

Fields

system_prompt_v2: Option<SystemPrompt>

System prompt configuration (simplified in v0.1.12+) Can be either a string or a preset configuration Replaces the old system_prompt and append_system_prompt fields

system_prompt: Option<String>

👎Deprecated since 0.1.12: Use system_prompt_v2 instead

[DEPRECATED] System prompt to prepend to all messages Use system_prompt_v2 instead

append_system_prompt: Option<String>

👎Deprecated since 0.1.12: Use system_prompt_v2 instead

[DEPRECATED] Additional system prompt to append Use system_prompt_v2 instead

allowed_tools: Vec<String>

List of allowed tools (auto-approval permissions only)

IMPORTANT: This only controls which tool invocations are auto-approved (bypass permission prompts). It does NOT disable or restrict which tools the AI can use. Use disallowed_tools to completely disable tools.

Example: allowed_tools: vec!["Bash(git:*)".to_string()] allows auto-approval for git commands in Bash, but doesn’t prevent AI from using other tools.

disallowed_tools: Vec<String>

List of disallowed tools (completely disabled)

IMPORTANT: This completely disables the specified tools. The AI will not be able to use these tools at all. Use this to restrict which tools the AI has access to.

Example: disallowed_tools: vec!["Bash".to_string(), "WebSearch".to_string()] prevents the AI from using Bash or WebSearch tools entirely.

permission_mode: PermissionMode

Permission mode for tool execution

mcp_servers: HashMap<String, McpServerConfig>

MCP server configurations

mcp_tools: Vec<String>

MCP tools to enable

max_turns: Option<i32>

Maximum number of conversation turns

max_thinking_tokens: i32

Maximum thinking tokens

max_output_tokens: Option<u32>

Maximum output tokens per response (1-32000, overrides CLAUDE_CODE_MAX_OUTPUT_TOKENS env var)

model: Option<String>

Model to use

cwd: Option<PathBuf>

Working directory

continue_conversation: bool

Continue from previous conversation

resume: Option<String>

Resume from a specific conversation ID

permission_prompt_tool_name: Option<String>

Custom permission prompt tool name

settings: Option<String>

Settings file path for Claude Code CLI

add_dirs: Vec<PathBuf>

Additional directories to add as working directories

extra_args: HashMap<String, Option<String>>

Extra arbitrary CLI flags

env: HashMap<String, String>

Environment variables to pass to the process

debug_stderr: Option<Arc<Mutex<dyn Write + Send + Sync>>>

Debug output stream (e.g., stderr)

include_partial_messages: bool

Include partial assistant messages in streaming output

can_use_tool: Option<Arc<dyn CanUseTool>>

Tool permission callback

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

Hook configurations

control_protocol_format: ControlProtocolFormat

Control protocol format (defaults to Legacy for compatibility)

setting_sources: Option<Vec<SettingSource>>

Setting sources to load (user, project, local) When None, no filesystem settings are loaded (matches Python SDK v0.1.0 behavior)

fork_session: bool

Fork session when resuming instead of continuing When true, creates a new branch from the resumed session

agents: Option<HashMap<String, AgentDefinition>>

Programmatic agent definitions Define agents inline without filesystem dependencies

cli_channel_buffer_size: Option<usize>

CLI channel buffer size for internal communication channels Controls the size of message, control, and stdin buffers (default: 100) Increase for high-throughput scenarios to prevent message lag

tools: Option<ToolsConfig>

Tools configuration for controlling available tools

This controls the base set of tools available to Claude, distinct from allowed_tools which only controls auto-approval permissions.

Examples

use cc_sdk::{ClaudeCodeOptions, ToolsConfig};

// Enable specific tools only
let options = ClaudeCodeOptions::builder()
    .tools(ToolsConfig::list(vec!["Read".into(), "Edit".into()]))
    .build();

// Disable all built-in tools
let options = ClaudeCodeOptions::builder()
    .tools(ToolsConfig::none())
    .build();

// Use claude_code preset
let options = ClaudeCodeOptions::builder()
    .tools(ToolsConfig::claude_code_preset())
    .build();

betas: Vec<SdkBeta>

SDK beta features to enable See https://docs.anthropic.com/en/api/beta-headers

max_budget_usd: Option<f64>

Maximum spending limit in USD for the session When exceeded, the session will automatically terminate

fallback_model: Option<String>

Fallback model to use when primary model is unavailable

output_format: Option<Value>

Output format for structured outputs Example: {"type": "json_schema", "schema": {"type": "object", "properties": {...}}}

enable_file_checkpointing: bool

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

sandbox: Option<SandboxSettings>

Sandbox configuration for bash command isolation Filesystem and network restrictions are derived from permission rules

plugins: Vec<SdkPluginConfig>

Plugin configurations for custom plugins

user: Option<String>

Run the CLI subprocess as a specific OS user (Unix-only).

This matches Python SDK behavior (anyio.open_process(user=...)).

• Supported on Unix platforms only (non-Unix returns SdkError::NotSupported)
• Typically requires elevated privileges to switch users
• Accepts a username (e.g. "nobody") or a numeric uid string (e.g. "1000")

stderr_callback: Option<Arc<dyn Fn(&str) + Send + Sync>>

Stderr callback (alternative to debug_stderr) Called with each line of stderr output from the CLI

auto_download_cli: bool

Automatically download Claude Code CLI if not found

When enabled, the SDK will automatically download and cache the Claude Code CLI binary if it’s not found in the system PATH or common installation locations.

The CLI is cached in:

• macOS: ~/Library/Caches/cc-sdk/cli/
• Linux: ~/.cache/cc-sdk/cli/
• Windows: %LOCALAPPDATA%\cc-sdk\cli\

Example

let options = ClaudeCodeOptions::builder()
    .auto_download_cli(true)
    .build();

Implementations

impl ClaudeCodeOptions

pub fn builder() -> ClaudeCodeOptionsBuilder

Create a new options builder

Trait Implementations

impl Clone for ClaudeCodeOptions

fn clone(&self) -> ClaudeCodeOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ClaudeCodeOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ClaudeCodeOptions

fn default() -> ClaudeCodeOptions

Returns the “default value” for a type.