claude-mpm 0.3.0__py3-none-any.whl

claude_mpm/hooks/builtin/todo_agent_prefix_hook.py

@@ -0,0 +1,239 @@
+"""Hook to enforce [Agent] prefix requirement for TodoWrite tool calls."""
+
+import re
+from typing import Dict, Any, List, Optional
+
+from claude_mpm.hooks.base_hook import BaseHook, HookContext, HookResult, HookType
+from claude_mpm.core.logger import get_logger
+from claude_mpm.core.agent_name_normalizer import agent_name_normalizer
+
+logger = get_logger(__name__)
+
+
+class TodoAgentPrefixHook(BaseHook):
+    """Hook that enforces agent name prefixes in TodoWrite tool calls."""
+    
+    def __init__(self):
+        super().__init__(name="todo_agent_prefix_enforcer", priority=20)
+        
+        # Mapping of task content patterns to appropriate agent prefixes
+        self.agent_patterns = {
+            'engineer': [
+                r'implement', r'code', r'fix', r'refactor', r'debug', r'develop',
+                r'create.*function', r'write.*class', r'add.*feature', r'optimize.*code'
+            ],
+            'research': [
+                r'research', r'investigate', r'analyze', r'explore', r'find.*best',
+                r'compare', r'evaluate', r'study', r'discover', r'understand'
+            ],
+            'documentation': [
+                r'document', r'write.*doc', r'update.*readme', r'changelog',
+                r'create.*guide', r'explain', r'describe', r'write.*tutorial'
+            ],
+            'qa': [
+                r'test', r'validate', r'verify', r'check', r'ensure.*quality',
+                r'run.*tests', r'coverage', r'lint', r'audit'
+            ],
+            'security': [
+                r'security', r'vulnerability', r'protect', r'secure', r'audit.*security',
+                r'penetration', r'encrypt', r'authenticate', r'authorize'
+            ],
+            'ops': [
+                r'deploy', r'configure', r'setup', r'install', r'provision',
+                r'infrastructure', r'ci/cd', r'pipeline', r'monitor'
+            ],
+            'data_engineer': [
+                r'data.*pipeline', r'etl', r'database', r'schema', r'migrate',
+                r'transform.*data', r'api.*integration', r'data.*flow'
+            ],
+            'version_control': [
+                r'version', r'release', r'tag', r'branch', r'merge',
+                r'git', r'commit', r'push', r'pull'
+            ]
+        }
+        
+        # Compile patterns for efficiency
+        self.compiled_patterns = {}
+        for agent, patterns in self.agent_patterns.items():
+            self.compiled_patterns[agent] = [
+                re.compile(pattern, re.IGNORECASE) for pattern in patterns
+            ]
+    
+    def execute(self, context: HookContext) -> HookResult:
+        """Check and enforce agent prefix in TodoWrite calls."""
+        try:
+            # This hook is designed to work with tool interception
+            # Check if this is a TodoWrite tool call
+            if context.hook_type != HookType.CUSTOM:
+                return HookResult(success=True, modified=False)
+            
+            tool_name = context.data.get('tool_name', '')
+            if tool_name != 'TodoWrite':
+                return HookResult(success=True, modified=False)
+            
+            # Extract todos from the tool parameters
+            tool_params = context.data.get('parameters', {})
+            todos = tool_params.get('todos', [])
+            
+            if not todos:
+                return HookResult(success=True, modified=False)
+            
+            # Check and fix each todo item
+            modified = False
+            validation_errors = []
+            updated_todos = []
+            
+            for todo in todos:
+                content = todo.get('content', '')
+                
+                # Check if content already has an agent prefix
+                if self._has_agent_prefix(content):
+                    updated_todos.append(todo)
+                    continue
+                
+                # Try to determine appropriate agent
+                suggested_agent = self._suggest_agent(content)
+                
+                if suggested_agent:
+                    # Automatically add the prefix using normalized format
+                    prefix = agent_name_normalizer.to_todo_prefix(suggested_agent)
+                    todo['content'] = f"{prefix} {content}"
+                    updated_todos.append(todo)
+                    modified = True
+                    logger.info(f"Added '{prefix}' prefix to todo: {content[:50]}...")
+                else:
+                    # If we can't determine the agent, block the call
+                    validation_errors.append(
+                        f"Todo item missing required [Agent] prefix: '{content[:50]}...'. "
+                        f"Please prefix with one of: [Research], [Engineer], [QA], "
+                        f"[Security], [Documentation], [Ops], [Data Engineer], or [Version Control]."
+                    )
+            
+            # If there are validation errors, block the call
+            if validation_errors:
+                return HookResult(
+                    success=False,
+                    error="\n".join(validation_errors),
+                    metadata={'validation_failed': True}
+                )
+            
+            # If we modified any todos, update the parameters
+            if modified:
+                tool_params['todos'] = updated_todos
+                return HookResult(
+                    success=True,
+                    data={
+                        'tool_name': tool_name,
+                        'parameters': tool_params
+                    },
+                    modified=True,
+                    metadata={'prefixes_added': True}
+                )
+            
+            return HookResult(success=True, modified=False)
+            
+        except Exception as e:
+            logger.error(f"Todo agent prefix enforcement failed: {e}")
+            return HookResult(
+                success=False,
+                error=str(e)
+            )
+    
+    def _has_agent_prefix(self, content: str) -> bool:
+        """Check if content already has an agent prefix."""
+        content = content.strip()
+        # Check if content has a valid agent prefix
+        agent = agent_name_normalizer.extract_from_todo(content)
+        return agent is not None
+    
+    def _suggest_agent(self, content: str) -> Optional[str]:
+        """Suggest an appropriate agent based on content analysis."""
+        content_lower = content.lower()
+        
+        # Check each agent's patterns
+        for agent, patterns in self.compiled_patterns.items():
+            for pattern in patterns:
+                if pattern.search(content_lower):
+                    return agent_name_normalizer.normalize(agent)
+        
+        # Default suggestions based on common keywords
+        if any(word in content_lower for word in ['code', 'implement', 'fix', 'bug']):
+            return 'engineer'
+        elif any(word in content_lower for word in ['test', 'validate', 'check']):
+            return 'qa'
+        elif any(word in content_lower for word in ['doc', 'readme', 'guide']):
+            return 'documentation'
+        elif any(word in content_lower for word in ['research', 'investigate']):
+            return 'research'
+        
+        return None
+    
+    def validate(self, context: HookContext) -> bool:
+        """Validate if hook should run for given context."""
+        if not super().validate(context):
+            return False
+        
+        # This hook only runs for CUSTOM type with tool_name = TodoWrite
+        return (context.hook_type == HookType.CUSTOM and 
+                context.data.get('tool_name') == 'TodoWrite')
+
+
+class TodoAgentPrefixValidatorHook(BaseHook):
+    """Alternative hook that only validates without auto-fixing."""
+    
+    def __init__(self):
+        super().__init__(name="todo_agent_prefix_validator", priority=15)
+        # Get valid agents from normalizer
+        self.valid_agents = list(agent_name_normalizer.CANONICAL_NAMES.values())
+    
+    def execute(self, context: HookContext) -> HookResult:
+        """Validate agent prefix in TodoWrite calls without auto-fixing."""
+        try:
+            # Check if this is a TodoWrite tool call
+            if context.data.get('tool_name') != 'TodoWrite':
+                return HookResult(success=True, modified=False)
+            
+            # Extract todos
+            tool_params = context.data.get('parameters', {})
+            todos = tool_params.get('todos', [])
+            
+            validation_errors = []
+            
+            for i, todo in enumerate(todos):
+                content = todo.get('content', '')
+                
+                # Check for agent prefix using normalizer
+                if not agent_name_normalizer.extract_from_todo(content):
+                    validation_errors.append(
+                        f"Todo #{i+1} missing required agent prefix. "
+                        f"Content: '{content[:50]}...'\n"
+                        f"Please use format: '[Agent] Task description' where [Agent] is one of: "
+                        f"{', '.join('[' + agent + ']' for agent in self.valid_agents)}"
+                    )
+            
+            if validation_errors:
+                return HookResult(
+                    success=False,
+                    error="\n\n".join(validation_errors),
+                    metadata={
+                        'validation_type': 'agent_prefix',
+                        'valid_agents': self.valid_agents
+                    }
+                )
+            
+            return HookResult(success=True, modified=False)
+            
+        except Exception as e:
+            logger.error(f"Todo validation failed: {e}")
+            return HookResult(
+                success=False,
+                error=str(e)
+            )
+    
+    def validate(self, context: HookContext) -> bool:
+        """Validate if hook should run for given context."""
+        if not super().validate(context):
+            return False
+        
+        return (context.hook_type == HookType.CUSTOM and 
+                context.data.get('tool_name') == 'TodoWrite')

