[roundtrip-sweep] ModelMessagesTypeAdapter: `NativeToolReturnPart` placed in `ModelRequest.parts` silently fails JSON round-trip (different gap fr [Content truncated due to length]

[github-actions]

Impact

A NativeToolReturnPart placed inside a ModelRequest.parts cannot survive a JSON round-trip through ModelMessagesTypeAdapter:

• dump_json succeeds (with PydanticSerializationUnexpectedValue warnings, because the request-side union doesn't list the part type).
• The resulting JSON carries part_kind: 'builtin-tool-return' and 'timestamp': ..., and the content/tool-id/provider_name all serialize.
• validate_json then raises pydantic_core.ValidationError: 1 validation error for list[tagged-union[ModelRequest,ModelResponse]] — 1.request.parts.0 — Input tag 'builtin-tool-return' found using _model_request_part_discriminator() does not match any of the expected tags.

Affected paths that produce ModelRequest(parts=[NativeToolReturnPart(...)]) in real code:

• pydantic_ai/ui/ag_ui/_adapter.py:533 — when an AG-UI client sends a ToolMessage whose toolCallId carries the BUILTIN_TOOL_CALL_ID_PREFIX (i.e. a server-side native tool return), the adapter builds a NativeToolReturnPart and adds it to a ModelRequest. Anyone who then reads AgentRun.all_messages_json() / new_messages_json() and re-loads (e.g. logfire exporters, Temporal payload converters, downstream consumers) hits this gap.
• Any user code that constructs such a history directly and tries to feed it back via result.new_messages() / message_history=.

The response-side path is fine: ModelResponse(parts=[NativeToolReturnPart(...)]) round-trips cleanly today (the tag is registered at messages.py:2756). Only the request-side path is broken.

Boundary & Code Path

• Serializer/Deserializer: ModelMessagesTypeAdapter (defined at pydantic_ai_slim/pydantic_ai/messages.py:2996).
• Union missing the tag: ModelRequestPart at pydantic_ai_slim/pydantic_ai/messages.py:2698 — its 8 members are system-prompt | user-prompt | speech | tool-search-return | capability-load-return | tool-return | retry-prompt | tool-availability-delta. The builtin-tool-return tag is not among them.
• Mirror union (correct one): ModelResponsePart at messages.py:2756 does include Annotated[NativeToolReturnPart, pydantic.Tag('builtin-tool-return')] — this is the pattern the request side is missing.
• Maintainer acknowledgment of the intent: NativeToolReturnPart.narrow_type's docstring at messages.py:1725-1729 literally says "keeping it on a base part would break a ModelMessagesTypeAdapter round-trip" — the runtime already wants this to round-trip; the discriminator just isn't wired up symmetrically.

Reproduction

Drop this into tests/test_messages.py — it fails today on the JSON round-trip with the same ValidationError documented above:

def test_native_tool_return_part_in_model_request_roundtrips():
    """`NativeToolReturnPart` is registered in `ModelResponsePart` (tag `builtin-tool-return`) but
    omitted from `ModelRequestPart`. Real AG-UI clients can build a `ModelRequest` carrying it —
    see `ag_ui/_adapter.py:533` — so dumping such a history (e.g. `all_messages_json()`) and
    re-validating raises `ValidationError: Input tag 'builtin-tool-return' does not match any
    of the expected tags` instead of round-tripping cleanly. Construction and response-side
    round-trips work; only the request path is broken.

    See: `pydantic_ai/messages.py:2698` for `ModelRequestPart` (gap) and `:2756` for
    `ModelResponsePart` (registration).
    """
    messages: list[ModelMessage] = [
        ModelResponse(
            parts=[
                NativeToolCallPart(
                    tool_name='web_search',
                    args={'query': 'pydantic-ai'},
                    tool_call_id='ws_1',
                    provider_name='openai',
                )
            ]
        ),
        ModelRequest(
            parts=[
                NativeToolReturnPart(
                    tool_name='web_search',
                    content={'results': [{'title': 'Pydantic AI', 'url': 'https://ai.pydantic.dev'}]},
                    tool_call_id='ws_1',
                    provider_name='openai',
                )
            ]
        ),
    ]

    with warnings.catch_warnings():
        warnings.simplefilter('ignore', category=UserWarning)
        json_bytes = ModelMessagesTypeAdapter.dump_json(messages)

    json_roundtripped = ModelMessagesTypeAdapter.validate_json(json_bytes)
    assert json_roundtripped == messages

Run:

.venv/bin/python -m pytest tests/test_messages.py::test_native_tool_return_part_in_model_request_roundtrips -x

Captured output (full failure):

pydantic_core._pydantic_core.ValidationError: 1 validation error for list[tagged-union[ModelRequest,ModelResponse]]
1.request.parts.0
  Input tag 'builtin-tool-return' found using _model_request_part_discriminator() does not match
  any of the expected tags: 'system-prompt', 'user-prompt', 'speech', 'tool-search-return',
  'capability-load-return', 'tool-return', 'retry-prompt', 'tool-availability-delta'
  [type=union_tag_invalid, input_value={'tool_name': 'web_search', ...,
                                          'part_kind': 'builtin-tool-return'}, input_type=dict]

Expected vs Actual

Expected: ModelMessagesTypeAdapter.validate_json(ModelMessagesTypeAdapter.dump_json(messages)) == messages for any input the runtime can produce via AgentRun.all_messages().

Actual: A ValidationError aborts the round-trip whenever the request side carries a NativeToolReturnPart. The same JSON deserializes fine if the part is rebuilt as part of a ModelResponse (already registered at messages.py:2756).

Evidence

• pydantic_ai_slim/pydantic_ai/messages.py:2698-2708 — ModelRequestPart declaration (8 tags, no builtin-tool-return).
• pydantic_ai_slim/pydantic_ai/messages.py:2748-2762 — ModelResponsePart declaration (includes the tag at line 2756).
• pydantic_ai_slim/pydantic_ai/messages.py:1718 — part_kind: Literal['builtin-tool-return'] = 'builtin-tool-return' on the base class.
• pydantic_ai_slim/pydantic_ai/ui/ag_ui/_adapter.py:533 — produces NativeToolReturnPart inside a ModelRequest.
• pydantic_ai_slim/pydantic_ai/messages.py:1725-1729 — docstring on narrow_type already states the round-trip intent.
• pydantic_ai/run.py:171-192 / pydantic_ai/result.py:545-562 — AgentRun/StreamedRunResult JSON dump methods, which silently emit UserWarnings today and break on any consumer that tries to re-parse.

Adversarial review

• Reproduced on main: ModelMessagesTypeAdapter.dump_json(...) produces ~390 bytes of JSON including part_kind: 'builtin-tool-return' for the request-side part; ModelMessagesTypeAdapter.validate_json(...) then raises pydantic_core.ValidationError. Concrete command + output above.
• Existing tests checked: tests/test_messages.py covers ToolReturnPart, ToolSearchReturnPart, LoadCapabilityReturnPart, and NativeToolReturnPart inside ModelResponse (e.g. test_speech_part_serialization_roundtrip:2821, the round-trip cluster at :2742-2840), but no test places NativeToolReturnPart directly inside ModelRequest.parts. Across the full repo I found 30+ NativeToolReturnPart constructions, all on the response side. No existing test asserts the broken behaviour is intentional. Adding the Annotated[NativeToolReturnPart, pydantic.Tag('builtin-tool-return')] member to ModelRequestPart does not collide with any existing test assertion.
• Ruled out by-design: No comment/docstring anywhere marks the request-side NativeToolReturnPart path as intentionally lossy. Maintainers' own docstring on narrow_type (messages.py:1725-1729) explicitly says keeping it on a base part would break the round-trip and signals they want it to round-trip. AG-UI adapter builds these parts into ModelRequests on the client path (ag_ui/_adapter.py:533) — the runtime does produce them. Conclusion: unintentional one-sided gap, not a design choice.
• Not a duplicate of any open roundtrip-sweep issue: label-filtered scan of /tmp/gh-aw/agent/github-context/open-issues.json returned issues [roundtrip-sweep] ModelMessagesTypeAdapter: tool_kind='tool-search' return part with non-typed content fails JSON round-trip (ValidationError ...) #7211, [roundtrip-sweep] ModelMessagesTypeAdapter: tool_kind='capability-load' return part silently empties content on round-trip [Content truncated due to length] #7805, [roundtrip-sweep] ModelMessagesTypeAdapter: typed tool_kind narrowers (tool-search call/return, capability-load call) silently drop extra [Content truncated due to length] #7929, [roundtrip-sweep] ModelMessagesTypeAdapter: LoadCapabilityReturnPart.content silently drops unknown keys on round-trip (gap in PR #7933 fix) #8002, [roundtrip-sweep] ModelMessagesTypeAdapter: InstructionPart is missing from ModelRequestPart discriminator, so it fails round-trip when placed [Content truncated due to length] #8143. Their titles cover: tool_kind='tool-search' return non-typed content ([roundtrip-sweep] ModelMessagesTypeAdapter: tool_kind='tool-search' return part with non-typed content fails JSON round-trip (ValidationError ...) #7211); tool_kind='capability-load' return empties content ([roundtrip-sweep] ModelMessagesTypeAdapter: tool_kind='capability-load' return part silently empties content on round-trip [Content truncated due to length] #7805); typed tool_kind narrowers dropping extra keys ([roundtrip-sweep] ModelMessagesTypeAdapter: typed tool_kind narrowers (tool-search call/return, capability-load call) silently drop extra [Content truncated due to length] #7929); LoadCapabilityReturnPart.content dropping unknown keys ([roundtrip-sweep] ModelMessagesTypeAdapter: LoadCapabilityReturnPart.content silently drops unknown keys on round-trip (gap in PR #7933 fix) #8002); InstructionPart missing from ModelRequestPart ([roundtrip-sweep] ModelMessagesTypeAdapter: InstructionPart is missing from ModelRequestPart discriminator, so it fails round-trip when placed [Content truncated due to length] #8143). None of these names NativeToolReturnPart or the 'builtin-tool-return' tag. Open PR Preserve extra keys in tool_search and load_capability typed message parts #7933 ("Preserve extra keys in tool_search and load_capability typed message parts") addresses the extra-keys cluster ([roundtrip-sweep] ModelMessagesTypeAdapter: typed tool_kind narrowers (tool-search call/return, capability-load call) silently drop extra [Content truncated due to length] #7929/[roundtrip-sweep] ModelMessagesTypeAdapter: LoadCapabilityReturnPart.content silently drops unknown keys on round-trip (gap in PR #7933 fix) #8002) but not the discriminator gap. Issue [roundtrip-sweep] ModelMessagesTypeAdapter: InstructionPart is missing from ModelRequestPart discriminator, so it fails round-trip when placed [Content truncated due to length] #8143 (the closest cousin) is about a different part class (InstructionPart, tag 'instruction'); fixing it does not address this NativeToolReturnPart gap.

[pydanty]

• Relationship resolved
• Existing-work coverage resolved
• Investigation inputs sufficient
• Supported production reachability established (not established)
• Contract and historical intent reconciled (not applicable)
• User/project relevance established (not applicable)
• Immediate relief assessed (not applicable)
• Long-term change is net-positive (not applicable)
• Change boundary and invasiveness understood (not applicable)
• Success criteria and integration-level regression tests defined (not applicable)

Decision: not actionable

Not actionable as filed: the round-trip failure exists only for a hand-built ModelRequest(parts=[NativeToolReturnPart]), and the report's sole claimed production producer is factually wrong on main. End-to-end AGUIAdapter runs (checkout 0ec8a5d) route a builtin-id ToolMessage into ModelResponse([NativeToolCallPart, NativeToolReturnPart]) — MessagesBuilder.add() dispatches by union membership, request-side NativeToolReturnPart count is 0, and full history JSON dumps warning-free and re-validates; snapshot tests lock that placement. The report's "ruled out by-design" conclusion is also contradicted by the maintainer record (#5723 review "The asymmetry is by design"; dsfaccini's 2026-07-30 closure of #5834; hands-off #5802), and the same objection — a request-side tag flips MessagesBuilder dispatch and crashes provider _map_messages (assert_never) on replay — sank fix PRs #6288/#6687/#8146. Fourth filing of an already-adjudicated mechanism with a disproved impact claim and no supported path to the failing shape: nothing to act on.

Why it matters: This is the fourth report of the same mechanism (#6286/#7048/#7270/#8234) and the first to carry reachability evidence: it forecloses the recurring "add one union tag" fix by showing both that no production path emits the failing shape and that the union change would flip MessagesBuilder dispatch and crash provider mappers on replay — the recorded reason every prior fix attempt was declined. Recording the contract basis (snapshots + maintainer adjudication) alongside the terminal judgment stops the bot sweep from re-filing the same non-gap and preserves the design rationale for the next sweep.

Evidence: issue: bot-authored roundtrip-sweep report (#8234, github-actions[bot]) claiming NativeToolReturnPart is missing from the ModelRequestPart union so ModelMessagesTypeAdapter round-trip fails with union_tag_invalid; its Impact section asserts the AG-UI adapter produces the failing shape via ag_ui/_adapter.py:533 ("the runtime does produce them"). relationship: #8234 is distinct against the open set (no open canonical), but it is the fourth report of the same mechanism — #6286 (closed invalid-style), #7048, #7270 — and its "ruled out by-design" claim is contradicted by #5723/#5834/#5802. reproduction: the hand-built mechanism reproduces verbatim on main (checkout 0ec8a5d), but the report's load-bearing production claim is disproved end-to-end — AGUIAdapter + TestModel with a builtin-id ToolMessage places the return in ModelResponse([NativeToolCallPart, NativeToolReturnPart]); MessagesBuilder.add() (ui/_messages_builder.py:31-45) routes by union membership; snapshots (tests/test_ag_ui.py:4226-4302, builtin-id handling :2859-2864/:4145-4160) lock the placement; supported-path history JSON dumps warning-free and re-validates. existing-work: no open or merged fix — the gap persists on main because it is adjudicated intent, not oversight; fix attempts #6288/#6687 closed unmerged on the recorded dispatch/mapper objection. actionability: inputs were concrete enough to probe, and the reachability probe resolved the production-path question negatively. The report's line citations are accurate; its reachability conclusion is not.