capt-hook 3.3.2__tar.gz → 3.4.0__tar.gz

capt_hook-3.4.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: capt-hook
+Version: 3.4.0
+Summary: Declarative hook framework for Claude Code
+Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
+Author: Yasyf Mohamedali
+Author-email: Yasyf Mohamedali <yasyfm@gmail.com>
+License-Expression: PolyForm-Noncommercial-1.0.0
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Dist: cc-transcript>=3.2,<4
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: tree-sitter>=0.24
+Requires-Dist: tree-sitter-bash>=0.23
+Requires-Dist: funcy>=2.0
+Requires-Dist: spacy>=3.7
+Requires-Dist: click>=8
+Requires-Dist: rich>=13
+Requires-Dist: orjsonl>=1.0
+Requires-Dist: wn>=1.1.0
+Requires-Dist: lazy-object-proxy>=1.12.0
+Requires-Dist: filelock>=3
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: spawnllm>=0.1.3
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
+Requires-Dist: pyright>=1.1 ; extra == 'dev'
+Requires-Dist: pyyaml>=6 ; extra == 'dev'
+Requires-Dist: ruff>=0.8 ; extra == 'dev'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/yasyf/captain-hook
+Project-URL: Documentation, https://yasyf.github.io/captain-hook/
+Project-URL: Repository, https://github.com/yasyf/captain-hook
+Project-URL: Issues, https://github.com/yasyf/captain-hook/issues
+Project-URL: Changelog, https://github.com/yasyf/captain-hook/blob/main/CHANGELOG.md
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# captain-hook
+
+![captain-hook banner](https://github.com/yasyf/captain-hook/raw/main/docs/assets/readme-banner.webp)
+
+[![PyPI](https://img.shields.io/pypi/v/capt-hook.svg)](https://pypi.org/project/capt-hook/)
+[![Python](https://img.shields.io/pypi/pyversions/capt-hook.svg)](https://pypi.org/project/capt-hook/)
+[![Docs](https://github.com/yasyf/captain-hook/actions/workflows/docs.yml/badge.svg)](https://yasyf.github.io/captain-hook/)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm_Noncommercial_1.0.0-blue.svg)](https://github.com/yasyf/captain-hook/blob/main/LICENSE)
+
+Guardrails for Claude Code, written as typed, testable data — and learned from the corrections you give Claude.
+
+A captain-hook hook is declarative Python: an event, some conditions, an action. Block a footgun before it runs, nudge the agent off a bad pattern, gate "done" until the tests pass. Then captain-hook closes the loop: it reads the corrections you give Claude as you work and opens pull requests that codify the durable ones as new hooks. You write the first few; it writes the rest.
+
+## Install
+
+captain-hook needs no install — it runs through [uvx](https://docs.astral.sh/uv/). From your project root:
+
+```bash
+uvx capt-hook init
+```
+
+`init` scaffolds `.claude/hooks/`, wires Claude Code's settings, installs the bundled skills, and arms the [session reviewer](#it-learns-from-your-corrections). Or install the plugin and let Claude do it. Run `/plugin marketplace add yasyf/captain-hook`, then ask Claude to "set up captain hook".
+
+## Your first hook
+
+A hook is an event, some conditions, and an action. This one stops the agent from finishing a UI change it never looked at:
+
+```python
+# .claude/hooks/visual_review.py
+from captain_hook import gate, TouchedFile, UsedSkill
+
+gate(
+    "You edited UI files. Open them with agent-browser and verify they render before finishing.",
+    only_if=[TouchedFile("**/src/routes/**", "**/src/components/**")],
+    skip_if=[UsedSkill("agent-browser")],
+)
+```
+
+`only_if` arms the gate only when UI files changed; `skip_if` stands it down once the agent has done the review. Conditions match tools, files, commands, and even which skills the agent used.
+
+## It learns from your corrections
+
+Most hooks you'll never write by hand.
+
+The corrections you give Claude as you work are exactly the rules a hook should enforce: "never force-push", "use `uv`, not `pip`", "you weakened that test". Writing the hook by hand is friction you skip in the moment, so the **session reviewer** notices for you. When a session ends, it reads the transcript, finds the durable corrections and the hooks that misfired, judges which ones are standing rules and which are one-offs, and once a pattern proves itself across sessions, opens a pull request that adds the hook — or fixes the one that misfired. You review the PR like any other.
+
+It's on by default after `init`. Turn it off for a repo with `uvx capt-hook review disable`. The [session reviewer guide](https://yasyf.github.io/captain-hook/docs/guide/session-reviewer.html) covers the prerequisites (an authenticated `claude` and `gh`) and the `HOOKS_REVIEW_*` thresholds.
+
+## Tested like code
+
+Every deterministic hook carries inline tests, so a broken hook fails like broken code:
+
+```python
+# .claude/hooks/safety.py
+from captain_hook import Allow, Block, Input, block_command
+
+block_command(
+    ["git", "stash"],
+    reason="Use the team's VCS workflow for shelving changes",
+    hint="Commit a WIP change instead of stashing",
+    tests={
+        Input(command="git stash"): Block(),
+        Input(command="git status"): Allow(),
+    },
+)
+```
+
+Run them from your project root, where `--hooks` defaults to `.claude/hooks`:
+
+```bash
+uvx capt-hook test
+```
+
+Wire that into CI and you catch a broken hook the way you catch broken code.
+
+## What it's for
+
+- Block footguns before they run on `PreToolUse`: force-push, `rm -rf`, package-manager traps.
+- Steer the agent with feedback that fires on the patterns it actually emits: repeated failures, weakened tests, missed conventions.
+- Hold the line on multi-step work with Stop gates and artifact checks, so the agent can't call it "done" before the tests run or the report's written.
+- Keep all of it testable; every hook ships with inline tests that run in CI.
+
+## Docs
+
+[Read the docs](https://yasyf.github.io/captain-hook/) for the full guide to conditions, primitives, LLM hooks, workflows, state, and real-world patterns. To work on captain-hook itself, see the [development guide](https://yasyf.github.io/captain-hook/docs/development/).
+
+## License
+
+Licensed under [PolyForm Noncommercial 1.0.0](LICENSE), free for noncommercial use.

capt_hook-3.4.0/README.md

@@ -0,0 +1,89 @@
+# captain-hook
+
+![captain-hook banner](https://github.com/yasyf/captain-hook/raw/main/docs/assets/readme-banner.webp)
+
+[![PyPI](https://img.shields.io/pypi/v/capt-hook.svg)](https://pypi.org/project/capt-hook/)
+[![Python](https://img.shields.io/pypi/pyversions/capt-hook.svg)](https://pypi.org/project/capt-hook/)
+[![Docs](https://github.com/yasyf/captain-hook/actions/workflows/docs.yml/badge.svg)](https://yasyf.github.io/captain-hook/)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm_Noncommercial_1.0.0-blue.svg)](https://github.com/yasyf/captain-hook/blob/main/LICENSE)
+
+Guardrails for Claude Code, written as typed, testable data — and learned from the corrections you give Claude.
+
+A captain-hook hook is declarative Python: an event, some conditions, an action. Block a footgun before it runs, nudge the agent off a bad pattern, gate "done" until the tests pass. Then captain-hook closes the loop: it reads the corrections you give Claude as you work and opens pull requests that codify the durable ones as new hooks. You write the first few; it writes the rest.
+
+## Install
+
+captain-hook needs no install — it runs through [uvx](https://docs.astral.sh/uv/). From your project root:
+
+```bash
+uvx capt-hook init
+```
+
+`init` scaffolds `.claude/hooks/`, wires Claude Code's settings, installs the bundled skills, and arms the [session reviewer](#it-learns-from-your-corrections). Or install the plugin and let Claude do it. Run `/plugin marketplace add yasyf/captain-hook`, then ask Claude to "set up captain hook".
+
+## Your first hook
+
+A hook is an event, some conditions, and an action. This one stops the agent from finishing a UI change it never looked at:
+
+```python
+# .claude/hooks/visual_review.py
+from captain_hook import gate, TouchedFile, UsedSkill
+
+gate(
+    "You edited UI files. Open them with agent-browser and verify they render before finishing.",
+    only_if=[TouchedFile("**/src/routes/**", "**/src/components/**")],
+    skip_if=[UsedSkill("agent-browser")],
+)
+```
+
+`only_if` arms the gate only when UI files changed; `skip_if` stands it down once the agent has done the review. Conditions match tools, files, commands, and even which skills the agent used.
+
+## It learns from your corrections
+
+Most hooks you'll never write by hand.
+
+The corrections you give Claude as you work are exactly the rules a hook should enforce: "never force-push", "use `uv`, not `pip`", "you weakened that test". Writing the hook by hand is friction you skip in the moment, so the **session reviewer** notices for you. When a session ends, it reads the transcript, finds the durable corrections and the hooks that misfired, judges which ones are standing rules and which are one-offs, and once a pattern proves itself across sessions, opens a pull request that adds the hook — or fixes the one that misfired. You review the PR like any other.
+
+It's on by default after `init`. Turn it off for a repo with `uvx capt-hook review disable`. The [session reviewer guide](https://yasyf.github.io/captain-hook/docs/guide/session-reviewer.html) covers the prerequisites (an authenticated `claude` and `gh`) and the `HOOKS_REVIEW_*` thresholds.
+
+## Tested like code
+
+Every deterministic hook carries inline tests, so a broken hook fails like broken code:
+
+```python
+# .claude/hooks/safety.py
+from captain_hook import Allow, Block, Input, block_command
+
+block_command(
+    ["git", "stash"],
+    reason="Use the team's VCS workflow for shelving changes",
+    hint="Commit a WIP change instead of stashing",
+    tests={
+        Input(command="git stash"): Block(),
+        Input(command="git status"): Allow(),
+    },
+)
+```
+
+Run them from your project root, where `--hooks` defaults to `.claude/hooks`:
+
+```bash
+uvx capt-hook test
+```
+
+Wire that into CI and you catch a broken hook the way you catch broken code.
+
+## What it's for
+
+- Block footguns before they run on `PreToolUse`: force-push, `rm -rf`, package-manager traps.
+- Steer the agent with feedback that fires on the patterns it actually emits: repeated failures, weakened tests, missed conventions.
+- Hold the line on multi-step work with Stop gates and artifact checks, so the agent can't call it "done" before the tests run or the report's written.
+- Keep all of it testable; every hook ships with inline tests that run in CI.
+
+## Docs
+
+[Read the docs](https://yasyf.github.io/captain-hook/) for the full guide to conditions, primitives, LLM hooks, workflows, state, and real-world patterns. To work on captain-hook itself, see the [development guide](https://yasyf.github.io/captain-hook/docs/development/).
+
+## License
+
+Licensed under [PolyForm Noncommercial 1.0.0](LICENSE), free for noncommercial use.

{capt_hook-3.3.2 → capt_hook-3.4.0}/captain_hook/cli.py

@@ -527,6 +527,18 @@ def logs(session: str | None, tail: int | None) -> None:
     show_logs(session=session, tail=tail)
 
 
+@cli.command()
+@click.option("--repo", "repo_", default=None, help="Repo key (default: the current repo)")
+@click.option("--sync/--no-sync", default=True, help="Refresh open PR states from GitHub in the background")
+@click.pass_obj
+def status(state: CliState, repo_: str | None, sync: bool) -> None:
+    """Show the corrections the session reviewer is tracking and the hook PRs they would open."""
+    from captain_hook.review.cli import resolve_repo
+    from captain_hook.review.dashboard import status_command
+
+    status_command(resolve_repo(repo_, state.root), sync=sync)
+
+
 @cli.group()
 def skills() -> None:
     """Manage the bundled Claude Code skills."""

{capt_hook-3.3.2 → capt_hook-3.4.0}/captain_hook/review/cli.py

@@ -198,6 +198,17 @@ def triage(limit: int | None) -> None:
     click.echo(f"judged {report.judged}, failed {report.failed}, pending {report.pending}")
 
 
+@review.command(name="status")
+@click.option("--repo", "repo_", default=None, help="Repo key (default: the current repo)")
+@click.option("--sync/--no-sync", default=True, help="Refresh open PR states from GitHub in the background")
+@click.pass_obj
+def status(state: CliState, repo_: str | None, sync: bool) -> None:
+    """Show the tracked corrections, their progress toward a PR, and open PR status."""
+    from captain_hook.review.dashboard import status_command
+
+    status_command(resolve_repo(repo_, state.root), sync=sync)
+
+
 @review.command(name="list")
 @click.option("--repo", "repo_", default=None, help="Repo key (default: the current repo)")
 @click.pass_obj

capt_hook-3.4.0/captain_hook/review/dashboard.py

@@ -0,0 +1,208 @@
+"""The ``capt-hook status`` dashboard: the corrections lifecycle, rendered.
+
+Reads the reviewer's :class:`~captain_hook.review.store.ReviewStore` and renders
+every candidate the reviewer tracks, bucketed by lifecycle stage — watching
+(building toward the bar), eligible (a PR opens next session), PR open, and the
+merged/closed/stale outcomes. Each row shows kind-aware progress toward its PR
+thresholds and the one-sentence summary of what its PR would do. Open PRs are
+shown from the last-synced state first, then refreshed against GitHub in the
+background so the view appears instantly and updates when ``gh`` returns.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from rich.console import Console, Group
+from rich.spinner import Spinner
+from rich.text import Text
+
+from captain_hook.review.store import CandidateKind, CandidateStatus
+
+if TYPE_CHECKING:
+    from rich.console import RenderableType
+
+    from captain_hook.review.repo import RepoKey
+    from captain_hook.review.settings import ReviewSettings
+    from captain_hook.review.store import CandidateView
+
+BAR_FILLED = "█"
+BAR_EMPTY = "░"
+DETAIL_WIDTH = 80
+KIND_STYLE = {CandidateKind.CREATE: "cyan", CandidateKind.FIX: "magenta"}
+
+
+class Stage(StrEnum):
+    """A candidate's dashboard bucket — its lifecycle status, with watching split by eligibility."""
+
+    WATCHING = "watching"
+    ELIGIBLE = "eligible"
+    PR_OPEN = "pr_open"
+    ACCEPTED = "accepted"
+    REJECTED = "rejected"
+    STALE = "stale"
+
+
+SECTIONS: tuple[tuple[Stage, str, str, str], ...] = (
+    (Stage.WATCHING, "WATCHING", "building toward the bar", "yellow"),
+    (Stage.ELIGIBLE, "ELIGIBLE", "a PR opens next session", "green"),
+    (Stage.PR_OPEN, "PR OPEN", "pull request awaiting your review", "blue"),
+    (Stage.ACCEPTED, "ACCEPTED", "PR merged", "green"),
+    (Stage.REJECTED, "REJECTED", "PR closed", "red"),
+    (Stage.STALE, "STALE", "PR open too long", "bright_black"),
+)
+
+
+def stage_of(view: CandidateView) -> Stage:
+    """Buckets a candidate: its status, with ``watching`` split into eligible vs not."""
+    match CandidateStatus(str(view.row["status"])):
+        case CandidateStatus.PR_OPEN:
+            return Stage.PR_OPEN
+        case CandidateStatus.ACCEPTED:
+            return Stage.ACCEPTED
+        case CandidateStatus.REJECTED:
+            return Stage.REJECTED
+        case CandidateStatus.STALE:
+            return Stage.STALE
+        case CandidateStatus.WATCHING:
+            return Stage.ELIGIBLE if view.eligible else Stage.WATCHING
+
+
+def trim(text: str, *, width: int = DETAIL_WIDTH) -> str:
+    return flat if len(flat := " ".join(text.split())) <= width else flat[: width - 1] + "…"
+
+
+def bar(done: int, need: int, *, width: int = 5) -> str:
+    cells = min(need, width)
+    filled = min(cells, round(done / need * cells)) if need else cells
+    return BAR_FILLED * filled + BAR_EMPTY * (cells - filled)
+
+
+def targets(view: CandidateView, settings: ReviewSettings) -> tuple[tuple[str, int, int], ...]:
+    t = view.threshold
+    match t.kind:
+        case CandidateKind.CREATE:
+            return (("sessions", t.sessions, settings.min_sessions), ("days", t.days, settings.min_days))
+        case CandidateKind.FIX:
+            return (("sessions", t.sessions, settings.min_sessions_fix), ("days", t.days, settings.min_days_fix))
+
+
+def progress_text(view: CandidateView, settings: ReviewSettings) -> str:
+    return "   ".join(
+        f"{label} {bar(done, need)} {done}/{need}" for label, done, need in targets(view, settings) if need > 0
+    )
+
+
+def pr_description(view: CandidateView) -> str:
+    """The one-line summary of what this candidate's PR would (or did) do."""
+    row = view.row
+    detail = trim(view.summary or str(row["sample_text"] or ""))
+    match CandidateKind(str(row["candidate_kind"])):
+        case CandidateKind.CREATE:
+            return f'would add a hook: "{detail}"' if detail else "would add a hook for this correction"
+        case CandidateKind.FIX:
+            tail = view.summary or (
+                f"regression test for {row['misfire_class']}" if row["misfire_class"] else "regression test for the misfire"
+            )
+            return f"would fix {row['target_hook_name']} ({row['target_source_file']}): {trim(str(tail))}"
+
+
+def age_days(row: dict[str, object]) -> int | None:
+    if not (opened := row["pr_opened_at"]):
+        return None
+    return (datetime.now(UTC) - datetime.fromisoformat(str(opened))).days
+
+
+def pr_link(view: CandidateView) -> str:
+    url = str(view.row["pr_url"] or "(no url)")
+    return f"{url}   ·   {days}d open" if stage_of(view) is Stage.PR_OPEN and (days := age_days(view.row)) is not None else url
+
+
+def lead_detail(view: CandidateView, settings: ReviewSettings) -> str:
+    match stage_of(view):
+        case Stage.WATCHING:
+            return progress_text(view, settings)
+        case Stage.ELIGIBLE:
+            return f"ready  ·  {progress_text(view, settings)}"
+        case _:
+            return pr_link(view)
+
+
+def candidate_block(view: CandidateView, settings: ReviewSettings) -> RenderableType:
+    kind = CandidateKind(str(view.row["candidate_kind"]))
+    return Group(
+        Text.assemble(
+            (f"  #{view.row['id']}", "bold"),
+            "  ",
+            (kind.value.ljust(6), KIND_STYLE[kind]),
+            "  ",
+            lead_detail(view, settings),
+        ),
+        Text(f"      {pr_description(view)}", style="dim"),
+    )
+
+
+def header(repo: RepoKey, views: list[CandidateView], settings: ReviewSettings, *, watching: bool) -> RenderableType:
+    open_n = sum(1 for v in views if stage_of(v) is Stage.PR_OPEN)
+    line = Text.assemble(
+        ("captain-hook", "bold"),
+        ("  ·  ", "dim"),
+        (str(repo), "cyan"),
+        "    ",
+        (f"[{'watching' if watching else 'not watching'}]", "green" if watching else "yellow"),
+        "    ",
+        (f"PR slots {open_n}/{settings.max_open_prs}", "dim"),
+    )
+    if watching:
+        return line
+    return Group(line, Text("  run `capt-hook review enable` to start tracking this repo.", style="dim"))
+
+
+def render(
+    views: list[CandidateView], *, repo: RepoKey, settings: ReviewSettings, watching: bool, syncing: bool = False
+) -> RenderableType:
+    """The whole dashboard frame: header, then a section per non-empty lifecycle stage."""
+    sections = [
+        block
+        for stage, title, desc, style in SECTIONS
+        if (members := [v for v in views if stage_of(v) is stage])
+        for block in (
+            Text.assemble((title, f"bold {style}"), (f"   {desc}", "dim")),
+            *(candidate_block(v, settings) for v in members),
+            Text(""),
+        )
+    ]
+    empty = [] if views else [Text("No corrections tracked yet — they appear here as you correct Claude.", style="dim")]
+    spinner = [Spinner("dots", text=Text("syncing open PRs with GitHub…", style="dim"))] if syncing else []
+    return Group(header(repo, views, settings, watching=watching), Text(""), *sections, *empty, *spinner)
+
+
+async def run_status(repo: RepoKey, *, sync: bool) -> None:
+    """Renders the dashboard for ``repo``, refreshing open-PR state in the background when ``sync``."""
+    from rich.live import Live
+
+    from captain_hook.review.judge import REVIEW_PROMPT_VERSION
+    from captain_hook.review.settings import ReviewSettings
+    from captain_hook.review.store import ReviewStore
+    from captain_hook.review.sync import sync_open_prs
+
+    settings = ReviewSettings()
+    console = Console()
+    async with await ReviewStore.open(settings.db_path) as store:
+        watching = await store.watching(repo)
+        views = await store.overview(repo, settings=settings, prompt_version=REVIEW_PROMPT_VERSION)
+        if not (sync and any(stage_of(v) is Stage.PR_OPEN for v in views)):
+            console.print(render(views, repo=repo, settings=settings, watching=watching))
+            return
+        with Live(render(views, repo=repo, settings=settings, watching=watching, syncing=True), console=console) as live:
+            await sync_open_prs(store, repo, settings=settings)
+            fresh = await store.overview(repo, settings=settings, prompt_version=REVIEW_PROMPT_VERSION)
+            live.update(render(fresh, repo=repo, settings=settings, watching=watching))
+
+
+def status_command(repo: RepoKey, *, sync: bool) -> None:
+    """The synchronous CLI boundary for ``review status`` / ``capt-hook status``."""
+    asyncio.run(run_status(repo, sync=sync))

{capt_hook-3.3.2 → capt_hook-3.4.0}/captain_hook/review/store.py

@@ -113,6 +113,22 @@ SELECT c.*,
 FROM candidates c
 """
 
+PR_SUMMARY_QUERY = """
+WITH latest AS (
+  SELECT v.dedup_key, v.{accepted} AS accepted, v.{summary} AS summary, v.confidence, ROW_NUMBER() OVER (
+    PARTITION BY v.dedup_key ORDER BY v.judged_at DESC, v.id DESC
+  ) AS rn
+  FROM {table} v
+  WHERE v.role = 'judge' AND v.prompt_version = ?
+)
+SELECT l.summary AS summary
+FROM candidate_observations o
+JOIN latest l ON l.dedup_key = o.dedup_key AND l.rn = 1
+WHERE o.candidate_id = ? AND l.accepted = 1 AND l.confidence >= ?
+ORDER BY l.confidence DESC, o.id DESC
+LIMIT 1
+"""
+
 
 class InvalidTransition(Exception):
     """Raised when a candidate status move is outside :data:`TRANSITIONS`."""
@@ -175,6 +191,47 @@ class ThresholdStatus:
     single_observation: bool
 
 
+def crosses_thresholds(status: ThresholdStatus, *, settings: ReviewSettings) -> bool:
+    """Whether a candidate's judge-accepted evidence clears its kind's PR thresholds.
+
+    The single eligibility predicate, shared by :meth:`ReviewStore.eligible` and
+    the status dashboard so a candidate shown as eligible is exactly one the
+    reviewer would act on. Create candidates need ``min_sessions`` distinct
+    judge-accepted sessions across ``min_days`` distinct UTC days; fix candidates
+    need the ``min_sessions_fix``/``min_days_fix`` pair or one observation that is
+    both judge-accepted and heuristically at least ``min_confidence_fix_single``.
+    Both require the repo watched and a free slot under ``max_open_prs``.
+    """
+    if status.status != CandidateStatus.WATCHING or not status.watching or status.open_prs >= settings.max_open_prs:
+        return False
+    match status.kind:
+        case CandidateKind.CREATE:
+            return status.sessions >= settings.min_sessions and status.days >= settings.min_days
+        case CandidateKind.FIX:
+            return (
+                status.sessions >= settings.min_sessions_fix and status.days >= settings.min_days_fix
+            ) or status.single_observation
+
+
+@dataclass(frozen=True, slots=True)
+class CandidateView:
+    """One candidate's full dashboard record: its row, evidence counts, eligibility, and the PR it would open.
+
+    Attributes:
+        row: The :meth:`ReviewStore.candidates` row (status, kind, ``pr_url``,
+            ``sample_text``, ``observations``, and the fix targets).
+        threshold: The judge-accepted evidence counts behind the eligibility call.
+        eligible: Whether :func:`crosses_thresholds` accepts ``threshold``.
+        summary: The highest-confidence accepted verdict's one-sentence summary —
+            what the candidate's PR would do — or ``None`` while still unjudged.
+    """
+
+    row: dict[str, object]
+    threshold: ThresholdStatus
+    eligible: bool
+    summary: str | None
+
+
 class ReviewStore(VerdictStoreMixin, FeedbackStore):
     """The session reviewer's persistent store over a :class:`FileStateStore`.
 
@@ -411,25 +468,64 @@ class ReviewStore(VerdictStoreMixin, FeedbackStore):
     async def eligible(self, candidate_id: int, *, settings: ReviewSettings, prompt_version: int) -> bool:
         """Returns whether a candidate's judge-accepted evidence crosses its thresholds.
 
-        Create candidates need ``min_sessions`` distinct judge-accepted sessions
-        across ``min_days`` distinct UTC days. Fix candidates need the
-        ``min_sessions_fix``/``min_days_fix`` pair, or one observation that is
-        both judge-accepted and heuristically at least
-        ``min_confidence_fix_single``. Both kinds require the repo watched and a
-        free slot under ``max_open_prs``.
+        Delegates to :func:`crosses_thresholds` over the candidate's
+        :meth:`threshold_status`, so the dashboard and the reviewer agree on what
+        is eligible.
 
         Args:
             candidate_id: The candidate to check.
             settings: The thresholds and judge knobs to check under.
             prompt_version: The judge prompt version whose verdicts apply.
         """
-        status = await self.threshold_status(candidate_id, settings=settings, prompt_version=prompt_version)
-        if status.status != CandidateStatus.WATCHING or not status.watching or status.open_prs >= settings.max_open_prs:
-            return False
-        match status.kind:
-            case CandidateKind.CREATE:
-                return status.sessions >= settings.min_sessions and status.days >= settings.min_days
-            case CandidateKind.FIX:
-                return (
-                    status.sessions >= settings.min_sessions_fix and status.days >= settings.min_days_fix
-                ) or status.single_observation
+        return crosses_thresholds(
+            await self.threshold_status(candidate_id, settings=settings, prompt_version=prompt_version),
+            settings=settings,
+        )
+
+    async def pr_summary(self, candidate_id: int, *, settings: ReviewSettings, prompt_version: int) -> str | None:
+        """Returns the candidate's most-confident accepted verdict summary — what its PR would do.
+
+        Reads the same judge-accepted observations the thresholds count and
+        returns the highest-confidence verdict's one-sentence summary, or ``None``
+        while no observation is judged-accepted yet.
+
+        Args:
+            candidate_id: The candidate to describe.
+            settings: The judge knobs supplying ``min_judge_confidence``.
+            prompt_version: The judge prompt version whose verdicts apply.
+        """
+        cur = await self.store.conn.execute(
+            PR_SUMMARY_QUERY.format(
+                table=self.VERDICT_TABLE, accepted=self.ACCEPTED_COLUMN, summary=self.SUMMARY_COLUMN
+            ),
+            (prompt_version, candidate_id, settings.min_judge_confidence),
+        )
+        return str(rows[0]["summary"]) if (rows := [dict(row) async for row in cur]) else None
+
+    async def candidate_view(
+        self, row: dict[str, object], *, settings: ReviewSettings, prompt_version: int
+    ) -> CandidateView:
+        """Assembles one :class:`CandidateView` from a :meth:`candidates` row."""
+        candidate_id = int(str(row["id"]))
+        threshold = await self.threshold_status(candidate_id, settings=settings, prompt_version=prompt_version)
+        return CandidateView(
+            row=row,
+            threshold=threshold,
+            eligible=crosses_thresholds(threshold, settings=settings),
+            summary=await self.pr_summary(candidate_id, settings=settings, prompt_version=prompt_version),
+        )
+
+    async def overview(
+        self, repo: RepoKey | None = None, *, settings: ReviewSettings, prompt_version: int
+    ) -> list[CandidateView]:
+        """Returns a :class:`CandidateView` per candidate — the status dashboard's whole read.
+
+        Args:
+            repo: When set, restrict to this repo.
+            settings: The thresholds and judge knobs to evaluate under.
+            prompt_version: The judge prompt version whose verdicts apply.
+        """
+        return [
+            await self.candidate_view(row, settings=settings, prompt_version=prompt_version)
+            for row in await self.candidates(repo)
+        ]

{capt_hook-3.3.2 → capt_hook-3.4.0}/captain_hook/review/sync.py

@@ -8,6 +8,7 @@ skipped so the detached child never dies on it.
 
 from __future__ import annotations
 
+import asyncio
 import json
 import subprocess
 from collections import Counter
@@ -75,9 +76,11 @@ async def sync_open_prs(store: ReviewStore, repo: RepoKey, *, settings: ReviewSe
         The pass's transition counts.
     """
     counts: Counter[str] = Counter()
-    for row in await store.candidates(repo, status=CandidateStatus.PR_OPEN):
+    rows = await store.candidates(repo, status=CandidateStatus.PR_OPEN)
+    states = await asyncio.gather(*(asyncio.to_thread(gh_pr_state, str(row["pr_url"])) for row in rows))
+    for row, state in zip(rows, states, strict=True):
         candidate_id, url = int(str(row["id"])), str(row["pr_url"])
-        match gh_pr_state(url):
+        match state:
             case "MERGED":
                 await store.transition(candidate_id, CandidateStatus.ACCEPTED)
                 counts["accepted"] += 1

{capt_hook-3.3.2 → capt_hook-3.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "capt-hook"
-version = "3.3.2"
+version = "3.4.0"
 description = "Declarative hook framework for Claude Code"
 readme = "README.md"
 license = "PolyForm-Noncommercial-1.0.0"
@@ -28,6 +28,7 @@ dependencies = [
     "funcy>=2.0",
     "spacy>=3.7",
     "click>=8",
+    "rich>=13",
     "orjsonl>=1.0",
     "wn>=1.1.0",
     "lazy-object-proxy>=1.12.0",

capt_hook-3.3.2/PKG-INFO

@@ -1,152 +0,0 @@
-Metadata-Version: 2.4
-Name: capt-hook
-Version: 3.3.2
-Summary: Declarative hook framework for Claude Code
-Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
-Author: Yasyf Mohamedali
-Author-email: Yasyf Mohamedali <yasyfm@gmail.com>
-License-Expression: PolyForm-Noncommercial-1.0.0
-License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Topic :: Software Development :: Quality Assurance
-Classifier: Topic :: Software Development :: Testing
-Classifier: Typing :: Typed
-Requires-Dist: cc-transcript>=3.2,<4
-Requires-Dist: pydantic>=2.0
-Requires-Dist: pydantic-settings>=2.0
-Requires-Dist: tree-sitter>=0.24
-Requires-Dist: tree-sitter-bash>=0.23
-Requires-Dist: funcy>=2.0
-Requires-Dist: spacy>=3.7
-Requires-Dist: click>=8
-Requires-Dist: orjsonl>=1.0
-Requires-Dist: wn>=1.1.0
-Requires-Dist: lazy-object-proxy>=1.12.0
-Requires-Dist: filelock>=3
-Requires-Dist: loguru>=0.7.3
-Requires-Dist: spawnllm>=0.1.3
-Requires-Dist: pytest>=8.0 ; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
-Requires-Dist: pyright>=1.1 ; extra == 'dev'
-Requires-Dist: pyyaml>=6 ; extra == 'dev'
-Requires-Dist: ruff>=0.8 ; extra == 'dev'
-Requires-Python: >=3.13
-Project-URL: Homepage, https://github.com/yasyf/captain-hook
-Project-URL: Documentation, https://yasyf.github.io/captain-hook/
-Project-URL: Repository, https://github.com/yasyf/captain-hook
-Project-URL: Issues, https://github.com/yasyf/captain-hook/issues
-Project-URL: Changelog, https://github.com/yasyf/captain-hook/blob/main/CHANGELOG.md
-Provides-Extra: dev
-Description-Content-Type: text/markdown
-
-# captain-hook
-
-![captain-hook banner](https://github.com/yasyf/captain-hook/raw/main/docs/assets/readme-banner.webp)
-
-[![PyPI](https://img.shields.io/pypi/v/capt-hook.svg)](https://pypi.org/project/capt-hook/)
-[![Python](https://img.shields.io/pypi/pyversions/capt-hook.svg)](https://pypi.org/project/capt-hook/)
-[![Docs](https://github.com/yasyf/captain-hook/actions/workflows/docs.yml/badge.svg)](https://yasyf.github.io/captain-hook/)
-[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm_Noncommercial_1.0.0-blue.svg)](https://github.com/yasyf/captain-hook/blob/main/LICENSE)
-
-Declarative hook framework for Claude Code. Write hooks as data, test them inline, and ship them to CI in the same shape they run in production.
-
-## Quickstart
-
-No install step — everything runs through [uvx](https://docs.astral.sh/uv/). Pick a front door:
-
-**From your terminal:**
-
-```bash
-uvx capt-hook init
-```
-
-**From inside Claude Code** — install the plugin, then ask Claude to set it up:
-
-```
-/plugin marketplace add yasyf/captain-hook
-/plugin install captain-hook@captain-hook
-```
-
-> set up captain hook
-
-Either path lands in the same place: `.claude/hooks/` scaffolded, Claude Code's settings wired, the bundled skills installed, and the [session reviewer](#session-reviewer) watching this repo. `uvx` fetches captain-hook into a throwaway environment, so it never enters your `pyproject.toml` — and every command below works the same way once you prefix it with `uvx`.
-
-## Your first hook
-
-A hook is declarative Python with an event, some conditions, and an action. This one stops the agent from finishing a UI change it never looked at.
-
-```python
-# .claude/hooks/visual_review.py
-from captain_hook import gate, TouchedFile, UsedSkill
-
-# A Stop gate: before the agent finishes, block if it edited UI files without doing a visual review.
-gate(
-    # the one-line reason shown to the agent when the gate fires
-    "You edited UI files. Open them with agent-browser and verify they render before finishing.",
-    # fires only if UI files changed
-    only_if=[TouchedFile("**/src/routes/**", "**/src/components/**")],
-    # already reviewed -> don't block
-    skip_if=[UsedSkill("agent-browser")],
-)
-```
-
-Conditions match tools, files, commands, and even which skills the agent used.
-
-## Test your hooks
-
-Every deterministic hook carries inline tests, so a broken hook fails like broken code. Run them from your project root, where `--hooks` defaults to `.claude/hooks`.
-
-```python
-# .claude/hooks/safety.py
-from captain_hook import Allow, Block, Input, block_command
-
-block_command(
-    ["git", "stash"],
-    reason="Use the team's VCS workflow for shelving changes",
-    hint="Commit a WIP change instead of stashing",
-    tests={
-        Input(command="git stash"): Block(),
-        Input(command="git status"): Allow(),
-    },
-)
-```
-
-```bash
-uvx capt-hook test
-```
-
-`init` already wired Claude Code's settings. Each event runs `uvx capt-hook run <Event>`, with the event JSON arriving on stdin and the verdict written to stdout. Re-run `uvx capt-hook register-hooks` only after you add hooks on a new event; it writes `.claude/settings.local.json` for you.
-
-## Session reviewer
-
-`init` also turns on the **session reviewer**. When a Claude Code session ends, it mines the transcript for the durable corrections you gave and the hooks that misfired, judges each one, and — once a pattern clears its thresholds — opens a pull request that adds a new hook or fixes the one that misfired. You review the PR like any other.
-
-It's on by default after `init`. Turn it off for a repo with `uvx capt-hook review disable`, or skip it at setup with `uvx capt-hook init --no-review`. The [session reviewer guide](https://yasyf.github.io/captain-hook/docs/guide/session-reviewer.html) covers prerequisites (an authenticated `claude` and `gh`) and the `HOOKS_REVIEW_*` tuning knobs.
-
-## Agent Skills
-
-captain-hook ships two [Agent Skills](https://yasyf.github.io/captain-hook/docs/getting-started/skills.html) so you don't have to write hooks by hand. `bootstrapping-hooks` surveys your repo's docs, CI, and git history and proposes gates and nudges; `translating-styleguides` turns a STYLEGUIDE.md into enforced rules. Both land in `.claude/skills/` via `init` and ship as the plugin in the [Quickstart](#quickstart) — ask Claude to "set up captain hook" and `bootstrapping-hooks` takes it from there.
-
-## What this solves
-
-captain-hook covers these jobs:
-
-- Block dangerous tool calls before they execute on `PreToolUse`, like force-push, package-manager footguns, and raw `rm -rf`.
-- Drive the agent with feedback that fires on the patterns it actually emits, such as repeated failures, weakened tests, and missed conventions.
-- Enforce multi-step workflows with Stop gates and artifact validation, so the agent can't declare "done" without running tests, writing a report, or completing a checklist.
-- Keep all of the above testable. Every hook ships with inline `tests = {...}` that `uvx capt-hook test` runs in CI, so you catch broken hooks the way you catch broken code.
-
-## Docs
-
-[Read the docs](https://yasyf.github.io/captain-hook/) for the full guide to conditions, primitives, LLM hooks, workflows, state, and real-world patterns.
-
-For working on captain-hook itself, see the [development guide](https://yasyf.github.io/captain-hook/docs/development/).
-
-## License
-
-Licensed under [PolyForm Noncommercial 1.0.0](LICENSE), free for noncommercial use.

capt_hook-3.3.2/README.md

@@ -1,106 +0,0 @@
-# captain-hook
-
-![captain-hook banner](https://github.com/yasyf/captain-hook/raw/main/docs/assets/readme-banner.webp)
-
-[![PyPI](https://img.shields.io/pypi/v/capt-hook.svg)](https://pypi.org/project/capt-hook/)
-[![Python](https://img.shields.io/pypi/pyversions/capt-hook.svg)](https://pypi.org/project/capt-hook/)
-[![Docs](https://github.com/yasyf/captain-hook/actions/workflows/docs.yml/badge.svg)](https://yasyf.github.io/captain-hook/)
-[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm_Noncommercial_1.0.0-blue.svg)](https://github.com/yasyf/captain-hook/blob/main/LICENSE)
-
-Declarative hook framework for Claude Code. Write hooks as data, test them inline, and ship them to CI in the same shape they run in production.
-
-## Quickstart
-
-No install step — everything runs through [uvx](https://docs.astral.sh/uv/). Pick a front door:
-
-**From your terminal:**
-
-```bash
-uvx capt-hook init
-```
-
-**From inside Claude Code** — install the plugin, then ask Claude to set it up:
-
-```
-/plugin marketplace add yasyf/captain-hook
-/plugin install captain-hook@captain-hook
-```
-
-> set up captain hook
-
-Either path lands in the same place: `.claude/hooks/` scaffolded, Claude Code's settings wired, the bundled skills installed, and the [session reviewer](#session-reviewer) watching this repo. `uvx` fetches captain-hook into a throwaway environment, so it never enters your `pyproject.toml` — and every command below works the same way once you prefix it with `uvx`.
-
-## Your first hook
-
-A hook is declarative Python with an event, some conditions, and an action. This one stops the agent from finishing a UI change it never looked at.
-
-```python
-# .claude/hooks/visual_review.py
-from captain_hook import gate, TouchedFile, UsedSkill
-
-# A Stop gate: before the agent finishes, block if it edited UI files without doing a visual review.
-gate(
-    # the one-line reason shown to the agent when the gate fires
-    "You edited UI files. Open them with agent-browser and verify they render before finishing.",
-    # fires only if UI files changed
-    only_if=[TouchedFile("**/src/routes/**", "**/src/components/**")],
-    # already reviewed -> don't block
-    skip_if=[UsedSkill("agent-browser")],
-)
-```
-
-Conditions match tools, files, commands, and even which skills the agent used.
-
-## Test your hooks
-
-Every deterministic hook carries inline tests, so a broken hook fails like broken code. Run them from your project root, where `--hooks` defaults to `.claude/hooks`.
-
-```python
-# .claude/hooks/safety.py
-from captain_hook import Allow, Block, Input, block_command
-
-block_command(
-    ["git", "stash"],
-    reason="Use the team's VCS workflow for shelving changes",
-    hint="Commit a WIP change instead of stashing",
-    tests={
-        Input(command="git stash"): Block(),
-        Input(command="git status"): Allow(),
-    },
-)
-```
-
-```bash
-uvx capt-hook test
-```
-
-`init` already wired Claude Code's settings. Each event runs `uvx capt-hook run <Event>`, with the event JSON arriving on stdin and the verdict written to stdout. Re-run `uvx capt-hook register-hooks` only after you add hooks on a new event; it writes `.claude/settings.local.json` for you.
-
-## Session reviewer
-
-`init` also turns on the **session reviewer**. When a Claude Code session ends, it mines the transcript for the durable corrections you gave and the hooks that misfired, judges each one, and — once a pattern clears its thresholds — opens a pull request that adds a new hook or fixes the one that misfired. You review the PR like any other.
-
-It's on by default after `init`. Turn it off for a repo with `uvx capt-hook review disable`, or skip it at setup with `uvx capt-hook init --no-review`. The [session reviewer guide](https://yasyf.github.io/captain-hook/docs/guide/session-reviewer.html) covers prerequisites (an authenticated `claude` and `gh`) and the `HOOKS_REVIEW_*` tuning knobs.
-
-## Agent Skills
-
-captain-hook ships two [Agent Skills](https://yasyf.github.io/captain-hook/docs/getting-started/skills.html) so you don't have to write hooks by hand. `bootstrapping-hooks` surveys your repo's docs, CI, and git history and proposes gates and nudges; `translating-styleguides` turns a STYLEGUIDE.md into enforced rules. Both land in `.claude/skills/` via `init` and ship as the plugin in the [Quickstart](#quickstart) — ask Claude to "set up captain hook" and `bootstrapping-hooks` takes it from there.
-
-## What this solves
-
-captain-hook covers these jobs:
-
-- Block dangerous tool calls before they execute on `PreToolUse`, like force-push, package-manager footguns, and raw `rm -rf`.
-- Drive the agent with feedback that fires on the patterns it actually emits, such as repeated failures, weakened tests, and missed conventions.
-- Enforce multi-step workflows with Stop gates and artifact validation, so the agent can't declare "done" without running tests, writing a report, or completing a checklist.
-- Keep all of the above testable. Every hook ships with inline `tests = {...}` that `uvx capt-hook test` runs in CI, so you catch broken hooks the way you catch broken code.
-
-## Docs
-
-[Read the docs](https://yasyf.github.io/captain-hook/) for the full guide to conditions, primitives, LLM hooks, workflows, state, and real-world patterns.
-
-For working on captain-hook itself, see the [development guide](https://yasyf.github.io/captain-hook/docs/development/).
-
-## License
-
-Licensed under [PolyForm Noncommercial 1.0.0](LICENSE), free for noncommercial use.