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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 4.3.1
+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.3.1 → capt_hook-4.5.0}/captain_hook/__init__.py

@@ -52,6 +52,7 @@ from captain_hook.primitives import (
     prompt_check,
     rewrite_code,
     rewrite_command,
+    set_tool_input,
     warn_command,
 )
 
@@ -90,8 +91,10 @@ from captain_hook.types import (
     TCondition,
     TestFile,
     Tool,
+    ToolInput,
     TouchedFile,
     UsedSkill,
     Waiting,
+    WorkflowScript,
 )
 from captain_hook.util import read_json, resolve_binary

{capt_hook-4.3.1 → capt_hook-4.5.0}/captain_hook/conditions.py

@@ -3,10 +3,11 @@
 from __future__ import annotations
 
 import re
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 from cc_transcript.models import OtherEvent
-from cc_transcript.tools import tool_name_matches
+from cc_transcript.tools import WorkflowCall, tool_name_matches
 
 from captain_hook.types import (
     Agent,
@@ -23,9 +24,11 @@ from captain_hook.types import (
     TCondition,
     TestFile,
     Tool,
+    ToolInput,
     TouchedFile,
     UsedSkill,
     Waiting,
+    WorkflowScript,
 )
 
 if TYPE_CHECKING:
@@ -80,6 +83,32 @@ def is_waiting(evt: BaseHookEvent) -> bool:
     )
 
 
+def workflow_script_source(evt: BaseHookEvent) -> str | None:
+    if not (call := evt.as_input(WorkflowCall)):
+        return None
+    if call.script is not None:
+        return call.script
+    if not call.script_path:
+        return None
+    try:
+        path = Path(call.script_path)
+        if not path.is_file() or path.stat().st_size > 1_000_000:
+            return None
+        return path.read_text(errors="ignore")
+    except OSError:
+        return None
+
+
+def matches_workflow_script(cond: WorkflowScript, evt: BaseHookEvent) -> bool:
+    if (source := workflow_script_source(evt)) is None:
+        return False
+    if cond.pattern is not None:
+        return bool(re.search(cond.pattern, source, re.MULTILINE))
+    return cond.model is not None and any(
+        re.search(cond.model, pinned) for pinned in re.findall(r"""model\s*:\s*['"]([^'"]*)['"]""", source)
+    )
+
+
 def is_project_file(evt: BaseHookEvent) -> bool:
     if not (file := evt.file):
         return False
@@ -104,6 +133,14 @@ def check_condition(c: TCondition, evt: BaseHookEvent) -> bool:
                 and evt.content
                 and re.search(pattern, evt.content, re.MULTILINE)
             )
+        case ToolInput(field, pattern):
+            return bool(
+                evt.tool_name
+                and isinstance(value := evt.input.raw.get(field), str)
+                and re.search(pattern, value, re.MULTILINE)
+            )
+        case WorkflowScript() as workflow_script:
+            return matches_workflow_script(workflow_script, evt)
         case Pattern(pattern, lang, project_only):
             from captain_hook.ast_grep import lang_for_path
             from captain_hook.ast_grep import matches as ast_grep_matches

{capt_hook-4.3.1 → capt_hook-4.5.0}/captain_hook/packs/general/capt-hook.toml

@@ -1,4 +1,4 @@
 name = "general"
-version = "0.1.0"
+version = "0.2.0"
 description = "Language-agnostic guards: git/command safety, doc & prompt nudges, task & plan discipline, and a code-review gate."
 hooks = "."

