@pennyfarthing/core 11.3.2 → 11.3.4

package/pennyfarthing_scripts/healthscore/formatters.py

@@ -1,46 +0,0 @@
-"""
-Output formatters for health score results.
-
-Supports table, JSON, and CSV output — no external dependencies.
-"""
-
-from __future__ import annotations
-
-import csv
-import io
-import json
-from dataclasses import asdict
-
-from pennyfarthing_scripts.healthscore.models import HealthscoreResult
-
-
-def format_table(result: HealthscoreResult) -> str:
-    """Format health score results as column-aligned table."""
-    lines = [
-        f"Health Score: {result.composite_score:.1f} / 100",
-        "",
-        f"{'Dimension':<30}  {'Score':>6}  {'Weight':>6}",
-        f"{'-' * 30}  {'------':>6}  {'------':>6}",
-    ]
-
-    for dim in result.dimensions:
-        score_str = f"{dim.score:.1f}" if dim.score is not None else "N/A"
-        weight_pct = f"{dim.weight * 100:.0f}%"
-        lines.append(f"{dim.name:<30}  {score_str:>6}  {weight_pct:>6}")
-
-    return "\n".join(lines)
-
-
-def export_json(result: HealthscoreResult) -> str:
-    """Serialize result to JSON string."""
-    return json.dumps(asdict(result), indent=2, default=str)
-
-
-def export_csv(result: HealthscoreResult) -> str:
-    """Export dimension scores as CSV."""
-    buf = io.StringIO()
-    writer = csv.writer(buf)
-    writer.writerow(["dimension", "score", "weight", "error"])
-    for dim in result.dimensions:
-        writer.writerow([dim.name, dim.score, dim.weight, dim.error or ""])
-    return buf.getvalue()

package/pennyfarthing_scripts/hooks/bell_mode.py

