claude-mpm 3.9.9__py3-none-any.whl → 4.0.3__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
@@ -12,47 +14,147 @@ WHY this is needed:
 
 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 typing import Any, Dict, Optional
 
 from ..core.logger import get_logger
-from ..deployment_paths import get_package_root
+from .config_constants import ConfigConstants
+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 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."""
+        try:
+            hook_type = hook_data['hook_type']
+            event_data = hook_data['event_data']
+
+            # Create the hook event
+            hook_event = {
+                "hook_event_name": hook_type,
+                "session_id": self.session_id,
+                "timestamp": hook_data.get('timestamp', datetime.utcnow().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,
+            )
+
+            if result.returncode != 0:
+                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
+            try:
+                self.hook_queue.put_nowait(None)
+            except queue.Full:
+                pass
+
+            # 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:
@@ -61,108 +163,105 @@ class HookManager:
         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: 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.utcnow().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.utcnow().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.utcnow().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.utcnow().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
-            )
-            
-            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}")
+
+            # Try to queue without blocking
+            self.hook_queue.put_nowait(hook_data)
+            self.logger.debug(f"Successfully queued {hook_type} hook for background processing")
+            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 +274,28 @@ 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: 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 +303,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,136 @@
+"""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
+        elif 'posttool' in hook_type_lower or 'post_tool' in hook_type_lower:
+            return self.enable_post_tool_hooks
+        elif 'userprompt' in hook_type_lower or 'user_prompt' in hook_type_lower:
+            return self.enable_user_prompt_hooks
+        elif '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)',
+}