claude-mpm 5.6.23__py3-none-any.whl → 5.6.73__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,6 +45,12 @@ 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
@@ -38,6 +72,7 @@ try:
     from .services import (
         ConnectionManagerService,
         DuplicateEventDetector,
+        HookServiceContainer,
         StateManagerService,
         SubagentResponseProcessor,
     )
@@ -55,10 +90,26 @@ except ImportError:
     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.
 
@@ -228,35 +279,69 @@ 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}")
 
-        # Initialize auto-pause handler
-        try:
-            self.auto_pause_handler = AutoPauseHandler()
-            # Pass reference to ResponseTrackingManager so it can call auto_pause
-            if hasattr(self, "response_tracking_manager"):
-                self.response_tracking_manager.auto_pause_handler = (
-                    self.auto_pause_handler
-                )
-        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
         # Note: HTTP-based connection manager doesn't use connection_pool
@@ -329,8 +414,6 @@ class ClaudeHookHandler:
             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()
                 _log(
                     f"🧹 Performed cleanup after {self.state_manager.events_processed} events"
@@ -496,11 +579,11 @@ 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}),
+                json.dumps({"continue": True, "tool_input": modified_input}),
                 flush=True,
             )
         else:
-            print(json.dumps({"action": "continue"}), flush=True)
+            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):
@@ -673,7 +756,7 @@ def main():
         # This prevents errors on older Claude Code versions
         if version:
             _log(f"Skipping hook processing due to version incompatibility ({version})")
-        print(json.dumps({"action": "continue"}), flush=True)
+        print(json.dumps({"continue": True}), flush=True)
         sys.exit(0)
 
     def cleanup_handler(signum=None, frame=None):
@@ -682,7 +765,7 @@ def main():
         _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"}), flush=True)
+            print(json.dumps({"continue": True}), flush=True)
             _continue_printed = True
             sys.exit(0)
 
@@ -715,7 +798,7 @@ def main():
     except Exception as e:
         # Only output continue if not already printed
         if not _continue_printed:
-            print(json.dumps({"action": "continue"}), flush=True)
+            print(json.dumps({"continue": True}), flush=True)
             _continue_printed = True
         # Log error for debugging
         _log(f"Hook handler error: {e}")
@@ -727,5 +810,5 @@ if __name__ == "__main__":
         main()
     except Exception:
         # Catastrophic failure (import error, etc.) - always output valid JSON
-        print(json.dumps({"action": "continue"}), flush=True)
+        print(json.dumps({"continue": True}), flush=True)
         sys.exit(0)

claude_mpm/hooks/claude_hooks/installer.py

