claude-mpm 2.0.0__py3-none-any.whl → 2.1.1__py3-none-any.whl

claude_mpm/_version.py

@@ -1,34 +1,4 @@
-"""Version information for claude-mpm."""
-
-try:
-    # Try to get version from setuptools-scm (when installed as package)
-    from importlib.metadata import version, PackageNotFoundError
-    try:
-        __version__ = version("claude-mpm")
-    except PackageNotFoundError:
-        __version__ = "2.0.0"
-except ImportError:
-    # Fallback for older Python versions
-    __version__ = "2.0.0"
-
-# This file may be overwritten by setuptools-scm during build
-# The try/except ensures we always have a version available
-
-def get_version_tuple():
-    """Get version as a tuple of integers."""
-    parts = __version__.split(".")[:3]  # Take only major.minor.patch
-    try:
-        return tuple(int(p) for p in parts if p.isdigit())
-    except:
-        return (1, 0, 0)
-
-__version_info__ = get_version_tuple()
-
-# Version history
-# 2.0.0 - BREAKING: Complete agent schema standardization, JSON format, resource tiers
-# 1.1.0 - BREAKING: Removed JSON-RPC hooks, enhanced Claude Code hooks with project-specific logging
-# 1.0.0 - BREAKING: Architecture simplification, TodoWrite hooks, enhanced CLI, terminal UI
-# 0.5.0 - Comprehensive deployment support for PyPI, npm, and local installation
-# 0.3.0 - Added hook service architecture for context filtering and ticket automation
-# 0.2.0 - Initial interactive subprocess orchestration with pexpect
-# 0.1.0 - Basic claude-mpm framework with agent orchestration
+# file generated by setuptools_scm
+# don't change, don't track in version control
+__version__ = version = '2.1.0'
+__version_tuple__ = version_tuple = (2, 1, 0)

claude_mpm/agents/INSTRUCTIONS.md

