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

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

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

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

@@ -17,8 +17,9 @@ from cc_transcript.ids import SessionId
 from captain_hook.app import _state, load_gitignore, reset
 from captain_hook.context import HookContext, load_transcript
 from captain_hook.dispatch import dispatch
-from captain_hook.loader import discover_hooks
+from captain_hook.loader import CONF_MODULE, discover_hooks, discover_pack
 from captain_hook.log import setup_logging
+from captain_hook.packs import manager
 from captain_hook.review.cli import review
 from captain_hook.session import SessionStore, ensure_session
 from captain_hook.types import Event
@@ -38,6 +39,14 @@ class CliState:
         reset()
         load_gitignore(self.root)
         discover_hooks(self.hooks)
+        resolved, missing = manager.resolve_enabled_packs(self.root)
+        for pack_ in resolved:
+            discover_pack(pack_.entry.name, pack_.path)
+        if missing:
+            print(
+                f"capt-hook: packs not cached: {', '.join(missing)} — run `capt-hook pack update`",
+                file=sys.stderr,
+            )
 
 
 def example_hook_source() -> str:
@@ -200,6 +209,14 @@ def print_hook_summary(label: str, summary: dict[str, str]) -> None:
         print(f"  unchanged: {', '.join(unchanged)} (already present)")
 
 
+def regenerate_settings(state: CliState) -> None:
+    state.discover()
+    settings_path = state.root / ".claude" / "settings.local.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)
+
+
 def settings_drift(root: Path) -> set[str]:
     settings = [p for name in ("settings.json", "settings.local.json") if (p := root / ".claude" / name).exists()]
     if not settings:
@@ -296,8 +313,7 @@ def init_project(root: Path) -> None:
         example.write_text(example_hook_source())
 
     settings_path = root / ".claude" / "settings.local.json"
-    reset()
-    discover_hooks(str(hooks_dir))
+    CliState(root=root, hooks=str(hooks_dir)).discover()
     merged, summary = merge_settings(".claude/hooks", settings_path)
     write_settings(settings_path, merged)
 
@@ -505,6 +521,75 @@ def skills_install(state: CliState, force: bool) -> None:
         click.echo(f"  {status} {name}")
 
 
