claude-mpm 5.0.9__py3-none-any.whl → 5.4.41__py3-none-any.whl

claude_mpm/hooks/claude_hooks/hook_handler.py

@@ -304,6 +304,10 @@ class ClaudeHookHandler:
             # Perform periodic cleanup if needed
             if self.state_manager.increment_events_processed():
                 self.state_manager.cleanup_old_entries()
+                # Also cleanup old correlation files
+                from .correlation_manager import CorrelationManager
+
+                CorrelationManager.cleanup_old()
                 if DEBUG:
                     print(
                         f"🧹 Performed cleanup after {self.state_manager.events_processed} events",
@@ -390,6 +394,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")
@@ -413,21 +419,48 @@ 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,
+            "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:
+                error_message = str(e)
+                return_value = None
                 if DEBUG:
                     print(f"Error handling {hook_type}: {e}", file=sys.stderr)
+            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
 
@@ -472,6 +505,127 @@ 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,
+            "session_id": session_id,
+            "working_directory": working_dir,
+            "success": success,
+            "duration_ms": duration_ms,
+            "result_summary": summary,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+
+        # 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)
+
+        if DEBUG:
+            print(
+                f"📊 Hook execution event: {hook_type} - {duration_ms}ms - {'✅' if success else '❌'}",
+                file=sys.stderr,
+            )
+
+    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."""
         # Clean up connection manager if it exists

claude_mpm/hooks/claude_hooks/installer.py

@@ -202,8 +202,9 @@ main "$@"
         self.hooks_dir = self.claude_dir / "hooks"  # Kept for backward compatibility
         # Use settings.json for hooks (Claude Code reads from this file)
         self.settings_file = self.claude_dir / "settings.json"
-        # Keep reference to old file for migration
-        self.old_settings_file = self.claude_dir / "settings.json"
+        # There is no legacy settings file - this was a bug where both pointed to same file
+        # Setting to None to disable cleanup that was deleting freshly installed hooks
+        self.old_settings_file = None
         self._claude_version: Optional[str] = None
         self._hook_script_path: Optional[Path] = None
 
@@ -462,7 +463,9 @@ main "$@"
 
     def _cleanup_old_settings(self) -> None:
         """Remove hooks from old settings.json file if present."""
-        if not self.old_settings_file.exists():
+        # No-op: old_settings_file was pointing to same file as settings_file (bug)
+        # This was causing freshly installed hooks to be immediately deleted
+        if self.old_settings_file is None or not self.old_settings_file.exists():
             return
 
         try:
@@ -518,15 +521,31 @@ main "$@"
                 }
             ]
 
-        # Non-tool events don't need a matcher
-        non_tool_events = ["UserPromptSubmit", "Stop", "SubagentStop", "SubagentStart"]
-        for event_type in non_tool_events:
+        # Simple events (no subtypes, no matcher needed)
+        simple_events = ["Stop", "SubagentStop", "SubagentStart"]
+        for event_type in simple_events:
             settings["hooks"][event_type] = [
                 {
                     "hooks": [hook_command],
                 }
             ]
 
+        # SessionStart needs matcher for subtypes (startup, resume)
+        settings["hooks"]["SessionStart"] = [
+            {
+                "matcher": "*",  # Match all SessionStart subtypes
+                "hooks": [hook_command],
+            }
+        ]
+
+        # UserPromptSubmit needs matcher for potential subtypes
+        settings["hooks"]["UserPromptSubmit"] = [
+            {
+                "matcher": "*",
+                "hooks": [hook_command],
+            }
+        ]
+
         # Write settings to settings.json
         with self.settings_file.open("w") as f:
             json.dump(settings, f, indent=2)
@@ -650,9 +669,13 @@ main "$@"
                 old_script.unlink()
                 self.logger.info(f"Removed old deployed script: {old_script}")
 
-            # Remove from Claude settings (both old and new locations)
-            for settings_path in [self.settings_file, self.old_settings_file]:
-                if settings_path.exists():
+            # Remove from Claude settings
+            settings_paths = [self.settings_file]
+            if self.old_settings_file is not None:
+                settings_paths.append(self.old_settings_file)
+
+            for settings_path in settings_paths:
+                if settings_path and settings_path.exists():
                     with settings_path.open() as f:
                         settings = json.load(f)
 
@@ -763,7 +786,7 @@ main "$@"
                 pass
 
         # Also check old settings file
-        if self.old_settings_file.exists():
+        if self.old_settings_file is not None and self.old_settings_file.exists():
             try:
                 with self.old_settings_file.open() as f:
                     old_settings = json.load(f)

claude_mpm/hooks/claude_hooks/memory_integration.py

@@ -5,8 +5,36 @@ This module provides utilities for integrating with the memory system,
 including pre and post delegation hooks.
 """
 
+import logging
 import os
 import sys
+
+# Install-type-aware logging configuration BEFORE kuzu-memory imports
+# This overrides kuzu-memory's WARNING-level basicConfig (fixes 1M-445)
+# but respects production install silence
+try:
+    from claude_mpm.core.unified_paths import DeploymentContext, PathContext
+
+    context = PathContext.detect_deployment_context()
+
+    # Only configure verbose logging for development/editable installs
+    # Production installs remain silent by default
+    if context in (DeploymentContext.DEVELOPMENT, DeploymentContext.EDITABLE_INSTALL):
+        logging.basicConfig(
+            level=logging.INFO,
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            force=True,  # Python 3.8+ - reconfigures root logger
+            stream=sys.stderr,
+        )
+except ImportError:
+    # Fallback: if unified_paths not available, configure logging
+    # This maintains backward compatibility
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        force=True,
+        stream=sys.stderr,
+    )
 from datetime import datetime, timezone
 from typing import Optional
 

claude_mpm/hooks/claude_hooks/response_tracking.py

@@ -18,8 +18,7 @@ DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
 
 # Response tracking integration
 # NOTE: ResponseTracker import moved to _initialize_response_tracking() for lazy loading
-# This prevents unnecessary import of base_agent_loader and other heavy dependencies
-# when hooks don't need response tracking
+# This prevents unnecessary import of heavy dependencies when hooks don't need response tracking
 RESPONSE_TRACKING_AVAILABLE = (
     True  # Assume available, will check on actual initialization
 )
@@ -51,7 +50,7 @@ class ResponseTrackingManager:
         response tracking without code changes.
 
         NOTE: ResponseTracker is imported lazily here to avoid loading
-        base_agent_loader and other heavy dependencies unless actually needed.
+        heavy dependencies unless actually needed.
         """
         try:
             # Lazy import of ResponseTracker to avoid unnecessary dependency loading

claude_mpm/hooks/claude_hooks/services/connection_manager.py

@@ -58,7 +58,7 @@ except ImportError:
                 (),
                 {
                     "to_dict": lambda: {
-                        "event": "claude_event",
+                        "event": "mpm_event",
                         "type": event_data.get("type", "unknown"),
                         "subtype": event_data.get("subtype", "generic"),
                         "timestamp": event_data.get(
@@ -115,14 +115,38 @@ class ConnectionManagerService:
         - Fallback: HTTP POST for reliability when direct connection fails
         - Eliminates duplicate events from multiple emission paths
         """
+        # Extract tool_call_id from data if present for correlation
+        tool_call_id = data.get("tool_call_id")
+
         # Create event data for normalization
+        # Extract session_id (try both camelCase and snake_case)
+        session_id = data.get("session_id") or data.get("sessionId")
+
+        # Extract working directory for project identification
+        # Try multiple field names for maximum compatibility
+        cwd = (
+            data.get("cwd")
+            or data.get("working_directory")
+            or data.get("workingDirectory")
+        )
+
+        # For hook_execution events, extract the actual hook type from data
+        # Otherwise use "hook" as the type
+        if event == "hook_execution":
+            hook_type = data.get("hook_type", "unknown")
+            event_type = hook_type
+        else:
+            event_type = "hook"
+
         raw_event = {
-            "type": "hook",
-            "subtype": event,  # e.g., "user_prompt", "pre_tool", "subagent_stop"
+            "type": event_type,  # Use actual hook type for hook_execution, "hook" otherwise
+            "subtype": event,  # e.g., "user_prompt", "pre_tool", "subagent_stop", "execution"
             "timestamp": datetime.now(timezone.utc).isoformat(),
             "data": data,
-            "source": "claude_hooks",  # Identify the source
-            "session_id": data.get("sessionId"),  # Include session if available
+            "source": "mpm_hook",  # Identify the source as mpm_hook
+            "session_id": session_id,  # Include session if available (supports both naming conventions)
+            "cwd": cwd,  # Add working directory at top level for easy frontend access
+            "correlation_id": tool_call_id,  # Set from tool_call_id for event correlation
         }
 
         # Normalize the event using EventNormalizer for consistent schema
@@ -150,7 +174,7 @@ class ConnectionManagerService:
         if self.connection_pool:
             try:
                 # Emit to Socket.IO server directly
-                self.connection_pool.emit("claude_event", claude_event_data)
+                self.connection_pool.emit("mpm_event", claude_event_data)
                 if DEBUG:
                     print(f"✅ Emitted via connection pool: {event}", file=sys.stderr)
                 return  # Success - no need for fallback

claude_mpm/hooks/memory_integration_hook.py

@@ -13,6 +13,7 @@ agent outputs because:
 """
 
 import re
+from datetime import datetime
 from typing import Dict, List
 
 from claude_mpm.core.config import Config
@@ -47,6 +48,16 @@ except ImportError as e:
     SOCKETIO_AVAILABLE = False
     get_socketio_server = None
 
+# Try to import event bus with fallback handling
+try:
+    from claude_mpm.services.event_bus.event_bus import EventBus
+
+    EVENT_BUS_AVAILABLE = True
+except ImportError as e:
+    logger.debug(f"EventBus not available: {e}")
+    EVENT_BUS_AVAILABLE = False
+    EventBus = None
+
 
 class MemoryPreDelegationHook(PreDelegationHook):
     """Inject agent memory into delegation context.
@@ -83,6 +94,16 @@ class MemoryPreDelegationHook(PreDelegationHook):
             logger.info("Memory manager not available - hook will be inactive")
             self.memory_manager = None
 
+        # Initialize event bus for observability
+        if EVENT_BUS_AVAILABLE and EventBus:
+            try:
+                self.event_bus = EventBus.get_instance()
+            except Exception as e:
+                logger.debug(f"Failed to get EventBus instance: {e}")
+                self.event_bus = None
+        else:
+            self.event_bus = None
+
     def execute(self, context: HookContext) -> HookResult:
         """Add agent memory to delegation context.
 
@@ -137,7 +158,31 @@ INSTRUCTIONS: Review your memory above before proceeding. Apply learned patterns
 
                     logger.info(f"Injected memory for agent '{agent_id}'")
 
-                    # Emit Socket.IO event for memory injected
+                    # Calculate memory size for observability
+                    memory_size = len(memory_content)
+
+                    # Emit event bus event for observability
+                    if self.event_bus:
+                        try:
+                            # Determine memory source (project or user level)
+                            # This is inferred from the memory manager's behavior
+                            memory_source = (
+                                "runtime"  # Runtime loading from memory manager
+                            )
+
+                            self.event_bus.publish(
+                                "agent.memory.loaded",
+                                {
+                                    "agent_id": agent_id,
+                                    "memory_source": memory_source,
+                                    "memory_size": memory_size,
+                                    "timestamp": datetime.now(datetime.UTC).isoformat(),
+                                },
+                            )
+                        except Exception as event_error:
+                            logger.debug(f"EventBus publish failed: {event_error}")
+
+                    # Emit Socket.IO event for memory injected (legacy compatibility)
                     try:
                         socketio_server = get_socketio_server()
                         # Calculate size of injected content

claude_mpm/init.py

@@ -141,25 +141,6 @@ class ProjectInitializer:
             if not gitignore.exists():
                 gitignore.write_text("logs/\n*.log\n*.pyc\n__pycache__/\n")
 
-            # Also ensure MCP directories are in main project .gitignore
-            try:
-                from claude_mpm.services.project.project_organizer import (
-                    ProjectOrganizer,
-                )
-
-                # Check if we're in a git repository
-                if (project_root / ".git").exists():
-                    organizer = ProjectOrganizer(project_root)
-                    # This will add MCP directories and other standard patterns
-                    organizer.update_gitignore()
-                    self.logger.debug(
-                        "Updated project .gitignore with MCP and standard patterns"
-                    )
-            except Exception as e:
-                self.logger.debug(
-                    f"Could not update project gitignore with MCP patterns: {e}"
-                )
-
             # Log successful creation with details
             self.logger.info(f"Initialized project directory at {self.project_dir}")
             self.logger.debug("Created directories: agents, config, responses, logs")
@@ -182,6 +163,9 @@ class ProjectInitializer:
                         f"✓ Found {agent_count} project agent(s) in .claude-mpm/agents/"
                     )
 
+            # Verify and deploy PM skills (non-blocking)
+            self._verify_and_deploy_pm_skills(project_root, is_mcp_mode)
+
             return True
 
         except Exception as e:
@@ -189,6 +173,66 @@ class ProjectInitializer:
             print(f"✗ Failed to create .claude-mpm/ directory: {e}")
             return False
 
+    def _verify_and_deploy_pm_skills(
+        self, project_root: Path, is_mcp_mode: bool = False
+    ) -> None:
+        """Verify PM skills are deployed and auto-deploy if missing.
+
+        Non-blocking operation that gracefully handles errors.
+
+        Args:
+            project_root: Project root directory
+            is_mcp_mode: Whether running in MCP mode (suppress console output)
+        """
+        try:
+            from claude_mpm.services.pm_skills_deployer import PMSkillsDeployerService
+
+            deployer = PMSkillsDeployerService()
+            result = deployer.verify_pm_skills(project_root)
+
+            if not result.verified:
+                # Log warnings
+                for warning in result.warnings:
+                    self.logger.warning(warning)
+
+                # Auto-deploy PM skills
+                self.logger.info("Auto-deploying PM skills...")
+                deploy_result = deployer.deploy_pm_skills(project_root)
+
+                if deploy_result.success:
+                    self.logger.info(
+                        f"PM skills deployed: {len(deploy_result.deployed)} deployed, "
+                        f"{len(deploy_result.skipped)} skipped"
+                    )
+
+                    # Print to console if not in MCP mode
+                    if not is_mcp_mode:
+                        if deploy_result.deployed:
+                            print(
+                                f"✓ Deployed {len(deploy_result.deployed)} PM skill(s) "
+                                f"to .claude-mpm/skills/pm/"
+                            )
+                else:
+                    self.logger.warning(
+                        f"PM skills deployment had errors: {len(deploy_result.errors)}"
+                    )
+                    if not is_mcp_mode and deploy_result.errors:
+                        print(f"⚠ PM skills deployment had {len(deploy_result.errors)} error(s)")
+            else:
+                # Skills verified successfully
+                registry = deployer._load_registry(project_root)
+                skill_count = len(registry.get("skills", []))
+                self.logger.debug(f"PM skills verified: {skill_count} skills")
+
+                if not is_mcp_mode and skill_count > 0:
+                    print(f"✓ Verified {skill_count} PM skill(s)")
+
+        except ImportError:
+            self.logger.debug("PM skills deployer not available")
+        except Exception as e:
+            self.logger.warning(f"PM skills verification failed: {e}")
+            # Don't print to console - this is a non-critical failure
+
     def _migrate_project_agents(self):
         """Migrate agents from old subdirectory structure to direct agents directory.
 