capt_hook-4.5.0/captain_hook/packs/general/models.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from captain_hook import (
+    Agent,
+    Allow,
+    Block,
+    Event,
+    Input,
+    Rewrite,
+    Tool,
+    ToolInput,
+    Warn,
+    WorkflowScript,
+    hook,
+    nudge,
+    set_tool_input,
+)
+
+hook(
+    Event.PreToolUse,
+    only_if=[Tool("Agent|Task"), ToolInput("model", r"(?i)\bhaiku\b")],
+    skip_if=[ToolInput("prompt", r"(?i)\b(classif|label|tag|categoriz|per.file|one (fact|thing))")],
+    message=(
+        "This subagent is pinned to haiku. Route a subagent to haiku only for a single-fact "
+        "mechanical step — classifying, labeling, or tagging one thing per item. Anything that "
+        "carries judgment should run on sonnet; use model='sonnet', or drop model entirely to "
+        "inherit the session model. See CLAUDE.md § Plan Execution & Orchestration (Models)."
+    ),
+    block=True,
+    tests={
+        Input(model="haiku", content="implement the retry backoff in the client"): Block(),
+        Input(model="haiku", content="classify each file's language"): Allow(),
+        Input(content="implement the retry backoff in the client"): Allow(),
+        Input(model="sonnet", content="implement the retry backoff in the client"): Allow(),
+    },
+)
+
+set_tool_input(
+    "model",
+    "sonnet",
+    tool="Agent|Task",
+    only_if=[Agent("Explore|claude-code-guide")],
+    note=(
+        "Upgraded this recon subagent from the silent haiku default to sonnet, per the Models "
+        "table in CLAUDE.md § Plan Execution & Orchestration (Models)."
+    ),
+    tests={
+        Input(agent_type="Explore"): Rewrite(),
+        Input(agent_type="Explore", model="haiku"): Allow(),
+        Input(agent_type="general-purpose"): Allow(),
+    },
+)
+
+nudge(
+    """
+    This workflow script pins agent() steps to haiku. Reserve haiku for mechanical single-fact
+    map steps; a judgment-bearing stage should inherit the session model or route up. See
+    CLAUDE.md § Plan Execution & Orchestration (Models).
+    """,
+    only_if=[Tool("Workflow"), WorkflowScript(model="haiku")],
+    events=Event.PreToolUse,
+    max_fires=2,
+    tests={
+        Input(tool="Workflow", tool_input={"script": "steps:\n  - agent: reviewer\n    model: 'haiku'\n"}): Warn(),
+        Input(tool="Workflow", tool_input={"script": "steps:\n  - agent: reviewer\n    model: 'sonnet'\n"}): Allow(),
+    },
+)

{capt_hook-4.3.1 → capt_hook-4.5.0}/captain_hook/primitives/__init__.py

@@ -12,4 +12,4 @@ from captain_hook.primitives.llm import (
     prompt_check,
 )
 from captain_hook.primitives.nudge import gate, nudge
-from captain_hook.primitives.rewrite import rewrite_code
+from captain_hook.primitives.rewrite import rewrite_code, set_tool_input

{capt_hook-4.3.1 → capt_hook-4.5.0}/captain_hook/primitives/rewrite.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from captain_hook import ast_grep
 from captain_hook.app import on
