PyPI - claude-mpm - Versions diffs - 4.16.0__py3-none-any.whl → 4.25.10__py3-none-any.whl - Mend

claude-mpm 4.16.0py3-none-any.whl → 4.25.10py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.

This version of claude-mpm might be problematic. Click here for more details.

Files changed (531) hide show

claude_mpm/dashboard/templates/index.html CHANGED Viewed

@@ -15,10 +15,10 @@
     <!-- External Dependencies -->
     <script src="https://cdn.socket.io/4.7.5/socket.io.min.js"></script>
     <!-- D3.js for Activity Tree Visualization -->
     <script src="https://d3js.org/d3.v7.min.js"></script>
     <!-- Font Awesome for icons -->
     <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
@@ -141,7 +141,7 @@
 <body>
     <!-- Connection Notifications Area -->
     <div id="connection-notifications" class="connection-notifications"></div>
     <div class="container">
         <!-- Header Section -->
         <div class="header">
@@ -435,19 +435,19 @@
         // Set up working directory environment variables
         // These will be used by the working-directory component
         // The server will inject these values through a separate API call
         // Get the current working directory from the server
         fetch('/api/working-directory')
             .then(response => response.json())
             .then(data => {
                 window.processWorkingDirectory = data.working_directory || '/Users/masa/Projects/claude-mpm';
                 window.homeDirectory = data.home_directory || '/Users/masa';
                 // Store in session storage for persistence
                 if (window.processWorkingDirectory && window.processWorkingDirectory !== '/') {
                     sessionStorage.setItem('currentWorkingDirectory', window.processWorkingDirectory);
                 }
                 // Dispatch event to notify components that working directory is ready
                 window.dispatchEvent(new CustomEvent('workingDirectoryInitialized', {
                     detail: {
@@ -462,10 +462,10 @@
                 window.processWorkingDirectory = '/Users/masa/Projects/claude-mpm';
                 window.homeDirectory = '/Users/masa';
             });
         // Add timestamp-based cache busting and ensure proper loading order
         const timestamp = Date.now();
         // Load modules sequentially to ensure dashboard.js loads first
         const loadModule = (src) => {
             return new Promise((resolve, reject) => {
@@ -477,7 +477,7 @@
                 document.body.appendChild(script);
             });
         };
         // Load shared services first, then components
         // Load services sequentially to ensure dependencies are available
         loadModule('/static/js/shared/tooltip-service.js')
@@ -540,21 +540,21 @@
                 console.error('[CRITICAL] Error loading dashboard modules:', error);
                 console.error('Stack trace:', error.stack);
             });
             // Give modules time to execute and initialize dashboard
             setTimeout(() => {
                 console.log('Checking dashboard initialization...');
                 if (window.dashboard) {
                     console.log('Dashboard found, checking auto-connect status...');
                     // Force auto-connect if not already connected
                     if (window.dashboard.socketManager) {
                         const socketManager = window.dashboard.socketManager;
                         if (!socketManager.isConnected() && !socketManager.isConnecting()) {
                             console.log('Dashboard loaded but not connected, forcing auto-connect...');
                             // Try to trigger auto-connect manually
                             const params = new URLSearchParams(window.location.search);
                             socketManager.initializeFromURL(params);
@@ -566,23 +566,23 @@
                     }
                 } else {
                     console.warn('Dashboard still not initialized after module loading');
                     // Try to manually trigger initialization
                     if (document.readyState === 'complete' || document.readyState === 'interactive') {
                         console.log('Document ready, attempting to trigger dashboard initialization...');
                         document.dispatchEvent(new Event('DOMContentLoaded'));
                     }
                 }
                 // Debug: Test connection settings button
                 const connectionToggleBtn = document.getElementById('connection-toggle-btn');
                 if (connectionToggleBtn) {
                     console.log('Connection toggle button found, testing functionality...');
                     // Add a debug click handler to ensure the button works
                     connectionToggleBtn.addEventListener('click', () => {
                         console.log('Connection toggle button clicked (debug handler)');
                         if (window.dashboard && window.dashboard.socketManager) {
                             console.log('Calling socketManager.toggleConnectionControls()');
                             window.dashboard.socketManager.toggleConnectionControls();

claude_mpm/hooks/README.md ADDED Viewed

@@ -0,0 +1,143 @@
+# Claude Code Hooks System
+This directory contains the Claude Code hook integration for claude-mpm.
+## Overview
+The hook system allows claude-mpm to intercept and handle commands typed in Claude Code, particularly the `/mpm` commands.
+## Version Requirements
+**Claude Code 1.0.92 or higher is required for hook monitoring features.**
+Earlier versions of Claude Code do not support the matcher-based hook configuration format needed for real-time event monitoring. If you have an older version:
+- The dashboard and other features will still work
+- Real-time monitoring will not be available
+- You'll see a clear message about the version requirement
+- To enable monitoring, upgrade Claude Code to 1.0.92+
+**Claude Code 2.0.30 or higher is required for PreToolUse input modification.**
+This advanced feature allows hooks to modify tool inputs before execution, enabling:
+- Context injection into file operations
+- Security guards that validate and block dangerous operations
+- Parameter enhancement with default values
+- Logging and auditing of tool invocations
+See [PreToolUse Hook Documentation](../../docs/developer/pretool-use-hooks.md) for details.
+## Architecture (v4.1.8+)
+Claude MPM uses a **deployment-root hook architecture** where Claude Code directly calls a script within the claude-mpm installation. See [HOOK_ARCHITECTURE.md](../../docs/developer/HOOK_ARCHITECTURE.md) for details.
+## Structure
+```
+hooks/
+├── claude_hooks/                      # Claude Code hook implementation
+│   ├── hook_handler.py               # Main Python handler that processes events
+│   ├── installer.py                  # Hook installation and configuration
+│   ├── event_handlers.py             # Event processing logic
+│   ├── memory_integration.py         # Memory system integration
+│   ├── response_tracking.py          # Response tracking
+│   └── services/                     # Service modules
+│       ├── connection_manager.py     # SocketIO/HTTP connections
+│       ├── state_manager.py          # State and delegation tracking
+│       └── subagent_processor.py     # Subagent response processing
+├── templates/                         # Hook script templates
+│   ├── pre_tool_use_template.py      # Comprehensive PreToolUse template
+│   ├── pre_tool_use_simple.py        # Simple PreToolUse template
+│   └── README.md                     # Template documentation
+└── scripts/
+    └── claude-hook-handler.sh        # Deployment-root hook script (called by Claude Code)
+```
+## Claude Code Hooks
+The Claude Code hooks are the primary integration point between claude-mpm and Claude Code. They allow:
+- Intercepting `/mpm` commands before they reach the LLM
+- Providing custom responses and actions
+- Blocking LLM processing when appropriate
+### Installation
+To install the Claude Code hooks:
+```bash
+# Using the configure command (recommended)
+claude-mpm configure --install-hooks
+# Or check your version compatibility first
+claude-mpm configure --verify-hooks
+```
+This will:
+1. Check your Claude Code version for compatibility
+2. If compatible (1.0.92+), create/update `~/.claude/settings.json` with hook configuration
+3. Install the smart hook script that dynamically finds claude-mpm
+4. Copy any custom commands to `~/.claude/commands/`
+If your Claude Code version is older than 1.0.92:
+- You'll see a message explaining the version requirement
+- Hooks will not be installed to prevent configuration errors
+- The system will continue to work without real-time monitoring
+### How It Works
+1. When you type in Claude Code, it triggers hook events
+2. Claude Code calls `hook_wrapper.sh` (the path in `~/.claude/settings.json`)
+3. The wrapper script:
+   - Detects if it's running from a local dev environment, npm, or PyPI installation
+   - Activates the appropriate Python environment
+   - Runs `hook_handler.py` with the event data
+4. The handler processes various event types:
+   - **UserPromptSubmit**: Checks if the prompt starts with `/mpm` and handles commands
+   - **PreToolUse**: Logs tool usage before execution
+   - **PostToolUse**: Logs tool results after execution
+   - **Stop**: Logs when a session or task stops
+   - **SubagentStop**: Logs when a subagent completes with agent type and ID
+5. For `/mpm` commands, it returns exit code 2 to block LLM processing
+6. All events are logged to project-specific log files in `.claude-mpm/logs/`
+### Available Commands
+- `/mpm` - Show help and available commands
+- `/mpm status` - Show claude-mpm status and environment
+- `/mpm help` - Show detailed help
+### Debugging
+To enable debug logging for hooks:
+```bash
+export CLAUDE_MPM_LOG_LEVEL=DEBUG
+```
+Then run Claude Code from that terminal. Hook events will be logged to `~/.claude-mpm/logs/`.
+## Legacy Hook System (Removed)
+The `builtin/` directory that contained the old internal hook system has been removed. All hook functionality is now handled through the Claude Code hooks system.
+## Development
+To add new `/mpm` commands:
+1. Edit `hook_handler.py` to handle the new command
+2. Update the help text in the `handle_mpm_help()` function
+3. Test by running Claude Code with the new command
+## Exit Codes
+The hook system uses specific exit codes:
+- `0` - Success, continue normal processing
+- `2` - Block LLM processing (command was handled)
+- Other - Error occurred
+## Environment Variables
+- `CLAUDE_MPM_LOG_LEVEL` - Set to DEBUG for detailed logging
+- `HOOK_EVENT_TYPE` - Set by Claude Code (UserPromptSubmit, PreToolUse, PostToolUse)
+- `HOOK_DATA` - JSON data from Claude Code with event details

claude_mpm/hooks/__init__.py CHANGED Viewed

@@ -12,6 +12,11 @@ from .failure_learning import (
 from .kuzu_enrichment_hook import KuzuEnrichmentHook, get_kuzu_enrichment_hook
 from .kuzu_memory_hook import KuzuMemoryHook, get_kuzu_memory_hook
 from .kuzu_response_hook import KuzuResponseHook, get_kuzu_response_hook
+from .session_resume_hook import (
+    SessionResumeStartupHook,
+    get_session_resume_hook,
+    trigger_session_resume_check,
+)
 __all__ = [
     "BaseHook",
@@ -24,10 +29,13 @@ __all__ = [
     "KuzuMemoryHook",
     "KuzuResponseHook",
     "LearningExtractionHook",
+    "SessionResumeStartupHook",
     "get_failure_detection_hook",
     "get_fix_detection_hook",
     "get_kuzu_enrichment_hook",
     "get_kuzu_memory_hook",
     "get_kuzu_response_hook",
     "get_learning_extraction_hook",
+    "get_session_resume_hook",
+    "trigger_session_resume_check",
 ]

claude_mpm/hooks/claude_hooks/event_handlers.py CHANGED Viewed

@@ -393,7 +393,9 @@ class EventHandlers:
             "status": (
                 "success"
                 if exit_code == 0
-                else "blocked" if exit_code == 2 else "error"
+                else "blocked"
+                if exit_code == 2
+                else "error"
             ),
             "duration_ms": duration,
             "result_summary": result_data,

claude_mpm/hooks/claude_hooks/hook_handler.py CHANGED Viewed

@@ -311,11 +311,12 @@ class ClaudeHookHandler:
                     )
             # Route event to appropriate handler
-            self._route_event(event)
+            # Handlers can optionally return modified input for PreToolUse events
+            modified_input = self._route_event(event)
             # Always continue execution (only if not already sent)
             if not _continue_sent:
-                self._continue_execution()
+                self._continue_execution(modified_input)
                 _continue_sent = True
         except Exception:
@@ -376,7 +377,7 @@ class ClaudeHookHandler:
                 print(f"Error reading hook event: {e}", file=sys.stderr)
             return None
-    def _route_event(self, event: dict) -> None:
+    def _route_event(self, event: dict) -> Optional[dict]:
         """
         Route event to appropriate handler based on type.
@@ -385,6 +386,9 @@ class ClaudeHookHandler:
         Args:
             event: Hook event dictionary
+        Returns:
+            Modified input for PreToolUse events (v2.0.30+), None otherwise
         """
         # Try multiple field names for compatibility
         hook_type = (
@@ -416,23 +420,36 @@ class ClaudeHookHandler:
         handler = event_handlers.get(hook_type)
         if handler:
             try:
-                handler(event)
+                # Handlers can optionally return modified input
+                result = handler(event)
+                # Only PreToolUse handlers should return modified input
+                if hook_type == "PreToolUse" and result is not None:
+                    return result
             except Exception as e:
                 if DEBUG:
                     print(f"Error handling {hook_type}: {e}", file=sys.stderr)
+        return None
     def handle_subagent_stop(self, event: dict):
         """Delegate subagent stop processing to the specialized processor."""
         self.subagent_processor.process_subagent_stop(event)
-    def _continue_execution(self) -> None:
+    def _continue_execution(self, modified_input: Optional[dict] = None) -> None:
         """
-        Send continue action to Claude.
+        Send continue action to Claude with optional input modification.
         WHY: Centralized response ensures consistent format
         and makes it easier to add response modifications.
+        Args:
+            modified_input: Modified tool parameters for PreToolUse hooks (v2.0.30+)
         """
-        print(json.dumps({"action": "continue"}))
+        if modified_input is not None:
+            # Claude Code v2.0.30+ supports modifying PreToolUse tool inputs
+            print(json.dumps({"action": "continue", "tool_input": modified_input}))
+        else:
+            print(json.dumps({"action": "continue"}))
     # Delegation methods for compatibility with event_handlers
     def _track_delegation(self, session_id: str, agent_type: str, request_data=None):

claude_mpm/hooks/claude_hooks/installer.py CHANGED Viewed

@@ -192,6 +192,8 @@ main "$@"
     # Minimum Claude Code version required for hook monitoring
     MIN_CLAUDE_VERSION = "1.0.92"
+    # Minimum version for PreToolUse input modification support
+    MIN_PRETOOL_MODIFY_VERSION = "2.0.30"
     def __init__(self):
         """Initialize the hook installer."""
@@ -292,6 +294,42 @@ main "$@"
         return (True, f"Claude Code {version} is compatible with hook monitoring.")
+    def supports_pretool_modify(self) -> bool:
+        """
+        Check if the installed Claude Code version supports PreToolUse input modification.
+        PreToolUse input modification was added in Claude Code v2.0.30.
+        Returns:
+            True if version supports input modification, False otherwise
+        """
+        version = self.get_claude_version()
+        if version is None:
+            return False
+        def parse_version(v: str) -> List[int]:
+            """Parse semantic version string to list of integers."""
+            try:
+                return [int(x) for x in v.split(".")]
+            except (ValueError, AttributeError):
+                return [0]
+        current = parse_version(version)
+        required = parse_version(self.MIN_PRETOOL_MODIFY_VERSION)
+        # Compare versions
+        for i in range(max(len(current), len(required))):
+            curr_part = current[i] if i < len(current) else 0
+            req_part = required[i] if i < len(required) else 0
+            if curr_part < req_part:
+                return False
+            if curr_part > req_part:
+                return True
+        return True
     def get_hook_script_path(self) -> Path:
         """Get the path to the hook handler script based on installation method.
@@ -677,6 +715,7 @@ main "$@"
         # Check version compatibility
         claude_version = self.get_claude_version()
         is_compatible, version_message = self.is_version_compatible()
+        pretool_modify_supported = self.supports_pretool_modify()
         is_valid, issues = self.verify_hooks()
@@ -701,6 +740,12 @@ main "$@"
             "version_compatible": is_compatible,
             "version_message": version_message,
             "deployment_type": "deployment-root",  # New field to indicate new architecture
+            "pretool_modify_supported": pretool_modify_supported,  # v2.0.30+ feature
+            "pretool_modify_message": (
+                f"PreToolUse input modification supported (v{claude_version})"
+                if pretool_modify_supported
+                else f"PreToolUse input modification requires Claude Code {self.MIN_PRETOOL_MODIFY_VERSION}+ (current: {claude_version or 'unknown'})"
+            ),
         }
         # Check Claude settings for hook configuration

claude_mpm/hooks/claude_hooks/response_tracking.py CHANGED Viewed

@@ -268,7 +268,10 @@ class ResponseTrackingManager:
     def track_stop_response(
         self, event: dict, session_id: str, metadata: dict, pending_prompts: dict
     ):
-        """Track response for stop events."""
+        """Track response for stop events.
+        Captures Claude API stop_reason and usage data for context management.
+        """
         if not (self.response_tracking_enabled and self.response_tracker):
             return
@@ -294,6 +297,37 @@ class ResponseTrackingManager:
                 # Add prompt timestamp to metadata
                 metadata["prompt_timestamp"] = prompt_data.get("timestamp")
+                # Capture Claude API stop_reason if available
+                if "stop_reason" in event:
+                    metadata["stop_reason"] = event["stop_reason"]
+                    if DEBUG:
+                        print(
+                            f"  - Captured stop_reason: {event['stop_reason']}",
+                            file=sys.stderr,
+                        )
+                # Capture Claude API usage data if available
+                if "usage" in event:
+                    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
+                        ),
+                    }
+                    if DEBUG:
+                        total_tokens = usage_data.get(
+                            "input_tokens", 0
+                        ) + usage_data.get("output_tokens", 0)
+                        print(
+                            f"  - Captured usage: {total_tokens} total tokens",
+                            file=sys.stderr,
+                        )
                 # Track the main Claude response
                 file_path = self.response_tracker.track_response(
                     agent_name="claude_main",

claude_mpm/hooks/session_resume_hook.py ADDED Viewed

@@ -0,0 +1,121 @@
+"""Session Resume Startup Hook.
+WHY: This hook automatically checks for paused sessions on PM startup and displays
+resume context to help users continue their work seamlessly.
+DESIGN DECISIONS:
+- Runs automatically on PM startup
+- Non-blocking: doesn't prevent PM from starting if check fails
+- Displays context to stdout for user visibility
+- Integrates with existing session pause/resume infrastructure
+"""
+from pathlib import Path
+from typing import Any, Dict, Optional
+from claude_mpm.core.logger import get_logger
+from claude_mpm.services.cli.session_resume_helper import SessionResumeHelper
+logger = get_logger(__name__)
+class SessionResumeStartupHook:
+    """Hook for automatic session resume detection on PM startup."""
+    def __init__(self, project_path: Optional[Path] = None):
+        """Initialize the session resume hook.
+        Args:
+            project_path: Project root path (default: current directory)
+        """
+        self.project_path = project_path or Path.cwd()
+        self.resume_helper = SessionResumeHelper(self.project_path)
+        self._session_displayed = False
+    def on_pm_startup(self) -> Optional[Dict[str, Any]]:
+        """Execute on PM startup to check for paused sessions.
+        Returns:
+            Session data if paused session found, None otherwise
+        """
+        try:
+            # Check if we already displayed a session in this process
+            if self._session_displayed:
+                logger.debug("Session already displayed, skipping")
+                return None
+            # Check for paused sessions
+            session_data = self.resume_helper.check_and_display_resume_prompt()
+            if session_data:
+                self._session_displayed = True
+                logger.info("Paused session context displayed to user")
+            return session_data
+        except Exception as e:
+            logger.error(f"Failed to check for paused sessions: {e}", exc_info=True)
+            return None
+    def get_session_count(self) -> int:
+        """Get count of paused sessions.
+        Returns:
+            Number of paused sessions
+        """
+        try:
+            return self.resume_helper.get_session_count()
+        except Exception as e:
+            logger.error(f"Failed to get session count: {e}")
+            return 0
+    def clear_displayed_session(self, session_data: Dict[str, Any]) -> bool:
+        """Clear a session after it has been displayed and user has acknowledged.
+        Args:
+            session_data: Session data to clear
+        Returns:
+            True if successfully cleared, False otherwise
+        """
+        try:
+            return self.resume_helper.clear_session(session_data)
+        except Exception as e:
+            logger.error(f"Failed to clear session: {e}")
+            return False
+# Global hook instance
+_session_resume_hook: Optional[SessionResumeStartupHook] = None
+def get_session_resume_hook(
+    project_path: Optional[Path] = None,
+) -> SessionResumeStartupHook:
+    """Get or create the global session resume hook instance.
+    Args:
+        project_path: Project root path (default: current directory)
+    Returns:
+        SessionResumeStartupHook instance
+    """
+    global _session_resume_hook
+    if _session_resume_hook is None:
+        _session_resume_hook = SessionResumeStartupHook(project_path)
+        logger.debug("Created session resume hook instance")
+    return _session_resume_hook
+def trigger_session_resume_check() -> Optional[Dict[str, Any]]:
+    """Trigger a session resume check (convenience function).
+    This is the main entry point for PM startup integration.
+    Returns:
+        Session data if found, None otherwise
+    """
+    hook = get_session_resume_hook()
+    return hook.on_pm_startup()

claude-mpm 4.16.0__py3-none-any.whl → 4.25.10__py3-none-any.whl

Potentially problematic release.

claude-mpm 4.16.0py3-none-any.whl → 4.25.10py3-none-any.whl