fix(plugins): make hooks/tools mutable, fix type annotation, export hook

Address additional PR feedback:
- Make hooks and tools properties return mutable lists for filtering/customization
- Fix type annotation: _hook_event_types is list[type[TEvent]] not list[TEvent]
- Export @hook from top-level strands package (from strands import hook)
- Fix docstring typo: 'argument' -> 'attribute'
- Add tests for filtering hooks and tools

Author: strands-agent

src/strands/__init__.py

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

src/strands/plugins/decorator.py

@@ -21,9 +21,9 @@ def on_model_call(self, event: BeforeModelCallEvent):
 
 
 class _WrappedHookCallable(HookCallback, Generic[TEvent]):
-    """Wrapped version of HookCallback that includes a `_hook_event_types` argument."""
+    """Wrapped version of HookCallback that includes a `_hook_event_types` attribute."""
 
-    _hook_event_types: list[TEvent]
+    _hook_event_types: list[type[TEvent]]
 
 
 # Handle @hook

src/strands/plugins/plugin.py

@@ -81,22 +81,24 @@ def __init__(self) -> None:
         self._discover_decorated_methods()
 
     @property
-    def hooks(self) -> tuple[_WrappedHookCallable, ...]:
+    def hooks(self) -> list[_WrappedHookCallable]:
         """Discovered @hook decorated methods.
 
-        Returns a tuple of hook callbacks that will be auto-registered
-        when the plugin is attached to an agent.
+        Returns the list of hook callbacks that will be auto-registered
+        when the plugin is attached to an agent. This list is mutable,
+        allowing users to filter or modify hooks before registration.
         """
-        return tuple(self._hooks)
+        return self._hooks
 
     @property
-    def tools(self) -> tuple[DecoratedFunctionTool, ...]:
+    def tools(self) -> list[DecoratedFunctionTool]:
         """Discovered @tool decorated methods.
 
-        Returns a tuple of tools that will be auto-registered
-        when the plugin is attached to an agent.
+        Returns the list of tools that will be auto-registered
+        when the plugin is attached to an agent. This list is mutable,
+        allowing users to filter or modify tools before registration.
         """
-        return tuple(self._tools)
+        return self._tools
 
     def _discover_decorated_methods(self) -> None:
         """Scan class for @hook and @tool decorated methods."""

tests/strands/plugins/test_plugin_base_class.py

@@ -141,8 +141,8 @@ def decorated_hook(self, event: BeforeModelCallEvent):
         assert len(plugin.hooks) == 1
         assert plugin.hooks[0].__name__ == "decorated_hook"
 
-    def test_hooks_property_returns_tuple(self):
-        """Test that hooks property returns an immutable tuple."""
+    def test_hooks_property_returns_list(self):
+        """Test that hooks property returns a mutable list."""
 
         class MyPlugin(Plugin):
             name = "my-plugin"
@@ -152,10 +152,10 @@ def my_hook(self, event: BeforeModelCallEvent):
                 pass
 
         plugin = MyPlugin()
-        assert isinstance(plugin.hooks, tuple)
+        assert isinstance(plugin.hooks, list)
 
-    def test_tools_property_returns_tuple(self):
-        """Test that tools property returns an immutable tuple."""
+    def test_tools_property_returns_list(self):
+        """Test that tools property returns a mutable list."""
 
         class MyPlugin(Plugin):
             name = "my-plugin"
@@ -166,7 +166,53 @@ def my_tool(self, param: str) -> str:
                 return param
 
         plugin = MyPlugin()
-        assert isinstance(plugin.tools, tuple)
+        assert isinstance(plugin.tools, list)
+
+    def test_hooks_can_be_filtered(self):
+        """Test that hooks list can be modified before registration."""
+
+        class MyPlugin(Plugin):
+            name = "my-plugin"
+
+            @hook
+            def hook1(self, event: BeforeModelCallEvent):
+                pass
+
+            @hook
+            def hook2(self, event: BeforeInvocationEvent):
+                pass
+
+        plugin = MyPlugin()
+        assert len(plugin.hooks) == 2
+
+        # Filter out hook1
+        plugin.hooks[:] = [h for h in plugin.hooks if h.__name__ != "hook1"]
+        assert len(plugin.hooks) == 1
+        assert plugin.hooks[0].__name__ == "hook2"
+
+    def test_tools_can_be_filtered(self):
+        """Test that tools list can be modified before registration."""
+
+        class MyPlugin(Plugin):
+            name = "my-plugin"
+
+            @tool
+            def tool1(self, param: str) -> str:
+                """Tool 1."""
+                return param
+
+            @tool
+            def tool2(self, param: str) -> str:
+                """Tool 2."""
+                return param
+
+        plugin = MyPlugin()
+        assert len(plugin.tools) == 2
+
+        # Filter out tool1
+        plugin.tools[:] = [t for t in plugin.tools if t.tool_name != "tool1"]
+        assert len(plugin.tools) == 1
+        assert plugin.tools[0].tool_name == "tool2"
 
 
 class TestPluginRegistryAutoRegistration: