capt-hook 0.2.0__py3-none-any.whl

captain_hook/events.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from functools import cached_property
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from captain_hook.file import File
+from captain_hook.transcript.inputs import (
+    AgentInput,
+    BashInput,
+    EditInput,
+    FileInputBase,
+    ToolInput,
+    WriteInput,
+    parse_tool_input,
+)
+from captain_hook.types import Event
+
+if TYPE_CHECKING:
+    from captain_hook.command import CommandLine as CommandLineType
+    from captain_hook.context import HookContext
+    from captain_hook.tasks import Tasks
+    from captain_hook.types import HookResult
+
+
+@dataclass
+class BaseHookEvent:
+    """Base class for all hook events, providing access to raw payload, context, and convenience methods."""
+
+    event_name: ClassVar[Event]
+
+    _raw: dict[str, Any]
+    ctx: HookContext
+
+    @property
+    def event(self) -> Event:
+        return self.event_name
+
+    @property
+    def is_subagent(self) -> bool:
+        return "agent_id" in self._raw
+
+    @property
+    def session_id(self) -> str:
+        return self._raw["session_id"]
+
+    @cached_property
+    def tasks(self) -> Tasks:
+        """The live task list for this session, read from Claude Code's native task store.
+
+        Unlike transcript-derived ``task_ops()``, this reflects updates made by
+        subagents, teammates, or resumed sessions, and is empty when the session
+        has no task store — it never falls back to another session's tasks.
+        """
+        from captain_hook.tasks import Tasks as T
+
+        return T.for_session(self.session_id)
+
+    @property
+    def user_prompt(self) -> str | None:
+        return self._raw.get("prompt")
+
+    @property
+    def stop_hook_active(self) -> bool:
+        return self._raw.get("stop_hook_active", False)
+
+    @property
+    def transcript_path(self) -> Path | None:
+        return Path(p) if (p := self._raw.get("transcript_path")) else None
+
+    @property
+    def permission_mode(self) -> str | None:
+        return self._raw.get("permission_mode")
+
+    @property
+    def parent_agent_type(self) -> str | None:
+        return self._raw.get("agent_type")
+
+    @property
+    def tool_name(self) -> str | None:
+        return None
+
+    @property
+    def _tool_input(self) -> dict[str, Any]:
+        return {}
+
+    @cached_property
+    def input(self) -> ToolInput:
+        return parse_tool_input(self.tool_name or "", self._tool_input)
+
+    @property
+    def command(self) -> str | None:
+        return self.input.command if isinstance(self.input, BashInput) else None
+
+    @cached_property
+    def command_line(self) -> CommandLineType | None:
+        return None
+
+    @property
+    def file(self) -> File | None:
+        return self.input.file if isinstance(self.input, FileInputBase) else None
+
+    @property
+    def content(self) -> str | None:
+        return None
+
+    @property
+    def old(self) -> str | None:
+        return None
+
+    @property
+    def agent_type(self) -> str | None:
+        return None
+
+    def command_matches(self, *patterns: str) -> bool:
+        return False
+
+    def file_matches(self, *globs: str) -> bool:
+        return False
+
+    def content_matches(self, pattern: str) -> bool:
+        return False
+
+    def allow(self) -> HookResult:
+        from captain_hook.types import Action
+        from captain_hook.types import HookResult as HR
+
+        return HR.of(Action.allow)
+
+    @staticmethod
+    def _render_part(part: str | tuple[str, object] | object) -> str:
+        match part:
+            case str():
+                return part
+            case (str() as label, value):
+                return f"{label}: " + json.dumps(value, default=str)
+            case _:
+                return json.dumps(part, default=str)
+
+    def warn(self, *parts: str | tuple[str, object] | object) -> HookResult:
+        r"""Emit a warning whose parts are auto-rendered and joined with newlines.
+
+        Each part is rendered by form: a plain ``str`` passes through verbatim; a
+        ``(label, value)`` tuple becomes ``"{label}: {json}"`` with ``value``
+        JSON-encoded; any other object is JSON-encoded directly. Rendered parts are
+        joined with ``"\n"``.
+
+        Args:
+            *parts: Warning fragments, each a ``str``, a ``(label, value)`` tuple, or
+                any JSON-serializable object.
+
+        Returns:
+            A warn :class:`HookResult` carrying the joined message.
+        """
+        from captain_hook.types import Action
+        from captain_hook.types import HookResult as HR
+
+        return HR.of(Action.warn, "\n".join(self._render_part(p) for p in parts))
+
+    def block(self, message: str) -> HookResult:
+        from captain_hook.types import Action
+        from captain_hook.types import HookResult as HR
+
+        return HR.of(Action.block, message)
+
+
+@dataclass
+class ToolHookEvent(BaseHookEvent):
+    """Event for tool-related hooks, adding tool name, input, command, and file access."""
+
+    @property
+    def tool_name(self) -> str | None:
+        return self._raw.get("tool_name")
+
+    @property
+    def _tool_input(self) -> dict[str, Any]:
+        return self._raw.get("tool_input", {})
+
+    @cached_property
+    def command_line(self) -> CommandLineType | None:
+        from captain_hook.command import CommandLine
+
+        return CommandLine.parse(cmd) if (cmd := self.command) else None
+
+    @property
+    def content(self) -> str | None:
+        match self.input:
+            case EditInput(new=new):
+                return new
+            case WriteInput(content=c):
+                return c
+            case _:
+                return None
+
+    @property
+    def old(self) -> str | None:
+        return self.input.old if isinstance(self.input, EditInput) else None
+
+    @property
+    def agent_type(self) -> str | None:
+        return ti.agent_type if isinstance(ti := self.input, AgentInput) else None
+
+    def command_matches(self, *patterns: str) -> bool:
+        if not (cl := self.command_line):
+            return False
+        return any(cl.primary.matches(p) for p in patterns)
+
+    def file_matches(self, *globs: str) -> bool:
+        return bool(self.file) and self.file.matches(*globs)
+
+    def content_matches(self, pattern: str) -> bool:
+        return bool(self.content) and bool(re.search(pattern, self.content, re.MULTILINE))
+
+
+@dataclass
+class PreToolUseEvent(ToolHookEvent):
+    """Fires before a tool is executed. Return a block result to prevent execution."""
+
+    event_name: ClassVar[Event] = Event.PreToolUse
+
+
+@dataclass
+class PostToolUseEvent(ToolHookEvent):
+    """Fires after a tool completes successfully, with access to the tool response."""
+
+    event_name: ClassVar[Event] = Event.PostToolUse
+
+    @property
+    def tool_response(self) -> str | None:
+        return self._raw.get("tool_response")
+
+
+@dataclass
+class PostToolUseFailureEvent(ToolHookEvent):
+    """Fires after a tool fails, providing the error message and interrupt status."""
+
+    event_name: ClassVar[Event] = Event.PostToolUseFailure
+
+    @property
+    def error(self) -> str:
+        return self._raw["error"]
+
+    @property
+    def is_interrupt(self) -> bool:
+        return self._raw.get("is_interrupt", False)
+
+
+@dataclass
+class UserPromptSubmitEvent(BaseHookEvent):
+    """Fires when the user submits a prompt, before the agent processes it."""
+
+    event_name: ClassVar[Event] = Event.UserPromptSubmit
+
+
+@dataclass
+class StopEvent(BaseHookEvent):
+    """Fires when the agent is about to stop. Return a block result to prevent stopping."""
+
+    event_name: ClassVar[Event] = Event.Stop
+
+
+@dataclass
+class SubagentStopEvent(BaseHookEvent):
+    """Fires when a subagent finishes. Provides ``agent_type`` for filtering."""
+
+    event_name: ClassVar[Event] = Event.SubagentStop
+
+    @property
+    def agent_type(self) -> str | None:
+        return self._raw.get("agent_type") or self._raw.get("tool_input", {}).get("subagent_type")
+
+
+@dataclass
+class SubagentStartEvent(BaseHookEvent):
+    """Fires when a subagent is launched. Provides ``agent_type`` for filtering."""
+
+    event_name: ClassVar[Event] = Event.SubagentStart
+
+    @property
+    def agent_type(self) -> str | None:
+        return self._raw.get("agent_type") or self._raw.get("tool_input", {}).get("subagent_type")
+
+
+@dataclass
+class PreCompactEvent(BaseHookEvent):
+    """Fires before context compaction, providing the trigger and custom instructions."""
+
+    event_name: ClassVar[Event] = Event.PreCompact
+
+    @property
+    def trigger(self) -> str | None:
+        return self._raw.get("trigger")
+
+    @property
+    def custom_instructions(self) -> str | None:
+        return self._raw.get("custom_instructions")
+
+
+@dataclass
+class NotificationEvent(BaseHookEvent):
+    """Fires on system notifications, providing message, title, and notification type."""
+
+    event_name: ClassVar[Event] = Event.Notification
+
+    @property
+    def message(self) -> str | None:
+        return self._raw.get("message")
+
+    @property
+    def title(self) -> str | None:
+        return self._raw.get("title")
+
+    @property
+    def notification_type(self) -> str | None:
+        return self._raw.get("notification_type")

