codepp 0.0.437__py3-none-any.whl

code_puppy/hook_engine/executor.py

@@ -0,0 +1,296 @@
+"""
+Command execution engine for hooks.
+
+Handles async command execution with timeout, variable substitution,
+and comprehensive error handling.
+
+Claude Code Hook Compatibility:
+  - Input is passed via STDIN as JSON (primary method, Claude Code standard)
+  - Input is also available via CLAUDE_TOOL_INPUT env var (legacy/convenience)
+  - Exit code 0  => success, stdout shown in transcript
+  - Exit code 1  => block the operation (stderr used as reason)
+  - Exit code 2  => error feedback to Claude (stderr fed back as tool error)
+"""
+
+import asyncio
+import json
+import logging
+import os
+import re
+import time
+from typing import Any, Dict, List, Optional
+
+from .matcher import _extract_file_path
+from .models import EventData, ExecutionResult, HookConfig
+
+logger = logging.getLogger(__name__)
+
+
+def _build_stdin_payload(event_data: EventData) -> bytes:
+    """
+    Build the JSON payload sent to hook scripts via stdin.
+
+    Matches the Claude Code hook input format:
+    {
+        "session_id": "...",
+        "hook_event_name": "PreToolUse",
+        "tool_name": "Bash",
+        "tool_input": { ... },
+        "cwd": "/path/to/project",
+        "permission_mode": "default"
+    }
+    """
+
+    def _make_serializable(obj: Any) -> Any:
+        if isinstance(obj, dict):
+            return {k: _make_serializable(v) for k, v in obj.items()}
+        if isinstance(obj, (list, tuple)):
+            return [_make_serializable(v) for v in obj]
+        if isinstance(obj, (str, int, float, bool, type(None))):
+            return obj
+        try:
+            return str(obj)
+        except Exception:
+            return "<unserializable>"
+
+    payload = {
+        "session_id": event_data.context.get("session_id", "codepuppy-session"),
+        "hook_event_name": event_data.event_type,
+        "tool_name": event_data.tool_name,
+        "tool_input": _make_serializable(event_data.tool_args),
+        "cwd": os.getcwd(),
+        "permission_mode": "default",
+    }
+    if "result" in event_data.context:
+        payload["tool_result"] = _make_serializable(event_data.context["result"])
+    if "duration_ms" in event_data.context:
+        payload["tool_duration_ms"] = event_data.context["duration_ms"]
+
+    return json.dumps(payload, ensure_ascii=False).encode("utf-8")
+
+
+async def execute_hook(
+    hook: HookConfig,
+    event_data: EventData,
+    env_vars: Optional[Dict[str, str]] = None,
+) -> ExecutionResult:
+    """
+    Execute a hook command with timeout and variable substitution.
+
+    Input to the hook script:
+      - stdin: JSON object (Claude Code compatible format)
+      - env CLAUDE_TOOL_INPUT: JSON string of tool_args (legacy)
+      - env CLAUDE_PROJECT_DIR: current working directory
+
+    Exit code semantics:
+      - 0: success (stdout shown in transcript)
+      - 1: block operation (stderr becomes block reason)
+      - 2: error feedback to Claude without blocking
+    """
+    if hook.type == "prompt":
+        return ExecutionResult(
+            blocked=False,
+            hook_command=hook.command,
+            stdout=hook.command,
+            exit_code=0,
+            duration_ms=0.0,
+            hook_id=hook.id,
+        )
+
+    command = _substitute_variables(hook.command, event_data, env_vars or {})
+    stdin_payload = _build_stdin_payload(event_data)
+    start_time = time.perf_counter()
+
+    try:
+        env = _build_environment(event_data, env_vars)
+
+        proc = await asyncio.create_subprocess_shell(
+            command,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=os.getcwd(),
+            env=env,
+        )
+
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(input=stdin_payload),
+                timeout=hook.timeout / 1000.0,
+            )
+        except asyncio.TimeoutError:
+            try:
+                proc.kill()
+                await proc.wait()
+            except Exception:
+                pass
+
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            return ExecutionResult(
+                blocked=True,
+                hook_command=command,
+                stdout="",
+                stderr=f"Command timed out after {hook.timeout}ms",
+                exit_code=-1,
+                duration_ms=duration_ms,
+                error=f"Hook execution timed out after {hook.timeout}ms",
+                hook_id=hook.id,
+            )
+
+        duration_ms = (time.perf_counter() - start_time) * 1000
+        stdout_str = stdout.decode("utf-8", errors="replace") if stdout else ""
+        stderr_str = stderr.decode("utf-8", errors="replace") if stderr else ""
+        exit_code = proc.returncode or 0
+
+        blocked = exit_code == 1
+        error = stderr_str if exit_code != 0 and stderr_str else None
+
+        return ExecutionResult(
+            blocked=blocked,
+            hook_command=command,
+            stdout=stdout_str,
+            stderr=stderr_str,
+            exit_code=exit_code,
+            duration_ms=duration_ms,
+            error=error,
+            hook_id=hook.id,
+        )
+
+    except Exception as e:
+        duration_ms = (time.perf_counter() - start_time) * 1000
+        logger.error(f"Hook execution failed: {e}", exc_info=True)
+        return ExecutionResult(
+            blocked=False,
+            hook_command=command,
+            stdout="",
+            stderr=str(e),
+            exit_code=-1,
+            duration_ms=duration_ms,
+            error=f"Hook execution error: {e}",
+            hook_id=hook.id,
+        )
+
+
+def _substitute_variables(
+    command: str,
+    event_data: EventData,
+    env_vars: Dict[str, str],
+) -> str:
+    substitutions = {
+        "CLAUDE_PROJECT_DIR": os.getcwd(),
+        "tool_name": event_data.tool_name,
+        "event_type": event_data.event_type,
+        "file": _extract_file_path(event_data.tool_args) or "",
+        "CLAUDE_TOOL_INPUT": json.dumps(event_data.tool_args),
+    }
+    if event_data.context:
+        if "result" in event_data.context:
+            substitutions["result"] = str(event_data.context["result"])
+        if "duration_ms" in event_data.context:
+            substitutions["duration_ms"] = str(event_data.context["duration_ms"])
+    substitutions.update(env_vars)
+
+    result = command
+    for var, value in substitutions.items():
+        result = result.replace(f"${{{var}}}", str(value))
+        result = re.sub(rf"\${re.escape(var)}(?=\W|$)", lambda m: str(value), result)
+    return result
+
+
+def _build_environment(
+    event_data: EventData,
+    env_vars: Optional[Dict[str, str]] = None,
+) -> Dict[str, str]:
+    env = os.environ.copy()
+    env["CLAUDE_PROJECT_DIR"] = os.getcwd()
+    env["CLAUDE_TOOL_INPUT"] = json.dumps(event_data.tool_args)
+    env["CLAUDE_TOOL_NAME"] = event_data.tool_name
+    env["CLAUDE_HOOK_EVENT"] = event_data.event_type
+    env["CLAUDE_CODE_HOOK"] = "1"
+
+    file_path = _extract_file_path(event_data.tool_args)
+    if file_path:
+        env["CLAUDE_FILE_PATH"] = file_path
+
+    if env_vars:
+        env.update(env_vars)
+    return env
+
+
+async def execute_hooks_parallel(
+    hooks: List[HookConfig],
+    event_data: EventData,
+    env_vars: Optional[Dict[str, str]] = None,
+) -> List[ExecutionResult]:
+    if not hooks:
+        return []
+    tasks = [execute_hook(hook, event_data, env_vars) for hook in hooks]
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+    final_results = []
+    for i, result in enumerate(results):
+        if isinstance(result, Exception):
+            final_results.append(
+                ExecutionResult(
+                    blocked=False,
+                    hook_command=hooks[i].command,
+                    stdout="",
+                    stderr=str(result),
+                    exit_code=-1,
+                    duration_ms=0.0,
+                    error=f"Hook execution failed: {result}",
+                    hook_id=hooks[i].id,
+                )
+            )
+        else:
+            final_results.append(result)
+    return final_results
+
+
+async def execute_hooks_sequential(
+    hooks: List[HookConfig],
+    event_data: EventData,
+    env_vars: Optional[Dict[str, str]] = None,
+    stop_on_block: bool = True,
+) -> List[ExecutionResult]:
+    results = []
+    for hook in hooks:
+        result = await execute_hook(hook, event_data, env_vars)
+        results.append(result)
+        if stop_on_block and result.blocked:
+            logger.debug(f"Hook blocked operation, stopping: {hook.command}")
+            break
+    return results
+
+
+def get_blocking_result(results: List[ExecutionResult]) -> Optional[ExecutionResult]:
+    for result in results:
+        if result.blocked:
+            return result
+    return None
+
+
+def get_failed_results(results: List[ExecutionResult]) -> List[ExecutionResult]:
+    return [result for result in results if not result.success]
+
+
+def format_execution_summary(results: List[ExecutionResult]) -> str:
+    if not results:
+        return "No hooks executed"
+    total = len(results)
+    successful = sum(1 for r in results if r.success)
+    blocked = sum(1 for r in results if r.blocked)
+    total_duration = sum(r.duration_ms for r in results)
+    summary = [
+        f"Executed {total} hook(s)",
+        f"Successful: {successful}",
+        f"Blocked: {blocked}",
+        f"Total duration: {total_duration:.2f}ms",
+    ]
+    if blocked > 0:
+        blocking_hooks = [r for r in results if r.blocked]
+        summary.append("\nBlocking hooks:")
+        for result in blocking_hooks:
+            summary.append(f"  - {result.hook_command}")
+            if result.error:
+                summary.append(f"    Error: {result.error}")
+    return "\n".join(summary)

