capt-hook 6.0.0__tar.gz → 6.2.0__tar.gz

{capt_hook-6.0.0 → capt_hook-6.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 6.0.0
+Version: 6.2.0
 Summary: Declarative hook framework for Claude Code
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali

{capt_hook-6.0.0 → capt_hook-6.2.0}/captain_hook/__init__.py

@@ -23,6 +23,7 @@ from captain_hook import file, style, util
 from captain_hook.app import hook, on
 from captain_hook.ast_grep import COMMENT_TYPES
 from captain_hook.command import CommandLine, ParsedCommand, Redirect
+from captain_hook.conditions import workflow_opt_values, workflow_script_source
 from captain_hook.context import HookContext
 from captain_hook.contexts import AfterEdit, BeforeEdit, Introduced, PromptContext, apply_contexts
 from captain_hook.durable import DurableSlot, DurableState, DurableStore

{capt_hook-6.0.0 → capt_hook-6.2.0}/captain_hook/cli.py

@@ -227,6 +227,9 @@ def print_hook_summary(label: str, summary: dict[str, str], deferred_to: str) ->
 
 
 def provision_nlp(resolved: Sequence[manager.ResolvedPack]) -> None:
+    import httpx
+    import wn
+
     from captain_hook.util import http
     from captain_hook.util.model_cache import ensure_nlp_resources
 
@@ -235,7 +238,7 @@ def provision_nlp(resolved: Sequence[manager.ResolvedPack]) -> None:
     click.echo("Provisioning NLP resources (spaCy en_core_web_sm ~13MB + oewn:2025 lexicon ~231MB, cached)...")
     try:
         ensure_nlp_resources()
-    except (http.GitHubFetchError, OSError) as e:
+    except (http.GitHubFetchError, OSError, wn.Error, httpx.HTTPError) as e:
         click.echo(f"  deferred (offline?): {e} — the SessionStart hook will retry at session start")
 
 

{capt_hook-6.0.0 → capt_hook-6.2.0}/captain_hook/conditions.py

@@ -87,6 +87,12 @@ def is_waiting(evt: BaseHookEvent) -> bool:
 
 
 def workflow_script_source(evt: BaseHookEvent) -> str | None:
+    """The pending ``Workflow`` call's script source, or ``None``.
+
+    Returns the inline ``script`` when present, else reads the file at
+    ``scriptPath``. A non-Workflow event, a missing/unreadable path, or a file
+    over ~1 MiB yields ``None``; never raises.
+    """
     if not (call := evt.as_input(WorkflowCall)):
         return None
     if call.script is not None:

{capt_hook-6.0.0 → capt_hook-6.2.0}/captain_hook/contexts.py

@@ -43,12 +43,13 @@ class PromptContext(Protocol):
 class BeforeEdit:
     """The pending edit's pre-image, as a ``<before_edit>`` block.
 
-    Reads :attr:`~captain_hook.events.ToolHookEvent.replaced` — an Edit's old text, a
-    MultiEdit's joined olds, or a Write's current on-disk content — so it carries
-    content only at ``PreToolUse`` on edit-shaped events. Attached to every LLM
-    primitive as a default context; ``required=False`` because it is ambient
-    enrichment, empty (and omitted) on non-edit events. Pass ``BeforeEdit(required=True)``
-    explicitly to gate a hook on a non-empty pre-image.
+    Reads :attr:`~captain_hook.events.ToolHookEvent.replaced` — an Edit's old text or
+    a MultiEdit's joined olds at any event, a Write's current on-disk content only at
+    ``PreToolUse`` (after the Write lands, disk holds the new text). The block is
+    omitted whenever the pre-image is unknowable: non-edit events, Writes off
+    ``PreToolUse``, unreadable paths. Attached to every LLM primitive as a default
+    context; ``required=False`` because it is ambient enrichment. Pass
+    ``BeforeEdit(required=True)`` explicitly to gate a hook on a non-empty pre-image.
     """
 
     tag: str = "before_edit"
@@ -84,6 +85,10 @@ class Introduced:
     see :data:`~captain_hook.ast_grep.COMMENT_TYPES`), ``pattern`` is an ast-grep
     pattern. Extraction diffs the event's before/after text, so only constructs
     absent before the edit appear; files without a supported language yield nothing.
