claude-mpm 1.1.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

claude_mpm/agents/templates/research.json

@@ -0,0 +1,75 @@
+{
+  "schema_version": "1.0.0",
+  "agent_id": "research_agent",
+  "agent_version": "2.1.0",
+  "agent_type": "research",
+  "metadata": {
+    "name": "Research Agent",
+    "description": "Prescriptive codebase analysis with confidence validation and PM escalation for reliable implementation guidance",
+    "created_at": "2025-07-27T03:45:51.485006Z",
+    "updated_at": "2025-07-27T10:30:00.000000Z",
+    "tags": [
+      "research",
+      "tree-sitter",
+      "codebase-analysis",
+      "confidence-validation",
+      "pm-escalation"
+    ],
+    "specializations": [
+      "tree-sitter-analysis",
+      "confidence-assessment",
+      "requirement-validation",
+      "pm-escalation"
+    ]
+  },
+  "capabilities": {
+    "when_to_use": [
+      "Pre-implementation codebase analysis with confidence validation",
+      "Technical requirement clarification and validation", 
+      "Implementation guidance preparation for specialized agents",
+      "Risk assessment and constraint identification",
+      "PM escalation when information gaps prevent reliable guidance"
+    ],
+    "specialized_knowledge": [
+      "Tree-sitter AST analysis and code structure extraction",
+      "Confidence assessment frameworks and escalation protocols",
+      "Security pattern recognition and vulnerability assessment",
+      "Performance pattern identification and optimization opportunities",
+      "PM communication and requirement clarification techniques"
+    ],
+    "unique_capabilities": [
+      "Validate confidence levels before agent delegation",
+      "Generate specific questions for PM when information gaps exist",
+      "Assess implementation readiness with quantifiable confidence metrics",
+      "Create risk-aware analysis with mitigation strategies",
+      "Escalate to PM with actionable clarification requests"
+    ]
+  },
+  "configuration": {
+    "model": "claude-4-sonnet-20250514",
+    "tools": [
+      "Read",
+      "Grep", 
+      "Glob",
+      "LS",
+      "WebSearch",
+      "WebFetch",
+      "Bash"
+    ],
+    "parameters": {
+      "temperature": 0.20,
+      "max_tokens": 12288
+    },
+    "limits": {
+      "timeout": 900,
+      "memory_limit": 3072,
+      "cpu_limit": 60
+    },
+    "permissions": {
+      "file_access": "project_only",
+      "network_access": true,
+      "dangerous_tools": false
+    }
+  },
+  "instructions": "# Research Agent - PRESCRIPTIVE ANALYSIS WITH CONFIDENCE VALIDATION\n\nConduct comprehensive codebase analysis with mandatory confidence validation. If confidence <80%, escalate to PM with specific questions needed to reach analysis threshold.\n\n## MANDATORY CONFIDENCE PROTOCOL\n\n### Confidence Assessment Framework\nAfter each analysis phase, evaluate confidence using this rubric:\n\n**80-100% Confidence (PROCEED)**: \n- All technical requirements clearly understood\n- Implementation patterns and constraints identified\n- Security and performance considerations documented\n- Clear path forward for target agent\n\n**60-79% Confidence (CONDITIONAL)**: \n- Core understanding present but gaps exist\n- Some implementation details unclear\n- Minor ambiguities in requirements\n- **ACTION**: Document gaps and proceed with caveats\n\n**<60% Confidence (ESCALATE)**: \n- Significant knowledge gaps preventing effective analysis\n- Unclear requirements or conflicting information\n- Unable to provide actionable guidance to target agent\n- **ACTION**: MANDATORY escalation to PM with specific questions\n\n### Escalation Protocol\nWhen confidence <80%, use TodoWrite to escalate:\n\n```\n[Research] CONFIDENCE THRESHOLD NOT MET - PM CLARIFICATION REQUIRED\n\nCurrent Confidence: [X]%\nTarget Agent: [Engineer/QA/Security/etc.]\n\nCRITICAL GAPS IDENTIFIED:\n1. [Specific gap 1] - Need: [Specific information needed]\n2. [Specific gap 2] - Need: [Specific information needed]\n3. [Specific gap 3] - Need: [Specific information needed]\n\nQUESTIONS FOR PM TO ASK USER:\n1. [Specific question about requirement/constraint]\n2. [Specific question about technical approach]\n3. [Specific question about integration/dependencies]\n\nIMPACT: Cannot provide reliable guidance to [Target Agent] without this information.\nRISK: Implementation may fail or require significant rework.\n```\n\n## Enhanced Analysis Protocol\n\n### Phase 1: Repository Structure Analysis (5 min)\n```bash\n# Get overall structure and file inventory\nfind . -name \"*.ts\" -o -name \"*.js\" -o -name \"*.py\" -o -name \"*.java\" -o -name \"*.rb\" -o -name \"*.php\" -o -name \"*.go\" | head -20\ntree -I 'node_modules|.git|dist|build|vendor|gems' -L 3\n\n# CONFIDENCE CHECK 1: Can I understand the project structure?\n# Required: Framework identification, file organization, entry points\n```\n\n### Phase 2: Tree-sitter Structural Extraction (10-15 min)\n```bash\n# Parse key files for structural data\ntree-sitter parse [file] --quiet | grep -E \"(function_declaration|class_declaration|interface_declaration|import_statement)\"\n\n# CONFIDENCE CHECK 2: Do I understand the code patterns and architecture?\n# Required: Component relationships, data flow, integration points\n```\n\n### Phase 3: Requirement Validation (5-10 min)\n```bash\n# Security patterns\ngrep -r \"password\\|token\\|auth\\|crypto\\|encrypt\" --include=\"*.ts\" --include=\"*.js\" --include=\"*.py\" --include=\"*.rb\" --include=\"*.php\" --include=\"*.go\" .\n# Performance patterns\ngrep -r \"async\\|await\\|Promise\\|goroutine\\|channel\" --include=\"*.ts\" --include=\"*.js\" --include=\"*.go\" .\n# Error handling\ngrep -r \"try.*catch\\|throw\\|Error\\|rescue\\|panic\\|recover\" --include=\"*.ts\" --include=\"*.js\" --include=\"*.py\" --include=\"*.rb\" --include=\"*.php\" --include=\"*.go\" .\n\n# CONFIDENCE CHECK 3: Do I understand the specific task requirements?\n# Required: Clear understanding of what needs to be implemented/fixed/analyzed\n```\n\n### Phase 4: Target Agent Preparation Assessment\n```bash\n# Assess readiness for specific agent delegation\n# For Engineer Agent: Implementation patterns, constraints, dependencies\n# For QA Agent: Testing infrastructure, validation requirements\n# For Security Agent: Attack surfaces, authentication flows, data handling\n\n# CONFIDENCE CHECK 4: Can I provide actionable guidance to the target agent?\n# Required: Specific recommendations, clear constraints, risk identification\n```\n\n### Phase 5: Final Confidence Evaluation\n**MANDATORY**: Before generating final report, assess overall confidence:\n\n1. **Technical Understanding**: Do I understand the codebase structure and patterns? [1-10]\n2. **Requirement Clarity**: Are the task requirements clear and unambiguous? [1-10]\n3. **Implementation Path**: Can I provide clear guidance for the target agent? [1-10]\n4. **Risk Assessment**: Have I identified the key risks and constraints? [1-10]\n5. **Context Completeness**: Do I have all necessary context for success? [1-10]\n\n**Overall Confidence**: (Sum / 5) * 10 = [X]%\n\n**Decision Matrix**:\n- 80-100%: Generate report and delegate\n- 60-79%: Generate report with clear caveats\n- <60%: ESCALATE to PM immediately\n\n## Enhanced Output Format\n\n```markdown\n# Tree-sitter Code Analysis Report\n\n## CONFIDENCE ASSESSMENT\n- **Overall Confidence**: [X]% \n- **Technical Understanding**: [X]/10\n- **Requirement Clarity**: [X]/10  \n- **Implementation Path**: [X]/10\n- **Risk Assessment**: [X]/10\n- **Context Completeness**: [X]/10\n- **Status**: [PROCEED/CONDITIONAL/ESCALATED]\n\n## Executive Summary\n- **Codebase**: [Project name]\n- **Primary Language**: [TypeScript/Python/Ruby/PHP/Go/JavaScript/Java]\n- **Architecture**: [MVC/Component-based/Microservices]\n- **Complexity Level**: [Low/Medium/High]\n- **Ready for [Agent Type] Work**: [✓/⚠️/❌]\n- **Confidence Level**: [High/Medium/Low]\n\n## Key Components Analysis\n### [Critical File 1]\n- **Type**: [Component/Service/Utility]\n- **Size**: [X lines, Y functions, Z classes]\n- **Key Functions**: `funcName()` - [purpose] (lines X-Y)\n- **Patterns**: [Error handling: ✓/⚠️/❌, Async: ✓/⚠️/❌]\n- **Confidence**: [High/Medium/Low] - [Rationale]\n\n## Agent-Specific Guidance\n### For [Target Agent]:\n**Confidence Level**: [X]%\n\n**Clear Requirements**:\n1. [Specific requirement 1] - [Confidence: High/Medium/Low]\n2. [Specific requirement 2] - [Confidence: High/Medium/Low]\n\n**Implementation Constraints**:\n1. [Technical constraint 1] - [Impact level]\n2. [Business constraint 2] - [Impact level]\n\n**Risk Areas**:\n1. [Risk 1] - [Likelihood/Impact] - [Mitigation strategy]\n2. [Risk 2] - [Likelihood/Impact] - [Mitigation strategy]\n\n**Success Criteria**:\n1. [Measurable outcome 1]\n2. [Measurable outcome 2]\n\n## KNOWLEDGE GAPS (if confidence <80%)\n### Unresolved Questions:\n1. [Question about requirement/constraint]\n2. [Question about technical approach]\n3. [Question about integration/dependencies]\n\n### Information Needed:\n1. [Specific information needed for confident analysis]\n2. [Additional context required]\n\n### Escalation Required:\n[YES/NO] - If YES, see TodoWrite escalation above\n\n## Recommendations\n1. **Immediate**: [Most urgent actions with confidence level]\n2. **Implementation**: [Specific guidance for target agent with confidence level]\n3. **Quality**: [Testing and validation needs with confidence level]\n4. **Risk Mitigation**: [Address identified uncertainties]\n```\n\n## Quality Standards\n- ✓ Confidence assessment completed for each phase\n- ✓ Overall confidence ≥80% OR escalation to PM\n- ✓ Agent-specific actionable insights with confidence levels\n- ✓ File paths and line numbers for reference\n- ✓ Security and performance concerns highlighted\n- ✓ Clear implementation recommendations with risk assessment\n- ✓ Knowledge gaps explicitly documented\n- ✓ Success criteria defined for target agent\n\n## Escalation Triggers\n- Confidence <80% on any critical aspect\n- Ambiguous or conflicting requirements\n- Missing technical context needed for implementation\n- Unclear success criteria or acceptance criteria\n- Unknown integration constraints or dependencies\n- Security implications not fully understood\n- Performance requirements unclear or unmeasurable"
+}

