capt-hook 4.4.0__tar.gz → 4.5.0__tar.gz

{capt_hook-4.4.0 → capt_hook-4.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 4.4.0
+Version: 4.5.0
 Summary: Declarative hook framework for Claude Code
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali

{capt_hook-4.4.0 → capt_hook-4.5.0}/captain_hook/review/cli.py

@@ -124,10 +124,9 @@ def run_hook() -> None:
 @click.option("--cwd", "cwd", default=None, help="The session's working directory (default: the process cwd)")
 def spawn(transcript: Path, cwd: str | None) -> None:
     """Run the detached reviewer pass over one ended session (spawned by ``review run``)."""
-    from captain_hook.review.pipeline import review_session
-    from captain_hook.review.settings import ReviewSettings
+    from captain_hook.review.pipeline import spawn_session
 
-    click.echo(asyncio.run(review_session(transcript, cwd=cwd or os.getcwd(), settings=ReviewSettings())))
+    click.echo(asyncio.run(spawn_session(transcript, cwd=cwd or os.getcwd())))
 
 
 @review.command()

{capt_hook-4.4.0 → capt_hook-4.5.0}/captain_hook/review/dashboard.py

@@ -12,7 +12,8 @@ background so the view appears instantly and updates when ``gh`` returns.
 from __future__ import annotations
 
 import asyncio
-from datetime import UTC, datetime
+import json
+from datetime import UTC, datetime, timedelta
 from enum import StrEnum
 from typing import TYPE_CHECKING
 
@@ -20,6 +21,7 @@ from rich.console import Console, Group
 from rich.spinner import Spinner
 from rich.text import Text
 
+from captain_hook.review.pipeline import review_log_path
 from captain_hook.review.store import CandidateKind, CandidateStatus
 
 if TYPE_CHECKING:
@@ -27,12 +29,13 @@ if TYPE_CHECKING:
 
     from captain_hook.review.repo import RepoKey
     from captain_hook.review.settings import ReviewSettings
-    from captain_hook.review.store import CandidateView
+    from captain_hook.review.store import CandidateView, SpawnHealth
 
 BAR_FILLED = "█"
 BAR_EMPTY = "░"
 DETAIL_WIDTH = 80
 KIND_STYLE = {CandidateKind.CREATE: "cyan", CandidateKind.FIX: "magenta"}
+SPAWN_STALE_AFTER = timedelta(days=7)
 
 
 class Stage(StrEnum):
@@ -151,6 +154,49 @@ def candidate_block(view: CandidateView, settings: ReviewSettings) -> Renderable
     )
 
 
