feat: Add hooks for before/after tool calls + allow hooks to update values

[zastrowm]

Description

Add Tool Call Hooks with Value Modification Support

This PR adds two new hook events that fire before and after tool execution, allowing hooks to inspect and modify tool calls and their results. The hook system has been enhanced to support selective property updates on event objects.

New Hook Events

• BeforeToolInvocation : Fires before a tool is executed, allowing modification of the selected tool and parameters
• AfterToolInvocation: Fires after tool execution completes, allowing modification of the result

Enhanced Hook Registry

The base HookEvent class now includes a property write protection system. Event classes can override _can_write() to specify which properties hooks are allowed to modify. This prevents accidental modification of read-only properties while enabling controlled updates where needed.

Usage Examples

Tool Replacement

def replace_calculator(event: BeforeToolInvocation):
    if event.tool_use["name"] == "calculator":
        event.selected_tool = my_custom_calculator

registry.add_callback(BeforeToolInvocation, replace_calculator)

Result Modification

Allow intercepting tools and preventing their usage:

class ToolLimiter(HookProvider):
    def register_hooks(self, registry: "HookRegistry") -> None:
        registry.add_callback(BeforeToolInvocationEvent, self.before_tool_call)
        registry.add_callback(AfterToolInvocationEvent, self.after_tool_call)

    def before_tool_call(self, event: BeforeToolInvocationEvent):
        if event.tool_use.get("name") == "test_quota":
            event.selected_tool = None

    def after_tool_call(self, event: AfterToolInvocationEvent):
        if event.tool_use.get("name") == "test_quota":
            event.result = {
                "status": "error",
                "toolUseId": "test",
                "content": [{"text": "This tool has been used too many times!"}],
            }

...
agent._hooks.add_hook(ToolLimiter())

Tool Monitoring

class ToolLogger(HookProvider):
    def register_hooks(self, registry):
        registry.add_callback(BeforeToolInvocationEvent, self.log_start)
        registry.add_callback(AfterToolInvocationEvent, self.log_end)
    
    def log_start(self, event):
        logger.info(f"Starting tool: {event.tool_use['name']}")
    
    def log_end(self, event):
        logger.info(f"Tool finished: {event.result['status']}")

Related Issues

#231

Documentation PR

N/A for now. Will soon begin PR to document hooks experimentally.

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.