claude-mpm 4.1.1__py3-none-any.whl → 4.1.3__py3-none-any.whl

claude_mpm/hooks/claude_hooks/services/subagent_processor.py

@@ -0,0 +1,374 @@
+"""Subagent response processing service for Claude hook handler.
+
+This service handles:
+- SubagentStop event processing
+- Structured response extraction
+- Response tracking and correlation
+- Memory field processing
+"""
+
+import json
+import os
+import re
+import sys
+from datetime import datetime
+from typing import Optional, Tuple
+
+# Debug mode is enabled by default for better visibility into hook processing
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+
+
+class SubagentResponseProcessor:
+    """Processes subagent responses and extracts structured data."""
+
+    def __init__(self, state_manager, response_tracking_manager, connection_manager):
+        """Initialize the subagent response processor.
+
+        Args:
+            state_manager: StateManagerService instance
+            response_tracking_manager: ResponseTrackingManager instance
+            connection_manager: ConnectionManagerService instance
+        """
+        self.state_manager = state_manager
+        self.response_tracking_manager = response_tracking_manager
+        self.connection_manager = connection_manager
+
+    def process_subagent_stop(self, event: dict):
+        """Handle subagent stop events with improved agent type detection.
+
+        WHY comprehensive subagent stop capture:
+        - Provides visibility into subagent lifecycle and delegation patterns
+        - Captures agent type, ID, reason, and results for analysis
+        - Enables tracking of delegation success/failure patterns
+        - Useful for understanding subagent performance and reliability
+        """
+        # Enhanced debug logging for session correlation
+        session_id = event.get("session_id", "")
+        if DEBUG:
+            print(
+                f"  - session_id: {session_id[:16] if session_id else 'None'}...",
+                file=sys.stderr,
+            )
+            print(f"  - event keys: {list(event.keys())}", file=sys.stderr)
+            print(
+                f"  - delegation_requests size: {len(self.state_manager.delegation_requests)}",
+                file=sys.stderr,
+            )
+            # Show all stored session IDs for comparison
+            all_sessions = list(self.state_manager.delegation_requests.keys())
+            if all_sessions:
+                print("  - Stored sessions (first 16 chars):", file=sys.stderr)
+                for sid in all_sessions[:10]:  # Show up to 10
+                    print(
+                        f"    - {sid[:16]}... (agent: {self.state_manager.delegation_requests[sid].get('agent_type', 'unknown')})",
+                        file=sys.stderr,
+                    )
+            else:
+                print("  - No stored sessions in delegation_requests!", file=sys.stderr)
+
+        # Get agent type and other basic info
+        agent_type, agent_id, reason = self._extract_basic_info(event, session_id)
+
+        # Always log SubagentStop events for debugging
+        if DEBUG or agent_type != "unknown":
+            print(
+                f"Hook handler: Processing SubagentStop - agent: '{agent_type}', session: '{session_id}', reason: '{reason}'",
+                file=sys.stderr,
+            )
+
+        # Get working directory and git branch
+        working_dir = event.get("cwd", "")
+        git_branch = (
+            self.state_manager.get_git_branch(working_dir) if working_dir else "Unknown"
+        )
+
+        # Try to extract structured response from output if available
+        output = event.get("output", "")
+        structured_response = self._extract_structured_response(output, agent_type)
+
+        # Track agent response
+        self._track_response(
+            event,
+            session_id,
+            agent_type,
+            reason,
+            working_dir,
+            git_branch,
+            output,
+            structured_response,
+        )
+
+        # Build subagent stop data for event emission
+        subagent_stop_data = self._build_subagent_stop_data(
+            event,
+            session_id,
+            agent_type,
+            agent_id,
+            reason,
+            working_dir,
+            git_branch,
+            structured_response,
+        )
+
+        # Debug log the processed data
+        if DEBUG:
+            print(
+                f"SubagentStop processed data: agent_type='{agent_type}', session_id='{session_id}'",
+                file=sys.stderr,
+            )
+
+        # Emit to /hook namespace with high priority
+        self.connection_manager.emit_event("/hook", "subagent_stop", subagent_stop_data)
+
+    def _extract_basic_info(self, event: dict, session_id: str) -> Tuple[str, str, str]:
+        """Extract basic info from the event."""
+        # First try to get agent type from our tracking
+        agent_type = (
+            self.state_manager.get_delegation_agent_type(session_id)
+            if session_id
+            else "unknown"
+        )
+
+        # Fall back to event data if tracking didn't have it
+        if agent_type == "unknown":
+            agent_type = event.get("agent_type", event.get("subagent_type", "unknown"))
+
+        agent_id = event.get("agent_id", event.get("subagent_id", ""))
+        reason = event.get("reason", event.get("stop_reason", "unknown"))
+
+        # Try to infer agent type from other fields if still unknown
+        if agent_type == "unknown" and "task" in event:
+            task_desc = str(event.get("task", "")).lower()
+            if "research" in task_desc:
+                agent_type = "research"
+            elif "engineer" in task_desc or "code" in task_desc:
+                agent_type = "engineer"
+            elif "pm" in task_desc or "project" in task_desc:
+                agent_type = "pm"
+
+        return agent_type, agent_id, reason
+
+    def _extract_structured_response(
+        self, output: str, agent_type: str
+    ) -> Optional[dict]:
+        """Extract structured JSON response from output."""
+        if not output:
+            return None
+
+        try:
+            json_match = re.search(r"```json\s*(\{.*?\})\s*```", str(output), re.DOTALL)
+            if json_match:
+                structured_response = json.loads(json_match.group(1))
+                if DEBUG:
+                    print(
+                        f"Extracted structured response from {agent_type} agent in SubagentStop",
+                        file=sys.stderr,
+                    )
+
+                # Log if MEMORIES field is present
+                if structured_response.get("MEMORIES") and DEBUG:
+                    memories_count = len(structured_response["MEMORIES"])
+                    print(
+                        f"Agent {agent_type} returned MEMORIES field with {memories_count} items",
+                        file=sys.stderr,
+                    )
+
+                return structured_response
+        except (json.JSONDecodeError, AttributeError):
+            pass  # No structured response, that's okay
+
+        return None
+
+    def _track_response(
+        self,
+        event: dict,
+        session_id: str,
+        agent_type: str,
+        reason: str,
+        working_dir: str,
+        git_branch: str,
+        output: str,
+        structured_response: Optional[dict],
+    ):
+        """Track the agent response if response tracking is enabled."""
+        if DEBUG:
+            print(
+                f"  - response_tracking_enabled: {self.response_tracking_manager.response_tracking_enabled}",
+                file=sys.stderr,
+            )
+            print(
+                f"  - response_tracker exists: {self.response_tracking_manager.response_tracker is not None}",
+                file=sys.stderr,
+            )
+            print(
+                f"  - session_id: {session_id[:16] if session_id else 'None'}...",
+                file=sys.stderr,
+            )
+            print(f"  - agent_type: {agent_type}", file=sys.stderr)
+            print(f"  - reason: {reason}", file=sys.stderr)
+
+        if (
+            self.response_tracking_manager.response_tracking_enabled
+            and self.response_tracking_manager.response_tracker
+        ):
+            try:
+                # Get the original request data (with fuzzy matching fallback)
+                request_info = self.state_manager.find_matching_request(session_id)
+
+                if DEBUG:
+                    print(
+                        f"  - request_info present: {bool(request_info)}",
+                        file=sys.stderr,
+                    )
+                    if request_info:
+                        print(
+                            "  - ✅ Found request data for response tracking",
+                            file=sys.stderr,
+                        )
+                        print(
+                            f"  - stored agent_type: {request_info.get('agent_type')}",
+                            file=sys.stderr,
+                        )
+                        print(
+                            f"  - request keys: {list(request_info.get('request', {}).keys())}",
+                            file=sys.stderr,
+                        )
+                    else:
+                        print(
+                            f"  - ❌ No request data found for session {session_id[:16]}...",
+                            file=sys.stderr,
+                        )
+
+                if request_info:
+                    # Use the output as the response
+                    response_text = (
+                        str(output)
+                        if output
+                        else f"Agent {agent_type} completed with reason: {reason}"
+                    )
+
+                    # Get the original request
+                    original_request = request_info.get("request", {})
+                    prompt = original_request.get("prompt", "")
+                    description = original_request.get("description", "")
+
+                    # Combine prompt and description
+                    full_request = prompt
+                    if description and description != prompt:
+                        if full_request:
+                            full_request += f"\n\nDescription: {description}"
+                        else:
+                            full_request = description
+
+                    if not full_request:
+                        full_request = f"Task delegation to {agent_type} agent"
+
+                    # Prepare metadata
+                    metadata = {
+                        "exit_code": event.get("exit_code", 0),
+                        "success": reason in ["completed", "finished", "done"],
+                        "has_error": reason
+                        in ["error", "timeout", "failed", "blocked"],
+                        "duration_ms": event.get("duration_ms"),
+                        "working_directory": working_dir,
+                        "git_branch": git_branch,
+                        "timestamp": datetime.now().isoformat(),
+                        "event_type": "subagent_stop",
+                        "reason": reason,
+                        "original_request_timestamp": request_info.get("timestamp"),
+                    }
+
+                    # Add structured response if available
+                    if structured_response:
+                        metadata["structured_response"] = structured_response
+                        metadata["task_completed"] = structured_response.get(
+                            "task_completed", False
+                        )
+
+                        # Check for MEMORIES field and process if present
+                        if structured_response.get("MEMORIES") and DEBUG:
+                            memories = structured_response["MEMORIES"]
+                            print(
+                                f"Found MEMORIES field in {agent_type} response with {len(memories)} items",
+                                file=sys.stderr,
+                            )
+                            # The memory will be processed by extract_and_update_memory
+                            # which is called by the memory hook service
+
+                    # Track the response
+                    file_path = (
+                        self.response_tracking_manager.response_tracker.track_response(
+                            agent_name=agent_type,
+                            request=full_request,
+                            response=response_text,
+                            session_id=session_id,
+                            metadata=metadata,
+                        )
+                    )
+
+                    if file_path and DEBUG:
+                        print(
+                            f"✅ Tracked {agent_type} agent response on SubagentStop: {file_path.name}",
+                            file=sys.stderr,
+                        )
+
+                    # Clean up the request data
+                    self.state_manager.remove_request(session_id)
+
+                elif DEBUG:
+                    print(
+                        f"No request data for SubagentStop session {session_id[:8]}..., agent: {agent_type}",
+                        file=sys.stderr,
+                    )
+
+            except Exception as e:
+                if DEBUG:
+                    print(
+                        f"❌ Failed to track response on SubagentStop: {e}",
+                        file=sys.stderr,
+                    )
+
+    def _build_subagent_stop_data(
+        self,
+        event: dict,
+        session_id: str,
+        agent_type: str,
+        agent_id: str,
+        reason: str,
+        working_dir: str,
+        git_branch: str,
+        structured_response: Optional[dict],
+    ) -> dict:
+        """Build the subagent stop data for event emission."""
+        subagent_stop_data = {
+            "agent_type": agent_type,
+            "agent_id": agent_id,
+            "reason": reason,
+            "session_id": session_id,
+            "working_directory": working_dir,
+            "git_branch": git_branch,
+            "timestamp": datetime.now().isoformat(),
+            "is_successful_completion": reason in ["completed", "finished", "done"],
+            "is_error_termination": reason in ["error", "timeout", "failed", "blocked"],
+            "is_delegation_related": agent_type
+            in ["research", "engineer", "pm", "ops", "qa", "documentation", "security"],
+            "has_results": bool(event.get("results") or event.get("output")),
+            "duration_context": event.get("duration_ms"),
+            "hook_event_name": "SubagentStop",  # Explicitly set for dashboard
+        }
+
+        # Add structured response data if available
+        if structured_response:
+            subagent_stop_data["structured_response"] = {
+                "task_completed": structured_response.get("task_completed", False),
+                "instructions": structured_response.get("instructions", ""),
+                "results": structured_response.get("results", ""),
+                "files_modified": structured_response.get("files_modified", []),
+                "tools_used": structured_response.get("tools_used", []),
+                "remember": structured_response.get("remember"),
+                "MEMORIES": structured_response.get(
+                    "MEMORIES"
+                ),  # Complete memory replacement
+            }
+
+        return subagent_stop_data

