hubkit-cli 0.1.0__py3-none-any.whl

hubcore/data/hub/scripts/hubcore/gate.py

@@ -0,0 +1,145 @@
+"""Stop-hook gate: reasons the hub may not end its turn yet (arm the watch, stalled item, unfounded question, unverified verdict)."""
+
+from __future__ import annotations
+
+import re
+import time
+
+from . import lessons, routed, slow, store
+from .orders import PR_REF, Orders
+from .status import work_load
+
+VERDICT = re.compile(r"(?i)\b(approved?|changes requested|request_changes|verdict|review(\s+(of|on|for)\s+\S+)?\s+(is\s+)?(done|complete|finished|landed))\b")
+_V = r"(?:verdict|review|approval)"
+AWAITING = re.compile(
+    rf"(?i)\b(?:wait(?:s|ing)?\s+(?:on|for)|awaiting|expect(?:s|ing|ed)?)\s+(?:\S+\s+){{0,3}}?{_V}\b"
+    rf"|\bpending\s+(?:an?\s+|the\s+)?{_V}\b|\bno\s+{_V}\b|\b(?:until|still\s+need\w*|yet\s+to\s+(?:get|have|receive|see))\s+(?:\S+\s+){{0,2}}?{_V}\b"
+)
+REPO_PR = re.compile(r"[\w.-]+(?:/[\w.-]+)?#\d{2,6}|\b[A-Za-z][\w.-]*\s+\d{2,6}\b")
+WATCH_CMD = "python3 ~/.claude/skills/hub/scripts/hubkit watch --interval 120 --max-cycles 30"
+
+
+def watch_live(cfg: dict) -> bool:
+    """A `hubkit watch` is running: its pidfile names a process that is still the same process."""
+    from . import hooks
+
+    p = store.state(cfg) / "watch.pid"
+    try:
+        pid, start = p.read_text(encoding="utf-8").split()
+    except ValueError, OSError:
+        return False
+    return hooks.proc_start(int(pid)) == start
+
+
+def open_work(cfg: dict) -> bool:
+    """True while routed work or a live open order exists."""
+    return bool(routed.items(cfg)) or any(o["state"] == "open" for o in Orders(cfg).live())
+
+
+def blocked_on_user(cfg: dict) -> bool:
+    """True when an `ask` work item says something really waits on the user."""
+    return any(i.get("kind") == "ask" for i in work_load(store.state(cfg)))
+
+
+def is_question(cfg: dict, last: str) -> bool:
+    """True when the final message ends in a question or holds a configured stop-guard phrase."""
+    tail = last.splitlines()[-1] if last else ""
+    return tail.endswith("?") or any(p in last.lower() for p in cfg["stop_guard"]["phrases"])
+
+
+def unverified_verdict(cfg: dict, last: str) -> list[str]:
+    """PRs of a tracked review item that a sentence of the message gives a verdict on, while GitHub shows no
+    review at the PR's current head that counts (routed.counts_as_review). A verdict word and a PR number count only in the same sentence."""
+    named: list[str] = []
+    for sentence in re.split(r"(?<=[.!?])\s+|\n", last):
+        if VERDICT.search(sentence) and (PR_REF.search(sentence) or REPO_PR.search(sentence)) and not AWAITING.search(sentence):
+            named += routed.refs(cfg, sentence)
+    urls = {
+        routed.pr_key(p): p
+        for i in routed.items(cfg)
+        if i.get("review")
+        for p in [*i["prs"], *i.get("queue", [])]
+        if any(routed.same_pr(p, r) for r in named)
+    }
+    timeout = float(routed.opts(cfg)["gh_timeout_s"])
+    return sorted(routed.pr_num(u) for u in urls.values() if not _reviewed_at_head(cfg, u, timeout))
+
+
+def _reviewed_at_head(cfg: dict, url: str, timeout: float) -> bool:
+    """True when GitHub shows a non-author review at the head, or cannot be read (an unreadable PR proves nothing)."""
+    info = routed.pr_info(cfg, url, timeout)
+    if info is None:
+        return True
+    return any(routed.counts_as_review(cfg, r, info) and routed.same_head(r["commit"], info["head"]) for r in info["reviews"])
+
+
+BLOCKED_WORDS = ["blocked", "is down", "are down", "failed", "failing", "no host", "cannot reach", "can't reach", "unreachable",
+                 "not available", "waiting on", "waiting for", "stuck", "needs a person", "needs his call", "needs her call"]
+
+
+NEGATION = re.compile(r"(?i)\b(no|not|nothing|nobody|none|never|nor|without|isn't|aren't|wasn't|weren't|hasn't|haven't|doesn't|don't)\s+(?:\w+\s+){0,3}$")
+
+
+# A wait that is the user's own stop or hold is not a blocker to solve: waiting on his word, or work he put on hold.
+USER_WAIT = re.compile(
+    r"(?i)\b(?:wait(?:s|ing)?|awaiting)\s+(?:on|for)\s+(?:your|you|his|her|the user'?s?)\b"
+    r"|\b(?:on\s+hold|held|(?:you|he|she)\s+(?:asked|told|said|ordered)\s+(?:me\s+)?to\s+(?:hold|stop|wait|pause))\b"
+)
+
+
+def _asserted(low: str, word: str) -> bool:
+    """The word is in the sentence and not negated ("nothing is stuck", "not blocked", "no failed runs" assert nothing)."""
+    return any(not NEGATION.search(low[: m.start()]) for m in re.finditer(rf"(?<!\w){re.escape(word)}(?!\w)", low))
+
+
+def blocked_claim(cfg: dict, last: str) -> str | None:
+    """The sentence of the final message that says live work is blocked, down, failed or waiting on a host, tool or
+    person, or None. Review-verdict waits are the verdict check's business. Words come from intents.toml [stop_gate]."""
+    words = [w.lower() for w in Orders(cfg).intents.get("stop_gate", {}).get("blocked_words", BLOCKED_WORDS)]
+    for sentence in re.split(r"(?<=[.!?])\s+|\n", last):
+        low = sentence.lower()
+        if any(_asserted(low, w) for w in words) and not AWAITING.search(sentence) and not USER_WAIT.search(sentence):
+            return sentence.strip()[:100]
+    return None
+
+
+def blocker_reasons(cfg: dict, last: str, now: float) -> list[str]:
+    """Blocked work must be solved, not reported: an open blocker without a running fix, a fix past its limit, a
+    stop-loss with no result since, or a message that calls an open order blocked when no fix is on record."""
+    orders = Orders(cfg)
+    out = []
+    live = [o for o in orders.live() if o["state"] == "open"]
+    for o in live:
+        why = orders.blocker_problem(o, now)
+        if why:
+            out.append(f"hubkit BLOCKER: {why}. NEXT: start the fix now on a free owner, record it: hubkit order block {o['id']} --on \"..\" "
+                       f"--fix \"<action running>\" --holder <who>; when it ran: hubkit order result {o['id']} --note \"<what came of it>\"")
+        if orders.stoploss_pending(o):
+            out.append(f"hubkit STOP-LOSS: {o['id']} was chased past the limit and no result is recorded since. A reply is not a result. "
+                       f"NEXT: do the blocking step, then: hubkit order result {o['id']} --note \"<what you did, what came of it>\"")
+    claim = blocked_claim(cfg, last) if live else None
+    if claim and not any((o.get("blocker") or {}).get("fix") for o in live):
+        out.append(f"hubkit: your message says work is blocked ({claim!r}) but no order has a fix on record. Solve it, do not report it. "
+                   f"NEXT: start the fix on a free owner, then: hubkit order block <id> --on \"..\" --fix \"<action running>\" --holder <who>")
+    return out
+
+
+def stop_reasons(cfg: dict, last: str, now: float | None = None, transcript: str | None = None) -> list[str]:
+    """Every reason the turn cannot end yet, each with its exact action. Empty = the turn may end."""
+    now = now or time.time()
+    reasons = routed.prompt_lines(cfg, now)
+    reasons += blocker_reasons(cfg, last, now)
+    reasons += [r for r in (lessons.unswept_asks(cfg, last, now), lessons.unchecked_claim(cfg, last, transcript)) if r]
+    try:
+        reasons += slow.gate_lines(cfg, now)
+    except Exception as e:  # a failing estimate check must not wedge the hub's turn end
+        store.append_row(store.state(cfg) / "hook-errors.jsonl", {"where": "slow.gate", "error": repr(e)[:200]})
+    if open_work(cfg) and not watch_live(cfg):
+        reasons.append(f"hubkit: nothing will wake you when routed work stalls. NEXT: start in the background: {WATCH_CMD}")
+    for n in unverified_verdict(cfg, last):
+        reasons.append(f"hubkit: your message gives a verdict on #{n}, but GitHub shows no review at its current head "
+                       "(agent words are not evidence). NEXT: correct the message; relay a verdict only after the item closes itself")
+    if is_question(cfg, last) and not blocked_on_user(cfg):
+        reasons.append("hubkit: you ended on a question to the user but nothing is blocked on him. NEXT: settle it from the record "
+                       "or route it; only if it truly needs him run: hubkit work add --kind ask --title \"<the one question>\" --note \"<ordered work it blocks>\"")
+    return reasons

