[FEATURE] Create `@hook` decorator for Plugins

[Unshure]

Overview

Add a @hook decorator for Plugins to simplify hook registration, and convert the Plugin from a Protocol to a base class that auto-discovers and registers decorated hooks and tools.

Problem Statement

Currently, plugin authors must manually register hooks in their init_plugin() method:

class Steering:
    name = "steering"
    
    def init_plugin(self, agent: Agent) -> None:
        agent.add_hook(self.log_call, BeforeModelCallEvent)

Proposed Solution

Enable declarative hook and tool registration using decorators:

class Steering(Plugin):
    name = "steering"

    @hook
    def log_call(self, event: BeforeModelCallEvent):
        print(event)

    @tool
    def printer(self, log: str):
        print(log)
        return "Printed log"

---

Implementation Requirements

1. Create @hook Decorator

Location: src/strands/plugins/decorator.py (new file)

Behavior:

• Mark methods as hook callbacks for automatic registration
• Infer event type from the callback's type hint (consistent with HookRegistry.add_callback)
• Support both @hook and @hook() syntax
• Support union types for multiple event types (e.g., BeforeModelCallEvent | AfterModelCallEvent)
• Store hook metadata on the decorated method for later discovery

Example Usage:

@hook
def on_model_call(self, event: BeforeModelCallEvent):
    print(event)

@hook
def on_any_model_event(self, event: BeforeModelCallEvent | AfterModelCallEvent):
    print(event)

2. Convert Plugin from Protocol to Base Class

Location: src/strands/plugins/plugin.py

Breaking Change: This is an intentional breaking change from the current Protocol-based approach.

Behavior:

• __init__(): Scan the class for @hook and @tool decorated methods and store references
• init_plugin(agent): Default implementation that:
  • Registers all discovered @hook methods with the agent's hook registry
  • Adds all discovered @tool methods to the agent's tools list
• Subclasses can override init_plugin() and call super().init_plugin(agent) for custom behavior

Requirements:

• name: str attribute still required (can be class attribute or property)
• Support both sync and async init_plugin() implementations
• Each agent gets its own registration (plugin can be attached to multiple agents)

3. Auto-Registration of Tools

Behavior:

• Methods decorated with existing @tool decorator should be auto-discovered
• Tools are added to the agent's tools list during init_plugin()
• The bound method (with self) should be registered, not the unbound function

4. Public API Exports

Update src/strands/plugins/__init__.py:

from .plugin import Plugin
from .decorator import hook

__all__ = ["Plugin", "hook"]

Update src/strands/__init__.py (if appropriate):

• Consider exporting hook from the top-level strands namespace

---

Acceptance Criteria

• @hook decorator created and functional
• @hook infers event types from type hints
• @hook supports union types for multiple events
• Plugin converted from Protocol to base class
• Plugin.__init__() discovers decorated methods
• Plugin.init_plugin() auto-registers hooks and tools
• @tool decorated methods in plugins are auto-added to agent's tools
• Multiple agents can use the same plugin instance (each gets its own registrations)
• Unit tests cover all new functionality
• Existing @tool decorator continues to work standalone (no breaking changes to tool system)

---

Files to Create/Modify

New Files

• src/strands/plugins/decorator.py - @hook decorator implementation

Modified Files

• src/strands/plugins/plugin.py - Convert Protocol to base class
• src/strands/plugins/__init__.py - Export hook decorator
• src/strands/__init__.py - Optionally export hook
• tests/strands/plugins/test_plugins.py - Update existing tests for new class-based approach
• tests/strands/plugins/test_hook_decorator.py - New tests for @hook decorator

---

Technical Notes

Decorator Implementation Pattern

Follow the existing @tool decorator pattern in src/strands/tools/decorator.py:

• Support both @hook and @hook() call patterns
• Use functools.wraps to preserve function metadata
• Store metadata as attributes on the decorated function (e.g., _hook_event_types)

Method Discovery in __init__

def __init__(self):
    self._hooks = []
    self._tools = []
    for name in dir(self):
        attr = getattr(self, name)
        if hasattr(attr, '_hook_event_types'):
            self._hooks.append(attr)
        if isinstance(attr, DecoratedFunctionTool):
            self._tools.append(attr)

