[DOCS] Missing `stop_reason` and `stop_sequence` in Python SDK `AssistantMessage` type

Documentation Type

Missing documentation (feature not documented)

Documentation Location

Provide a URL if possible: https://platform.claude.com/docs/en/agent-sdk/python#assistantmessage

Section/Topic

The Message Types section, specifically the definition and properties of the AssistantMessage class.

Current Documentation

The documentation defines the AssistantMessage as follows:

@dataclass
class AssistantMessage:
    """Assistant message with content blocks."""

    content: list[ContentBlock]
    model: str
    parent_tool_use_id: str | None = None
    error: AssistantMessageError | None = None

What's Wrong or Missing?

The AssistantMessage dataclass in the Python SDK is missing the stop_reason and stop_sequence fields.

According to the general guide on Handling Stop Reasons, these fields are "crucial for building robust applications" to detect if a response was cut off due to max_tokens, if the model is attempting a tool_use, or if a refusal occurred.

While the underlying Messages API and the TypeScript Agent SDK include these fields, the Python SDK implementation (as seen in src/claude_agent_sdk/types.py) and its corresponding documentation do not provide a way to access this metadata on the assistant message object.

Suggested Improvement

Update the documentation and the underlying SDK types to include stop_reason and stop_sequence.

Suggested Text for Property Table:
| Property | Type | Description |
| :--- | :--- | :--- |
| stop_reason | str \| None | The reason generation stopped (e.g., "end_turn", "max_tokens", "tool_use"). |
| stop_sequence | str \| None | The specific custom stop sequence that was encountered, if any. |

Suggested Code Update:

@dataclass
class AssistantMessage:
    """Assistant message with content blocks."""

    content: list[ContentBlock]
    model: str
    parent_tool_use_id: str | None = None
    error: AssistantMessageError | None = None
    stop_reason: str | None = None
    stop_sequence: str | None = None

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: Handling stop reasons
• Comparison: The TypeScript SDK equivalent (SDKAssistantMessage) provides access to the full APIAssistantMessage from the core SDK, which contains these fields. In Python, the fields are currently dropped during the parsing phase in message_parser.py.
• Impact: Without these fields, developers using the ClaudeSDKClient cannot programmatically determine why an agent turn ended without manually inspecting the content blocks for tool calls or checking the final ResultMessage.