capt-hook 9.3.0__tar.gz → 9.4.0__tar.gz

{capt_hook-9.3.0 → capt_hook-9.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 9.3.0
+Version: 9.4.0
 Summary: Stop repeating yourself to Claude.
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali

{capt_hook-9.3.0 → capt_hook-9.4.0}/captain_hook/app.py

@@ -8,6 +8,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, get_args
 
 from captain_hook.conditions import matches_conditions
+from captain_hook.state import caller_file, hook_name
 from captain_hook.types import (
     Agent,
     Command,
@@ -113,7 +114,6 @@ class State:
     settings: HooksSettings | None = None
     classifier: UserClassifier | None = None
     load_errors: list[LoadError] = field(default_factory=list)
-    counter: int = field(default=0, repr=False)
 
 
 _state = State()
@@ -123,7 +123,6 @@ def reset() -> None:
     _state.hooks.clear()
     _state.gitignore_patterns.clear()
     _state.load_errors.clear()
-    _state.counter = 0
     _state.settings = None
     _state.classifier = None
 
@@ -161,7 +160,6 @@ def hook(
 ) -> None:
     validate_conditions(only_if, "only_if", events)
     validate_conditions(skip_if, "skip_if", events)
-    _state.counter += 1
     _state.hooks.append(
         RegisteredHook(
             spec=HookSpec(
@@ -176,7 +174,8 @@ def hook(
                 async_=async_,
                 skip_planning_agents=skip_planning_agents,
             ),
-            name=f"declarative_{_state.counter}",
+            name=hook_name("hook", None, message),
+            source_file=caller_file(),
         )
     )
 

{capt_hook-9.3.0 → capt_hook-9.4.0}/captain_hook/cli.py

@@ -17,7 +17,14 @@ from loguru import logger
 
 from captain_hook.app import _state, load_gitignore, reset
 from captain_hook.dispatch import dispatch
-from captain_hook.loader import CONF_MODULE, discover_hooks, discover_pack, is_skip_marked, register_nlp_provisioning
+from captain_hook.loader import (
+    CONF_MODULE,
+    discover_hooks,
+    discover_pack,
+    is_skip_marked,
+    register_nlp_provisioning,
+    register_pr_announcements,
+)
 from captain_hook.log import setup_logging
 from captain_hook.once import claim_once
 from captain_hook.packs import manager
@@ -54,6 +61,10 @@ class CliState:
         project_nlp = any(pack_.manifest.nlp for pack_ in resolved)
         if project_nlp:
             register_nlp_provisioning()
+        # The PR announcer is one shared sync SessionStart hook, registered unconditionally.
+        # All gating (spawned run, no repo, no DB, repo not watching) lives in
+        # collect_announcements, so registration needs no settings or store inspection here.
+        register_pr_announcements()
         attached = self.attached_packs(resolved, session_dir)
         for pack_ in attached:
             discover_pack(pack_.entry.name, pack_.path)

{capt_hook-9.3.0 → capt_hook-9.4.0}/captain_hook/hooks/hooks.json

@@ -3,85 +3,98 @@
     "PreToolUse": [
       {
         "hooks": [
-          { "type": "command", "command": "uvx capt-hook run PreToolUse" }
+          { "type": "command", "command": "uvx capt-hook run PreToolUse" },
+          { "type": "command", "command": "uvx capt-hook run PreToolUse --async", "async": true }
         ]
       }
     ],
     "PostToolUse": [
       {
         "hooks": [
-          { "type": "command", "command": "uvx capt-hook run PostToolUse" }
+          { "type": "command", "command": "uvx capt-hook run PostToolUse" },
+          { "type": "command", "command": "uvx capt-hook run PostToolUse --async", "async": true }
         ]
       }
     ],
     "PostToolUseFailure": [
       {
         "hooks": [
-          { "type": "command", "command": "uvx capt-hook run PostToolUseFailure" }
+          { "type": "command", "command": "uvx capt-hook run PostToolUseFailure" },
+          { "type": "command", "command": "uvx capt-hook run PostToolUseFailure --async", "async": true }
         ]
       }
     ],
     "UserPromptSubmit": [
       {
         "hooks": [
-          { "type": "command", "command": "uvx capt-hook run UserPromptSubmit" }
+          { "type": "command", "command": "uvx capt-hook run UserPromptSubmit" },
+          { "type": "command", "command": "uvx capt-hook run UserPromptSubmit --async", "async": true }
         ]
       }
     ],
     "Stop": [
       {
         "hooks": [
-          { "type": "command", "command": "uvx capt-hook run Stop" }
+          { "type": "command", "command": "uvx capt-hook run Stop" },
+          { "type": "command", "command": "uvx capt-hook run Stop --async", "async": true }
         ]
       }
     ],
     "SubagentStop": [
       {
         "hooks": [
-          { "type": "command", "command": "uvx capt-hook run SubagentStop" }
+          { "type": "command", "command": "uvx capt-hook run SubagentStop" },
+          { "type": "command", "command": "uvx capt-hook run SubagentStop --async", "async": true }
         ]
       }
     ],
     "SubagentStart": [
       {
         "hooks": [
-          { "type": "command", "command": "uvx capt-hook run SubagentStart" }
+          { "type": "command", "command": "uvx capt-hook run SubagentStart" },
+          { "type": "command", "command": "uvx capt-hook run SubagentStart --async", "async": true }
         ]
       }
     ],
     "PreCompact": [
       {
         "hooks": [
-          { "type": "command", "command": "uvx capt-hook run PreCompact" }
+          { "type": "command", "command": "uvx capt-hook run PreCompact" },
+          { "type": "command", "command": "uvx capt-hook run PreCompact --async", "async": true }
         ]
       }
     ],
     "Notification": [
       {
         "hooks": [
-          { "type": "command", "command": "uvx capt-hook run Notification" }
+          { "type": "command", "command": "uvx capt-hook run Notification" },
+          { "type": "command", "command": "uvx capt-hook run Notification --async", "async": true }
         ]
       }
     ],
     "PermissionRequest": [
       {
         "hooks": [
-          { "type": "command", "command": "uvx capt-hook run PermissionRequest" }
+          { "type": "command", "command": "uvx capt-hook run PermissionRequest" },
+          { "type": "command", "command": "uvx capt-hook run PermissionRequest --async", "async": true }
         ]
       }
     ],
     "SessionStart": [
       {
         "hooks": [
-          { "type": "command", "command": "uvx capt-hook run SessionStart --async", "async": true }
+          { "type": "command", "command": "uvx capt-hook run SessionStart" },
+          { "type": "command", "command": "uvx capt-hook run SessionStart --async", "async": true },
+          { "type": "command", "command": "uvx capt-hook review run", "async": true }
         ]
       }
     ],
     "SessionEnd": [
       {
         "hooks": [
-          { "type": "command", "command": "uvx capt-hook review run", "async": true },
-          { "type": "command", "command": "uvx capt-hook run SessionEnd --async", "async": true }
+          { "type": "command", "command": "uvx capt-hook run SessionEnd" },
+          { "type": "command", "command": "uvx capt-hook run SessionEnd --async", "async": true },
+          { "type": "command", "command": "uvx capt-hook review run", "async": true }
         ]
       }
     ]

{capt_hook-9.3.0 → capt_hook-9.4.0}/captain_hook/loader.py

@@ -14,13 +14,14 @@ from typing import TYPE_CHECKING
 from loguru import logger
 
 from captain_hook.app import LoadError, _state, on
+from captain_hook.state import PACK_PACKAGE_PREFIX
 from captain_hook.types import Event
 
 if TYPE_CHECKING:
     from captain_hook.events import BaseHookEvent
+    from captain_hook.types import HookResult
 
 CONF_MODULE = "conf"
-PACK_PACKAGE_PREFIX = "captain_hook._packs"
 
 
 def is_test_module(fqn: str) -> bool:
@@ -124,8 +125,29 @@ def register_nlp_provisioning() -> None:
         ensure_nlp_resources()
 
 
+def register_pr_announcements() -> None:
+    """Register the shared sync SessionStart hook that surfaces changed PR outcomes to the user.
+
+    Called once per discovery pass, unconditionally: every gate (spawned run, no repo, no
+    database, repo not watched) lives in :func:`~captain_hook.review.announce.collect_announcements`.
+    The detached reviewer opens and resolves hook PRs on its own; this hook is how a session
+    start tells the user what happened.
+    """
+
+    @on(Event.SessionStart, max_fires=1)
+    def announce_pr_status(evt: BaseHookEvent) -> HookResult | None:
+        from captain_hook.review.announce import collect_announcements
+        from captain_hook.types import Action, HookResult
+
+        if message := collect_announcements(evt.ctx.project_root):
+            return HookResult(action=Action.warn, message=message)
+        return None
+
+
 def discover_pack(name: str, pack_dir: Path) -> None:
-    pkg = f"{PACK_PACKAGE_PREFIX}.{re.sub(r'\W', '_', name)}"
+    from captain_hook.packs.manager import pack_module_name
+
+    pkg = f"{PACK_PACKAGE_PREFIX}.{pack_module_name(name)}"
     ensure_pack_package(PACK_PACKAGE_PREFIX, [])
     ensure_pack_package(pkg, [str(pack_dir)])
     for path in sorted(pack_dir.glob("*.py")):

{capt_hook-9.3.0 → capt_hook-9.4.0}/captain_hook/once.py

@@ -4,7 +4,8 @@ Claude Code runs the byte-identical ``uvx capt-hook run <Event>`` command once p
 registering source (project settings plus each plugin), so one event fans out into
 N sibling processes reading identical stdin within milliseconds of each other. A
 side-effecting hook then fires N times. The guard lets the first sibling win an
-``O_EXCL`` sentinel keyed by the event and its payload; the rest exit silently.
+``O_EXCL`` sentinel keyed by the event, its sync/async variant, and its payload; the
+rest exit silently.
 
 Best-effort only: no locking beyond the atomic create, no daemon. A TTL bounds how
 long a claim suppresses siblings (covering uvx's multi-second startup skew) and how

{capt_hook-9.3.0 → capt_hook-9.4.0}/captain_hook/packs/general/tombstones.py

@@ -81,10 +81,12 @@ def is_tombstone(text: str) -> bool:
                         "retire",
                         "deprecate",
                     ),
-                    completed=True,
+                    tense="completed",
                     subject="no_nominal",
                 ),
-                Clause(verb=Phrase("be"), adj=Phrase("previously", "formerly", "originally", "here"), completed=True),
+                Clause(
+                    verb=Phrase("be"), adj=Phrase("previously", "formerly", "originally", "here"), tense="completed"
+                ),
             ],
             text,
         )

