feat: expose tool_call_id on RunContextWrapper for lifecycle hooks

Add a `tool_call_id: str | None` field (init=False, default None) to
`RunContextWrapper` so that callers of `on_tool_start` / `on_tool_end`
hooks can read the tool call ID directly from the context parameter
without needing an `isinstance(context, ToolContext)` guard.

`ToolContext` already declares `tool_call_id` as a required init field
(str, not str | None), so subclass behaviour is unchanged.  The base
field is `init=False` to avoid clashing with `ToolContext.from_agent_context`
which copies base-class init fields by name.

Both `_fork_with_tool_input` and `_fork_without_tool_input` are updated
to propagate the value when forking.

Closes #1849

Author: nileshpatil6

src/agents/run_context.py

@@ -61,6 +61,16 @@ class RunContextWrapper(Generic[TContext]):
     tool_input: Any | None = None
     """Structured input for the current agent tool run, when available."""
 
+    tool_call_id: str | None = field(default=None, init=False)
+    """The tool call ID for the current tool invocation, when available.
+
+    Populated on :class:`ToolContext` instances that are passed to
+    :meth:`RunHooksBase.on_tool_start <agents.lifecycle.RunHooksBase.on_tool_start>` and
+    :meth:`RunHooksBase.on_tool_end <agents.lifecycle.RunHooksBase.on_tool_end>` for
+    function-tool invocations. ``None`` for non-function-tool hook invocations and for plain
+    :class:`RunContextWrapper` instances used outside of a tool call.
+    """
+
     @staticmethod
     def _to_str_or_none(value: Any) -> str | None:
         if isinstance(value, str):
@@ -461,6 +471,7 @@ def _fork_with_tool_input(self, tool_input: Any) -> RunContextWrapper[TContext]:
         fork._approvals = self._approvals
         fork.turn_input = self.turn_input
         fork.tool_input = tool_input
+        fork.tool_call_id = self.tool_call_id
         return fork
 
     def _fork_without_tool_input(self) -> RunContextWrapper[TContext]:
@@ -469,6 +480,7 @@ def _fork_without_tool_input(self) -> RunContextWrapper[TContext]:
         fork.usage = self.usage
         fork._approvals = self._approvals
         fork.turn_input = self.turn_input
+        fork.tool_call_id = self.tool_call_id
         return fork
 
 

tests/test_run_hooks.py

@@ -16,6 +16,7 @@
 from .fake_model import FakeModel
 from .test_responses import (
     get_function_tool,
+    get_function_tool_call,
     get_text_message,
 )
 
@@ -318,3 +319,49 @@ async def test_run_hooks_receives_turn_input_streamed():
     turn_input = hooks.captured_turn_inputs[0]
     assert len(turn_input) == 1
     assert turn_input[0]["content"] == "streamed input"
+
+
+class RunHooksToolCallId(RunHooks):
+    """Capture tool_call_id from on_tool_start and on_tool_end via RunContextWrapper directly."""
+
+    def __init__(self):
+        self.start_ids: list[str | None] = []
+        self.end_ids: list[str | None] = []
+
+    async def on_tool_start(
+        self, context: RunContextWrapper[TContext], agent: Agent[TContext], tool: Tool
+    ) -> None:
+        # tool_call_id is now accessible directly on RunContextWrapper, no isinstance check needed.
+        self.start_ids.append(context.tool_call_id)
+
+    async def on_tool_end(
+        self,
+        context: RunContextWrapper[TContext],
+        agent: Agent[TContext],
+        tool: Tool,
+        result: str,
+    ) -> None:
+        self.end_ids.append(context.tool_call_id)
+
+
+@pytest.mark.asyncio
+async def test_tool_call_id_exposed_on_run_context_wrapper():
+    """tool_call_id on RunContextWrapper is set during on_tool_start/on_tool_end."""
+    hooks = RunHooksToolCallId()
+    model = FakeModel()
+    agent = Agent(name="A", model=model, tools=[get_function_tool("my_tool", "ok")])
+
+    model.set_next_output([get_function_tool_call("my_tool", "{}", call_id="call_abc123")])
+    model.add_multiple_turn_outputs([[get_text_message("done")]])
+
+    await Runner.run(agent, input="go", hooks=hooks)
+
+    assert hooks.start_ids == ["call_abc123"], f"Expected [call_abc123], got {hooks.start_ids}"
+    assert hooks.end_ids == ["call_abc123"], f"Expected [call_abc123], got {hooks.end_ids}"
+
+
+@pytest.mark.asyncio
+async def test_tool_call_id_is_none_outside_tool_context():
+    """tool_call_id on a plain RunContextWrapper (outside a tool call) is None."""
+    ctx = RunContextWrapper(context=None)
+    assert ctx.tool_call_id is None