capt-hook 0.2.0__py3-none-any.whl

captain_hook/conditions.py

@@ -0,0 +1,136 @@
+"""Condition evaluation: checks ``TCondition`` instances against the current event."""
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from captain_hook.types import (
+    Agent,
+    Command,
+    Content,
+    CustomCondition,
+    FilePath,
+    InPlanMode,
+    Or,
+    RanCommand,
+    ReadFile,
+    SourceEdits,
+    TCondition,
+    TestFile,
+    Tool,
+    TouchedFile,
+    UsedSkill,
+    Waiting,
+    tool_name_matches,
+)
+
+if TYPE_CHECKING:
+    from captain_hook.events import BaseHookEvent
+    from captain_hook.transcript import Transcript
+    from captain_hook.transcript.models import ToolUse
+    from captain_hook.types import HookSpec
+
+
+def has_completion_notification(t: Transcript, tool_use_id: str, after_idx: int) -> bool:
+    return any(
+        (n := m.notification) and n.tool_use_id == tool_use_id
+        for m in t.messages[after_idx + 1 :]
+    )
+
+
+def waiting_tool_names(evt: BaseHookEvent) -> set[str]:
+    from captain_hook.settings import DEFAULT_WAITING_TOOLS
+
+    custom: object = getattr(evt.ctx.settings, "waiting_tools", None)
+    return {str(x) for x in custom} if isinstance(custom, list) else set(DEFAULT_WAITING_TOOLS)
+
+
+def tool_use_waiting(tu: ToolUse, t: Transcript, waiting_names: set[str]) -> bool:
+    if tu.name in waiting_names:
+        return True
+    match tu.name:
+        case "Agent" | "Task" | "Bash" if tu.raw_input.get("run_in_background"):
+            return True
+        case "Agent" | "Task" if "subagent_type" not in tu.raw_input:
+            return True
+        case "Agent" | "Task" if tu.result and tu.result.is_async:
+            return not has_completion_notification(t, tu.id, tu.message_index)
+        case "Workflow":
+            return not has_completion_notification(t, tu.id, tu.message_index)
+    return False
+
+
+def is_waiting(evt: BaseHookEvent) -> bool:
+    if not (t := evt.ctx.transcript):
+        return False
+    waiting_names = waiting_tool_names(evt)
+    return any(tool_use_waiting(tu, t.current_turn, waiting_names) for tu in t.current_turn.tool_uses)
+
+
+def is_project_file(evt: BaseHookEvent) -> bool:
+    if not (file := evt.file):
+        return False
+    if not file.path.is_absolute():
+        return True
+    if not (root := evt.ctx.repo_root):
+        return True
+    return file.path.resolve().is_relative_to(root.resolve())
+
+
+def check_condition(c: TCondition, evt: BaseHookEvent) -> bool:
+    match c:
+        case Tool(pattern):
+            if not evt.tool_name:
+                return False
+            return any(tool_name_matches(evt.tool_name, p) for p in pattern.split("|"))
+        case FilePath(patterns, project_only):
+            return bool(evt.file and (not project_only or is_project_file(evt)) and evt.file.matches(*patterns))
+        case Command(pattern):
+            return bool((cl := evt.command_line) and any(re.search(pattern, str(cmd)) for cmd in cl.commands))
+        case Content(pattern, project_only):
+            return bool(
+                (not project_only or is_project_file(evt))
+                and evt.content
+                and re.search(pattern, evt.content, re.MULTILINE)
+            )
+        case Agent(name):
+            return bool(evt.agent_type) and evt.agent_type in name.split("|")
+        case TestFile(project_only):
+            return bool(evt.file and (not project_only or is_project_file(evt)) and evt.file.is_test)
+        case SourceEdits(lang, include_tests, paths):
+            return bool(
+                evt.tool_name
+                and any(tool_name_matches(evt.tool_name, n) for n in ("Edit", "Write"))
+                and (f := evt.file)
+                and f.matches(*SourceEdits(lang=lang).globs)
+                and (include_tests or not f.is_test)
+                and (paths is None or f.matches(paths))
+            )
+        case UsedSkill(name, subagents):
+            return bool(evt.ctx.transcript) and evt.ctx.transcript.has_skill(*name.split("|"), subagents=subagents)
+        case ReadFile(patterns, subagents):
+            return bool(evt.ctx.transcript) and any(evt.ctx.transcript.has_read(p, subagents=subagents) for p in patterns)
+        case TouchedFile(patterns, subagents):
+            return bool(evt.ctx.transcript) and evt.ctx.transcript.has_edit_to(*patterns, subagents=subagents)
+        case RanCommand(pattern, subagents):
+            return bool(evt.ctx.transcript) and evt.ctx.transcript.has_command(pattern, subagents=subagents)
+        case InPlanMode():
+            return evt.permission_mode == "plan" or (
+                bool(t := evt.ctx.transcript)
+                and t.count_tools("EnterPlanMode") > t.count_tools("ExitPlanMode")
+            )
+        case Waiting():
+            return is_waiting(evt)
+        case Or(conditions):
+            return any(check_condition(sub, evt) for sub in conditions)
+        case CustomCondition():
+            return c.check(evt)
+    return False
+
+
+def matches_conditions(spec: HookSpec, evt: BaseHookEvent) -> bool:
+    if any(not check_condition(c, evt) for c in spec.only_if):
+        return False
+    if any(check_condition(c, evt) for c in spec.skip_if):
+        return False
+    return True

