feat(plugins): implement Phase 2 hook integration (#845)

* feat(plugins): implement Phase 2 hook integration

- Add hook_modules field to Plugin dataclass
- Implement hook discovery in _load_plugin()
- Add register_plugin_hooks() function to auto-register hooks
- Integrate plugin hooks with init_hooks()
- Fix Path conversion for plugin paths
- Add comprehensive tests for hook discovery and registration
- Update documentation with Phase 2 hooks support

Fixes #842 (Phase 2)

Co-authored-by: Bob <bob@superuserlabs.org>

* style(plugins): convert empty enabled list to None for consistency

Addresses Greptile review feedback about style inconsistency between tools
and hooks handling of empty enabled_plugins list. Both functions already
treat [] and None identically (falsy check), but for clarity and consistency,
explicitly convert empty list to None at call site using 'or None' pattern.

This makes intent clear: empty config means 'use all plugins' (None behavior)
rather than passing falsy-but-not-None value.

Author: TimeToBuildBob

docs/plugins.md

@@ -11,7 +11,9 @@ my_plugin/
 ├── tools/               # Tool modules (optional)
 │   ├── __init__.py     # Makes tools/ a package
 │   └── my_tool.py      # Individual tool modules
-├── hooks/               # Hook modules (future)
+├── hooks/               # Hook modules (optional)
+│   ├── __init__.py     # Makes hooks/ a package
+│   └── my_hook.py      # Individual hook modules
 └── commands/            # Command modules (future)
 
 
@@ -74,9 +76,15 @@ Hello from my plugin!
 ## How It Works
 
 1. **Discovery**: gptme searches configured plugin paths for directories with `__init__.py`
-2. **Loading**: For each plugin, gptme discovers tool modules in `tools/` subdirectory
-3. **Integration**: Plugin tools are loaded using the same mechanism as built-in tools
-4. **Availability**: Tools appear in `--tools` list and can be used like built-in tools
+2. **Loading**: For each plugin, gptme discovers:
+   - Tool modules in `tools/` subdirectory
+   - Hook modules in `hooks/` subdirectory
+3. **Integration**:
+   - Plugin tools are loaded using the same mechanism as built-in tools
+   - Plugin hooks are registered during initialization via their `register()` functions
+4. **Availability**:
+   - Tools appear in `--tools` list and can be used like built-in tools
+   - Hooks are automatically triggered at appropriate lifecycle points
 
 ## Plugin Tool Modules
 
@@ -105,6 +113,103 @@ my_plugin/tools/
 
 Each file will be imported as `my_plugin.tools.tool1`, `my_plugin.tools.tool2`, etc.
 
+
+
+## Plugin Hook Modules
+
+Plugins can provide hooks to extend gptme's behavior at various lifecycle points, similar to how tools work.
+
+### Option 1: hooks/ as a Package
+
+Create `hooks/__init__.py` and define a `register()` function:
+
+```python
+# my_plugin/hooks/__init__.py
+from gptme.hooks import HookType, register_hook
+from gptme.message import Message
+
+def my_session_hook(logdir, workspace, initial_msgs):
+    """Hook called at session start."""
+    yield Message("system", f"Plugin initialized in workspace: {workspace}")
+
+def register():
+    """Register all hooks from this module."""
+    register_hook(
+        "my_plugin.session_start",
+        HookType.SESSION_START,
+        my_session_hook,
+        priority=0
+    )
+```
+
+### Option 2: Individual Hook Files
+
+Create individual hook modules without `hooks/__init__.py`:
+
+```python
+# my_plugin/hooks/logging_hook.py
+from gptme.hooks import HookType, register_hook
+from gptme.message import Message
+
+def log_tool_execution(log, workspace, tool_use):
+    """Log tool executions."""
+    print(f"Executing tool: {tool_use.tool}")
+    yield  # Hooks must be generators
+
+def register():
+    """Register hooks from this module."""
+    register_hook(
+        "my_plugin.log_tool",
+        HookType.TOOL_PRE_EXECUTE,
+        log_tool_execution,
+        priority=0
+    )
+```
+
+### Hook Types
+
+Available hook types:
+- `SESSION_START` - Called at session start
+- `SESSION_END` - Called at session end
+- `TOOL_PRE_EXECUTE` - Before tool execution
+- `TOOL_POST_EXECUTE` - After tool execution
+- `FILE_PRE_SAVE` - Before saving a file
+- `FILE_POST_SAVE` - After saving a file
+- `GENERATION_PRE` - Before generating response
+- `GENERATION_POST` - After generating response
+- And more (see `gptme.hooks.HookType`)
+
+### Hook Registration
+
+Every hook module must have a `register()` function that calls `register_hook()` for each hook it provides. The plugin system automatically calls `register()` during initialization.
+
+## Example: Logging Plugin
+
+A complete example of a plugin that logs tool executions:
+
+```python
+# my_logging_plugin/hooks/tool_logger.py
+from gptme.hooks import HookType, register_hook
+import logging
+
+logger = logging.getLogger(__name__)
+
+def log_tool_pre(log, workspace, tool_use):
+    """Log before tool execution."""
+    logger.info(f"Executing tool: {tool_use.tool} with args: {tool_use.args}")
+    yield  # Hooks must be generators
+
+def log_tool_post(log, workspace, tool_use, result):
+    """Log after tool execution."""
+    logger.info(f"Tool {tool_use.tool} completed")
+    yield
+
+def register():
+    register_hook("tool_logger.pre", HookType.TOOL_PRE_EXECUTE, log_tool_pre)
+    register_hook("tool_logger.post", HookType.TOOL_POST_EXECUTE, log_tool_post)
+```
+
+
 ## Example: Weather Plugin
 
 A complete example of a weather information plugin:

gptme/hooks/__init__.py

@@ -4,6 +4,7 @@
 from collections.abc import Generator
 from dataclasses import dataclass, field
 from enum import Enum
+from pathlib import Path
 from time import time
 from typing import Any, Literal, overload
 
@@ -56,7 +57,6 @@ class HookType(str, Enum):
     LOOP_CONTINUE = "loop_continue"  # Decide whether/how to continue the chat loop
 
 
-from pathlib import Path
 from typing import TYPE_CHECKING, Protocol
 
 if TYPE_CHECKING:
@@ -565,3 +565,14 @@ def init_hooks() -> None:
     markdown_validation.register()
     time_awareness.register()
     token_awareness.register()
+
+    # Register plugin hooks
+    from ..config import get_config
+    from ..plugins import register_plugin_hooks
+
+    config = get_config()
+    if config.project and config.project.plugins and config.project.plugins.paths:
+        register_plugin_hooks(
+            plugin_paths=[Path(p) for p in config.project.plugins.paths],
+            enabled_plugins=config.project.plugins.enabled or None,
+        )

gptme/plugins/__init__.py

@@ -25,6 +25,7 @@
     "Plugin",
     "discover_plugins",
     "get_plugin_tool_modules",
+    "register_plugin_hooks",
 ]
 
 