+    The pre-image comes from ``evt.replaced``, so hooks covering Writes need
+    ``events=Event.PreToolUse`` — at any other event a Write's pre-image is
+    unknowable, the context yields ``None``, and (being ``required``) the LLM call
+    skips rather than misreporting every construct as introduced.
 
     ``required`` defaults to ``True``: a context you attach explicitly IS the
     evidence — no evidence, no LLM call. ``tag`` auto-derives from the class name in

{capt_hook-6.0.0 → capt_hook-6.2.0}/captain_hook/events.py

@@ -36,6 +36,18 @@ if TYPE_CHECKING:
 T = TypeVar("T", bound=ToolCallBase)
 
 
+def disk_pre_image(path: Path) -> str | None:
+    if not path.exists():
+        return ""
+    if not path.is_file():
+        return None
+    try:
+        data = path.read_bytes()
+    except OSError:
+        return None
+    return data.decode(errors="replace")
+
+
 @dataclass
 class BaseHookEvent:
     """Base class for all hook events, providing access to raw payload, context, and convenience methods."""
@@ -233,18 +245,20 @@ class ToolHookEvent(BaseHookEvent):
 
     @property
     def replaced(self) -> str | None:
-        """The pre-image of the text this call overwrites.
-
-        An Edit's ``old``, a MultiEdit's newline-joined olds, or — for a Write — the
-        file's current on-disk content (``""`` for a new file). ``None`` for other
-        tools. The Write arm reads the disk, so it is only meaningful at
-        ``PreToolUse``: once the Write lands, disk already holds the new text.
+        """The pre-image of the text this call overwrites, when knowable.
+
+        An Edit's ``old`` and a MultiEdit's newline-joined olds carry the pre-image at
+        any event. A Write's pre-image is the file's current on-disk content — ``""``
+        for a new file, lossily decoded for non-UTF-8 bytes, ``None`` for a directory
+        or unreadable path — and only at ``PreToolUse``: once the Write lands, disk
+        already holds the new text, so any other event yields ``None``. ``None`` for
+        other tools.
         """
         match self.input:
             case EditCall() | MultiEditCall():
                 return self.old
-            case WriteCall(file_path=path):
-                return p.read_text() if (p := Path(path)).exists() else ""
+            case WriteCall(file_path=path) if self.event is Event.PreToolUse:
+                return disk_pre_image(Path(path))
             case _:
                 return None
 

capt_hook-6.2.0/captain_hook/packs/general/_lib.py

@@ -0,0 +1,31 @@
+"""Conditions shared by the general pack's hook modules; the ``_`` prefix keeps the loader from registering it."""
+
+from __future__ import annotations
+
+from captain_hook import BaseHookEvent, CustomCondition
+
+# Prose and config file extensions that shouldn't, on their own, demand a code-review pass.
+# Tailor this (and the excluded dirs below) to scope what counts as "source" for your repo.
+NON_SOURCE_SUFFIXES = (
+    ".md",
+    ".mdx",
+    ".rst",
+    ".txt",
+    ".json",
+    ".toml",
+    ".yaml",
+    ".yml",
+    ".ini",
+    ".cfg",
+    ".lock",
+)
+
+
+class EditedSource(CustomCondition):
+    """True when the session edited a non-test source file (docs and config excluded)."""
+
+    def check(self, evt: BaseHookEvent) -> bool:
+        return any(
+            not f.is_test and f.suffix not in NON_SOURCE_SUFFIXES and not f.under("docs", ".claude", ".github")
+            for f in evt.ctx.t.tool_calls.named("Edit|Write").files()
+        )

{capt_hook-6.0.0 → capt_hook-6.2.0}/captain_hook/packs/general/capt-hook.toml

@@ -1,5 +1,5 @@
 name = "general"
-version = "0.5.0"
-description = "Language-agnostic guards: git/command safety, doc & prompt nudges, task & plan discipline, and a code-review gate."
+version = "0.7.0"
+description = "Language-agnostic guards: git/command safety, doc & prompt nudges, task & plan discipline, and code-review + docs-freshness gates."
 hooks = "."
 nlp = true

