feat(hooks): add @hook decorator for simplified hook definitions

[strands-agent]

Description

This PR adds a @hook decorator that transforms Python functions into HookProvider implementations with automatic event type detection from type hints - mirroring the ergonomics of the existing @tool decorator.

Features

• Simple decorator syntax: @hook extracts event type from type hints
• Explicit event type: @hook(event=EventType) for functions without type hints
• Multi-event support: @hook(events=[...]) or Union types (A | B)
• Async support: Works with both sync and async hook functions
• Metadata preservation: Function name, docstring preserved via functools.wraps
• Direct invocation: Decorated hooks can be called directly for testing

Before (Class-based):

from strands.hooks import HookProvider, HookRegistry, BeforeToolCallEvent

class MyHooks(HookProvider):
    def register_hooks(self, registry: HookRegistry) -> None:
        registry.add_callback(BeforeToolCallEvent, self.on_tool_call)
    
    def on_tool_call(self, event: BeforeToolCallEvent) -> None:
        print(f"Tool: {event.tool_use}")

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

After (Decorator-based):

from strands import Agent, hook
from strands.hooks import BeforeToolCallEvent

@hook
def log_tool_calls(event: BeforeToolCallEvent) -> None:
    """Log all tool calls before execution."""
    print(f"Tool: {event.tool_use}")

agent = Agent(hooks=[log_tool_calls])

New Exports

# From strands
from strands import hook

# From strands.hooks
from strands.hooks import hook, DecoratedFunctionHook, FunctionHookMetadata, HookMetadata

Related Issues

Fixes #1483

Documentation PR

No documentation changes required - follows existing patterns established by @tool.

Type of Change

New feature (non-breaking addition)

Testing

• Added comprehensive unit tests (20 test cases)
• Tests cover: basic usage, explicit events, multi-events, union types, async, errors, mixed usage with class-based hooks
• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly (exports in __init__.py)
• My changes generate no new warnings
• Any dependent changes have been merged and published

[codecov]

Codecov Report

❌ Patch coverage is 87.75510% with 18 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/strands/hooks/decorator.py	87.58%	11 Missing and 7 partials ⚠️

📢 Thoughts on this report? Let us know!