claude-mpm 4.1.1__py3-none-any.whl → 4.1.3__py3-none-any.whl

claude_mpm/hooks/claude_hooks/hook_handler_refactored.py

@@ -0,0 +1,347 @@
+#!/usr/bin/env python3
+"""Refactored Claude Code hook handler with modular service architecture.
+
+This handler uses a service-oriented architecture with:
+- StateManagerService: Manages state and delegation tracking
+- ConnectionManagerService: Handles SocketIO and EventBus connections
+- SubagentResponseProcessor: Processes complex subagent responses
+- DuplicateEventDetector: Detects and filters duplicate events
+
+WHY service-oriented approach:
+- Better separation of concerns and modularity
+- Easier testing and maintenance
+- Reduced file size from 1040 to ~400 lines
+- Clear service boundaries and responsibilities
+"""
+
+import json
+import os
+import select
+import signal
+import sys
+import threading
+from datetime import datetime
+
+# Import extracted modules with fallback for direct execution
+try:
+    # Try relative imports first (when imported as module)
+    from .event_handlers import EventHandlers
+    from .memory_integration import MemoryHookManager
+    from .response_tracking import ResponseTrackingManager
+    from .services import (
+        ConnectionManagerService,
+        DuplicateEventDetector,
+        StateManagerService,
+        SubagentResponseProcessor,
+    )
+except ImportError:
+    # Fall back to absolute imports (when run directly)
+    from pathlib import Path
+
+    # Add parent directory to path
+    sys.path.insert(0, str(Path(__file__).parent))
+
+    from event_handlers import EventHandlers
+    from memory_integration import MemoryHookManager
+    from response_tracking import ResponseTrackingManager
+    from services import (
+        ConnectionManagerService,
+        DuplicateEventDetector,
+        StateManagerService,
+        SubagentResponseProcessor,
+    )
+
+# Debug mode is enabled by default for better visibility into hook processing
+# Set CLAUDE_MPM_HOOK_DEBUG=false to disable debug output
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+
+# Global singleton handler instance
+_global_handler = None
+_handler_lock = threading.Lock()
+
+
+class ClaudeHookHandler:
+    """Refactored hook handler with service-oriented architecture.
+
+    WHY service-oriented approach:
+    - Modular design with clear service boundaries
+    - Each service handles a specific responsibility
+    - Easier to test, maintain, and extend
+    - Reduced complexity in main handler class
+    """
+
+    def __init__(self):
+        # Initialize services
+        self.state_manager = StateManagerService()
+        self.connection_manager = ConnectionManagerService()
+        self.duplicate_detector = DuplicateEventDetector()
+
+        # Initialize extracted managers
+        self.memory_hook_manager = MemoryHookManager()
+        self.response_tracking_manager = ResponseTrackingManager()
+        self.event_handlers = EventHandlers(self)
+
+        # Initialize subagent processor with dependencies
+        self.subagent_processor = SubagentResponseProcessor(
+            self.state_manager, self.response_tracking_manager, self.connection_manager
+        )
+
+    def handle(self):
+        """Process hook event with minimal overhead and timeout protection.
+
+        WHY this approach:
+        - Fast path processing for minimal latency (no blocking waits)
+        - Non-blocking Socket.IO connection and event emission
+        - Timeout protection prevents indefinite hangs
+        - Connection timeout prevents indefinite hangs
+        - Graceful degradation if Socket.IO unavailable
+        - Always continues regardless of event status
+        - Process exits after handling to prevent accumulation
+        """
+        _continue_sent = False  # Track if continue has been sent
+
+        def timeout_handler(signum, frame):
+            """Handle timeout by forcing exit."""
+            nonlocal _continue_sent
+            if DEBUG:
+                print(f"Hook handler timeout (pid: {os.getpid()})", file=sys.stderr)
+            if not _continue_sent:
+                self._continue_execution()
+                _continue_sent = True
+            sys.exit(0)
+
+        try:
+            # Set a 10-second timeout for the entire operation
+            signal.signal(signal.SIGALRM, timeout_handler)
+            signal.alarm(10)
+
+            # Read and parse event
+            event = self._read_hook_event()
+            if not event:
+                if not _continue_sent:
+                    self._continue_execution()
+                    _continue_sent = True
+                return
+
+            # Check for duplicate events (same event within 100ms)
+            if self.duplicate_detector.is_duplicate(event):
+                if DEBUG:
+                    print(
+                        f"[{datetime.now().isoformat()}] Skipping duplicate event: {event.get('hook_event_name', 'unknown')} (PID: {os.getpid()})",
+                        file=sys.stderr,
+                    )
+                # Still need to output continue for this invocation
+                if not _continue_sent:
+                    self._continue_execution()
+                    _continue_sent = True
+                return
+
+            # Debug: Log that we're processing an event
+            if DEBUG:
+                hook_type = event.get("hook_event_name", "unknown")
+                print(
+                    f"\n[{datetime.now().isoformat()}] Processing hook event: {hook_type} (PID: {os.getpid()})",
+                    file=sys.stderr,
+                )
+
+            # Perform periodic cleanup if needed
+            if self.state_manager.increment_events_processed():
+                self.state_manager.cleanup_old_entries()
+                if DEBUG:
+                    print(
+                        f"🧹 Performed cleanup after {self.state_manager.events_processed} events",
+                        file=sys.stderr,
+                    )
+
+            # Route event to appropriate handler
+            self._route_event(event)
+
+            # Always continue execution (only if not already sent)
+            if not _continue_sent:
+                self._continue_execution()
+                _continue_sent = True
+
+        except Exception:
+            # Fail fast and silent (only send continue if not already sent)
+            if not _continue_sent:
+                self._continue_execution()
+                _continue_sent = True
+        finally:
+            # Cancel the alarm
+            signal.alarm(0)
+
+    def _read_hook_event(self) -> dict:
+        """
+        Read and parse hook event from stdin with timeout.
+
+        WHY: Centralized event reading with error handling and timeout
+        ensures consistent parsing and validation while preventing
+        processes from hanging indefinitely on stdin.read().
+
+        Returns:
+            Parsed event dictionary or None if invalid/timeout
+        """
+        try:
+            # Check if data is available on stdin with 1 second timeout
+            if sys.stdin.isatty():
+                # Interactive terminal - no data expected
+                return None
+
+            ready, _, _ = select.select([sys.stdin], [], [], 1.0)
+            if not ready:
+                # No data available within timeout
+                if DEBUG:
+                    print("No hook event data received within timeout", file=sys.stderr)
+                return None
+
+            # Data is available, read it
+            event_data = sys.stdin.read()
+            if not event_data.strip():
+                # Empty or whitespace-only data
+                return None
+
+            return json.loads(event_data)
+        except (json.JSONDecodeError, ValueError) as e:
+            if DEBUG:
+                print(f"Failed to parse hook event: {e}", file=sys.stderr)
+            return None
+        except Exception as e:
+            if DEBUG:
+                print(f"Error reading hook event: {e}", file=sys.stderr)
+            return None
+
+    def _route_event(self, event: dict) -> None:
+        """
+        Route event to appropriate handler based on type.
+
+        WHY: Centralized routing reduces complexity and makes
+        it easier to add new event types.
+
+        Args:
+            event: Hook event dictionary
+        """
+        hook_type = event.get("hook_event_name", "unknown")
+
+        # Map event types to handlers
+        event_handlers = {
+            "UserPromptSubmit": self.event_handlers.handle_user_prompt_fast,
+            "PreToolUse": self.event_handlers.handle_pre_tool_fast,
+            "PostToolUse": self.event_handlers.handle_post_tool_fast,
+            "Notification": self.event_handlers.handle_notification_fast,
+            "Stop": self.event_handlers.handle_stop_fast,
+            "SubagentStop": self.handle_subagent_stop,
+            "AssistantResponse": self.event_handlers.handle_assistant_response,
+        }
+
+        # Call appropriate handler if exists
+        handler = event_handlers.get(hook_type)
+        if handler:
+            try:
+                handler(event)
+            except Exception as e:
+                if DEBUG:
+                    print(f"Error handling {hook_type}: {e}", file=sys.stderr)
+
+    def handle_subagent_stop(self, event: dict):
+        """Delegate subagent stop processing to the specialized processor."""
+        self.subagent_processor.process_subagent_stop(event)
+
+    def _continue_execution(self) -> None:
+        """
+        Send continue action to Claude.
+
+        WHY: Centralized response ensures consistent format
+        and makes it easier to add response modifications.
+        """
+        print(json.dumps({"action": "continue"}))
+
+    # Delegation methods for compatibility with event_handlers
+    def _track_delegation(self, session_id: str, agent_type: str, request_data=None):
+        """Track delegation through state manager."""
+        self.state_manager.track_delegation(session_id, agent_type, request_data)
+
+    def _get_delegation_agent_type(self, session_id: str) -> str:
+        """Get delegation agent type through state manager."""
+        return self.state_manager.get_delegation_agent_type(session_id)
+
+    def _get_git_branch(self, working_dir=None) -> str:
+        """Get git branch through state manager."""
+        return self.state_manager.get_git_branch(working_dir)
+
+    def _emit_socketio_event(self, namespace: str, event: str, data: dict):
+        """Emit event through connection manager."""
+        self.connection_manager.emit_event(namespace, event, data)
+
+    def __del__(self):
+        """Cleanup on handler destruction."""
+        # Clean up connection manager if it exists
+        if hasattr(self, "connection_manager") and self.connection_manager:
+            try:
+                self.connection_manager.cleanup()
+            except:
+                pass  # Ignore cleanup errors during destruction
+
+
+def main():
+    """Entry point with singleton pattern and proper cleanup."""
+    global _global_handler
+    _continue_printed = False  # Track if we've already printed continue
+
+    def cleanup_handler(signum=None, frame=None):
+        """Cleanup handler for signals and exit."""
+        nonlocal _continue_printed
+        if DEBUG:
+            print(
+                f"Hook handler cleanup (pid: {os.getpid()}, signal: {signum})",
+                file=sys.stderr,
+            )
+        # Only output continue if we haven't already (i.e., if interrupted by signal)
+        if signum is not None and not _continue_printed:
+            print(json.dumps({"action": "continue"}))
+            _continue_printed = True
+            sys.exit(0)
+
+    # Register cleanup handlers
+    signal.signal(signal.SIGTERM, cleanup_handler)
+    signal.signal(signal.SIGINT, cleanup_handler)
+    # Don't register atexit handler since we're handling exit properly in main
+
+    try:
+        # Use singleton pattern to prevent creating multiple instances
+        with _handler_lock:
+            if _global_handler is None:
+                _global_handler = ClaudeHookHandler()
+                if DEBUG:
+                    print(
+                        f"✅ Created new ClaudeHookHandler singleton (pid: {os.getpid()})",
+                        file=sys.stderr,
+                    )
+            elif DEBUG:
+                print(
+                    f"♻️ Reusing existing ClaudeHookHandler singleton (pid: {os.getpid()})",
+                    file=sys.stderr,
+                )
+
+            handler = _global_handler
+
+        # Mark that handle() will print continue
+        handler.handle()
+        _continue_printed = True  # Mark as printed since handle() always prints it
+
+        # handler.handle() already calls _continue_execution(), so we don't need to do it again
+        # Just exit cleanly
+        sys.exit(0)
+
+    except Exception as e:
+        # Only output continue if not already printed
+        if not _continue_printed:
+            print(json.dumps({"action": "continue"}))
+            _continue_printed = True
+        # Log error for debugging
+        if DEBUG:
+            print(f"Hook handler error: {e}", file=sys.stderr)
+        sys.exit(0)  # Exit cleanly even on error
+
+
+if __name__ == "__main__":
+    main()

