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

{capt_hook-3.5.0 → capt_hook-3.7.0}/PKG-INFO

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

{capt_hook-3.5.0 → capt_hook-3.7.0}/captain_hook/cli.py

@@ -155,21 +155,25 @@ def capt_hook_events(path: Path) -> set[str]:
     }
 
 
+def sibling_settings(path: Path) -> Path:
+    return path.parent / ("settings.json" if path.name == "settings.local.json" else "settings.local.json")
+
+
 def merge_settings(
     hooks_dir: str, settings_path: Path, from_source: str = DIST_NAME
 ) -> tuple[dict[str, Any], dict[str, str]]:
     new_hooks: dict[str, list[dict[str, Any]]] = generate_settings(hooks_dir, from_source=from_source)["hooks"]
     existing = json.loads(settings_path.read_text()) if settings_path.exists() else {}
     existing_hooks: dict[str, list[dict[str, Any]]] = existing.get("hooks") or {}
-    committed = capt_hook_events(settings_path.parent / "settings.json")
+    deferred = capt_hook_events(sibling_settings(settings_path))
 
     summary: dict[str, str] = {}
     merged_hooks: dict[str, list[dict[str, Any]]] = {}
     for event in sorted(existing_hooks.keys() | new_hooks.keys()):
         foreign = [g for g in existing_hooks.get(event, []) if not is_captain_hook_group(g)]
         old_own = [g for g in existing_hooks.get(event, []) if is_captain_hook_group(g)]
-        fresh_own = [] if event in committed else new_hooks.get(event, [])
-        if event in committed and (old_own or new_hooks.get(event)):
+        fresh_own = [] if event in deferred else new_hooks.get(event, [])
+        if event in deferred and (old_own or new_hooks.get(event)):
             summary[event] = "deferred"
         elif old_own or fresh_own:
             summary[event] = (
@@ -193,7 +197,7 @@ def write_settings(settings_path: Path, data: dict[str, Any]) -> None:
     os.replace(tmp, settings_path)
 
 
-def print_hook_summary(label: str, summary: dict[str, str]) -> None:
+def print_hook_summary(label: str, summary: dict[str, str], deferred_to: str) -> None:
     by_status: defaultdict[str, list[str]] = defaultdict(list)
     for event, status in summary.items():
         by_status[status].append(event)
@@ -209,15 +213,15 @@ def print_hook_summary(label: str, summary: dict[str, str]) -> None:
     if unchanged := by_status["unchanged"]:
         click.echo(f"  unchanged: {', '.join(unchanged)} (already present)")
     if deferred := by_status["deferred"]:
-        click.echo(f"  deferred to settings.json: {', '.join(deferred)}")
+        click.echo(f"  deferred to {deferred_to}: {', '.join(deferred)}")
 
 
 def regenerate_settings(state: CliState) -> None:
     state.discover()
-    settings_path = state.root / ".claude" / "settings.local.json"
+    settings_path = state.root / ".claude" / "settings.json"
     merged, summary = merge_settings(".claude/hooks", settings_path)
     write_settings(settings_path, merged)
-    print_hook_summary(str(settings_path.relative_to(state.root)), summary)
+    print_hook_summary(str(settings_path.relative_to(state.root)), summary, sibling_settings(settings_path).name)
 
 
 def settings_drift(root: Path) -> set[str]:
@@ -309,7 +313,7 @@ def init_project(root: Path, *, review: bool = True) -> None:
     if not example.exists():
         example.write_text(example_hook_source())
 
-    settings_path = root / ".claude" / "settings.local.json"
+    settings_path = root / ".claude" / "settings.json"
     CliState(root=root, hooks=str(hooks_dir)).discover()
     merged, summary = merge_settings(".claude/hooks", settings_path)
     write_settings(settings_path, merged)
@@ -318,7 +322,7 @@ def init_project(root: Path, *, review: bool = True) -> None:
 
     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_hook_summary(str(settings_path.relative_to(root)), summary, sibling_settings(settings_path).name)
     click.echo()
     click.echo("Claude Code plugin:")
     click.echo(f"  + registered {PLUGIN_ID} in .claude/settings.json (skills install on folder-trust)")
@@ -476,15 +480,15 @@ def run(state: CliState, event: str, async_: bool) -> None:
 )
 @click.pass_obj
 def register_hooks_cmd(state: CliState, hooks_dir: str, dry_run: bool, from_source: str) -> None:
