claude-mpm 4.1.2__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/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

claude_mpm/hooks/claude_hooks/services/duplicate_detector.py

@@ -0,0 +1,106 @@
+"""Duplicate event detection service for Claude hook handler.
+
+This service manages:
+- Event key generation
+- Duplicate event detection within time windows
+- Recent event tracking
+"""
+
+import threading
+import time
+from collections import deque
+
+
+class DuplicateEventDetector:
+    """Detects and filters duplicate events."""
+
+    def __init__(
+        self, max_recent_events: int = 10, duplicate_window_seconds: float = 0.1
+    ):
+        """Initialize duplicate event detector.
+
+        Args:
+            max_recent_events: Maximum number of recent events to track
+            duplicate_window_seconds: Time window in seconds for duplicate detection
+        """
+        # Track recent events to detect duplicates
+        self._recent_events = deque(maxlen=max_recent_events)
+        self._events_lock = threading.Lock()
+        self.duplicate_window_seconds = duplicate_window_seconds
+
+    def is_duplicate(self, event: dict) -> bool:
+        """Check if an event is a duplicate of a recent event.
+
+        Args:
+            event: The event dictionary to check
+
+        Returns:
+            True if the event is a duplicate, False otherwise
+        """
+        event_key = self.generate_event_key(event)
+        current_time = time.time()
+
+        with self._events_lock:
+            # Check if we've seen this event recently
+            for recent_key, recent_time in self._recent_events:
+                if (
+                    recent_key == event_key
+                    and (current_time - recent_time) < self.duplicate_window_seconds
+                ):
+                    return True
+
+            # Not a duplicate, record it
+            self._recent_events.append((event_key, current_time))
+            return False
+
+    def generate_event_key(self, event: dict) -> str:
+        """Generate a unique key for an event to detect duplicates.
+
+        WHY: Claude Code may call the hook multiple times for the same event
+        because the hook is registered for multiple event types. We need to
+        detect and skip duplicate processing while still returning continue.
+
+        Args:
+            event: The event dictionary
+
+        Returns:
+            A unique string key for the event
+        """
+        # Create a key from event type, session_id, and key data
+        hook_type = event.get("hook_event_name", "unknown")
+        session_id = event.get("session_id", "")
+
+        # Add type-specific data to make the key unique
+        if hook_type == "PreToolUse":
+            tool_name = event.get("tool_name", "")
+            # For some tools, include parameters to distinguish calls
+            if tool_name == "Task":
+                tool_input = event.get("tool_input", {})
+                agent = tool_input.get("subagent_type", "")
+                prompt_preview = (
+                    tool_input.get("prompt", "") or tool_input.get("description", "")
+                )[:50]
+                return f"{hook_type}:{session_id}:{tool_name}:{agent}:{prompt_preview}"
+            return f"{hook_type}:{session_id}:{tool_name}"
+
+        if hook_type == "UserPromptSubmit":
+            prompt_preview = event.get("prompt", "")[:50]
+            return f"{hook_type}:{session_id}:{prompt_preview}"
+
+        # For other events, just use type and session
+        return f"{hook_type}:{session_id}"
+
+    def clear_old_events(self):
+        """Clear events older than the duplicate window."""
+        current_time = time.time()
+        cutoff_time = current_time - self.duplicate_window_seconds
+
+        with self._events_lock:
+            # Create a new deque with only recent events
+            recent_only = deque(
+                (key, timestamp)
+                for key, timestamp in self._recent_events
+                if timestamp > cutoff_time
+            )
+            recent_only.maxlen = self._recent_events.maxlen
+            self._recent_events = recent_only