claude_mpm/hooks/claude_hooks/memory_integration.py

@@ -8,7 +8,7 @@ including pre and post delegation hooks.
 import os
 import sys
 from datetime import datetime
-from typing import Any, Dict, Optional
+from typing import Optional
 
 # Debug mode
 DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
@@ -21,14 +21,12 @@ try:
 
     paths.ensure_in_path()
 
-    from claude_mpm.core.config import Config
     from claude_mpm.core.shared.config_loader import ConfigLoader
     from claude_mpm.hooks.base_hook import HookContext, HookType
     from claude_mpm.hooks.memory_integration_hook import (
         MemoryPostDelegationHook,
         MemoryPreDelegationHook,
     )
-    from claude_mpm.services.hook_service import HookService
 
     MEMORY_HOOKS_AVAILABLE = True
 except Exception as e:
@@ -181,7 +179,7 @@ class MemoryHookManager:
             if output:
                 result_content = str(output)
             elif error:
-                result_content = f"Error: {str(error)}"
+                result_content = f"Error: {error!s}"
             else:
                 result_content = f"Task completed with exit code: {exit_code}"
 

claude_mpm/hooks/claude_hooks/response_tracking.py

@@ -10,7 +10,7 @@ import os
 import re
 import sys
 from datetime import datetime
