claude-mpm 5.6.17__py3-none-any.whl → 5.6.33__py3-none-any.whl

claude_mpm/hooks/claude_hooks/services/protocols.py

@@ -0,0 +1,328 @@
+"""Protocol definitions for hook handler services.
+
+This module defines Protocol classes for all hook handler services,
+enabling type-safe dependency injection and easy testing through
+protocol-based duck typing.
+
+WHY Protocol-based DI:
+- Enables loose coupling between components
+- Allows easy mocking in tests without monkey-patching
+- Provides clear interface contracts
+- Supports static type checking with mypy
+"""
+
+from typing import Any, Callable, Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class IStateManager(Protocol):
+    """Protocol for state management service.
+
+    Manages:
+    - Agent delegation tracking
+    - Git branch caching
+    - Session state management
+    - Cleanup of old entries
+    """
+
+    active_delegations: dict
+    delegation_history: Any  # deque
+    delegation_requests: dict
+    pending_prompts: dict
+    events_processed: int
+
+    def track_delegation(
+        self, session_id: str, agent_type: str, request_data: Optional[dict] = None
+    ) -> None:
+        """Track a new agent delegation with optional request data."""
+        ...
+
+    def get_delegation_agent_type(self, session_id: str) -> str:
+        """Get the agent type for a session's active delegation."""
+        ...
+
+    def cleanup_old_entries(self) -> None:
+        """Clean up old entries to prevent memory growth."""
+        ...
+
+    def get_git_branch(self, working_dir: Optional[str] = None) -> str:
+        """Get git branch for the given directory with caching."""
+        ...
+
+    def find_matching_request(self, session_id: str) -> Optional[dict]:
+        """Find matching request data for a session, with fuzzy matching fallback."""
+        ...
+
+    def remove_request(self, session_id: str) -> None:
+        """Remove request data for a session."""
+        ...
+
+    def increment_events_processed(self) -> bool:
+        """Increment events processed counter and return True if cleanup is needed."""
+        ...
+
+
+@runtime_checkable
+class IConnectionManager(Protocol):
+    """Protocol for connection management service.
+
+    Handles:
+    - HTTP-based event emission to dashboard
+    - Event queuing and batching
+    - Connection state management
+    """
+
+    def emit_event(self, namespace: str, event: str, data: dict) -> None:
+        """Emit an event through HTTP to the dashboard."""
+        ...
+
+    def cleanup(self) -> None:
+        """Clean up any resources."""
+        ...
+
+
+@runtime_checkable
+class IDuplicateDetector(Protocol):
+    """Protocol for duplicate event detection service.
+
+    Detects:
+    - Duplicate events within a time window
+    - Rapid-fire events that should be deduplicated
+    """
+
+    def is_duplicate(self, event: dict) -> bool:
+        """Check if an event is a duplicate of a recent event."""
+        ...
+
+    def generate_event_key(self, event: dict) -> str:
+        """Generate a unique key for an event for deduplication."""
+        ...
+
+
+@runtime_checkable
+class IResponseTrackingManager(Protocol):
+    """Protocol for response tracking management.
+
+    Manages:
+    - Response tracking enablement
+    - Comprehensive response logging
+    - Agent response correlation
+    """
+
+    response_tracking_enabled: bool
+    response_tracker: Optional[Any]
+    track_all_interactions: bool
+    auto_pause_handler: Optional[Any]
+
+    def track_agent_response(
+        self,
+        session_id: str,
+        agent_type: str,
+        event: dict,
+        delegation_requests: dict,
+    ) -> None:
+        """Track an agent response for logging."""
+        ...
+
+    def track_stop_response(
+        self,
+        event: dict,
+        session_id: str,
+        metadata: dict,
+        pending_prompts: dict,
+    ) -> None:
+        """Track a stop event response."""
+        ...
+
+    def track_assistant_response(
+        self,
+        event: dict,
+        pending_prompts: dict,
+    ) -> None:
+        """Track an assistant response."""
+        ...
+
+
+@runtime_checkable
+class IMemoryHookManager(Protocol):
+    """Protocol for memory hook management.
+
+    Manages:
+    - Pre/post delegation memory hooks
+    - Memory field processing
+    """
+
+    def trigger_pre_delegation_hook(
+        self, agent_type: str, tool_input: dict, session_id: str
+    ) -> None:
+        """Trigger memory hooks before delegation."""
+        ...
+
+    def trigger_post_delegation_hook(
+        self, agent_type: str, event: dict, session_id: str
+    ) -> None:
+        """Trigger memory hooks after delegation."""
+        ...
+
+
+@runtime_checkable
+class ISubagentProcessor(Protocol):
+    """Protocol for subagent response processing.
+
+    Handles:
+    - SubagentStop event processing
+    - Structured response extraction
+    - Response tracking and correlation
+    """
+
+    def process_subagent_stop(self, event: dict) -> None:
+        """Handle subagent stop events."""
+        ...
+
+
+@runtime_checkable
+class IAutoPauseHandler(Protocol):
+    """Protocol for auto-pause functionality.
+
+    Manages:
+    - Session pause tracking
+    - Usage threshold monitoring
+    - Session state capture
+    """
+
+    def is_pause_active(self) -> bool:
+        """Check if auto-pause is currently active."""
+        ...
+
+    def on_user_message(self, message: str) -> None:
+        """Record a user message for auto-pause tracking."""
+        ...
+
+    def on_tool_call(self, tool_name: str, tool_input: dict) -> None:
+        """Record a tool call for auto-pause tracking."""
+        ...
+
+    def on_assistant_response(self, response: str) -> None:
+        """Record an assistant response for auto-pause tracking."""
+        ...
+
+    def on_usage_update(self, usage: dict) -> Optional[str]:
+        """Update usage metrics and return threshold crossed if any."""
+        ...
+
+    def emit_threshold_warning(self, threshold: str) -> str:
+        """Emit a warning for a crossed threshold."""
+        ...
+
+    def on_session_end(self) -> Optional[Any]:
+        """Finalize the current auto-pause session."""
+        ...
+
+
+@runtime_checkable
+class IEventHandlers(Protocol):
+    """Protocol for event handler collection.
+
+    Provides handlers for:
+    - UserPromptSubmit
+    - PreToolUse
+    - PostToolUse
+    - Notification
+    - Stop
+    - SubagentStop
+    - SubagentStart
+    - SessionStart
+    - AssistantResponse
+    """
+
+    def handle_user_prompt_fast(self, event: dict) -> None:
+        """Handle user prompt with comprehensive data capture."""
+        ...
+
+    def handle_pre_tool_fast(self, event: dict) -> Optional[dict]:
+        """Handle pre-tool use with comprehensive data capture."""
+        ...
+
+    def handle_post_tool_fast(self, event: dict) -> None:
+        """Handle post-tool use with comprehensive data capture."""
+        ...
+
+    def handle_notification_fast(self, event: dict) -> None:
+        """Handle notification events from Claude."""
+        ...
+
+    def handle_stop_fast(self, event: dict) -> None:
+        """Handle stop events when Claude processing stops."""
+        ...
+
+    def handle_subagent_stop_fast(self, event: dict) -> None:
+        """Handle subagent stop events."""
+        ...
+
+    def handle_subagent_start_fast(self, event: dict) -> None:
+        """Handle SubagentStart events."""
+        ...
+
+    def handle_session_start_fast(self, event: dict) -> None:
+        """Handle session start events."""
+        ...
+
+    def handle_assistant_response(self, event: dict) -> None:
+        """Handle assistant response events."""
+        ...
+
+
+# Type alias for log function
+LogFunction = Callable[[str], None]
+
+
+@runtime_checkable
+class ILogManager(Protocol):
+    """Protocol for log manager service (optional dependency).
+
+    Used for logging agent prompts and responses.
+    """
+
+    async def log_prompt(
+        self, source: str, content: str, metadata: dict
+    ) -> Optional[Any]:
+        """Log a prompt to the log manager."""
+        ...
+
+
+@runtime_checkable
+class IDelegationDetector(Protocol):
+    """Protocol for delegation pattern detector (optional dependency).
+
+    Used for detecting delegation anti-patterns in responses.
+    """
+
+    def detect_user_delegation(self, text: str) -> list[dict]:
+        """Detect delegation patterns in text."""
+        ...
+
+
+@runtime_checkable
+class IEventLog(Protocol):
+    """Protocol for event log service (optional dependency).
+
+    Used for logging PM violations and other events.
+    """
+
+    def append_event(
+        self,
+        event_type: str,
+        payload: dict,
+        status: str = "pending",
+    ) -> None:
+        """Append an event to the log."""
+        ...
+
+
+@runtime_checkable
+class IConfig(Protocol):
+    """Protocol for configuration service (optional dependency)."""
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a configuration value."""
+        ...

claude_mpm/hooks/claude_hooks/services/state_manager.py

@@ -33,8 +33,8 @@ except ImportError:
         QUICK_TIMEOUT = 2.0
 
 
-# Debug mode is enabled by default for better visibility into hook processing
-DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+# Debug mode - disabled by default to prevent logging overhead in production
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "false").lower() == "true"
 
 
 class StateManagerService:

claude_mpm/hooks/claude_hooks/services/subagent_processor.py

@@ -22,8 +22,8 @@ except ImportError:
         pass  # Silent fallback
 
 
-# Debug mode is enabled by default for better visibility into hook processing
-DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "true").lower() != "false"
+# Debug mode - disabled by default to prevent logging overhead in production
+DEBUG = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "false").lower() == "true"
 
 
 class SubagentResponseProcessor:

claude_mpm/hooks/templates/pre_tool_use_simple.py

@@ -38,7 +38,7 @@ def main():
         # Read event from stdin
         event_data = sys.stdin.read()
         if not event_data.strip():
-            print(json.dumps({"action": "continue"}))
+            print(json.dumps({"continue": True}))
             return
 
         event = json.loads(event_data)
@@ -49,7 +49,7 @@ def main():
         if tool_name == "Grep" and "-n" not in tool_input:
             modified_input = tool_input.copy()
             modified_input["-n"] = True
-            print(json.dumps({"action": "continue", "tool_input": modified_input}))
+            print(json.dumps({"continue": True, "tool_input": modified_input}))
             return
 
         # Example: Block operations on .env files
@@ -59,19 +59,19 @@ def main():
                 print(
                     json.dumps(
                         {
-                            "action": "block",
-                            "message": "Access to .env file blocked for security",
+                            "continue": False,
+                            "stopReason": "Access to .env file blocked for security",
                         }
                     )
                 )
                 return
 
         # Default: continue without modification
-        print(json.dumps({"action": "continue"}))
+        print(json.dumps({"continue": True}))
 
     except Exception:
         # Always continue on error to avoid blocking Claude
-        print(json.dumps({"action": "continue"}))
+        print(json.dumps({"continue": True}))
 
 
 if __name__ == "__main__":

claude_mpm/hooks/templates/pre_tool_use_template.py

@@ -29,7 +29,7 @@ Input Format (stdin):
 
 Output Format (stdout):
 {
-  "action": "continue",
+  "continue": true,
   "tool_input": {
     "file_path": "/path/to/file.py",
     "old_string": "foo",
@@ -39,13 +39,13 @@ Output Format (stdout):
 
 Or to block execution:
 {
-  "action": "block",
-  "message": "Reason for blocking"
+  "continue": false,
+  "stopReason": "Reason for blocking"
 }
 
 Or to continue without modification:
 {
-  "action": "continue"
+  "continue": true
 }
 """
 
