claude-mpm 5.6.3__py3-none-any.whl → 5.6.16__py3-none-any.whl

claude_mpm/hooks/claude_hooks/services/state_manager.py

@@ -8,13 +8,22 @@ This service manages:
 """
 
 import os
-import subprocess
+import subprocess  # nosec B404
 import time
 from collections import deque
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
+# Try to import _log from hook_handler, fall back to no-op
+try:
+    from claude_mpm.hooks.claude_hooks.hook_handler import _log
+except ImportError:
+
+    def _log(msg: str) -> None:
+        pass  # Silent fallback
+
+
 # Import constants for configuration
 try:
     from claude_mpm.core.constants import TimeoutConfig
@@ -63,17 +72,11 @@ class StateManagerService:
     ):
         """Track a new agent delegation with optional request data for response correlation."""
         if DEBUG:
-            import sys
-
-            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"  - request_data provided: {bool(request_data)}", file=sys.stderr)
-            print(
-                f"  - delegation_requests size before: {len(self.delegation_requests)}",
-                file=sys.stderr,
+            _log(f"  - session_id: {session_id[:16] if session_id else 'None'}...")
+            _log(f"  - agent_type: {agent_type}")
+            _log(f"  - request_data provided: {bool(request_data)}")
+            _log(
+                f"  - delegation_requests size before: {len(self.delegation_requests)}"
             )
 
         if session_id and agent_type and agent_type != "unknown":
@@ -89,15 +92,9 @@ class StateManagerService:
                     "timestamp": datetime.now(timezone.utc).isoformat(),
                 }
                 if DEBUG:
-                    import sys
-
-                    print(
-                        f"  - ✅ Stored in delegation_requests[{session_id[:16]}...]",
-                        file=sys.stderr,
-                    )
-                    print(
-                        f"  - delegation_requests size after: {len(self.delegation_requests)}",
-                        file=sys.stderr,
+                    _log(f"  - ✅ Stored in delegation_requests[{session_id[:16]}...]")
+                    _log(
+                        f"  - delegation_requests size after: {len(self.delegation_requests)}"
                     )
 
             # Clean up old delegations (older than 5 minutes)
@@ -197,7 +194,7 @@ class StateManagerService:
             os.chdir(working_dir)
 
             # Run git command to get current branch
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B603 B607
                 ["git", "branch", "--show-current"],
                 capture_output=True,
                 text=True,
@@ -233,17 +230,12 @@ class StateManagerService:
     def find_matching_request(self, session_id: str) -> Optional[dict]:
         """Find matching request data for a session, with fuzzy matching fallback."""
         # First try exact match
-        request_info = self.delegation_requests.get(session_id)
+        request_info = self.delegation_requests.get(session_id)  # nosec B113
 
         # If exact match fails, try partial matching
         if not request_info and session_id:
             if DEBUG:
-                import sys
-
-                print(
-                    f"  - Trying fuzzy match for session {session_id[:16]}...",
-                    file=sys.stderr,
-                )
+                _log(f"  - Trying fuzzy match for session {session_id[:16]}...")
             # Try to find a session that matches the first 8-16 characters
             for stored_sid in list(self.delegation_requests.keys()):
                 if (
@@ -256,13 +248,8 @@ class StateManagerService:
                     )
                 ):
                     if DEBUG:
-                        import sys
-
-                        print(
-                            f"  - ✅ Fuzzy match found: {stored_sid[:16]}...",
-                            file=sys.stderr,
-                        )
-                    request_info = self.delegation_requests.get(stored_sid)
+                        _log(f"  - ✅ Fuzzy match found: {stored_sid[:16]}...")
+                    request_info = self.delegation_requests.get(stored_sid)  # nosec B113
                     # Update the key to use the current session_id for consistency
                     if request_info:
                         self.delegation_requests[session_id] = request_info

claude_mpm/hooks/claude_hooks/services/subagent_processor.py

@@ -10,10 +10,18 @@ This service handles:
 import json
 import os
 import re
-import sys
 from datetime import datetime, timezone
 from typing import Optional, Tuple
 
+# Try to import _log from hook_handler, fall back to no-op
+try:
+    from claude_mpm.hooks.claude_hooks.hook_handler import _log
+except ImportError:
+
+    def _log(msg: str) -> None:
+        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"
 
@@ -45,26 +53,21 @@ class SubagentResponseProcessor:
         # 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,
+            _log(f"  - session_id: {session_id[:16] if session_id else 'None'}...")
+            _log(f"  - event keys: {list(event.keys())}")
+            _log(
+                f"  - delegation_requests size: {len(self.state_manager.delegation_requests)}"
             )
             # 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)
+                _log("  - Stored sessions (first 16 chars):")
                 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,
+                    _log(
+                        f"    - {sid[:16]}... (agent: {self.state_manager.delegation_requests[sid].get('agent_type', 'unknown')})"
                     )
             else:
-                print("  - No stored sessions in delegation_requests!", file=sys.stderr)
+                _log("  - No stored sessions in delegation_requests!")
 
         # Get agent type and other basic info
         agent_type, agent_id, reason, agent_type_inferred = self._extract_basic_info(
@@ -73,9 +76,8 @@ class SubagentResponseProcessor:
 
         # 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,
+            _log(
+                f"Hook handler: Processing SubagentStop - agent: '{agent_type}', session: '{session_id}', reason: '{reason}'"
             )
 
         # Get working directory and git branch
@@ -115,9 +117,8 @@ class SubagentResponseProcessor:
 
         # Debug log the processed data
         if DEBUG:
-            print(
-                f"SubagentStop processed data: agent_type='{agent_type}', session_id='{session_id}'",
-                file=sys.stderr,
+            _log(
+                f"SubagentStop processed data: agent_type='{agent_type}', session_id='{session_id}'"
             )
 
         # Emit to default namespace (consistent with subagent_start)
@@ -163,10 +164,7 @@ class SubagentResponseProcessor:
             agent_type = "pm"
             agent_type_inferred = True
             if DEBUG:
-                print(
-                    "  - Inferred agent_type='pm' (no explicit type found)",
-                    file=sys.stderr,
-                )
+                _log("  - Inferred agent_type='pm' (no explicit type found)")
 
         return agent_type, agent_id, reason, agent_type_inferred
 
@@ -182,17 +180,15 @@ class SubagentResponseProcessor:
             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(
+                        f"Extracted structured response from {agent_type} agent in SubagentStop"
                     )
 
                 # 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,
+                    _log(
+                        f"Agent {agent_type} returned MEMORIES field with {memories_count} items"
                     )
 
                 return structured_response
@@ -214,20 +210,15 @@ class SubagentResponseProcessor:
     ):
         """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,