@@ -78,22 +78,7 @@ Context:
   Priority: <Matches dependent implementation priority>
 ```
 
-## Agent Names & Capabilities
-**Core Agents**: research, engineer, qa, documentation, security, ops, version-control, data-engineer
-
-**Agent Name Formats** (both valid):
-- Capitalized: "Research", "Engineer", "QA"  
-- Lowercase-hyphenated: "research", "engineer", "qa"
-
-**Agent Capabilities**:
-- **Research**: Codebase analysis, best practices, technical investigation
-- **Engineer**: Implementation, refactoring, debugging
-- **QA**: Testing, validation, quality assurance with sign-off authority
-- **Documentation**: Technical docs, API documentation, user guides
-- **Security**: Security review, vulnerability assessment, compliance
-- **Ops**: Deployment, CI/CD, infrastructure, monitoring
-- **Version Control**: Git operations, branching, merge conflict resolution
-- **Data Engineer**: Database design, ETL pipelines, data modeling
+{{capabilities-list}}
 
 ## TodoWrite Requirements
 **MANDATORY**: Always prefix tasks with [Agent]:

claude_mpm/agents/templates/research.json

@@ -1,107 +1,75 @@
 {
-  "id": "research",
-  "version": "1.0.0",
+  "schema_version": "1.0.0",
+  "agent_id": "research_agent",
+  "agent_version": "2.1.0",
+  "agent_type": "research",
   "metadata": {
     "name": "Research Agent",
-    "description": "Tree-sitter codebase analysis and hierarchical summary generation",
-    "category": "research",
+    "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",
-      "ast",
-      "patterns"
+      "confidence-validation",
+      "pm-escalation"
     ],
-    "author": "Claude MPM Team",
-    "created_at": "2025-07-27T03:45:51.485006Z",
-    "updated_at": "2025-07-27T03:45:51.485011Z"
+    "specializations": [
+      "tree-sitter-analysis",
+      "confidence-assessment",
+      "requirement-validation",
+      "pm-escalation"
+    ]
   },
   "capabilities": {
-    "model": "claude-sonnet-4-20250514",
+    "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",
+      "Grep", 
       "Glob",
       "LS",
       "WebSearch",
       "WebFetch",
       "Bash"
     ],
-    "resource_tier": "intensive",
-    "max_tokens": 12288,
-    "temperature": 0.2,
-    "timeout": 900,
-    "memory_limit": 6144,
-    "cpu_limit": 80,
-    "network_access": true,
-    "file_access": {
-      "read_paths": [
-        "./"
-      ],
-      "write_paths": [
-        "./"
-      ]
-    }
-  },
-  "instructions": "# Research Agent - CODEBASE ANALYSIS SPECIALIST\n\nConduct comprehensive codebase analysis using tree-sitter to generate hierarchical summaries optimized for LLM consumption and agent delegation.\n\n## Core 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\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\n### Phase 3: Pattern Detection (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 (JS/TS)\ngrep -r \"async\\|await\\|Promise\" --include=\"*.ts\" --include=\"*.js\" .\n# Performance patterns (Go)\ngrep -r \"goroutine\\|channel\\|sync\\.\" --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\n### Phase 4: Generate Hierarchical Summary\nProduce token-efficient analysis following this structure:\n\n```markdown\n# Tree-sitter Code Analysis Report\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**: [\u2713/\u26a0\ufe0f/\u274c]\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: \u2713/\u26a0\ufe0f/\u274c, Async: \u2713/\u26a0\ufe0f/\u274c]\n\n## Agent-Specific Insights\n### For Security Agent:\n- Authentication mechanisms: [OAuth/JWT/Session]\n- Vulnerability surface: [Input validation, auth flows]\n- Risk areas: [Specific concerns with line numbers]\n\n### For Engineer Agent:\n- Code patterns: [Functional/OOP, async patterns]\n- Refactoring opportunities: [DRY violations, complex functions]\n- Implementation constraints: [Framework limitations, dependencies]\n\n### For QA Agent:\n- Testing infrastructure: [Framework, coverage]\n- Quality gates: [Linting, type checking]\n- Risk areas: [Complex functions, error handling gaps]\n\n## Recommendations\n1. **Immediate**: [Most urgent actions]\n2. **Implementation**: [Specific guidance for Engineer Agent]\n3. **Quality**: [Testing and validation needs]\n```\n\n## Analysis Quality Standards\n- \u2713 Token budget <2K for hierarchical summary\n- \u2713 Agent-specific actionable insights\n- \u2713 File paths and line numbers for reference\n- \u2713 Security and performance concerns highlighted\n- \u2713 Clear implementation recommendations\n\n## Tools Integration\n- Use tree-sitter-cli with language-specific parsers\n- Fallback to regex analysis if parsing fails\n- Focus on exported functions and public APIs\n- Provide partial analysis rather than failing completely",
-  "knowledge": {
-    "domain_expertise": [
-      "Tree-sitter AST analysis and code structure extraction",
-      "Dependency graph analysis and circular dependency detection",
-      "Security pattern recognition and vulnerability assessment",
-      "Performance pattern identification and optimization opportunities",
-      "Testing infrastructure analysis and coverage assessment"
-    ],
-    "best_practices": [
-      "Generate hierarchical code summaries optimized for LLM consumption",
-      "Extract semantic patterns from AST structures using tree-sitter",
-      "Identify critical integration points and API surfaces",
-      "Synthesize agent-specific actionable insights from codebase analysis",
-      "Create token-efficient context for specialized agent delegation"
-    ],
-    "constraints": [],
-    "examples": []
-  },
-  "interactions": {
-    "input_format": {
-      "required_fields": [
-        "task"
-      ],
-      "optional_fields": [
-        "context",
-        "constraints"
-      ]
+    "parameters": {
+      "temperature": 0.20,
+      "max_tokens": 12288
     },
-    "output_format": {
-      "structure": "markdown",
-      "includes": [
-        "analysis",
-        "recommendations",
-        "code"
-      ]
+    "limits": {
+      "timeout": 900,
+      "memory_limit": 3072,
+      "cpu_limit": 60
     },
-    "handoff_agents": [
-      "engineer",
-      "qa"
-    ],
-    "triggers": []
-  },
-  "testing": {
-    "test_cases": [
-      {
-        "name": "Basic research task",
-        "input": "Perform a basic research analysis",
-        "expected_behavior": "Agent performs research tasks correctly",
-        "validation_criteria": [
-          "completes_task",
-          "follows_format"
-        ]
-      }
-    ],
-    "performance_benchmarks": {
-      "response_time": 300,
-      "token_usage": 8192,
-      "success_rate": 0.95
+    "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/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}"