ClaudeAgentOptions Configuration Reference

Location and Type

ClaudeAgentOptions is defined as a Python dataclass in src/claude_agent_sdk/types.py716-784 It is re-exported from claude_agent_sdk.__init__ and is the primary configuration surface for all SDK entry points.

Definition overview:

@dataclass
class ClaudeAgentOptions:
    """Configuration options for Claude agent."""
    # Defined in src/claude_agent_sdk/types.py, lines 716–784

The following diagram maps the dataclass fields to the CLI flags and internal subsystems they control.

Field-to-Subsystem Map

Diagram: ClaudeAgentOptions field routing

Sources: src/claude_agent_sdk/types.py716-784 src/claude_agent_sdk/_internal/transport/subprocess_cli.py166-260 tests/test_transport.py39-134

Complete Field Reference

System Prompt

Field	Type	Default	CLI flag
`system_prompt`	`str	SystemPromptPreset	SystemPromptFile

Controls the system prompt sent to Claude.

str: Passed verbatim as --system-prompt <value>.
SystemPromptPreset: Uses the built-in Claude Code system prompt. If an append key is present, --append-system-prompt <value> is added.
SystemPromptFile: Uses a prompt stored in a file via --system-prompt-file <path>.
None (default): Passes --system-prompt "" — an empty system prompt.

Tool Selection and Skills

Field	Type	Default	CLI flag
`tools`	`list[str]	ToolsPreset	None`
`allowed_tools`	`list[str]`	`[]`	`--allowedTools`
`disallowed_tools`	`list[str]`	`[]`	`--disallowedTools`
`skills`	`Literal["all"]	list[str]	None`

Model Selection

Field	Type	Default	CLI flag
`model`	`str	None`	`None`
`fallback_model`	`str	None`	`None`

Permission Mode and Callbacks

Field	Type	Default	CLI flag
`permission_mode`	`PermissionMode	None`	`None`
`can_use_tool`	`CanUseTool	None`	`None`

Lifecycle Hooks and Agents

Field	Type	Default
`hooks`	`dict[HookEvent, list[HookMatcher]]	None`
`agents`	`dict[str, AgentDefinition]	None`

Session and Resource Limits

Field	Type	Default	CLI flag
`continue_conversation`	`bool`	`False`	`--continue`
`resume`	`str	None`	`None`
`max_turns`	`int	None`	`None`
`max_budget_usd`	`float	None`	`None`
`task_budget`	`TaskBudget	None`	`None`

Thinking Configuration

Field	Type	Default	CLI flag
`thinking`	`ThinkingConfig	None`	`None`
`effort`	`Literal["low","medium","high","max"]	int	None`
`max_thinking_tokens`	`int	None`	`None`

Environment and Sources

Field	Type	Default	CLI flag
`setting_sources`	`list[SettingSource]	None`	`None`
`mcp_servers`	`dict[str, McpServerConfig]	str	Path`