refactor: make HookEventMessage a SystemMessage subclass

HookEventMessage arrives on the wire as a system-typed message
(type=system, subtype=hook_started|hook_response), matching the
established pattern for TaskStartedMessage, TaskProgressMessage,
TaskNotificationMessage, and MirrorErrorMessage. Subclassing
SystemMessage means existing isinstance(msg, SystemMessage) and
case SystemMessage() checks continue to match, and the redundant
HookEventMessage entry can be dropped from the Message union.

Also fix the docstring to reference the actual hook_response keys
(output, exit_code, outcome) instead of a nonexistent response
key, and update the test fixture to match the real wire shape.

Author: qing-ant

src/claude_agent_sdk/types.py

@@ -1153,7 +1153,7 @@ class RateLimitEvent:
 
 
 @dataclass
-class HookEventMessage:
+class HookEventMessage(SystemMessage):
     """Hook event emitted by the CLI when ``include_hook_events`` is enabled.
 
     When ``ClaudeAgentOptions.include_hook_events`` is ``True``, the CLI emits
@@ -1164,10 +1164,15 @@ class HookEventMessage:
     These arrive on the wire as ``{"type": "system", "subtype":
     "hook_started" | "hook_response", "hook_event": "PreToolUse", ...}``.
 
+    Subclass of SystemMessage: existing ``isinstance(msg, SystemMessage)`` and
+    ``case SystemMessage()`` checks continue to match. The base ``subtype``
+    and ``data`` fields remain populated with the raw payload.
+
     Attributes:
         subtype: Lifecycle phase — ``"hook_started"`` when a hook begins
             executing, ``"hook_response"`` when it completes (the latter
-            carries a ``response`` key in ``data``).
+            carries ``output``, ``exit_code``, and ``outcome`` keys 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
@@ -1176,9 +1181,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)
+    hook_event_name: str = ""
     session_id: str | None = None
     uuid: str | None = None
 
@@ -1190,7 +1193,6 @@ class HookEventMessage:
     | ResultMessage
     | StreamEvent
     | RateLimitEvent
-    | HookEventMessage
 )
 
 

tests/test_message_parser.py

@@ -995,15 +995,26 @@ def test_parse_hook_event_message_response(self):
             "hook_name": "PostToolUse",
             "session_id": "sess-123",
             "uuid": "uuid-789",
-            "response": {"decision": "approve"},
+            "output": "",
+            "exit_code": 0,
+            "outcome": "success",
         }
         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"}
+        assert message.data["output"] == ""
+        assert message.data["exit_code"] == 0
+        assert message.data["outcome"] == "success"
+
+    def test_parse_hook_event_message_isinstance_system(self):
+        """HookEventMessage is a SystemMessage subclass for backward compat."""
+        data = {"type": "system", "subtype": "hook_started", "hook_event": "PreToolUse"}
+        message = parse_message(data)
+        assert isinstance(message, HookEventMessage)
+        assert isinstance(message, SystemMessage)
 
     def test_parse_hook_event_message_minimal(self):
         """Hook events without session_id/uuid/hook_event still parse."""