claude_mpm/agents/templates/security.json

@@ -0,0 +1,105 @@
+{
+  "id": "security",
+  "version": "1.0.0",
+  "metadata": {
+    "name": "Security Agent",
+    "description": "Security analysis and vulnerability assessment",
+    "category": "quality",
+    "tags": [
+      "security",
+      "vulnerability",
+      "compliance",
+      "protection"
+    ],
+    "author": "Claude MPM Team",
+    "created_at": "2025-07-27T03:45:51.489358Z",
+    "updated_at": "2025-07-27T03:45:51.489363Z"
+  },
+  "capabilities": {
+    "model": "claude-sonnet-4-20250514",
+    "tools": [
+      "Read",
+      "Grep",
+      "Glob",
+      "LS",
+      "Bash",
+      "WebSearch"
+    ],
+    "resource_tier": "standard",
+    "max_tokens": 8192,
+    "temperature": 0.05,
+    "timeout": 600,
+    "memory_limit": 3072,
+    "cpu_limit": 50,
+    "network_access": true,
+    "file_access": {
+      "read_paths": [
+        "./"
+      ],
+      "write_paths": [
+        "./"
+      ]
+    }
+  },
+  "instructions": "# Security Agent - AUTO-ROUTED\n\nAutomatically handle all security-sensitive operations. Focus on vulnerability assessment and secure implementation patterns.\n\n## Security Protocol\n1. **Threat Assessment**: Identify potential security risks and vulnerabilities\n2. **Secure Design**: Recommend secure implementation patterns\n3. **Compliance Check**: Validate against OWASP and security standards\n4. **Risk Mitigation**: Provide specific security improvements\n\n## Security Focus\n- OWASP compliance and best practices\n- Authentication/authorization security\n- Data protection and encryption standards",
+  "knowledge": {
+    "domain_expertise": [
+      "OWASP security guidelines",
+      "Authentication/authorization patterns",
+      "Data protection and encryption",
+      "Vulnerability assessment techniques",
+      "Security compliance frameworks"
+    ],
+    "best_practices": [
+      "Identify security vulnerabilities and risks",
+      "Design secure authentication flows",
+      "Assess data protection measures",
+      "Perform security-focused code review",
+      "Ensure compliance with security standards"
+    ],
+    "constraints": [],
+    "examples": []
+  },
+  "interactions": {
+    "input_format": {
+      "required_fields": [
+        "task"
+      ],
+      "optional_fields": [
+        "context",
+        "constraints"
+      ]
+    },
+    "output_format": {
+      "structure": "markdown",
+      "includes": [
+        "analysis",
+        "recommendations",
+        "code"
+      ]
+    },
+    "handoff_agents": [
+      "engineer",
+      "ops"
+    ],
+    "triggers": []
+  },
+  "testing": {
+    "test_cases": [
+      {
+        "name": "Basic security task",
+        "input": "Perform a basic security analysis",
+        "expected_behavior": "Agent performs security tasks correctly",
+        "validation_criteria": [
+          "completes_task",
+          "follows_format"
+        ]
+      }
+    ],
+    "performance_benchmarks": {
+      "response_time": 300,
+      "token_usage": 8192,
+      "success_rate": 0.95
+    }
+  }
+}

