chainlesschain 0.162.148 → 0.162.149

package/src/lib/plugin-runtime/trust.js

@@ -0,0 +1,140 @@
+/**
+ * Plugin trust gating (Phase 3.3f) — decide whether a plugin's CODE-BEARING
+ * components (hooks that run shell, LSP servers that spawn binaries) are allowed
+ * to execute.
+ *
+ * Threat model: `cc plugin add owner/repo` and, worse, a cloned repo that ships
+ * a project-scope plugin under `.chainlesschain/plugins/`, could run arbitrary
+ * commands the moment the agent starts. So:
+ *
+ *   - user / local scope  → TRUSTED. The developer installed it on their own
+ *     machine (same consent model as an npm dependency's lifecycle scripts).
+ *   - project scope       → UNTRUSTED until the user explicitly trusts it, since
+ *     it can arrive with a git clone. Trust is pinned to the exact version, so a
+ *     later version bump re-requires consent.
+ *
+ * Trust is recorded in the USER data dir (never in the repo), keyed by
+ * `<scope>:<name>` → { version, trustedAt }.
+ *
+ * Only code execution is gated here. Declarative components (skills are prompts,
+ * mcp/settings are config) load regardless; this is specifically about not
+ * running untrusted SHELL/binaries behind the user's back.
+ */
+
+import fs from "fs";
+import path from "path";
+import { getElectronUserDataDir } from "../paths.js";
+
+export const _deps = {
+  existsSync: fs.existsSync,
+  readFileSync: fs.readFileSync,
+  writeFileSync: fs.writeFileSync,
+  mkdirSync: fs.mkdirSync,
+  now: () => new Date().toISOString(),
+  // Path of the trust store; injectable so unit tests never touch the real
+  // user-data dir.
+  storePath: () => path.join(getElectronUserDataDir(), "plugin-trust.json"),
+};
+
+const AUTO_TRUSTED_SCOPES = new Set(["user", "local"]);
+
+export function loadTrustStore() {
+  try {
+    const p = _deps.storePath();
+    if (!_deps.existsSync(p)) return {};
+    const data = JSON.parse(_deps.readFileSync(p, "utf8"));
+    return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+function saveTrustStore(store) {
+  const p = _deps.storePath();
+  _deps.mkdirSync(path.dirname(p), { recursive: true });
+  _deps.writeFileSync(p, JSON.stringify(store, null, 2), "utf8");
+}
+
+function trustKey(scope, name) {
+  return `${scope}:${name}`;
+}
+
+/**
+ * May this plugin's code-bearing components run?
+ * @param {{ scope, name, version }} plugin
+ */
+export function isPluginTrusted(plugin) {
+  if (!plugin || !plugin.name) return false;
+  if (AUTO_TRUSTED_SCOPES.has(plugin.scope)) return true;
+  const entry = loadTrustStore()[trustKey(plugin.scope, plugin.name)];
+  return Boolean(entry && entry.version === plugin.version);
+}
+
+/** Trust a plugin (records the exact version). */
+export function trustPlugin(name, { scope = "project", version } = {}) {
+  if (!version) throw new Error("trustPlugin requires a version");
+  const store = loadTrustStore();
+  store[trustKey(scope, name)] = { version, trustedAt: _deps.now() };
+  saveTrustStore(store);
+  return { name, scope, version };
+}
+
+/** Revoke trust for a plugin at a scope. */
+export function untrustPlugin(name, { scope = "project" } = {}) {
+  const store = loadTrustStore();
+  const key = trustKey(scope, name);
+  const existed = Object.prototype.hasOwnProperty.call(store, key);
+  delete store[key];
+  saveTrustStore(store);
+  return { name, scope, removed: existed };
+}
+
+/** All trust entries (for `cc plugin trust --list`). */
+export function listTrust() {
+  return Object.entries(loadTrustStore()).map(([key, v]) => {
+    const idx = key.indexOf(":");
+    return {
+      scope: key.slice(0, idx),
+      name: key.slice(idx + 1),
+      version: v?.version || null,
+      trustedAt: v?.trustedAt || null,
+    };
+  });
+}
+
+/**
+ * Split discovered plugins into those whose code may run and those gated out.
+ * @returns {{ trusted: any[], skipped: any[] }}
+ */
+export function partitionByTrust(plugins) {
+  const trusted = [];
+  const skipped = [];
+  for (const p of plugins || []) {
+    (isPluginTrusted(p) ? trusted : skipped).push(p);
+  }
+  return { trusted, skipped };
+}
+
+// One-time stderr notice so a user isn't mystified when a project plugin's
+// hooks/servers silently don't run. Guarded so it prints at most once per
+// (component-kind) per process.
+const _warned = new Set();
+export function warnUntrustedOnce(names, kind) {
+  if (!names || names.length === 0) return;
+  if (_warned.has(kind)) return;
+  _warned.add(kind);
+  const list = [...new Set(names)].join(", ");
+  try {
+    process.stderr.write(
+      `[plugins] skipped ${kind} from untrusted project plugin(s): ${list}\n` +
+        `          run \`cc plugin trust <name>\` to enable them.\n`,
+    );
+  } catch {
+    /* stderr notice is best-effort */
+  }
+}
+
+/** Test hook: reset the one-time warning guard. */
+export function _resetTrustWarnings() {
+  _warned.clear();
+}

package/src/lib/sandbox-egress-proxy.js

@@ -0,0 +1,162 @@
+/**
+ * Sandbox egress-filtering proxy (Phase 1 enforcement).
+ *
+ * The domain policy in `sandbox-network-policy.js` DECIDES whether a host is
+ * reachable; this turns that decision into ENFORCEMENT against real
+ * subprocesses. A local forward proxy consults `evaluateNetworkAccess` for
+ * every request (plain HTTP) and CONNECT tunnel (HTTPS) and refuses the blocked
+ * ones. Point a sandboxed process's `HTTP_PROXY`/`HTTPS_PROXY` at it and its
+ * `curl`/`npm`/`pip`/`git`/`wget`/`fetch` traffic is filtered.
+ *
+ * This is a proxy-level control, not a kernel one: a tool that deliberately
+ * ignores proxy env can still open a raw socket, so a hard guarantee also needs
+ * OS network isolation (Docker `--network`, bwrap netns). But it is fully
+ * cross-platform (works on Windows, no root) and closes the common egress path
+ * that the domain allow/deny list is actually about.
+ */
+
+import http from "node:http";
+import net from "node:net";
+import { evaluateNetworkAccess } from "./sandbox-network-policy.js";
+
+/**
+ * Build the proxy env vars a child process needs to route through the proxy.
+ * `NO_PROXY` is intentionally empty so nothing bypasses the filter.
+ * @param {number} port
+ * @param {string} host  address the CHILD uses to reach the proxy (for a Docker
+ *                       container this is `host.docker.internal`, not localhost)
+ */
+export function proxyEnv(port, host = "127.0.0.1") {
+  const url = `http://${host}:${port}`;
+  return {
+    HTTP_PROXY: url,
+    HTTPS_PROXY: url,
+    ALL_PROXY: url,
+    http_proxy: url,
+    https_proxy: url,
+    all_proxy: url,
+    NO_PROXY: "",
+    no_proxy: "",
+  };
+}
+
+/**
+ * Create (but do not yet listen on) an egress-filtering proxy for a policy.
+ * @param {object} policy  { allowedDomains?, deniedDomains?, allowPrivate? }
+ * @param {object} [opts]  { onDecision?(info), bindHost? }
+ * @returns {{ listen():Promise<{port,env,server}>, close():Promise<void>,
+ *             server:import('http').Server, blocked:number, allowed:number }}
+ */
+export function createEgressProxy(policy = {}, opts = {}) {
+  const bindHost = opts.bindHost || "127.0.0.1";
+  const state = { blocked: 0, allowed: 0 };
+  const decide = (target, kind) => {
+    const verdict = evaluateNetworkAccess(target, policy);
+    if (verdict.allowed) state.allowed += 1;
+    else state.blocked += 1;
+    if (typeof opts.onDecision === "function") {
+      try {
+        opts.onDecision({ kind, target, ...verdict });
+      } catch {
+        /* observation is best-effort */
+      }
+    }
+    return verdict;
+  };
+
+  const server = http.createServer((req, res) => {
+    // A forward-proxy request carries the absolute URL in the request line.
+    const verdict = decide(req.url, "http");
+    if (!verdict.allowed) {
+      res.writeHead(403, { "content-type": "text/plain" });
+      res.end(`egress blocked: ${verdict.host} — ${verdict.reason}\n`);
+      return;
+    }
+    let u;
+    try {
+      u = new URL(req.url);
+    } catch {
+      res.writeHead(400, { "content-type": "text/plain" });
+      res.end("bad request target\n");
+      return;
+    }
+    const upstream = http.request(
+      {
+        hostname: u.hostname,
+        port: u.port || 80,
+        path: `${u.pathname}${u.search}`,
+        method: req.method,
+        headers: req.headers,
+      },
+      (upRes) => {
+        res.writeHead(upRes.statusCode || 502, upRes.headers);
+        upRes.pipe(res);
+      },
+    );
+    upstream.on("error", () => {
+      if (!res.headersSent)
+        res.writeHead(502, { "content-type": "text/plain" });
+      res.end("upstream error\n");
+    });
+    req.pipe(upstream);
+  });
+
+  // HTTPS (and any TLS) goes through CONNECT — tunnel only allowed hosts.
+  server.on("connect", (req, clientSocket, head) => {
+    const verdict = decide(req.url, "connect"); // req.url = "host:port"
+    if (!verdict.allowed) {
+      clientSocket.write(
+        "HTTP/1.1 403 Forbidden\r\n" +
+          "Content-Type: text/plain\r\n\r\n" +
+          `egress blocked: ${verdict.host} — ${verdict.reason}\n`,
+      );
+      clientSocket.end();
+      return;
+    }
+    const [host, portStr] = req.url.split(":");
+    const port = parseInt(portStr, 10) || 443;
+    const upstream = net.connect(port, host, () => {
+      clientSocket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+      if (head && head.length) upstream.write(head);
+      upstream.pipe(clientSocket);
+      clientSocket.pipe(upstream);
+    });
+    upstream.on("error", () => {
+      try {
+        clientSocket.end();
+      } catch {
+        /* already closed */
+      }
+    });
+    clientSocket.on("error", () => {
+      try {
+        upstream.destroy();
+      } catch {
+        /* already gone */
+      }
+    });
+  });
+
+  return {
+    server,
+    get blocked() {
+      return state.blocked;
+    },
+    get allowed() {
+      return state.allowed;
+    },
+    listen() {
+      return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, bindHost, () => {
+          server.removeListener("error", reject);
+          const port = server.address().port;
+          resolve({ port, env: proxyEnv(port), server });
+        });
+      });
+    },
+    close() {
+      return new Promise((resolve) => server.close(() => resolve()));
+    },
+  };
+}

package/src/lib/sandbox-network-policy.js

@@ -0,0 +1,134 @@
+/**
+ * Sandbox network domain policy (Phase 1) — decide whether a Shell subprocess is
+ * allowed to reach a given URL/host under `sandbox.network.allowedDomains` /
+ * `deniedDomains`. OS-level ENFORCEMENT is platform-specific (a proxy / seatbelt
+ * / bwrap egress filter), but the POLICY decision is pure, shared, and must get
+ * the tricky cases right — so it lives here, fully unit-tested:
+ *
+ *   - wildcard subdomains (`*.example.com` matches `api.example.com` AND the
+ *     apex `example.com`), exact hosts, and `*` (all);
+ *   - deny takes precedence over allow;
+ *   - default-DENY when an allowlist is set and the host isn't on it
+ *     (Phase 1 acceptance "未授权域名无法通过 curl/npm/pip 访问");
+ *   - private / loopback / link-local / metadata targets are blocked unless
+ *     explicitly allowed — an SSRF / DNS-rebinding guard, and it fixes the
+ *     `new URL()` IPv6-bracket gotcha where `[::1]` leaks brackets into the
+ *     hostname and defeats a naive string check.
+ */
+
+/** Extract a normalized lowercase host from a URL or bare host:port. */
+export function extractHost(target) {
+  if (target == null) return null;
+  let s = String(target).trim();
+  if (!s) return null;
+  // Try URL parse first (covers scheme://host:port/path, userinfo, etc.).
+  try {
+    // Add a scheme if it looks scheme-less so URL() can parse host:port.
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(s) ? s : `http://${s}`;
+    const u = new URL(withScheme);
+    s = u.hostname; // may be "[::1]" for IPv6 — normalize below
+  } catch {
+    // Not a URL — treat as a bare host, strip any :port.
+    s = s.replace(/:\d+$/, "");
+  }
+  // Strip IPv6 brackets ("[::1]" → "::1") — the documented SSRF gotcha.
+  if (s.startsWith("[") && s.endsWith("]")) s = s.slice(1, -1);
+  return s.toLowerCase() || null;
+}
+
+/** Does `host` match a domain `pattern` (`*`, `*.example.com`, or exact)? */
+export function matchesDomain(host, pattern) {
+  if (!host || !pattern) return false;
+  const p = String(pattern).trim().toLowerCase();
+  if (p === "*") return true;
+  if (p.startsWith("*.")) {
+    const base = p.slice(2);
+    // `*.example.com` matches subdomains AND the apex `example.com`.
+    return host === base || host.endsWith(`.${base}`);
+  }
+  return host === p;
+}
+
+function anyMatch(host, patterns) {
+  return (patterns || []).some((p) => matchesDomain(host, p));
+}
+
+/** Private / loopback / link-local / cloud-metadata target? (SSRF guard) */
+export function isPrivateHost(host) {
+  if (!host) return false;
+  const h = host.toLowerCase();
+  if (h === "localhost" || h.endsWith(".localhost")) return true;
+  // Cloud metadata endpoint.
+  if (h === "169.254.169.254" || h === "metadata.google.internal") return true;
+  // IPv6 loopback / unique-local / link-local.
+  if (h === "::1" || h === "::") return true;
+  if (/^f[cd][0-9a-f]{2}:/i.test(h)) return true; // fc00::/7 unique-local
+  if (/^fe80:/i.test(h)) return true; // link-local
+  // IPv4-mapped IPv6 (::ffff:127.0.0.1) — check the tail.
+  const mapped = h.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+  const ipv4 = mapped ? mapped[1] : h;
+  const m = ipv4.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (m) {
+    const [a, b] = [Number(m[1]), Number(m[2])];
+    if (a === 127) return true; // 127.0.0.0/8 loopback
+    if (a === 10) return true; // 10.0.0.0/8
+    if (a === 192 && b === 168) return true; // 192.168.0.0/16
+    if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12
+    if (a === 169 && b === 254) return true; // 169.254.0.0/16 link-local
+    if (a === 0) return true; // 0.0.0.0/8
+  }
+  return false;
+}
+
+/**
+ * Evaluate network access for a target under a policy.
+ *
+ * @param {string} target  URL or host (optionally with :port)
+ * @param {object} policy  { allowedDomains?:string[], deniedDomains?:string[],
+ *                           allowPrivate?:boolean }
+ * @returns {{ allowed:boolean, host:string|null, reason:string }}
+ */
+export function evaluateNetworkAccess(target, policy = {}) {
+  const allowed = policy.allowedDomains || [];
+  const denied = policy.deniedDomains || [];
+  const host = extractHost(target);
+  if (!host) {
+    return { allowed: false, host: null, reason: "unparseable target" };
+  }
+  // 1) Deny wins over everything.
+  if (anyMatch(host, denied)) {
+    return { allowed: false, host, reason: "denied by deniedDomains" };
+  }
+  // 2) A SPECIFIC (non-`*`) allow-list match overrides the private-host guard,
+  //    so an intentionally-allowed localhost/dev host still works. A bare `*`
+  //    does NOT — it means "all public domains", never internal/metadata.
+  const explicitNonStar = anyMatch(
+    host,
+    allowed.filter((p) => String(p).trim() !== "*"),
+  );
+  if (explicitNonStar) {
+    return { allowed: true, host, reason: "matched allowedDomains" };
+  }
+  // 3) Private / loopback / metadata targets are blocked unless allowed above.
+  if (isPrivateHost(host) && !policy.allowPrivate) {
+    return {
+      allowed: false,
+      host,
+      reason: "private/loopback target blocked (SSRF guard)",
+    };
+  }
+  // 4) A `*` (or any remaining) allow-list match → allow.
+  if (anyMatch(host, allowed)) {
+    return { allowed: true, host, reason: "matched allowedDomains" };
+  }
+  // 5) With an allow-list present, anything not on it is denied (default-deny).
+  if (allowed.length > 0) {
+    return {
+      allowed: false,
+      host,
+      reason: "not in allowedDomains (default-deny)",
+    };
+  }
+  // 6) No allow-list → permissive (deny-list + private guard still applied).
+  return { allowed: true, host, reason: "no allowlist (permissive)" };
+}

package/src/lib/sandbox-v2.js

@@ -5,6 +5,7 @@
 
 import crypto from "crypto";
 import { safeJsonParse } from "./safe-json.js";
+import { evaluateNetworkAccess } from "./sandbox-network-policy.js";
 import { createRequire } from "module";
 
 const _require = createRequire(import.meta.url);
@@ -158,11 +159,16 @@ function checkFilePermission(permissions, filePath, mode) {
 }
 
 function checkNetworkPermission(permissions, host) {
+  // Delegate to the shared domain policy: wildcard subdomains, deny-precedence,
+  // default-deny under an allowlist, URL/host normalization, and the SSRF /
+  // loopback / metadata guard (incl. the IPv6-bracket gotcha). The old check was
+  // exact-string only and let e.g. a URL or `[::1]` slip past.
   const net = permissions.network || {};
-  const denied = net.denied || [];
-  if (denied.includes(host)) return false;
-  const allowed = net.allowed || [];
-  return allowed.includes(host) || allowed.includes("*");
+  return evaluateNetworkAccess(host, {
+    allowedDomains: net.allowed || [],
+    deniedDomains: net.denied || [],
+    allowPrivate: net.allowPrivate === true,
+  }).allowed;
 }
 
 function checkSystemCallPermission(permissions, call) {

package/src/lib/settings-hook-events.cjs

@@ -19,6 +19,24 @@
 const { collectHooks } = require("./settings-hooks.cjs");
 const { runHooks } = require("./hook-runner.cjs");
 
+/**
+ * Split collected hooks into the blocking (sync) set and the fire-and-forget
+ * (`async: true`) set. Only NON-decision events should dispatch async hooks —
+ * an async hook can't gate a turn it no longer blocks, so a UserPromptSubmit
+ * hook that must be able to `block` should stay sync. The caller decides which
+ * events are eligible; this is just the partition.
+ * @returns {{ sync: Array, async: Array }}
+ */
+function partitionAsyncHooks(hooks) {
+  const sync = [];
+  const asyncHooks = [];
+  for (const h of hooks || []) {
+    if (h && h.async === true) asyncHooks.push(h);
+    else sync.push(h);
+  }
+  return { sync, async: asyncHooks };
+}
+
 /** Join the context emitted by the hooks that ran (additionalContext / plain stdout). */
 function aggregateContext(results) {
   const parts = [];
@@ -36,19 +54,32 @@ function aggregateContext(results) {
 /**
  * UserPromptSubmit settings hooks. A `block`/`ask` decision aborts the turn;
  * otherwise any emitted context is returned for the caller to inject.
+ *
+ * `async: true` hooks are EXCLUDED from this blocking run — they can't gate a
+ * turn they no longer block, so a fire-and-forget hook is dispatched separately
+ * (see dispatchAsyncHooks). This keeps the sync/decision path unchanged while a
+ * long-running check runs alongside the turn.
  * @returns {{ blocked:boolean, reason?:string, hook?:string, additionalContext:string|null }}
  */
-function runUserPromptSubmitHooks(settingsHooks, { prompt, cwd, sessionId } = {}) {
+function runUserPromptSubmitHooks(
+  settingsHooks,
+  { prompt, cwd, sessionId } = {},
+) {
   if (!settingsHooks) return { blocked: false, additionalContext: null };
   const matched = collectHooks(settingsHooks, "UserPromptSubmit", "");
   if (matched.length === 0) return { blocked: false, additionalContext: null };
+  const { sync } = partitionAsyncHooks(matched);
+  if (sync.length === 0) return { blocked: false, additionalContext: null };
   const payload = {
     hook_event_name: "UserPromptSubmit",
     prompt: String(prompt || ""),
     cwd,
     session_id: sessionId || null,
   };
-  const outcome = runHooks(matched, payload, { cwd, event: "UserPromptSubmit" });
+  const outcome = runHooks(sync, payload, {
+    cwd,
+    event: "UserPromptSubmit",
+  });
   if (outcome.decision === "block" || outcome.decision === "ask") {
     return {
       blocked: true,
@@ -57,7 +88,36 @@ function runUserPromptSubmitHooks(settingsHooks, { prompt, cwd, sessionId } = {}
       additionalContext: null,
     };
   }
-  return { blocked: false, additionalContext: aggregateContext(outcome.results) };
+  return {
+    blocked: false,
+    additionalContext: aggregateContext(outcome.results),
+  };
+}
+
+/**
+ * Dispatch the `async: true` hooks for an event fire-and-forget onto the given
+ * supervisor (see async-hook-supervisor). Sync hooks are ignored here — they run
+ * on the blocking path. No-op (returns []) without a supervisor or async hooks,
+ * so callers can wire it unconditionally.
+ *
+ * @param {object} settingsHooks   merged hooks block
+ * @param {string} event           UserPromptSubmit / PostToolUse / Stop / …
+ * @param {object} payload         extra fields merged into the hook stdin JSON
+ * @param {object} opts            { cwd, matchTarget, supervisor }
+ * @returns {Array<{command:string, dispatched:boolean, reason?:string}>}
+ */
+function dispatchAsyncHooks(settingsHooks, event, payload = {}, opts = {}) {
+  const supervisor = opts.supervisor;
+  if (!settingsHooks || !supervisor) return [];
+  const matched = collectHooks(settingsHooks, event, opts.matchTarget || "");
+  if (matched.length === 0) return [];
+  const { async: asyncHooks } = partitionAsyncHooks(matched);
+  if (asyncHooks.length === 0) return [];
+  return supervisor.dispatch(
+    asyncHooks,
+    { hook_event_name: event, cwd: opts.cwd, ...payload },
+    { cwd: opts.cwd },
+  );
 }
 
 /**
@@ -82,13 +142,23 @@ function runSessionStartHooks(settingsHooks, { source, cwd, sessionId } = {}) {
 /**
  * Generic observe-only fire (SessionEnd / Stop / PreCompact). Returns the raw
  * runHooks outcome so callers can read a block reason; never gates flow here.
+ *
+ * `async: true` hooks are EXCLUDED from this synchronous run — they are always
+ * fire-and-forget and are dispatched separately (dispatchAsyncHooks), so running
+ * them here too would double-execute them.
  */
-function runObserveHooks(settingsHooks, event, payload = {}, { cwd, matchTarget } = {}) {
+function runObserveHooks(
+  settingsHooks,
+  event,
+  payload = {},
+  { cwd, matchTarget } = {},
+) {
   if (!settingsHooks) return { decision: "continue", results: [] };
   const matched = collectHooks(settingsHooks, event, matchTarget || "");
-  if (matched.length === 0) return { decision: "continue", results: [] };
+  const { sync } = partitionAsyncHooks(matched);
+  if (sync.length === 0) return { decision: "continue", results: [] };
   return runHooks(
-    matched,
+    sync,
     { hook_event_name: event, cwd, ...payload },
     { cwd, event },
   );
@@ -99,4 +169,6 @@ module.exports = {
   runSessionStartHooks,
   runObserveHooks,
   aggregateContext,
+  partitionAsyncHooks,
+  dispatchAsyncHooks,
 };

package/src/lib/settings-hooks.cjs

@@ -39,9 +39,13 @@ const HOOK_EVENTS = Object.freeze([
   "PostToolUse",
   "UserPromptSubmit",
   "Stop",
+  "SubagentStart",
   "SubagentStop",
   "SessionStart",
+  "SessionResume",
+  "SessionPause",
   "SessionEnd",
+  "ConfigChange",
   "PreCompact",
   "Notification",
 ]);
@@ -210,18 +214,40 @@ function umbrellaFor(tool) {
  * matcher is tested against BOTH the CC umbrella (`Bash`) and the raw tool
  * name (`run_shell`), so settings written either way fire.
  *
- * @returns {Array<{command:string, timeout?:number}>}
+ * `async`/`asyncRewake` are carried through (default false) so the caller can
+ * split fire-and-forget hooks off the blocking path (see async-hook-supervisor).
+ * `event` is stamped on each hook so a supervisor can key runs by (event+cmd).
+ *
+ * @returns {Array<{command:string, timeout?:number, event:string,
+ *                  async:boolean, asyncRewake:boolean}>}
  */
 function collectHooks(hooksBlock, event, toolName) {
   const groups = (hooksBlock && hooksBlock[event]) || [];
   const umbrella = umbrellaFor(toolName);
   const raw = String(toolName || "");
+  // Claude-Code MCP parity: a bare server-prefix matcher (`mcp__github`) fires
+  // for EVERY tool from that server (`mcp__github__create_issue`, …). Our
+  // matcher is anchored (`^…$`), so the server prefix alone would never match a
+  // full `mcp__server__tool` name without also testing the prefix explicitly.
+  // (Users can still target one tool with the full name, or all of a server's
+  // tools with a `mcp__server*` wildcard / `/mcp__server__/` regex.)
+  let mcpServer = null;
+  if (raw.startsWith("mcp__")) {
+    const parts = raw.split("__");
+    if (parts.length >= 3) mcpServer = `${parts[0]}__${parts[1]}`;
+  }
   const out = [];
   for (const g of groups) {
     const fn = compileMatcher(g.matcher);
-    if (fn(umbrella) || (raw && fn(raw))) {
+    if (fn(umbrella) || (raw && fn(raw)) || (mcpServer && fn(mcpServer))) {
       for (const h of g.hooks)
-        out.push({ command: h.command, timeout: h.timeout });
+        out.push({
+          command: h.command,
+          timeout: h.timeout,
+          event,
+          async: h.async === true,
+          asyncRewake: h.asyncRewake === true,
+        });
     }
   }
   return out;