claude_mpm/models/agent_definition.py

@@ -103,6 +103,10 @@ class AgentMetadata:
     author: Optional[str] = None
     tags: List[str] = field(default_factory=list)
     specializations: List[str] = field(default_factory=list)
+    # NEW: Collection metadata for enhanced agent matching
+    collection_id: Optional[str] = None  # Format: owner/repo-name
+    source_path: Optional[str] = None  # Relative path in repository
+    canonical_id: Optional[str] = None  # Format: collection_id:agent_id
 
     def increment_serial_version(self) -> None:
         """Increment the patch version number.
@@ -181,6 +185,9 @@ class AgentDefinition:
                 "author": self.metadata.author,
                 "tags": self.metadata.tags,
                 "specializations": self.metadata.specializations,
+                "collection_id": self.metadata.collection_id,
+                "source_path": self.metadata.source_path,
+                "canonical_id": self.metadata.canonical_id,
             },
             "primary_role": self.primary_role,
             "when_to_use": self.when_to_use,

claude_mpm/models/git_repository.py

@@ -34,7 +34,7 @@ class GitRepository:
     def cache_path(self) -> Path:
         """Return cache directory path for this repository.
 
-        Cache structure: ~/.claude-mpm/cache/remote-agents/{owner}/{repo}/{subdirectory}/
+        Cache structure: ~/.claude-mpm/cache/agents/{owner}/{repo}/{subdirectory}/
 
         Returns:
             Absolute path to cache directory for this repository
@@ -45,10 +45,10 @@ class GitRepository:
             ...     subdirectory="agents"
             ... )
             >>> repo.cache_path
-            Path('/Users/user/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents/agents')
+            Path('/Users/user/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents/agents')
         """
         home = Path.home()
-        base_cache = home / ".claude-mpm" / "cache" / "remote-agents"
+        base_cache = home / ".claude-mpm" / "cache" / "agents"
 
         # Extract owner and repo from URL
         owner, repo = self._parse_github_url(self.url)