portawhip 0.1.0

package/adapters/hooks/universal-hook.mjs

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+// One hook body, many host adapters.
+//
+// Host config files should call this script with:
+//   node adapters/hooks/universal-hook.mjs --host <host-id> --event <logical-event>
+//
+// Logical events:
+//   user_prompt -> route capabilities and inject additionalContext
+//   post_tool   -> mark suggested capabilities as used
+
+import { existsSync } from "node:fs";
+import spawn from "cross-spawn";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, join, isAbsolute } from "node:path";
+import { loadIndex, readCachedIndex } from "../../core/registry/registry.mjs";
+import { runRoute } from "../../core/router/route-entry.mjs";
+import { pointerFor } from "../../core/registry/capability-docs.mjs";
+import { loadConfig } from "../../core/state/config.mjs";
+import { computeFactors, logEvent, readEvents } from "../../core/state/feedback.mjs";
+import { stackFactors, combineFactors } from "../../core/state/stack-detect.mjs";
+import { readActiveSelection, resolveRecipePaths } from "../../core/state/bundle-state.mjs";
+import { isSyntheticPrompt } from "../../core/router/prompt-hygiene.mjs";
+
+const ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+// Whatever bundles were opted into via `scripts/bundles.mjs select` (foundry
+// + roles), resolved in front of this repo's own recipe.yaml — defaults to
+// just recipe.yaml when nothing has been selected (today's behavior).
+const RECIPE_PATHS = resolveRecipePaths(ROOT, readActiveSelection(ROOT));
+const CONFIG_PATH = join(ROOT, "router.config.yaml");
+const MIN_PROMPT_LEN = 8;
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i += 1) {
+    if (argv[i].startsWith("--")) {
+      args[argv[i].slice(2)] = argv[i + 1];
+      i += 1;
+    }
+  }
+  return args;
+}
+
+async function readStdinJson() {
+  const raw = await new Promise((res, rej) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => (data += chunk));
+    process.stdin.on("end", () => res(data));
+    process.stdin.on("error", rej);
+  });
+  const text = raw.replace(/^\uFEFF/, "").trim();
+  return text ? JSON.parse(text) : {};
+}
+
+function payloadCwd(payload) {
+  return payload.cwd || process.cwd();
+}
+
+function promptFromPayload(payload) {
+  return (payload.prompt || payload.user_prompt || payload.input?.prompt || "").trim();
+}
+
+function readinessNote(hit, cwd) {
+  if (!hit.readyMarker) return "";
+  const ready = existsSync(join(cwd, hit.readyMarker));
+  return ready ? "" : ` (not set up here - run \`${hit.readyHint ?? "see docs"}\`)`;
+}
+
+// A bare pointer alone doesn't get acted on. Verified live (2026-07-06):
+// this repo's own push hook correctly suggested workspace-surface-audit and
+// configure-ecc on every turn of a session about diagnosing this project's
+// own hooks — genuinely relevant — and neither was ever invoked. The
+// rendered line gave a bare path/name with no invocation syntax, so it read
+// as background info, not a directive. adapters/instructions/generate.mjs
+// already proved the fix for the sibling problem (route() itself never
+// being called): be maximally explicit and host-aware, not more
+// descriptive. Same principle here, generic over kind/host — never a
+// specific tool name hardcoded, so this scales to whatever the caller has
+// installed.
+export function actionDirective(hit, host) {
+  if (hit.kind === "skill") {
+    return host === "claude-code"
+      ? `invoke now via the Skill tool (skill: "${hit.id}")`
+      : `read and follow this skill's instructions now: ${hit.pointer}`;
+  }
+  if (hit.kind === "agent") {
+    return host === "claude-code"
+      ? `delegate now via the Agent tool (subagent_type: "${hit.id}")`
+      : `use this agent capability now if relevant: ${hit.pointer}`;
+  }
+  if (hit.type === "mcp") {
+    return host === "claude-code"
+      ? `call its MCP tool directly now (tool names start with "mcp__${hit.id}__"; if not shown as callable yet, call ToolSearch with query "${hit.id}" first)`
+      : `call this MCP tool directly now if relevant`;
+  }
+  // cli (and any other pointer-bearing type): the pointer is already a
+  // runnable shell command - see capability-docs.mjs's pointerFor.
+  return `run it directly now: ${hit.pointer}`;
+}
+
+// Every "suggested" event is already logged per-sessionId (see the bottom
+// of userPrompt()) purely for computeFactors' boost/decay signal - never
+// read back to affect what gets rendered. Found live (2026-07-06): the
+// mcp directive's ToolSearch-fallback clause alone costs ~150 chars, and
+// full lines repeat every single turn a capability keeps matching, even
+// within the same session where the agent was already told this once.
+// Reusing that existing log to render tersely on repeat costs nothing new
+// (no state to add). Extended 2026-07-09 from a Set to per-id counts:
+// mention 1 renders full, mention 2 renders terse, then the id goes SILENT
+// for the session (interrupt budget - an assistant that reminds twice and
+// then shuts up, instead of nagging every turn a capability keeps matching).
+function sessionSuggestedCounts(root, sessionId) {
+  const counts = new Map();
+  if (!sessionId) return counts;
+  for (const e of readEvents(root)) {
+    if (e.type !== "suggested" || e.sessionId !== sessionId) continue;
+    counts.set(e.id, (counts.get(e.id) ?? 0) + 1);
+  }
+  return counts;
+}
+
+// Returns {block, renderedIds}: only ids actually shown to the model get
+// logged as "suggested" (previously every routed hit was logged even when
+// the char budget dropped its line - phantom suggestions the model never
+// saw, each counting as an "ignored" outcome in computeFactors).
+function formatBlock(result, budgetChars, cwd, host, mentionCounts, maxMentions) {
+  const lines = [];
+  const renderedIds = [];
+  let used = 0;
+  for (const hit of result) {
+    const mentions = mentionCounts.get(hit.id) ?? 0;
+    if (mentions >= maxMentions) continue; // interrupt budget spent for this session
+    const line =
+      mentions > 0
+        ? `- ${hit.id} - still relevant, use it again if applicable`
+        : `- ${hit.id} - ${hit.how_to_use}${readinessNote(hit, cwd)} - ${actionDirective(hit, host)}`;
+    if (used + line.length > budgetChars && lines.length > 0) break;
+    lines.push(line);
+    renderedIds.push(hit.id);
+    used += line.length;
+  }
+  return { block: lines.join("\n"), renderedIds };
+}
+
+function outputAdditionalContext(host, nativeEvent, additionalContext) {
+  const hookEventName = nativeEvent || (host === "gemini-cli" ? "BeforeAgent" : "UserPromptSubmit");
+  return {
+    hookSpecificOutput: {
+      hookEventName,
+      additionalContext,
+    },
+  };
+}
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function resolveId(index, toolName, toolInput) {
+  const mcpMatch = /^mcp[_]{1,2}([^_]+)[_]{1,2}/.exec(toolName || "");
+  if (mcpMatch) {
+    const id = mcpMatch[1];
+    return index.entries.some((e) => e.id === id && e.type === "mcp") ? id : null;
+  }
+
+  // Skill/Agent invocations are how MOST suggestions actually get acted on
+  // (352 skills + 90 agents vs 11 mcp/11 cli in today's index), yet neither
+  // had a branch here - so a suggested skill being used never logged a
+  // "used" event, boost never fired, and the 2026-07-09 hit-rate audit
+  // (4/26) was measuring with one eye shut. Host invocations may be
+  // plugin-namespaced ("ecc:code-review") while registry ids are plain
+  // slugs - match both the raw arg and the part after the last colon.
+  if (toolName === "Skill" || toolName === "Agent") {
+    const wantType = toolName === "Skill" ? "skill" : "agent";
+    const arg = String(
+      (toolName === "Skill" ? toolInput?.skill : toolInput?.subagent_type) ?? "",
+    );
+    if (!arg) return null;
+    const bare = arg.includes(":") ? arg.slice(arg.lastIndexOf(":") + 1) : arg;
+    const hit = index.entries.find((e) => e.type === wantType && (e.id === arg || e.id === bare));
+    return hit?.id ?? null;
+  }
+
+  if (["Read", "read_file"].includes(toolName)) {
+    const filePath = (toolInput?.file_path || toolInput?.path || "").replace(/\\/g, "/");
+    if (!filePath) return null;
+    const hit = index.entries.find(
+      (e) => e.type === "skill" && e.path && filePath.includes(String(e.path).replace(/\\/g, "/")),
+    );
+    return hit?.id ?? null;
+  }
+
+  if (["Bash", "run_shell_command", "bash"].includes(toolName)) {
+    const command = toolInput?.command || toolInput?.cmd || "";
+    // name comes from the registry (route.binary/source), not the tool call
+    // itself, but a CLI binary name can still contain regex metacharacters
+    // (e.g. "g++") - unescaped, that either throws (an uncaught exception
+    // here propagates out of postTool(), silently disabling pull-mode
+    // matching for every entry, not just this one - main() fails open with
+    // an empty catch) or matches something nonsensical.
+    const hit = index.entries.find((e) => {
+      if (e.type !== "cli") return false;
+      const name = e.route?.binary ?? e.source;
+      return name && new RegExp(`\\b${escapeRegExp(name)}\\b`, "i").test(command);
+    });
+    return hit?.id ?? null;
+  }
+
+  return null;
+}
+
+function toolFields(payload) {
+  return {
+    toolName: payload.tool_name || payload.toolName || payload.tool || payload.input?.tool || "",
+    toolInput: payload.tool_input || payload.toolInput || payload.args || payload.input?.tool_input || {},
+  };
+}
+
+async function userPrompt(payload, args) {
+  const prompt = promptFromPayload(payload);
+  if (prompt.length < MIN_PROMPT_LEN || prompt.startsWith("/")) return;
+  // Harness-generated payloads (task notifications, system reminders) arrive
+  // through the same UserPromptSubmit channel as real typing - routing them
+  // was 81% of all suggested events and pure decay-noise for computeFactors
+  // (see core/prompt-hygiene.mjs for the live numbers).
+  if (isSyntheticPrompt(prompt)) return;
+
+  const config = loadConfig(CONFIG_PATH);
+  // Workstream A: a push hook sees only the raw prompt, not the agent's
+  // reasoned task summary. The characterization spikes proved no lexical or
+  // embedding threshold can reliably separate meta-discussion from a real
+  // capability request, so unsolicited push stays silent by default. The env
+  // override is a scoped rollback switch; it never changes retrieval itself.
+  const pushMode = process.env.PORTAWHIP_PUSH_MODE === "legacy" ? "legacy" : config.pushMode;
+  if (pushMode === "silent") return;
+  const index = await loadIndex(RECIPE_PATHS);
+  const graphPath =
+    config.graphPath && !isAbsolute(config.graphPath) ? join(ROOT, config.graphPath) : config.graphPath;
+  const factors = combineFactors(computeFactors(ROOT), stackFactors(index, payloadCwd(payload)));
+  // Dense retrieval (core/dense-embedder.mjs) loads a 500MB+ model on first
+  // use - fine for the long-lived MCP server/CLI, but this hook is a fresh
+  // subprocess per prompt (see hook-stub.mjs), so it would pay that cold
+  // load on every keystroke. Push mode stays sparse+peakedness-gate only;
+  // dense is opt-in for callers that can amortize the load across calls.
+  const routed = await runRoute(index, prompt, {
+    ...config,
+    graphPath,
+    factors,
+    denseEnabled: false,
+    mode: "push",
+    pushMode,
+  });
+  if (!routed || routed.length === 0) return;
+
+  // Push precision gate (2026-07-09): an unsolicited interruption needs a
+  // much higher bar than a solicited MCP route() lookup - see
+  // router.config.yaml's pushMinConfidence comment (alert fatigue). Curated
+  // required-tier entries keep their deliberately-authored pass.
+  const result = routed.filter(
+    (hit) => hit.tier === "required" || hit.confidence >= config.pushMinConfidence,
+  );
+  if (result.length === 0) return;
+
+  const mentionCounts = sessionSuggestedCounts(ROOT, payload.session_id ?? null);
+  const { block, renderedIds } = formatBlock(
+    result,
+    config.pushBudgetChars,
+    payloadCwd(payload),
+    args.host,
+    mentionCounts,
+    config.pushMaxMentionsPerSession,
+  );
+  if (!block) return;
+
+  for (const id of renderedIds) {
+    logEvent(ROOT, { type: "suggested", id, prompt, sessionId: payload.session_id ?? null });
+  }
+
+  process.stdout.write(JSON.stringify(outputAdditionalContext(args.host, args.nativeEvent, block)));
+}
+
+// Soft nudge only — hooks must stay fail-open (see main()'s catch below), so
+// this never blocks the tool call that already ran. It just tells the model
+// a harness capability covers what it just did by hand, for next time.
+function neverSuggested(root, id) {
+  return !readEvents(root).some((e) => e.type === "suggested" && e.id === id);
+}
+
+async function postTool(payload, args) {
+  const index = readCachedIndex(RECIPE_PATHS);
+  if (!index) return;
+  const { toolName, toolInput } = toolFields(payload);
+  const id = resolveId(index, toolName, toolInput);
+  if (!id) return;
+
+  const wasIgnored = neverSuggested(ROOT, id);
+  logEvent(ROOT, { type: "used", id, tool: toolName, sessionId: payload.session_id ?? null });
+  if (!wasIgnored) return;
+
+  const entry = index.entries.find((e) => e.id === id);
+  if (!entry) return;
+  // Raw index entries only carry route.description/path/source — how_to_use
+  // and pointer are fields scorer.mjs constructs for the FORMATTED route()
+  // output, not present here. Reading them off the raw entry silently
+  // produced "undefined - undefined" (found live 2026-07-05, first time a
+  // curated CLI entry with a `binary` field actually matched a Bash command).
+  const description = entry.route?.description ?? "";
+  const pointer = pointerFor(entry) ?? "";
+  const nudge = `Note: "${toolName}" just did something \`${id}\` already covers - ${description} - ${pointer}. Prefer it next time.`;
+  process.stdout.write(JSON.stringify(outputAdditionalContext(args.host, args.nativeEvent, nudge)));
+}
+
+// Session start: fire-and-forget the auto-sync worker (decision D). This hook
+// must return instantly, so it detaches a fully independent process and
+// unrefs it — the worker throttles/locks and fans already-canonical
+// capabilities out to all hosts on its own, logging to
+// .hp-state/auto-sync.log. Import stays manual; this only propagates what is
+// already canonical. Any failure stays inside the worker; the session is
+// never blocked or delayed.
+function sessionStart() {
+  try {
+    const child = spawn.spawn(process.execPath, [join(ROOT, "scripts", "sync", "auto-sync.mjs")], {
+      cwd: ROOT,
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+  } catch {
+    // fail-open: never block session start on a spawn error
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (args.event === "session_start") {
+    sessionStart();
+    return;
+  }
+  const payload = await readStdinJson();
+  if (args.event === "user_prompt") await userPrompt(payload, args);
+  if (args.event === "post_tool") await postTool(payload, args);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch(() => {
+    // Hooks must fail open; a sync-layer bug should never block the user.
+  });
+}

package/adapters/hooks/universal-hook.test.mjs

@@ -0,0 +1,294 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync, rmSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { actionDirective, resolveId } from "./universal-hook.mjs";
+
+// Integration-level: runs the real hook as a subprocess against this
+// repo's real recipe.yaml (same style as core/router.test.mjs's
+// discovery tests, which already exercise the live machine state).
+// Feedback events land in this repo's real .hp-state/feedback, so every
+// test needs a clean slate to assert against - but a plain rm here was
+// found live (2026-07-06) to permanently delete real dogfood events
+// (this repo's own push-hook firing during actual use), the first time
+// this suite happened to run right after a real hook fire. Snapshot and
+// restore instead of deleting, so running tests never costs real history.
+const ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const HOOK = join(ROOT, "adapters", "hooks", "universal-hook.mjs");
+const FEEDBACK_PATH = join(ROOT, ".hp-state", "feedback", "events.jsonl");
+
+let feedbackBackup;
+
+function clearFeedback() {
+  feedbackBackup = existsSync(FEEDBACK_PATH) ? readFileSync(FEEDBACK_PATH, "utf8") : null;
+  if (existsSync(FEEDBACK_PATH)) rmSync(FEEDBACK_PATH);
+}
+
+function restoreFeedback() {
+  if (existsSync(FEEDBACK_PATH)) rmSync(FEEDBACK_PATH);
+  if (feedbackBackup != null) {
+    mkdirSync(dirname(FEEDBACK_PATH), { recursive: true });
+    writeFileSync(FEEDBACK_PATH, feedbackBackup);
+  }
+}
+
+const LEGACY_PUSH_ENV = { PORTAWHIP_PUSH_MODE: "legacy" };
+
+function runHook(args, payload, { env = {} } = {}) {
+  const result = spawnSync(process.execPath, [HOOK, ...args], {
+    input: JSON.stringify(payload ?? {}),
+    encoding: "utf8",
+    cwd: ROOT,
+    env: { ...process.env, ...env },
+  });
+  return result.stdout.trim();
+}
+
+test("universal-hook: user_prompt is silent by default even on a confident match", () => {
+  clearFeedback();
+  try {
+    const stdout = runHook(
+      ["--host", "claude-code", "--event", "user_prompt", "--nativeEvent", "UserPromptSubmit"],
+      { prompt: "search codebase for the word foo" },
+    );
+    assert.equal(stdout, "");
+    assert.ok(!existsSync(FEEDBACK_PATH), "silent push must not log a suggested event");
+  } finally {
+    restoreFeedback();
+  }
+});
+
+test("universal-hook: raw meta-prompts stay silent and create no suggestion events", () => {
+  clearFeedback();
+  try {
+    const args = ["--host", "claude-code", "--event", "user_prompt", "--nativeEvent", "UserPromptSubmit"];
+    const prompts = [
+      "what are the tradeoffs of cross-host agent capability loading",
+      "how should a router avoid token bloat when many tools are installed",
+    ];
+    for (const prompt of prompts) assert.equal(runHook(args, { prompt }), "", prompt);
+    assert.ok(!existsSync(FEEDBACK_PATH), "silent meta-prompts must not log suggested events");
+  } finally {
+    restoreFeedback();
+  }
+});
+
+test("universal-hook: legacy push is an explicit opt-in for rollback", () => {
+  clearFeedback();
+  try {
+    const stdout = runHook(
+      ["--host", "claude-code", "--event", "user_prompt", "--nativeEvent", "UserPromptSubmit"],
+      { prompt: "search codebase for the word foo" },
+      { env: LEGACY_PUSH_ENV },
+    );
+    assert.ok(stdout, "expected non-empty stdout for a matching prompt");
+    const parsed = JSON.parse(stdout);
+    assert.equal(parsed.hookSpecificOutput.hookEventName, "UserPromptSubmit");
+    assert.ok(parsed.hookSpecificOutput.additionalContext.includes("ripgrep"));
+  } finally {
+    restoreFeedback();
+  }
+});
+
+test("universal-hook: user_prompt renders tersely once a capability was already suggested this session", () => {
+  clearFeedback();
+  try {
+    const args = ["--host", "claude-code", "--event", "user_prompt", "--nativeEvent", "UserPromptSubmit"];
+    const payload = { prompt: "search codebase for the word foo", session_id: "test-session-repeat" };
+
+    const first = JSON.parse(runHook(args, payload, { env: LEGACY_PUSH_ENV }));
+    assert.match(first.hookSpecificOutput.additionalContext, /ripgrep/);
+    assert.match(first.hookSpecificOutput.additionalContext, /run it directly now/);
+
+    const second = JSON.parse(runHook(args, payload, { env: LEGACY_PUSH_ENV }));
+    assert.match(second.hookSpecificOutput.additionalContext, /- ripgrep - still relevant, use it again/);
+    assert.doesNotMatch(second.hookSpecificOutput.additionalContext, /run it directly now/);
+  } finally {
+    restoreFeedback();
+  }
+});
+
+test("universal-hook: user_prompt stays silent on a short/unrelated prompt", () => {
+  clearFeedback();
+  try {
+    const stdout = runHook(
+      ["--host", "claude-code", "--event", "user_prompt", "--nativeEvent", "UserPromptSubmit"],
+      { prompt: "hi" },
+    );
+    assert.equal(stdout, "");
+  } finally {
+    restoreFeedback();
+  }
+});
+
+test("universal-hook: gemini-cli defaults hookEventName to BeforeAgent when no nativeEvent is passed", () => {
+  clearFeedback();
+  try {
+    const stdout = runHook(
+      ["--host", "gemini-cli", "--event", "user_prompt"],
+      { prompt: "search codebase for the word foo" },
+      { env: LEGACY_PUSH_ENV },
+    );
+    assert.ok(stdout);
+    const parsed = JSON.parse(stdout);
+    assert.equal(parsed.hookSpecificOutput.hookEventName, "BeforeAgent");
+  } finally {
+    restoreFeedback();
+  }
+});
+
+test("actionDirective: skill on claude-code names the Skill tool by id", () => {
+  const directive = actionDirective({ kind: "skill", id: "workspace-surface-audit", pointer: "/some/path" }, "claude-code");
+  assert.match(directive, /Skill tool/);
+  assert.match(directive, /"workspace-surface-audit"/);
+});
+
+test("actionDirective: skill on a non-claude-code host falls back to reading the pointer", () => {
+  const directive = actionDirective({ kind: "skill", id: "workspace-surface-audit", pointer: "/some/path" }, "gemini-cli");
+  assert.doesNotMatch(directive, /Skill tool/);
+  assert.match(directive, /\/some\/path/);
+});
+
+test("actionDirective: mcp on claude-code gives the mcp__<id>__ prefix and a ToolSearch fallback", () => {
+  const directive = actionDirective({ kind: "tool", type: "mcp", id: "playwright", pointer: "@playwright/mcp@latest" }, "claude-code");
+  assert.match(directive, /mcp__playwright__/);
+  assert.match(directive, /ToolSearch/);
+});
+
+test("actionDirective: mcp on a non-claude-code host stays generic, no invented syntax", () => {
+  const directive = actionDirective({ kind: "tool", type: "mcp", id: "playwright", pointer: "@playwright/mcp@latest" }, "codex");
+  assert.doesNotMatch(directive, /mcp__/);
+});
+
+test("actionDirective: agent on claude-code names the Agent tool by subagent_type", () => {
+  const directive = actionDirective({ kind: "agent", id: "e2e-runner", pointer: "/agents/e2e-runner.md" }, "claude-code");
+  assert.match(directive, /Agent tool/);
+  assert.match(directive, /"e2e-runner"/);
+});
+
+test("actionDirective: cli surfaces the pointer as a runnable command", () => {
+  const directive = actionDirective({ kind: "tool", type: "cli", id: "ripgrep", pointer: "mise exec -- ripgrep" }, "claude-code");
+  assert.match(directive, /mise exec -- ripgrep/);
+});
+
+test("resolveId: a CLI binary name with a regex metacharacter still matches its own command", () => {
+  // "." is unescaped-regex "any character" - a dot-containing name sitting
+  // between word characters (unlike a trailing "g++") still hits \b on
+  // both sides, so this exercises the escaping fix without the separate,
+  // pre-existing \b-at-a-symbol-edge limitation (word boundaries don't
+  // fire between two non-word characters, e.g. "+" then a space - a
+  // different, lower-priority gap left as-is since no registered CLI name
+  // ends in a symbol today).
+  const index = {
+    entries: [{ id: "foo-dot-bar", type: "cli", source: "foo.bar", route: {} }],
+  };
+  assert.doesNotThrow(() => {
+    const id = resolveId(index, "Bash", { command: "foo.bar --version" });
+    assert.equal(id, "foo-dot-bar");
+  });
+});
+
+test("resolveId: an unescaped '.' would false-match a lookalike command; escaped it does not", () => {
+  const index = {
+    entries: [{ id: "foo-dot-bar", type: "cli", source: "foo.bar", route: {} }],
+  };
+  // Unescaped, "." in the regex means "any character" - "fooXbar" would
+  // wrongly match a binary named "foo.bar". Escaped, it correctly doesn't.
+  const id = resolveId(index, "Bash", { command: "run fooXbar now" });
+  assert.equal(id, null);
+});
+
+test("universal-hook: third mention of the same id in one session is silent (interrupt budget)", () => {
+  clearFeedback();
+  try {
+    const args = ["--host", "claude-code", "--event", "user_prompt", "--nativeEvent", "UserPromptSubmit"];
+    const payload = { prompt: "search codebase for the word foo", session_id: "test-session-budget" };
+
+    const first = JSON.parse(runHook(args, payload, { env: LEGACY_PUSH_ENV }));
+    assert.match(first.hookSpecificOutput.additionalContext, /run it directly now/);
+    const second = JSON.parse(runHook(args, payload, { env: LEGACY_PUSH_ENV }));
+    assert.match(second.hookSpecificOutput.additionalContext, /still relevant/);
+    // Budget (pushMaxMentionsPerSession=2) spent: full once, terse once, then silence.
+    const third = runHook(args, payload, { env: LEGACY_PUSH_ENV });
+    assert.equal(third, "");
+  } finally {
+    restoreFeedback();
+  }
+});
+
+test("universal-hook: user_prompt stays silent on a harness-generated task-notification payload", () => {
+  clearFeedback();
+  try {
+    // Real shape from a live session: a background-task completion notice
+    // that arrives through UserPromptSubmit. Long enough and vocabulary-rich
+    // enough that it WOULD route (21/26 historical suggested events were
+    // exactly this) - only the synthetic-prompt gate keeps it silent.
+    const stdout = runHook(
+      ["--host", "claude-code", "--event", "user_prompt", "--nativeEvent", "UserPromptSubmit"],
+      {
+        prompt:
+          "<task-notification>\n<task-id>b9ugezqg8</task-id>\n<summary>Background command \"search codebase for the word foo\" completed (exit code 0)</summary>\n</task-notification>",
+      },
+    );
+    assert.equal(stdout, "");
+    assert.ok(!existsSync(FEEDBACK_PATH), "no suggested events should be logged for synthetic prompts");
+  } finally {
+    restoreFeedback();
+  }
+});
+
+test("universal-hook: post_tool with the Skill tool logs a used event for the skill id", () => {
+  clearFeedback();
+  try {
+    runHook(["--host", "claude-code", "--event", "post_tool"], {
+      tool_name: "Skill",
+      tool_input: { skill: "workspace-surface-audit" },
+    });
+    assert.ok(existsSync(FEEDBACK_PATH));
+    const contents = readFileSync(FEEDBACK_PATH, "utf8");
+    assert.ok(contents.includes('"type":"used"'));
+    assert.ok(contents.includes('"id":"workspace-surface-audit"'));
+  } finally {
+    restoreFeedback();
+  }
+});
+
+test("resolveId: a plugin-namespaced Skill invocation matches the plain-slug registry id", () => {
+  const index = {
+    entries: [{ id: "code-review", type: "skill", route: {} }],
+  };
+  assert.equal(resolveId(index, "Skill", { skill: "ecc:code-review" }), "code-review");
+});
+
+test("resolveId: an Agent invocation matches an agent entry by subagent_type, not a same-named skill", () => {
+  const index = {
+    entries: [
+      { id: "e2e-runner", type: "skill", route: {} },
+      { id: "e2e-runner", type: "agent", route: {} },
+    ],
+  };
+  // Both exist; the Agent tool must attribute to the agent-type entry.
+  const id = resolveId(index, "Agent", { subagent_type: "ecc:e2e-runner" });
+  assert.equal(id, "e2e-runner");
+  // And an id that only exists as a skill must NOT match via the Agent tool.
+  const skillOnly = { entries: [{ id: "pdf", type: "skill", route: {} }] };
+  assert.equal(resolveId(skillOnly, "Agent", { subagent_type: "pdf" }), null);
+});
+
+test("universal-hook: post_tool with an mcp__<id>__ tool name logs a used event for that id", () => {
+  clearFeedback();
+  try {
+    runHook(["--host", "claude-code", "--event", "post_tool"], {
+      tool_name: "mcp__context7__resolve-library-id",
+      tool_input: {},
+    });
+    assert.ok(existsSync(FEEDBACK_PATH));
+    const contents = readFileSync(FEEDBACK_PATH, "utf8");
+    assert.ok(contents.includes('"type":"used"'));
+    assert.ok(contents.includes('"id":"context7"'));
+  } finally {
+    restoreFeedback();
+  }
+});