claude_mpm/agents/templates/version_control.json

@@ -0,0 +1,103 @@
+{
+  "id": "version_control",
+  "version": "1.0.0",
+  "metadata": {
+    "name": "Version Control Agent",
+    "description": "Git operations and version management",
+    "category": "specialized",
+    "tags": [
+      "git",
+      "versioning",
+      "releases",
+      "branches"
+    ],
+    "author": "Claude MPM Team",
+    "created_at": "2025-07-27T03:45:51.494064Z",
+    "updated_at": "2025-07-27T03:45:51.494067Z"
+  },
+  "capabilities": {
+    "model": "claude-sonnet-4-20250514",
+    "tools": [
+      "Read",
+      "Bash",
+      "Grep",
+      "Glob",
+      "LS"
+    ],
+    "resource_tier": "lightweight",
+    "max_tokens": 8192,
+    "temperature": 0.05,
+    "timeout": 600,
+    "memory_limit": 1024,
+    "cpu_limit": 20,
+    "network_access": false,
+    "file_access": {
+      "read_paths": [
+        "./"
+      ],
+      "write_paths": [
+        "./"
+      ]
+    }
+  },
+  "instructions": "# Version Control Agent\n\nManage all git operations, versioning, and release coordination. Maintain clean history and consistent versioning.\n\n## Version Control Protocol\n1. **Git Operations**: Execute precise git commands with proper commit messages\n2. **Version Management**: Apply semantic versioning consistently\n3. **Release Coordination**: Manage release processes with proper tagging\n4. **Conflict Resolution**: Resolve merge conflicts safely\n\n## Versioning Focus\n- Semantic versioning (MAJOR.MINOR.PATCH) enforcement\n- Clean git history with meaningful commits\n- Coordinated release management",
+  "knowledge": {
+    "domain_expertise": [
+      "Git workflows and best practices",
+      "Semantic versioning standards",
+      "Branch management strategies",
+      "Release coordination processes",
+      "Repository maintenance techniques"
+    ],
+    "best_practices": [
+      "Execute precise git operations",
+      "Manage semantic versioning consistently",
+      "Coordinate releases across components",
+      "Resolve complex merge conflicts",
+      "Maintain clean repository history"
+    ],
+    "constraints": [],
+    "examples": []
+  },
+  "interactions": {
+    "input_format": {
+      "required_fields": [
+        "task"
+      ],
+      "optional_fields": [
+        "context",
+        "constraints"
+      ]
+    },
+    "output_format": {
+      "structure": "markdown",
+      "includes": [
+        "analysis",
+        "recommendations",
+        "code"
+      ]
+    },
+    "handoff_agents": [
+      "documentation"
+    ],
+    "triggers": []
+  },
+  "testing": {
+    "test_cases": [
+      {
+        "name": "Basic version_control task",
+        "input": "Perform a basic version_control analysis",
+        "expected_behavior": "Agent performs version_control tasks correctly",
+        "validation_criteria": [
+          "completes_task",
+          "follows_format"
+        ]
+      }
+    ],
+    "performance_benchmarks": {
+      "response_time": 300,
+      "token_usage": 8192,
+      "success_rate": 0.95
+    }
+  }
+}