+@cli.group()
+def pack() -> None:
+    """Manage capt-hook packs — named collections of hooks (builtin or from GitHub)."""
+
+
+@pack.command(name="add")
+@click.argument("target")
+@click.pass_obj
+def pack_add(state: CliState, target: str) -> None:
+    """Enable a builtin pack by name, or an external pack as github:owner/repo[@ref]."""
+    try:
+        entry = (
+            manager.BuiltinPack(name=target)
+            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
+    click.echo(f"  added {entry.name}")
+    regenerate_settings(state)
+
+
+@pack.command(name="list")
+@click.pass_obj
+def pack_list(state: CliState) -> None:
+    """List the packs enabled in .claude/hooks/packs.toml."""
+    resolved, missing = manager.resolve_enabled_packs(state.root)
+    for r in resolved:
+        match r.entry:
+            case manager.BuiltinPack():
+                kind, ref = "builtin", "-"
+            case manager.ExternalPack(source=source, commit=commit):
+                kind, ref = "github", f"{source.ref or 'HEAD'}@{commit[:7]}"
+        count = sum(1 for p in r.path.glob("*.py") if not p.stem.startswith("_") and p.stem != CONF_MODULE)
+        click.echo(f"  {r.entry.name:24} {kind:8} {ref:20} v{r.manifest.version:8} {count} hooks")
+    for name in missing:
+        click.echo(f"  {name:24} github   (not cached — run `capt-hook pack update`)")
+
+
+@pack.command(name="remove")
+@click.argument("name")
+@click.pass_obj
+def pack_remove(state: CliState, name: str) -> None:
+    """Disable a pack (leaves its content-addressed cache intact)."""
+    try:
+        manager.delete_entry(manager.packs_toml_path(state.root), name)
+    except manager.PackError as e:
+        raise click.ClickException(str(e)) from e
+    click.echo(f"  removed {name}")
+    regenerate_settings(state)
+
+
+@pack.command(name="update")
+@click.argument("name", required=False)
+@click.pass_obj
+def pack_update(state: CliState, name: str | None) -> None:
+    """Re-resolve external packs' refs to fresh commits and re-fetch."""
+    path = manager.packs_toml_path(state.root)
+    for entry in manager.read_entries(path):
+        match entry:
+            case manager.ExternalPack(name=n, source=source) if name in (None, n):
+                manager.upsert_entry(path, fresh := manager.fetch_pack(source).entry)
+                click.echo(f"  updated {n} -> {fresh.commit[:7]}")
+            case manager.BuiltinPack(name=n) if name == n:
+                click.echo(f"  {n} is builtin; it tracks the installed capt-hook version")
+    regenerate_settings(state)
+
+
 cli.add_command(review)
 
 main = cli

{capt_hook-3.1.0 → capt_hook-3.2.0}/captain_hook/loader.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 import importlib
+import importlib.machinery
 import importlib.util
 import pkgutil
+import re
 import sys
 from pathlib import Path
 from types import ModuleType
@@ -14,6 +16,7 @@ from pydantic_settings import BaseSettings
 from captain_hook.app import State, _state
 
 CONF_MODULE = "conf"
+PACK_PACKAGE_PREFIX = "captain_hook._packs"
 
 
 def build_hook_settings(module: ModuleType) -> BaseSettings | ModuleType:
@@ -61,3 +64,18 @@ def discover_hooks(hooks_dir: str | Path, state: State | None = None) -> None:
 
     for fqn in sorted(all_modules - {f"{pkg}.{CONF_MODULE}"}):
         import_or_reload(fqn, fresh_this_pass)
+
+
+def import_pack_module(fqn: str, path: Path) -> ModuleType:
+    loader = importlib.machinery.SourceFileLoader(fqn, str(path))
+    module = importlib.util.module_from_spec(importlib.machinery.ModuleSpec(fqn, loader, origin=str(path)))
+    sys.modules[fqn] = module
+    loader.exec_module(module)
+    return module
+
+
+def discover_pack(name: str, pack_dir: Path) -> None:
+    pkg = f"{PACK_PACKAGE_PREFIX}.{re.sub(r'\W', '_', name)}"
+    for path in sorted(pack_dir.glob("*.py")):
+        if not (path.stem.startswith("_") or path.stem == CONF_MODULE):
+            import_pack_module(f"{pkg}.{path.stem}", path)

capt_hook-3.2.0/captain_hook/packs/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

capt_hook-3.2.0/captain_hook/packs/general/capt-hook.toml

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

capt_hook-3.2.0/captain_hook/packs/general/commands.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from captain_hook import (
+    Allow,
+    BaseHookEvent,
+    Block,
+    CustomCondition,
+    Event,
+    Input,
+    Tool,
+    UsedSkill,
+    block_command,
+    hook,
+    nudge,
+)
+
+block_command(
+    ["git", "stash"],
+    reason="git stash is not allowed",
+    hint="Commit your changes to a branch instead",
+    tests={
+        Input(command="git stash"): Block(),
+        Input(command="git stash pop"): Block(),
+        Input(command="git status"): Allow(),
+    },
+)
+
+
+class UnpipedGrep(CustomCondition):
+    """True when a `grep` command does not consume piped input.
+
+    Allows the stream-filter idiom (`… | grep`) while still blocking grep used
+    for file searching, whether standalone, heading a pipe, or in a `&&`/`;` chain.
+    """
+
+    def check(self, evt: BaseHookEvent) -> bool:
+        if not (cl := evt.command_line):
+            return False
+        return any(
+            cmd.matches(r"^grep\b") and (i == 0 or cl.parts[i - 1][1] != "|") for i, (cmd, _) in enumerate(cl.parts)
+        )
+
+
+hook(
+    Event.PreToolUse,
+    only_if=[Tool("Bash"), UnpipedGrep()],
+    message="BLOCKED: Use ripgrep (rg) instead of grep. Replace grep with rg, or use the built-in Grep tool.",
+    block=True,
+    tests={
+        Input(command="grep -rn foo src/"): Block(),
+        Input(command="ls | grep foo"): Allow(),
+        Input(command="cat x | grep foo | sort"): Allow(),
+        Input(command="grep foo file.py | wc -l"): Block(),
+        Input(command="grep foo a && echo done"): Block(),
+        Input(command="git log --grep=fix"): Allow(),
+        Input(command='git log --grep "fix bug"'): Allow(),
+    },
+)
+
+# Requires the codex plugin (/plugin install codex@skills from yasyf/cc-skills).
+# Delete this nudge if you don't use Codex.
+nudge(
+    """
+    Multiple tool failures detected without a /codex invocation. After 2 failed
+    approaches, get a second opinion from `/codex` before attempting a 3rd —
+    Codex catches errors that Claude may miss.
+    """,
+    skip_if=[UsedSkill("codex|codex:codex")],
+    events=Event.PostToolUseFailure,
+    when=lambda evt: evt.ctx.turn.count_failures() >= 2 and not evt.ctx.t.has_command(r"codex"),
+)

capt_hook-3.2.0/captain_hook/packs/general/docs.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from captain_hook import Allow, FilePath, Input, Tool, UsedSkill, Warn, nudge
+
+# Advisory reminder to consult the writing-docs skill (and run slop-cop) before
+# editing documentation. Fires once per session on the first doc edit and stands
+# down once the skill has been used. Advisory only, so it never blocks an edit.
+#
+# The scaffolded .claude/settings.json registers the yasyf/cc-skills marketplace
+# and enables writing-docs@skills, so the skill (and the skip_if check) activates
+# when the folder is trusted — no manual /plugin install.
+nudge(
+    "You're editing documentation. Consult the writing-docs skill first for the "
+    "Diataxis modes, voice rules, and code-sample rules, then run "
+    "`slop-cop check <file> --lang=markdown` to catch prose tells before you finish.",
+    only_if=[Tool("Write|Edit"), FilePath("**/*.md", "**/*.qmd", "docs/**", "README.md")],
+    skip_if=[UsedSkill("writing-docs|writing-docs:writing-docs")],
+    max_fires=1,
+    tests={
+        Input(tool="Write", file="docs/guide/x.qmd", content="# X"): Warn(pattern="writing-docs"),
+        Input(tool="Edit", file="src/app.py", content="x = 1"): Allow(),
+    },
+)

capt_hook-3.2.0/captain_hook/packs/general/plans.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from captain_hook import Allow, BaseHookEvent, Block, CustomCondition, Event, Input, Tool, hook
+
+
+class RewritingExistingPlan(CustomCondition):
+    """True when a Write targets a plan file (`.md` under `plans/` or `specs/`) that was
+    already written earlier this session, with no new plan cycle (EnterPlanMode) since the
+    last Write to it.
+
+    Reads from ``evt.ctx.prior`` (the window before the current turn's last exchange) so the
+    pending Write being evaluated is never itself counted as the prior edit. A write to the
+    file this session already implies it exists, so no filesystem check is needed.
+    """
+
+    def check(self, evt: BaseHookEvent) -> bool:
+        fp = evt.file
+        if not fp or fp.suffix != ".md" or not fp.under("plans/", "specs/"):
+            return False
+        if not evt.ctx.prior.has_edit_to(str(fp)):
+            return False
+        return not evt.ctx.prior.after(tool="Write", file=str(fp)).has_tool("EnterPlanMode")
+
+
+hook(
+    Event.PreToolUse,
+    only_if=[Tool("Write"), RewritingExistingPlan()],
+    message=(
+        "This plan file was already written in this planning session. Use the Edit tool "
+        "to make incremental changes instead of rewriting the entire plan with Write."
+    ),
+    block=True,
+    tests={
+        # Rewriting a plan already written this session, no new plan cycle since -> block.
+        Input(
+            tool="Write",
+            file="/x/plans/p.md",
+            content="# Plan v2",
+            transcript=[
+                {"type": "assistant", "message": {"content": [
+                    {"type": "tool_use", "name": "Write", "id": "w0",
+                     "input": {"file_path": "/x/plans/p.md", "content": "# Plan v1"}}]}},
+                {"type": "assistant", "message": {"content": [
+                    {"type": "tool_use", "name": "Write", "id": "w1",
+                     "input": {"file_path": "/x/plans/p.md", "content": "# Plan v2"}}]}},
+            ],
+        ): Block(),
+        # A new plan cycle (EnterPlanMode) started since the last write -> allow the rewrite.
+        Input(
+            tool="Write",
+            file="/x/plans/p.md",
+            content="# Plan v2",
+            transcript=[
+                {"type": "assistant", "message": {"content": [
+                    {"type": "tool_use", "name": "Write", "id": "w0",
+                     "input": {"file_path": "/x/plans/p.md", "content": "# Plan v1"}}]}},
+                {"type": "assistant", "message": {"content": [
+                    {"type": "tool_use", "name": "EnterPlanMode", "id": "p1", "input": {}}]}},
+                {"type": "assistant", "message": {"content": [
+                    {"type": "tool_use", "name": "Write", "id": "w1",
+                     "input": {"file_path": "/x/plans/p.md", "content": "# Plan v2"}}]}},
+            ],
+        ): Allow(),
+        # First write of this plan this session -> allow.
+        Input(tool="Write", file="/x/plans/p.md", content="# Plan", transcript=[]): Allow(),
+        # Not a plan file -> allow.
+        Input(tool="Write", file="/x/src/main.py", content="x = 1"): Allow(),
+    },
+)

capt_hook-3.2.0/captain_hook/packs/general/prompts.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from captain_hook import Allow, Content, Input, Tool, UsedSkill, Warn, nudge
+
+PROMPT_MARKERS = (
+    r"<instruction>|<system>|<examples>|<success_criteria>|<output_format>|"
+    r"<key_constraints>|<reasoning_framework>|<action_rules>|<preferred_patterns>|"
+    r"<persona>|<role>|<tool_persistence>|<completeness_contract>|<verification_loop>|"
+    r"You are an?\b|Your task is to\b|You will be provided with\b|"
+    r"def\s+\w*prompt\s*\(|(?i:\b(?:system|developer) prompt\b)|"
+    r"messages\s*=\s*\[|"
+    r"""["']role["']\s*:\s*["'](?:system|user|assistant|developer)["']"""
+)
+
+nudge(
+    "You're editing LLM prompt content. The `llm-prompts` skill covers positive framing, "
+    "XML structure, the prompting principles, and current per-provider model behaviors "
+    "(Claude, GPT-5.x, Gemini) — consult it before writing prompts. After editing, run "
+    "`/slop-cop-check` on the file to surface LLM-generated writing tells (overused "
+    "intensifiers, hedge stacks, em-dash pivots, throat-clearing) and revise any real hits.",
+    only_if=[Tool("Edit|Write"), Content(PROMPT_MARKERS, project_only=False)],
+    skip_if=[
+        UsedSkill("llm-prompts|llm-prompts:llm-prompts"),
+        UsedSkill("slop-cop:slop-cop-check|slop-cop:slop-cop-prose|slop-cop-check|slop-cop-prose"),
+    ],
+    tests={
+        Input(
+            file="agent.py", content='messages = [{"role": "system", "content": "You are a helpful assistant."}]\n'
+        ): Warn(),
+        Input(file="prompt.md", content="<instruction>\nSummarize the document.\n</instruction>\n"): Warn(),
+        Input(file="util.py", content="def add(a, b):\n    return a + b\n"): Allow(),
+    },
+)

capt_hook-3.2.0/captain_hook/packs/general/review.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from captain_hook import Allow, BaseHookEvent, Block, CustomCondition, Event, Input, Waiting, gate
+
+# Prose and config file extensions that shouldn't, on their own, demand a code-review pass.
+# Tailor this (and the excluded dirs below) to scope what counts as "source" for your repo.
+NON_SOURCE_SUFFIXES = (
+    ".md", ".mdx", ".rst", ".txt", ".json", ".toml",
+    ".yaml", ".yml", ".ini", ".cfg", ".lock",
+)
+
+
+class EditedSource(CustomCondition):
+    """True when the session edited a non-test source file (docs and config excluded)."""
+
+    def check(self, evt: BaseHookEvent) -> bool:
+        return any(
+            not f.is_test
+            and f.suffix not in NON_SOURCE_SUFFIXES
+            and not f.under("docs", ".claude", ".github")
+            for f in evt.ctx.t.tool_calls.named("Edit|Write").files()
+        )
+
+
+gate(
+    "You changed source files but haven't done a review pass. Before stopping, review your "
+    "changes for correctness and against STYLEGUIDE.md, and fix any issues in the code you "
+    "wrote. See: STYLEGUIDE.md.",
+    only_if=[EditedSource()],
+    skip_if=[Waiting()],
+    events=Event.Stop,
+    tests={
+        Input(transcript=[
+            {"type": "assistant", "message": {"content": [
+                {"type": "tool_use", "name": "Edit", "id": "e1",
+                 "input": {"file_path": "src/app.py", "old_string": "a", "new_string": "b"}}]}},
+        ]): Block(),
+        Input(transcript=[
+            {"type": "assistant", "message": {"content": [
+                {"type": "tool_use", "name": "Edit", "id": "e1",
+                 "input": {"file_path": "README.md", "old_string": "a", "new_string": "b"}}]}},
+        ]): Allow(),
+    },
+)