capt-hook 8.3.0__tar.gz → 8.4.0__tar.gz

{capt_hook-8.3.0 → capt_hook-8.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 8.3.0
+Version: 8.4.0
 Summary: Stop repeating yourself to Claude.
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali

{capt_hook-8.3.0 → capt_hook-8.4.0}/captain_hook/packs/general/models.py

@@ -770,9 +770,9 @@ An unpinned security audit inherits fable; security review/audit is the codex-wr
             script="agent(`Synthesize the confirmed review findings and decide which to fix`)",
             llm={"fire": False},
         ): Allow(),
-        Input(
-            script="agent(`Audit the login flow for auth bypass and injection; return findings as JSON`)"
-        ): Warn(pattern="gpt-5.5"),
+        Input(script="agent(`Audit the login flow for auth bypass and injection; return findings as JSON`)"): Warn(
+            pattern="gpt-5.5"
+        ),
         Input(script="agent('Verify the CLI renders the last page correctly')"): Allow(),
     },
 )

{capt_hook-8.3.0 → capt_hook-8.4.0}/captain_hook/packs/steering/capt-hook.toml

@@ -1,5 +1,5 @@
 name = "steering"
-version = "0.4.0"
+version = "0.5.0"
 description = "Steer the agent's judgment on what's worth fixing: prefer fundamental, first-principles fixes over band-aids, don't dismiss a real pre-existing issue, don't chase trivial type noise, and don't defer the requested fix by swapping in docs or a follow-up nobody asked for."
 hooks = "."
 nlp = true

{capt_hook-8.3.0 → capt_hook-8.4.0}/captain_hook/packs/steering/steering.py