@@ -37,7 +38,8 @@ class Plugin:
 
     # Module names for discovered components
     tool_modules: list[str] = field(default_factory=list)
-    # Future: hook_modules, command_modules
+    hook_modules: list[str] = field(default_factory=list)
+    # Future: command_modules
 
 
 def discover_plugins(plugin_paths: list[Path]) -> list[Plugin]:
@@ -117,10 +119,21 @@ def _load_plugin(plugin_path: Path) -> Plugin | None:
                 plugin.tool_modules.append(module_name)
                 logger.debug(f"  Found tool module: {module_name}")
 
-    # Future: Discover hooks similarly
-    # hooks_dir = plugin_path / "hooks"
-    # if hooks_dir.exists() and hooks_dir.is_dir():
-    #     plugin.hook_modules = _discover_hook_modules(plugin_name, hooks_dir)
+    # Discover hooks
+    hooks_dir = plugin_path / "hooks"
+    if hooks_dir.exists() and hooks_dir.is_dir():
+        if (hooks_dir / "__init__.py").exists():
+            # hooks/ is a package, register the package module
+            plugin.hook_modules.append(f"{plugin_name}.hooks")
+            logger.debug(f"  Found hooks package: {plugin_name}.hooks")
+        else:
+            # hooks/ is a directory with individual modules
+            for hook_file in hooks_dir.glob("*.py"):
+                if hook_file.name.startswith("_"):
+                    continue
+                module_name = f"{plugin_name}.hooks.{hook_file.stem}"
+                plugin.hook_modules.append(module_name)
+                logger.debug(f"  Found hook module: {module_name}")
 
     # Future: Discover commands similarly
     # commands_dir = plugin_path / "commands"