claude_mpm/hooks/claude_hooks/tool_analysis.py

@@ -5,8 +5,6 @@ This module provides utilities for analyzing tool usage, extracting parameters,
 and assessing security risks.
 """
 
-from typing import Any, Dict, List
-
 
 def extract_tool_parameters(tool_name: str, tool_input: dict) -> dict:
     """Extract relevant parameters based on tool type.
@@ -99,7 +97,7 @@ def extract_tool_parameters(tool_name: str, tool_input: dict) -> dict:
                 "has_in_progress": any(t.get("status") == "in_progress" for t in todos),
                 "has_pending": any(t.get("status") == "pending" for t in todos),
                 "has_completed": any(t.get("status") == "completed" for t in todos),
-                "priorities": list(set(t.get("priority", "medium") for t in todos)),
+                "priorities": list({t.get("priority", "medium") for t in todos}),
             }
         )
 
@@ -144,18 +142,17 @@ def classify_tool_operation(tool_name: str, tool_input: dict) -> str:
     """Classify the type of operation being performed."""
     if tool_name in ["Read", "LS", "Glob", "Grep", "NotebookRead"]:
         return "read"
-    elif tool_name in ["Write", "Edit", "MultiEdit", "NotebookEdit"]:
+    if tool_name in ["Write", "Edit", "MultiEdit", "NotebookEdit"]:
         return "write"
