ClaudeAgentSDK.Options (claude_agent_sdk v0.11.0)

Configuration options for Claude Code SDK requests.

This struct defines all available options that can be passed to Claude Code CLI. All fields are optional and will be omitted from the CLI command if not provided.

Fields

max_turns - Maximum number of conversation turns (integer)
system_prompt - Custom system prompt to use (string)
append_system_prompt - Additional system prompt to append (string)
output_format - Output format (:text, :json, :stream_json, or structured JSON schema config)
tools - Base tools set selection (--tools) (Python v0.1.12+)
allowed_tools - List of allowed tool names (list of strings)
disallowed_tools - List of disallowed tool names (list of strings)
mcp_servers - Map of MCP server configurations or JSON/path string (v0.5.0+)
mcp_config - Path to MCP configuration file (string, backward compat)
betas - SDK beta feature flags (--betas) (Python v0.1.12+)
permission_prompt_tool - Tool for permission prompts (string)
permission_mode - Permission handling mode (see permission_mode/0)
cwd - Working directory for the CLI (string)
verbose - Enable verbose output (boolean)
executable - Custom executable to run (string)
executable_args - Arguments for custom executable (list of strings)
path_to_claude_code_executable - Path to Claude Code CLI (string)
abort_ref - Reference for aborting requests (reference)
hooks - Hook configurations (see ClaudeAgentSDK.Hooks.hook_config/0)
timeout_ms - Command execution timeout in milliseconds (integer, default: 4_500_000)
sandbox - Sandbox settings merged into --settings JSON when present (Python v0.1.12+)
enable_file_checkpointing - Enables file checkpointing + rewind_files (Python v0.1.15+)
include_partial_messages - Enable character-level streaming (boolean) (v0.8.0+)
stream_buffer_limit - Max inbound entries buffered before first subscriber (integer, default: 1000)
preferred_transport - Override automatic transport selection (:auto | :cli | :control) (v0.8.0+)

Streaming + Tools (v0.8.0)

The SDK automatically selects the appropriate transport:

CLI-only: Fast streaming without control features (no hooks, MCP, or permissions)
Control client: Full features with streaming (hooks + partial messages)

Override with preferred_transport:

:auto - Automatic selection (default)
:cli - Force CLI-only mode (ignores control features)
:control - Force control client (even without features)

Examples

# Basic configuration
%ClaudeAgentSDK.Options{
  max_turns: 5,
  output_format: :stream_json,
  verbose: true
}

# Advanced configuration
%ClaudeAgentSDK.Options{
  system_prompt: "You are a helpful coding assistant",
  allowed_tools: ["editor", "bash"],
  permission_mode: :accept_edits,
  cwd: "/path/to/project"
}

# Streaming with tools (v0.8.0)
%ClaudeAgentSDK.Options{
  include_partial_messages: true,
  hooks: %{pre_tool_use: [...]},
  mcp_servers: %{"math" => sdk_server}
}
# → Automatically selects control client with streaming enabled

Summary

Types

agent_definition()

agent_name()

external_mcp_server()

External MCP server (stdio, sse, or http)

http_mcp_server()

HTTP MCP server configuration (HTTP transport). Headers is optional (defaults to empty map if not provided).

mcp_server()

MCP server (either SDK or external)

model_name()

output_format()

permission_mode()

plugin_config()

Plugin configuration supported by the SDK (currently local directories only).

sdk_beta()

SDK beta feature flag.

sdk_mcp_server()

SDK MCP server configuration (in-process)

sse_mcp_server()

SSE MCP server configuration (Server-Sent Events). Headers is optional (defaults to empty map if not provided).

stdio_mcp_server()

External MCP server configuration (subprocess via stdio)

structured_output_format()

t()

tools_option()

Tools option - controls the base set of available tools.

tools_preset()

Tools preset configuration.

transport_preference()

Functions

agents_for_initialize(agents)

