claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/core/hook_manager.py

@@ -1,3 +1,5 @@
+from pathlib import Path
+
 """Hook manager for manually triggering hook events in PM operations.
 
 This module provides a way for the PM agent to manually trigger hook events
@@ -10,159 +12,300 @@ WHY this is needed:
 - Ensures consistent event streaming to Socket.IO dashboard
 """
 
+import contextlib
 import json
 import os
+import queue
 import subprocess
+import threading
 import uuid
-from datetime import datetime
-from typing import Dict, Any, Optional
-from pathlib import Path
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
 
 from ..core.logger import get_logger
-from ..deployment_paths import get_package_root
+from .hook_error_memory import get_hook_error_memory
+from .hook_performance_config import get_hook_performance_config
+from .unified_paths import get_package_root
 
 
 class HookManager:
     """Manager for manually triggering hook events from PM operations.
-    
+
     WHY this design:
     - Mimics Claude Code's hook event structure exactly
     - Uses the same hook handler that regular agents use
     - Provides session tracking consistent with regular hook events
     - Enables PM operations to appear in Socket.IO dashboard
     """
-    
+
     def __init__(self):
         self.logger = get_logger("hook_manager")
         self.session_id = self._get_or_create_session_id()
         self.hook_handler_path = self._find_hook_handler()
-        
+
+        # Initialize error memory for tracking and preventing repeated errors
+        self.error_memory = get_hook_error_memory()
+
+        # Initialize background hook processing for async execution
+        self.performance_config = get_hook_performance_config()
+        queue_config = self.performance_config.get_queue_config()
+        self.hook_queue = queue.Queue(maxsize=queue_config["maxsize"])
+        self.background_thread = None
+        self.shutdown_event = threading.Event()
+
+        # Start background processing if hook handler is available
+        if self.hook_handler_path:
+            self._start_background_processor()
+            self.logger.debug(
+                f"Hook handler found with async processing: {self.hook_handler_path}"
+            )
+        else:
+            self.logger.debug("Hook handler not found - hooks will be skipped")
+
     def _get_or_create_session_id(self) -> str:
         """Get or create a session ID for hook events."""
         # Try to get session ID from environment (set by ClaudeRunner)
-        session_id = os.environ.get('CLAUDE_MPM_SESSION_ID')
+        session_id = os.environ.get("CLAUDE_MPM_SESSION_ID")
         if not session_id:
             # Generate new session ID
             session_id = str(uuid.uuid4())
-            os.environ['CLAUDE_MPM_SESSION_ID'] = session_id
+            os.environ["CLAUDE_MPM_SESSION_ID"] = session_id
         return session_id