claude_mpm/hooks/builtin/workflow_start_hook.py

@@ -0,0 +1,181 @@
+"""Hook to log workflow information at the start of execution."""
+
+import json
+from typing import Dict, Any, List, Optional
+from datetime import datetime
+
+from claude_mpm.hooks.base_hook import SubmitHook, HookContext, HookResult, HookType
+from claude_mpm.core.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class WorkflowStartHook(SubmitHook):
+    """Hook that logs workflow information including steps list at workflow start."""
+    
+    def __init__(self):
+        super().__init__(name="workflow_start_logger", priority=5)
+    
+    def execute(self, context: HookContext) -> HookResult:
+        """Log workflow information when a workflow starts."""
+        try:
+            # Extract prompt and workflow data from context
+            prompt = context.data.get('prompt', '')
+            workflow_data = context.data.get('workflow', {})
+            
+            # Check if this is a workflow start (either by explicit workflow data or detected pattern)
+            if workflow_data or self._is_workflow_prompt(prompt):
+                # Extract workflow information
+                workflow_name = workflow_data.get('name', 'Unnamed Workflow')
+                workflow_steps = workflow_data.get('steps', [])
+                
+                # If no explicit steps provided, try to parse from prompt
+                if not workflow_steps and prompt:
+                    workflow_steps = self._extract_steps_from_prompt(prompt)
+                
+                # Log workflow start information
+                logger.info("="*60)
+                logger.info("WORKFLOW START")
+                logger.info("="*60)
+                logger.info(f"Workflow: {workflow_name}")
+                logger.info(f"Started at: {context.timestamp.isoformat()}")
+                logger.info(f"Session ID: {context.session_id or 'N/A'}")
+                logger.info(f"User ID: {context.user_id or 'N/A'}")
+                
+                if workflow_steps:
+                    logger.info(f"\nWorkflow Steps ({len(workflow_steps)} total):")
+                    for i, step in enumerate(workflow_steps, 1):
+                        if isinstance(step, dict):
+                            step_name = step.get('name', step.get('description', 'Unnamed step'))
+                            step_type = step.get('type', 'task')
+                            logger.info(f"  {i}. [{step_type}] {step_name}")
+                        else:
+                            # Handle simple string steps
+                            logger.info(f"  {i}. {step}")
+                else:
+                    logger.info("\nNo explicit workflow steps defined")
+                
+                # Log additional metadata if present
+                metadata = workflow_data.get('metadata', {})
+                if metadata:
+                    logger.info(f"\nWorkflow Metadata:")
+                    for key, value in metadata.items():
+                        logger.info(f"  {key}: {value}")
+                
+                logger.info("="*60)
+                
+                # Add workflow info to result metadata for downstream hooks
+                return HookResult(
+                    success=True,
+                    modified=False,
+                    metadata={
+                        'workflow_logged': True,
+                        'workflow_name': workflow_name,
+                        'step_count': len(workflow_steps),
+                        'has_explicit_workflow': bool(workflow_data)
+                    }
+                )
+            
+            # Not a workflow start, pass through
+            return HookResult(success=True, modified=False)
+            
+        except Exception as e:
+            logger.error(f"Workflow start logging failed: {e}")
+            # Don't block execution on logging errors
+            return HookResult(
+                success=True,
+                modified=False,
+                error=str(e)
+            )
+    
+    def _is_workflow_prompt(self, prompt: str) -> bool:
+        """Detect if a prompt indicates a workflow start."""
+        if not prompt:
+            return False
+        
+        prompt_lower = prompt.lower()
+        workflow_indicators = [
+            'workflow', 'steps:', 'step 1', 'first,', 'then,', 'finally,',
+            'process:', 'procedure:', 'sequence:', 'plan:'
+        ]
+        
+        return any(indicator in prompt_lower for indicator in workflow_indicators)
+    
+    def _extract_steps_from_prompt(self, prompt: str) -> List[str]:
+        """Try to extract workflow steps from a prompt text."""
+        steps = []
+        
+        # Look for numbered steps (1. 2. 3. or 1) 2) 3))
+        import re
+        numbered_pattern = re.compile(r'^\s*\d+[\)\.]\s*(.+)$', re.MULTILINE)
+        matches = numbered_pattern.findall(prompt)
+        if matches:
+            steps.extend(matches)
+            return steps
+        
+        # Look for bullet points
+        bullet_pattern = re.compile(r'^\s*[-*•]\s*(.+)$', re.MULTILINE)
+        matches = bullet_pattern.findall(prompt)
+        if matches:
+            steps.extend(matches)
+            return steps
+        
+        # Look for sequential keywords
+        sequential_pattern = re.compile(
+            r'(?:first|then|next|after that|finally|lastly),?\s*(.+?)(?=(?:first|then|next|after that|finally|lastly|$))',
+            re.IGNORECASE | re.DOTALL
+        )
+        matches = sequential_pattern.findall(prompt)
+        if matches:
+            steps.extend([m.strip() for m in matches if m.strip()])
+        
+        return steps
+    
+    def validate(self, context: HookContext) -> bool:
+        """Validate if hook should run for given context."""
+        if not super().validate(context):
+            return False
+        
+        # This hook runs for all submit contexts to check for workflows
+        return context.hook_type == HookType.SUBMIT
+
+
+class WorkflowStepLogger(SubmitHook):
+    """Alternative hook that logs individual workflow step execution."""
+    
+    def __init__(self):
+        super().__init__(name="workflow_step_logger", priority=6)
+    
+    def execute(self, context: HookContext) -> HookResult:
+        """Log individual workflow step execution."""
+        try:
+            # Check if this is a workflow step execution
+            step_data = context.data.get('workflow_step', {})
+            if not step_data:
+                return HookResult(success=True, modified=False)
+            
+            # Extract step information
+            step_number = step_data.get('number', 0)
+            step_name = step_data.get('name', 'Unnamed step')
+            step_type = step_data.get('type', 'task')
+            workflow_name = step_data.get('workflow_name', 'Unknown workflow')
+            
+            # Log step execution
+            logger.info(f"\n→ Executing Step {step_number}: {step_name}")
+            logger.info(f"  Type: {step_type}")
+            logger.info(f"  Workflow: {workflow_name}")
+            logger.info(f"  Started: {context.timestamp.isoformat()}")
+            
+            return HookResult(
+                success=True,
+                modified=False,
+                metadata={
+                    'step_logged': True,
+                    'step_number': step_number,
+                    'step_name': step_name
+                }
+            )
+            
+        except Exception as e:
+            logger.error(f"Workflow step logging failed: {e}")
+            return HookResult(success=True, modified=False, error=str(e))

