claude-code-capabilities 0.1.2__py3-none-any.whl

capdisc/discovery.py

@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from pydantic import TypeAdapter, ValidationError
+
+from .base import InputModel
+from .catalog import (
+    CATALOG_ID_MAX,
+    BuiltinTool,
+    Catalog,
+    CatalogMcpServer,
+    CatalogSkill,
+    CatalogTool,
+    SkillRef,
+    catalog_id,
+)
+from .frontmatter import read_frontmatter
+from .scope import ArtifactKind, ScopeInventory, ScopeRoots
+
+_SKILL_REF: TypeAdapter[SkillRef] = TypeAdapter(SkillRef)  # one place a skill name becomes a ref
+_DESCRIPTION_SCAN_MAX = 800
+
+# The built-in Claude Code tools any subagent may be granted. read_only / needs_network
+# record each tool's real behaviour as catalog metadata (surfaced in the inventory report).
+BUILTIN_TOOLS: list[CatalogTool] = [
+    CatalogTool(
+        id="builtin.read",
+        ref=BuiltinTool.read.value,
+        description="Read a file from the filesystem.",
+        tags=["file", "files", "read", "open", "load", "view", "contents"],
+        read_only=True,
+    ),
+    CatalogTool(
+        id="builtin.write",
+        ref=BuiltinTool.write.value,
+        description="Write or overwrite a file on the filesystem.",
+        tags=["file", "files", "write", "create", "generate", "save", "output", "produce"],
+        read_only=False,
+    ),
+    CatalogTool(
+        id="builtin.edit",
+        ref=BuiltinTool.edit.value,
+        description="Edit a file by replacing an exact string.",
+        tags=["file", "files", "edit", "modify", "change", "replace", "update", "line"],
+        read_only=False,
+    ),
+    CatalogTool(
+        id="builtin.glob",
+        ref=BuiltinTool.glob.value,
+        description="Find files by glob pattern.",
+        tags=["file", "files", "find", "search", "glob", "pattern", "match", "locate"],
+        read_only=True,
+    ),
+    CatalogTool(
+        id="builtin.grep",
+        ref=BuiltinTool.grep.value,
+        description="Search file contents with a regular expression.",
+        tags=["search", "grep", "find", "pattern", "regex", "contents", "match", "code"],
+        read_only=True,
+    ),
+    CatalogTool(
+        id="builtin.bash",
+        ref=BuiltinTool.bash.value,
+        description="Run a shell command in the workspace.",
+        tags=["shell", "run", "execute", "command", "build", "script", "terminal"],
+        read_only=False,
+    ),
+    CatalogTool(
+        id="builtin.web_fetch",
+        ref=BuiltinTool.web_fetch.value,
+        description="Fetch and read a web page over the network.",
+        tags=["web", "fetch", "network", "url", "page", "download", "http"],
+        read_only=True,
+        needs_network=True,
+    ),
+    CatalogTool(
+        id="builtin.web_search",
+        ref=BuiltinTool.web_search.value,
+        description="Search the web and read result snippets.",
+        tags=["web", "search", "network", "query", "results", "internet"],
+        read_only=True,
+        needs_network=True,
+    ),
+    CatalogTool(
+        id="builtin.task",
+        ref=BuiltinTool.task.value,
+        description="Spawn a subagent to handle a delegated task.",
+        tags=["agent", "delegate", "subagent", "spawn", "task"],
+        read_only=False,
+    ),
+]
+
+
+class _SkillFrontmatter(InputModel):
+    name: str | None = None
+    description: str | None = None
+    tags: list[str] = []
+
+
+def _parse_frontmatter(text: str) -> _SkillFrontmatter | None:
+    """Parse a SKILL.md's YAML frontmatter into its typed fields.
+
+    Args:
+        text: The full SKILL.md body, frontmatter and all.
+
+    Returns:
+        The parsed frontmatter, or None when there is no frontmatter or it doesn't validate.
+    """
+    data = read_frontmatter(text)
+    if data is None:
+        return None
+    try:
+        return _SkillFrontmatter.model_validate(data)
+    except ValidationError:
+        return None
+
+
+def _disambiguated_ids(ref: str, count: int) -> list[str]:
+    """Mint `count` distinct ids for skills sharing `ref`: the bare id, then `-2`, `-3`, ….
+
+    Args:
+        ref: The skill ref the ids are minted for.
+        count: How many colliding skills share this ref.
+
+    Returns:
+        `count` distinct ids, in the order a caller's own content-sorted list should be assigned
+        them — this function only mints the id strings; which skill gets which is the caller's
+        choice. The base is trimmed so each suffix survives the id length cap; if that trim
+        happens to reproduce an id already minted (the base's own tail already reads e.g. "-2"),
+        one more character is trimmed until the candidate is unique.
+    """
+    base = catalog_id("skill", ref)
+    ids = [base]
+    seen = {base}
+    for suffix in range(2, count + 1):
+        tail = f"-{suffix}"
+        trim = len(tail)
+        candidate = base[: CATALOG_ID_MAX - trim] + tail
+        while candidate in seen and trim < len(base):
+            trim += 1
+            candidate = base[: CATALOG_ID_MAX - trim] + tail
+        seen.add(candidate)
+        ids.append(candidate)
+    return ids
+
+
+def skill_ref(skill_md: Path) -> SkillRef | None:
+    """Resolve the `SkillRef` a SKILL.md file declares.
+
+    Shared by the skill index and plugin discovery so a plugin's declared skill refs match the
+    refs of the indexed skills they point at — both go through the same `SkillRef` normalization.
+
+    Args:
+        skill_md: Path to a `SKILL.md` file; read with errors ignored.
+
+    Returns:
+        The ref from the frontmatter `name` (falling back to the parent dir name), or None when
+        the file is unreadable, lacks a usable description, or the name won't normalize.
+    """
+    try:
+        text = skill_md.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return None
+    frontmatter = _parse_frontmatter(text)
+    if frontmatter is None or not frontmatter.description:
+        return None
+    try:
+        return _SKILL_REF.validate_python(frontmatter.name or skill_md.parent.name)
+    except ValidationError:
+        return None
+
+
+def _card(skill_id: str, ref: str, frontmatter: _SkillFrontmatter) -> CatalogSkill | None:
+    """Assemble one `CatalogSkill` from a skill's id, ref, and parsed frontmatter.
+
+    Args:
+        skill_id: The unique catalog id minted for this skill.
+        ref: The skill's normalized ref.
+        frontmatter: Its parsed frontmatter; the description is truncated to the scan cap and
+            an absent one becomes empty.
+
+    Returns:
+        The card, or None if the fields don't validate.
+    """
+    try:
+        return CatalogSkill(
+            id=skill_id,
+            ref=ref,
+            description=(frontmatter.description or "")[:_DESCRIPTION_SCAN_MAX],
+            tags=frontmatter.tags,
+        )
+    except ValidationError:
+        return None
+
+
+def scan_indexed_skills(roots: ScopeRoots) -> list[tuple[CatalogSkill, Path]]:
+    """Index every SKILL.md the scope inventory captures under `roots` into `(card, path)` pairs.
+
+    The inventory owns where skills live (project walk-up, user, managed, plugin, nested); this
+    classifies each capture — parsing its contents, deduping a skill cached across locations by
+    (name, description), and disambiguating colliding ids.
+
+    Args:
+        roots: The scope roots to scan; passed straight to `ScopeInventory.scan`.
+
+    Returns:
+        One `(card, path)` per distinct skill — a stable id and the path to load its body —
+        skipping captures with no description and dropping later duplicates of a (name,
+        description) already seen.
+    """
+    seen: set[tuple[str, str]] = set()
+    by_ref: dict[str, list[tuple[_SkillFrontmatter, Path]]] = {}
+    for captured in ScopeInventory.scan(roots).artifacts:
+        if captured.kind is not ArtifactKind.skill:
+            continue
+        frontmatter = _parse_frontmatter(captured.contents)
+        if frontmatter is None or not frontmatter.description:
+            continue
+        name = frontmatter.name or captured.path.parent.name
+        key = (name, frontmatter.description)
+        if key in seen:
+            continue
+        try:
+            ref = _SKILL_REF.validate_python(name)
+        except ValidationError:
+            continue
+        seen.add(key)
+        by_ref.setdefault(ref, []).append((frontmatter, captured.path))
+
+    indexed: list[tuple[CatalogSkill, Path]] = []
+    for ref, entries in by_ref.items():
+        # sorted by content, never by scan order — the id a colliding skill gets must depend
+        # only on which skills exist, not on which scope root or filesystem order happened to
+        # surface it first; otherwise a consumer that persisted the id could silently resolve
+        # to a different skill after an unrelated scan-root change.
+        ordered = sorted(entries, key=lambda item: (item[0].description or "", str(item[1])))
+        for skill_id, (frontmatter, path) in zip(
+            _disambiguated_ids(ref, len(ordered)), ordered, strict=True
+        ):
+            card = _card(skill_id, ref, frontmatter)
+            if card is None:
+                continue
+            indexed.append((card, path))
+    return indexed
+
+
+def scan_skills(roots: ScopeRoots) -> list[CatalogSkill]:
+    """Index the skill cards captured under `roots`, discarding their on-disk paths.
+
+    Args:
+        roots: The scope roots to scan.
+
+    Returns:
+        One card per distinct skill, skipping malformed ones.
+    """
+    return [card for card, _ in scan_indexed_skills(roots)]
+
+
+def scan_environment(
+    roots: ScopeRoots,
+    mcp_servers: Sequence[CatalogMcpServer] = (),
+) -> Catalog:
+    """Build a live catalog from the captured skills and connected MCP servers — the entries
+    recall ranks against. Built-in tools are not retrieved by text (their descriptions never match
+    a task's goal language), so they are not in the catalog; every generated agent gets the fixed
+    `DEFAULT_TOOLS` set at selection time instead.
+
+    Args:
+        roots: The scope roots to scan for skills.
+        mcp_servers: Connected MCP server cards to include; pass `enumerate_mcp_servers()` to
+            harvest them. The empty default keeps the scan hermetic.
+
+    Returns:
+        A `Catalog` of the captured skills and `mcp_servers`.
+    """
+    return Catalog(entries=[*scan_skills(roots), *mcp_servers])

capdisc/frontmatter.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import re
+
+import yaml
+from pydantic import JsonValue, TypeAdapter, ValidationError
+
+# \r?\n: CRLF-authored files (git core.autocrlf) must not silently lose their frontmatter.
+_FRONTMATTER = re.compile(r"^---\r?\n(.*?)\r?\n---", re.DOTALL)
+_BOM = "\ufeff"
+_MAPPING: TypeAdapter[dict[str, JsonValue]] = TypeAdapter(dict[str, JsonValue])
+
+
+def load[T](text: str, shape: TypeAdapter[T]) -> T | None:
+    """Parse YAML or JSON text into `shape`.
+
+    No format sniffing is needed: YAML is a superset of JSON, so one `yaml.safe_load` reads both.
+    When the text is known to be JSON, prefer `shape.validate_json(text)` — stricter and faster.
+
+    Args:
+        text: The YAML/JSON source.
+        shape: The adapter to validate the parsed value into.
+
+    Returns:
+        The validated value, or None if `text` is neither valid YAML/JSON nor that shape.
+    """
+    try:
+        return shape.validate_python(yaml.safe_load(text))
+    except (yaml.YAMLError, ValidationError, RecursionError):
+        # RecursionError: deeply nested YAML in untrusted repo content must skip itself,
+        # not abort the scan.
+        return None
+
+
+def read_frontmatter(text: str) -> dict[str, JsonValue] | None:
+    """Extract the leading `--- … ---` frontmatter block as a mapping.
+
+    The single frontmatter-parsing boundary; callers validate the mapping into their own typed
+    model.
+
+    Args:
+        text: The document body, which may open with a frontmatter block.
+
+    Returns:
+        The frontmatter as a mapping, or None when the text has no such block or it isn't a
+        mapping.
+    """
+    match = _FRONTMATTER.match(text.removeprefix(_BOM))
+    return load(match.group(1), _MAPPING) if match else None

