code-puppy-core-plugins 0.0.2__py3-none-any.whl

code_puppy_core_plugins/claude_code_hooks/config.py

@@ -0,0 +1,137 @@
+"""
+Configuration loader for Claude Code hooks.
+
+Loads and merges hooks from multiple locations:
+1. ~/.code_puppy/hooks.json (global level) - always loaded if exists
+2. .claude/settings.json (project-level) - merged with global
+
+Both configurations are loaded and merged so that hooks from both levels
+coexist and execute together.
+"""
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+PROJECT_HOOKS_FILE = ".claude/settings.json"
+GLOBAL_HOOKS_FILE = os.path.expanduser("~/.code_puppy/hooks.json")
+
+
+def _deep_merge_hooks(base: Dict[str, Any], overlay: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Merge hook configurations, combining event types and hook groups.
+
+    When the same event type exists in both base and overlay, their hook groups
+    are concatenated (overlay hooks appear after base hooks).
+
+    Args:
+        base: Base configuration dictionary
+        overlay: Configuration to merge on top
+
+    Returns:
+        Merged configuration with all hooks from both sources
+    """
+    merged = dict(base)
+
+    for event_type, hook_groups in overlay.items():
+        if event_type.startswith("_"):
+            # Skip comment keys
+            merged[event_type] = hook_groups
+            continue
+
+        if event_type not in merged:
+            # New event type, just add it
+            merged[event_type] = hook_groups
+        elif isinstance(merged[event_type], list) and isinstance(hook_groups, list):
+            # Both are lists, concatenate them (overlay hooks come after)
+            merged[event_type] = merged[event_type] + hook_groups
+            logger.debug(
+                f"Merged {len(hook_groups)} hook group(s) for event '{event_type}'"
+            )
+        else:
+            # Type mismatch or unexpected structure, keep base
+            logger.warning(
+                f"Cannot merge event type '{event_type}': type mismatch or unexpected structure"
+            )
+
+    return merged
+
+
+def load_hooks_config() -> Optional[Dict[str, Any]]:
+    """
+    Load and merge hooks configuration from available sources.
+
+    Priority order:
+    1. ~/.code_puppy/hooks.json (global level) - always loaded if exists
+    2. .claude/settings.json (project-level) - merged with global
+
+    Returns:
+        Configuration dictionary or None if no config found
+    """
+    merged_config: Dict[str, Any] = {}
+
+    # Load global hooks first
+    global_config_path = Path(GLOBAL_HOOKS_FILE)
+
+    if global_config_path.exists():
+        try:
+            with open(global_config_path, "r", encoding="utf-8") as f:
+                config = json.load(f)
+            if "hooks" in config and isinstance(config["hooks"], dict):
+                logger.info(
+                    f"Loaded hooks configuration (wrapped format) from {GLOBAL_HOOKS_FILE}"
+                )
+                merged_config = _deep_merge_hooks(merged_config, config["hooks"])
+            elif isinstance(config, dict):
+                logger.info(f"Loaded hooks configuration from {GLOBAL_HOOKS_FILE}")
+                merged_config = _deep_merge_hooks(merged_config, config)
+        except json.JSONDecodeError as e:
+            logger.error(f"Invalid JSON in {GLOBAL_HOOKS_FILE}: {e}")
+        except Exception as e:
+            logger.error(f"Failed to load {GLOBAL_HOOKS_FILE}: {e}", exc_info=True)
+
+    # Load and merge project-level hooks
+    project_config_path = Path(os.getcwd()) / PROJECT_HOOKS_FILE
+
+    if project_config_path.exists():
+        try:
+            with open(project_config_path, "r", encoding="utf-8") as f:
+                config = json.load(f)
+            hooks_config = config.get("hooks")
+            if hooks_config:
+                logger.info(f"Merging hooks configuration from {project_config_path}")
+                merged_config = _deep_merge_hooks(merged_config, hooks_config)
+            else:
+                logger.debug(f"No 'hooks' section found in {project_config_path}")
+        except json.JSONDecodeError as e:
+            logger.error(f"Invalid JSON in {project_config_path}: {e}")
+        except Exception as e:
+            logger.error(f"Failed to load {project_config_path}: {e}", exc_info=True)
+
+    if not merged_config:
+        logger.debug("No hooks configuration found")
+        return None
+
+    event_count = len(
+        [event for event in merged_config.keys() if not event.startswith("_")]
+    )
+    logger.info(f"Hooks configuration ready ({event_count} event type(s))")
+    return merged_config
+
+
+def get_hooks_config_paths() -> list:
+    """
+    Return list of hook configuration paths.
+
+    Returns paths in order of precedence (project-level first, then global).
+    Note: internally, hooks are loaded in reverse order (global first, then project)
+    so that project-level hooks can extend/append to global hooks.
+    """
+    return [
+        str(Path(os.getcwd()) / PROJECT_HOOKS_FILE),
+        GLOBAL_HOOKS_FILE,
+    ]

code_puppy_core_plugins/claude_code_hooks/register_callbacks.py

@@ -0,0 +1,383 @@
+"""
+Register callbacks for Claude Code hooks plugin.
+
+Integrates the hook engine with code_puppy's callback system.
+
+This bridge maps Claude Code hook events to code_puppy lifecycle callbacks:
+
+    Claude Code event   →  code_puppy callback
+    -----------------   →  -------------------
+    PreToolUse          →  pre_tool_call
+    PostToolUse         →  post_tool_call
+    SessionStart        →  startup
+    SessionEnd          →  session_end
+    UserPromptSubmit    →  user_prompt_submit
+    PreCompact          →  pre_compact
+    Notification        →  notification
+    Stop / SubagentStop →  agent_run_end
+
+Hook stdout on exit code 0 is propagated to the agent context for the events
+where Claude Code's spec says it should become "additional context"
+(SessionStart, UserPromptSubmit, PreToolUse). See issue #298.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from code_puppy.callbacks import register_callback
+from code_puppy.hook_engine import EventData, HookEngine
+
+from .config import load_hooks_config
+
+_SUBAGENT_NAMES = frozenset(
+    {
+        "pack_leader",
+        "bloodhound",
+        "code-puppy",
+        "code_puppy",
+        "retriever",
+        "shepherd",
+        "terrier",
+        "watchdog",
+        "subagent",
+        "sub_agent",
+    }
+)
+
+logger = logging.getLogger(__name__)
+
+_hook_engine: Optional[HookEngine] = None
+
+# Deferred-context buffer: SessionStart hook stdout lands in the next user prompt
+# (where the spec says "additional context" goes). One-shot per session.
+_pending_session_context: List[str] = []
+
+
+def _initialize_engine() -> Optional[HookEngine]:
+    config = load_hooks_config()
+
+    if not config:
+        logger.info("No hooks configuration found - Claude Code hooks disabled")
+        return None
+
+    try:
+        engine = HookEngine(config, strict_validation=False)
+        stats = engine.get_stats()
+        logger.info(
+            f"Hook engine ready - Total: {stats['total_hooks']}, "
+            f"Enabled: {stats['enabled_hooks']}"
+        )
+        return engine
+    except Exception as e:
+        logger.error(f"Failed to initialize hook engine: {e}", exc_info=True)
+        return None
+
+
+_hook_engine = _initialize_engine()
+
+
+def _collect_context_stdout(result: Any) -> List[str]:
+    """Pull stdout from non-blocking, exit-0 hook results.
+
+    Per Claude Code spec, only exit code 0 hooks contribute "additional
+    context" — exit 1 blocks and exit 2 routes stderr back as a tool error.
+    """
+    chunks: List[str] = []
+    for r in getattr(result, "results", []) or []:
+        if getattr(r, "blocked", False):
+            continue
+        if getattr(r, "exit_code", 0) != 0:
+            continue
+        stdout = (getattr(r, "stdout", "") or "").strip()
+        if stdout:
+            chunks.append(stdout)
+    return chunks
+
+
+# ---------------------------------------------------------------------------
+# PreToolUse / PostToolUse
+# ---------------------------------------------------------------------------
+
+
+async def on_pre_tool_call_hook(
+    tool_name: str,
+    tool_args: Dict[str, Any],
+    context: Any = None,
+) -> Optional[Dict[str, Any]]:
+    """Pre-tool callback — executes hooks before tool runs. Can block AND
+    inject stdout as additional context for the model."""
+    if not _hook_engine:
+        return None
+
+    event_data = EventData(
+        event_type="PreToolUse",
+        tool_name=tool_name,
+        tool_args=tool_args,
+        context={"context": context} if context else {},
+    )
+
+    try:
+        result = await _hook_engine.process_event("PreToolUse", event_data)
+
+        if result.blocked:
+            logger.debug(
+                f"Tool '{tool_name}' blocked by hook: {result.blocking_reason}"
+            )
+            return {
+                "blocked": True,
+                "reason": result.blocking_reason,
+                "error_message": result.blocking_reason,
+            }
+
+        # Exit code 0 hooks: propagate stdout via ``context_message`` (issue #298) so
+        # the pydantic_patches consumer prepends it to the tool result.
+        stdout_chunks = _collect_context_stdout(result)
+        if stdout_chunks:
+            return {"context_message": "\n\n".join(stdout_chunks)}
+        return None
+    except Exception as e:
+        logger.error(f"Error in pre-tool hook: {e}", exc_info=True)
+        return None
+
+
+async def on_post_tool_call_hook(
+    tool_name: str,
+    tool_args: Dict[str, Any],
+    result: Any,
+    duration_ms: float,
+    context: Any = None,
+) -> None:
+    """Post-tool callback — executes hooks after tool completes."""
+    if not _hook_engine:
+        return
+
+    event_data = EventData(
+        event_type="PostToolUse",
+        tool_name=tool_name,
+        tool_args=tool_args,
+        context={"result": result, "duration_ms": duration_ms, "context": context},
+    )
+
+    try:
+        await _hook_engine.process_event("PostToolUse", event_data)
+    except Exception as e:
+        logger.error(f"Error in post-tool hook: {e}", exc_info=True)
+
+
+register_callback("pre_tool_call", on_pre_tool_call_hook)
+register_callback("post_tool_call", on_post_tool_call_hook)
+
+
+# ---------------------------------------------------------------------------
+# SessionStart  /  SessionEnd
+# ---------------------------------------------------------------------------
+
+
+async def on_startup_hook() -> None:
+    """Startup callback — fires SessionStart hooks when code_puppy boots.
+
+    Captures stdout into ``_pending_session_context`` so the first user prompt
+    can be augmented with the SessionStart "additional context" (project
+    constitutions, etc.). See issue #298.
+    """
+    if not _hook_engine:
+        return
+
+    event_data = EventData(
+        event_type="SessionStart",
+        tool_name="session",
+        tool_args={},
+    )
+
+    try:
+        result = await _hook_engine.process_event("SessionStart", event_data)
+        stdout_chunks = _collect_context_stdout(result)
+        if stdout_chunks:
+            _pending_session_context.extend(stdout_chunks)
+            logger.debug(
+                f"SessionStart captured {len(stdout_chunks)} stdout chunk(s) "
+                f"for injection on next user prompt"
+            )
+    except Exception as e:
+        logger.error(f"Error in SessionStart hook: {e}", exc_info=True)
+
+
+async def on_session_end_hook() -> None:
+    """Session-end callback — fires SessionEnd hooks (issue #298)."""
+    if not _hook_engine:
+        return
+
+    event_data = EventData(
+        event_type="SessionEnd",
+        tool_name="session",
+        tool_args={},
+    )
+
+    try:
+        await _hook_engine.process_event("SessionEnd", event_data)
+    except Exception as e:
+        logger.error(f"Error in SessionEnd hook: {e}", exc_info=True)
+
+
+register_callback("startup", on_startup_hook)
+register_callback("session_end", on_session_end_hook)
+
+
+# ---------------------------------------------------------------------------
+# UserPromptSubmit
+# ---------------------------------------------------------------------------
+
+
+async def on_user_prompt_submit_hook(
+    prompt: str, session_id: Optional[str] = None
+) -> Optional[str]:
+    """Fire UserPromptSubmit hooks and inject their stdout (+ any pending
+    SessionStart stdout) into the user prompt.
+
+    Returns the (possibly augmented) prompt, or ``None`` if there's nothing
+    to add. See issue #298.
+    """
+    chunks: List[str] = []
+
+    # Drain any pending SessionStart context first.
+    if _pending_session_context:
+        chunks.extend(_pending_session_context)
+        _pending_session_context.clear()
+
+    if _hook_engine:
+        event_data = EventData(
+            event_type="UserPromptSubmit",
+            tool_name="user_prompt",
+            tool_args={"prompt": prompt},
+            context={"session_id": session_id} if session_id else {},
+        )
+
+        try:
+            result = await _hook_engine.process_event("UserPromptSubmit", event_data)
+            chunks.extend(_collect_context_stdout(result))
+        except Exception as e:
+            logger.error(f"Error in UserPromptSubmit hook: {e}", exc_info=True)
+
+    if not chunks:
+        return None
+
+    header = "\n\n".join(f"[hook context]\n{c}" for c in chunks)
+    return f"{header}\n\n{prompt}"
+
+
+register_callback("user_prompt_submit", on_user_prompt_submit_hook)
+
+
+# ---------------------------------------------------------------------------
+# PreCompact
+# ---------------------------------------------------------------------------
+
+
+async def on_pre_compact_hook(
+    agent_name: str,
+    strategy: str,
+    message_count: int,
+    token_count: int,
+) -> None:
+    """Fire PreCompact hooks before history compaction (issue #298)."""
+    if not _hook_engine:
+        return
+
+    event_data = EventData(
+        event_type="PreCompact",
+        tool_name="compact",
+        tool_args={
+            "agent_name": agent_name,
+            "strategy": strategy,
+            "message_count": message_count,
+            "token_count": token_count,
+        },
+    )
+
+    try:
+        await _hook_engine.process_event("PreCompact", event_data)
+    except Exception as e:
+        logger.error(f"Error in PreCompact hook: {e}", exc_info=True)
+
+
+register_callback("pre_compact", on_pre_compact_hook)
+
+
+# ---------------------------------------------------------------------------
+# Notification
+# ---------------------------------------------------------------------------
+
+
+async def on_notification_hook(
+    message: str, level: str = "info", context: Any = None
+) -> None:
+    """Fire Notification hooks when the agent surfaces a user-attention event."""
+    if not _hook_engine:
+        return
+
+    event_data = EventData(
+        event_type="Notification",
+        tool_name="notification",
+        tool_args={"message": message, "level": level},
+        context={"context": context} if context else {},
+    )
+
+    try:
+        await _hook_engine.process_event("Notification", event_data)
+    except Exception as e:
+        logger.error(f"Error in Notification hook: {e}", exc_info=True)
+
+
+register_callback("notification", on_notification_hook)
+
+
+# ---------------------------------------------------------------------------
+# Stop / SubagentStop  (via agent_run_end)
+# ---------------------------------------------------------------------------
+
+
+async def on_agent_run_end_hook(
+    agent_name: str,
+    model_name: str,
+    session_id: str | None = None,
+    success: bool = True,
+    error: Exception | None = None,
+    response_text: str | None = None,
+    metadata: dict | None = None,
+) -> None:
+    """agent_run_end callback — fires Stop or SubagentStop hooks."""
+    if not _hook_engine:
+        return
+
+    agent_lower = (agent_name or "").lower()
+    is_subagent = any(name in agent_lower for name in _SUBAGENT_NAMES)
+    event_type = "SubagentStop" if is_subagent else "Stop"
+
+    event_data = EventData(
+        event_type=event_type,
+        tool_name=agent_name or "agent",
+        tool_args={},
+        context={
+            "agent_name": agent_name,
+            "model_name": model_name,
+            "session_id": session_id,
+            "success": success,
+            "error": str(error) if error else None,
+            "response_text": response_text,
+            "metadata": metadata,
+        },
+    )
+
+    try:
+        await _hook_engine.process_event(event_type, event_data)
+    except Exception as e:
+        logger.error(f"Error in {event_type} hook: {e}", exc_info=True)
+
+
+register_callback("agent_run_end", on_agent_run_end_hook)
+
+logger.info(
+    "Claude Code hooks plugin registered (PreToolUse, PostToolUse, "
+    "SessionStart, SessionEnd, UserPromptSubmit, PreCompact, "
+    "Notification, Stop, SubagentStop)"
+)

code_puppy_core_plugins/claude_code_oauth/README.md

@@ -0,0 +1,167 @@
+# Claude Code OAuth Plugin
+
+This plugin adds OAuth authentication for Claude Code to Code Puppy, automatically importing available models into your configuration.
+
+## Features
+
+- **OAuth Authentication**: Secure OAuth flow for Claude Code using PKCE
+- **Automatic Model Discovery**: Fetches available models from the Claude API once authenticated
+- **Model Registration**: Automatically adds models to `extra_models.json` with the `claude-code-` prefix
+- **Token Management**: Secure storage of OAuth tokens in the Code Puppy config directory
+- **Browser Integration**: Launches the Claude OAuth consent flow automatically
+- **Callback Capture**: Listens on localhost to receive and process the OAuth redirect
+
+## Commands
+
+### `/claude-code-auth`
+Authenticate with Claude Code via OAuth and import available models.
+
+This will:
+1. Launch the Claude OAuth consent flow in your browser
+2. Walk you through approving access for the shared `claude-cli` client
+3. Capture the redirect from Claude in a temporary local callback server
+4. Exchange the returned code for access tokens and store them securely
+5. Fetch available models from Claude Code and add them to your configuration
+
+### `/claude-code-status`
+Check Claude Code OAuth authentication status and configured models.
+
+Shows:
+- Current authentication status
+- Token expiry information (if available)
+- Number and names of configured Claude Code models
+
+### `/claude-code-logout`
+Remove Claude Code OAuth tokens and imported models.
+
+This will:
+1. Remove stored OAuth tokens
+2. Remove all Claude Code models from `extra_models.json`
+
+## Setup
+
+### Prerequisites
+
+1. **Claude account** with access to the Claude Console developer settings
+2. **Browser access** to generate authorization codes
+
+### Configuration
+
+The plugin ships with sensible defaults in `config.py`:
+
+```python
+CLAUDE_CODE_OAUTH_CONFIG = {
+    "auth_url": "https://claude.ai/oauth/authorize",
+    "token_url": "https://console.anthropic.com/v1/oauth/token",
+    "api_base_url": "https://api.anthropic.com",
+    "client_id": "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
+    "scope": "org:create_api_key user:profile user:inference",
+    "redirect_host": "http://localhost",
+    "redirect_path": "callback",
+    "callback_port_range": (8765, 8795),
+    "callback_timeout": 180,
+    "prefix": "claude-code-",
+    "default_context_length": 200000,
+    "api_key_env_var": "CLAUDE_CODE_ACCESS_TOKEN",
+}
+```
+
+These values mirror the public client used by llxprt-code. Adjust only if Anthropic changes their configuration.
+
+### Environment Variables
+
+After authentication, the models will reference:
+- `CLAUDE_CODE_ACCESS_TOKEN`: Automatically written by the plugin
+
+## Usage Example
+
+```bash
+# Authenticate with Claude Code
+/claude-code-auth
+
+# Check status
+/claude-code-status
+
+# Use a Claude Code model
+/set model claude-code-claude-3-5-sonnet-20241022
+
+# When done, logout
+/claude-code-logout
+```
+
+## Model Configuration
+
+After authentication, models will be added to `~/.code_puppy/extra_models.json`:
+
+```json
+{
+  "claude-code-claude-3-5-sonnet-20241022": {
+    "type": "anthropic",
+    "name": "claude-3-5-sonnet-20241022",
+    "custom_endpoint": {
+      "url": "https://api.anthropic.com",
+      "api_key": "$CLAUDE_CODE_ACCESS_TOKEN"
+    },
+    "context_length": 200000,
+    "oauth_source": "claude-code-plugin"
+  }
+}
+```
+
+## Security
+
+- **Token Storage**: Tokens are saved to `~/.code_puppy/claude_code_oauth.json` with `0o600` permissions
+- **PKCE Support**: Uses Proof Key for Code Exchange for enhanced security
+- **State Validation**: Checks the returned state (if provided) to guard against CSRF
+- **HTTPS Only**: All OAuth communications use HTTPS endpoints
+
+## Troubleshooting
+
+### Browser doesn't open
+- Manually visit the URL shown in the output
+- Check that a default browser is configured
+
+### Authentication fails
+- Ensure the browser completed the redirect back to Code Puppy (no pop-up blockers)
+- Retry if the window shows an error; codes expire quickly
+- Confirm network access to `claude.ai`
+
+### Models not showing up
+- Claude may not return the model list for your account; verify access manually
+- Check `/claude-code-status` to confirm authentication succeeded
+
+## Development
+
+### File Structure
+
+```
+claude_code_oauth/
+├── __init__.py
+├── register_callbacks.py  # Main plugin logic and command handlers
+├── config.py              # Configuration settings
+├── utils.py               # OAuth helpers and file operations
+├── README.md              # This file
+├── SETUP.md               # Quick setup guide
+└── test_plugin.py         # Manual test helper
+```
+
+### Key Components
+
+- **OAuth Flow**: Authorization code flow with PKCE and automatic callback capture
+- **Token Management**: Secure storage and retrieval helpers
+- **Model Discovery**: API integration for model fetching
+- **Plugin Registration**: Custom command handlers wired into Code Puppy
+
+## Notes
+
+- The plugin assumes Anthropic continues to expose the shared `claude-cli` OAuth client
+- Tokens are refreshed on subsequent API calls if the service returns refresh tokens
+- Models are prefixed with `claude-code-` to avoid collisions with other Anthropic models
+
+## Contributing
+
+When modifying this plugin:
+1. Maintain security best practices
+2. Test OAuth flow changes manually before shipping
+3. Update documentation for any configuration or UX changes
+4. Keep files under 600 lines; split into helpers when needed