claude-mpm 5.4.91__py3-none-any.whl → 5.4.95__py3-none-any.whl

claude_mpm/hooks/claude_hooks/event_handlers.py

@@ -115,7 +115,7 @@ class EventHandlers:
                             f"Stored prompt for comprehensive tracking: session {session_id[:8]}...",
                             file=sys.stderr,
                         )
-        except Exception:
+        except Exception:  # nosec B110
             # Response tracking is optional - silently continue if it fails
             pass
 
@@ -297,7 +297,7 @@ class EventHandlers:
             mhm = getattr(self.hook_handler, "memory_hook_manager", None)
             if mhm and hasattr(mhm, "trigger_pre_delegation_hook"):
                 mhm.trigger_pre_delegation_hook(agent_type, tool_input, session_id)
-        except Exception:
+        except Exception:  # nosec B110
             # Memory hooks are optional
             pass
 
@@ -390,7 +390,7 @@ class EventHandlers:
             os.chdir(working_dir)
 
             # Run git command to get current branch
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B603 B607
                 ["git", "branch", "--show-current"],
                 capture_output=True,
                 text=True,
@@ -500,7 +500,7 @@ class EventHandlers:
                 mhm = getattr(self.hook_handler, "memory_hook_manager", None)
                 if mhm and hasattr(mhm, "trigger_post_delegation_hook"):
                     mhm.trigger_post_delegation_hook(agent_type, event, session_id)
-            except Exception:
+            except Exception:  # nosec B110
                 # Memory hooks are optional
                 pass
 
@@ -514,7 +514,7 @@ class EventHandlers:
                     rtm.track_agent_response(
                         session_id, agent_type, event, delegation_requests
                     )
-            except Exception:
+            except Exception:  # nosec B110
                 # Response tracking is optional
                 pass
 
@@ -576,13 +576,49 @@ class EventHandlers:
         if DEBUG:
             self._log_stop_event_debug(event, session_id, metadata)
 
+        # Auto-pause integration (independent of response tracking)
+        # WHY HERE: Auto-pause must work even when response_tracking is disabled
+        # Extract usage data directly from event and trigger auto-pause if thresholds crossed
+        if "usage" in event:
+            auto_pause = getattr(self.hook_handler, "auto_pause_handler", None)
+            if auto_pause:
+                try:
+                    usage_data = event["usage"]
+                    metadata["usage"] = {
+                        "input_tokens": usage_data.get("input_tokens", 0),
+                        "output_tokens": usage_data.get("output_tokens", 0),
+                        "cache_creation_input_tokens": usage_data.get(
+                            "cache_creation_input_tokens", 0
+                        ),
+                        "cache_read_input_tokens": usage_data.get(
+                            "cache_read_input_tokens", 0
+                        ),
+                    }
+
+                    threshold_crossed = auto_pause.on_usage_update(metadata["usage"])
+                    if threshold_crossed:
+                        warning = auto_pause.emit_threshold_warning(threshold_crossed)
+                        print(f"\n⚠️  {warning}", file=sys.stderr)
+
+                        if DEBUG:
+                            print(
+                                f"  - Auto-pause threshold crossed: {threshold_crossed}",
+                                file=sys.stderr,
+                            )
+                except Exception as e:
+                    if DEBUG:
+                        print(
+                            f"Auto-pause error in handle_stop_fast: {e}",
+                            file=sys.stderr,
+                        )
+
         # Track response if enabled
         try:
             rtm = getattr(self.hook_handler, "response_tracking_manager", None)
             if rtm and hasattr(rtm, "track_stop_response"):
                 pending_prompts = getattr(self.hook_handler, "pending_prompts", {})
                 rtm.track_stop_response(event, session_id, metadata, pending_prompts)
-        except Exception:
+        except Exception:  # nosec B110
             # Response tracking is optional
             pass
 
@@ -624,7 +660,7 @@ class EventHandlers:
                 f"  - response_tracker exists: {tracker_exists}",
                 file=sys.stderr,
             )
-        except Exception:
+        except Exception:  # nosec B110
             # If debug logging fails, just skip it
             pass
 
@@ -690,7 +726,7 @@ class EventHandlers:
         try:
             # Get the original request data (with fuzzy matching fallback)
             delegation_requests = getattr(self.hook_handler, "delegation_requests", {})