Converts the agents map to CLI-compatible format for the initialize request.

new(attrs \\ [])

Creates a new Options struct with the given attributes.

prepare_servers_for_cli(servers)

Prepares MCP server configurations for the Claude CLI.

to_args(options)

Converts the options to command line arguments for the Claude CLI.

validate_agents(options)

Validates agent configuration in Options.

Types

agent_definition()

@type agent_definition() :: ClaudeAgentSDK.Agent.t()

agent_name()

@type agent_name() :: atom()

external_mcp_server()

@type external_mcp_server() ::
  stdio_mcp_server() | sse_mcp_server() | http_mcp_server()

External MCP server (stdio, sse, or http)

http_mcp_server()

@type http_mcp_server() :: %{
  :type => :http,
  :url => String.t(),
  optional(:headers) => %{required(String.t()) => String.t()}
}

HTTP MCP server configuration (HTTP transport). Headers is optional (defaults to empty map if not provided).

mcp_server()

@type mcp_server() :: sdk_mcp_server() | external_mcp_server()

MCP server (either SDK or external)

model_name()

@type model_name() :: String.t()

output_format()

@type output_format() :: :text | :json | :stream_json | structured_output_format()

permission_mode()

@type permission_mode() ::
  :default | :accept_edits | :bypass_permissions | :plan | :delegate | :dont_ask

plugin_config()

@type plugin_config() :: %{type: :local | String.t(), path: String.t()}

Plugin configuration supported by the SDK (currently local directories only).

sdk_beta()

@type sdk_beta() :: String.t()

SDK beta feature flag.

sdk_mcp_server()

@type sdk_mcp_server() :: %{
  type: :sdk,
  name: String.t(),
  version: String.t(),
  registry_pid: pid()
}

SDK MCP server configuration (in-process)

sse_mcp_server()

@type sse_mcp_server() :: %{
  :type => :sse,
  :url => String.t(),
  optional(:headers) => %{required(String.t()) => String.t()}
}

SSE MCP server configuration (Server-Sent Events). Headers is optional (defaults to empty map if not provided).

stdio_mcp_server()

@type stdio_mcp_server() :: %{type: :stdio, command: String.t(), args: [String.t()]}

External MCP server configuration (subprocess via stdio)

structured_output_format()

@type structured_output_format() ::
  {:json_schema, map()}
  | %{
      :type => :json_schema | String.t(),
      :schema => map(),
      optional(:output_format) => :json | :stream_json | String.t()
    }

t()

@type t() :: %ClaudeAgentSDK.Options{
  abort_ref: reference() | nil,
  add_dir: [String.t()] | nil,
  add_dirs: [String.t()] | nil,
  agent: agent_name() | nil,
  agents: %{required(agent_name()) => agent_definition()} | nil,
  allowed_tools: [String.t()] | nil,
  append_system_prompt: String.t() | nil,
  betas: [sdk_beta()] | nil,
  can_use_tool: ClaudeAgentSDK.Permission.callback() | nil,
  continue_conversation: boolean() | nil,
  cwd: String.t() | nil,
  disallowed_tools: [String.t()] | nil,
  enable_file_checkpointing: boolean() | nil,
  env: %{optional(String.t()) => String.t()},
  executable: String.t() | nil,
  executable_args: [String.t()] | nil,
  extra_args: %{optional(String.t()) => String.t() | boolean() | nil},
  fallback_model: model_name() | nil,
  fork_session: boolean() | nil,
  hooks: ClaudeAgentSDK.Hooks.hook_config() | nil,
  include_partial_messages: boolean() | nil,
  max_budget_usd: number() | nil,
  max_buffer_size: pos_integer() | nil,
  max_thinking_tokens: pos_integer() | nil,
  max_turns: integer() | nil,
  mcp_config: String.t() | nil,
  mcp_servers: %{required(String.t()) => mcp_server()} | String.t() | nil,
  model: model_name() | nil,
  output_format: output_format() | nil,
  path_to_claude_code_executable: String.t() | nil,
  permission_mode: permission_mode() | nil,
  permission_prompt_tool: String.t() | nil,
  plugins: [plugin_config()],
  preferred_transport: transport_preference() | nil,
  resume: String.t() | nil,
  sandbox: map() | nil,
  session_id: String.t() | nil,
  setting_sources: [String.t() | atom()] | nil,
  settings: String.t() | nil,
  stderr: (String.t() -> any()) | nil,
  stream_buffer_limit: non_neg_integer() | nil,
  strict_mcp_config: boolean() | nil,
  system_prompt: String.t() | map() | nil,
  timeout_ms: integer() | nil,
  tools: tools_option(),
  user: String.t() | nil,
  verbose: boolean() | nil
}

