claude-mpm 4.21.3__py3-none-any.whl → 5.1.9__py3-none-any.whl

claude_mpm/hooks/templates/pre_tool_use_template.py

@@ -0,0 +1,323 @@
+#!/usr/bin/env python3
+"""
+PreToolUse Hook Template for Claude Code v2.0.30+
+
+This template demonstrates how to create PreToolUse hooks that can modify
+tool inputs before execution. Use cases include:
+
+1. Context Injection: Add project context to Read/Edit operations
+2. Security Guards: Validate file paths before operations
+3. Logging: Log tool invocations before execution
+4. Parameter Enhancement: Add default parameters to tool calls
+
+Requirements:
+- Claude Code v2.0.30 or higher
+- Hook must be configured with "modifyInput": true in settings.json
+
+Input Format (stdin):
+{
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Edit",
+  "tool_input": {
+    "file_path": "/path/to/file.py",
+    "old_string": "foo",
+    "new_string": "bar"
+  },
+  "session_id": "abc123...",
+  "cwd": "/working/directory"
+}
+
+Output Format (stdout):
+{
+  "action": "continue",
+  "tool_input": {
+    "file_path": "/path/to/file.py",
+    "old_string": "foo",
+    "new_string": "bar_modified"
+  }
+}
+
+Or to block execution:
+{
+  "action": "block",
+  "message": "Reason for blocking"
+}
+
+Or to continue without modification:
+{
+  "action": "continue"
+}
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+class PreToolUseHook:
+    """Base class for PreToolUse hooks with input modification support."""
+
+    def __init__(self):
+        """Initialize the hook."""
+        self.debug = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "false").lower() == "true"
+
+    def log_debug(self, message: str) -> None:
+        """Log debug message to stderr."""
+        if self.debug:
+            print(f"[PreToolUse Hook] {message}", file=sys.stderr)
+
+    def read_event(self) -> Optional[Dict[str, Any]]:
+        """Read and parse the hook event from stdin."""
+        try:
+            event_data = sys.stdin.read()
+            if not event_data.strip():
+                return None
+            return json.loads(event_data)
+        except json.JSONDecodeError as e:
+            self.log_debug(f"Failed to parse event: {e}")
+            return None
+        except Exception as e:
+            self.log_debug(f"Error reading event: {e}")
+            return None
+
+    def continue_execution(
+        self, modified_input: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Continue execution with optional modified input."""
+        response = {"action": "continue"}
+        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}
+        print(json.dumps(response))
+
+    def modify_input(
+        self, tool_name: str, tool_input: Dict[str, Any], event: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Modify tool input before execution.
+
+        Override this method in subclasses to implement custom logic.
+
+        Args:
+            tool_name: Name of the tool being invoked
+            tool_input: Original tool input parameters
+            event: Full event data including session_id, cwd, etc.
+
+        Returns:
+            Modified tool input dict, or None to continue without modification
+        """
+        # Default: no modification
+        return None
+
+    def should_block(
+        self, tool_name: str, tool_input: Dict[str, Any], event: Dict[str, Any]
+    ) -> tuple[bool, str]:
+        """
+        Check if execution should be blocked.
+
+        Override this method in subclasses to implement validation logic.
+
+        Args:
+            tool_name: Name of the tool being invoked
+            tool_input: Original tool input parameters
+            event: Full event data including session_id, cwd, etc.
+
+        Returns:
+            Tuple of (should_block, reason)
+        """
+        # Default: don't block
+        return False, ""
+
+    def run(self) -> None:
+        """Main entry point for the hook."""
+        try:
+            # Read event from stdin
+            event = self.read_event()
+            if not event:
+                self.continue_execution()
+                return
+
+            tool_name = event.get("tool_name", "")
+            tool_input = event.get("tool_input", {})
+
+            self.log_debug(
+                f"Processing {tool_name} with input: {list(tool_input.keys())}"
+            )
+
+            # Check if execution should be blocked
+            should_block, reason = self.should_block(tool_name, tool_input, event)
+            if should_block:
+                self.log_debug(f"Blocking {tool_name}: {reason}")
+                self.block_execution(reason)
+                return
+
+            # Try to modify input
+            modified_input = self.modify_input(tool_name, tool_input, event)
+            if modified_input is not None:
+                self.log_debug(f"Modified {tool_name} input")
+                self.continue_execution(modified_input)
+            else:
+                self.log_debug(f"No modification for {tool_name}")
+                self.continue_execution()
+
+        except Exception as e:
+            self.log_debug(f"Hook error: {e}")
+            # Always continue on error to avoid blocking Claude
+            self.continue_execution()
+
+
+# ============================================================================
+# Example Implementations
+# ============================================================================
+
+
+class ContextInjectionHook(PreToolUseHook):
+    """
+    Example: Auto-inject project context into Read/Edit tool calls.
+
+    This hook adds project-specific context as comments to file operations.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.project_context = self._load_project_context()
+
+    def _load_project_context(self) -> str:
+        """Load project context from a file or environment."""
+        # Example: Load from .claude-context file
+        context_file = Path.cwd() / ".claude-context"
+        if context_file.exists():
+            return context_file.read_text()
+        return ""
+
+    def modify_input(
+        self, tool_name: str, tool_input: Dict[str, Any], event: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Inject context into Read operations."""
+        if tool_name == "Read" and self.project_context:
+            # Add context as a note (this is conceptual - actual implementation depends on use case)
+            modified = tool_input.copy()
+            # You could add context to a metadata field if the tool supports it
+            modified["_context"] = self.project_context[:200]
+            return modified
+        return None
+
+
+class SecurityGuardHook(PreToolUseHook):
+    """
+    Example: Validate file paths before file operations.
+
+    This hook blocks operations on sensitive files or directories.
+    """
+
+    BLOCKED_PATHS = [
+        ".env",
+        "credentials.json",
+        "secrets/",
+        ".ssh/",
+        "id_rsa",
+    ]
+
+    def should_block(
+        self, tool_name: str, tool_input: Dict[str, Any], event: Dict[str, Any]
+    ) -> tuple[bool, str]:
+        """Block operations on sensitive files."""
+        if tool_name in ["Write", "Edit", "Read"]:
+            file_path = tool_input.get("file_path", "")
+            if any(blocked in file_path for blocked in self.BLOCKED_PATHS):
+                return True, f"Access to sensitive file blocked: {file_path}"
+        return False, ""
+
+
+class LoggingHook(PreToolUseHook):
+    """
+    Example: Log all tool invocations before execution.
+
+    This hook logs tool calls to a file for debugging and audit purposes.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.log_file = Path.home() / ".claude-mpm" / "tool-calls.log"
+        self.log_file.parent.mkdir(exist_ok=True)
+
+    def modify_input(
+        self, tool_name: str, tool_input: Dict[str, Any], event: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Log the tool call."""
+        try:
+            from datetime import datetime, timezone
+
+            log_entry = {
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "tool_name": tool_name,
+                "session_id": event.get("session_id", ""),
+                "cwd": event.get("cwd", ""),
+                "parameters": list(tool_input.keys()),
+            }
+            with self.log_file.open("a") as f:
+                f.write(json.dumps(log_entry) + "\n")
+        except Exception as e:
+            self.log_debug(f"Failed to log tool call: {e}")
+
+        # Don't modify input, just log
+        return None
+
+
+class ParameterEnhancementHook(PreToolUseHook):
+    """
+    Example: Add default parameters to tool calls.
+
+    This hook adds default values to tool parameters if not provided.
+    """
+
+    def modify_input(
+        self, tool_name: str, tool_input: Dict[str, Any], event: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Add default parameters."""
+        modified = tool_input.copy()
+
+        if tool_name == "Bash":
+            # Add default timeout if not specified
+            if "timeout" not in modified:
+                modified["timeout"] = 30000  # 30 seconds
+                return modified
+
+        elif tool_name == "Grep":
+            # Add line numbers by default
+            if "-n" not in modified:
+                modified["-n"] = True
+                return modified
+
+        return None
+
+
+# ============================================================================
+# Main Entry Point
+# ============================================================================
+
+
+def main():
+    """Main entry point - choose which hook implementation to use."""
+    # Select which hook implementation to use
+    # Uncomment the one you want to use:
+
+    # hook = ContextInjectionHook()
+    # hook = SecurityGuardHook()
+    # hook = LoggingHook()
+    # hook = ParameterEnhancementHook()
+
+    # Default: use base hook (no modification)
+    hook = PreToolUseHook()
+
+    hook.run()
+
+
+if __name__ == "__main__":
+    main()

claude_mpm/models/agent_definition.py

@@ -103,6 +103,10 @@ class AgentMetadata:
     author: Optional[str] = None
     tags: List[str] = field(default_factory=list)
     specializations: List[str] = field(default_factory=list)
+    # NEW: Collection metadata for enhanced agent matching
+    collection_id: Optional[str] = None  # Format: owner/repo-name
+    source_path: Optional[str] = None  # Relative path in repository
+    canonical_id: Optional[str] = None  # Format: collection_id:agent_id
 
     def increment_serial_version(self) -> None:
         """Increment the patch version number.
@@ -181,6 +185,9 @@ class AgentDefinition:
                 "author": self.metadata.author,
                 "tags": self.metadata.tags,
                 "specializations": self.metadata.specializations,
+                "collection_id": self.metadata.collection_id,
+                "source_path": self.metadata.source_path,
+                "canonical_id": self.metadata.canonical_id,
             },
             "primary_role": self.primary_role,
             "when_to_use": self.when_to_use,

claude_mpm/models/git_repository.py

@@ -0,0 +1,198 @@
+"""Git repository model for agent sources."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+
+@dataclass
+class GitRepository:
+    """Represents a Git repository configuration for agent sources.
+
+    This model tracks Git repositories that contain agent markdown files.
+    Repositories are cached locally and synced using ETag-based HTTP caching.
+
+    Attributes:
+        url: Full GitHub repository URL (e.g., https://github.com/owner/repo)
+        subdirectory: Optional subdirectory within repository (e.g., "agents/backend")
+        enabled: Whether this repository should be synced
+        priority: Priority for agent resolution (lower = higher precedence)
+        last_synced: Timestamp of last successful sync
+        etag: HTTP ETag from last sync for incremental updates
+    """
+
+    url: str
+    subdirectory: Optional[str] = None
+    enabled: bool = True
+    priority: int = 100
+    last_synced: Optional[datetime] = None
+    etag: Optional[str] = None
+
+    @property
+    def cache_path(self) -> Path:
+        """Return cache directory path for this repository.
+
+        Cache structure: ~/.claude-mpm/cache/remote-agents/{owner}/{repo}/{subdirectory}/
+
+        Returns:
+            Absolute path to cache directory for this repository
+
+        Example:
+            >>> repo = GitRepository(
+            ...     url="https://github.com/bobmatnyc/claude-mpm-agents",
+            ...     subdirectory="agents"
+            ... )
+            >>> repo.cache_path
+            Path('/Users/user/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents/agents')
+        """
+        home = Path.home()
+        base_cache = home / ".claude-mpm" / "cache" / "remote-agents"
+
+        # Extract owner and repo from URL
+        owner, repo = self._parse_github_url(self.url)
+
+        # Build cache path: base/owner/repo/subdirectory
+        cache_path = base_cache / owner / repo
+
+        if self.subdirectory:
+            # Normalize subdirectory path (remove leading/trailing slashes)
+            normalized_subdir = self.subdirectory.strip("/")
+            cache_path = cache_path / normalized_subdir
+
+        return cache_path
+
+    @property
+    def identifier(self) -> str:
+        """Return unique identifier for this repository.
+
+        Format: {owner}/{repo}/{subdirectory} or {owner}/{repo}
+
+        Returns:
+            Unique identifier string
+
+        Example:
+            >>> repo = GitRepository(
+            ...     url="https://github.com/owner/repo",
+            ...     subdirectory="agents"
+            ... )
+            >>> repo.identifier
+            'owner/repo/agents'
+        """
+        owner, repo = self._parse_github_url(self.url)
+        base_id = f"{owner}/{repo}"
+
+        if self.subdirectory:
+            normalized_subdir = self.subdirectory.strip("/")
+            return f"{base_id}/{normalized_subdir}"
+
+        return base_id
+
+    def validate(self) -> list[str]:
+        """Validate repository configuration.
+
+        Returns:
+            List of validation error messages (empty if valid)
+
+        Validation checks:
+            - URL is not empty
+            - URL is valid HTTP/HTTPS format
+            - URL is a GitHub repository URL
+            - Priority is non-negative
+            - Priority is reasonable (<= 1000, warning only)
+            - Subdirectory is relative path (not absolute)
+        """
+        errors = []
+
+        # Validate URL
+        if not self.url or not self.url.strip():
+            errors.append("URL cannot be empty")
+            return errors  # Can't continue validation without URL
+
+        # Check URL format
+        try:
+            parsed = urlparse(self.url)
+
+            # Must be HTTP or HTTPS
+            if parsed.scheme not in ("http", "https"):
+                errors.append(
+                    f"URL must use http:// or https:// protocol, got: {parsed.scheme}"
+                )
+
+            # Must be GitHub (for now)
+            if not parsed.netloc.endswith("github.com"):
+                errors.append(f"URL must be a GitHub repository, got: {parsed.netloc}")
+
+            # Should have owner/repo path structure
+            path_parts = [p for p in parsed.path.strip("/").split("/") if p]
+            if len(path_parts) < 2:
+                errors.append(f"URL must include owner/repo path, got: {parsed.path}")
+
+        except Exception as e:
+            errors.append(f"Invalid URL format: {e}")
+
+        # Validate priority
+        if self.priority < 0:
+            errors.append("Priority must be non-negative (0 or greater)")
+
+        if self.priority > 1000:
+            errors.append(
+                f"Priority {self.priority} is unusually high (recommended: 0-1000). "
+                "Lower priority numbers have higher precedence."
+            )
+
+        # Validate subdirectory
+        if self.subdirectory:
+            # Must be relative path
+            if Path(self.subdirectory).is_absolute():
+                errors.append(
+                    f"Subdirectory must be a relative path, got absolute: {self.subdirectory}"
+                )
+
+            # Should not start with slash
+            if self.subdirectory.startswith("/"):
+                errors.append(
+                    f"Subdirectory should not start with '/', got: {self.subdirectory}"
+                )
+
+        return errors
+
+    def _parse_github_url(self, url: str) -> tuple[str, str]:
+        """Parse GitHub URL to extract owner and repository name.
+
+        Args:
+            url: GitHub repository URL
+
+        Returns:
+            Tuple of (owner, repository_name)
+
+        Example:
+            >>> repo = GitRepository(url="https://github.com/owner/repo")
+            >>> repo._parse_github_url(repo.url)
+            ('owner', 'repo')
+        """
+        # Remove .git suffix if present
+        url = url.rstrip("/")
+        if url.endswith(".git"):
+            url = url[:-4]
+
+        # Parse URL
+        parsed = urlparse(url)
+        path_parts = [p for p in parsed.path.strip("/").split("/") if p]
+
+        if len(path_parts) >= 2:
+            owner = path_parts[0]
+            repo = path_parts[1]
+            return owner, repo
+
+        # Fallback: Use URL as-is if parsing fails
+        # This will be caught by validation
+        return "unknown", "unknown"
+
+    def __repr__(self) -> str:
+        """Return string representation of repository."""
+        return (
+            f"GitRepository(identifier='{self.identifier}', "
+            f"priority={self.priority}, enabled={self.enabled})"
+        )

claude_mpm/scripts/claude-hook-handler.sh

@@ -89,7 +89,7 @@ fi
 # STRATEGY:
 # This function implements a fallback chain to find Python with claude-mpm dependencies:
 # 1. Project-specific virtual environments (venv, .venv)
-# 2. Currently active virtual environment ($VIRTUAL_ENV)  
+# 2. Currently active virtual environment ($VIRTUAL_ENV)
 # 3. System python3 (may lack dependencies)
 # 4. System python (last resort)
 #
@@ -121,7 +121,7 @@ find_python_command() {
             return
         fi
     fi
-    
+
     # 2. Check for project-local virtual environment (common in development)
     if [ -f "$CLAUDE_MPM_ROOT/venv/bin/activate" ]; then
         source "$CLAUDE_MPM_ROOT/venv/bin/activate"
@@ -152,7 +152,7 @@ if [[ "$SCRIPT_DIR" == *"/.local/pipx/venvs/claude-mpm/"* ]]; then
 elif [ -d "$CLAUDE_MPM_ROOT/src" ]; then
     # Development install - add src to PYTHONPATH
     export PYTHONPATH="$CLAUDE_MPM_ROOT/src:$PYTHONPATH"
-    
+
     if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
         echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Development environment detected" >> /tmp/claude-mpm-hook.log
     fi

claude_mpm/scripts/start_activity_logging.py

@@ -51,7 +51,9 @@ if __name__ == "__main__":
 
     # Initialize aggregator
     aggregator = EventAggregator(
-        host="localhost", port=dashboard_port, save_dir=None  # Will use config value
+        host="localhost",
+        port=dashboard_port,
+        save_dir=None,  # Will use config value
     )
 
     # Set up signal handlers

claude_mpm/services/agents/agent_builder.py

@@ -8,12 +8,13 @@ This service provides comprehensive agent lifecycle management including:
 - Integration with deployment services
 """
 
-import json
 import re
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, ClassVar, Dict, List, Optional, Tuple
 
+import yaml
+
 from claude_mpm.core.exceptions import AgentDeploymentError
 from claude_mpm.core.logging_config import get_logger
 
@@ -285,10 +286,15 @@ class AgentBuilderService:
         if not self.templates_dir.exists():
             return templates
 
-        for template_file in self.templates_dir.glob("*.json"):
+        # Agent templates migrated to Markdown with YAML frontmatter (v4.26.0+)
+        for template_file in self.templates_dir.glob("*.md"):
             try:
-                with template_file.open() as f:
-                    config = json.load(f)
+                # Read markdown content and extract YAML frontmatter
+                content = template_file.read_text()
+                config = self._extract_yaml_frontmatter(content)
+                if not config:
+                    self.logger.warning(f"No YAML frontmatter in {template_file.name}")
+                    continue
 
                 # Use filename stem as ID if not specified in config
                 template_id = config.get("id") or template_file.stem
@@ -308,6 +314,30 @@ class AgentBuilderService:
 
         return templates
 
+    def _extract_yaml_frontmatter(self, content: str) -> Optional[Dict[str, Any]]:
+        """
+        Extract and parse YAML frontmatter from markdown content.
+
+        Args:
+            content: File content to parse
+
+        Returns:
+            Parsed YAML frontmatter as dict, or None if not found/invalid
+        """
+        if not content.strip().startswith("---"):
+            return None
+
+        # Split on --- delimiters
+        parts = content.split("---", 2)
+        if len(parts) < 3:
+            return None
+
+        try:
+            return yaml.safe_load(parts[1])
+        except yaml.YAMLError as e:
+            self.logger.warning(f"Failed to parse YAML frontmatter: {e}")
+            return None
+
     def _validate_agent_id(self, agent_id: str) -> None:
         """Validate agent ID format.
 
@@ -371,16 +401,22 @@ class AgentBuilderService:
         if template_id in self._template_cache:
             return self._template_cache[template_id].copy()
 
-        template_file = self.templates_dir / f"{template_id}.json"
+        # Agent templates migrated to Markdown with YAML frontmatter (v4.26.0+)
+        template_file = self.templates_dir / f"{template_id}.md"
 
         if not template_file.exists():
             raise AgentDeploymentError(f"Template '{template_id}' not found")
 
         try:
-            with template_file.open() as f:
-                config = json.load(f)
-                self._template_cache[template_id] = config
-                return config.copy()
+            # Read markdown content and extract YAML frontmatter
+            content = template_file.read_text()
+            config = self._extract_yaml_frontmatter(content)
+            if not config:
+                raise AgentDeploymentError(
+                    f"No YAML frontmatter in template '{template_id}'"
+                )
+            self._template_cache[template_id] = config
+            return config.copy()
         except Exception as e:
             raise AgentDeploymentError(
                 f"Failed to load template '{template_id}': {e}"