claude_mpm/cli.py

@@ -323,6 +323,74 @@ def _get_user_input(args, logger):
         return sys.stdin.read()
 
 
+def _get_agent_versions_display():
+    """Get formatted agent versions display as a string.
+    
+    WHY: This function was created to provide a single source of truth for agent version
+    information that can be displayed both at startup and on-demand via the /mpm agents command.
+    This ensures consistency in how agent versions are presented to users.
+    
+    Returns:
+        str: Formatted string containing agent version information, or None if failed
+    """
+    try:
+        from .services.agent_deployment import AgentDeploymentService
+        deployment_service = AgentDeploymentService()
+        
+        # Get deployed agents
+        verification = deployment_service.verify_deployment()
+        if not verification.get("agents_found"):
+            return None
+            
+        output_lines = []
+        output_lines.append("\nDeployed Agent Versions:")
+        output_lines.append("-" * 40)
+        
+        # Sort agents by name for consistent display
+        agents = sorted(verification["agents_found"], key=lambda x: x.get('name', x.get('file', '')))
+        
+        for agent in agents:
+            name = agent.get('name', 'unknown')
+            version = agent.get('version', 'unknown')
+            # Format: name (version)
+            output_lines.append(f"  {name:<20} {version}")
+        
+        # Add base agent version info
+        try:
+            import json
+            base_agent_path = deployment_service.base_agent_path
+            if base_agent_path.exists():
+                base_data = json.loads(base_agent_path.read_text())
+                # Parse version the same way as AgentDeploymentService
+                raw_version = base_data.get('base_version') or base_data.get('version', 0)
+                base_version_tuple = deployment_service._parse_version(raw_version)
+                base_version_str = deployment_service._format_version_display(base_version_tuple)
+                output_lines.append(f"\n  Base Agent Version:  {base_version_str}")
+        except:
+            pass
+        
+        # Check for agents needing migration
+        if verification.get("agents_needing_migration"):
+            output_lines.append(f"\n  ⚠️  {len(verification['agents_needing_migration'])} agent(s) need migration to semantic versioning")
+            output_lines.append(f"     Run 'claude-mpm agents deploy' to update")
+            
+        output_lines.append("-" * 40)
+        return "\n".join(output_lines)
+    except Exception as e:
+        # Log error but don't fail
+        logger = get_logger("cli")
+        logger.debug(f"Failed to get agent versions: {e}")
+        return None
+
+
+def _list_agent_versions_at_startup():
+    """List deployed agent versions at startup."""
+    agent_versions = _get_agent_versions_display()
+    if agent_versions:
+        print(agent_versions)
+        print()  # Extra newline after the display
+
+
 
 
 def run_session(args):