@@ -358,17 +358,21 @@ decided it) in `reasoning`.""",
 
 
 llm_gate(
-    """You are a senior engineer. Another engineer ("the agent") is trying to end its turn. You
-are running in agent mode in the project's working directory, with read tools. Your one job:
-decide whether the agent DELIVERED the fix the user asked for, or silently DOWNGRADED the
-deliverable while the real fix stays undone.
+    """You are a senior engineer. Another engineer ("the agent") is ending its turn or has just
+produced deferral-shaped content mid-work (a thinking block, a review finding, a task or todo it
+filed). You are running in agent mode in the project's working directory, with read tools. Your
+one job: decide whether the agent DELIVERED the fix the user asked for, or silently DOWNGRADED
+the deliverable while the real fix stays undone.
 
 Read first, judge second:
 - The session transcript is rendered above inside `<transcript path="...">`; long content is
   clipped (you'll see `…(+Nch)` markers). Read the FULL exchange from that path (prefer
   `cc-transcript show`/`grep`; else read the file). You need: (1) what the user actually asked
   for (including any later approval of a reduced scope), (2) what the agent actually changed
-  this turn, and (3) the agent's closing justification (the flagged lines are in `<context>`).
+  this turn, and (3) the agent's justification (the flagged lines are in `<context>`). On a
+  mid-turn firing the flagged content may be deliberation in flight — check whether the agent
+  has COMMITTED to the downgrade (substitute edits landed, a softer task filed as the plan of
+  record, the real fix abandoned), not merely weighed it.
 - Then inspect the working directory enough to confirm whether the requested fix was made or
   only a softer substitute (docs, help text, error copy) shipped.
 
@@ -391,21 +395,28 @@ how to proceed before substituting anything; the softer deliverable IS the task
 requested; the user approved a plan or message that explicitly named the smaller deliverable (an
 approved ExitPlanMode plan counts as the go-ahead); a genuine hard blockage the agent reported
 plainly (no access to the other repo, missing credentials, an API that does not exist); the
-agent shipped the real fix AND improved docs alongside it.
+agent shipped the real fix AND improved docs alongside it; deliberation that names the softer
+option in order to reject it and commits to the real fix; a finding or quoted text reporting
+the codebase's or someone else's existing deferral debt or a genuine upstream bug — reporting
+is not deferring, UNLESS the same content prescribes the downgrade as the remediation (e.g.
+"fix requires a release, so document the constraint instead"); a task recording a genuine
+environmental constraint that replaces no requested fix.
 
 Do NOT fire when: the user explicitly asked for the docs/help-text/error-copy change; the turn
 ends in a question to the user about the blocker (asking is the sanctioned escape hatch, not
 laziness); the deferral language refers to genuinely optional extras after the requested fix
-landed; or the blockage is real, outside the agent's reach, and clearly reported rather than
-papered over.
+landed; the flagged content is mid-turn deliberation where no substitute has been executed yet;
+or the blockage is real, outside the agent's reach, and clearly reported rather than papered
+over.
 
 When uncertain, return block=false. A missed deferral costs one nag; a false alarm on an honest
 stop teaches the agent to ignore this gate. Fire only when a specific tell is clearly present
 and no "do not fire" condition applies. Put your reasoning (under 60 words, ending with the one
 tell that decided it) in `reasoning`.""",
     message=lambda r: (
-        "You appear to be deferring the real fix — declaring it out of reach and "
-        f"substituting a softer deliverable without asking. Why: {r.reasoning} "
+        "You appear to be deferring the real fix — whether closing the turn or still mid-work, "
+        "you have declared it out of reach and substituted a softer deliverable (or filed one "
+        f"as the plan of record) without asking. Why: {r.reasoning} "
         "Do the fix the user asked for: a release, version bump, or cross-repo change is "
         "routine work here, not a blocker — plan it and do it. If you are genuinely blocked, "
         "stop and ask the user how to proceed instead of substituting docs, help text, or a "
@@ -445,14 +456,14 @@ tell that decided it) in `reasoning`.""",
             Signal(
                 pattern=(
                     r"(?i)\b(?:improv|updat|expand|clarif|document|add)\w*\s+(?:the\s+|this\s+|that\s+|a\s+)?"
-                    r"(?:documentation|docs\b|help\s+text|readme|error\s+(?:message|copy|text)|limitation)"
+                    r"(?:documentation|docs\b|help\s+text|readme|error\s+(?:message|copy|text))"
                 ),
                 weight=1,
             ),
             Signal(
                 pattern=(
                     r"(?i)\b(?:document\w*|not(?:e|es|ed|ing)|record\w*)\s+(?:the\s+|this\s+|that\s+|a\s+|its\s+)?"
-                    r"(?:limitation|caveat|constraint|shortcoming|known\s+issue|behavior)"
+                    r"(?:[\w'-]+\s+){0,2}?(?:limitation|caveat|constraint|shortcoming|known\s+issue|behavior)"
                 ),
                 weight=2,
             ),
@@ -460,7 +471,7 @@ tell that decided it) in `reasoning`.""",
                 pattern=(
                     r"(?i)(?:(?:left|leaves?|leaving)\s+(?:the\s+|it\s+|this\s+|that\s+)?"
                     r"(?:code|implementation|behavior|bug|issue|it)?\s*(?:as-?is|untouched|unchanged|in\s+place)"
-                    r"|still\s+(?:present|broken|unfixed|unaddressed|reproduc\w+)"
+                    r"|still\s+(?:present|broken|unfixed|unaddressed|there\b|reproduc\w+)"
                     r"|remains?\s+(?:broken|unfixed|in\s+place))"
                 ),
                 weight=2,
