@pennyfarthing/core 11.2.0 → 11.2.2

package/pennyfarthing_scripts/hooks/__init__.py

@@ -0,0 +1,442 @@
+"""
+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
+    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"]
+
+    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_scripts/hooks/bell_mode.py

@@ -0,0 +1,214 @@
+"""
+PostToolUse Hook — Bell Mode + Tandem Injection.
+
+Called by Claude Code after each tool execution. Handles two independent
+injection systems:
+
+1. Bell queue (Cyclist only) — injects queued user messages when Cyclist
+   is running and bell_mode is enabled. In CLI sessions this is a no-op.
+2. Tandem observations (always active) — injects backseat agent observations
+   when tandem observation files exist. No configuration required.
+
+Bell queue takes precedence: if a queued message exists, tandem is
+deferred to the next hook invocation.
+
+Consolidates bellmode_hook.py into the hooks subpackage.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+from pennyfarthing_scripts.hooks import (
+    CYCLIST_PORT_FILE,
+    HookResponse,
+    find_project_root,
+    is_bell_mode_enabled,
+    output_hook_response,
+    read_port_file,
+    send_to_cyclist,
+)
+
+# =============================================================================
+# Bell Queue
+# =============================================================================
+
+
+def _read_bell_queue(project_root: Path) -> list[dict]:
+    queue_path = project_root / ".pennyfarthing" / "bell-queue.json"
+    if not queue_path.exists():
+        return []
+    try:
+        with open(queue_path) as f:
+            queue = json.load(f)
+            if isinstance(queue, list):
+                return queue
+    except (json.JSONDecodeError, OSError):
+        pass
+    return []
+
+
+def _dequeue_message(project_root: Path) -> None:
+    queue_path = project_root / ".pennyfarthing" / "bell-queue.json"
+    if not queue_path.exists():
+        return
+    try:
+        with open(queue_path) as f:
+            queue = json.load(f)
+        if isinstance(queue, list) and len(queue) > 0:
+            queue = queue[1:]
+            with open(queue_path, "w") as f:
+                json.dump(queue, f)
+    except (json.JSONDecodeError, OSError):
+        pass
+
+
+def _notify_cyclist(project_root: Path, message_text: str) -> None:
+    try:
+        send_to_cyclist(
+            endpoint="/api/bell-consumed",
+            data={"text": message_text},
+            project_root=project_root,
+            timeout=5,
+        )
+    except Exception:
+        pass
+
+
+# =============================================================================
+# Tandem Observations
+# =============================================================================
+
+
+def _read_tandem_observations(project_root: Path) -> list[Path]:
+    session_dir = project_root / ".session"
+    if not session_dir.is_dir():
+        return []
+    return sorted(session_dir.glob("*-tandem-*.md"))
+
+
+def _get_latest_observation(file_content: str) -> dict | None:
+    persona_match = re.search(r"\*\*Observer:\*\*\s*\w+\s*\(([^)]+)\)", file_content)
+    persona = persona_match.group(1) if persona_match else "Unknown"
+
+    entries = re.split(r"## \[\d{1,2}:\d{2}\] Observation\n", file_content)
+    if len(entries) < 2:
+        return None
+
+    last_entry = entries[-1].strip()
+    last_entry = re.sub(r"\n---\s*$", "", last_entry).strip()
+    lines = last_entry.split("\n")
+    text_lines = [line for line in lines if not line.startswith("**Trigger:**")]
+    text = "\n".join(text_lines).strip()
+
+    if not text:
+        return None
+
+    return {"persona": persona, "text": text}
+
+
+def _get_tandem_mtime(project_root: Path, agent: str) -> float:
+    sidecar = project_root / ".session" / f".tandem-mtime-{agent}"
+    if not sidecar.exists():
+        return 0.0
+    try:
+        return float(sidecar.read_text().strip())
+    except (ValueError, OSError):
+        return 0.0
+
+
+def _save_tandem_mtime(project_root: Path, agent: str, mtime: float) -> None:
+    sidecar = project_root / ".session" / f".tandem-mtime-{agent}"
+    try:
+        sidecar.write_text(str(mtime))
+    except OSError:
+        pass
+
+
+def _check_tandem_files(project_root: Path) -> list[dict]:
+    tandem_files = _read_tandem_observations(project_root)
+    if not tandem_files:
+        return []
+
+    results = []
+    for obs_file in tandem_files:
+        agent_match = re.search(r"-tandem-(\w+)\.md$", obs_file.name)
+        if not agent_match:
+            continue
+        agent = agent_match.group(1)
+
+        try:
+            file_mtime = obs_file.stat().st_mtime
+        except OSError:
+            continue
+        saved_mtime = _get_tandem_mtime(project_root, agent)
+        if file_mtime == saved_mtime:
+            continue
+
+        try:
+            content = obs_file.read_text()
+        except OSError:
+            continue
+        obs = _get_latest_observation(content)
+        if not obs:
+            _save_tandem_mtime(project_root, agent, file_mtime)
+            continue
+
+        message = f"[Tandem] {obs['persona']}: {obs['text']}"
+        results.append({"agent": agent, "message": message})
+        _save_tandem_mtime(project_root, agent, file_mtime)
+
+    return results
+
+
+# =============================================================================
+# Entry Point
+# =============================================================================
+
+
+def main() -> None:
+    """Main entry point for PostToolUse hook."""
+    try:
+        # Read and discard stdin (required by hook protocol)
+        sys.stdin.read()
+
+        project_root = find_project_root()
+        if not project_root:
+            sys.exit(0)
+
+        # --- Bell queue (Cyclist only, requires bell_mode: true) ---
+        is_cyclist = read_port_file(CYCLIST_PORT_FILE, project_root) is not None
+        if is_cyclist and is_bell_mode_enabled(project_root):
+            queue = _read_bell_queue(project_root)
+            if queue:
+                first_message = queue[0]
+                message_text = first_message.get("text", "")
+                if message_text:
+                    output_hook_response(HookResponse(
+                        event_name="PostToolUse",
+                        additional_context=f"User feedback: {message_text}",
+                    ))
+                    _dequeue_message(project_root)
+                    _notify_cyclist(project_root, message_text)
+                    sys.exit(0)
+
+        # --- Tandem observations (always active) ---
+        tandem_results = _check_tandem_files(project_root)
+        if tandem_results:
+            output_hook_response(HookResponse(
+                event_name="PostToolUse",
+                additional_context=tandem_results[0]["message"],
+            ))
+
+        sys.exit(0)
+
+    except Exception as e:
+        print(f"[bellmode-hook] Error: {e}", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()