[DOCS] Contradiction in Python SDK HookEvent type definition and supported features

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The Hook Types section, specifically the HookEvent type definition.

Current Documentation

The documentation provides the following code block for the HookEvent type:

HookEvent = Literal[
    "PreToolUse",      # Called before tool execution
    "PostToolUse",     # Called after tool execution
    "UserPromptSubmit", # Called when user submits a prompt
    "Stop",            # Called when stopping execution
    "SubagentStop",    # Called when a subagent stops
    "PreCompact"       # Called before message compaction
]

Immediately followed by this prose:

"Note that due to setup limitations, the Python SDK does not support SessionStart, SessionEnd, and Notification hooks."

What's Wrong or Missing?

The documentation is contradictory. While the prose correctly identifies that SessionStart, SessionEnd, and Notification are unsupported in Python, the provided HookEvent code block should explicitly exclude these types to reflect the actual functional state of the SDK.

Currently, a developer looking only at the Literal type definition might attempt to implement these hooks, leading to confusion when they do not fire or are not recognized by the runtime, only to find the "unsupported" note afterward.

Suggested Improvement

Update the HookEvent code block in the Python SDK reference to strictly list the supported events. Additionally, clarify the note to ensure it is prominent.

Suggested Text:

# Supported hook event types in Python
HookEvent = Literal[
    "PreToolUse",       # Called before tool execution
    "PostToolUse",      # Called after tool execution
    "UserPromptSubmit", # Called when user submits a prompt
    "Stop",             # Called when stopping execution
    "SubagentStop",     # Called when a subagent stops
    "PreCompact"        # Called before message compaction
]

Note: Unlike the TypeScript SDK, the Python SDK currently does not support SessionStart, SessionEnd, or Notification hooks due to architectural limitations.

Impact

High - Prevents users from using a feature

Additional Context

• This contradiction is specific to the Python SDK documentation.
• The TypeScript SDK documentation correctly lists these as supported at https://platform.claude.com/docs/en/agent-sdk/typescript#hookevent.
• Aligning the code blocks with functional reality prevents developers from writing dead code for unsupported event listeners.