hooks - before tool call event - cancel tool

[pgrayy]

Description

Support cancelling tool calls from a BeforeToolCallEvent hook. This feature is meant to compliment interrupts as part of the human-in-the-loop (HIL) process. The idea is that if a customer interrupts a tool for human approval and that human sends back a rejection, the tool call will be cancelled. This however could also be extended to use cases outside of HIL.

Usage

class CancelHook(HookProvider):
    def register_hooks(self, registry) -> None:
        registry.add_callback(BeforeToolCallEvent, self.cancel)

    def cancel(self, event: BeforeToolCallEvent) -> None:
        if event.tool_use["name"] == "delete_tool":
            response = event.interrupt("Tool needs approval")
            if response == "REJECT":
                event.cancel_tool = "tool rejected"

agent = Agent(hooks=[CancelHook()])

If rejected, the tool will not execute and the tool result will look as follows:

{
    "toolUseId": "delete_tool",
    "status": "error",
    "content": [{"text": "tool rejected"}],
}

Note, this cancellation does not stop the agent loop. It strictly prevents the given tool from executing. Any other tools executing in sequence or concurrently will continue to do so. All results (including the cancel result) are sent to the model on the next iteration of the agent loop.

Related Issues

#204

Documentation PR

Will follow up on this after all the HIL changes are merged.

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: Wrote new unit tests.
• hatch test tests_integ/tools/executors/*.py: Wrote new integ tests.

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

Follow up

The SequentialToolExecutor will execute all tools in sequence even if one fails. Support for cancellation got me thinking that maybe we want to break out of execution if a tool fails since the SequentialToolExecutor is meant to set an order/dependency between calls.

---

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