@@ -94,14 +94,14 @@ class PreToolUseHook:
         self, modified_input: Optional[Dict[str, Any]] = None
     ) -> None:
         """Continue execution with optional modified input."""
-        response = {"action": "continue"}
+        response = {"continue": True}
         if modified_input is not None:
             response["tool_input"] = modified_input
         print(json.dumps(response))
 
     def block_execution(self, message: str) -> None:
         """Block execution with a message."""
-        response = {"action": "block", "message": message}
+        response = {"continue": False, "stopReason": message}
         print(json.dumps(response))
 
     def modify_input(

claude_mpm/scripts/claude-hook-handler.sh

@@ -222,13 +222,13 @@ log_debug() {
 if [[ "$PYTHON_CMD" == "uv run"* ]]; then
     if ! uv run --directory "$CLAUDE_MPM_ROOT" python -c "import claude_mpm" 2>/dev/null; then
         log_debug "claude_mpm module not available, continuing without hook"
-        echo '{"action": "continue"}'
+        echo '{"continue": true}'
         exit 0
     fi
 else
     if ! $PYTHON_CMD -c "import claude_mpm" 2>/dev/null; then
         log_debug "claude_mpm module not available, continuing without hook"
-        echo '{"action": "continue"}'
+        echo '{"continue": true}'
         exit 0
     fi
 fi
@@ -250,5 +250,5 @@ if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
     echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Error: $(cat /tmp/claude-mpm-hook-error.log 2>/dev/null | head -5)" >> /tmp/claude-mpm-hook.log
 fi
 # Return continue action to prevent blocking Claude Code
-echo '{"action": "continue"}'
+echo '{"continue": true}'
 exit 0

claude_mpm/services/command_deployment_service.py

@@ -1,10 +1,14 @@
-"""Service for deploying MPM slash commands to user's Claude configuration.
+"""Service for managing MPM slash commands in user's Claude configuration.
 
-This service handles:
-1. Copying command markdown files from source to user's ~/.claude/commands directory
-2. Creating the commands directory if it doesn't exist
-3. Overwriting existing commands to ensure they're up-to-date
-4. Parsing and validating YAML frontmatter for namespace metadata (Phase 1 - 1M-400)
+DEPRECATED: User-level commands in ~/.claude/commands/ are deprecated.
+Project-level skills (.claude/skills/) are now the only source for commands.
+
+This service now only handles:
+1. Cleanup of deprecated commands from previous versions
+2. Cleanup of stale commands that no longer exist in source
+3. Parsing and validating YAML frontmatter (for internal use)
+
+New command deployment is intentionally disabled - see deploy_commands_on_startup().
 """
 
 from pathlib import Path
@@ -17,20 +21,34 @@ from claude_mpm.core.logger import get_logger
 
 
 class CommandDeploymentService(BaseService):
-    """Service for deploying MPM slash commands."""
+    """Service for managing MPM slash commands (cleanup only - deployment deprecated)."""
 
-    # Deprecated commands that have been replaced (cleanup on startup)
+    # Deprecated commands that should be removed from ~/.claude/commands/
+    # ALL user-level commands are now deprecated - project-level skills are the only source
     DEPRECATED_COMMANDS = [
+        # Legacy deprecated commands (historical)
         "mpm-agents.md",  # Replaced by mpm-agents-list.md
         "mpm-auto-configure.md",  # Replaced by mpm-agents-auto-configure.md
         "mpm-config-view.md",  # Replaced by mpm-config.md
         "mpm-resume.md",  # Replaced by mpm-session-resume.md
         "mpm-ticket.md",  # Replaced by mpm-ticket-view.md
-        # Removed - consolidated into /mpm-configure
         "mpm-agents-list.md",  # Consolidated into /mpm-configure
         "mpm-agents-detect.md",  # Consolidated into /mpm-configure
         "mpm-agents-auto-configure.md",  # Consolidated into /mpm-configure
         "mpm-agents-recommend.md",  # Consolidated into /mpm-configure
+        # ALL user-level commands are now deprecated (use project-level skills)
+        "mpm.md",
+        "mpm-config.md",
+        "mpm-doctor.md",
+        "mpm-help.md",
+        "mpm-init.md",
+        "mpm-monitor.md",
+        "mpm-organize.md",
+        "mpm-postmortem.md",
+        "mpm-session-resume.md",
+        "mpm-status.md",
+        "mpm-ticket-view.md",
+        "mpm-version.md",
     ]
 
     def __init__(self):
@@ -414,33 +432,33 @@ class CommandDeploymentService(BaseService):
 def deploy_commands_on_startup(force: bool = False) -> None:
     """Convenience function to deploy commands during startup.
 
-    This function:
-    1. Removes deprecated commands that have been replaced
-    2. Removes stale commands that no longer exist in source
-    3. Deploys current command files
+    DEPRECATED: User-level commands in ~/.claude/commands/ are deprecated.
+    Project-level skills should be the only source for commands.
+
+    This function now only cleans up any existing deprecated/stale commands
+    without deploying new ones.
 
     Args:
-        force: Force deployment even if files exist
+        force: Force deployment even if files exist (ignored - deployment disabled)
     """
-    service = CommandDeploymentService()
     logger = get_logger("startup")
+    logger.debug(
+        "User-level command deployment is deprecated - "
+        "project-level skills are the only command source"
+    )
 
-    # Clean up deprecated commands FIRST (known old commands)
+    # Still clean up any lingering deprecated/stale commands from previous versions
+    service = CommandDeploymentService()
+
+    # Clean up deprecated commands
     deprecated_count = service.remove_deprecated_commands()
     if deprecated_count > 0:
         logger.info(f"Cleaned up {deprecated_count} deprecated command(s)")
 
-    # Clean up stale commands SECOND (deployed but not in source anymore)
+    # Clean up stale commands
     stale_count = service.remove_stale_commands()
     if stale_count > 0:
         logger.info(f"Cleaned up {stale_count} stale command(s)")
 
-    # Deploy current commands LAST
-    result = service.deploy_commands(force=force)
-
-    if result["deployed"]:
-        logger.info(f"MPM commands deployed: {', '.join(result['deployed'])}")
-
-    if result["errors"]:
-        for error in result["errors"]:
-            logger.warning(f"Command deployment issue: {error}")
+    # NOTE: Deployment of new commands is intentionally disabled.
+    # Project-level skills (.claude/skills/) are the only source for commands.

claude_mpm/services/hook_installer_service.py

@@ -20,8 +20,13 @@ class HookInstallerService:
     def __init__(self):
         """Initialize the hook installer service."""
         self.logger = get_logger(__name__)
-        self.claude_dir = Path.home() / ".claude"
-        self.settings_file = self.claude_dir / "settings.json"
+        # Use project-level paths, NEVER global ~/.claude/settings.json
+        # This ensures hooks are scoped to the current project only
+        self.project_root = Path.cwd()
+        self.claude_dir = self.project_root / ".claude"
+        # Use settings.local.json for project-level hook settings
+        # Claude Code reads project-level settings from .claude/settings.local.json
+        self.settings_file = self.claude_dir / "settings.local.json"
 
     def is_hooks_configured(self) -> bool:
         """Check if hooks are configured in Claude settings.
@@ -299,16 +304,77 @@ class HookInstallerService:
                 self.logger.debug("Creating new Claude settings")
 
             # Configure hooks
-            hook_config = {
-                "matcher": "*",
-                "hooks": [{"type": "command", "command": hook_script_path}],
-            }
+            new_hook_command = {"type": "command", "command": hook_script_path}
 
             # Update settings
             if "hooks" not in settings:
                 settings["hooks"] = {}
 
-            # Add hooks for all event types
+            def is_our_hook(cmd: Dict[str, Any]) -> bool:
+                """Check if a hook command belongs to claude-mpm."""
+                if cmd.get("type") != "command":
+                    return False
+                command = cmd.get("command", "")
+                return (
+                    "hook_wrapper.sh" in command
+                    or "claude-hook-handler.sh" in command
+                    or "claude-mpm" in command
+                )
+
+            def merge_hooks_for_event(
+                existing_hooks: list, hook_command: Dict[str, Any]
+            ) -> list:
+                """Merge new hook command into existing hooks without duplication.
+
+                Args:
+                    existing_hooks: Current hooks configuration for an event type
+                    hook_command: The claude-mpm hook command to add
+
+                Returns:
+                    Updated hooks list with our hook merged in
+                """
+                # Check if our hook already exists in any existing hook config
+                our_hook_exists = False
+
+                for hook_config in existing_hooks:
+                    if "hooks" in hook_config and isinstance(
+                        hook_config["hooks"], list
+                    ):
+                        for hook in hook_config["hooks"]:
+                            if is_our_hook(hook):
+                                # Update existing hook command path (in case it changed)
+                                hook["command"] = hook_command["command"]
+                                our_hook_exists = True
+                                break
+                    if our_hook_exists:
+                        break
+
+                if our_hook_exists:
+                    # Our hook already exists, just return the updated list
+                    return existing_hooks
+
+                # Our hook doesn't exist - need to add it
+                # Strategy: Add our hook to the first "*" matcher config, or create new
+                added = False
+
+                for hook_config in existing_hooks:
+                    # Check if this config has matcher: "*"
+                    if hook_config.get("matcher") == "*":
+                        # Add our hook to this config's hooks array
+                        if "hooks" not in hook_config:
+                            hook_config["hooks"] = []
+                        hook_config["hooks"].append(hook_command)
+                        added = True
+                        break
+
+                if not added:
+                    # No suitable config found, create a new one
+                    new_config = {"matcher": "*", "hooks": [hook_command]}
+                    existing_hooks.append(new_config)
+
+                return existing_hooks
+
+            # Add hooks for all event types - MERGE instead of overwrite
             for event_type in [
                 "UserPromptSubmit",
                 "PreToolUse",
@@ -316,7 +382,10 @@ class HookInstallerService:
                 "Stop",
                 "SubagentStop",
             ]:
-                settings["hooks"][event_type] = [hook_config]
+                existing = settings["hooks"].get(event_type, [])
+                settings["hooks"][event_type] = merge_hooks_for_event(
+                    existing, new_hook_command
+                )
 
             # Write settings
             with self.settings_file.open("w") as f: