fix: correctly parse hook events from system/hook_started|hook_response messages

Author: qing-ant

src/claude_agent_sdk/_internal/message_parser.py

@@ -49,11 +49,23 @@ def parse_message(data: dict[str, Any]) -> Message | None:
             data,
         )
 
-    # Hook events (emitted when ``include_hook_events`` is enabled) carry a
-    # ``hook_event_name`` discriminator rather than a standard ``type`` field.
-    if "hook_event_name" in data:
+    # Hook events (emitted when ``include_hook_events`` is enabled) arrive as
+    # ``system`` messages with ``subtype`` of ``hook_started`` or
+    # ``hook_response``. Route them to ``HookEventMessage`` before the generic
+    # ``SystemMessage`` handling below.
+    if data.get("type") == "system" and data.get("subtype") in (
+        "hook_started",
+        "hook_response",
+    ):
+        hook_event_name = (
+            data.get("hook_event")
+            or data.get("hook_name")
+            or data.get("hook_event_name")
+            or ""
+        )
         return HookEventMessage(
-            hook_event_name=data["hook_event_name"],
+            subtype=data["subtype"],
+            hook_event_name=hook_event_name,
             data=data,
             session_id=data.get("session_id"),
             uuid=data.get("uuid"),

src/claude_agent_sdk/types.py

@@ -1161,7 +1161,13 @@ class HookEventMessage:
     message stream. Each event is identified by ``hook_event_name`` and the
     full raw payload is available in ``data``.
 
+    These arrive on the wire as ``{"type": "system", "subtype":
+    "hook_started" | "hook_response", "hook_event": "PreToolUse", ...}``.
+
     Attributes:
+        subtype: Lifecycle phase — ``"hook_started"`` when a hook begins
+            executing, ``"hook_response"`` when it completes (the latter
+            carries a ``response`` key in ``data``).
         hook_event_name: Name of the hook event (e.g. ``"PreToolUse"``,
             ``"PostToolUse"``, ``"Stop"``).
         data: Full raw event dict from the CLI, including any
@@ -1170,6 +1176,7 @@ class HookEventMessage:
         uuid: Unique ID of the event, if present.
     """
 
+    subtype: str
     hook_event_name: str
     data: dict[str, Any] = field(default_factory=dict)
     session_id: str | None = None

tests/test_message_parser.py

@@ -967,26 +967,50 @@ def test_parse_result_message_success_no_errors(self):
         assert message.result == "Task completed successfully"
 
     def test_parse_hook_event_message(self):
-        """Test parsing a hook event into HookEventMessage."""
+        """Hook started events (system/hook_started) parse into HookEventMessage."""
         data = {
-            "hook_event_name": "PreToolUse",
+            "type": "system",
+            "subtype": "hook_started",
+            "hook_event": "PreToolUse",
+            "hook_name": "PreToolUse",
             "session_id": "sess-123",
             "uuid": "uuid-456",
             "tool_name": "Bash",
             "tool_input": {"command": "ls"},
         }
         message = parse_message(data)
         assert isinstance(message, HookEventMessage)
+        assert message.subtype == "hook_started"
         assert message.hook_event_name == "PreToolUse"
         assert message.session_id == "sess-123"
         assert message.uuid == "uuid-456"
         assert message.data == data
 
+    def test_parse_hook_event_message_response(self):
+        """Hook response events (system/hook_response) parse into HookEventMessage."""
+        data = {
+            "type": "system",
+            "subtype": "hook_response",
+            "hook_event": "PostToolUse",
+            "hook_name": "PostToolUse",
+            "session_id": "sess-123",
+            "uuid": "uuid-789",
+            "response": {"decision": "approve"},
+        }
+        message = parse_message(data)
+        assert isinstance(message, HookEventMessage)
+        assert message.subtype == "hook_response"
+        assert message.hook_event_name == "PostToolUse"
+        assert message.session_id == "sess-123"
+        assert message.uuid == "uuid-789"
+        assert message.data["response"] == {"decision": "approve"}
+
     def test_parse_hook_event_message_minimal(self):
-        """Hook events without session_id/uuid still parse."""
-        data = {"hook_event_name": "Stop"}
+        """Hook events without session_id/uuid/hook_event still parse."""
+        data = {"type": "system", "subtype": "hook_started", "hook_name": "Stop"}
         message = parse_message(data)
         assert isinstance(message, HookEventMessage)
+        assert message.subtype == "hook_started"
         assert message.hook_event_name == "Stop"
         assert message.session_id is None
         assert message.uuid is None