@@ -474,7 +485,7 @@ tell that decided it) in `reasoning`.""",
             ),
             Signal(
                 pattern=(
-                    r"(?i)(?:as\s+a\s+workaround|stop-?gap|interim\s+(?:fix|solution|measure)|band-?aid"
+                    r"(?i)(?:workaround|stop-?gap|interim\s+(?:fix|solution|measure)|band-?aid"
                     r"|(?:as\s+a\s+)?temporary\s+(?:measure|fix|solution|patch|guard)"
                     r"|in\s+the\s+meantime|for\s+the\s+time\s+being)"
                 ),
@@ -483,7 +494,8 @@ tell that decided it) in `reasoning`.""",
             Signal(pattern=r"(?i)\bfor\s+now\b", weight=1),
             Signal(
                 pattern=(
-                    r"(?i)(?:follow-?up\s+(?:pr|work|issue|task|change)|future\s+(?:pr|work|release)"
+                    r"(?i)(?:follow-?up\s+(?:pr|work|issue|task|change)|(?:in|as)\s+a\s+follow-?up\b"
+                    r"|future\s+(?:pr|work|release)"
                     r"|file\s+(?:an?\s+)?issue|(?:separate|later|subsequent)\s+(?:pr|patch|pass|iteration)|backlog"
                     r"|out\s+of\s+scope\s+for\s+this)"
                 ),
@@ -502,8 +514,20 @@ tell that decided it) in `reasoning`.""",
                     r"|so\s+(?:it|this|that|the\s+\w+)\s+(?:no\s+longer|doesn['’]t|does\s+not|won['’]t)\s+"
                     r"(?:crash|die|fail|error)\w*)"
                 ),
+                weight=2,
+            ),
+            Signal(
+                pattern=(
+                    r"(?i)\b(?:punt|defer|postpon)\w*\s+(?:the|this|that|it)\b"
+                    r"|\bskip\w*\s+the\s+(?:real|proper|actual|root)\b"
+                ),
+                weight=2,
+            ),
+            Signal(
+                pattern=r"(?i)\brevisit\s+(?:it\s+|this\s+)?later\b|\bcome\s+back\s+to\s+(?:it|this)\b",
                 weight=1,
             ),
+            Signal(pattern=r"(?i)\bmov(?:e[ds]?|ing)\s+on\b", weight=1),
             NlpSignal(
                 clauses=[Clause(noun=Phrase.expand("fix"), verb=Phrase("defer", "postpone", "punt"))],
                 weight=2,
@@ -523,8 +547,9 @@ tell that decided it) in `reasoning`.""",
             ),
         ],
         threshold=3,
-        window=10,
+        window="turn",
     ),
