ClaudeAgentSDK.Options (claude_agent_sdk v0.6.9)

View Source

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 (SDK and external servers) (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.6.0+)

  • preferred_transport - Override automatic transport selection (:auto | :cli | :control) (v0.6.0+)

Streaming + Tools (v0.6.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.6.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 configuration (subprocess)

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)

structured_output_format()
t()
tools_option()

Tools option - controls the base set of available tools.

tools_preset()

Tools preset configuration.

transport_preference()

Functions

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() :: %{
  type: :stdio | :sse | :http,
  command: String.t(),
  args: [String.t()]
}

External MCP server configuration (subprocess)

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

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)

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()} | 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,
  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

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}}