capt-hook 12.2.0__tar.gz → 12.4.0__tar.gz

{capt_hook-12.2.0 → capt_hook-12.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 12.2.0
+Version: 12.4.0
 Summary: Stop repeating yourself to Claude.
 Project-URL: Homepage, https://github.com/yasyf/captain-hook
 Project-URL: Documentation, https://yasyf.github.io/captain-hook/

{capt_hook-12.2.0 → capt_hook-12.4.0}/capt_hook_client/client.py

@@ -140,7 +140,6 @@ def build_request(event: str, root: str, payload_raw: str, *, async_: bool) -> d
         "async": async_,
         "root": root,
         "cwd": os.getcwd(),
-        "hooks": None,
         "env": key.request_env(),
         "payload_raw": payload_raw,
     }

{capt_hook-12.2.0 → capt_hook-12.4.0}/captain_hook/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "captain-hook",
-  "version": "12.1.0",
+  "version": "12.3.0",
   "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": {

{capt_hook-12.2.0 → capt_hook-12.4.0}/captain_hook/__init__.py

@@ -46,6 +46,7 @@ EXPORTS: dict[str, str] = {
     "Redirects": "captain_hook.conditions",
     "RewritingExistingPlan": "captain_hook.conditions",
     "ScratchPath": "captain_hook.conditions",
+    "UserSaid": "captain_hook.conditions",
     "workflow_opt_matches": "captain_hook.conditions",
     "workflow_opt_values": "captain_hook.conditions",
     "workflow_script_source": "captain_hook.conditions",
@@ -122,6 +123,7 @@ EXPORTS: dict[str, str] = {
     "Phrase": "captain_hook.signals.nlp",
     "has_nominal_subject": "captain_hook.signals.nlp",
     "is_past_predicate": "captain_hook.signals.nlp",
+    "subject_kind": "captain_hook.signals.nlp",
     "HookState": "captain_hook.state",
     "PrimitiveState": "captain_hook.state",
     "WorkflowState": "captain_hook.state",
@@ -129,6 +131,7 @@ EXPORTS: dict[str, str] = {
     "Task": "captain_hook.tasks",
     "Tasks": "captain_hook.tasks",
     "Allow": "captain_hook.testing.types",
+    "Turn": "captain_hook.turn",
     "Ask": "captain_hook.testing.types",
     "Block": "captain_hook.testing.types",
     "FileFixture": "captain_hook.testing.types",
@@ -167,6 +170,7 @@ EXPORTS: dict[str, str] = {
     "ToolInput": "captain_hook.types",
     "TouchedFile": "captain_hook.types",
     "UsedSkill": "captain_hook.types",
+    "UsedTool": "captain_hook.types",
     "Waiting": "captain_hook.types",
     "WorkflowScript": "captain_hook.types",
     "binary_supports": "captain_hook.util.fs",

{capt_hook-12.2.0 → capt_hook-12.4.0}/captain_hook/__init__.pyi

@@ -42,6 +42,7 @@ from captain_hook.conditions import Headless as Headless
 from captain_hook.conditions import Redirects as Redirects
 from captain_hook.conditions import RewritingExistingPlan as RewritingExistingPlan
 from captain_hook.conditions import ScratchPath as ScratchPath
+from captain_hook.conditions import UserSaid as UserSaid
 from captain_hook.conditions import workflow_opt_matches as workflow_opt_matches
 from captain_hook.conditions import workflow_opt_values as workflow_opt_values
 from captain_hook.conditions import workflow_script_source as workflow_script_source
@@ -118,6 +119,7 @@ from captain_hook.signals.nlp import NlpSignal as NlpSignal
 from captain_hook.signals.nlp import Phrase as Phrase
 from captain_hook.signals.nlp import has_nominal_subject as has_nominal_subject
 from captain_hook.signals.nlp import is_past_predicate as is_past_predicate
+from captain_hook.signals.nlp import subject_kind as subject_kind
 from captain_hook.state import HookState as HookState
 from captain_hook.state import PrimitiveState as PrimitiveState
 from captain_hook.state import WorkflowState as WorkflowState
@@ -133,6 +135,7 @@ from captain_hook.testing.types import Input as Input
 from captain_hook.testing.types import Rewrite as Rewrite
 from captain_hook.testing.types import TranscriptFixture as TranscriptFixture
 from captain_hook.testing.types import Warn as Warn
+from captain_hook.turn import Turn as Turn
 from captain_hook.types import Action as Action
 from captain_hook.types import Agent as Agent
 from captain_hook.types import And as And
@@ -163,6 +166,7 @@ from captain_hook.types import Tool as Tool
 from captain_hook.types import ToolInput as ToolInput
 from captain_hook.types import TouchedFile as TouchedFile
 from captain_hook.types import UsedSkill as UsedSkill
+from captain_hook.types import UsedTool as UsedTool
 from captain_hook.types import Waiting as Waiting
 from captain_hook.types import WorkflowScript as WorkflowScript
 from captain_hook.util.fs import binary_supports as binary_supports

{capt_hook-12.2.0 → capt_hook-12.4.0}/captain_hook/builtin_packs/fixes/hooks/scratch_writes.py

@@ -15,7 +15,7 @@ from captain_hook.builtin_packs.fixes.hooks._lib import McpTool
 
 approve(
     "scratch-dir writes under skip-permissions",
-    only_if=[Tool("Edit|Write|MultiEdit|NotebookEdit"), ScratchPath(), SkipPermissions()],
+    only_if=[Tool.EditTools, ScratchPath(), SkipPermissions()],
     skip_if=[McpTool()],
     tests={
         Input(file="/tmp/sweep_arc.py", content="print(1)", skip_permissions=True): Allow(explicit=True),

{capt_hook-12.2.0 → capt_hook-12.4.0}/captain_hook/builtin_packs/general/hooks/tombstones.py

@@ -82,7 +82,7 @@ def is_tombstone(text: str) -> bool:
                         "deprecate",
                     ),
                     tense="completed",
-                    subject="no_nominal",
+                    subject=("unnamed", "passive"),
                 ),
                 Clause(
                     verb=Phrase("be"), adj=Phrase("previously", "formerly", "originally", "here"), tense="completed"

{capt_hook-12.2.0 → capt_hook-12.4.0}/captain_hook/conditions.py

@@ -33,6 +33,7 @@ from captain_hook.types import (
     ToolInput,
     TouchedFile,
     UsedSkill,
+    UsedTool,
     Waiting,
     WorkflowScript,
 )
@@ -44,6 +45,7 @@ if TYPE_CHECKING:
     from cc_transcript.query import Session
 
     from captain_hook.events import BaseHookEvent
+    from captain_hook.signals.nlp import Clause
     from captain_hook.types import HookSpec
 
 # Prose and config file extensions that shouldn't, on their own, demand a code-review pass.
@@ -183,13 +185,24 @@ def is_project_file(evt: BaseHookEvent) -> bool:
 
 
 class UserSaid(CustomCondition):
-    """Matches when the user's messages contain any of the given keywords."""
+    """Matches when any user prompt in the session matches one of ``patterns``.
 
-    def __init__(self, *keywords: str) -> None:
-        self.keywords = keywords
+    A string pattern is a case-insensitive regex, so plain keywords keep their
+    substring behavior; a :class:`~captain_hook.Clause` runs the dependency-clause
+    scan against each prompt. To match only the current turn's prompt, use
+    ``evt.ctx.turn.matches`` instead.
+
+    Example:
+        >>> UserSaid("just commit", Clause(noun=Phrase("test"), verb=Phrase("skip")))
+    """
+
+    def __init__(self, *patterns: str | Clause) -> None:
+        self.patterns = patterns
 
     def check(self, evt: BaseHookEvent) -> bool:
-        return evt.ctx.t.user_said(*self.keywords)
+        from captain_hook.signals.nlp import scan_text
+
+        return any(scan_text(turn.prompt, self.patterns) for turn in evt.ctx.t.turns if turn.prompt)
 
 
 class AllEditsUnder(CustomCondition):
@@ -393,6 +406,10 @@ def check_condition(c: TCondition, evt: BaseHookEvent) -> bool:
             )
         case UsedSkill(names, subagents):
             return has_used_skill(evt.ctx.transcript, names, subagents=subagents)
+        case UsedTool(names, subagents, scope):
+            return (evt.ctx.turn if scope == "turn" else evt.ctx.transcript).has_tool(
+                "|".join(names), subagents=subagents
+            )
         case ReadFile(patterns, subagents):
             return has_read_glob(evt.ctx.transcript, *patterns, subagents=subagents)
         case TouchedFile(patterns, subagents):

{capt_hook-12.2.0 → capt_hook-12.4.0}/captain_hook/context.py

@@ -17,6 +17,8 @@ if TYPE_CHECKING:
     from spawnllm import TModel, TSpecialty
 
     from captain_hook.settings import HooksSettings
+    from captain_hook.signals.nlp import Clause
+    from captain_hook.turn import Turn
 
 
 RECENT_WINDOW = 15
@@ -70,15 +72,31 @@ class HookContext:
         return self.conf
 
     @cached_property
-    def turn(self) -> Session:
-        """The one-turn view of the current turn (cached)."""
-        return self.transcript.current_turn
+    def turn(self) -> Turn:
+        """The one-turn view of the current turn (cached), with prompt matching via ``matches``."""
+        from captain_hook.turn import Turn
+
+        return Turn((current := self.transcript.current_turn).turns, current.path)
 
     @cached_property
     def prior(self) -> Session:
         """The session window before the current turn's last exchange (cached)."""
         return self.transcript.prior()
 
+    def nlp(self, text: str, *patterns: str | Clause) -> bool:
+        """Whether ``text`` matches any pattern — the escape hatch for matching arbitrary prose.
+
+        A string pattern is a case-insensitive regex; a :class:`~captain_hook.Clause`
+        runs the dependency-clause scan. For the current turn's prompt, prefer
+        ``evt.ctx.turn.matches(*patterns)``.
+
+        Example:
+            >>> evt.ctx.nlp(evt.ctx.t.assistant_text(), Clause(noun=Phrase("test"), verb=Phrase("skip")))
+        """
+        from captain_hook.signals.nlp import scan_text
+
+        return scan_text(text, patterns)
+
     def transcript_text(self, *, window: int | None = None) -> str:
         """The transcript rendered turn by turn under the default budget.
 

{capt_hook-12.2.0 → capt_hook-12.4.0}/captain_hook/daemon/protocol.py

@@ -104,7 +104,6 @@ class Request:
     async_: bool = False
     root: str | None = None
     cwd: str | None = None
-    hooks: str | None = None
     env: dict[str, str] = field(default_factory=dict)
     payload_raw: str = ""
 
@@ -132,26 +131,50 @@ def decode_request(line: bytes) -> Request:
         data = json.loads(line)
     except (ValueError, UnicodeDecodeError) as exc:
         raise ProtocolError(f"malformed request JSON: {exc}") from exc
-    match data:
-        case {
-            "v": int() as v,
-            "kind": str() as kind,
-            "client": {"version": str() as cv, "build": str() as cb, "pid": int() as cpid, "ppid": int() as cppid},
-        } if kind in REQUEST_KINDS:
-            return Request(
-                v=v,
-                kind=kind,
-                client=ClientInfo(version=cv, build=cb, pid=cpid, ppid=cppid),
-                event=data.get("event"),
-                async_=bool(data.get("async", False)),
-                root=data.get("root"),
-                cwd=data.get("cwd"),
-                hooks=data.get("hooks"),
-                env=data.get("env") or {},
-                payload_raw=data.get("payload_raw", ""),
-            )
-        case _:
-            raise ProtocolError(f"invalid request shape: {data!r}")
+    if type(data) is not dict:
+        raise ProtocolError(f"invalid request shape: {data!r}")
+    kind = data.get("kind")
+    keys = {"v", "kind", "client"}
+    if kind == "event":
+        keys |= {"event", "async", "root", "cwd", "env", "payload_raw"}
+    if kind not in REQUEST_KINDS or set(data) != keys:
+        raise ProtocolError(f"invalid request shape: {data!r}")
+    client = data["client"]
+    if type(client) is not dict or set(client) != {"version", "build", "pid", "ppid"}:
+        raise ProtocolError(f"invalid request shape: {data!r}")
+    if not (
+        type(data["v"]) is int
+        and type(client["version"]) is str
+        and type(client["build"]) is str
+        and type(client["pid"]) is int
+        and type(client["ppid"]) is int
+    ):
+        raise ProtocolError(f"invalid request shape: {data!r}")
+    info = ClientInfo(version=client["version"], build=client["build"], pid=client["pid"], ppid=client["ppid"])
+    if kind != "event":
+        return Request(v=data["v"], kind=kind, client=info)
+    env = data["env"]
+    if not (
+        type(data["event"]) is str
+        and type(data["async"]) is bool
+        and type(data["root"]) is str
+        and type(data["cwd"]) is str
+        and type(env) is dict
+        and all(type(key) is str and type(value) is str for key, value in env.items())
+        and type(data["payload_raw"]) is str
+    ):
+        raise ProtocolError(f"invalid request shape: {data!r}")
+    return Request(
+        v=data["v"],
+        kind=kind,
+        client=info,
+        event=data["event"],
+        async_=data["async"],
+        root=data["root"],
+        cwd=data["cwd"],
+        env=env,
+        payload_raw=data["payload_raw"],
+    )
 
 
 def encode_response(response: Response) -> bytes:

{capt_hook-12.2.0 → capt_hook-12.4.0}/captain_hook/primitives/rewrite.py

@@ -65,7 +65,7 @@ def rewrite_code(
     handler.__name__ = handler.__qualname__ = hook_name("rewrite_code", None, f"{pattern}=>{replace}")
     on(
         Event.PreToolUse,
-        only_if=[Tool("Edit|Write|MultiEdit|NotebookEdit"), *only_if],
+        only_if=[Tool.EditTools, *only_if],
         skip_if=skip_if,
         tests=tests,
     )(handler)

{capt_hook-12.2.0 → capt_hook-12.4.0}/captain_hook/signals/nlp.py

@@ -1,13 +1,16 @@
 from __future__ import annotations
 
 import functools
+import re
 from collections.abc import Sequence
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Literal, get_args
 
 if TYPE_CHECKING:
     from spacy.tokens import Doc, Span, Token
 
+SubjectKind = Literal["unnamed", "passive", "actor"]
+
 
 @dataclass(frozen=True, slots=True)
 class PhraseFields:
@@ -96,18 +99,21 @@ class Clause:
             are *not* past predicates and *not* counterfactual modal-perfects —
             "will leave"/"leaving"/"leave it"/"will have left" but not
             "left the workspace", "left to clean up", or "should have left".
-        subject: ``"no_nominal"`` vetoes verbs with both a substantive active
-            subject (see ``has_nominal_subject``) and a direct object — "the
-            parser removed the node" is vetoed while "we removed it", passives,
-            and objectless elliptical passives ("config moved to settings.py",
-            "logic migrated to the worker") still match. ``"none"`` vetoes any
-            verb with a substantive active subject, transitive or not —
-            imperatives and pronoun subjects ("switch back to plan mode",
-            "we should replan") still match while described behavior
-            ("the daemon switches to degraded mode") does not.
+        subject: The subject shapes the verb may have (see ``subject_kind``), as
+            a tuple — ``()`` (default) applies no constraint, and a bare string
+            means that one shape. ``"unnamed"``: no substantive active subject —
+            imperatives ("switch back to plan mode"), pronoun subjects
+            ("we should replan"), and true passives ("the file was removed").
+            ``"passive"``: a substantive subject but no direct object —
+            elliptical passives ("config moved to settings.py") and intransitive
+            actives ("the parser crashed"). ``"actor"``: a substantive subject
+            acting on a direct object — described behavior like "the parser
+            removed the node". ``("unnamed",)`` matches directives but not
+            descriptions; ``("unnamed", "passive")`` also admits statements
+            about the thing acted on.
 
     Example:
-        >>> Clause(verb=Phrase("remove", "delete"), tense="completed", subject="no_nominal")
+        >>> Clause(verb=Phrase("remove", "delete"), tense="completed", subject=("unnamed", "passive"))
     """
 
     noun: Phrase | None = None
@@ -115,19 +121,23 @@ class Clause:
     adj: Phrase | None = None
     negated: bool = False
     tense: Literal["any", "completed", "prospective"] = "any"
-    subject: Literal["any", "no_nominal", "none"] = "any"
+    subject: SubjectKind | tuple[SubjectKind, ...] = ()
 
     def __post_init__(self) -> None:
+        if isinstance(self.subject, str):
+            object.__setattr__(self, "subject", (self.subject,))
+        if invalid := set(self.subject) - set(get_args(SubjectKind)):
+            raise ValueError(f"Unknown subject kinds: {sorted(invalid)}")
         if (anchor := self.noun or self.verb) is None:
             raise ValueError("Clause needs a noun or verb anchor")
-        if self.verb is None and (self.tense != "any" or self.subject != "any"):
+        if self.verb is None and (self.tense != "any" or self.subject):
             raise ValueError("Clause tense and subject constraints require a verb")
         if not (
             (self.noun and self.verb)
             or self.adj
             or self.negated
             or self.tense != "any"
-            or self.subject != "any"
+            or self.subject
             or any(" " in lemma for lemma in anchor.lemmas)
         ):
             raise ValueError("Clause needs a second constraint or a compound anchor phrase")
@@ -234,14 +244,18 @@ def tense_matches(tense: Literal["any", "completed", "prospective"], tok: Token)
             return not is_past_predicate(tok) and not is_modal_perfect(tok)
 
 
-def subject_matches(subject: Literal["any", "no_nominal", "none"], tok: Token) -> bool:
-    match subject:
-        case "any":
-            return True
-        case "no_nominal":
-            return not (has_nominal_subject(tok) and any(c.dep_ == "dobj" for c in tok.children))
-        case "none":
-            return not has_nominal_subject(tok)
+def subject_kind(tok: Token) -> SubjectKind:
+    """The shape of ``tok``'s subject, as :class:`Clause`'s ``subject`` constraint sees it.
+
+    ``"unnamed"`` — no substantive active subject (see ``has_nominal_subject``);
+    ``"actor"`` — a substantive subject plus a direct object; ``"passive"`` — a
+    substantive subject without one.
+    """
+    if not has_nominal_subject(tok):
+        return "unnamed"
+    if any(c.dep_ == "dobj" for c in tok.children):
+        return "actor"
+    return "passive"
 
 
 def verb_candidates(clause: Clause, sent: Span) -> list[Token]:
@@ -251,7 +265,7 @@ def verb_candidates(clause: Clause, sent: Span) -> list[Token]:
         v
         for v in find_lemma_matches(clause.verb, sent, {"VERB", "AUX"})
         if tense_matches(clause.tense, v)
-        and subject_matches(clause.subject, v)
+        and (not clause.subject or subject_kind(v) in clause.subject)
         and not (
             clause.tense == "prospective"
             and not clause.negated
@@ -278,3 +292,10 @@ def nlp_scan(clauses: Sequence[Clause], text: str) -> list[str]:
     if not text.strip():
         return []
     return [sent.text.strip() for sent in parse(text).sents if any(match_clause(clause, sent) for clause in clauses)]
+
+
+def scan_text(text: str, patterns: Sequence[str | Clause]) -> bool:
+    clauses = [p for p in patterns if isinstance(p, Clause)]
+    return any(isinstance(p, str) and re.search(p, text, re.IGNORECASE) for p in patterns) or bool(
+        clauses and nlp_scan(clauses, text)
+    )

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

@@ -22,7 +22,7 @@ from captain_hook import (
     Allow, And, Agent, Ask, BaseHookEvent, Block, Event, FilePath, FromSubagent,
     HookResult, InlineTests, Input, Not, Or, Prompt, RanCommand, ReadFile, Rewrite, Runs,
     Signal, Signals, SkipPermissions, SourceEdits, TestFile, Tool, ToolInput, TouchedFile,
-    TranscriptFixture, UsedSkill, Warn, WorkflowScript,
+    TranscriptFixture, UsedSkill, UsedTool, UserSaid, Warn, WorkflowScript,
     approve, block_command, deny, gate, hook, lint, llm_approve, llm_gate, llm_nudge, nudge, on,
     prompt_check, rewrite_command, set_tool_input, warn_command, workflow, Artifact, Step, text_matches,
 )
@@ -154,7 +154,7 @@ evaluated first.
 <!-- gen:conditions -->
 | Need | Use |
 |---|---|
-| Filter by tool name | `Tool("Bash")` or `Tool("Edit", "Write")` — exact names (not regex), aliases auto-expand (Bash=Execute, Write=Create, Agent=Task), MCP suffixes match |
+| Filter by tool name | `Tool("Bash")` or `Tool("Edit", "Write")` — exact names (not regex), aliases auto-expand (Bash=Execute, Write=Create, Agent=Task), MCP suffixes match; `Tool.EditTools` = the prebuilt edit-shaped set (Edit, MultiEdit, NotebookEdit, Write) |
 | Filter by file path | `FilePath("*.py", "*.pyi")` |
 | Filter by bash command text | `CommandCondition(r"git\s+push")` (`captain_hook.types.Command`) — regex over the raw line and each parsed command |
 | Filter by file content being written | `Content(r"print\(")` (multiline regex over Edit new / Write content) |
@@ -165,6 +165,7 @@ evaluated first.
 | Event comes from a subagent/teammate | `FromSubagent()` — the payload carries an `agent_id`; matches the ask's *origin*, where `Agent` matches its *type* |
 | Session launched with bypass available | `SkipPermissions()` — walks to the nearest `claude` ancestor process and matches `--dangerously-skip-permissions` **or** `--allow-dangerously-skip-permissions`; availability counts as consent, whatever the active `permission_mode` |
 | Skill was invoked | `UsedSkill("codex")` — bare name also matches `plugin:name` |
+| Tool was previously used | `UsedTool("EnterPlanMode", scope="turn")` — exact names (a `\|`-joined string works); `scope="turn"` searches only the current turn |
 | File was previously read | `ReadFile("TESTING.md")` — fnmatch globs; anchor dirs with `**/` |
 | Match only test files | `TestFile()` (`**/test_*.py`, `**/*_test.py`, `**/conftest.py`, `**/tests/**/*.py`, `**/*_test.go`, `**/*.test.*`, `**/*.spec.*`) |
 | Python source edits (skips tests by default, in-repo only) | `SourceEdits(lang="py")`; `lang` also `ts`, `go`, `rs`, ...; `project_only=False` to also match out-of-repo files |
@@ -177,7 +178,7 @@ evaluated first.
 | Custom logic | implement `CustomCondition` |
 <!-- /gen:conditions -->
 
-`ReadFile`/`TouchedFile`/`RanCommand`/`UsedSkill` inspect the session transcript — they are
+`ReadFile`/`TouchedFile`/`RanCommand`/`UsedSkill`/`UsedTool` inspect the session transcript — they are
 how Stop gates know what already happened. Custom conditions are any object with a
 `check(self, evt: BaseHookEvent) -> bool` method (a Protocol — no inheritance needed):
 

{capt_hook-12.2.0 → capt_hook-12.4.0}/captain_hook/skills/authoring-hooks/references/testing-hooks.md

@@ -50,7 +50,7 @@ All fields are keyword-only — `Block(pattern="...")`, never `Block("...")`.
 
 ## TranscriptFixture recipe
 
-Transcript-history conditions (`TouchedFile`, `RanCommand`, `ReadFile`, `UsedSkill`) read
+Transcript-history conditions (`TouchedFile`, `RanCommand`, `ReadFile`, `UsedSkill`, `UsedTool`) read
 the session transcript, so their tests supply one. The message shape is Claude Code JSONL:
 `{"type": "assistant", "message": {"content": [<tool_use blocks>]}}`.
 

{capt_hook-12.2.0 → capt_hook-12.4.0}/captain_hook/skills/scanning-sessions/SKILL.md

@@ -103,7 +103,7 @@ Review Progress:
          gression test; create-as-edit: EXTEND mode — broaden + new test pair)
   - [ ] Step 5: Verify (uvx --isolated capt-hook test green in the worktree)
   - [ ] Step 6: Slot check (review slots --repo <the Step-3 target>), then commit,
-         push, gh pr create (verbatim evidence in the body)
+         push, gh pr create (Issue/Fix/Example body per pr-workflow.md)
   - [ ] Step 7: review update <ID> pr_open --pr-url <url>
 - [ ] Step 8: Final report
 ```

{capt_hook-12.2.0 → capt_hook-12.4.0}/captain_hook/skills/scanning-sessions/references/pr-workflow.md

@@ -121,54 +121,67 @@ the amended hook and the mined rule.
 Title: `[capt-hook] <imperative rule statement>` — e.g.
 `[capt-hook] Block force-pushes to protected branches`.
 
-Body template:
+Body template — three sections and the footer, nothing else:
 
-```markdown
-## Rule
+````markdown
+## Issue
 
-<one-sentence rule the corrections imply>
+<1–2 sentences: the failure mode observed in this repo's sessions, with the
+strongest correction woven in verbatim — e.g. "the agent kept committing without
+running tests — corrected repeatedly ('run pytest before you commit', session
+`<session_id>`, <YYYY-MM-DD>)".>
 
-## Hook
+## Fix
 
-`.claude/hooks/<slug>.py` — <primitive> on <event>; fires on <offending shape>, stays
-silent on <benign neighbor>. Inline tests pass (`uvx --isolated capt-hook test`).
+<1–2 sentences: `.claude/hooks/<slug>.py` — <primitive> on <event>; fires on
+<offending shape>, stays silent on <benign neighbor>. Inline tests pass
+(`uvx --isolated capt-hook test`).>
 
-## Evidence
+## Example
 
-Corrections given in this repo's sessions, verbatim:
-
-- "<verbatim correction>" — session `<session_id>`, <YYYY-MM-DD>
-- "<verbatim correction>" — session `<session_id>`, <YYYY-MM-DD>
+```text
+agent › <the tool call or action that used to slip through>
+hook  › ⛔ <the hook's actual message>
+agent › <the corrected next step>
+```
 
 ---
 Opened by capt-hook's session reviewer (candidate #<ID>). Merging adopts the rule;
 closing rejects it and the reviewer will not re-propose this candidate.
-```
-
-The Evidence section is the PR's case: every quote verbatim, each with its session id
-and date taken from the Step-2 verification — the transcript file the quote was found
-in names the session (the JSONL filename stem is the session id) and the matching
-line's `timestamp` field gives the date.
+````
+
+The Issue section carries the case: weave the 1–2 strongest corrections in
+verbatim, each with its session id and date from the Step-2 verification (the
+transcript's JSONL filename stem is the session id; the matching line's
+`timestamp` field gives the date). Weaker duplicate quotes drop — one sharp quote
+beats four bullets. The Example section is the sell: a short transcript vignette
+of the recurring situation going better with the hook live, concrete enough that
+the reviewer sees the exact moment the guard lands and what the agent does
+instead. Keep the whole body under ~25 lines; anything the diff already shows
+stays out of it.
 
 A fix PR adapts the template: title `[capt-hook] Fix <slug> misfiring on
-<misfire-class>`; the Rule section states what the hook wrongly fired on and the
-amendment chosen (tightened condition, re-fire guard, live state, demoted severity, or
-removal); the Hook section names the regression test pair (silent on the misfiring
-input, still firing on the genuine case); the Evidence section quotes Claude's
-verbatim complaints with their session ids and dates, plus the decision-ledger attribution
-(`target_hook_name`, the fire's event/action, and its message).
-
-A create-as-edit PR adapts it differently: title `[capt-hook] Broaden <hook-slug>:
-<imperative rule statement>`; the Hook section names the edited hook file
-(repo-relative), what broadened (condition, pattern, or carve-out), and the new test
-pair (fires on the newly covered shape, `Allow()` on its benign neighbor, all
-pre-existing tests untouched and green); Evidence is unchanged. When the edit
-targets a **pack** repo, the Rule section additionally carries a one-sentence
-universality justification — why the broadening is correct for every consumer of
-the pack; a body you cannot write that sentence for is a PR that should not exist
-(route repo-local instead) — and the footer notes the rule was mined from one
-repo's sessions and is proposed as universal, so the pack maintainer can reject on
-that axis alone. A repo-local edit needs neither; the repo's hooks are its own.
+<misfire-class>`; Issue states what the hook wrongly fired on, quoting Claude's
+verbatim complaint (with session id and date) plus the decision-ledger
+attribution (`target_hook_name`, the fire's event/action, and its message); Fix
+names the amendment chosen (tightened condition, re-fire guard, live state,
+demoted severity, or removal) and the regression-test pair (silent on the
+misfiring input, still firing on the genuine case); Example replays the false
+positive going quiet — the once-misfiring input passing clean, beside the genuine
+case still blocked.
+
+A create-as-edit PR adapts it differently: title `[capt-hook] Broaden
+<hook-slug>: <imperative rule statement>`; Fix names the edited hook file
+(repo-relative), what broadened (condition, pattern, or carve-out), and the new
+test pair (fires on the newly covered shape, `Allow()` on its benign neighbor,
+all pre-existing tests untouched and green); Example shows the newly covered
+shape being caught. When the edit targets a **pack** repo, Issue additionally
+carries a one-sentence universality justification — why the broadening is correct
+for every consumer of the pack; a body you cannot write that sentence for is a PR
+that should not exist (route repo-local instead) — and the footer notes the rule
+was mined from one repo's sessions and is proposed as universal, so the pack
+maintainer can reject on that axis alone. A repo-local edit needs neither; the
+repo's hooks are its own.
 
 ```bash
 gh pr create --title "<title>" --body "<body>" \

capt_hook-12.4.0/captain_hook/turn.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cc_transcript.query import Session
+
+if TYPE_CHECKING:
+    from captain_hook.signals.nlp import Clause
+
+
+class Turn(Session):
+    """The current turn as a one-turn :class:`~cc_transcript.query.Session` view.
+
+    What ``evt.ctx.turn`` returns: the full windowed transcript surface
+    (``user_text``, ``has_tool``, ``tool_calls``, …) plus prompt matching, so
+    hooks can test the turn's opening prompt without importing the NLP machinery.
+    """
+
+    __slots__ = ()
+
+    def matches(self, *patterns: str | Clause) -> bool:
+        """Whether the turn's opening prompt matches any pattern.
+
+        A string pattern is a case-insensitive regex; a
+        :class:`~captain_hook.Clause` runs the dependency-clause scan.
+
+        Example:
+            >>> evt.ctx.turn.matches(Clause(noun=Phrase("work"), verb=Phrase("stop", "halt")))
+        """
+        from captain_hook.signals.nlp import scan_text
+
+        return scan_text(self.user_text, patterns)