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

capt_hook-3.5.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: capt-hook
+Version: 3.5.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, registers the captain-hook plugin so its skills install on workspace-trust, and arms the [session reviewer](#it-learns-from-your-corrections). Or do it all from a session. 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.5.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, registers the captain-hook plugin so its skills install on workspace-trust, and arms the [session reviewer](#it-learns-from-your-corrections). Or do it all from a session. 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.5.0}/captain_hook/cli.py

@@ -54,40 +54,24 @@ def example_hook_source() -> str:
     return (importlib.resources.files("captain_hook") / "templates" / "example_hook.py.tmpl").read_text()
 
 
-def install_skills(root: Path, *, force: bool = False) -> dict[str, str]:
-    """Copy the bundled Claude Code skills into ``root/.claude/skills``.
+def plugin_dir() -> Path:
+    """Filesystem path to the bundled captain-hook plugin root.
 
-    Args:
-        root: Project root receiving the skills.
-        force: Replace existing skill directories wholesale instead of skipping them.
-
-    Returns:
-        Per-skill status of ``"installed"``, ``"replaced"``, or ``"skipped"``.
+    Holds ``.claude-plugin/plugin.json`` and ``skills/``, so ``claude --plugin-dir``
+    can load the skills in-place from the installed wheel without a marketplace clone.
     """
-    dest_root = root / ".claude" / "skills"
-    summary: dict[str, str] = {}
-    with importlib.resources.as_file(importlib.resources.files("captain_hook") / "skills") as src_root:
-        for skill in sorted(p for p in src_root.iterdir() if p.is_dir()):
-            dest = dest_root / skill.name
-            if dest.exists() and not force:
-                summary[skill.name] = "skipped"
-                continue
-            if dest.exists():
-                shutil.rmtree(dest)
-                summary[skill.name] = "replaced"
-            else:
-                summary[skill.name] = "installed"
-            shutil.copytree(skill, dest)
-    return summary
+    return Path(str(importlib.resources.files("captain_hook")))
 
 
 def register_marketplace(root: Path) -> None:
-    """Enable the captain-hook plugin marketplace in ``root/.claude/settings.local.json``.
+    """Enable the captain-hook plugin marketplace in ``root/.claude/settings.json``.
 
     Merges ``extraKnownMarketplaces`` and ``enabledPlugins`` entries into the
-    existing settings so the bundled skills track the repository as a plugin.
+    committed settings so the skills load from the plugin (tracking the repository)
+    instead of being copied into ``.claude/skills``. Claude Code prompts to install
+    the plugin when the project folder is trusted.
     """
-    settings_path = root / ".claude" / "settings.local.json"
+    settings_path = root / ".claude" / "settings.json"
     existing = json.loads(settings_path.read_text()) if settings_path.exists() else {}
     write_settings(
         settings_path,
@@ -104,7 +88,9 @@ def maybe_launch_bootstrap(root: Path) -> bool:
 
     Only fires in an interactive session with the ``claude`` CLI on PATH; CI and
     scripted runs skip the prompt entirely. On acceptance, the captain-hook plugin
-    marketplace is registered in ``.claude/settings.local.json`` before launching.
+    marketplace is registered in ``.claude/settings.json``, and Claude is launched
+    with the bundled plugin loaded via ``--plugin-dir`` so the namespaced skill
+    resolves immediately without waiting on a marketplace install.
 
     Returns:
         Whether Claude was launched.
@@ -114,7 +100,9 @@ def maybe_launch_bootstrap(root: Path) -> bool:
     if not click.confirm("Bootstrap hooks now? (launches Claude with the bootstrapping-hooks skill)", default=True):
         return False
     register_marketplace(root)
-    subprocess.run(["claude", "/bootstrapping-hooks"], cwd=root, check=False)
+    subprocess.run(
+        ["claude", "--plugin-dir", str(plugin_dir()), "/captain-hook:bootstrapping-hooks"], cwd=root, check=False
+    )
     return True
 
 
@@ -326,17 +314,14 @@ def init_project(root: Path, *, review: bool = True) -> None:
     merged, summary = merge_settings(".claude/hooks", settings_path)
     write_settings(settings_path, merged)
 
-    skills_summary = install_skills(root)
+    register_marketplace(root)
 
     click.echo(f"Scaffolded {example.relative_to(root)} + {settings_path.relative_to(root)}.")
     click.echo()
     print_hook_summary(str(settings_path.relative_to(root)), summary)
     click.echo()
-    click.echo(".claude/skills/:")
-    for name in (n for n, status in skills_summary.items() if status == "installed"):
-        click.echo(f"  + installed {name}")
-    if skipped := [n for n, status in skills_summary.items() if status == "skipped"]:
-        click.echo(f"  unchanged: {', '.join(skipped)} (already present; capt-hook skills install --force to refresh)")
+    click.echo("Claude Code plugin:")
+    click.echo(f"  + registered {PLUGIN_ID} in .claude/settings.json (skills install on folder-trust)")
     click.echo()
     match (review, repo_key(root)):
         case (False, _):
@@ -527,18 +512,29 @@ 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."""
 
 
 @skills.command(name="install")
-@click.option("--force", is_flag=True, default=False, help="Replace skills that already exist in .claude/skills")
 @click.pass_obj
-def skills_install(state: CliState, force: bool) -> None:
-    """Copy the bundled skills into .claude/skills/."""
-    for name, status in install_skills(state.root, force=force).items():
-        click.echo(f"  {status} {name}")
+def skills_install(state: CliState) -> None:
+    """Register the captain-hook plugin in .claude/settings.json (skills load from the plugin, not copied files)."""
+    register_marketplace(state.root)
+    click.echo(f"  registered {PLUGIN_ID} in .claude/settings.json")
 
 
 @cli.group()

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

@@ -120,12 +120,12 @@ def spawn(transcript: Path, cwd: str | None) -> None:
 @review.command()
 @click.pass_obj
 def enable(state: CliState) -> None:
-    """Watch the current repo, install the reviewer's skills, and wire the SessionEnd hook."""
-    from captain_hook.cli import install_skills
+    """Watch the current repo, register the captain-hook plugin, and wire the SessionEnd hook."""
+    from captain_hook.cli import register_marketplace
 
     repo = current_repo(state.root)
     watch_repo(repo)
-    install_skills(state.root)
+    register_marketplace(state.root)
     wired = ensure_review_wiring(state.root / ".claude" / "settings.local.json")
     click.echo(f"watching {repo}" + (" (SessionEnd hook wired into .claude/settings.local.json)" if wired else ""))
 
@@ -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.5.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.5.0}/captain_hook/review/pipeline.py

@@ -134,7 +134,7 @@ def brain_prompt(transcript: Path) -> str:
     from captain_hook.review.scan import REVIEWER_MARKER
 
     return (
-        f"/scanning-sessions --transcript {transcript}\n\n"
+        f"/captain-hook:scanning-sessions --transcript {transcript}\n\n"
         f"[{REVIEWER_MARKER}] Review this repo's eligible candidates and open at most one pull request per"
         " candidate. Work in one continuous run: do not stop to summarize after drafting — you are done only"
         " when every eligible candidate has a PR recorded via `review update <id> pr_open --pr-url <url>` or"
@@ -143,13 +143,22 @@ def brain_prompt(transcript: Path) -> str:
 
 
 def brain_argv(*, max_turns: int, max_budget_usd: float) -> list[str]:
+    from captain_hook.cli import plugin_dir
     from captain_hook.llm import ClaudeBackend
 
     backend = ClaudeBackend()
     argv = backend.build_command(backend.models[BRAIN_TIER], None, agent=True)
     argv[argv.index("--permission-mode") + 1] = "acceptEdits"
     argv[argv.index("--max-budget-usd") + 1] = str(max_budget_usd)
-    return [*argv, "--max-turns", str(max_turns), "--allowedTools", ",".join(BRAIN_ALLOWED_TOOLS)]
+    return [
+        *argv,
+        "--plugin-dir",
+        str(plugin_dir()),
+        "--max-turns",
+        str(max_turns),
+        "--allowedTools",
+        ",".join(BRAIN_ALLOWED_TOOLS),
+    ]
 
 
 def spawn_brain(transcript: Path, *, repo_root: Path, settings: ReviewSettings) -> None: