fix: add missing errors field to ResultMessage (#749)

The TypeScript SDK's `SDKResultErrorSchema` defines `errors:
z.array(z.string())` on error result messages (subtypes:
`error_during_execution`, `error_max_turns`, `error_max_budget_usd`,
`error_max_structured_output_retries`). This array contains diagnostic
strings explaining why the CLI exited with an error.

The Python SDK's `ResultMessage` dataclass was missing this field, so
when the CLI emitted error results with an `errors` array, the data was
silently dropped. SDK users had no way to programmatically access error
diagnostics from non-zero CLI exits.

## Changes

- Add `errors: list[str] | None = None` to the `ResultMessage` dataclass
in `types.py`
- Extract the `errors` field from JSON in the message parser
(`message_parser.py`)
- Add regression tests verifying:
  - Error result messages with `errors` array are correctly parsed
  - Success result messages have `errors` defaulting to `None`
- The `errors` field defaults to `None` when absent (backward
compatible)

## Testing

All 45 message parser tests pass, including 2 new tests for this change.

Author: qing-ant

src/claude_agent_sdk/_internal/message_parser.py

@@ -209,6 +209,7 @@ def parse_message(data: dict[str, Any]) -> Message | None:
                     structured_output=data.get("structured_output"),
                     model_usage=data.get("modelUsage"),
                     permission_denials=data.get("permission_denials"),
+                    errors=data.get("errors"),
                     uuid=data.get("uuid"),
                 )
             except KeyError as e:

src/claude_agent_sdk/types.py

@@ -915,6 +915,7 @@ class ResultMessage:
     structured_output: Any = None
     model_usage: dict[str, Any] | None = None
     permission_denials: list[Any] | None = None
+    errors: list[str] | None = None
     uuid: str | None = None
 
 

tests/test_message_parser.py

@@ -825,4 +825,53 @@ def test_parse_result_message_optional_fields_absent(self):
         assert isinstance(message, ResultMessage)
         assert message.model_usage is None
         assert message.permission_denials is None
+        assert message.errors is None
         assert message.uuid is None
+
+    def test_parse_result_message_with_errors(self):
+        """Test that ResultMessage preserves the errors field from error results.
+
+        The CLI emits errors: string[] on error result messages (subtypes like
+        error_during_execution, error_max_turns, etc.). Without this field,
+        SDK users cannot diagnose why a non-zero exit occurred.
+        """
+        data = {
+            "type": "result",
+            "subtype": "error_during_execution",
+            "duration_ms": 5000,
+            "duration_api_ms": 3000,
+            "is_error": True,
+            "num_turns": 3,
+            "session_id": "session_456",
+            "errors": [
+                "Tool execution failed: permission denied",
+                "Unable to write to /etc/hosts",
+            ],
+            "uuid": "err-uuid-789",
+        }
+        message = parse_message(data)
+        assert isinstance(message, ResultMessage)
+        assert message.errors == [
+            "Tool execution failed: permission denied",
+            "Unable to write to /etc/hosts",
+        ]
+        assert message.is_error is True
+        assert message.subtype == "error_during_execution"
+        assert message.uuid == "err-uuid-789"
+
+    def test_parse_result_message_success_no_errors(self):
+        """Test that a successful result message has no errors field."""
+        data = {
+            "type": "result",
+            "subtype": "success",
+            "duration_ms": 1000,
+            "duration_api_ms": 500,
+            "is_error": False,
+            "num_turns": 1,
+            "session_id": "session_789",
+            "result": "Task completed successfully",
+        }
+        message = parse_message(data)
+        assert isinstance(message, ResultMessage)
+        assert message.errors is None
+        assert message.result == "Task completed successfully"