claude-mpm 3.5.1__py3-none-any.whl → 3.5.4__py3-none-any.whl

claude_mpm/core/claude_runner.py

@@ -110,6 +110,22 @@ class ClaudeRunner:
             self.logger.error(f"Failed to load configuration: {e}")
             raise RuntimeError(f"Configuration initialization failed: {e}") from e
         
+        # Initialize response logging if enabled
+        self.response_logger = None
+        response_config = self.config.get('response_logging', {})
+        if response_config.get('enabled', False):
+            try:
+                from claude_mpm.services.claude_session_logger import get_session_logger
+                self.response_logger = get_session_logger(self.config)
+                if self.project_logger:
+                    self.project_logger.log_system(
+                        "Response logging initialized",
+                        level="INFO",
+                        component="logging"
+                    )
+            except Exception as e:
+                self.logger.warning(f"Failed to initialize response logger: {e}")
+        
         # Initialize hook service
         try:
             self.hook_service = HookService(self.config)
@@ -199,7 +215,7 @@ class ClaudeRunner:
             return False
         
         except FileNotFoundError as e:
-            error_msg = f"Agent templates not found: {e}"
+            error_msg = f"Agent files not found: {e}"
             self.logger.error(error_msg)
             print(f"❌ {error_msg}")
             print("💡 Ensure claude-mpm is properly installed")
@@ -228,9 +244,10 @@ class ClaudeRunner:
     def ensure_project_agents(self) -> bool:
         """Ensure system agents are available in the project directory.
         
-        Deploys system agents to project's .claude-mpm/agents/ directory
-        if they don't exist or are outdated. This enables project-level
-        agent customization and ensures all agents are available locally.
+        Deploys system agents to project's .claude/agents/ directory
+        if they don't exist or are outdated. This ensures agents are
+        available for Claude Code to use. Project-specific JSON templates
+        should be placed in .claude-mpm/agents/.
         
         Returns:
             bool: True if agents are available, False on error
@@ -250,10 +267,12 @@ class ClaudeRunner:
                     component="deployment"
                 )
             
-            # Deploy agents to project directory with project deployment mode
+            # Deploy agents to project's .claude/agents directory (not .claude-mpm)
             # This ensures all system agents are deployed regardless of version
+            # .claude-mpm/agents/ should only contain JSON source templates
+            # .claude/agents/ should contain the built MD files for Claude Code
             results = self.deployment_service.deploy_agents(
-                target_dir=project_dir / ".claude-mpm",
+                target_dir=project_dir / ".claude",
                 force_rebuild=False,
                 deployment_mode="project"
             )
@@ -286,8 +305,146 @@ class ClaudeRunner:
                 )
             return False
     
+    def deploy_project_agents_to_claude(self) -> bool:
+        """Deploy project agents from .claude-mpm/agents/ to .claude/agents/.
+        
+        This method handles the deployment of project-specific agents (JSON format)
+        from the project's agents directory to Claude's agent directory.
+        Project agents take precedence over system agents.
+        
+        WHY: Project agents allow teams to define custom, project-specific agents
+        that override system agents. These are stored in JSON format in 
+        .claude-mpm/agents/ and need to be deployed to .claude/agents/
+        as MD files for Claude to use them.
+        
+        Returns:
+            bool: True if deployment successful or no agents to deploy, False on error
+        """
+        try:
+            project_dir = Path.cwd()
+            project_agents_dir = project_dir / ".claude-mpm" / "agents"
+            claude_agents_dir = project_dir / ".claude" / "agents"
+            
+            # Check if project agents directory exists
+            if not project_agents_dir.exists():
+                self.logger.debug("No project agents directory found")
+                return True  # Not an error - just no project agents
+            
+            # Get JSON agent files from agents directory
+            json_files = list(project_agents_dir.glob("*.json"))
+            if not json_files:
+                self.logger.debug("No JSON agents in project")
+                return True
+            
+            # Create .claude/agents directory if needed
+            claude_agents_dir.mkdir(parents=True, exist_ok=True)
+            
+            self.logger.info(f"Deploying {len(json_files)} project agents to .claude/agents/")
+            if self.project_logger:
+                self.project_logger.log_system(
+                    f"Deploying project agents from {project_agents_dir} to {claude_agents_dir}",
+                    level="INFO",
+                    component="deployment"
+                )
+            
+            deployed_count = 0
+            updated_count = 0
+            errors = []
+            
+            # Deploy each JSON agent
+            for json_file in json_files:
+                try:
+                    agent_name = json_file.stem
+                    target_file = claude_agents_dir / f"{agent_name}.md"
+                    
+                    # Check if agent needs update
+                    needs_update = True
+                    if target_file.exists():
+                        # Check if it's a project agent (has project marker)
+                        existing_content = target_file.read_text()
+                        if "author: claude-mpm-project" in existing_content or "source: project" in existing_content:
+                            # Compare modification times
+                            if target_file.stat().st_mtime >= json_file.stat().st_mtime:
+                                needs_update = False
+                                self.logger.debug(f"Project agent {agent_name} is up to date")
+                    
+                    if needs_update:
+                        # Use deployment service to build the agent
+                        from claude_mpm.services.agents.deployment.agent_deployment import AgentDeploymentService
+                        
+                        # Create a temporary deployment service for this specific task
+                        project_deployment = AgentDeploymentService(
+                            templates_dir=project_agents_dir,
+                            base_agent_path=project_dir / ".claude-mpm" / "agents" / "base_agent.json"
+                        )
+                        
+                        # Load base agent data if available
+                        base_agent_data = {}
+                        base_agent_path = project_dir / ".claude-mpm" / "agents" / "base_agent.json"
+                        if base_agent_path.exists():
+                            import json
+                            try:
+                                base_agent_data = json.loads(base_agent_path.read_text())
+                            except Exception as e:
+                                self.logger.warning(f"Could not load project base agent: {e}")
+                        
+                        # Build the agent markdown
+                        agent_content = project_deployment._build_agent_markdown(
+                            agent_name, json_file, base_agent_data
+                        )
+                        
+                        # Mark as project agent
+                        agent_content = agent_content.replace(
+                            "author: claude-mpm",
+                            "author: claude-mpm-project"
+                        )
+                        
+                        # Write the agent file
+                        is_update = target_file.exists()
+                        target_file.write_text(agent_content)
+                        
+                        if is_update:
+                            updated_count += 1
+                            self.logger.info(f"Updated project agent: {agent_name}")
+                        else:
+                            deployed_count += 1
+                            self.logger.info(f"Deployed project agent: {agent_name}")
+                            
+                except Exception as e:
+                    error_msg = f"Failed to deploy project agent {json_file.name}: {e}"
+                    self.logger.error(error_msg)
+                    errors.append(error_msg)
+            
+            # Report results
+            if deployed_count > 0 or updated_count > 0:
+                print(f"✓ Deployed {deployed_count} project agents, updated {updated_count}")
+                if self.project_logger:
+                    self.project_logger.log_system(
+                        f"Project agent deployment: {deployed_count} deployed, {updated_count} updated",
+                        level="INFO",
+                        component="deployment"
+                    )
+            
+            if errors:
+                for error in errors:
+                    print(f"⚠️  {error}")
+                return False
+            
+            return True
+            
+        except Exception as e:
+            error_msg = f"Failed to deploy project agents: {e}"
+            self.logger.error(error_msg)
+            print(f"⚠️  {error_msg}")
+            if self.project_logger:
+                self.project_logger.log_system(error_msg, level="ERROR", component="deployment")
+            return False
+    
     def run_interactive(self, initial_context: Optional[str] = None):
         """Run Claude in interactive mode."""
+        # TODO: Add response logging for interactive mode
+        # This requires capturing stdout from the exec'd process or using subprocess with PTY
+        
         # Connect to Socket.IO server if enabled
         if self.enable_websocket:
             try:
@@ -336,10 +493,13 @@ class ClaudeRunner:
                 component="session"
             )
         
-        # Setup agents
+        # Setup agents - first deploy system agents, then project agents
         if not self.setup_agents():
             print("Continuing without native agents...")
         
+        # Deploy project-specific agents if they exist
+        self.deploy_project_agents_to_claude()
+        
         # Build command with system instructions
         cmd = [
             "claude",
@@ -587,10 +747,13 @@ class ClaudeRunner:
                 component="session"
             )
         
-        # Setup agents
+        # Setup agents - first deploy system agents, then project agents
         if not self.setup_agents():
             print("Continuing without native agents...")
         
+        # Deploy project-specific agents if they exist
+        self.deploy_project_agents_to_claude()
+        
         # Combine context and prompt
         full_prompt = prompt
         if context:
@@ -671,6 +834,22 @@ class ClaudeRunner:
                 response = result.stdout.strip()
                 print(response)
                 
+                # Log response if logging enabled
+                if self.response_logger and response:
+                    execution_time = time.time() - start_time
+                    response_summary = prompt[:200] + "..." if len(prompt) > 200 else prompt
+                    self.response_logger.log_response(
+                        request_summary=response_summary,
+                        response_content=response,
+                        metadata={
+                            "mode": "oneshot",
+                            "model": "opus",
+                            "exit_code": result.returncode,
+                            "execution_time": execution_time
+                        },
+                        agent="claude-direct"
+                    )
+                
                 # Broadcast output to WebSocket clients
                 if self.websocket_server and response:
                     self.websocket_server.claude_output(response, "stdout")
@@ -1185,6 +1364,10 @@ class ClaudeRunner:
         import tty
         import signal
         
+        # Collect output for response logging if enabled
+        collected_output = [] if self.response_logger else None
+        collected_input = [] if self.response_logger else None
+        
         # Save original terminal settings
         original_tty = None
         if sys.stdin.isatty():
@@ -1247,6 +1430,13 @@ class ClaudeRunner:
                         data = os.read(master_fd, 4096)
                         if data:
                             os.write(sys.stdout.fileno(), data)
+                            # Collect output for response logging
+                            if collected_output is not None:
+                                try:
+                                    output_text = data.decode('utf-8', errors='replace')
+                                    collected_output.append(output_text)
+                                except Exception:
+                                    pass
                             # Broadcast output to WebSocket clients
                             if self.websocket_server:
                                 try:
@@ -1265,12 +1455,38 @@ class ClaudeRunner:
                         data = os.read(sys.stdin.fileno(), 4096)
                         if data:
                             os.write(master_fd, data)
+                            # Collect input for response logging
+                            if collected_input is not None:
+                                try:
+                                    input_text = data.decode('utf-8', errors='replace')
+                                    collected_input.append(input_text)
+                                except Exception:
+                                    pass
                     except OSError:
                         break
             
             # Wait for process to complete
             process.wait()
             
+            # Log the interactive session if response logging is enabled
+            if self.response_logger and collected_output is not None and collected_output:
+                try:
+                    full_output = ''.join(collected_output)
+                    full_input = ''.join(collected_input) if collected_input else "Interactive session"
+                    self.response_logger.log_response(
+                        request_summary=f"Interactive session: {full_input[:200]}..." if len(full_input) > 200 else f"Interactive session: {full_input}",
+                        response_content=full_output,
+                        metadata={
+                            "mode": "interactive-subprocess",
+                            "model": "opus",
+                            "exit_code": process.returncode,
+                            "session_type": "subprocess"
+                        },
+                        agent="claude-interactive"
+                    )
+                except Exception as e:
+                    self.logger.debug(f"Failed to log interactive session: {e}")
+            
             if self.project_logger:
                 self.project_logger.log_system(
                     f"Claude subprocess exited with code {process.returncode}",

claude_mpm/services/agents/deployment/agent_deployment.py

@@ -75,7 +75,7 @@ class AgentDeploymentService:
         Initialize agent deployment service.
         
         Args:
-            templates_dir: Directory containing agent template files
+            templates_dir: Directory containing agent JSON files
             base_agent_path: Path to base_agent.md file
             
         METRICS OPPORTUNITY: Track initialization performance:
@@ -105,6 +105,8 @@ class AgentDeploymentService:
             self.templates_dir = Path(templates_dir)
         else:
             # Use centralized paths instead of fragile parent calculations
+            # For system agents, still use templates subdirectory
+            # For project/user agents, this should be overridden with actual agents dir
             self.templates_dir = paths.agents_dir / "templates"
         
         # Find base agent file
@@ -224,13 +226,20 @@ class AgentDeploymentService:
         try:
             # Create agents directory if needed
             agents_dir.mkdir(parents=True, exist_ok=True)
-            self.logger.info(f"Building and deploying agents to: {agents_dir}")
+            # Determine source tier for logging
+            source_tier = "SYSTEM"
+            if ".claude-mpm/agents" in str(self.templates_dir) and "/templates" not in str(self.templates_dir):
+                source_tier = "PROJECT" 
+            elif "/.claude-mpm/agents" in str(self.templates_dir) and "/templates" not in str(self.templates_dir):
+                source_tier = "USER"
+            
+            self.logger.info(f"Building and deploying {source_tier} agents to: {agents_dir}")
             
             # Note: System instructions are now loaded directly by SimpleClaudeRunner
             
             # Check if templates directory exists
             if not self.templates_dir.exists():
-                error_msg = f"Templates directory not found: {self.templates_dir}"
+                error_msg = f"Agents directory not found: {self.templates_dir}"
                 self.logger.error(error_msg)
                 results["errors"].append(error_msg)
                 return results
@@ -568,20 +577,36 @@ class AgentDeploymentService:
         # Simplify model name for Claude Code
         model_map = {
             'claude-4-sonnet-20250514': 'sonnet',
-            'claude-sonnet-4-20250514': 'sonnet', 
+            'claude-sonnet-4-20250514': 'sonnet',
+            'claude-opus-4-20250514': 'opus',
             'claude-3-opus-20240229': 'opus',
             'claude-3-haiku-20240307': 'haiku',
             'claude-3.5-sonnet': 'sonnet',
             'claude-3-sonnet': 'sonnet'
         }
-        model = model_map.get(model, model.split('-')[-1] if '-' in model else model)
+        # Better fallback: extract the model type (opus/sonnet/haiku) from the string
+        if model not in model_map:
+            if 'opus' in model.lower():
+                model = 'opus'
+            elif 'sonnet' in model.lower():
+                model = 'sonnet'
+            elif 'haiku' in model.lower():
+                model = 'haiku'
+            else:
+                # Last resort: try to extract from hyphenated format
+                model = model_map.get(model, model.split('-')[-1] if '-' in model else model)
+        else:
+            model = model_map[model]
         
         # Get response format from template or use base agent default
         response_format = template_data.get('response', {}).get('format', 'structured')
         
         # Convert lists to space-separated strings for Claude Code compatibility
         tags_str = ' '.join(tags) if isinstance(tags, list) else tags
-        tools_str = ', '.join(tools) if isinstance(tools, list) else tools
+        
+        # Convert tools list to comma-separated string for Claude Code compatibility
+        # IMPORTANT: No spaces after commas - Claude Code requires exact format
+        tools_str = ','.join(tools) if isinstance(tools, list) else tools
         
         # Build frontmatter with only the fields Claude Code uses
         frontmatter_lines = [
@@ -596,8 +621,13 @@ class AgentDeploymentService:
         ]
         
         # Add optional fields if present
-        if template_data.get('color'):
-            frontmatter_lines.append(f"color: {template_data['color']}")
+        # Check for color in metadata section (new format) or root (old format)
+        color = (
+            template_data.get('metadata', {}).get('color') or
+            template_data.get('color')
+        )
+        if color:
+            frontmatter_lines.append(f"color: {color}")
         
         frontmatter_lines.append("---")
         frontmatter_lines.append("")
@@ -1059,7 +1089,7 @@ temperature: {temperature}"""
         agents = []
         
         if not self.templates_dir.exists():
-            self.logger.warning(f"Templates directory not found: {self.templates_dir}")
+            self.logger.warning(f"Agents directory not found: {self.templates_dir}")
             return agents
         
         template_files = sorted(self.templates_dir.glob("*.json"))

claude_mpm/services/agents/registry/agent_registry.py

@@ -31,6 +31,7 @@ from enum import Enum
 
 from claude_mpm.core.config_paths import ConfigPaths
 from claude_mpm.services.memory.cache.simple_cache import SimpleCacheService
+from claude_mpm.agents.frontmatter_validator import FrontmatterValidator, ValidationResult
 
 logger = logging.getLogger(__name__)
 
@@ -130,6 +131,9 @@ class AgentRegistry:
         
         self.model_selector = model_selector
         
+        # Initialize frontmatter validator
+        self.frontmatter_validator = FrontmatterValidator()
+        
         # Registry storage
         self.registry: Dict[str, AgentMetadata] = {}
         self.discovery_paths: List[Path] = []
@@ -337,10 +341,27 @@ class AgentRegistry:
                             if len(parts) >= 3:
                                 frontmatter_text = parts[1].strip()
                                 data = yaml.safe_load(frontmatter_text)
+                                
+                                # Validate and correct frontmatter
+                                validation_result = self.frontmatter_validator.validate_and_correct(data)
+                                if validation_result.corrections:
+                                    logger.info(f"Applied corrections to {file_path.name}:")
+                                    for correction in validation_result.corrections:
+                                        logger.info(f"  - {correction}")
+                                    
+                                    # Use corrected frontmatter if available
+                                    if validation_result.corrected_frontmatter:
+                                        data = validation_result.corrected_frontmatter
+                                
+                                if validation_result.errors:
+                                    logger.warning(f"Validation errors in {file_path.name}:")
+                                    for error in validation_result.errors:
+                                        logger.warning(f"  - {error}")
+                                
                                 description = data.get('description', '')
                                 version = data.get('version', '0.0.0')
                                 capabilities = data.get('tools', [])  # Tools in .md format