-from typing import Any, Dict, Optional
+from typing import Optional
 
 # Debug mode
 DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
@@ -53,7 +53,6 @@ class ResponseTrackingManager:
         try:
             # Create configuration with optional config file using ConfigLoader
             config_file = os.environ.get("CLAUDE_PM_CONFIG_FILE")
-            from claude_mpm.core.config import Config
             from claude_mpm.core.shared.config_loader import ConfigLoader, ConfigPattern
 
             config_loader = ConfigLoader()
@@ -62,9 +61,11 @@ class ResponseTrackingManager:
                 pattern = ConfigPattern(
                     filenames=[os.path.basename(config_file)],
                     search_paths=[os.path.dirname(config_file)],
-                    env_prefix="CLAUDE_MPM_"
+                    env_prefix="CLAUDE_MPM_",
+                )
+                config = config_loader.load_config(
+                    pattern, cache_key=f"response_tracking_{config_file}"
                 )
-                config = config_loader.load_config(pattern, cache_key=f"response_tracking_{config_file}")
             else:
                 config = config_loader.load_main_config()
 
@@ -101,7 +102,9 @@ class ResponseTrackingManager:
 
         except Exception as e:
             if DEBUG:
-                print(f"❌ Failed to initialize response tracking: {e}", file=sys.stderr)
+                print(
+                    f"❌ Failed to initialize response tracking: {e}", file=sys.stderr
+                )
             # Don't fail the entire handler - response tracking is optional
 
     def track_agent_response(
@@ -203,11 +206,13 @@ class ResponseTrackingManager:
                     "files_modified": structured_response.get("files_modified", []),
                     "tools_used": structured_response.get("tools_used", []),
                     "remember": structured_response.get("remember"),
-                    "MEMORIES": structured_response.get("MEMORIES"),  # Complete memory replacement
+                    "MEMORIES": structured_response.get(
+                        "MEMORIES"
+                    ),  # Complete memory replacement
                 }