@@ -149,7 +149,7 @@ main() {
         if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
             echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Claude MPM not found, continuing..." >> /tmp/claude-mpm-hook.log
         fi
-        echo '{"action": "continue"}'
+        echo '{"continue": true}'
         exit 0
     fi
 
@@ -176,7 +176,7 @@ main() {
             echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Hook handler failed, see /tmp/claude-mpm-hook-error.log" >> /tmp/claude-mpm-hook.log
             echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Error: $(cat /tmp/claude-mpm-hook-error.log 2>/dev/null | head -5)" >> /tmp/claude-mpm-hook.log
         fi
-        echo '{"action": "continue"}'
+        echo '{"continue": true}'
         exit 0
     fi
 
@@ -203,10 +203,14 @@ main "$@"
         import logging
 
         self.logger = logging.getLogger(__name__)
-        self.claude_dir = Path.home() / ".claude"
+        # Use project-level paths, NEVER global ~/.claude/settings.json
+        # This ensures hooks are scoped to the current project only
+        self.project_root = Path.cwd()
+        self.claude_dir = self.project_root / ".claude"
         self.hooks_dir = self.claude_dir / "hooks"  # Kept for backward compatibility
-        # Use settings.json for hooks (Claude Code reads from this file)
-        self.settings_file = self.claude_dir / "settings.json"
+        # Use settings.local.json for project-level hook settings
+        # Claude Code reads project-level settings from .claude/settings.local.json
+        self.settings_file = self.claude_dir / "settings.local.json"
         # There is no legacy settings file - this was a bug where both pointed to same file
         # Setting to None to disable cleanup that was deleting freshly installed hooks
         self.old_settings_file = None
@@ -383,8 +387,35 @@ main "$@"
             return False
         return self._version_meets_minimum(version, self.MIN_SKILLS_VERSION)
 
-    def get_hook_script_path(self) -> Path:
-        """Get the path to the hook handler script based on installation method.
+    def get_hook_command(self) -> str:
+        """Get the hook command based on installation method.
+
+        Priority order:
+        1. claude-hook entry point (uv tool install, pipx install, pip install)
+        2. Fallback to bash script (development installs)
+
+        Returns:
+            Command string for the hook handler (either 'claude-hook' or path to bash script)
+
+        Raises:
+            FileNotFoundError: If no hook handler can be found
+        """
+        # Check if claude-hook entry point is available in PATH
+        claude_hook_path = shutil.which("claude-hook")
+        if claude_hook_path:
+            self.logger.info(f"Using claude-hook entry point: {claude_hook_path}")
+            return "claude-hook"
+
+        # Fallback to bash script for development installs
+        script_path = self._get_hook_script_path()
+        self.logger.info(f"Using fallback bash script: {script_path}")
+        return str(script_path.absolute())
+
+    def _get_hook_script_path(self) -> Path:
+        """Get the path to the fallback bash hook handler script.
+
+        This is used when the claude-hook entry point is not available
+        (e.g., development installs without uv tool install).
 
         Returns:
             Path to the claude-hook-handler.sh script
@@ -437,6 +468,19 @@ main "$@"
 
         raise FileNotFoundError(f"Hook handler script not found at {script_path}")
 
+    def get_hook_script_path(self) -> Path:
+        """Get the path to the hook handler script based on installation method.
+
+        DEPRECATED: Use get_hook_command() instead for proper entry point support.
+
+        Returns:
+            Path to the claude-hook-handler.sh script
+
+        Raises:
+            FileNotFoundError: If the script cannot be found
+        """
+        return self._get_hook_script_path()
+
     def install_hooks(self, force: bool = False) -> bool:
         """
         Install Claude MPM hooks.
@@ -469,18 +513,16 @@ main "$@"
             # Create Claude directory (hooks_dir no longer needed)
             self.claude_dir.mkdir(exist_ok=True)
 
-            # Get the deployment-root hook script path
+            # Get the hook command (either claude-hook entry point or fallback bash script)
             try:
-                hook_script_path = self.get_hook_script_path()
-                self.logger.info(
-                    f"Using deployment-root hook script: {hook_script_path}"
-                )
+                hook_command = self.get_hook_command()
+                self.logger.info(f"Using hook command: {hook_command}")
             except FileNotFoundError as e:
-                self.logger.error(f"Failed to locate hook script: {e}")
+                self.logger.error(f"Failed to locate hook handler: {e}")
                 return False
 
-            # Update Claude settings to use deployment-root script
-            self._update_claude_settings(hook_script_path)
+            # Update Claude settings to use the hook command
+            self._update_claude_settings(hook_command)
 
             # Install commands if available
             self._install_commands()
@@ -575,8 +617,12 @@ main "$@"
                 "StatusLine command already supports both schemas or not present"
             )
 
-    def _update_claude_settings(self, hook_script_path: Path) -> None:
-        """Update Claude settings to use the installed hook."""
+    def _update_claude_settings(self, hook_cmd: str) -> None:
+        """Update Claude settings to use the installed hook.
+
+        Args:
+            hook_cmd: The hook command to use (either 'claude-hook' or path to bash script)
+        """
         self.logger.info("Updating Claude settings...")
 
         # Load existing settings.json or create new
@@ -599,42 +645,104 @@ main "$@"
             settings["hooks"] = {}
 
         # Hook configuration for each event type
-        hook_command = {"type": "command", "command": str(hook_script_path.absolute())}
+        hook_command = {"type": "command", "command": hook_cmd}
+
+        def is_our_hook(cmd: dict) -> bool:
+            """Check if a hook command belongs to claude-mpm."""
+            if cmd.get("type") != "command":
+                return False
+            command = cmd.get("command", "")
+            # Match claude-hook entry point or bash script fallback
+            return (
+                command == "claude-hook"
+                or "claude-hook-handler.sh" in command
+                or command.endswith("claude-mpm-hook.sh")
+            )
+
+        def merge_hooks_for_event(
+            existing_hooks: list, new_hook_command: dict, use_matcher: bool = True
+        ) -> list:
+            """Merge new hook command into existing hooks without duplication.
+
+            Args:
+                existing_hooks: Current hooks configuration for an event type
+                new_hook_command: The claude-mpm hook command to add
+                use_matcher: Whether to include matcher: "*" in the config
+
+            Returns:
+                Updated hooks list with our hook merged in
+            """
+            # Check if our hook already exists in any existing hook config
+            our_hook_exists = False
+
+            for hook_config in existing_hooks:
+                if "hooks" in hook_config and isinstance(hook_config["hooks"], list):
+                    for hook in hook_config["hooks"]:
+                        if is_our_hook(hook):
+                            # Update existing hook command path (in case it changed)
+                            hook["command"] = new_hook_command["command"]
+                            our_hook_exists = True
+                            break
+                if our_hook_exists:
+                    break
+
+            if our_hook_exists:
+                # Our hook already exists, just return the updated list
+                return existing_hooks
+
+            # Our hook doesn't exist - need to add it
+            # Strategy: Add our hook to the first "*" matcher config, or create new config
+            added = False
+
+            for hook_config in existing_hooks:
+                # Check if this config has matcher: "*" (or no matcher for simple events)
+                matcher = hook_config.get("matcher")
+                if matcher == "*" or (not use_matcher and matcher is None):
+                    # Add our hook to this config's hooks array
+                    if "hooks" not in hook_config:
+                        hook_config["hooks"] = []
+                    hook_config["hooks"].append(new_hook_command)
+                    added = True
+                    break
+
+            if not added:
+                # No suitable config found, create a new one
+                if use_matcher:
+                    new_config = {"matcher": "*", "hooks": [new_hook_command]}
+                else:
+                    new_config = {"hooks": [new_hook_command]}
+                existing_hooks.append(new_config)
+
+            return existing_hooks
 
         # Tool-related events need a matcher string
         tool_events = ["PreToolUse", "PostToolUse"]
         for event_type in tool_events:
-            settings["hooks"][event_type] = [
-                {
-                    "matcher": "*",  # String value to match all tools
-                    "hooks": [hook_command],
-                }
-            ]
+            existing = settings["hooks"].get(event_type, [])
+            settings["hooks"][event_type] = merge_hooks_for_event(
+                existing, hook_command, use_matcher=True
+            )
 
         # Simple events (no subtypes, no matcher needed)
-        simple_events = ["Stop", "SubagentStop", "SubagentStart"]
+        # Note: SubagentStart is NOT a valid Claude Code event (only SubagentStop is)
+        simple_events = ["Stop", "SubagentStop"]
         for event_type in simple_events:
-            settings["hooks"][event_type] = [
-                {
-                    "hooks": [hook_command],
-                }
-            ]
+            existing = settings["hooks"].get(event_type, [])
+            settings["hooks"][event_type] = merge_hooks_for_event(
+                existing, hook_command, use_matcher=False
+            )
 
         # SessionStart needs matcher for subtypes (startup, resume)
-        settings["hooks"]["SessionStart"] = [
-            {
-                "matcher": "*",  # Match all SessionStart subtypes
-                "hooks": [hook_command],
-            }
-        ]
+        existing = settings["hooks"].get("SessionStart", [])
+        settings["hooks"]["SessionStart"] = merge_hooks_for_event(
+            existing, hook_command, use_matcher=True
+        )
 
         # UserPromptSubmit needs matcher for potential subtypes
-        settings["hooks"]["UserPromptSubmit"] = [
-            {
-                "matcher": "*",
-                "hooks": [hook_command],
-            }
-        ]
+        existing = settings["hooks"].get("UserPromptSubmit", [])
+        settings["hooks"]["UserPromptSubmit"] = merge_hooks_for_event(
+            existing, hook_command, use_matcher=True
+        )
 
         # Fix statusLine command to handle both output style schemas
         self._fix_status_line(settings)
@@ -736,10 +844,10 @@ main "$@"
                     issues.append("No hooks configured in Claude settings")
                 else:
                     # Check for required event types
+                    # Note: SubagentStart is NOT a valid Claude Code event
                     required_events = [
                         "Stop",
                         "SubagentStop",
-                        "SubagentStart",
                         "PreToolUse",
                         "PostToolUse",
                     ]
@@ -805,7 +913,8 @@ main "$@"
                                         ):
                                             cmd = hook_cmd.get("command", "")
                                             if (
-                                                "claude-hook-handler.sh" in cmd
+                                                cmd == "claude-hook"
+                                                or "claude-hook-handler.sh" in cmd
                                                 or cmd.endswith("claude-mpm-hook.sh")
                                             ):
                                                 is_claude_mpm = True
@@ -850,27 +959,42 @@ main "$@"
 
         is_valid, issues = self.verify_hooks()
 
-        # Try to get deployment-root script path
+        # Try to get hook command (entry point or fallback script)
+        hook_command = None
+        using_entry_point = False
         try:
-            hook_script_path = self.get_hook_script_path()
+            hook_command = self.get_hook_command()
+            using_entry_point = hook_command == "claude-hook"
+        except FileNotFoundError:
+            hook_command = None
+
+        # For backward compatibility, also try to get the script path
+        hook_script_str = None
+        script_exists = False
+        try:
+            hook_script_path = self._get_hook_script_path()
             hook_script_str = str(hook_script_path)
             script_exists = hook_script_path.exists()
         except FileNotFoundError:
-            hook_script_str = None
-            script_exists = False
+            pass
 
         status = {
-            "installed": script_exists and self.settings_file.exists(),
+            "installed": (hook_command is not None or script_exists)
+            and self.settings_file.exists(),
             "valid": is_valid,
             "issues": issues,
-            "hook_script": hook_script_str,
+            "hook_command": hook_command,
+            "hook_script": hook_script_str,  # Kept for backward compatibility
+            "using_entry_point": using_entry_point,
             "settings_file": (
                 str(self.settings_file) if self.settings_file.exists() else None
             ),
             "claude_version": claude_version,
             "version_compatible": is_compatible,
             "version_message": version_message,
-            "deployment_type": "deployment-root",  # New field to indicate new architecture
+            "deployment_type": "entry-point"
+            if using_entry_point
+            else "deployment-root",
             "pretool_modify_supported": pretool_modify_supported,  # v2.0.30+ feature
             "pretool_modify_message": (
                 f"PreToolUse input modification supported (v{claude_version})"

claude_mpm/hooks/claude_hooks/memory_integration.py

@@ -67,7 +67,7 @@ from datetime import datetime, timezone
 from typing import Optional
 
 # Debug mode
-DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "false").lower() == "true"
 
 # Memory hooks integration
 MEMORY_HOOKS_AVAILABLE = False

claude_mpm/hooks/claude_hooks/response_tracking.py

@@ -22,7 +22,7 @@ except ImportError:
 
 
 # Debug mode
-DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "false").lower() == "true"
 
 # Response tracking integration
 # NOTE: ResponseTracker import moved to _initialize_response_tracking() for lazy loading

claude_mpm/hooks/claude_hooks/services/__init__.py

@@ -3,13 +3,34 @@
 # Use HTTP-based connection manager for stable dashboard communication
 # from .connection_manager import ConnectionManagerService  # Old SocketIO-based
 from .connection_manager_http import ConnectionManagerService  # New HTTP-based
+from .container import HookServiceContainer, get_container
 from .duplicate_detector import DuplicateEventDetector
+from .protocols import (
+    IAutoPauseHandler,
+    IConnectionManager,
+    IDuplicateDetector,
+    IEventHandlers,
+    IMemoryHookManager,
+    IResponseTrackingManager,
+    IStateManager,
+    ISubagentProcessor,
+)
 from .state_manager import StateManagerService
 from .subagent_processor import SubagentResponseProcessor
 
 __all__ = [
     "ConnectionManagerService",
     "DuplicateEventDetector",
+    "HookServiceContainer",
+    "IAutoPauseHandler",
+    "IConnectionManager",
+    "IDuplicateDetector",
+    "IEventHandlers",
+    "IMemoryHookManager",
+    "IResponseTrackingManager",
+    "IStateManager",
+    "ISubagentProcessor",
     "StateManagerService",
     "SubagentResponseProcessor",
+    "get_container",
 ]

claude_mpm/hooks/claude_hooks/services/connection_manager.py

@@ -29,8 +29,8 @@ except ImportError:
         pass  # Silent fallback
 
 
-# Debug mode is enabled by default for better visibility into hook processing
-DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+# Debug mode - disabled by default to prevent logging overhead in production
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "false").lower() == "true"
 
 # Import extracted modules with fallback for direct execution
 try:

claude_mpm/hooks/claude_hooks/services/connection_manager_http.py

@@ -28,8 +28,8 @@ except ImportError:
         pass  # Silent fallback
 
 
-# Debug mode is enabled by default for better visibility into hook processing
-DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+# Debug mode - disabled by default to prevent logging overhead in production
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "false").lower() == "true"
 
 # Import requests for HTTP POST communication
 try: