[DOCS] Python SDK HookEvent enum missing 4 documented hook events

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/19413
2. https://github.com/anthropics/claude-code/issues/18927
3. https://github.com/anthropics/claude-code/issues/18773

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

Issue #20911 Verification

Title: [DOCS] Python SDK HookEvent enum missing 4 documented hook events
Issue Date: Unknown
Verification Date: 2026-02-01
Status: RESOLVED

---

Issue Summary

This issue reports that the Python SDK's HookEvent enum was missing 4 hook events documented in the Claude Code hooks reference: SubagentStart, PermissionRequest, PostToolUseFailure, and Setup. Additionally, it noted a naming convention discrepancy between the SDK (snake_case like tool_start) and the hooks docs (PascalCase like PreToolUse).

---

Verification Results

Claim 1: Python SDK showed HookEvent with 8 events using snake_case naming

Status: RESOLVED

The issue claimed the Python SDK documentation showed:

class HookEvent(str, Enum):
    TOOL_START = "tool_start"
    TOOL_END = "tool_end"
    AGENT_START = "agent_start"
    ...

The current documentation now shows:

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
]

Verdict: The enum has been completely restructured. It now uses a Literal type with PascalCase naming that matches the Claude Code hooks reference. The old snake_case naming (tool_start, tool_end, etc.) no longer exists.

---

Claim 2: Four events missing from Python SDK (SubagentStart, PermissionRequest, PostToolUseFailure, Setup)

Status: RESOLVED

The current Agent SDK hooks guide now includes an explicit compatibility table:

| Hook Event | Python SDK | TypeScript SDK |
|------------|------------|----------------|
| PreToolUse | Yes | Yes |
| PostToolUse | Yes | Yes |
| PostToolUseFailure | No | Yes |
| UserPromptSubmit | Yes | Yes |
| Stop | Yes | Yes |
| SubagentStart | No | Yes |
| SubagentStop | Yes | Yes |
| PreCompact | Yes | Yes |
| PermissionRequest | No | Yes |
| SessionStart | No | Yes |
| SessionEnd | No | Yes |
| Notification | No | Yes |

Additionally, the Python SDK reference states:

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

Verdict: The documentation now explicitly documents which events are supported in each SDK. The "missing" events (SubagentStart, PermissionRequest, PostToolUseFailure) are now clearly marked as "Python SDK: No" in the table. The Setup event mentioned in the issue does not exist in the Claude Code hooks reference—this appears to have been a misreading of the original documentation.

---

Claim 3: Naming convention discrepancy (snake_case vs PascalCase)

Status: RESOLVED

The Python SDK now uses PascalCase ("PreToolUse", "PostToolUse", etc.) that matches the Claude Code hooks reference exactly. The old snake_case values (tool_start, tool_end, etc.) are no longer present.

Verdict: Naming is now consistent across both documentation sources.

---

Current State

| Claim | Status |
|-------|--------|
| HookEvent showed wrong 8 events with snake_case | RESOLVED - Now shows 6 events with correct PascalCase |
| SubagentStart missing without explanation | RESOLVED - Explicitly documented as "Python SDK: No" |
| PermissionRequest missing without explanation | RESOLVED - Explicitly documented as "Python SDK: No" |
| PostToolUseFailure missing without explanation | RESOLVED - Explicitly documented as "Python SDK: No" |
| Setup event missing | RESOLVED - This event never existed; was a misreading |
| Naming convention inconsistency | RESOLVED - Both now use PascalCase |

---

Suggested Fix

N/A - issue has been resolved.

---

References

• URL: https://platform.claude.com/docs/en/agent-sdk/python (Python SDK Reference)
• Current HookEvent definition using Literal type with PascalCase

• URL: https://platform.claude.com/docs/en/agent-sdk/hooks (Agent SDK Hooks Guide)
• Explicit compatibility table showing Python vs TypeScript SDK support

• URL: https://code.claude.com/docs/en/hooks (Claude Code Hooks Reference)
• Complete list of 12 hook events

---

Conclusion & Recommendation

Primary Concern: The Python SDK's HookEvent enum was missing events and used inconsistent naming compared to the Claude Code hooks documentation.

Resolution Status: RESOLVED

Recommendation: CLOSE

The documentation has been comprehensively restructured. The HookEvent type now uses correct PascalCase naming matching Claude Code's hooks, and an explicit compatibility table clearly documents which events are available in Python vs TypeScript SDKs with explanatory notes about SDK limitations.

Closing as resolved - the HookEvent type has been restructured with correct PascalCase naming, and a compatibility table now clearly documents SDK-specific event support.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.