captain_hook/file.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from fnmatch import fnmatch
+from functools import cached_property
+from pathlib import Path
+from typing import Any, ClassVar
+
+
+@dataclass(frozen=True, kw_only=True)
+class File:
+    """A file path wrapper with glob matching, prefix checks, and test-file detection.
+
+    Delegates ``Path`` methods via ``__getattr__`` so ``.suffix``, ``.name``,
+    ``.parent``, ``.exists()`` etc. work directly.
+    """
+
+    path: Path
+
+    TEST_PATTERNS: ClassVar[list[str]] = ["**/test_*.py", "**/conftest.py", "**/tests/**/*.py"]
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.path, name)
+
+    def __str__(self) -> str:
+        return str(self.path)
+
+    def __fspath__(self) -> str:
+        return str(self.path)
+
+    def __eq__(self, other: object) -> bool:
+        match other:
+            case File(path=p):
+                return self.path == p
+            case Path():
+                return self.path == other
+            case _:
+                return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(self.path)
+
+    @cached_property
+    def is_test(self) -> bool:
+        return self.matches(*self.TEST_PATTERNS)
+
+    def matches(self, *patterns: str) -> bool:
+        s, name = str(self.path), self.path.name
+        return any(fnmatch(s, p) or fnmatch(name, p) for p in patterns)
+
+    def under(self, *prefixes: str) -> bool:
+        s = str(self.path)
+        return any(s.startswith(p) or f"/{p}" in s for p in prefixes)
+
+    def exists(self) -> bool:
+        return self.path.exists()
+
+    def read_text(self) -> str:
+        return self.path.read_text()
+
+    def contains(self, pattern: str) -> bool:
+        try:
+            return bool(re.search(pattern, self.read_text()))
+        except (OSError, UnicodeDecodeError):
+            return False
+
+
+@dataclass(frozen=True, kw_only=True)
+class PathMatcher:
+    """A reusable set of glob patterns for matching file paths. Supports ``in`` operator."""
+
+    patterns: list[str]
+
+    def matches(self, path: str | Path | File) -> bool:
+        match path:
+            case File():
+                return path.matches(*self.patterns)
+            case _:
+                return File(path=Path(path)).matches(*self.patterns)
+
+    def __contains__(self, path: str | Path | File) -> bool:
+        return self.matches(path)
+
+
+def categorize_files(
+    paths: Iterable[str | Path], *, lang: str = "py"
+) -> tuple[list[str], list[str], list[str]]:
+    """Split paths into source, test, and skipped buckets for a language.
+
+    A path that does not match the ``lang`` globs is skipped; otherwise it is
+    classified as a test file (via :attr:`File.is_test`, which treats ``conftest.py``
+    and anything under a ``tests/`` directory as tests) or as source.
+
+    Args:
+        paths: File paths to categorize; blank entries are ignored.
+        lang: Language key into ``LANG_GLOBS`` (defaults to ``"py"``); unknown keys
+            fall back to ``*.<lang>``.
+
+    Returns:
+        A ``(source, test, skipped)`` tuple, each a sorted, de-duplicated list of
+        path strings.
+    """
+    from captain_hook.types import LANG_GLOBS
+
+    matcher = PathMatcher(patterns=list(LANG_GLOBS.get(lang, (f"*.{lang}",))))
+    source: set[str] = set()
+    test: set[str] = set()
+    skipped: set[str] = set()
+    for raw in paths:
+        if not (p := str(raw).strip()):
+            continue
+        if (f := File(path=Path(p))) not in matcher:
+            skipped.add(p)
+        elif f.is_test:
+            test.add(p)
+        else:
+            source.add(p)
+    return sorted(source), sorted(test), sorted(skipped)

