capt-hook 8.2.0__tar.gz → 8.3.0__tar.gz

{capt_hook-8.2.0 → capt_hook-8.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 8.2.0
+Version: 8.3.0
 Summary: Stop repeating yourself to Claude.
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali

{capt_hook-8.2.0 → capt_hook-8.3.0}/captain_hook/app.py

@@ -106,6 +106,9 @@ class State:
     settings: HooksSettings | None = None
     classifier: UserClassifier | None = None
     load_errors: list[tuple[str, BaseException]] = field(default_factory=list)
+    # Events subscribed only by session-attached packs — excluded from settings-drift
+    # warnings, since a plugin wires them in its own hooks.json, not the project's settings.
+    attach_only_events: set[str] = field(default_factory=set)
     counter: int = field(default=0, repr=False)
 
 
@@ -116,6 +119,7 @@ def reset() -> None:
     _state.hooks.clear()
     _state.gitignore_patterns.clear()
     _state.load_errors.clear()
+    _state.attach_only_events.clear()
     _state.counter = 0
     _state.settings = None
     _state.classifier = None

{capt_hook-8.2.0 → capt_hook-8.3.0}/captain_hook/cli.py

@@ -15,6 +15,7 @@ from typing import Any
 
 import click
 from cc_transcript.ids import SessionId
+from loguru import logger
 
 from captain_hook.app import _state, load_gitignore, reset
 from captain_hook.context import HookContext, load_transcript
@@ -36,22 +37,62 @@ class CliState:
     root: Path
     hooks: str
 
-    def discover(self) -> list[manager.ResolvedPack]:
+    def discover(self, session_dir: Path | None = None) -> 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):
+        # NLP provisioning is one shared SessionStart hook. Register it before the attached
+        # span when a project (packs.toml) pack needs it, so it counts as project-owned; only
+        # when solely an attached pack needs it does it register inside the span, so an
+        # attach-only NLP hook is attributed to the attach and never flagged as settings drift.
+        project_nlp = any(pack_.manifest.nlp for pack_ in resolved)
+        if project_nlp:
             register_nlp_provisioning()
+        attached = self.attached_packs(resolved, session_dir)
+        attached_start = len(_state.hooks)
+        for pack_ in attached:
+            discover_pack(pack_.entry.name, pack_.path)
+        if not project_nlp and any(pack_.manifest.nlp for pack_ in attached):
+            register_nlp_provisioning()
+        attached_hooks = _state.hooks[attached_start:]
+        all_resolved = [*resolved, *attached]
+        attached_ids = {id(h) for h in attached_hooks}
+        _state.attach_only_events = {n for h in attached_hooks for n in event_names(h.spec.events)} - {
+            n for h in _state.hooks if id(h) not in attached_ids for n in event_names(h.spec.events)
+        }
         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
+        return all_resolved
+
+    def attached_packs(
+        self, resolved: Sequence[manager.ResolvedPack], session_dir: Path | None
+    ) -> list[manager.ResolvedPack]:
+        """Resolve session-attached packs a builtin or packs.toml pack doesn't already own.
+
+        A packs.toml entry (builtin, source, or ``disabled = true``) of the same name wins
+        over an ambient plugin attach; the shadowed attach is dropped with a debug log.
+        """
+        if session_dir is None:
+            return []
+        owned = {pack_.entry.name for pack_ in resolved} | {
+            e.name
+            for e in manager.read_entries(manager.packs_toml_path(self.root))
+            if isinstance(e, manager.DisabledPack)
+        }
+        kept: list[manager.ResolvedPack] = []
+        for pack_ in manager.resolve_attached(session_dir):
+            if pack_.entry.name in owned:
+                logger.bind(pack=pack_.entry.name).debug("attached pack shadowed by a packs.toml or disabled entry")
+                continue
+            kept.append(pack_)
+        return kept
 
 
 def example_hook_source() -> str:
@@ -253,7 +294,10 @@ def regenerate_settings(state: CliState) -> None:
 
 def settings_drift(root: Path) -> set[str]:
     paths = [p for name in ("settings.json", "settings.local.json") if (p := root / ".claude" / name).exists()]
