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

claude-mpm 4.20.3py3-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 (454) 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/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/templates/README.md ADDED Viewed

@@ -0,0 +1,180 @@
+# Claude MPM Hook Templates
+This directory contains ready-to-use hook templates for extending Claude Code functionality.
+## Available Templates
+### PreToolUse Hooks (Claude Code v2.0.30+)
+#### `pre_tool_use_template.py`
+Comprehensive template with multiple example implementations:
+- **ContextInjectionHook**: Auto-inject project context into file operations
+- **SecurityGuardHook**: Block operations on sensitive files
+- **LoggingHook**: Log all tool invocations for debugging
+- **ParameterEnhancementHook**: Add default parameters to tool calls
+**Usage:**
+```bash
+# Copy and customize
+cp pre_tool_use_template.py ~/.claude-mpm/hooks/my_hook.py
+chmod +x ~/.claude-mpm/hooks/my_hook.py
+# Edit to uncomment the implementation you want
+nano ~/.claude-mpm/hooks/my_hook.py
+```
+#### `pre_tool_use_simple.py`
+Minimal example for quick customization:
+- Shows basic hook structure
+- Includes simple parameter enhancement example
+- Includes security guard example
+- Easy to understand and modify
+**Usage:**
+```bash
+# Copy for quick start
+cp pre_tool_use_simple.py ~/.claude-mpm/hooks/my_hook.py
+chmod +x ~/.claude-mpm/hooks/my_hook.py
+```
+## Configuration
+Add hooks to `~/.claude/settings.json`:
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/Users/YOUR_USERNAME/.claude-mpm/hooks/my_hook.py",
+            "modifyInput": true
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+## Requirements
+- Claude Code v2.0.30+ for PreToolUse input modification
+- Python 3.7+
+- claude-mpm installed and configured
+## Version Check
+Check if your Claude Code version supports input modification:
+```bash
+claude --version
+```
+Or programmatically:
+```python
+from claude_mpm.hooks.claude_hooks.installer import HookInstaller
+installer = HookInstaller()
+if installer.supports_pretool_modify():
+    print("✓ PreToolUse input modification supported")
+else:
+    print(f"✗ Requires Claude Code 2.0.30+ (current: {installer.get_claude_version()})")
+```
+## Documentation
+See [PreToolUse Hook Documentation](../../../docs/developer/pretool-use-hooks.md) for:
+- Detailed usage guide
+- Best practices
+- Testing strategies
+- Troubleshooting
+- Advanced examples
+## Quick Examples
+### Add Line Numbers to Grep
+```python
+#!/usr/bin/env python3
+import json
+import sys
+event = json.loads(sys.stdin.read())
+if event.get("tool_name") == "Grep":
+    modified = event["tool_input"].copy()
+    modified["-n"] = True
+    print(json.dumps({"action": "continue", "tool_input": modified}))
+else:
+    print(json.dumps({"action": "continue"}))
+```
+### Block Sensitive Files
+```python
+#!/usr/bin/env python3
+import json
+import sys
+event = json.loads(sys.stdin.read())
+tool_name = event.get("tool_name", "")
+if tool_name in ["Write", "Edit", "Read"]:
+    file_path = event["tool_input"].get("file_path", "")
+    if ".env" in file_path:
+        print(json.dumps({"action": "block", "message": "Access to .env blocked"}))
+        sys.exit(0)
+print(json.dumps({"action": "continue"}))
+```
+### Add Default Timeout to Bash
+```python
+#!/usr/bin/env python3
+import json
+import sys
+event = json.loads(sys.stdin.read())
+if event.get("tool_name") == "Bash":
+    modified = event["tool_input"].copy()
+    if "timeout" not in modified:
+        modified["timeout"] = 30000  # 30 seconds
+        print(json.dumps({"action": "continue", "tool_input": modified}))
+        sys.exit(0)
+print(json.dumps({"action": "continue"}))
+```
+## Testing Your Hook
+Test manually with sample input:
+```bash
+echo '{
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Grep",
+  "tool_input": {"pattern": "test"},
+  "session_id": "test123",
+  "cwd": "/tmp"
+}' | python3 your_hook.py
+```
+Enable debug mode:
+```bash
+export CLAUDE_MPM_HOOK_DEBUG=true
+```
+## Support
+For issues or questions:
+- See [Documentation](../../../docs/developer/pretool-use-hooks.md)
+- Check [GitHub Issues](https://github.com/yourusername/claude-mpm/issues)
+- Review [Examples](./pre_tool_use_template.py)

claude_mpm/hooks/templates/pre_tool_use_simple.py ADDED Viewed

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""
+Simple PreToolUse Hook Example for Claude Code v2.0.30+
+This is a minimal example showing the basic structure of a PreToolUse hook
+that can modify tool inputs.
+To use this hook:
+1. Copy this file to ~/.claude-mpm/hooks/
+2. Make it executable: chmod +x ~/.claude-mpm/hooks/pre_tool_use_simple.py
+3. Add to ~/.claude/settings.json:
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/Users/YOUR_USERNAME/.claude-mpm/hooks/pre_tool_use_simple.py",
+            "modifyInput": true
+          }
+        ]
+      }
+    ]
+  }
+}
+"""
+import json
+import sys
+def main():
+    """Process PreToolUse event and optionally modify input."""
+    try:
+        # Read event from stdin
+        event_data = sys.stdin.read()
+        if not event_data.strip():
+            print(json.dumps({"action": "continue"}))
+            return
+        event = json.loads(event_data)
+        tool_name = event.get("tool_name", "")
+        tool_input = event.get("tool_input", {})
+        # Example: Add line numbers to all Grep operations
+        if tool_name == "Grep" and "-n" not in tool_input:
+            modified_input = tool_input.copy()
+            modified_input["-n"] = True
+            print(json.dumps({"action": "continue", "tool_input": modified_input}))
+            return
+        # Example: Block operations on .env files
+        if tool_name in ["Write", "Edit", "Read"]:
+            file_path = tool_input.get("file_path", "")
+            if ".env" in file_path:
+                print(
+                    json.dumps(
+                        {
+                            "action": "block",
+                            "message": "Access to .env file blocked for security",
+                        }
+                    )
+                )
+                return
+        # Default: continue without modification
+        print(json.dumps({"action": "continue"}))
+    except Exception:
+        # Always continue on error to avoid blocking Claude
+        print(json.dumps({"action": "continue"}))
+if __name__ == "__main__":
+    main()

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

Potentially problematic release.

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