Backward Compatibility Consideration

This is a breaking change from the Protocol-based approach. Users with existing plugins implementing the Protocol will need to:

1. Inherit from Plugin class instead of implementing the protocol
2. Their existing init_plugin() implementations will continue to work

---

Additional Context

• Related documentation: docs/HOOKS.md
• Existing hook events: src/strands/hooks/events.py
• Existing tool decorator: src/strands/tools/decorator.py

[Unshure]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

I've analyzed the repository structure, existing Plugin and Hook systems, and the @tool decorator pattern. Here are my findings and questions to ensure proper implementation:

Repository Context

Current Plugin Architecture

• Plugin is a Protocol (not a class) defined in src/strands/plugins/plugin.py
• Requires: name: str attribute + init_plugin(agent) -> None | Awaitable[None] method
• Plugins manually register hooks via agent.add_hook() in their init_plugin() method

Current Hook System

• Events: BeforeModelCallEvent, AfterModelCallEvent, BeforeToolCallEvent, AfterToolCallEvent, etc.
• HookRegistry supports both explicit event type specification and type hint inference
• Supports both sync and async callbacks (except AgentInitializedEvent must be sync)

Existing @tool Decorator Pattern

• @tool transforms functions into DecoratedFunctionTool objects
• Extracts metadata from docstrings and type hints
• Supports both @tool and @tool() syntax

Clarifying Questions

1. @hook Decorator Behavior

Q1.1: Should the @hook decorator infer the event type from the callback's type hint (like HookRegistry.add_callback currently supports), or should it require an explicit event type argument?

Example with type hint inference:

@hook
def log_call(self, event: BeforeModelCallEvent):
    print(event)

Example with explicit event type:

@hook(BeforeModelCallEvent)
def log_call(self, event):
    print(event)

Q1.2: Should @hook support registering the same callback for multiple event types (e.g., union types or a list)?

@hook
def handle_both(self, event: BeforeModelCallEvent | AfterModelCallEvent):
    ...

2. Plugin Architecture Change

Q2.1: Should Plugin be converted from a Protocol to a base class, or should we maintain backward compatibility by keeping the Protocol and adding an optional base class (e.g., PluginBase)?

Current Protocol approach (users implement from scratch):

class Steering:
    name = "steering"
    
    def init_plugin(self, agent: Agent) -> None:
        agent.add_hook(self.log_call, BeforeModelCallEvent)

Base class approach (auto-discovery of decorated methods):

class Steering(PluginBase):
    name = "steering"
    
    @hook
    def log_call(self, event: BeforeModelCallEvent):
        print(event)

Q2.2: If we add a base class, should the auto-registration happen:

• In __init__ of the Plugin class?
• In init_plugin() when the plugin is attached to an agent?

3. Tools in Plugins

Q3.1: Your example shows @tool decorated methods in a Plugin. Should tools also be auto-registered to the agent when the plugin is attached?

@tool
def printer(self, log: str):
    print(log)
    return "Printed log"

Q3.2: If so, should they be added to the agent's tools list, or is there another integration point you have in mind?

4. Additional Considerations

Q4.1: What should happen if a plugin with hooks/tools is attached to multiple agents - should each agent get its own copy of the hooks/tools?

Q4.2: Are there any naming conventions you'd prefer for the decorator or base class (e.g., @hook, @on_event, PluginBase, BasePlugin)?

Scope Assessment

This feature appears appropriately scoped for a single PR. The implementation would involve:

• Creating the @hook decorator (new file or in existing module)
• Optionally adding a base class for plugins
• Auto-discovery logic for decorated methods
• Unit tests for all new functionality
• Documentation updates

Please let me know your thoughts on these questions!

[Unshure]

/strands

1. infer from the typehint. yes.
2. convert to class. init identifies decorated methods on the class, and init_plugin will have a default implementation where that registration happens.
3. yes. Added to the agents tool list
4. The hooks and tools should be attached to each agent. No, go with the proposed names.

[Unshure]

/strands implement

[github-actions]

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