Surface message origin on UserMessage and ResultMessage - #1199

@claude please review this PR for correctness, edge cases, and test coverage.

Claude finished @qing-ant's task in 1m 39s —— View job

Code Review: Surface message origin on UserMessage and ResultMessage

• Gather context and read changed files
• Review types.py changes
• Review message_parser.py changes
• Review __init__.py exports
• Review unit tests
• Review e2e tests
• Post final review

Verified: ruff check, ruff format --check, mypy src/ scripts/, and pytest tests/ all pass cleanly (78/78 tests).

Summary

Clean, well-scoped PR that closes the TypeScript-parity gap for MessageOrigin. The implementation is correct and the design choices are sound. No blocking issues found.

types.py

Good choices:

• Using the functional TypedDict(...) syntax to accommodate the from keyword as a dict key — the right call here.
• total=False with Required[MessageOriginKind] on kind only — correctly models the wire format where only kind is guaranteed and everything else is per-kind.
• Appending origin at the end of both dataclasses with = None default — backwards compatible, no positional breakage for existing consumers.
• Docstrings on MessageOriginKind and MessageOrigin are thorough and include a usage example.

No issues found. The type is faithfully documented with per-kind field semantics in comments, and the Literal union covers all current CLI values while the docstring on MessageOriginKind correctly warns about future unrecognized kinds.

message_parser.py — _parse_origin

def _parse_origin(data: dict[str, Any]) -> MessageOrigin | None:
    origin = data.get("origin")
    if isinstance(origin, dict) and isinstance(origin.get("kind"), str):
        return cast(MessageOrigin, origin)
    return None

Correct and robust. This is the right level of validation — it guards against absent/non-object/kind-less payloads, while passing through unrecognized kinds and future fields. The cast is appropriate here since the dict is an opaque pass-through and runtime validation would add cost without benefit. Both UserMessage and ResultMessage parsing paths call it identically — good.

init.py exports

All three new types (MessageOrigin, MessageOriginKind, TaskNotificationOriginSubkind) are correctly added to both the from .types import block and __all__. Alphabetical ordering is maintained. No issues.

Unit tests (tests/test_message_parser.py)

Good coverage:

• test_parse_user_message_origin: Tests both content shapes (string and list-of-blocks), verifies pass-through of unmodeled keys (someFutureField), and checks field access.
• test_parse_user_message_origin_absent_or_malformed: Covers {} (no origin key), None, string value, and empty dict origin — all correctly parse to None.
• test_parse_result_message_origin: Covers absent origin, human kind, both task-notification sub-kinds, and unclassified.

e2e test (e2e-tests/test_message_origin.py)

Well-structured round-trip test against the real CLI. The helper _user_message correctly constructs the wire-format user message dict with the **extra pattern for injecting origin. The assertion messages include CLI version requirements which will help debugging in CI.

Overall

This is a clean, minimal addition. The forward-compatibility story is well handled (pass-through semantics, cast rather than constructor, docstring warning about unrecognized kinds). LGTM.