feat(hooks): Add hook decorator

[mkmeral]

Description

This PR adds a @hook decorator that transforms Python functions into HookProvider implementations with automatic event type detection from type hints.

Motivation

Defining hooks currently requires implementing the HookProvider protocol with a class, which is verbose for simple use cases:

# Current approach - verbose
class LoggingHooks(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=[LoggingHooks()])

The @hook decorator provides a simpler function-based approach that reduces boilerplate while maintaining full compatibility with the existing hooks system.

Resolves: #1483

Public API Changes

New @hook decorator exported from strands and strands.hooks:

# After - concise
from strands import Agent, hook
from strands.hooks import BeforeToolCallEvent

@hook
def log_tool_calls(event: BeforeToolCallEvent) -> None:
    print(f"Tool: {event.tool_use}")

agent = Agent(hooks=[log_tool_calls])

The decorator supports multiple usage patterns:

# Type hint detection
@hook
def my_hook(event: BeforeToolCallEvent) -> None: ...

# Explicit event type
@hook(event=BeforeToolCallEvent)
def my_hook(event) -> None: ...

# Multiple events via parameter
@hook(events=[BeforeToolCallEvent, AfterToolCallEvent])
def my_hook(event) -> None: ...

# Multiple events via Union type
@hook
def my_hook(event: BeforeToolCallEvent | AfterToolCallEvent) -> None: ...

# Async hooks
@hook
async def my_hook(event: BeforeToolCallEvent) -> None: ...

# Class methods
class MyHooks:
    @hook
    def my_hook(self, event: BeforeToolCallEvent) -> None: ...

Agent injection is available for hooks handling HookEvent subclasses:

@hook
def my_hook(event: BeforeToolCallEvent, agent: Agent) -> None:
    print(f"Agent {agent.name} calling tool")

Related Issues

Fixes #1483

Documentation PR

No documentation changes required.

Type of Change

New feature

Testing

• Added comprehensive unit tests (53 test cases)
• Tests cover: basic usage, explicit events, multi-events, union types, async, class methods, agent injection, error handling
• 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.

[codecov]

Codecov Report

❌ Patch coverage is 96.69421% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/strands/hooks/decorator.py	96.63%	2 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!