@@ -1,214 +0,0 @@
-"""
-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()

package/pennyfarthing_scripts/hooks/cli.py

@@ -1,96 +0,0 @@
-"""
-Hook CLI group — internal hooks called by Claude Code settings.
-
-All hooks read JSON from stdin (Claude Code protocol) and output
-JSON/text to stdout. Exit codes: 0=allow, 2=block (PreToolUse).
-
-Usage in settings.local.json:
-  "command": "pf hooks session-start"
-  "command": "pf hooks bell-mode"
-  "command": "pf hooks statusline"
-"""
-
-import click
-
-
-@click.group(hidden=True)
-def hooks():
-    """Internal hooks (called by Claude Code settings)."""
-    pass
-
-
-@hooks.command("session-start")
-def session_start():
-    """SessionStart hook — session setup, WheelHub auto-start, OTEL config."""
-    from pennyfarthing_scripts.hooks.session_start import main
-    main()
-
-
-@hooks.command("session-stop")
-def session_stop():
-    """Stop hook — save checkpoint for cross-session continuity."""
-    from pennyfarthing_scripts.hooks.session_stop import main
-    main()
-
-
-@hooks.command("reflector-check")
-def reflector_check():
-    """Stop hook — enforce CYCLIST reflector markers on every turn."""
-    from pennyfarthing_scripts.hooks.reflector_check import main
-    main()
-
-
-@hooks.command("pre-edit-check")
-def pre_edit_check():
-    """PreToolUse hook — block edits to protected files."""
-    from pennyfarthing_scripts.hooks.pre_edit_check import main
-    main()
-
-
-@hooks.command("context-warning")
-def context_warning():
-    """PreToolUse hook — warn when context usage is high."""
-    from pennyfarthing_scripts.hooks.context_warning import main
-    main()
-
-
-@hooks.command("context-breaker")
-def context_breaker():
-    """PreToolUse hook — block tool execution at critical context usage."""
-    from pennyfarthing_scripts.hooks.context_breaker import main
-    main()
-
-
-@hooks.command("cyclist-pretooluse")
-def cyclist_pretooluse():
-    """PreToolUse hook — route approval through WheelHub when Cyclist is running."""
-    from pennyfarthing_scripts.hooks.cyclist_pretooluse import main
-    main()
-
-
-@hooks.command("schema-validation")
-def schema_validation():
-    """PreToolUse hook — validate XML schema on Write operations."""
-    from pennyfarthing_scripts.hooks.schema_validation import main
-    main()
-
-
-@hooks.command("bell-mode")
-def bell_mode():
-    """PostToolUse hook — bell queue + tandem observation injection."""
-    from pennyfarthing_scripts.hooks.bell_mode import main
-    main()
-
-
-@hooks.command("sprint-yaml")
-def sprint_yaml():
-    """PostToolUse hook — validate sprint YAML after Edit/Write."""
-    from pennyfarthing_scripts.hooks.sprint_yaml_validation import main
-    main()
-
-
-@hooks.command("statusline")
-def statusline():
-    """statusLine hook — render Claude Code status bar."""
-    from pennyfarthing_scripts.hooks.statusline import main
-    main()

package/pennyfarthing_scripts/hooks/context_breaker.py

@@ -1,104 +0,0 @@
-"""
-Context circuit breaker hook (PreToolUse) — block tool execution at critical usage.
-
-When context exceeds the critical threshold (default 80%), blocks tool execution
-with exit code 2 and saves the active agent to a checkpoint for /continue-session.
-
-Unlike context_warning.py which only warns, this is a hard stop.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import sys
-from datetime import UTC, datetime
-from pathlib import Path
-
-from pennyfarthing_scripts.context import check_context, load_config
-
-
-def _checkpoint_save(project_dir: str, label: str, data: str) -> None:
-    """Save a checkpoint entry (reimplements checkpoint.sh logic in Python)."""
-    try:
-        checkpoint_file = Path(project_dir) / ".session" / "checkpoints.log"
-        checkpoint_file.parent.mkdir(parents=True, exist_ok=True)
-        timestamp = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
-        with open(checkpoint_file, "a") as f:
-            f.write(f"{timestamp}|{label}|{data}\n")
-    except OSError:
-        pass
-
-
-def main() -> None:
-    """Main entry point for context circuit breaker hook."""
-    try:
-        # Read stdin to get session_id
-        raw_input = sys.stdin.read()
-        input_data = {}
-        try:
-            input_data = json.loads(raw_input)
-        except (json.JSONDecodeError, ValueError):
-            pass
-
-        project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
-        config = load_config(project_dir)
-
-        result = check_context(project_dir=project_dir)
-
-        if result.error:
-            sys.exit(0)
-
-        critical_threshold = config.critical_threshold
-        pct = result.usable_percent
-
-        if pct >= critical_threshold:
-            # Auto-save active agent to checkpoint
-            session_id = input_data.get("session_id", "")
-            active_agent = ""
-
-            if session_id:
-                agent_file = Path(project_dir) / ".session" / "agents" / session_id
-                if agent_file.is_file():
-                    try:
-                        active_agent = agent_file.read_text().strip()
-                    except OSError:
-                        pass
-
-            if active_agent:
-                _checkpoint_save(project_dir, "circuit_breaker_agent", active_agent)
-
-            # Send error to stderr (Claude sees this)
-            msg = f"""CONTEXT CIRCUIT BREAKER TRIGGERED
-
-Context usage: {pct}% - CRITICAL (threshold: {critical_threshold}%)
-
-Tool execution BLOCKED. You must stop and hand off."""
-
-            if active_agent:
-                msg += f"""
-
-Active agent saved: {active_agent}
-The agent will be restored with FULL context when you run /continue-session."""
-
-            msg += """
-
-Required actions:
-1. Commit any pending changes
-2. Tell user to start fresh session with /continue-session
-
-DO NOT attempt further tool calls. This is a hard stop.
-
-To resume later: /continue-session"""
-
-            print(msg, file=sys.stderr)
-            sys.exit(2)
-
-    except Exception:
-        pass
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

package/pennyfarthing_scripts/hooks/context_warning.py

@@ -1,66 +0,0 @@
-"""
-Context warning hook (PreToolUse) — warn agent when context usage is high.
-
-Uses context.py to check transcript-based context percentage.
-Outputs warning text to stdout but always exits 0 (never blocks).
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-
-from pennyfarthing_scripts.context import check_context, load_config
-
-
-def main() -> None:
-    """Main entry point for context warning hook."""
-    try:
-        # Read and discard stdin (required by hook protocol)
-        sys.stdin.read()
-
-        project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
-        config = load_config(project_dir)
-
-        result = check_context(project_dir=project_dir)
-
-        if result.error:
-            sys.exit(0)
-
-        warning_threshold = config.warning_threshold
-        critical_threshold = config.critical_threshold
-        pct = result.usable_percent
-
-        if pct >= critical_threshold:
-            print(f"""
----
-CONTEXT WARNING: {pct}% (CRITICAL)
-
-Context usage is critically high. Recommended actions:
-1. Complete current task immediately
-2. Commit any pending changes
-3. Hand off to next agent or ask user to start fresh session
-
-Do NOT start new subtasks. Wrap up and hand off.
----
-""")
-        elif pct >= warning_threshold:
-            print(f"""
----
-CONTEXT WARNING: {pct}%
-
-Context usage is high. Consider:
-- Wrapping up current task soon
-- Preparing for handoff to next agent
-- Avoiding large file reads or complex operations
----
-""")
-
-    except Exception:
-        pass
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

package/pennyfarthing_scripts/hooks/cyclist_pretooluse.py

@@ -1,129 +0,0 @@
-"""
-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 pennyfarthing_scripts.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 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)
-
-        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()