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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 3.20.0
+Version: 4.0.0
 Summary: Declarative hook framework for Claude Code
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Software Development :: Testing
 Classifier: Typing :: Typed
-Requires-Dist: cc-transcript>=5,<6
+Requires-Dist: cc-transcript>=7,<8
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pydantic-settings>=2.0
 Requires-Dist: tree-sitter>=0.24
@@ -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.4.0
+Requires-Dist: spawnllm>=0.5.0
 Requires-Dist: pytest>=8.0 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
 Requires-Dist: pyright>=1.1 ; extra == 'dev'

{capt_hook-3.20.0 → capt_hook-4.0.0}/captain_hook/context.py

@@ -15,7 +15,8 @@ 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, run_cli
+from spawnllm import call_sync, extract_sync
+from spawnllm.proc import run_cli
 
 from captain_hook.classifiers import detect
 from captain_hook.llm import LlmBackends, TModel, TSpecialty
@@ -214,12 +215,10 @@ class HookContext:
             if transcript:
                 template = f"{{transcript}}\n\n<task>\n{template}\n</task>"
             prompt = template.format(*args, **kwargs, transcript=self.transcript_block())
-        return call_sync(
-            prompt,
-            backend=LlmBackends.for_specialty(specialty),
-            model=model,
-            agent=agent,
-            response_model=response_model,
-            cwd=os.environ.get("CLAUDE_PROJECT_DIR") or os.environ.get("FACTORY_PROJECT_DIR"),
-            timeout=timeout,
-        )
+        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:
+            return extract_sync(
+                prompt, response_model, backend=backend, model=model, agent=agent, cwd=cwd, timeout=timeout
+            )
+        return call_sync(prompt, backend=backend, model=model, agent=agent, cwd=cwd, timeout=timeout)

{capt_hook-3.20.0 → capt_hook-4.0.0}/captain_hook/review/fix.py

@@ -38,8 +38,9 @@ from typing import TYPE_CHECKING, Literal
 
 from cc_transcript.filterspec import tool_uses
 from cc_transcript.mining.confidence import MEDIUM, VERY_HIGH, CandidateSignal
-from cc_transcript.mining.signals import CONFIDENCE_STEP, MiningSignal, adjust
+from cc_transcript.mining.signals import MiningSignal
 from cc_transcript.mining.sourcekind import SourceKind
+from cc_transcript.mining.spec import CONFIDENCE_STEP, bump
 from cc_transcript.models import AssistantEvent, OtherEvent, ToolResultBlock, UserEvent
 
 if TYPE_CHECKING:
@@ -211,7 +212,7 @@ def complaint_signal(marker: Marker, turns_back: int) -> CandidateSignal:
         VERY_HIGH if marker.strength == "strong" else MEDIUM,
         (f"{marker.strength}_marker", marker.misfire_class),
     )
-    return adjust(base, CONFIDENCE_STEP, "tight_proximity") if turns_back <= TIGHT_PROXIMITY_TURNS else base
+    return bump(base, CONFIDENCE_STEP, "tight_proximity") if turns_back <= TIGHT_PROXIMITY_TURNS else base
 
 
 def iter_hook_complaint_signals(events: Sequence[TranscriptEvent], *, decisions: DecisionLog) -> Iterator[MiningSignal]:

{capt_hook-3.20.0 → capt_hook-4.0.0}/captain_hook/review/formats.py

@@ -2,32 +2,51 @@
 
 The generic :class:`ReviewComment`/:class:`ReviewFormat` types and the
 format-dispatch live in :mod:`cc_transcript.mining`; this module supplies
-the reviewer's policy — the three review formats it recognizes — and injects them
-into the domain's review-comment detector. The shapes are shared transcript
-conventions (inline ``In file:Lx:`` cites, conductor finding blocks, conductor
-workstream headers) first proven in cc-pushback's formats module, not
-cc-pushback specifics.
+the reviewer's policy — the three review formats it recognizes — and assembles them
+into the :class:`~cc_transcript.mining.ReviewSpec` the review-comment detector runs.
+The shapes are shared transcript conventions (inline ``In file:Lx:`` cites,
+conductor finding blocks, conductor workstream headers) first proven in
+cc-pushback's formats module, not cc-pushback specifics.
+
+``conductor-finding`` is a Rust-portable :class:`~cc_transcript.mining.RegexReviewFormat`
+(a declarative claim+suggestion group-join); ``superset-inline`` (lookahead) and
+``conductor-workstream`` (multi-pass header + body scan) stay
+:class:`~cc_transcript.mining.CallableReviewFormat` escape hatches, which keep the
+review-comment detector in Python for those formats.
 """
 
 from __future__ import annotations
 
 import re
 
-from cc_transcript.mining.formats import ReviewComment, ReviewFormat
+from cc_transcript.mining.formats import ReviewComment
+from cc_transcript.mining.spec import CallableReviewFormat, RegexReviewFormat, ReviewSpec
 
 SUPERSET_INLINE_RE = re.compile(r"^In ((?=\S*[./]|\S+?:L)\S+?)(?::L(\d+)(?:-(\d+))?)?: (.+)$", re.MULTILINE)
-CONDUCTOR_FINDING_RE = re.compile(
-    r"^- file: (?P<file>\S+?):(?P<line>\d+)\s*$"
-    r"(?:\n- theme: .+$)?"
-    r"(?:\n- claim: (?P<claim>.+)$)?"
-    r"(?:\n- suggestion: (?P<suggestion>.+)$)?",
-    re.MULTILINE,
-)
 CONDUCTOR_WORKSTREAM_HEADER_RE = re.compile(
     r"^### (?P<id>[A-Z][\w-]*\d*)\s*\[(?P<kind>[A-Z]+)\]\s*—\s*(?P<title>.+)$",
     re.MULTILINE,
 )
 WORKSTREAM_BODY_RE = re.compile(r"^(?:FIX|Tests): .+$", re.MULTILINE)
+CONDUCTOR_FINDING_FMT = RegexReviewFormat(
+    name="conductor-finding",
+    groups=(
+        (
+            "conductor-finding",
+            r"^- file: (\S+?):(\d+)\s*$"
+            r"(?:\n- theme: .+$)?"
+            r"(?:\n- claim: (.+)$)?"
+            r"(?:\n- suggestion: (.+)$)?",
+        ),
+    ),
+    file_group=1,
+    line_start_group=2,
+    line_end_group=None,
+    comment_groups=(3, 4),
+    join=" ",
+    multiline=True,
+    ignore_case=False,
+)
 
 
 def extract_superset_inline(text: str) -> tuple[ReviewComment, ...]:
@@ -42,18 +61,6 @@ def extract_superset_inline(text: str) -> tuple[ReviewComment, ...]:
     )
 
 
-def extract_conductor_finding(text: str) -> tuple[ReviewComment, ...]:
-    return tuple(
-        ReviewComment(
-            file=match.group("file"),
-            line_start=int(match.group("line")),
-            line_end=None,
-            comment=" ".join(part.strip() for part in (match.group("claim"), match.group("suggestion")) if part),
-        )
-        for match in CONDUCTOR_FINDING_RE.finditer(text)
-    )
-
-
 def extract_conductor_workstream(text: str) -> tuple[ReviewComment, ...]:
     headers = list(CONDUCTOR_WORKSTREAM_HEADER_RE.finditer(text))
     return tuple(
@@ -74,9 +81,13 @@ def extract_conductor_workstream(text: str) -> tuple[ReviewComment, ...]:
     )
 
 
-def formats() -> tuple[ReviewFormat, ...]:
-    return (
-        ReviewFormat("superset-inline", SUPERSET_INLINE_RE, extract_superset_inline),
-        ReviewFormat("conductor-finding", CONDUCTOR_FINDING_RE, extract_conductor_finding),
-        ReviewFormat("conductor-workstream", CONDUCTOR_WORKSTREAM_HEADER_RE, extract_conductor_workstream),
+def review_spec() -> ReviewSpec:
+    return ReviewSpec(
+        regex_formats=(CONDUCTOR_FINDING_FMT,),
+        callable_formats=(
+            CallableReviewFormat("superset-inline", SUPERSET_INLINE_RE, extract_superset_inline),
+            CallableReviewFormat("conductor-workstream", CONDUCTOR_WORKSTREAM_HEADER_RE, extract_conductor_workstream),
+        ),
+        structured_formats=(),
+        surfaces=frozenset({"typed"}),
     )

{capt_hook-3.20.0 → capt_hook-4.0.0}/captain_hook/review/scan.py

@@ -58,20 +58,14 @@ from cc_transcript.filterspec import (
 from cc_transcript.ids import EventRef
 from cc_transcript.mining.candidates import FeedbackCandidate, dedup_key
 from cc_transcript.mining.filterspec import at_least, build_candidate_filter, keep_candidate
-from cc_transcript.mining.signals import (
-    iter_interrupt_marker_signals,
-    iter_plan_reentry_signals,
-    iter_plan_rejection_signals,
-    iter_review_comment_signals,
-    iter_tool_denial_signals,
-    iter_user_message_signals,
-)
+from cc_transcript.mining.signals import mine
+from cc_transcript.mining.spec import MiningSpec
 from cc_transcript.models import UserEvent
 from cc_transcript.parser import TranscriptParser
 
 from captain_hook.decisions import decisions_db_path, open_decision_log
 from captain_hook.review.fix import HOOK_COMPLAINT, iter_hook_complaint_signals
-from captain_hook.review.formats import formats
+from captain_hook.review.formats import review_spec
 from captain_hook.review.repo import resolve_repo_key
 from captain_hook.review.store import CandidateKind
 
@@ -92,6 +86,14 @@ REVIEWER_MARKER = "capt-hook-session-reviewer"
 
 SPEC_DETECTORS = frozenset({"transcript_message", "plan_reentry", "review_comment"})
 
+REVIEWER_MINING_SPEC = MiningSpec(review=review_spec())
+"""The reviewer's mining policy: all six core detectors with the reviewer's review formats.
+
+Scoring, provenance, reentry lookback, and edit tools take the :class:`MiningSpec`
+defaults; only the review-comment policy (the three reviewer formats, ``typed``
+surfaces, no structured formats) is customized.
+"""
+
 STRICT_USER: FilterSpec = build_spec(
     keep_only("user"),
     drop_sidechain(),
@@ -191,23 +193,16 @@ def to_candidate(activity: SessionActivity, sig: MiningSignal) -> FeedbackCandid
 
 
 def detect(events: Sequence[TranscriptEvent]) -> Iterator[MiningSignal]:
-    """Composes all six neutral mining iterators over one transcript's events.
+    """Mines all six neutral detectors over one transcript's events.
 
     Args:
         events: The transcript's full ordered event stream.
 
     Returns:
         Every mining signal the detectors recognize, ungated; review comments
-        run under the reviewer's :func:`~captain_hook.review.formats.formats`.
+        run under the reviewer's :data:`REVIEWER_MINING_SPEC`.
     """
