capt-hook 2.0.0__tar.gz → 2.1.0__tar.gz

{capt_hook-2.0.0 → capt_hook-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 2.0.0
+Version: 2.1.0
 Summary: Declarative hook framework for Claude Code
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali
@@ -16,20 +16,22 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Software Development :: Testing
 Classifier: Typing :: Typed
-Requires-Dist: cc-transcript>=2.0,<3
+Requires-Dist: cc-transcript>=5,<6
 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.1.3
+Requires-Dist: spawnllm>=0.4.0
 Requires-Dist: pytest>=8.0 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
 Requires-Dist: pyright>=1.1 ; extra == 'dev'
@@ -53,48 +55,48 @@ Description-Content-Type: text/markdown
 [![Docs](https://github.com/yasyf/captain-hook/actions/workflows/docs.yml/badge.svg)](https://yasyf.github.io/captain-hook/)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm_Noncommercial_1.0.0-blue.svg)](https://github.com/yasyf/captain-hook/blob/main/LICENSE)
 
-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.
+Guardrails for Claude Code, written as typed, testable data — and learned from the corrections you give Claude.
+
+A captain-hook hook is declarative Python: an event, some conditions, an action. Block a footgun before it runs, nudge the agent off a bad pattern, gate "done" until the tests pass. Then captain-hook closes the loop: it reads the corrections you give Claude as you work and opens pull requests that codify the durable ones as new hooks. You write the first few; it writes the rest.
 
 ## Install
 
-There's no install step. Run everything through [uvx](https://docs.astral.sh/uv/).
+captain-hook needs no install — it runs through [uvx](https://docs.astral.sh/uv/). From your project root:
 
 ```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`.
-
-## First 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".
 
-`uvx capt-hook init` scaffolds `.claude/hooks/`, wires Claude Code's settings, and installs the skills. One command and you're live.
+## Your first hook
 
-```bash
-uvx capt-hook init
-```
-
-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.
+A hook is an event, some conditions, and an action. This one stops the agent from finishing a UI change it never looked at:
 
 ```python
 # .claude/hooks/visual_review.py
 from captain_hook import gate, TouchedFile, UsedSkill
 
-# A Stop gate: before the agent finishes, block if it edited UI files without doing a visual review.
 gate(
-    # the one-line reason shown to the agent when the gate fires
     "You edited UI files. Open them with agent-browser and verify they render before finishing.",
-    # fires only if UI files changed
     only_if=[TouchedFile("**/src/routes/**", "**/src/components/**")],
-    # already reviewed -> don't block
     skip_if=[UsedSkill("agent-browser")],
 )
 ```
 
-Conditions match tools, files, commands, and even which skills the agent used.
+`only_if` arms the gate only when UI files changed; `skip_if` stands it down once the agent has done the review. Conditions match tools, files, commands, and even which skills the agent used.
+
+## It learns from your corrections
+
+Most hooks you'll never write by hand.
+
+The corrections you give Claude as you work are exactly the rules a hook should enforce: "never force-push", "use `uv`, not `pip`", "you weakened that test". Writing the hook by hand is friction you skip in the moment, so the **session reviewer** notices for you. When a session ends, it reads the transcript, finds the durable corrections and the hooks that misfired, judges which ones are standing rules and which are one-offs, and once a pattern proves itself across sessions, opens a pull request that adds the hook — or fixes the one that misfired. You review the PR like any other.
 
-## Test your hooks
+It's on by default after `init`. Turn it off for a repo with `uvx capt-hook review disable`. The [session reviewer guide](https://yasyf.github.io/captain-hook/docs/guide/session-reviewer.html) covers the prerequisites (an authenticated `claude` and `gh`) and the `HOOKS_REVIEW_*` thresholds.
 
-Every deterministic hook carries inline tests, so a broken hook fails like broken code. Run them from your project root, where `--hooks` defaults to `.claude/hooks`.
+## Tested like code
+
+Every deterministic hook carries inline tests, so a broken hook fails like broken code:
 
 ```python
 # .claude/hooks/safety.py
@@ -111,35 +113,24 @@ block_command(
 )
 ```
 
+Run them from your project root, where `--hooks` defaults to `.claude/hooks`:
+
 ```bash
 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
+Wire that into CI and you catch a broken hook the way you catch broken code.
 
-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.
+## What it's for
 
-```
-/plugin marketplace add yasyf/captain-hook
-/plugin install captain-hook@captain-hook
-```
-
-## What this solves
-
-captain-hook covers these jobs:
-
-- Block dangerous tool calls before they execute on `PreToolUse`, like force-push, package-manager footguns, and raw `rm -rf`.
-- Drive the agent with feedback that fires on the patterns it actually emits, such as repeated failures, weakened tests, and missed conventions.
-- Enforce multi-step workflows with Stop gates and artifact validation, so the agent can't declare "done" without running tests, writing a report, or completing a checklist.
-- Keep all of the above testable. Every hook ships with inline `tests = {...}` that `uvx capt-hook test` runs in CI, so you catch broken hooks the way you catch broken code.
+- Block footguns before they run on `PreToolUse`: force-push, `rm -rf`, package-manager traps.
+- Steer the agent with feedback that fires on the patterns it actually emits: repeated failures, weakened tests, missed conventions.
+- Hold the line on multi-step work with Stop gates and artifact checks, so the agent can't call it "done" before the tests run or the report's written.
+- Keep all of it testable; every hook ships with inline tests that run in CI.
 
 ## Docs
 
-[Read the docs](https://yasyf.github.io/captain-hook/) for the full guide to conditions, primitives, LLM hooks, workflows, state, and real-world patterns.
-
-For working on captain-hook itself, see the [development guide](https://yasyf.github.io/captain-hook/docs/development/).
+[Read the docs](https://yasyf.github.io/captain-hook/) for the full guide to conditions, primitives, LLM hooks, workflows, state, and real-world patterns. To work on captain-hook itself, see the [development guide](https://yasyf.github.io/captain-hook/docs/development/).
 
 ## License
 

capt_hook-2.1.0/README.md

@@ -0,0 +1,89 @@
+# captain-hook
+
+![captain-hook banner](https://github.com/yasyf/captain-hook/raw/main/docs/assets/readme-banner.webp)
+
+[![PyPI](https://img.shields.io/pypi/v/capt-hook.svg)](https://pypi.org/project/capt-hook/)
+[![Python](https://img.shields.io/pypi/pyversions/capt-hook.svg)](https://pypi.org/project/capt-hook/)
+[![Docs](https://github.com/yasyf/captain-hook/actions/workflows/docs.yml/badge.svg)](https://yasyf.github.io/captain-hook/)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm_Noncommercial_1.0.0-blue.svg)](https://github.com/yasyf/captain-hook/blob/main/LICENSE)
+
+Guardrails for Claude Code, written as typed, testable data — and learned from the corrections you give Claude.
+
+A captain-hook hook is declarative Python: an event, some conditions, an action. Block a footgun before it runs, nudge the agent off a bad pattern, gate "done" until the tests pass. Then captain-hook closes the loop: it reads the corrections you give Claude as you work and opens pull requests that codify the durable ones as new hooks. You write the first few; it writes the rest.
+
+## Install
+
+captain-hook needs no install — it runs through [uvx](https://docs.astral.sh/uv/). From your project root:
+
+```bash
+uvx capt-hook init
+```
+
+`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
+
+A hook is an event, some conditions, and an action. This one stops the agent from finishing a UI change it never looked at:
+
+```python
+# .claude/hooks/visual_review.py
+from captain_hook import gate, TouchedFile, UsedSkill
+
+gate(
+    "You edited UI files. Open them with agent-browser and verify they render before finishing.",
+    only_if=[TouchedFile("**/src/routes/**", "**/src/components/**")],
+    skip_if=[UsedSkill("agent-browser")],
+)
+```
+
+`only_if` arms the gate only when UI files changed; `skip_if` stands it down once the agent has done the review. Conditions match tools, files, commands, and even which skills the agent used.
+
+## It learns from your corrections
+
+Most hooks you'll never write by hand.
+
+The corrections you give Claude as you work are exactly the rules a hook should enforce: "never force-push", "use `uv`, not `pip`", "you weakened that test". Writing the hook by hand is friction you skip in the moment, so the **session reviewer** notices for you. When a session ends, it reads the transcript, finds the durable corrections and the hooks that misfired, judges which ones are standing rules and which are one-offs, and once a pattern proves itself across sessions, opens a pull request that adds the hook — or fixes the one that misfired. You review the PR like any other.
+
+It's on by default after `init`. Turn it off for a repo with `uvx capt-hook review disable`. The [session reviewer guide](https://yasyf.github.io/captain-hook/docs/guide/session-reviewer.html) covers the prerequisites (an authenticated `claude` and `gh`) and the `HOOKS_REVIEW_*` thresholds.
+
+## Tested like code
+
+Every deterministic hook carries inline tests, so a broken hook fails like broken code:
+
+```python
+# .claude/hooks/safety.py
+from captain_hook import Allow, Block, Input, block_command
+
+block_command(
+    ["git", "stash"],
+    reason="Use the team's VCS workflow for shelving changes",
+    hint="Commit a WIP change instead of stashing",
+    tests={
+        Input(command="git stash"): Block(),
+        Input(command="git status"): Allow(),
+    },
+)
+```
+
+Run them from your project root, where `--hooks` defaults to `.claude/hooks`:
+
+```bash
+uvx capt-hook test
+```
+
+Wire that into CI and you catch a broken hook the way you catch broken code.
+
+## What it's for
+
+- Block footguns before they run on `PreToolUse`: force-push, `rm -rf`, package-manager traps.
+- Steer the agent with feedback that fires on the patterns it actually emits: repeated failures, weakened tests, missed conventions.
+- Hold the line on multi-step work with Stop gates and artifact checks, so the agent can't call it "done" before the tests run or the report's written.
+- Keep all of it testable; every hook ships with inline tests that run in CI.
+
+## Docs
+
+[Read the docs](https://yasyf.github.io/captain-hook/) for the full guide to conditions, primitives, LLM hooks, workflows, state, and real-world patterns. To work on captain-hook itself, see the [development guide](https://yasyf.github.io/captain-hook/docs/development/).
+
+## License
+
+Licensed under [PolyForm Noncommercial 1.0.0](LICENSE), free for noncommercial use.

capt_hook-2.1.0/captain_hook/__init__.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from cc_transcript.tools import (
+    BashCall,
+    EditCall,
+    ExitPlanModeCall,
+    GlobCall,
+    GrepCall,
+    MultiEditCall,
+    NotebookEditCall,
+    OtherCall,
+    ReadCall,
+    SkillCall,
+    TaskCall,
+    TaskCreateCall,
+    TaskUpdateCall,
+    ToolCall,
+    ToolCallBase,
+    WriteCall,
+)
+
+from captain_hook import file, style, utils
+from captain_hook.app import hook, on, register
+from captain_hook.command import Command, CommandLine, Redirect
+from captain_hook.context import HookContext
+from captain_hook.events import (
+    BaseHookEvent,
+    NotificationEvent,
+    PostToolUseEvent,
+    PostToolUseFailureEvent,
+    PreCompactEvent,
+    PreToolUseEvent,
+    SessionEndEvent,
+    StopEvent,
+    SubagentStartEvent,
+    SubagentStopEvent,
+    ToolHookEvent,
+    UserPromptSubmitEvent,
+)
+from captain_hook.file import File, categorize_files
+from captain_hook.primitives import (
+    GateVerdict,
+    NudgeVerdict,
+    PromptCheckVerdict,
+    block_command,
+    gate,
+    llm_evaluate,
+    llm_gate,
+    llm_nudge,
+    prompt_check,
+    rewrite_code,
+    rewrite_command,
+    warn_command,
+)
+
+# lint/nudge are imported from their defining modules, not the primitives
+# package: the package attribute and the submodule share a name, and an alias
+# targeting captain_hook.primitives.<name> resolves to the module under static
+# analysis (griffe), shadowing the function.
+from captain_hook.primitives.lint import diff_lint, lint
+from captain_hook.primitives.nudge import nudge
+from captain_hook.primitives.workflow import Artifact, Step, Workflow, text_matches, workflow
+from captain_hook.prompt import Prompt
+from captain_hook.session import SessionSlot, SessionStore, session_state
+from captain_hook.settings import HooksSettings, build_settings
+from captain_hook.signals.nlp import Clause, NlpSignal, Phrase
+from captain_hook.state import HookState, PrimitiveState, WorkflowState, workflow_state
+from captain_hook.tasks import Task, Tasks
+from captain_hook.testing import Allow, Block, FileFixture, InlineTests, Input, Rewrite, TranscriptFixture, Warn
+from captain_hook.types import (
+    Action,
+    Agent,
+    Content,
+    CustomCommandLineCondition,
+    CustomCondition,
+    CustomInputTypeCondition,
+    Event,
+    FilePath,
+    HookResponse,
+    HookResult,
+    InPlanMode,
+    Pattern,
+    RanCommand,
+    ReadFile,
+    Signal,
+    Signals,
+    SourceEdits,
+    TCondition,
+    TestFile,
+    Tool,
+    TouchedFile,
+    UsedSkill,
+    Waiting,
+)
+from captain_hook.utils import read_json, resolve_binary

{capt_hook-2.0.0 → capt_hook-2.1.0}/captain_hook/app.py

@@ -7,8 +7,6 @@ from fnmatch import fnmatch
 from pathlib import Path
 from typing import TYPE_CHECKING, get_args
 
-from pydantic_settings import BaseSettings
-
 from captain_hook.conditions import matches_conditions
 from captain_hook.types import (
     CustomCondition,
@@ -23,6 +21,7 @@ if TYPE_CHECKING:
     from cc_transcript.activity import UserClassifier
 
     from captain_hook.events import BaseHookEvent
+    from captain_hook.settings import HooksSettings
     from captain_hook.types import HookResult
 
 HookHandler = Callable[["BaseHookEvent"], "HookResult | None"]
@@ -69,7 +68,7 @@ def validate_handler_signature(fn: HookHandler) -> None:
 class State:
     hooks: list[RegisteredHook] = field(default_factory=list)
     gitignore_patterns: list[str] = field(default_factory=list)
-    settings: BaseSettings | None = None
+    settings: HooksSettings | None = None
     classifier: UserClassifier | None = None
     counter: int = field(default=0, repr=False)
 
@@ -254,7 +253,7 @@ def is_planning_agent_skip(spec: HookSpec, evt: BaseHookEvent) -> bool:
         return False
     if evt.event not in (Event.SubagentStop | Event.SubagentStart):
         return False
-    names = getattr(_state.settings, "planning_agents", DEFAULT_PLANNING_AGENTS)
+    names = settings.planning_agents if (settings := _state.settings) else DEFAULT_PLANNING_AGENTS
     return bool(evt.agent_type and evt.agent_type in names)
 
 

capt_hook-2.1.0/captain_hook/ast_grep.py

@@ -0,0 +1,136 @@
+"""The only module that imports ``ast_grep_py``: structural code search and rewriting by language.
+
+Everything else in the framework reaches ast-grep through here — the :class:`~captain_hook.types.Pattern`
+condition, the ``ast_grep_rule`` style builders, and the ``rewrite_code`` primitive — so the binding
+lives behind one seam.
+
+Patterns are plain ast-grep pattern strings with metavariables: ``print($$$)`` matches a print call
+however its arguments are spelled, ``os.system($CMD)`` captures the argument as ``$CMD``. Rewrites
+reuse ast-grep's ``$VAR`` / ``$$$VAR`` fix syntax. Language ids are the same short keys as
+:data:`~captain_hook.types.LANG_GLOBS` (``"py"``, ``"go"``, ``"ts"``, ...); ast-grep also accepts the
+long names (``"python"``).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from captain_hook.types import LANG_GLOBS
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from ast_grep_py import SgNode
+
+EXT_TO_LANG: dict[str, str] = {glob.removeprefix("*."): lang for lang, globs in LANG_GLOBS.items() for glob in globs}
+
+TEMPLATE_VAR = re.compile(r"\$\$\$([A-Z_][A-Z0-9_]*)|\$([A-Z_][A-Z0-9_]*)")
+
+
+@dataclass(frozen=True, slots=True)
+class Match:
+    """A structural match, located by 1-based line to align with ``Violation`` and changed-line scoping."""
+
+    line: int
+    end_line: int
+    text: str
+
+
+def lang_for_path(path: Path) -> str | None:
+    """Infer an ast-grep language id from a file extension, or ``None`` when unsupported."""
+    return EXT_TO_LANG.get(path.suffix.removeprefix("."))
+
+
+def has_metavar(text: str) -> bool:
+    """Whether ``text`` carries an ast-grep metavariable (``$NAME`` or ``$$$NAME``)."""
+    return TEMPLATE_VAR.search(text) is not None
+
+
+def parse(source: str, lang: str) -> SgNode:
+    from ast_grep_py import SgRoot
+
+    return SgRoot(source, lang).root()
+
+
+def to_match(node: SgNode) -> Match:
+    r = node.range()
+    return Match(line=r.start.line + 1, end_line=r.end.line + 1, text=node.text())
+
+
+def match_key(m: Match) -> str:
+    return " ".join(m.text.split())
+
+
+def matches(source: str, lang: str, pattern: str) -> bool:
+    """Whether ``pattern`` matches anywhere in ``source`` — the cheap boolean for conditions."""
+    return parse(source, lang).find(pattern=pattern) is not None
+
+
+def find_all(source: str, lang: str, pattern: str) -> Iterator[Match]:
+    """Every structural match of ``pattern`` in ``source``, as 1-based-line :class:`Match` objects."""
+    return (to_match(node) for node in parse(source, lang).find_all(pattern=pattern))
+
+
+def find_introduced(old: str, new: str, lang: str, pattern: str) -> Iterator[Match]:
+    """Matches present in ``new`` whose construct was absent from ``old`` — the diff helper.
+
+    Identity is the match's whitespace-normalized text, not its range (which shifts as
+    surrounding code moves) — so a pre-existing construct is never reported as newly added.
+    """
+    before = {match_key(m) for m in find_all(old, lang, pattern)}
+    return (m for m in find_all(new, lang, pattern) if match_key(m) not in before)
+
+
+def rewrite(source: str, lang: str, pattern: str, replace: str) -> str:
+    """Rewrite every ``pattern`` match in ``source`` to ``replace``, an ast-grep fix template.
+
+    ``replace`` uses ast-grep's ``$VAR`` / ``$$$VAR`` fix syntax, each metavariable filled from the
+    match it names. Returns ``source`` unchanged when nothing matches.
+    """
+    root = parse(source, lang)
+    if not (edits := [node.replace(fill_template(node, replace)) for node in root.find_all(pattern=pattern)]):
+        return source
+    return root.commit_edits(edits)
+
+
+def capture(source: str, lang: str, pattern: str) -> dict[str, str] | None:
+    """Match ``pattern`` against ``source`` and extract its named metavars, or ``None`` when it doesn't match.
+
+    Each ``$NAME`` in the pattern maps to the matched node's text; each ``$$$NAME`` maps to the
+    original-source span covering its matches, so whitespace is preserved (mirroring :func:`fill_template`).
+    A pattern with no metavars that still matches yields an empty dict — present but empty.
+    """
+    if (node := parse(source, lang).find(pattern=pattern)) is None:
+        return None
+
+    def value(m: re.Match[str]) -> str:
+        if (name := m.group(1)) is not None:
+            if not (spans := node.get_multiple_matches(name)):
+                return ""
+            full = node.get_root().root().text()
+            return full[spans[0].range().start.index : spans[-1].range().end.index]
+        return single.text() if (single := node.get_match(m.group(2))) else ""
+
+    return {(m.group(1) or m.group(2)): value(m) for m in TEMPLATE_VAR.finditer(pattern)}
+
+
+def fill_template(node: SgNode, template: str) -> str:
+    """Fill an ast-grep fix ``template`` against one match: ``$NAME`` becomes the metavar's text;
+    ``$$$NAME`` becomes the original-source span covering its matches, so whitespace is preserved.
+
+    A ``$NAME`` the pattern never captured is left untouched, so literal ``$VAR`` text in a
+    replacement — a shell variable like ``$HOME``, say — passes through unchanged.
+    """
+
+    def substitute(m: re.Match[str]) -> str:
+        if (name := m.group(1)) is not None:
+            if not (spans := node.get_multiple_matches(name)):
+                return ""
+            source = node.get_root().root().text()
+            return source[spans[0].range().start.index : spans[-1].range().end.index]
+        return single.text() if (single := node.get_match(m.group(2))) else m.group(0)
+
+    return TEMPLATE_VAR.sub(substitute, template)