feat: add on_tool_call_sealed hook for eager tool dispatch

[Oxygen56]

Summary

Adds a new lifecycle hook on_tool_call_sealed to both RunHooksBase and AgentHooksBase that fires during streaming when a tool call's arguments are sealed and ready, before the full response is complete and before the tool is invoked.

This provides a hook point for consumers to implement early tool preparation or eager dispatch without changing the SDK's execution flow. The default runner does not act on this hook — callers that do nothing with it see unchanged behavior.

Refs #3404

Changes

1. src/agents/lifecycle.py: Added on_tool_call_sealed method to RunHooksBase and AgentHooksBase
2. src/agents/run_internal/run_loop.py: Wired the hook into run_single_turn_streamed at the point where ToolCallItem is created from a ResponseOutputItemDoneEvent
3. tests/test_run_hooks.py: Added test_streamed_run_hooks_tool_call_sealed test that verifies the hook fires with the correct tool name and call_id during streaming

Test plan

• make format — passed
• make lint — passed
• make tests — all 44 relevant tests pass
• New test test_streamed_run_hooks_tool_call_sealed passes

Closes #3404

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d8f480a434

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[bmd1905]

Thanks for picking this up, this is the read-only seam I wanted in #3404. Going through ResponseOutputItemDoneEvent is the right call, it avoids the index-to-id bookkeeping you'd need to infer completion from a changing call_id. And the runner stays hands-off: it surfaces the sealed call and commits nothing, so ignoring the hook changes no behavior. That's the early-preparation vs early-commitment split @scosemicolon described.

This is enough to build real eager dispatch on top. My reference impl (cloudthinker-ai/eager-tools) takes a sealed (call_id, tool_name, arguments) and runs the tool early in a pool, with an idempotency gate so destructive calls fall back to the normal turn boundary. A hook like this is exactly where it would attach.

One thing to confirm: when several tool calls stream in one turn, does it fire once per call as each seals? The test covers the single-call case. A two-tool case asserting it fires twice with the right call_id would nail down what downstream dispatch depends on.

[Oxygen56]

@bmd1905 Good catch — I've added test_streamed_run_hooks_tool_call_sealed_multiple that verifies the hook fires twice with correct call_id values when two tool calls seal in the same turn. Also changed the tracking from a single last_sealed_tool_call to a sealed_tool_calls list so the test can assert on both calls.

The implementation already fires per-call via the ResponseOutputItemDoneEvent loop in run_loop.py, so no runtime change was needed — just the test coverage.