claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/hooks/templates/pre_tool_use_simple.py

@@ -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/hooks/templates/pre_tool_use_template.py

@@ -0,0 +1,323 @@
+#!/usr/bin/env python3
+"""
+PreToolUse Hook Template for Claude Code v2.0.30+
+
+This template demonstrates how to create PreToolUse hooks that can modify
+tool inputs before execution. Use cases include:
+
+1. Context Injection: Add project context to Read/Edit operations
+2. Security Guards: Validate file paths before operations
+3. Logging: Log tool invocations before execution
+4. Parameter Enhancement: Add default parameters to tool calls
+
+Requirements:
+- Claude Code v2.0.30 or higher
+- Hook must be configured with "modifyInput": true in settings.json
+
+Input Format (stdin):
+{
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Edit",
+  "tool_input": {
+    "file_path": "/path/to/file.py",
+    "old_string": "foo",
+    "new_string": "bar"
+  },
+  "session_id": "abc123...",
+  "cwd": "/working/directory"
+}
+
+Output Format (stdout):
+{
+  "action": "continue",
+  "tool_input": {
+    "file_path": "/path/to/file.py",
+    "old_string": "foo",
+    "new_string": "bar_modified"
+  }
+}
+
+Or to block execution:
+{
+  "action": "block",
+  "message": "Reason for blocking"
+}
+
+Or to continue without modification:
+{
+  "action": "continue"
+}
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+class PreToolUseHook:
+    """Base class for PreToolUse hooks with input modification support."""
+
+    def __init__(self):
+        """Initialize the hook."""
+        self.debug = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "false").lower() == "true"
+
+    def log_debug(self, message: str) -> None:
+        """Log debug message to stderr."""
+        if self.debug:
+            print(f"[PreToolUse Hook] {message}", file=sys.stderr)
+
+    def read_event(self) -> Optional[Dict[str, Any]]:
+        """Read and parse the hook event from stdin."""
+        try:
+            event_data = sys.stdin.read()
+            if not event_data.strip():
+                return None
+            return json.loads(event_data)
+        except json.JSONDecodeError as e:
+            self.log_debug(f"Failed to parse event: {e}")
+            return None
+        except Exception as e:
+            self.log_debug(f"Error reading event: {e}")
+            return None
+
+    def continue_execution(
+        self, modified_input: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Continue execution with optional modified input."""
+        response = {"action": "continue"}
+        if modified_input is not None:
+            response["tool_input"] = modified_input
+        print(json.dumps(response))
+
+    def block_execution(self, message: str) -> None:
+        """Block execution with a message."""
+        response = {"action": "block", "message": message}
+        print(json.dumps(response))
+
+    def modify_input(
+        self, tool_name: str, tool_input: Dict[str, Any], event: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Modify tool input before execution.
+
+        Override this method in subclasses to implement custom logic.
+
+        Args:
+            tool_name: Name of the tool being invoked
+            tool_input: Original tool input parameters
+            event: Full event data including session_id, cwd, etc.
+
+        Returns:
+            Modified tool input dict, or None to continue without modification
+        """
+        # Default: no modification
+        return None
+
+    def should_block(
+        self, tool_name: str, tool_input: Dict[str, Any], event: Dict[str, Any]
+    ) -> tuple[bool, str]:
+        """
+        Check if execution should be blocked.
+
+        Override this method in subclasses to implement validation logic.
+
+        Args:
+            tool_name: Name of the tool being invoked
+            tool_input: Original tool input parameters
+            event: Full event data including session_id, cwd, etc.
+
+        Returns:
+            Tuple of (should_block, reason)
+        """
+        # Default: don't block
+        return False, ""
+
+    def run(self) -> None:
+        """Main entry point for the hook."""
+        try:
+            # Read event from stdin
+            event = self.read_event()
+            if not event:
+                self.continue_execution()
+                return
+
+            tool_name = event.get("tool_name", "")
+            tool_input = event.get("tool_input", {})
+
+            self.log_debug(
+                f"Processing {tool_name} with input: {list(tool_input.keys())}"
+            )
+
+            # Check if execution should be blocked
+            should_block, reason = self.should_block(tool_name, tool_input, event)
+            if should_block:
+                self.log_debug(f"Blocking {tool_name}: {reason}")
+                self.block_execution(reason)
+                return
+
+            # Try to modify input
+            modified_input = self.modify_input(tool_name, tool_input, event)
+            if modified_input is not None:
+                self.log_debug(f"Modified {tool_name} input")
+                self.continue_execution(modified_input)
+            else:
+                self.log_debug(f"No modification for {tool_name}")
+                self.continue_execution()
+
+        except Exception as e:
+            self.log_debug(f"Hook error: {e}")
+            # Always continue on error to avoid blocking Claude
+            self.continue_execution()
+
+
+# ============================================================================
+# Example Implementations
+# ============================================================================
+
+
+class ContextInjectionHook(PreToolUseHook):
+    """
+    Example: Auto-inject project context into Read/Edit tool calls.
+
+    This hook adds project-specific context as comments to file operations.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.project_context = self._load_project_context()
+
+    def _load_project_context(self) -> str:
+        """Load project context from a file or environment."""
+        # Example: Load from .claude-context file
+        context_file = Path.cwd() / ".claude-context"
+        if context_file.exists():
+            return context_file.read_text()
+        return ""
+
+    def modify_input(
+        self, tool_name: str, tool_input: Dict[str, Any], event: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Inject context into Read operations."""
+        if tool_name == "Read" and self.project_context:
+            # Add context as a note (this is conceptual - actual implementation depends on use case)
+            modified = tool_input.copy()
+            # You could add context to a metadata field if the tool supports it
+            modified["_context"] = self.project_context[:200]
+            return modified
+        return None
+
+
+class SecurityGuardHook(PreToolUseHook):
+    """
+    Example: Validate file paths before file operations.
+
+    This hook blocks operations on sensitive files or directories.
+    """
+
+    BLOCKED_PATHS = [
+        ".env",
+        "credentials.json",
+        "secrets/",
+        ".ssh/",
+        "id_rsa",
+    ]
+
+    def should_block(
+        self, tool_name: str, tool_input: Dict[str, Any], event: Dict[str, Any]
+    ) -> tuple[bool, str]:
+        """Block operations on sensitive files."""
+        if tool_name in ["Write", "Edit", "Read"]:
+            file_path = tool_input.get("file_path", "")
+            if any(blocked in file_path for blocked in self.BLOCKED_PATHS):
+                return True, f"Access to sensitive file blocked: {file_path}"
+        return False, ""
+
+
+class LoggingHook(PreToolUseHook):
+    """
+    Example: Log all tool invocations before execution.
+
+    This hook logs tool calls to a file for debugging and audit purposes.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.log_file = Path.home() / ".claude-mpm" / "tool-calls.log"
+        self.log_file.parent.mkdir(exist_ok=True)
+
+    def modify_input(
+        self, tool_name: str, tool_input: Dict[str, Any], event: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Log the tool call."""
+        try:
+            from datetime import datetime, timezone
+
+            log_entry = {
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "tool_name": tool_name,
+                "session_id": event.get("session_id", ""),
+                "cwd": event.get("cwd", ""),
+                "parameters": list(tool_input.keys()),
+            }
+            with self.log_file.open("a") as f:
+                f.write(json.dumps(log_entry) + "\n")
+        except Exception as e:
+            self.log_debug(f"Failed to log tool call: {e}")
+
+        # Don't modify input, just log
+        return None
+
+
+class ParameterEnhancementHook(PreToolUseHook):
+    """
+    Example: Add default parameters to tool calls.
+
+    This hook adds default values to tool parameters if not provided.
+    """
+
+    def modify_input(
+        self, tool_name: str, tool_input: Dict[str, Any], event: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Add default parameters."""
+        modified = tool_input.copy()
+
+        if tool_name == "Bash":
+            # Add default timeout if not specified
+            if "timeout" not in modified:
+                modified["timeout"] = 30000  # 30 seconds
+                return modified
+
+        elif tool_name == "Grep":
+            # Add line numbers by default
+            if "-n" not in modified:
+                modified["-n"] = True
+                return modified
+
+        return None
+
+
+# ============================================================================
+# Main Entry Point
+# ============================================================================
+
+
+def main():
+    """Main entry point - choose which hook implementation to use."""
+    # Select which hook implementation to use
+    # Uncomment the one you want to use:
+
+    # hook = ContextInjectionHook()
+    # hook = SecurityGuardHook()
+    # hook = LoggingHook()
+    # hook = ParameterEnhancementHook()
+
+    # Default: use base hook (no modification)
+    hook = PreToolUseHook()
+
+    hook.run()
+
+
+if __name__ == "__main__":
+    main()

claude_mpm/hooks/tool_call_interceptor.py

@@ -1,92 +1,95 @@
 """Tool call interceptor for claude-mpm hook system."""
 
 import asyncio
-import json
-from typing import Dict, Any, Optional, List
-from datetime import datetime
 from collections import defaultdict
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
 
-from claude_mpm.hooks.base_hook import BaseHook, HookContext, HookType, HookResult
 from claude_mpm.core.logger import get_logger
+from claude_mpm.hooks.base_hook import BaseHook, HookContext, HookType
 
 logger = get_logger(__name__)
 
 
 class SimpleHookRunner:
     """Simple hook runner for direct hook execution."""
-    
+
     def __init__(self):
         """Initialize the simple hook runner."""
         self._hooks: Dict[HookType, List[BaseHook]] = defaultdict(list)
         self._hook_instances: Dict[str, BaseHook] = {}
-    
+
     def register_hook(self, hook: BaseHook, hook_type: Optional[HookType] = None):
         """Register a hook instance."""
         if hook_type is None:
             hook_type = HookType.CUSTOM
-        
+
         if hook.name in self._hook_instances:
             # Remove old instance
             for hook_list in self._hooks.values():
                 if self._hook_instances[hook.name] in hook_list:
                     hook_list.remove(self._hook_instances[hook.name])
-        
+
         self._hooks[hook_type].append(hook)
         self._hook_instances[hook.name] = hook
         self._hooks[hook_type].sort()  # Sort by priority
-    
+
     async def run_hooks(self, context: HookContext) -> List[Dict[str, Any]]:
         """Run all hooks for the given context."""
         hooks = [h for h in self._hooks[context.hook_type] if h.enabled]
         results = []
-        
+
         for hook in hooks:
             try:
                 if hook.validate(context):
                     result = hook.execute(context)
-                    results.append({
-                        'hook_name': hook.name,
-                        'success': result.success,
-                        'data': result.data,
-                        'error': result.error,
-                        'modified': result.modified,
-                        'metadata': result.metadata
-                    })
-                    
+                    results.append(
+                        {
+                            "hook_name": hook.name,
+                            "success": result.success,
+                            "data": result.data,
+                            "error": result.error,
+                            "modified": result.modified,
+                            "metadata": result.metadata,
+                        }
+                    )
+
                     # Update context if modified
                     if result.modified and result.data:
                         context.data.update(result.data)
             except Exception as e:
                 logger.error(f"Hook '{hook.name}' execution failed: {e}")
-                results.append({
-                    'hook_name': hook.name,
-                    'success': False,
-                    'error': str(e)
-                })
-        
+                results.append(
+                    {"hook_name": hook.name, "success": False, "error": str(e)}
+                )
+
         return results
 
 
 class ToolCallInterceptor:
     """Intercepts and processes tool calls through the hook system."""
-    
+
     def __init__(self, hook_runner: Optional[SimpleHookRunner] = None):
         """Initialize the tool call interceptor.
-        
+
         Args:
             hook_runner: Optional hook runner instance. If not provided, creates a new one.
         """
         self.hook_runner = hook_runner or SimpleHookRunner()
-        
-    async def intercept_tool_call(self, tool_name: str, parameters: Dict[str, Any], 
-                                  metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+
+    async def intercept_tool_call(
+        self,
+        tool_name: str,
+        parameters: Dict[str, Any],
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
         """Intercept a tool call and run it through the hook system.
-        
+
         Args:
             tool_name: Name of the tool being called
             parameters: Parameters being passed to the tool
             metadata: Optional metadata for the tool call
-            
+
         Returns:
             Dict containing:
                 - allowed: Whether the tool call should proceed
@@ -98,45 +101,54 @@ class ToolCallInterceptor:
         context = HookContext(
             hook_type=HookType.CUSTOM,
             data={
-                'tool_name': tool_name,
-                'parameters': parameters.copy()  # Copy to avoid modifying original
+                "tool_name": tool_name,
+                "parameters": parameters.copy(),  # Copy to avoid modifying original
             },
             metadata=metadata or {},
-            timestamp=datetime.now()
+            timestamp=datetime.now(timezone.utc),
         )
-        
+
         # Run hooks
         results = await self.hook_runner.run_hooks(context)
-        
+
         # Process results
         allowed = True
         modified_params = parameters
         errors = []
         hook_metadata = {}
-        
+
         for result in results:
-            if not result.get('success', True):
+            if not result.get("success", True):
                 allowed = False
-                if result.get('error'):
-                    errors.append(f"[{result.get('hook_name', 'Unknown')}] {result.get('error')}")
-            
-            if result.get('modified') and result.get('data'):
+                if result.get("error"):
+                    errors.append(
+                        f"[{result.get('hook_name', 'Unknown')}] {result.get('error')}"
+                    )
+
+            if (
+                result.get("modified")
+                and result.get("data")
+                and "parameters" in result.get("data", {})
+            ):
                 # Update parameters if modified
-                if 'parameters' in result.get('data', {}):
-                    modified_params = result['data']['parameters']
-            
-            if result.get('metadata'):
-                hook_metadata.update(result['metadata'])
-        
+                modified_params = result["data"]["parameters"]
+
+            if result.get("metadata"):
+                hook_metadata.update(result["metadata"])
+
         return {
-            'allowed': allowed,
-            'parameters': modified_params,
-            'error': '\n'.join(errors) if errors else None,
-            'metadata': hook_metadata
+            "allowed": allowed,
+            "parameters": modified_params,
+            "error": "\n".join(errors) if errors else None,
+            "metadata": hook_metadata,
         }
-    
-    def intercept_tool_call_sync(self, tool_name: str, parameters: Dict[str, Any], 
-                                metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+
+    def intercept_tool_call_sync(
+        self,
+        tool_name: str,
+        parameters: Dict[str, Any],
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
         """Synchronous version of intercept_tool_call."""
         loop = asyncio.new_event_loop()
         asyncio.set_event_loop(loop)
@@ -150,55 +162,59 @@ class ToolCallInterceptor:
 
 class ToolCallHookIntegration:
     """Integration helper for adding tool call interception to existing systems."""
-    
+
     @staticmethod
     def wrap_tool_executor(original_executor, interceptor: ToolCallInterceptor):
         """Wrap an existing tool executor with hook interception.
-        
+
         Args:
             original_executor: The original tool execution function
             interceptor: The tool call interceptor instance
-            
+
         Returns:
             Wrapped executor function
         """
-        async def wrapped_executor(tool_name: str, parameters: Dict[str, Any], **kwargs):
+
+        async def wrapped_executor(
+            tool_name: str, parameters: Dict[str, Any], **kwargs
+        ):
             # Intercept the tool call
             interception_result = await interceptor.intercept_tool_call(
-                tool_name, parameters, kwargs.get('metadata')
+                tool_name, parameters, kwargs.get("metadata")
             )
-            
+
             # Check if allowed
-            if not interception_result['allowed']:
+            if not interception_result["allowed"]:
                 raise ValueError(f"Tool call blocked: {interception_result['error']}")
-            
+
             # Execute with potentially modified parameters
             return await original_executor(
-                tool_name, 
-                interception_result['parameters'], 
-                **kwargs
+                tool_name, interception_result["parameters"], **kwargs
             )
-        
+
         return wrapped_executor
-    
+
     @staticmethod
-    def create_tool_call_validator(valid_tools: List[str], interceptor: ToolCallInterceptor):
+    def create_tool_call_validator(
+        valid_tools: List[str], interceptor: ToolCallInterceptor
+    ):
         """Create a tool call validator that uses the hook system.
-        
+
         Args:
             valid_tools: List of valid tool names
             interceptor: The tool call interceptor instance
-            
+
         Returns:
             Validator function
         """
+
         def validator(tool_name: str, parameters: Dict[str, Any]) -> bool:
             # Basic validation
             if tool_name not in valid_tools:
                 return False
-            
+
             # Hook-based validation
             result = interceptor.intercept_tool_call_sync(tool_name, parameters)
-            return result['allowed']
-        
-        return validator
+            return result["allowed"]
+
+        return validator