-            request_info = delegation_requests.get(session_id)
+            request_info = delegation_requests.get(session_id)  # nosec B113
 
             # If exact match fails, try partial matching
             if not request_info and session_id:
@@ -715,7 +751,7 @@ class EventHandlers:
                                 f"  - ✅ Fuzzy match found: {stored_sid[:16]}...",
                                 file=sys.stderr,
                             )
-                        request_info = delegation_requests.get(stored_sid)
+                        request_info = delegation_requests.get(stored_sid)  # nosec B113
                         # Update the key to use the current session_id for consistency
                         if request_info:
                             delegation_requests[session_id] = request_info
@@ -822,7 +858,7 @@ class EventHandlers:
             if rtm and hasattr(rtm, "track_assistant_response"):
                 pending_prompts = getattr(self.hook_handler, "pending_prompts", {})
                 rtm.track_assistant_response(event, pending_prompts)
-        except Exception:
+        except Exception:  # nosec B110
             # Response tracking is optional
             pass
 

claude_mpm/hooks/claude_hooks/hook_handler.py

@@ -550,13 +550,15 @@ class ClaudeHookHandler:
         # Build hook execution data
         hook_data = {
             "hook_name": hook_type,
-            "hook_type": hook_type,
+            "hook_type": hook_type,  # Actual hook type (PreToolUse, UserPromptSubmit, etc.)
+            "hook_event_type": hook_type,  # Additional field for clarity
             "session_id": session_id,
             "working_directory": working_dir,
             "success": success,
             "duration_ms": duration_ms,
             "result_summary": summary,
             "timestamp": datetime.now(timezone.utc).isoformat(),
+            "source": "claude_hook_handler",  # Explicit source identification
         }
 
         # Add error information if present

claude_mpm/hooks/claude_hooks/response_tracking.py

@@ -306,6 +306,8 @@ class ResponseTrackingManager:
                         )
 
                 # Capture Claude API usage data if available
+                # NOTE: Usage data is already captured in metadata by handle_stop_fast()
+                # which also handles auto-pause triggering (even when response tracking disabled)
                 if "usage" in event:
                     usage_data = event["usage"]
                     metadata["usage"] = {
@@ -327,22 +329,6 @@ class ResponseTrackingManager:
                             file=sys.stderr,
                         )
 