-    elif tool_name == "Bash":
+    if tool_name == "Bash":
         return "execute"
-    elif tool_name in ["WebFetch", "WebSearch"]:
+    if tool_name in ["WebFetch", "WebSearch"]:
         return "network"
-    elif tool_name == "TodoWrite":
+    if tool_name == "TodoWrite":
         return "task_management"
-    elif tool_name == "Task":
+    if tool_name == "Task":
         return "delegation"
-    else:
-        return "other"
+    return "other"
 
 
 def assess_security_risk(tool_name: str, tool_input: dict) -> str:
@@ -174,21 +171,18 @@ def assess_security_risk(tool_name: str, tool_input: dict) -> str:
         ]
         if any(pattern in command for pattern in dangerous_patterns):
             return "high"
-        elif any(word in command for word in ["install", "delete", "format", "kill"]):
+        if any(word in command for word in ["install", "delete", "format", "kill"]):
             return "medium"
-        else:
-            return "low"
-    elif tool_name in ["Write", "Edit", "MultiEdit"]:
+        return "low"
+    if tool_name in ["Write", "Edit", "MultiEdit"]:
         file_path = tool_input.get("file_path", "")
         # Check for system file modifications
         if any(path in file_path for path in ["/etc/", "/usr/", "/var/", "/sys/"]):
             return "high"
