claude-mpm 0.3.0__py3-none-any.whl

claude_mpm/hooks/README.md

@@ -0,0 +1,243 @@
+# Claude MPM Hook System
+
+The Claude MPM hook system provides extensibility points for customizing behavior at key stages of execution.
+
+## Current Implementation (v0.5.0+)
+
+As of version 0.5.0, the hook system uses JSON-RPC for all hook executions. The previous HTTP-based implementation is deprecated and will be removed in a future release.
+
+## Overview
+
+The hook system allows you to intercept and modify behavior at various points in the orchestration workflow:
+
+- **Submit Hooks**: Process user prompts before orchestration
+- **Pre-Delegation Hooks**: Filter/enhance context before delegating to agents  
+- **Post-Delegation Hooks**: Validate/process results from agents
+- **Ticket Extraction Hooks**: Automatically extract and create tickets from conversations
+
+## Architecture
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│   Orchestrator  │────▶│ JSON-RPC Client  │────▶│   Hook Types    │
+│                 │     │                  │     ├─────────────────┤
+│ - Process prompt│     │ - No server req. │     │ - SubmitHook    │
+│ - Delegate work │     │ - Direct exec    │     │ - PreDelegation │
+│ - Create tickets│     │ - Auto discovery │     │ - PostDelegation│
+└─────────────────┘     └──────────────────┘     │ - TicketExtract │
+                                                  └─────────────────┘
+```
+
+## Usage
+
+### Basic Client Usage
+```python
+from claude_mpm.hooks.json_rpc_hook_client import JSONRPCHookClient
+
+# Create client
+client = JSONRPCHookClient()
+
+# Check system health
+health = client.health_check()
+print(f"Status: {health['status']}")
+print(f"Hooks available: {health['hook_count']}")
+
+# List available hooks
+hooks = client.list_hooks()
+for hook_type, hook_list in hooks.items():
+    print(f"{hook_type}: {len(hook_list)} hooks")
+```
+
+### Executing Hooks
+```python
+# Execute submit hooks
+results = client.execute_submit_hook(
+    prompt="URGENT: Fix the login bug",
+    user_id="user123"
+)
+
+# Get modified data
+modified_data = client.get_modified_data(results)
+if modified_data.get('priority') == 'high':
+    print("High priority task detected!")
+
+# Execute pre-delegation hooks
+results = client.execute_pre_delegation_hook(
+    agent="engineer",
+    context={"task": "implement feature"}
+)
+
+# Execute ticket extraction
+results = client.execute_ticket_extraction_hook(
+    content="TODO: Add tests\nFIXME: Memory leak"
+)
+tickets = client.get_extracted_tickets(results)
+```
+
+## Hook Types
+
+### 1. Submit Hooks
+Process user prompts before they're sent to the orchestrator:
+```python
+from claude_mpm.hooks.base_hook import SubmitHook, HookContext, HookResult
+
+class TicketDetectionSubmitHook(SubmitHook):
+    name = "ticket_detection"
+    priority = 10
+    
+    def execute(self, context: HookContext) -> HookResult:
+        prompt = context.data.get('prompt', '')
+        # Detect ticket references like TSK-001
+        tickets = self.ticket_pattern.findall(prompt)
+        return HookResult(
+            success=True,
+            data={'tickets': tickets},
+            modified=True
+        )
+```
+
+### 2. Pre-Delegation Hooks
+Modify agent context before delegation:
+```python
+from claude_mpm.hooks.base_hook import PreDelegationHook
+
+class ContextFilterHook(PreDelegationHook):
+    name = "context_filter"
+    priority = 20
+    
+    def execute(self, context: HookContext) -> HookResult:
+        # Filter sensitive information
+        filtered_context = self._filter_sensitive(context.data['context'])
+        return HookResult(
+            success=True,
+            data={'context': filtered_context},
+            modified=True
+        )
+```
+
+### 3. Post-Delegation Hooks
+Process agent results:
+```python
+from claude_mpm.hooks.base_hook import PostDelegationHook
+
+class ResultValidatorHook(PostDelegationHook):
+    name = "result_validator"
+    priority = 30
+    
+    def execute(self, context: HookContext) -> HookResult:
+        result = context.data.get('result', {})
+        # Validate result quality
+        issues = self._validate_result(result)
+        return HookResult(
+            success=True,
+            data={'validation_issues': issues},
+            modified=bool(issues)
+        )
+```
+
+### 4. Ticket Extraction Hooks
+Extract actionable items from conversations:
+```python
+from claude_mpm.hooks.base_hook import TicketExtractionHook
+
+class AutoTicketExtractionHook(TicketExtractionHook):
+    name = "auto_ticket_extraction"
+    priority = 40
+    
+    def execute(self, context: HookContext) -> HookResult:
+        content = context.data.get('content', '')
+        # Extract TODO, FIXME, etc.
+        tickets = self._extract_tickets(content)
+        return HookResult(
+            success=True,
+            data={'tickets': tickets},
+            modified=True
+        )
+```
+
+## Creating Custom Hooks
+
+### 1. Create Hook File
+Create a new Python file in the `builtin/` directory:
+
+```python
+# builtin/my_custom_hook.py
+from claude_mpm.hooks.base_hook import SubmitHook, HookContext, HookResult
+
+class MyCustomHook(SubmitHook):
+    name = "my_custom_hook"
+    priority = 25  # 0-100, lower executes first
+    
+    def execute(self, context: HookContext) -> HookResult:
+        # Your hook logic here
+        prompt = context.data.get('prompt', '')
+        
+        # Process prompt
+        processed = self._process(prompt)
+        
+        return HookResult(
+            success=True,
+            data={'prompt': processed},
+            modified=True
+        )
+    
+    def _process(self, prompt: str) -> str:
+        # Your processing logic
+        return prompt.upper()
+```
+
+### 2. Hook Discovery
+Hooks are automatically discovered from the `builtin/` directory when the client is initialized. No manual registration required!
+
+### 3. Hook Priority
+Hooks execute in priority order (0-100, lower first):
+- 0-20: Critical preprocessing (security, validation)
+- 21-40: Data transformation
+- 41-60: Enhancement and enrichment
+- 61-80: Analytics and metrics
+- 81-100: Low priority post-processing
+
+## Migration from HTTP-based Hooks
+
+If you're migrating from the old HTTP-based hook system, see `/docs/hook_system_migration_guide.md` for detailed instructions.
+
+Key changes:
+- No server startup required
+- Import from `json_rpc_hook_client` instead of `hook_client`
+- Automatic hook discovery from `builtin/` directory
+- Better error handling and performance
+
+## Best Practices
+
+1. **Keep Hooks Fast**: Hooks run synchronously, so keep execution time minimal
+2. **Handle Errors Gracefully**: Always return a HookResult, even on failure
+3. **Use Appropriate Priority**: Consider hook dependencies when setting priority
+4. **Validate Input**: Always validate context data before processing
+5. **Log Important Events**: Use logging for debugging and monitoring
+6. **Make Hooks Idempotent**: Hooks should produce same result if run multiple times
+
+## Troubleshooting
+
+### Hooks Not Discovered
+- Verify hook file is in `builtin/` directory
+- Check file has `.py` extension
+- Ensure hook class inherits from correct base type
+- Check for Python syntax errors
+
+### Hook Execution Errors
+- Enable debug logging to see detailed errors
+- Check hook's execute method returns HookResult
+- Verify context data structure matches expectations
+
+### Performance Issues
+- Check hook execution times in results
+- Consider caching expensive operations
+- Profile hooks with `cProfile` if needed
+
+## Examples
+
+See the `builtin/` directory for example implementations:
+- `submit_hook_example.py`: Ticket and priority detection
+- `pre_delegation_hook_example.py`: Context filtering and enhancement  
+- `post_delegation_hook_example.py`: Result validation and metrics
+- `ticket_extraction_hook_example.py`: Automatic ticket extraction

claude_mpm/hooks/__init__.py

@@ -0,0 +1,5 @@
+"""Hook system for claude-mpm."""
+
+from .base_hook import BaseHook, HookContext, HookResult, HookType
+
+__all__ = ["BaseHook", "HookContext", "HookResult", "HookType"]

claude_mpm/hooks/base_hook.py

@@ -0,0 +1,154 @@
+"""Base hook class and types for claude-mpm hook system."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+import asyncio
+import logging
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+class HookType(Enum):
+    """Types of hooks available in the system."""
+    SUBMIT = "submit"  # Process user prompts
+    PRE_DELEGATION = "pre_delegation"  # Filter context before delegation
+    POST_DELEGATION = "post_delegation"  # Process results after delegation
+    TICKET_EXTRACTION = "ticket_extraction"  # Extract and create tickets
+    CUSTOM = "custom"  # User-defined hooks
+
+
+@dataclass
+class HookContext:
+    """Context passed to hooks for processing."""
+    hook_type: HookType
+    data: Dict[str, Any]
+    metadata: Dict[str, Any]
+    timestamp: datetime
+    session_id: Optional[str] = None
+    user_id: Optional[str] = None
+    
+    def __post_init__(self):
+        """Ensure timestamp is set."""
+        if not hasattr(self, 'timestamp') or self.timestamp is None:
+            self.timestamp = datetime.now()
+
+
+@dataclass
+class HookResult:
+    """Result returned from hook execution."""
+    success: bool
+    data: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+    modified: bool = False
+    metadata: Optional[Dict[str, Any]] = None
+    execution_time_ms: Optional[float] = None
+
+
+class BaseHook(ABC):
+    """Base class for all hooks."""
+    
+    def __init__(self, name: str, priority: int = 50):
+        """Initialize hook with name and priority.
+        
+        Args:
+            name: Unique name for the hook
+            priority: Execution priority (0-100, lower executes first)
+        """
+        self.name = name
+        self.priority = max(0, min(100, priority))  # Clamp to 0-100
+        self.enabled = True
+        self._async = False
+        
+    @abstractmethod
+    def execute(self, context: HookContext) -> HookResult:
+        """Execute the hook with given context.
+        
+        Args:
+            context: Hook context containing data and metadata
+            
+        Returns:
+            HookResult with execution results
+        """
+        pass
+    
+    async def async_execute(self, context: HookContext) -> HookResult:
+        """Async version of execute. Override for async hooks."""
+        # Default implementation calls sync execute in executor
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, self.execute, context)
+    
+    def validate(self, context: HookContext) -> bool:
+        """Validate if hook should run for given context.
+        
+        Args:
+            context: Hook context to validate
+            
+        Returns:
+            True if hook should execute, False otherwise
+        """
+        return self.enabled
+    
+    def __repr__(self):
+        """String representation of hook."""
+        return f"{self.__class__.__name__}(name='{self.name}', priority={self.priority}, enabled={self.enabled})"
+    
+    def __lt__(self, other):
+        """Compare hooks by priority for sorting."""
+        if not isinstance(other, BaseHook):
+            return NotImplemented
+        return self.priority < other.priority
+
+
+class SubmitHook(BaseHook):
+    """Base class for hooks that process user prompts."""
+    
+    def __init__(self, name: str, priority: int = 50):
+        super().__init__(name, priority)
+        
+    def validate(self, context: HookContext) -> bool:
+        """Validate submit hook context."""
+        if not super().validate(context):
+            return False
+        return context.hook_type == HookType.SUBMIT and 'prompt' in context.data
+
+
+class PreDelegationHook(BaseHook):
+    """Base class for hooks that filter context before delegation."""
+    
+    def __init__(self, name: str, priority: int = 50):
+        super().__init__(name, priority)
+        
+    def validate(self, context: HookContext) -> bool:
+        """Validate pre-delegation hook context."""
+        if not super().validate(context):
+            return False
+        return context.hook_type == HookType.PRE_DELEGATION and 'agent' in context.data
+
+
+class PostDelegationHook(BaseHook):
+    """Base class for hooks that process results after delegation."""
+    
+    def __init__(self, name: str, priority: int = 50):
+        super().__init__(name, priority)
+        
+    def validate(self, context: HookContext) -> bool:
+        """Validate post-delegation hook context."""
+        if not super().validate(context):
+            return False
+        return context.hook_type == HookType.POST_DELEGATION and 'result' in context.data
+
+
+class TicketExtractionHook(BaseHook):
+    """Base class for hooks that extract and create tickets."""
+    
+    def __init__(self, name: str, priority: int = 50):
+        super().__init__(name, priority)
+        
+    def validate(self, context: HookContext) -> bool:
+        """Validate ticket extraction hook context."""
+        if not super().validate(context):
+            return False
+        return context.hook_type == HookType.TICKET_EXTRACTION

claude_mpm/hooks/builtin/__init__.py

@@ -0,0 +1 @@
+"""Built-in hooks for claude-mpm."""

claude_mpm/hooks/builtin/logging_hook_example.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""
+Example logging hook for Claude MPM.
+
+This hook demonstrates how to capture and log all prompts and responses
+through the hook system, providing an alternative to built-in logging.
+"""
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+# Configure your logging directory
+LOG_DIR = Path.home() / ".claude-mpm-hook-logs"
+LOG_DIR.mkdir(exist_ok=True)
+
+
+def execute_pre_delegation_hook(agent: str, context: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Log task details before delegation.
+    
+    Args:
+        agent: The agent being invoked
+        context: Contains 'task' and other context data
+    
+    Returns:
+        Empty dict (no modifications)
+    """
+    timestamp = datetime.now().isoformat()
+    log_entry = {
+        "timestamp": timestamp,
+        "event": "pre_delegation",
+        "agent": agent,
+        "task": context.get("task", ""),
+        "context": context
+    }
+    
+    # Write to daily log file
+    log_file = LOG_DIR / f"delegations_{datetime.now().strftime('%Y%m%d')}.jsonl"
+    with open(log_file, 'a') as f:
+        f.write(json.dumps(log_entry) + '\n')
+    
+    return {}
+
+
+def execute_post_delegation_hook(agent: str, result: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Log complete prompt and response after delegation.
+    
+    Args:
+        agent: The agent that was invoked
+        result: Contains task, response, execution_time, tokens
+    
+    Returns:
+        Empty dict (no modifications)
+    """
+    timestamp = datetime.now().isoformat()
+    
+    # Extract data
+    task = result.get("task", "")
+    response = result.get("response", "")
+    execution_time = result.get("execution_time", 0)
+    tokens = result.get("tokens", 0)
+    
+    # Create detailed log entry
+    log_entry = {
+        "timestamp": timestamp,
+        "event": "post_delegation",
+        "agent": agent,
+        "task": task,
+        "response_length": len(response),
+        "execution_time": execution_time,
+        "tokens": tokens,
+        "success": not response.startswith("Error:"),
+        "response_preview": response[:500] + "..." if len(response) > 500 else response
+    }
+    
+    # Write to agent-specific log
+    agent_log_dir = LOG_DIR / "agents" / agent.lower()
+    agent_log_dir.mkdir(parents=True, exist_ok=True)
+    
+    log_file = agent_log_dir / f"{datetime.now().strftime('%Y%m%d')}.jsonl"
+    with open(log_file, 'a') as f:
+        f.write(json.dumps(log_entry) + '\n')
+    
+    # Save full prompt/response if needed
+    if os.environ.get("CLAUDE_MPM_HOOK_LOG_FULL", "").lower() == "true":
+        # Create unique filename
+        task_hash = str(hash(task))[-8:]
+        prompt_file = agent_log_dir / f"prompt_{timestamp}_{task_hash}.txt"
+        response_file = agent_log_dir / f"response_{timestamp}_{task_hash}.txt"
+        
+        # Note: We don't have access to the original prompt in post-delegation
+        # To capture prompts, you'd need to store them in pre-delegation
+        # and match them up using task hash or similar
+        
+        response_file.write_text(response)
+        
+        log_entry["response_file"] = str(response_file)
+    
+    return {}
+
+
+def execute_submit_hook(prompt: str, session_type: str) -> Dict[str, Any]:
+    """
+    Log user prompts at session start.
+    
+    Args:
+        prompt: The user's input prompt
+        session_type: Type of session (e.g., "subprocess")
+    
+    Returns:
+        Empty dict (no modifications)
+    """
+    timestamp = datetime.now().isoformat()
+    log_entry = {
+        "timestamp": timestamp,
+        "event": "user_submit",
+        "session_type": session_type,
+        "prompt": prompt,
+        "prompt_length": len(prompt)
+    }
+    
+    # Write to session log
+    log_file = LOG_DIR / f"sessions_{datetime.now().strftime('%Y%m%d')}.jsonl"
+    with open(log_file, 'a') as f:
+        f.write(json.dumps(log_entry) + '\n')
+    
+    print(f"[Logging Hook] Logged user prompt to {log_file}")
+    
+    return {}
+
+
+# Optional: Hook metadata for registration
+HOOK_METADATA = {
+    "name": "logging_hook",
+    "description": "Comprehensive logging of all prompts and responses",
+    "version": "1.0.0",
+    "author": "claude-mpm",
+    "events": ["pre_delegation", "post_delegation", "submit"],
+    "config": {
+        "log_dir": str(LOG_DIR),
+        "full_logging": os.environ.get("CLAUDE_MPM_HOOK_LOG_FULL", "false")
+    }
+}
+
+
+if __name__ == "__main__":
+    # Test the hook
+    print(f"Logging hook configured to write to: {LOG_DIR}")
+    print("Set CLAUDE_MPM_HOOK_LOG_FULL=true to save complete responses")
+    
+    # Example usage
+    execute_submit_hook("Test prompt", "test")
+    execute_pre_delegation_hook("Engineer", {"task": "Test task"})
+    execute_post_delegation_hook("Engineer", {
+        "task": "Test task",
+        "response": "Test response",
+        "execution_time": 1.5,
+        "tokens": 100
+    })
+    
+    print(f"\nCheck logs in: {LOG_DIR}")

claude_mpm/hooks/builtin/post_delegation_hook_example.py

@@ -0,0 +1,124 @@
+"""Example post-delegation hook implementation."""
+
+import json
+import re
+from typing import Dict, Any, List
+
+from claude_mpm.hooks.base_hook import PostDelegationHook, HookContext, HookResult
+from claude_mpm.core.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class ResultValidatorHook(PostDelegationHook):
+    """Hook that validates agent results for quality and completeness."""
+    
+    def __init__(self):
+        super().__init__(name="result_validator", priority=10)
+        
+    def execute(self, context: HookContext) -> HookResult:
+        """Validate agent results."""
+        try:
+            result = context.data.get('result', {})
+            agent = context.data.get('agent', 'unknown')
+            
+            # Validation checks
+            issues = []
+            
+            # Check for empty results
+            if not result:
+                issues.append("Empty result returned")
+                
+            # Check for error indicators
+            error_patterns = ['error', 'failed', 'exception', 'traceback']
+            result_str = json.dumps(result).lower()
+            for pattern in error_patterns:
+                if pattern in result_str and 'success' not in result:
+                    issues.append(f"Result contains '{pattern}' indicator")
+                    
+            # Agent-specific validation
+            if agent.lower() == 'engineer' and 'code' in str(result):
+                # Check for code quality indicators
+                if 'todo' in result_str or 'fixme' in result_str:
+                    issues.append("Code contains TODO/FIXME comments")
+                    
+            if issues:
+                logger.warning(f"Validation issues found: {issues}")
+                return HookResult(
+                    success=True,
+                    data={
+                        'result': result,
+                        'validation_issues': issues
+                    },
+                    modified=True,
+                    metadata={'issues_count': len(issues)}
+                )
+            else:
+                return HookResult(
+                    success=True,
+                    data=context.data,
+                    modified=False,
+                    metadata={'validated': True}
+                )
+                
+        except Exception as e:
+            logger.error(f"Result validation failed: {e}")
+            return HookResult(
+                success=False,
+                error=str(e)
+            )
+
+
+class ResultMetricsHook(PostDelegationHook):
+    """Hook that collects metrics from agent results."""
+    
+    def __init__(self):
+        super().__init__(name="result_metrics", priority=50)
+        
+    def execute(self, context: HookContext) -> HookResult:
+        """Collect metrics from agent results."""
+        try:
+            result = context.data.get('result', {})
+            agent = context.data.get('agent', 'unknown')
+            execution_time = context.metadata.get('execution_time_ms', 0)
+            
+            # Collect metrics
+            metrics = {
+                'agent': agent,
+                'execution_time_ms': execution_time,
+                'result_size_bytes': len(json.dumps(result).encode()),
+                'timestamp': context.timestamp.isoformat()
+            }
+            
+            # Agent-specific metrics
+            if agent.lower() == 'engineer':
+                # Count code-related metrics
+                code_content = str(result)
+                metrics['lines_of_code'] = code_content.count('\n')
+                metrics['functions_created'] = len(re.findall(r'def\s+\w+', code_content))
+                metrics['classes_created'] = len(re.findall(r'class\s+\w+', code_content))
+                
+            elif agent.lower() == 'qa':
+                # Count test-related metrics
+                test_content = str(result)
+                metrics['tests_count'] = len(re.findall(r'test_\w+', test_content))
+                metrics['assertions_count'] = len(re.findall(r'assert\s+', test_content))
+                
+            logger.info(f"Collected metrics: {metrics}")
+            
+            return HookResult(
+                success=True,
+                data={
+                    'result': result,
+                    'metrics': metrics
+                },
+                modified=True,
+                metadata=metrics
+            )
+            
+        except Exception as e:
+            logger.error(f"Metrics collection failed: {e}")
+            return HookResult(
+                success=False,
+                error=str(e)
+            )