claude-mpm 5.5.0__py3-none-any.whl → 5.6.2__py3-none-any.whl

claude_mpm/hooks/claude_hooks/hook_handler.py

@@ -62,14 +62,31 @@ except ImportError:
 """
 Debug mode configuration for hook processing.
 
-WHY enabled by default: Hook processing can be complex and hard to debug.
-Having debug output available by default helps diagnose issues during development.
-Production deployments can disable via environment variable.
+WHY disabled by default: Production users should see clean output without debug noise.
+Hook errors appear less confusing when debug output is minimal.
+Development and debugging can enable via CLAUDE_MPM_HOOK_DEBUG=true.
 
 Performance Impact: Debug logging adds ~5-10% overhead but provides crucial
-visibility into event flow, timing, and error conditions.
+visibility into event flow, timing, and error conditions when enabled.
 """
-DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "false").lower() == "true"
+
+
+def _log(message: str) -> None:
+    """Log message to file if DEBUG enabled. Never write to stderr.
+
+    WHY: Claude Code interprets ANY stderr output as a hook error.
+    Writing to stderr causes confusing "hook error" messages even for debug logs.
+
+    This helper ensures all debug output goes to a log file instead.
+    """
+    if DEBUG:
+        try:
+            with open("/tmp/claude-mpm-hook.log", "a") as f:  # nosec B108
+                f.write(f"[{datetime.now(timezone.utc).isoformat()}] {message}\n")
+        except Exception:  # nosec B110 - intentional silent failure
+            pass  # Never disrupt hook execution
+
 
 """
 Conditional imports with graceful fallbacks for testing and modularity.
@@ -188,22 +205,17 @@ def check_claude_version() -> Tuple[bool, Optional[str]]:
                     req_part = required[i] if i < len(required) else 0
 
                     if curr_part < req_part:
-                        if DEBUG:
-                            print(
-                                f"⚠️  Claude Code {version} does not support matcher-based hooks "
-                                f"(requires {MIN_CLAUDE_VERSION}+). Hook monitoring disabled.",
-                                file=sys.stderr,
-                            )
+                        _log(
+                            f"⚠️  Claude Code {version} does not support matcher-based hooks "
+                            f"(requires {MIN_CLAUDE_VERSION}+). Hook monitoring disabled."
+                        )
                         return False, version
                     if curr_part > req_part:
                         return True, version
 
                 return True, version
     except Exception as e:
-        if DEBUG:
-            print(
-                f"Warning: Could not detect Claude Code version: {e}", file=sys.stderr
-            )
+        _log(f"Warning: Could not detect Claude Code version: {e}")
 
     return False, None
 
@@ -244,8 +256,7 @@ class ClaudeHookHandler:
                 )
         except Exception as e:
             self.auto_pause_handler = None
-            if DEBUG:
-                print(f"Auto-pause initialization failed: {e}", file=sys.stderr)
+            _log(f"Auto-pause initialization failed: {e}")
 
         # Backward compatibility properties for tests
         # Note: HTTP-based connection manager doesn't use connection_pool
@@ -278,8 +289,7 @@ class ClaudeHookHandler:
         def timeout_handler(signum, frame):
             """Handle timeout by forcing exit."""
             nonlocal _continue_sent
-            if DEBUG:
-                print(f"Hook handler timeout (pid: {os.getpid()})", file=sys.stderr)
+            _log(f"Hook handler timeout (pid: {os.getpid()})")
             if not _continue_sent:
                 self._continue_execution()
                 _continue_sent = True
@@ -300,11 +310,9 @@ class ClaudeHookHandler:
 
             # Check for duplicate events (same event within 100ms)
             if self.duplicate_detector.is_duplicate(event):
-                if DEBUG:
-                    print(
-                        f"[{datetime.now(timezone.utc).isoformat()}] Skipping duplicate event: {event.get('hook_event_name', 'unknown')} (PID: {os.getpid()})",
-                        file=sys.stderr,
-                    )
+                _log(
+                    f"[{datetime.now(timezone.utc).isoformat()}] Skipping duplicate event: {event.get('hook_event_name', 'unknown')} (PID: {os.getpid()})"
+                )
                 # Still need to output continue for this invocation
                 if not _continue_sent:
                     self._continue_execution()
@@ -312,12 +320,10 @@ class ClaudeHookHandler:
                 return
 
             # Debug: Log that we're processing an event
-            if DEBUG:
-                hook_type = event.get("hook_event_name", "unknown")
-                print(
-                    f"\n[{datetime.now(timezone.utc).isoformat()}] Processing hook event: {hook_type} (PID: {os.getpid()})",
-                    file=sys.stderr,
-                )
+            hook_type = event.get("hook_event_name", "unknown")
+            _log(
+                f"\n[{datetime.now(timezone.utc).isoformat()}] Processing hook event: {hook_type} (PID: {os.getpid()})"
+            )
 
             # Perform periodic cleanup if needed
             if self.state_manager.increment_events_processed():
@@ -326,11 +332,9 @@ class ClaudeHookHandler:
                 from .correlation_manager import CorrelationManager
 
                 CorrelationManager.cleanup_old()
-                if DEBUG:
-                    print(
-                        f"🧹 Performed cleanup after {self.state_manager.events_processed} events",
-                        file=sys.stderr,
-                    )
+                _log(
+                    f"🧹 Performed cleanup after {self.state_manager.events_processed} events"
+                )
 
             # Route event to appropriate handler
             # Handlers can optionally return modified input for PreToolUse events
@@ -370,8 +374,7 @@ class ClaudeHookHandler:
             ready, _, _ = select.select([sys.stdin], [], [], 1.0)
             if not ready:
                 # No data available within timeout
-                if DEBUG:
-                    print("No hook event data received within timeout", file=sys.stderr)
+                _log("No hook event data received within timeout")
                 return None
 
             # Data is available, read it
@@ -382,21 +385,16 @@ class ClaudeHookHandler:
 
             parsed = json.loads(event_data)
             # Debug: Log the actual event format we receive
-            if DEBUG:
-                print(
-                    f"Received event with keys: {list(parsed.keys())}", file=sys.stderr
-                )
-                for key in ["hook_event_name", "event", "type", "event_type"]:
-                    if key in parsed:
-                        print(f"  {key} = '{parsed[key]}'", file=sys.stderr)
+            _log(f"Received event with keys: {list(parsed.keys())}")
+            for key in ["hook_event_name", "event", "type", "event_type"]:
+                if key in parsed:
+                    _log(f"  {key} = '{parsed[key]}'")
             return parsed
         except (json.JSONDecodeError, ValueError) as e:
-            if DEBUG:
-                print(f"Failed to parse hook event: {e}", file=sys.stderr)
+            _log(f"Failed to parse hook event: {e}")
             return None
         except Exception as e:
-            if DEBUG:
-                print(f"Error reading hook event: {e}", file=sys.stderr)
+            _log(f"Error reading hook event: {e}")
             return None
 
     def _route_event(self, event: dict) -> Optional[dict]:
@@ -425,9 +423,9 @@ class ClaudeHookHandler:
         )
 
         # Log the actual event structure for debugging
-        if DEBUG and hook_type == "unknown":
-            print(f"Unknown event format, keys: {list(event.keys())}", file=sys.stderr)
-            print(f"Event sample: {str(event)[:200]}", file=sys.stderr)
+        if hook_type == "unknown":
+            _log(f"Unknown event format, keys: {list(event.keys())}")
+            _log(f"Event sample: {str(event)[:200]}")
 
         # Map event types to handlers
         event_handlers = {
@@ -463,8 +461,7 @@ class ClaudeHookHandler:
             except Exception as e:
                 error_message = str(e)
                 return_value = None
-                if DEBUG:
-                    print(f"Error handling {hook_type}: {e}", file=sys.stderr)
+                _log(f"Error handling {hook_type}: {e}")
             finally:
                 # Calculate duration
                 duration_ms = int((time.time() - start_time) * 1000)
@@ -589,11 +586,9 @@ class ClaudeHookHandler:
         # 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,
-            )
+        _log(
+            f"📊 Hook execution event: {hook_type} - {duration_ms}ms - {'✅' if success else '❌'}"
+        )
 
     def _generate_hook_summary(self, hook_type: str, event: dict, success: bool) -> str:
         """Generate a human-readable summary of what the hook did.
