claude-mpm 4.0.32__py3-none-any.whl → 4.1.0__py3-none-any.whl

claude_mpm/hooks/claude_hooks/hook_handler_eventbus.py

@@ -0,0 +1,398 @@
+#!/usr/bin/env python3
+"""Optimized Claude Code hook handler with EventBus architecture.
+
+This handler uses the EventBus for decoupled event emission instead of
+direct Socket.IO connections. This provides better separation of concerns
+and improved testability.
+
+WHY EventBus approach:
+- Decouples hook processing from Socket.IO implementation
+- Enables multiple event consumers without code changes
+- Simplifies testing by removing Socket.IO dependencies
+- Provides centralized event routing and filtering
+- Maintains backward compatibility with existing hooks
+"""
+
+import json
+import os
+import select
+import signal
+import subprocess
+import sys
+import threading
+import time
+from collections import deque
+from datetime import datetime
+from pathlib import Path
+
+# Add parent path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent))
+
+# Import EventBus
+try:
+    from claude_mpm.services.event_bus import EventBus
+    EVENTBUS_AVAILABLE = True
+except ImportError:
+    EVENTBUS_AVAILABLE = False
+    EventBus = None
+
+# Import EventNormalizer for consistent event formatting
+try:
+    from claude_mpm.services.socketio.event_normalizer import EventNormalizer
+except ImportError:
+    # Create a simple fallback EventNormalizer if import fails
+    class EventNormalizer:
+        def normalize(self, event_data, source="hook"):
+            """Simple fallback normalizer that returns event as-is."""
+            return type('NormalizedEvent', (), {
+                'to_dict': lambda: {
+                    'event': 'claude_event',
+                    'type': event_data.get('type', 'unknown'),
+                    'subtype': event_data.get('subtype', 'generic'),
+                    'timestamp': event_data.get('timestamp', datetime.now().isoformat()),
+                    'data': event_data.get('data', event_data),
+                    'source': source
+                }
+            })
+
+# Import constants for configuration
+try:
+    from claude_mpm.core.constants import TimeoutConfig
+except ImportError:
+    # Fallback values if constants module not available
+    class TimeoutConfig:
+        QUICK_TIMEOUT = 2.0
+
+# Import other handler modules
+try:
+    from .memory_integration import MemoryHookManager
+    from .response_tracking import ResponseTrackingManager
+    from .event_handlers import EventHandlers
+except ImportError:
+    # Fallback for direct execution
+    from memory_integration import MemoryHookManager
+    from response_tracking import ResponseTrackingManager
+    from event_handlers import EventHandlers
+
+# Debug mode is enabled by default for better visibility into hook processing
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+
+# Global singleton handler instance
+_global_handler = None
+_handler_lock = threading.Lock()
+
+# Track recent events to detect duplicates
+_recent_events = deque(maxlen=10)
+_events_lock = threading.Lock()
+
+
+class HookHandler:
+    """Main hook handler class using EventBus for event emission.
+    
+    WHY EventBus integration:
+    - Replaces direct Socket.IO connections with EventBus publishing
+    - Events are published once and consumed by multiple listeners
+    - Failures in one consumer don't affect others
+    - Simplified testing without Socket.IO dependencies
+    """
+    
+    # Tracking dictionaries with size limits
+    MAX_DELEGATION_TRACKING = 100
+    MAX_PROMPT_TRACKING = 50
+    MAX_CACHE_AGE_SECONDS = 1800  # 30 minutes
+    
+    def __init__(self):
+        """Initialize the hook handler with EventBus."""
+        # Initialize EventBus if available
+        self.event_bus = EventBus.get_instance() if EVENTBUS_AVAILABLE else None
+        self.event_normalizer = EventNormalizer()
+        
+        # Initialize tracking managers
+        self.memory_manager = MemoryHookManager()
+        self.response_tracker = ResponseTrackingManager()
+        self.event_handlers = EventHandlers(self)
+        
+        # Delegation tracking
+        self.active_delegations = {}
+        self.delegation_requests = {}
+        self.delegation_history = deque(maxlen=20)
+        
+        # Prompt tracking
+        self.pending_prompts = {}
+        
+        # Git branch caching
+        self._git_branch_cache = {}
+        self._git_branch_cache_time = {}
+        
+        # Session tracking
+        self.current_session_id = None
+        
+        # Cleanup old entries periodically
+        self._last_cleanup = time.time()
+        
+        if self.event_bus:
+            logger_msg = "HookHandler initialized with EventBus"
+        else:
+            logger_msg = "HookHandler initialized (EventBus not available)"
+        
+        if DEBUG:
+            print(f"🚀 {logger_msg}", file=sys.stderr)
+    
+    def _emit_event(self, event_type: str, data: dict):
+        """Emit an event through the EventBus.
+        
+        WHY this approach:
+        - Single point of event emission
+        - Consistent event normalization
+        - Graceful fallback if EventBus unavailable
+        - Easy to add metrics and monitoring
+        
+        Args:
+            event_type: The event type (e.g., 'pre_tool', 'subagent_stop')
+            data: The event data
+        """
+        if not self.event_bus:
+            if DEBUG:
+                print(f"EventBus not available, cannot emit: hook.{event_type}", file=sys.stderr)
+            return
+        
+        try:
+            # Create event data for normalization
+            raw_event = {
+                "type": "hook",
+                "subtype": event_type,
+                "timestamp": datetime.now().isoformat(),
+                "data": data,
+                "source": "claude_hooks",
+                "session_id": data.get("sessionId", self.current_session_id)
+            }
+            
+            # Normalize the event
+            normalized_event = self.event_normalizer.normalize(raw_event, source="hook")
+            event_data = normalized_event.to_dict()
+            
+            # Publish to EventBus
+            success = self.event_bus.publish(f"hook.{event_type}", event_data)
+            
+            if DEBUG:
+                if success:
+                    print(f"✅ Published to EventBus: hook.{event_type}", file=sys.stderr)
+                else:
+                    print(f"⚠️ EventBus rejected event: hook.{event_type}", file=sys.stderr)
+            
+            # Log important events
+            if DEBUG and event_type in ["subagent_stop", "pre_tool"]:
+                if event_type == "subagent_stop":
+                    agent_type = data.get("agent_type", "unknown")
+                    print(f"📤 Published SubagentStop for agent '{agent_type}'", file=sys.stderr)
+                elif event_type == "pre_tool" and data.get("tool_name") == "Task":
+                    delegation = data.get("delegation_details", {})
+                    agent_type = delegation.get("agent_type", "unknown")
+                    print(f"📤 Published Task delegation to agent '{agent_type}'", file=sys.stderr)
+                    
+        except Exception as e:
+            if DEBUG:
+                print(f"❌ Failed to publish event hook.{event_type}: {e}", file=sys.stderr)
+    
+    def _get_git_branch(self, working_dir: str = None) -> str:
+        """Get git branch for the given directory with caching."""
+        # Use current working directory if not specified
+        if not working_dir:
+            working_dir = os.getcwd()
+        
+        # Check cache first (cache for 30 seconds)
+        current_time = time.time()
+        cache_key = working_dir
+        
+        if (
+            cache_key in self._git_branch_cache
+            and cache_key in self._git_branch_cache_time
+            and current_time - self._git_branch_cache_time[cache_key] < 30
+        ):
+            return self._git_branch_cache[cache_key]
+        
+        # Try to get git branch
+        try:
+            # Change to the working directory temporarily
+            original_cwd = os.getcwd()
+            os.chdir(working_dir)
+            
+            # Run git command to get current branch
+            result = subprocess.run(
+                ["git", "branch", "--show-current"],
+                capture_output=True,
+                text=True,
+                timeout=TimeoutConfig.QUICK_TIMEOUT
+            )
+            
+            # Restore original directory
+            os.chdir(original_cwd)
+            
+            if result.returncode == 0 and result.stdout.strip():
+                branch = result.stdout.strip()
+                # Cache the result
+                self._git_branch_cache[cache_key] = branch
+                self._git_branch_cache_time[cache_key] = current_time
+                return branch
+            else:
+                return "unknown"
+                
+        except Exception:
+            return "unknown"
+    
+    def _cleanup_old_entries(self):
+        """Clean up old entries to prevent memory growth."""
+        cutoff_time = time.time() - self.MAX_CACHE_AGE_SECONDS
+        
+        # Clean up delegation tracking dictionaries
+        for storage in [self.active_delegations, self.delegation_requests]:
+            if len(storage) > self.MAX_DELEGATION_TRACKING:
+                # Keep only the most recent entries
+                sorted_keys = sorted(storage.keys())
+                excess = len(storage) - self.MAX_DELEGATION_TRACKING
+                for key in sorted_keys[:excess]:
+                    del storage[key]
+        
+        # Clean up pending prompts
+        if len(self.pending_prompts) > self.MAX_PROMPT_TRACKING:
+            sorted_keys = sorted(self.pending_prompts.keys())
+            excess = len(self.pending_prompts) - self.MAX_PROMPT_TRACKING
+            for key in sorted_keys[:excess]:
+                del self.pending_prompts[key]
+        
+        # Clean up git branch cache
+        expired_keys = [
+            key
+            for key, cache_time in self._git_branch_cache_time.items()
+            if time.time() - cache_time > self.MAX_CACHE_AGE_SECONDS
+        ]
+        for key in expired_keys:
+            self._git_branch_cache.pop(key, None)
+            self._git_branch_cache_time.pop(key, None)
+    
+    def handle_event(self, event: dict):
+        """Process an event from Claude Code.
+        
+        Args:
+            event: The event dictionary from Claude
+        """
+        # Periodic cleanup
+        current_time = time.time()
+        if current_time - self._last_cleanup > 300:  # Every 5 minutes
+            self._cleanup_old_entries()
+            self._last_cleanup = current_time
+        
+        # Extract event details
+        event_type = event.get("type", "")
+        event_name = event.get("name", "")
+        
+        # Update session ID if present
+        if "sessionId" in event:
+            self.current_session_id = event["sessionId"]
+        
+        # Detect duplicate events
+        event_signature = f"{event_type}:{event_name}:{json.dumps(event.get('data', ''))[:100]}"
+        with _events_lock:
+            if event_signature in _recent_events:
+                if DEBUG:
+                    print(f"Skipping duplicate event: {event_type}", file=sys.stderr)
+                return
+            _recent_events.append(event_signature)
+        
+        # Route to appropriate handler
+        if event_type == "Start":
+            self.event_handlers.handle_start(event)
+        elif event_type == "Stop":
+            self.event_handlers.handle_stop(event)
+        elif event_type == "UserPrompt":
+            self.event_handlers.handle_user_prompt(event)
+        elif event_type == "AssistantResponse":
+            self.event_handlers.handle_assistant_response(event)
+        elif event_type == "SubagentStart":
+            self.event_handlers.handle_subagent_start(event)
+        elif event_type == "SubagentStop":
+            self.event_handlers.handle_subagent_stop(event)
+        elif event_type == "PreToolExecution" and event_name == "Task":
+            self.event_handlers.handle_task_delegation(event)
+        elif event_type == "PreToolExecution":
+            self.event_handlers.handle_pre_tool(event)
+        elif event_type == "PostToolExecution":
+            self.event_handlers.handle_post_tool(event)
+        elif event_type == "PromptCachingBetaStats":
+            # Ignore caching stats events
+            pass
+        else:
+            # Log unhandled events in debug mode
+            if DEBUG:
+                print(f"Unhandled event type: {event_type}", file=sys.stderr)
+
+
+def get_handler() -> HookHandler:
+    """Get or create the global hook handler instance.
+    
+    Returns:
+        HookHandler: The singleton handler instance
+    """
+    global _global_handler
+    if _global_handler is None:
+        with _handler_lock:
+            if _global_handler is None:
+                _global_handler = HookHandler()
+    return _global_handler
+
+
+def main():
+    """Main entry point for the hook handler."""
+    if DEBUG:
+        print("🎯 EventBus Hook Handler starting...", file=sys.stderr)
+    
+    handler = get_handler()
+    
+    # Set up signal handling for clean shutdown
+    def signal_handler(signum, frame):
+        if DEBUG:
+            print("\n👋 Hook handler shutting down...", file=sys.stderr)
+        sys.exit(0)
+    
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+    
+    # Process events from stdin
+    try:
+        while True:
+            # Check if data is available with timeout
+            readable, _, _ = select.select([sys.stdin], [], [], 0.1)
+            if readable:
+                line = sys.stdin.readline()
+                if not line:
+                    break
+                
+                try:
+                    event = json.loads(line.strip())
+                    handler.handle_event(event)
+                    
+                    # Acknowledge event
+                    print(json.dumps({"status": "ok"}))
+                    sys.stdout.flush()
+                    
+                except json.JSONDecodeError as e:
+                    if DEBUG:
+                        print(f"Invalid JSON: {e}", file=sys.stderr)
+                    print(json.dumps({"status": "error", "message": str(e)}))
+                    sys.stdout.flush()
+                except Exception as e:
+                    if DEBUG:
+                        print(f"Error processing event: {e}", file=sys.stderr)
+                    print(json.dumps({"status": "error", "message": str(e)}))
+                    sys.stdout.flush()
+                    
+    except KeyboardInterrupt:
+        if DEBUG:
+            print("\n👋 Hook handler interrupted", file=sys.stderr)
+    finally:
+        if DEBUG:
+            print("Hook handler exiting", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

claude_mpm/hooks/claude_hooks/response_tracking.py

@@ -203,7 +203,17 @@ class ResponseTrackingManager:
                     "files_modified": structured_response.get("files_modified", []),
                     "tools_used": structured_response.get("tools_used", []),
                     "remember": structured_response.get("remember"),
+                    "MEMORIES": structured_response.get("MEMORIES"),  # Complete memory replacement
                 }
