capt-hook 6.3.0__tar.gz → 6.5.0__tar.gz

capt_hook-6.5.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: capt-hook
+Version: 6.5.0
+Summary: Stop repeating yourself to Claude.
+Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
+Author: Yasyf Mohamedali
+Author-email: Yasyf Mohamedali <yasyfm@gmail.com>
+License-Expression: PolyForm-Noncommercial-1.0.0
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Dist: cc-transcript>=7.1,<8
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: tree-sitter>=0.24
+Requires-Dist: tree-sitter-bash>=0.23
+Requires-Dist: ast-grep-py>=0.39,<1
+Requires-Dist: funcy>=2.0
+Requires-Dist: spacy>=3.7
+Requires-Dist: click>=8
+Requires-Dist: rich>=13
+Requires-Dist: orjsonl>=1.0
+Requires-Dist: wn>=1.1.0
+Requires-Dist: lazy-object-proxy>=1.12.0
+Requires-Dist: filelock>=3
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: spawnllm>=0.5.2,<0.6
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
+Requires-Dist: pyright>=1.1 ; extra == 'dev'
+Requires-Dist: pyyaml>=6 ; extra == 'dev'
+Requires-Dist: ruff>=0.8 ; extra == 'dev'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/yasyf/captain-hook
+Project-URL: Documentation, https://yasyf.github.io/captain-hook/
+Project-URL: Repository, https://github.com/yasyf/captain-hook
+Project-URL: Issues, https://github.com/yasyf/captain-hook/issues
+Project-URL: Changelog, https://github.com/yasyf/captain-hook/blob/main/CHANGELOG.md
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# ![captain-hook](https://github.com/yasyf/captain-hook/raw/main/docs/assets/readme-banner.webp)
+
+**Stop repeating yourself to Claude.** captain-hook mines your transcripts for the corrections you keep giving and opens PRs that turn each one into a typed, tested Python hook.
+
+[![CI](https://github.com/yasyf/captain-hook/actions/workflows/ci.yml/badge.svg)](https://github.com/yasyf/captain-hook/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/capt-hook)](https://pypi.org/project/capt-hook/)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm--Noncommercial--1.0.0-blue)](https://github.com/yasyf/captain-hook/blob/main/LICENSE)
+
+## Get started
+
+```bash
+uvx capt-hook init
+```
+
+`init` scaffolds `.claude/hooks/`, wires Claude Code's settings, and arms the session reviewer. One `block_command` later, a force-push dies at `PreToolUse` and the hook's inline tests run green:
+
+<img src="https://github.com/yasyf/captain-hook/raw/main/docs/assets/demo.png" alt="Terminal running 'uvx capt-hook test' — a hook blocks git push --force and both inline tests pass" width="700">
+
+Driving with an agent? Paste this:
+
+```text
+/plugin marketplace add yasyf/captain-hook
+/plugin install captain-hook@captain-hook
+```
+
+<details>
+<summary>Prefer a prompt over the plugin?</summary>
+
+```text
+Run `uvx capt-hook init` in this repo, write one hook that blocks force-pushes,
+and verify it with `uvx capt-hook test`. Read https://yasyf.github.io/captain-hook/
+if you get stuck.
+```
+
+</details>
+
+---
+
+## Use cases
+
+### Block force-push and rm -rf before they run
+
+One bad Bash call rewrites shared history or eats a directory, and by the time you spot it in the transcript it already ran. Declare the block once, tests inline:
+
+```python
+# .claude/hooks/safety.py
+from captain_hook import Allow, Block, Input, block_command
+
+block_command(
+    ["git", "push", "--force"],
+    reason="Force-pushing rewrites shared history",
+    hint="Use `git push --force-with-lease` instead",
+    tests={
+        Input(command="git push --force"): Block(),
+        Input(command="git push origin main"): Allow(),
+    },
+)
+```
+
+The next `git push --force` never executes: the agent sees `BLOCKED: Force-pushing rewrites shared history` plus the hint, and reaches for `--force-with-lease` instead. `rm -rf` is one more `block_command` away.
+
+### Turn repeated corrections into rules Claude can't forget
+
+You've typed "use uv, not pip" in a dozen sessions, and session thirteen makes the same mistake. After `init`, the session reviewer reads each transcript as the session ends, keeps the corrections that are standing rules, and — once a pattern proves itself across sessions — opens a PR that codifies it as a hook. Watch the pipeline:
+
+```bash
+uvx capt-hook status
+```
+
+The dashboard lists every correction it's tracking, staged from first sighting to open PR. You review the PR like any other; merged hooks enforce the rule from then on.
+
+### Gate "done" until the tests actually pass
+
+The agent declares victory while the suite is red. A Stop gate holds the line:
+
+```python
+# .claude/hooks/quality.py
+from captain_hook import RanCommand, TouchedFile, gate
+
+gate(
+    "You edited Python files but never ran the tests. Run `uv run pytest` before finishing.",
+    only_if=[TouchedFile("**/*.py")],
+    skip_if=[RanCommand(r"\bpytest\b")],
+)
+```
+
+The agent can't end the turn until a pytest run shows up in the transcript, and the gate stands down on its own once one does.
+
+## More in the docs
+
+- **Session reviewer** — the full corrections lifecycle, from transcript to merged hook PR — [guide](https://yasyf.github.io/captain-hook/docs/guide/session-reviewer.html)
+- **Conditions** — typed filters over tools, files, commands, and transcript history — [guide](https://yasyf.github.io/captain-hook/docs/guide/conditions.html)
+- **LLM hooks** — gate on a model's verdict when a regex can't decide — [guide](https://yasyf.github.io/captain-hook/docs/guide/llm-hooks.html)
+- **Workflows** — multi-step Stop gates with artifact checks and checklists — [guide](https://yasyf.github.io/captain-hook/docs/guide/workflows.html)
+- **Packs** — the shipped `general`, `python`, and `go` hook packs — [guide](https://yasyf.github.io/captain-hook/docs/guide/packs.html)
+- **Testing** — run `uvx capt-hook test --json` in CI so a regressed hook fails the build — [guide](https://yasyf.github.io/captain-hook/docs/guide/testing.html)
+
+Read the [docs](https://yasyf.github.io/captain-hook/) for the full guide. Licensed under [PolyForm Noncommercial 1.0.0](https://github.com/yasyf/captain-hook/blob/main/LICENSE), free for noncommercial use.

capt_hook-6.5.0/README.md

@@ -0,0 +1,98 @@
+# ![captain-hook](https://github.com/yasyf/captain-hook/raw/main/docs/assets/readme-banner.webp)
+
+**Stop repeating yourself to Claude.** captain-hook mines your transcripts for the corrections you keep giving and opens PRs that turn each one into a typed, tested Python hook.
+
+[![CI](https://github.com/yasyf/captain-hook/actions/workflows/ci.yml/badge.svg)](https://github.com/yasyf/captain-hook/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/capt-hook)](https://pypi.org/project/capt-hook/)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm--Noncommercial--1.0.0-blue)](https://github.com/yasyf/captain-hook/blob/main/LICENSE)
+
+## Get started
+
+```bash
+uvx capt-hook init
+```
+
+`init` scaffolds `.claude/hooks/`, wires Claude Code's settings, and arms the session reviewer. One `block_command` later, a force-push dies at `PreToolUse` and the hook's inline tests run green:
+
+<img src="https://github.com/yasyf/captain-hook/raw/main/docs/assets/demo.png" alt="Terminal running 'uvx capt-hook test' — a hook blocks git push --force and both inline tests pass" width="700">
+
+Driving with an agent? Paste this:
+
+```text
+/plugin marketplace add yasyf/captain-hook
+/plugin install captain-hook@captain-hook
+```
+
+<details>
+<summary>Prefer a prompt over the plugin?</summary>
+
+```text
+Run `uvx capt-hook init` in this repo, write one hook that blocks force-pushes,
+and verify it with `uvx capt-hook test`. Read https://yasyf.github.io/captain-hook/
+if you get stuck.
+```
+
+</details>
+
+---
+
+## Use cases
+
+### Block force-push and rm -rf before they run
+
+One bad Bash call rewrites shared history or eats a directory, and by the time you spot it in the transcript it already ran. Declare the block once, tests inline:
+
+```python
+# .claude/hooks/safety.py
+from captain_hook import Allow, Block, Input, block_command
+
+block_command(
+    ["git", "push", "--force"],
+    reason="Force-pushing rewrites shared history",
+    hint="Use `git push --force-with-lease` instead",
+    tests={
+        Input(command="git push --force"): Block(),
+        Input(command="git push origin main"): Allow(),
+    },
+)
+```
+
+The next `git push --force` never executes: the agent sees `BLOCKED: Force-pushing rewrites shared history` plus the hint, and reaches for `--force-with-lease` instead. `rm -rf` is one more `block_command` away.
+
+### Turn repeated corrections into rules Claude can't forget
+
+You've typed "use uv, not pip" in a dozen sessions, and session thirteen makes the same mistake. After `init`, the session reviewer reads each transcript as the session ends, keeps the corrections that are standing rules, and — once a pattern proves itself across sessions — opens a PR that codifies it as a hook. Watch the pipeline:
+
+```bash
+uvx capt-hook status
+```
+
+The dashboard lists every correction it's tracking, staged from first sighting to open PR. You review the PR like any other; merged hooks enforce the rule from then on.
+
+### Gate "done" until the tests actually pass
+
+The agent declares victory while the suite is red. A Stop gate holds the line:
+
+```python
+# .claude/hooks/quality.py
+from captain_hook import RanCommand, TouchedFile, gate
+
+gate(
+    "You edited Python files but never ran the tests. Run `uv run pytest` before finishing.",
+    only_if=[TouchedFile("**/*.py")],
+    skip_if=[RanCommand(r"\bpytest\b")],
+)
+```
+
+The agent can't end the turn until a pytest run shows up in the transcript, and the gate stands down on its own once one does.
+
+## More in the docs
+
+- **Session reviewer** — the full corrections lifecycle, from transcript to merged hook PR — [guide](https://yasyf.github.io/captain-hook/docs/guide/session-reviewer.html)
+- **Conditions** — typed filters over tools, files, commands, and transcript history — [guide](https://yasyf.github.io/captain-hook/docs/guide/conditions.html)
+- **LLM hooks** — gate on a model's verdict when a regex can't decide — [guide](https://yasyf.github.io/captain-hook/docs/guide/llm-hooks.html)
+- **Workflows** — multi-step Stop gates with artifact checks and checklists — [guide](https://yasyf.github.io/captain-hook/docs/guide/workflows.html)
+- **Packs** — the shipped `general`, `python`, and `go` hook packs — [guide](https://yasyf.github.io/captain-hook/docs/guide/packs.html)
+- **Testing** — run `uvx capt-hook test --json` in CI so a regressed hook fails the build — [guide](https://yasyf.github.io/captain-hook/docs/guide/testing.html)
+
+Read the [docs](https://yasyf.github.io/captain-hook/) for the full guide. Licensed under [PolyForm Noncommercial 1.0.0](https://github.com/yasyf/captain-hook/blob/main/LICENSE), free for noncommercial use.

{capt_hook-6.3.0 → capt_hook-6.5.0}/captain_hook/cli.py

@@ -501,7 +501,9 @@ def run_tests(json_output: bool = False) -> None:
 @click.pass_context
 def cli(ctx: click.Context, hooks: str | None, root_path: str | None) -> None:
     """Captain Hook — declarative hook framework for Claude Code lifecycle events."""
-    root = Path(root_path) if root_path else Path(env) if (env := os.environ.get("CLAUDE_PROJECT_DIR")) else Path.cwd()
+    from captain_hook.settings import resolve_project_dir
+
+    root = Path(root_path) if root_path else Path(p) if (p := resolve_project_dir()) else Path.cwd()
     ctx.obj = CliState(root=root, hooks=hooks or str(root / ".claude" / "hooks"))
 
 

{capt_hook-6.3.0 → capt_hook-6.5.0}/captain_hook/context.py

@@ -21,6 +21,7 @@ from spawnllm.proc import run_cli
 from captain_hook.classifiers import detect
 from captain_hook.prompt import Prompt
 from captain_hook.session import SessionStore
+from captain_hook.settings import resolve_project_dir
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -78,7 +79,7 @@ def lift_session(events: Sequence[TranscriptEvent], *, path: Path | None = None)
     from captain_hook.app import _state
 
     classifier = _state.classifier or detect(
-        cwd=os.environ.get("CLAUDE_PROJECT_DIR") or os.environ.get("FACTORY_PROJECT_DIR"),
+        cwd=resolve_project_dir(),
         transcript_path=str(path) if path else None,
         events=events,
     )
@@ -185,7 +186,7 @@ class HookContext:
                 input=input,
                 timeout=timeout,
                 env=os.environ | (env or {}),
-                cwd=os.environ.get("CLAUDE_PROJECT_DIR") or os.environ.get("FACTORY_PROJECT_DIR"),
+                cwd=resolve_project_dir(),
             )
         except (OSError, subprocess.SubprocessError):
             if throw:
@@ -309,7 +310,7 @@ class HookContext:
     ) -> str | BaseModel:
         diff_text = self.diff("uncommitted" if diff is True else diff) if diff else None
         prompt = self.assemble_prompt(template, args, kwargs, transcript=transcript, diff_text=diff_text)
-        cwd = os.environ.get("CLAUDE_PROJECT_DIR") or os.environ.get("FACTORY_PROJECT_DIR")
+        cwd = resolve_project_dir()
         if response_model is not None:
             return extract_sync(
                 prompt, response_model, specialty=specialty, model=model, agent=agent, cwd=cwd, timeout=timeout

{capt_hook-6.3.0 → capt_hook-6.5.0}/captain_hook/durable.py

@@ -26,13 +26,11 @@ if TYPE_CHECKING:
 
 Scope = Literal["project", "global"]
 
-DURABLE_ROOT_OVERRIDE: list[Path] = []
-
 
 def durable_root() -> Path:
     from captain_hook.settings import resolve_state_dir
 
-    return DURABLE_ROOT_OVERRIDE[-1] if DURABLE_ROOT_OVERRIDE else resolve_state_dir() / "hooks" / "durable"
+    return resolve_state_dir() / "hooks" / "durable"
 
 
 def project_key(repo_root: Path) -> str:
@@ -98,11 +96,6 @@ class DurableStore:
         if model not in cls.TRACKED:
             cls.TRACKED.append(model)
 
-    @classmethod
-    def untrack(cls, model: type[BaseModel]) -> None:
-        if model in cls.TRACKED:
-            cls.TRACKED.remove(model)
-
     @classmethod
     def tracked_models(cls) -> Sequence[type[BaseModel]]:
         return tuple(cls.TRACKED)

{capt_hook-6.3.0 → capt_hook-6.5.0}/captain_hook/loader.py

@@ -13,7 +13,7 @@ from typing import TYPE_CHECKING
 
 from loguru import logger
 
-from captain_hook.app import State, _state, on
+from captain_hook.app import _state, on
 from captain_hook.settings import build_settings
 from captain_hook.types import Event
 
@@ -47,8 +47,7 @@ def import_or_reload(fqn: str, fresh_this_pass: set[str]) -> ModuleType:
     return mod
 
 
-def discover_hooks(hooks_dir: str | Path, state: State | None = None) -> None:
-    target = state or _state
+def discover_hooks(hooks_dir: str | Path) -> None:
     hooks_path = Path(hooks_dir).resolve()
     if str(hooks_path.parent) not in sys.path:
         sys.path.insert(0, str(hooks_path.parent))
@@ -60,9 +59,9 @@ def discover_hooks(hooks_dir: str | Path, state: State | None = None) -> None:
 
     if CONF_MODULE in top_level:
         conf_module = import_or_reload(f"{pkg}.{CONF_MODULE}", fresh_this_pass)
-        target.settings = build_settings(conf_module)
+        _state.settings = build_settings(conf_module)
         if classifier := getattr(conf_module, "classifier", None):
-            target.classifier = classifier
+            _state.classifier = classifier
 
     all_modules = {
         info.name
@@ -80,7 +79,7 @@ def discover_hooks(hooks_dir: str | Path, state: State | None = None) -> None:
             import_or_reload(fqn, fresh_this_pass)
         except Exception as exc:
             logger.bind(module=fqn).opt(exception=True).warning("skipped unloadable hook module")
-            target.load_errors.append((fqn, exc))
+            _state.load_errors.append((fqn, exc))
 
 
 def ensure_pack_package(fqn: str, search_paths: list[str]) -> ModuleType:

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

@@ -0,0 +1,5 @@
+name = "general"
+version = "0.10.0"
+description = "Language-agnostic guards: git/command safety, doc & prompt nudges, task & plan discipline, code-review + docs-freshness gates, and a detour check-in nudge."
+hooks = "."
+nlp = true

capt_hook-6.5.0/captain_hook/packs/general/detours.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+from captain_hook import (
+    Allow,
+    Event,
+    Input,
+    Signal,
+    Signals,
+    Tool,
+    Warn,
+    llm_nudge,
+)
+
+llm_nudge(
+    """You are a senior engineer watching another engineer ("the agent") mid-task. You are
+running in agent mode in the project's working directory, with read tools. Your one job:
+decide whether the agent has veered onto an UNREQUESTED DETOUR — side work nobody asked
+for — without checking in first.
+
+Read first, judge second:
+- The session transcript is rendered above inside `<transcript path="...">`; long content is
+  clipped (you'll see `…(+Nch)` markers). From the full history (prefer `cc-transcript
+  show`/`grep`; else read the file) establish: (1) what was actually ASKED — the user's
+  original request plus any later redirections or standing permissions — and (2) what the
+  agent is doing RIGHT NOW — the just-run tool call and the last few assistant messages.
+
+Discriminator: the current work is either (a) the requested task, (b) a necessary
+prerequisite of it (the task cannot land or be verified without it), or (c) authorized —
+the user said some form of "also…", "while you're there…", "fix anything you find", or it
+is a small stewardship fix inside code the task already touches. Any of those -> fire=false.
+Otherwise — the agent noticed something adjacent and started acting on it without surfacing
+it — fire=true.
+
+Detour tells (lean fire=true): "while I'm here" / "might as well" / "let me also" followed
+by edits to files the task doesn't need; fixing or refactoring code the request never
+mentioned and the task doesn't depend on; a cleanup sweep starting mid-task; chasing a side
+mystery at length while the requested work sits unfinished.
+
+Do NOT fire when: the side work blocks the task (a broken build or failing test the change
+trips over); it's a small stewardship fix in a file already being edited for the task; the
+user pre-authorized it; the agent is gathering context it needs; or the agent already
+surfaced the discovery and offered options instead of acting.
+
+<examples>
+<example fire="true">
+Asked: "rename the config flag". Agent: "While I'm here, the retry logic in client.py looks
+wrong — let me fix that too", then edits client.py.
+Unrequested fix in a file the rename never touches.
+</example>
+<example fire="true">
+Asked: "add a --json flag". Agent: "I also noticed the error handling is inconsistent
+across commands; I'll clean that up as well", then starts a multi-file sweep.
+Scope expansion nobody asked for, no options offered.
+</example>
+<example fire="false">
+Asked: "fix the failing test". Agent: "The fixture helper it calls has the actual bug —
+fixing that first."
+A prerequisite: the requested fix cannot land without it.
+</example>
+<example fire="false">
+User said "clean up anything you find along the way"; agent fixes a stale docstring in a
+file it was already editing.
+Pre-authorized stewardship.
+</example>
+<example fire="false">
+Agent: "I noticed X while working on Y — options: (1) finish Y and file X as a follow-up,
+(2) fix X now, (3) ignore it. Which?"
+Already surfacing options instead of acting.
+</example>
+</examples>
+
+When uncertain, return fire=false. A missed detour costs one review comment; a false alarm
+on legitimate work teaches the agent to ignore this nudge. Fire only when the current action
+is clearly outside both the request and its prerequisites. Put your reasoning (under 50
+words, naming the detour and the requested task) in `reasoning`.""",
+    message=lambda r: (
+        f"This looks like a detour — side work nobody asked for. {r.reasoning} "
+        "Stop and check in before acting: say what you noticed, then propose 2-4 concrete "
+        "options (finish the task and file this as a follow-up; pause and fix it now; ignore "
+        "it) and let the user pick — or, if you are a delegated agent, stop and return early "
+        "with findings plus options for your orchestrator instead of improvising. "
+        "See: AGENTS.md § Ask Before Assuming."
+    ),
+    only_if=[Tool("Edit|Write|MultiEdit|NotebookEdit|Bash")],
+    events=Event.PostToolUse,
+    signals=Signals(
+        [
+            Signal(pattern=r"(?i)\bwhile (?:I'm|I am|we're|we are) (?:here|at it|in (?:here|there))\b", weight=2),
+            Signal(pattern=r"(?i)\bmight as well\b", weight=2),
+            Signal(pattern=r"(?i)\b(?:let me|I'll|I will) also\b", weight=2),
+            Signal(pattern=r"(?i)\bas a bonus\b", weight=2),
+            Signal(pattern=r"(?i)\bI (?:also )?noticed\b", weight=1),
+            Signal(pattern=r"(?i)\b(?:unrelated|a side note|tangent)\b", weight=1),
+            Signal(pattern=r"(?i)\bone more thing\b", weight=1),
+            Signal(pattern=r"(?i)\bquick(?:ly)? (?:fix|clean|tidy|refactor)\w*\b", weight=1),
+        ],
+        threshold=2,
+        window=8,
+    ),
+    tests={
+        Input(
+            file="client.py",
+            content="retry = 3\n",
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {"type": "text", "text": "While I'm here, the retry logic looks wrong — fixing it too."}
+                        ]
+                    },
+                }
+            ],
+        ): Warn(pattern="detour"),
+        Input(
+            command="./scripts/cleanup.sh",
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {"type": "text", "text": "I also noticed stale artifacts. One more thing to clean up."}
+                        ]
+                    },
+                }
+            ],
+        ): Warn(pattern="options"),
+        Input(
+            file="flags.py",
+            content="json_flag = True\n",
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {"content": [{"type": "text", "text": "Implementing the requested --json flag now."}]},
+                }
+            ],
+        ): Allow(),
+        Input(
+            tool="Read",
+            file="client.py",
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [{"type": "text", "text": "While I'm here, might as well look at the retry logic."}]
+                    },
+                }
+            ],
+        ): Allow(),
+    },
+)