Update docstrings

Author: Unshure

src/strands/__init__.py

@@ -4,15 +4,14 @@
 from .agent.agent import Agent
 from .agent.base import AgentBase
 from .event_loop._retry import ModelRetryStrategy
-from .plugins import Plugin, hook
+from .plugins import Plugin
 from .tools.decorator import tool
 from .types.tools import ToolContext
 
 __all__ = [
     "Agent",
     "AgentBase",
     "agent",
-    "hook",
     "models",
     "ModelRetryStrategy",
     "Plugin",

src/strands/plugins/__init__.py

@@ -2,43 +2,6 @@
 
 This module provides a composable mechanism for building objects that can
 extend agent behavior through automatic hook and tool registration.
-
-Example Usage with Decorators (recommended):
-    ```python
-    from strands.plugins import Plugin, hook
-    from strands.hooks import BeforeModelCallEvent
-    from strands import tool
-
-    class LoggingPlugin(Plugin):
-        name = "logging"
-
-        @hook
-        def on_model_call(self, event: BeforeModelCallEvent) -> None:
-            print(f"Model called for {event.agent.name}")
-
-        @tool
-        def log_message(self, message: str) -> str:
-            '''Log a message.'''
-            print(message)
-            return "Logged"
-    ```
-
-Example Usage with Custom Initialization:
-    ```python
-    from strands.plugins import Plugin
-    from strands.hooks import BeforeModelCallEvent
-
-    class LoggingPlugin(Plugin):
-        name = "logging"
-
-        def init_agent(self, agent: Agent) -> None:
-            # Custom initialization - no super() needed
-            # Decorated hooks/tools are auto-registered by the registry
-            agent.hooks.add_callback(BeforeModelCallEvent, self.on_model_call)
-
-        def on_model_call(self, event: BeforeModelCallEvent) -> None:
-            print(f"Model called for {event.agent.name}")
-    ```
 """
 
 from .decorator import hook

src/strands/plugins/plugin.py

@@ -9,8 +9,8 @@
 from collections.abc import Awaitable
 from typing import TYPE_CHECKING
 
+from ..hooks.registry import HookCallback
 from ..tools.decorator import DecoratedFunctionTool
-from .decorator import _WrappedHookCallable
 
 if TYPE_CHECKING:
     from ..agent import Agent
@@ -27,8 +27,8 @@ class Plugin(ABC):
 
     Attributes:
         name: A stable string identifier for the plugin (must be provided by subclass)
-        hooks: List of hooks the plugin provides, auto-discovered from @hook decorated methods
-        tools: List of tools the plugin provides, auto-discovered from @tool decorated methods
+        hooks: Hooks attached to the agent, auto-discovered from @hook decorated methods during __init__
+        tools: Tools attached to the agent, auto-discovered from @tool decorated methods during __init__
 
     Example using decorators (recommended):
         ```python
@@ -49,6 +49,10 @@ def my_tool(self, param: str) -> str:
                 return f"Result: {param}"
         ```
 
+        Note: Decorated methods are registered in declaration order, with parent
+        class methods registered before child class methods. If a child overrides
+        a parent's decorated method, only the child's version is registered.
+
     Example with custom initialization:
         ```python
         class MyPlugin(Plugin):
@@ -57,7 +61,7 @@ class MyPlugin(Plugin):
             def init_agent(self, agent: Agent) -> None:
                 # Custom initialization logic - no super() needed
                 # Decorated hooks/tools are auto-registered by the plugin registry
-                agent.hooks.add_callback(BeforeModelCallEvent, self.custom_hook)
+                agent.add_hook(self.custom_hook)
 
             def custom_hook(self, event: BeforeModelCallEvent):
                 print(event)
@@ -76,12 +80,12 @@ def __init__(self) -> None:
         Scans the class for methods decorated with @hook and @tool and stores
         references for later registration when the plugin is attached to an agent.
         """
-        self._hooks: list[_WrappedHookCallable] = []
+        self._hooks: list[HookCallback] = []
         self._tools: list[DecoratedFunctionTool] = []
         self._discover_decorated_methods()
 
     @property
-    def hooks(self) -> list[_WrappedHookCallable]:
+    def hooks(self) -> list[HookCallback]:
         """List of hooks the plugin provides, auto-discovered from @hook decorated methods."""
         return self._hooks
 
@@ -120,8 +124,7 @@ def init_agent(self, agent: "Agent") -> None | Awaitable[None]:
         """Initialize the agent instance.
 
         Override this method to add custom initialization logic. Decorated
-        hooks and tools are automatically registered by the plugin registry,
-        so there's no need to call super().init_agent(agent).
+        hooks and tools are automatically registered by the plugin registry.
 
         Args:
             agent: The agent instance to initialize.

src/strands/plugins/registry.py

@@ -97,6 +97,10 @@ def add_and_init(self, plugin: Plugin) -> None:
     def _register_hooks(self, plugin: Plugin) -> None:
         """Register all discovered hooks from the plugin with the agent.
 
+        Warns if a hook callback is already registered for an event type,
+        which can happen when init_agent() manually registers a hook that
+        is also decorated with @hook.
+
         Args:
             plugin: The plugin whose hooks should be registered.
         """

tests/strands/agent/test_agent.py

@@ -14,7 +14,7 @@
 from pydantic import BaseModel
 
 import strands
-from strands import Agent, ToolContext
+from strands import Agent, Plugin, ToolContext
 from strands.agent import AgentResult
 from strands.agent.conversation_manager.null_conversation_manager import NullConversationManager
 from strands.agent.conversation_manager.sliding_window_conversation_manager import SlidingWindowConversationManager
@@ -2625,6 +2625,8 @@ def test_agent_plugins_sync_initialization():
     """Test that plugins with sync init_agent are initialized correctly."""
     plugin_mock = unittest.mock.Mock()
     plugin_mock.name = "test-plugin"
+    plugin_mock.hooks = []
+    plugin_mock.tools = []
     plugin_mock.init_agent = unittest.mock.Mock()
 
     agent = Agent(
@@ -2639,6 +2641,8 @@ def test_agent_plugins_async_initialization():
     """Test that plugins with async init_agent are initialized correctly."""
     plugin_mock = unittest.mock.Mock()
     plugin_mock.name = "async-plugin"
+    plugin_mock.hooks = []
+    plugin_mock.tools = []
     plugin_mock.init_agent = unittest.mock.AsyncMock()
 
     agent = Agent(
@@ -2655,10 +2659,14 @@ def test_agent_plugins_multiple_in_order():
 
     plugin1 = unittest.mock.Mock()
     plugin1.name = "plugin1"
+    plugin1.hooks = []
+    plugin1.tools = []
     plugin1.init_agent = unittest.mock.Mock(side_effect=lambda agent: call_order.append("plugin1"))
 
     plugin2 = unittest.mock.Mock()
     plugin2.name = "plugin2"
+    plugin2.hooks = []
+    plugin2.tools = []
     plugin2.init_agent = unittest.mock.Mock(side_effect=lambda agent: call_order.append("plugin2"))
 
     Agent(
@@ -2673,7 +2681,7 @@ def test_agent_plugins_can_register_hooks():
     """Test that plugins can register hooks during initialization."""
     hook_called = []
 
-    class TestPlugin:
+    class TestPlugin(Plugin):
         name = "hook-plugin"
 
         def init_agent(self, agent):