hubcore/data/hub/scripts/hubcore/hooks.py

@@ -0,0 +1,326 @@
+"""Hook entry points. Every hook: no-op outside the live bound hub, fail open, exit 0."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import time
+import traceback
+from pathlib import Path
+from typing import TypeGuard
+
+from . import compat, config, gate, lessons, routed, store
+from .orders import Orders, hook_intake
+from .redact import redact
+from .status import read_status, render_block
+
+# ---- bind: hub identity = session id + pid + procStart, liveness read through compat ----
+
+def proc_start(pid: int) -> str | None:
+    """Start-time token of a live process (see compat), or None when it is gone."""
+    return compat.proc_start(pid)
+
+
+def session_file(cfg: dict, pid: int) -> dict | None:
+    """The Claude Code session file for a pid, or None."""
+    try:
+        return json.loads((config.sessions_dir(cfg) / f"{pid}.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def find_session_pid(cfg: dict) -> int | None:
+    """Walk up the parent chain from this process to the nearest pid with a session file."""
+    pid = os.getppid()
+    for _ in range(12):
+        if pid <= 1:
+            return None
+        if session_file(cfg, pid):
+            return pid
+        parent = compat.parent_pid(pid)
+        if parent is None:
+            return None
+        pid = parent
+    return None
+
+
+def bind_path(cfg: dict) -> Path:
+    """File that records which session is the hub."""
+    return store.state(cfg, create=False) / "hub.bind"
+
+
+def read_bind(cfg: dict) -> dict | None:
+    """The hub bind record, or None when absent or unreadable."""
+    try:
+        return json.loads(bind_path(cfg).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def bind_alive(b: dict | None) -> TypeGuard[dict]:
+    """True when the bind record names a process that is still the same process (pid plus start time)."""
+    if not b:
+        return False
+    return proc_start(int(b["pid"])) == str(b["procStart"])
+
+
+def bind(cfg: dict, pid: int | None) -> str:
+    """Bind the session of `pid` (or of this process tree) as the hub; refuses a second live hub."""
+    pid = pid or find_session_pid(cfg)
+    sess = session_file(cfg, pid) if pid else None
+    if not sess or not pid:
+        raise RuntimeError("no Claude session found for this process (pass --pid)")
+    if sess.get("kind") != "interactive":
+        raise RuntimeError(f"session kind is {sess.get('kind')!r}, only interactive sessions can be the hub")
+    cur = read_bind(cfg)
+    if bind_alive(cur) and cur["session_id"] != sess["sessionId"]:
+        raise RuntimeError(f"live hub already bound: {cur.get('name')} (pid {cur['pid']})")
+    rec = {"session_id": sess["sessionId"], "pid": pid, "procStart": proc_start(pid),
+           "name": sess.get("name", ""), "cwd": sess.get("cwd", ""), "bound_at": time.time()}
+    store.state(cfg)  # create the state dir
+    store.write_atomic(bind_path(cfg), json.dumps(rec))
+    return f"bound {rec['name'] or rec['session_id']} (pid {pid})"
+
+
+def unbind(cfg: dict) -> str:
+    """Remove the hub bind."""
+    bind_path(cfg).unlink(missing_ok=True)
+    return "unbound"
+
+
+def is_hub(cfg: dict, payload: dict) -> bool:
+    """True only for the live bound interactive hub session."""
+    if os.environ.get("HUBKIT_DISABLE"):
+        return False
+    b = read_bind(cfg)
+    if not bind_alive(b) or payload.get("session_id") != b["session_id"]:
+        return False
+    sess = session_file(cfg, int(b["pid"]))
+    return sess is not None and sess.get("kind") == "interactive" and sess.get("sessionId") == b["session_id"]
+
+
+# ---- the hooks ----
+
+def _session_by_id(cfg: dict, session_id: str | None) -> tuple[int | None, dict | None]:
+    """The running session file for this session id (the hook payload names it)."""
+    for f in config.sessions_dir(cfg).glob("*.json"):
+        sess = session_file(cfg, int(f.stem)) if f.stem.isdigit() else None
+        if sess and session_id and sess.get("sessionId") == session_id and proc_start(int(f.stem)) == str(sess.get("procStart")):
+            return int(f.stem), sess
+    return None, None
+
+
+def _rebind_candidate(cfg: dict, payload: dict) -> int | None:
+    """Pid of this session when it may take over a dead bind, else None.
+
+    Only a session that resumes the bound session id, or that has the configured hub name AND the
+    bound cwd, qualifies. A live bind is never taken over; any other session is left alone.
+    """
+    b = read_bind(cfg)
+    if not b or bind_alive(b):
+        return None
+    pid, sess = _session_by_id(cfg, payload.get("session_id"))
+    if not sess or sess.get("kind") != "interactive":
+        return None
+    resumed = sess["sessionId"] == b["session_id"]
+    named = bool(b.get("cwd")) and sess.get("cwd") == b["cwd"] and sess.get("name") == cfg["hub"]["name"]
+    return pid if resumed or named else None
+
+
+def hook_session(cfg: dict, payload: dict) -> str:
+    """SessionStart hook: print the status block, and re-bind a hub that resumed."""
+    rebound = ""
+    if not is_hub(cfg, payload):
+        pid = _rebind_candidate(cfg, payload)
+        if pid is None:
+            return ""  # nothing printed, nothing written outside the bound hub
+        rebound = f"hubkit: {bind(cfg, pid)}; the old bind was dead (re-bound by the SessionStart hook)\n"
+    store.touch_seen(store.state(cfg), "session")
+    return rebound + render_block(cfg, Orders(cfg), read_status(cfg))
+
+
+def _words(text: str) -> set[str]:
+    return {w for w in re.findall(r"[a-z0-9']+", text.lower()) if len(w) > 2}
+
+
+def correction_line(orders: Orders, sd: Path, text: str, now: float) -> str:
+    """Detect a correction (configured phrases, or the same instruction repeated) and inject a record prompt."""
+    cfg = orders.intents.get("corrections", {})
+    why = ""
+    if any(re.search(p, text) for p in cfg.get("patterns", [])):
+        why = "correction phrase"
+    recent_path = sd / "recent-prompts.jsonl"
+    rows, _ = store.read_rows(recent_path)
+    mine = _words(text)
+    window = float(cfg.get("repeat_window_min", 30)) * 60
+    if not why and len(mine) >= 4:
+        for r in rows:
+            if now - r["ts"] <= window and len(_words(r["text"])) >= 4:
+                other = _words(r["text"])
+                if len(mine & other) / len(mine | other) >= float(cfg.get("repeat_similarity", 0.6)):
+                    why = "repeated instruction"
+                    break
+    store.append_row(recent_path, {"text": store.safe(text, 300), "ts": now})
+    if len(rows) > 2000:  # `hubkit asks ls` reads this file: keep a day or more of the user's words
+        store.write_atomic(recent_path, "".join(json.dumps(r) + "\n" for r in rows[-1000:]))
+    if not why:
+        return ""
+    quote = redact(text)[0][:200]
+    return (f'hubkit CORRECTION ({why}): record it this turn. Quote: "{quote}". '
+            "Run learn.py add --class <existing-or-new-kebab> --gate <G1..G8> --quote <the words> "
+            "--situation .. --wrong .. --right .. --evidence .. (reuse a class from the block if it is the same mistake).")
+
+
+def unordered_chase_lines(cfg: dict, orders: Orders, text: str, now: float) -> list[str]:
+    """A short chase ("any progress?") with no order live: nothing counts it, so answer it from the job list."""
+    intake = orders.intents.get("intake", {})
+    chase = intake.get("chase")
+    if not chase or orders.live() or len(text) > int(intake.get("verb_max_chars", 120)) or not re.search(chase, text):
+        return []
+    from . import slow
+
+    jobs = slow.jobs(cfg, orders, now)
+    return ["hubkit: no order is live, so this chase is on the job list:", *(slow.block_lines(jobs, now) or ["no live job either: say so plainly"])]
+
+
+def hook_prompt(cfg: dict, payload: dict) -> str:
+    """UserPromptSubmit hook: open, chase, hold or cancel orders from the user's words; inject correction and overdue lines."""
+    if not is_hub(cfg, payload):
+        return ""
+    sd = store.state(cfg)
+    store.touch_seen(sd, "prompt")
+    text = payload.get("prompt") or ""
+    origin = (payload.get("origin") or {}).get("kind")
+    now = time.time()
+    routed.scan_transcript(cfg, payload.get("transcript_path"))  # heard-from before the stall clock is read
+    if peer := routed.peer_name(text):  # a peer message that did reach this hook: heard now, opens nothing
+        routed.heard(cfg, [(now, peer, text)])
+    if not store.is_human(text, origin):
+        return ""
+    orders = Orders(cfg)
+    corr = correction_line(orders, sd, text, now)
+    return "\n".join([*routed.prompt_lines(cfg, now), *hook_intake(orders, text), *unordered_chase_lines(cfg, orders, text, now), *([corr] if corr else [])])
+
+
+def _answer_text(resp: object) -> str:
+    """The user's answer text from an AskUserQuestion tool_response (dict with answers, or plain text)."""
+    if isinstance(resp, dict):
+        ans = resp.get("answers")
+        return "\n".join(str(v) for v in ans.values()) if isinstance(ans, dict) else ""
+    return resp if isinstance(resp, str) else ""
+
+
+def hook_answer(cfg: dict, payload: dict) -> str:
+    """A card answer (AskUserQuestion) goes through the same intake as a typed prompt."""
+    if not is_hub(cfg, payload) or payload.get("tool_name") != "AskUserQuestion":
+        return ""
+    store.touch_seen(store.state(cfg), "answer")
+    text = _answer_text(payload.get("tool_response"))
+    if not store.is_human(text):
+        return ""
+    routed.close_asks(cfg, time.time())  # the user answered the card: nothing is blocked on him now
+    return "\n".join(hook_intake(Orders(cfg), text))
+
+
+def hook_routed(cfg: dict, payload: dict) -> str:
+    """SendMessage / Agent from the hub: open or refresh the routed item (see routed.from_tool)."""
+    tool = payload.get("tool_name")
+    if not is_hub(cfg, payload) or tool not in ("SendMessage", "Agent"):
+        return ""
+    store.touch_seen(store.state(cfg), "routed")
+    routed.scan_transcript(cfg, payload.get("transcript_path"))
+    ti = payload.get("tool_input") or {}
+    forbids = lessons.brief_forbids_fix(cfg, str(ti.get("message") or ti.get("prompt") or ""))
+    item = routed.from_tool(cfg, tool, payload.get("tool_input") or {}, payload.get("tool_response"),
+                            str(payload.get("tool_use_id") or ""))
+    if not item:
+        return forbids or ""
+    out = f"hubkit: tracking {item['id']} routed to {item['owner']}; stall clock {routed.opts(cfg)['stall_min']} min"
+    if item.get("estimate_min") is not None:
+        out += f"; estimate {item['estimate_min']:g}m"
+        if item.get("estimate_defaulted"):
+            out += (f" DEFAULTED ({item.get('estimate_basis', '')}), the brief had no `Estimate: <n>m` line. "
+                    f"Set it: hubkit work estimate {item['id']} --minutes N --why \"...\"")
+    out += queue_warning(cfg, item)
+    return out + (f"\n{forbids}" if forbids else "")
+
+
+def hook_pretool(cfg: dict, payload: dict) -> str:
+    """PreToolUse on Bash: warn (never deny) about a `gh pr merge` nobody ordered."""
+    if not is_hub(cfg, payload) or payload.get("tool_name") != "Bash":
+        return ""
+    warning = lessons.merge_warning(cfg, str((payload.get("tool_input") or {}).get("command") or ""))
+    if not warning:
+        return ""
+    return json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": warning}})
+
+
+def queue_warning(cfg: dict, item: dict) -> str:
+    """A new job sent to an owner who already holds another live job, while an order is open: it queues behind that job."""
+    if not item.get("behind") or len(item.get("events", [])) != 1 or not any(o["state"] == "open" for o in Orders(cfg).live()):
+        return ""
+    return (f"\nhubkit WARNING: {item['owner']} already holds {', '.join(item['behind'])}; {item['id']} queues behind it while an order is open. "
+            "An urgent step never waits in a busy agent's queue. NEXT: send it to a free owner now")
+
+
+def hook_stop(cfg: dict, payload: dict) -> str:
+    """Block the turn end (JSON decision, which reaches the model; plain Stop stdout does not) while the hub owes
+    something: arm the watch, chase a stalled item, back a verdict, or justify a question. Once per stop:
+    `stop_hook_active` means the harness already sent the hub back, so it is let through."""
+    if not is_hub(cfg, payload) or payload.get("stop_hook_active"):
+        return ""
+    sd = store.state(cfg)
+    store.touch_seen(sd, "stop")
+    routed.scan_transcript(cfg, payload.get("transcript_path"))
+    last = (payload.get("last_assistant_message") or "").strip()
+    reasons = gate.stop_reasons(cfg, last, transcript=payload.get("transcript_path"))
+    if not reasons:
+        return ""
+    store.append_row(sd / "stop-guard.jsonl", {"blocked": True, "reasons": [store.safe(r, 300) for r in reasons]})
+    return json.dumps({"decision": "block", "reason": "\n".join(reasons)})
+
+
+def hook_record(cfg: dict, payload: dict) -> str:
+    """Schema canary: keys and value types of the real payload, never values."""
+    if not is_hub(cfg, payload):
+        return ""
+    sd = store.state(cfg)
+    ev = payload.get("hook_event_name", "unknown")
+    src = payload.get("source", "")
+    sample = {k: type(v).__name__ for k, v in sorted(payload.items())}
+    store.write_atomic(sd / "payload-samples" / f"{ev}{'-' + src if src else ''}.json",
+                       json.dumps({"keys": sample, "at": time.time()}))
+    return ""
+
+
+HOOKS = {"session": hook_session, "prompt": hook_prompt, "stop": hook_stop, "record": hook_record, "answer": hook_answer, "routed": hook_routed, "pretool": hook_pretool}
+
+
+def main(event: str) -> int:
+    """Run one hook. Always exit 0. Errors are logged and shown only for the bound hub session."""
+    payload: dict = {}
+    cfg: dict = {}
+    try:
+        raw = sys.stdin.read()
+        payload = json.loads(raw) if raw.strip() else {}
+        payload = payload if isinstance(payload, dict) else {}
+        cfg = config.load()
+        out = HOOKS[event](cfg, payload)
+        if event != "record":
+            hook_record(cfg, payload)  # real payload keys and types, hub session only
+        if out:
+            print(out)
+    except BaseException as e:  # a hook must never break the session
+        try:
+            if cfg and is_hub(cfg, payload):  # outside the hub: silent, no shared error file
+                store.append_row(
+                    config.state_dir(cfg) / "hook-errors.jsonl",
+                    {"event": event, "error": repr(e)[:200], "trace": traceback.format_exc()[-600:]},
+                )
+                if event in ("session", "prompt"):
+                    print(f"hubkit: hook {event} failed ({type(e).__name__}); see hook-errors.jsonl")
+        except BaseException:
+            pass
+    return 0

