# `ClaudeAgentSDK.Options`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.14.0/lib/claude_agent_sdk/options.ex#L1)

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 `t: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 `t: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

# `agent_definition`

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

# `agent_name`

```elixir
@type agent_name() :: atom()
```

# `external_mcp_server`

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

External MCP server (stdio, sse, or http)

# `http_mcp_server`

```elixir
@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`

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

MCP server (either SDK or external)

# `model_name`

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

# `output_format`

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

# `permission_mode`

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

# `plugin_config`

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

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

# `sdk_beta`

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

SDK beta feature flag.

# `sdk_mcp_server`

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

SDK MCP server configuration (in-process)

# `sse_mcp_server`

```elixir
@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`

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

External MCP server configuration (subprocess via stdio)

# `structured_output_format`

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

# `t`

```elixir
@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`

```elixir
@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`

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

Tools preset configuration.

# `transport_preference`

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

# `agents_for_initialize`

```elixir
@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`

```elixir
@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 `t: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`

```elixir
@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`

```elixir
@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`

```elixir
@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}}

---

*Consult [api-reference.md](api-reference.md) for complete listing*