Backtestspydantic-airun-20260918-215936#4728

Issue #4728 Merged fix PR # Run 18 Sep 2026 · run-20260918-215936 pydantic/pydantic-ai

Built-in HistoryProcessor for orphaned tool call/result repair

Worse

The merged fix was judged better than our patch.

No judgment was produced for this ticket. It counts as an error in the run total.

Solve

18m 57s3 turns

Wall-clock time in the container

Full test suite

10 new failures

5,797 passed · 485 skipped · 6,390 total

Contamination audit

Unknown

See the audit notes for this run

Patch size

316vs 593 merged

Changed lines, ours vs merged

Description

The problem

Multi-turn conversations with tools can accumulate broken message history — tool calls without matching results, or results referencing calls that don't exist. This is just structurally invalid (a tool call without a result before the next turn doesn't make sense), and providers rightfully reject it. Anthropic is the strictest about enforcement — you get a 400 — but even providers that silently tolerate it will produce worse results from garbled history.

The ways this happens in practice:

  • A streaming response with ToolCallPart gets persisted, but the agent times out before ToolReturnPart arrives. Next turn inherits a dangling tool call.
  • Deferred tools (UI-resolved via Vercel AI adapter) get their results dropped or arrive with a different tool_call_id than the original call.
  • Multi-run conversations that span many agent.run() calls accumulate orphans from each interrupted run. Once one bad pair gets in, every subsequent run 400s on the same history. The conversation is permanently broken.

That last one is the real pain point. There's no self-healing — once a conversation is poisoned, it stays poisoned until someone manually fixes the stored messages.

What we built

We wrote a ~120-line sanitize_message_history function that plugs in as a HistoryProcessor:

  • Strips trailing ModelResponse messages with unmatched tool calls
  • Injects synthetic ToolReturnPart ("Tool call was not completed") for orphaned regular calls, BuiltinToolReturnPart for orphaned builtin calls (in the same response, since Anthropic requires that)
  • Strips ToolReturnPart/RetryPromptPart whose tool_call_id doesn't exist in the preceding ModelResponse. If that empties the ModelRequest, drops in a placeholder UserPromptPart to keep the user/assistant alternation intact
agent = Agent('anthropic:claude-sonnet', history_processors=[sanitize_message_history])

It works, we've been running it in production. But it feels like something that shouldn't live in userland — maintaining valid tool call/result pairing in persisted history seems like a framework-level concern.

The ask

Would it make sense to ship a built-in history processor for this? If it's not something Pydantic AI wants to maintain then it's okay and we can close the issue, was thinking this is going to be a very common use case. Something like:

from pydantic_ai.history_processors import repair_tool_orphans

agent = Agent('anthropic:claude-sonnet', history_processors=[repair_tool_orphans])

The HistoryProcessor abstraction is already the right place for this. The logic is provider-agnostic (it operates on ModelMessage types), though the one Anthropic-specific wrinkle is that builtin tool results need to live in the same ModelResponse as the call, not the next ModelRequest.

How we got here

We run a chat agent with deferred tools in production. The pattern that broke things: each run ends with a deferred get_editor_content call that times out. The next run starts with a tool_return for edit_content with a different tool_call_id (generated by the frontend). After a few runs, the conversation has multiple orphaned calls and mismatched results, and Anthropic starts rejecting everything.

References

_No response_

The two patches