claude_mpm/hooks/hook_client.py

@@ -0,0 +1,264 @@
+"""Client for interacting with the hook service.
+
+DEPRECATED: This HTTP-based hook client is deprecated and will be removed in a future release.
+Please use the JSON-RPC implementation from claude_mpm.hooks.json_rpc_hook_client instead.
+See /docs/hook_system_migration_guide.md for migration instructions.
+"""
+
+import json
+import logging
+import warnings
+from typing import Any, Dict, List, Optional
+from urllib.parse import urljoin
+
+import requests
+from requests.adapters import HTTPAdapter
+from requests.packages.urllib3.util.retry import Retry
+
+from claude_mpm.hooks.base_hook import HookType
+from claude_mpm.core.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class HookServiceClient:
+    """Client for interacting with the centralized hook service.
+    
+    DEPRECATED: Use JSONRPCHookClient from claude_mpm.hooks.json_rpc_hook_client instead.
+    """
+    
+    def __init__(self, base_url: str = "http://localhost:5001", timeout: int = 30):
+        """Initialize hook service client.
+        
+        Args:
+            base_url: Base URL of hook service
+            timeout: Request timeout in seconds
+        """
+        warnings.warn(
+            "HookServiceClient is deprecated and will be removed in a future release. "
+            "Please use JSONRPCHookClient from claude_mpm.hooks.json_rpc_hook_client instead. "
+            "See /docs/hook_system_migration_guide.md for migration instructions.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        self.base_url = base_url.rstrip('/')
+        self.timeout = timeout
+        
+        # Setup session with retry logic
+        self.session = requests.Session()
+        retry_strategy = Retry(
+            total=3,
+            backoff_factor=1,
+            status_forcelist=[429, 500, 502, 503, 504]
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        self.session.mount("http://", adapter)
+        self.session.mount("https://", adapter)
+        
+    def health_check(self) -> Dict[str, Any]:
+        """Check health of hook service.
+        
+        Returns:
+            Health status dictionary
+        """
+        try:
+            response = self.session.get(
+                urljoin(self.base_url, '/health'),
+                timeout=self.timeout
+            )
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            logger.error(f"Health check failed: {e}")
+            return {
+                'status': 'unhealthy',
+                'error': str(e)
+            }
+            
+    def list_hooks(self) -> Dict[str, List[Dict[str, Any]]]:
+        """List all registered hooks.
+        
+        Returns:
+            Dictionary mapping hook types to hook info
+        """
+        try:
+            response = self.session.get(
+                urljoin(self.base_url, '/hooks/list'),
+                timeout=self.timeout
+            )
+            response.raise_for_status()
+            data = response.json()
+            return data.get('hooks', {})
+        except Exception as e:
+            logger.error(f"Failed to list hooks: {e}")
+            return {}
+            
+    def execute_hook(self, hook_type: HookType, context_data: Dict[str, Any],
+                    metadata: Optional[Dict[str, Any]] = None,
+                    specific_hook: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Execute hooks of a given type.
+        
+        Args:
+            hook_type: Type of hooks to execute
+            context_data: Data to pass to hooks
+            metadata: Optional metadata
+            specific_hook: Optional specific hook name to execute
+            
+        Returns:
+            List of execution results
+        """
+        try:
+            payload = {
+                'hook_type': hook_type.value,
+                'context': context_data,
+                'metadata': metadata or {}
+            }
+            
+            if specific_hook:
+                payload['hook_name'] = specific_hook
+                
+            response = self.session.post(
+                urljoin(self.base_url, '/hooks/execute'),
+                json=payload,
+                timeout=self.timeout
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            if data.get('status') == 'success':
+                return data.get('results', [])
+            else:
+                logger.error(f"Hook execution failed: {data.get('error')}")
+                return []
+                
+        except Exception as e:
+            logger.error(f"Failed to execute hooks: {e}")
+            return []
+            
+    def execute_submit_hook(self, prompt: str, **kwargs) -> List[Dict[str, Any]]:
+        """Execute submit hooks on a user prompt.
+        
+        Args:
+            prompt: User prompt to process
+            **kwargs: Additional context data
+            
+        Returns:
+            List of execution results
+        """
+        context_data = {'prompt': prompt}
+        context_data.update(kwargs)
+        return self.execute_hook(HookType.SUBMIT, context_data)
+        
+    def execute_pre_delegation_hook(self, agent: str, context: Dict[str, Any],
+                                   **kwargs) -> List[Dict[str, Any]]:
+        """Execute pre-delegation hooks.
+        
+        Args:
+            agent: Agent being delegated to
+            context: Context being passed to agent
+            **kwargs: Additional data
+            
+        Returns:
+            List of execution results
+        """
+        context_data = {
+            'agent': agent,
+            'context': context
+        }
+        context_data.update(kwargs)
+        return self.execute_hook(HookType.PRE_DELEGATION, context_data)
+        
+    def execute_post_delegation_hook(self, agent: str, result: Any,
+                                    **kwargs) -> List[Dict[str, Any]]:
+        """Execute post-delegation hooks.
+        
+        Args:
+            agent: Agent that was delegated to
+            result: Result from agent
+            **kwargs: Additional data
+            
+        Returns:
+            List of execution results
+        """
+        context_data = {
+            'agent': agent,
+            'result': result
+        }
+        context_data.update(kwargs)
+        return self.execute_hook(HookType.POST_DELEGATION, context_data)
+        
+    def execute_ticket_extraction_hook(self, content: Any,
+                                      **kwargs) -> List[Dict[str, Any]]:
+        """Execute ticket extraction hooks.
+        
+        Args:
+            content: Content to extract tickets from
+            **kwargs: Additional data
+            
+        Returns:
+            List of execution results
+        """
+        context_data = {'content': content}
+        context_data.update(kwargs)
+        return self.execute_hook(HookType.TICKET_EXTRACTION, context_data)
+        
+    def get_modified_data(self, results: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Extract modified data from hook results.
+        
+        Args:
+            results: Hook execution results
+            
+        Returns:
+            Combined modified data from all hooks
+        """
+        modified_data = {}
+        
+        for result in results:
+            if result.get('modified') and result.get('data'):
+                modified_data.update(result['data'])
+                
+        return modified_data
+        
+    def get_extracted_tickets(self, results: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Extract tickets from hook results.
+        
+        Args:
+            results: Hook execution results
+            
+        Returns:
+            List of extracted tickets
+        """
+        all_tickets = []
+        
+        for result in results:
+            if result.get('success') and 'tickets' in result.get('data', {}):
+                tickets = result['data']['tickets']
+                if isinstance(tickets, list):
+                    all_tickets.extend(tickets)
+                    
+        return all_tickets
+
+
+# Convenience function for creating a default client
+def get_hook_client(base_url: Optional[str] = None) -> 'JSONRPCHookClient':
+    """Get a hook client instance.
+    
+    DEPRECATED: This function now returns a JSONRPCHookClient for compatibility.
+    Import directly from claude_mpm.hooks.json_rpc_hook_client instead.
+    
+    Args:
+        base_url: Ignored (kept for backward compatibility)
+        
+    Returns:
+        JSONRPCHookClient instance
+    """
+    warnings.warn(
+        "get_hook_client from hook_client module is deprecated. "
+        "Import from claude_mpm.hooks.json_rpc_hook_client instead.",
+        DeprecationWarning,
+        stacklevel=2
+    )
+    
+    # Import and return JSON-RPC client for compatibility
+    from claude_mpm.hooks.json_rpc_hook_client import JSONRPCHookClient
+    return JSONRPCHookClient()