[FEATURE] Hooks - Events - BeforeToolsEvent and AfterToolsEvent

[zastrowm]

Overview

Add BeforeToolsEvent and AfterToolsEvent hooks to the Python SDK for parity with the TypeScript SDK (docs).

These batch-level events are triggered before and after a group of tools are executed, complementing the existing per-tool BeforeToolCallEvent and AfterToolCallEvent.

Implementation Requirements

Based on clarification discussion and repository analysis:

Event Specifications

BeforeToolsEvent

Purpose: Triggered before tools are executed in a batch, after the model returns tool use blocks.

Implementation Details:

• Location: /src/strands/hooks/events.py
• Base Classes: HookEvent and _Interruptible
• Fields:
  • agent: Agent - The agent executing the tools
  • message: Message - The message containing tool use blocks
  • tool_uses: list[ToolUse] - List of tools to be executed (extracted from message for convenience)
• Interruptible: Yes - supports event.interrupt() for approval workflows
• Writable Properties: None (no cancel_tools property)
• Callback Ordering: Normal (first registered, first executed)

Example Use Case:

class ApprovalHook(HookProvider):
    def register_hooks(self, registry: HookRegistry) -> None:
        registry.add_callback(BeforeToolsEvent, self.approve_batch)
    
    def approve_batch(self, event: BeforeToolsEvent) -> None:
        tool_names = [tool['name'] for tool in event.tool_uses]
        approval = event.interrupt("batch-approval", reason={"tools": tool_names})
        if approval.lower() != "y":
            # Individual tools can be cancelled via BeforeToolCallEvent
            pass

AfterToolsEvent

Purpose: Triggered after all tools in a batch complete execution, before results are added to conversation.

Implementation Details:

• Location: /src/strands/hooks/events.py
• Base Class: HookEvent
• Fields:
  • agent: Agent - The agent that executed the tools
  • message: Message - The original message containing tool use blocks
  • tool_uses: list[ToolUse] - List of tools that were executed
• Writable Properties: None
• Callback Ordering: Reverse (last registered, first executed) for proper cleanup semantics

Note: Tool results are available in the tool result message created after this event. This event receives the original assistant message with tool uses, not the result message.

Integration Points

File Modifications Required

1. /src/strands/hooks/events.py

   • Add BeforeToolsEvent class with _Interruptible mixin
   • Add AfterToolsEvent class with reverse callback ordering
   • Add docstrings following existing event documentation patterns

2. /src/strands/tools/executors/_executor.py

   • Update _execute() abstract method signature to handle tool batch events
   • Document when these events are triggered

3. /src/strands/tools/executors/sequential.py

   • Trigger BeforeToolsEvent at start of _execute() method
   • Handle interrupts from BeforeToolsEvent
   • Trigger AfterToolsEvent at end of _execute() method

4. /src/strands/tools/executors/concurrent.py

   • Trigger BeforeToolsEvent at start of _execute() method
   • Handle interrupts from BeforeToolsEvent
   • Trigger AfterToolsEvent at end after all tasks complete

5. /src/strands/hooks/__init__.py

   • Export new event classes

6. Documentation Updates:

   • AGENTS.md - Update hooks section to mention new events
   • docs/HOOKS.md - Add BeforeToolsEvent and AfterToolsEvent to documentation

Event Flow in Agent Loop

1. Model returns message with tool uses
2. → BeforeToolsEvent triggered (batch-level, interruptible)
3. For each tool in batch:
   a. → BeforeToolCallEvent triggered (per-tool, interruptible)
   b. Tool execution
   c. → AfterToolCallEvent triggered (per-tool, reverse order)
4. → AfterToolsEvent triggered (batch-level, reverse order)
5. Tool results added to conversation

Testing Requirements

Unit Tests

Location: /tests/strands/agent/test_agent_hooks.py

Required test cases:

• BeforeToolsEvent is triggered before tool batch execution
• AfterToolsEvent is triggered after all tools complete
• AfterToolsEvent uses reverse callback ordering
• BeforeToolsEvent contains correct agent, message, and tool_uses
• AfterToolsEvent contains correct agent, message, and tool_uses
• BeforeToolsEvent interrupt functionality works correctly
• Events work with sequential executor
• Events work with concurrent executor
• Events are not triggered when no tools are present

Integration Tests

Location: /tests_integ/hooks/ or /tests_integ/interrupts/

Required test cases:

• End-to-end interrupt workflow with batch approval
• Multiple interrupts in same batch
• Batch events with actual model provider
• Sequential vs concurrent executor behavior

Acceptance Criteria

• BeforeToolsEvent and AfterToolsEvent classes implemented in /src/strands/hooks/events.py
• Events exported from /src/strands/hooks/__init__.py
• Both executors (sequential and concurrent) trigger the events
• BeforeToolsEvent supports interrupts for approval workflows
• AfterToolsEvent uses reverse callback ordering
• All unit tests pass
• All integration tests pass
• Documentation updated in AGENTS.md and docs/HOOKS.md
• Existing tests continue to pass
• Type hints are correct and mypy passes

