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

claude_mpm/agents/templates/research.json

@@ -1,7 +1,7 @@
 {
-  "schema_version": "1.0.0",
+  "schema_version": "1.2.0",
   "agent_id": "research_agent",
-  "agent_version": "2.1.0",
+  "agent_version": "2.2.0",
   "agent_type": "research",
   "metadata": {
     "name": "Research Agent",
@@ -15,61 +15,50 @@
       "confidence-validation",
       "pm-escalation"
     ],
-    "specializations": [
-      "tree-sitter-analysis",
-      "confidence-assessment",
-      "requirement-validation",
-      "pm-escalation"
-    ]
+    "category": "research"
   },
   "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"
+    "model": "claude-sonnet-4-20250514",
+    "tools": [
+      "Read",
+      "Grep", 
+      "Glob",
+      "LS",
+      "WebSearch",
+      "WebFetch",
+      "Bash",
+      "TodoWrite"
     ],
-    "specialized_knowledge": [
+    "resource_tier": "standard",
+    "temperature": 0.20,
+    "max_tokens": 12288,
+    "timeout": 900,
+    "memory_limit": 3072,
+    "cpu_limit": 60,
+    "network_access": true
+  },
+  "knowledge": {
+    "domain_expertise": [
       "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": [
+    "best_practices": [
       "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
-    }
+    "constraints": [
+      "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"
+    ]
   },
   "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

@@ -1,6 +1,8 @@
 {
-  "id": "security",
-  "version": "1.0.0",
+  "schema_version": "1.2.0",
+  "agent_id": "security_agent",
+  "agent_version": "1.1.0",
+  "agent_type": "security",
   "metadata": {
     "name": "Security Agent",
     "description": "Security analysis and vulnerability assessment",
@@ -22,12 +24,12 @@
       "Grep",
       "Glob",
       "LS",
-      "Bash",
-      "WebSearch"
+      "WebSearch",
+      "TodoWrite"
     ],
     "resource_tier": "standard",
     "max_tokens": 8192,
-    "temperature": 0.05,
+    "temperature": 0.0,
     "timeout": 600,
     "memory_limit": 3072,
     "cpu_limit": 50,
@@ -39,7 +41,13 @@
       "write_paths": [
         "./"
       ]
-    }
+    },
+    "disallowed_tools": [
+      "Bash",
+      "Write",
+      "Edit",
+      "MultiEdit"
+    ]
   },
   "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": {

claude_mpm/agents/templates/version_control.json

@@ -1,6 +1,8 @@
 {
-  "id": "version_control",
-  "version": "1.0.0",
+  "schema_version": "1.2.0",
+  "agent_id": "version_control_agent",
+  "agent_version": "1.1.0",
+  "agent_type": "version_control",
   "metadata": {
     "name": "Version Control Agent",
     "description": "Git operations and version management",
@@ -9,7 +11,8 @@
       "git",
       "versioning",
       "releases",
-      "branches"
+      "branches",
+      "todo-write"
     ],
     "author": "Claude MPM Team",
     "created_at": "2025-07-27T03:45:51.494064Z",
@@ -22,11 +25,12 @@
       "Bash",
       "Grep",
       "Glob",
-      "LS"
+      "LS",
+      "TodoWrite"
     ],
     "resource_tier": "lightweight",
     "max_tokens": 8192,
-    "temperature": 0.05,
+    "temperature": 0.0,
     "timeout": 600,
     "memory_limit": 1024,
     "cpu_limit": 20,

claude_mpm/core/base_service.py

@@ -720,7 +720,67 @@ class BaseService(LoggerMixin, ABC):
         return None
 
     async def _collect_custom_metrics(self) -> None:
-        """Collect custom metrics. Override in subclasses."""
+        """Collect custom metrics. Override in subclasses.
+        
+        METRICS COLLECTION PATTERN:
+        This method is called periodically by the metrics task to collect
+        service-specific metrics. Subclasses should override this to:
+        
+        1. COLLECT OPERATIONAL METRICS:
+           - Request rates and latencies
+           - Queue depths and processing times
+           - Error rates by type
+           - Resource utilization
+        
+        2. COLLECT BUSINESS METRICS:
+           - Agent usage patterns
+           - Model selection distribution
+           - Task complexity trends
+           - Cost tracking metrics
+        
+        3. COLLECT PERFORMANCE METRICS:
+           - Cache hit rates
+           - Database query times
+           - API call latencies
+           - Memory usage patterns
+        
+        EXAMPLE IMPLEMENTATION:
+        ```python
+        async def _collect_custom_metrics(self) -> None:
+            # Collect agent-specific metrics
+            if hasattr(self, 'agent_loader'):
+                loader_metrics = self.agent_loader.get_metrics()
+                self.update_metrics(
+                    cache_hit_rate=loader_metrics['cache_hit_rate_percent'],
+                    top_agents=loader_metrics['top_agents_by_usage']
+                )
+            
+            # Collect deployment metrics
+            if hasattr(self, 'deployment_service'):
+                deploy_metrics = self.deployment_service.get_deployment_metrics()
+                self.update_metrics(
+                    deployment_success_rate=deploy_metrics['success_rate_percent'],
+                    avg_deployment_time=deploy_metrics['average_deployment_time_ms']
+                )
+            
+            # Collect resource metrics
+            import psutil
+            process = psutil.Process()
+            self.update_metrics(
+                cpu_percent=process.cpu_percent(),
+                memory_mb=process.memory_info().rss / 1024 / 1024,
+                open_files=len(process.open_files()),
+                thread_count=process.num_threads()
+            )
+        ```
+        
+        BEST PRACTICES:
+        - Keep collection fast (< 100ms)
+        - Handle errors gracefully
+        - Use sampling for expensive operations
+        - Store aggregated data, not raw events
+        - Consider metric cardinality
+        """
         pass
 
     # Utility methods

claude_mpm/hooks/claude_hooks/hook_handler.py

@@ -4,6 +4,31 @@
 This script is called by hook_wrapper.sh, which is the shell script
 that gets installed in ~/.claude/settings.json. The wrapper handles
 environment setup and then executes this Python handler.
+
+## Hook System Architecture:
+
+The claude-mpm hook system follows an event-driven architecture where Claude Code
+emits events that are intercepted by this handler. The system consists of:
+
+1. **Event Source (Claude Code)**: Emits hook events for various actions
+2. **Hook Wrapper (hook_wrapper.sh)**: Shell script that sets up the environment
+3. **Hook Handler (this file)**: Python script that processes events
+4. **Response Actions**: Continue, block, or modify Claude Code behavior
+
+## Design Patterns Used:
+
+1. **Chain of Responsibility**: Each hook type has its own handler method
+2. **Strategy Pattern**: Different handling strategies for different event types
+3. **Template Method**: Base handling logic with hook-specific implementations
+
+## Event Flow:
+
+1. User types in Claude Code -> Claude Code emits event
+2. Event is passed to hook_wrapper.sh via stdin as JSON
+3. Wrapper sets up Python environment and calls this handler
+4. Handler reads event, logs it, and routes to appropriate method
+5. Handler returns action response (continue/block) via stdout
+6. Claude Code acts based on the response
 """
 
 import json
@@ -25,48 +50,93 @@ logger = None
 
 
 class ClaudeHookHandler:
-    """Handler for all Claude Code hook events."""
+    """Handler for all Claude Code hook events.
+    
+    This is the main service class that implements the hook system logic.
+    It acts as a central dispatcher for all hook events from Claude Code.
+    
+    The handler follows these principles:
+    - **Fail-safe**: Always returns a continue action on errors
+    - **Non-blocking**: Quick responses to avoid UI delays
+    - **Project-aware**: Maintains separate logs per project
+    - **Extensible**: Easy to add new commands and event handlers
+    """
     
     def __init__(self):
-        self.event = None
-        self.hook_type = None
+        """Initialize the hook handler.
+        
+        Sets up the handler state and defines available MPM commands.
+        The handler is stateless between invocations - each hook event
+        creates a new instance.
+        """
+        self.event = None  # The current event being processed
+        self.hook_type = None  # Type of hook event (UserPromptSubmit, etc.)
         
-        # Available MPM arguments
+        # Registry of available MPM commands
+        # This acts as a command registry pattern for extensibility
         self.mpm_args = {
             'status': 'Show claude-mpm system status',
             'agents': 'Show deployed agent versions',
-            # Add more arguments here as they're implemented
+            # Future commands can be added here:
             # 'config': 'Configure claude-mpm settings',
             # 'debug': 'Toggle debug mode',
+            # 'logs': 'Show recent hook logs',
+            # 'reload': 'Reload agent configurations',
         }
         
     def handle(self):
-        """Main entry point for hook handling."""
+        """Main entry point for hook handling.
+        
+        This is the core method that:
+        1. Reads the event from stdin (passed by Claude Code)
+        2. Sets up project-specific logging
+        3. Routes the event to the appropriate handler
+        4. Returns the action response
+        
+        The method implements the Template Method pattern where the overall
+        algorithm is defined here, but specific steps are delegated to
+        specialized methods.
+        
+        Error Handling:
+        - All exceptions are caught to ensure fail-safe behavior
+        - Errors result in a 'continue' action to avoid blocking Claude Code
+        - Debug logs are written to /tmp for troubleshooting
+        """
         global logger
         try:
-            # Quick debug log to file
+            # Quick debug log to file for troubleshooting
+            # This is separate from the main logger for bootstrap debugging
             with open('/tmp/claude-mpm-hook.log', 'a') as f:
                 f.write(f"[{datetime.now().isoformat()}] Hook called\n")
             
             # Read event from stdin
+            # Claude Code passes the event as JSON on stdin
+            # Format: {"hook_event_name": "...", "prompt": "...", ...}
             event_data = sys.stdin.read()
             self.event = json.loads(event_data)
             self.hook_type = self.event.get('hook_event_name', 'unknown')
             
             # Get the working directory from the event
+            # This ensures logs are written to the correct project directory
             cwd = self.event.get('cwd', os.getcwd())
             project_dir = Path(cwd)
             
             # Initialize project-specific logging
+            # Each project gets its own log directory to avoid conflicts
+            # Logs are rotated daily by using date in filename
             log_dir = project_dir / '.claude-mpm' / 'logs'
             log_dir.mkdir(parents=True, exist_ok=True)
             
             # Set up logging for this specific project
-            # Use a single log file per day per project
+            # Design decisions:
+            # - One log file per day for easy rotation and cleanup
+            # - Project-specific logger names to avoid cross-contamination
+            # - Environment variable for log level control
             log_level = os.environ.get('CLAUDE_MPM_LOG_LEVEL', 'INFO')
             log_file = log_dir / f"hooks_{datetime.now().strftime('%Y%m%d')}.log"
             
             # Only set up logging if we haven't already for this project
+            # This avoids duplicate handlers when multiple hooks fire quickly
             logger_name = f"claude_mpm_hooks_{project_dir.name}"
             if not logging.getLogger(logger_name).handlers:
                 logger = setup_logging(
@@ -92,7 +162,16 @@ class ClaudeHookHandler:
             # Log the event if DEBUG logging is enabled
             self._log_event()
             
-            # Route to appropriate handler
+            # Route to appropriate handler based on event type
+            # This implements the Chain of Responsibility pattern
+            # Each handler method is responsible for its specific event type
+            #
+            # Available hook types:
+            # - UserPromptSubmit: User submits a prompt (can intercept /mpm commands)
+            # - PreToolUse: Before Claude uses a tool (can block/modify)
+            # - PostToolUse: After tool execution (for logging/monitoring)
+            # - Stop: Session or task ends
+            # - SubagentStop: Subagent completes its task
             if self.hook_type == 'UserPromptSubmit':
                 with open('/tmp/claude-mpm-hook.log', 'a') as f:
                     f.write(f"[{datetime.now().isoformat()}] About to call _handle_user_prompt_submit\n")
@@ -119,7 +198,16 @@ class ClaudeHookHandler:
             return self._continue()
     
     def _log_event(self):
-        """Log the event details if DEBUG logging is enabled."""
+        """Log the event details if DEBUG logging is enabled.
+        
+        This method provides visibility into the hook system's operation.
+        It logs at different levels:
+        - INFO: Basic event occurrence (always logged)
+        - DEBUG: Full event details (only when DEBUG is enabled)
+        
+        The method handles different event types specially to avoid
+        logging sensitive information or overly verbose data.
+        """
         global logger
         if not logger:
             return
@@ -179,7 +267,23 @@ class ClaudeHookHandler:
             logger.info(f"SubagentStop: agent_type={agent_type}, agent_id={agent_id}, reason={reason} at {timestamp}")
     
     def _handle_user_prompt_submit(self):
-        """Handle UserPromptSubmit events."""
+        """Handle UserPromptSubmit events.
+        
+        This is the most important handler as it intercepts user prompts
+        before they reach the LLM. It can:
+        - Detect and handle /mpm commands
+        - Modify prompts before processing
+        - Block prompts from reaching the LLM
+        
+        Returns:
+            - Calls _continue() to let prompt pass through
+            - Exits with code 2 to block LLM processing (for /mpm commands)
+        
+        Command Processing:
+        The method checks if the prompt starts with '/mpm' and routes
+        to the appropriate command handler. This allows claude-mpm to
+        provide an in-IDE command interface.
+        """
         try:
             prompt = self.event.get('prompt', '').strip()
             
@@ -218,11 +322,29 @@ class ClaudeHookHandler:
         return self._continue()
     
     def _handle_pre_tool_use(self):
-        """Handle PreToolUse events."""
+        """Handle PreToolUse events.
+        
+        This handler is called before Claude executes any tool. It implements
+        security policies by:
+        - Checking for path traversal attempts
+        - Ensuring file operations stay within the working directory
+        - Blocking dangerous operations
+        
+        Security Design:
+        - Fail-secure: Block suspicious operations
+        - Clear error messages to help users understand restrictions
+        - Log security events for auditing
+        
+        Returns:
+            - JSON response with action="continue" to allow the tool
+            - JSON response with action="block" and error message to prevent execution
+        """
         tool_name = self.event.get('tool_name', '')
         tool_input = self.event.get('tool_input', {})
         
         # List of tools that perform write operations
+        # These tools need special security checks to prevent
+        # writing outside the project directory
         write_tools = ['Write', 'Edit', 'MultiEdit', 'NotebookEdit']
         
         # Check if this is a write operation
@@ -296,22 +418,68 @@ class ClaudeHookHandler:
         return self._continue()
     
     def _handle_post_tool_use(self):
-        """Handle PostToolUse events."""
+        """Handle PostToolUse events.
+        
+        Called after a tool has been executed. Currently used for:
+        - Logging tool execution results
+        - Monitoring tool usage patterns
+        - Future: Could modify tool outputs or trigger follow-up actions
+        
+        This handler always continues as it's for observation only.
+        """
         # For now, just log and continue
+        # Future enhancements could include:
+        # - Modifying tool outputs
+        # - Triggering notifications on certain conditions
+        # - Collecting metrics on tool usage
         return self._continue()
     
     def _handle_stop(self):
-        """Handle Stop events."""
+        """Handle Stop events.
+        
+        Called when a Claude Code session or task ends. Useful for:
+        - Cleanup operations
+        - Final logging
+        - Session statistics
+        
+        Currently just logs the event for monitoring purposes.
+        """
         # Log the stop event and continue
+        # Future: Could trigger cleanup or summary generation
         return self._continue()
     
     def _handle_subagent_stop(self):
-        """Handle SubagentStop events."""
+        """Handle SubagentStop events.
+        
+        Called when a subagent completes its task. Provides:
+        - Agent type and ID for tracking
+        - Completion reason
+        - Timing information
+        
+        This is particularly useful for multi-agent workflows to track
+        which agents were involved and how they performed.
+        """
         # Log the subagent stop event and continue
+        # Future: Could aggregate subagent performance metrics
         return self._continue()
     
     def _handle_mpm_status(self, args=None):
-        """Handle the /mpm:status command."""
+        """Handle the /mpm status command.
+        
+        Displays comprehensive status information about the claude-mpm system.
+        This helps users verify their installation and troubleshoot issues.
+        
+        Args:
+            args: Optional arguments like --verbose for detailed output
+        
+        The method collects information about:
+        - Version information
+        - Python environment
+        - Logging configuration
+        - Hook system status
+        
+        Uses ANSI colors for better readability in the terminal.
+        """
         # Parse arguments if provided
         verbose = False
         if args:
@@ -429,9 +597,17 @@ class ClaudeHookHandler:
     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
+        This command 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.
+        
+        Design Philosophy:
+        - Reuse existing CLI functionality for consistency
+        - Display agent versions in the same format as CLI startup
+        - Graceful error handling with helpful messages
+        
+        The method imports and reuses the CLI's agent version display function
+        to ensure consistent formatting across all interfaces.
         """
         try:
             # Import the agent version display function
@@ -463,7 +639,20 @@ class ClaudeHookHandler:
         sys.exit(2)
     
     def _handle_mpm_help(self, unknown_arg=None):
-        """Show help for MPM commands."""
+        """Show help for MPM commands.
+        
+        Displays a formatted help screen with available commands.
+        This serves as the primary documentation for in-IDE commands.
+        
+        Args:
+            unknown_arg: If provided, shows an error for unknown command
+        
+        Design:
+        - Uses ANSI colors that work in Claude Code's output
+        - Lists all registered commands from self.mpm_args
+        - Provides examples for common use cases
+        - Extensible: New commands automatically appear in help
+        """
         # ANSI colors
         CYAN = '\033[96m'
         RED = '\033[91m'
@@ -497,14 +686,29 @@ class ClaudeHookHandler:
         sys.exit(2)
     
     def _continue(self):
-        """Return continue response to let prompt pass through."""
+        """Return continue response to let prompt pass through.
+        
+        This is the default response for most hooks. It tells Claude Code
+        to continue with normal processing.
+        
+        Response Format:
+        - {"action": "continue"}: Process normally
+        - Exit code 0: Success
+        
+        This method ensures consistent response formatting across all handlers.
+        """
         response = {"action": "continue"}
         print(json.dumps(response))
         sys.exit(0)
 
 
 def main():
-    """Main entry point."""
+    """Main entry point.
+    
+    Creates a new handler instance and processes the current event.
+    Each hook invocation is independent - no state is maintained
+    between calls. This ensures reliability and prevents memory leaks.
+    """
     handler = ClaudeHookHandler()
     handler.handle()