{capt_hook-9.3.0 → capt_hook-9.4.0}/captain_hook/packs/manager.py

@@ -51,6 +51,11 @@ PACK_NAME_RE = re.compile(r"[a-z][a-z0-9-]*")
 KEEP_COMMITS = 2
 
 
+def pack_module_name(name: str) -> str:
+    """The import-safe module component a pack loads under (a pack name's hyphens become underscores)."""
+    return re.sub(r"\W", "_", name)
+
+
 class PackError(Exception):
     """A pack source, manifest, or enabled-packs entry was invalid or unresolvable."""
 

{capt_hook-9.3.0 → capt_hook-9.4.0}/captain_hook/packs/steering/capt-hook.toml

@@ -1,5 +1,5 @@
 name = "steering"
-version = "0.6.0"
+version = "0.7.0"
 description = "Steer the agent's judgment on what's worth fixing: prefer fundamental, first-principles fixes over band-aids, don't dismiss a real pre-existing issue, don't chase trivial type noise, don't defer the requested fix by swapping in docs or a follow-up nobody asked for, and remind a starting teammate to return tight digests instead of flooding the shared context."
 hooks = "."
 nlp = true

{capt_hook-9.3.0 → capt_hook-9.4.0}/captain_hook/packs/steering/steering.py

@@ -47,21 +47,31 @@ nudge(
     skip_if=[TypeCheckerContext()],
     signals=Signals(
         [
-            Signal(pattern=r"(?i)(?:pre-existing|preexisting)", weight=1),
-            Signal(pattern=r"(?i)(?:outside|beyond) (?:the )?scope", weight=1),
+            Signal(
+                pattern=(
+                    r"(?i)\b(?:pre-?existing|already (?:existed|present|broken)"
+                    r"|(?:existing|known|old|previous) (?:issue|bug|problem|failure)s?)\b"
+                ),
+                weight=1,
+            ),
+            Signal(pattern=r"(?i)(?<!no change )(?<!no changes )(?:outside|beyond) (?:the )?scope", weight=1),
             NlpSignal(
                 clauses=[
                     Clause(noun=Phrase.expand("change"), verb=Phrase("cause", "introduce"), negated=True),
-                    Clause(noun=Phrase.expand("issue"), verb=Phrase("leave")),
+                    Clause(
+                        noun=Phrase("issue", "bug", "problem", "error", "failure", "violation", "warning"),
+                        verb=Phrase("leave"),
+                        tense="prospective",
+                    ),
+                    Clause(
+                        noun=Phrase("test"),
+                        verb=Phrase("leave"),
+                        adj=Phrase("broken", "failing", "flaky"),
+                        tense="prospective",
+                    ),
                 ],
                 weight=2,
             ),
-            NlpSignal(
-                clauses=[
-                    Clause(noun=Phrase.expand("issue"), adj=Phrase("existing", "present", "previous")),
-                ],
-                weight=1,
-            ),
         ],
         threshold=2,
         window=15,
@@ -254,6 +264,296 @@ nudge(
                 }
             ]
         ): Warn(),