-        elif file_path.startswith("/"):
+        if file_path.startswith("/"):
             return "medium"
-        else:
-            return "low"
-    else:
         return "low"
+    return "low"
 
 
 def extract_tool_results(event: dict) -> dict:

claude_mpm/hooks/memory_integration_hook.py

@@ -13,7 +13,7 @@ agent outputs because:
 """
 
 import re
-from typing import Any, Dict, List
+from typing import Dict, List
 
 from claude_mpm.core.config import Config
 from claude_mpm.core.logger import get_logger
@@ -162,7 +162,7 @@ INSTRUCTIONS: Review your memory above before proceeding. Apply learned patterns
                 success=True,
                 data=context.data,
                 modified=False,
-                error=f"Memory injection failed: {str(e)}",
+                error=f"Memory injection failed: {e!s}",
             )
 
 
@@ -319,7 +319,7 @@ class MemoryPostDelegationHook(PostDelegationHook):
                 success=True,
                 data=context.data,
                 modified=False,
-                error=f"Learning extraction failed: {str(e)}",
+                error=f"Learning extraction failed: {e!s}",
             )
 
     def _extract_learnings(self, text: str) -> Dict[str, List[str]]:
@@ -339,7 +339,7 @@ class MemoryPostDelegationHook(PostDelegationHook):
         Returns:
             Dictionary mapping learning types to lists of extracted learnings
         """
