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

claude_mpm/hooks/claude_hooks/hook_handler.py

@@ -1,4 +1,32 @@
 #!/usr/bin/env python3
+# ==============================================================================
+# CRITICAL: EARLY LOGGING SUPPRESSION - MUST BE FIRST
+# ==============================================================================
+# Suppress ALL logging before any other imports to prevent REPL pollution.
+# The StreamingHandler in logger.py writes carriage returns (\r) and spaces
+# to stderr which pollutes Claude Code's REPL output.
+#
+# This MUST be before any imports that could trigger module-level loggers.
+# ==============================================================================
+import logging as _early_logging
+import sys as _early_sys
+
+# Force redirect all logging to NullHandler before any module imports
+# This prevents ANY log output from polluting stdout/stderr during hook execution
+_early_logging.basicConfig(handlers=[_early_logging.NullHandler()], force=True)
+# Also ensure root logger has no handlers that write to stderr
+_early_logging.getLogger().handlers = [_early_logging.NullHandler()]
+# Suppress all loggers by setting a very high level initially
+_early_logging.getLogger().setLevel(_early_logging.CRITICAL + 1)
+
+# Clean up namespace to avoid polluting module scope
+del _early_logging
+del _early_sys
+
+# ==============================================================================
+# END EARLY LOGGING SUPPRESSION
+# ==============================================================================
+
 """Refactored Claude Code hook handler with modular service architecture.
 
 This handler uses a service-oriented architecture with:
@@ -17,12 +45,18 @@ NOTE: Requires Claude Code version 1.0.92 or higher for proper hook support.
 Earlier versions do not support matcher-based hook configuration.
 """
 
+# Suppress RuntimeWarning from frozen runpy (prevents REPL pollution in Claude Code)
+# Must be before other imports to suppress warnings during import
+import warnings
+
+warnings.filterwarnings("ignore", category=RuntimeWarning)
+
 import json
 import os
 import re
 import select
 import signal
-import subprocess
+import subprocess  # nosec B404
 import sys
 import threading
 from datetime import datetime, timezone
@@ -31,12 +65,14 @@ from typing import Optional, Tuple
 # Import extracted modules with fallback for direct execution
 try:
     # Try relative imports first (when imported as module)
+    from .auto_pause_handler import AutoPauseHandler
     from .event_handlers import EventHandlers
     from .memory_integration import MemoryHookManager
     from .response_tracking import ResponseTrackingManager
     from .services import (
         ConnectionManagerService,
         DuplicateEventDetector,
+        HookServiceContainer,
         StateManagerService,
         SubagentResponseProcessor,
     )
@@ -47,27 +83,61 @@ except ImportError:
     # Add parent directory to path
     sys.path.insert(0, str(Path(__file__).parent))
 
+    from auto_pause_handler import AutoPauseHandler
     from event_handlers import EventHandlers
     from memory_integration import MemoryHookManager
     from response_tracking import ResponseTrackingManager
     from services import (
         ConnectionManagerService,
         DuplicateEventDetector,
+        HookServiceContainer,
         StateManagerService,
         SubagentResponseProcessor,
     )
 
+# Import CorrelationManager with fallback (used in _route_event cleanup)
+# WHY at top level: Runtime relative imports fail with "no known parent package" error
+try:
+    from .correlation_manager import CorrelationManager
+except ImportError:
+    try:
+        from correlation_manager import CorrelationManager
+    except ImportError:
+        # Fallback: create a no-op class if module unavailable
+        class CorrelationManager:
+            @staticmethod
+            def cleanup_old():
+                pass
+
+
 """
 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.
+WHY disabled by default: Production users should see clean output without debug noise.
+Hook errors appear less confusing when debug output is minimal.
+Development and debugging can enable via CLAUDE_MPM_HOOK_DEBUG=true.
 
 Performance Impact: Debug logging adds ~5-10% overhead but provides crucial
-visibility into event flow, timing, and error conditions.
+visibility into event flow, timing, and error conditions when enabled.
 """
-DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "false").lower() == "true"
+
+
+def _log(message: str) -> None:
+    """Log message to file if DEBUG enabled. Never write to stderr.
+
+    WHY: Claude Code interprets ANY stderr output as a hook error.
+    Writing to stderr causes confusing "hook error" messages even for debug logs.
+
+    This helper ensures all debug output goes to a log file instead.
+    """
+    if DEBUG:
+        try:
+            with open("/tmp/claude-mpm-hook.log", "a") as f:  # nosec B108
+                f.write(f"[{datetime.now(timezone.utc).isoformat()}] {message}\n")
+        except Exception:  # nosec B110 - intentional silent failure
+            pass  # Never disrupt hook execution
+
 
 """
 Conditional imports with graceful fallbacks for testing and modularity.
@@ -109,6 +179,8 @@ WHY version checking:
 Security: Version checking prevents execution on incompatible environments.
 """
 MIN_CLAUDE_VERSION = "1.0.92"
