[DOCS] Inconsistency in Python SDK Hook Event support for `SubagentStart`

Documentation Type

Unclear/confusing documentation

Documentation Location

• URL: https://platform.claude.com/docs/en/agent-sdk/hooks - Source File: src/claude_agent_sdk/types.py (claude-agent-sdk-python)

Section/Topic

• The "Available hooks" comparison table in the documentation and the HookEvent type definition in the Python SDK.

Current Documentation

The documentation table in docs/en/agent-sdk/hooks.md explicitly states that SubagentStart is not supported in the Python SDK:

| Hook Event | Python SDK | TypeScript SDK | What triggers it |
|------------|------------|----------------|------------------|
| SubagentStart | No | Yes | Subagent initialization |

However, the Python SDK source code (src/claude_agent_sdk/types.py) includes a definition for the input type:

class SubagentStartHookInput(BaseHookInput):
    """Input data for SubagentStart hook events."""
    hook_event_name: Literal["SubagentStart"]
    agent_id: str
    agent_type: str

But the HookEvent literal type in the same file omits it:

HookEvent = (
    Literal["PreToolUse"]
    | Literal["PostToolUse"]
    | Literal["UserPromptSubmit"]
    | Literal["Stop"]
    | Literal["SubagentStop"]
    | Literal["PreCompact"]
)

What's Wrong or Missing?

There is a three-way contradiction between the documentation and the source code:

1. Documentation claims the feature is TypeScript-only.
2. SDK Types define a helper class (SubagentStartHookInput) suggesting the feature might be implemented or planned.
3. SDK Type Aliases (HookEvent) exclude the event, meaning even if a developer tried to use it, their IDE/Type-checker would flag it as invalid.

This leaves the user unsure if SubagentStart is a "hidden" supported feature, a planned feature, or if the SubagentStartHookInput class is simply dead code that should be ignored.

Suggested Improvement

• If SubagentStart IS supported in Python:
• Update the HookEvent Literal in src/claude_agent_sdk/types.py to include "SubagentStart".
• Update the table in docs/en/agent-sdk/hooks.md to show "Yes" for the Python SDK.
• If SubagentStart IS NOT supported in Python:
• Remove the unused SubagentStartHookInput class from src/claude_agent_sdk/types.py to avoid developer confusion.
• Keep the documentation as is.

Impact

High - Prevents users from using a feature

Additional Context

• This inconsistency was found by cross-referencing the platform.claude.com documentation markdown with the released claude-agent-sdk-python source code.
• Similar hooks like SubagentStop are correctly aligned (Docs say "Yes", and it is present in both the classes and the HookEvent Literal).