# ClaudeAgentOptions Configuration Reference

## Location and Type

`ClaudeAgentOptions` is defined as a Python `dataclass` in [src/claude_agent_sdk/types.py716-784](https://github.com/anthropics/claude-agent-sdk-python/blob/7ca64f67/src/claude_agent_sdk/types.py#L716-L784) 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](https://github.com/anthropics/claude-agent-sdk-python/blob/7ca64f67/src/claude_agent_sdk/types.py#L716-L784) [src/claude_agent_sdk/_internal/transport/subprocess_cli.py166-260](https://github.com/anthropics/claude-agent-sdk-python/blob/7ca64f67/src/claude_agent_sdk/_internal/transport/subprocess_cli.py#L166-L260) [tests/test_transport.py39-134](https://github.com/anthropics/claude-agent-sdk-python/blob/7ca64f67/tests/test_transport.py#L39-L134)

## Complete Field Reference

### System Prompt

| Field | Type | Default | CLI flag |
| --- | --- | --- | --- |
| `system_prompt` | `str | SystemPromptPreset | SystemPromptFile | None` | `None` | `--system-prompt`, `--append-system-prompt`, or `--system-prompt-file` |

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` | `None` | `--tools` |
| `allowed_tools` | `list[str]` | `[]` | `--allowedTools` |
| `disallowed_tools` | `list[str]` | `[]` | `--disallowedTools` |
| `skills` | `Literal["all"] | list[str] | None` | `None` | `--skills` |

### Model Selection

| Field | Type | Default | CLI flag |
| --- | --- | --- | --- |
| `model` | `str | None` | `None` | `--model` |
| `fallback_model` | `str | None` | `None` | `--fallback-model` |

### Permission Mode and Callbacks

| Field | Type | Default | CLI flag |
| --- | --- | --- | --- |
| `permission_mode` | `PermissionMode | None` | `None` | `--permission-mode` |
| `can_use_tool` | `CanUseTool | None` | `None` | N/A |

### Lifecycle Hooks and Agents

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

### Session and Resource Limits

| Field | Type | Default | CLI flag |
| --- | --- | --- | --- |
| `continue_conversation` | `bool` | `False` | `--continue` |
| `resume` | `str | None` | `None` | `--resume <session_id>` |
| `max_turns` | `int | None` | `None` | `--max-turns` |
| `max_budget_usd` | `float | None` | `None` | `--max-budget-usd` |
| `task_budget` | `TaskBudget | None` | `None` | `--max-budget-tokens` |

### Thinking Configuration

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

### Environment and Sources

| Field | Type | Default | CLI flag |
| --- | --- | --- | --- |
| `setting_sources` | `list[SettingSource] | None` | `None` | N/A |
| `mcp_servers` | `dict[str, McpServerConfig] | str | Path` | `{}` | `--mcp-config` |