capdisc/hooks/__init__.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from ..catalog import McpToolName
+from .schema import (
+    EVENT_HANDLER_TYPES,
+    AgentHook,
+    CommandHook,
+    HandlerType,
+    HookAdapter,
+    HookConfig,
+    HookEvent,
+    HookHandler,
+    HttpHook,
+    MatcherGroup,
+    McpToolHook,
+    PromptHook,
+)
+from .types import (
+    EnvVarName,
+    HeaderName,
+    HeaderValue,
+    HookCondition,
+    HookMatcherPattern,
+    HookModel,
+    HookPrompt,
+    HookShell,
+    HookTimeout,
+    HookUrl,
+    ShellArg,
+    ShellCommand,
+    StatusMessage,
+)
+
+__all__ = [
+    "EVENT_HANDLER_TYPES",
+    "AgentHook",
+    "CommandHook",
+    "EnvVarName",
+    "HandlerType",
+    "HeaderName",
+    "HeaderValue",
+    "HookAdapter",
+    "HookCondition",
+    "HookConfig",
+    "HookEvent",
+    "HookHandler",
+    "HookMatcherPattern",
+    "HookModel",
+    "HookPrompt",
+    "HookShell",
+    "HookTimeout",
+    "HookUrl",
+    "HttpHook",
+    "MatcherGroup",
+    "McpToolHook",
+    "McpToolName",
+    "PromptHook",
+    "ShellArg",
+    "ShellCommand",
+    "StatusMessage",
+]

