@pennyfarthing/core 11.2.0 → 11.2.2

package/pennyfarthing_scripts/hooks.py

@@ -1,437 +1,32 @@
 """
-Shared utilities for Pennyfarthing Claude Code hooks.
+Backward-compatibility shim — hooks utilities moved to hooks/ subpackage.
 
-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 exports are re-imported from pennyfarthing_scripts.hooks (the package).
+Existing code that does `from hooks import ...` or
+`from pennyfarthing_scripts.hooks import ...` continues to work.
 
-All hooks should import from this module for consistency.
-
-Story: MSSCI-12409 - Hook consistency and relay mode compatibility
+This file will be removed in a future version.
 """
 
-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 = ".wheelhub-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. .wheelhub-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. .wheelhub-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
-    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"]
-
-    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
+# Re-export everything from the hooks package
+from pennyfarthing_scripts.hooks import (  # noqa: F401
+    CYCLIST_PORT_FILE,
+    DEFAULT_CYCLIST_PORT,
+    HTTP_TIMEOUT_SECONDS,
+    ContextState,
+    CyclistSettings,
+    HookResponse,
+    find_project_root,
+    get_context_state,
+    get_cyclist_port,
+    is_bell_mode_enabled,
+    is_cyclist_running,
+    is_relay_mode_enabled,
+    load_settings,
+    output_hook_response,
+    read_port_file,
+    read_stdin_json,
+    send_to_cyclist,
+    should_auto_approve,
+    should_auto_handoff,
+)

package/pennyfarthing_scripts/pretooluse_hook.py

@@ -1,192 +1,10 @@
-#!/usr/bin/env python3
 """
-Cyclist PreToolUse Hook (Python)
+Backward-compatibility shim — pretooluse hook moved to hooks/cyclist_pretooluse.py.
 
-This script is called by Claude Code before each tool execution.
-It communicates with WheelHub (Cyclist's central coordination server)
-via HTTP to get approval decisions.
-
-Flow:
-1. Claude Code calls this script with tool info via stdin (JSON)
-2. Script reads port from .wheelhub-port in project directory
-3. Script sends request to WheelHub's /api/hook-request endpoint
-4. WheelHub shows approval modal, user decides
-5. Script receives response, outputs JSON decision to stdout
-6. Claude Code proceeds or blocks based on decision
-
-Per ADR-0004: All communication converges through WheelHub.
-
-Story: MSSCI-12409 - Hook consistency and WheelHub consolidation
-
-Usage:
-  Install in ~/.claude/settings.json or project .claude/settings.json:
-  {
-    "hooks": {
-      "PreToolUse": [{
-        "matcher": "Bash",
-        "hooks": [{
-          "type": "command",
-          "command": "python3 /path/to/pretooluse_hook.py"
-        }]
-      }]
-    }
-  }
+This file will be removed in a future version.
 """
 
-import sys
-from pathlib import Path
-
-# Add parent directory to path for imports
-sys.path.insert(0, str(Path(__file__).parent))
-
-from 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.
-
-    Looks up .session/agents/{session_id} to find the active agent name.
-    Falls back to the most recently modified agent file if session_id
-    doesn't match.
-
-    Args:
-        session_id: Claude Code session ID
-        project_root: Project root directory
-
-    Returns:
-        Agent name string, or None if not found
-    """
-    if not project_root:
-        return None
-
-    agents_dir = project_root / ".session" / "agents"
-    if not agents_dir.is_dir():
-        return None
-
-    # Try exact session_id match first
-    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
-
-    # Fallback: most recently modified agent file
-    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 main() -> None:
-    """Main entry point for PreToolUse hook."""
-    try:
-        # Read tool data from Claude Code
-        tool_data = read_stdin_json()
-
-        # Extract relevant fields
-        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")
-
-        # Find project root
-        project_root = find_project_root()
-
-        # Resolve agent name from session file (MSSCI-14392)
-        agent_name = _resolve_agent(session_id, project_root)
-
-        # Check if Cyclist is running
-        if not is_cyclist_running(project_root):
-            # No Cyclist - pass through to Claude Code's built-in permissions
-            # Using "allow" so the hook doesn't override Claude Code's own
-            # permission system (settings.json allow lists still apply)
-            sys.exit(0)
-
-        # Load settings to check for auto-approval mode
-        settings = load_settings(project_root)
-        if settings.permission_mode == "accept":
-            # Auto-accept mode - approve everything
-            output_hook_response(HookResponse(
-                event_name="PreToolUse",
-                decision="allow",
-                reason="Auto-accept mode enabled",
-            ))
-            sys.exit(0)
-
-        # Get context state for inclusion in request
-        context = get_context_state(project_root)
-
-        # Build request data
-        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,
-            },
-        }
-        # Include agent identity if resolved (MSSCI-14392)
-        if agent_name:
-            request_data["agent"] = agent_name
-
-        # Send approval request to WheelHub with context info
-        response = send_to_cyclist(
-            endpoint="/api/hook-request",
-            data=request_data,
-            project_root=project_root,
-        )
-
-        if response is None:
-            # Connection failed - defer to Claude Code
-            output_hook_response(HookResponse(
-                event_name="PreToolUse",
-                decision="ask",
-                reason="Could not connect to WheelHub",
-            ))
-            sys.exit(0)
-
-        # Extract decision from response
-        decision = response.get("decision", "ask")
-        reason = response.get("reason", "")
-        data = response.get("data")
-
-        # Output decision
-        output_hook_response(HookResponse(
-            event_name="PreToolUse",
-            decision=decision,
-            reason=reason,
-            updated_input=data,
-        ))
-        sys.exit(0)
-
-    except Exception as e:
-        # On error, output to stderr and exit with code 0 (allow)
-        # We don't want hook failures to block the user
-        print(f"[pretooluse-hook] Error: {e}", file=sys.stderr)
-        sys.exit(0)
-
+from pennyfarthing_scripts.hooks.cyclist_pretooluse import main  # noqa: F401
 
 if __name__ == "__main__":
     main()