-    """Register captain-hook's event hooks into .claude/settings.local.json."""
+    """Register captain-hook's event hooks into .claude/settings.json."""
     state.discover()
-    settings_path = state.root / ".claude" / "settings.local.json"
+    settings_path = state.root / ".claude" / "settings.json"
     merged, summary = merge_settings(hooks_dir, settings_path, from_source=from_source)
     if dry_run:
         click.echo(json.dumps(merged, indent=2))
         return
     write_settings(settings_path, merged)
-    print_hook_summary(str(settings_path), summary)
+    print_hook_summary(str(settings_path), summary, sibling_settings(settings_path).name)
 
 
 @cli.command()

{capt_hook-3.5.0 → capt_hook-3.7.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.5.0 → capt_hook-3.7.0}/captain_hook/review/cli.py

@@ -57,13 +57,13 @@ def review_wired(hooks: dict[str, Any]) -> bool:
 
 
 def ensure_review_wiring(settings_path: Path) -> bool:
-    from captain_hook.cli import write_settings
+    from captain_hook.cli import sibling_settings, write_settings
 
     existing: dict[str, Any] = json.loads(settings_path.read_text()) if settings_path.exists() else {}
-    committed = settings_path.parent / "settings.json"
-    committed_hooks: dict[str, Any] = (json.loads(committed.read_text()).get("hooks") or {}) if committed.exists() else {}
+    sibling = sibling_settings(settings_path)
+    sibling_hooks: dict[str, Any] = (json.loads(sibling.read_text()).get("hooks") or {}) if sibling.exists() else {}
     hooks: dict[str, Any] = existing.get("hooks") or {}
-    if review_wired(hooks) or review_wired(committed_hooks):
+    if review_wired(hooks) or review_wired(sibling_hooks):
         return False
     group = {"hooks": [{"type": "command", "command": f"uvx {REVIEW_RUN_COMMAND}"}]}
     write_settings(
@@ -126,8 +126,8 @@ def enable(state: CliState) -> None:
     repo = current_repo(state.root)
     watch_repo(repo)
     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 ""))
+    wired = ensure_review_wiring(state.root / ".claude" / "settings.json")
+    click.echo(f"watching {repo}" + (" (SessionEnd hook wired into .claude/settings.json)" if wired else ""))
 
 
 @review.command()

{capt_hook-3.5.0 → capt_hook-3.7.0}/captain_hook/skills/authoring-hooks/SKILL.md

