ClaudeAgentSDK.Options (claude_agent_sdk v0.5.3)

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, or :stream_json)
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)
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)

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

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

sdk_mcp_server()

SDK MCP server configuration (in-process)

t()

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

permission_mode()

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

sdk_mcp_server()

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

SDK MCP server configuration (in-process)

t()

@type t() :: %ClaudeAgentSDK.Options{
  abort_ref: reference() | nil,
  add_dir: [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,
  can_use_tool: ClaudeAgentSDK.Permission.callback() | nil,
  cwd: String.t() | nil,
  disallowed_tools: [String.t()] | nil,
  executable: String.t() | nil,
  executable_args: [String.t()] | nil,
  fallback_model: model_name() | nil,
  fork_session: boolean() | nil,
  hooks: ClaudeAgentSDK.Hooks.hook_config() | 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,
  session_id: String.t() | nil,
  strict_mcp_config: boolean() | nil,
  system_prompt: String.t() | nil,
  timeout_ms: term(),
  verbose: boolean() | nil
}

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