claude-mpm 5.0.9__py3-none-any.whl → 5.6.23__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,21 +320,21 @@ 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()
-                if DEBUG:
-                    print(
-                        f"🧹 Performed cleanup after {self.state_manager.events_processed} events",
-                        file=sys.stderr,
-                    )
+                # Also cleanup old correlation files
+                from .correlation_manager import CorrelationManager
+
+                CorrelationManager.cleanup_old()
+                _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
@@ -348,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
@@ -360,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]:
@@ -390,6 +410,8 @@ class ClaudeHookHandler:
         Returns:
             Modified input for PreToolUse events (v2.0.30+), None otherwise
         """
+        import time
+
         # Try multiple field names for compatibility
         hook_type = (
             event.get("hook_event_name")
@@ -401,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 = {
@@ -413,21 +435,47 @@ 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_subagent_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:
                 # 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 result
+                    return_value = result
+                else:
+                    return_value = None
             except Exception as e:
-                if DEBUG:
-                    print(f"Error handling {hook_type}: {e}", file=sys.stderr)
+                error_message = str(e)
+                return_value = None
+                _log(f"Error handling {hook_type}: {e}")
+            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
 
@@ -447,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):
@@ -472,14 +523,142 @@ class ClaudeHookHandler:
         """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
+        """
+        # 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,  # 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
+        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)
+
+        _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.
+
+        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 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 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():
@@ -492,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)
 
@@ -524,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
@@ -548,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 $?