-    
+
+    def _start_background_processor(self):
+        """Start background thread to process hooks asynchronously."""
+
+        def process_hooks():
+            """Background thread function to process hook queue."""
+            while not self.shutdown_event.is_set():
+                try:
+                    # Get hook data with timeout to allow shutdown checking
+                    hook_data = self.hook_queue.get(timeout=1.0)
+                    if hook_data is None:  # Shutdown signal
+                        break
+
+                    # Process the hook synchronously in background thread
+                    self._execute_hook_sync(hook_data)
+                    self.hook_queue.task_done()
+
+                except queue.Empty:
+                    # Timeout - continue to check shutdown event
+                    continue
+                except Exception as e:
+                    self.logger.error(f"Hook processing error: {e}")
+
+        self.background_thread = threading.Thread(
+            target=process_hooks, name="hook-processor", daemon=True
+        )
+        self.background_thread.start()
+        self.logger.debug("Started background hook processor thread")
+
+    def _execute_hook_sync(self, hook_data: Dict[str, Any]):
+        """Execute a single hook synchronously in the background thread with error detection.
+
+        WHY error detection:
+        - Prevents repeated execution of failing hooks
+        - Provides actionable error messages to users
+        - Learns from failures to improve system reliability
+        - Reduces log noise from repeated errors
+        """
+        try:
+            hook_type = hook_data["hook_type"]
+            event_data = hook_data["event_data"]
+
+            # Check if this hook is known to fail repeatedly
+            if self.error_memory.should_skip_hook(hook_type):
+                known_error = self.error_memory.is_known_failing_hook(hook_type)
+                if known_error:
+                    # Log warning but don't spam - only on first skip
+                    if known_error["count"] == 2:  # First time we're skipping
+                        self.logger.warning(
+                            f"⚠️  Skipping {hook_type} hook - failed {known_error['count']} times previously\n"
+                            f"Error: {known_error['match']}\n"
+                            f"To retry: rm {self.error_memory.memory_file}"
+                        )
+                return
+
+            # Create the hook event
+            hook_event = {
+                "hook_event_name": hook_type,
+                "session_id": self.session_id,
+                "timestamp": hook_data.get(
+                    "timestamp", datetime.now(timezone.utc).isoformat()
+                ),
+                **event_data,
+            }
+
+            event_json = json.dumps(hook_event)
+            env = os.environ.copy()
+            env["CLAUDE_MPM_HOOK_DEBUG"] = "true"
+
+            # Execute with timeout in background thread
+            result = subprocess.run(
+                ["python", str(self.hook_handler_path)],
+                input=event_json,
+                text=True,
+                capture_output=True,
+                env=env,
+                timeout=self.performance_config.background_timeout,
+                check=False,
+            )
+
+            # Detect errors in the output
+            error_info = self.error_memory.detect_error(
+                result.stdout or "", result.stderr or "", result.returncode
+            )
+
+            if error_info:
+                # Record the error
+                self.error_memory.record_error(error_info, hook_type)
+
+                # Get fix suggestion
+                suggestion = self.error_memory.suggest_fix(error_info)
+
+                # Log error with suggestion
+                self.logger.warning(f"Hook {hook_type} error detected:\n{suggestion}")
+            elif result.returncode != 0:
+                # Non-zero return without detected pattern
+                self.logger.debug(f"Hook {hook_type} returned code {result.returncode}")
+                if result.stderr:
+                    self.logger.debug(f"Hook stderr: {result.stderr}")
+
+        except subprocess.TimeoutExpired:
+            self.logger.debug(
+                f"Hook {hook_data.get('hook_type', 'unknown')} timed out in background"
+            )
+        except Exception as e:
+            self.logger.debug(f"Background hook execution error: {e}")
+
+    def shutdown(self):
+        """Shutdown the background hook processor."""
+        if self.background_thread and self.background_thread.is_alive():
+            self.shutdown_event.set()
+            # Signal shutdown by putting None in queue
+            with contextlib.suppress(queue.Full):
+                self.hook_queue.put_nowait(None)
+
+            # Wait for thread to finish
+            self.background_thread.join(timeout=2.0)
+            self.logger.debug("Background hook processor shutdown")
+
     def _find_hook_handler(self) -> Optional[Path]:
         """Find the hook handler script."""
         try:
             # Look for hook handler in the expected location
-            hook_handler = get_package_root() / "hooks" / "claude_hooks" / "hook_handler.py"
-            
+            hook_handler = (
+                get_package_root() / "hooks" / "claude_hooks" / "hook_handler.py"
+            )
+
             if hook_handler.exists():
                 return hook_handler
-            else:
-                self.logger.warning(f"Hook handler not found at: {hook_handler}")
-                return None
+            self.logger.warning(f"Hook handler not found at: {hook_handler}")
+            return None
         except Exception as e:
             self.logger.error(f"Error finding hook handler: {e}")
             return None
-    
-    def trigger_pre_tool_hook(self, tool_name: str, tool_args: Dict[str, Any] = None) -> bool:
+
+    def trigger_pre_tool_hook(
+        self, tool_name: str, tool_args: Optional[Dict[str, Any]] = None
+    ) -> bool:
         """Trigger PreToolUse hook event.
-        
+
         Args:
             tool_name: Name of the tool being used (e.g., "TodoWrite")
             tool_args: Arguments passed to the tool
-            
+
         Returns:
             bool: True if hook was triggered successfully
         """
