feat(plugins): improve plugin creation devex with @hook and @tool decorators

[Unshure]

Motivation

Currently, plugin authors must manually register hooks in their init_plugin() method, which is verbose and error-prone:

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

This PR enables declarative hook registration using a @hook decorator, making plugin development more intuitive and reducing boilerplate:

class MyPlugin(Plugin):
    name = "my-plugin"

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

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

Resolves: #1739

Public API Changes

New @hook decorator

The @hook decorator marks methods for automatic registration:

from strands.plugins import Plugin, hook
from strands.hooks import BeforeModelCallEvent, AfterModelCallEvent

class MyPlugin(Plugin):
    name = "my-plugin"

    # Single event type - inferred from type hint
    @hook
    def on_model_call(self, event: BeforeModelCallEvent):
        print(event)

    # Union types - registers for multiple events
    @hook
    def on_any_model_event(self, event: BeforeModelCallEvent | AfterModelCallEvent):
        print(event)
``

[codecov]

Codecov Report

❌ Patch coverage is 94.50549% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/strands/hooks/_type_inference.py	91.42%	3 Missing ⚠️
src/strands/plugins/plugin.py	93.33%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[mkmeral]

/strands don't say mutable or immutable for in the comment. just say this is a list of hooks/tools the plugin provides, autogenerated from decorators

[mkmeral]

/strands for discovering decorated methods, instead of using dir, let's use MRO (method resolution order), so we keep the order of hooks as they are defined in the class. See example code

def _discover_decorated_methods(self) -> None:
    """Scan class for @hook and @tool decorated methods in declaration order."""
    seen = set()
    # Walk MRO so parent class hooks come first, child overrides win
    for cls in reversed(type(self).__mro__):
        for name, attr in cls.__dict__.items():
            if name in seen:
                continue
            seen.add(name)

            # Get the bound method from self
            try:
                bound = getattr(self, name)
            except Exception:
                continue

            if hasattr(bound, "_hook_event_types") and callable(bound):
                self._hooks.append(bound)

            if isinstance(bound, DecoratedFunctionTool):
                self._tools.append(bound)

[github-actions]

Updated hook/tool discovery to use MRO instead of dir() to preserve definition order. Parent class hooks come first, child overrides win. Added test to verify definition order is preserved.

[github-actions]

Review Update - Commit 703cece

All feedback from @mkmeral has been addressed:

Feedback	Status
Type annotation bug (list[TEvent] → list[type[TEvent]])	✅ Fixed
@hook export from top-level strands	✅ Fixed
MRO-based discovery for definition order	✅ Fixed
Docstring wording ("read-only" removed)	✅ Fixed

Architecture Improvements

The refactoring brought a cleaner design:

• Registration moved to _PluginRegistry: Hooks/tools are now auto-registered by the registry, not the plugin itself
• No super() needed: Plugin.init_agent() is purely for custom initialization
• MRO ordering: Parent class hooks come first, child overrides win
• Public hooks/tools properties: Expose discovered methods for inspection

Recommendation: ✅ Ready for approval - Clean implementation with all feedback incorporated.