capt-hook 4.1.0__tar.gz → 4.2.0__tar.gz

{capt_hook-4.1.0 → capt_hook-4.2.0}/PKG-INFO

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

{capt_hook-4.1.0 → capt_hook-4.2.0}/captain_hook/context.py

@@ -35,10 +35,14 @@ if TYPE_CHECKING:
 RECENT_WINDOW = 15
 
 
-def transcript_window(transcript: bool | int | str) -> int | None:
-    if transcript == "full":
-        return None
-    return transcript if isinstance(transcript, int) and transcript is not True else RECENT_WINDOW
+def transcript_window(transcript: bool | int | Literal["recent", "full"]) -> int | None:
+    match transcript:
+        case "full":
+            return None
+        case True | "recent":
+            return RECENT_WINDOW
+        case int() as events:
+            return events
 
 
 class LenientToolUseBlock(ToolUseBlock):
@@ -195,23 +199,37 @@ class HookContext:
         except (subprocess.CalledProcessError, FileNotFoundError):
             return None
 
-    def diff(self, source: str = "uncommitted", *, scope: str | None = None, budget: int = 4000) -> str | None:
-        """A compact working-tree diff via ``ccx diff`` when available, else plain ``git diff``.
+    def diff(
+        self,
+        source: str = "uncommitted",
+        *,
+        commit: str | None = None,
+        scope: str | None = None,
+        budget: int = 4000,
+    ) -> str | None:
+        """A compact diff via ``ccx diff`` when available, else plain ``git``.
 
-        Prefers cc-context's token-budgeted ``ccx diff`` and transparently falls back to
-        ``git diff`` when ``ccx`` is absent or fails, so a hook gets the same diff in any repo.
+        Prefers cc-context's token-budgeted ``ccx diff`` and falls back to ``git`` when ``ccx`` is
+        absent, fails, or returns a hunkless symbol-outline (no ``@@`` / ``diff --git`` lines, as in
+        jj-colocated repos), so a hook gets a real diff in any repo. The git fallback is bounded to
+        roughly ``budget`` tokens with a trailing marker when truncated, so a large diff can't blow
+        the caller's context.
 
         Args:
-            source: ``"uncommitted"`` (working tree, the default), ``"staged"``, or any git ref.
+            source: ``"uncommitted"`` (the default), ``"staged"``, or any git ref. Ignored when
+                ``commit`` is set.
+            commit: When set, the diff *introduced by* this commit (root-commit-safe), overriding
+                ``source``; its git fallback is ``git show --stat -p``, so it carries the commit
+                header + diffstat ahead of the patch.
             scope: Restrict the diff to this path.
-            budget: Approximate token budget for the ``ccx`` output (the ``git`` fallback is unbounded).
-
-        Returns:
-            The rendered diff, or ``None`` when neither ``ccx`` nor ``git`` produces output.
+            budget: Token budget for both the ``ccx`` output and the bounded git fallback.
         """
-        ccx = ["ccx", "diff", source, "--budget", str(budget), *(("--scope", scope) if scope else ())]
-        if (out := self.call_cli(ccx, throw=False)) is not None:
+        target = f"{commit}~1..{commit}" if commit is not None else source
+        if (out := self.ccx_diff(target, scope=scope, budget=budget)) is not None:
             return out
+        git_scope = ("--", scope) if scope else ()
+        if commit is not None:
+            return self.bounded_git(budget, "show", "--stat", "-p", commit, *git_scope)
         match source:
             case "uncommitted":
                 args = ["diff"]
@@ -219,7 +237,17 @@ class HookContext:
                 args = ["diff", "--staged"]
             case ref:
                 args = ["diff", ref]
-        return self.git(*args, *(("--", scope) if scope else ()))
+        return self.bounded_git(budget, *args, *git_scope)
+
+    def ccx_diff(self, target: str, *, scope: str | None, budget: int) -> str | None:
+        cmd = ["ccx", "diff", target, "--budget", str(budget), *(("--scope", scope) if scope else ())]
+        out = self.call_cli(cmd, throw=False)
+        return out if out is not None and ("@@" in out or "diff --git" in out) else None
+
+    def bounded_git(self, budget: int, *args: str) -> str | None:
+        if (out := self.git(*args)) is None or len(out) <= (limit := budget * 4):
+            return out
+        return out[:limit].rstrip() + f"\n... [diff truncated to ~{budget} tokens] ..."
 
     @cached_property
     def changed_paths(self) -> frozenset[Path] | None:

{capt_hook-4.1.0 → capt_hook-4.2.0}/captain_hook/session.py

@@ -5,7 +5,7 @@ import re
 import shutil
 import tempfile
 import time
-from collections.abc import Sequence
+from collections.abc import Iterable, Sequence
 from pathlib import Path
 from typing import ClassVar, Generic, TypeVar, overload
 
@@ -119,6 +119,30 @@ class SessionStore:
         """
         return self[model].get(model())
 
+    def once(self, key: str, *, scope: str | None = None) -> bool:
+        """Return ``True`` the first time ``(scope, key)`` is seen this session, ``False`` thereafter.
+
+        Keyed, scoped dedup for hook authors — the single-key case of :meth:`unseen`.
+        """
+        return bool(self.unseen([key], scope=scope))
+
+    def unseen(self, keys: Iterable[str], *, scope: str | None = None) -> list[str]:
+        """Return the first-sight ``keys`` under ``scope``, recording the whole fresh subset in one write.
+
+        De-duplicates within the batch (order-preserving) and marks every returned key before any
+        downstream filtering, so a batch is never partially recorded; no write when nothing is fresh.
+        ``scope`` namespaces independent call sites on the shared session store.
+        """
+        from captain_hook.state import SeenKeys
+
+        blob = self.load(SeenKeys)
+        seen = blob.seen.setdefault(scope or "", [])
+        if not (fresh := [key for key in dict.fromkeys(keys) if key not in seen]):
+            return []
+        seen.extend(fresh)
+        self[SeenKeys].set(blob)
+        return fresh
+
     @classmethod
     def track(cls, model: type[BaseModel]) -> None:
         """Register ``model`` so it appears in ``tracked_models()`` and ``tracked_paths()``."""

{capt_hook-4.1.0 → capt_hook-4.2.0}/captain_hook/state.py

@@ -227,5 +227,12 @@ def workflow_state(name: str) -> Callable[[type[T]], type[T]]:
     return wrap
 
 
+class SeenKeys(BaseModel):
+    """Session-scoped record of keys observed by ``SessionStore.once``/``unseen``, namespaced by scope."""
+
+    seen: dict[str, list[str]] = Field(default_factory=dict)
+
+
 SessionStore.track(HookState)
 SessionStore.track(PrimitiveState)
+SessionStore.track(SeenKeys)

{capt_hook-4.1.0 → capt_hook-4.2.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "capt-hook"
 # Inert sentinel — the real version is stamped from the release tag (uv version --frozen).
-version = "4.1.0"
+version = "4.2.0"
 description = "Declarative hook framework for Claude Code"
 readme = "README.md"
 license = "PolyForm-Noncommercial-1.0.0"