Summary

The pre_api_request hook is currently observe-only — plugins receive metadata (model name, token counts, etc.) but cannot modify the actual API request. The return value is discarded.

This PR passes api_kwargs into the hook and allows callbacks to return a modified dict that replaces the original api_kwargs for the API call.

Changes

run_agent.py (~5 lines changed):

• Pass api_kwargs=api_kwargs as an additional kwarg to the pre_api_request hook
• Capture the hook's return list; iterate results — last non-None dict becomes the new api_kwargs

Convention

Last non-None dict wins. If multiple plugins return modified kwargs, the last one in registration order takes precedence. Plugins that just observe can continue returning None — fully backward compatible.

Use cases

• Set tool_choice to force tool calls during specific execution phases
• Inject or override request parameters based on plugin state
• Implement request-level middleware (rate shaping, payload transforms, etc.)

Example

def on_pre_api_request(**kwargs):
    api_kwargs = kwargs.get("api_kwargs", {})
    if should_force_tool_call():
        api_kwargs["tool_choice"] = {"type": "function", "function": {"name": "my_tool"}}
        return api_kwargs
    return None  # pass-through

Testing

Existing tests pass — test_tool_calls_then_stop (exercises the hook path) and all 48 plugin tests.