-        return self._trigger_hook_event("PreToolUse", {
-            "tool_name": tool_name,
-            "tool_args": tool_args or {},
-            "timestamp": datetime.utcnow().isoformat()
-        })
-    
-    def trigger_post_tool_hook(self, tool_name: str, exit_code: int = 0, result: Any = None) -> bool:
+        return self._trigger_hook_event(
+            "PreToolUse",
+            {
+                "tool_name": tool_name,
+                "tool_args": tool_args or {},
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            },
+        )
+
+    def trigger_post_tool_hook(
+        self, tool_name: str, exit_code: int = 0, result: Any = None
+    ) -> bool:
         """Trigger PostToolUse hook event.
-        
+
         Args:
             tool_name: Name of the tool that was used
             exit_code: Exit code (0 for success, non-zero for error)
             result: Result returned by the tool
-            
+
         Returns:
             bool: True if hook was triggered successfully
         """
-        return self._trigger_hook_event("PostToolUse", {
-            "tool_name": tool_name,
-            "exit_code": exit_code,
-            "result": str(result) if result is not None else None,
-            "timestamp": datetime.utcnow().isoformat()
-        })
-    
+        return self._trigger_hook_event(
+            "PostToolUse",
+            {
+                "tool_name": tool_name,
+                "exit_code": exit_code,
+                "result": str(result) if result is not None else None,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            },
+        )
+
     def trigger_user_prompt_hook(self, prompt: str) -> bool:
         """Trigger UserPromptSubmit hook event.
-        
+
         Args:
             prompt: The user prompt
-            
+
         Returns:
             bool: True if hook was triggered successfully
         """
-        return self._trigger_hook_event("UserPromptSubmit", {
-            "prompt": prompt,
-            "timestamp": datetime.utcnow().isoformat()
-        })
-    
+        return self._trigger_hook_event(
+            "UserPromptSubmit",
+            {"prompt": prompt, "timestamp": datetime.now(timezone.utc).isoformat()},
+        )
+
     def _trigger_hook_event(self, hook_type: str, event_data: Dict[str, Any]) -> bool:
-        """Trigger a hook event by calling the hook handler.
-        
+        """Trigger a hook event by queuing it for background processing.
+
+        This method uses a background queue to process hooks asynchronously,
+        providing minimal overhead on the main execution thread.
+
         Args:
             hook_type: Type of hook event
             event_data: Event data
-            
+
         Returns:
-            bool: True if hook was triggered successfully
+            bool: True if hook was queued successfully (not execution success)
         """
         if not self.hook_handler_path:
             self.logger.debug("Hook handler not available - skipping hook event")
             return False
-        
+
+        # Check if this hook type is enabled
+        if not self.performance_config.is_hook_enabled(hook_type):
+            self.logger.debug(f"Hook type {hook_type} disabled by configuration")
+            return True
+
         try:
-            # Create the hook event in the same format as Claude Code
-            hook_event = {
-                "hook_event_name": hook_type,
-                "session_id": self.session_id,
-                "timestamp": datetime.utcnow().isoformat(),
-                **event_data
+            # Queue hook for background processing
+            hook_data = {
+                "hook_type": hook_type,
+                "event_data": event_data,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
             }
-            
-            # Convert to JSON
-            event_json = json.dumps(hook_event)
-            
-            # Call the hook handler
-            env = os.environ.copy()
-            env['CLAUDE_MPM_HOOK_DEBUG'] = 'true'  # Enable debug logging
-            
-            result = subprocess.run(
-                ["python", str(self.hook_handler_path)],
-                input=event_json,
-                text=True,
-                capture_output=True,
-                env=env,
-                timeout=5  # 5 second timeout to prevent hanging
+
+            # Try to queue without blocking
+            self.hook_queue.put_nowait(hook_data)
+            self.logger.debug(
+                f"Successfully queued {hook_type} hook for background processing"
             )
-            
-            if result.returncode == 0:
-                self.logger.debug(f"Successfully triggered {hook_type} hook")
-                return True
-            else:
-                self.logger.warning(f"Hook handler returned non-zero exit code: {result.returncode}")
-                if result.stderr:
-                    self.logger.warning(f"Hook handler stderr: {result.stderr}")
-                return False
-                
-        except subprocess.TimeoutExpired:
-            self.logger.warning(f"Hook handler timed out for {hook_type}")
+            return True
+
+        except queue.Full:
+            self.logger.warning(f"Hook queue full, dropping {hook_type} event")
             return False
         except Exception as e:
-            self.logger.error(f"Error triggering {hook_type} hook: {e}")
+            self.logger.error(f"Error queuing {hook_type} hook: {e}")
             return False
 
 
@@ -175,12 +318,29 @@ def get_hook_manager() -> HookManager:
     global _hook_manager
     if _hook_manager is None:
         _hook_manager = HookManager()
+        # Register cleanup on exit
+        import atexit
+
+        atexit.register(_cleanup_hook_manager)
     return _hook_manager
 
 
-def trigger_tool_hooks(tool_name: str, tool_args: Dict[str, Any] = None, result: Any = None, exit_code: int = 0):
+def _cleanup_hook_manager():
+    """Cleanup function to shutdown hook manager on exit."""
+    global _hook_manager
+    if _hook_manager is not None:
+        _hook_manager.shutdown()
+        _hook_manager = None
+
+
+def trigger_tool_hooks(
+    tool_name: str,
+    tool_args: Optional[Dict[str, Any]] = None,
+    result: Any = None,
+    exit_code: int = 0,
+):
     """Convenience function to trigger both pre and post tool hooks.
