claude-mpm 4.1.6__py3-none-any.whl → 4.24.0__py3-none-any.whl

claude_mpm/hooks/claude_hooks/event_handlers.py

@@ -9,7 +9,8 @@ import os
 import re
 import subprocess
 import sys
-from datetime import datetime
+from datetime import datetime, timezone
+from pathlib import Path
 from typing import Optional
 
 # Import tool analysis with fallback for direct execution
@@ -77,7 +78,7 @@ class EventHandlers:
             "session_id": event.get("session_id", ""),
             "working_directory": working_dir,
             "git_branch": git_branch,
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "is_command": prompt.startswith("/"),
             "contains_code": "```" in prompt
             or "python" in prompt.lower()
@@ -101,7 +102,7 @@ class EventHandlers:
             if session_id:
                 self.hook_handler.pending_prompts[session_id] = {
                     "prompt": prompt,
-                    "timestamp": datetime.now().isoformat(),
+                    "timestamp": datetime.now(timezone.utc).isoformat(),
                     "working_directory": working_dir,
                 }
                 if DEBUG:
@@ -150,7 +151,7 @@ class EventHandlers:
             "session_id": event.get("session_id", ""),
             "working_directory": working_dir,
             "git_branch": git_branch,
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "parameter_count": len(tool_input) if isinstance(tool_input, dict) else 0,
             "is_file_operation": tool_name
             in ["Write", "Edit", "MultiEdit", "Read", "LS", "Glob"],
@@ -249,7 +250,7 @@ class EventHandlers:
             "session_id": session_id,
             "prompt": tool_input.get("prompt", ""),
             "description": tool_input.get("description", ""),
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "hook_event_name": "SubagentStart",  # For dashboard compatibility
         }
         self.hook_handler._emit_socketio_event(
@@ -277,18 +278,18 @@ class EventHandlers:
                     "session_id": session_id,
                     "delegation_context": {
                         "description": tool_input.get("description", ""),
-                        "timestamp": datetime.now().isoformat(),
+                        "timestamp": datetime.now(timezone.utc).isoformat(),
                     },
                 }
 
                 # Log the agent prompt asynchronously
                 try:
                     loop = asyncio.get_running_loop()
-                    asyncio.create_task(
+                    _task = asyncio.create_task(
                         log_manager.log_prompt(
                             f"agent_{agent_type}", prompt_content, metadata
                         )
-                    )
+                    )  # Fire-and-forget logging (ephemeral hook process)
                 except RuntimeError:
                     # No running loop, create one
                     loop = asyncio.new_event_loop()
@@ -309,23 +310,25 @@ class EventHandlers:
         """Get git branch for the given directory with caching."""
         # Use current working directory if not specified
         if not working_dir:
-            working_dir = os.getcwd()
+            working_dir = Path.cwd()
 
-        # Check cache first (cache for 30 seconds)
-        current_time = datetime.now().timestamp()
+        # Check cache first (cache for 300 seconds = 5 minutes)
+        # WHY 5 minutes: Git branches rarely change during development sessions,
+        # reducing subprocess overhead significantly without staleness issues
+        current_time = datetime.now(timezone.utc).timestamp()
         cache_key = working_dir
 
         if (
             cache_key in self.hook_handler._git_branch_cache
             and cache_key in self.hook_handler._git_branch_cache_time
-            and current_time - self.hook_handler._git_branch_cache_time[cache_key] < 30
+            and current_time - self.hook_handler._git_branch_cache_time[cache_key] < 300
         ):
             return self.hook_handler._git_branch_cache[cache_key]
 
         # Try to get git branch
         try:
             # Change to the working directory temporarily
-            original_cwd = os.getcwd()
+            original_cwd = Path.cwd()
             os.chdir(working_dir)
 
             # Run git command to get current branch