captain_hook/llm/__init__.py

@@ -0,0 +1,9 @@
+"""LLM backend abstractions for captain-hook's ``call_llm`` helper."""
+from __future__ import annotations
+
+from captain_hook.llm.backends import ClaudeBackend as ClaudeBackend
+from captain_hook.llm.backends import CodexBackend as CodexBackend
+from captain_hook.llm.backends import LlmBackend as LlmBackend
+from captain_hook.llm.backends import LlmBackends as LlmBackends
+from captain_hook.llm.backends import TModel as TModel
+from captain_hook.llm.backends import TSpecialty as TSpecialty

captain_hook/llm/backends.py

@@ -0,0 +1,152 @@
+"""LLM CLI backends for :func:`HookContext.call_llm`.
+
+Each backend maps the framework's abstract :data:`TModel` sizes to provider
+model names and knows how to build the CLI invocation and parse its response.
+"""
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar, Literal, cast
+
+from pydantic import BaseModel
+
+TSpecialty = Literal["debugging", "review", "general"]
+TModel = Literal["small", "medium", "large"]
+
+
+class LlmBackend(ABC):
+    """Abstract interface for an LLM CLI backend.
+
+    Concrete backends map abstract :data:`TModel` sizes to provider-specific
+    model names and encapsulate how to invoke the provider's CLI and parse the
+    raw response.
+
+    Attributes:
+        models: Mapping from abstract model size to the provider's model name.
+    """
+
+    models: ClassVar[dict[TModel, str]]
+
+    @abstractmethod
+    def build_command(self, model: str, schema_path: str | None, agent: bool) -> list[str]:
+        """Build the CLI argv for a single LLM invocation.
+
+        Args:
+            model: Provider-specific model name.
+            schema_path: Path to a JSON schema for structured output, or ``None``.
+            agent: Whether the invocation may use tools / agent capabilities.
+
+        Returns:
+            The argv list to execute.
+        """
+
+    @abstractmethod
+    def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
+        """Parse raw CLI stdout into text or a validated model.
+
+        Args:
+            raw: Raw stdout from the backend CLI.
+            response_model: Model to validate against, or ``None`` for raw text.
+
+        Returns:
+            ``raw`` when ``response_model`` is ``None``, else a validated instance.
+        """
+
+    @abstractmethod
+    def env(self) -> dict[str, str]:
+        """Return extra environment variables to set for the CLI invocation."""
+
+
+class CodexBackend(LlmBackend):
+    """:class:`LlmBackend` for the OpenAI ``codex`` CLI."""
+
+    models: ClassVar[dict[TModel, str]] = {
+        "small": "gpt-5.3-codex-spark",
+        "medium": "gpt-5.4-mini",
+        "large": "gpt-5.5",
+    }
+
+    def build_command(self, model: str, schema_path: str | None, agent: bool) -> list[str]:
+        return [
+            "codex",
+            "exec",
+            "--ephemeral",
+            "--sandbox",
+            "read-only",
+            "--model",
+            model,
+            *([] if agent else ["-c", "features.codex_hooks=false", "-c", "features.mcp_servers=false"]),
+            *(["--output-schema", schema_path] if schema_path else []),
+        ]
+
+    def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
+        return raw if not response_model else response_model.model_validate_json(raw)
+
+    def env(self) -> dict[str, str]:
+        return {}
+
+
+class ClaudeBackend(LlmBackend):
+    """:class:`LlmBackend` for the Anthropic ``claude`` CLI."""
+
+    models: ClassVar[dict[TModel, str]] = {
+        "small": "haiku",
+        "medium": "sonnet",
+        "large": "opus",
+    }
+
+    def build_command(self, model: str, schema_path: str | None, agent: bool) -> list[str]:
+        return [
+            "claude",
+            "-p",
+            "--no-session-persistence",
+            "--model",
+            model,
+            *(
+                ["--permission-mode", "auto", "--max-budget-usd", "1"]
+                if agent
+                else [
+                    "--system-prompt", "",
+                    "--setting-sources", "",
+                    "--strict-mcp-config",
+                ]
+            ),
+            *(["--json-schema", schema_path, "--output-format", "json"] if schema_path else []),
+        ]
+
+    def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
+        if not response_model:
+            return raw
+        data: Any = json.loads(raw)
+        if isinstance(data, list) and data:
+            return self.extract_structured(
+                cast(list[dict[str, Any]], data), response_model
+            ) or response_model.model_validate_json(raw)
+        return response_model.model_validate_json(raw)
+
+    @staticmethod
+    def extract_structured(events: list[dict[str, Any]], model: type[BaseModel]) -> BaseModel | None:
+        """Return the validated ``structured_output`` from a stream-json event list, if present."""
+        for e in events:
+            if e.get("type") == "result" and "structured_output" in e:
+                return model.model_validate(e["structured_output"])
+        return None
+
+    def env(self) -> dict[str, str]:
+        return {"CLAUDE_CODE_SIMPLE": "1"}
+
+
+class LlmBackends:
+    """Registry mapping each :data:`TSpecialty` to the :class:`LlmBackend` that serves it."""
+
+    LLM_BACKENDS: ClassVar[dict[TSpecialty, LlmBackend]] = {
+        "debugging": CodexBackend(),
+        "review": CodexBackend(),
+        "general": ClaudeBackend(),
+    }
+
+    @classmethod
+    def for_specialty(cls, specialty: TSpecialty) -> LlmBackend:
+        """Return the backend registered for ``specialty``."""
+        return cls.LLM_BACKENDS[specialty]

