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

claude_mpm/hooks/claude_hooks/hook_handler.py

@@ -22,7 +22,7 @@ import os
 import re
 import select
 import signal
-import subprocess
+import subprocess  # nosec B404
 import sys
 import threading
 from datetime import datetime, timezone
@@ -31,6 +31,7 @@ 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
@@ -47,6 +48,7 @@ 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
@@ -60,14 +62,31 @@ except ImportError:
 """
 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 +128,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 +174,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 +205,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
 
@@ -230,8 +246,21 @@ class ClaudeHookHandler:
             self.state_manager, self.response_tracking_manager, self.connection_manager
         )
 
+        # 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}")
+
         # 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 +289,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 +310,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,12 +320,10 @@ 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():
@@ -308,11 +332,9 @@ class ClaudeHookHandler:
                 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 +374,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 +385,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 +423,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 +435,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 +461,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 +495,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({"action": "continue", "tool_input": modified_input}),
+                flush=True,
+            )
         else:
-            print(json.dumps({"action": "continue"}))
+            print(json.dumps({"action": "continue"}), flush=True)
 
     # Delegation methods for compatibility with event_handlers
     def _track_delegation(self, session_id: str, agent_type: str, request_data=None):
@@ -535,13 +553,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 +586,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 +646,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 +671,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({"action": "continue"}), 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({"action": "continue"}), flush=True)
             _continue_printed = True
             sys.exit(0)
 
@@ -678,15 +696,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 +715,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({"action": "continue"}), 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({"action": "continue"}), 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 $?

claude_mpm/hooks/claude_hooks/installer.py

@@ -10,7 +10,7 @@ import os
 import re
 import shutil
 import stat
-import subprocess
+import subprocess  # nosec B404 - Safe: only uses hardcoded 'claude' CLI command, no user input
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple
 
@@ -194,6 +194,8 @@ main "$@"
     MIN_CLAUDE_VERSION = "1.0.92"
     # Minimum version for PreToolUse input modification support
     MIN_PRETOOL_MODIFY_VERSION = "2.0.30"
+    # Minimum version for user-invocable skills support
+    MIN_SKILLS_VERSION = "2.1.3"
 
     def __init__(self):
         """Initialize the hook installer."""
@@ -220,7 +222,7 @@ main "$@"
 
         try:
             # Run claude --version command
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B607 B603 - Safe: hardcoded command, no user input
                 ["claude", "--version"],
                 capture_output=True,
                 text=True,
@@ -331,6 +333,53 @@ main "$@"
 
         return True
 
+    def _version_meets_minimum(self, version: str, min_version: str) -> bool:
+        """Check if a version meets minimum requirements.
+
+        Args:
+            version: Current version string (e.g., "2.1.3")
+            min_version: Minimum required version string (e.g., "2.1.3")
+
+        Returns:
+            True if version meets or exceeds minimum, False otherwise
+        """
+
+        def parse_version(v: str) -> List[int]:
+            """Parse semantic version string to list of integers."""
+            try:
+                return [int(x) for x in v.split(".")]
+            except (ValueError, AttributeError):
+                return [0]
+
+        current = parse_version(version)
+        required = parse_version(min_version)
+
+        # Compare versions
+        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:
+                return False
+            if curr_part > req_part:
+                return True
+
+        return True
+
+    def supports_user_invocable_skills(self) -> bool:
+        """Check if Claude Code version supports user-invocable skills.
+
+        User-invocable skills were added in Claude Code v2.1.3.
+        This feature allows users to invoke skills via slash commands.
+
+        Returns:
+            True if version supports user-invocable skills, False otherwise
+        """
+        version = self.get_claude_version()
+        if not version:
+            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.
 
@@ -556,7 +605,22 @@ main "$@"
         self._cleanup_old_settings()
 
     def _install_commands(self) -> None:
-        """Install custom commands for Claude Code."""
+        """Install custom commands for Claude Code.
+
+        For Claude Code >= 2.1.3, commands are deployed as skills via PMSkillsDeployerService.
+        This method provides backward compatibility for older versions.
+        """
+        # Check if skills-based commands are supported
+        if self.supports_user_invocable_skills():
+            self.logger.info(
+                "Claude Code >= 2.1.3 detected. Commands deployed as skills - "
+                "skipping legacy command installation."
+            )
+            return
+
+        # Legacy installation for older Claude Code versions
+        self.logger.info("Installing legacy commands for Claude Code < 2.1.3")
+
         # Find commands directory using proper resource resolution
         try:
             from ...core.unified_paths import get_package_resource_path
@@ -782,7 +846,7 @@ main "$@"
                     if "hooks" in settings:
                         status["configured_events"] = list(settings["hooks"].keys())
                         configured_in_local = True
-            except Exception:
+            except Exception:  # nosec B110 - Intentional: ignore errors reading settings file
                 pass
 
         # Also check old settings file
@@ -796,7 +860,7 @@ main "$@"
                             status["warning"] = (
                                 "Hooks found in settings.local.json but Claude Code reads from settings.json"
                             )
-            except Exception:
+            except Exception:  # nosec B110 - Intentional: ignore errors reading old settings file
                 pass
 
         status["settings_location"] = (

claude_mpm/hooks/claude_hooks/response_tracking.py

@@ -130,7 +130,7 @@ class ResponseTrackingManager:
 
         try:
             # Get the original request data stored during pre-tool
-            request_info = delegation_requests.get(session_id)
+            request_info = delegation_requests.get(session_id)  # nosec B113 - False positive: dict.get(), not requests library
             if not request_info:
                 if DEBUG:
                     print(
@@ -306,6 +306,8 @@ class ResponseTrackingManager:
                         )
 
                 # Capture Claude API usage data if available
+                # NOTE: Usage data is already captured in metadata by handle_stop_fast()
+                # which also handles auto-pause triggering (even when response tracking disabled)
                 if "usage" in event:
                     usage_data = event["usage"]
                     metadata["usage"] = {

claude_mpm/hooks/claude_hooks/services/connection_manager.py

@@ -134,6 +134,26 @@ class ConnectionManagerService:
         # Otherwise use "hook" as the type
         if event == "hook_execution":
             hook_type = data.get("hook_type", "unknown")
+
+            # BUGFIX: Validate hook_type is meaningful (not generic/invalid values)
+            # Problem: Dashboard shows "hook hook" instead of "PreToolUse", "UserPromptSubmit", etc.
+            # Root cause: hook_type defaults to "hook" or "unknown", providing no useful information
+            # Solution: Fallback to hook_name, then to descriptive "hook_execution_untyped"
+            if hook_type in ("hook", "unknown", "", None):
+                # Try fallback to hook_name field (set by _emit_hook_execution_event)
+                hook_type = data.get("hook_name", "unknown_hook")
+
+                # Final fallback if still generic - use descriptive name
+                if hook_type in ("hook", "unknown", "", None):
+                    hook_type = "hook_execution_untyped"
+
+                # Debug log when we detect invalid hook_type for troubleshooting
+                if DEBUG:
+                    print(
+                        f"⚠️ Invalid hook_type detected, using fallback: {hook_type}",
+                        file=sys.stderr,
+                    )
+
             event_type = hook_type
         else:
             event_type = "hook"