capt-hook 3.2.0__tar.gz → 3.3.0__tar.gz

{capt_hook-3.2.0 → capt_hook-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 3.2.0
+Version: 3.3.0
 Summary: Declarative hook framework for Claude Code
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali
@@ -55,23 +55,28 @@ Description-Content-Type: text/markdown
 
 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.
 
-## Install
+## Quickstart
 
-There's no install step. Run everything through [uvx](https://docs.astral.sh/uv/).
+No install step — everything runs through [uvx](https://docs.astral.sh/uv/). Pick a front door:
+
+**From your terminal:**
 
 ```bash
 uvx capt-hook init
 ```
 
-`uvx` fetches captain-hook into a throwaway environment and runs it, so you never add it to `pyproject.toml`. Every command in this README works the same way once you prefix it with `uvx`.
+**From inside Claude Code** — install the plugin, then ask Claude to set it up:
 
-## First hook
+```
+/plugin marketplace add yasyf/captain-hook
+/plugin install captain-hook@captain-hook
+```
 
-`uvx capt-hook init` scaffolds `.claude/hooks/`, wires Claude Code's settings, and installs the skills. One command and you're live.
+> set up captain hook
 
-```bash
-uvx capt-hook init
-```
+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.
 
@@ -117,14 +122,15 @@ 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.
 
-## Agent Skills & plugin
+## Session reviewer
 
-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` mines your repo's docs, CI, and git history into proposed gates and nudges. `translating-styleguides` turns a STYLEGUIDE.md into enforced rules. `uvx capt-hook init` installs both into `.claude/skills/`, or you can add them as a plugin.
+`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.
 
-```
-/plugin marketplace add yasyf/captain-hook
-/plugin install captain-hook@captain-hook
-```
+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
 

{capt_hook-3.2.0 → capt_hook-3.3.0}/README.md

@@ -9,23 +9,28 @@
 
 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.
 
-## Install
+## Quickstart
 
-There's no install step. Run everything through [uvx](https://docs.astral.sh/uv/).
+No install step — everything runs through [uvx](https://docs.astral.sh/uv/). Pick a front door:
+
+**From your terminal:**
 
 ```bash
 uvx capt-hook init
 ```
 
-`uvx` fetches captain-hook into a throwaway environment and runs it, so you never add it to `pyproject.toml`. Every command in this README works the same way once you prefix it with `uvx`.
+**From inside Claude Code** — install the plugin, then ask Claude to set it up:
 
-## First hook
+```
+/plugin marketplace add yasyf/captain-hook
+/plugin install captain-hook@captain-hook
+```
 
-`uvx capt-hook init` scaffolds `.claude/hooks/`, wires Claude Code's settings, and installs the skills. One command and you're live.
+> set up captain hook
 
-```bash
-uvx capt-hook init
-```
+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.
 
@@ -71,14 +76,15 @@ 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.
 
-## Agent Skills & plugin
+## Session reviewer
 
-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` mines your repo's docs, CI, and git history into proposed gates and nudges. `translating-styleguides` turns a STYLEGUIDE.md into enforced rules. `uvx capt-hook init` installs both into `.claude/skills/`, or you can add them as a plugin.
+`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.
 
-```
-/plugin marketplace add yasyf/captain-hook
-/plugin install captain-hook@captain-hook
-```
+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
 

{capt_hook-3.2.0 → capt_hook-3.3.0}/captain_hook/cli.py

@@ -196,17 +196,17 @@ def print_hook_summary(label: str, summary: dict[str, str]) -> None:
     by_status: defaultdict[str, list[str]] = defaultdict(list)
     for event, status in summary.items():
         by_status[status].append(event)
-    print(f"{label}:")
+    click.echo(f"{label}:")
     if not summary:
-        print("  no hook entries")
+        click.echo("  no hook entries")
     for event in by_status["added"]:
-        print(f"  + added {event}")
+        click.echo(f"  + added {event}")
     for event in by_status["updated"]:
-        print(f"  ~ updated {event}")
+        click.echo(f"  ~ updated {event}")
     for event in by_status["removed"]:
-        print(f"  - removed {event}")
+        click.echo(f"  - removed {event}")
     if unchanged := by_status["unchanged"]:
-        print(f"  unchanged: {', '.join(unchanged)} (already present)")
+        click.echo(f"  unchanged: {', '.join(unchanged)} (already present)")
 
 
 def regenerate_settings(state: CliState) -> None:
@@ -303,13 +303,15 @@ def run_event(
         print(json.dumps(output))
 
 
-def init_project(root: Path) -> None:
+def init_project(root: Path, *, review: bool = True) -> None:
+    from captain_hook.review.cli import watch_repo
+    from captain_hook.review.repo import repo_key
+
     hooks_dir = root / ".claude" / "hooks"
     hooks_dir.mkdir(parents=True, exist_ok=True)
 
     example = hooks_dir / "example.py"
-    example_created = not example.exists()
-    if example_created:
+    if not example.exists():
         example.write_text(example_hook_source())
 
     settings_path = root / ".claude" / "settings.local.json"
@@ -319,23 +321,33 @@ def init_project(root: Path) -> None:
 
     skills_summary = install_skills(root)
 
-    print(f"Scaffolded {example.relative_to(root)} + {settings_path.relative_to(root)}.")
-    print()
+    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)
-    print()
-    print(".claude/skills/:")
+    click.echo()
+    click.echo(".claude/skills/:")
     for name in (n for n, status in skills_summary.items() if status == "installed"):
-        print(f"  + installed {name}")
+        click.echo(f"  + installed {name}")
     if skipped := [n for n, status in skills_summary.items() if status == "skipped"]:
-        print(f"  unchanged: {', '.join(skipped)} (already present; capt-hook skills install --force to refresh)")
-    print()
-    print("Next:")
-    print("  1. Read the quickstart: https://yasyf.github.io/captain-hook/")
-    print("  2. Edit example.py or add new files under .claude/hooks/")
-    print("  3. uvx capt-hook test       # verify inline tests")
-    print("  4. uvx capt-hook register-hooks    # re-register after adding events")
-    print("  5. /bootstrapping-hooks in Claude  # mine hooks from this repo's conventions")
-    print()
+        click.echo(f"  unchanged: {', '.join(skipped)} (already present; capt-hook skills install --force to refresh)")
+    click.echo()
+    match (review, repo_key(root)):
+        case (False, _):
+            click.echo("Session reviewer: skipped (--no-review) — `uvx capt-hook review enable` to turn it on later.")
+        case (True, None):
+            click.echo("Session reviewer: needs a git repo with a remote — `uvx capt-hook review enable` once it has one.")
+        case (True, repo):
+            watch_repo(repo)
+            click.echo(f"Session reviewer: watching {repo} — mines your ended sessions and opens hook PRs automatically.")
+            click.echo("  Stop anytime with `uvx capt-hook review disable`.")
+    click.echo()
+    click.echo("Next:")
+    click.echo("  1. Read the quickstart: https://yasyf.github.io/captain-hook/")
+    click.echo("  2. Edit example.py or add new files under .claude/hooks/")
+    click.echo("  3. uvx capt-hook test               # verify inline tests")
+    click.echo("  4. uvx capt-hook register-hooks     # re-register after adding events")
+    click.echo('  5. Ask Claude "set up captain hook" # mine guardrails from this repo (the bootstrapping-hooks skill)')
+    click.echo()
     maybe_launch_bootstrap(root)
 
 
@@ -493,10 +505,11 @@ def test(state: CliState, json_output: bool) -> None:
 
 
 @cli.command()
+@click.option("--no-review", is_flag=True, default=False, help="Skip enabling the SessionEnd session reviewer for this repo")
 @click.pass_obj
-def init(state: CliState) -> None:
-    """Scaffold the hooks directory, install bundled skills, and wire settings."""
-    init_project(state.root)
+def init(state: CliState, no_review: bool) -> None:
+    """Scaffold the hooks directory, install bundled skills, wire settings, and enable the session reviewer."""
+    init_project(state.root, review=not no_review)
 
 
 @cli.command()
@@ -537,9 +550,9 @@ def pack_add(state: CliState, target: str) -> None:
             if target in manager.builtin_packs()
             else manager.fetch_pack(manager.PackSource.parse(target)).entry
         )
-        manager.upsert_entry(manager.packs_toml_path(state.root), entry)
     except manager.PackError as e:
         raise click.ClickException(str(e)) from e
+    manager.upsert_entry(manager.packs_toml_path(state.root), entry)
     click.echo(f"  added {entry.name}")
     regenerate_settings(state)
 

{capt_hook-3.2.0 → capt_hook-3.3.0}/captain_hook/packs/manager.py

@@ -170,11 +170,25 @@ def resolve_commit(source: PackSource) -> str:
 
 def strip_top_level(tf: tarfile.TarFile) -> Iterator[tarfile.TarInfo]:
     for member in tf.getmembers():
-        if (tail := member.name.partition("/")[2]):
+        if tail := member.name.partition("/")[2]:
             member.path = tail
             yield member
 
 
+def members_under(members: list[tarfile.TarInfo], hooks: str) -> Iterator[tarfile.TarInfo]:
+    """Yield the manifest plus members within the pack's hooks dir.
+
+    hooks == "." (hooks beside the manifest) selects the whole tree; a real
+    subdir selects only the manifest and that subtree, so the cache holds just
+    what the loader imports.
+    """
+    rel = hooks.strip("/")
+    prefix = "" if rel in ("", ".") else rel + "/"
+    for m in members:
+        if m.path == PACK_MANIFEST or not prefix or m.path == rel or m.path.startswith(prefix):
+            yield m
+
+
 def find_cached(name: str, sha: str) -> Path | None:
     return d if (d := packs_cache_root() / f"{name}@{sha}").is_dir() and (d / SHA_MARKER).is_file() else None
 
@@ -188,14 +202,21 @@ def fetch_commit(source: PackSource, sha: str) -> ResolvedPack:
         if staging.exists():
             shutil.rmtree(staging)
         with tarfile.open(tarball) as tf:
-            tf.extractall(staging, members=strip_top_level(tf), filter="data")
-        manifest = PackManifest.load(staging / PACK_MANIFEST)
+            members = list(strip_top_level(tf))
+            manifest_member = next((m for m in members if m.path == PACK_MANIFEST), None)
+            if manifest_member is None:
+                raise PackError(f"pack manifest {PACK_MANIFEST} missing in {source}")
+            tf.extract(manifest_member, staging, filter="data")
+            manifest = PackManifest.load(staging / PACK_MANIFEST)
+            tf.extractall(staging, members=list(members_under(members, manifest.hooks)), filter="data")
         final = root / f"{manifest.name}@{sha}"
         if final.exists():
             shutil.rmtree(final)
         os.replace(staging, final)
         (final / SHA_MARKER).write_text(sha)
-    return ResolvedPack(ExternalPack(name=manifest.name, source=source, commit=sha), manifest.hooks_dir(final), manifest)
+    return ResolvedPack(
+        ExternalPack(name=manifest.name, source=source, commit=sha), manifest.hooks_dir(final), manifest
+    )
 
 
 def fetch_pack(source: PackSource) -> ResolvedPack:
@@ -228,6 +249,8 @@ def resolve_enabled_packs(root: Path) -> tuple[list[ResolvedPack], list[str]]:
         match entry:
             case BuiltinPack(name=name):
                 resolved.append(resolve_builtin(name))
+            case ExternalPack() as ext if found := resolve_external(ext):
+                resolved.append(found)
             case ExternalPack() as ext:
-                resolved.append(found) if (found := resolve_external(ext)) else missing.append(ext.name)
+                missing.append(ext.name)
     return resolved, missing

{capt_hook-3.2.0 → capt_hook-3.3.0}/captain_hook/review/cli.py

@@ -71,6 +71,18 @@ def ensure_review_wiring(settings_path: Path) -> bool:
     return True
 
 
+def watch_repo(repo: RepoKey) -> None:
+    """Flip the global watching bit for ``repo`` — the single persistence path shared by ``init`` and ``review enable``."""
+    from captain_hook.review.settings import ReviewSettings
+    from captain_hook.review.store import ReviewStore
+
+    async def go() -> None:
+        async with await ReviewStore.open(ReviewSettings().db_path) as store:
+            await store.enable(repo)
+
+    asyncio.run(go())
+
+
 def candidate_line(row: dict[str, object]) -> str:
     text = str(row["sample_text"] or "").replace("\n", " ")
     return (
@@ -106,17 +118,12 @@ def spawn(transcript: Path, cwd: str | None) -> None:
 @review.command()
 @click.pass_obj
 def enable(state: CliState) -> None:
-    """Watch the current repo and wire the SessionEnd reviewer hook."""
-    from captain_hook.review.settings import ReviewSettings
-    from captain_hook.review.store import ReviewStore
+    """Watch the current repo, install the reviewer's skills, and wire the SessionEnd hook."""
+    from captain_hook.cli import install_skills
 
     repo = current_repo(state.root)
-
-    async def go() -> None:
-        async with await ReviewStore.open(ReviewSettings().db_path) as store:
-            await store.enable(repo)
-
-    asyncio.run(go())
+    watch_repo(repo)
+    install_skills(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 ""))
 

{capt_hook-3.2.0 → capt_hook-3.3.0}/captain_hook/review/settings.py

@@ -36,7 +36,7 @@ class ReviewSettings(HooksSettings):
     min_days_fix: int = 0
     min_confidence_fix: Confidence = MEDIUM
     min_confidence_fix_single: Confidence = VERY_HIGH
-    judge_tier: TModel = "small"
+    judge_tier: TModel = "medium"
     judge_concurrency: int = 8
     judge_timeout: int = 180
     min_judge_confidence: float = 0.6

{capt_hook-3.2.0 → capt_hook-3.3.0}/captain_hook/skills/bootstrapping-hooks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bootstrapping-hooks
-description: Surveys a repository and sets up captain-hook (capt-hook) guardrails for Claude Code — blocking gates, advisory nudges, command blocks, and test-integrity checks mined from the repo's own docs, CI workflows, lint configs, and git history. Proposes categorized candidates for user approval before writing anything, then writes .claude/hooks/*.py with inline tests, verifies with capt-hook test, and wires .claude/settings.local.json. Use when the user asks to "set up hooks", "bootstrap capt-hook", "add guardrails", "enforce our conventions with hooks", "protect this repo", or "make Claude follow CONTRIBUTING.md".
+description: Surveys a repository and sets up captain-hook (capt-hook) guardrails for Claude Code — blocking gates, advisory nudges, command blocks, and test-integrity checks mined from the repo's own docs, CI workflows, lint configs, and git history. Scaffolds the framework and enables the session reviewer up front (Step 1), then proposes categorized candidates for user approval before writing anything, then writes .claude/hooks/*.py with inline tests, verifies with capt-hook test, and wires .claude/settings.local.json. Use when the user asks to "set up captain hook", "set up capt-hook", "set up hooks", "bootstrap capt-hook", "add guardrails", "enforce our conventions with hooks", "protect this repo", or "make Claude follow CONTRIBUTING.md".
 argument-hint: "[repo path] (defaults to current project)"
 allowed-tools: Read, Grep, Glob, AskUserQuestion, Write, Edit, Bash(uvx capt-hook:*, capt-hook:*, git log:*, git diff:*, ls:*, find:*)
 ---
@@ -29,28 +29,41 @@ Copy this checklist into your response and check off steps as you complete them:
 
 ```
 Bootstrap Progress:
-- [ ] Step 1: Locate + pre-flight (.claude/hooks, settings)
+- [ ] Step 1: Locate + scaffold (init or review enable) + pre-flight
 - [ ] Step 2: Survey the repo (docs, CI, lint configs, git log)
 - [ ] Step 3: Mine candidates onto the taxonomy
 - [ ] Step 4: Propose via AskUserQuestion — nothing written before approval
-- [ ] Step 5: Scaffold (uvx capt-hook init)
+- [ ] Step 5: Clear the demo example.py (scaffolding ran in Step 1)
 - [ ] Step 6: Draft approved hooks via authoring-hooks, one file per category
 - [ ] Step 7: Verify (uvx capt-hook test, fix until green)
 - [ ] Step 8: Wire settings (register-hooks if new events)
 - [ ] Step 9: Final report (table + declined list)
 ```
 
-### 1. Locate + pre-flight
+### 1. Locate + scaffold + pre-flight
 
-Resolve the target repo (argument path, else current project). Run:
+Resolve the target repo (argument path, else current project). Inspect what's already wired:
 
 ```bash
 ls .claude/hooks/ 2>/dev/null
+grep -lq 'capt-hook' .claude/settings.json 2>/dev/null && echo COMMITTED || echo FRESH
 ```
 
-Read `.claude/settings.local.json` and `.claude/settings.json` if present. If capt-hook hooks
-already exist, switch to **additive mode**: never overwrite existing hook files; new categories
-go in new files, and the Step 4 menu only offers candidates not already covered.
+Then scaffold up front, so the framework and the session reviewer are live before you propose
+anything — pick the command by what you found:
+
+- **FRESH** (no committed capt-hook wiring) — run `uvx capt-hook init`. It scaffolds
+  `.claude/hooks/`, wires `.claude/settings.local.json`, installs the skills, and **enables the
+  session reviewer** (watching this repo; it mines ended sessions and opens hook PRs —
+  `uvx capt-hook review disable` to stop).
+- **COMMITTED** (a checked-in `.claude/settings.json` already runs `uvx capt-hook run …`) — do
+  **not** run `init`; it would duplicate those hooks into `settings.local.json` and double-fire.
+  Run `uvx capt-hook review enable` instead — it installs the reviewer skills and arms the session
+  reviewer without touching the committed event hooks.
+
+Read `.claude/settings.local.json` and `.claude/settings.json`. If capt-hook hooks already exist,
+switch to **additive mode**: never overwrite existing hook files; new categories go in new files,
+and the Step 4 menu only offers candidates not already covered.
 
 ### 2. Survey the repo
 
@@ -99,17 +112,11 @@ and the proposed primitive + severity. Then one final severity question:
 If a styleguide-like markdown was found, category E is a single option: **"Translate `<file>`
 into enforced style rules (runs the translating-styleguides skill)"**.
 
-### 5. Scaffold
-
-Run:
-
-```bash
-uvx capt-hook init
-```
+### 5. Clear the demo example.py
 
-This creates `.claude/hooks/example.py` (only when absent) and merges capt-hook entries into
-`.claude/settings.local.json`. If this run created the demo `example.py`, delete it after
-writing the real hooks — the approved hooks replace it.
+Scaffolding already ran in Step 1. If that `init` created the demo `.claude/hooks/example.py`,
+delete it once you've drafted the real hooks (Step 6) — the approved hooks replace it. (In
+**COMMITTED** repos `review enable` writes no `example.py`, so there's nothing to clear.)
 
 ### 6. Write hooks
 
@@ -168,7 +175,9 @@ Declined: <candidates the user rejected, with their source quotes>
 ```
 
 Close with next steps: `uvx capt-hook logs --tail 50` to inspect live firings, and tune
-`max_fires` on any hook that nags.
+`max_fires` on any hook that nags. Note that Step 1 also armed the **session reviewer** — it now
+watches this repo, mines your ended sessions for durable corrections, and opens hook PRs
+automatically; `uvx capt-hook review disable` turns it off.
 
 ## Worked mini-example
 

{capt_hook-3.2.0 → capt_hook-3.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "capt-hook"
-version = "3.2.0"
+version = "3.3.0"
 description = "Declarative hook framework for Claude Code"
 readme = "README.md"
 license = "PolyForm-Noncommercial-1.0.0"