feat: #858 add include_conversation_history to Agent.as_tool()

[0xSudoSSH]

Summary

Add include_conversation_history parameter to Agent.as_tool() that passes the parent's conversation history to the sub-agent as a <CONVERSATION HISTORY> summary, matching the format used by handoff history nesting.

This addresses the gap between handoffs (full history, no return) and as_tool() (no history, returns control) by allowing sub-agents to see the full conversation context while still returning results to the orchestrator.

API: include_conversation_history is optional, defaults to False — fully backward compatible.

sub_agent.as_tool(
    tool_name="analyze",
    tool_description="Analyze with full context",
    include_conversation_history=True,  # opt-in, default False
)

What the sub-agent receives:

• A <CONVERSATION HISTORY> text summary of the full parent conversation (including tool calls/results)
• Filtered raw items forwarded alongside (matching handoff nesting behavior)
• The tool input as a user message at the end

Implementation:

• ToolExecutionContext captures conversation state (input_history, pre_step_items, new_step_items) before tool execution in execute_tools_and_side_effects:

  context_wrapper.tool_execution_context = ToolExecutionContext(
      input_history=tuple(original_input) if isinstance(original_input, list) else original_input,
      pre_step_items=tuple(pre_step_items),
      new_step_items=tuple(new_step_items),
  )

• build_agent_tool_history() reuses a shared _build_history() helper extracted from nest_handoff_history(), ensuring consistent summarization
• Same filtering rules as handoffs: _should_forward_pre_item (strict) for previous turns, _should_forward_new_item (permissive) for current turn
• Cleared after _execute_tool_plan to prevent stale state
• Interrupt/resume safe: the history-prepended input becomes part of RunState on the first run, so resuming from approval interruptions preserves full context without re-prepending

Files changed:

• src/agents/run_context.py — ToolExecutionContext dataclass + field on RunContextWrapper
• src/agents/run_internal/turn_resolution.py — set/clear tool_execution_context
• src/agents/handoffs/history.py — extract _build_history shared helper + add build_agent_tool_history
• src/agents/agent.py — include_conversation_history param + prepend logic in _run_agent_impl
• src/agents/tool_context.py — accept tool_execution_context in constructor

Test plan

• 12 unit tests covering: default off, history prepend, empty context, assistant forwarding, pre-step filtering, nested history flattening, handoff refactoring, resume from interruption, execution context propagation
• make format, make lint, make typecheck — all pass
• Interactive example: examples/agent_patterns/agents_as_tools_with_history.py

Issue number

Closes #858

Checks

• I've added new tests (if relevant)
• I've added/updated the relevant documentation
• I've run make lint and make format
• I've made sure tests pass

[seratch]

Thanks for sharing this idea, but we intentionally avoid adding this feature. The mentioned issue should be closed, so I will do so later.

[0xSudoSSH]

Thanks for sharing this idea, but we intentionally avoid adding this feature. The mentioned issue should be closed, so I will do so later.

@seratch Thanks for the quick feedback! I understand the design intent to keep as_tool and handoffs distinct.

I'm relatively new to open source contributing but enjoyed working on this codebase (my first merged PR was #3339). Are there any open issues — ideally small to medium in scope — where contributions would be welcome? Happy to help with bug fixes or smaller features that align with the team's roadmap.