code_puppy/hook_engine/matcher.py

@@ -0,0 +1,156 @@
+"""
+Pattern matching engine for hook filters.
+
+Provides flexible pattern matching to determine if a hook should execute
+based on tool name, arguments, and other event data.
+"""
+
+import re
+from typing import Any, Dict, Optional
+
+from .aliases import get_aliases
+
+
+def matches(matcher: str, tool_name: str, tool_args: Dict[str, Any]) -> bool:
+    """
+    Evaluate if a matcher pattern matches the tool call.
+
+    Matcher Syntax:
+        - "*" - Matches all tools
+        - "ToolName" - Exact tool name match
+        - ".ext" - File extension match (e.g., ".py", ".ts")
+        - "Pattern1 && Pattern2" - AND condition (all must match)
+        - "Pattern1 || Pattern2" - OR condition (any must match)
+    """
+    if not matcher:
+        return False
+
+    if matcher.strip() == "*":
+        return True
+
+    if "||" in matcher:
+        parts = [p.strip() for p in matcher.split("||")]
+        return any(matches(part, tool_name, tool_args) for part in parts)
+
+    if "&&" in matcher:
+        parts = [p.strip() for p in matcher.split("&&")]
+        return all(matches(part, tool_name, tool_args) for part in parts)
+
+    return _match_single(matcher.strip(), tool_name, tool_args)
+
+
+def _match_single(pattern: str, tool_name: str, tool_args: Dict[str, Any]) -> bool:
+    if pattern == tool_name:
+        return True
+
+    if pattern.lower() == tool_name.lower():
+        return True
+
+    # Check cross-provider aliases: a hook written for "Bash" (Claude Code) should
+    # fire when code_puppy calls "agent_run_shell_command", and vice-versa.
+    tool_aliases = get_aliases(tool_name)
+    pattern_aliases = get_aliases(pattern)
+    if tool_aliases & pattern_aliases:  # non-empty intersection → same logical tool
+        return True
+
+    if pattern.startswith("."):
+        file_path = _extract_file_path(tool_args)
+        if file_path:
+            return file_path.endswith(pattern)
+        return False
+
+    if "*" in pattern:
+        parts = pattern.split("*")
+        regex_pattern = ".*".join(re.escape(part) for part in parts)
+        if re.match(f"^{regex_pattern}$", tool_name, re.IGNORECASE):
+            return True
+
+    if _is_regex_pattern(pattern):
+        try:
+            if re.search(pattern, tool_name, re.IGNORECASE):
+                return True
+            file_path = _extract_file_path(tool_args)
+            if file_path and re.search(pattern, file_path, re.IGNORECASE):
+                return True
+        except re.error:
+            pass
+
+    return False
+
+
+def _extract_file_path(tool_args: Dict[str, Any]) -> Optional[str]:
+    file_keys = [
+        "file_path",
+        "file",
+        "path",
+        "target",
+        "input_file",
+        "output_file",
+        "source",
+        "destination",
+        "src",
+        "dest",
+        "filename",
+    ]
+    for key in file_keys:
+        if key in tool_args:
+            value = tool_args[key]
+            if isinstance(value, str):
+                return value
+            if hasattr(value, "__fspath__"):
+                return str(value)
+    for value in tool_args.values():
+        if isinstance(value, str) and _looks_like_file_path(value):
+            return value
+    return None
+
+
+def _looks_like_file_path(value: str) -> bool:
+    if not value:
+        return False
+    if "." in value and not value.startswith("."):
+        parts = value.rsplit(".", 1)
+        if len(parts) == 2 and len(parts[1]) <= 10 and parts[1].isalnum():
+            return True
+    if "/" in value or "\\" in value:
+        return True
+    return False
+
+
+def _is_regex_pattern(pattern: str) -> bool:
+    regex_chars = ["^", "$", ".", "+", "?", "[", "]", "(", ")", "{", "}", "|", "\\"]
+    return any(char in pattern for char in regex_chars)
+
+
+def extract_file_extension(file_path: str) -> Optional[str]:
+    if not file_path or "." not in file_path:
+        return None
+    if "/" in file_path:
+        file_path = file_path.rsplit("/", 1)[-1]
+    if "\\" in file_path:
+        file_path = file_path.rsplit("\\", 1)[-1]
+    if "." in file_path:
+        return "." + file_path.rsplit(".", 1)[-1]
+    return None
+
+
+def matches_tool(tool_name: str, *names: str) -> bool:
+    return tool_name.lower() in [name.lower() for name in names]
+
+
+def matches_file_extension(tool_args: Dict[str, Any], *extensions: str) -> bool:
+    file_path = _extract_file_path(tool_args)
+    if not file_path:
+        return False
+    ext = extract_file_extension(file_path)
+    return ext in extensions
+
+
+def matches_file_pattern(tool_args: Dict[str, Any], pattern: str) -> bool:
+    file_path = _extract_file_path(tool_args)
+    if not file_path:
+        return False
+    try:
+        return bool(re.search(pattern, file_path, re.IGNORECASE))
+    except re.error:
+        return False