-                                metadata = data.get('metadata', {})
+                                metadata = data
                             else:
                                 # No frontmatter, use defaults
                                 description = f"{file_path.stem} agent"

claude_mpm/validation/agent_validator.py

@@ -53,6 +53,23 @@ class AgentValidator:
     - Privilege escalation (via tool combinations)
     """
     
+    # Model name mappings for normalization to tier names
+    MODEL_MAPPINGS = {
+        # Sonnet variations
+        "claude-3-5-sonnet-20241022": "sonnet",
+        "claude-3-5-sonnet-20240620": "sonnet",
+        "claude-sonnet-4-20250514": "sonnet",
+        "claude-4-sonnet-20250514": "sonnet",
+        "claude-3-sonnet-20240229": "sonnet",
+        # Opus variations
+        "claude-3-opus-20240229": "opus",
+        "claude-opus-4-20250514": "opus",
+        "claude-4-opus-20250514": "opus",
+        # Haiku variations
+        "claude-3-haiku-20240307": "haiku",
+        "claude-3-5-haiku-20241022": "haiku",
+    }
+    
     def __init__(self, schema_path: Optional[Path] = None):
         """Initialize the validator with the agent schema."""
         if schema_path is None:
@@ -83,6 +100,33 @@ class AgentValidator:
             logger.error(f"Failed to load schema from {self.schema_path}: {e}")
             raise
     
+    def _normalize_model(self, model: str) -> str:
+        """Normalize model name to standard tier (opus, sonnet, haiku).
+        
+        Args:
+            model: Original model name
+            
+        Returns:
+            Normalized model tier name
+        """
+        # Direct mapping check
+        if model in self.MODEL_MAPPINGS:
+            return self.MODEL_MAPPINGS[model]
+        
+        # Already normalized
+        if model in {"opus", "sonnet", "haiku"}:
+            return model
+        
+        # Check if model contains tier name
+        model_lower = model.lower()
+        for tier in {"opus", "sonnet", "haiku"}:
+            if tier in model_lower:
+                return tier
+        
+        # Default to sonnet if unrecognized
+        logger.warning(f"Unrecognized model '{model}', defaulting to 'sonnet'")
+        return "sonnet"
+    
     def validate_agent(self, agent_data: Dict[str, Any]) -> ValidationResult:
         """
         Validate a single agent configuration against the schema.
