feat: add conversation history to ToolContext

Author: HuxleyHu98

docs/context.md

@@ -126,6 +126,7 @@ plus additional fields specific to the current tool call:
 - `tool_arguments` – the raw argument string passed to the tool  
 - `tool_namespace` – the Responses namespace for the tool call, when the tool was loaded through `tool_namespace()` or another namespaced surface  
 - `qualified_tool_name` – the tool name qualified with the namespace when one is available  
+- `conversation_history` – a visible history snapshot available to the tool at invocation time. For local function tools in non-streaming runs, this includes the current input plus prior visible run items that can be represented as model input.  
 
 Use `ToolContext` when you need tool-level metadata during execution.  
 For general context sharing between agents and tools, `RunContextWrapper` remains sufficient. Because `ToolContext` extends `RunContextWrapper`, it can also expose `.tool_input` when a nested `Agent.as_tool()` run supplied structured input.

src/agents/agent.py

@@ -602,6 +602,7 @@ async def _run_agent_impl(context: ToolContext, input_json: str) -> Any:
                     tool_namespace=context.tool_namespace,
                     agent=context.agent,
                     run_config=resolved_run_config,
+                    conversation_history=context.conversation_history,
                 )
                 set_agent_tool_state_scope(nested_context, tool_state_scope_id)
                 if should_capture_tool_input:

src/agents/result.py