-                
-                # Log if MEMORIES field is present  
-                if "MEMORIES" in structured_response and structured_response["MEMORIES"]:
+
+                # Log if MEMORIES field is present
+                if structured_response.get("MEMORIES"):
                     if DEBUG:
                         memories_count = len(structured_response["MEMORIES"])
                         print(
@@ -247,8 +252,7 @@ class ResponseTrackingManager:
                 )
 
             # Clean up the request data after successful tracking
-            if session_id in delegation_requests:
-                del delegation_requests[session_id]
+            delegation_requests.pop(session_id, None)
 
         except Exception as e:
             if DEBUG:

claude_mpm/hooks/claude_hooks/services/__init__.py

@@ -0,0 +1,13 @@
+"""Hook handler services for modular functionality."""
+
+from .connection_manager import ConnectionManagerService
+from .duplicate_detector import DuplicateEventDetector
+from .state_manager import StateManagerService
+from .subagent_processor import SubagentResponseProcessor
+
+__all__ = [
+    "ConnectionManagerService",
+    "DuplicateEventDetector",
+    "StateManagerService",
+    "SubagentResponseProcessor",
+]

claude_mpm/hooks/claude_hooks/services/connection_manager.py

@@ -0,0 +1,190 @@
+"""Connection management service for Claude hook handler.
+
+This service manages:
+- SocketIO connection pool initialization
+- EventBus initialization
+- Event emission through both channels
+- Connection cleanup
+"""
+
+import os
+import sys
+from datetime import datetime
+
+# Debug mode is enabled by default for better visibility into hook processing
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+
+# Import extracted modules with fallback for direct execution
+try:
+    # Try relative imports first (when imported as module)
+    # Use the modern SocketIOConnectionPool instead of the deprecated local one
+    from claude_mpm.core.socketio_pool import get_connection_pool
+except ImportError:
+    # Fall back to absolute imports (when run directly)
+    from pathlib import Path
+
+    # Add parent directory to path
+    sys.path.insert(0, str(Path(__file__).parent))
+
+    # Try to import get_connection_pool from deprecated location
+    try:
+        from connection_pool import SocketIOConnectionPool
+
+        def get_connection_pool():
+            return SocketIOConnectionPool()
+
+    except ImportError:
+        get_connection_pool = None
+
+# Import EventNormalizer for consistent event formatting
+try:
+    from claude_mpm.services.socketio.event_normalizer import EventNormalizer
+except ImportError:
+    # Create a simple fallback EventNormalizer if import fails
+    class EventNormalizer:
+        def normalize(self, event_data, source="hook"):
+            """Simple fallback normalizer that returns event as-is."""
+            return type(
+                "NormalizedEvent",
+                (),
+                {
+                    "to_dict": lambda: {
+                        "event": "claude_event",
+                        "type": event_data.get("type", "unknown"),
+                        "subtype": event_data.get("subtype", "generic"),
+                        "timestamp": event_data.get(
+                            "timestamp", datetime.now().isoformat()
+                        ),
+                        "data": event_data.get("data", event_data),
+                    }
+                },
+            )
+
+
+# Import EventBus for decoupled event distribution
+try:
+    from claude_mpm.services.event_bus import EventBus
+
+    EVENTBUS_AVAILABLE = True
+except ImportError:
+    EVENTBUS_AVAILABLE = False
+    EventBus = None
+
+
+class ConnectionManagerService:
+    """Manages connections for the Claude hook handler."""
+
+    def __init__(self):
+        """Initialize connection management service."""
+        # Event normalizer for consistent event schema
+        self.event_normalizer = EventNormalizer()
+
+        # Initialize SocketIO connection pool for inter-process communication
+        # This sends events directly to the Socket.IO server in the daemon process
+        self.connection_pool = None
+        self._initialize_socketio_pool()
+
+        # Initialize EventBus for in-process event distribution (optional)
+        self.event_bus = None
+        self._initialize_eventbus()
+
+    def _initialize_socketio_pool(self):
+        """Initialize the SocketIO connection pool."""
+        try:
+            self.connection_pool = get_connection_pool()
+            if DEBUG:
+                print("✅ Modern SocketIO connection pool initialized", file=sys.stderr)
+        except Exception as e:
+            if DEBUG:
+                print(
+                    f"⚠️ Failed to initialize SocketIO connection pool: {e}",
+                    file=sys.stderr,
+                )
+            self.connection_pool = None
+
+    def _initialize_eventbus(self):
+        """Initialize the EventBus for in-process distribution."""
+        if EVENTBUS_AVAILABLE:
+            try:
+                self.event_bus = EventBus.get_instance()
+                if DEBUG:
+                    print("✅ EventBus initialized for hook handler", file=sys.stderr)
+            except Exception as e:
+                if DEBUG:
+                    print(f"⚠️ Failed to initialize EventBus: {e}", file=sys.stderr)
+                self.event_bus = None
+
+    def emit_event(self, namespace: str, event: str, data: dict):
+        """Emit event through both connection pool and EventBus.
+
+        WHY dual approach:
+        - Connection pool: Direct Socket.IO connection for inter-process communication
+        - EventBus: For in-process subscribers (if any)
+        - Ensures events reach the dashboard regardless of process boundaries
+        """
+        # Create event data for normalization
+        raw_event = {
+            "type": "hook",
+            "subtype": event,  # e.g., "user_prompt", "pre_tool", "subagent_stop"
+            "timestamp": datetime.now().isoformat(),
+            "data": data,
+            "source": "claude_hooks",  # Identify the source
+            "session_id": data.get("sessionId"),  # Include session if available
+        }
+
+        # Normalize the event using EventNormalizer for consistent schema
+        normalized_event = self.event_normalizer.normalize(raw_event, source="hook")
+        claude_event_data = normalized_event.to_dict()
+
+        # Log important events for debugging
+        if DEBUG and event in ["subagent_stop", "pre_tool"]:
+            if event == "subagent_stop":
+                agent_type = data.get("agent_type", "unknown")
+                print(
+                    f"Hook handler: Publishing SubagentStop for agent '{agent_type}'",
+                    file=sys.stderr,
+                )
+            elif event == "pre_tool" and data.get("tool_name") == "Task":
+                delegation = data.get("delegation_details", {})
+                agent_type = delegation.get("agent_type", "unknown")
+                print(
+                    f"Hook handler: Publishing Task delegation to agent '{agent_type}'",
+                    file=sys.stderr,
+                )
+
+        # First, try to emit through direct Socket.IO connection pool
+        # This is the primary path for inter-process communication
+        if self.connection_pool:
+            try:
+                # Emit to Socket.IO server directly
+                self.connection_pool.emit("claude_event", claude_event_data)
+                if DEBUG:
+                    print(f"✅ Emitted via connection pool: {event}", file=sys.stderr)
+            except Exception as e:
+                if DEBUG:
+                    print(f"⚠️ Failed to emit via connection pool: {e}", file=sys.stderr)
+
+        # Also publish to EventBus for any in-process subscribers
+        if self.event_bus and EVENTBUS_AVAILABLE:
+            try:
+                # Publish to EventBus with topic format: hook.{event}
+                topic = f"hook.{event}"
+                self.event_bus.publish(topic, claude_event_data)
+                if DEBUG:
+                    print(f"✅ Published to EventBus: {topic}", file=sys.stderr)
+            except Exception as e:
+                if DEBUG:
+                    print(f"⚠️ Failed to publish to EventBus: {e}", file=sys.stderr)
+
+        # Warn if neither method is available
+        if not self.connection_pool and not self.event_bus and DEBUG:
+            print(f"⚠️ No event emission method available for: {event}", file=sys.stderr)
+
+    def cleanup(self):
+        """Cleanup connections on service destruction."""
+        # Clean up connection pool if it exists
+        if self.connection_pool:
+            try:
+                self.connection_pool.cleanup()
+            except:
+                pass  # Ignore cleanup errors during destruction