capt-hook 5.1.0__tar.gz → 6.0.0__tar.gz

{capt_hook-5.1.0 → capt_hook-6.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 5.1.0
+Version: 6.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>=7,<8
+Requires-Dist: cc-transcript>=7.1,<8
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pydantic-settings>=2.0
 Requires-Dist: tree-sitter>=0.24

{capt_hook-5.1.0 → capt_hook-6.0.0}/captain_hook/__init__.py

@@ -21,8 +21,10 @@ from cc_transcript.tools import (
 
 from captain_hook import file, style, util
 from captain_hook.app import hook, on
+from captain_hook.ast_grep import COMMENT_TYPES
 from captain_hook.command import CommandLine, ParsedCommand, Redirect
 from captain_hook.context import HookContext
+from captain_hook.contexts import AfterEdit, BeforeEdit, Introduced, PromptContext, apply_contexts
 from captain_hook.durable import DurableSlot, DurableState, DurableStore
 from captain_hook.events import (
     BaseHookEvent,
@@ -32,6 +34,7 @@ from captain_hook.events import (
     PreCompactEvent,
     PreToolUseEvent,
     SessionEndEvent,
+    SessionStartEvent,
     StopEvent,
     SubagentStartEvent,
     SubagentStopEvent,
@@ -66,7 +69,7 @@ from captain_hook.primitives.workflow import Artifact, Step, Workflow, text_matc
 from captain_hook.prompt import Prompt
 from captain_hook.session import SessionSlot, SessionStore, session_state
 from captain_hook.settings import HooksSettings, build_settings
-from captain_hook.signals.nlp import Clause, NlpSignal, Phrase
+from captain_hook.signals.nlp import Clause, NlpSignal, Phrase, has_nominal_subject, is_past_predicate
 from captain_hook.state import HookState, PrimitiveState, WorkflowState, workflow_state
 from captain_hook.tasks import Task, Tasks
 from captain_hook.testing import Allow, Block, FileFixture, InlineTests, Input, Rewrite, TranscriptFixture, Warn

{capt_hook-5.1.0 → capt_hook-6.0.0}/captain_hook/ast_grep.py

@@ -14,7 +14,7 @@ long names (``"python"``).
 from __future__ import annotations
 
 import re
-from collections.abc import Iterator
+from collections.abc import Iterable, Iterator, Set
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
@@ -29,6 +29,13 @@ EXT_TO_LANG: dict[str, str] = {glob.removeprefix("*."): lang for lang, globs in
 
 TEMPLATE_VAR = re.compile(r"\$\$\$([A-Z_][A-Z0-9_]*)|\$([A-Z_][A-Z0-9_]*)")
 
+COMMENT_TYPES: frozenset[str] = frozenset({"comment", "line_comment", "block_comment"})
+"""Tree-sitter node kinds that denote a comment, across every supported grammar.
+
+The union covers every [`LANG_GLOBS`][captain_hook.types.LANG_GLOBS] grammar; a future grammar
+whose top-level comment kind is named differently would silently miss.
+"""
+
 
 @dataclass(frozen=True, slots=True)
 class Match:
@@ -39,6 +46,31 @@ class Match:
     text: str
 
 
+@dataclass(frozen=True, slots=True)
+class SyntaxNode:
+    """One node of a parsed syntax tree — the framework's face over the ast-grep binding node."""
+
+    raw: SgNode
+
+    @property
+    def kind(self) -> str:
+        return self.raw.kind()
+
+    @property
+    def text(self) -> str:
+        return self.raw.text()
+
+    def descendants(self) -> Iterator[SyntaxNode]:
+        """Every node below this one, in document order."""
+        for raw in self.raw.children():
+            yield (child := SyntaxNode(raw))
+            yield from child.descendants()
+
+    def to_match(self) -> Match:
+        r = self.raw.range()
+        return Match(line=r.start.line + 1, end_line=r.end.line + 1, text=self.raw.text())
+
+
 def lang_for_path(path: Path) -> str | None:
     """Infer an ast-grep language id from a file extension, or ``None`` when unsupported."""
     return EXT_TO_LANG.get(path.suffix.removeprefix("."))
@@ -49,15 +81,10 @@ def has_metavar(text: str) -> bool:
     return TEMPLATE_VAR.search(text) is not None
 
 
-def parse(source: str, lang: str) -> SgNode:
+def parse(source: str, lang: str) -> SyntaxNode:
     from ast_grep_py import SgRoot
 
-    return SgRoot(source, lang).root()
-
-
-def to_match(node: SgNode) -> Match:
-    r = node.range()
-    return Match(line=r.start.line + 1, end_line=r.end.line + 1, text=node.text())
+    return SyntaxNode(SgRoot(source, lang).root())
 
 
 def match_key(m: Match) -> str:
@@ -66,22 +93,46 @@ def match_key(m: Match) -> str:
 
 def matches(source: str, lang: str, pattern: str) -> bool:
     """Whether ``pattern`` matches anywhere in ``source`` — the cheap boolean for conditions."""
-    return parse(source, lang).find(pattern=pattern) is not None
+    return parse(source, lang).raw.find(pattern=pattern) is not None
 
 
 def find_all(source: str, lang: str, pattern: str) -> Iterator[Match]:
     """Every structural match of ``pattern`` in ``source``, as 1-based-line :class:`Match` objects."""
-    return (to_match(node) for node in parse(source, lang).find_all(pattern=pattern))
+    return (SyntaxNode(node).to_match() for node in parse(source, lang).raw.find_all(pattern=pattern))
 
 
-def find_introduced(old: str, new: str, lang: str, pattern: str) -> Iterator[Match]:
-    """Matches present in ``new`` whose construct was absent from ``old`` — the diff helper.
+def find_kinds(source: str, lang: str, kinds: Set[str]) -> Iterator[Match]:
+    """Every node whose tree-sitter kind is in ``kinds``, in document order.
+
+    Kinds are read off parsed nodes rather than passed to the ast-grep kind
+    matcher, which raises on kind names a grammar doesn't define.
+    """
+    return (n.to_match() for n in parse(source, lang).descendants() if n.kind in kinds)
+
+
+def comments(source: str, lang: str) -> Iterator[Match]:
+    """Every comment in ``source``, in document order — regardless of language."""
+    return find_kinds(source, lang, COMMENT_TYPES)
+
+
+def introduced(old: Iterable[Match], new: Iterable[Match]) -> Iterator[Match]:
+    """Matches in ``new`` whose construct was absent from ``old``.
 
     Identity is the match's whitespace-normalized text, not its range (which shifts as
     surrounding code moves) — so a pre-existing construct is never reported as newly added.
     """
-    before = {match_key(m) for m in find_all(old, lang, pattern)}
-    return (m for m in find_all(new, lang, pattern) if match_key(m) not in before)
+    before = {match_key(m) for m in old}
+    return (m for m in new if match_key(m) not in before)
+
+
+def find_introduced(old: str, new: str, lang: str, pattern: str) -> Iterator[Match]:
+    """Matches of ``pattern`` present in ``new`` but absent from ``old`` — the diff helper."""
+    return introduced(find_all(old, lang, pattern), find_all(new, lang, pattern))
+
+
+def introduced_comments(old: str, new: str, lang: str) -> Iterator[Match]:
+    """Comments present in ``new`` whose text was absent from ``old``."""
+    return introduced(comments(old, lang), comments(new, lang))
 
 
 def rewrite(source: str, lang: str, pattern: str, replace: str) -> str:
@@ -90,7 +141,7 @@ def rewrite(source: str, lang: str, pattern: str, replace: str) -> str:
     ``replace`` uses ast-grep's ``$VAR`` / ``$$$VAR`` fix syntax, each metavariable filled from the
     match it names. Returns ``source`` unchanged when nothing matches.
     """
-    root = parse(source, lang)
+    root = parse(source, lang).raw
     if not (edits := [node.replace(fill_template(node, replace)) for node in root.find_all(pattern=pattern)]):
         return source
     return root.commit_edits(edits)
@@ -103,7 +154,7 @@ def capture(source: str, lang: str, pattern: str) -> dict[str, str] | None:
     original-source span covering its matches, so whitespace is preserved (mirroring :func:`fill_template`).
     A pattern with no metavars that still matches yields an empty dict — present but empty.
     """
-    if (node := parse(source, lang).find(pattern=pattern)) is None:
+    if (node := parse(source, lang).raw.find(pattern=pattern)) is None:
         return None
 
     def value(m: re.Match[str]) -> str:

{capt_hook-5.1.0 → capt_hook-6.0.0}/captain_hook/cli.py

@@ -8,6 +8,7 @@ import subprocess
 import sys
 import time
 from collections import defaultdict
+from collections.abc import Sequence
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
@@ -18,7 +19,7 @@ from cc_transcript.ids import SessionId
 from captain_hook.app import _state, load_gitignore, reset
 from captain_hook.context import HookContext, load_transcript
 from captain_hook.dispatch import dispatch
-from captain_hook.loader import CONF_MODULE, discover_hooks, discover_pack, is_skip_marked
+from captain_hook.loader import CONF_MODULE, discover_hooks, discover_pack, is_skip_marked, register_nlp_provisioning
 from captain_hook.log import setup_logging
 from captain_hook.packs import manager
 from captain_hook.review.cli import review
@@ -35,19 +36,22 @@ class CliState:
     root: Path
     hooks: str
 
-    def discover(self) -> None:
+    def discover(self) -> list[manager.ResolvedPack]:
         reset()
         load_gitignore(self.root)
         discover_hooks(self.hooks)
         resolved, missing = manager.resolve_enabled_packs(self.root)
         for pack_ in resolved:
             discover_pack(pack_.entry.name, pack_.path)
+        if any(pack_.manifest.nlp for pack_ in resolved):
+            register_nlp_provisioning()
         if missing:
             print(
                 f"capt-hook: packs unavailable (offline and not cached): {', '.join(missing)} "
                 "— run `capt-hook pack update` when online",
                 file=sys.stderr,
             )
+        return resolved
 
 
 def example_hook_source() -> str:
@@ -222,12 +226,26 @@ def print_hook_summary(label: str, summary: dict[str, str], deferred_to: str) ->
         click.echo(f"  deferred to {deferred_to}: {', '.join(deferred)}")
 
 
+def provision_nlp(resolved: Sequence[manager.ResolvedPack]) -> None:
+    from captain_hook.util import http
+    from captain_hook.util.model_cache import ensure_nlp_resources
+
+    if not any(pack_.manifest.nlp for pack_ in resolved):
+        return
+    click.echo("Provisioning NLP resources (spaCy en_core_web_sm ~13MB + oewn:2025 lexicon ~231MB, cached)...")
+    try:
+        ensure_nlp_resources()
+    except (http.GitHubFetchError, OSError) as e:
+        click.echo(f"  deferred (offline?): {e} — the SessionStart hook will retry at session start")
+
+
 def regenerate_settings(state: CliState) -> None:
-    state.discover()
+    resolved = state.discover()
     settings_path = state.root / ".claude" / "settings.json"
     merged, summary = merge_settings(".claude/hooks", settings_path)
     write_settings(settings_path, merged)
     print_hook_summary(str(settings_path.relative_to(state.root)), summary, sibling_settings(settings_path).name)
+    provision_nlp(resolved)
 
 
 def settings_drift(root: Path) -> set[str]:
@@ -320,9 +338,10 @@ def init_project(root: Path, *, review: bool = True) -> None:
         example.write_text(example_hook_source())
 
     settings_path = root / ".claude" / "settings.json"
-    CliState(root=root, hooks=str(hooks_dir)).discover()
+    resolved = CliState(root=root, hooks=str(hooks_dir)).discover()
     merged, summary = merge_settings(".claude/hooks", settings_path)
     write_settings(settings_path, merged)
+    provision_nlp(resolved)
 
     register_marketplace(root)
 
@@ -507,7 +526,7 @@ def run(state: CliState, event: str, async_: bool) -> None:
 @click.pass_obj
 def register_hooks_cmd(state: CliState, hooks_dir: str, dry_run: bool, from_source: str) -> None:
     """Register captain-hook's event hooks into .claude/settings.json."""
-    state.discover()
+    resolved = state.discover()
     settings_path = state.root / ".claude" / "settings.json"
     merged, summary = merge_settings(hooks_dir, settings_path, from_source=from_source)
     if dry_run:
@@ -515,6 +534,7 @@ def register_hooks_cmd(state: CliState, hooks_dir: str, dry_run: bool, from_sour
         return
     write_settings(settings_path, merged)
     print_hook_summary(str(settings_path), summary, sibling_settings(settings_path).name)
+    provision_nlp(resolved)
 
 
 @cli.command()

capt_hook-6.0.0/captain_hook/contexts.py

@@ -0,0 +1,151 @@
+"""Declarative prompt contexts: named XML evidence blocks attached to LLM primitives.
+
+A :class:`PromptContext` resolves one ``<tag>…</tag>`` block from the current event at
+evaluation time. Pass instances via ``contexts=[...]`` on ``llm_nudge``/``llm_gate``;
+a ``required`` context whose content is empty skips the LLM call entirely. The ambient
+defaults :class:`BeforeEdit` and :class:`AfterEdit` attach to every primitive, carrying
+the pending edit's before/after text on edit-shaped events and nothing elsewhere.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from functools import partial
+from typing import TYPE_CHECKING, Protocol
+
+from captain_hook.ast_grep import find_all, find_kinds, introduced, lang_for_path
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence, Set
+
+    from captain_hook.events import BaseHookEvent
+    from captain_hook.prompt import Prompt
+
+SNAKE_CASE = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+class PromptContext(Protocol):
+    """One declarative XML block attached to an LLM primitive's prompt.
+
+    ``content(evt)`` runs at evaluation time; ``None`` or empty content omits the
+    block. When a ``required`` context yields empty content, the primitive skips
+    the LLM call entirely — nothing fires and no fire is consumed.
+    """
+
+    tag: str
+    required: bool
+
+    def content(self, evt: BaseHookEvent) -> str | None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class BeforeEdit:
+    """The pending edit's pre-image, as a ``<before_edit>`` block.
+
+    Reads :attr:`~captain_hook.events.ToolHookEvent.replaced` — an Edit's old text, a
+    MultiEdit's joined olds, or a Write's current on-disk content — so it carries
+    content only at ``PreToolUse`` on edit-shaped events. Attached to every LLM
+    primitive as a default context; ``required=False`` because it is ambient
+    enrichment, empty (and omitted) on non-edit events. Pass ``BeforeEdit(required=True)``
+    explicitly to gate a hook on a non-empty pre-image.
+    """
+
+    tag: str = "before_edit"
+    required: bool = False
+
+    def content(self, evt: BaseHookEvent) -> str | None:
+        return evt.replaced
+
+
+@dataclass(frozen=True, slots=True)
+class AfterEdit:
+    """The pending edit's new text, as an ``<after_edit>`` block.
+
+    Reads :attr:`~captain_hook.events.BaseHookEvent.content` — the text an Edit,
+    Write, MultiEdit, or NotebookEdit is about to land. Attached to every LLM
+    primitive as a default context; ``required=False`` because it is ambient
+    enrichment, empty (and omitted) on non-edit events.
+    """
+
+    tag: str = "after_edit"
+    required: bool = False
+
+    def content(self, evt: BaseHookEvent) -> str | None:
+        return evt.content
+
+
+@dataclass(frozen=True, slots=True)
+class Introduced:
+    """Constructs the pending edit newly introduces, as an auto-tagged block.
+
+    Exactly one of ``kind``/``pattern`` selects the constructs: ``kind`` names
+    tree-sitter node kinds (a bare string or any set — normalized to ``frozenset``;
+    see :data:`~captain_hook.ast_grep.COMMENT_TYPES`), ``pattern`` is an ast-grep
+    pattern. Extraction diffs the event's before/after text, so only constructs
+    absent before the edit appear; files without a supported language yield nothing.
+
+    ``required`` defaults to ``True``: a context you attach explicitly IS the
+    evidence — no evidence, no LLM call. ``tag`` auto-derives from the class name in
+    snake_case (``Introduced()`` renders ``<introduced>``; a subclass named
+    ``TombstoneComments`` renders ``<tombstone_comments>``). Subclass and override
+    :meth:`keep` to filter which introduced constructs count.
+
+    Example:
+        >>> llm_nudge("...", contexts=[Introduced(pattern="print($$$)")],
+        ...           events=Event.PreToolUse, only_if=[Tool("Edit", "Write", "MultiEdit")])
+    """
+
+    kind: str | Set[str] | None = None
+    pattern: str | None = None
+    required: bool = True
+    tag: str | None = None
+
+    def __post_init__(self) -> None:
+        if (self.kind is None) == (self.pattern is None):
+            raise ValueError(f"{type(self).__name__} requires exactly one of kind or pattern")
+        if self.kind is not None and not isinstance(self.kind, frozenset):
+            object.__setattr__(self, "kind", frozenset([self.kind] if isinstance(self.kind, str) else self.kind))
+        if self.tag is None:
+            object.__setattr__(self, "tag", SNAKE_CASE.sub("_", type(self).__name__).lower())
+
+    def keep(self, text: str) -> bool:
+        """Whether an introduced construct's text belongs in the block — override to filter."""
+        return True
+
+    def content(self, evt: BaseHookEvent) -> str | None:
+        if (
+            not (file := evt.file)
+            or not (lang := lang_for_path(file.path))
+            or (old := evt.replaced) is None
+            or (new := evt.content) is None
+        ):
+            return None
+        extract = (
+            partial(find_kinds, lang=lang, kinds=self.kind)
+            if self.pattern is None
+            else partial(find_all, lang=lang, pattern=self.pattern)
+        )
+        return "\n".join(m.text for m in introduced(extract(old), extract(new)) if self.keep(m.text))
+
+
+def with_defaults(contexts: Sequence[PromptContext]) -> tuple[PromptContext, ...]:
+    defaults: tuple[PromptContext, ...] = (BeforeEdit(), AfterEdit())
+    return (*contexts, *(d for d in defaults if not any(isinstance(c, type(d)) for c in contexts)))
+
+
+def apply_contexts(
+    prompt: Prompt, evt: BaseHookEvent, contexts: Sequence[PromptContext], *, max_len: int = 2000
+) -> Prompt | None:
+    """Append each context's block to ``prompt`` in order, each capped at ``max_len`` characters.
+
+    A context yielding ``None`` or whitespace-only content has its block omitted;
+    when that context is ``required``, returns ``None`` instead — the caller must
+    skip the LLM call entirely.
+    """
+    for c in contexts:
+        text = c.content(evt)
+        if c.required and not (text and text.strip()):
+            return None
+        prompt = prompt.context(c.tag, text and text[:max_len])
+    return prompt

{capt_hook-5.1.0 → capt_hook-6.0.0}/captain_hook/durable.py

@@ -26,11 +26,13 @@ if TYPE_CHECKING:
 
 Scope = Literal["project", "global"]
 
+DURABLE_ROOT_OVERRIDE: list[Path] = []
+
 
 def durable_root() -> Path:
     from captain_hook.settings import resolve_state_dir
 
-    return resolve_state_dir() / "hooks" / "durable"
+    return DURABLE_ROOT_OVERRIDE[-1] if DURABLE_ROOT_OVERRIDE else resolve_state_dir() / "hooks" / "durable"
 
 
 def project_key(repo_root: Path) -> str:

{capt_hook-5.1.0 → capt_hook-6.0.0}/captain_hook/events.py

@@ -129,6 +129,10 @@ class BaseHookEvent:
     def old(self) -> str | None:
         return None
 
+    @property
+    def replaced(self) -> str | None:
+        return None
+
     @property
     def agent_type(self) -> str | None:
         return None
@@ -227,6 +231,23 @@ class ToolHookEvent(BaseHookEvent):
             case _:
                 return None
 
+    @property
+    def replaced(self) -> str | None:
+        """The pre-image of the text this call overwrites.
+
+        An Edit's ``old``, a MultiEdit's newline-joined olds, or — for a Write — the
+        file's current on-disk content (``""`` for a new file). ``None`` for other
+        tools. The Write arm reads the disk, so it is only meaningful at
+        ``PreToolUse``: once the Write lands, disk already holds the new text.
+        """
+        match self.input:
+            case EditCall() | MultiEditCall():
+                return self.old
+            case WriteCall(file_path=path):
+                return p.read_text() if (p := Path(path)).exists() else ""
+            case _:
+                return None
+
     @property
     def agent_type(self) -> str | None:
         return call.agent_type if isinstance(call := self.input, TaskCall) else None
@@ -383,6 +404,20 @@ class NotificationEvent(BaseHookEvent):
         return self._raw.get("notification_type")
 
 
+@dataclass
+class SessionStartEvent(BaseHookEvent):
+    """Fires when a session starts, providing what triggered it. Warns inject context; it cannot block.
+
+    ``source`` is one of ``"startup"``, ``"resume"``, ``"clear"``, or ``"compact"``.
+    """
+
+    event_name: ClassVar[Event] = Event.SessionStart
+
+    @property
+    def source(self) -> str:
+        return self._raw["source"]
+
+
 @dataclass
 class SessionEndEvent(BaseHookEvent):
     """Fires when the session ends, providing the termination reason. Output is ignored, so it cannot block."""

{capt_hook-5.1.0 → capt_hook-6.0.0}/captain_hook/loader.py

@@ -9,11 +9,16 @@ import re
 import sys
 from pathlib import Path
 from types import ModuleType
+from typing import TYPE_CHECKING
 
 from loguru import logger
 
-from captain_hook.app import State, _state
+from captain_hook.app import State, _state, on
 from captain_hook.settings import build_settings
+from captain_hook.types import Event
+
+if TYPE_CHECKING:
+    from captain_hook.events import BaseHookEvent
 
 CONF_MODULE = "conf"
 PACK_PACKAGE_PREFIX = "captain_hook._packs"
@@ -105,6 +110,20 @@ def import_pack_module(fqn: str, path: Path) -> ModuleType:
     return module
 
 
+def register_nlp_provisioning() -> None:
+    """Register the shared SessionStart hook that eagerly provisions NLP resources.
+
+    Called once per discovery pass when any resolved pack manifest declares ``nlp``,
+    so both event dispatch and settings generation see the async hook.
+    """
+
+    @on(Event.SessionStart, async_=True)
+    def provision_nlp_resources(evt: BaseHookEvent) -> None:
+        from captain_hook.util.model_cache import ensure_nlp_resources
+
+        ensure_nlp_resources()
+
+
 def discover_pack(name: str, pack_dir: Path) -> None:
     pkg = f"{PACK_PACKAGE_PREFIX}.{re.sub(r'\W', '_', name)}"
     ensure_pack_package(PACK_PACKAGE_PREFIX, [])

{capt_hook-5.1.0 → capt_hook-6.0.0}/captain_hook/packs/general/capt-hook.toml

@@ -1,4 +1,5 @@
 name = "general"
-version = "0.3.0"
+version = "0.5.0"
 description = "Language-agnostic guards: git/command safety, doc & prompt nudges, task & plan discipline, and a code-review gate."
 hooks = "."
+nlp = true

{capt_hook-5.1.0 → capt_hook-6.0.0}/captain_hook/packs/general/models.py

@@ -1,21 +1,41 @@
 from __future__ import annotations
 
+from dataclasses import dataclass
+
 from captain_hook import (
     Agent,
     Allow,
+    BaseHookEvent,
     Block,
     Event,
     Input,
     Rewrite,
+    TaskCall,
     Tool,
     ToolInput,
     Warn,
     WorkflowScript,
     hook,
+    llm_nudge,
     nudge,
     set_tool_input,
 )
 
+
+@dataclass(frozen=True, slots=True)
+class DelegatedSpawn:
+    """Gating context: the pending Agent/Task call's model pin, agent type, and prompt."""
+
+    tag: str = "delegated_spawn"
+    required: bool = True
+
+    def content(self, evt: BaseHookEvent) -> str | None:
+        if (call := evt.as_input(TaskCall)) is None or not call.prompt:
+            return None
+        model = call.model or "(none — inherits the session model, fable)"
+        return f"model: {model}\nagent_type: {call.agent_type or '(default)'}\nprompt:\n{call.prompt}"
+
+
 hook(
     Event.PreToolUse,
     only_if=[Tool("Agent|Task"), ToolInput("model", r"(?i)\bhaiku\b")],
@@ -51,7 +71,10 @@ hook(
     only_if=[
         Tool("Agent|Task"),
         ToolInput("model", r"(?i)\b(haiku|sonnet|opus)\b"),
-        ToolInput("prompt", r"(?i)\b(writ(e|es|ing|ten)|draft|redraft|rewrit|revis|polish|copyedit|compose|author|update|edit)"),
+        ToolInput(
+            "prompt",
+            r"(?i)\b(writ(e|es|ing|ten)|draft|redraft|rewrit|revis|polish|copyedit|compose|author|update|edit)",
+        ),
         ToolInput(
             "prompt",
             r"(?i)\b(readme|docs?|documentation|blog|changelog|release notes|announcement"
@@ -95,6 +118,71 @@ set_tool_input(
     },
 )
 
+llm_nudge(
+    """Decide whether this delegated subagent should run on opus-4.8 instead of fable-5.
+
+<delegated_spawn> holds the pending Agent/Task call: its model pin (or that it inherits
+the session model, fable), agent type, and prompt.
+
+The Models rubric: implementation delegates to opus-4.8 at xhigh — opus is ~2x cheaper
+than fable and nearly as capable. Fable's lanes are orchestration, review, hard
+planning/design/diagnosis, all prose/writing, and implementation that is very sensitive
+or error-prone (auth, migrations, concurrency, data loss, crypto, subtle algorithms).
+
+Set fire=true only when the prompt is clearly routine implementation — building, fixing,
+wiring, or refactoring code — with no fable-lane signal. A prompt that reviews, plans,
+designs, diagnoses a hard bug, writes prose, or touches a sensitive surface stays on
+fable: fire=false. When uncertain, fire=false — the agent may have chosen fable
+deliberately, and a false alarm teaches it to ignore this nudge. Keep reasoning under
+40 words.
+
+<examples>
+<example fire="true">
+Implement the pagination endpoint in api/users.py per the spec in the plan.
+Routine implementation with no sensitivity signal — the opus xhigh lane.
+</example>
+<example fire="true">
+Add a --json flag to the export command and thread it through the formatter.
+Well-scoped feature wiring; the default implementation lane.
+</example>
+<example fire="false">
+Review the diff for correctness and concurrency issues.
+Review is fable's lane.
+</example>
+<example fire="false">
+Design the migration strategy for the sharded session store.
+Hard planning/design stays on fable.
+</example>
+<example fire="false">
+Implement the token-refresh race fix in the auth middleware.
+Auth plus concurrency: sensitive, error-prone implementation stays on fable.
+</example>
+</examples>""",
+    message=lambda r: (
+        f"This delegation would run on fable, but it reads as routine implementation. {r.reasoning} "
+        "Implementation defaults to model='opus' + effort='xhigh' (~2x cheaper, nearly as capable); "
+        "a well-scoped edit to existing code can also go to gpt-5.5 via the codex skill behind a "
+        "model='sonnet' low-effort wrapper. Keep fable if this genuinely is sensitive or error-prone. "
+        "See CLAUDE.md § Plan Execution & Orchestration (Models)."
+    ),
+    contexts=[DelegatedSpawn()],
+    events=Event.PreToolUse,
+    only_if=[Tool("Agent|Task")],
+    skip_if=[
+        ToolInput("model", r"(?i)\b(opus|sonnet|haiku)\b"),
+        Agent("Explore|claude-code-guide"),
+    ],
+    agent=False,
+    transcript=False,
+    tests={
+        Input(prompt="implement the pagination endpoint in api/users.py"): Warn(pattern="opus"),
+        Input(model="fable", prompt="add a --json flag to the export command"): Warn(pattern="opus"),
+        Input(model="opus", prompt="implement the pagination endpoint in api/users.py"): Allow(),
+        Input(model="sonnet", prompt="scan the repo for TODO markers"): Allow(),
+        Input(agent_type="Explore", prompt="find where the config loader lives"): Allow(),
+    },
+)
+
 nudge(
     """
     This workflow script pins agent() steps to haiku. Reserve haiku for mechanical single-fact