capt-hook 4.3.1__tar.gz → 4.4.0__tar.gz

{capt_hook-4.3.1 → capt_hook-4.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 4.3.1
+Version: 4.4.0
 Summary: Declarative hook framework for Claude Code
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali

{capt_hook-4.3.1 → capt_hook-4.4.0}/captain_hook/__init__.py

@@ -52,6 +52,7 @@ from captain_hook.primitives import (
     prompt_check,
     rewrite_code,
     rewrite_command,
+    set_tool_input,
     warn_command,
 )
 
@@ -90,8 +91,10 @@ from captain_hook.types import (
     TCondition,
     TestFile,
     Tool,
+    ToolInput,
     TouchedFile,
     UsedSkill,
     Waiting,
+    WorkflowScript,
 )
 from captain_hook.util import read_json, resolve_binary

{capt_hook-4.3.1 → capt_hook-4.4.0}/captain_hook/conditions.py

@@ -3,10 +3,11 @@
 from __future__ import annotations
 
 import re
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 from cc_transcript.models import OtherEvent
-from cc_transcript.tools import tool_name_matches
+from cc_transcript.tools import WorkflowCall, tool_name_matches
 
 from captain_hook.types import (
     Agent,
@@ -23,9 +24,11 @@ from captain_hook.types import (
     TCondition,
     TestFile,
     Tool,
+    ToolInput,
     TouchedFile,
     UsedSkill,
     Waiting,
+    WorkflowScript,
 )
 
 if TYPE_CHECKING:
@@ -80,6 +83,32 @@ def is_waiting(evt: BaseHookEvent) -> bool:
     )
 
 
+def workflow_script_source(evt: BaseHookEvent) -> str | None:
+    if not (call := evt.as_input(WorkflowCall)):
+        return None
+    if call.script is not None:
+        return call.script
+    if not call.script_path:
+        return None
+    try:
+        path = Path(call.script_path)
+        if not path.is_file() or path.stat().st_size > 1_000_000:
+            return None
+        return path.read_text(errors="ignore")
+    except OSError:
+        return None
+
+
+def matches_workflow_script(cond: WorkflowScript, evt: BaseHookEvent) -> bool:
+    if (source := workflow_script_source(evt)) is None:
+        return False
+    if cond.pattern is not None:
+        return bool(re.search(cond.pattern, source, re.MULTILINE))
+    return cond.model is not None and any(
+        re.search(cond.model, pinned) for pinned in re.findall(r"""model\s*:\s*['"]([^'"]*)['"]""", source)
+    )
+
+
 def is_project_file(evt: BaseHookEvent) -> bool:
     if not (file := evt.file):
         return False
@@ -104,6 +133,14 @@ def check_condition(c: TCondition, evt: BaseHookEvent) -> bool:
                 and evt.content
                 and re.search(pattern, evt.content, re.MULTILINE)
             )
+        case ToolInput(field, pattern):
+            return bool(
+                evt.tool_name
+                and isinstance(value := evt.input.raw.get(field), str)
+                and re.search(pattern, value, re.MULTILINE)
+            )
+        case WorkflowScript() as workflow_script:
+            return matches_workflow_script(workflow_script, evt)
         case Pattern(pattern, lang, project_only):
             from captain_hook.ast_grep import lang_for_path
             from captain_hook.ast_grep import matches as ast_grep_matches

{capt_hook-4.3.1 → capt_hook-4.4.0}/captain_hook/packs/general/capt-hook.toml

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