@@ -161,3 +174,50 @@ def get_plugin_tool_modules(
 
     logger.info(f"Loaded {len(tool_modules)} tool modules from {len(plugins)} plugins")
     return tool_modules
+
+
+def register_plugin_hooks(
+    plugin_paths: list[Path],
+    enabled_plugins: list[str] | None = None,
+) -> None:
+    """
+    Register hooks from all enabled plugins.
+
+    Discovers plugins, imports their hook modules, and calls their register()
+    functions to register hooks with the gptme hook system.
+
+    Args:
+        plugin_paths: Paths to search for plugins
+        enabled_plugins: Optional allowlist of plugin names (None = all)
+    """
+    plugins = discover_plugins(plugin_paths)
+
+    hooks_registered = 0
+    for plugin in plugins:
+        # Apply allowlist if provided
+        if enabled_plugins and plugin.name not in enabled_plugins:
+            logger.debug(f"Skipping plugin {plugin.name}: not in allowlist")
+            continue
+
+        # Register hooks from each module
+        for module_name in plugin.hook_modules:
+            try:
+                # Import the hook module
+                module = __import__(module_name, fromlist=["register"])
+
+                # Call the module's register() function if it exists
+                if hasattr(module, "register"):
+                    module.register()
+                    hooks_registered += 1
+                    logger.debug(f"Registered hooks from {module_name}")
+                else:
+                    logger.warning(
+                        f"Hook module {module_name} has no register() function"
+                    )
+
+            except Exception as e:
+                logger.error(f"Failed to register hooks from {module_name}: {e}")
+
+    logger.info(
+        f"Registered {hooks_registered} hook modules from {len(plugins)} plugins"
+    )

tests/test_plugins.py

@@ -159,3 +159,107 @@ def test_discover_plugins_with_individual_tool_files():
         assert "my_plugin.tools.tool1" in plugin.tool_modules
         assert "my_plugin.tools.tool2" in plugin.tool_modules
         assert "my_plugin.tools._private" not in plugin.tool_modules
+
+
+def test_plugin_hooks_dataclass():
+    """Test Plugin dataclass with hook modules."""
+    plugin = Plugin(
+        name="test_plugin",
+        path=Path("/tmp/test_plugin"),
+        tool_modules=["test_plugin.tools"],
+        hook_modules=["test_plugin.hooks"],
+    )
+    assert plugin.hook_modules == ["test_plugin.hooks"]
+
+
+def test_discover_plugins_with_hooks():
+    """Test plugin discovery with hooks directory."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        plugin_dir = Path(tmpdir) / "my_plugin"
+        plugin_dir.mkdir()
+
+        # Create __init__.py
+        (plugin_dir / "__init__.py").write_text("# Plugin init")
+
+        # Create hooks directory with __init__.py
+        hooks_dir = plugin_dir / "hooks"
+        hooks_dir.mkdir()
+        (hooks_dir / "__init__.py").write_text("# Hooks init")
+
+        # Discover plugins
+        plugins = discover_plugins([Path(tmpdir)])
+
+        assert len(plugins) == 1
+        assert plugins[0].name == "my_plugin"
+        assert "my_plugin.hooks" in plugins[0].hook_modules
+
+
+def test_discover_plugins_with_individual_hook_modules():
+    """Test plugin discovery with individual hook module files."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        plugin_dir = Path(tmpdir) / "my_plugin"
+        plugin_dir.mkdir()
+
+        # Create __init__.py
+        (plugin_dir / "__init__.py").write_text("# Plugin init")
+
+        # Create hooks directory without __init__.py
+        hooks_dir = plugin_dir / "hooks"
+        hooks_dir.mkdir()
+
+        # Create individual hook modules
+        (hooks_dir / "my_hook.py").write_text("def my_hook(): pass")
+        (hooks_dir / "another_hook.py").write_text("def another_hook(): pass")
+
+        # Discover plugins
+        plugins = discover_plugins([Path(tmpdir)])
+
+        assert len(plugins) == 1
+        assert "my_plugin.hooks.my_hook" in plugins[0].hook_modules
+        assert "my_plugin.hooks.another_hook" in plugins[0].hook_modules
+
+
+def test_register_plugin_hooks():
+    """Test plugin hook registration."""
+    from gptme.hooks import HookType, clear_hooks, get_hooks
+    from gptme.plugins import register_plugin_hooks
+
+    # Clear any existing hooks
+    clear_hooks()
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        plugin_dir = Path(tmpdir) / "test_plugin"
+        plugin_dir.mkdir()
+
+        # Create __init__.py
+        (plugin_dir / "__init__.py").write_text("# Plugin init")
+
+        # Create hooks directory with a hook module
+        hooks_dir = plugin_dir / "hooks"
+        hooks_dir.mkdir()
+
+        # Create a hook module with register() function
+        hook_code = """
+from gptme.hooks import HookType, register_hook
+from gptme.message import Message
+
+def test_hook(**kwargs):
+    yield Message("system", "Test hook executed")
+
+def register():
+    register_hook(
+        "test_plugin.test_hook",
+        HookType.SESSION_START,
+        test_hook,
+        priority=0
+    )
+"""
+        (hooks_dir / "test_hooks.py").write_text(hook_code)
+
+        # Register plugin hooks
+        register_plugin_hooks([Path(tmpdir)])
+
+        # Verify hook was registered
+        hooks = get_hooks(HookType.SESSION_START)
+        hook_names = [h.name for h in hooks]
+        assert "test_plugin.test_hook" in hook_names