[DOCS] Omission of `model_context_window_exceeded` stop reason in Python SDK type definitions

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons

Section/Topic

The model_context_window_exceeded stop reason section and the corresponding Python SDK type definitions in src/claude_agent_sdk/types.py.

Current Documentation

The documentation on the website states:

model_context_window_exceeded Claude stopped because it reached the model's context window limit. This allows you to request the maximum possible tokens without knowing the exact input size. Note: This stop reason is available by default in Sonnet 4.5 and newer models.

However, the Python SDK source code (src/claude_agent_sdk/types.py) defines AssistantMessageError as:

AssistantMessageError = Literal[
    "authentication_failed",
    "billing_error",
    "rate_limit",
    "invalid_request",
    "server_error",
    "unknown",
]

What's Wrong or Missing?

There is a discrepancy between the platform documentation and the Python SDK type hints. While the documentation introduces model_context_window_exceeded as a valid stop reason for Claude 4.5, the SDK's internal type definitions have not been updated to include it.

This causes two issues:

1. Type Checking Failures: Developers using strict type checkers (like Mypy or Pyright) will encounter errors when attempting to handle or check for this specific stop reason.
2. Runtime Robustness: While the parse_message logic might pass it through as a string, it is missing from the explicit Literal types that guide IDE autocomplete and validation logic for the AssistantMessage and ResultMessage objects.

Suggested Improvement

The Python SDK source code should be updated to match the documentation. Specifically:

In src/claude_agent_sdk/types.py, update the AssistantMessageError (or add to a StopReason type if applicable) to include the new variant:

AssistantMessageError = Literal[
    "authentication_failed",
    "billing_error",
    "rate_limit",
    "invalid_request",
    "server_error",
    "model_context_window_exceeded", # Add this line
    "unknown",
]

Additionally, ensure that the StopReason literal (if defined separately in the internal protocol) also includes this value to ensure ResultMessage.subtype or related fields can correctly surface it.

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: Stop Reasons API Reference
• Code Reference: See src/claude_agent_sdk/types.py in the claude-agent-sdk-python repository.
• Example from other projects: The TypeScript SDK already includes support for newer stop reasons to ensure parity with the Messages API's feature set for Claude 4.5.