-    return subscribed_events() - {event for p in paths for event in capt_hook_events(p)} if paths else set()
+    if not paths:
+        return set()
+    wired = {event for p in paths for event in capt_hook_events(p)}
+    return subscribed_events() - _state.attach_only_events - wired
 
 
 def warn_settings_drift(
@@ -285,12 +329,7 @@ def warn_settings_drift(
     return base
 
 
-def run_event(
-    event_name: str,
-    *,
-    async_: bool = False,
-    root: Path | None = None,
-) -> None:
+def run_event(state: CliState, event_name: str, *, async_: bool = False) -> None:
     try:
         event = Event[event_name]
     except KeyError:
@@ -315,19 +354,22 @@ def run_event(
     setup_logging(session_id)
     resolved_path = raw.get("agent_transcript_path") or raw.get("transcript_path")
 
+    # stdin is parsed first so the session dir is known before discovery: CliState.discover
+    # loads this session's attached packs (see attached_packs) on top of packs.toml.
     session_dir = ensure_session(SessionId(session_id)) if session_id else None
+    state.discover(session_dir=session_dir)
     ctx = HookContext(
         session=SessionStore(session_dir),
         transcript=load_transcript(resolved_path),
         settings=_state.settings,
-        project_root=root,
+        project_root=state.root,
     )
     evt = event.event_class(_raw=raw, ctx=ctx)
 
     if output := warn_settings_drift(
         dispatch(event, evt, session_dir=session_dir, async_=async_),
         event,
-        root,
+        state.root,
         session_dir,
         async_=async_,
     ):
@@ -520,8 +562,7 @@ def cli(ctx: click.Context, hooks: str | None, root_path: str | None) -> None:
 @click.option("--async", "async_", is_flag=True, default=False, help="Run async hooks only")
 @click.pass_obj
 def run(state: CliState, event: str, async_: bool) -> None:
-    state.discover()
-    run_event(event, async_=async_, root=state.root)
+    run_event(state, event, async_=async_)
 
 
 @cli.command(name="register-hooks")
@@ -622,6 +663,29 @@ def pack_add(state: CliState, target: str) -> None:
     regenerate_settings(state)
 
 
+@pack.command(name="attach")
+@click.argument("directory")
+def pack_attach(directory: str) -> None:
+    """Register a plugin's pack for the current session (reads the SessionStart JSON on stdin).
+
+    A Claude plugin wires this to a SessionStart hook so its pack loads under the byte-identical
+    canonical ``uvx capt-hook run <Event>`` commands, letting Claude Code's exact-command dedup
+    collapse plugin and project wiring into one process per event. Writes nothing to stdout on
+    success (SessionStart stdout is injected into the model context); a missing or invalid
+    manifest exits 1 with a stderr message.
+    """
+    raw = json.loads(sys.stdin.read())
+    session_dir = ensure_session(SessionId(raw["session_id"]))
+    root = Path(directory).resolve()
+    try:
+        manifest = manager.PackManifest.load(manager.manifest_in(root))
+    except manager.PackError as e:
+        raise click.ClickException(str(e)) from e
+    manager.upsert_attached(
+        session_dir, manager.AttachedPack(name=manifest.name, dir=str(root), version=manifest.version)
+    )
+
+
 @pack.command(name="list")
 @click.pass_obj
 def pack_list(state: CliState) -> None:

{capt_hook-8.2.0 → capt_hook-8.3.0}/captain_hook/packs/manager.py

@@ -22,6 +22,7 @@ import os
 import re
 import shutil
 import tarfile
+import tempfile
 import time
 import tomllib
 from collections.abc import Iterator, Sequence
@@ -31,11 +32,13 @@ from pathlib import Path
 from typing import Any
 
 from filelock import FileLock
+from loguru import logger
 
 from captain_hook.settings import resolve_cache_dir
 from captain_hook.util import http
 
 PACK_MANIFEST = "capt-hook.toml"
+ATTACHED_FILE = "attached_packs.json"
 SHA_MARKER = ".sha"
 LATEST_REF = "latest"
 # Moving refs (@latest / a branch / a bare default-branch source) re-resolve to a fresh
@@ -108,12 +111,39 @@ class ExternalPack:
     commit: str | None = None
 
 
-type PackEntry = BuiltinPack | ExternalPack
+@dataclass(frozen=True, slots=True)
+class DisabledPack:
+    """A packs.toml entry that declines a pack by name.
+
+    ``[packs.<name>] disabled = true`` suppresses a pack the repo would otherwise
+    inherit — a builtin, a packs.toml source, or a plugin-attached pack — regardless of
+    any other keys on the entry. Disabling always wins.
+    """
+
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class AttachedPack:
+    """A pack a Claude plugin registered for the current session via ``pack attach``.
+
+    Stored per session in ``attached_packs.json`` keyed by ``name``; ``dir`` is the
+    absolute pack root (holding the ``capt-hook.toml`` manifest) and ``version`` is the
+    manifest version recorded at attach time.
+    """
+
+    name: str
+    dir: str
+    version: str
+
+
+type PackEntry = BuiltinPack | ExternalPack | DisabledPack
+type ResolvedEntry = BuiltinPack | ExternalPack | AttachedPack
 
 
 @dataclass(frozen=True, slots=True)
 class ResolvedPack:
-    entry: PackEntry
+    entry: ResolvedEntry
     path: Path
     manifest: PackManifest
 
@@ -160,6 +190,8 @@ def manifest_in(root: Path) -> Path:
 
 def parse_entry(name: str, table: dict[str, Any]) -> PackEntry:
     match table:
+        case {"disabled": True}:
+            return DisabledPack(name=name)
         case {"source": source, "commit": commit}:
             return ExternalPack(name=name, source=PackSource.parse(source), commit=commit)
         case {"source": source}:
@@ -180,6 +212,8 @@ def render_entry(entry: PackEntry) -> str:
     match entry:
         case BuiltinPack(name=name):
             return f"[packs.{name}]\n\n"
+        case DisabledPack(name=name):
+            return f"[packs.{name}]\ndisabled = true\n\n"
         case ExternalPack(name=name, source=source, commit=None):
             return f'[packs.{name}]\nsource = "{source}"\n\n'
         case ExternalPack(name=name, source=source, commit=commit):
@@ -191,10 +225,20 @@ def render_packs_toml(entries: Sequence[PackEntry]) -> str:
 
 
 def atomic_write(path: Path, text: str) -> None:
+    """Write ``text`` to ``path`` atomically via a unique temp file in the same directory.
+
+    The temp name is per-call (``mkstemp``), so concurrent writers to the same path never
+    consume each other's temp file — one writer's ``os.replace`` can't yank another's out.
+    """
     path.parent.mkdir(parents=True, exist_ok=True)
-    tmp = path.with_suffix(f"{path.suffix}.tmp")
-    tmp.write_text(text)
-    os.replace(tmp, path)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, suffix=f"{path.suffix}.tmp")
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(text)
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
 
 
 def upsert_entry(path: Path, entry: PackEntry) -> None:
@@ -444,6 +488,8 @@ def resolve_enabled_packs(root: Path) -> tuple[list[ResolvedPack], list[str]]:
         match entry:
             case BuiltinPack(name=name):
                 resolved.append(resolve_builtin(name))
+            case DisabledPack():
+                pass
             case ExternalPack() as ext if found := (load_cached_fresh(ext, now) if fast else resolve_external(ext)):
                 resolved.append(found)
             case ExternalPack() as ext:
@@ -451,3 +497,60 @@ def resolve_enabled_packs(root: Path) -> tuple[list[ResolvedPack], list[str]]:
     if not (fast or missing):
         atomic_write(fastpath_path(root), toml_hash(root))
     return resolved, missing
+
+
+def attached_path(session_dir: Path) -> Path:
+    return session_dir / ATTACHED_FILE
+
+
+def read_attached(session_dir: Path) -> list[AttachedPack]:
+    path = attached_path(session_dir)
+    if not path.exists():
+        return []
+    return [AttachedPack(name=e["name"], dir=e["dir"], version=e["version"]) for e in json.loads(path.read_text())]
+
+
+def upsert_attached(session_dir: Path, pack: AttachedPack) -> None:
+    """Record ``pack`` in the session's attach file, replacing any entry of the same name.
+
+    The read-modify-write runs under a file lock so two ``pack attach`` processes (parallel
+    SessionStart hooks) serialize rather than clobber each other's entries.
+    """
+    path = attached_path(session_dir)
+    lock = path.with_name(path.name + ".lock")
+    with FileLock(str(lock)):
+        existing = read_attached(session_dir)
+        if (prior := next((p for p in existing if p.name == pack.name), None)) and prior.dir != pack.dir:
+            logger.bind(pack=pack.name, previous=prior.dir, incoming=pack.dir).debug(
+                "attached pack name re-bound to a different dir; the newer attach wins"
+            )
+        entries = [*(p for p in existing if p.name != pack.name), pack]
+        atomic_write(
+            path,
+            json.dumps([{"name": p.name, "dir": p.dir, "version": p.version} for p in entries]),
+        )
+
+
+def resolve_attached(session_dir: Path) -> list[ResolvedPack]:
+    """Resolve this session's attached packs, dropping entries that no longer resolve.
+
+    A plugin update moves or non-atomically rewrites its versioned cache path, so a prior
+    session's attach entry can dangle or point at a half-written manifest. SessionStart
+    re-attaches every session, so an entry whose dir has vanished or whose manifest is
+    missing/malformed is skipped with a debug log rather than killing dispatch for every
+    other hook in the event — the same fail-soft shape as ``resolve_enabled_packs``.
+    """
+    resolved: list[ResolvedPack] = []
+    for pack in read_attached(session_dir):
+        root = Path(pack.dir)
+        if not root.is_dir():
+            continue
+        try:
+            manifest = PackManifest.load(manifest_in(root))
+        except (PackError, tomllib.TOMLDecodeError, KeyError, OSError):
+            logger.bind(pack=pack.name, dir=pack.dir).opt(exception=True).debug(
+                "skipped attached pack with a missing or malformed manifest"
+            )
+            continue
+        resolved.append(ResolvedPack(pack, manifest.hooks_dir(root), manifest))
+    return resolved

{capt_hook-8.2.0 → capt_hook-8.3.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 = "8.2.0"
+version = "8.3.0"
 description = "Stop repeating yourself to Claude."
 readme = "README.md"
 license = "PolyForm-Noncommercial-1.0.0"