Technical Constraints

• No Bidi Support: Do not add these events to the experimental bidirectional streaming system (/src/strands/experimental/bidi/) at this time
• No cancel_tools Property: Unlike per-tool cancel_tool, there is no batch cancellation property
• No invocation_state: Events do not include invocation_state field (use BeforeToolCallEvent for that)
• Consistency: Follow existing event patterns for docstrings, type hints, and structure

Reference Implementation

TypeScript SDK Reference: sdk-typescript/src/hooks/events.ts

The Python implementation should provide equivalent functionality while following Python SDK conventions and patterns.

Original Request

Problem Statement

I would like the Python SDK to support a BeforeToolsEvent and AfterToolsEvent for parity with the TypeScript SDK (docs).

• BeforeToolsEvent: Triggered before tools are executed in a batch.
• AfterToolsEvent: Triggered after tools are executed in a batch. Uses reverse callback ordering.

Use Case

An example use case would be for requesting approval on a batch of tool calls through the interrupt mechanism.

[zastrowm]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

Repository Analysis

I've analyzed the Python SDK repository and the TypeScript SDK implementation to understand how to implement BeforeToolsEvent and AfterToolsEvent for parity.

Current State

Python SDK (this repository):

• Has per-tool events: BeforeToolCallEvent and AfterToolCallEvent
• These are triggered for each individual tool execution
• BeforeToolCallEvent is interruptible (supports the event.interrupt() method)
• Located in: /src/strands/hooks/events.py

TypeScript SDK (reference):

• Has batch-level events: BeforeToolsEvent and AfterToolsEvent
• These are triggered once per batch of tools
• Structure:

  BeforeToolsEvent {
    agent: AgentData
    message: Message  // Contains the tool uses
  }
  
  AfterToolsEvent {
    agent: AgentData
    message: Message  // Contains the tool uses
    _shouldReverseCallbacks(): boolean  // Returns true
  }

Implementation Location

Tools are executed in batch in the executor's _execute() method:

• /src/strands/tools/executors/sequential.py - Sequential execution
• /src/strands/tools/executors/concurrent.py - Concurrent execution
• Called from: /src/strands/event_loop/event_loop.py in _handle_tool_execution()

The events would be triggered:

• BeforeToolsEvent: At the start of _execute(), before the tool loop
• AfterToolsEvent: At the end of _execute(), after all tools complete

---

Clarifying Questions

To ensure the implementation meets your needs and maintains API consistency, I have the following questions:

1. Interruptibility for Approval Use Case

Your issue mentions using these events for "requesting approval on a batch of tool calls through the interrupt mechanism."

Question: Should BeforeToolsEvent be interruptible (like BeforeToolCallEvent)?

• This would allow hook callbacks to call event.interrupt() to pause execution and request human approval
• The TypeScript version doesn't appear to support interrupts, but Python's BeforeToolCallEvent does
• This would enable the approval use case you mentioned

Options:

• Option A: Make it interruptible (extends _Interruptible mixin)
• Option B: Keep it non-interruptible (like TypeScript)

2. Batch Cancellation Property

Python's BeforeToolCallEvent has a cancel_tool property that can cancel a single tool execution.

Question: Should BeforeToolsEvent have a cancel_tools property to cancel the entire batch?

• Similar to cancel_tool but applies to all tools in the batch
• Could be a boolean or string (like cancel_tool)
• The TypeScript version doesn't have this feature

Options:

• Option A: Add cancel_tools property (writable, similar to cancel_tool)
• Option B: Don't add it (keep closer to TypeScript parity)

3. Event Data Structure

The TypeScript version only includes agent and message. Python's individual BeforeToolCallEvent includes more fields.

Question: What fields should the Python events contain?

TypeScript has:

• agent: AgentData
• message: Message

Python could have (considering Python patterns):

• agent: Agent
• message: Message (contains the tool uses)
• tool_uses: list[ToolUse] (extracted for convenience?)
• invocation_state: dict[str, Any] (like BeforeToolCallEvent?)

Options:

• Option A: Minimal (match TypeScript exactly): agent and message only
• Option B: Extended (match Python patterns): add tool_uses list and invocation_state
• Option C: Hybrid: add tool_uses for convenience, skip invocation_state

4. Experimental Bidi System

Question: Should these events also be added to the experimental bidirectional streaming system?

• The bidi system has BidiBeforeToolCallEvent and BidiAfterToolCallEvent
• Should we also add BidiBeforeToolsEvent and BidiAfterToolsEvent?
• Or is batch tool execution not relevant for the bidi use case?

---

My Recommendations

Based on the repository patterns and your stated use case, I recommend:

1. Interruptibility: ✅ Make BeforeToolsEvent interruptible

   • Directly supports your approval use case
   • Consistent with Python's BeforeToolCallEvent

2. Batch Cancellation: ✅ Add cancel_tools property

   • Provides a way to cancel all tools after approval is denied
   • Consistent with Python's individual tool cancellation pattern

3. Event Data: Option B (Extended)

   • Include tool_uses list for easy access to the batch
   • Include invocation_state for consistency with BeforeToolCallEvent
   • Provides more flexibility for Python developers

4. Bidi System: ❌ Skip for now

   • Can be added later if needed
   • Not clear if batch approval is relevant for realtime streaming

---

Please let me know your preferences on these questions, and I'll prepare the implementation accordingly!

[github-actions]

I've analyzed the repository and compared it with the TypeScript SDK implementation. I've posted a detailed comment on issue #25 with:

1. Repository Analysis: Understanding of the current state and where the implementation would go
2. Clarifying Questions: 4 key design questions about:
   • Whether BeforeToolsEvent should be interruptible (for your approval use case)
   • Whether to add a cancel_tools property
   • What data fields the events should contain
   • Whether to add these events to the experimental bidi system

I've also included my recommendations based on Python SDK patterns and your stated use case.

Please review the questions on the issue and let me know your preferences. Once I have your answers, I'll prepare a comprehensive task description with implementation requirements ready for development.

[zastrowm]

/strands

Clarifying Questions

To ensure the implementation meets your needs and maintains API consistency, I have the following questions:

1. Interruptibility for Approval Use Case

Your issue mentions using these events for "requesting approval on a batch of tool calls through the interrupt mechanism."

Question: Should BeforeToolsEvent be interruptible (like BeforeToolCallEvent)?

• This would allow hook callbacks to call event.interrupt() to pause execution and request human approval
• The TypeScript version doesn't appear to support interrupts, but Python's BeforeToolCallEvent does
• This would enable the approval use case you mentioned

Options:

• Option A: Make it interruptible (extends _Interruptible mixin)
• Option B: Keep it non-interruptible (like TypeScript)

Make it interruptable

2. Batch Cancellation Property

Python's BeforeToolCallEvent has a cancel_tool property that can cancel a single tool execution.

Question: Should BeforeToolsEvent have a cancel_tools property to cancel the entire batch?

• Similar to cancel_tool but applies to all tools in the batch
• Could be a boolean or string (like cancel_tool)
• The TypeScript version doesn't have this feature

Options:

• Option A: Add cancel_tools property (writable, similar to cancel_tool)
• Option B: Don't add it (keep closer to TypeScript parity)

Option B

3. Event Data Structure

The TypeScript version only includes agent and message. Python's individual BeforeToolCallEvent includes more fields.

Question: What fields should the Python events contain?

TypeScript has:

• agent: AgentData
• message: Message

Python could have (considering Python patterns):

• agent: Agent
• message: Message (contains the tool uses)
• tool_uses: list[ToolUse] (extracted for convenience?)
• invocation_state: dict[str, Any] (like BeforeToolCallEvent?)

Options:

• Option A: Minimal (match TypeScript exactly): agent and message only
• Option B: Extended (match Python patterns): add tool_uses list and invocation_state

Option C: Hybrid: add tool_uses for convenience, skip invocation_state

4. Experimental Bidi System

Question: Should these events also be added to the experimental bidirectional streaming system?

• The bidi system has BidiBeforeToolCallEvent and BidiAfterToolCallEvent
• Should we also add BidiBeforeToolsEvent and BidiAfterToolsEvent?
• Or is batch tool execution not relevant for the bidi use case?

Bidi System: ❌ Skip for now

[github-actions]

Task Refinement Complete

Summary

Issue #25 has been refined and is ready for implementation. The task description has been updated with comprehensive implementation requirements based on our clarification discussion.

What Was Accomplished

✅ Repository Analysis:

• Analyzed current Python SDK hook system and tool execution flow
• Compared with TypeScript SDK implementation for parity
• Identified integration points in executors and event loop

✅ Design Clarifications:

• Confirmed BeforeToolsEvent should be interruptible for approval workflows
• Decided against cancel_tools property to maintain simplicity
• Chose hybrid data structure: agent, message, and tool_uses fields
• Agreed to skip bidi system support for now

✅ Implementation Requirements:

• Detailed event specifications with all fields and behaviors
• File modification list with specific paths
• Event flow diagram showing integration with existing hooks
• Comprehensive testing requirements (unit and integration)
• Complete acceptance criteria checklist

Key Design Decisions

1. BeforeToolsEvent: Interruptible, triggered before batch execution
2. AfterToolsEvent: Reverse callback ordering, triggered after all tools complete
3. Data Structure: agent, message, tool_uses (no invocation_state)
4. Scope: No bidi support, no batch cancellation property

Ready for Implementation

The issue description now contains all information needed to implement this feature, including:

• Clear specifications for both event classes
• Integration points in sequential and concurrent executors
• Testing strategy with specific test cases
• Acceptance criteria for verification
• Technical constraints and patterns to follow

This feature can be implemented in a single pull request and should take approximately 2-3 days for a developer familiar with the codebase.

[zastrowm]

/strands implement

[github-actions]

Unable to create pull request via API. You can create it manually by clicking here.