[DOCS] Python examples pass raw dicts to `options` parameter instead of `ClaudeAgentOptions` instances

Documentation Type

unclear/confusing documentation

Documentation Location

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

Section/Topic

Multiple Python code examples across several guide pages

Current Documentation

async for message in query(
prompt="/compact",
options={"max_turns": 1}  # Raw dict instead of ClaudeAgentOptions
):

What's Wrong or Missing?

The Python SDK Reference defines the query() function signature as:

async def query(
prompt: str | AsyncIterable[dict[str, Any]],
options: ClaudeAgentOptions | None = None
) -> AsyncIterator[Message]

The options parameter is typed as ClaudeAgentOptions | None, but many examples pass raw dictionaries. This creates several problems:

1. Type checker failures: Static analysis tools (mypy, pyright) will flag this as a type error
2. IDE autocomplete broken: Users won't get property suggestions when using dicts
3. Inconsistency: Some examples use the dataclass correctly, others use dicts
4. Unclear contract: Users don't know if dict conversion is guaranteed behavior

Affected Pages:

| Page | Line(s) |
|------|---------|
| platform.claude.com/docs/en/agent-sdk/slash-commands | 36, 75, 115, 158, 256, 264, 321, 471, 479 |
| platform.claude.com/docs/en/agent-sdk/todo-tracking | 61, 156 |
| platform.claude.com/docs/en/agent-sdk/plugins | 49, 108, 155 |

Total scope: 3 pages, 14 occurrences

Suggested Improvement

Update all Python examples to use the ClaudeAgentOptions dataclass:

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
prompt="/compact",
options=ClaudeAgentOptions(max_turns=1)
):

Alternatively, if dict-to-dataclass conversion is intentionally supported, update the type signature and document this behavior:

async def query(
prompt: str | AsyncIterable[dict[str, Any]],
options: ClaudeAgentOptions | dict[str, Any] | None = None
) -> AsyncIterator[Message]

Impact

Medium - Makes feature difficult to understand

Additional Context

• The TypeScript examples correctly use the typed Options interface
• This inconsistency is likely due to Python's duck typing making dicts work at runtime
• Following the documented type signature improves code quality and IDE support