+# Minimum version for user-invocable skills support
+MIN_SKILLS_VERSION = "2.1.3"
 
 
 def check_claude_version() -> Tuple[bool, Optional[str]]:
@@ -153,7 +225,7 @@ def check_claude_version() -> Tuple[bool, Optional[str]]:
     """
     try:
         # Try to detect Claude Code version
-        result = subprocess.run(
+        result = subprocess.run(  # nosec B603 B607 - Safe: hardcoded claude CLI with --version flag, no user input
             ["claude", "--version"],
             capture_output=True,
             text=True,
@@ -184,22 +256,17 @@ def check_claude_version() -> Tuple[bool, Optional[str]]:
                     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,
-                            )
+                        _log(
+                            f"⚠️  Claude Code {version} does not support matcher-based hooks "
+                            f"(requires {MIN_CLAUDE_VERSION}+). Hook monitoring disabled."
+                        )
                         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
-            )
+        _log(f"Warning: Could not detect Claude Code version: {e}")
 
     return False, None
 
@@ -212,26 +279,73 @@ class ClaudeHookHandler:
     - Each service handles a specific responsibility
     - Easier to test, maintain, and extend
     - Reduced complexity in main handler class
+
+    Supports Dependency Injection:
+    - Pass a HookServiceContainer to override default services
+    - Useful for testing with mock services
+    - Maintains backward compatibility when no container is provided
     """
 
-    def __init__(self):
-        # Initialize services
-        self.state_manager = StateManagerService()
-        self.connection_manager = ConnectionManagerService()
-        self.duplicate_detector = DuplicateEventDetector()
+    def __init__(self, container: Optional[HookServiceContainer] = None):
+        """Initialize hook handler with optional DI container.
 
-        # Initialize extracted managers
-        self.memory_hook_manager = MemoryHookManager()
-        self.response_tracking_manager = ResponseTrackingManager()
-        self.event_handlers = EventHandlers(self)
+        Args:
+            container: Optional HookServiceContainer for dependency injection.
+                      If None, services are created directly (backward compatible).
+        """
+        # Use container if provided, otherwise create services directly
+        if container is not None:
+            # DI mode: get services from container
+            self._container = container
+            self.state_manager = container.get_state_manager()
+            self.connection_manager = container.get_connection_manager()
+            self.duplicate_detector = container.get_duplicate_detector()
+            self.memory_hook_manager = container.get_memory_hook_manager()
+            self.response_tracking_manager = container.get_response_tracking_manager()
+            self.auto_pause_handler = container.get_auto_pause_handler()
+
+            # Event handlers need reference to this handler (circular, but contained)
+            self.event_handlers = EventHandlers(self)
+
+            # Subagent processor with injected dependencies
+            self.subagent_processor = container.get_subagent_processor(
+                self.state_manager,
+                self.response_tracking_manager,
+                self.connection_manager,
+            )
+        else:
+            # Backward compatible mode: create services directly
+            self._container = None
+            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,
+            )
 
-        # Initialize subagent processor with dependencies
-        self.subagent_processor = SubagentResponseProcessor(
-            self.state_manager, self.response_tracking_manager, self.connection_manager
-        )
+            # Initialize auto-pause handler
+            try:
+                self.auto_pause_handler = AutoPauseHandler()
+            except Exception as e:
+                self.auto_pause_handler = None
+                _log(f"Auto-pause initialization failed: {e}")
+
+        # Link auto-pause handler to response tracking manager
+        if self.auto_pause_handler and hasattr(self, "response_tracking_manager"):
+            self.response_tracking_manager.auto_pause_handler = self.auto_pause_handler
 
         # Backward compatibility properties for tests
-        self.connection_pool = self.connection_manager.connection_pool
+        # Note: HTTP-based connection manager doesn't use connection_pool
+        self.connection_pool = None  # Deprecated: No longer needed with HTTP emission
 
         # Expose state manager properties for backward compatibility
         self.active_delegations = self.state_manager.active_delegations
@@ -260,8 +374,7 @@ class ClaudeHookHandler:
         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)