@@ -9,7 +9,7 @@ allowed-tools: Read, Grep, Glob, Write, Edit, Bash(uvx capt-hook:*, capt-hook:*,
 
 capt-hook is a declarative hook framework for Claude Code. Hooks are Python files in
 `.claude/hooks/`, dispatched by `uvx capt-hook run <Event>` entries in
-`.claude/settings.local.json`. Each hook carries inline tests —
+`.claude/settings.json`. Each hook carries inline tests —
 `tests={Input(...): Block() | Warn() | Allow()}` — run with `uvx capt-hook test`. This
 skill turns **one durable correction** (the user's verbatim feedback plus the context it
 fired in) into **one new hook file** `.claude/hooks/<slug>.py`. Full API:
@@ -111,7 +111,7 @@ hook.
 ### 5. Wire settings
 
 Only after Step 4 is green, and only when the hook targets an event no existing
-`.claude/settings.local.json` entry dispatches:
+`.claude/settings.json` entry dispatches:
 
 ```bash
 uvx capt-hook register-hooks

{capt_hook-3.5.0 → capt_hook-3.7.0}/captain_hook/skills/authoring-hooks/references/capt-hook-api.md

@@ -159,7 +159,7 @@ Glob caveat: patterns match the full relative path. `**/*.py` matches `src/main.
 |---|---|
 | `uvx capt-hook init` | Scaffold `.claude/hooks/example.py` + merge settings entries |
 | `uvx capt-hook test [--json]` | Run all inline tests; exit 1 on failure; `--json` = one record per test |
-| `uvx capt-hook register-hooks [--hooks-dir D] [--dry-run] [--from SRC]` | Merge captain-hook's hooks into `.claude/settings.local.json` and write it (`--dry-run` prints without writing) |
+| `uvx capt-hook register-hooks [--hooks-dir D] [--dry-run] [--from SRC]` | Merge captain-hook's hooks into `.claude/settings.json` and write it (`--dry-run` prints without writing) |
 | `uvx capt-hook run <Event> [--async]` | Dispatch one event (Claude Code calls this, not you) |
 | `uvx capt-hook logs [--session S] [--tail N]` | View a recent capt-hook session log |
 

{capt_hook-3.5.0 → capt_hook-3.7.0}/captain_hook/skills/authoring-hooks/references/pitfalls.md

@@ -44,7 +44,7 @@ broken hook.
 
 Wire only commands proven to run: execute the exact settings command by hand first, and
 prefer `uvx capt-hook register-hooks` (which writes known-good entries) over editing
-`.claude/settings.local.json` manually.
+`.claude/settings.json` manually.
 
 ## 4. `uvx capt-hook test` green BEFORE wiring — always
 

{capt_hook-3.5.0 → capt_hook-3.7.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. 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".
+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.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:*)
 ---
@@ -9,7 +9,7 @@ allowed-tools: Read, Grep, Glob, AskUserQuestion, Write, Edit, Bash(uvx capt-hoo
 
 capt-hook is a declarative hook framework for Claude Code. Hooks are Python files in
 `.claude/hooks/`, dispatched by `uvx capt-hook run <Event>` entries in
-`.claude/settings.local.json`. Each hook carries inline tests —
+`.claude/settings.json`. Each hook carries inline tests —
 `tests={Input(...): Block() | Warn() | Allow()}` — run with `uvx capt-hook test`. Hooks are
 always Python regardless of the target repo's language: conditions like `Command` and
 `FilePath` are language-agnostic; only AST `lint` rules are Python-specific. The full
@@ -51,11 +51,11 @@ grep -lq 'capt-hook' .claude/settings.json 2>/dev/null && echo COMMITTED || echo
 
 Then scaffold up front, so the framework and the session reviewer are live before you propose
 anything. Run `uvx capt-hook init` in every repo. It scaffolds `.claude/hooks/`,
-wires `.claude/settings.local.json`, installs the skills, and **enables the session reviewer**
+wires `.claude/settings.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). In a **COMMITTED** repo (a checked-in `.claude/settings.json` already runs
-`uvx capt-hook run …`), `init` defers those events to the committed file instead of re-wiring
-them locally. It prints `deferred to settings.json: …` and never double-fires.
+to stop). When `.claude/settings.local.json` already runs `uvx capt-hook run …` for some events
+(a per-machine setup), `init` defers those events to the local file instead of duplicating them
+into the committed settings. It prints `deferred to settings.local.json: …` and never double-fires.
 
 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,
@@ -154,7 +154,7 @@ after scaffolding). Run:
 uvx capt-hook register-hooks
 ```
 
-`register-hooks` writes `.claude/settings.local.json` directly, merging non-destructively: it
+`register-hooks` writes `.claude/settings.json` directly, merging non-destructively: it
 preserves every non-captain-hook entry, refreshes captain-hook's own, and drops entries for
 events you no longer subscribe to. Add `--dry-run` to print the merged JSON without writing.
 

{capt_hook-3.5.0 → capt_hook-3.7.0}/captain_hook/skills/scanning-sessions/references/review-cli.md

@@ -25,7 +25,7 @@ defaults to the process cwd. This is what spawned you; do not recurse into it.
 ### `review enable` / `review disable`
 
 `enable` marks the current repo watched and wires the SessionEnd hook into
-`.claude/settings.local.json` (idempotent). `disable` stops watching; candidates stay
+`.claude/settings.json` (idempotent). `disable` stops watching; candidates stay
 recorded but never become eligible.
 
 ### `review scan [--transcript <file>]... [--dir <dir>]...`

{capt_hook-3.5.0 → capt_hook-3.7.0}/captain_hook/skills/translating-styleguides/SKILL.md

@@ -166,7 +166,7 @@ and every `Input` runs through the *whole* styleguide. A failing test usually me
 input trips a sibling rule — shrink it to a single construct that trips exactly one rule.
 
 If `style_llm.py` added hooks on new events (e.g. a `Stop`-targeted `llm_nudge`), run
-`uvx capt-hook register-hooks` (it merges non-destructively into `.claude/settings.local.json`
+`uvx capt-hook register-hooks` (it merges non-destructively into `.claude/settings.json`
 and writes it).
 
 ### 8. Enforcement report

{capt_hook-3.5.0 → capt_hook-3.7.0}/pyproject.toml

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