captain_hook/loader.py

@@ -0,0 +1,62 @@
+"""Hook discovery: imports a hooks package, loads its ``conf`` module, and registers every hook module."""
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import pkgutil
+import sys
+from pathlib import Path
+from types import ModuleType
+
+from pydantic_settings import BaseSettings
+
+from captain_hook.app import State, _state
+
+CONF_MODULE = "conf"
+
+
+def build_hook_settings(module: ModuleType) -> BaseSettings | ModuleType:
+    if importlib.util.find_spec("captain_hook.settings"):
+        settings_mod = importlib.import_module("captain_hook.settings")
+        return settings_mod.build_settings(module)
+    return module
+
+
+def import_or_reload(fqn: str, fresh_this_pass: set[str]) -> ModuleType:
+    if fqn in fresh_this_pass:
+        return sys.modules[fqn]
+    before = set(sys.modules)
+    if fqn in sys.modules:
+        mod = importlib.reload(sys.modules[fqn])
+    else:
+        mod = importlib.import_module(fqn)
+    fresh_this_pass.update(set(sys.modules) - before)
+    fresh_this_pass.add(fqn)
+    return mod
+
+
+def discover_hooks(hooks_dir: str | Path, state: State | None = None) -> None:
+    target = state or _state
+    hooks_path = Path(hooks_dir).resolve()
+    if str(hooks_path.parent) not in sys.path:
+        sys.path.insert(0, str(hooks_path.parent))
+
+    pkg = hooks_path.name
+    fresh_this_pass: set[str] = set()
+
+    top_level = {info.name for info in pkgutil.iter_modules([str(hooks_path)]) if not info.name.startswith("_")}
+
+    if CONF_MODULE in top_level:
+        conf_module = import_or_reload(f"{pkg}.{CONF_MODULE}", fresh_this_pass)
+        target.settings = build_hook_settings(conf_module)
+        if classifier := getattr(conf_module, "classifier", None):
+            target.classifier = classifier
+
+    all_modules = {
+        info.name
+        for info in pkgutil.walk_packages([str(hooks_path)], prefix=f"{pkg}.")
+        if not info.name.rpartition(".")[2].startswith("_")
+    }
+
+    for fqn in sorted(all_modules - {f"{pkg}.{CONF_MODULE}"}):
+        import_or_reload(fqn, fresh_this_pass)