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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 9.3.0
+Version: 9.5.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.5.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.5.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.5.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.5.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.5.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.5.0}/captain_hook/packs/general/capt-hook.toml

@@ -1,5 +1,5 @@
 name = "general"
-version = "0.17.0"
-description = "Language-agnostic guards: git/jj command safety, doc & prompt nudges, task & plan discipline, model-routing nudges (review, security audit, and diagnosis route to gpt-5.6-sol via the codex-wrapper agent), code-review + docs-freshness gates, a detour check-in nudge, a verbose-comment nudge, and delegated-prose nudges that catch doc writing handed to a subagent or workflow without the writing-docs skill."
+version = "0.18.0"
+description = "Language-agnostic guards: git/jj command safety, doc & prompt nudges, task & plan discipline, model-routing nudges (review, security audit, and diagnosis route to gpt-5.6-sol via the codex-wrapper agent), code-review + docs-freshness gates, a detour check-in nudge, a verbose-comment nudge, a first-turn nudge to batch-load the always-used deferred tools in one ToolSearch call, and delegated-prose nudges that catch doc writing handed to a subagent or workflow without the writing-docs skill."
 hooks = "."
 nlp = true

capt_hook-9.5.0/captain_hook/packs/general/prompts/tools/preload_nudge.md

@@ -0,0 +1,5 @@
+Before anything else on your first turn, load the always-used deferred tools in one batch:
+
+ToolSearch with query "select:TaskCreate,TaskGet,TaskList,TaskOutput,TaskStop,TaskUpdate,Monitor,SendMessage,EnterPlanMode,ExitPlanMode" and max_results 10.
+
+One call covers the whole set — do not load these names one at a time as you first need them. Names already resident or absent in this version simply don't match; that is harmless. Leave every other deferred tool (Cron*, Design*, rarely-used MCP tools) unloaded until the task at hand actually calls for it.

{capt_hook-9.3.0 → capt_hook-9.5.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.5.0/captain_hook/packs/general/tools.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from captain_hook import (
+    Allow,
+    BaseHookEvent,
+    CustomCondition,
+    Event,
+    FromSubagent,
+    Input,
+    Prompt,
+    Warn,
+    nudge,
+)
+from captain_hook.events import SessionStartEvent
+
+
+class FreshSession(CustomCondition):
+    """True when a SessionStart fires from a fresh ``startup`` or ``clear``, not a ``resume`` or ``compact``."""
+
+    def check(self, evt: BaseHookEvent) -> bool:
+        return isinstance(evt, SessionStartEvent) and evt.source in ("startup", "clear")
+
+
+nudge(
+    str(Prompt.load("tools/preload_nudge")),
+    only_if=[FreshSession()],
+    skip_if=[FromSubagent()],
+    events=Event.SessionStart,
+    max_fires=1,
+    tests={
+        Input(source="startup"): Warn(pattern="select:TaskCreate"),
+        Input(source="clear"): Warn(pattern="select:TaskCreate"),
+        Input(source="resume"): Allow(),
+        Input(source="compact"): Allow(),
+        Input(source="startup", agent_id="sub-1"): Allow(),
+        Input(source="clear", agent_id="sub-1"): Allow(),
+    },
+)

{capt_hook-9.3.0 → capt_hook-9.5.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.5.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