Better error message when passing AgentHooks to runner

[bonk1t]

Describe the bug

Passing an AgentHooks instance to the global hooks parameter of Runner.run(...) leads to a confusing runtime error. The runner expects RunHooks, but there’s no runtime type check. As soon as the run invokes lifecycle callbacks, it either:

• raises AttributeError (missing on_agent_start), or
• when those methods exist, raises TypeError at handoff because RunHooks.on_handoff(context, from_agent, to_agent) kwargs are used, which do not match AgentHooks.on_handoff(context, agent, source).

This makes the failure mode opaque to users and hard to diagnose.

• Agents SDK version: 0.3.0 (from /references/openai-agents-python-0.3.0)
• Python version: 3.13.5

Repro steps

• Minimal pure repro (no external frameworks), fully based on /references:
  1. Run this script:
     • test.py
  2. What it does:
     • Imports Agents SDK from /references/openai-agents-python-0.3.0/src and test helpers from /references/openai-agents-python-0.3.0/tests to avoid model API calls.
     • Sets up two agents and a FakeModel that emits a handoff tool call.
     • Intentionally passes a subclass of AgentHooks to Runner.run(..., hooks=...) so the run reaches the handoff and triggers the kwargs mismatch.
  3. Actual output:
     • Raises:
       • TypeError: AgentHooksBase.on_handoff() got an unexpected keyword argument 'from_agent'

Expected behavior

• Either:
  • A clear runtime error if the wrong hook type is supplied (e.g., “hooks must be RunHooks, got AgentHooks”), or
  • Support both hook types (global and agent-scoped) in a way that avoids kwargs mismatch and confusing errors.