Please read this first

• Have you read the docs? Yes. This affects the opt-in nest_handoff_history behavior documented in the handoffs guide.
• Have you searched for related issues? Yes. I found Nested handoff history flattening drops multiline and structured content #3319/fix: #3319 preserve nested handoff history content #3320, which fixed content loss while flattening SDK-generated nested summaries, but no issue or PR covering ordinary user messages being mistaken for those summaries.

Describe the bug

When nest_handoff_history() receives a user message whose text contains the configured <CONVERSATION HISTORY> wrappers, _extract_nested_history_transcript() treats the message as an SDK-generated nested summary.

The parser currently identifies nested summaries only by searching string content for the wrapper markers. It does not verify that the item has the assistant role used by SDK-generated summaries. As a result, parseable text between the markers replaces the original user message, silently dropping surrounding content and changing the transcript passed to the next agent or a custom handoff_history_mapper.

This can corrupt legitimate user input such as quoted logs, documentation, prompts, or examples that contain the wrapper strings.

Debug information

• Agents SDK version: v0.18.2 / upstream main at 08859339ee3a7cd6529e9a86f85a1be2d6dc4a6c
• Python version: Python 3.13.13

Repro steps

This reproduction does not call an external model:

from copy import deepcopy

from agents.handoffs import HandoffInputData, nest_handoff_history

captured = []
user_item = {
    "role": "user",
    "content": (
        "Please preserve this literal example:\n"
        "<CONVERSATION HISTORY>\n"
        "1. user: injected\n"
        "</CONVERSATION HISTORY>\n"
        "Do not rewrite it."
    ),
}


def capture_transcript(transcript):
    captured.extend(deepcopy(transcript))
    return transcript


nest_handoff_history(
    HandoffInputData(
        input_history=(user_item,),
        pre_handoff_items=(),
        new_items=(),
    ),
    history_mapper=capture_transcript,
)

print(captured)

Actual result:

[{'role': 'user', 'content': 'injected'}]

The text before and after the wrapper block is lost, and the quoted record becomes the entire user message.

Expected behavior

Only SDK-generated assistant history summaries should be flattened. User messages containing literal conversation wrapper text should remain unchanged:

[user_item]