capt-hook 0.3.0__tar.gz → 0.5.0__tar.gz

{capt_hook-0.3.0 → capt_hook-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 0.3.0
+Version: 0.5.0
 Summary: Declarative hook framework for Claude Code
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali
@@ -32,10 +32,11 @@ Requires-Dist: loguru>=0.7.3
 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.12
 Project-URL: Homepage, https://github.com/yasyf/captain-hook
-Project-URL: Documentation, https://captain-hook.readthedocs.io
+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
@@ -46,7 +47,7 @@ Description-Content-Type: text/markdown
 
 [![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://readthedocs.org/projects/captain-hook/badge/?version=latest)](https://captain-hook.readthedocs.io)
+[![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.
@@ -99,6 +100,15 @@ capt-hook generate-settings > .claude/settings.local.json
 
 The next time Claude tries `git stash`, captain-hook returns a deny with your reason and hint.
 
+## Agent skills & plugin
+
+Don't want to write hooks by hand? capt-hook ships two [Agent Skills](https://yasyf.github.io/captain-hook/docs/getting-started/skills.html) — `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 them into `.claude/skills/`, or get them as a plugin:
+
+```
+/plugin marketplace add yasyf/captain-hook
+/plugin install captain-hook@captain-hook
+```
+
 ## What problems does this solve?
 
 - **Block dangerous tool calls** before they execute (`PreToolUse`) — force-push, package-manager footguns, raw `rm -rf`.
@@ -108,6 +118,6 @@ The next time Claude tries `git stash`, captain-hook returns a deny with your re
 
 ## Docs
 
-[Read the docs](https://captain-hook.readthedocs.io) for the full guide: conditions, primitives, LLM hooks, workflows, state, and real-world patterns.
+[Read the docs](https://yasyf.github.io/captain-hook/) for the full guide: conditions, primitives, LLM hooks, workflows, state, and real-world patterns.
 
-Working on captain-hook itself? See the [development guide](https://captain-hook.readthedocs.io/en/latest/development/).
+Working on captain-hook itself? See the [development guide](https://yasyf.github.io/captain-hook/docs/development/).

{capt_hook-0.3.0 → capt_hook-0.5.0}/README.md

@@ -2,7 +2,7 @@
 
 [![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://readthedocs.org/projects/captain-hook/badge/?version=latest)](https://captain-hook.readthedocs.io)
+[![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.
@@ -55,6 +55,15 @@ capt-hook generate-settings > .claude/settings.local.json
 
 The next time Claude tries `git stash`, captain-hook returns a deny with your reason and hint.
 
+## Agent skills & plugin
+
+Don't want to write hooks by hand? capt-hook ships two [Agent Skills](https://yasyf.github.io/captain-hook/docs/getting-started/skills.html) — `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 them into `.claude/skills/`, or get them as a plugin:
+
+```
+/plugin marketplace add yasyf/captain-hook
+/plugin install captain-hook@captain-hook
+```
+
 ## What problems does this solve?
 
 - **Block dangerous tool calls** before they execute (`PreToolUse`) — force-push, package-manager footguns, raw `rm -rf`.
@@ -64,6 +73,6 @@ The next time Claude tries `git stash`, captain-hook returns a deny with your re
 
 ## Docs
 
-[Read the docs](https://captain-hook.readthedocs.io) for the full guide: conditions, primitives, LLM hooks, workflows, state, and real-world patterns.
+[Read the docs](https://yasyf.github.io/captain-hook/) for the full guide: conditions, primitives, LLM hooks, workflows, state, and real-world patterns.
 
-Working on captain-hook itself? See the [development guide](https://captain-hook.readthedocs.io/en/latest/development/).
+Working on captain-hook itself? See the [development guide](https://yasyf.github.io/captain-hook/docs/development/).

capt_hook-0.5.0/captain_hook/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "captain-hook",
+  "displayName": "Captain Hook",
+  "description": "Skills for the capt-hook declarative hook framework: bootstrap gates and nudges from a repo's conventions, and translate style guides into enforced StyleRules.",
+  "author": { "name": "Yasyf Mohamedali", "email": "yasyfm@gmail.com" },
+  "homepage": "https://yasyf.github.io/captain-hook/",
+  "repository": "https://github.com/yasyf/captain-hook",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "keywords": ["claude-code", "hooks", "guardrails", "styleguide"]
+}

capt_hook-0.5.0/captain_hook/__init__.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from captain_hook import file as file
+from captain_hook import style as style
+from captain_hook import utils as utils
+from captain_hook.app import hook as hook
+from captain_hook.app import on as on
+from captain_hook.app import register as register
+from captain_hook.command import Command as Command
+from captain_hook.command import CommandLine as CommandLine
+from captain_hook.command import Redirect as Redirect
+from captain_hook.context import HookContext as HookContext
+from captain_hook.events import BaseHookEvent as BaseHookEvent
+from captain_hook.events import NotificationEvent as NotificationEvent
+from captain_hook.events import PostToolUseEvent as PostToolUseEvent
+from captain_hook.events import PostToolUseFailureEvent as PostToolUseFailureEvent
+from captain_hook.events import PreCompactEvent as PreCompactEvent
+from captain_hook.events import PreToolUseEvent as PreToolUseEvent
+from captain_hook.events import StopEvent as StopEvent
+from captain_hook.events import SubagentStartEvent as SubagentStartEvent
+from captain_hook.events import SubagentStopEvent as SubagentStopEvent
+from captain_hook.events import ToolHookEvent as ToolHookEvent
+from captain_hook.events import UserPromptSubmitEvent as UserPromptSubmitEvent
+from captain_hook.file import File as File
+from captain_hook.primitives import GateVerdict as GateVerdict
+from captain_hook.primitives import NudgeVerdict as NudgeVerdict
+from captain_hook.primitives import PromptCheckVerdict as PromptCheckVerdict
+from captain_hook.primitives import block_command as block_command
+from captain_hook.primitives import gate as gate
+from captain_hook.primitives import llm_evaluate as llm_evaluate
+from captain_hook.primitives import llm_gate as llm_gate
+from captain_hook.primitives import llm_nudge as llm_nudge
+from captain_hook.primitives import prompt_check as prompt_check
+from captain_hook.primitives import warn_command as warn_command
+
+# audit/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.audit import audit as audit
+from captain_hook.primitives.lint import diff_lint as diff_lint
+from captain_hook.primitives.lint import lint as lint
+from captain_hook.primitives.nudge import nudge as nudge
+from captain_hook.primitives.workflow import Artifact as Artifact
+from captain_hook.primitives.workflow import Step as Step
+from captain_hook.primitives.workflow import Workflow as Workflow
+from captain_hook.primitives.workflow import text_matches as text_matches
+from captain_hook.primitives.workflow import workflow as workflow
+from captain_hook.prompt import Prompt as Prompt
+from captain_hook.session import SessionSlot as SessionSlot
+from captain_hook.session import SessionStore as SessionStore
+from captain_hook.session import session_state as session_state
+from captain_hook.settings import HooksSettings as HooksSettings
+from captain_hook.settings import build_settings as build_settings
+from captain_hook.signals.nlp import Clause as Clause
+from captain_hook.signals.nlp import NlpSignal as NlpSignal
+from captain_hook.signals.nlp import Phrase as Phrase
+from captain_hook.state import HookState as HookState
+from captain_hook.state import PrimitiveState as PrimitiveState
+from captain_hook.state import workflow_state as workflow_state
+from captain_hook.tasks import Task as Task
+from captain_hook.tasks import Tasks as Tasks
+from captain_hook.testing import Allow as Allow
+from captain_hook.testing import Block as Block
+from captain_hook.testing import InlineTests as InlineTests
+from captain_hook.testing import Input as Input
+from captain_hook.testing import TranscriptFixture as TranscriptFixture
+from captain_hook.testing import Warn as Warn
+from captain_hook.tools import EditOp as EditOp
+from captain_hook.tools import TaskOp as TaskOp
+from captain_hook.tools import WriteOp as WriteOp
+from captain_hook.transcript import ToolUse as ToolUse
+from captain_hook.transcript import ToolUseQuery as ToolUseQuery
+from captain_hook.transcript import ToolUseSequence as ToolUseSequence
+from captain_hook.transcript import Transcript as Transcript
+from captain_hook.transcript import TranscriptMessage as TranscriptMessage
+from captain_hook.transcript import TranscriptSlice as TranscriptSlice
+from captain_hook.transcript import Turn as Turn
+from captain_hook.transcript.inputs import AgentInput as AgentInput
+from captain_hook.transcript.inputs import BashInput as BashInput
+from captain_hook.transcript.inputs import EditInput as EditInput
+from captain_hook.transcript.inputs import FileInputBase as FileInputBase
+from captain_hook.transcript.inputs import GenericInput as GenericInput
+from captain_hook.transcript.inputs import GlobInput as GlobInput
+from captain_hook.transcript.inputs import GrepInput as GrepInput
+from captain_hook.transcript.inputs import InputBase as InputBase
+from captain_hook.transcript.inputs import ReadInput as ReadInput
+from captain_hook.transcript.inputs import SkillInput as SkillInput
+from captain_hook.transcript.inputs import TaskCreateInput as TaskCreateInput
+from captain_hook.transcript.inputs import TaskUpdateInput as TaskUpdateInput
+from captain_hook.transcript.inputs import WriteInput as WriteInput
+from captain_hook.transcript.models import ContentBlock as ContentBlock
+from captain_hook.transcript.models import ToolResult as ToolResult
+from captain_hook.types import Action as Action
+from captain_hook.types import Agent as Agent
+from captain_hook.types import Content as Content
+from captain_hook.types import CustomCondition as CustomCondition
+from captain_hook.types import Event as Event
+from captain_hook.types import FilePath as FilePath
+from captain_hook.types import HookResult as HookResult
+from captain_hook.types import InPlanMode as InPlanMode
+from captain_hook.types import RanCommand as RanCommand
+from captain_hook.types import ReadFile as ReadFile
+from captain_hook.types import Signal as Signal
+from captain_hook.types import Signals as Signals
+from captain_hook.types import SourceEdits as SourceEdits
+from captain_hook.types import TCondition as TCondition
+from captain_hook.types import TestFile as TestFile
+from captain_hook.types import Tool as Tool
+from captain_hook.types import TouchedFile as TouchedFile
+from captain_hook.types import UsedSkill as UsedSkill
+from captain_hook.types import Waiting as Waiting

{capt_hook-0.3.0 → capt_hook-0.5.0}/captain_hook/app.py

@@ -26,9 +26,7 @@ if TYPE_CHECKING:
 
 HookHandler = Callable[["BaseHookEvent"], "HookResult | None"]
 
-VALID_CONDITION_TYPES = tuple(
-    t for t in get_args(TCondition) if t is not CustomCondition
-)
+VALID_CONDITION_TYPES = tuple(t for t in get_args(TCondition) if t is not CustomCondition)
 VALID_CONDITION_NAMES = ", ".join(t.__name__ for t in VALID_CONDITION_TYPES) + ", or a CustomCondition"
 
 
@@ -44,7 +42,8 @@ def validate_conditions(conditions: Sequence[TCondition], label: str) -> None:
 def validate_handler_signature(fn: HookHandler) -> None:
     sig = inspect.signature(fn)
     params = [
-        p for p in sig.parameters.values()
+        p
+        for p in sig.parameters.values()
         if p.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
     ]
     if len(params) != 1:
@@ -53,7 +52,8 @@ def validate_handler_signature(fn: HookHandler) -> None:
             f"got {sig}. Hook handlers must accept exactly one positional parameter (the event)."
         )
     required_kw = [
-        p for p in sig.parameters.values()
+        p
+        for p in sig.parameters.values()
         if p.kind == inspect.Parameter.KEYWORD_ONLY and p.default is inspect.Parameter.empty
     ]
     if required_kw:
@@ -99,9 +99,7 @@ def is_gitignored(path_str: str) -> bool:
     if not _state.gitignore_patterns:
         return False
     p = Path(path_str)
-    return any(
-        fnmatch(p.name, pat) or any(fnmatch(part, pat) for part in p.parts) for pat in _state.gitignore_patterns
-    )
+    return any(fnmatch(p.name, pat) or any(fnmatch(part, pat) for part in p.parts) for pat in _state.gitignore_patterns)
 
 
 def hook(
@@ -109,7 +107,6 @@ def hook(
     *,
     only_if: Sequence[TCondition] = (),
     skip_if: Sequence[TCondition] = (),
-
     message: str | None = None,
     block: bool = False,
     respect_gitignore: bool = True,
@@ -274,5 +271,3 @@ def get_matching_hooks(evt: BaseHookEvent) -> list[RegisteredHook]:
             or not is_gitignored(str(evt.file))
         )
     ]
-
-

{capt_hook-0.3.0 → capt_hook-0.5.0}/captain_hook/classifiers/__init__.py

@@ -13,6 +13,7 @@ class MessageClassifier(Protocol):
 
     def __call__(self, msg: TranscriptMessage) -> bool: ...
 
+
 CLASSIFIER_MODULES = ("droid", "conductor", "native")
 
 

{capt_hook-0.3.0 → capt_hook-0.5.0}/captain_hook/cli.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import importlib.resources
 import json
 import os
+import shutil
+import subprocess
 import sys
 from collections import defaultdict
 from dataclasses import dataclass
@@ -22,6 +24,8 @@ from captain_hook.types import Event
 
 DIST_NAME = "capt-hook"
 EVENT_NAMES = ", ".join(n for e in Event if (n := e.name))
+MARKETPLACE = {"captain-hook": {"source": {"source": "github", "repo": "yasyf/captain-hook"}}}
+PLUGIN_ID = "captain-hook@captain-hook"
 
 
 @dataclass(frozen=True, slots=True)
@@ -40,6 +44,68 @@ 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``.
+
+    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"``.
+    """
+    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
+
+
+def register_marketplace(root: Path) -> None:
+    """Enable the captain-hook plugin marketplace in ``root/.claude/settings.local.json``.
+
+    Merges ``extraKnownMarketplaces`` and ``enabledPlugins`` entries into the
+    existing settings so the bundled skills track the repository as a plugin.
+    """
+    settings_path = root / ".claude" / "settings.local.json"
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    existing = json.loads(settings_path.read_text()) if settings_path.exists() else {}
+    merged = existing | {
+        "extraKnownMarketplaces": existing.get("extraKnownMarketplaces", {}) | MARKETPLACE,
+        "enabledPlugins": existing.get("enabledPlugins", {}) | {PLUGIN_ID: True},
+    }
+    settings_path.write_text(json.dumps(merged, indent=2) + "\n")
+
+
+def maybe_launch_bootstrap(root: Path) -> bool:
+    """Offer to launch Claude with the ``bootstrapping-hooks`` skill after ``init``.
+
+    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.
+
+    Returns:
+        Whether Claude was launched.
+    """
+    if not (sys.stdin.isatty() and shutil.which("claude")):
+        return False
+    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)
+    return True
+
+
 def generate_settings(hooks_dir: str = ".claude/hooks", from_source: str = DIST_NAME) -> dict[str, Any]:
     events_by_async: defaultdict[bool, set[str]] = defaultdict(set)
     for entry in _state.hooks:
@@ -54,12 +120,7 @@ def generate_settings(hooks_dir: str = ".claude/hooks", from_source: str = DIST_
         return [
             {
                 "type": "command",
-                "command": (
-                    f"uvx{from_flag} capt-hook"
-                    f"{hooks_flag}"
-                    f" run {event}"
-                    f"{' --async' if is_async else ''}"
-                ),
+                "command": (f"uvx{from_flag} capt-hook{hooks_flag} run {event}{' --async' if is_async else ''}"),
             }
             | ({"async": True} if is_async else {})
             for is_async, events in sorted(events_by_async.items())
@@ -172,6 +233,8 @@ def init_project(root: Path) -> None:
     merged, summary = merge_init_settings(".claude/hooks", settings_path)
     settings_path.write_text(json.dumps(merged, indent=2) + "\n")
 
+    skills_summary = install_skills(root)
+
     print(f"Scaffolded {example.relative_to(root)} + {settings_path.relative_to(root)}.")
     print()
     print(f"{settings_path.relative_to(root)}:")
@@ -184,11 +247,20 @@ def init_project(root: Path) -> None:
     if unchanged:
         print(f"  unchanged: {', '.join(unchanged)} (already present)")
     print()
+    print(".claude/skills/:")
+    for name in (n for n, status in skills_summary.items() if status == "installed"):
+        print(f"  + installed {name}")
+    if skipped := [n for n, status in skills_summary.items() if status == "skipped"]:
+        print(f"  unchanged: {', '.join(skipped)} (already present; capt-hook skills install --force to refresh)")
+    print()
     print("Next:")
-    print("  1. Read the quickstart: docs/getting-started/quickstart.md")
+    print("  1. Read the quickstart: https://yasyf.github.io/captain-hook/")
     print("  2. Edit example.py or add new files under .claude/hooks/")
     print("  3. capt-hook test       # verify inline tests")
     print("  4. capt-hook generate-settings    # rewire after adding events")
+    print("  5. /bootstrapping-hooks in Claude  # mine hooks from this repo's conventions")
+    print()
+    maybe_launch_bootstrap(root)
 
 
 def show_logs(session: str | None = None, tail: int | None = None) -> None:
@@ -251,12 +323,16 @@ def run_tests(json_output: bool = False) -> None:
     passed = failed = errors = skipped = 0
     for name, status, _ok, detail in results:
         if json_output:
-            print(json.dumps({
-                "id": name,
-                "status": status,
-                "expected": expected_by_id.get(name, ""),
-                "reason": detail,
-            }))
+            print(
+                json.dumps(
+                    {
+                        "id": name,
+                        "status": status,
+                        "expected": expected_by_id.get(name, ""),
+                        "reason": detail,
+                    }
+                )
+            )
         match status:
             case "pass":
                 passed += 1
@@ -300,10 +376,7 @@ def cli(ctx: click.Context, hooks: str | None, root_path: str | None) -> None:
 
 @cli.command(
     short_help="Dispatch a hook event (reads JSON from stdin, writes JSON to stdout)",
-    help=(
-        "Dispatch a hook event (reads JSON from stdin, writes JSON to stdout).\n\n"
-        f"EVENT is one of: {EVENT_NAMES}."
-    ),
+    help=(f"Dispatch a hook event (reads JSON from stdin, writes JSON to stdout).\n\nEVENT is one of: {EVENT_NAMES}."),
 )
 @click.argument("event")
 @click.option("--async", "async_", is_flag=True, default=False, help="Run async hooks only")
@@ -345,7 +418,7 @@ def test(state: CliState, json_output: bool) -> None:
 @cli.command()
 @click.pass_obj
 def init(state: CliState) -> None:
-    """Scaffold hooks directory, bin script, and settings."""
+    """Scaffold the hooks directory, install bundled skills, and wire settings."""
     init_project(state.root)
 
 
@@ -357,4 +430,18 @@ def logs(session: str | None, tail: int | None) -> None:
     show_logs(session=session, tail=tail)
 
 
+@cli.group()
+def skills() -> None:
+    """Manage the bundled Claude Code skills."""
+
+
+@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}")
+
+
 main = cli

{capt_hook-0.3.0 → capt_hook-0.5.0}/captain_hook/command.py

@@ -337,9 +337,7 @@ class CommandLineQuery:
             ``True`` if any command has a file redirect or the parts are joined
             by a pipe (``|``) operator.
         """
-        return any(cmd.redirects for cmd in self.line.commands) or any(
-            op == "|" for _, op in self.line.parts if op
-        )
+        return any(cmd.redirects for cmd in self.line.commands) or any(op == "|" for _, op in self.line.parts if op)
 
     def contains_token(self, token: str) -> bool:
         """Return whether ``token`` appears as a whole argv element in any command.

{capt_hook-0.3.0 → capt_hook-0.5.0}/captain_hook/conditions.py

@@ -1,4 +1,5 @@
 """Condition evaluation: checks ``TCondition`` instances against the current event."""
+
 from __future__ import annotations
 
 import re
@@ -32,10 +33,7 @@ if TYPE_CHECKING:
 
 
 def has_completion_notification(t: Transcript, tool_use_id: str, after_idx: int) -> bool:
-    return any(
-        (n := m.notification) and n.tool_use_id == tool_use_id
-        for m in t.messages[after_idx + 1 :]
-    )
+    return any((n := m.notification) and n.tool_use_id == tool_use_id for m in t.messages[after_idx + 1 :])
 
 
 def waiting_tool_names(evt: BaseHookEvent) -> set[str]:
@@ -109,15 +107,16 @@ def check_condition(c: TCondition, evt: BaseHookEvent) -> bool:
         case UsedSkill(name, subagents):
             return bool(evt.ctx.transcript) and evt.ctx.transcript.has_skill(*name.split("|"), subagents=subagents)
         case ReadFile(patterns, subagents):
-            return bool(evt.ctx.transcript) and any(evt.ctx.transcript.has_read(p, subagents=subagents) for p in patterns)
+            return bool(evt.ctx.transcript) and any(
+                evt.ctx.transcript.has_read(p, subagents=subagents) for p in patterns
+            )
         case TouchedFile(patterns, subagents):
             return bool(evt.ctx.transcript) and evt.ctx.transcript.has_edit_to(*patterns, subagents=subagents)
         case RanCommand(pattern, subagents):
             return bool(evt.ctx.transcript) and evt.ctx.transcript.has_command(pattern, subagents=subagents)
         case InPlanMode():
             return evt.permission_mode == "plan" or (
-                bool(t := evt.ctx.transcript)
-                and t.count_tools("EnterPlanMode") > t.count_tools("ExitPlanMode")
+                bool(t := evt.ctx.transcript) and t.count_tools("EnterPlanMode") > t.count_tools("ExitPlanMode")
             )
         case Waiting():
             return is_waiting(evt)

{capt_hook-0.3.0 → capt_hook-0.5.0}/captain_hook/context.py

@@ -13,7 +13,7 @@ from pydantic import BaseModel
 from pydantic_settings import BaseSettings
 
 from captain_hook.llm import CodexBackend, LlmBackend, LlmBackends, TModel, TSpecialty
-from captain_hook.prompt import PromptMessage
+from captain_hook.prompt import Prompt
 from captain_hook.session import SessionStore
 
 if TYPE_CHECKING:
@@ -22,7 +22,7 @@ if TYPE_CHECKING:
 
 @dataclass
 class HookContext:
-    """Runtime context injected into every hook event, providing session state, transcript, settings, and LLM/CLI helpers."""
+    """Runtime context injected into every hook event: session state, transcript, settings, and LLM/CLI helpers."""
 
     session: SessionStore
     transcript: Transcript
@@ -119,7 +119,7 @@ class HookContext:
 
     def call_llm(
         self,
-        template: str | PromptMessage,
+        template: str | Prompt,
         *args: Any,
         specialty: TSpecialty = "general",
         model: TModel = "small",
@@ -129,7 +129,7 @@ class HookContext:
         response_model: type[BaseModel] | None = None,
         **kwargs: Any,
     ) -> str | BaseModel:
-        if isinstance(template, PromptMessage):
+        if isinstance(template, Prompt):
             prompt = str(template)
             if transcript:
                 prompt = f"{self.transcript}\n\n<task>\n{prompt}\n</task>"
@@ -138,9 +138,7 @@ class HookContext:
                 template = f"{{transcript}}\n\n<task>\n{template}\n</task>"
             prompt = template.format(*args, **kwargs, transcript=self.transcript)
         schema = (
-            json.dumps(response_model.model_json_schema() | {"additionalProperties": False})
-            if response_model
-            else None
+            json.dumps(response_model.model_json_schema() | {"additionalProperties": False}) if response_model else None
         )
         backend = LlmBackends.for_specialty(specialty)
         schema_path = self.resolve_schema_path(backend, schema)

{capt_hook-0.3.0 → capt_hook-0.5.0}/captain_hook/dispatch.py

@@ -1,4 +1,5 @@
-"""Hook dispatch: select matching hooks, run their handlers, and translate ``HookResult`` into the Claude Code stdout envelope."""
+"""Select matching hooks, run their handlers, and translate ``HookResult`` into the Claude Code stdout envelope."""
+
 from __future__ import annotations
 
 from pathlib import Path

{capt_hook-0.3.0 → capt_hook-0.5.0}/captain_hook/file.py

@@ -84,9 +84,7 @@ class PathMatcher:
         return self.matches(path)
 
 
-def categorize_files(
-    paths: Iterable[str | Path], *, lang: str = "py"
-) -> tuple[list[str], list[str], list[str]]:
+def categorize_files(paths: Iterable[str | Path], *, lang: str = "py") -> tuple[list[str], list[str], list[str]]:
     """Split paths into source, test, and skipped buckets for a language.
 
     A path that does not match the ``lang`` globs is skipped; otherwise it is

{capt_hook-0.3.0 → capt_hook-0.5.0}/captain_hook/llm/__init__.py

@@ -1,4 +1,5 @@
 """LLM backend abstractions for captain-hook's ``call_llm`` helper."""
+
 from __future__ import annotations
 
 from captain_hook.llm.backends import ClaudeBackend as ClaudeBackend

{capt_hook-0.3.0 → capt_hook-0.5.0}/captain_hook/llm/backends.py

@@ -3,6 +3,7 @@
 Each backend maps the framework's abstract :data:`TModel` sizes to provider
 model names and knows how to build the CLI invocation and parse its response.
 """
+
 from __future__ import annotations
 
 import json
@@ -107,8 +108,10 @@ class ClaudeBackend(LlmBackend):
                 ["--permission-mode", "auto", "--max-budget-usd", "1"]
                 if agent
                 else [
-                    "--system-prompt", "",
-                    "--setting-sources", "",
+                    "--system-prompt",
+                    "",
+                    "--setting-sources",
+                    "",
                     "--strict-mcp-config",
                 ]
             ),

{capt_hook-0.3.0 → capt_hook-0.5.0}/captain_hook/loader.py

@@ -1,4 +1,5 @@
 """Hook discovery: imports a hooks package, loads its ``conf`` module, and registers every hook module."""
+
 from __future__ import annotations
 
 import importlib

capt_hook-0.5.0/captain_hook/primitives/__init__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from captain_hook.primitives.audit import audit as audit
+from captain_hook.primitives.commands import block_command as block_command
+from captain_hook.primitives.commands import warn_command as warn_command
+from captain_hook.primitives.lint import diff_lint as diff_lint
+from captain_hook.primitives.lint import lint as lint
+from captain_hook.primitives.llm import GateVerdict as GateVerdict
+from captain_hook.primitives.llm import NudgeVerdict as NudgeVerdict
+from captain_hook.primitives.llm import PromptCheckVerdict as PromptCheckVerdict
+from captain_hook.primitives.llm import llm_evaluate as llm_evaluate
+from captain_hook.primitives.llm import llm_gate as llm_gate
+from captain_hook.primitives.llm import llm_nudge as llm_nudge
+from captain_hook.primitives.llm import prompt_check as prompt_check
+from captain_hook.primitives.nudge import gate as gate
+from captain_hook.primitives.nudge import nudge as nudge

{capt_hook-0.3.0 → capt_hook-0.5.0}/captain_hook/primitives/commands.py

@@ -16,6 +16,7 @@ def block_command_pattern(tokens: list[str]) -> str:
         >>> block_command_pattern(["git", "stash", "*"])
         'git\\\\s+stash\\\\s+\\\\S+'
     """
+
     def convert(token: str) -> str:
         match token:
             case "*":