+    events=Event.PostToolUse | Event.Stop | Event.SubagentStop,
     tests={
         Input(
             transcript=[
@@ -727,5 +752,298 @@ tell that decided it) in `reasoning`.""",
                 }
             ]
         ): Allow(),
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "id": "tu_findings",
+                                "name": "ReportFindings",
+                                "input": {
+                                    "findings": [
+                                        {
+                                            "file": "internal/daemon/daemon.go",
+                                            "line": 105,
+                                            "summary": (
+                                                "OpClose --stale and OpList are documented as cross-repo "
+                                                "commands, but cc-interact's dispatch runs ScopeResolve "
+                                                "(vcs.Root) on the caller's cwd for every domain op with a "
+                                                "hardcoded exemption set, so both error when invoked "
+                                                "outside a git/jj repo."
+                                            ),
+                                            "failure_scenario": (
+                                                "User cd ~ && cc-review list → error from vcs.Root instead "
+                                                "of the cross-repo listing; fix requires a cc-interact "
+                                                "release, so cc-review documents the run-inside-a-repo "
+                                                "constraint instead."
+                                            ),
+                                            "verdict": "CONFIRMED",
+                                        }
+                                    ]
+                                },
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Block(),
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "thinking",
+                                "thinking": (
+                                    "I'm seeing that cc-interact has hardcoded exemptions for certain "
+                                    "operations, which means any domain operation without an exemption "
+                                    "gets an error when the scope can't be resolved. The issue is that "
+                                    "`cc-review list` and `close --stale` commands don't have consumer "
+                                    "hooks to exempt them, so running these from outside a repo directory "
+                                    "triggers a vcs.Root error. Since fixing this requires a cc-interact "
+                                    "release, the practical solution is to improve the documentation and "
+                                    "help text to guide users on where to run these commands from."
+                                ),
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Block(),
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": (
+                                    "Since fixing this requires a cc-interact release, the practical "
+                                    "solution is to document the limitation in the help text."
+                                ),
+                            }
+                        ]
+                    },
+                },
+                *(
+                    block
+                    for i in range(6)
+                    for block in (
+                        {
+                            "type": "assistant",
+                            "message": {
+                                "content": [
+                                    {
+                                        "type": "tool_use",
+                                        "id": f"tu_{i}",
+                                        "name": "Read",
+                                        "input": {"file_path": f"/tmp/f{i}.py"},
+                                    }
+                                ]
+                            },
+                        },
+                        {
+                            "type": "user",
+                            "message": {
+                                "content": [{"type": "tool_result", "tool_use_id": f"tu_{i}", "content": "ok"}]
+                            },
+                        },
+                    )
+                ),
+            ]
+        ): Block(),
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "id": "tu_findings",
+                                "name": "ReportFindings",
+                                "input": {
+                                    "findings": [
+                                        {
+                                            "file": "captain_hook/signals/__init__.py",
+                                            "line": 46,
+                                            "summary": (
+                                                "Off-by-one in windowed() drops the final event when stop "
+                                                "lands on a turn boundary."
+                                            ),
+                                            "failure_scenario": (
+                                                "Session.recent(1) on a three-event transcript returns an "
+                                                "empty window, so signal scoring sees no text."
+                                            ),
+                                            "verdict": "CONFIRMED",
+                                        }
+                                    ]
+                                },
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Allow(),
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "id": "tu_todos",
+                                "name": "TodoWrite",
+                                "input": {
+                                    "todos": [
+                                        {
+                                            "content": "Add SSE reconnect test",
+                                            "status": "pending",
+                                            "activeForm": "Adding SSE reconnect test",
+                                        },
+                                        {
+                                            "content": "Wire the backoff cap into the client config",
+                                            "status": "in_progress",
+                                            "activeForm": "Wiring the backoff cap",
+                                        },
+                                    ]
+                                },
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Allow(),
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "id": "tu_task_workaround",
+                                "name": "TaskCreate",
+                                "input": {
+                                    "subject": "Workaround for the crash",
+                                    "description": (
+                                        "Wrap the call in try/except so the session survives; revisit later."
+                                    ),
+                                },
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Block(),
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "id": "tu_todo_defer",
+                                "name": "TodoWrite",
+                                "input": {
+                                    "todos": [
+                                        {
+                                            "content": "Defer the parser rewrite to a later pass",
+                                            "status": "pending",
+                                            "activeForm": "Deferring the parser rewrite",
+                                        },
+                                    ]
+                                },
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Block(),
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "id": "tu_task_skip",
+                                "name": "TaskCreate",
+                                "input": {
+                                    "subject": "Skip the real fix",
+                                    "description": (
+                                        "Too big for this pass; just note it somewhere and come back to it."
+                                    ),
+                                },
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Block(),
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "id": "tu_findings_deadcode",
+                                "name": "ReportFindings",
+                                "input": {
+                                    "findings": [
+                                        {
+                                            "file": "captain_hook/signals/__init__.py",
+                                            "line": 90,
+                                            "summary": (
+                                                "The `document the limitation` fallback branch in "
+                                                "cite_message is dead code — no caller reaches it."
+                                            ),
+                                            "failure_scenario": (
+                                                "extract_signal_context always returns a non-empty list "
+                                                "for these patterns, so the else arm never runs."
+                                            ),
+                                            "verdict": "CONFIRMED",
+                                        }
+                                    ]
+                                },
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Allow(),
+        Input(
+            transcript=[
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "id": "tu_task_spacy_docs",
+                                "name": "TaskCreate",
+                                "input": {
+                                    "subject": "Document the limitation",
+                                    "description": (
+                                        "Note in the README that NLP scoring needs the spaCy "
+                                        "en_core_web_sm model provisioned."
+                                    ),
+                                },
+                            }
+                        ]
+                    },
+                }
+            ]
+        ): Allow(),
     },
 )

{capt_hook-8.3.0 → capt_hook-8.4.0}/captain_hook/review/judge.py

@@ -26,6 +26,7 @@ from cc_transcript.judge.llm import resolved_model, structured_judge
 from cc_transcript.judge.verdicts import run_verdicts
 from cc_transcript.mining.candidates import DedupKey
 from cc_transcript.mining.confidence import NOISE_FLOOR
+from cc_transcript.mining.sourcekind import QUESTION_ANSWER
 from cc_transcript.render import Budget
 from pydantic import BaseModel, Field
 
@@ -131,6 +132,27 @@ async def render_context(window: ContextWindow) -> tuple[str, Fidelity]:
     )
 
 
+def question_answer_block(row: Mapping[str, object]) -> str:
+    if str(row["source_kind"]) != QUESTION_ANSWER:
+        return ""
+    payload: dict[str, object] = json.loads(str(row["payload_json"]))
+    match payload["picked_labels"]:
+        case []:
+            resolved = "The developer picked none of the offered options and wrote a freeform answer."
+        case [*labels]:
+            choice = "options" if payload["multi_select"] else "option"
+            standing = (
+                "which is the option the assistant marked (Recommended)"
+                if payload["recommended_pick"]
+                else "which is not the recommended option"
+            )
+            resolved = f"The answer resolves to the {choice} {'; '.join(map(str, labels))} — {standing}."
+    return (
+        f"=== QUESTION THE ASSISTANT ASKED ===\n{payload['question']}\n{resolved}\n"
+        "The feedback below is the developer's answer to that question.\n"
+    )
+
+
 def build_create_prompt(row: Mapping[str, object], context: str) -> str:
     return f"""\
 You are auditing one piece of feedback a developer gave an AI coding assistant
@@ -170,7 +192,7 @@ Respond with strict JSON matching the schema — no extra keys, no prose.
 
 [source: {row["source_kind"]}]
 {context}
-=== FEEDBACK TO CLASSIFY ===
+{question_answer_block(row)}=== FEEDBACK TO CLASSIFY ===
 {row["text"]}"""
 
 

{capt_hook-8.3.0 → capt_hook-8.4.0}/captain_hook/review/scan.py

@@ -150,6 +150,8 @@ def rule_parts(sig: MiningSignal) -> tuple[str, ...]:
                 str(sig.evidence["line_end"] or ""),
                 sig.text,
             )
+        case "ask_user_question":
+            return ("question_answer", str(sig.evidence["question"] or ""), sig.text)
         case _:
             raise AssertionError(sig.detector)
 
@@ -171,6 +173,8 @@ def payload_of(sig: MiningSignal) -> Mapping[str, Any] | None:
             return dict(sig.evidence) or None
         case "review_comment":
             return {key: sig.evidence[key] for key in ("format", "file", "line_start", "line_end")}
+        case "ask_user_question":
+            return dict(sig.evidence)
         case _:
             raise AssertionError(sig.detector)
 

capt_hook-8.4.0/captain_hook/signals/__init__.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from typing import TYPE_CHECKING, Any, Literal
+
+from cc_transcript.models import AssistantEvent, ThinkingBlock, ToolUseBlock, UserEvent
+
+from captain_hook.signals.nlp import NlpSignal
+from captain_hook.types import Event, Signal, Signals
+
+if TYPE_CHECKING:
+    from captain_hook.events import BaseHookEvent
+
+PROSE_TOOLS: dict[str, Callable[[Mapping[str, Any]], list[str]]] = {
+    "ReportFindings": lambda inp: [
+        " ".join(filter(None, (f.get("summary"), f.get("failure_scenario")))) for f in inp.get("findings", ())
+    ],
+    "TaskCreate": lambda inp: [" ".join(filter(None, (inp.get("subject"), inp.get("description"))))],
+    "TaskUpdate": lambda inp: [" ".join(filter(None, (inp.get("subject"), inp.get("description"))))],
+    "TodoWrite": lambda inp: [
+        " ".join(filter(None, (t.get("content"), t.get("subject")))) for t in inp.get("todos", ())
+    ],
+}
+
+TSignalPattern = Signal | NlpSignal
+
+
+def score_signals(patterns: Sequence[TSignalPattern], text: str) -> int:
+    from captain_hook.signals.nlp import nlp_scan
+
+    total = 0
+    for s in patterns:
+        match s:
+            case NlpSignal(clauses=clauses) if nlp_scan(clauses, text):
+                total += s.weight
+            case Signal() if re.search(s.pattern, text, s.flags):
+                total += s.weight
+            case _:
+                pass
+    return total
+
+
+def extract_signal_context(patterns: Sequence[TSignalPattern], text: str) -> list[str]:
+    from captain_hook.signals.nlp import nlp_scan
+
+    result: list[str] = []
+    for s in patterns:
+        match s:
+            case NlpSignal(clauses=clauses):
+                result.extend(nlp_scan(clauses, text))
+            case Signal():
+                result.extend(line for line in text.splitlines() if re.search(s.pattern, line, s.flags))
+    return result
+
+
+def block_texts(event: UserEvent | AssistantEvent) -> Iterator[str]:
+    for block in event.blocks:
+        match block:
+            case ThinkingBlock(thinking=thinking):
+                yield thinking
+            case ToolUseBlock(name=name, input=payload) if extract := PROSE_TOOLS.get(name):
+                yield from extract(payload)
+            case _:
+                pass
+
+
+def transcript_texts(evt: BaseHookEvent, window: int | Literal["turn"]) -> list[str]:
+    """Extract prose from recent transcript events for signal scoring.
+
+    For ``UserPromptSubmit`` events, returns just the user prompt. Otherwise scans
+    the last ``window`` events — the whole current turn when ``window`` is
+    ``"turn"`` — and returns one entry per prose source: each event's ``.text``,
+    each thinking block, and the prose fields of prose-carrying tool calls
+    (``ReportFindings`` findings, ``TaskCreate``/``TaskUpdate`` subjects and
+    descriptions, ``TodoWrite`` todos).
+    """
+    if evt.event == Event.UserPromptSubmit and evt.user_prompt:
+        return [evt.user_prompt]
+    scope = evt.ctx.turn if window == "turn" else evt.ctx.t.recent(window)
+    return [
+        text
+        for event in scope.events
+        if isinstance(event, UserEvent | AssistantEvent)
+        for text in (event.text, *block_texts(event))
+        if text
+    ]
+
+
+def cite_message(sig: Signals, triggering: list[str], message: str) -> str:
+    """Append trigger context to a message when signal matches are found."""
+    return (
+        f"{message}\n\nTriggered by: {'; '.join(context)}"
+        if (context := extract_signal_context(sig.patterns, "\n".join(triggering)))
+        else message
+    )
+
+
+def resolve_signals(signals: Sequence[Signal | NlpSignal] | Signals | None) -> Signals | None:
+    """Normalize signals input into a ``Signals`` bundle, or None.
+
+    A bare ``list[Signal]`` is wrapped with ``threshold=1`` (any single match triggers).
+    """
+    if signals is None:
+        return None
+    if isinstance(signals, Signals):
+        return signals
+    return Signals(patterns=list(signals), threshold=1)

{capt_hook-8.3.0 → capt_hook-8.4.0}/captain_hook/types.py

@@ -9,6 +9,7 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Generic,
+    Literal,
     Protocol,
     TypeVar,
     get_args,
@@ -657,11 +658,17 @@ class Signals:
     When a bare ``list[Signal]`` is passed to a primitive, ``resolve_signals``
     wraps it with ``threshold=1`` — meaning *any* single signal match triggers.
     Pass a higher threshold to require multiple signals to fire together.
+
+    ``window`` bounds how much transcript each scoring pass reads: the last
+    ``window`` events by default, or the whole current turn with the ``"turn"``
+    sentinel. Use ``"turn"`` when the tell can sit hundreds of events before the
+    turn ends — a fixed window at ``Stop`` only reaches the last few tool
+    exchanges.
     """
 
     patterns: Sequence[Signal | NlpSignal]
     threshold: int
-    window: int = 15
+    window: int | Literal["turn"] = 15
 
 
 @dataclass(frozen=True, kw_only=True)

{capt_hook-8.3.0 → capt_hook-8.4.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 = "8.3.0"
+version = "8.4.0"
 description = "Stop repeating yourself to Claude."
 readme = "README.md"
 license = "PolyForm-Noncommercial-1.0.0"

capt_hook-8.3.0/captain_hook/signals/__init__.py

@@ -1,81 +0,0 @@
-from __future__ import annotations
-
-import re
-from collections.abc import Sequence
-from typing import TYPE_CHECKING
-
-from cc_transcript.models import AssistantEvent, UserEvent
-
-from captain_hook.signals.nlp import NlpSignal
-from captain_hook.types import Event, Signal, Signals
-
-if TYPE_CHECKING:
-    from captain_hook.events import BaseHookEvent
-
-TSignalPattern = Signal | NlpSignal
-
-
-def score_signals(patterns: Sequence[TSignalPattern], text: str) -> int:
-    from captain_hook.signals.nlp import nlp_scan
-
-    total = 0
-    for s in patterns:
-        match s:
-            case NlpSignal(clauses=clauses) if nlp_scan(clauses, text):
-                total += s.weight
-            case Signal() if re.search(s.pattern, text, s.flags):
-                total += s.weight
-            case _:
-                pass
-    return total
-
-
-def extract_signal_context(patterns: Sequence[TSignalPattern], text: str) -> list[str]:
-    from captain_hook.signals.nlp import nlp_scan
-
-    result: list[str] = []
-    for s in patterns:
-        match s:
-            case NlpSignal(clauses=clauses):
-                result.extend(nlp_scan(clauses, text))
-            case Signal():
-                result.extend(line for line in text.splitlines() if re.search(s.pattern, line, s.flags))
-    return result
-
-
-def transcript_texts(evt: BaseHookEvent, window: int) -> list[str]:
-    """Extract text from recent transcript events for signal scoring.
-
-    For ``UserPromptSubmit`` events, returns just the user prompt.
-    Otherwise returns ``.text`` from the last ``window`` events.
-    """
-    return (
-        [evt.user_prompt]
-        if evt.event == Event.UserPromptSubmit and evt.user_prompt
-        else [
-            text
-            for event in evt.ctx.t.recent(window).events
-            if isinstance(event, UserEvent | AssistantEvent) and (text := event.text)
-        ]
-    )
-
-
-def cite_message(sig: Signals, triggering: list[str], message: str) -> str:
-    """Append trigger context to a message when signal matches are found."""
-    return (
-        f"{message}\n\nTriggered by: {'; '.join(context)}"
-        if (context := extract_signal_context(sig.patterns, "\n".join(triggering)))
-        else message
-    )
-
-
-def resolve_signals(signals: Sequence[Signal | NlpSignal] | Signals | None) -> Signals | None:
-    """Normalize signals input into a ``Signals`` bundle, or None.
-
-    A bare ``list[Signal]`` is wrapped with ``threshold=1`` (any single match triggers).
-    """
-    if signals is None:
-        return None
-    if isinstance(signals, Signals):
-        return signals
-    return Signals(patterns=list(signals), threshold=1)