@@ -339,6 +407,9 @@ def run_session(args):
     # Skip native agents if disabled
     if getattr(args, 'no_native_agents', False):
         print("Native agents disabled")
+    else:
+        # List deployed agent versions at startup
+        _list_agent_versions_at_startup()
     
     # Create simple runner
     enable_tickets = not args.no_tickets
@@ -420,17 +491,15 @@ def manage_agents(args):
         deployment_service = AgentDeploymentService()
         
         if not args.agents_command:
-            print("Error: No agent command specified")
-            print("\nUsage: claude-mpm --mpm:agents <command> [options]")
-            print("\nAvailable commands:")
-            print("  list          - List available agents")
-            print("  deploy        - Deploy system agents")
-            print("  force-deploy  - Force deploy all system agents")
-            print("  clean         - Remove deployed system agents")
-            print("\nExamples:")
-            print("  claude-mpm --mpm:agents list --system")
-            print("  claude-mpm --mpm:agents deploy")
-            print("  claude-mpm --mpm:agents force-deploy")
+            # When no subcommand is provided, display agent versions
+            # WHY: This provides a quick way for users to check deployed agent versions
+            # without needing to specify additional subcommands, matching the startup display
+            agent_versions = _get_agent_versions_display()
+            if agent_versions:
+                print(agent_versions)
+            else:
+                print("No deployed agents found")
+                print("\nTo deploy agents, run: claude-mpm --mpm:agents deploy")
             return
         
         if args.agents_command == AgentCommands.LIST.value:

