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

{capt_hook-3.4.0 → capt_hook-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 3.4.0
+Version: 3.6.0
 Summary: Declarative hook framework for Claude Code
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali
@@ -66,7 +66,7 @@ captain-hook needs no install — it runs through [uvx](https://docs.astral.sh/u
 uvx capt-hook init
 ```
 
-`init` scaffolds `.claude/hooks/`, wires Claude Code's settings, installs the bundled skills, and arms the [session reviewer](#it-learns-from-your-corrections). Or install the plugin and let Claude do it. Run `/plugin marketplace add yasyf/captain-hook`, then ask Claude to "set up captain hook".
+`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
 

{capt_hook-3.4.0 → capt_hook-3.6.0}/README.md

@@ -19,7 +19,7 @@ captain-hook needs no install — it runs through [uvx](https://docs.astral.sh/u
 uvx capt-hook init
 ```
 
-`init` scaffolds `.claude/hooks/`, wires Claude Code's settings, installs the bundled skills, and arms the [session reviewer](#it-learns-from-your-corrections). Or install the plugin and let Claude do it. Run `/plugin marketplace add yasyf/captain-hook`, then ask Claude to "set up captain hook".
+`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
 

{capt_hook-3.4.0 → capt_hook-3.6.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, _):
@@ -545,12 +530,11 @@ def skills() -> None:
 
 
 @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.4.0 → capt_hook-3.6.0}/captain_hook/packs/manager.py

@@ -27,6 +27,8 @@ from captain_hook import state
 
 PACKS_TOML = "packs.toml"
 PACK_MANIFEST = "capt-hook.toml"
+# A pack's manifest may sit in .claude/ (preferred) or at the repo root.
+MANIFEST_MEMBERS = (f".claude/{PACK_MANIFEST}", PACK_MANIFEST)
 SHA_MARKER = ".sha"
 SOURCE_RE = re.compile(r"^github:(?P<owner>[\w.-]+)/(?P<repo>[\w.-]+?)(?:@(?P<ref>[\w./-]+))?$")
 PACK_NAME_RE = re.compile(r"[a-z][a-z0-9-]*")
@@ -102,6 +104,16 @@ def packs_toml_path(root: Path) -> Path:
     return root / ".claude" / "hooks" / PACKS_TOML
 
 
+def manifest_in(root: Path) -> Path:
+    """Return the pack manifest path under root, preferring .claude/capt-hook.toml.
+
+    Falls back to the repo-root location. The returned path may not exist (the
+    canonical missing location), so PackManifest.load still fails loudly.
+    """
+    claude = root / ".claude" / PACK_MANIFEST
+    return claude if claude.is_file() else root / PACK_MANIFEST
+
+
 def parse_entry(name: str, table: dict[str, Any]) -> PackEntry:
     match table:
         case {"source": source, "commit": commit}:
@@ -175,17 +187,18 @@ def strip_top_level(tf: tarfile.TarFile) -> Iterator[tarfile.TarInfo]:
             yield member
 
 
-def members_under(members: list[tarfile.TarInfo], hooks: str) -> Iterator[tarfile.TarInfo]:
+def members_under(members: list[tarfile.TarInfo], hooks: str, manifest_path: 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.
+    what the loader imports. The manifest is included by its actual archive path
+    so a .claude/ manifest survives without dragging in the rest of .claude/.
     """
     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):
+        if m.path == manifest_path or not prefix or m.path == rel or m.path.startswith(prefix):
             yield m
 
 
@@ -203,12 +216,15 @@ def fetch_commit(source: PackSource, sha: str) -> ResolvedPack:
             shutil.rmtree(staging)
         with tarfile.open(tarball) as tf:
             members = list(strip_top_level(tf))
-            manifest_member = next((m for m in members if m.path == PACK_MANIFEST), None)
+            by_path = {m.path: m for m in members}
+            manifest_member = next((by_path[p] for p in MANIFEST_MEMBERS if p in by_path), 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")
+            manifest = PackManifest.load(staging / manifest_member.path)
+            tf.extractall(
+                staging, members=list(members_under(members, manifest.hooks, manifest_member.path)), filter="data"
+            )
         final = root / f"{manifest.name}@{sha}"
         if final.exists():
             shutil.rmtree(final)
@@ -225,20 +241,20 @@ def fetch_pack(source: PackSource) -> ResolvedPack:
 
 def builtin_packs() -> dict[str, Path]:
     base = Path(str(importlib.resources.files("captain_hook") / "packs"))
-    return {p.name: p for p in base.iterdir() if p.is_dir() and (p / PACK_MANIFEST).is_file()}
+    return {p.name: p for p in base.iterdir() if p.is_dir() and manifest_in(p).is_file()}
 
 
 def resolve_builtin(name: str) -> ResolvedPack:
     if not (pack_dir := builtin_packs().get(name)):
         raise PackError(f"unknown builtin pack {name!r}; available: {', '.join(sorted(builtin_packs())) or 'none'}")
-    manifest = PackManifest.load(pack_dir / PACK_MANIFEST)
+    manifest = PackManifest.load(manifest_in(pack_dir))
     return ResolvedPack(BuiltinPack(name=name), manifest.hooks_dir(pack_dir), manifest)
 
 
 def resolve_external(entry: ExternalPack) -> ResolvedPack | None:
     if not (cached := find_cached(entry.name, entry.commit)):
         return None
-    manifest = PackManifest.load(cached / PACK_MANIFEST)
+    manifest = PackManifest.load(manifest_in(cached))
     return ResolvedPack(entry, manifest.hooks_dir(cached), manifest)
 
 

{capt_hook-3.4.0 → capt_hook-3.6.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 ""))
 

{capt_hook-3.4.0 → capt_hook-3.6.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:

{capt_hook-3.4.0 → capt_hook-3.6.0}/captain_hook/skills/authoring-hooks/SKILL.md

@@ -70,7 +70,7 @@ has the full decision rules and defaults:
 | A done-criterion to check once at stop ("run tests before stopping") | `gate(only_if=[...], skip_if=[RanCommand(...)])` |
 | Advice worth surfacing once per session | `nudge` |
 | A code-content rule needing AST precision | `lint()` |
-| A whole style guide | delegate to the `translating-styleguides` skill |
+| A whole style guide | delegate to the `captain-hook:translating-styleguides` skill |
 
 Worked, test-passing code for each shape:
 [pattern catalog](references/pattern-catalog.md).

{capt_hook-3.4.0 → capt_hook-3.6.0}/captain_hook/skills/authoring-hooks/references/pattern-catalog.md

@@ -364,6 +364,6 @@ CONTRIBUTING/AGENTS/CLAUDE.
 
 Found one? Stop. Do not write `StyleRule`s, `lint` approximations of style rules, or a
 `style.py` here. Offer the category E menu option and, if approved, invoke the
-`translating-styleguides` skill with the markdown path — it owns rule atomization, the
+`captain-hook:translating-styleguides` skill with the markdown path — it owns rule atomization, the
 Matcher/`check()`/LLM tier decision, `style.py`, and its own enforcement report. If the
 Skill tool is unavailable, read that skill's `SKILL.md` and follow it (both ship together).

{capt_hook-3.4.0 → capt_hook-3.6.0}/captain_hook/skills/bootstrapping-hooks/SKILL.md

@@ -119,7 +119,7 @@ that already had its own `.claude/hooks/`, `init` leaves those files untouched a
 
 One file per approved category: `safety.py`, `quality.py`, `testing.py`, `workflow.py`
 (+ `style.py`, owned end-to-end by `translating-styleguides`). Drafting is delegated:
-for each approved hook, invoke the `authoring-hooks` skill via the Skill tool, passing
+for each approved hook, invoke the `captain-hook:authoring-hooks` skill via the Skill tool, passing
 
 - the **source quote, verbatim** (it becomes the citation inside the message — the
   agent being blocked learns *why*),
@@ -225,7 +225,7 @@ Report row:
 
 When the survey finds a style guide (`STYLEGUIDE.md`, a "Code style" section in
 CONTRIBUTING/AGENTS/CLAUDE, `docs/style*.md`), this skill **never** writes `StyleRule`s
-itself. If the user approves the category E option, invoke the `translating-styleguides`
+itself. If the user approves the category E option, invoke the `captain-hook:translating-styleguides`
 skill via the Skill tool with the markdown path as args; it owns `style.py` end-to-end and
 its enforcement report is appended to this skill's final report. If the Skill tool is
 unavailable, read that skill's `SKILL.md` directly and follow it — both skills ship together.

{capt_hook-3.4.0 → capt_hook-3.6.0}/captain_hook/skills/scanning-sessions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scanning-sessions
-description: The headless session-reviewer brain — turns a watched repo's PR-eligible candidates into pull requests, both kinds. Invoked as /scanning-sessions --transcript <path> inside the target repo by capt-hook's detached SessionEnd reviewer pipeline. Enumerates judge-accepted, threshold-eligible candidates via uvx capt-hook review (the CLI is the source of truth), re-verifies every cited correction or complaint verbatim against its session transcript, then per candidate drafts a new hook (create candidates) or amends the attributed misfiring hook with a regression test (fix candidates) in a worktree by delegating to the authoring-hooks skill, proves it with uvx capt-hook test, opens exactly one PR with the verbatim evidence, and records the PR on the candidate. Use when a prompt starts with /scanning-sessions, or to review eligible capt-hook candidates and open hook PRs.
+description: The headless session-reviewer brain — turns a watched repo's PR-eligible candidates into pull requests, both kinds. Invoked as /captain-hook:scanning-sessions --transcript <path> inside the target repo by capt-hook's detached SessionEnd reviewer pipeline. Enumerates judge-accepted, threshold-eligible candidates via uvx capt-hook review (the CLI is the source of truth), re-verifies every cited correction or complaint verbatim against its session transcript, then per candidate drafts a new hook (create candidates) or amends the attributed misfiring hook with a regression test (fix candidates) in a worktree by delegating to the authoring-hooks skill, proves it with uvx capt-hook test, opens exactly one PR with the verbatim evidence, and records the PR on the candidate. Use when a prompt starts with /captain-hook:scanning-sessions, or to review eligible capt-hook candidates and open hook PRs.
 argument-hint: "--transcript <path to the ended session's transcript>"
 allowed-tools: Read, Grep, Glob, Bash, Skill
 ---
@@ -46,7 +46,7 @@ user feedback next pass.
   the candidate stays `watching`, and you never open a PR against a hook that is no
   longer there.
 - **You do not draft hooks yourself** — this skill carries no Write/Edit. Drafting
-  happens inside the `authoring-hooks` skill, invoked via the Skill tool.
+  happens inside the `captain-hook:authoring-hooks` skill, invoked via the Skill tool.
 - **`uvx capt-hook test` must be green** in the worktree before `gh pr create`.
 - **Run to completion — never stop early.** You run headless; a text-only reply ends
   the session immediately. After the authoring-hooks skill returns, keep going in the
@@ -126,7 +126,7 @@ Follow [references/pr-workflow.md](references/pr-workflow.md) exactly:
 
 1. **Worktree** — fetch, then `git worktree add` a `capt-hook/review/<rule-slug>`
    branch off `origin/<default>`.
-2. **Draft** — invoke the `authoring-hooks` skill via the Skill tool, passing the
+2. **Draft** — invoke the `captain-hook:authoring-hooks` skill via the Skill tool, passing the
    verbatim correction, its context, and the worktree path. It picks the primitive,
    writes `.claude/hooks/<slug>.py` with inline tests (one firing on the offending
    shape, one `Allow()` on a benign neighbor), and runs `uvx capt-hook test`. For a

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

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