tools_option()

@type tools_option() :: [String.t()] | tools_preset() | map() | nil

Tools option - controls the base set of available tools.

Supported forms:

List of tool names: ["Read", "Edit"]
Empty list: [] (disables all built-in tools)
Preset map: %{type: :preset, preset: :claude_code} (maps to "default")

tools_preset()

@type tools_preset() :: %{
  type: :preset | String.t(),
  preset: :claude_code | String.t()
}

Tools preset configuration.

transport_preference()

@type transport_preference() :: :auto | :cli | :control

Functions

agents_for_initialize(agents)

@spec agents_for_initialize(%{required(agent_name()) => agent_definition()} | nil) ::
  map() | nil

Converts the agents map to CLI-compatible format for the initialize request.

Transforms %{atom_name => Agent.t()} to %{"string_name" => cli_map}.

Parameters

agents - Map of atom names to Agent structs

Returns

Map of string names to CLI-compatible maps, or nil if no agents.

new(attrs \\ [])

@spec new(keyword()) :: t()

Creates a new Options struct with the given attributes.

Parameters

attrs - Keyword list of attributes to set (keyword list)

Returns

A new ClaudeAgentSDK.Options.t/0 struct with the specified attributes.

Examples

ClaudeAgentSDK.Options.new(
  max_turns: 5,
  output_format: :json,
  verbose: true
)

# Empty options (all defaults)
ClaudeAgentSDK.Options.new()

prepare_servers_for_cli(servers)

@spec prepare_servers_for_cli(%{required(String.t()) => mcp_server()}) :: %{
  required(String.t()) => map()
}

Prepares MCP server configurations for the Claude CLI.

SDK servers: Strips the registry_pid field (CLI doesn't need it) External servers: Passed through as-is

Parameters

servers - Map of server name to server configuration

Returns

Map ready to be JSON-encoded for --mcp-config argument

to_args(options)

@spec to_args(t()) :: [String.t()]

Converts the options to command line arguments for the Claude CLI.

Parameters

options - The options struct to convert

Returns

A list of strings representing CLI arguments.

Examples

options = %ClaudeAgentSDK.Options{max_turns: 5, verbose: true}
ClaudeAgentSDK.Options.to_args(options)
# => ["--max-turns", "5", "--verbose"]

validate_agents(options)

@spec validate_agents(t()) :: :ok | {:error, term()}

Validates agent configuration in Options.

Ensures that:

All agents in the agents map are valid Agent structs
If an active agent is specified, it exists in the agents map
Agents and agent fields have correct types

Parameters

options - Options struct to validate

Returns

:ok if validation succeeds
{:error, reason} if validation fails

Examples

options = Options.new(
  agents: %{test: Agent.new(description: "Test", prompt: "Test")},
  agent: :test
)
Options.validate_agents(options)
#=> :ok

invalid = Options.new(
  agents: %{test: Agent.new(description: "Test", prompt: "Test")},
  agent: :nonexistent
)
Options.validate_agents(invalid)
#=> {:error, {:agent_not_found, :nonexistent}}