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

claude_mpm/hooks/claude_hooks/hook_handler.py

@@ -1,932 +1,709 @@
 #!/usr/bin/env python3
-"""Optimized Claude Code hook handler with Socket.IO connection pooling.
+"""Refactored Claude Code hook handler with modular service architecture.
 
-This handler now uses a connection pool for Socket.IO clients to reduce
-connection overhead and implement circuit breaker and batching patterns.
+This handler uses a service-oriented architecture with:
+- StateManagerService: Manages state and delegation tracking
+- ConnectionManagerService: Handles SocketIO connections with HTTP fallback
+- SubagentResponseProcessor: Processes complex subagent responses
+- DuplicateEventDetector: Detects and filters duplicate events
 
-WHY connection pooling approach:
-- Reduces connection setup/teardown overhead by 80%
-- Implements circuit breaker for resilience during outages
-- Provides micro-batching for high-frequency events
-- Maintains persistent connections for better performance
-- Falls back gracefully when Socket.IO unavailable
+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
+
+NOTE: Requires Claude Code version 1.0.92 or higher for proper hook support.
+Earlier versions do not support matcher-based hook configuration.
 """
 
 import json
-import sys
 import os
+import re
+import select
+import signal
 import subprocess
-from datetime import datetime
-from pathlib import Path
-from collections import deque
-
-# Quick environment check - must be defined before any code that might use it
-DEBUG = os.environ.get('CLAUDE_MPM_HOOK_DEBUG', '').lower() == 'true'
+import sys
+import threading
+from datetime import datetime, timezone
+from typing import Optional, Tuple
 
-# Add imports for memory hook integration with comprehensive error handling
-MEMORY_HOOKS_AVAILABLE = False
+# Import extracted modules with fallback for direct execution
 try:
-    # Try to add src to path if not already there (fallback for missing PYTHONPATH)
-    import sys
+    # 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
-    src_path = Path(__file__).parent.parent.parent.parent
-    if src_path.exists() and str(src_path) not in sys.path:
-        sys.path.insert(0, str(src_path))
-    
-    from claude_mpm.services.hook_service import HookService
-    from claude_mpm.hooks.memory_integration_hook import (
-        MemoryPreDelegationHook,
-        MemoryPostDelegationHook
+
+    # 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,
     )
-    from claude_mpm.hooks.base_hook import HookContext, HookType
-    from claude_mpm.core.config import Config
-    MEMORY_HOOKS_AVAILABLE = True
-except Exception as e:
-    # Catch all exceptions to prevent any import errors from breaking the handler
-    if DEBUG:
-        print(f"Memory hooks not available: {e}", file=sys.stderr)
-    MEMORY_HOOKS_AVAILABLE = False
-
-# Socket.IO import
+
+"""
+Debug mode configuration for hook processing.
+
+WHY enabled by default: Hook processing can be complex and hard to debug.
+Having debug output available by default helps diagnose issues during development.
+Production deployments can disable via environment variable.
+
+Performance Impact: Debug logging adds ~5-10% overhead but provides crucial
+visibility into event flow, timing, and error conditions.
+"""
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+
+"""
+Conditional imports with graceful fallbacks for testing and modularity.
+
+WHY conditional imports:
+- Tests may not have full environment setup
+- Allows hooks to work in minimal configurations
+- Graceful degradation when dependencies unavailable
+"""
+
+# Import get_connection_pool for backward compatibility with tests
 try:
-    import socketio
-    SOCKETIO_AVAILABLE = True
+    from claude_mpm.core.socketio_pool import get_connection_pool
 except ImportError:
-    SOCKETIO_AVAILABLE = False
-    socketio = None
+    get_connection_pool = None
+
+"""
+Global singleton pattern for hook handler.
+
+WHY singleton:
+- Only one handler should process Claude Code events
+- Maintains consistent state across all hook invocations
+- Prevents duplicate event processing
+- Thread-safe initialization with lock
+
+GOTCHA: Must use get_global_handler() not direct access to avoid race conditions.
+"""
+_global_handler = None
+_handler_lock = threading.Lock()
+
+"""
+Version compatibility checking.
+
+WHY version checking:
+- Claude Code hook support was added in v1.0.92
+- Earlier versions don't support matcher-based configuration
+- Prevents confusing errors with unsupported versions
+
+Security: Version checking prevents execution on incompatible environments.
+"""
+MIN_CLAUDE_VERSION = "1.0.92"
+
+
+def check_claude_version() -> Tuple[bool, Optional[str]]:
+    """
+    Verify Claude Code version compatibility for hook support.
+
+    Executes 'claude --version' command to detect installed version and
+    compares against minimum required version for hook functionality.
+
+    Version Checking Logic:
+    1. Execute 'claude --version' with timeout
+    2. Parse version string using regex
+    3. Compare against MIN_CLAUDE_VERSION (1.0.92)
+    4. Return compatibility status and detected version
+
+    WHY this check is critical:
+    - Hook support was added in Claude Code v1.0.92
+    - Earlier versions don't understand matcher-based hooks
+    - Prevents cryptic errors from unsupported configurations
+    - Allows graceful fallback or user notification
+
+    Error Handling:
+    - Command timeout after 5 seconds
+    - Subprocess errors caught and logged
+    - Invalid version formats handled gracefully
+    - Returns (False, None) on any failure
+
+    Performance Notes:
+    - Subprocess call has ~100ms overhead
+    - Result should be cached by caller
+    - Only called during initialization
+
+    Returns:
+        Tuple[bool, Optional[str]]:
+            - bool: True if version is compatible
+            - str|None: Detected version string, None if detection failed
+
+    Examples:
+        >>> is_compatible, version = check_claude_version()
+        >>> if not is_compatible:
+        ...     print(f"Claude Code {version or 'unknown'} is not supported")
+    """
+    try:
+        # Try to detect Claude Code version
+        result = subprocess.run(
+            ["claude", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+
+        if result.returncode == 0:
+            version_text = result.stdout.strip()
+            # Extract version number (e.g., "1.0.92 (Claude Code)" -> "1.0.92")
+            match = re.match(r"^([\d\.]+)", version_text)
+            if match:
+                version = match.group(1)
+
+                # Compare versions
+                def parse_version(v: str):
+                    try:
+                        return [int(x) for x in v.split(".")]
+                    except (ValueError, AttributeError):
+                        return [0]
+
+                current = parse_version(version)
+                required = parse_version(MIN_CLAUDE_VERSION)
+
+                # Check if current version meets minimum
+                for i in range(max(len(current), len(required))):
+                    curr_part = current[i] if i < len(current) else 0
+                    req_part = required[i] if i < len(required) else 0
+
+                    if curr_part < req_part:
+                        if DEBUG:
+                            print(
+                                f"⚠️  Claude Code {version} does not support matcher-based hooks "
+                                f"(requires {MIN_CLAUDE_VERSION}+). Hook monitoring disabled.",
+                                file=sys.stderr,
+                            )
+                        return False, version
+                    if curr_part > req_part:
+                        return True, version
+
+                return True, version
+    except Exception as e:
+        if DEBUG:
+            print(
+                f"Warning: Could not detect Claude Code version: {e}", file=sys.stderr
+            )
 
-# No fallback needed - we only use Socket.IO now
+    return False, None
 
 
 class ClaudeHookHandler:
-    """Optimized hook handler with direct Socket.IO client.
-    
-    WHY direct client approach:
-    - Simple and reliable synchronous operation
-    - No complex threading or async issues
-    - Fast connection reuse when possible
-    - Graceful fallback when Socket.IO unavailable
+    """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):
-        # Socket.IO client (persistent if possible)
-        self.sio_client = None
-        self.sio_connected = False
-        
-        # Agent delegation tracking
-        # Store recent Task delegations: session_id -> agent_type
-        self.active_delegations = {}
-        # Use deque to limit memory usage (keep last 100 delegations)
-        self.delegation_history = deque(maxlen=100)
-        
-        # Git branch cache (to avoid repeated subprocess calls)
+        # 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
+        )
+
+        # Backward compatibility properties for tests
+        self.connection_pool = self.connection_manager.connection_pool
+
+        # Expose state manager properties for backward compatibility
+        self.active_delegations = self.state_manager.active_delegations
+        self.delegation_history = self.state_manager.delegation_history
+        self.delegation_requests = self.state_manager.delegation_requests
+        self.pending_prompts = self.state_manager.pending_prompts
+
+        # Initialize git branch cache (used by event_handlers)
         self._git_branch_cache = {}
         self._git_branch_cache_time = {}
-        
-        # Initialize memory hooks if available
-        self.memory_hooks_initialized = False
-        self.pre_delegation_hook = None
-        self.post_delegation_hook = None
-        if MEMORY_HOOKS_AVAILABLE:
-            self._initialize_memory_hooks()
-        
-        # No fallback server needed - we only use Socket.IO now
-    
-    def _track_delegation(self, session_id: str, agent_type: str):
-        """Track a new agent delegation."""
-        if session_id and agent_type and agent_type != 'unknown':
-            self.active_delegations[session_id] = agent_type
-            key = f"{session_id}:{datetime.now().timestamp()}"
-            self.delegation_history.append((key, agent_type))
-            
-            # Clean up old delegations (older than 5 minutes)
-            cutoff_time = datetime.now().timestamp() - 300
-            keys_to_remove = []
-            for sid in list(self.active_delegations.keys()):
-                # Check if this is an old entry by looking in history
-                found_recent = False
-                for hist_key, _ in reversed(self.delegation_history):
-                    if hist_key.startswith(sid):
-                        _, timestamp = hist_key.split(':', 1)
-                        if float(timestamp) > cutoff_time:
-                            found_recent = True
-                            break
-                if not found_recent:
-                    keys_to_remove.append(sid)
-            
-            for key in keys_to_remove:
-                del self.active_delegations[key]
-    
-    def _get_delegation_agent_type(self, session_id: str) -> str:
-        """Get the agent type for a session's active delegation."""
-        # First try exact session match
-        if session_id and session_id in self.active_delegations:
-            return self.active_delegations[session_id]
-        
-        # Then try to find in recent history
-        if session_id:
-            for key, agent_type in reversed(self.delegation_history):
-                if key.startswith(session_id):
-                    return agent_type
-        
-        return 'unknown'
-    
-    def _initialize_memory_hooks(self):
-        """Initialize memory hooks for automatic agent memory management.
-        
-        WHY: This activates the memory system by connecting Claude Code hook events
-        to our memory integration hooks. This enables automatic memory injection
-        before delegations and learning extraction after delegations.
-        
-        DESIGN DECISION: We initialize hooks here in the Claude hook handler because
-        this is where Claude Code events are processed. This ensures memory hooks
-        are triggered at the right times during agent delegation.
+
+    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:
-            # Create configuration
-            config = Config()
-            
-            # Only initialize if memory system is enabled
-            if not config.get('memory.enabled', True):
+            # 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("Memory system disabled - skipping hook initialization", file=sys.stderr)
+                    print(
+                        f"[{datetime.now(timezone.utc).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
-            
-            # Initialize pre-delegation hook for memory injection
-            self.pre_delegation_hook = MemoryPreDelegationHook(config)
-            
-            # Initialize post-delegation hook if auto-learning is enabled
-            if config.get('memory.auto_learning', True):  # Default to True now
-                self.post_delegation_hook = MemoryPostDelegationHook(config)
-            
-            self.memory_hooks_initialized = True
-            
-            if DEBUG:
-                hooks_info = []
-                if self.pre_delegation_hook:
-                    hooks_info.append("pre-delegation")
-                if self.post_delegation_hook:
-                    hooks_info.append("post-delegation")
-                print(f"✅ Memory hooks initialized: {', '.join(hooks_info)}", file=sys.stderr)
-                
-        except Exception as e:
+
+            # Debug: Log that we're processing an event
             if DEBUG:
-                print(f"❌ Failed to initialize memory hooks: {e}", file=sys.stderr)
-            # Don't fail the entire handler - memory system is optional
-    
-    def _get_git_branch(self, working_dir: str = None) -> str:
-        """Get git branch for the given directory with caching.
-        
-        WHY caching approach:
-        - Avoids repeated subprocess calls which are expensive
-        - Caches results for 30 seconds per directory
-        - Falls back gracefully if git command fails
-        - Returns 'Unknown' for non-git directories
+                hook_type = event.get("hook_event_name", "unknown")
+                print(
+                    f"\n[{datetime.now(timezone.utc).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()
+                # Also cleanup old correlation files
+                from .correlation_manager import CorrelationManager
+
+                CorrelationManager.cleanup_old()
+                if DEBUG:
+                    print(
+                        f"🧹 Performed cleanup after {self.state_manager.events_processed} events",
+                        file=sys.stderr,
+                    )
+
+            # Route event to appropriate handler
+            # Handlers can optionally return modified input for PreToolUse events
+            modified_input = self._route_event(event)
+
+            # Always continue execution (only if not already sent)
+            if not _continue_sent:
+                self._continue_execution(modified_input)
+                _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:
         """
-        # Use current working directory if not specified
-        if not working_dir:
-            working_dir = os.getcwd()
-        
-        # Check cache first (cache for 30 seconds)
-        current_time = datetime.now().timestamp()
-        cache_key = working_dir
-        
-        if (cache_key in self._git_branch_cache 
-            and cache_key in self._git_branch_cache_time
-            and current_time - self._git_branch_cache_time[cache_key] < 30):
-            return self._git_branch_cache[cache_key]
-        
-        # Try to get git branch
-        try:
-            # Change to the working directory temporarily
-            original_cwd = os.getcwd()
-            os.chdir(working_dir)
-            
-            # Run git command to get current branch
-            result = subprocess.run(
-                ['git', 'branch', '--show-current'],
-                capture_output=True,
-                text=True,
-                timeout=2  # Quick timeout to avoid hanging
-            )
-            
-            # Restore original directory
-            os.chdir(original_cwd)
-            
-            if result.returncode == 0 and result.stdout.strip():
-                branch = result.stdout.strip()
-                # Cache the result
-                self._git_branch_cache[cache_key] = branch
-                self._git_branch_cache_time[cache_key] = current_time
-                return branch
-            else:
-                # Not a git repository or no branch
-                self._git_branch_cache[cache_key] = 'Unknown'
-                self._git_branch_cache_time[cache_key] = current_time
-                return 'Unknown'
-                
-        except (subprocess.TimeoutExpired, subprocess.CalledProcessError, FileNotFoundError, OSError):
-            # Git not available or command failed
-            self._git_branch_cache[cache_key] = 'Unknown'
-            self._git_branch_cache_time[cache_key] = current_time
-            return 'Unknown'
-    
-    def _get_socketio_client(self):
-        """Get or create Socket.IO client.
-        
-        WHY this approach:
-        - Reuses existing connection when possible
-        - Creates new connection only when needed
-        - Handles connection failures gracefully
+        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
         """
-        if not SOCKETIO_AVAILABLE:
-            return None
-            
-        # Check if we have a connected client
-        if self.sio_client and self.sio_connected:
-            try:
-                # Test if still connected
-                if self.sio_client.connected:
-                    return self.sio_client
-            except:
-                pass
-        
-        # Need to create new client
         try:
-            port = int(os.environ.get('CLAUDE_MPM_SOCKETIO_PORT', '8765'))
-            self.sio_client = socketio.Client(
-                reconnection=False,  # Don't auto-reconnect in hooks
-                logger=False,
-                engineio_logger=False
-            )
-            
-            # Try to connect with short timeout
-            self.sio_client.connect(f'http://localhost:{port}', wait_timeout=1)
-            self.sio_connected = True
-            
+            # 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
+
+            parsed = json.loads(event_data)
+            # Debug: Log the actual event format we receive
             if DEBUG:
-                print(f"Hook handler: Connected to Socket.IO server on port {port}", file=sys.stderr)
-            
-            return self.sio_client
-            
+                print(
+                    f"Received event with keys: {list(parsed.keys())}", file=sys.stderr
+                )
+                for key in ["hook_event_name", "event", "type", "event_type"]:
+                    if key in parsed:
+                        print(f"  {key} = '{parsed[key]}'", file=sys.stderr)
+            return parsed
+        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"Hook handler: Failed to connect to Socket.IO: {e}", file=sys.stderr)
-            self.sio_client = None
-            self.sio_connected = False
+                print(f"Error reading hook event: {e}", file=sys.stderr)
             return None
-    
-    def handle(self):
-        """Process hook event with minimal overhead and zero blocking delays.
-        
-        WHY this approach:
-        - Fast path processing for minimal latency (no blocking waits)
-        - Non-blocking Socket.IO connection and event emission
-        - Removed sleep() delays that were adding 100ms+ to every hook
-        - Connection timeout prevents indefinite hangs
-        - Graceful degradation if Socket.IO unavailable
-        - Always continues regardless of event status
+
+    def _route_event(self, event: dict) -> Optional[dict]:
         """
-        try:
-            # Read event
-            event_data = sys.stdin.read()
-            event = json.loads(event_data)
-            hook_type = event.get('hook_event_name', 'unknown')
-            
-            # Fast path for common events
-            if hook_type == 'UserPromptSubmit':
-                self._handle_user_prompt_fast(event)
-            elif hook_type == 'PreToolUse':
-                self._handle_pre_tool_fast(event)
-            elif hook_type == 'PostToolUse':
-                self._handle_post_tool_fast(event)
-            elif hook_type == 'Notification':
-                self._handle_notification_fast(event)
-            elif hook_type == 'Stop':
-                self._handle_stop_fast(event)
-            elif hook_type == 'SubagentStop':
-                self._handle_subagent_stop_fast(event)
-            
-            # Socket.IO emit is non-blocking and will complete asynchronously
-            # Removed sleep() to eliminate 100ms delay that was blocking Claude execution
-            
-            # Always continue
-            print(json.dumps({"action": "continue"}))
-            
-        except:
-            # Fail fast and silent
-            print(json.dumps({"action": "continue"}))
-    
-    def _emit_socketio_event(self, namespace: str, event: str, data: dict):
-        """Emit Socket.IO event using direct client.
-        
-        WHY direct client approach:
-        - Simple synchronous emission
-        - No threading complexity
-        - Reliable delivery
-        - Fast when connection is reused
+        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
+
+        Returns:
+            Modified input for PreToolUse events (v2.0.30+), None otherwise
         """
-        # Fast path: Skip all Socket.IO operations unless configured
-        if not os.environ.get('CLAUDE_MPM_SOCKETIO_PORT') and not DEBUG:
-            return
-        
-        # Get Socket.IO client
-        client = self._get_socketio_client()
-        if client:
+        import time
+
+        # Try multiple field names for compatibility
+        hook_type = (
+            event.get("hook_event_name")
+            or event.get("event")
+            or event.get("type")
+            or event.get("event_type")
+            or event.get("hook_event_type")
+            or "unknown"
+        )
+
+        # Log the actual event structure for debugging
+        if DEBUG and hook_type == "unknown":
+            print(f"Unknown event format, keys: {list(event.keys())}", file=sys.stderr)
+            print(f"Event sample: {str(event)[:200]}", file=sys.stderr)
+
+        # 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.event_handlers.handle_subagent_stop_fast,
+            "SubagentStart": self.event_handlers.handle_session_start_fast,
+            "SessionStart": self.event_handlers.handle_session_start_fast,
+            "AssistantResponse": self.event_handlers.handle_assistant_response,
+        }
+
+        # Call appropriate handler if exists
+        handler = event_handlers.get(hook_type)
+        if handler:
+            # Track execution timing for hook emission
+            start_time = time.time()
+            success = False
+            error_message = None
+            result = None
+
             try:
-                # Format event for Socket.IO server
-                claude_event_data = {
-                    'type': f'hook.{event}',
-                    'timestamp': datetime.now().isoformat(),
-                    'data': data
-                }
-                
-                # Emit synchronously
-                client.emit('claude_event', claude_event_data)
-                
-                if DEBUG:
-                    print(f"Emitted Socket.IO event: hook.{event}", file=sys.stderr)
-                    
+                # Handlers can optionally return modified input
+                result = handler(event)
+                success = True
+                # Only PreToolUse handlers should return modified input
+                if hook_type == "PreToolUse" and result is not None:
+                    return_value = result
+                else:
+                    return_value = None
             except Exception as e:
+                error_message = str(e)
+                return_value = None
                 if DEBUG:
-                    print(f"Socket.IO emit failed: {e}", file=sys.stderr)
-                # Mark as disconnected so next call will reconnect
-                self.sio_connected = False
-    
-    def _handle_user_prompt_fast(self, event):
-        """Handle user prompt with comprehensive data capture.
-        
-        WHY enhanced data capture:
-        - Provides full context for debugging and monitoring
-        - Captures prompt text, working directory, and session context
-        - Enables better filtering and analysis in dashboard
-        """
-        prompt = event.get('prompt', '')
-        
-        # Skip /mpm commands to reduce noise unless debug is enabled
-        if prompt.startswith('/mpm') and not DEBUG:
-            return
-        
-        # Get working directory and git branch
-        working_dir = event.get('cwd', '')
-        git_branch = self._get_git_branch(working_dir) if working_dir else 'Unknown'
-        
-        # Extract comprehensive prompt data
-        prompt_data = {
-            'event_type': 'user_prompt',
-            'prompt_text': prompt,
-            'prompt_preview': prompt[:200] if len(prompt) > 200 else prompt,
-            'prompt_length': len(prompt),
-            'session_id': event.get('session_id', ''),
-            'working_directory': working_dir,
-            'git_branch': git_branch,
-            'timestamp': datetime.now().isoformat(),
-            'is_command': prompt.startswith('/'),
-            'contains_code': '```' in prompt or 'python' in prompt.lower() or 'javascript' in prompt.lower(),
-            'urgency': 'high' if any(word in prompt.lower() for word in ['urgent', 'error', 'bug', 'fix', 'broken']) else 'normal'
-        }
-        
-        # Emit to /hook namespace
-        self._emit_socketio_event('/hook', 'user_prompt', prompt_data)
-    
-    def _handle_pre_tool_fast(self, event):
-        """Handle pre-tool use with comprehensive data capture.
-        
-        WHY comprehensive capture:
-        - Captures tool parameters for debugging and security analysis
-        - Provides context about what Claude is about to do
-        - Enables pattern analysis and security monitoring
-        """
-        tool_name = event.get('tool_name', '')
-        tool_input = event.get('tool_input', {})
-        
-        # Extract key parameters based on tool type
-        tool_params = self._extract_tool_parameters(tool_name, tool_input)
-        
-        # Classify tool operation
-        operation_type = self._classify_tool_operation(tool_name, tool_input)
-        
-        # Get working directory and git branch
-        working_dir = event.get('cwd', '')
-        git_branch = self._get_git_branch(working_dir) if working_dir else 'Unknown'
-        
-        pre_tool_data = {
-            'event_type': 'pre_tool',
-            'tool_name': tool_name,
-            'operation_type': operation_type,
-            'tool_parameters': tool_params,
-            'session_id': event.get('session_id', ''),
-            'working_directory': working_dir,
-            'git_branch': git_branch,
-            'timestamp': datetime.now().isoformat(),
-            'parameter_count': len(tool_input) if isinstance(tool_input, dict) else 0,
-            'is_file_operation': tool_name in ['Write', 'Edit', 'MultiEdit', 'Read', 'LS', 'Glob'],
-            'is_execution': tool_name in ['Bash', 'NotebookEdit'],
-            'is_delegation': tool_name == 'Task',
-            'security_risk': self._assess_security_risk(tool_name, tool_input)
-        }
-        
-        # Add delegation-specific data if this is a Task tool
-        if tool_name == 'Task' and isinstance(tool_input, dict):
-            agent_type = tool_input.get('subagent_type', 'unknown')
-            pre_tool_data['delegation_details'] = {
-                'agent_type': agent_type,
-                'prompt': tool_input.get('prompt', ''),
-                'description': tool_input.get('description', ''),
-                'task_preview': (tool_input.get('prompt', '') or tool_input.get('description', ''))[:100]
-            }
-            
-            # Track this delegation for SubagentStop correlation
-            session_id = event.get('session_id', '')
-            if session_id and agent_type != 'unknown':
-                self._track_delegation(session_id, agent_type)
-            
-            # Trigger memory pre-delegation hook
-            self._trigger_memory_pre_delegation_hook(agent_type, tool_input, session_id)
-        
-        self._emit_socketio_event('/hook', 'pre_tool', pre_tool_data)
-    
-    def _handle_post_tool_fast(self, event):
-        """Handle post-tool use with comprehensive data capture.
-        
-        WHY comprehensive capture:
-        - Captures execution results and success/failure status
-        - Provides duration and performance metrics
-        - Enables pattern analysis of tool usage and success rates
-        """
-        tool_name = event.get('tool_name', '')
-        exit_code = event.get('exit_code', 0)
-        
-        # Extract result data
-        result_data = self._extract_tool_results(event)
-        
-        # Calculate duration if timestamps are available
-        duration = self._calculate_duration(event)
-        
-        # Get working directory and git branch
-        working_dir = event.get('cwd', '')
-        git_branch = self._get_git_branch(working_dir) if working_dir else 'Unknown'
-        
-        post_tool_data = {
-            'event_type': 'post_tool',
-            'tool_name': tool_name,
-            'exit_code': exit_code,
-            'success': exit_code == 0,
-            'status': 'success' if exit_code == 0 else 'blocked' if exit_code == 2 else 'error',
-            'duration_ms': duration,
-            'result_summary': result_data,
-            'session_id': event.get('session_id', ''),
-            'working_directory': working_dir,
-            'git_branch': git_branch,
-            'timestamp': datetime.now().isoformat(),
-            'has_output': bool(result_data.get('output')),
-            'has_error': bool(result_data.get('error')),
-            'output_size': len(str(result_data.get('output', ''))) if result_data.get('output') else 0
-        }
-        
-        # Handle Task delegation completion for memory hooks
-        if tool_name == 'Task':
-            session_id = event.get('session_id', '')
-            agent_type = self._get_delegation_agent_type(session_id)
-            self._trigger_memory_post_delegation_hook(agent_type, event, session_id)
-        
-        self._emit_socketio_event('/hook', 'post_tool', post_tool_data)
-    
-    def _extract_tool_parameters(self, tool_name: str, tool_input: dict) -> dict:
-        """Extract relevant parameters based on tool type.
-        
-        WHY tool-specific extraction:
-        - Different tools have different important parameters
-        - Provides meaningful context for dashboard display
-        - Enables tool-specific analysis and monitoring
-        """
-        if not isinstance(tool_input, dict):
-            return {'raw_input': str(tool_input)}
-        
-        # Common parameters across all tools
-        params = {
-            'input_type': type(tool_input).__name__,
-            'param_keys': list(tool_input.keys()) if tool_input else []
-        }
-        
-        # Tool-specific parameter extraction
-        if tool_name in ['Write', 'Edit', 'MultiEdit', 'Read', 'NotebookRead', 'NotebookEdit']:
-            params.update({
-                'file_path': tool_input.get('file_path') or tool_input.get('notebook_path'),
-                'content_length': len(str(tool_input.get('content', tool_input.get('new_string', '')))),
-                'is_create': tool_name == 'Write',
-                'is_edit': tool_name in ['Edit', 'MultiEdit', 'NotebookEdit']
-            })
-        elif tool_name == 'Bash':
-            command = tool_input.get('command', '')
-            params.update({
-                'command': command[:100],  # Truncate long commands
-                'command_length': len(command),
-                'has_pipe': '|' in command,
-                'has_redirect': '>' in command or '<' in command,
-                'timeout': tool_input.get('timeout')
-            })
-        elif tool_name in ['Grep', 'Glob']:
-            params.update({
-                'pattern': tool_input.get('pattern', ''),
-                'path': tool_input.get('path', ''),
-                'output_mode': tool_input.get('output_mode')
-            })
-        elif tool_name == 'WebFetch':
-            params.update({
-                'url': tool_input.get('url', ''),
-                'prompt': tool_input.get('prompt', '')[:50]  # Truncate prompt
-            })
-        elif tool_name == 'Task':
-            # Special handling for Task tool (agent delegations)
-            params.update({
-                'subagent_type': tool_input.get('subagent_type', 'unknown'),
-                'description': tool_input.get('description', ''),
-                'prompt': tool_input.get('prompt', ''),
-                'prompt_preview': tool_input.get('prompt', '')[:200] if tool_input.get('prompt') else '',
-                'is_pm_delegation': tool_input.get('subagent_type') == 'pm',
-                'is_research_delegation': tool_input.get('subagent_type') == 'research',
-                'is_engineer_delegation': tool_input.get('subagent_type') == 'engineer'
-            })
-        elif tool_name == 'TodoWrite':
-            # Special handling for TodoWrite tool (task management)
-            todos = tool_input.get('todos', [])
-            params.update({
-                'todo_count': len(todos),
-                'todos': todos,  # Full todo list
-                'todo_summary': self._summarize_todos(todos),
-                'has_in_progress': any(t.get('status') == 'in_progress' for t in todos),
-                'has_pending': any(t.get('status') == 'pending' for t in todos),
-                'has_completed': any(t.get('status') == 'completed' for t in todos),
-                'priorities': list(set(t.get('priority', 'medium') for t in todos))
-            })
-        
-        return params
-    
-    def _summarize_todos(self, todos: list) -> dict:
-        """Create a summary of the todo list for quick understanding."""
-        if not todos:
-            return {'total': 0, 'summary': 'Empty todo list'}
-        
-        status_counts = {'pending': 0, 'in_progress': 0, 'completed': 0}
-        priority_counts = {'high': 0, 'medium': 0, 'low': 0}
-        
-        for todo in todos:
-            status = todo.get('status', 'pending')
-            priority = todo.get('priority', 'medium')
-            
-            if status in status_counts:
-                status_counts[status] += 1
-            if priority in priority_counts:
-                priority_counts[priority] += 1
-        
-        # Create a text summary
-        summary_parts = []
-        if status_counts['completed'] > 0:
-            summary_parts.append(f"{status_counts['completed']} completed")
-        if status_counts['in_progress'] > 0:
-            summary_parts.append(f"{status_counts['in_progress']} in progress")
-        if status_counts['pending'] > 0:
-            summary_parts.append(f"{status_counts['pending']} pending")
-        
-        return {
-            'total': len(todos),
-            'status_counts': status_counts,
-            'priority_counts': priority_counts,
-            'summary': ', '.join(summary_parts) if summary_parts else 'No tasks'
-        }
-    
-    def _classify_tool_operation(self, tool_name: str, tool_input: dict) -> str:
-        """Classify the type of operation being performed."""
-        if tool_name in ['Read', 'LS', 'Glob', 'Grep', 'NotebookRead']:
-            return 'read'
-        elif tool_name in ['Write', 'Edit', 'MultiEdit', 'NotebookEdit']:
-            return 'write'
-        elif tool_name == 'Bash':
-            return 'execute'
-        elif tool_name in ['WebFetch', 'WebSearch']:
-            return 'network'
-        elif tool_name == 'TodoWrite':
-            return 'task_management'
-        elif tool_name == 'Task':
-            return 'delegation'
-        else:
-            return 'other'
-    
-    def _assess_security_risk(self, tool_name: str, tool_input: dict) -> str:
-        """Assess the security risk level of the tool operation."""
-        if tool_name == 'Bash':
-            command = tool_input.get('command', '').lower()
-            # Check for potentially dangerous commands
-            dangerous_patterns = ['rm -rf', 'sudo', 'chmod 777', 'curl', 'wget', '> /etc/', 'dd if=']
-            if any(pattern in command for pattern in dangerous_patterns):
-                return 'high'
-            elif any(word in command for word in ['install', 'delete', 'format', 'kill']):
-                return 'medium'
-            else:
-                return 'low'
-        elif tool_name in ['Write', 'Edit', 'MultiEdit']:
-            file_path = tool_input.get('file_path', '')
-            # Check for system file modifications
-            if any(path in file_path for path in ['/etc/', '/usr/', '/var/', '/sys/']):
-                return 'high'
-            elif file_path.startswith('/'):
-                return 'medium'
-            else:
-                return 'low'
-        else:
-            return 'low'
-    
-    def _extract_tool_results(self, event: dict) -> dict:
-        """Extract and summarize tool execution results."""
-        result = {
-            'exit_code': event.get('exit_code', 0),
-            'has_output': False,
-            'has_error': False
-        }
-        
-        # Extract output if available
-        if 'output' in event:
-            output = str(event['output'])
-            result.update({
-                'has_output': bool(output.strip()),
-                'output_preview': output[:200] if len(output) > 200 else output,
-                'output_lines': len(output.split('\n')) if output else 0
-            })
-        
-        # Extract error information
-        if 'error' in event or event.get('exit_code', 0) != 0:
-            error = str(event.get('error', ''))
-            result.update({
-                'has_error': True,
-                'error_preview': error[:200] if len(error) > 200 else error
-            })
-        
-        return result
-    
-    def _calculate_duration(self, event: dict) -> int:
-        """Calculate operation duration in milliseconds if timestamps are available."""
-        # This would require start/end timestamps from Claude Code
-        # For now, return None as we don't have this data
+                    print(f"Error handling {hook_type}: {e}", file=sys.stderr)
+            finally:
+                # Calculate duration
+                duration_ms = int((time.time() - start_time) * 1000)
+
+                # Emit hook execution event
+                self._emit_hook_execution_event(
+                    hook_type=hook_type,
+                    event=event,
+                    success=success,
+                    duration_ms=duration_ms,
+                    error_message=error_message,
+                )
+
+            return return_value
+
         return None
-    
-    def _handle_notification_fast(self, event):
-        """Handle notification events from Claude.
-        
-        WHY enhanced notification capture:
-        - Provides visibility into Claude's status and communication flow
-        - Captures notification type, content, and context for monitoring
-        - Enables pattern analysis of Claude's notification behavior
-        - Useful for debugging communication issues and user experience
+
+    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, modified_input: Optional[dict] = None) -> None:
         """
-        notification_type = event.get('notification_type', 'unknown')
-        message = event.get('message', '')
-        
-        # Get working directory and git branch
-        working_dir = event.get('cwd', '')
-        git_branch = self._get_git_branch(working_dir) if working_dir else 'Unknown'
-        
-        notification_data = {
-            'event_type': 'notification',
-            'notification_type': notification_type,
-            'message': message,
-            'message_preview': message[:200] if len(message) > 200 else message,
-            'message_length': len(message),
-            'session_id': event.get('session_id', ''),
-            'working_directory': working_dir,
-            'git_branch': git_branch,
-            'timestamp': datetime.now().isoformat(),
-            'is_user_input_request': 'input' in message.lower() or 'waiting' in message.lower(),
-            'is_error_notification': 'error' in message.lower() or 'failed' in message.lower(),
-            'is_status_update': any(word in message.lower() for word in ['processing', 'analyzing', 'working', 'thinking'])
-        }
-        
-        # Emit to /hook namespace
-        self._emit_socketio_event('/hook', 'notification', notification_data)
-    
-    def _handle_stop_fast(self, event):
-        """Handle stop events when Claude processing stops.
-        
-        WHY comprehensive stop capture:
-        - Provides visibility into Claude's session lifecycle
-        - Captures stop reason and context for analysis
-        - Enables tracking of session completion patterns
-        - Useful for understanding when and why Claude stops responding
+        Send continue action to Claude with optional input modification.
+
+        WHY: Centralized response ensures consistent format
+        and makes it easier to add response modifications.
+
+        Args:
+            modified_input: Modified tool parameters for PreToolUse hooks (v2.0.30+)
         """
-        reason = event.get('reason', 'unknown')
-        stop_type = event.get('stop_type', 'normal')
-        
-        # Get working directory and git branch
-        working_dir = event.get('cwd', '')
-        git_branch = self._get_git_branch(working_dir) if working_dir else 'Unknown'
-        
-        stop_data = {
-            'event_type': 'stop',
-            'reason': reason,
-            'stop_type': stop_type,
-            'session_id': event.get('session_id', ''),
-            'working_directory': working_dir,
-            'git_branch': git_branch,
-            'timestamp': datetime.now().isoformat(),
-            'is_user_initiated': reason in ['user_stop', 'user_cancel', 'interrupt'],
-            'is_error_stop': reason in ['error', 'timeout', 'failed'],
-            'is_completion_stop': reason in ['completed', 'finished', 'done'],
-            'has_output': bool(event.get('final_output'))
-        }
-        
-        # Emit to /hook namespace
-        self._emit_socketio_event('/hook', 'stop', stop_data)
-    
-    def _handle_subagent_stop_fast(self, event):
-        """Handle subagent stop events when subagent processing stops.
-        
-        WHY comprehensive subagent stop capture:
-        - Provides visibility into subagent lifecycle and delegation patterns
-        - Captures agent type, ID, reason, and results for analysis
-        - Enables tracking of delegation success/failure patterns
-        - Useful for understanding subagent performance and reliability
+        if modified_input is not None:
+            # Claude Code v2.0.30+ supports modifying PreToolUse tool inputs
+            print(json.dumps({"action": "continue", "tool_input": modified_input}))
+        else:
+            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 _get_event_key(self, event: dict) -> str:
+        """Generate event key through duplicate detector (backward compatibility)."""
+        return self.duplicate_detector.generate_event_key(event)
+
+    def _emit_hook_execution_event(
+        self,
+        hook_type: str,
+        event: dict,
+        success: bool,
+        duration_ms: int,
+        error_message: Optional[str] = None,
+    ):
+        """Emit a structured JSON event for hook execution.
+
+        This emits a normalized event following the claude_event schema to provide
+        visibility into hook processing, timing, and success/failure status.
+
+        Args:
+            hook_type: The type of hook that executed (e.g., "UserPromptSubmit", "PreToolUse")
+            event: The original hook event data
+            success: Whether the hook executed successfully
+            duration_ms: How long the hook took to execute in milliseconds
+            error_message: Optional error message if the hook failed
         """