@@ -676,22 +671,15 @@ def main():
     if not is_compatible:
         # Version incompatible - just continue without processing
         # This prevents errors on older Claude Code versions
-        if DEBUG and version:
-            print(
-                f"Skipping hook processing due to version incompatibility ({version})",
-                file=sys.stderr,
-            )
+        if version:
+            _log(f"Skipping hook processing due to version incompatibility ({version})")
         print(json.dumps({"action": "continue"}), flush=True)
         sys.exit(0)
 
     def cleanup_handler(signum=None, frame=None):
         """Cleanup handler for signals and exit."""
         nonlocal _continue_printed
-        if DEBUG:
-            print(
-                f"Hook handler cleanup (pid: {os.getpid()}, signal: {signum})",
-                file=sys.stderr,
-            )
+        _log(f"Hook handler cleanup (pid: {os.getpid()}, signal: {signum})")
         # Only output continue if we haven't already (i.e., if interrupted by signal)
         if signum is not None and not _continue_printed:
             print(json.dumps({"action": "continue"}), flush=True)
@@ -708,15 +696,10 @@ def main():
         with _handler_lock:
             if _global_handler is None:
                 _global_handler = ClaudeHookHandler()
-                if DEBUG:
-                    print(
-                        f"✅ Created new ClaudeHookHandler singleton (pid: {os.getpid()})",
-                        file=sys.stderr,
-                    )
-            elif DEBUG:
-                print(
-                    f"♻️ Reusing existing ClaudeHookHandler singleton (pid: {os.getpid()})",
-                    file=sys.stderr,
+                _log(f"✅ Created new ClaudeHookHandler singleton (pid: {os.getpid()})")
+            else:
+                _log(
+                    f"♻️ Reusing existing ClaudeHookHandler singleton (pid: {os.getpid()})"
                 )
 
             handler = _global_handler
@@ -735,10 +718,14 @@ def main():
             print(json.dumps({"action": "continue"}), flush=True)
             _continue_printed = True
         # Log error for debugging
-        if DEBUG:
-            print(f"Hook handler error: {e}", file=sys.stderr)
+        _log(f"Hook handler error: {e}")
         sys.exit(0)  # Exit cleanly even on error
 
 
 if __name__ == "__main__":
-    main()
+    try:
+        main()
+    except Exception:
+        # Catastrophic failure (import error, etc.) - always output valid JSON
+        print(json.dumps({"action": "continue"}), flush=True)
+        sys.exit(0)

claude_mpm/hooks/claude_hooks/installer.py

@@ -14,8 +14,6 @@ import subprocess  # nosec B404 - Safe: only uses hardcoded 'claude' CLI command
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple
 
-from ...core.logger import get_logger
-
 
 class HookInstaller:
     """Manages installation and configuration of Claude MPM hooks."""
@@ -199,7 +197,12 @@ main "$@"
 
     def __init__(self):
         """Initialize the hook installer."""
-        self.logger = get_logger(__name__)
+        # Use __name__ directly to avoid double prefix
+        # __name__ is already 'claude_mpm.hooks.claude_hooks.installer'
+        # get_logger() adds 'claude_mpm.' prefix, causing duplicate
+        import logging
+
+        self.logger = logging.getLogger(__name__)
         self.claude_dir = Path.home() / ".claude"
         self.hooks_dir = self.claude_dir / "hooks"  # Kept for backward compatibility
         # Use settings.json for hooks (Claude Code reads from this file)

claude_mpm/hooks/claude_hooks/memory_integration.py

@@ -11,15 +11,23 @@ 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
+# but respects production install silence AND startup suppression
 try:
     from claude_mpm.core.unified_paths import DeploymentContext, PathContext
 
     context = PathContext.detect_deployment_context()
 
+    # CRITICAL: Check if root logger is already suppressed (CRITICAL+1 from startup.py)
+    # If so, don't call basicConfig as it will reset the level to INFO
+    root_logger = logging.getLogger()
+    is_suppressed = root_logger.level > logging.CRITICAL  # CRITICAL+1 = 51
+
     # Only configure verbose logging for development/editable installs
-    # Production installs remain silent by default
-    if context in (DeploymentContext.DEVELOPMENT, DeploymentContext.EDITABLE_INSTALL):
+    # AND if logging isn't already suppressed by startup.py
+    if not is_suppressed and context in (
+        DeploymentContext.DEVELOPMENT,
+        DeploymentContext.EDITABLE_INSTALL,
+    ):
         logging.basicConfig(
             level=logging.INFO,
             format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
@@ -27,14 +35,17 @@ try:
             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,
-    )
+    # Fallback: if unified_paths not available, check suppression before configuring
+    root_logger = logging.getLogger()
+    is_suppressed = root_logger.level > logging.CRITICAL
+
+    if not is_suppressed:
+        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/services/skills/git_skill_source_manager.py

@@ -682,7 +682,7 @@ class GitSkillSourceManager:
                 try:
                     with open(etag_cache_file, encoding="utf-8") as f:
                         etag_cache = json.load(f)
-                except Exception:
+                except Exception:  # nosec B110 - intentional: proceed without cache on read failure
                     pass
 
             cached_etag = etag_cache.get(str(local_path))
@@ -1163,6 +1163,10 @@ class GitSkillSourceManager:
     ) -> List[str]:
         """Remove skills from target directory that aren't in the filtered skill list.
 
+        CRITICAL: Only removes MPM-managed skills (those in our cache). Custom user skills
+        are preserved. This prevents accidental deletion of user-created skills that were
+        never part of MPM's skill repository.
+
         Uses fuzzy matching to handle both exact deployment names and short skill names.
         For example:
         - "toolchains-python-frameworks-flask" (deployed dir) matches "flask" (filter)
@@ -1213,6 +1217,40 @@ class GitSkillSourceManager:
 
             return False
 
+        def is_mpm_managed_skill(skill_dir_name: str) -> bool:
+            """Check if skill is managed by MPM (exists in our cache).
+
+            Custom user skills (not in cache) are NEVER deleted, even if not in filter.
+            Only MPM-managed skills (in cache but not in filter) are candidates for removal.
+
+            Args:
+                skill_dir_name: Name of deployed skill directory
+
+            Returns:
+                True if skill exists in MPM cache (MPM-managed), False if custom user skill
+            """
+            # Check all configured skill sources for this skill
+            for source in self.config.get_enabled_sources():
+                cache_path = self._get_source_cache_path(source)
+                if not cache_path.exists():
+                    continue
+
+                # Check if this skill directory exists anywhere in the cache
+                # Use glob to find matching directories recursively
+                matches = list(cache_path.rglob(f"*{skill_dir_name}*"))
+                if matches:
+                    # Found in cache - this is MPM-managed
+                    self.logger.debug(
+                        f"Skill '{skill_dir_name}' found in cache at {matches[0]} - MPM-managed"
+                    )
+                    return True
+
+            # Not found in any cache - this is a custom user skill
+            self.logger.debug(
+                f"Skill '{skill_dir_name}' not found in cache - custom user skill, preserving"
+            )
+            return False
+
         # Check each directory in target_dir
         if not target_dir.exists():
             return removed_skills
@@ -1229,6 +1267,15 @@ class GitSkillSourceManager:
 
                 # Check if this skill directory should be kept (fuzzy matching)
                 if not should_keep_skill(item.name):
+                    # CRITICAL: Check if this is an MPM-managed skill before deletion
+                    if not is_mpm_managed_skill(item.name):
+                        # This is a custom user skill - NEVER delete
+                        self.logger.debug(
+                            f"Preserving custom user skill (not in MPM cache): {item.name}"
+                        )
+                        continue
+
+                    # It's MPM-managed but not in filter - safe to remove
                     try:
                         # Security: Validate path is within target_dir
                         if not self._validate_safe_path(target_dir, item):
@@ -1244,7 +1291,9 @@ class GitSkillSourceManager:
                             shutil.rmtree(item)
 
                         removed_skills.append(item.name)
-                        self.logger.info(f"Removed orphaned skill: {item.name}")
+                        self.logger.info(
+                            f"Removed orphaned MPM-managed skill: {item.name}"
+                        )
 
                     except Exception as e:
                         self.logger.warning(

{claude_mpm-5.5.0.dist-info → claude_mpm-5.6.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 5.5.0
+Version: 5.6.2
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team
@@ -49,6 +49,8 @@ Requires-Dist: rich>=13.0.0
 Requires-Dist: questionary>=2.0.0
 Requires-Dist: pyee>=13.0.0
 Requires-Dist: pathspec>=0.11.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.20.0
 Provides-Extra: mcp
 Requires-Dist: mcp>=0.1.0; extra == "mcp"
 Requires-Dist: mcp-vector-search>=0.1.0; extra == "mcp"
@@ -233,6 +235,16 @@ ls ~/.claude/agents/    # Should show 47+ agents
 
 [→ Learn more: Developer Use Cases](docs/usecases/developers.md#semantic-code-search)
 
+### 🧪 MPM Commander (ALPHA)
+- **Multi-Project Orchestration** with autonomous AI coordination across codebases
+- **Tmux Integration** for isolated project environments and session management
+- **Event-Driven Architecture** with inbox system for cross-project communication
+- **LLM-Powered Decisions** via OpenRouter for autonomous work queue processing
+- **Real-Time Monitoring** with state tracking (IDLE, WORKING, BLOCKED, PAUSED, ERROR)
+- ⚠️ **Experimental** - API and CLI interface subject to change
+
+[→ Commander Documentation](docs/commander/usage-guide.md)
+
 ### 🔌 Advanced Integration
 - **MCP Integration** with full Model Context Protocol support
 - **Real-Time Monitoring** via `--monitor` flag and web dashboard