code_puppy/hook_engine/models.py

@@ -0,0 +1,240 @@
+"""
+Data models for the hook engine.
+
+Defines all data structures used throughout the hook engine with full type
+safety and validation.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional
+
+
+@dataclass
+class HookConfig:
+    """
+    Configuration for a single hook.
+
+    Attributes:
+        matcher: Pattern to match against events (e.g., "Edit && .py")
+        type: Type of hook action ("command" or "prompt")
+        command: Command or prompt text to execute
+        timeout: Maximum execution time in milliseconds (default: 5000)
+        once: Execute only once per session (default: False)
+        enabled: Whether this hook is enabled (default: True)
+        id: Optional unique identifier for this hook
+    """
+
+    matcher: str
+    type: Literal["command", "prompt"]
+    command: str
+    timeout: int = 5000
+    once: bool = False
+    enabled: bool = True
+    id: Optional[str] = None
+
+    def __post_init__(self):
+        """Validate hook configuration after initialization."""
+        if not self.matcher:
+            raise ValueError("Hook matcher cannot be empty")
+
+        if self.type not in ("command", "prompt"):
+            raise ValueError(
+                f"Hook type must be 'command' or 'prompt', got: {self.type}"
+            )
+
+        if not self.command:
+            raise ValueError("Hook command cannot be empty")
+
+        if self.timeout < 100:
+            raise ValueError(f"Hook timeout must be >= 100ms, got: {self.timeout}")
+
+        if self.id is None:
+            import hashlib
+
+            content = f"{self.matcher}:{self.type}:{self.command}"
+            self.id = hashlib.sha256(content.encode()).hexdigest()[:12]
+
+
+@dataclass
+class EventData:
+    """
+    Input data for hook processing.
+
+    Attributes:
+        event_type: Type of event (PreToolUse, PostToolUse, etc.)
+        tool_name: Name of the tool being called
+        tool_args: Arguments passed to the tool
+        context: Optional context metadata (result, duration, etc.)
+    """
+
+    event_type: str
+    tool_name: str
+    tool_args: Dict[str, Any] = field(default_factory=dict)
+    context: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        if not self.event_type:
+            raise ValueError("Event type cannot be empty")
+        if not self.tool_name:
+            raise ValueError("Tool name cannot be empty")
+
+
+@dataclass
+class ExecutionResult:
+    """
+    Result from executing a hook.
+
+    Attributes:
+        blocked: Whether the hook blocked the operation
+        hook_command: The command that was executed
+        stdout: Standard output from command
+        stderr: Standard error from command
+        exit_code: Exit code from command execution
+        duration_ms: Execution duration in milliseconds
+        error: Error message if execution failed
+        hook_id: ID of the hook that was executed
+    """
+
+    blocked: bool
+    hook_command: str
+    stdout: str = ""
+    stderr: str = ""
+    exit_code: int = 0
+    duration_ms: float = 0.0
+    error: Optional[str] = None
+    hook_id: Optional[str] = None
+
+    @property
+    def success(self) -> bool:
+        """Whether the hook executed successfully (exit code 0)."""
+        return self.exit_code == 0 and self.error is None
+
+    @property
+    def output(self) -> str:
+        """Combined stdout and stderr."""
+        parts = []
+        if self.stdout:
+            parts.append(self.stdout)
+        if self.stderr:
+            parts.append(self.stderr)
+        return "\n".join(parts)
+
+
+@dataclass
+class HookGroup:
+    """A group of hooks that share the same matcher."""
+
+    matcher: str
+    hooks: List[HookConfig] = field(default_factory=list)
+
+    def __post_init__(self):
+        if not self.matcher:
+            raise ValueError("Hook group matcher cannot be empty")
+
+
+@dataclass
+class HookRegistry:
+    """Registry of all hooks organized by event type."""
+
+    pre_tool_use: List[HookConfig] = field(default_factory=list)
+    post_tool_use: List[HookConfig] = field(default_factory=list)
+    session_start: List[HookConfig] = field(default_factory=list)
+    session_end: List[HookConfig] = field(default_factory=list)
+    pre_compact: List[HookConfig] = field(default_factory=list)
+    user_prompt_submit: List[HookConfig] = field(default_factory=list)
+    notification: List[HookConfig] = field(default_factory=list)
+    stop: List[HookConfig] = field(default_factory=list)
+    subagent_stop: List[HookConfig] = field(default_factory=list)
+
+    _executed_once_hooks: set = field(default_factory=set, repr=False)
+
+    def get_hooks_for_event(self, event_type: str) -> List[HookConfig]:
+        attr_name = self._normalize_event_type(event_type)
+        if not hasattr(self, attr_name):
+            return []
+        all_hooks = getattr(self, attr_name)
+        enabled_hooks = []
+        for hook in all_hooks:
+            if not hook.enabled:
+                continue
+            if hook.once and hook.id in self._executed_once_hooks:
+                continue
+            enabled_hooks.append(hook)
+        return enabled_hooks
+
+    def mark_hook_executed(self, hook_id: str) -> None:
+        self._executed_once_hooks.add(hook_id)
+
+    def reset_once_hooks(self) -> None:
+        self._executed_once_hooks.clear()
+
+    @staticmethod
+    def _normalize_event_type(event_type: str) -> str:
+        import re
+
+        s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", event_type)
+        return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
+
+    def add_hook(self, event_type: str, hook: HookConfig) -> None:
+        attr_name = self._normalize_event_type(event_type)
+        if not hasattr(self, attr_name):
+            raise ValueError(f"Unknown event type: {event_type}")
+        getattr(self, attr_name).append(hook)
+
+    def remove_hook(self, event_type: str, hook_id: str) -> bool:
+        attr_name = self._normalize_event_type(event_type)
+        if not hasattr(self, attr_name):
+            return False
+        hooks_list = getattr(self, attr_name)
+        for i, hook in enumerate(hooks_list):
+            if hook.id == hook_id:
+                hooks_list.pop(i)
+                return True
+        return False
+
+    def count_hooks(self, event_type: Optional[str] = None) -> int:
+        if event_type is None:
+            total = 0
+            for attr in [
+                "pre_tool_use",
+                "post_tool_use",
+                "session_start",
+                "session_end",
+                "pre_compact",
+                "user_prompt_submit",
+                "notification",
+                "stop",
+                "subagent_stop",
+            ]:
+                total += len(getattr(self, attr))
+            return total
+        attr_name = self._normalize_event_type(event_type)
+        if not hasattr(self, attr_name):
+            return 0
+        return len(getattr(self, attr_name))
+
+
+@dataclass
+class ProcessEventResult:
+    """Result from processing an event through the hook engine."""
+
+    blocked: bool
+    executed_hooks: int
+    results: List[ExecutionResult]
+    blocking_reason: Optional[str] = None
+    total_duration_ms: float = 0.0
+
+    @property
+    def all_successful(self) -> bool:
+        return all(result.success for result in self.results)
+
+    @property
+    def failed_hooks(self) -> List[ExecutionResult]:
+        return [result for result in self.results if not result.success]
+
+    def get_combined_output(self) -> str:
+        outputs = []
+        for result in self.results:
+            if result.output:
+                outputs.append(f"[{result.hook_command}]\n{result.output}")
+        return "\n\n".join(outputs)