@pennyfarthing/core 11.3.3 → 11.3.4

package/pennyfarthing-dist/pf/healthscore/formatters.py

@@ -0,0 +1,46 @@
+"""
+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 pf.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-dist/pf/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 pf.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-dist/pf/hooks/cli.py

@@ -0,0 +1,96 @@
+"""
+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 pf.hooks.session_start import main
+    main()
+
+
+@hooks.command("session-stop")
+def session_stop():
+    """Stop hook — save checkpoint for cross-session continuity."""
+    from pf.hooks.session_stop import main
+    main()
+
+
+@hooks.command("reflector-check")
+def reflector_check():
+    """Stop hook — enforce CYCLIST reflector markers on every turn."""
+    from pf.hooks.reflector_check import main
+    main()
+
+
+@hooks.command("pre-edit-check")
+def pre_edit_check():
+    """PreToolUse hook — block edits to protected files."""
+    from pf.hooks.pre_edit_check import main
+    main()
+
+
+@hooks.command("context-warning")
+def context_warning():
+    """PreToolUse hook — warn when context usage is high."""
+    from pf.hooks.context_warning import main
+    main()
+
+
+@hooks.command("context-breaker")
+def context_breaker():
+    """PreToolUse hook — block tool execution at critical context usage."""
+    from pf.hooks.context_breaker import main
+    main()
+
+
+@hooks.command("cyclist-pretooluse")
+def cyclist_pretooluse():
+    """PreToolUse hook — route approval through WheelHub when Cyclist is running."""
+    from pf.hooks.cyclist_pretooluse import main
+    main()
+
+
+@hooks.command("schema-validation")
+def schema_validation():
+    """PreToolUse hook — validate XML schema on Write operations."""
+    from pf.hooks.schema_validation import main
+    main()
+
+
+@hooks.command("bell-mode")
+def bell_mode():
+    """PostToolUse hook — bell queue + tandem observation injection."""
+    from pf.hooks.bell_mode import main
+    main()
+
+
+@hooks.command("sprint-yaml")
+def sprint_yaml():
+    """PostToolUse hook — validate sprint YAML after Edit/Write."""
+    from pf.hooks.sprint_yaml_validation import main
+    main()
+
+
+@hooks.command("statusline")
+def statusline():
+    """statusLine hook — render Claude Code status bar."""
+    from pf.hooks.statusline import main
+    main()

package/pennyfarthing-dist/pf/hooks/context_breaker.py

@@ -0,0 +1,104 @@
+"""
+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 pf.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-dist/pf/hooks/context_warning.py

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