+            _log(f"Hook handler timeout (pid: {os.getpid()})")
             if not _continue_sent:
                 self._continue_execution()
                 _continue_sent = True
@@ -282,11 +395,9 @@ class ClaudeHookHandler:
 
             # Check for duplicate events (same event within 100ms)
             if self.duplicate_detector.is_duplicate(event):
-                if DEBUG:
-                    print(
-                        f"[{datetime.now(timezone.utc).isoformat()}] Skipping duplicate event: {event.get('hook_event_name', 'unknown')} (PID: {os.getpid()})",
-                        file=sys.stderr,
-                    )
+                _log(
+                    f"[{datetime.now(timezone.utc).isoformat()}] Skipping duplicate event: {event.get('hook_event_name', 'unknown')} (PID: {os.getpid()})"
+                )
                 # Still need to output continue for this invocation
                 if not _continue_sent:
                     self._continue_execution()
@@ -294,25 +405,19 @@ class ClaudeHookHandler:
                 return
 
             # Debug: Log that we're processing an event
-            if DEBUG:
-                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,
-                )
+            hook_type = event.get("hook_event_name", "unknown")
+            _log(
+                f"\n[{datetime.now(timezone.utc).isoformat()}] Processing hook event: {hook_type} (PID: {os.getpid()})"
+            )
 
             # 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,
-                    )
+                _log(
+                    f"🧹 Performed cleanup after {self.state_manager.events_processed} events"
+                )
 
             # Route event to appropriate handler
             # Handlers can optionally return modified input for PreToolUse events
@@ -352,8 +457,7 @@ class ClaudeHookHandler:
             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)
+                _log("No hook event data received within timeout")
                 return None
 
             # Data is available, read it
@@ -364,21 +468,16 @@ class ClaudeHookHandler:
 
             parsed = json.loads(event_data)
             # Debug: Log the actual event format we receive
-            if DEBUG:
-                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)
+            _log(f"Received event with keys: {list(parsed.keys())}")
+            for key in ["hook_event_name", "event", "type", "event_type"]:
+                if key in parsed:
+                    _log(f"  {key} = '{parsed[key]}'")
             return parsed
         except (json.JSONDecodeError, ValueError) as e:
-            if DEBUG:
-                print(f"Failed to parse hook event: {e}", file=sys.stderr)
+            _log(f"Failed to parse hook event: {e}")
             return None
         except Exception as e:
-            if DEBUG:
-                print(f"Error reading hook event: {e}", file=sys.stderr)
+            _log(f"Error reading hook event: {e}")
             return None
 
     def _route_event(self, event: dict) -> Optional[dict]:
@@ -407,9 +506,9 @@ class ClaudeHookHandler:
         )
 
         # 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)
+        if hook_type == "unknown":
+            _log(f"Unknown event format, keys: {list(event.keys())}")
+            _log(f"Event sample: {str(event)[:200]}")
 
         # Map event types to handlers
         event_handlers = {
@@ -419,7 +518,7 @@ class ClaudeHookHandler:
             "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,
+            "SubagentStart": self.event_handlers.handle_subagent_start_fast,
             "SessionStart": self.event_handlers.handle_session_start_fast,
             "AssistantResponse": self.event_handlers.handle_assistant_response,
         }
@@ -445,8 +544,7 @@ class ClaudeHookHandler:
             except Exception as e:
                 error_message = str(e)
                 return_value = None
-                if DEBUG:
-                    print(f"Error handling {hook_type}: {e}", file=sys.stderr)
+                _log(f"Error handling {hook_type}: {e}")
             finally:
                 # Calculate duration
                 duration_ms = int((time.time() - start_time) * 1000)
