[DOCS] Discrepancy in Subagent hook support and missing type definitions in Python SDK

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The Available hooks table.

Current Documentation

The table under the "Available hooks" section lists the following:

| Hook Event | Python SDK | TypeScript SDK | What triggers it | Example use case |
| :--- | :--- | :--- | :--- | :--- |
| SubagentStart | No | Yes | Subagent initialization | Track parallel task spawning |
| SubagentStop | Yes | Yes | Subagent completion | Aggregate results from parallel tasks |

What's Wrong or Missing?

There is an inconsistency between the documentation and the actual Python SDK implementation found in the claude-agent-sdk repository:

1. Code/Doc Mismatch: The documentation states that SubagentStop is supported in Python ("Yes"). While the type SubagentStopHookInput exists in src/claude_agent_sdk/types.py, the corresponding SubagentStart is marked as "No" in the docs and is completely missing from the codebase.
2. Missing Types: In src/claude_agent_sdk/types.py, the HookInput union and the HookEvent literal include SubagentStop but exclude SubagentStart.
3. Logical Gap: It is confusing for users to have a hook for a subagent stopping without a corresponding hook for it starting. If the Python SDK cannot support SubagentStart due to transport or architectural limitations, having SubagentStop remains half-implemented and potentially unreachable or "phantom" code.

Suggested Improvement

• Clarification: If SubagentStart is intentionally omitted from the Python SDK, the documentation should provide a brief note explaining why SubagentStop is supported but SubagentStart is not.
• Code Realignment: If the feature is not yet implemented for Python, consider adding a "Coming Soon" or "Planned" status instead of a flat "No" if parity is expected.
• Type Cleanup: If SubagentStart is never coming to Python, the SubagentStop types should be scrutinized to ensure they aren't misleading developers into expecting full subagent lifecycle management.

Suggested text for the table if parity is planned:

SubagentStart | Pending | Yes | Subagent initialization | Track parallel task spawning

Impact

High - Prevents users from using a feature

Additional Context

In the current Python SDK src/claude_agent_sdk/types.py:

# HookEvent is missing SubagentStart
HookEvent = (
    Literal["PreToolUse"]
    | Literal["PostToolUse"]
    | Literal["UserPromptSubmit"]
    | Literal["Stop"]
    | Literal["SubagentStop"] # Stop exists
    | Literal["PreCompact"]
)

# SubagentStopHookInput exists, but no SubagentStartHookInput
class SubagentStopHookInput(BaseHookInput):
    """Input data for SubagentStop hook events."""
    hook_event_name: Literal["SubagentStop"]
    stop_hook_active: bool

Comparatively, the TypeScript SDK at https://platform.claude.com/docs/en/agent-sdk/typescript lists both as fully functional, highlighting the lack of parity in the Python environment.