capt_hook-6.2.0/captain_hook/packs/general/docs.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import os
+
+from captain_hook import (
+    Allow,
+    BaseHookEvent,
+    Block,
+    CustomCondition,
+    Event,
+    FilePath,
+    Input,
+    Tool,
+    TouchedFile,
+    UsedSkill,
+    Waiting,
+    Warn,
+    llm_gate,
+    nudge,
+)
+from captain_hook.packs.general._lib import EditedSource
+
+
+class Headless(CustomCondition):
+    """True in a headless ``claude -p`` / SDK run (``CLAUDE_CODE_ENTRYPOINT`` in the ``sdk-*`` family)."""
+
+    def check(self, evt: BaseHookEvent) -> bool:
+        return os.environ.get("CLAUDE_CODE_ENTRYPOINT", "").startswith("sdk")
+
+
+# Advisory reminder to consult the writing-docs skill (and run slop-cop) before
+# editing documentation. Fires once per session on the first doc edit and stands
+# down once the skill has been used. Advisory only, so it never blocks an edit.
+#
+# The scaffolded .claude/settings.json registers the yasyf/cc-skills marketplace
+# and enables writing-docs@skills, so the skill (and the skip_if check) activates
+# when the folder is trusted — no manual /plugin install.
+nudge(
+    "You're editing documentation. Consult the writing-docs skill first for the "
+    "Diataxis modes, voice rules, and code-sample rules, then run "
+    "`slop-cop check <file> --lang=markdown` to catch prose tells before you finish. "
+    "slop-cop is a Go binary — if it's not on PATH, run the `/slop-cop-check` skill "
+    "(it installs it), never `uvx slop-cop`.",
+    only_if=[Tool("Write|Edit"), FilePath("**/*.md", "**/*.qmd", "docs/**", "README.md")],
+    skip_if=[UsedSkill("writing-docs")],
+    max_fires=1,
+    tests={
+        Input(tool="Write", file="docs/guide/x.qmd", content="# X"): Warn(pattern="writing-docs"),
+        Input(tool="Edit", file="src/app.py", content="x = 1"): Allow(),
+    },
+)
+
+
+# Docs-freshness gate: after source edits, an LLM reads the uncommitted diff before the
+# agent stops and blocks once when a user-facing change isn't reflected in README.md or
+# docs/. Complements review.py's gate, which reviews correctness — this one reviews
+# documentation. Stands down when the session already touched markdown/docs or used the
+# writing-docs skill, and in headless (cron/CI) runs.
+llm_gate(
+    "You are checking documentation freshness before the agent stops. The compact diff of "
+    "the uncommitted changes is in <diff>. Decide whether the session changed anything "
+    "user-facing — a new flag or option, a renamed command, changed output or behavior, a "
+    "new feature — that README.md or the pages under docs/ don't reflect. Set block=true "
+    "ONLY for a concrete gap, naming exactly which file and section to update in "
+    "`reasoning`. Otherwise block=false. Do not block on internal refactors, test or "
+    "tooling changes, or speculative staleness.",
+    message=lambda r: (
+        f"Docs freshness check found a gap to close before stopping: {r.reasoning} "
+        "Update README.md or docs/ via the writing-docs skill, or state that nothing "
+        "user-facing changed and finish."
+    ),
+    diff=True,
+    only_if=[EditedSource()],
+    skip_if=[
+        Waiting(),
+        TouchedFile("**/*.md", "**/*.qmd"),
+        UsedSkill("writing-docs|writing-docs:writing-docs"),
+        Headless(),
+    ],
+    events=Event.Stop,
+    max_fires=1,
+    tests={
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "name": "Edit",
+                                "id": "e1",
+                                "input": {"file_path": "/repo/src/app.py", "old_string": "a", "new_string": "b"},
+                            }
+                        ]
+                    },
+                },
+            ]
+        ): Block(pattern="writing-docs"),
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "name": "Edit",
+                                "id": "e1",
+                                "input": {"file_path": "/repo/src/app.py", "old_string": "a", "new_string": "b"},
+                            },
+                            {
+                                "type": "tool_use",
+                                "name": "Edit",
+                                "id": "e2",
+                                "input": {"file_path": "/repo/README.md", "old_string": "a", "new_string": "b"},
+                            },
+                        ]
+                    },
+                },
+            ]
+        ): Allow(),
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "name": "Edit",
+                                "id": "e1",
+                                "input": {"file_path": "/repo/README.md", "old_string": "a", "new_string": "b"},
+                            }
+                        ]
+                    },
+                },
+            ]
+        ): Allow(),
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "name": "Edit",
+                                "id": "e1",
+                                "input": {"file_path": "/repo/tests/test_app.py", "old_string": "a", "new_string": "b"},
+                            }
+                        ]
+                    },
+                },
+            ]
+        ): Allow(),
+    },
+)