@@ -62,3 +62,40 @@ def rewrite_code(
 
     handler.__name__ = handler.__qualname__ = hook_name("rewrite_code", None, f"{pattern}=>{replace}")
     on(Event.PreToolUse, only_if=[Tool("Edit|Write|MultiEdit|NotebookEdit"), *only_if], tests=tests)(handler)
+
+
+def set_tool_input(
+    field: str,
+    value: Any,
+    *,
+    tool: str,
+    only_if: Sequence[TCondition] = (),
+    skip_if: Sequence[TCondition] = (),
+    note: str | None = None,
+    tests: InlineTests | None = None,
+) -> None:
+    """Register a ``PreToolUse`` hook that fills a MISSING top-level input field with ``value``.
+
+    When ``field`` is absent from the matched tool's input, the input is rewritten to
+    ``{**raw, field: value}`` and allowed, with ``note`` surfaced as ``additionalContext``. A field
+    already present — even falsy — is left untouched, so an explicit choice is never clobbered.
+
+    Args:
+        field: The top-level tool-input key to fill.
+        value: The value to set when the field is absent.
+        tool: Tool-name pattern to gate on, e.g. ``"Agent|Task"``.
+        only_if: Extra conditions ANDed onto the built-in tool guard.
+        skip_if: Conditions that skip the hook when any matches.
+        note: Advisory context surfaced alongside the rewrite.
+        tests: Inline tests for the registered hook.
+
+    Example:
+        >>> set_tool_input("model", "sonnet", tool="Agent|Task", only_if=[Agent("Explore")], note="upgraded")
+    """
+
+    def handler(evt: PreToolUseEvent) -> HookResponse:
+        raw = evt.input.raw
+        return None if field in raw else evt.rewrite({**raw, field: value}, note=note)
+
+    handler.__name__ = handler.__qualname__ = hook_name("set_tool_input", None, f"{tool}:{field}")
+    on(Event.PreToolUse, only_if=[Tool(tool), *only_if], skip_if=skip_if, tests=tests)(handler)

{capt_hook-4.3.1 → 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.3.1 → 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.3.1 → 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.3.1 → 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.3.1 → 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.3.1 → 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.3.1 → capt_hook-4.5.0}/captain_hook/skills/authoring-hooks/references/capt-hook-api.md

@@ -20,10 +20,10 @@ from __future__ import annotations
 
 from captain_hook import (
     Allow, BaseHookEvent, Block, Event, HookResult, InlineTests, Input, Prompt,
-    RanCommand, Rewrite, Signal, Signals, SourceEdits, TestFile, Tool, TouchedFile,
-    TranscriptFixture, Warn,
+    RanCommand, Rewrite, Signal, Signals, SourceEdits, TestFile, Tool, ToolInput, TouchedFile,
+    TranscriptFixture, Warn, WorkflowScript,
     block_command, gate, hook, lint, llm_gate, llm_nudge, nudge, on,
-    prompt_check, rewrite_command, warn_command, workflow, Artifact, Step, text_matches,
+    prompt_check, rewrite_command, set_tool_input, warn_command, workflow, Artifact, Step, text_matches,
 )
 from captain_hook.types import Command
 ```
@@ -70,6 +70,7 @@ def handler(evt: BaseHookEvent) -> HookResult | None:
 | `block_command` | `(pattern, *, reason, hint=None, tests=None)` | `PreToolUse` + `Tool("Bash")`; message `"BLOCKED: {reason}. {hint}."` |
 | `warn_command` | `(pattern, *, message, tests=None, events=Event.PostToolUse)` | warns, never blocks |
 | `rewrite_command` | `(pattern, replace, *, note=None, tests=None)` | `PreToolUse` + `Tool("Bash")`; `re.sub(pattern, replace, command)` then allows with the rewritten command |
+| `set_tool_input` | `(field, value, *, tool, only_if=(), skip_if=(), note=None, tests=None)` | `PreToolUse` + `Tool(tool)`; fills a **missing** top-level input field with `value` and allows, never clobbering a present one |
 | `gate` | `(message, *, when=None, only_if=(), skip_if=(), events=None, max_fires=None, tests=None)` | `Stop \| SubagentStop`, `max_fires=1`; blocks |
 | `nudge` | `(message, *, when=None, signals=None, only_if=(), skip_if=(), block=False, events=None, max_fires=None, tests=None)` | `PostToolUse` (with signals) else `PreToolUse`; `max_fires` 3 / 1; warns |
 | `lint` | `(check, *, message, trigger=None, sep=", ", block=False, events=None, tests=None, max_shown=5)` | `PostToolUse`, `Tool("Edit\|Write")` + `*.py`, skips test files |
@@ -128,6 +129,8 @@ evaluated first.
 | Filter by file path | `FilePath("*.py", "*.pyi")` |
 | Filter by bash command text | `Command(r"git\s+push")` — from `captain_hook.types` |
 | Filter by file content being written | `Content(r"print\(")` (multiline regex over Edit new / Write content) |
+| Filter by one raw tool-input field | `ToolInput("model", r"(?i)\bhaiku\b")` (multiline regex over one top-level field of any tool) |
+| Filter by a Workflow script | `WorkflowScript(model="haiku")` (inline `script`, or the `script_path` file's contents) |
 | Filter by subagent type | `Agent("cleanup")` |
 | Match only test files | `TestFile()` (`test_*.py`, `conftest.py`) |
 | Python source edits (skips tests by default) | `SourceEdits(lang="py")`; `lang` also `ts`, `go`, `rs`, ... |

{capt_hook-4.3.1 → 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.3.1 → capt_hook-4.5.0}/captain_hook/testing/helpers.py

@@ -105,7 +105,12 @@ def make_tool_input(
     old: str | None,
     offset: int | None = None,
     limit: int | None = None,
+    agent_type: str | None = None,
+    model: str | None = None,
+    tool_input: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
+    if tool_input is not None:
+        return tool_input
     match tool:
         case "Bash" | "Execute":
             return omit_none({"command": command, "timeout": None, "description": None})
@@ -118,7 +123,7 @@ def make_tool_input(
         case "Read":
             return omit_none({"file_path": file or "", "limit": limit, "offset": offset})
         case "Agent" | "Task":
-            return omit_none({"prompt": content or "", "subagent_type": None})
+            return omit_none({"prompt": content or "", "subagent_type": agent_type, "model": model})
         case _:
             return omit_none({"command": command, "file_path": file, "new_string": content, "old_string": old})
 
@@ -134,6 +139,8 @@ def mock_tool_event(
     offset: int | None = None,
     limit: int | None = None,
     agent_type: str | None = None,
+    model: str | None = None,
+    tool_input: dict[str, Any] | None = None,
     permission_mode: str | None = None,
     transcript: Session | None = None,
     transcript_path: str | Path | None = None,
@@ -143,7 +150,12 @@ def mock_tool_event(
     return cast(
         ToolHookEvent,
         event.event_class(
-            _raw={"tool_name": tool, "tool_input": make_tool_input(tool, command, file, content, old, offset, limit)}
+            _raw={
+                "tool_name": tool,
+                "tool_input": make_tool_input(
+                    tool, command, file, content, old, offset, limit, agent_type, model, tool_input
+                ),
+            }
             | ({"agent_type": agent_type} if agent_type else {})
             | ({"permission_mode": permission_mode} if permission_mode else {}),
             ctx=build_context(transcript, transcript_path, session_dir, project_root),
@@ -325,6 +337,8 @@ def input_to_event(
                 offset=inp.offset,
                 limit=inp.limit,
                 agent_type=inp.agent_type,
+                model=inp.model,
+                tool_input=inp.tool_input,
                 **ctx_kw,
             )
 

{capt_hook-4.3.1 → capt_hook-4.5.0}/captain_hook/testing/types.py

@@ -85,8 +85,12 @@ class Input:
         content: New file content for ``Edit``/``Write``.
         old: Pre-edit content for ``Edit`` and ``diff_lint``.
         tool: Tool name when no condition pins it.
+        tool_input: Verbatim raw tool-input mapping — an escape hatch that wins
+            over the input synthesized from the other fields.
         prompt: ``UserPromptSubmit`` text.
-        agent_type: Subagent type for subagent events.
+        agent_type: Subagent type for subagent events (an Agent/Task call's
+            ``subagent_type``).
+        model: Model for an Agent/Task call's ``model`` input field.
         reason: ``SessionEnd`` reason.
         permission_mode: Permission mode, e.g. ``"plan"`` for plan-mode gating.
         offset: ``Read`` call offset.
@@ -101,8 +105,10 @@ class Input:
     content: str | None = None
     old: str | None = None
     tool: str | None = None
+    tool_input: dict[str, Any] | None = None
     prompt: str | None = None
     agent_type: str | None = None
+    model: str | None = None
     reason: str | None = None
     permission_mode: str | None = None
     offset: int | None = None

{capt_hook-4.3.1 → capt_hook-4.5.0}/captain_hook/types.py

@@ -169,6 +169,46 @@ class Content:
     project_only: bool = True
 
 
+@dataclass(frozen=True, slots=True)
+class ToolInput:
+    """Condition matching one top-level field of the raw tool input against a regex.
+
+    Reads a single top-level key of the current event's tool input and searches its value with
+    ``re.MULTILINE``. Works for any tool; false for non-tool events, a missing field, or a
+    non-string value.
+
+    Example:
+        >>> hook(Event.PreToolUse, only_if=[ToolInput("model", r"(?i)\\bhaiku\\b")], message="...", block=True)
+    """
+
+    field: str
+    pattern: str
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowScript:
+    """Condition matching a ``Workflow`` tool's script source.
+
+    ``model`` matches the model names pinned in the script's ``agent()`` opts
+    (``model: 'haiku'`` and friends) — no hand-written quote-aware regex; ``pattern``
+    searches the raw script source (``re.MULTILINE``). Provide exactly one. The source is
+    the inline ``script``, or — when ``script`` is None and ``script_path`` points at a
+    file — that file's contents. A missing or unreadable path, or a file larger than
+    ~1 MiB, never matches and never raises. False for any non-Workflow tool.
+
+    Example:
+        >>> nudge("no haiku steps", only_if=[Tool("Workflow"), WorkflowScript(model="haiku")],
+        ...       events=Event.PreToolUse)
+    """
+
+    pattern: str | None = None
+    model: str | None = None
+
+    def __post_init__(self) -> None:
+        if (self.pattern is None) == (self.model is None):
+            raise ValueError("WorkflowScript takes exactly one of pattern or model")
+
+
 @dataclass(frozen=True, slots=True)
 class Pattern:
     """Condition matching the edit's new content against an ast-grep **structural** pattern.
@@ -379,6 +419,8 @@ TCondition = (
     | FilePath
     | Command
     | Content
+    | ToolInput
+    | WorkflowScript
     | Pattern
     | Agent
     | UsedSkill

{capt_hook-4.3.1 → 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.3.1"
+version = "4.5.0"
 description = "Declarative hook framework for Claude Code"
 readme = "README.md"
 license = "PolyForm-Noncommercial-1.0.0"