+def relative(stamp: str) -> str:
+    minutes = int((datetime.now(UTC) - datetime.fromisoformat(stamp)).total_seconds()) // 60
+    match minutes:
+        case m if m < 60:
+            return f"{m}m ago"
+        case m if m < 1440:
+            return f"{m // 60}h ago"
+        case m:
+            return f"{m // 1440}d ago"
+
+
+def spawn_stale(stamp: str) -> bool:
+    return datetime.now(UTC) - datetime.fromisoformat(stamp) > SPAWN_STALE_AFTER
+
+
+def health_line(health: SpawnHealth) -> RenderableType:
+    match health.last:
+        case None:
+            return Text("reviewer has never run — check the SessionEnd hook wiring", style="yellow")
+        case {"ok": 0, "error": error}:
+            return Group(
+                Text.assemble(
+                    ("REVIEWER FAILING", "bold red"),
+                    (
+                        f"   {health.consecutive_failures} consecutive since {health.failing_since}"
+                        f"  ·  {trim(str(error))}",
+                        "red",
+                    ),
+                ),
+                Text(f"  see {review_log_path()}", style="dim"),
+            )
+        case {"finished_at": finished} if spawn_stale(str(finished)):
+            return Text(
+                f"reviewer last ran {relative(str(finished))} — check the SessionEnd hook wiring", style="yellow"
+            )
+        case last:
+            return Text(
+                f"reviewer ok  ·  last run {relative(str(last['finished_at']))}"
+                f"  ·  judged {json.loads(str(last['report_json']))['judged']}",
+                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(
@@ -168,9 +214,15 @@ def header(repo: RepoKey, views: list[CandidateView], settings: ReviewSettings,
 
 
 def render(
-    views: list[CandidateView], *, repo: RepoKey, settings: ReviewSettings, watching: bool, syncing: bool = False
+    views: list[CandidateView],
+    *,
+    repo: RepoKey,
+    settings: ReviewSettings,
+    watching: bool,
+    health: SpawnHealth,
+    syncing: bool = False,
 ) -> RenderableType:
-    """The whole dashboard frame: header, then a section per non-empty lifecycle stage."""
+    """The whole dashboard frame: reviewer health, header, then a section per non-empty lifecycle stage."""
     sections = [
         block
         for stage, title, desc, style in SECTIONS
@@ -183,7 +235,9 @@ def render(
     ]
     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)
+    return Group(
+        health_line(health), header(repo, views, settings, watching=watching), Text(""), *sections, *empty, *spinner
+    )
 
 
 async def run_status(repo: RepoKey, *, sync: bool) -> None:
@@ -198,17 +252,19 @@ async def run_status(repo: RepoKey, *, sync: bool) -> None:
     settings = ReviewSettings()
     console = Console()
     async with await ReviewStore.open(settings.db_path) as store:
+        health = await store.spawn_health()
         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))
+            console.print(render(views, repo=repo, settings=settings, watching=watching, health=health))
             return
         with Live(
-            render(views, repo=repo, settings=settings, watching=watching, syncing=True), console=console
+            render(views, repo=repo, settings=settings, watching=watching, health=health, 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))
+            live.update(render(fresh, repo=repo, settings=settings, watching=watching, health=health))
 
 
 def status_command(repo: RepoKey, *, sync: bool) -> None:

{capt_hook-4.4.0 → capt_hook-4.5.0}/captain_hook/review/fix.py

@@ -25,9 +25,14 @@ shapes (Stop feedback, blocking errors) fall back to
 :meth:`~cc_transcript.decisions.DecisionLog.attribute_nearest` with the
 decision's recorded message as the tiebreak — the only place message-substring
 matching survives. The PR target resolves primitive-aware: a ``nudge()``/``gate()``
-fire records the primitive file as its ``source_file``, so the real user hook
-comes from the decision ``kind``'s module prefix. Unattributable or unresolvable
-complaints are dropped — precision over recall.
+fire records the primitive file as its ``source_file``, so the real hook comes
+from the decision ``kind``'s module prefix — a ``<pack>.<module>`` prefix naming
+a module the installed builtin pack actually ships targets the pack source inside
+captain-hook itself (``captain_hook/packs/<pack>/<module>.py``), while any other
+module prefix — including a packaged user hook whose package merely shares a
+builtin pack's name — targets the repo-local ``.claude/hooks/<module>.py``.
+Unattributable or unresolvable complaints (including legacy kinds whose prefix is
+not a module path, e.g. ``<frozen importlib``) are dropped — precision over recall.
 """
 
 from __future__ import annotations
@@ -59,6 +64,7 @@ TIGHT_PROXIMITY_TURNS = 1
 STOP_FEEDBACK_PREFIX = "Stop hook feedback:\n"
 PRIMITIVES_DIR = "captain_hook/primitives/"
 HOOKS_DIR = ".claude/hooks"
+PACKS_DIR = "captain_hook/packs"
 
 HOOK_VOCAB_RE = re.compile(r"\b(?:hook|reminder|nudge|gate|guard)s?\b", re.IGNORECASE)
 
@@ -199,12 +205,20 @@ def attribute_fingerprint(
 
 
 def resolve_target(decision: Decision) -> tuple[str, str] | None:
+    from captain_hook.packs.manager import builtin_packs
+
     if PRIMITIVES_DIR not in decision.source_file:
         return decision.source_file, decision.kind
     module, sep, _ = decision.kind.partition(":")
     if not sep or not module:
         return None
-    return f"{HOOKS_DIR}/{module.rsplit('.', 1)[-1]}.py", decision.kind
+    match module.split("."):
+        case [pack, mod] if (pack_dir := builtin_packs().get(pack)) and (pack_dir / f"{mod}.py").is_file():
+            return f"{PACKS_DIR}/{pack}/{mod}.py", decision.kind
+        case parts if all(part.isidentifier() for part in parts):
+            return f"{HOOKS_DIR}/{parts[-1]}.py", decision.kind
+        case _:
+            return None
 
 
 def complaint_signal(marker: Marker, turns_back: int) -> CandidateSignal:

{capt_hook-4.4.0 → capt_hook-4.5.0}/captain_hook/review/pipeline.py

@@ -5,10 +5,11 @@ path — a non-zero or hanging hook wedges the user's session — so
 :func:`guard_and_spawn` does nothing but parse, guard, and detach
 ``capt-hook review spawn`` via ``Popen(start_new_session=True)``; no database
 reads, no scanning, no ``gh``, and no heavy imports happen on that path. The
-detached child (:func:`review_session`) does the real work: resolve the repo,
-check it is watched, scan the transcript incrementally, run the judge pass,
-sync open PR states, and — when at least one candidate crosses its
-thresholds — spawn the headless brain that drafts the PRs.
+detached child (:func:`spawn_session`, wrapping :func:`review_session`) does
+the real work: resolve the repo, check it is watched, scan the transcript
+incrementally, run the judge pass, sync open PR states, and — when at least
+one candidate crosses its thresholds — spawn the headless brain that drafts
+the PRs, recording each run's outcome for the status dashboard's health line.
 """
 
 from __future__ import annotations
@@ -17,7 +18,8 @@ import json
 import os
 import subprocess
 import sys
-from dataclasses import dataclass
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import TYPE_CHECKING, TypeGuard
 
@@ -247,3 +249,44 @@ async def review_session(transcript: Path, *, cwd: str, settings: ReviewSettings
         eligible=eligible,
         brain=bool(eligible),
     )
+
+
+async def spawn_session(transcript: Path, *, cwd: str, settings: ReviewSettings | None = None) -> SpawnReport:
+    """Runs :func:`review_session` and records its outcome — the ``review spawn`` entry.
+
+    Wraps the whole reviewer pass — settings construction, repo resolve, and
+    store open included (the historical crash sites were inside them) — and
+    records exactly one ``spawn_runs`` row per run into a freshly opened store,
+    so ``capt-hook status`` surfaces a silently crashing reviewer. A crash
+    records ``ok=0`` and re-raises, so the traceback still lands in the spawn
+    log; the catch is ``BaseException`` because anyio cancellation shapes are
+    not ``Exception``. When settings construction itself is the crash, the row
+    lands at the default db path.
+
+    Args:
+        transcript: The ended session's transcript file.
+        cwd: The session's working directory, used to resolve the repo.
+        settings: The reviewer settings; constructed inside the recording
+            boundary when omitted, so a settings/env failure still records.
+
+    Returns:
+        The recorded :class:`SpawnReport` for this pass.
+    """
+    from captain_hook.review.settings import ReviewSettings, resolve_review_db_path
+    from captain_hook.review.store import ReviewStore
+
+    started = datetime.now(UTC)
+    try:
+        settings = settings or ReviewSettings()
+        report = await review_session(transcript, cwd=cwd, settings=settings)
+    except BaseException as exc:
+        async with await ReviewStore.open(settings.db_path if settings else resolve_review_db_path()) as store:
+            await store.record_spawn_run(
+                str(transcript), started_at=started, ok=False, error=f"{type(exc).__name__}: {exc}"
+            )
+        raise
+    async with await ReviewStore.open(settings.db_path) as store:
+        await store.record_spawn_run(
+            str(transcript), started_at=started, ok=True, report_json=json.dumps(asdict(report))
+        )
+    return report

{capt_hook-4.4.0 → capt_hook-4.5.0}/captain_hook/review/scan.py

@@ -64,9 +64,9 @@ from cc_transcript.models import UserEvent
 from cc_transcript.parser import TranscriptParser
 
 from captain_hook.decisions import decisions_db_path, open_decision_log
-from captain_hook.review.fix import HOOK_COMPLAINT, iter_hook_complaint_signals
+from captain_hook.review.fix import HOOK_COMPLAINT, PACKS_DIR, iter_hook_complaint_signals
 from captain_hook.review.formats import review_spec
-from captain_hook.review.repo import resolve_repo_key
+from captain_hook.review.repo import RepoKey, resolve_repo_key
 from captain_hook.review.store import CandidateKind
 
 if TYPE_CHECKING:
@@ -77,13 +77,15 @@ if TYPE_CHECKING:
     from cc_transcript.mining.signals import MiningSignal
     from cc_transcript.models import TranscriptEvent
 
-    from captain_hook.review.repo import RepoKey
     from captain_hook.review.settings import ReviewSettings
     from captain_hook.review.store import ReviewStore
 
 REVIEWER_MARKER = "capt-hook-session-reviewer"
 """The token the reviewer's own headless sessions carry in their first user message."""
 
+CAPTAIN_HOOK_REPO = RepoKey("github.com/yasyf/captain-hook")
+"""Captain-hook's own repo key: fix candidates targeting a builtin pack file open upstream here."""
+
 SPEC_DETECTORS = frozenset({"transcript_message", "plan_reentry", "review_comment"})
 
 REVIEWER_MINING_SPEC = MiningSpec(review=review_spec())
@@ -238,6 +240,10 @@ def transcript_repo(events: Sequence[TranscriptEvent]) -> RepoKey | None:
     )
 
 
