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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 4.0.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.0.0 → capt_hook-4.2.0}/captain_hook/context.py

@@ -5,7 +5,7 @@ import subprocess
 from dataclasses import dataclass, replace
 from functools import cached_property
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 from cc_transcript.activity import SessionActivity, meta_of
 from cc_transcript.ids import SessionId
@@ -32,6 +32,19 @@ if TYPE_CHECKING:
     from captain_hook.settings import HooksSettings
 
 
+RECENT_WINDOW = 15
+
+
+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):
     """A ``ToolUseBlock`` whose typed parse degrades to ``OtherCall`` instead of raising.
 
@@ -134,19 +147,26 @@ class HookContext:
         """The session window before the current turn's last exchange (cached)."""
         return self.transcript.prior()
 
-    def transcript_text(self) -> str:
-        """The transcript rendered turn by turn under the default budget."""
-        return "\n\n".join(
-            rendered for turn in self.transcript.turns if (rendered := render_turn(turn, budget=Budget()))
-        )
+    def transcript_text(self, *, window: int | None = None) -> str:
+        """The transcript rendered turn by turn under the default budget.
+
+        Args:
+            window: Render only the most recent ``window`` events; ``None`` renders the whole session.
+        """
+        src = self.transcript if window is None else self.transcript.recent(window)
+        return "\n\n".join(rendered for turn in src.turns if (rendered := render_turn(turn, budget=Budget())))
 
-    def transcript_block(self) -> str:
+    def transcript_block(self, *, window: int | None = RECENT_WINDOW) -> str:
         """The rendered transcript wrapped in a ``<transcript>`` tag carrying its source path.
 
-        The render clips long turns and tool calls under :class:`Budget`, so an agent-mode
-        LLM needs the path to read the untruncated content (e.g. a full ``ExitPlanMode`` plan).
+        Defaults to a recent-event window rather than the whole session. The render clips long
+        turns and tool calls under :class:`Budget`, so an agent-mode LLM uses the path to read
+        the untruncated content (e.g. a full ``ExitPlanMode`` plan) or earlier history.
+
+        Args:
+            window: Render only the most recent ``window`` events; ``None`` renders the whole session.
         """
-        rendered = self.transcript_text()
+        rendered = self.transcript_text(window=window)
         if (path := self.transcript.path) is not None:
             return f'<transcript path="{path}">\n{rendered}\n</transcript>'
         return f"<transcript>\n{rendered}\n</transcript>"
@@ -179,6 +199,56 @@ class HookContext:
         except (subprocess.CalledProcessError, FileNotFoundError):
             return None
 
+    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 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"`` (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: Token budget for both the ``ccx`` output and the bounded git fallback.
+        """
+        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"]
+            case "staged":
+                args = ["diff", "--staged"]
+            case ref:
+                args = ["diff", ref]
+        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:
         if (out := self.git("diff", "--name-only", "HEAD", "--no-renames")) is None or (root := self.repo_root) is None:
@@ -202,19 +272,24 @@ class HookContext:
         specialty: TSpecialty = "general",
         model: TModel = "small",
         timeout: int = 180,
-        transcript: bool = False,
+        transcript: bool | int | Literal["recent", "full"] = False,
+        diff: bool | str = False,
         agent: bool = False,
         response_model: type[BaseModel] | None = None,
         **kwargs: Any,
     ) -> str | BaseModel:
+        diff_text = self.diff("uncommitted" if diff is True else diff) if diff else None
         if isinstance(template, Prompt):
-            prompt = str(template)
+            prompt = str(template.context("diff", diff_text))
             if transcript:
-                prompt = f"{self.transcript_block()}\n\n<task>\n{prompt}\n</task>"
+                prompt = f"{self.transcript_block(window=transcript_window(transcript))}\n\n<task>\n{prompt}\n</task>"
         else:
+            block = self.transcript_block(window=transcript_window(transcript)) if transcript else ""
             if transcript:
                 template = f"{{transcript}}\n\n<task>\n{template}\n</task>"
-            prompt = template.format(*args, **kwargs, transcript=self.transcript_block())
+            prompt = template.format(*args, **kwargs, transcript=block)
+            if diff_text is not None:
+                prompt = f"<diff>\n{diff_text}\n</diff>\n\n{prompt}"
         backend = LlmBackends.for_specialty(specialty)
         cwd = os.environ.get("CLAUDE_PROJECT_DIR") or os.environ.get("FACTORY_PROJECT_DIR")
         if response_model is not None:

{capt_hook-4.0.0 → capt_hook-4.2.0}/captain_hook/packs/general/review.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from captain_hook import Allow, BaseHookEvent, Block, CustomCondition, Event, Input, Waiting, gate
+from captain_hook import Allow, BaseHookEvent, Block, CustomCondition, Event, Input, llm_gate
 
 # 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.
@@ -29,12 +29,16 @@ class EditedSource(CustomCondition):
         )
 
 
-gate(
-    "You changed source files but haven't done a review pass. Before stopping, review your "
-    "changes for correctness and against STYLEGUIDE.md, and fix any issues in the code you "
-    "wrote. See: STYLEGUIDE.md.",
+llm_gate(
+    "You are reviewing a code change before the agent stops. The compact diff of the "
+    "uncommitted changes is in <diff>. Review it for (1) correctness bugs and (2) clear "
+    "violations of the project's STYLEGUIDE.md (read STYLEGUIDE.md from the working dir). "
+    "Set block=true ONLY for a concrete, real issue in the changed code, with the specific "
+    "problem and the fix in `reasoning`. Otherwise block=false. Do not block on style nits "
+    "absent from STYLEGUIDE, on unchanged pre-existing code, or on speculative concerns.",
+    message=lambda r: f"Review flagged an issue to fix before stopping: {r.reasoning}",
+    diff=True,
     only_if=[EditedSource()],
-    skip_if=[Waiting()],
     events=Event.Stop,
     tests={
         Input(

{capt_hook-4.0.0 → capt_hook-4.2.0}/captain_hook/primitives/llm.py

@@ -65,7 +65,8 @@ def llm_evaluate[M: BaseModel](
     specialty: TSpecialty = "review",
     model: TModel = "small",
     agent: bool = False,
-    transcript: bool = False,
+    transcript: bool | int | Literal["recent", "full"] = False,
+    diff: bool | str = False,
 ) -> M | None:
     if fired_this_turn(evt):
         return None
@@ -99,6 +100,7 @@ def llm_evaluate[M: BaseModel](
             model=model,
             agent=agent,
             transcript=transcript,
+            diff=diff,
             response_model=response_model,
         )
     except Exception:
@@ -137,7 +139,8 @@ def llm_primitive[M: BaseModel](
     specialty: TSpecialty = "review",
     model: TModel = "small",
     agent: bool = False,
-    transcript: bool = False,
+    transcript: bool | int | Literal["recent", "full"] = False,
+    diff: bool | str = False,
 ) -> None:
     sig = resolve_signals(signals)
 
@@ -154,6 +157,7 @@ def llm_primitive[M: BaseModel](
                 model=model,
                 agent=agent,
                 transcript=transcript,
+                diff=diff,
             )
         ):
             return None
@@ -197,13 +201,15 @@ def llm_gate(
     specialty: TSpecialty = "review",
     model: TModel = "small",
     agent: bool = True,
-    transcript: bool = True,
+    transcript: bool | int | Literal["recent", "full"] = True,
+    diff: bool | str = False,
 ) -> None:
     """Register an LLM-powered blocking gate.
 
     Defaults are tuned for the common case: ``agent=True`` and ``transcript=True``
-    so the gate has tool access and full transcript context. Pass
-    ``agent=False, transcript=False`` for cheap, stateless yes/no checks.
+    so the gate has tool access and a recent transcript window (the path lets the agent
+    read full history). Pass ``diff=True`` to attach a compact working-tree diff as a
+    ``<diff>`` block, or ``agent=False, transcript=False`` for cheap, stateless yes/no checks.
 
     Example:
         >>> llm_gate("Is the agent making excuses?",
@@ -231,6 +237,7 @@ def llm_gate(
         model=model,
         agent=agent,
         transcript=transcript,
+        diff=diff,
     )
 
 
@@ -252,13 +259,15 @@ def llm_nudge(
     specialty: TSpecialty = "review",
     model: TModel = "small",
     agent: bool = True,
-    transcript: bool = True,
+    transcript: bool | int | Literal["recent", "full"] = True,
+    diff: bool | str = False,
 ) -> None:
     """Register an LLM-powered advisory nudge.
 
     Defaults are tuned for the common case: ``agent=True`` and ``transcript=True``
-    so the nudge has tool access and full transcript context. Pass
-    ``agent=False, transcript=False`` for cheap, stateless yes/no checks.
+    so the nudge has tool access and a recent transcript window (the path lets the agent
+    read full history). Pass ``diff=True`` to attach a compact working-tree diff as a
+    ``<diff>`` block, or ``agent=False, transcript=False`` for cheap, stateless yes/no checks.
 
     Example:
         >>> llm_nudge("Is the agent speculating instead of observing?",
@@ -287,6 +296,7 @@ def llm_nudge(
         model=model,
         agent=agent,
         transcript=transcript,
+        diff=diff,
     )
 
 
@@ -343,6 +353,7 @@ def prompt_check(
     suffix: str = "",
     timeout: int = 45,
     include_reasoning: bool = True,
+    diff: bool | str = False,
     response_model: type[PromptCheckVerdict] = PromptCheckVerdict,
 ) -> HookResult | None:
     """Run an LLM check with a formatted prompt and return block/warn/None."""
@@ -356,6 +367,7 @@ def prompt_check(
         verdict = evt.ctx.call_llm(
             built,
             timeout=timeout,
+            diff=diff,
             response_model=response_model,
         )
     except Exception as exc:

{capt_hook-4.0.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.0.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.0.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.0.0"
+version = "4.2.0"
 description = "Declarative hook framework for Claude Code"
 readme = "README.md"
 license = "PolyForm-Noncommercial-1.0.0"