+        # FIX-mode regression matrix (misfires watched live 2026-07-10); message byte-identical.
+        # m1 briefing-quote: dismissal quoted into a subagent briefing arrives user-role -> origin drop
+        Input(
+            transcript=[
+                {
+                    "type": "user",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": (
+                                    "Review this transcript excerpt for whether the nudge should have fired:\n"
+                                    "> That's a pre-existing issue, not caused by my change. I'll leave the broken "
+                                    "test as is since it's beyond the scope of my change.\n"
+                                    "Report your assessment."
+                                ),
+                            }
+                        ]
+                    },
+                },
+                {
+                    "type": "assistant",
+                    "message": {"content": [{"type": "text", "text": "Starting the review of that excerpt now."}]},
+                },
+            ]
+        ): Allow(),
+        # m2 TaskUpdate-description: misfire note (PROSE_TOOLS path) scores "pre-existing" once post-merge
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "id": "tu_upd",
+                                "name": "TaskUpdate",
+                                "input": {
+                                    "subject": "Investigate steering nudge misfire",
+                                    "description": (
+                                        "The pre-existing issue nudge fired again on a quoted transcript; "
+                                        "capturing the offending shape for the fix."
+                                    ),
+                                },
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Allow(),
+        # m3 salvage-assessment: salvage-vs-rerun reasoning naming the misfire scores "pre-existing" once
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": (
+                                    "Ignoring the pre-existing issue with the hook misfires for a moment — I'm "
+                                    "assessing the partial work to decide whether to salvage the existing progress "
+                                    "or rerun from scratch."
+                                ),
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Allow(),
+        # m4 quoted-fixture: this file's own fixtures read back arrive user-role -> origin drop
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {"content": [{"type": "text", "text": "Reading the steering pack fixtures."}]},
+                },
+                {
+                    "type": "user",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": (
+                                    "steering.py fixtures:\n"
+                                    "  \"Let's just leave the login issue for now; it's pre-existing and beyond "
+                                    "the scope of my change.\"  -> Warn()\n"
+                                    "  \"That's a pre-existing issue, not caused by my change.\"  -> Warn()"
+                                ),
+                            }
+                        ]
+                    },
+                },
+            ]
+        ): Allow(),
+        # m5 self-echo: the nudge's own opening sentence echoed back scores "pre-existing" once post-merge
+        # (verbatim cross-turn echoes are additionally damped by echo_verbatim on a real dispatch, 8.18.0)
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": (
+                                    "You appear to be dismissing a pre-existing issue rather than fixing it. "
+                                    "Acknowledged — I'll actually fix it."
+                                ),
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Allow(),
+        # m6 user-origin: full dismissal in a user message (scores 4 as assistant prose) -> origin drop
+        Input(
+            transcript=[
+                {
+                    "type": "user",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": (
+                                    "That's a pre-existing issue, not caused by my change, and it's beyond the "
+                                    "scope of my change — I'll leave the broken test as is."
+                                ),
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Allow(),
+        # fl1 fire-log completion: past-tense "left" (VBD) is not a prospective leave
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": (
+                                    "Fixed the failing test and left the flaky one documented in the tracking "
+                                    "issue so we can revisit it deliberately."
+                                ),
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Allow(),
+        # fl2 fire-log completion: real report, "pre-existing" scored once + past "left" not matched
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": (
+                                    "Landed the parser fix; I left the pre-existing lint warnings alone since they "
+                                    "predate this change, and all 42 tests pass."
+                                ),
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Allow(),
+        # tp_existing_issue: genuine dismissal pairing "pre-existing" with change-not-caused still warns
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": (
+                                    "That's a pre-existing issue, not caused by my change — I'm not going to touch it."
+                                ),
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Warn(),
+        # tp_prospective_leave: genuine prospective dismissal ("I'll leave the broken test") still warns
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [{"type": "text", "text": "I'll leave the broken test as is."}]
+                    },
+                }
+            ]
+        ): Warn(),
+        # tp_leave_flaky_test: a flaky (ADJ) defect qualifier on "leave the test" still warns
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {"content": [{"type": "text", "text": "I'll leave the flaky test as is."}]},
+                }
+            ]
+        ): Warn(),
+        # f16 leave-test-no-defect: prospective "leave the test" with no defect qualifier is benign
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": "I'll leave the integration test running while I inspect its logs.",
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Allow(),
+        # f17 negated-scope: "made no changes outside the scope" is scope compliance, not dismissal
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": "I fixed all known issues and made no changes outside the scope of the task.",
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Allow(),
+        # f18a modal-perfect counterfactual: "should have left ... but I fixed it" is not a prospective leave
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {"type": "text", "text": "I should have left the broken test alone, but I fixed it."}
+                        ]
+                    },
+                }
+            ]
+        ): Allow(),
+        # f18b negated prospective: "Leaving ... was never an option, so I fixed it" is not a dismissal
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {"type": "text", "text": "Leaving the test broken was never an option, so I fixed it."}
+                        ]
+                    },
+                }
+            ]
+        ): Allow(),
+        # f19 previous-issue dismissal: "the previous issue is beyond the scope" warns (regex arm restored)
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [{"type": "text", "text": "The previous issue is beyond the scope of this change."}]
+                    },
+                }
+            ]
+        ): Warn(),
+        # f21 word-boundary: "unknown bugs" must not match the "known bug" arm
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [{"type": "text", "text": "There are no unknown bugs left outside scope."}]
+                    },
+                }
+            ]
+        ): Allow(),
     },
 )