Our patch+316 −0
pydantic_ai_slim/pydantic_ai/history_processors.pynew file mode 100644index 00000000..eb883c4e@@ -0,0 +1,143 @@+"""Built-in [history processors][pydantic_ai.agent.AbstractAgent] for repairing message history.++See [message history](../message-history.md) for background on history processors.+"""++from __future__ import annotations++from dataclasses import replace++from .messages import (+    BuiltinToolCallPart,+    BuiltinToolReturnPart,+    ModelMessage,+    ModelRequest,+    ModelRequestPart,+    ModelResponse,+    ModelResponsePart,+    RetryPromptPart,+    ToolCallPart,+    ToolReturnPart,+    UserPromptPart,+)++__all__ = ('repair_tool_orphans',)++_ORPHAN_TOOL_RETURN_CONTENT = 'Tool call was not completed'+"""Content used for synthetic tool return/prompt parts injected to repair orphaned tool calls."""+++def repair_tool_orphans(messages: list[ModelMessage]) -> list[ModelMessage]:+    """Repair orphaned tool calls and tool results in a message history.++    Providers such as Anthropic reject histories where a tool call has no matching result, or a+    tool result references a call that doesn't exist. This history processor makes such histories+    valid again so a poisoned conversation can heal itself instead of failing on every subsequent run:++    * A builtin tool call whose result is missing gets a synthetic+      [`BuiltinToolReturnPart`][pydantic_ai.messages.BuiltinToolReturnPart] appended to the same+      [`ModelResponse`][pydantic_ai.messages.ModelResponse] (providers such as Anthropic require the+      builtin result to live alongside the call, not in the following request).+    * A regular tool call whose result is missing from the following+      [`ModelRequest`][pydantic_ai.messages.ModelRequest] gets a synthetic+      [`ToolReturnPart`][pydantic_ai.messages.ToolReturnPart] injected into that request.+    * A trailing `ModelResponse` with unanswered tool calls is dropped, since there is no following+      request to carry the results.+    * A [`ToolReturnPart`][pydantic_ai.messages.ToolReturnPart] or+      [`RetryPromptPart`][pydantic_ai.messages.RetryPromptPart] whose `tool_call_id` doesn't match a+      call in the preceding response is removed. If that empties the request, a placeholder+      [`UserPromptPart`][pydantic_ai.messages.UserPromptPart] is inserted to keep the request/response+      alternation intact.++    Use it like any other history processor:++    ```python {test="skip"}+    from pydantic_ai import Agent+    from pydantic_ai.history_processors import repair_tool_orphans++    agent = Agent('anthropic:claude-sonnet-4-0', history_processors=[repair_tool_orphans])+    ```+    """+    repaired: list[ModelMessage] = []++    for index, message in enumerate(messages):+        if isinstance(message, ModelResponse):+            message = _repair_builtin_returns(message)+            open_calls = [part for part in message.parts if isinstance(part, ToolCallPart)]+            if open_calls:+                next_message = messages[index + 1] if index + 1 < len(messages) else None+                if not isinstance(next_message, ModelRequest):+                    # No following request can carry the results, so drop the dangling response.+                    continue+            repaired.append(message)+        elif isinstance(message, ModelRequest):+            previous = messages[index - 1] if index > 0 else None+            open_calls = (+                [part for part in previous.parts if isinstance(part, ToolCallPart)]+                if isinstance(previous, ModelResponse)+                else []+            )+            repaired.append(_repair_request(message, open_calls))+        else:  # pragma: no cover+            repaired.append(message)++    return repaired+++def _repair_builtin_returns(response: ModelResponse) -> ModelResponse:+    """Append synthetic builtin tool returns for any builtin calls missing a result.++    Builtin results must live in the same response as the call, so they are repaired in place.+    """+    returned_ids = {part.tool_call_id for part in response.parts if isinstance(part, BuiltinToolReturnPart)}+    missing = [+        part+        for part in response.parts+        if isinstance(part, BuiltinToolCallPart) and part.tool_call_id not in returned_ids+    ]+    if not missing:+        return response++    parts: list[ModelResponsePart] = list(response.parts)+    for call in missing:+        parts.append(+            BuiltinToolReturnPart(+                tool_name=call.tool_name,+                content=_ORPHAN_TOOL_RETURN_CONTENT,+                tool_call_id=call.tool_call_id,+                provider_name=call.provider_name,+            )+        )+    return replace(response, parts=parts)+++def _repair_request(request: ModelRequest, open_calls: list[ToolCallPart]) -> ModelRequest:+    """Strip tool results with no matching call and inject results for unanswered calls."""+    open_call_ids = {call.tool_call_id for call in open_calls}+    answered_ids: set[str] = set()+    kept_parts: list[ModelRequestPart] = []+    for part in request.parts:+        if isinstance(part, ToolReturnPart | RetryPromptPart):+            if part.tool_call_id not in open_call_ids:+                # Result references a call that isn't in the preceding response: drop it.+                continue+            answered_ids.add(part.tool_call_id)+        kept_parts.append(part)++    # Inject synthetic returns (at the front) for calls that never got a result.+    synthetic: list[ModelRequestPart] = [+        ToolReturnPart(+            tool_name=call.tool_name,+            content=_ORPHAN_TOOL_RETURN_CONTENT,+            tool_call_id=call.tool_call_id,+        )+        for call in open_calls+        if call.tool_call_id not in answered_ids+    ]+    parts = [*synthetic, *kept_parts]++    if not parts:+        # Stripping emptied the request; keep alternation valid with a placeholder.+        parts = [UserPromptPart(content=_ORPHAN_TOOL_RETURN_CONTENT)]++    return replace(request, parts=parts)tests/test_history_processor.pyindex 113e9b4c..f33c4ffb 100644@@ -7,6 +7,8 @@ import pytest  from pydantic_ai import (     Agent,+    BuiltinToolCallPart,+    BuiltinToolReturnPart,     ModelMessage,     ModelRequest,     ModelRequestPart,@@ -1688,3 +1690,174 @@ def test_takes_ctx_returns_false_for_untyped_processor():      # When first param has no type annotation, takes_run_context returns False     assert takes_run_context(untyped_processor) is False  # pyright: ignore[reportUnknownArgumentType]+++def test_repair_tool_orphans_noop_on_valid_history():+    """A well-formed tool-call/tool-return history is returned unchanged."""+    from pydantic_ai.history_processors import repair_tool_orphans++    messages: list[ModelMessage] = [+        ModelRequest(parts=[UserPromptPart(content='q')]),+        ModelResponse(parts=[ToolCallPart(tool_name='t', args={}, tool_call_id='c1')]),+        ModelRequest(parts=[ToolReturnPart(tool_name='t', content='ok', tool_call_id='c1')]),+    ]++    result = repair_tool_orphans(messages)++    assert result == messages+++def test_repair_tool_orphans_injects_missing_tool_return():+    """An unanswered tool call gets a synthetic tool return injected before the following user prompt."""+    from pydantic_ai.history_processors import _ORPHAN_TOOL_RETURN_CONTENT, repair_tool_orphans++    messages: list[ModelMessage] = [+        ModelRequest(parts=[UserPromptPart(content='q1')]),+        ModelResponse(parts=[ToolCallPart(tool_name='t', args={}, tool_call_id='c1')]),+        ModelRequest(parts=[UserPromptPart(content='q2')]),+    ]++    result = repair_tool_orphans(messages)++    last_request = result[-1]+    assert isinstance(last_request, ModelRequest)+    assert last_request.parts == [+        ToolReturnPart(tool_name='t', content=_ORPHAN_TOOL_RETURN_CONTENT, tool_call_id='c1'),+        UserPromptPart(content='q2'),+    ]+    # The earlier messages are untouched.+    assert result[0] == messages[0]+    assert result[1] == messages[1]+++def test_repair_tool_orphans_injects_missing_builtin_return():+    """An unanswered builtin tool call gets a synthetic builtin return appended to the same response."""+    from pydantic_ai.history_processors import _ORPHAN_TOOL_RETURN_CONTENT, repair_tool_orphans++    messages: list[ModelMessage] = [+        ModelRequest(parts=[UserPromptPart(content='q1')]),+        ModelResponse(+            parts=[+                TextPart(content='thinking'),+                BuiltinToolCallPart(+                    tool_name='web_search', args={}, tool_call_id='b1', provider_name='anthropic'+                ),+            ]+        ),+        ModelRequest(parts=[UserPromptPart(content='q2')]),+    ]++    result = repair_tool_orphans(messages)++    response = result[1]+    assert isinstance(response, ModelResponse)+    assert response.parts == [+        TextPart(content='thinking'),+        BuiltinToolCallPart(tool_name='web_search', args={}, tool_call_id='b1', provider_name='anthropic'),+        BuiltinToolReturnPart(+            tool_name='web_search',+            content=_ORPHAN_TOOL_RETURN_CONTENT,+            tool_call_id='b1',+            provider_name='anthropic',+        ),+    ]+    # The following request is untouched (no ToolReturnPart injected there).+    assert result[-1] == messages[-1]+++def test_repair_tool_orphans_strips_mismatched_tool_return():+    """A tool return referencing a non-existent call is stripped and its request kept non-empty."""+    from pydantic_ai.history_processors import _ORPHAN_TOOL_RETURN_CONTENT, repair_tool_orphans++    messages: list[ModelMessage] = [+        ModelRequest(parts=[UserPromptPart(content='q1')]),+        ModelResponse(parts=[TextPart(content='answer')]),+        ModelRequest(parts=[ToolReturnPart(tool_name='ghost', content='x', tool_call_id='nope')]),+        ModelRequest(parts=[UserPromptPart(content='q2')]),+    ]++    result = repair_tool_orphans(messages)++    third = result[2]+    assert isinstance(third, ModelRequest)+    assert third.parts == [UserPromptPart(content=_ORPHAN_TOOL_RETURN_CONTENT)]+    # The mismatched ghost/nope return is gone from the entire history.+    for message in result:+        if isinstance(message, ModelRequest):+            for part in message.parts:+                assert not (isinstance(part, ToolReturnPart) and part.tool_call_id == 'nope')+++def test_repair_tool_orphans_strips_trailing_response_with_tool_calls():+    """A trailing response with an unanswered tool call is dropped entirely."""+    from pydantic_ai.history_processors import repair_tool_orphans++    messages: list[ModelMessage] = [+        ModelRequest(parts=[UserPromptPart(content='q1')]),+        ModelResponse(parts=[TextPart(content='a'), ToolCallPart(tool_name='t', args={}, tool_call_id='c1')]),+    ]++    result = repair_tool_orphans(messages)++    assert result == [ModelRequest(parts=[UserPromptPart(content='q1')])]+++def test_repair_tool_orphans_deferred_tool_mismatch_scenario():+    """Mismatched return dropped and synthetic return injected for the unanswered call."""+    from pydantic_ai.history_processors import _ORPHAN_TOOL_RETURN_CONTENT, repair_tool_orphans++    messages: list[ModelMessage] = [+        ModelRequest(parts=[UserPromptPart(content='q1')]),+        ModelResponse(parts=[ToolCallPart(tool_name='get_editor_content', args={}, tool_call_id='A')]),+        ModelRequest(parts=[ToolReturnPart(tool_name='edit_content', content='...', tool_call_id='B')]),+    ]++    result = repair_tool_orphans(messages)++    second_request = result[-1]+    assert isinstance(second_request, ModelRequest)+    assert second_request.parts == [+        ToolReturnPart(+            tool_name='get_editor_content',+            content=_ORPHAN_TOOL_RETURN_CONTENT,+            tool_call_id='A',+        )+    ]+    assert result[0] == messages[0]+    assert result[1] == messages[1]+++async def test_repair_tool_orphans_as_history_processor(+    function_model: FunctionModel, received_messages: list[ModelMessage]+):+    """End-to-end: the processor makes an orphaned tool call history valid before the provider sees it."""+    from pydantic_ai.history_processors import _ORPHAN_TOOL_RETURN_CONTENT, repair_tool_orphans++    agent = Agent(function_model, history_processors=[repair_tool_orphans])++    message_history: list[ModelMessage] = [+        ModelRequest(parts=[UserPromptPart(content='Previous question')]),+        ModelResponse(parts=[ToolCallPart(tool_name='t', args={}, tool_call_id='c1')]),+    ]++    await agent.run('New question', message_history=message_history)++    assert received_messages == snapshot(+        [+            ModelRequest(parts=[UserPromptPart(content='Previous question', timestamp=IsDatetime())]),+            ModelResponse(parts=[ToolCallPart(tool_name='t', args={}, tool_call_id='c1')], timestamp=IsDatetime()),+            ModelRequest(+                parts=[+                    ToolReturnPart(+                        tool_name='t',+                        content=_ORPHAN_TOOL_RETURN_CONTENT,+                        tool_call_id='c1',+                        timestamp=IsDatetime(),+                    ),+                    UserPromptPart(content='New question', timestamp=IsDatetime()),+                ],+                timestamp=IsDatetime(),+                run_id=IsStr(),+            ),+        ]+    ) 
Merged fix · PR #+593 −0
pydantic_ai_slim/pydantic_ai/capabilities/__init__.pyindex ae88f8abc0..8150a8dab2 100644@@ -25,6 +25,7 @@ from .include_return_schemas import IncludeToolReturnSchemas from .mcp import MCP from .prefix_tools import PrefixTools from .prepare_tools import PrepareTools+from .repair_tool_orphans import RepairToolOrphans from .set_tool_metadata import SetToolMetadata from .thinking import Thinking from .thread_executor import ThreadExecutor@@ -43,6 +44,7 @@ CAPABILITY_TYPES: dict[str, type[AbstractCapability[Any]]] = {         MCP,         PrefixTools,         PrepareTools,+        RepairToolOrphans,         SetToolMetadata,         Thinking,         Toolset,@@ -79,6 +81,7 @@ __all__ = [     'MCP',     'PrefixTools',     'PrepareTools',+    'RepairToolOrphans',     'SetToolMetadata',     'Thinking',     'ThreadExecutor',pydantic_ai_slim/pydantic_ai/capabilities/repair_tool_orphans.pynew file mode 100644index 0000000000..d8e821d7e8@@ -0,0 +1,250 @@+"""Capability that repairs broken tool-call / tool-return pairing in message history.++Multi-turn conversations with tools can accumulate structural problems:+dangling tool calls without matching returns, or orphaned returns referencing+calls that don't exist. Providers like Anthropic strictly enforce pairing and+will reject malformed history with a 400 error.++This capability hooks into ``before_model_request`` to transparently repair+these issues before each model request.++Usage::++    from pydantic_ai import Agent+    from pydantic_ai.capabilities import RepairToolOrphans++    agent = Agent('anthropic:claude-sonnet', capabilities=[RepairToolOrphans()])++See https://github.com/pydantic/pydantic-ai/issues/4728 for background.+"""++from __future__ import annotations++import warnings+from dataclasses import dataclass+from typing import TYPE_CHECKING++from pydantic_ai import messages as _messages+from pydantic_ai.tools import AgentDepsT++from .abstract import AbstractCapability++if TYPE_CHECKING:+    from pydantic_ai.models import ModelRequestContext+    from pydantic_ai.tools import RunContext++__all__ = ['RepairToolOrphans']++_DANGLING_TOOL_CALL_MESSAGE = 'Tool call was not completed.'+++@dataclass+class RepairToolOrphans(AbstractCapability[AgentDepsT]):+    """Repair broken tool-call / tool-return pairing in message history.++    Fixes two classes of structural problems:++    1. **Dangling tool calls** -- a ``ToolCallPart`` or ``BuiltinToolCallPart``+       in a ``ModelResponse`` that has no matching return anywhere later in the+       history.++       - For regular ``ToolCallPart``: a synthetic ``ToolReturnPart`` is injected+         into the next ``ModelRequest``.+       - For ``BuiltinToolCallPart``: a synthetic ``BuiltinToolReturnPart`` is+         injected into the *same* ``ModelResponse`` (required by Anthropic).++    2. **Orphaned tool returns** -- a ``ToolReturnPart`` or ``RetryPromptPart``+       whose ``tool_call_id`` does not match any tool call in the preceding+       ``ModelResponse``.  These parts are removed.  If that empties the+       ``ModelRequest``, a placeholder ``UserPromptPart`` is inserted.++    Args:+        warn: If ``True`` (the default), emit a warning when repairs are made+              so the underlying issue can be investigated.+    """++    warn: bool = True++    async def before_model_request(+        self,+        ctx: RunContext[AgentDepsT],+        request_context: ModelRequestContext,+    ) -> ModelRequestContext:+        request_context.messages = _repair_messages(request_context.messages, warn=self.warn)+        return request_context+++def _repair_messages(+    messages: list[_messages.ModelMessage],+    *,+    warn: bool,+) -> list[_messages.ModelMessage]:+    """Core repair logic operating on a message list."""+    if not messages:+        return messages++    repaired = False+    result: list[_messages.ModelMessage] = []++    for i, message in enumerate(messages):+        if isinstance(message, _messages.ModelResponse):+            fixed = _repair_response(message)+            if fixed is not message:+                repaired = True+            result.append(fixed)+        elif isinstance(message, _messages.ModelRequest):+            fixed = _repair_request(message, result)+            if fixed is not message:+                repaired = True+            result.append(fixed)+        else:+            result.append(message)++    # Handle trailing ModelResponse with dangling regular tool calls+    if result and isinstance(result[-1], _messages.ModelResponse):+        trailing = result[-1]+        dangling_calls = [p for p in trailing.parts if isinstance(p, _messages.ToolCallPart)]+        if dangling_calls:+            repaired = True+            result.append(+                _messages.ModelRequest(+                    parts=[+                        _messages.ToolReturnPart(+                            tool_name=part.tool_name,+                            content=_DANGLING_TOOL_CALL_MESSAGE,+                            tool_call_id=part.tool_call_id,+                        )+                        for part in dangling_calls+                    ]+                )+            )++    if repaired and warn:+        warnings.warn(+            'RepairToolOrphans: repaired broken tool-call/return pairing in message history. '+            'This usually means a previous agent run was interrupted before tool results '+            'were recorded. Consider investigating the root cause.',+            UserWarning,+            stacklevel=4,+        )++    return result+++def _repair_response(response: _messages.ModelResponse) -> _messages.ModelResponse:+    """Inject synthetic BuiltinToolReturnPart for unanswered BuiltinToolCallParts.++    Builtin tool returns must live in the same ModelResponse as the call+    (required by Anthropic).+    """+    builtin_call_ids: set[str] = set()+    existing_return_ids: set[str] = set()++    for part in response.parts:+        if isinstance(part, _messages.BuiltinToolCallPart):+            builtin_call_ids.add(part.tool_call_id)+        elif isinstance(part, _messages.BuiltinToolReturnPart):+            existing_return_ids.add(part.tool_call_id)++    unanswered = builtin_call_ids - existing_return_ids+    if not unanswered:+        return response++    new_parts: list[_messages.ModelResponsePart] = list(response.parts)+    for part in response.parts:+        if isinstance(part, _messages.BuiltinToolCallPart) and part.tool_call_id in unanswered:+            new_parts.append(+                _messages.BuiltinToolReturnPart(+                    tool_name=part.tool_name,+                    content=_DANGLING_TOOL_CALL_MESSAGE,+                    tool_call_id=part.tool_call_id,+                )+            )++    return _messages.ModelResponse(+        parts=new_parts,+        usage=response.usage,+        model_name=response.model_name,+        timestamp=response.timestamp,+        provider_name=response.provider_name,+        provider_url=response.provider_url,+        provider_details=response.provider_details,+        provider_response_id=response.provider_response_id,+        finish_reason=response.finish_reason,+        run_id=response.run_id,+    )+++def _repair_request(+    request: _messages.ModelRequest,+    preceding: list[_messages.ModelMessage],+) -> _messages.ModelRequest:+    """Fix orphaned tool returns and inject synthetic returns for dangling calls.++    1. Find the preceding ModelResponse's regular tool call IDs.+    2. Remove ToolReturnPart / RetryPromptPart whose tool_call_id is not in+       the preceding response.+    3. Inject synthetic ToolReturnPart for any ToolCallPart in the preceding+       response that has no matching return in this request.+    4. If the request ends up empty, insert a placeholder UserPromptPart.+    """+    # Find preceding ModelResponse's tool call IDs+    prev_regular_calls: dict[str, _messages.ToolCallPart] = {}+    for prev in reversed(preceding):+        if isinstance(prev, _messages.ModelResponse):+            for part in prev.parts:+                if isinstance(part, _messages.ToolCallPart):+                    prev_regular_calls[part.tool_call_id] = part+            break++    prev_call_ids = set(prev_regular_calls.keys())++    # Step 1: Filter out orphaned tool returns / retries+    filtered_parts: list[_messages.ModelRequestPart] = []+    answered_ids: set[str] = set()+    changed = False+    for part in request.parts:+        if isinstance(part, (_messages.ToolReturnPart, _messages.RetryPromptPart)):+            if part.tool_call_id in prev_call_ids:+                filtered_parts.append(part)+                answered_ids.add(part.tool_call_id)+            else:+                changed = True  # Dropping orphaned part+        else:+            filtered_parts.append(part)++    # Step 2: Inject synthetic returns for unanswered regular tool calls+    unanswered = prev_call_ids - answered_ids+    synthetic_parts: list[_messages.ModelRequestPart] = []+    if unanswered:+        changed = True+        # Preserve the order of tool calls from the response+        for prev in reversed(preceding):+            if isinstance(prev, _messages.ModelResponse):+                for part in prev.parts:+                    if isinstance(part, _messages.ToolCallPart) and part.tool_call_id in unanswered:+                        synthetic_parts.append(+                            _messages.ToolReturnPart(+                                tool_name=part.tool_name,+                                content=_DANGLING_TOOL_CALL_MESSAGE,+                                tool_call_id=part.tool_call_id,+                            )+                        )+                break++    if not changed:+        return request++    all_parts = synthetic_parts + filtered_parts++    # Step 3: If empty, add placeholder+    if not all_parts:+        all_parts = [_messages.UserPromptPart(content='...')]++    return _messages.ModelRequest(+        parts=all_parts,+        timestamp=request.timestamp,+        instructions=request.instructions,+        run_id=request.run_id,+        metadata=request.metadata,+    )tests/test_capabilities.pyindex f63d6965ab..ab235b4136 100644@@ -71,6 +71,8 @@ from pydantic_graph import End from ._inline_snapshot import snapshot from .conftest import IsDatetime, IsInstance, IsStr +from pydantic_ai.capabilities import RepairToolOrphans+ pytestmark = [     pytest.mark.anyio, ]@@ -84,6 +86,7 @@ def test_capability_types() -> None:             'IncludeToolReturnSchemas': IncludeToolReturnSchemas,             'MCP': MCP,             'PrefixTools': PrefixTools,+            'RepairToolOrphans': RepairToolOrphans,             'SetToolMetadata': SetToolMetadata,             'Thinking': Thinking,             'WebFetch': WebFetch,tests/test_repair_tool_orphans.pynew file mode 100644index 0000000000..3fbd104bbc@@ -0,0 +1,337 @@+"""Tests for the RepairToolOrphans capability."""++from __future__ import annotations++import warnings+from collections.abc import AsyncIterator++import pytest++from pydantic_ai import Agent+from pydantic_ai.capabilities import RepairToolOrphans+from pydantic_ai.messages import (+    BuiltinToolCallPart,+    BuiltinToolReturnPart,+    ModelMessage,+    ModelRequest,+    ModelResponse,+    RetryPromptPart,+    TextPart,+    ToolCallPart,+    ToolReturnPart,+    UserPromptPart,+)+from pydantic_ai.models.function import AgentInfo, FunctionModel++pytestmark = [pytest.mark.anyio]+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------++_DANGLING_MSG = 'Tool call was not completed.'+++def _ids_of(parts: list, cls: type) -> set[str]:+    """Extract tool_call_ids from parts of a given type."""+    return {p.tool_call_id for p in parts if isinstance(p, cls)}+++# ---------------------------------------------------------------------------+# Unit tests for the repair logic+# ---------------------------------------------------------------------------+++class TestRepairToolOrphansUnit:+    """Unit tests that directly call the internal _repair_messages function."""++    def _repair(self, messages: list[ModelMessage], *, warn: bool = False) -> list[ModelMessage]:+        from pydantic_ai.capabilities.repair_tool_orphans import _repair_messages++        return _repair_messages(messages, warn=warn)++    def test_empty_history(self):+        assert self._repair([]) == []++    def test_clean_history_unchanged(self):+        messages: list[ModelMessage] = [+            ModelRequest(parts=[UserPromptPart(content='hello')]),+            ModelResponse(parts=[ToolCallPart(tool_name='t', args='{}', tool_call_id='tc1')]),+            ModelRequest(parts=[ToolReturnPart(tool_name='t', content='ok', tool_call_id='tc1')]),+            ModelResponse(parts=[TextPart(content='done')]),+        ]+        result = self._repair(messages)+        assert len(result) == 4+        # No synthetic parts should have been added+        req = result[2]+        assert isinstance(req, ModelRequest)+        returns = [p for p in req.parts if isinstance(p, ToolReturnPart)]+        assert len(returns) == 1+        assert returns[0].tool_call_id == 'tc1'++    def test_dangling_regular_call_with_following_request(self):+        """ToolCallPart with no return -> synthetic ToolReturnPart injected."""+        messages: list[ModelMessage] = [+            ModelRequest(parts=[UserPromptPart(content='hi')]),+            ModelResponse(parts=[ToolCallPart(tool_name='t', args='{}', tool_call_id='tc1')]),+            ModelRequest(parts=[UserPromptPart(content='continue')]),+        ]+        result = self._repair(messages)+        assert len(result) == 3+        req = result[2]+        assert isinstance(req, ModelRequest)+        synthetic = [p for p in req.parts if isinstance(p, ToolReturnPart)]+        assert len(synthetic) == 1+        assert synthetic[0].tool_call_id == 'tc1'+        assert synthetic[0].content == _DANGLING_MSG+        # Original user prompt preserved+        assert any(isinstance(p, UserPromptPart) for p in req.parts)++    def test_dangling_regular_call_trailing(self):+        """Trailing ModelResponse with dangling call -> synthetic request appended."""+        messages: list[ModelMessage] = [+            ModelRequest(parts=[UserPromptPart(content='hi')]),+            ModelResponse(parts=[ToolCallPart(tool_name='t', args='{}', tool_call_id='tc1')]),+        ]+        result = self._repair(messages)+        assert len(result) == 3+        req = result[2]+        assert isinstance(req, ModelRequest)+        assert len(req.parts) == 1+        assert isinstance(req.parts[0], ToolReturnPart)+        assert req.parts[0].tool_call_id == 'tc1'++    def test_dangling_builtin_call(self):+        """BuiltinToolCallPart without return -> synthetic return in same response."""+        messages: list[ModelMessage] = [+            ModelRequest(parts=[UserPromptPart(content='hi')]),+            ModelResponse(+                parts=[BuiltinToolCallPart(tool_name='web_search', args='{}', tool_call_id='btc1')]+            ),+            ModelRequest(parts=[UserPromptPart(content='continue')]),+        ]+        result = self._repair(messages)+        resp = result[1]+        assert isinstance(resp, ModelResponse)+        builtin_returns = [p for p in resp.parts if isinstance(p, BuiltinToolReturnPart)]+        assert len(builtin_returns) == 1+        assert builtin_returns[0].tool_call_id == 'btc1'+        assert builtin_returns[0].content == _DANGLING_MSG++    def test_orphaned_tool_return_removed(self):+        """ToolReturnPart with no matching call in preceding response -> removed."""+        messages: list[ModelMessage] = [+            ModelRequest(parts=[UserPromptPart(content='hi')]),+            ModelResponse(parts=[TextPart(content='no tools called')]),+            ModelRequest(+                parts=[+                    ToolReturnPart(tool_name='t', content='stale', tool_call_id='orphan'),+                    UserPromptPart(content='continue'),+                ]+            ),+        ]+        result = self._repair(messages)+        req = result[2]+        assert isinstance(req, ModelRequest)+        # Orphaned return should be gone+        returns = [p for p in req.parts if isinstance(p, ToolReturnPart)]+        assert len(returns) == 0+        # User prompt preserved+        assert any(isinstance(p, UserPromptPart) for p in req.parts)++    def test_orphaned_retry_prompt_removed(self):+        """RetryPromptPart with no matching call -> removed."""+        messages: list[ModelMessage] = [+            ModelRequest(parts=[UserPromptPart(content='hi')]),+            ModelResponse(parts=[TextPart(content='done')]),+            ModelRequest(+                parts=[+                    RetryPromptPart(content='retry orphan', tool_call_id='orphan'),+                    UserPromptPart(content='next'),+                ]+            ),+        ]+        result = self._repair(messages)+        req = result[2]+        assert isinstance(req, ModelRequest)+        retries = [p for p in req.parts if isinstance(p, RetryPromptPart)]+        assert len(retries) == 0++    def test_empty_request_gets_placeholder(self):+        """If removing orphans empties the request, a placeholder is inserted."""+        messages: list[ModelMessage] = [+            ModelRequest(parts=[UserPromptPart(content='hi')]),+            ModelResponse(parts=[TextPart(content='done')]),+            ModelRequest(+                parts=[ToolReturnPart(tool_name='t', content='orphan', tool_call_id='orphan')]+            ),+        ]+        result = self._repair(messages)+        req = result[2]+        assert isinstance(req, ModelRequest)+        assert len(req.parts) == 1+        assert isinstance(req.parts[0], UserPromptPart)+        assert req.parts[0].content == '...'++    def test_multiple_dangling_calls(self):+        """Multiple tool calls without returns -> all get synthetic returns."""+        messages: list[ModelMessage] = [+            ModelRequest(parts=[UserPromptPart(content='hi')]),+            ModelResponse(+                parts=[+                    ToolCallPart(tool_name='a', args='{}', tool_call_id='tc1'),+                    ToolCallPart(tool_name='b', args='{}', tool_call_id='tc2'),+                ]+            ),+            ModelRequest(parts=[UserPromptPart(content='continue')]),+        ]+        result = self._repair(messages)+        req = result[2]+        assert isinstance(req, ModelRequest)+        returns = [p for p in req.parts if isinstance(p, ToolReturnPart)]+        assert len(returns) == 2+        assert _ids_of(returns, ToolReturnPart) == {'tc1', 'tc2'}++    def test_partial_answer(self):+        """One of two calls answered -> only the unanswered one gets synthetic return."""+        messages: list[ModelMessage] = [+            ModelRequest(parts=[UserPromptPart(content='hi')]),+            ModelResponse(+                parts=[+                    ToolCallPart(tool_name='a', args='{}', tool_call_id='tc1'),+                    ToolCallPart(tool_name='b', args='{}', tool_call_id='tc2'),+                ]+            ),+            ModelRequest(+                parts=[ToolReturnPart(tool_name='a', content='ok', tool_call_id='tc1')]+            ),+        ]+        result = self._repair(messages)+        req = result[2]+        assert isinstance(req, ModelRequest)+        returns = [p for p in req.parts if isinstance(p, ToolReturnPart)]+        assert len(returns) == 2+        ids = {r.tool_call_id for r in returns}+        assert ids == {'tc1', 'tc2'}+        # tc1 should have real content, tc2 synthetic+        for r in returns:+            if r.tool_call_id == 'tc1':+                assert r.content == 'ok'+            else:+                assert r.content == _DANGLING_MSG++    def test_metadata_preserved(self):+        """Request metadata should survive repair."""+        messages: list[ModelMessage] = [+            ModelRequest(parts=[UserPromptPart(content='hi')]),+            ModelResponse(parts=[ToolCallPart(tool_name='t', args='{}', tool_call_id='tc1')]),+            ModelRequest(+                parts=[UserPromptPart(content='next')],+                instructions='keep me',+                metadata={'key': 'value'},+            ),+        ]+        result = self._repair(messages)+        req = result[2]+        assert isinstance(req, ModelRequest)+        assert req.instructions == 'keep me'+        assert req.metadata == {'key': 'value'}++    def test_warning_emitted(self):+        """When warn=True, a UserWarning should be emitted on repair."""+        messages: list[ModelMessage] = [+            ModelRequest(parts=[UserPromptPart(content='hi')]),+            ModelResponse(parts=[ToolCallPart(tool_name='t', args='{}', tool_call_id='tc1')]),+            ModelRequest(parts=[UserPromptPart(content='continue')]),+        ]+        with warnings.catch_warnings(record=True) as w:+            warnings.simplefilter('always')+            self._repair(messages, warn=True)+            assert len(w) == 1+            assert 'RepairToolOrphans' in str(w[0].message)++    def test_no_warning_when_clean(self):+        """No warning should be emitted when no repairs are needed."""+        messages: list[ModelMessage] = [+            ModelRequest(parts=[UserPromptPart(content='hi')]),+            ModelResponse(parts=[TextPart(content='done')]),+        ]+        with warnings.catch_warnings(record=True) as w:+            warnings.simplefilter('always')+            self._repair(messages, warn=True)+            assert len(w) == 0++    def test_no_warning_when_disabled(self):+        """No warning when warn=False even if repairs happen."""+        messages: list[ModelMessage] = [+            ModelRequest(parts=[UserPromptPart(content='hi')]),+            ModelResponse(parts=[ToolCallPart(tool_name='t', args='{}', tool_call_id='tc1')]),+            ModelRequest(parts=[UserPromptPart(content='continue')]),+        ]+        with warnings.catch_warnings(record=True) as w:+            warnings.simplefilter('always')+            self._repair(messages, warn=False)+            assert len(w) == 0++    def test_multi_turn_poisoned_conversation(self):+        """Multiple rounds of damage: dangling calls + orphaned returns."""+        messages: list[ModelMessage] = [+            # Turn 1: normal+            ModelRequest(parts=[UserPromptPart(content='start')]),+            ModelResponse(parts=[ToolCallPart(tool_name='a', args='{}', tool_call_id='tc1')]),+            ModelRequest(parts=[ToolReturnPart(tool_name='a', content='ok', tool_call_id='tc1')]),+            # Turn 2: response has dangling call, next request has orphaned return+            ModelResponse(parts=[ToolCallPart(tool_name='b', args='{}', tool_call_id='tc2')]),+            ModelRequest(+                parts=[+                    ToolReturnPart(tool_name='c', content='stale', tool_call_id='tc_orphan'),+                    UserPromptPart(content='help'),+                ]+            ),+            # Turn 3: clean+            ModelResponse(parts=[TextPart(content='final')]),+        ]+        result = self._repair(messages)+        # Turn 2 request should have: synthetic for tc2, user prompt, orphan removed+        req = result[4]+        assert isinstance(req, ModelRequest)+        returns = [p for p in req.parts if isinstance(p, ToolReturnPart)]+        assert len(returns) == 1+        assert returns[0].tool_call_id == 'tc2'+        assert returns[0].content == _DANGLING_MSG+        # User prompt preserved+        assert any(isinstance(p, UserPromptPart) and p.content == 'help' for p in req.parts)+++# ---------------------------------------------------------------------------+# Integration test with Agent+# ---------------------------------------------------------------------------+++class TestRepairToolOrphansIntegration:+    """Test the capability end-to-end with a real Agent."""++    async def test_agent_with_poisoned_history(self):+        """Agent should successfully run with a poisoned message history when+        RepairToolOrphans is enabled."""++        def model_func(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:+            return ModelResponse(parts=[TextPart(content='recovered')])++        agent = Agent(+            FunctionModel(model_func),+            capabilities=[RepairToolOrphans(warn=False)],+        )++        # Poisoned history: dangling tool call+        poisoned_history: list[ModelMessage] = [+            ModelRequest(parts=[UserPromptPart(content='hello')]),+            ModelResponse(parts=[ToolCallPart(tool_name='t', args='{}', tool_call_id='tc1')]),+            # Missing ToolReturnPart for tc1+            ModelRequest(parts=[UserPromptPart(content='continue')]),+            ModelResponse(parts=[TextPart(content='partial')]),+        ]++        result = await agent.run('try again', message_history=poisoned_history)+        assert result.output == 'recovered' 

What the agent reported

The test run is still in progress (empty output so far). I'll wait for the completion notification.