codepp 0.0.437__py3-none-any.whl

code_puppy/hook_engine/README.md

@@ -0,0 +1,105 @@
+# Hook Engine
+
+A standalone, testable hook execution system for processing events and executing
+configured hooks with pattern matching, timeout handling, and blocking capabilities.
+
+## Overview
+
+The Hook Engine provides a complete system for implementing event-driven automation
+through configurable hooks. It is compatible with Anthropic's Claude Code
+`.claude/settings.json` format.
+
+Features:
+- **Pattern matching** - Wildcards, file extensions, `&&` / `||` compound logic, regex
+- **Event types** - PreToolUse, PostToolUse, SessionStart, Stop, and more
+- **Async execution** - Non-blocking subprocess execution with per-hook timeouts
+- **Claude Code compatible stdin** - JSON payload on stdin, env vars for compatibility
+- **Blocking capability** - Exit code 1 vetoes the tool call
+- **Once-per-session** - Hooks that only run once per session
+- **Comprehensive validation** - Clear error messages for misconfigured hooks
+
+## Quick Start
+
+```python
+from code_puppy.hook_engine import HookEngine, EventData
+
+config = {
+    "PreToolUse": [{
+        "matcher": "Bash|agent_run_shell_command",
+        "hooks": [{
+            "type": "command",
+            "command": "bash .claude/hooks/my-check.sh",
+            "timeout": 5000
+        }]
+    }]
+}
+
+import asyncio
+
+engine = HookEngine(config)
+event_data = EventData(
+    event_type="PreToolUse",
+    tool_name="agent_run_shell_command",
+    tool_args={"command": "git status"}
+)
+
+async def main():
+    result = await engine.process_event("PreToolUse", event_data)
+    if result.blocked:
+        print(f"Blocked: {result.blocking_reason}")
+
+asyncio.run(main())
+```
+
+## Hook Input Format
+
+Scripts receive JSON on stdin (Claude Code compatible):
+
+```json
+{
+    "session_id": "codepuppy-session",
+    "hook_event_name": "PreToolUse",
+    "tool_name": "agent_run_shell_command",
+    "tool_input": {"command": "git status"},
+    "cwd": "/path/to/project",
+    "permission_mode": "default"
+}
+```
+
+Also available as environment variables: `CLAUDE_TOOL_INPUT`, `CLAUDE_TOOL_NAME`,
+`CLAUDE_PROJECT_DIR`, `CLAUDE_HOOK_EVENT`, `CLAUDE_FILE_PATH`.
+
+## Exit Codes
+
+- `0` - Allow (stdout shown in transcript)
+- `1` - Block (stderr shown as block reason)
+- `2` - Error feedback to Claude without blocking
+
+See `docs/HOOKS.md` for the full user-facing guide.
+
+## Tool Name Compatibility
+
+Hooks can be written using **either** the provider's tool name **or** code_puppy's
+internal tool name — the matcher treats them as equivalent.
+
+### Claude Code → code_puppy
+
+| Claude Code (`matcher`) | code_puppy internal | Notes |
+|-------------------------|---------------------|-------|
+| `Bash`            | `agent_run_shell_command` | Shell execution |
+| `Glob`            | `list_files`              | File glob / directory listing |
+| `Read`            | `read_file`               | Read file contents |
+| `Grep`            | `grep`                    | Text search |
+| `Edit`            | `replace_in_file`         | Patch / partial edit |
+| `Write`           | `create_file`             | Full-file overwrite |
+| `Delete`          | `delete_file`             | File deletion |
+| `AskUserQuestion` | `ask_user_question`       | Interactive user prompt |
+| `Task`            | `invoke_agent`            | Sub-agent / task spawn |
+| `Skill`           | `activate_skill`          | Skill activation |
+| `ToolSearch`      | `list_or_search_skills`   | Skill/tool discovery |
+
+Provider aliases for **Gemini**, **Codex**, and **Swarm** are reserved in
+`aliases.py` and will be populated once their MCP tool vocabularies are verified.
+
+Both directions work — `"matcher": "Bash"` and `"matcher": "agent_run_shell_command"`
+are identical at match time.

code_puppy/hook_engine/__init__.py

@@ -0,0 +1,21 @@
+"""Hook engine package for Code Puppy."""
+
+from . import aliases
+from .engine import HookEngine
+from .models import (
+    EventData,
+    ExecutionResult,
+    HookConfig,
+    HookRegistry,
+    ProcessEventResult,
+)
+
+__all__ = [
+    "HookEngine",
+    "HookConfig",
+    "EventData",
+    "ExecutionResult",
+    "ProcessEventResult",
+    "HookRegistry",
+    "aliases",
+]

