feat: surface terminal_reason on ResultMessage (#1142)

Surfaces `ResultMessage.terminal_reason` on the Python SDK. The CLI
already emits `terminal_reason` on the result frame (`"completed"`,
`"max_turns"`, `"aborted_streaming"`, `"aborted_tools"`, …); the Python
SDK was dropping it. A value of `"aborted_streaming"` /
`"aborted_tools"` indicates the turn was cancelled via
`ClaudeSDKClient.interrupt()`, giving callers an explicit cancelled
marker without a new result subtype. Mirrors the TypeScript SDK's
`SDKResultMessage.terminal_reason`.

Companion docs PR: anthropics/claude-code-docs#4360 (should land no
earlier than the SDK release that ships this).

CHANGELOG entry (for the release cutter to place under the version
header — kept out of this diff because `tests/test_changelog.py` rejects
`## Unreleased`):

```
### Features

- **terminal_reason on ResultMessage**: `ResultMessage.terminal_reason` now
  surfaces why the query loop ended (`"completed"`, `"max_turns"`,
  `"aborted_streaming"`, `"aborted_tools"`, etc.). A value of
  `"aborted_streaming"` or `"aborted_tools"` means the turn was cancelled
  via `ClaudeSDKClient.interrupt()`. Mirrors the TypeScript SDK's
  `SDKResultMessage.terminal_reason`.
```

**Verification:** ruff check + format clean; `pytest
tests/test_message_parser.py` 75 passed (2 new); full `pytest tests/`
1302 passed, 4 skipped.

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: benlehrburger-ant <benlehrburger-ant@users.noreply.github.com>

Author: benlehrburger-ant

src/claude_agent_sdk/_internal/message_parser.py

@@ -314,6 +314,7 @@ def parse_message(data: dict[str, Any]) -> Message | None:
                     errors=data.get("errors"),
                     api_error_status=data.get("api_error_status"),
                     uuid=data.get("uuid"),
+                    terminal_reason=data.get("terminal_reason"),
                 )
             except KeyError as e:
                 raise MessageParseError(

src/claude_agent_sdk/types.py

@@ -1221,6 +1221,15 @@ class ResultMessage:
     # Emitted by the CLI since v2.1.110. Safe to log (no message content).
     api_error_status: int | None = None
     uuid: str | None = None
+    terminal_reason: str | None = None
+    """Why the query loop terminated (e.g. ``"completed"``, ``"max_turns"``,
+    ``"aborted_streaming"``). A value of ``"aborted_streaming"`` or
+    ``"aborted_tools"`` indicates the turn was cancelled (via
+    :meth:`ClaudeSDKClient.interrupt` or an ``interrupt`` control request).
+    ``None`` when the CLI did not report a terminal reason (older CLI
+    versions, or a result that bypassed the query loop such as a local
+    slash command). Mirrors the TypeScript SDK's
+    ``SDKResultMessage.terminal_reason``."""
 
 
 @dataclass

tests/test_message_parser.py

@@ -834,6 +834,38 @@ def test_parse_result_message_with_null_stop_reason(self):
         assert isinstance(message, ResultMessage)
         assert message.stop_reason is None
 
+    def test_parse_result_message_with_terminal_reason(self):
+        """Test parsing a result message with terminal_reason field."""
+        data = {
+            "type": "result",
+            "subtype": "success",
+            "duration_ms": 1000,
+            "duration_api_ms": 500,
+            "is_error": False,
+            "num_turns": 2,
+            "session_id": "session_123",
+            "result": "",
+            "terminal_reason": "aborted_tools",
+        }
+        message = parse_message(data)
+        assert isinstance(message, ResultMessage)
+        assert message.terminal_reason == "aborted_tools"
+
+    def test_parse_result_message_missing_terminal_reason_is_none(self):
+        """A result message without terminal_reason parses to None."""
+        data = {
+            "type": "result",
+            "subtype": "success",
+            "duration_ms": 1000,
+            "duration_api_ms": 500,
+            "is_error": False,
+            "num_turns": 2,
+            "session_id": "session_123",
+        }
+        message = parse_message(data)
+        assert isinstance(message, ResultMessage)
+        assert message.terminal_reason is None
+
     def test_parse_rate_limit_event(self):
         """Test parsing a rate_limit_event into a typed RateLimitEvent."""
         data = {