+def fix_repo(repo_key: RepoKey, target_source_file: str) -> RepoKey:
+    return CAPTAIN_HOOK_REPO if target_source_file.startswith(f"{PACKS_DIR}/") else repo_key
+
+
 def transcript_cwd(events: Sequence[TranscriptEvent]) -> Path | None:
     return next(
         (Path(meta.cwd) for event in events if (meta := event_meta(event)) is not None if meta.cwd is not None),
@@ -287,7 +293,7 @@ async def ingest(
     for sig, candidate in kept:
         candidate_id = (
             await store.ensure_candidate(
-                repo_key,
+                fix_repo(repo_key, str(sig.evidence["target_source_file"])),
                 kind=CandidateKind.FIX,
                 rule=dedup_key(*rule_parts(sig)),
                 source_kind=sig.kind,

{capt_hook-4.4.0 → capt_hook-4.5.0}/captain_hook/review/store.py

@@ -75,6 +75,16 @@ CREATE TABLE IF NOT EXISTS repos (
   repo_key TEXT PRIMARY KEY,
   watching INTEGER NOT NULL
 );
+CREATE TABLE IF NOT EXISTS spawn_runs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  started_at TEXT NOT NULL,
+  finished_at TEXT NOT NULL,
+  transcript TEXT NOT NULL,
+  ok INTEGER NOT NULL,
+  error TEXT,
+  report_json TEXT,
+  CHECK ((ok = 1) = (error IS NULL))
+);
 """
 
 INSERT_CANDIDATE = """
@@ -138,6 +148,21 @@ ORDER BY l.confidence DESC, o.id DESC
 LIMIT 1
 """
 
+INSERT_SPAWN_RUN = """
+INSERT INTO spawn_runs (started_at, finished_at, transcript, ok, error, report_json)
+VALUES (?, ?, ?, ?, ?, ?)
+"""
+
+SPAWN_STREAK_QUERY = """
+WITH streak AS (
+  SELECT id, started_at FROM spawn_runs
+  WHERE id > COALESCE((SELECT MAX(id) FROM spawn_runs WHERE ok = 1), 0)
+)
+SELECT
+  (SELECT COUNT(*) FROM streak) AS consecutive_failures,
+  (SELECT started_at FROM streak ORDER BY id LIMIT 1) AS failing_since
+"""
+
 
 class InvalidTransition(Exception):
     """Raised when a candidate status move is outside :data:`TRANSITIONS`."""
@@ -241,6 +266,21 @@ class CandidateView:
     summary: str | None
 
 
+@dataclass(frozen=True, slots=True)
+class SpawnHealth:
+    """The detached reviewer's run health — what the status dashboard's top line reads.
+
+    Attributes:
+        last: The newest ``spawn_runs`` row, or ``None`` before the first recorded run.
+        consecutive_failures: How many runs have failed since the last success.
+        failing_since: The failing streak's first ``started_at``, or ``None`` while healthy.
+    """
+
+    last: dict[str, object] | None
+    consecutive_failures: int
+    failing_since: str | None
+
+
 class ReviewStore(VerdictStoreMixin, FeedbackStore):
     """The session reviewer's persistent store over a :class:`FileStateStore`.
 
@@ -560,3 +600,43 @@ class ReviewStore(VerdictStoreMixin, FeedbackStore):
             await self.candidate_view(row, settings=settings, prompt_version=prompt_version)
             for row in await self.candidates(repo)
         ]
+
+    async def record_spawn_run(
+        self,
+        transcript: str,
+        *,
+        started_at: datetime,
+        ok: bool,
+        error: str | None = None,
+        report_json: str | None = None,
+    ) -> None:
+        """Records one detached reviewer run's outcome — the only spawn-health write.
+
+        ``finished_at`` is stamped here, so the row's span is start-to-record.
+
+        Args:
+            transcript: The reviewed session's transcript path.
+            started_at: When the run started.
+            ok: Whether the run finished cleanly.
+            error: The crash's ``TypeName: message`` line (failed runs only).
+            report_json: The run's serialized ``SpawnReport`` (clean runs only).
+        """
+        await self.store.conn.execute(
+            INSERT_SPAWN_RUN,
+            (started_at.astimezone(UTC).isoformat(), now(), transcript, int(ok), error, report_json),
+        )
+
+    async def spawn_health(self) -> SpawnHealth:
+        """Returns the detached reviewer's run health — the only spawn-health read.
+
+        The failing streak is every run after the last clean one, so a single
+        success resets both ``consecutive_failures`` and ``failing_since``.
+        """
+        last_cur = await self.store.conn.execute("SELECT * FROM spawn_runs ORDER BY id DESC LIMIT 1")
+        streak_cur = await self.store.conn.execute(SPAWN_STREAK_QUERY)
+        streak = [dict(row) async for row in streak_cur][0]
+        return SpawnHealth(
+            last=rows[0] if (rows := [dict(row) async for row in last_cur]) else None,
+            consecutive_failures=int(streak["consecutive_failures"]),
+            failing_since=str(since) if (since := streak["failing_since"]) is not None else None,
+        )

{capt_hook-4.4.0 → capt_hook-4.5.0}/captain_hook/state.py

@@ -23,6 +23,7 @@ if TYPE_CHECKING:
     from captain_hook.types import Signals
 
 FRAMEWORK_DIR = str(Path(__file__).resolve().parent)
+PACKS_DIR = str(Path(FRAMEWORK_DIR) / "packs")
 CACHE_ROOT = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "captain-hook"
 SPACY_MODEL = "en_core_web_sm"
 
@@ -134,6 +135,8 @@ def text_hash(text: str) -> str:
 
 
 def package_aware_stem(p: Path) -> str:
+    if str(p).startswith(PACKS_DIR):
+        return f"{p.parent.name}.{p.stem}"
     if (
         p.name != "__init__.py"
         and not str(p).startswith(FRAMEWORK_DIR)
@@ -144,11 +147,15 @@ def package_aware_stem(p: Path) -> str:
     return p.stem
 
 
+def framework_frame(filename: str) -> bool:
+    return filename.startswith(FRAMEWORK_DIR) and not filename.startswith(PACKS_DIR)
+
+
 def caller_stem() -> str:
     frame: FrameType | None = inspect.currentframe()
     if frame:
         frame = frame.f_back
-    while frame and frame.f_code.co_filename.startswith(FRAMEWORK_DIR):
+    while frame and framework_frame(frame.f_code.co_filename):
         frame = frame.f_back
     return package_aware_stem(Path(frame.f_code.co_filename)) if frame else "unknown"
 

{capt_hook-4.4.0 → capt_hook-4.5.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "capt-hook"
 # Inert sentinel — the real version is stamped from the release tag (uv version --frozen).
-version = "4.4.0"
+version = "4.5.0"
 description = "Declarative hook framework for Claude Code"
 readme = "README.md"
 license = "PolyForm-Noncommercial-1.0.0"