@@ -101,6 +145,14 @@ class AgentValidator:
         """
         result = ValidationResult(is_valid=True)
         
+        # Normalize model name before validation
+        if "capabilities" in agent_data and "model" in agent_data["capabilities"]:
+            original_model = agent_data["capabilities"]["model"]
+            normalized_model = self._normalize_model(original_model)
+            if original_model != normalized_model:
+                agent_data["capabilities"]["model"] = normalized_model
+                result.warnings.append(f"Normalized model from '{original_model}' to '{normalized_model}'")
+        
         # Perform JSON schema validation
         try:
             validate(instance=agent_data, schema=self.schema)
@@ -242,8 +294,11 @@ class AgentValidator:
         model = agent_data.get("capabilities", {}).get("model", "")
         tools = agent_data.get("capabilities", {}).get("tools", [])
         
+        # Normalize model name for comparison
+        normalized_model = self._normalize_model(model)
+        
         # Haiku models shouldn't use resource-intensive tools
-        if "haiku" in model.lower():
+        if normalized_model == "haiku":
             intensive_tools = {"docker", "kubectl", "terraform", "aws", "gcloud", "azure"}
             used_intensive = set(tools) & intensive_tools
             if used_intensive:

{claude_mpm-3.5.1.dist-info → claude_mpm-3.5.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 3.5.1
+Version: 3.5.4
 Summary: Claude Multi-agent Project Manager - Clean orchestration with ticket management
 Home-page: https://github.com/bobmatnyc/claude-mpm
 Author: Claude MPM Team
@@ -92,6 +92,19 @@ claude-mpm run --monitor
 claude-mpm run --resume
 ```
 
+### Agent Management
+
+```bash
+# View agent hierarchy and precedence
+claude-mpm agents list --by-tier
+
+# Inspect specific agent configuration
+claude-mpm agents view engineer
+
+# Fix agent configuration issues
+claude-mpm agents fix --all --dry-run
+```
+
 For detailed usage, see [QUICKSTART.md](QUICKSTART.md)
 
 ## Key Capabilities
@@ -108,6 +121,8 @@ The PM agent automatically delegates work to specialized agents:
 - **Test Integration**: E2E testing and cross-system validation
 - **Version Control**: Git workflows and release management
 
+**Three-Tier Agent System**: PROJECT > USER > SYSTEM precedence allows project-specific agent customization while maintaining fallbacks. Use `claude-mpm agents list --by-tier` to see the active agent hierarchy.
+
 ### Session Management
 - All work is tracked in persistent sessions
 - Resume any session with `--resume`
@@ -144,14 +159,14 @@ The `--monitor` flag opens a web dashboard showing:
 - Tool usage and results
 - Session management UI
 
-See [docs/developer/monitoring.md](docs/developer/monitoring.md) for full monitoring guide.
+See [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.md) for full monitoring guide.
 
 
 ## Documentation
 
 - **[Quick Start Guide](QUICKSTART.md)** - Get running in 5 minutes
 - **[Agent Memory System](docs/MEMORY.md)** - Comprehensive memory documentation
-- **[Monitoring Dashboard](docs/developer/monitoring.md)** - Real-time monitoring features
+- **[Monitoring Dashboard](docs/developer/11-dashboard/README.md)** - Real-time monitoring features
 - **[Project Structure](docs/STRUCTURE.md)** - Codebase organization
 - **[Deployment Guide](docs/DEPLOY.md)** - Publishing and versioning
 - **[User Guide](docs/user/)** - Detailed usage documentation