@@ -99,6 +99,10 @@ def _populate_state_from_result(
     state._reasoning_item_id_policy = getattr(result, "_reasoning_item_id_policy", None)
 
     interruptions = list(getattr(result, "interruptions", []))
+    if interruptions:
+        state._interrupted_turn_input = copy.deepcopy(result.context_wrapper.turn_input)
+    else:
+        state._interrupted_turn_input = None
     if interruptions:
         state._current_step = NextStepInterruption(interruptions=interruptions)
 

src/agents/run_internal/agent_runner_helpers.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import copy
 from typing import Any, cast
 
 from ..agent import Agent
@@ -311,6 +312,9 @@ def update_run_state_for_interruption(
         run_state._session_items = list(session_items)
     run_state._current_step = next_step
     run_state._current_turn = current_turn
+    run_state._interrupted_turn_input = (
+        copy.deepcopy(run_state._context.turn_input) if run_state._context is not None else None
+    )
 
 
 async def save_turn_items_if_needed(

src/agents/run_internal/run_loop.py

@@ -1587,6 +1587,7 @@ async def get_new_response(
     )
     if isinstance(filtered.input, list):
         filtered.input = deduplicate_input_items_preferring_latest(filtered.input)
+    context_wrapper.turn_input = list(filtered.input)
 
     model = get_model(agent, run_config)
     model_settings = agent.model_settings.resolve(run_config.model_settings)

src/agents/run_internal/tool_execution.py

@@ -55,6 +55,7 @@
     RunItemBase,
     ToolApprovalItem,
     ToolCallOutputItem,
+    TResponseInputItem,
 )
 from ..logger import logger
 from ..model_settings import ModelSettings
@@ -1284,13 +1285,17 @@ def __init__(
         hooks: RunHooks[Any],
         context_wrapper: RunContextWrapper[Any],
         config: RunConfig,
+        conversation_history: list[TResponseInputItem] | None,
         isolate_parallel_failures: bool | None,
     ) -> None:
         self.agent = agent
         self.tool_runs = tool_runs
         self.hooks = hooks
         self.context_wrapper = context_wrapper
         self.config = config
+        self.conversation_history = (
+            list(conversation_history) if conversation_history is not None else None
+        )
         self.isolate_parallel_failures = (
             len(tool_runs) > 1 if isolate_parallel_failures is None else isolate_parallel_failures
         )
@@ -1465,6 +1470,7 @@ async def _run_single_tool(
                 tool_namespace=tool_context_namespace,
                 agent=self.agent,
                 run_config=self.config,
+                conversation_history=self.conversation_history,
             )
             agent_hooks = self.agent.hooks
             if self.config.trace_include_sensitive_data:
@@ -1797,6 +1803,7 @@ async def execute_function_tool_calls(
     hooks: RunHooks[Any],
     context_wrapper: RunContextWrapper[Any],
     config: RunConfig,
+    conversation_history: list[TResponseInputItem] | None = None,
     isolate_parallel_failures: bool | None = None,
 ) -> tuple[
     list[FunctionToolResult], list[ToolInputGuardrailResult], list[ToolOutputGuardrailResult]
@@ -1808,6 +1815,7 @@ async def execute_function_tool_calls(
         hooks=hooks,
         context_wrapper=context_wrapper,
         config=config,
+        conversation_history=conversation_history,
         isolate_parallel_failures=isolate_parallel_failures,
     ).execute()
 

src/agents/run_internal/tool_planning.py

@@ -20,6 +20,7 @@
     ToolApprovalItem,
     ToolCallItem,
     ToolCallOutputItem,
+    TResponseInputItem,
 )
 from ..run_context import RunContextWrapper
 from ..tool import FunctionTool, MCPToolApprovalRequest
@@ -522,6 +523,7 @@ async def _execute_tool_plan(
     hooks,
     context_wrapper: RunContextWrapper[Any],
     run_config,
+    conversation_history: list[TResponseInputItem] | None = None,
     parallel: bool = True,
 ) -> tuple[
     list[Any],
@@ -556,6 +558,7 @@ async def _execute_tool_plan(
                 hooks=hooks,
                 context_wrapper=context_wrapper,
                 config=run_config,
+                conversation_history=conversation_history,
                 isolate_parallel_failures=isolate_function_tool_failures,
             ),
             execute_computer_actions(
@@ -598,6 +601,7 @@ async def _execute_tool_plan(
             hooks=hooks,
             context_wrapper=context_wrapper,
             config=run_config,
+            conversation_history=conversation_history,
             isolate_parallel_failures=isolate_function_tool_failures,
         )
         computer_results = await execute_computer_actions(

src/agents/run_internal/turn_resolution.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import copy
 import inspect
 from collections.abc import Awaitable, Callable, Mapping, Sequence
 from typing import Any, Literal, cast
@@ -87,7 +88,10 @@
 from .items import (
     REJECTION_MESSAGE,
     apply_patch_rejection_item,
+    deduplicate_input_items_preferring_latest,
     function_rejection_item,
+    prepare_model_input_items,
+    run_items_to_input_items,
     shell_rejection_item,
 )
 from .run_steps import (
@@ -139,6 +143,7 @@
     _make_unique_item_appender,
     _select_function_tool_runs_for_resume,
 )
+from .turn_preparation import maybe_filter_model_input
 
 __all__ = [
     "execute_final_output_step",
@@ -153,6 +158,13 @@
 ]
 
 
+def _build_function_tool_conversation_history(
+    turn_input: Sequence[TResponseInputItem],
+) -> list[TResponseInputItem]:
+    """Build the visible history snapshot for a local function tool invocation."""
+    return list(turn_input)
+
+
 async def _maybe_finalize_from_tool_results(
     *,
     agent: Agent[TContext],
@@ -528,6 +540,8 @@ async def execute_tools_and_side_effects(
         new_items=processed_response.new_items,
     )
 
+    conversation_history = _build_function_tool_conversation_history(context_wrapper.turn_input)
+
     (
         function_results,
         tool_input_guardrail_results,
@@ -542,6 +556,7 @@ async def execute_tools_and_side_effects(
         hooks=hooks,
         context_wrapper=context_wrapper,
         run_config=run_config,
+        conversation_history=conversation_history,
     )
     new_step_items.extend(
         _build_tool_result_items(
@@ -1103,6 +1118,33 @@ def _add_unmatched_pending(approval: ToolApprovalItem) -> None:
         apply_patch_calls=approved_apply_patch_calls,
     )
 
+    resolved_reasoning_item_id_policy = (
+        run_config.reasoning_item_id_policy
+        if run_config.reasoning_item_id_policy is not None
+        else (run_state._reasoning_item_id_policy if run_state is not None else None)
+    )
+    if run_state is not None and isinstance(run_state._interrupted_turn_input, list):
+        context_wrapper.turn_input = copy.deepcopy(run_state._interrupted_turn_input)
+    else:
+        reconstructed_turn_input = prepare_model_input_items(
+            ItemHelpers.input_to_new_input_list(original_input),
+            run_items_to_input_items(original_pre_step_items, resolved_reasoning_item_id_policy),
+        )
+        system_prompt = await agent.get_system_prompt(context_wrapper)
+        filtered_model_input = await maybe_filter_model_input(
+            agent=agent,
+            run_config=run_config,
+            context_wrapper=context_wrapper,
+            input_items=reconstructed_turn_input,
+            system_instructions=system_prompt,
+        )
+        if isinstance(filtered_model_input.input, list):
+            filtered_model_input.input = deduplicate_input_items_preferring_latest(
+                filtered_model_input.input
+            )
+        context_wrapper.turn_input = list(filtered_model_input.input)
+    conversation_history = _build_function_tool_conversation_history(context_wrapper.turn_input)
+
     (
         function_results,
         tool_input_guardrail_results,
@@ -1117,6 +1159,7 @@ def _add_unmatched_pending(approval: ToolApprovalItem) -> None:
         hooks=hooks,
         context_wrapper=context_wrapper,
         run_config=run_config,
+        conversation_history=conversation_history,
     )
 
     for interruption in _collect_tool_interruptions(

src/agents/run_state.py

@@ -118,9 +118,9 @@
 # 3. to_json() always emits CURRENT_SCHEMA_VERSION.
 # 4. Forward compatibility is intentionally fail-fast (older SDKs reject newer or unsupported
 #    versions).
-CURRENT_SCHEMA_VERSION = "1.6"
+CURRENT_SCHEMA_VERSION = "1.7"
 SUPPORTED_SCHEMA_VERSIONS = frozenset(
-    {"1.0", "1.1", "1.2", "1.3", "1.4", "1.5", CURRENT_SCHEMA_VERSION}
+    {"1.0", "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", CURRENT_SCHEMA_VERSION}
 )
 
 _FUNCTION_OUTPUT_ADAPTER: TypeAdapter[FunctionCallOutput] = TypeAdapter(FunctionCallOutput)
@@ -187,6 +187,9 @@ class RunState(Generic[TContext, TAgent]):
     _reasoning_item_id_policy: Literal["preserve", "omit"] | None = None
     """How reasoning item IDs are represented in next-turn model input."""
 
+    _interrupted_turn_input: list[TResponseInputItem] | None = None
+    """Filtered turn input snapshot for the currently interrupted turn, if any."""
+
     _input_guardrail_results: list[InputGuardrailResult] = field(default_factory=list)
     """Results from input guardrails applied to the run."""
 
@@ -240,6 +243,7 @@ def __init__(
         self._previous_response_id = previous_response_id
         self._auto_previous_response_id = auto_previous_response_id
         self._reasoning_item_id_policy = None
+        self._interrupted_turn_input = None
         self._model_responses = []
         self._generated_items = []
         self._session_items = []
@@ -657,6 +661,7 @@ def to_json(
             "previous_response_id": self._previous_response_id,
             "auto_previous_response_id": self._auto_previous_response_id,
             "reasoning_item_id_policy": self._reasoning_item_id_policy,
+            "interrupted_turn_input": copy.deepcopy(self._interrupted_turn_input),
         }
 
         generated_items = self._merge_generated_items_with_processed()
@@ -2288,6 +2293,11 @@ async def _build_run_state_from_json(
         state._reasoning_item_id_policy = cast(Literal["preserve", "omit"], serialized_policy)
     else:
         state._reasoning_item_id_policy = None
+    serialized_interrupted_turn_input = state_json.get("interrupted_turn_input")
+    if isinstance(serialized_interrupted_turn_input, list):
+        state._interrupted_turn_input = copy.deepcopy(serialized_interrupted_turn_input)
+    else:
+        state._interrupted_turn_input = None
     state.set_tool_use_tracker_snapshot(state_json.get("tool_use_tracker", {}))
     trace_data = state_json.get("trace")
     if isinstance(trace_data, Mapping):

src/agents/tool_context.py

@@ -57,6 +57,9 @@ class ToolContext(RunContextWrapper[TContext]):
     run_config: RunConfig | None = None
     """The active run config for this tool call, when available."""
 
+    conversation_history: list[TResponseInputItem] = field(default_factory=list)
+    """Visible conversation history snapshot available when this tool is invoked."""
+
     def __init__(
         self,
         context: TContext,
@@ -69,6 +72,7 @@ def __init__(
         tool_namespace: str | None = None,
         agent: AgentBase[Any] | None = None,
         run_config: RunConfig | None = None,
+        conversation_history: list[TResponseInputItem] | None = None,
         turn_input: list[TResponseInputItem] | None = None,
         _approvals: dict[str, _ApprovalRecord] | None = None,
         tool_input: Any | None = None,
@@ -103,6 +107,7 @@ def __init__(
         )
         self.agent = agent
         self.run_config = run_config
+        self.conversation_history = list(conversation_history or [])
 
     @property
     def qualified_tool_name(self) -> str:
@@ -119,6 +124,7 @@ def from_agent_context(
         *,
         tool_namespace: str | None = None,
         run_config: RunConfig | None = None,
+        conversation_history: list[TResponseInputItem] | None = None,
     ) -> ToolContext:
         """
         Create a ToolContext from a RunContextWrapper.
@@ -137,6 +143,9 @@ def from_agent_context(
         tool_run_config = run_config
         if tool_run_config is None and isinstance(context, ToolContext):
             tool_run_config = context.run_config
+        tool_conversation_history = conversation_history
+        if tool_conversation_history is None and isinstance(context, ToolContext):
+            tool_conversation_history = context.conversation_history
 
         tool_context = cls(
             tool_name=tool_name,
@@ -155,6 +164,7 @@ def from_agent_context(
             ),
             agent=tool_agent,
             run_config=tool_run_config,
+            conversation_history=tool_conversation_history,
             **base_values,
         )
         set_agent_tool_state_scope(tool_context, get_agent_tool_state_scope(context))