@pennyfarthing/core 11.4.0 → 12.0.0

package/pennyfarthing-dist/src/pf/hooks/__init__.py

@@ -0,0 +1,447 @@
+"""
+Shared utilities for Pennyfarthing Claude Code hooks.
+
+Provides common functionality for all hooks:
+- Project root detection
+- Port file discovery
+- Settings loading (relay_mode, permission_mode)
+- Context state checking
+- HTTP communication with Cyclist
+
+All hooks should import from this module for consistency.
+
+Story: MSSCI-12409 - Hook consistency and relay mode compatibility
+"""
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+# =============================================================================
+# Port File Constants
+# =============================================================================
+
+# WheelHub port file - central coordination server for all communication
+# Per ADR-0004: "the hub where all communication converges"
+CYCLIST_PORT_FILE = ".bikerack-port"
+
+# Default port if file not found
+DEFAULT_CYCLIST_PORT = 7431
+
+# HTTP timeout for Cyclist communication
+HTTP_TIMEOUT_SECONDS = 120
+
+
+# =============================================================================
+# Project Root Detection
+# =============================================================================
+
+
+def find_project_root(start_dir: Path | None = None) -> Path | None:
+    """Find the project root by looking for marker files.
+
+    Searches for (in order):
+    1. .bikerack-port (WheelHub is running)
+    2. .pennyfarthing directory
+    3. .claude directory
+
+    Args:
+        start_dir: Directory to start search from (defaults to cwd)
+
+    Returns:
+        Path to project root, or None if not found
+    """
+    current = Path(start_dir) if start_dir else Path.cwd()
+    current = current.resolve()
+
+    while current != current.parent:
+        # Check for Cyclist port files first (indicates Cyclist is running)
+        if (current / CYCLIST_PORT_FILE).exists():
+            return current
+        # Fall back to directory markers
+        if (current / ".pennyfarthing").is_dir():
+            return current
+        if (current / ".claude").is_dir():
+            return current
+        current = current.parent
+
+    return None
+
+
+# =============================================================================
+# Port File Reading
+# =============================================================================
+
+
+def read_port_file(file_name: str, project_root: Path | None = None) -> int | None:
+    """Read a port number from a Cyclist port file.
+
+    Args:
+        file_name: Name of the port file (e.g. .bikerack-port)
+        project_root: Project root directory (auto-detected if not provided)
+
+    Returns:
+        Port number, or None if file not found or invalid
+    """
+    root = project_root or find_project_root()
+    if not root:
+        return None
+
+    port_file = root / file_name
+    if not port_file.exists():
+        return None
+
+    try:
+        content = port_file.read_text().strip()
+        port = int(content)
+        if 0 < port < 65536:
+            return port
+    except (ValueError, OSError):
+        pass
+
+    return None
+
+
+def get_cyclist_port(project_root: Path | None = None) -> int:
+    """Get the WheelHub server port.
+
+    WheelHub is the central coordination server for all Cyclist communication,
+    including hook requests, OTEL, REST APIs, and WebSocket.
+
+    Args:
+        project_root: Project root directory (auto-detected if not provided)
+
+    Returns:
+        Port number (default if file not found)
+    """
+    port = read_port_file(CYCLIST_PORT_FILE, project_root)
+    if port:
+        return port
+
+    return DEFAULT_CYCLIST_PORT
+
+
+# =============================================================================
+# Settings Loading
+# =============================================================================
+
+
+@dataclass
+class CyclistSettings:
+    """Cyclist workflow settings from config.local.yaml."""
+
+    permission_mode: str = "manual"  # plan, manual, accept
+    relay_mode: bool = False
+    bell_mode: bool = False
+    git_monitor: bool = False
+    statusbar: bool = True
+    theme: str | None = None
+
+
+def load_settings(project_root: Path | None = None) -> CyclistSettings:
+    """Load Cyclist settings from .pennyfarthing/config.local.yaml.
+
+    Handles legacy setting migrations:
+    - permission_mode: 'turbo' -> 'accept' + relay_mode: True
+    - handoff_mode: 'auto' -> relay_mode: True
+    - auto_handoff: True -> relay_mode: True
+
+    Args:
+        project_root: Project root directory (auto-detected if not provided)
+
+    Returns:
+        CyclistSettings with current configuration
+    """
+    settings = CyclistSettings()
+
+    root = project_root or find_project_root()
+    if not root:
+        return settings
+
+    config_path = root / ".pennyfarthing" / "config.local.yaml"
+    if not config_path.exists():
+        return settings
+
+    try:
+        with open(config_path) as f:
+            config = yaml.safe_load(f) or {}
+    except (OSError, yaml.YAMLError):
+        return settings
+
+    # Extract theme
+    settings.theme = config.get("theme")
+
+    # Extract workflow settings
+    workflow = config.get("workflow", {})
+    if not isinstance(workflow, dict):
+        return settings
+
+    # Handle permission_mode
+    mode = workflow.get("permission_mode", "manual")
+    if mode == "turbo":
+        # Migrate turbo -> accept + relay_mode
+        settings.permission_mode = "accept"
+        settings.relay_mode = True
+    elif mode in ("plan", "manual", "accept"):
+        settings.permission_mode = mode
+    else:
+        settings.permission_mode = "manual"
+
+    # Handle explicit relay_mode (overrides migration)
+    if "relay_mode" in workflow and isinstance(workflow["relay_mode"], bool):
+        settings.relay_mode = workflow["relay_mode"]
+    elif not settings.relay_mode:
+        # Check legacy settings
+        if workflow.get("handoff_mode") == "auto":
+            settings.relay_mode = True
+        elif workflow.get("auto_handoff") is True:
+            settings.relay_mode = True
+
+    # Handle bell_mode
+    if "bell_mode" in workflow and isinstance(workflow["bell_mode"], bool):
+        settings.bell_mode = workflow["bell_mode"]
+
+    # Handle git_monitor
+    if "git_monitor" in workflow and isinstance(workflow["git_monitor"], bool):
+        settings.git_monitor = workflow["git_monitor"]
+
+    # Handle statusbar
+    if "statusbar" in workflow and isinstance(workflow["statusbar"], bool):
+        settings.statusbar = workflow["statusbar"]
+
+    return settings
+
+
+def is_relay_mode_enabled(project_root: Path | None = None) -> bool:
+    """Check if relay mode (auto-handoff) is enabled.
+
+    Args:
+        project_root: Project root directory (auto-detected if not provided)
+
+    Returns:
+        True if relay mode is enabled
+    """
+    return load_settings(project_root).relay_mode
+
+
+def is_bell_mode_enabled(project_root: Path | None = None) -> bool:
+    """Check if bell mode is enabled.
+
+    Args:
+        project_root: Project root directory (auto-detected if not provided)
+
+    Returns:
+        True if bell mode is enabled
+    """
+    return load_settings(project_root).bell_mode
+
+
+# =============================================================================
+# Context State
+# =============================================================================
+
+
+@dataclass
+class ContextState:
+    """Current context usage state."""
+
+    used_tokens: int = 0
+    max_tokens: int = 200000
+    percentage: float = 0.0
+    is_high: bool = False  # > 60%
+    is_critical: bool = False  # > 80%
+
+
+def get_context_state(project_root: Path | None = None) -> ContextState:
+    """Get current context usage from Cyclist API.
+
+    Calls Cyclist's /api/context endpoint which runs check-context.sh.
+
+    Args:
+        project_root: Project root directory (auto-detected if not provided)
+
+    Returns:
+        ContextState with current usage (defaults if Cyclist not running)
+    """
+    state = ContextState()
+
+    port = get_cyclist_port(project_root)
+    url = f"http://127.0.0.1:{port}/api/context"
+
+    try:
+        with urllib.request.urlopen(url, timeout=5) as response:
+            data = json.loads(response.read().decode())
+            state.used_tokens = data.get("used_tokens", 0)
+            state.max_tokens = data.get("max_tokens", 200000)
+            if state.max_tokens > 0:
+                state.percentage = (state.used_tokens / state.max_tokens) * 100
+            state.is_high = state.percentage > 60
+            state.is_critical = state.percentage > 80
+    except (urllib.error.URLError, json.JSONDecodeError, OSError):
+        # Cyclist not running or error - return defaults
+        pass
+
+    return state
+
+
+# =============================================================================
+# Cyclist HTTP Communication
+# =============================================================================
+
+
+def send_to_cyclist(
+    endpoint: str,
+    data: dict[str, Any],
+    port: int | None = None,
+    project_root: Path | None = None,
+    timeout: int = HTTP_TIMEOUT_SECONDS,
+) -> dict[str, Any] | None:
+    """Send a POST request to WheelHub (Cyclist's central coordination server).
+
+    All endpoints go through WheelHub per ADR-0004.
+
+    Args:
+        endpoint: API endpoint path (e.g., "/api/hook-request")
+        data: JSON data to send
+        port: Port to use (auto-detected if not provided)
+        project_root: Project root for port discovery
+        timeout: Request timeout in seconds
+
+    Returns:
+        Response JSON as dict, or None on error
+    """
+    if port is None:
+        port = get_cyclist_port(project_root)
+
+    url = f"http://127.0.0.1:{port}{endpoint}"
+    json_data = json.dumps(data).encode("utf-8")
+
+    request = urllib.request.Request(
+        url,
+        data=json_data,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return json.loads(response.read().decode())
+    except urllib.error.URLError as e:
+        # Connection refused means Cyclist isn't running
+        if "Connection refused" in str(e):
+            return None
+        raise
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+# =============================================================================
+# Hook Response Formatting
+# =============================================================================
+
+
+@dataclass
+class HookResponse:
+    """Standard hook response for Claude Code."""
+
+    event_name: str
+    decision: str | None = None  # allow, deny, ask (for PreToolUse)
+    reason: str | None = None
+    updated_input: dict[str, Any] | None = None
+    additional_context: str | None = None  # For PostToolUse context injection
+
+    def to_json(self) -> str:
+        """Format as Claude Code hook JSON output."""
+        output: dict[str, Any] = {
+            "hookSpecificOutput": {
+                "hookEventName": self.event_name,
+            }
+        }
+
+        hook_output = output["hookSpecificOutput"]
+
+        if self.decision:
+            hook_output["permissionDecision"] = self.decision
+        if self.reason:
+            hook_output["permissionDecisionReason"] = self.reason
+        if self.updated_input:
+            hook_output["updatedInput"] = self.updated_input
+        if self.additional_context:
+            hook_output["additionalContext"] = self.additional_context
+
+        return json.dumps(output)
+
+
+def output_hook_response(response: HookResponse) -> None:
+    """Output hook response to stdout for Claude Code."""
+    print(response.to_json())
+
+
+def read_stdin_json() -> dict[str, Any]:
+    """Read JSON from stdin (hook input from Claude Code).
+
+    Returns:
+        Parsed JSON as dict
+
+    Raises:
+        ValueError: If input is not valid JSON
+    """
+    data = sys.stdin.read()
+    try:
+        return json.loads(data)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid JSON input: {e}") from e
+
+
+# =============================================================================
+# Hook Execution Utilities
+# =============================================================================
+
+
+def is_cyclist_running(project_root: Path | None = None) -> bool:
+    """Check if Cyclist server is running.
+
+    Checks the CYCLIST environment variable set by ClaudeService when
+    spawning Claude inside Cyclist. No file I/O, no HTTP, no signals —
+    this runs on every tool invocation and must be instant.
+
+    The project_root parameter is kept for backward compatibility but
+    is no longer used.
+
+    Returns:
+        True if running inside a Cyclist-spawned Claude process
+    """
+    return os.environ.get("CYCLIST") == "1"
+
+
+def should_auto_approve(settings: CyclistSettings) -> bool:
+    """Check if requests should be auto-approved based on settings.
+
+    Auto-approve when permission_mode is 'accept' (formerly turbo).
+
+    Args:
+        settings: Current Cyclist settings
+
+    Returns:
+        True if auto-approval is enabled
+    """
+    return settings.permission_mode == "accept"
+
+
+def should_auto_handoff(settings: CyclistSettings) -> bool:
+    """Check if handoffs should be automatic based on settings.
+
+    Args:
+        settings: Current Cyclist settings
+
+    Returns:
+        True if relay_mode is enabled
+    """
+    return settings.relay_mode

package/pennyfarthing-dist/src/pf/hooks/cyclist_pretooluse.py

@@ -0,0 +1,161 @@
+"""
+Cyclist PreToolUse Hook — route tool approval through WheelHub.
+
+When Cyclist is running, sends approval requests to WheelHub's /api/hook-request
+endpoint. Falls back to Claude Code's built-in permissions when Cyclist is not active.
+
+Consolidates pretooluse_hook.py into the hooks subpackage.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from pf.hooks import (
+    HookResponse,
+    find_project_root,
+    get_context_state,
+    is_cyclist_running,
+    load_settings,
+    output_hook_response,
+    read_stdin_json,
+    send_to_cyclist,
+)
+
+
+def _resolve_agent(session_id: str | None, project_root: Path | None) -> str | None:
+    """Resolve agent name from session file."""
+    if not project_root:
+        return None
+
+    agents_dir = project_root / ".session" / "agents"
+    if not agents_dir.is_dir():
+        return None
+
+    if session_id:
+        agent_file = agents_dir / session_id
+        if agent_file.is_file():
+            try:
+                return agent_file.read_text().strip() or None
+            except OSError:
+                pass
+
+    try:
+        agent_files = sorted(
+            (f for f in agents_dir.iterdir() if f.is_file()),
+            key=lambda f: f.stat().st_mtime,
+            reverse=True,
+        )
+        if agent_files:
+            return agent_files[0].read_text().strip() or None
+    except OSError:
+        pass
+
+    return None
+
+
+def _forward_tool_input(
+    tool_name: str,
+    tool_id: str,
+    tool_input: dict,
+    project_root: Path | None,
+) -> None:
+    """Forward tool input to WheelHub for OTEL span correlation.
+
+    Story 120-13: BikeRack's audit log needs tool inputs for Read, Grep, Edit,
+    Write, etc. OTEL tool_result events don't include tool_parameters for these
+    tools. This function sends tool inputs to WheelHub's pending-tool-input
+    endpoint so the OTLP receiver can correlate them with incoming spans.
+    """
+    if not project_root:
+        return
+    try:
+        send_to_cyclist(
+            endpoint="/api/pending-tool-input",
+            data={
+                "toolName": tool_name,
+                "toolId": tool_id,
+                "input": tool_input,
+            },
+            project_root=project_root,
+        )
+    except Exception:
+        pass  # Non-blocking — don't fail the hook if forwarding fails
+
+
+def main() -> None:
+    """Main entry point for PreToolUse hook."""
+    try:
+        tool_data = read_stdin_json()
+        tool_name = tool_data.get("tool_name", "")
+        tool_id = tool_data.get("tool_use_id", "")
+        tool_input = tool_data.get("tool_input", {})
+        session_id = tool_data.get("session_id")
+
+        project_root = find_project_root()
+        agent_name = _resolve_agent(session_id, project_root)
+
+        if not is_cyclist_running(project_root):
+            sys.exit(0)
+
+        # Forward tool input for audit log enrichment (Story 120-13)
+        _forward_tool_input(tool_name, tool_id, tool_input, project_root)
+
+        settings = load_settings(project_root)
+        if settings.permission_mode == "accept":
+            output_hook_response(HookResponse(
+                event_name="PreToolUse",
+                decision="allow",
+                reason="Auto-accept mode enabled",
+            ))
+            sys.exit(0)
+
+        context = get_context_state(project_root)
+        request_data = {
+            "toolName": tool_name,
+            "toolId": tool_id,
+            "input": tool_input,
+            "sessionId": session_id,
+            "context": {
+                "percentage": context.percentage,
+                "isHigh": context.is_high,
+                "isCritical": context.is_critical,
+            },
+        }
+        if agent_name:
+            request_data["agent"] = agent_name
+
+        response = send_to_cyclist(
+            endpoint="/api/hook-request",
+            data=request_data,
+            project_root=project_root,
+        )
+
+        if response is None:
+            output_hook_response(HookResponse(
+                event_name="PreToolUse",
+                decision="ask",
+                reason="Could not connect to WheelHub",
+            ))
+            sys.exit(0)
+
+        decision = response.get("decision", "ask")
+        reason = response.get("reason", "")
+        data = response.get("data")
+
+        output_hook_response(HookResponse(
+            event_name="PreToolUse",
+            decision=decision,
+            reason=reason,
+            updated_input=data,
+        ))
+        sys.exit(0)
+
+    except Exception as e:
+        print(f"[pretooluse-hook] Error: {e}", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()