captain_hook/context.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from functools import cached_property
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+from pydantic_settings import BaseSettings
+
+from captain_hook.llm import CodexBackend, LlmBackend, LlmBackends, TModel, TSpecialty
+from captain_hook.prompt import PromptMessage
+from captain_hook.session import SessionStore
+
+if TYPE_CHECKING:
+    from captain_hook.transcript import Transcript, TranscriptSlice, Turn
+
+
+@dataclass
+class HookContext:
+    """Runtime context injected into every hook event, providing session state, transcript, settings, and LLM/CLI helpers."""
+
+    session: SessionStore
+    transcript: Transcript
+    settings: BaseSettings | None
+    project_root: Path | None = None
+
+    @property
+    def t(self) -> Transcript:
+        """Alias for ``transcript``."""
+        return self.transcript
+
+    @property
+    def s(self) -> SessionStore:
+        """Alias for ``session``."""
+        return self.session
+
+    @property
+    def state(self) -> SessionStore:
+        """Alias for ``session``."""
+        return self.session
+
+    @property
+    def conf(self) -> BaseSettings | None:
+        """Alias for ``settings``."""
+        return self.settings
+
+    @property
+    def c(self) -> BaseSettings | None:
+        """Alias for ``settings`` (shortest form)."""
+        return self.conf
+
+    @cached_property
+    def turn(self) -> Turn:
+        """The current transcript turn (cached)."""
+        return self.transcript.current_turn
+
+    @cached_property
+    def prior(self) -> TranscriptSlice:
+        """Transcript slice before the current turn (cached)."""
+        return self.transcript.prior()
+
+    def call_cli(
+        self,
+        args: list[str],
+        *,
+        input: str | None = None,
+        timeout: int = 30,
+        env: dict[str, str] | None = None,
+    ) -> str:
+        result = subprocess.run(
+            args,
+            input=input,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=os.environ | (env or {}),
+            cwd=os.environ.get("CLAUDE_PROJECT_DIR") or os.environ.get("FACTORY_PROJECT_DIR"),
+        )
+        if result.returncode != 0:
+            err = subprocess.CalledProcessError(
+                result.returncode,
+                args,
+                output=result.stdout,
+                stderr=result.stderr,
+            )
+            err.add_note(f"argv: {args}")
+            err.add_note(f"exit_code: {result.returncode}")
+            err.add_note(f"stderr: {result.stderr[-4096:]}")
+            err.add_note(f"stdout: {result.stdout[-4096:]}")
+            raise err
+        return result.stdout
+
+    def git(self, *args: str) -> str | None:
+        try:
+            return self.call_cli(["git", *args], timeout=5)
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return None
+
+    @cached_property
+    def changed_paths(self) -> frozenset[Path] | None:
+        if (out := self.git("diff", "--name-only", "HEAD", "--no-renames")) is None or (root := self.repo_root) is None:
+            return None
+        return frozenset((root / line).resolve() for line in out.splitlines() if line)
+
+    @cached_property
+    def repo_root(self) -> Path | None:
+        if self.project_root is not None:
+            return self.project_root.resolve()
+        return Path(out.strip()) if (out := self.git("rev-parse", "--show-toplevel")) else None
+
+    @cached_property
+    def current_branch(self) -> str | None:
+        return out.strip() if (out := self.git("symbolic-ref", "--short", "HEAD")) else None
+
+    def call_llm(
+        self,
+        template: str | PromptMessage,
+        *args: Any,
+        specialty: TSpecialty = "general",
+        model: TModel = "small",
+        timeout: int = 180,
+        transcript: bool = False,
+        agent: bool = False,
+        response_model: type[BaseModel] | None = None,
+        **kwargs: Any,
+    ) -> str | BaseModel:
+        if isinstance(template, PromptMessage):
+            prompt = str(template)
+            if transcript:
+                prompt = f"{self.transcript}\n\n<task>\n{prompt}\n</task>"
+        else:
+            if transcript:
+                template = f"{{transcript}}\n\n<task>\n{template}\n</task>"
+            prompt = template.format(*args, **kwargs, transcript=self.transcript)
+        schema = (
+            json.dumps(response_model.model_json_schema() | {"additionalProperties": False})
+            if response_model
+            else None
+        )
+        backend = LlmBackends.for_specialty(specialty)
+        schema_path = self.resolve_schema_path(backend, schema)
+
+        cmd = backend.build_command(backend.models[model], schema_path, agent)
+        raw = self.call_cli(cmd, input=prompt, timeout=timeout, env=backend.env())
+        return backend.parse_response(raw, response_model)
+
+    @staticmethod
+    def resolve_schema_path(backend: LlmBackend, schema: str | None) -> str | None:
+        if not schema:
+            return None
+        if isinstance(backend, CodexBackend):
+            fd, path = tempfile.mkstemp(suffix=".json")
+            os.write(fd, schema.encode())
+            os.close(fd)
+            return path
+        return schema