capdisc/hooks/schema.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Annotated, Literal
+
+from pydantic import Field, JsonValue, RootModel, TypeAdapter, model_validator
+
+from ..base import FrozenWireModel
+from ..catalog import McpServerRef, McpToolName
+from .types import (
+    AsyncRewake,
+    EnvVarName,
+    HeaderName,
+    HeaderValue,
+    HookCondition,
+    HookMatcherPattern,
+    HookModel,
+    HookPrompt,
+    HookShell,
+    HookTimeout,
+    HookUrl,
+    RunAsync,
+    RunOnce,
+    ShellArg,
+    ShellCommand,
+    StatusMessage,
+)
+
+
+class _Handler(FrozenWireModel):
+    """Fields every hook handler carries, whatever its `type`."""
+
+    timeout: HookTimeout | None = None
+    status_message: StatusMessage | None = None
+    once: RunOnce = False
+    condition: HookCondition | None = Field(default=None, alias="if")
+
+
+class CommandHook(_Handler):
+    """Runs a shell command, or spawns an executable directly when `args` is set."""
+
+    type: Literal["command"] = "command"
+    command: ShellCommand
+    args: list[ShellArg] = []
+    run_async: RunAsync = Field(default=False, alias="async")
+    async_rewake: AsyncRewake = False
+    shell: HookShell | None = None
+
+    @model_validator(mode="after")
+    def _async_rewake_implies_async(self) -> CommandHook:
+        """`asyncRewake` implies `async` (per the hooks docs), so `run_async` stays truthful as
+        'runs in background': any hook with `asyncRewake` set is forced async."""
+        if self.async_rewake and not self.run_async:
+            return self.model_copy(update={"run_async": True})
+        return self
+
+
+class HttpHook(_Handler):
+    """POSTs the event JSON to an endpoint and reads the decision from the response body."""
+
+    type: Literal["http"] = "http"
+    url: HookUrl
+    headers: dict[HeaderName, HeaderValue] = {}
+    allowed_env_vars: list[EnvVarName] = []
+
+
+class McpToolHook(_Handler):
+    """Calls a tool on an already-connected MCP server."""
+
+    type: Literal["mcp_tool"] = "mcp_tool"
+    server: McpServerRef
+    tool: McpToolName
+    input: dict[str, JsonValue] = {}
+
+
+class _LlmHook(_Handler):
+    """Shared fields of the LLM-evaluated hooks: a prompt sent to a model for an allow/block
+    decision. Prompt and agent hooks differ only in whether that model gets tool access."""
+
+    prompt: HookPrompt
+    model: HookModel | None = None
+
+
+class PromptHook(_LlmHook):
+    """Single-turn LLM evaluation that allows or blocks the action."""
+
+    type: Literal["prompt"] = "prompt"
+    continue_on_block: bool = False
+
+
+class AgentHook(_LlmHook):
+    """Multi-turn agentic verifier with tool access (experimental)."""
+
+    type: Literal["agent"] = "agent"
+
+
+HookHandler = Annotated[
+    CommandHook | HttpHook | McpToolHook | PromptHook | AgentHook,
+    Field(discriminator="type"),
+]
+
+HookAdapter: TypeAdapter[HookHandler] = TypeAdapter(HookHandler)
+
+HandlerType = Literal["command", "http", "mcp_tool", "prompt", "agent"]
+
+
+class HookEvent(StrEnum):
+    """An event a hook can fire on. Which handler `type`s an event accepts varies — see
+    `EVENT_HANDLER_TYPES`."""
+
+    pre_tool_use = "PreToolUse"
+    post_tool_use = "PostToolUse"
+    post_tool_use_failure = "PostToolUseFailure"
+    post_tool_batch = "PostToolBatch"
+    permission_denied = "PermissionDenied"
+    permission_request = "PermissionRequest"
+    user_prompt_submit = "UserPromptSubmit"
+    user_prompt_expansion = "UserPromptExpansion"
+    stop = "Stop"
+    subagent_stop = "SubagentStop"
+    task_completed = "TaskCompleted"
+    task_created = "TaskCreated"
+    teammate_idle = "TeammateIdle"
+    config_change = "ConfigChange"
+    cwd_changed = "CwdChanged"
+    elicitation = "Elicitation"
+    elicitation_result = "ElicitationResult"
+    file_changed = "FileChanged"
+    instructions_loaded = "InstructionsLoaded"
+    notification = "Notification"
+    post_compact = "PostCompact"
+    pre_compact = "PreCompact"
+    session_end = "SessionEnd"
+    stop_failure = "StopFailure"
+    subagent_start = "SubagentStart"
+    worktree_create = "WorktreeCreate"
+    worktree_remove = "WorktreeRemove"
+    session_start = "SessionStart"
+    setup = "Setup"
+
+
+# Which handler types each event accepts, per the Claude Code hooks docs. Three tiers: all
+# five types, the non-LLM three (no prompt/agent), and command+mcp_tool only.
+# Source: https://code.claude.com/docs/en/hooks (snapshot verified 2026-06). This mirrors a
+# product matrix that shifts between releases — refresh against the docs when events change.
+_ALL_TYPES: frozenset[HandlerType] = frozenset(("command", "http", "mcp_tool", "prompt", "agent"))
+_NO_LLM_TYPES: frozenset[HandlerType] = frozenset(("command", "http", "mcp_tool"))
+_CMD_MCP_TYPES: frozenset[HandlerType] = frozenset(("command", "mcp_tool"))
+
+EVENT_HANDLER_TYPES: dict[HookEvent, frozenset[HandlerType]] = {
+    HookEvent.session_start: _CMD_MCP_TYPES,
+    HookEvent.setup: _CMD_MCP_TYPES,
+    **dict.fromkeys(
+        (
+            HookEvent.config_change,
+            HookEvent.cwd_changed,
+            HookEvent.elicitation,
+            HookEvent.elicitation_result,
+            HookEvent.file_changed,
+            HookEvent.instructions_loaded,
+            HookEvent.notification,
+            HookEvent.post_compact,
+            HookEvent.pre_compact,
+            HookEvent.session_end,
+            HookEvent.stop_failure,
+            HookEvent.subagent_start,
+            HookEvent.worktree_create,
+            HookEvent.worktree_remove,
+        ),
+        _NO_LLM_TYPES,
+    ),
+    **dict.fromkeys(
+        (
+            HookEvent.pre_tool_use,
+            HookEvent.post_tool_use,
+            HookEvent.post_tool_use_failure,
+            HookEvent.post_tool_batch,
+            HookEvent.permission_denied,
+            HookEvent.permission_request,
+            HookEvent.user_prompt_submit,
+            HookEvent.user_prompt_expansion,
+            HookEvent.stop,
+            HookEvent.subagent_stop,
+            HookEvent.task_completed,
+            HookEvent.task_created,
+            HookEvent.teammate_idle,
+        ),
+        _ALL_TYPES,
+    ),
+}
+
+
+class MatcherGroup(FrozenWireModel):
+    """One `{matcher, hooks}` entry under an event: the handlers that run for matched subjects."""
+
+    matcher: HookMatcherPattern = "*"
+    hooks: list[HookHandler]
+
+
+class HookConfig(RootModel[dict[HookEvent, list[MatcherGroup]]]):
+    """The value of a `hooks` settings key (or a plugin's hooks.json): events mapped to their
+    matcher groups. Enforces that each handler `type` is one its event supports."""
+
+    @model_validator(mode="after")
+    def _enforce_event_support(self) -> HookConfig:
+        """Reject any handler whose `type` its event doesn't accept (per `EVENT_HANDLER_TYPES`)."""
+        for event, groups in self.root.items():
+            allowed = EVENT_HANDLER_TYPES[event]
+            for group in groups:
+                for handler in group.hooks:
+                    if handler.type not in allowed:
+                        raise ValueError(
+                            f"{handler.type!r} hook is not supported on {event.value} "
+                            f"(allowed: {sorted(allowed)})"
+                        )
+        return self