capt_hook-4.4.0/captain_hook/packs/general/models.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from captain_hook import (
+    Agent,
+    Allow,
+    Block,
+    Event,
+    Input,
+    Rewrite,
+    Tool,
+    ToolInput,
+    Warn,
+    WorkflowScript,
+    hook,
+    nudge,
+    set_tool_input,
+)
+
+hook(
+    Event.PreToolUse,
+    only_if=[Tool("Agent|Task"), ToolInput("model", r"(?i)\bhaiku\b")],
+    skip_if=[ToolInput("prompt", r"(?i)\b(classif|label|tag|categoriz|per.file|one (fact|thing))")],
+    message=(
+        "This subagent is pinned to haiku. Route a subagent to haiku only for a single-fact "
+        "mechanical step — classifying, labeling, or tagging one thing per item. Anything that "
+        "carries judgment should run on sonnet; use model='sonnet', or drop model entirely to "
+        "inherit the session model. See CLAUDE.md § Plan Execution & Orchestration (Models)."
+    ),
+    block=True,
+    tests={
+        Input(model="haiku", content="implement the retry backoff in the client"): Block(),
+        Input(model="haiku", content="classify each file's language"): Allow(),
+        Input(content="implement the retry backoff in the client"): Allow(),
+        Input(model="sonnet", content="implement the retry backoff in the client"): Allow(),
+    },
+)
+
+set_tool_input(
+    "model",
+    "sonnet",
+    tool="Agent|Task",
+    only_if=[Agent("Explore|claude-code-guide")],
+    note=(
+        "Upgraded this recon subagent from the silent haiku default to sonnet, per the Models "
+        "table in CLAUDE.md § Plan Execution & Orchestration (Models)."
+    ),
+    tests={
+        Input(agent_type="Explore"): Rewrite(),
+        Input(agent_type="Explore", model="haiku"): Allow(),
+        Input(agent_type="general-purpose"): Allow(),
+    },
+)
+
+nudge(
+    """
+    This workflow script pins agent() steps to haiku. Reserve haiku for mechanical single-fact
+    map steps; a judgment-bearing stage should inherit the session model or route up. See
+    CLAUDE.md § Plan Execution & Orchestration (Models).
+    """,
+    only_if=[Tool("Workflow"), WorkflowScript(model="haiku")],
+    events=Event.PreToolUse,
+    max_fires=2,
+    tests={
+        Input(tool="Workflow", tool_input={"script": "steps:\n  - agent: reviewer\n    model: 'haiku'\n"}): Warn(),
+        Input(tool="Workflow", tool_input={"script": "steps:\n  - agent: reviewer\n    model: 'sonnet'\n"}): Allow(),
+    },
+)

{capt_hook-4.3.1 → capt_hook-4.4.0}/captain_hook/primitives/__init__.py

@@ -12,4 +12,4 @@ from captain_hook.primitives.llm import (
     prompt_check,
 )
 from captain_hook.primitives.nudge import gate, nudge
-from captain_hook.primitives.rewrite import rewrite_code
+from captain_hook.primitives.rewrite import rewrite_code, set_tool_input

{capt_hook-4.3.1 → capt_hook-4.4.0}/captain_hook/primitives/rewrite.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from captain_hook import ast_grep
 from captain_hook.app import on