claude_mpm/core/simple_runner.py

@@ -417,7 +417,11 @@ class SimpleClaudeRunner:
             self.logger.debug(f"Ticket extraction failed: {e}")
 
     def _load_system_instructions(self) -> Optional[str]:
-        """Load system instructions from agents/INSTRUCTIONS.md."""
+        """Load and process system instructions from agents/INSTRUCTIONS.md.
+        
+        WHY: Process template variables like {{capabilities-list}} to include
+        dynamic agent capabilities in the PM's system instructions.
+        """
         try:
             # Find the INSTRUCTIONS.md file
             module_path = Path(__file__).parent.parent
@@ -427,9 +431,22 @@ class SimpleClaudeRunner:
                 self.logger.warning(f"System instructions not found: {instructions_path}")
                 return None
             
-            instructions = instructions_path.read_text()
-            self.logger.info("Loaded PM framework system instructions")
-            return instructions
+            # Read raw instructions
+            raw_instructions = instructions_path.read_text()
+            
+            # Process template variables if ContentAssembler is available
+            try:
+                from claude_mpm.services.framework_claude_md_generator.content_assembler import ContentAssembler
+                assembler = ContentAssembler()
+                processed_instructions = assembler.apply_template_variables(raw_instructions)
+                self.logger.info("Loaded and processed PM framework system instructions with dynamic capabilities")
+                return processed_instructions
+            except ImportError:
+                self.logger.warning("ContentAssembler not available, using raw instructions")
+                return raw_instructions
+            except Exception as e:
+                self.logger.warning(f"Failed to process template variables: {e}, using raw instructions")
+                return raw_instructions
             
         except Exception as e:
             self.logger.error(f"Failed to load system instructions: {e}")
@@ -488,9 +505,32 @@ class SimpleClaudeRunner:
                         component="command"
                     )
                 return True
+            elif command == "agents":
+                # Handle agents command - display deployed agent versions
+                # WHY: This provides users with a quick way to check deployed agent versions
+                # directly from within Claude Code, maintaining consistency with CLI behavior
+                try:
+                    from claude_mpm.cli import _get_agent_versions_display
+                    agent_versions = _get_agent_versions_display()
+                    if agent_versions:
+                        print(agent_versions)
+                    else:
+                        print("No deployed agents found")
+                        print("\nTo deploy agents, run: claude-mpm --mpm:agents deploy")
+                    
+                    if self.project_logger:
+                        self.project_logger.log_system(
+                            "Executed /mpm:agents command",
+                            level="INFO",
+                            component="command"
+                        )
+                    return True
+                except Exception as e:
+                    print(f"Error getting agent versions: {e}")
+                    return False
             else:
                 print(f"Unknown command: {command}")
-                print("Available commands: test")
+                print("Available commands: test, agents")
                 return True
                 
         except Exception as e:

claude_mpm/hooks/claude_hooks/hook_handler.py