hubcore/data/hub/scripts/hubcore/install.py

@@ -0,0 +1,66 @@
+"""`hubkit skills --install DIR` and `hubkit hooks`: put the skills where the agent tool reads them, and print the hooks block."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+from . import config
+
+HUB_FILES = ("SKILL.md", "LICENSE", "config.example.toml", "intents.example.toml", "references", "docs", "scripts")
+EVENTS = (
+    ("SessionStart", "", "session", 5),
+    ("UserPromptSubmit", "", "prompt", 5),
+    ("PostToolUse", "AskUserQuestion", "answer", 5),
+    ("PostToolUse", "SendMessage|Agent", "routed", 6),
+    ("Stop", "", "stop", 5),
+)
+IGNORE = shutil.ignore_patterns("__pycache__", "*.pyc", ".pytest_cache", ".ruff_cache", ".mypy_cache", "data")
+
+
+def sources() -> dict[str, list[Path]]:
+    """Skill name -> the paths copied into `<dir>/<name>/`, from a clone or from the wheel's package data."""
+    root = config.SKILL_DIR
+    extra = root if (root / "skills").is_dir() else root.parent
+    return {
+        "hub": [root / n for n in HUB_FILES if (root / n).exists()],
+        "hub-mep": [extra / "skills" / "hub-mep"] if (extra / "skills" / "hub-mep").is_dir() else [extra / "hub-mep"],
+        "hubkit-setup": [extra / "skills" / "hubkit-setup"] if (extra / "skills" / "hubkit-setup").is_dir() else [extra / "hubkit-setup"],
+    }
+
+
+def install_skills(target: Path) -> list[str]:
+    """Copy the skills into `target`, replacing earlier copies of the same files. Returns one line per skill."""
+    out = []
+    for name, paths in sources().items():
+        dest = target / name
+        if dest.resolve() == config.SKILL_DIR.resolve():
+            out.append(f"{name}: already the running copy, left alone")
+            continue
+        for p in paths:
+            if not p.exists():
+                raise FileNotFoundError(f"packaged skill file missing: {p}")
+            if p.is_dir() and p.name == name:  # a whole skill directory
+                shutil.copytree(p, dest, dirs_exist_ok=True, ignore=IGNORE)
+            elif p.is_dir():
+                shutil.copytree(p, dest / p.name, dirs_exist_ok=True, ignore=IGNORE)
+            else:
+                dest.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(p, dest / p.name)
+        out.append(f"{name}: installed in {dest}")
+    return out
+
+
+def hooks_block(skills_dir: str, merge_guard: bool = False) -> str:
+    """The `hooks` JSON for settings.json: each hook runs the hub skill's script, and says so if the script is missing."""
+    script = f"{skills_dir.rstrip('/')}/hub/scripts/hubkit"
+    hooks: dict[str, list[dict]] = {}
+    events = [*EVENTS, *((("PreToolUse", "Bash", "pretool", 5),) if merge_guard else ())]
+    for event, matcher, name, timeout in events:
+        cmd = f'[ -f "{script}" ] || echo "hubkit: script missing at {script}"; python3 "{script}" hook {name}'
+        group: dict = {"hooks": [{"type": "command", "command": cmd, "timeout": timeout}]}
+        if matcher:
+            group = {"matcher": matcher, **group}
+        hooks.setdefault(event, []).append(group)
+    return json.dumps({"hooks": hooks}, indent=2)