+            _log(
+                f"  - response_tracking_enabled: {self.response_tracking_manager.response_tracking_enabled}"
             )
-            print(
-                f"  - session_id: {session_id[:16] if session_id else 'None'}...",
-                file=sys.stderr,
+            _log(
+                f"  - response_tracker exists: {self.response_tracking_manager.response_tracker is not None}"
             )
-            print(f"  - agent_type: {agent_type}", file=sys.stderr)
-            print(f"  - reason: {reason}", file=sys.stderr)
+            _log(f"  - session_id: {session_id[:16] if session_id else 'None'}...")
+            _log(f"  - agent_type: {agent_type}")
+            _log(f"  - reason: {reason}")
 
         if (
             self.response_tracking_manager.response_tracking_enabled
@@ -238,27 +229,16 @@ class SubagentResponseProcessor:
                 request_info = self.state_manager.find_matching_request(session_id)
 
                 if DEBUG:
-                    print(
-                        f"  - request_info present: {bool(request_info)}",
-                        file=sys.stderr,
-                    )
+                    _log(f"  - request_info present: {bool(request_info)}")
                     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,
+                        _log("  - ✅ Found request data for response tracking")
+                        _log(f"  - stored agent_type: {request_info.get('agent_type')}")
+                        _log(
+                            f"  - request keys: {list(request_info.get('request', {}).keys())}"
                         )
                     else:
-                        print(
-                            f"  - ❌ No request data found for session {session_id[:16]}...",
-                            file=sys.stderr,
+                        _log(
+                            f"  - ❌ No request data found for session {session_id[:16]}..."
                         )
 
                 if request_info:
@@ -310,9 +290,8 @@ class SubagentResponseProcessor:
                         # 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,
+                            _log(
+                                f"Found MEMORIES field in {agent_type} response with {len(memories)} items"
                             )
                             # The memory will be processed by extract_and_update_memory
                             # which is called by the memory hook service
@@ -329,26 +308,21 @@ class SubagentResponseProcessor:
                     )
 
                     if file_path and DEBUG:
-                        print(
-                            f"✅ Tracked {agent_type} agent response on SubagentStop: {file_path.name}",
-                            file=sys.stderr,
+                        _log(
+                            f"✅ Tracked {agent_type} agent response on SubagentStop: {file_path.name}"
                         )
 
                     # 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,
+                    _log(
+                        f"No request data for SubagentStop session {session_id[:8]}..., agent: {agent_type}"
                     )
 
             except Exception as e:
                 if DEBUG:
-                    print(
-                        f"❌ Failed to track response on SubagentStop: {e}",
-                        file=sys.stderr,
-                    )
+                    _log(f"❌ Failed to track response on SubagentStop: {e}")
 
     def _build_subagent_stop_data(
         self,

claude_mpm/hooks/session_resume_hook.py

@@ -12,13 +12,21 @@ DESIGN DECISIONS:
 """
 
 import json
-import sys
 from pathlib import Path
 from typing import Any, Dict, Optional
 
 from claude_mpm.core.logger import get_logger
 from claude_mpm.services.cli.session_resume_helper import SessionResumeHelper
 
+# Try to import _log from hook_handler, fall back to no-op
+try:
+    from claude_mpm.hooks.claude_hooks.hook_handler import _log
+except ImportError:
+
+    def _log(msg: str) -> None:
+        pass  # Silent fallback
+
+
 logger = get_logger(__name__)
 
 
@@ -86,23 +94,19 @@ class SessionResumeStartupHook:
         Args:
             pause_info: Pause session metadata from check_for_active_pause()
         """
-        print("\n" + "=" * 60, file=sys.stderr)
-        print("⚠️  ACTIVE AUTO-PAUSE SESSION DETECTED", file=sys.stderr)
-        print("=" * 60, file=sys.stderr)
-        print(f"Session ID: {pause_info['session_id']}", file=sys.stderr)
-        print(f"Started at: {pause_info['started_at']}", file=sys.stderr)
-        print(
-            f"Context at pause: {pause_info['context_at_start']:.1%}", file=sys.stderr
-        )
-        print(f"Actions recorded: {pause_info['action_count']}", file=sys.stderr)
-        print(
-            "\nThis session was auto-paused due to high context usage.", file=sys.stderr
-        )
-        print("Options:", file=sys.stderr)
-        print("  1. Continue (actions will be appended)", file=sys.stderr)
-        print("  2. Use /mpm-init pause --finalize to create snapshot", file=sys.stderr)
-        print("  3. Use /mpm-init pause --discard to abandon", file=sys.stderr)
-        print("=" * 60 + "\n", file=sys.stderr)
+        _log("=" * 60)
+        _log("⚠️  ACTIVE AUTO-PAUSE SESSION DETECTED")
+        _log("=" * 60)
+        _log(f"Session ID: {pause_info['session_id']}")
+        _log(f"Started at: {pause_info['started_at']}")
+        _log(f"Context at pause: {pause_info['context_at_start']:.1%}")
+        _log(f"Actions recorded: {pause_info['action_count']}")
+        _log("\nThis session was auto-paused due to high context usage.")
+        _log("Options:")
+        _log("  1. Continue (actions will be appended)")
+        _log("  2. Use /mpm-init pause --finalize to create snapshot")
+        _log("  3. Use /mpm-init pause --discard to abandon")
+        _log("=" * 60 + "\n")
 
     def on_pm_startup(self) -> Optional[Dict[str, Any]]:
         """Execute on PM startup to check for paused sessions.

claude_mpm/hooks/templates/pre_tool_use_template.py

@@ -55,6 +55,14 @@ import sys
 from pathlib import Path
 from typing import Any, Dict, Optional
 
+# Try to import _log from hook_handler, fall back to no-op
+try:
+    from claude_mpm.hooks.claude_hooks.hook_handler import _log
+except ImportError:
+
+    def _log(msg: str) -> None:
+        pass  # Silent fallback
+
 
 class PreToolUseHook:
     """Base class for PreToolUse hooks with input modification support."""
@@ -64,9 +72,9 @@ class PreToolUseHook:
         self.debug = os.environ.get("CLAUDE_MPM_HOOK_DEBUG", "false").lower() == "true"
 
     def log_debug(self, message: str) -> None:
-        """Log debug message to stderr."""
+        """Log debug message using _log helper."""
         if self.debug:
-            print(f"[PreToolUse Hook] {message}", file=sys.stderr)
+            _log(f"[PreToolUse Hook] {message}")
 
     def read_event(self) -> Optional[Dict[str, Any]]:
         """Read and parse the hook event from stdin."""

claude_mpm/scripts/claude-hook-handler.sh

@@ -125,7 +125,7 @@ find_python_command() {
     # 1. Check for UV project first (uv.lock or pyproject.toml with uv)
     if [ -f "$CLAUDE_MPM_ROOT/uv.lock" ]; then
         if command -v uv &> /dev/null; then
-            echo "uv run python"
+            echo "uv run --directory \"$CLAUDE_MPM_ROOT\" python"
             return
         fi
     fi
@@ -219,8 +219,8 @@ log_debug() {
 
 # Test Python works and module exists
 # Handle UV's multi-word command specially
-if [[ "$PYTHON_CMD" == "uv run python" ]]; then
-    if ! uv run python -c "import claude_mpm" 2>/dev/null; then
+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"}'
         exit 0
@@ -237,8 +237,8 @@ fi
 # Use exec to replace the shell process with Python
 # Handle UV's multi-word command specially
 # Suppress RuntimeWarning to prevent stderr output (which causes hook errors)
-if [[ "$PYTHON_CMD" == "uv run python" ]]; then
-    exec uv run python -W ignore::RuntimeWarning -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/claude-mpm-hook-error.log
+if [[ "$PYTHON_CMD" == "uv run"* ]]; then
+    exec uv run --directory "$CLAUDE_MPM_ROOT" python -W ignore::RuntimeWarning -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/claude-mpm-hook-error.log
 else
     exec "$PYTHON_CMD" -W ignore::RuntimeWarning -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/claude-mpm-hook-error.log
 fi

claude_mpm/services/agents/agent_selection_service.py

@@ -39,10 +39,10 @@ import logging
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Set, Tuple
 
-from src.claude_mpm.services.agents.single_tier_deployment_service import (
+from claude_mpm.services.agents.single_tier_deployment_service import (
     SingleTierDeploymentService,
 )
-from src.claude_mpm.services.agents.toolchain_detector import ToolchainDetector
+from claude_mpm.services.agents.toolchain_detector import ToolchainDetector
 
 logger = logging.getLogger(__name__)
 

claude_mpm/services/agents/single_tier_deployment_service.py

@@ -30,12 +30,12 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from src.claude_mpm.config.agent_sources import AgentSourceConfiguration
-from src.claude_mpm.models.git_repository import GitRepository
-from src.claude_mpm.services.agents.deployment.remote_agent_discovery_service import (
+from claude_mpm.config.agent_sources import AgentSourceConfiguration
+from claude_mpm.models.git_repository import GitRepository
+from claude_mpm.services.agents.deployment.remote_agent_discovery_service import (
     RemoteAgentDiscoveryService,
 )
-from src.claude_mpm.services.agents.git_source_manager import GitSourceManager
+from claude_mpm.services.agents.git_source_manager import GitSourceManager
 
 logger = logging.getLogger(__name__)
 

claude_mpm/services/skills/git_skill_source_manager.py

@@ -16,6 +16,7 @@ Trade-offs:
 - Flexibility: Easy to extend with skills-specific features
 """
 
+import os
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from datetime import datetime, timezone
 from pathlib import Path
@@ -32,6 +33,46 @@ from claude_mpm.services.skills.skill_discovery_service import SkillDiscoverySer
 logger = get_logger(__name__)
 
 
+def _get_github_token(source: Optional[SkillSource] = None) -> Optional[str]:
+    """Get GitHub token with source-specific override support.
+
+    Priority: source.token > GITHUB_TOKEN > GH_TOKEN
+
+    Args:
+        source: Optional SkillSource to check for per-source token
+
+    Returns:
+        GitHub token if found, None otherwise
+
+    Token Resolution:
+        1. If source has token starting with "$", resolve as env var
+        2. If source has direct token, use it (not recommended for security)
+        3. Fall back to GITHUB_TOKEN env var
+        4. Fall back to GH_TOKEN env var
+        5. Return None if no token found
+
+    Security Note:
+        Token is never logged or printed to avoid exposure.
+        Direct tokens in config are discouraged - use env var refs ($VAR_NAME).
+
+    Example:
+        >>> source = SkillSource(..., token="$PRIVATE_TOKEN")
+        >>> token = _get_github_token(source)  # Resolves $PRIVATE_TOKEN from env
+        >>> token = _get_github_token()  # Falls back to GITHUB_TOKEN
+    """
+    # Priority 1: Per-source token (env var reference or direct)
+    if source and source.token:
+        if source.token.startswith("$"):
+            # Env var reference: $VAR_NAME -> os.environ.get("VAR_NAME")
+            env_var_name = source.token[1:]
+            return os.environ.get(env_var_name)
+        # Direct token (not recommended but supported)
+        return source.token
+
+    # Priority 2-3: Global environment variables
+    return os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+
+
 class GitSkillSourceManager:
     """Manages multiple Git-based skill sources with priority resolution.
 
@@ -217,9 +258,21 @@ class GitSkillSourceManager:
             )
 
             # Discover skills in cache
+            self.logger.debug(f"Scanning cache path for skills: {cache_path}")
             discovery_service = SkillDiscoveryService(cache_path)
             discovered_skills = discovery_service.discover_skills()
 
+            # Log discovery results
+            if len(discovered_skills) == 0:
+                self.logger.info(
+                    f"No SKILL.md files found in {cache_path}. "
+                    "Ensure your skill source has SKILL.md files with valid frontmatter."
+                )
+            else:
+                self.logger.debug(
+                    f"Successfully parsed {len(discovered_skills)} skills from {cache_path}"
+                )
+
             # Build result
             result = {
                 "synced": True,
@@ -469,7 +522,7 @@ class GitSkillSourceManager:
         # Step 1: Discover all files via GitHub Tree API (single request)
         # This discovers the COMPLETE repository structure (272 files for skills)
         all_files = self._discover_repository_files_via_tree_api(
-            owner_repo, source.branch
+            owner_repo, source.branch, source
         )
 
         if not all_files:
@@ -504,7 +557,7 @@ class GitSkillSourceManager:
                 raw_url = f"https://raw.githubusercontent.com/{owner_repo}/{source.branch}/{file_path}"
                 cache_file = cache_path / file_path
                 future = executor.submit(
-                    self._download_file_with_etag, raw_url, cache_file, force
+                    self._download_file_with_etag, raw_url, cache_file, force, source
                 )
                 future_to_file[future] = file_path
 
@@ -533,7 +586,7 @@ class GitSkillSourceManager:
         return files_updated, files_cached
 
     def _discover_repository_files_via_tree_api(
-        self, owner_repo: str, branch: str
+        self, owner_repo: str, branch: str, source: Optional[SkillSource] = None
     ) -> List[str]:
         """Discover all files in repository using GitHub Git Tree API.
 
@@ -596,9 +649,17 @@ class GitSkillSourceManager:
             )
             self.logger.debug(f"Fetching commit SHA from {refs_url}")
 
-            refs_response = requests.get(
-                refs_url, headers={"Accept": "application/vnd.github+json"}, timeout=30
-            )
+            # Build headers with authentication if token available
+            headers = {"Accept": "application/vnd.github+json"}
+            token = _get_github_token(source)
+            if token:
+                headers["Authorization"] = f"token {token}"
+                if source and source.token:
+                    self.logger.debug(f"Using source-specific token for {source.id}")
+                else:
+                    self.logger.debug("Using GitHub token for authentication")
+
+            refs_response = requests.get(refs_url, headers=headers, timeout=30)
 
             # Check for rate limiting
             if refs_response.status_code == 403:
@@ -621,7 +682,7 @@ class GitSkillSourceManager:
             self.logger.debug(f"Fetching recursive tree from {tree_url}")
             tree_response = requests.get(
                 tree_url,
-                headers={"Accept": "application/vnd.github+json"},
+                headers=headers,  # Reuse headers with auth from Step 1
                 params=params,
                 timeout=30,
             )
@@ -652,7 +713,11 @@ class GitSkillSourceManager:
         return all_files
 
     def _download_file_with_etag(
-        self, url: str, local_path: Path, force: bool = False
+        self,
+        url: str,
+        local_path: Path,
+        force: bool = False,
+        source: Optional[SkillSource] = None,
     ) -> bool:
         """Download file from URL with ETag caching (thread-safe).
 
@@ -660,6 +725,7 @@ class GitSkillSourceManager:
             url: Raw GitHub URL
             local_path: Local file path to save to
             force: Force download even if cached
+            source: Optional SkillSource for token resolution
 
         Returns:
             True if file was updated, False if cached
@@ -692,6 +758,11 @@ class GitSkillSourceManager:
         if cached_etag and not force:
             headers["If-None-Match"] = cached_etag
 
+        # Add GitHub authentication if token available
+        token = _get_github_token(source)
+        if token:
+            headers["Authorization"] = f"token {token}"
+
         try:
             response = requests.get(url, headers=headers, timeout=30)