-    return chain(
-        iter_user_message_signals(events),
-        iter_plan_rejection_signals(events),
-        iter_plan_reentry_signals(events),
-        iter_tool_denial_signals(events),
-        iter_interrupt_marker_signals(events),
-        iter_review_comment_signals(events, formats(), surfaces=frozenset({"typed"}), structured_formats=()),
-    )
+    return mine(events, REVIEWER_MINING_SPEC)
 
 
 def candidates_from(

{capt_hook-3.20.0 → capt_hook-4.0.0}/captain_hook/tests/helpers.py

@@ -122,9 +122,13 @@ def make_pre_tool_event(
     tool_name: str = "Bash",
     tool_input: dict[str, Any] | None = None,
     ctx: Any = None,
+    *,
+    permission_mode: str | None = None,
 ) -> PreToolUseEvent:
     return PreToolUseEvent(
-        _raw={"tool_name": tool_name} | ({"tool_input": tool_input} if tool_input is not None else {}),
+        _raw={"tool_name": tool_name}
+        | ({"tool_input": tool_input} if tool_input is not None else {})
+        | ({"permission_mode": permission_mode} if permission_mode is not None else {}),
         ctx=ctx or make_ctx(),
     )
 

capt_hook-4.0.0/captain_hook/tests/review_helpers.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import itertools
+import json
+import subprocess
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from cc_transcript import parse_events_from_bytes
+
+from captain_hook.review.judge import ReviewVerdict
+from captain_hook.review.repo import RepoKey
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from cc_transcript.models import TranscriptEvent
+
+    from captain_hook.review.judge import Category
+
+REPO = RepoKey("github.com/yasyf/captain-hook")
+BASE_TS = "2026-06-01T12:00:00+00:00"
+CORRECTION = "no, never use a bare except here, always catch the specific parser error"
+PROMPT_VERSION = 1
+
+REVIEW_UUIDS = itertools.count()
+
+
+@dataclass(frozen=True, slots=True)
+class Verdict:
+    accepted: bool = True
+    confidence: float = 0.9
+    category: str = "durable_correction"
+    summary: str = "user corrected approach"
+    rationale: str = "explicit correction"
+
+
+def next_uuid() -> str:
+    return f"uuid-{next(REVIEW_UUIDS)}"
+
+
+def envelope(entry_type: str, **overrides: Any) -> dict[str, Any]:
+    return {
+        "type": entry_type,
+        "uuid": overrides.pop("uuid", next_uuid()),
+        "parentUuid": None,
+        "sessionId": overrides.pop("sessionId", "sess-1"),
+        "timestamp": overrides.pop("timestamp", BASE_TS),
+        "cwd": overrides.pop("cwd", "/repo"),
+        "gitBranch": "main",
+        "version": "1.2.3",
+        "isSidechain": False,
+        "isMeta": False,
+        "entrypoint": "cli",
+        **overrides,
+    }
+
+
+def user_text(text: str, **overrides: Any) -> dict[str, Any]:
+    return envelope("user", message={"role": "user", "content": text}, **overrides)
+
+
+def assistant_text(text: str, **overrides: Any) -> dict[str, Any]:
+    return envelope(
+        "assistant",
+        message={"role": "assistant", "model": "claude", "content": [{"type": "text", "text": text}]},
+        **overrides,
+    )
+
+
+def assistant_tool_use(tool_id: str, name: str, tool_input: dict[str, Any], **overrides: Any) -> dict[str, Any]:
+    return envelope(
+        "assistant",
+        message={
+            "role": "assistant",
+            "model": "claude",
+            "content": [{"type": "tool_use", "id": tool_id, "name": name, "input": tool_input}],
+        },
+        **overrides,
+    )
+
+
+def tool_result(tool_id: str, content: str, *, is_error: bool = False, **overrides: Any) -> dict[str, Any]:
+    return envelope(
+        "user",
+        message={
+            "role": "user",
+            "content": [{"type": "tool_result", "tool_use_id": tool_id, "content": content, "is_error": is_error}],
+        },
+        **overrides,
+    )
+
+
+def correction_entries(*, session: str = "sess-1", timestamp: str = BASE_TS, **overrides: Any) -> list[dict[str, Any]]:
+    return [
+        assistant_text("I'll wrap the parser in a bare except", sessionId=session, timestamp=timestamp, **overrides),
+        user_text(CORRECTION, sessionId=session, timestamp=timestamp, **overrides),
+    ]
+
+
+def parse(entries: list[dict[str, Any]]) -> list[TranscriptEvent]:
+    return parse_events_from_bytes("".join(json.dumps(entry) + "\n" for entry in entries).encode())
+
+
+def write_transcript(path: Path, entries: list[dict[str, Any]]) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("".join(json.dumps(entry) + "\n" for entry in entries))
+    return path
+
+
+def llm_backend_available() -> bool:
+    from cc_transcript.judge.llm import default_backend
+    from spawnllm import BackendUnavailable
+
+    try:
+        default_backend()
+    except BackendUnavailable:
+        return False
+    return True
+
+
+requires_llm_backend = pytest.mark.skipif(
+    not llm_backend_available(),
+    reason="no installed, authenticated LLM backend (spawnllm.select_backend raised BackendUnavailable)",
+)
+
+
+def install_judge(
+    monkeypatch: pytest.MonkeyPatch, *, category: Category = "durable_style_rule", fail_on: str | None = None
+) -> list[str]:
+    calls: list[str] = []
+
+    async def judge(prompt: str) -> ReviewVerdict:
+        calls.append(prompt)
+        if fail_on is not None and fail_on in prompt:
+            raise subprocess.CalledProcessError(1, ["claude"])
+        return ReviewVerdict(category=category, summary="states a durable rule", confidence=0.9, rationale="r")
+
+    monkeypatch.setattr("captain_hook.review.judge.structured_judge", lambda *_, **__: judge)
+    return calls

{capt_hook-3.20.0 → capt_hook-4.0.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 = "3.20.0"
+version = "4.0.0"
 description = "Declarative hook framework for Claude Code"
 readme = "README.md"
 license = "PolyForm-Noncommercial-1.0.0"
@@ -21,7 +21,7 @@ classifiers = [
 ]
 requires-python = ">=3.13"
 dependencies = [
-    "cc-transcript>=5,<6",
+    "cc-transcript>=7,<8",
     "pydantic>=2.0",
     "pydantic-settings>=2.0",
     "tree-sitter>=0.24",
@@ -36,7 +36,7 @@ dependencies = [
     "lazy-object-proxy>=1.12.0",
     "filelock>=3",
     "loguru>=0.7.3",
-    "spawnllm>=0.4.0",
+    "spawnllm>=0.5.0",
 ]
 
 [project.optional-dependencies]