feat: add before_tool_call_hooks for pre-execution tool-call gating (fixes #2557)

[kuangmi-bit]

Summary

Adds a supported before_tool_call_hooks extension point to MultiStepAgent, enabling pre-execution policy gates before tool calls with side effects. Fixes #2557.

Problem

smolagents has step_callbacks but they fire after tool execution via _finalize_step(). There is no way to intercept and potentially block a tool call before it runs — only post-hoc observation of what already happened.

This is a gap compared to CrewAI (before_tool_call hook) and LangChain (wrap_tool_call middleware), both of which let a host application enforce a policy boundary before tools with real-world side effects execute.

Solution

Three changes across 2 files:

1. AgentToolCallBlockedError (new exception in utils.py) — raised when a hook blocks execution.

2. before_tool_call_hooks parameter on MultiStepAgent.__init__() — a list of callables, each receiving (tool_name, arguments, agent) and returning False to block or True/truthy to allow.

3. Hook invocation in process_single_tool_call() before execute_tool_call() — hooks are iterated before any tool runs. Exceptions from hooks (other than AgentToolCallBlockedError) are caught and logged as warnings so one faulty hook doesn't break the agent loop.

Usage

def security_gate(tool_name: str, arguments: dict, agent) -> bool:
    if tool_name == "install_package":
        return False  # block
    return True

agent = CodeAgent(
    tools=[...],
    before_tool_call_hooks=[security_gate],
)

Design decisions

• Follows the existing step_callbacks / final_answer_checks pattern (simple callable list, no registry class)
• Minimal API surface — just a list, no dict/registry needed since there's only one event type (before tool call)
• Fault-tolerant: broken hooks warn instead of crashing the agent
• Backward-compatible: default is None, no behavior change for existing users