@pennyfarthing/core 11.2.0 → 11.2.1

package/pennyfarthing_scripts/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 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

@@ -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 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

@@ -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 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

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

package/pennyfarthing_scripts/hooks/pre_edit_check.py

@@ -0,0 +1,78 @@
+"""
+Pre-edit check hook (PreToolUse) — block edits to protected files.
+
+Prevents editing sensitive files (.env, .pem, .key, credentials, secrets),
+git internals, node_modules, and managed pennyfarthing files.
+
+Exit 0 = allow, Exit 2 = block.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import os
+import sys
+from pathlib import Path
+
+
+# Protected patterns — files that should never be edited automatically
+PROTECTED_PATTERNS = [
+    "*.env",
+    "*.pem",
+    "*.key",
+    "*credentials*",
+    "*secrets*",
+    ".git/*",
+    "node_modules/*",
+    "vendor/*",
+]
+
+
+def main() -> None:
+    """Main entry point for pre-edit check hook."""
+    try:
+        raw = sys.stdin.read()
+        try:
+            input_data = json.loads(raw)
+        except (json.JSONDecodeError, ValueError):
+            sys.exit(0)
+
+        tool_input = input_data.get("tool_input", {})
+        file_path = tool_input.get("file_path", "") or tool_input.get("path", "")
+
+        if not file_path:
+            sys.exit(0)
+
+        # Check managed pennyfarthing files protection
+        # EXCEPTION: If we ARE in the pennyfarthing library itself, allow edits
+        project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+        is_pennyfarthing_lib = Path(project_dir, "pennyfarthing-dist").is_dir()
+
+        if ".claude/pennyfarthing/" in file_path and not is_pennyfarthing_lib:
+            print("BLOCKED: Cannot edit managed pennyfarthing files.", file=sys.stderr)
+            print(f"File: {file_path}", file=sys.stderr)
+            print("", file=sys.stderr)
+            print("These files are managed by pennyfarthing and will be overwritten on update.", file=sys.stderr)
+            print("Instead:", file=sys.stderr)
+            print("  - Put project-specific customizations in .claude/project/", file=sys.stderr)
+            print("  - For framework changes, edit the pennyfarthing repo and run 'pennyfarthing update'", file=sys.stderr)
+            sys.exit(2)
+
+        # Check protected patterns
+        for pattern in PROTECTED_PATTERNS:
+            if fnmatch.fnmatch(file_path, pattern):
+                print(f"BLOCKED: Cannot edit protected file matching pattern: {pattern}", file=sys.stderr)
+                print(f"File: {file_path}", file=sys.stderr)
+                sys.exit(2)
+
+    except SystemExit:
+        raise
+    except Exception:
+        pass
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()