code_puppy/hook_engine/aliases.py

@@ -0,0 +1,155 @@
+"""
+Tool name alias registry — maps each AI provider's tool names to code_puppy's
+internal tool names, enabling hooks written for any provider to fire correctly.
+
+Structure
+---------
+Each provider block defines a dict[str, str] mapping:
+    "<Provider tool name>" -> "<code_puppy internal tool name>"
+
+The mapping is bidirectional at lookup time: a hook matcher that names *either*
+the provider tool OR the internal tool will match the same event.
+
+Adding a new provider
+---------------------
+1. Add a new section following the pattern below.
+2. Register it in PROVIDER_ALIASES at the bottom of this file.
+3. That's it — the matcher picks it up automatically.
+"""
+
+from typing import Dict, FrozenSet, Optional
+
+# ---------------------------------------------------------------------------
+# Claude Code  (Anthropic)
+# Source: `claude mcp serve` → tools/list  (verified against v2.1.52)
+# ---------------------------------------------------------------------------
+CLAUDE_CODE_ALIASES: Dict[str, str] = {
+    # Shell execution
+    "Bash": "agent_run_shell_command",
+    # File system — read
+    "Glob": "list_files",
+    "Read": "read_file",
+    "Grep": "grep",
+    # File system — write
+    "Edit": "replace_in_file",
+    "Write": "create_file",  # Write = full overwrite
+    # File system — delete
+    "Delete": "delete_file",
+    # User interaction
+    "AskUserQuestion": "ask_user_question",
+    # Agent / task orchestration
+    "Task": "invoke_agent",
+    # Skills
+    "Skill": "activate_skill",
+    "ToolSearch": "list_or_search_skills",
+    # NOTE: the tools below have no direct code_puppy equivalent yet.
+    # They are listed here for documentation and future mapping:
+    #   "TaskOutput"     -> (no equivalent)
+    #   "TaskStop"       -> (no equivalent)
+    #   "WebFetch"       -> (no equivalent — see browser_navigate)
+    #   "WebSearch"      -> (no equivalent)
+    #   "NotebookEdit"   -> (no equivalent)
+    #   "TodoWrite"      -> (no equivalent)
+    #   "EnterPlanMode"  -> (no equivalent)
+    #   "ExitPlanMode"   -> (no equivalent)
+    #   "EnterWorktree"  -> (no equivalent)
+}
+
+
+# ---------------------------------------------------------------------------
+# Gemini  (Google)
+# TODO: populate once Gemini MCP tool names are verified.
+# Run `gemini mcp serve` (or equivalent) and inspect the tools/list response,
+# then add entries following the same pattern as CLAUDE_CODE_ALIASES above.
+# ---------------------------------------------------------------------------
+GEMINI_ALIASES: Dict[str, str] = {
+    # Add Gemini → code_puppy tool mappings here
+}
+
+
+# ---------------------------------------------------------------------------
+# Codex  (OpenAI)
+# TODO: populate once Codex MCP tool names are verified.
+# Run the Codex MCP server, inspect tools/list, and add entries here.
+# ---------------------------------------------------------------------------
+CODEX_ALIASES: Dict[str, str] = {
+    # Add Codex → code_puppy tool mappings here
+}
+
+
+# ---------------------------------------------------------------------------
+# Swarm  (internal / multi-agent)
+# TODO: populate if Swarm exposes its own canonical tool name vocabulary.
+# ---------------------------------------------------------------------------
+SWARM_ALIASES: Dict[str, str] = {
+    # Add Swarm → code_puppy tool mappings here
+}
+
+
+# ---------------------------------------------------------------------------
+# Master registry — all active alias tables, merged at module load time.
+# To disable a provider's aliases, remove its entry from this dict.
+# ---------------------------------------------------------------------------
+PROVIDER_ALIASES: Dict[str, Dict[str, str]] = {
+    "claude": CLAUDE_CODE_ALIASES,
+    "gemini": GEMINI_ALIASES,  # placeholder — empty until populated
+    "codex": CODEX_ALIASES,  # placeholder — empty until populated
+    "swarm": SWARM_ALIASES,  # placeholder — empty until populated
+}
+
+
+# ---------------------------------------------------------------------------
+# Flattened lookup structures — built once at import time for O(1) access.
+# ---------------------------------------------------------------------------
+
+
+def _build_lookup() -> Dict[str, FrozenSet[str]]:
+    """
+    Return a dict mapping every known name (provider *and* internal) to the
+    full set of equivalent names, including itself.
+
+    Example result entry:
+        "Bash" -> frozenset({"Bash", "agent_run_shell_command"})
+        "agent_run_shell_command" -> frozenset({"Bash", "agent_run_shell_command"})
+    """
+    groups: Dict[str, set] = {}
+
+    for provider_aliases in PROVIDER_ALIASES.values():
+        for provider_name, internal_name in provider_aliases.items():
+            # Collect all names that map to the same internal tool
+            key = internal_name.lower()
+            if key not in groups:
+                groups[key] = {internal_name}
+            groups[key].add(provider_name)
+
+    # Build the final lookup: every alias points to the frozen group
+    lookup: Dict[str, FrozenSet[str]] = {}
+    for group in groups.values():
+        frozen = frozenset(group)
+        for name in group:
+            lookup[name.lower()] = frozen
+    return lookup
+
+
+# Module-level singleton — import this in matcher.py
+ALIAS_LOOKUP: Dict[str, FrozenSet[str]] = _build_lookup()
+
+
+def get_aliases(tool_name: str) -> FrozenSet[str]:
+    """
+    Return all known equivalent names for *tool_name* (including itself).
+    Returns a frozenset containing only *tool_name* when no aliases exist.
+    """
+    return ALIAS_LOOKUP.get(tool_name.lower(), frozenset({tool_name}))
+
+
+def resolve_internal_name(provider_tool_name: str) -> Optional[str]:
+    """
+    Return the code_puppy internal tool name for a given provider tool name,
+    or None if the name is not a known provider alias.
+    """
+    for provider_aliases in PROVIDER_ALIASES.values():
+        for pname, internal in provider_aliases.items():
+            if pname.lower() == provider_tool_name.lower():
+                return internal
+    return None

