[DOCS] Python SDK ClaudeAgentOptions Code Block Missing import sys Statement

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The ClaudeAgentOptions dataclass definition in the "Types" section (lines 453-488).

Current Documentation

@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)
    output_format: OutputFormat | None = None
    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  # Deprecated  <-- USES sys WITHOUT IMPORT
    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
    max_thinking_tokens: int | None = None

What's Wrong or Missing?

Line 478 uses sys.stderr as a default value, but the code block has no import sys statement. If a developer copies this dataclass definition directly, they will get a NameError: name 'sys' is not defined.

The properties table at line 515 confirms the default is sys.stderr, but the code snippet doesn't include the necessary import.

Suggested Improvement

Add the import statement at the beginning of the code block:

import sys
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Callable

@dataclass
class ClaudeAgentOptions:
    # ... rest of the class

Alternatively, since debug_stderr is marked as deprecated, consider:

1. Removing it from the code example entirely, or
2. Using None as the default with a comment explaining the actual default behavior

Impact

Medium - Makes feature difficult to understand

Additional Context

• Mirror location: platform.claude.com/docs/en/agent-sdk/python.md (line 478)
• The debug_stderr field is marked as deprecated, which may explain why the import was overlooked
• Other type hints in the same block (like Path, Callable, Any) would also require imports that aren't shown