-        # First try to get agent type from our tracking
-        session_id = event.get('session_id', '')
-        agent_type = self._get_delegation_agent_type(session_id) if session_id else 'unknown'
-        
-        # Fall back to event data if tracking didn't have it
-        if agent_type == 'unknown':
-            agent_type = event.get('agent_type', event.get('subagent_type', 'unknown'))
-        
-        agent_id = event.get('agent_id', event.get('subagent_id', ''))
-        reason = event.get('reason', event.get('stop_reason', 'unknown'))
-        
-        # Try to infer agent type from other fields if still unknown
-        if agent_type == 'unknown' and 'task' in event:
-            task_desc = str(event.get('task', '')).lower()
-            if 'research' in task_desc:
-                agent_type = 'research'
-            elif 'engineer' in task_desc or 'code' in task_desc:
-                agent_type = 'engineer'
-            elif 'pm' in task_desc or 'project' in task_desc:
-                agent_type = 'pm'
-        
-        # Get working directory and git branch
-        working_dir = event.get('cwd', '')
-        git_branch = self._get_git_branch(working_dir) if working_dir else 'Unknown'
-        
-        subagent_stop_data = {
-            'event_type': 'subagent_stop',
-            'agent_type': agent_type,
-            'agent_id': agent_id,
-            'reason': reason,
-            'session_id': event.get('session_id', ''),
-            'working_directory': working_dir,
-            'git_branch': git_branch,
-            'timestamp': datetime.now().isoformat(),
-            'is_successful_completion': reason in ['completed', 'finished', 'done'],
-            'is_error_termination': reason in ['error', 'timeout', 'failed', 'blocked'],
-            'is_delegation_related': agent_type in ['research', 'engineer', 'pm', 'ops'],
-            'has_results': bool(event.get('results') or event.get('output')),
-            'duration_context': event.get('duration_ms')
+        # Generate a human-readable summary based on hook type
+        summary = self._generate_hook_summary(hook_type, event, success)
+
+        # Extract common fields
+        session_id = event.get("session_id", "")
+        working_dir = event.get("cwd", "")
+
+        # Build hook execution data
+        hook_data = {
+            "hook_name": hook_type,
+            "hook_type": hook_type,
+            "session_id": session_id,
+            "working_directory": working_dir,
+            "success": success,
+            "duration_ms": duration_ms,
+            "result_summary": summary,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
         }
-        
-        # Debug log the raw event data
+
+        # Add error information if present
+        if error_message:
+            hook_data["error_message"] = error_message
+
+        # Add hook-specific context
+        if hook_type == "PreToolUse":
+            hook_data["tool_name"] = event.get("tool_name", "")
+        elif hook_type == "PostToolUse":
+            hook_data["tool_name"] = event.get("tool_name", "")
+            hook_data["exit_code"] = event.get("exit_code", 0)
+        elif hook_type == "UserPromptSubmit":
+            prompt = event.get("prompt", "")
+            hook_data["prompt_preview"] = prompt[:100] if len(prompt) > 100 else prompt
+            hook_data["prompt_length"] = len(prompt)
+        elif hook_type == "SubagentStop":
+            hook_data["agent_type"] = event.get("agent_type", "unknown")
+            hook_data["reason"] = event.get("reason", "unknown")
+
+        # Emit through connection manager with proper structure
+        # This uses the existing event infrastructure
+        self._emit_socketio_event("", "hook_execution", hook_data)
+
         if DEBUG:
-            print(f"SubagentStop raw event data: {json.dumps(event, indent=2)}", file=sys.stderr)
-        
-        # Emit to /hook namespace
-        self._emit_socketio_event('/hook', 'subagent_stop', subagent_stop_data)
-    
-    def _trigger_memory_pre_delegation_hook(self, agent_type: str, tool_input: dict, session_id: str):
-        """Trigger memory pre-delegation hook for agent memory injection.
-        
-        WHY: This connects Claude Code's Task delegation events to our memory system.
-        When Claude is about to delegate to an agent, we inject the agent's memory
-        into the delegation context so the agent has access to accumulated knowledge.
-        
-        DESIGN DECISION: We modify the tool_input in place to inject memory context.
-        This ensures the agent receives the memory as part of their initial context.
-        """
-        if not self.memory_hooks_initialized or not self.pre_delegation_hook:
-            return
-        
-        try:
-            # Create hook context for memory injection
-            hook_context = HookContext(
-                hook_type=HookType.PRE_DELEGATION,
-                data={
-                    'agent': agent_type,
-                    'context': tool_input,
-                    'session_id': session_id
-                },
-                metadata={
-                    'source': 'claude_hook_handler',
-                    'tool_name': 'Task'
-                },
-                timestamp=datetime.now().isoformat(),
-                session_id=session_id
+            print(
+                f"📊 Hook execution event: {hook_type} - {duration_ms}ms - {'✅' if success else '❌'}",
+                file=sys.stderr,
             )
-            
-            # Execute pre-delegation hook
-            result = self.pre_delegation_hook.execute(hook_context)
-            
-            if result.success and result.modified and result.data:
-                # Update tool_input with memory-enhanced context
-                enhanced_context = result.data.get('context', {})
-                if enhanced_context and 'agent_memory' in enhanced_context:
-                    # Inject memory into the task prompt/description
-                    original_prompt = tool_input.get('prompt', '')
-                    memory_section = enhanced_context['agent_memory']
-                    
-                    # Prepend memory to the original prompt
-                    enhanced_prompt = f"{memory_section}\n\n{original_prompt}"
-                    tool_input['prompt'] = enhanced_prompt
-                    
-                    if DEBUG:
-                        memory_size = len(memory_section.encode('utf-8'))
-                        print(f"✅ Injected {memory_size} bytes of memory for agent '{agent_type}'", file=sys.stderr)
-            
-        except Exception as e:
-            if DEBUG:
-                print(f"❌ Memory pre-delegation hook failed: {e}", file=sys.stderr)
-            # Don't fail the delegation - memory is optional
-    
-    def _trigger_memory_post_delegation_hook(self, agent_type: str, event: dict, session_id: str):
-        """Trigger memory post-delegation hook for learning extraction.
-        
-        WHY: This connects Claude Code's Task completion events to our memory system.
-        When an agent completes a task, we extract learnings from the result and
-        store them in the agent's memory for future use.
-        
-        DESIGN DECISION: We extract learnings from both the tool output and any
-        error messages, providing comprehensive context for the memory system.
+
+    def _generate_hook_summary(self, hook_type: str, event: dict, success: bool) -> str:
+        """Generate a human-readable summary of what the hook did.
+
+        Args:
+            hook_type: The type of hook
+            event: The hook event data
+            success: Whether the hook executed successfully
+
+        Returns:
+            A brief description of what happened
         """
-        if not self.memory_hooks_initialized or not self.post_delegation_hook:
-            return
-        
-        try:
-            # Extract result content from the event
-            result_content = ""
-            output = event.get('output', '')
-            error = event.get('error', '')
-            exit_code = event.get('exit_code', 0)
-            
-            # Build result content
-            if output:
-                result_content = str(output)
-            elif error:
-                result_content = f"Error: {str(error)}"
-            else:
-                result_content = f"Task completed with exit code: {exit_code}"
-            
-            # Create hook context for learning extraction
-            hook_context = HookContext(
-                hook_type=HookType.POST_DELEGATION,
-                data={
-                    'agent': agent_type,
-                    'result': {
-                        'content': result_content,
-                        'success': exit_code == 0,
-                        'exit_code': exit_code
-                    },
-                    'session_id': session_id
-                },
-                metadata={
-                    'source': 'claude_hook_handler',
-                    'tool_name': 'Task',
-                    'duration_ms': event.get('duration_ms', 0)
-                },
-                timestamp=datetime.now().isoformat(),
-                session_id=session_id
-            )
-            
-            # Execute post-delegation hook
-            result = self.post_delegation_hook.execute(hook_context)
-            
-            if result.success and result.metadata:
-                learnings_extracted = result.metadata.get('learnings_extracted', 0)
-                if learnings_extracted > 0 and DEBUG:
-                    print(f"✅ Extracted {learnings_extracted} learnings for agent '{agent_type}'", file=sys.stderr)
-            
-        except Exception as e:
-            if DEBUG:
-                print(f"❌ Memory post-delegation hook failed: {e}", file=sys.stderr)
-            # Don't fail the delegation result - memory is optional
-    
+        if not success:
+            return f"Hook {hook_type} failed during processing"
+
+        # Generate hook-specific summaries
+        if hook_type == "UserPromptSubmit":
+            prompt = event.get("prompt", "")
+            if prompt.startswith("/"):
+                return f"Processed command: {prompt.split()[0]}"
+            return f"Processed user prompt ({len(prompt)} chars)"
+
+        if hook_type == "PreToolUse":
+            tool_name = event.get("tool_name", "unknown")
+            return f"Pre-processing tool call: {tool_name}"
+
+        if hook_type == "PostToolUse":
+            tool_name = event.get("tool_name", "unknown")
+            exit_code = event.get("exit_code", 0)
+            status = "success" if exit_code == 0 else "failed"
+            return f"Completed tool call: {tool_name} ({status})"
+
+        if hook_type == "SubagentStop":
+            agent_type = event.get("agent_type", "unknown")
+            reason = event.get("reason", "unknown")
+            return f"Subagent {agent_type} stopped: {reason}"
+
+        if hook_type == "SessionStart":
+            return "New session started"
+
+        if hook_type == "Stop":
+            reason = event.get("reason", "unknown")
+            return f"Session stopped: {reason}"
+
+        if hook_type == "Notification":
+            notification_type = event.get("notification_type", "unknown")
+            return f"Notification received: {notification_type}"
+
+        if hook_type == "AssistantResponse":
+            response_len = len(event.get("response", ""))
+            return f"Assistant response generated ({response_len} chars)"
+
+        # Default summary
+        return f"Hook {hook_type} processed successfully"
+
     def __del__(self):
-        """Cleanup Socket.IO client on handler destruction."""
-        if self.sio_client and self.sio_connected:
+        """Cleanup on handler destruction."""
+        # Clean up connection manager if it exists
+        if hasattr(self, "connection_manager") and self.connection_manager:
             try:
-                self.sio_client.disconnect()
-            except:
-                pass
+                self.connection_manager.cleanup()
+            except Exception:
+                pass  # Ignore cleanup errors during destruction
 
 
 def main():
-    """Entry point with comprehensive error handling."""
+    """Entry point with singleton pattern and proper cleanup."""
+    global _global_handler
+    _continue_printed = False  # Track if we've already printed continue
+
+    # Check Claude Code version compatibility first
+    is_compatible, version = check_claude_version()
+    if not is_compatible:
+        # Version incompatible - just continue without processing
+        # This prevents errors on older Claude Code versions
+        if DEBUG and version:
+            print(
+                f"Skipping hook processing due to version incompatibility ({version})",
+                file=sys.stderr,
+            )
+        print(json.dumps({"action": "continue"}))
+        sys.exit(0)
+
+    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:
-        handler = ClaudeHookHandler()
+        # 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:
-        # Always output continue action to not block Claude
-        print(json.dumps({"action": "continue"}))
+        # 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)
@@ -934,4 +711,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()