-    
+
     Args:
         tool_name: Name of the tool
         tool_args: Arguments passed to the tool
@@ -188,9 +348,9 @@ def trigger_tool_hooks(tool_name: str, tool_args: Dict[str, Any] = None, result:
         exit_code: Exit code (0 for success)
     """
     manager = get_hook_manager()
-    
+
     # Trigger pre-tool hook
     manager.trigger_pre_tool_hook(tool_name, tool_args)
-    
+
     # Trigger post-tool hook
-    manager.trigger_post_tool_hook(tool_name, exit_code, result)
+    manager.trigger_post_tool_hook(tool_name, exit_code, result)

claude_mpm/core/hook_performance_config.py

@@ -0,0 +1,147 @@
+"""Hook performance configuration for Claude MPM.
+
+This module provides configuration options to optimize hook performance
+and enable/disable hooks based on performance requirements.
+"""
+
+import os
+from typing import Dict, Optional
+
+
+class HookPerformanceConfig:
+    """Configuration for hook performance optimization."""
+
+    def __init__(self):
+        """Initialize hook performance configuration from environment."""
+        self._load_config()
+
+    def _load_config(self):
+        """Load configuration from environment variables."""
+        # Performance mode - disables all hooks for maximum speed
+        self.performance_mode = (
+            os.getenv("CLAUDE_MPM_PERFORMANCE_MODE", "false").lower() == "true"
+        )
+
+        # Individual hook type controls
+        self.enable_pre_tool_hooks = (
+            os.getenv("CLAUDE_MPM_HOOKS_PRE_TOOL", "true").lower() == "true"
+        )
+        self.enable_post_tool_hooks = (
+            os.getenv("CLAUDE_MPM_HOOKS_POST_TOOL", "true").lower() == "true"
+        )
+        self.enable_user_prompt_hooks = (
+            os.getenv("CLAUDE_MPM_HOOKS_USER_PROMPT", "true").lower() == "true"
+        )
+        self.enable_delegation_hooks = (
+            os.getenv("CLAUDE_MPM_HOOKS_DELEGATION", "true").lower() == "true"
+        )
+
+        # Background processing settings
+        self.queue_size = int(os.getenv("CLAUDE_MPM_HOOK_QUEUE_SIZE", "1000"))
+        self.background_timeout = float(os.getenv("CLAUDE_MPM_HOOK_BG_TIMEOUT", "2.0"))
+
+        # Batching settings (for future implementation)
+        self.enable_batching = (
+            os.getenv("CLAUDE_MPM_HOOK_BATCHING", "false").lower() == "true"
+        )
+        self.batch_size = int(os.getenv("CLAUDE_MPM_HOOK_BATCH_SIZE", "10"))
+        self.batch_timeout_ms = int(
+            os.getenv("CLAUDE_MPM_HOOK_BATCH_TIMEOUT_MS", "100")
+        )
+
+    def is_hook_enabled(self, hook_type: str) -> bool:
+        """Check if a specific hook type is enabled.
+
+        Args:
+            hook_type: Type of hook (PreToolUse, PostToolUse, UserPromptSubmit, etc.)
+
+        Returns:
+            bool: True if hook should be processed
+        """
+        if self.performance_mode:
+            return False
+
+        hook_type_lower = hook_type.lower()
+
+        if "pretool" in hook_type_lower or "pre_tool" in hook_type_lower:
+            return self.enable_pre_tool_hooks
+        if "posttool" in hook_type_lower or "post_tool" in hook_type_lower:
+            return self.enable_post_tool_hooks
+        if "userprompt" in hook_type_lower or "user_prompt" in hook_type_lower:
+            return self.enable_user_prompt_hooks
+        if "delegation" in hook_type_lower:
+            return self.enable_delegation_hooks
+
+        # Default to enabled for unknown hook types
+        return True
+
+    def get_queue_config(self) -> Dict[str, int]:
+        """Get queue configuration for background processing."""
+        return {"maxsize": self.queue_size, "timeout": self.background_timeout}
+
+    def get_batch_config(self) -> Dict[str, any]:
+        """Get batching configuration (for future use)."""
+        return {
+            "enabled": self.enable_batching,
+            "batch_size": self.batch_size,
+            "timeout_ms": self.batch_timeout_ms,
+        }
+
+    def print_config(self) -> str:
+        """Return a string representation of current configuration."""
+        config_lines = [
+            "Hook Performance Configuration:",
+            f"  Performance Mode: {self.performance_mode}",
+            f"  Pre-tool Hooks: {self.enable_pre_tool_hooks}",
+            f"  Post-tool Hooks: {self.enable_post_tool_hooks}",
+            f"  User Prompt Hooks: {self.enable_user_prompt_hooks}",
+            f"  Delegation Hooks: {self.enable_delegation_hooks}",
+            f"  Queue Size: {self.queue_size}",
+            f"  Background Timeout: {self.background_timeout}s",
+            f"  Batching Enabled: {self.enable_batching}",
+        ]
+        return "\n".join(config_lines)
+
+
+# Global configuration instance
+_hook_config: Optional[HookPerformanceConfig] = None
+
+
+def get_hook_performance_config() -> HookPerformanceConfig:
+    """Get the global hook performance configuration instance."""
+    global _hook_config
+    if _hook_config is None:
+        _hook_config = HookPerformanceConfig()
+    return _hook_config
+
+
+def set_performance_mode(enabled: bool):
+    """Enable or disable performance mode programmatically.
+
+    Args:
+        enabled: True to enable performance mode (disable all hooks)
+    """
+    os.environ["CLAUDE_MPM_PERFORMANCE_MODE"] = "true" if enabled else "false"
+    # Reload configuration
+    global _hook_config
+    _hook_config = None
+
+
+def is_performance_mode() -> bool:
+    """Check if performance mode is currently enabled."""
+    return get_hook_performance_config().performance_mode
+
+
+# Environment variable documentation for users
+ENVIRONMENT_VARIABLES = {
+    "CLAUDE_MPM_PERFORMANCE_MODE": 'Set to "true" to disable all hooks for maximum performance',
+    "CLAUDE_MPM_HOOKS_PRE_TOOL": 'Set to "false" to disable pre-tool hooks',
+    "CLAUDE_MPM_HOOKS_POST_TOOL": 'Set to "false" to disable post-tool hooks',
+    "CLAUDE_MPM_HOOKS_USER_PROMPT": 'Set to "false" to disable user prompt hooks',
+    "CLAUDE_MPM_HOOKS_DELEGATION": 'Set to "false" to disable delegation hooks',
+    "CLAUDE_MPM_HOOK_QUEUE_SIZE": "Maximum number of hooks in background queue (default: 1000)",
+    "CLAUDE_MPM_HOOK_BG_TIMEOUT": "Timeout for background hook processing in seconds (default: 2.0)",
+    "CLAUDE_MPM_HOOK_BATCHING": 'Set to "true" to enable hook batching (experimental)',
+    "CLAUDE_MPM_HOOK_BATCH_SIZE": "Number of hooks to batch together (default: 10)",
+    "CLAUDE_MPM_HOOK_BATCH_TIMEOUT_MS": "Batch timeout in milliseconds (default: 100)",
+}