captain_hook/dispatch.py

@@ -0,0 +1,107 @@
+"""Hook dispatch: select matching hooks, run their handlers, and translate ``HookResult`` into the Claude Code stdout envelope."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+from captain_hook.app import get_matching_hooks
+from captain_hook.session import SessionStore
+from captain_hook.state import HookState
+from captain_hook.types import Action, Event, HookResult, HookSpec, RegisteredHook
+
+if TYPE_CHECKING:
+    from captain_hook.events import BaseHookEvent
+
+
+def run_declarative(spec: HookSpec, evt: BaseHookEvent) -> HookResult | None:
+    return (
+        HookResult(action=Action.block if spec.block else Action.warn, message=spec.message) if spec.message else None
+    )
+
+
+def execute_hook(
+    entry: RegisteredHook,
+    evt: BaseHookEvent,
+    session_dir: Path | None = None,
+) -> HookResult | None:
+    """Execute a single registered hook, respecting ``max_fires`` and persisting fire count."""
+    hook_session_dir = (session_dir / entry.name) if session_dir else None
+    if hook_session_dir:
+        hook_session_dir.mkdir(parents=True, exist_ok=True)
+
+    store = SessionStore(hook_session_dir)
+    hook_state = store[HookState].get(HookState())
+
+    if entry.spec.max_fires is not None and hook_state.fire_count >= entry.spec.max_fires:
+        return None
+
+    try:
+        result = entry.handler(evt) if entry.handler else run_declarative(entry.spec, evt)
+    except Exception:
+        logger.bind(hook=entry.name).exception("hook handler failed")
+        return None
+
+    if result:
+        hook_state.fire_count += 1
+        store[HookState].set(hook_state)
+
+    return result
+
+
+def format_output(event: Event, result: HookResult) -> dict[str, Any] | None:
+    """Render a ``HookResult`` as the JSON envelope Claude Code expects on stdout for *event*."""
+    if event in (Event.Stop | Event.SubagentStop):
+        return {"decision": "block", "reason": result.message} if result.action is not Action.allow else None
+
+    match result.action:
+        case Action.block:
+            return {
+                "hookSpecificOutput": {
+                    "hookEventName": event.name,
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": result.message,
+                }
+            }
+        case Action.warn:
+            return {
+                "hookSpecificOutput": {
+                    "hookEventName": event.name,
+                    "additionalContext": result.message,
+                    **({"permissionDecision": "allow"} if event is Event.PreToolUse else {}),
+                }
+            }
+        case Action.allow:
+            return {
+                "hookSpecificOutput": {
+                    "hookEventName": event.name,
+                    "permissionDecision": "allow",
+                }
+            }
+
+
+def dispatch(
+    event: Event,
+    evt: BaseHookEvent,
+    session_dir: Path | None = None,
+    *,
+    async_: bool = False,
+) -> dict[str, Any] | None:
+    """Dispatch an event to all matching hooks and return the combined result."""
+    matching = [h for h in get_matching_hooks(evt) if h.spec.async_ == async_]
+
+    warns: list[str] = []
+    for entry in matching:
+        match execute_hook(entry, evt, session_dir):
+            case HookResult(action=Action.block | Action.allow) as r:
+                return format_output(event, r)
+            case HookResult(action=Action.warn, message=msg) if msg:
+                warns.append(msg)
+            case _:
+                pass
+
+    if warns:
+        return format_output(event, HookResult(action=Action.warn, message="\n\n".join(warns)))
+
+    return None