-        learnings = {learning_type: [] for learning_type in self.type_mapping.keys()}
+        learnings = {learning_type: [] for learning_type in self.type_mapping}
         seen_learnings = set()  # Avoid duplicates
 
         # Pattern to find memory blocks with multiple trigger phrases
@@ -394,7 +394,7 @@ class MemoryPostDelegationHook(PostDelegationHook):
                         f"Unsupported learning type: {learning_type}. Supported types: {list(self.type_mapping.keys())}"
                     )
             else:
-                logger.debug(f"Invalid memory block format - missing Type or Content")
+                logger.debug("Invalid memory block format - missing Type or Content")
 
         # Log summary of extracted learnings
         total_learnings = sum(len(items) for items in learnings.values())

claude_mpm/hooks/tool_call_interceptor.py

@@ -6,7 +6,7 @@ from datetime import datetime
 from typing import Any, Dict, List, Optional
 
 from claude_mpm.core.logger import get_logger
-from claude_mpm.hooks.base_hook import BaseHook, HookContext, HookResult, HookType
+from claude_mpm.hooks.base_hook import BaseHook, HookContext, HookType
 
 logger = get_logger(__name__)
 

claude_mpm/hooks/validation_hooks.py

@@ -61,7 +61,7 @@ class ValidationHooks:
                         result.is_valid = False
             except Exception as e:
                 logger.error(f"Pre-load hook failed: {e}")
-                result.warnings.append(f"Pre-load hook failed: {str(e)}")
+                result.warnings.append(f"Pre-load hook failed: {e!s}")
 
         return result
 
@@ -79,7 +79,7 @@ class ValidationHooks:
                     result.warnings.extend(hook_result.warnings)
             except Exception as e:
                 logger.error(f"Post-load hook failed: {e}")
-                result.warnings.append(f"Post-load hook failed: {str(e)}")
+                result.warnings.append(f"Post-load hook failed: {e!s}")
 
         return result
 
@@ -107,7 +107,7 @@ class ValidationHooks:
                     result.is_valid = False
             except Exception as e:
                 logger.error(f"Pre-execute hook failed: {e}")
-                result.warnings.append(f"Pre-execute hook failed: {str(e)}")
+                result.warnings.append(f"Pre-execute hook failed: {e!s}")
 
         return result
 
@@ -118,7 +118,7 @@ async def validate_agent_dependencies(profile_path: Path) -> ValidationResult:
     result = ValidationResult(is_valid=True)
 
     try:
-        with open(profile_path, "r") as f:
+        with open(profile_path) as f:
             profile_data = yaml.safe_load(f)
 
         # Check for circular dependencies

claude_mpm/init.py

@@ -8,7 +8,8 @@ Handles creation of necessary directories and configuration files.
 import json
 import os
 import shutil
-from typing import Any, Dict, Optional
+import sys
+from typing import Dict, Optional
 
 import yaml
 
@@ -142,12 +143,10 @@ class ProjectInitializer:
 
             # Log successful creation with details
             self.logger.info(f"Initialized project directory at {self.project_dir}")
-            self.logger.debug(f"Created directories: agents, config, responses, logs")
+            self.logger.debug("Created directories: agents, config, responses, logs")
 
             # Print appropriate message to console for visibility during startup
             # BUT: Don't print to stdout when running MCP server (interferes with JSON-RPC)
