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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 4.1.0
+Version: 4.3.0
 Summary: Declarative hook framework for Claude Code
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali
@@ -31,7 +31,7 @@ Requires-Dist: wn>=1.1.0
 Requires-Dist: lazy-object-proxy>=1.12.0
 Requires-Dist: filelock>=3
 Requires-Dist: loguru>=0.7.3
-Requires-Dist: spawnllm>=0.5.0
+Requires-Dist: spawnllm>=0.5.2,<0.6
 Requires-Dist: pytest>=8.0 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
 Requires-Dist: pyright>=1.1 ; extra == 'dev'

{capt_hook-4.1.0 → capt_hook-4.3.0}/captain_hook/__init__.py

@@ -19,10 +19,11 @@ from cc_transcript.tools import (
     WriteCall,
 )
 
-from captain_hook import file, style, utils
+from captain_hook import file, style, util
 from captain_hook.app import hook, on, register
 from captain_hook.command import Command, CommandLine, Redirect
 from captain_hook.context import HookContext
+from captain_hook.durable import DurableSlot, DurableState, DurableStore
 from captain_hook.events import (
     BaseHookEvent,
     NotificationEvent,
@@ -37,6 +38,7 @@ from captain_hook.events import (
     ToolHookEvent,
     UserPromptSubmitEvent,
 )
+from captain_hook.fields import Deque
 from captain_hook.file import File, categorize_files
 from captain_hook.primitives import (
     GateVerdict,
@@ -92,4 +94,4 @@ from captain_hook.types import (
     UsedSkill,
     Waiting,
 )
-from captain_hook.utils import read_json, resolve_binary
+from captain_hook.util import read_json, resolve_binary

{capt_hook-4.1.0 → capt_hook-4.3.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, Literal
+from typing import TYPE_CHECKING, Any, Literal, overload
 
 from cc_transcript.activity import SessionActivity, meta_of
 from cc_transcript.ids import SessionId
@@ -15,11 +15,10 @@ from cc_transcript.query import Session
 from cc_transcript.render import Budget, render_turn
 from cc_transcript.tools import parse_tool_call
 from pydantic import BaseModel
-from spawnllm import call_sync, extract_sync
+from spawnllm import TModel, TSpecialty, call_sync, extract_sync
 from spawnllm.proc import run_cli
 
 from captain_hook.classifiers import detect
-from captain_hook.llm import LlmBackends, TModel, TSpecialty
 from captain_hook.prompt import Prompt
 from captain_hook.session import SessionStore
 
@@ -35,10 +34,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 +198,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 +236,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:
@@ -237,6 +264,36 @@ class HookContext:
     def current_branch(self) -> str | None:
         return out.strip() if (out := self.git("symbolic-ref", "--short", "HEAD")) else None
 
+    @overload
+    def call_llm[M: BaseModel](
+        self,
+        template: str | Prompt,
+        *args: Any,
+        specialty: TSpecialty = "general",
+        model: TModel = "small",
+        timeout: int = 180,
+        transcript: bool | int | Literal["recent", "full"] = False,
+        diff: bool | str = False,
+        agent: bool = False,
+        response_model: type[M],
+        **kwargs: Any,
+    ) -> M: ...
+
+    @overload
+    def call_llm(
+        self,
+        template: str | Prompt,
+        *args: Any,
+        specialty: TSpecialty = "general",
+        model: TModel = "small",
+        timeout: int = 180,
+        transcript: bool | int | Literal["recent", "full"] = False,
+        diff: bool | str = False,
+        agent: bool = False,
+        response_model: None = None,
+        **kwargs: Any,
+    ) -> str: ...
+
     def call_llm(
         self,
         template: str | Prompt,
@@ -251,21 +308,30 @@ class HookContext:
         **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.context("diff", diff_text))
-            if transcript:
-                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=block)
-            if diff_text is not None:
-                prompt = f"<diff>\n{diff_text}\n</diff>\n\n{prompt}"
-        backend = LlmBackends.for_specialty(specialty)
+        prompt = self.assemble_prompt(template, args, kwargs, transcript=transcript, diff_text=diff_text)
         cwd = os.environ.get("CLAUDE_PROJECT_DIR") or os.environ.get("FACTORY_PROJECT_DIR")
         if response_model is not None:
             return extract_sync(
-                prompt, response_model, backend=backend, model=model, agent=agent, cwd=cwd, timeout=timeout
+                prompt, response_model, specialty=specialty, model=model, agent=agent, cwd=cwd, timeout=timeout
             )
-        return call_sync(prompt, backend=backend, model=model, agent=agent, cwd=cwd, timeout=timeout)
+        return call_sync(prompt, specialty=specialty, model=model, agent=agent, cwd=cwd, timeout=timeout)
+
+    def assemble_prompt(
+        self,
+        template: str | Prompt,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+        *,
+        transcript: bool | int | Literal["recent", "full"],
+        diff_text: str | None,
+    ) -> str:
+        window = transcript_window(transcript) if transcript else None
+        match template:
+            case Prompt():
+                prompt = str(template.context("diff", diff_text))
+                return f"{self.transcript_block(window=window)}\n\n<task>\n{prompt}\n</task>" if transcript else prompt
+            case str():
+                block = self.transcript_block(window=window) if transcript else ""
+                wrapped = f"{{transcript}}\n\n<task>\n{template}\n</task>" if transcript else template
+                body = wrapped.format(*args, **kwargs, transcript=block)
+                return f"<diff>\n{diff_text}\n</diff>\n\n{body}" if diff_text is not None else body

{capt_hook-4.1.0 → capt_hook-4.3.0}/captain_hook/dispatch.py

@@ -23,6 +23,22 @@ def run_declarative(spec: HookSpec, evt: BaseHookEvent) -> HookResult | None:
     )
 
 
+def record_fire(
+    entry: RegisteredHook,
+    evt: BaseHookEvent,
+    result: HookResult,
+    store: SessionStore,
+    hook_state: HookState,
+) -> None:
+    """React to a hook firing: bump and persist the fire count, then record the decision."""
+    hook_state.fire_count += 1
+    store[HookState].set(hook_state)
+    try:
+        record_decision(entry, evt, result)
+    except Exception:
+        logger.bind(hook=entry.name).exception("decision write failed")
+
+
 def execute_hook(
     entry: RegisteredHook,
     evt: BaseHookEvent,
@@ -46,12 +62,7 @@ def execute_hook(
         return None
 
     if result:
-        hook_state.fire_count += 1
-        store[HookState].set(hook_state)
-        try:
-            record_decision(entry, evt, result)
-        except Exception:
-            logger.bind(hook=entry.name).exception("decision write failed")
+        record_fire(entry, evt, result, store, hook_state)
 
     return result
 

capt_hook-4.3.0/captain_hook/durable.py

@@ -0,0 +1,148 @@
+"""Durable, cross-session state: the durable twin of ``SessionStore``.
+
+Where :class:`~captain_hook.SessionStore` is scoped to one session, a
+:class:`DurableStore` persists across sessions, keyed by project (default) or globally.
+Its slots add a ``filelock``-guarded :meth:`DurableSlot.mutate` so concurrent writers
+across sessions never lose an update.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
+from hashlib import sha256
+from typing import TYPE_CHECKING, Any, ClassVar, Literal, Self
+
+from filelock import FileLock
+from loguru import logger
+from pydantic import BaseModel
+
+from captain_hook.session import SessionSlot
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from captain_hook.events import BaseHookEvent
+
+Scope = Literal["project", "global"]
+
+
+def durable_root() -> Path:
+    from captain_hook.settings import resolve_state_dir
+
+    return resolve_state_dir() / "hooks" / "durable"
+
+
+def project_key(repo_root: Path) -> str:
+    return f"{repo_root.name}-{sha256(str(repo_root.resolve()).encode()).hexdigest()[:16]}"
+
+
+def durable_dir(scope: Scope, repo_root: Path | None) -> Path | None:
+    match scope:
+        case "global":
+            return durable_root() / "global"
+        case "project" if repo_root is not None:
+            return durable_root() / "projects" / project_key(repo_root)
+        case "project":
+            logger.warning("durable project state has no repo_root; not persisting")
+            return None
+        case _:
+            raise ValueError(f"scope must be 'project' or 'global', got {scope!r}")
+
+
+class DurableSlot[M: BaseModel](SessionSlot[M]):
+    """A :class:`SessionSlot` rooted in a durable directory, with a locked :meth:`mutate`."""
+
+    @contextmanager
+    def mutate(self) -> Iterator[M]:
+        """Yield the loaded model under an exclusive file lock; persist it on clean exit.
+
+        The lock is held for the whole ``with`` block, so concurrent writers across sessions
+        serialize rather than clobber. The body must be short — no slow work under the lock.
+        A null slot (project scope with no ``repo_root``) yields an in-memory model and
+        persists nothing.
+        """
+        if self._path is None:
+            yield self.get(self._model())
+            return
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        lock = self._path.with_name(self._path.name + ".lock")
+        with FileLock(str(lock)):
+            obj = self.get(self._model())
+            yield obj
+            self.set(obj)
+
+
+class DurableStore:
+    """Class-keyed durable store providing typed :class:`DurableSlot` access via ``store[Model]``."""
+
+    TRACKED: ClassVar[list[type[BaseModel]]] = []
+
+    def __init__(self, directory: Path | None) -> None:
+        self._dir = directory
+
+    def __getitem__[M: BaseModel](self, model: type[M]) -> DurableSlot[M]:
+        return DurableSlot(self._dir, model)
+
+    def load[M: BaseModel](self, model: type[M]) -> M:
+        return self[model].get(model())
+
+    @classmethod
+    def for_event(cls, evt: BaseHookEvent, *, scope: Scope = "project") -> DurableStore:
+        return cls(durable_dir(scope, evt.ctx.repo_root))
+
+    @classmethod
+    def track(cls, model: type[BaseModel]) -> None:
+        if model not in cls.TRACKED:
+            cls.TRACKED.append(model)
+
+    @classmethod
+    def untrack(cls, model: type[BaseModel]) -> None:
+        if model in cls.TRACKED:
+            cls.TRACKED.remove(model)
+
+    @classmethod
+    def tracked_models(cls) -> Sequence[type[BaseModel]]:
+        return tuple(cls.TRACKED)
+
+
+class DurableState(BaseModel):
+    """Base for a model persisted across sessions, scoped by the ``scope`` class keyword.
+
+    Declare the scope at subclass time — ``class Foo(DurableState, scope="global")``; it
+    defaults to ``"project"`` (keyed by the repo root). The subclass carries ``load``/``save``/
+    ``reset`` plus a locked :meth:`mutate` context manager. Reach for it when state must
+    outlive a single session; for within-session sharing use
+    [`workflow_state`][captain_hook.workflow_state] instead.
+
+    Example:
+        >>> from captain_hook import Deque
+        >>> class JsonShapes(DurableState, scope="global"):
+        ...     shapes: Deque[256]
+    """
+
+    __durable_scope__: ClassVar[Scope] = "project"
+
+    def __init_subclass__(cls, *, scope: Scope = "project", **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if scope not in ("project", "global"):
+            raise ValueError(f"scope must be 'project' or 'global', got {scope!r}")
+        cls.__durable_scope__ = scope
+        DurableStore.track(cls)
+
+    @classmethod
+    def load(cls, evt: BaseHookEvent) -> Self:
+        return DurableStore.for_event(evt, scope=cls.__durable_scope__).load(cls)
+
+    def save(self, evt: BaseHookEvent) -> None:
+        DurableStore.for_event(evt, scope=type(self).__durable_scope__)[type(self)].set(self)
+
+    @classmethod
+    def reset(cls, evt: BaseHookEvent) -> None:
+        DurableStore.for_event(evt, scope=cls.__durable_scope__)[cls].delete()
+
+    @classmethod
+    @contextmanager
+    def mutate(cls, evt: BaseHookEvent) -> Iterator[Self]:
+        with DurableStore.for_event(evt, scope=cls.__durable_scope__)[cls].mutate() as obj:
+            yield obj

capt_hook-4.3.0/captain_hook/fields.py

@@ -0,0 +1,45 @@
+"""Reusable Pydantic field types for hook state models."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Annotated, Any
+
+from pydantic_core import core_schema
+
+if TYPE_CHECKING:
+    from pydantic import GetCoreSchemaHandler
+
+
+@dataclass(frozen=True, slots=True)
+class Deque:
+    """A bounded ``deque`` field type whose ``maxlen`` survives JSON round-trips.
+
+    Subscript with the cap: ``Deque[256]`` is a ``deque[str]`` capped at 256, and
+    ``Deque[int, 256]`` sets the element type. A bare ``Deque`` field (no ``= Field(...)``)
+    defaults to an empty bounded deque, the cap is re-applied on every load, and the deque
+    auto-evicts its oldest item on append — so a growing collection stays bounded across
+    sessions. Unlike :class:`annotated_types.MaxLen`, which only rejects over-long input,
+    this caps the collection instead of raising.
+
+    Example:
+        >>> from captain_hook import DurableState, Deque
+        >>> class JsonShapes(DurableState, scope="global"):
+        ...     shapes: Deque[256]
+    """
+
+    maxlen: int
+
+    def __class_getitem__(cls, params: int | tuple[type, int]) -> Any:
+        match params:
+            case int(maxlen):
+                return Annotated[deque[str], cls(maxlen)]
+            case (item, int(maxlen)):
+                return Annotated[deque[item], cls(maxlen)]
+            case _:
+                raise TypeError(f"Deque[...] takes an int cap or (item, cap), got {params!r}")
+
+    def __get_pydantic_core_schema__(self, source: Any, handler: GetCoreSchemaHandler) -> core_schema.CoreSchema:
+        bounded = core_schema.no_info_after_validator_function(lambda d: deque(d, maxlen=self.maxlen), handler(source))
+        return core_schema.with_default_schema(bounded, default_factory=lambda: deque(maxlen=self.maxlen))

{capt_hook-4.1.0 → capt_hook-4.3.0}/captain_hook/primitives/llm.py

@@ -28,8 +28,9 @@ from captain_hook.types import (
 FAILURE_ROOT = state.CACHE_ROOT / "failures"
 
 if TYPE_CHECKING:
+    from spawnllm import TModel, TSpecialty
+
     from captain_hook.events import BaseHookEvent
-    from captain_hook.llm import TModel, TSpecialty
     from captain_hook.signals.nlp import NlpSignal
 
 
@@ -377,7 +378,6 @@ def prompt_check(
     if not verdict:
         return None
 
-    assert isinstance(verdict, response_model)
     match verdict.action:
         case "block":
             return HookResult(action=Action.block, message=f"{prefix}: {verdict.reason}{suffix}")