@@ -34,6 +34,7 @@ class ClaudeHookHandler:
         # Available MPM arguments
         self.mpm_args = {
             'status': 'Show claude-mpm system status',
+            'agents': 'Show deployed agent versions',
             # Add more arguments here as they're implemented
             # 'config': 'Configure claude-mpm settings',
             # 'debug': 'Toggle debug mode',
@@ -200,6 +201,9 @@ class ClaudeHookHandler:
                     # Extract status args if any
                     status_args = arg[6:].strip() if arg.startswith('status ') else ''
                     return self._handle_mpm_status(status_args)
+                elif arg == 'agents' or arg.startswith('agents '):
+                    # Handle agents command
+                    return self._handle_mpm_agents()
                 else:
                     # Show help for empty or unknown argument
                     return self._handle_mpm_help(arg)
@@ -215,7 +219,80 @@ class ClaudeHookHandler:
     
     def _handle_pre_tool_use(self):
         """Handle PreToolUse events."""
-        # For now, just log and continue
+        tool_name = self.event.get('tool_name', '')
+        tool_input = self.event.get('tool_input', {})
+        
+        # List of tools that perform write operations
+        write_tools = ['Write', 'Edit', 'MultiEdit', 'NotebookEdit']
+        
+        # Check if this is a write operation
+        if tool_name in write_tools:
+            # Get the working directory from the event
+            working_dir = Path(self.event.get('cwd', os.getcwd())).resolve()
+            
+            # Extract file path based on tool type
+            file_path = None
+            if tool_name in ['Write', 'Edit', 'NotebookEdit']:
+                file_path = tool_input.get('file_path')
+                if tool_name == 'NotebookEdit':
+                    file_path = tool_input.get('notebook_path')
+            elif tool_name == 'MultiEdit':
+                file_path = tool_input.get('file_path')
+            
+            if file_path:
+                # First check for path traversal attempts before resolving
+                if '..' in str(file_path):
+                    if logger:
+                        logger.warning(f"Security: Potential path traversal attempt in {tool_name}: {file_path}")
+                    response = {
+                        "action": "block",
+                        "error": f"Security Policy: Path traversal attempts are not allowed.\n\n"
+                               f"The path '{file_path}' contains '..' which could be used to escape the working directory.\n"
+                               f"Please use absolute paths or paths relative to the working directory without '..'."
+                    }
+                    print(json.dumps(response))
+                    sys.exit(0)
+                    return
+                
+                try:
+                    # Resolve the file path to absolute path
+                    target_path = Path(file_path).resolve()
+                    
+                    # Check if the target path is within the working directory
+                    try:
+                        target_path.relative_to(working_dir)
+                    except ValueError:
+                        # Path is outside working directory
+                        if logger:
+                            logger.warning(f"Security: Blocked {tool_name} operation outside working directory: {file_path}")
+                        
+                        # Return block action with helpful error message
+                        response = {
+                            "action": "block",
+                            "error": f"Security Policy: Cannot write to files outside the working directory.\n\n"
+                                   f"Working directory: {working_dir}\n"
+                                   f"Attempted path: {file_path}\n\n"
+                                   f"Please ensure all file operations are within the project directory."
+                        }
+                        print(json.dumps(response))
+                        sys.exit(0)
+                        return
+                    
+                        
+                except Exception as e:
+                    if logger:
+                        logger.error(f"Error validating path in {tool_name}: {e}")
+                    # In case of error, err on the side of caution and block
+                    response = {
+                        "action": "block",
+                        "error": f"Error validating file path: {str(e)}\n\n"
+                               f"Please ensure the path is valid and accessible."
+                    }
+                    print(json.dumps(response))
+                    sys.exit(0)
+                    return
+        
+        # For read operations and other tools, continue normally
         return self._continue()
     
     def _handle_post_tool_use(self):
@@ -349,6 +426,42 @@ class ClaudeHookHandler:
         
         return output
     
+    def _handle_mpm_agents(self):
+        """Handle the /mpm agents command to display deployed agent versions.
+        
+        WHY: This provides users with a quick way to check deployed agent versions
+        directly from within Claude Code, maintaining consistency with the CLI
+        and startup display functionality.
+        """
+        try:
+            # Import the agent version display function
+            from claude_mpm.cli import _get_agent_versions_display
+            
+            # Get the formatted agent versions
+            agent_versions = _get_agent_versions_display()
+            
+            if agent_versions:
+                # Display the agent versions
+                print(agent_versions, file=sys.stderr)
+            else:
+                # No agents found
+                output = "\nNo deployed agents found\n"
+                output += "\nTo deploy agents, run: claude-mpm --mpm:agents deploy\n"
+                print(output, file=sys.stderr)
+                
+        except Exception as e:
+            # Handle any errors gracefully
+            output = f"\nError getting agent versions: {e}\n"
+            output += "\nPlease check your claude-mpm installation.\n"
+            print(output, file=sys.stderr)
+            
+            # Log the error for debugging
+            if logger:
+                logger.error(f"Error in _handle_mpm_agents: {e}")
+        
+        # Block LLM processing since we've handled the command
+        sys.exit(2)
+    
     def _handle_mpm_help(self, unknown_arg=None):
         """Show help for MPM commands."""
         # ANSI colors
@@ -375,6 +488,7 @@ class ClaudeHookHandler:
         output += f"  /mpm         - Show this help\n"
         output += f"  /mpm status  - Show system status\n"
         output += f"  /mpm status --verbose - Show detailed status\n"
+        output += f"  /mpm agents  - Show deployed agent versions\n"
         
         output += f"\n{DIM}{'─' * 60}{RESET}"