[DOCS] `ClaudeAgentOptions` code block missing implemented fields in Python SDK reference

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://platform.claude.com/docs/en/agent-sdk/python

Section/Topic

The ClaudeAgentOptions class definition snippet within the Types section.

Current Documentation

The current code block provided for the ClaudeAgentOptions dataclass is truncated and omits several fields that are actually supported and implemented in the SDK:

@dataclass
class ClaudeAgentOptions:
    allowed_tools: list[str] = field(default_factory=list)
    system_prompt: str | SystemPromptPreset | None = None
    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
    permission_mode: PermissionMode | None = None
    continue_conversation: bool = False
    resume: str | None = None
    max_turns: int | None = None
    disallowed_tools: list[str] = field(default_factory=list)
    # ... (several fields listed) ...
    setting_sources: list[SettingSource] | None = None

What's Wrong or Missing?

The primary code block defining ClaudeAgentOptions is missing critical fields that are present in the SDK source code and, in some cases, described in the table below the snippet. This creates an inconsistency where users copying the type definition for their own type-checking or documentation will have an incomplete model.

Specifically, the following fields are missing from the code snippet:

• cli_path: str | Path | None = None
• enable_file_checkpointing: bool = False
• max_thinking_tokens: int | None = None
• fallback_model: str | None = None
• max_budget_usd: float | None = None
• betas: list[SdkBeta] = field(default_factory=list)
• plugins: list[SdkPluginConfig] = field(default_factory=list)
• sandbox: SandboxSettings | None = None

Suggested Improvement

Update the ClaudeAgentOptions code block in https://platform.claude.com/docs/en/agent-sdk/python to match the actual implementation in the source code.

Suggested Text:

@dataclass
class ClaudeAgentOptions:
    tools: list[str] | ToolsPreset | None = None
    allowed_tools: list[str] = field(default_factory=list)
    system_prompt: str | SystemPromptPreset | None = None
    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
    permission_mode: PermissionMode | None = None
    continue_conversation: bool = False
    resume: str | None = None
    max_turns: int | None = None
    max_budget_usd: float | None = None
    disallowed_tools: list[str] = field(default_factory=list)
    model: str | None = None
    fallback_model: str | None = None
    betas: list[SdkBeta] = field(default_factory=list)
    permission_prompt_tool_name: str | None = None
    cwd: str | Path | None = None
    cli_path: str | Path | None = None
    settings: str | None = None
    add_dirs: list[str | Path] = field(default_factory=list)
    env: dict[str, str] = field(default_factory=dict)
    extra_args: dict[str, str | None] = field(default_factory=dict)
    max_buffer_size: int | None = None
    debug_stderr: Any = sys.stderr
    stderr: Callable[[str], None] | None = None
    can_use_tool: CanUseTool | None = None
    hooks: dict[HookEvent, list[HookMatcher]] | None = None
    user: str | None = None
    include_partial_messages: bool = False
    fork_session: bool = False
    agents: dict[str, AgentDefinition] | None = None
    setting_sources: list[SettingSource] | None = None
    sandbox: SandboxSettings | None = None
    plugins: list[SdkPluginConfig] = field(default_factory=list)
    max_thinking_tokens: int | None = None
    output_format: dict[str, Any] | None = None
    enable_file_checkpointing: bool = False

Impact

High - Prevents users from using a feature

Additional Context

• The source of truth for these fields can be found in the repository at src/claude_agent_sdk/types.py.
• Discrepancies between the code snippet and the detailed property table below it can lead to confusion for developers trying to implement advanced features like file checkpointing or custom CLI paths.