-            import sys
-
             is_mcp_mode = "mcp" in sys.argv and "start" in sys.argv
 
             if not is_mcp_mode:
@@ -216,8 +215,6 @@ class ProjectInitializer:
 
                 if migrated_count > 0:
                     # Don't print to stdout when running MCP server
-                    import sys
-
                     is_mcp_mode = "mcp" in sys.argv and "start" in sys.argv
                     if not is_mcp_mode:
                         print(
@@ -254,7 +251,7 @@ class ProjectInitializer:
         """
         try:
             # Read existing JSON configuration
-            with open(old_file, "r") as f:
+            with open(old_file) as f:
                 config = json.load(f)
 
             # Write as YAML
@@ -327,8 +324,6 @@ class ProjectInitializer:
         dependencies = {}
 
         # Check Python version
-        import sys
-
         dependencies["python"] = sys.version_info >= (3, 8)
 
         # Check Claude CLI

claude_mpm/models/__init__.py

@@ -17,8 +17,8 @@ from .agent_definition import (
 __all__ = [
     "AgentDefinition",
     "AgentMetadata",
-    "AgentType",
+    "AgentPermissions",
     "AgentSection",
+    "AgentType",
     "AgentWorkflow",
-    "AgentPermissions",
 ]

claude_mpm/models/agent_session.py

@@ -12,7 +12,6 @@ chronological order for session replay and analysis.
 """
 
 import json
-import os
 from dataclasses import asdict, dataclass, field
 from datetime import datetime
 from enum import Enum
@@ -241,29 +240,28 @@ class AgentSession:
         # Check event type patterns
         if "prompt" in event_type.lower() or event_type == "user_input":
             return EventCategory.PROMPT
-        elif "delegation" in event_type.lower() or event_type == "Task":
+        if "delegation" in event_type.lower() or event_type == "Task":
             return EventCategory.DELEGATION
-        elif "tool" in event_type.lower() or event_type in [
+        if "tool" in event_type.lower() or event_type in [
             "PreToolUse",
             "PostToolUse",
         ]:
             return EventCategory.TOOL
-        elif (
+        if (
             "file" in event_type.lower()
             or "write" in event_type.lower()
             or "read" in event_type.lower()
         ):
             return EventCategory.FILE
-        elif "todo" in event_type.lower():
+        if "todo" in event_type.lower():
             return EventCategory.TODO
-        elif "response" in event_type.lower() or event_type in ["Stop", "SubagentStop"]:
+        if "response" in event_type.lower() or event_type in ["Stop", "SubagentStop"]:
             return EventCategory.RESPONSE
-        elif "memory" in event_type.lower():
+        if "memory" in event_type.lower():
             return EventCategory.MEMORY
-        elif "status" in event_type.lower() or "session" in event_type.lower():
+        if "status" in event_type.lower() or "session" in event_type.lower():
             return EventCategory.STATUS
-        else:
-            return EventCategory.SYSTEM
+        return EventCategory.SYSTEM
 
     def _process_event(self, event: SessionEvent):
         """Process specific event types to update session state.
@@ -376,9 +374,8 @@ class AgentSession:
                 self.active_delegation.todos_modified.append(data["todos"])
 
         # Track memory updates
-        elif event.category == EventCategory.MEMORY:
-            if self.active_delegation:
-                self.active_delegation.memory_updates.append(data)
+        elif event.category == EventCategory.MEMORY and self.active_delegation:
+            self.active_delegation.memory_updates.append(data)
 
     def finalize(self):
         """Finalize the session by calculating final metrics.
@@ -534,6 +531,6 @@ class AgentSession:
 
         WHY: Enables analysis of historical sessions.
         """
-        with open(filepath, "r", encoding="utf-8") as f:
+        with open(filepath, encoding="utf-8") as f:
             data = json.load(f)
         return cls.from_dict(data)