@@ -62,3 +62,40 @@ def rewrite_code(
 
     handler.__name__ = handler.__qualname__ = hook_name("rewrite_code", None, f"{pattern}=>{replace}")
     on(Event.PreToolUse, only_if=[Tool("Edit|Write|MultiEdit|NotebookEdit"), *only_if], tests=tests)(handler)
+
+
+def set_tool_input(
+    field: str,
+    value: Any,
+    *,
+    tool: str,
+    only_if: Sequence[TCondition] = (),
+    skip_if: Sequence[TCondition] = (),
+    note: str | None = None,
+    tests: InlineTests | None = None,
+) -> None:
+    """Register a ``PreToolUse`` hook that fills a MISSING top-level input field with ``value``.
+
+    When ``field`` is absent from the matched tool's input, the input is rewritten to
+    ``{**raw, field: value}`` and allowed, with ``note`` surfaced as ``additionalContext``. A field
+    already present — even falsy — is left untouched, so an explicit choice is never clobbered.
+
+    Args:
+        field: The top-level tool-input key to fill.
+        value: The value to set when the field is absent.
+        tool: Tool-name pattern to gate on, e.g. ``"Agent|Task"``.
+        only_if: Extra conditions ANDed onto the built-in tool guard.
+        skip_if: Conditions that skip the hook when any matches.
+        note: Advisory context surfaced alongside the rewrite.
+        tests: Inline tests for the registered hook.
+
+    Example:
+        >>> set_tool_input("model", "sonnet", tool="Agent|Task", only_if=[Agent("Explore")], note="upgraded")
+    """
+
+    def handler(evt: PreToolUseEvent) -> HookResponse:
+        raw = evt.input.raw
+        return None if field in raw else evt.rewrite({**raw, field: value}, note=note)
+
+    handler.__name__ = handler.__qualname__ = hook_name("set_tool_input", None, f"{tool}:{field}")
+    on(Event.PreToolUse, only_if=[Tool(tool), *only_if], skip_if=skip_if, tests=tests)(handler)

{capt_hook-4.3.1 → capt_hook-4.4.0}/captain_hook/skills/authoring-hooks/references/capt-hook-api.md

@@ -20,10 +20,10 @@ from __future__ import annotations
 
 from captain_hook import (
     Allow, BaseHookEvent, Block, Event, HookResult, InlineTests, Input, Prompt,
-    RanCommand, Rewrite, Signal, Signals, SourceEdits, TestFile, Tool, TouchedFile,
-    TranscriptFixture, Warn,
+    RanCommand, Rewrite, Signal, Signals, SourceEdits, TestFile, Tool, ToolInput, TouchedFile,
+    TranscriptFixture, Warn, WorkflowScript,
     block_command, gate, hook, lint, llm_gate, llm_nudge, nudge, on,
-    prompt_check, rewrite_command, warn_command, workflow, Artifact, Step, text_matches,
+    prompt_check, rewrite_command, set_tool_input, warn_command, workflow, Artifact, Step, text_matches,
 )
 from captain_hook.types import Command
 ```
@@ -70,6 +70,7 @@ def handler(evt: BaseHookEvent) -> HookResult | None:
 | `block_command` | `(pattern, *, reason, hint=None, tests=None)` | `PreToolUse` + `Tool("Bash")`; message `"BLOCKED: {reason}. {hint}."` |
 | `warn_command` | `(pattern, *, message, tests=None, events=Event.PostToolUse)` | warns, never blocks |
 | `rewrite_command` | `(pattern, replace, *, note=None, tests=None)` | `PreToolUse` + `Tool("Bash")`; `re.sub(pattern, replace, command)` then allows with the rewritten command |
+| `set_tool_input` | `(field, value, *, tool, only_if=(), skip_if=(), note=None, tests=None)` | `PreToolUse` + `Tool(tool)`; fills a **missing** top-level input field with `value` and allows, never clobbering a present one |
 | `gate` | `(message, *, when=None, only_if=(), skip_if=(), events=None, max_fires=None, tests=None)` | `Stop \| SubagentStop`, `max_fires=1`; blocks |
 | `nudge` | `(message, *, when=None, signals=None, only_if=(), skip_if=(), block=False, events=None, max_fires=None, tests=None)` | `PostToolUse` (with signals) else `PreToolUse`; `max_fires` 3 / 1; warns |
 | `lint` | `(check, *, message, trigger=None, sep=", ", block=False, events=None, tests=None, max_shown=5)` | `PostToolUse`, `Tool("Edit\|Write")` + `*.py`, skips test files |
@@ -128,6 +129,8 @@ evaluated first.
 | Filter by file path | `FilePath("*.py", "*.pyi")` |
 | Filter by bash command text | `Command(r"git\s+push")` — from `captain_hook.types` |
 | Filter by file content being written | `Content(r"print\(")` (multiline regex over Edit new / Write content) |
+| Filter by one raw tool-input field | `ToolInput("model", r"(?i)\bhaiku\b")` (multiline regex over one top-level field of any tool) |
+| Filter by a Workflow script | `WorkflowScript(model="haiku")` (inline `script`, or the `script_path` file's contents) |
 | Filter by subagent type | `Agent("cleanup")` |
 | Match only test files | `TestFile()` (`test_*.py`, `conftest.py`) |
 | Python source edits (skips tests by default) | `SourceEdits(lang="py")`; `lang` also `ts`, `go`, `rs`, ... |

{capt_hook-4.3.1 → capt_hook-4.4.0}/captain_hook/testing/helpers.py

@@ -105,7 +105,12 @@ def make_tool_input(
     old: str | None,
     offset: int | None = None,
     limit: int | None = None,
+    agent_type: str | None = None,
+    model: str | None = None,
+    tool_input: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
+    if tool_input is not None:
+        return tool_input
     match tool:
         case "Bash" | "Execute":
             return omit_none({"command": command, "timeout": None, "description": None})
@@ -118,7 +123,7 @@ def make_tool_input(
         case "Read":
             return omit_none({"file_path": file or "", "limit": limit, "offset": offset})
         case "Agent" | "Task":
-            return omit_none({"prompt": content or "", "subagent_type": None})
+            return omit_none({"prompt": content or "", "subagent_type": agent_type, "model": model})
         case _:
             return omit_none({"command": command, "file_path": file, "new_string": content, "old_string": old})
 
@@ -134,6 +139,8 @@ def mock_tool_event(
     offset: int | None = None,
     limit: int | None = None,
     agent_type: str | None = None,
+    model: str | None = None,
+    tool_input: dict[str, Any] | None = None,
     permission_mode: str | None = None,
     transcript: Session | None = None,
     transcript_path: str | Path | None = None,
@@ -143,7 +150,12 @@ def mock_tool_event(
     return cast(
         ToolHookEvent,
         event.event_class(
-            _raw={"tool_name": tool, "tool_input": make_tool_input(tool, command, file, content, old, offset, limit)}
+            _raw={
+                "tool_name": tool,
+                "tool_input": make_tool_input(
+                    tool, command, file, content, old, offset, limit, agent_type, model, tool_input
+                ),
+            }
             | ({"agent_type": agent_type} if agent_type else {})
             | ({"permission_mode": permission_mode} if permission_mode else {}),
             ctx=build_context(transcript, transcript_path, session_dir, project_root),
@@ -325,6 +337,8 @@ def input_to_event(
                 offset=inp.offset,
                 limit=inp.limit,
                 agent_type=inp.agent_type,
+                model=inp.model,
+                tool_input=inp.tool_input,
                 **ctx_kw,
             )
 

{capt_hook-4.3.1 → capt_hook-4.4.0}/captain_hook/testing/types.py

@@ -85,8 +85,12 @@ class Input:
         content: New file content for ``Edit``/``Write``.
         old: Pre-edit content for ``Edit`` and ``diff_lint``.
         tool: Tool name when no condition pins it.
+        tool_input: Verbatim raw tool-input mapping — an escape hatch that wins
+            over the input synthesized from the other fields.
         prompt: ``UserPromptSubmit`` text.
-        agent_type: Subagent type for subagent events.
+        agent_type: Subagent type for subagent events (an Agent/Task call's
+            ``subagent_type``).
+        model: Model for an Agent/Task call's ``model`` input field.
         reason: ``SessionEnd`` reason.
         permission_mode: Permission mode, e.g. ``"plan"`` for plan-mode gating.
         offset: ``Read`` call offset.
@@ -101,8 +105,10 @@ class Input:
     content: str | None = None
     old: str | None = None
     tool: str | None = None
+    tool_input: dict[str, Any] | None = None
     prompt: str | None = None
     agent_type: str | None = None
+    model: str | None = None
     reason: str | None = None
     permission_mode: str | None = None
     offset: int | None = None

{capt_hook-4.3.1 → capt_hook-4.4.0}/captain_hook/types.py

@@ -169,6 +169,46 @@ class Content:
     project_only: bool = True
 
 
+@dataclass(frozen=True, slots=True)
+class ToolInput:
+    """Condition matching one top-level field of the raw tool input against a regex.
+
+    Reads a single top-level key of the current event's tool input and searches its value with
+    ``re.MULTILINE``. Works for any tool; false for non-tool events, a missing field, or a
+    non-string value.
+
+    Example:
+        >>> hook(Event.PreToolUse, only_if=[ToolInput("model", r"(?i)\\bhaiku\\b")], message="...", block=True)
+    """
+
+    field: str
+    pattern: str
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowScript:
+    """Condition matching a ``Workflow`` tool's script source.
+
+    ``model`` matches the model names pinned in the script's ``agent()`` opts
+    (``model: 'haiku'`` and friends) — no hand-written quote-aware regex; ``pattern``
+    searches the raw script source (``re.MULTILINE``). Provide exactly one. The source is
+    the inline ``script``, or — when ``script`` is None and ``script_path`` points at a
+    file — that file's contents. A missing or unreadable path, or a file larger than
+    ~1 MiB, never matches and never raises. False for any non-Workflow tool.
+
+    Example:
+        >>> nudge("no haiku steps", only_if=[Tool("Workflow"), WorkflowScript(model="haiku")],
+        ...       events=Event.PreToolUse)
+    """
+
+    pattern: str | None = None
+    model: str | None = None
+
+    def __post_init__(self) -> None:
+        if (self.pattern is None) == (self.model is None):
+            raise ValueError("WorkflowScript takes exactly one of pattern or model")
+
+
 @dataclass(frozen=True, slots=True)
 class Pattern:
     """Condition matching the edit's new content against an ast-grep **structural** pattern.
@@ -379,6 +419,8 @@ TCondition = (
     | FilePath
     | Command
     | Content
+    | ToolInput
+    | WorkflowScript
     | Pattern
     | Agent
     | UsedSkill

{capt_hook-4.3.1 → capt_hook-4.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 = "4.3.1"
+version = "4.4.0"
 description = "Declarative hook framework for Claude Code"
 readme = "README.md"
 license = "PolyForm-Noncommercial-1.0.0"