Add tool call parameters for on_tool_start hook

[yanmxa]

Resolve: #252

[louis-sanna-eki]

@yanmxa thanks for doing this work, very useful!

[wesleytao]

much needed feature!

[mattmorgis]

I learned that if you use Runner.run_streamed(), they provide a RunItemStreamEvent, one of which is type tool_called. It gives you a full RunItem which has the tool arguments. I think this is the preferred approach because it uses SSE from the responses api.

Example:

result = Runner.run_streamed(
    agent,
    input,
)
async for event in result.stream_events():
    if event.type == "run_item_stream_event":
        if event.name == "tool_called":
            print(
                f"-- Tool {event.item.raw_item.name} was called with args: {event.item.raw_item.arguments} "
            )
        elif event.name == "reasoning_item_created":
            summary = event.item.raw_item.summary
            # there’s at least one summary part
            # o-series models will send this every response, it is sometimes blank
            if summary:
                text = summary[0].text
                print(f"-- Reasoning item created: {text}")
                print("--")
        elif event.name == "message_output_created":
            print(event.item.raw_item.content[0].text)
        else:
            pass  # Ignore other event types

[rm-openai]

Apologies for missing this PR. It looks good, but is a breaking change. We could certainly make a breaking change but I'd like to avoid it unless absolutely necessary. Another option could be to add a new method for the args. Thoughts on which would be better?

[yanmxa]

Thanks @rm-openai!

I tend to favor the breaking change approach because:

1. Adding a new method (like on_tool_start_with_args()) creates API confusion - developers would choose between two similar hooks, and we'd maintain both forever

2. Simple migration - users just replace tool with action, then access tool via action.function_tool

3. Clean long-term design - one unified hook that provides complete information

The community feedback shows this is needed. A clean break now might be better than API fragmentation.

What do you think?

[ludovicoserrani-nautes]

@rm-openai do you have any ETA on this PR?