@@ -480,9 +578,12 @@ class ClaudeHookHandler:
         """
         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}))
+            print(
+                json.dumps({"continue": True, "tool_input": modified_input}),
+                flush=True,
+            )
         else:
-            print(json.dumps({"action": "continue"}))
+            print(json.dumps({"continue": True}), flush=True)
 
     # Delegation methods for compatibility with event_handlers
     def _track_delegation(self, session_id: str, agent_type: str, request_data=None):
@@ -535,13 +636,15 @@ class ClaudeHookHandler:
         # Build hook execution data
         hook_data = {
             "hook_name": hook_type,
-            "hook_type": hook_type,
+            "hook_type": hook_type,  # Actual hook type (PreToolUse, UserPromptSubmit, etc.)
+            "hook_event_type": hook_type,  # Additional field for clarity
             "session_id": session_id,
             "working_directory": working_dir,
             "success": success,
             "duration_ms": duration_ms,
             "result_summary": summary,
             "timestamp": datetime.now(timezone.utc).isoformat(),
+            "source": "claude_hook_handler",  # Explicit source identification
         }
 
         # Add error information if present
@@ -566,11 +669,9 @@ class ClaudeHookHandler:
         # This uses the existing event infrastructure
         self._emit_socketio_event("", "hook_execution", hook_data)
 
-        if DEBUG:
-            print(
-                f"📊 Hook execution event: {hook_type} - {duration_ms}ms - {'✅' if success else '❌'}",
-                file=sys.stderr,
-            )
+        _log(
+            f"📊 Hook execution event: {hook_type} - {duration_ms}ms - {'✅' if success else '❌'}"
+        )
 
     def _generate_hook_summary(self, hook_type: str, event: dict, success: bool) -> str:
         """Generate a human-readable summary of what the hook did.
@@ -628,12 +729,19 @@ class ClaudeHookHandler:
 
     def __del__(self):
         """Cleanup on handler destruction."""
+        # Finalize any active auto-pause session
+        if hasattr(self, "auto_pause_handler") and self.auto_pause_handler:
+            try:
+                self.auto_pause_handler.on_session_end()
+            except Exception:
+                pass  # nosec B110 - Intentionally ignore cleanup errors during handler destruction
+
         # Clean up connection manager if it exists
         if hasattr(self, "connection_manager") and self.connection_manager:
             try:
                 self.connection_manager.cleanup()
             except Exception:
-                pass  # Ignore cleanup errors during destruction
+                pass  # nosec B110 - Intentionally ignore cleanup errors during handler destruction
 
 
 def main():
@@ -646,25 +754,18 @@ def main():
     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"}))
+        if version:
+            _log(f"Skipping hook processing due to version incompatibility ({version})")
+        print(json.dumps({"continue": True}), flush=True)
         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,
-            )
+        _log(f"Hook handler cleanup (pid: {os.getpid()}, signal: {signum})")
         # 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"}))
+            print(json.dumps({"continue": True}), flush=True)
             _continue_printed = True
             sys.exit(0)
 
@@ -678,15 +779,10 @@ def main():
         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,
+                _log(f"✅ Created new ClaudeHookHandler singleton (pid: {os.getpid()})")
+            else:
+                _log(
+                    f"♻️ Reusing existing ClaudeHookHandler singleton (pid: {os.getpid()})"
                 )
 
             handler = _global_handler
@@ -702,13 +798,17 @@ def main():
     except Exception as e:
         # Only output continue if not already printed
         if not _continue_printed:
-            print(json.dumps({"action": "continue"}))
+            print(json.dumps({"continue": True}), flush=True)
             _continue_printed = True
         # Log error for debugging
-        if DEBUG:
-            print(f"Hook handler error: {e}", file=sys.stderr)
+        _log(f"Hook handler error: {e}")
         sys.exit(0)  # Exit cleanly even on error
 
 
 if __name__ == "__main__":
-    main()
+    try:
+        main()
+    except Exception:
+        # Catastrophic failure (import error, etc.) - always output valid JSON
+        print(json.dumps({"continue": True}), flush=True)
+        sys.exit(0)

claude_mpm/hooks/claude_hooks/hook_wrapper.sh

@@ -48,15 +48,10 @@ echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] PYTHONPATH: $PYTHONPATH" >> /tmp/hook
 echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Running: $PYTHON_CMD -m claude_mpm.hooks.claude_hooks.hook_handler" >> /tmp/hook-wrapper.log
 echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] SOCKETIO_PORT: $CLAUDE_MPM_SOCKETIO_PORT" >> /tmp/hook-wrapper.log
 
-# Run the Python hook handler as a module with error handling
-# Use exec to replace the shell process, but wrap in error handling
-if ! "$PYTHON_CMD" -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/hook-error.log; then
-    # If the Python handler fails, always return continue to not block Claude
-    echo '{"action": "continue"}'
-    # Log the error for debugging
-    echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Hook handler failed, see /tmp/hook-error.log" >> /tmp/hook-wrapper.log
-    exit 0
-fi
+# Run the Python hook handler as a module
+# Python handler is responsible for ALL stdout output (including error fallback)
+# Redirect stderr to log file for debugging
+"$PYTHON_CMD" -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/hook-error.log
 
-# Success - Python handler already printed continue, just exit
-exit 0
+# Exit with Python's exit code (should always be 0)
+exit $?