-                # Auto-pause integration
-                auto_pause = getattr(self, "auto_pause_handler", None)
-                if auto_pause and metadata.get("usage"):
-                    try:
-                        threshold_crossed = auto_pause.on_usage_update(
-                            metadata["usage"]
-                        )
-                        if threshold_crossed:
-                            warning = auto_pause.emit_threshold_warning(
-                                threshold_crossed
-                            )
-                            print(f"\n⚠️  {warning}", file=sys.stderr)
-                    except Exception as e:
-                        if DEBUG:
-                            print(f"Auto-pause error: {e}", file=sys.stderr)
-
                 # Track the main Claude response
                 file_path = self.response_tracker.track_response(
                     agent_name="claude_main",

claude_mpm/hooks/claude_hooks/services/connection_manager.py

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

claude_mpm/services/agents/cache_git_manager.py

@@ -88,7 +88,7 @@ class CacheGitManager:
         if self.repo_path:
             logger.debug(f"Initialized CacheGitManager for repo: {self.repo_path}")
         else:
-            logger.warning(f"Cache path is not a git repository: {cache_path}")
+            logger.debug(f"Cache path is not a git repository: {cache_path}")
 
     def _find_git_root(self) -> Optional[Path]:
         """

claude_mpm/services/agents/deployment/remote_agent_discovery_service.py

@@ -491,6 +491,9 @@ class RemoteAgentDiscoveryService:
             "SKILL.md",
             "SKILLS.md",
             "skill-template.md",
+            # Legacy agents superseded by newer versions
+            # TODO: Remove after bobmatnyc/claude-mpm-agents#XXX is merged
+            "memory-manager.md",  # Superseded by memory-manager-agent.md (v1.2.0)
         }
         md_files = [f for f in md_files if f.name not in excluded_files]
 

claude_mpm/services/diagnostics/checks/agent_sources_check.py

@@ -69,6 +69,13 @@ class AgentSourcesCheck(BaseDiagnosticCheck):
                     fix_command="claude-mpm agent-source add https://github.com/bobmatnyc/claude-mpm-agents",
                     fix_description="Add default system repository",
                     sub_results=sub_results if self.verbose else [],
+                    explanation=(
+                        "Agent sources define where Claude MPM discovers specialized agents. "
+                        "Without configured sources, no agents can be deployed or delegated to. "
+                        "This is a critical component for multi-agent workflows."
+                    ),
+                    severity="critical",
+                    doc_link="https://github.com/bobmatnyc/claude-mpm/blob/main/docs/guides/agent-sources.md",
                 )
 
             # Check 2: Configuration is valid YAML
@@ -141,16 +148,30 @@ class AgentSourcesCheck(BaseDiagnosticCheck):
                 r for r in sub_results if r.status == ValidationSeverity.WARNING
             ]
 
+            # Determine status and enhanced troubleshooting info (issue #125)
             if error_results:
                 status = ValidationSeverity.ERROR
                 message = f"Agent sources have {len(error_results)} critical issue(s)"
                 fix_command = None
                 fix_description = None
+                severity = "critical"
+                explanation = (
+                    "Agent sources are the foundation of Claude MPM's delegation system. "
+                    "Critical errors prevent agent discovery and deployment, blocking "
+                    "multi-agent workflows entirely."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/guides/agent-sources.md"
             elif warning_results:
                 status = ValidationSeverity.WARNING
                 message = f"Agent sources have {len(warning_results)} minor issue(s)"
                 fix_command = "claude-mpm agent-source update"
                 fix_description = "Update all sources to refresh cache"
+                severity = "medium"
+                explanation = (
+                    "Some agent sources have issues but the system can still function. "
+                    "You may have limited agent availability or outdated cache."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/guides/agent-sources.md"
             else:
                 status = OperationResult.SUCCESS
                 enabled_count = details["enabled_sources"]
@@ -158,6 +179,12 @@ class AgentSourcesCheck(BaseDiagnosticCheck):
                 message = f"All checks passed ({enabled_count} source(s), {agents_count} agent(s))"
                 fix_command = None
                 fix_description = None
+                severity = "info"
+                explanation = (
+                    "Agent sources are properly configured and agents are discoverable. "
+                    "You can delegate tasks to specialized agents."
+                )
+                doc_link = ""
 
             return DiagnosticResult(
                 category=self.category,
@@ -167,6 +194,9 @@ class AgentSourcesCheck(BaseDiagnosticCheck):
                 fix_command=fix_command,
                 fix_description=fix_description,
                 sub_results=sub_results if self.verbose else [],
+                explanation=explanation,
+                severity=severity,
+                doc_link=doc_link,
             )
 
         except Exception as e:

claude_mpm/services/diagnostics/checks/configuration_check.py

@@ -63,12 +63,36 @@ class ConfigurationCheck(BaseDiagnosticCheck):
                 status = OperationResult.SUCCESS
                 message = "Configuration is valid"
 
+            # Add enhanced troubleshooting info (issue #125)
+            severity = "medium"
+            explanation = ""
+            doc_link = ""
+
+            if status == ValidationSeverity.ERROR:
+                severity = "high"
+                explanation = (
+                    "Configuration files control how Claude MPM behaves. Critical errors "
+                    "in configuration may prevent features from working correctly or cause "
+                    "unexpected behavior."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/configuration.md"
+            elif status == ValidationSeverity.WARNING:
+                severity = "low"
+                explanation = (
+                    "Configuration has minor issues that may affect optional features. "
+                    "Core functionality should still work."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/configuration.md"
+
             return DiagnosticResult(
                 category=self.category,
                 status=status,
                 message=message,
                 details=details,
                 sub_results=sub_results if self.verbose else [],
+                explanation=explanation,
+                severity=severity,
+                doc_link=doc_link,
             )
 
         except Exception as e:

claude_mpm/services/diagnostics/checks/installation_check.py

@@ -65,12 +65,34 @@ class InstallationCheck(BaseDiagnosticCheck):
                 status = OperationResult.SUCCESS
                 message = "Installation is healthy"
 
+            # Determine severity and explanation based on status (issue #125)
+            severity = "medium"
+            explanation = ""
+            doc_link = ""
+
+            if status == ValidationSeverity.ERROR:
+                severity = "high"
+                explanation = (
+                    "Claude MPM installation verification failed. Critical components are missing "
+                    "or misconfigured, which will prevent the system from functioning properly."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/installation.md"
+            elif status == ValidationSeverity.WARNING:
+                severity = "medium"
+                explanation = (
+                    "Installation is functional but has minor issues. These may affect "
+                    "performance or features but won't prevent basic operation."
+                )
+
             return DiagnosticResult(
                 category=self.category,
                 status=status,
                 message=message,
                 details=details,
                 sub_results=sub_results if self.verbose else [],
+                explanation=explanation,
+                severity=severity,
+                doc_link=doc_link,
             )
 
         except Exception as e:

claude_mpm/services/diagnostics/checks/mcp_services_check.py

@@ -216,12 +216,35 @@ class MCPServicesCheck(BaseDiagnosticCheck):
                 status = ValidationSeverity.WARNING
                 message = f"All {total_services} MCP services installed but connections not tested"
 
+            # Enhanced troubleshooting info (issue #125)
+            severity = "medium"
+            explanation = ""
+            doc_link = ""
+
+            if status == ValidationSeverity.ERROR:
+                severity = "high"
+                explanation = (
+                    "MCP services provide enhanced capabilities like vector search, browser automation, "
+                    "and ticket management. Critical errors prevent these services from functioning."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/mcp-services.md"
+            elif status == ValidationSeverity.WARNING:
+                severity = "low"
+                explanation = (
+                    "MCP services are optional but provide powerful features. "
+                    "Some services may not be installed or configured properly."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/mcp-services.md"
+
             return DiagnosticResult(
                 category=self.category,
                 status=status,
                 message=message,
                 details=details,
                 sub_results=sub_results if self.verbose else [],
+                explanation=explanation,
+                severity=severity,
+                doc_link=doc_link,
             )
 
         except Exception as e:

claude_mpm/services/diagnostics/doctor_reporter.py

@@ -28,6 +28,15 @@ class DoctorReporter:
         OperationResult.SKIPPED: "⏭️ ",
     }
 
+    # Severity level emojis (issue #125)
+    SEVERITY_SYMBOLS = {
+        "critical": "🔴",
+        "high": "🟠",
+        "medium": "🟡",
+        "low": "🟢",
+        "info": "🔵",
+    }
+
     # ANSI color codes
     COLORS = {
         "reset": "\033[0m",
@@ -93,8 +102,15 @@ class DoctorReporter:
         symbol = self.STATUS_SYMBOLS.get(result.status, "?")
         color = self._get_status_color(result.status)
 
+        # Add severity indicator if present (issue #125)
+        severity_prefix = ""
+        if result.severity and result.severity != "medium":
+            severity_symbol = self.SEVERITY_SYMBOLS.get(result.severity, "")
+            if severity_symbol:
+                severity_prefix = f"{severity_symbol} {result.severity.upper()}: "
+
         # Main result line
-        line = f"{indent_str}{symbol} {result.category}: "
+        line = f"{indent_str}{severity_prefix}{symbol} {result.category}: "
 
         if result.status == OperationResult.SUCCESS:
             line += self._color("OK", color)
@@ -111,6 +127,15 @@ class DoctorReporter:
         message_indent = "   " + indent_str
         print(f"{message_indent}{result.message}")
 
+        # Explanation (issue #125)
+        if result.explanation:
+            # Format multi-line explanations with proper indentation
+            explanation_lines = result.explanation.split("\n")
+            for explanation_line in explanation_lines:
+                print(
+                    f"{message_indent}{self._color(explanation_line.strip(), 'gray')}"
+                )
+
         # Details (in verbose mode)
         if self.verbose and result.details:
             for key, value in result.details.items():
@@ -126,6 +151,11 @@ class DoctorReporter:
             if result.fix_description:
                 print(f"{fix_indent}  {self._color(result.fix_description, 'gray')}")
 
+        # Documentation link (issue #125)
+        if result.doc_link:
+            doc_indent = "   " + indent_str
+            print(f"{doc_indent}{self._color('📖 Docs:', 'blue')} {result.doc_link}")
+
         # Sub-results (in verbose mode)
         if self.verbose and result.sub_results:
             for sub_result in result.sub_results:

claude_mpm/services/diagnostics/models.py

@@ -51,9 +51,14 @@ class DiagnosticResult:
     fix_description: Optional[str] = None
     sub_results: List["DiagnosticResult"] = field(default_factory=list)
 
+    # Enhanced troubleshooting fields (issue #125)
+    explanation: str = ""  # What this check means and why it matters
+    severity: str = "medium"  # critical, high, medium, low, info
+    doc_link: str = ""  # Link to relevant documentation
+
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary for JSON serialization."""
-        return {
+        result = {
             "category": self.category,
             "status": self.status.value,
             "message": self.message,
@@ -62,6 +67,14 @@ class DiagnosticResult:
             "fix_description": self.fix_description,
             "sub_results": [r.to_dict() for r in self.sub_results],
         }
+        # Include enhanced fields if present
+        if self.explanation:
+            result["explanation"] = self.explanation
+        if self.severity != "medium":
+            result["severity"] = self.severity
+        if self.doc_link:
+            result["doc_link"] = self.doc_link
+        return result
 
     @property
     def has_issues(self) -> bool:

claude_mpm/services/monitor/daemon_manager.py

@@ -95,10 +95,10 @@ class DaemonManager:
     def _get_default_log_file(self) -> Path:
         """Get default log file path with port number to support multiple daemons."""
         project_root = Path.cwd()
-        claude_mpm_dir = project_root / ".claude-mpm"
-        claude_mpm_dir.mkdir(exist_ok=True)
+        logs_dir = project_root / ".claude-mpm" / "logs"
+        logs_dir.mkdir(parents=True, exist_ok=True)
         # Include port in filename to support multiple daemon instances
-        return claude_mpm_dir / f"monitor-daemon-{self.port}.log"
+        return logs_dir / f"monitor-daemon-{self.port}.log"
 
     def cleanup_port_conflicts(self, max_retries: int = 3) -> bool:
         """Clean up any processes using the daemon port.
@@ -649,14 +649,24 @@ class DaemonManager:
 
                 # Wait for the subprocess to write its PID file and bind to port
                 # The subprocess will write the PID file after it starts successfully
-                max_wait = 10  # seconds
+                # Allow configuration via environment variable (default 30s to account for agent/skill sync)
+                max_wait = int(os.environ.get("CLAUDE_MPM_MONITOR_TIMEOUT", "30"))
                 start_time = time.time()
                 pid_file_found = False
                 port_bound = False
+                last_progress_log = 0.0
 
                 self.logger.debug(f"Waiting up to {max_wait}s for daemon to start...")
 
                 while time.time() - start_time < max_wait:
+                    # Log progress every 5 seconds to show we're waiting
+                    elapsed = time.time() - start_time
+                    if elapsed - last_progress_log >= 5.0:
+                        self.logger.info(
+                            f"Waiting for monitor daemon... ({int(elapsed)}s elapsed, syncing agents/skills)"
+                        )
+                        last_progress_log = elapsed
+
                     # Check if process is still running
                     returncode = process.poll()
                     if returncode is not None:
@@ -976,6 +986,7 @@ class DaemonManager:
                 os.dup2(null_in.fileno(), sys.stdin.fileno())
 
             # Redirect stdout and stderr to log file
+            # Ensure logs directory exists
             self.log_file.parent.mkdir(parents=True, exist_ok=True)
             with self.log_file.open("a") as log_out:
                 os.dup2(log_out.fileno(), sys.stdout.fileno())

claude_mpm/services/monitor/management/lifecycle.py

@@ -128,12 +128,16 @@ class DaemonLifecycle:
             # Redirect stdout and stderr
             if self.log_file:
                 # Redirect to log file
+                # Ensure logs directory exists
+                self.log_file.parent.mkdir(parents=True, exist_ok=True)
                 with self.log_file.open("a") as log_out:
                     os.dup2(log_out.fileno(), sys.stdout.fileno())
                     os.dup2(log_out.fileno(), sys.stderr.fileno())
             else:
                 # Default to a daemon log file instead of /dev/null for errors
-                default_log = Path.home() / ".claude-mpm" / "monitor-daemon.log"
+                default_log = (
+                    Path.home() / ".claude-mpm" / "logs" / "monitor-daemon.log"
+                )
                 default_log.parent.mkdir(parents=True, exist_ok=True)
                 with default_log.open("a") as log_out:
                     os.dup2(log_out.fileno(), sys.stdout.fileno())
@@ -475,7 +479,9 @@ class DaemonLifecycle:
         try:
             # If no log file specified, create a default one
             if not self.log_file:
-                default_log = Path.home() / ".claude-mpm" / "monitor-daemon.log"
+                default_log = (
+                    Path.home() / ".claude-mpm" / "logs" / "monitor-daemon.log"
+                )
                 default_log.parent.mkdir(parents=True, exist_ok=True)
                 self.log_file = default_log