code_puppy/hook_engine/engine.py

@@ -0,0 +1,221 @@
+"""
+Main HookEngine orchestration class.
+"""
+
+import logging
+import time
+from typing import Any, Dict, List, Optional
+
+from .executor import execute_hooks_sequential, get_blocking_result
+from .matcher import matches
+from .models import (
+    EventData,
+    HookConfig,
+    HookRegistry,
+    ProcessEventResult,
+)
+from .registry import build_registry_from_config, get_registry_stats
+from .validator import (
+    format_validation_report,
+    get_config_suggestions,
+    validate_hooks_config,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class HookEngine:
+    """
+    Main hook engine for processing events and executing hooks.
+
+    Coordinates all hook engine components:
+    - Loads and validates configuration
+    - Matches events against hook patterns
+    - Executes hooks with timeout and error handling
+    - Aggregates results and determines blocking status
+    """
+
+    def __init__(
+        self,
+        config: Optional[Dict[str, Any]] = None,
+        strict_validation: bool = True,
+        env_vars: Optional[Dict[str, str]] = None,
+    ):
+        self.env_vars = env_vars or {}
+        self.strict_validation = strict_validation
+        self._registry: Optional[HookRegistry] = None
+
+        if config:
+            self.load_config(config)
+        else:
+            self._registry = HookRegistry()
+
+    def load_config(self, config: Dict[str, Any]) -> None:
+        is_valid, errors = validate_hooks_config(config)
+
+        if not is_valid:
+            error_msg = format_validation_report(
+                is_valid, errors, get_config_suggestions(config, errors)
+            )
+            if self.strict_validation:
+                raise ValueError(f"Invalid hook configuration:\n{error_msg}")
+            else:
+                logger.warning(f"Hook configuration has errors:\n{error_msg}")
+
+        try:
+            self._registry = build_registry_from_config(config)
+            logger.info(
+                f"Loaded hook configuration: {self._registry.count_hooks()} total hooks"
+            )
+        except Exception as e:
+            if self.strict_validation:
+                raise ValueError(f"Failed to build hook registry: {e}") from e
+            else:
+                logger.error(f"Failed to build hook registry: {e}", exc_info=True)
+                self._registry = HookRegistry()
+
+    def reload_config(self, config: Dict[str, Any]) -> None:
+        self.load_config(config)
+
+    async def process_event(
+        self,
+        event_type: str,
+        event_data: EventData,
+        sequential: bool = True,
+        stop_on_block: bool = True,
+    ) -> ProcessEventResult:
+        """Process an event through the hook engine."""
+        start_time = time.perf_counter()
+
+        if not self._registry:
+            return ProcessEventResult(
+                blocked=False, executed_hooks=0, results=[], total_duration_ms=0.0
+            )
+
+        all_hooks = self._registry.get_hooks_for_event(event_type)
+
+        if not all_hooks:
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            return ProcessEventResult(
+                blocked=False,
+                executed_hooks=0,
+                results=[],
+                total_duration_ms=duration_ms,
+            )
+
+        matching_hooks = self._filter_hooks_by_matcher(
+            all_hooks, event_data.tool_name, event_data.tool_args
+        )
+
+        if not matching_hooks:
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            return ProcessEventResult(
+                blocked=False,
+                executed_hooks=0,
+                results=[],
+                total_duration_ms=duration_ms,
+            )
+
+        logger.debug(
+            f"Processing {event_type}: {len(matching_hooks)} matching hook(s) for tool '{event_data.tool_name}'"
+        )
+
+        if sequential:
+            results = await execute_hooks_sequential(
+                matching_hooks, event_data, self.env_vars, stop_on_block=stop_on_block
+            )
+        else:
+            from .executor import execute_hooks_parallel
+
+            results = await execute_hooks_parallel(
+                matching_hooks, event_data, self.env_vars
+            )
+
+        for hook, result in zip(matching_hooks, results):
+            if hook.once and result.success:
+                self._registry.mark_hook_executed(hook.id)
+
+        blocking_result = get_blocking_result(results)
+        blocked = blocking_result is not None
+        blocking_reason = None
+
+        if blocked:
+            blocking_reason = (
+                f"Hook '{blocking_result.hook_command}' failed: "
+                f"{blocking_result.error or blocking_result.stderr or 'blocked (no details provided)'}"
+            )
+
+        duration_ms = (time.perf_counter() - start_time) * 1000
+        return ProcessEventResult(
+            blocked=blocked,
+            executed_hooks=len(results),
+            results=results,
+            blocking_reason=blocking_reason,
+            total_duration_ms=duration_ms,
+        )
+
+    def _filter_hooks_by_matcher(
+        self,
+        hooks: List[HookConfig],
+        tool_name: str,
+        tool_args: Dict[str, Any],
+    ) -> List[HookConfig]:
+        matching_hooks = []
+        for hook in hooks:
+            try:
+                if matches(hook.matcher, tool_name, tool_args):
+                    matching_hooks.append(hook)
+            except Exception as e:
+                logger.error(
+                    f"Error matching hook '{hook.matcher}': {e}", exc_info=True
+                )
+        return matching_hooks
+
+    def get_stats(self) -> Dict[str, Any]:
+        if not self._registry:
+            return {"total_hooks": 0, "error": "No registry loaded"}
+        return get_registry_stats(self._registry)
+
+    def get_hooks_for_event(self, event_type: str) -> List[HookConfig]:
+        if not self._registry:
+            return []
+        return self._registry.get_hooks_for_event(event_type)
+
+    def count_hooks(self, event_type: Optional[str] = None) -> int:
+        if not self._registry:
+            return 0
+        return self._registry.count_hooks(event_type)
+
+    def reset_once_hooks(self) -> None:
+        if self._registry:
+            self._registry.reset_once_hooks()
+
+    def add_hook(self, event_type: str, hook: HookConfig) -> None:
+        if not self._registry:
+            self._registry = HookRegistry()
+        self._registry.add_hook(event_type, hook)
+
+    def remove_hook(self, event_type: str, hook_id: str) -> bool:
+        if not self._registry:
+            return False
+        return self._registry.remove_hook(event_type, hook_id)
+
+    def set_env_vars(self, env_vars: Dict[str, str]) -> None:
+        self.env_vars = env_vars
+
+    def update_env_vars(self, env_vars: Dict[str, str]) -> None:
+        self.env_vars.update(env_vars)
+
+    @property
+    def is_loaded(self) -> bool:
+        return self._registry is not None
+
+    @property
+    def registry(self) -> Optional[HookRegistry]:
+        return self._registry
+
+
+def validate_config_file(config: Dict[str, Any]) -> str:
+    is_valid, errors = validate_hooks_config(config)
+    suggestions = get_config_suggestions(config, errors) if not is_valid else []
+    return format_validation_report(is_valid, errors, suggestions)