@@ -397,7 +400,7 @@ class EventHandlers:
             "session_id": event.get("session_id", ""),
             "working_directory": working_dir,
             "git_branch": git_branch,
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "has_output": bool(result_data.get("output")),
             "has_error": bool(result_data.get("error")),
             "output_size": (
@@ -448,7 +451,7 @@ class EventHandlers:
             "session_id": event.get("session_id", ""),
             "working_directory": working_dir,
             "git_branch": git_branch,
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "is_user_input_request": "input" in message.lower()
             or "waiting" in message.lower(),
             "is_error_notification": "error" in message.lower()
@@ -492,7 +495,7 @@ class EventHandlers:
         """Extract metadata from stop event."""
         working_dir = event.get("cwd", "")
         return {
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "working_directory": working_dir,
             "git_branch": (
                 self._get_git_branch(working_dir) if working_dir else "Unknown"
@@ -639,7 +642,7 @@ class EventHandlers:
                     "has_error": reason in ["error", "timeout", "failed", "blocked"],
                     "working_directory": working_dir,
                     "git_branch": git_branch,
-                    "timestamp": datetime.now().isoformat(),
+                    "timestamp": datetime.now(timezone.utc).isoformat(),
                     "event_type": "subagent_stop",
                     "reason": reason,
                     "original_request_timestamp": request_info.get("timestamp"),
@@ -715,7 +718,7 @@ class EventHandlers:
             "session_id": session_id,
             "working_directory": working_dir,
             "git_branch": git_branch,
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "contains_code": "```" in response_text,
             "contains_json": "```json" in response_text,
             "hook_event_name": "AssistantResponse",  # Explicitly set for dashboard

claude_mpm/hooks/claude_hooks/hook_handler.py

@@ -3,7 +3,7 @@
 
 This handler uses a service-oriented architecture with:
 - StateManagerService: Manages state and delegation tracking
-- ConnectionManagerService: Handles SocketIO and EventBus connections
+- ConnectionManagerService: Handles SocketIO connections with HTTP fallback
 - SubagentResponseProcessor: Processes complex subagent responses
 - DuplicateEventDetector: Detects and filters duplicate events
 
@@ -12,15 +12,21 @@ WHY service-oriented approach:
 - Easier testing and maintenance
 - Reduced file size from 1040 to ~400 lines
 - Clear service boundaries and responsibilities
+
+NOTE: Requires Claude Code version 1.0.92 or higher for proper hook support.
+Earlier versions do not support matcher-based hook configuration.
 """
 
 import json
 import os
+import re
 import select
 import signal
+import subprocess
 import sys
 import threading
-from datetime import datetime
+from datetime import datetime, timezone
+from typing import Optional, Tuple
 
 # Import extracted modules with fallback for direct execution
 try:
@@ -51,18 +57,26 @@ except ImportError:
         SubagentResponseProcessor,
     )
 
-# Debug mode is enabled by default for better visibility into hook processing
-# Set CLAUDE_MPM_HOOK_DEBUG=false to disable debug output
+"""
+Debug mode configuration for hook processing.
+
+WHY enabled by default: Hook processing can be complex and hard to debug.
+Having debug output available by default helps diagnose issues during development.
+Production deployments can disable via environment variable.
+
+Performance Impact: Debug logging adds ~5-10% overhead but provides crucial
+visibility into event flow, timing, and error conditions.
+"""
 DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
 
-# Import EventBus availability flag for backward compatibility with tests
-try:
-    from claude_mpm.services.event_bus import EventBus
+"""
+Conditional imports with graceful fallbacks for testing and modularity.
 
-    EVENTBUS_AVAILABLE = True
-except ImportError:
-    EVENTBUS_AVAILABLE = False
-    EventBus = None
+WHY conditional imports:
+- Tests may not have full environment setup
+- Allows hooks to work in minimal configurations
+- Graceful degradation when dependencies unavailable
+"""
 
 # Import get_connection_pool for backward compatibility with tests
 try:
@@ -70,10 +84,125 @@ try:
 except ImportError:
     get_connection_pool = None
 
-# Global singleton handler instance
+"""
+Global singleton pattern for hook handler.
+
+WHY singleton:
+- Only one handler should process Claude Code events
+- Maintains consistent state across all hook invocations
+- Prevents duplicate event processing
+- Thread-safe initialization with lock
+
+GOTCHA: Must use get_global_handler() not direct access to avoid race conditions.
+"""
 _global_handler = None
 _handler_lock = threading.Lock()
 
+"""
+Version compatibility checking.
+
+WHY version checking:
+- Claude Code hook support was added in v1.0.92
+- Earlier versions don't support matcher-based configuration
+- Prevents confusing errors with unsupported versions
+
+Security: Version checking prevents execution on incompatible environments.
+"""
+MIN_CLAUDE_VERSION = "1.0.92"
+
+
+def check_claude_version() -> Tuple[bool, Optional[str]]:
+    """
+    Verify Claude Code version compatibility for hook support.
+
+    Executes 'claude --version' command to detect installed version and
+    compares against minimum required version for hook functionality.
+
+    Version Checking Logic:
+    1. Execute 'claude --version' with timeout
+    2. Parse version string using regex
+    3. Compare against MIN_CLAUDE_VERSION (1.0.92)
+    4. Return compatibility status and detected version
+
+    WHY this check is critical:
+    - Hook support was added in Claude Code v1.0.92
+    - Earlier versions don't understand matcher-based hooks
+    - Prevents cryptic errors from unsupported configurations
+    - Allows graceful fallback or user notification
+
+    Error Handling:
+    - Command timeout after 5 seconds
+    - Subprocess errors caught and logged
+    - Invalid version formats handled gracefully
+    - Returns (False, None) on any failure
+
+    Performance Notes:
+    - Subprocess call has ~100ms overhead
+    - Result should be cached by caller
+    - Only called during initialization
+
+    Returns:
+        Tuple[bool, Optional[str]]:
+            - bool: True if version is compatible
+            - str|None: Detected version string, None if detection failed
+
+    Examples:
+        >>> is_compatible, version = check_claude_version()
+        >>> if not is_compatible:
+        ...     print(f"Claude Code {version or 'unknown'} is not supported")
+    """
+    try:
+        # Try to detect Claude Code version
+        result = subprocess.run(
+            ["claude", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+
+        if result.returncode == 0:
+            version_text = result.stdout.strip()
+            # Extract version number (e.g., "1.0.92 (Claude Code)" -> "1.0.92")
+            match = re.match(r"^([\d\.]+)", version_text)
+            if match:
+                version = match.group(1)
+
+                # Compare versions
+                def parse_version(v: str):
+                    try:
+                        return [int(x) for x in v.split(".")]
+                    except (ValueError, AttributeError):
+                        return [0]
+
+                current = parse_version(version)
+                required = parse_version(MIN_CLAUDE_VERSION)
+
+                # Check if current version meets minimum
+                for i in range(max(len(current), len(required))):
+                    curr_part = current[i] if i < len(current) else 0
+                    req_part = required[i] if i < len(required) else 0
+
+                    if curr_part < req_part:
+                        if DEBUG:
+                            print(
+                                f"⚠️  Claude Code {version} does not support matcher-based hooks "
+                                f"(requires {MIN_CLAUDE_VERSION}+). Hook monitoring disabled.",
+                                file=sys.stderr,
+                            )
+                        return False, version
+                    if curr_part > req_part:
+                        return True, version
+
+                return True, version
+    except Exception as e:
+        if DEBUG:
+            print(
+                f"Warning: Could not detect Claude Code version: {e}", file=sys.stderr
+            )
+
+    return False, None
+
 
 class ClaudeHookHandler:
     """Refactored hook handler with service-oriented architecture.
@@ -103,7 +232,6 @@ class ClaudeHookHandler:
 
         # Backward compatibility properties for tests
         self.connection_pool = self.connection_manager.connection_pool
-        self.event_bus = self.connection_manager.event_bus
 
         # Expose state manager properties for backward compatibility
         self.active_delegations = self.state_manager.active_delegations
@@ -111,6 +239,10 @@ class ClaudeHookHandler:
         self.delegation_requests = self.state_manager.delegation_requests
         self.pending_prompts = self.state_manager.pending_prompts
 
+        # Initialize git branch cache (used by event_handlers)
+        self._git_branch_cache = {}
+        self._git_branch_cache_time = {}
+
     def handle(self):
         """Process hook event with minimal overhead and timeout protection.
 
@@ -152,7 +284,7 @@ class ClaudeHookHandler:
             if self.duplicate_detector.is_duplicate(event):
                 if DEBUG:
                     print(
-                        f"[{datetime.now().isoformat()}] Skipping duplicate event: {event.get('hook_event_name', 'unknown')} (PID: {os.getpid()})",
+                        f"[{datetime.now(timezone.utc).isoformat()}] Skipping duplicate event: {event.get('hook_event_name', 'unknown')} (PID: {os.getpid()})",
                         file=sys.stderr,
                     )
                 # Still need to output continue for this invocation
@@ -165,7 +297,7 @@ class ClaudeHookHandler:
             if DEBUG:
                 hook_type = event.get("hook_event_name", "unknown")
                 print(
-                    f"\n[{datetime.now().isoformat()}] Processing hook event: {hook_type} (PID: {os.getpid()})",
+                    f"\n[{datetime.now(timezone.utc).isoformat()}] Processing hook event: {hook_type} (PID: {os.getpid()})",
                     file=sys.stderr,
                 )
 
@@ -179,11 +311,12 @@ class ClaudeHookHandler:
                     )
 
             # Route event to appropriate handler
-            self._route_event(event)
+            # Handlers can optionally return modified input for PreToolUse events
+            modified_input = self._route_event(event)
 
             # Always continue execution (only if not already sent)
             if not _continue_sent:
-                self._continue_execution()
+                self._continue_execution(modified_input)
                 _continue_sent = True
 
         except Exception:
@@ -225,7 +358,16 @@ class ClaudeHookHandler:
                 # Empty or whitespace-only data
                 return None
 
-            return json.loads(event_data)
+            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)
+            return parsed
         except (json.JSONDecodeError, ValueError) as e:
             if DEBUG:
                 print(f"Failed to parse hook event: {e}", file=sys.stderr)
@@ -235,7 +377,7 @@ class ClaudeHookHandler:
                 print(f"Error reading hook event: {e}", file=sys.stderr)
             return None
 
-    def _route_event(self, event: dict) -> None:
+    def _route_event(self, event: dict) -> Optional[dict]:
         """
         Route event to appropriate handler based on type.
 
@@ -244,8 +386,24 @@ class ClaudeHookHandler:
 
         Args:
             event: Hook event dictionary
+
+        Returns:
+            Modified input for PreToolUse events (v2.0.30+), None otherwise
         """
-        hook_type = event.get("hook_event_name", "unknown")
+        # Try multiple field names for compatibility
+        hook_type = (
+            event.get("hook_event_name")
+            or event.get("event")
+            or event.get("type")
+            or event.get("event_type")
+            or event.get("hook_event_type")
+            or "unknown"
+        )
+
+        # Log the actual event structure for debugging
+        if DEBUG and hook_type == "unknown":
+            print(f"Unknown event format, keys: {list(event.keys())}", file=sys.stderr)
+            print(f"Event sample: {str(event)[:200]}", file=sys.stderr)
 
         # Map event types to handlers
         event_handlers = {
@@ -262,23 +420,36 @@ class ClaudeHookHandler:
         handler = event_handlers.get(hook_type)
         if handler:
             try:
-                handler(event)
+                # Handlers can optionally return modified input
+                result = handler(event)
+                # Only PreToolUse handlers should return modified input
+                if hook_type == "PreToolUse" and result is not None:
+                    return result
             except Exception as e:
                 if DEBUG:
                     print(f"Error handling {hook_type}: {e}", file=sys.stderr)
 
+        return None
+
     def handle_subagent_stop(self, event: dict):
         """Delegate subagent stop processing to the specialized processor."""
         self.subagent_processor.process_subagent_stop(event)
 
-    def _continue_execution(self) -> None:
+    def _continue_execution(self, modified_input: Optional[dict] = None) -> None:
         """
-        Send continue action to Claude.
+        Send continue action to Claude with optional input modification.
 
         WHY: Centralized response ensures consistent format
         and makes it easier to add response modifications.
+
+        Args:
+            modified_input: Modified tool parameters for PreToolUse hooks (v2.0.30+)
         """
-        print(json.dumps({"action": "continue"}))
+        if modified_input is not None:
+            # Claude Code v2.0.30+ supports modifying PreToolUse tool inputs
+            print(json.dumps({"action": "continue", "tool_input": modified_input}))
+        else:
+            print(json.dumps({"action": "continue"}))
 
     # Delegation methods for compatibility with event_handlers
     def _track_delegation(self, session_id: str, agent_type: str, request_data=None):
@@ -307,7 +478,7 @@ class ClaudeHookHandler:
         if hasattr(self, "connection_manager") and self.connection_manager:
             try:
                 self.connection_manager.cleanup()
-            except:
+            except Exception:
                 pass  # Ignore cleanup errors during destruction
 
 
@@ -316,6 +487,19 @@ def main():
     global _global_handler
     _continue_printed = False  # Track if we've already printed continue
 
+    # Check Claude Code version compatibility first
+    is_compatible, version = check_claude_version()
+    if not is_compatible:
+        # Version incompatible - just continue without processing
+        # This prevents errors on older Claude Code versions
+        if DEBUG and version:
+            print(
+                f"Skipping hook processing due to version incompatibility ({version})",
+                file=sys.stderr,
+            )
+        print(json.dumps({"action": "continue"}))
+        sys.exit(0)
+
     def cleanup_handler(signum=None, frame=None):
         """Cleanup handler for signals and exit."""
         nonlocal _continue_printed