+                
+                # Log if MEMORIES field is present  
+                if "MEMORIES" in structured_response and structured_response["MEMORIES"]:
+                    if DEBUG:
+                        memories_count = len(structured_response["MEMORIES"])
+                        print(
+                            f"Agent {agent_type} returned MEMORIES field with {memories_count} items",
+                            file=sys.stderr,
+                        )
 
                 # Check if task was completed for logging purposes
                 if structured_response.get("task_completed"):

claude_mpm/services/agents/deployment/agent_deployment.py

@@ -385,12 +385,23 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
             
             if use_multi_source:
                 # Use multi-source deployment to get highest version agents
-                template_files, agent_sources = self._get_multi_source_templates(
+                template_files, agent_sources, cleanup_results = self._get_multi_source_templates(
                     excluded_agents, config, agents_dir, force_rebuild
                 )
                 results["total"] = len(template_files)
                 results["multi_source"] = True
                 results["agent_sources"] = agent_sources
+                results["cleanup"] = cleanup_results
+                
+                # Log cleanup results if any agents were removed
+                if cleanup_results.get("removed"):
+                    self.logger.info(
+                        f"Cleaned up {len(cleanup_results['removed'])} outdated user agents"
+                    )
+                    for removed in cleanup_results["removed"]:
+                        self.logger.debug(
+                            f"  - Removed: {removed['name']} v{removed['version']} ({removed['reason']})"
+                        )
             else:
                 # Get and filter template files from single source
                 template_files = self._get_filtered_templates(excluded_agents, config)
@@ -516,11 +527,11 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
                 return False
 
             # Ensure target directory exists
-            agents_dir = target_dir / ".claude" / "agents"
-            agents_dir.mkdir(parents=True, exist_ok=True)
+            # target_dir should already be the agents directory
+            target_dir.mkdir(parents=True, exist_ok=True)
 
             # Build and deploy the agent
-            target_file = agents_dir / f"{agent_name}.md"
+            target_file = target_dir / f"{agent_name}.md"
 
             # Check if update is needed
             if not force_rebuild and target_file.exists():
@@ -618,7 +629,7 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
 
         deployer = SystemInstructionsDeployer(self.logger, self.working_directory)
         deployer.deploy_system_instructions(
-            target_dir, force_rebuild, results, self._is_project_specific_deployment()
+            target_dir, force_rebuild, results
         )
 
     def deploy_system_instructions_explicit(
@@ -629,11 +640,11 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
         
         This method should ONLY be called when the user explicitly requests
         deployment of system instructions through agent-manager commands.
-        It will deploy INSTRUCTIONS.md, MEMORY.md, and WORKFLOW.md to .claude-mpm/
-        directory (not .claude/).
+        It will deploy INSTRUCTIONS.md, MEMORY.md, and WORKFLOW.md to .claude/
+        directory in the project.
         
         Args:
-            target_dir: Target directory for deployment (defaults to .claude-mpm/)
+            target_dir: Target directory for deployment (ignored - always uses .claude/)
             force_rebuild: Force rebuild even if files exist
             
         Returns:
@@ -647,23 +658,19 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
         }
         
         try:
-            # Use .claude-mpm/ instead of .claude/
-            if target_dir is None:
-                if self._is_project_specific_deployment():
-                    target_dir = self.working_directory / ".claude-mpm"
-                else:
-                    target_dir = Path.home() / ".claude-mpm"
+            # Always use project's .claude directory
+            target_dir = self.working_directory / ".claude"
             
             # Ensure directory exists
             target_dir.mkdir(parents=True, exist_ok=True)
             
-            # Deploy using the modified deployer (targeting .claude-mpm/)
+            # Deploy using the deployer (targeting .claude/)
             from .system_instructions_deployer import SystemInstructionsDeployer
             deployer = SystemInstructionsDeployer(self.logger, self.working_directory)
             
-            # We'll need to pass .claude-mpm as the target
-            deployer.deploy_system_instructions_to_claude_mpm(
-                target_dir, force_rebuild, results, self._is_project_specific_deployment()
+            # Deploy to .claude directory
+            deployer.deploy_system_instructions(
+                target_dir, force_rebuild, results
             )
             
             self.logger.info(
@@ -764,32 +771,9 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
         """Determine the correct agents directory based on input."""
         from .agents_directory_resolver import AgentsDirectoryResolver
 
-        resolver = AgentsDirectoryResolver(
-            self.working_directory,
-            self._is_system_agent_deployment(),
-            self._is_project_specific_deployment(),
-        )
+        resolver = AgentsDirectoryResolver(self.working_directory)
         return resolver.determine_agents_directory(target_dir)
 
-    def _is_system_agent_deployment(self) -> bool:
-        """Check if this is a deployment of system agents."""
-        from .deployment_type_detector import DeploymentTypeDetector
-
-        return DeploymentTypeDetector.is_system_agent_deployment(self.templates_dir)
-
-    def _is_project_specific_deployment(self) -> bool:
-        """Check if deploying project-specific agents."""
-        from .deployment_type_detector import DeploymentTypeDetector
-
-        return DeploymentTypeDetector.is_project_specific_deployment(
-            self.templates_dir, self.working_directory
-        )
-
-    def _is_user_custom_deployment(self) -> bool:
-        """Check if deploying user custom agents."""
-        from .deployment_type_detector import DeploymentTypeDetector
-
-        return DeploymentTypeDetector.is_user_custom_deployment(self.templates_dir)
 
     def _initialize_deployment_results(
         self, agents_dir: Path, deployment_start_time: float
@@ -1125,7 +1109,7 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
     def _get_multi_source_templates(
         self, excluded_agents: List[str], config: Config, agents_dir: Path, 
         force_rebuild: bool = False
-    ) -> Tuple[List[Path], Dict[str, str]]:
+    ) -> Tuple[List[Path], Dict[str, str], Dict[str, Any]]:
         """Get agent templates from multiple sources with version comparison.
         
         WHY: This method uses the multi-source service to discover agents
@@ -1135,9 +1119,10 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
             excluded_agents: List of agents to exclude
             config: Configuration object
             agents_dir: Target deployment directory
+            force_rebuild: Whether to force rebuild
             
         Returns:
-            Tuple of (template_files, agent_sources)
+            Tuple of (template_files, agent_sources, cleanup_results)
         """
         # Determine source directories
         system_templates_dir = self.templates_dir
@@ -1158,14 +1143,15 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
             user_agents_dir = potential_user_dir
             self.logger.info(f"Found user agents at: {user_agents_dir}")
         
-        # Get agents with version comparison
-        agents_to_deploy, agent_sources = self.multi_source_service.get_agents_for_deployment(
+        # Get agents with version comparison and cleanup
+        agents_to_deploy, agent_sources, cleanup_results = self.multi_source_service.get_agents_for_deployment(
             system_templates_dir=system_templates_dir,
             project_agents_dir=project_agents_dir,
             user_agents_dir=user_agents_dir,
             working_directory=self.working_directory,
             excluded_agents=excluded_agents,
-            config=config
+            config=config,
+            cleanup_outdated=True  # Enable cleanup by default
         )
         
         # Compare with deployed versions if agents directory exists
@@ -1206,7 +1192,7 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
         # Convert to list of Path objects
         template_files = list(agents_to_deploy.values())
         
-        return template_files, agent_sources
+        return template_files, agent_sources, cleanup_results
 
     # ================================================================================
     # Interface Adapter Methods

claude_mpm/services/agents/deployment/agent_discovery_service.py

@@ -198,7 +198,10 @@ class AgentDiscoveryService:
                 "name": metadata.get("name", template_file.stem),
                 "description": metadata.get("description", "No description available"),
                 "version": template_data.get(
-                    "agent_version", template_data.get("version", "1.0.0")
+                    "agent_version", 
+                    template_data.get("version", 
+                        metadata.get("version", "1.0.0")
+                    )
                 ),
                 "tools": capabilities.get("tools", []),
                 "specializations": metadata.get(

claude_mpm/services/agents/deployment/agent_template_builder.py

@@ -136,7 +136,8 @@ class AgentTemplateBuilder:
         )
 
         # Extract custom metadata fields
-        agent_version = template_data.get("agent_version", "1.0.0")
+        metadata = template_data.get("metadata", {})
+        agent_version = template_data.get("agent_version") or template_data.get("version") or metadata.get("version", "1.0.0")
         agent_type = template_data.get("agent_type", "general")
         # Use the capabilities_model we already extracted earlier
         model_type = capabilities_model or "sonnet"
@@ -148,16 +149,24 @@ class AgentTemplateBuilder:
         else:
             claude_model = "inherit"
 
-        # Determine color based on agent type
-        color_map = {
-            "engineer": "blue",
-            "qa": "green",
-            "security": "red",
-            "research": "purple",
-            "documentation": "orange",
-            "ops": "gray",
-        }
-        color = color_map.get(agent_type, "blue")
+        # Determine color - prefer template's color, fallback to type-based defaults
+        template_metadata = template_data.get("metadata", {})
+        template_color = template_metadata.get("color")
+        
+        if template_color:
+            # Use the color specified in the template
+            color = template_color
+        else:
+            # Fallback to default color map based on agent type
+            color_map = {
+                "engineer": "blue",
+                "qa": "green",
+                "security": "red",
+                "research": "purple",
+                "documentation": "cyan",  # Changed default to match template preference
+                "ops": "gray",
+            }
+            color = color_map.get(agent_type, "blue")
 
         # Check if we should include tools field (only if significantly restricting)
         # Claude Code approach: omit tools field unless specifically restricting

claude_mpm/services/agents/deployment/agent_version_manager.py

@@ -254,8 +254,11 @@ class AgentVersionManager:
             template_data = json.loads(template_file.read_text())
 
             # Extract agent version from template
+            metadata = template_data.get("metadata", {})
             current_agent_version = self.parse_version(
-                template_data.get("agent_version") or template_data.get("version", 0)
+                template_data.get("agent_version") or 
+                template_data.get("version") or
+                metadata.get("version", 0)
             )
 
             # If old format detected, always trigger update for migration