narai-primitives 2.1.3 → 2.2.0

package/dist/toolkit/usage/aggregate.js

@@ -19,6 +19,9 @@ export function aggregateRecords(sessionId, connector, records) {
     let errors = 0;
     let start = records[0].ts;
     let end = records[0].ts;
+    let top1 = null;
+    let top2 = null;
+    let top3 = null;
     for (const rec of records) {
         totalBytes += rec.response_bytes;
         totalTokens += rec.estimated_tokens;
@@ -28,6 +31,20 @@ export function aggregateRecords(sessionId, connector, records) {
             start = rec.ts;
         if (rec.ts > end)
             end = rec.ts;
+        // ⚡ Bolt: Replace O(N log N) sort with O(N) Top-K manual tracking
+        // Avoids sorting the entire records array to find the 3 largest response_bytes.
+        if (!top1 || rec.response_bytes > top1.response_bytes) {
+            top3 = top2;
+            top2 = top1;
+            top1 = rec;
+        }
+        else if (!top2 || rec.response_bytes > top2.response_bytes) {
+            top3 = top2;
+            top2 = rec;
+        }
+        else if (!top3 || rec.response_bytes > top3.response_bytes) {
+            top3 = rec;
+        }
         const slot = byAction[rec.action] ??
             (byAction[rec.action] = {
                 calls: 0,
@@ -53,9 +70,8 @@ export function aggregateRecords(sessionId, connector, records) {
             avg_ms: s.ms_count > 0 ? Math.round(s.ms_total / s.ms_count) : 0,
         };
     }
-    const top_responses = [...records]
-        .sort((a, b) => b.response_bytes - a.response_bytes)
-        .slice(0, 3)
+    const top_responses = [top1, top2, top3]
+        .filter((r) => r !== null)
         .map((r) => ({ action: r.action, response_bytes: r.response_bytes }));
     return {
         session_id: sessionId,

package/dist/toolkit/usage/aggregate.js.map

@@ -1 +1 @@
-{"version":3,"file":"aggregate.js","sourceRoot":"","sources":["../../../src/toolkit/usage/aggregate.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,SAAiB,EACjB,OAAsB;IAEtB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,UAAU,EAAE,SAAS;YACrB,SAAS;YACT,KAAK,EAAE,EAAE;YACT,GAAG,EAAE,EAAE;YACP,WAAW,EAAE,CAAC;YACd,oBAAoB,EAAE,CAAC;YACvB,sBAAsB,EAAE,CAAC;YACzB,UAAU,EAAE,CAAC;YACb,SAAS,EAAE,EAAE;YACb,aAAa,EAAE,EAAE;SAClB,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAGV,EAAE,CAAC;IAEP,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1B,IAAI,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAExB,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,UAAU,IAAI,GAAG,CAAC,cAAc,CAAC;QACjC,WAAW,IAAI,GAAG,CAAC,gBAAgB,CAAC;QACpC,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS;YAAE,MAAM,IAAI,CAAC,CAAC;QAC1C,IAAI,GAAG,CAAC,EAAE,GAAG,KAAK;YAAE,KAAK,GAAG,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,GAAG,CAAC,EAAE,GAAG,GAAG;YAAE,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC;QAE/B,MAAM,IAAI,GACR,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC;YACpB,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG;gBACtB,KAAK,EAAE,CAAC;gBACR,cAAc,EAAE,CAAC;gBACjB,gBAAgB,EAAE,CAAC;gBACnB,QAAQ,EAAE,CAAC;gBACX,QAAQ,EAAE,CAAC;aACZ,CAAC,CAAC;QACL,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;QAChB,IAAI,CAAC,cAAc,IAAI,GAAG,CAAC,cAAc,CAAC;QAC1C,IAAI,CAAC,gBAAgB,IAAI,GAAG,CAAC,gBAAgB,CAAC;QAC9C,IAAI,OAAO,GAAG,CAAC,iBAAiB,KAAK,QAAQ,EAAE,CAAC;YAC9C,IAAI,CAAC,QAAQ,IAAI,GAAG,CAAC,iBAAiB,CAAC;YACvC,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAyC,EAAE,CAAC;IAC3D,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnD,SAAS,CAAC,MAAM,CAAC,GAAG;YAClB,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,cAAc,EAAE,CAAC,CAAC,cAAc;YAChC,gBAAgB,EAAE,CAAC,CAAC,gBAAgB;YACpC,MAAM,EAAE,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;SACjE,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAuB,CAAC,GAAG,OAAO,CAAC;SACnD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC;SACnD,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;IAExE,OAAO;QACL,UAAU,EAAE,SAAS;QACrB,SAAS;QACT,KAAK;QACL,GAAG;QACH,WAAW,EAAE,OAAO,CAAC,MAAM;QAC3B,oBAAoB,EAAE,UAAU;QAChC,sBAAsB,EAAE,WAAW;QACnC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM;QACnC,SAAS;QACT,aAAa;KACd,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,CAAe;IACnD,IAAI,CAAC,CAAC,WAAW,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC,CAAC,SAAS,oBAAoB,CAAC,CAAC,UAAU,0BAA0B,CAAC;IACpF,CAAC;IACD,MAAM,SAAS,GAAG,CAAC,CAAC,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;IAC3E,MAAM,MAAM,GAAG,CAAC,CAAC,WAAW,GAAG,SAAS,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;SACrC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC;SAC3D,GAAG,CACF,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CACd,KAAK,MAAM,MAAM,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,cAAc,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,gBAAgB,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,MAAM,IAAI,CAC7H;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,MAAM,GAAG,GAAG,CAAC,CAAC,aAAa;SACxB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,cAAc,CAAC,cAAc,EAAE,SAAS,CAAC;SACnF,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,OAAO;QACL,KAAK,CAAC,CAAC,SAAS,oBAAoB,CAAC,CAAC,UAAU,EAAE;QAClD,EAAE;QACF,aAAa,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,GAAG,EAAE;QACjC,YAAY,CAAC,CAAC,WAAW,KAAK,SAAS,aAAa,MAAM,YAAY,CAAC,CAAC,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;QACzG,qBAAqB,CAAC,CAAC,oBAAoB,CAAC,cAAc,EAAE,wBAAwB,CAAC,CAAC,sBAAsB,CAAC,cAAc,EAAE,EAAE;QAC/H,EAAE;QACF,cAAc;QACd,EAAE;QACF,mDAAmD;QACnD,uBAAuB;QACvB,IAAI;QACJ,EAAE;QACF,kBAAkB;QAClB,EAAE;QACF,GAAG;QACH,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"aggregate.js","sourceRoot":"","sources":["../../../src/toolkit/usage/aggregate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "narai-primitives",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "description": "Read-only connectors + planning hub + connector framework + credential resolution, in one package. Bundles what was @narai/connector-toolkit, @narai/connector-config, @narai/connector-hub, the seven @narai/<svc>-agent-connector packages, and @narai/credential-providers.",
   "type": "module",
   "main": "./dist/hub/index.js",
@@ -65,6 +65,14 @@
     "./notion": {
       "types": "./dist/connectors/notion/index.d.ts",
       "import": "./dist/connectors/notion/index.js"
+    },
+    "./linear": {
+      "types": "./dist/connectors/linear/index.d.ts",
+      "import": "./dist/connectors/linear/index.js"
+    },
+    "./gitlab": {
+      "types": "./dist/connectors/gitlab/index.d.ts",
+      "import": "./dist/connectors/gitlab/index.js"
     }
   },
   "bin": {
@@ -76,10 +84,12 @@
     "github-agent-connector": "./dist/connectors/github/cli.js",
     "jira-agent-connector": "./dist/connectors/jira/cli.js",
     "notion-agent-connector": "./dist/connectors/notion/cli.js",
+    "linear-agent-connector": "./dist/connectors/linear/cli.js",
+    "gitlab-agent-connector": "./dist/connectors/gitlab/cli.js",
     "usage-report": "./dist/toolkit/cli/usage-report.js"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.10.0"
   },
   "files": [
     "dist/",
@@ -108,8 +118,10 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.119",
+    "adf-to-markdown": "^1.0.1",
     "better-sqlite3": "^12.9.0",
     "js-yaml": "^4.1.1",
+    "marklassian": "^1.2.1",
     "zod": "^3.23.0"
   },
   "optionalDependencies": {

package/plugin-hooks/dispatcher.mjs

@@ -0,0 +1,584 @@
+#!/usr/bin/env node
+/**
+ * Shared PreToolUse / PostToolUse / SessionStart / SessionEnd dispatcher
+ * for narai-primitives builtin Claude Code plugins.
+ *
+ * Usage:
+ *   node dispatcher.mjs <event>
+ *
+ * Where <event> is one of: session-start, pre-tool-use, post-tool-use,
+ * session-end. Reads ${CLAUDE_PLUGIN_ROOT}/plugin-config.json for the
+ * plugin's identity and routes to the appropriate handler.
+ *
+ * Best-effort: handler-internal failures are logged to stderr but do not
+ * block tool execution. Argument / configuration errors exit with a
+ * non-zero code so Claude Code surfaces them to the operator.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { parsePluginConfig } from "./plugin-config.mjs";
+
+const VALID_EVENTS = new Set([
+  "session-start",
+  "pre-tool-use",
+  "post-tool-use",
+  "session-end",
+]);
+
+// Only run main() when invoked as a CLI, not when imported by tests.
+// Resolve symlinks on both sides so the smart-bootstrap dedup path
+// (where `node_modules/narai-primitives` is symlinked from a sibling
+// plugin) still recognizes itself as the CLI entrypoint.
+const isMainScript = (() => {
+  if (process.argv[1] === undefined) return false;
+  try {
+    const realArgv = fs.realpathSync(process.argv[1]);
+    const realSelf = fs.realpathSync(fileURLToPath(import.meta.url));
+    return realArgv === realSelf;
+  } catch {
+    // Fall back to literal comparison if realpath can't resolve.
+    return process.argv[1] === fileURLToPath(import.meta.url);
+  }
+})();
+
+if (isMainScript) {
+  main().catch((err) => {
+    process.stderr.write(`dispatcher: ${err?.message ?? err}\n`);
+    process.exit(1);
+  });
+}
+
+async function main() {
+  const event = process.argv[2];
+  if (!VALID_EVENTS.has(event)) {
+    process.stderr.write(
+      `dispatcher: unknown event '${event}' (expected one of ${[...VALID_EVENTS].join(", ")})\n`,
+    );
+    process.exit(2);
+  }
+
+  const root = process.env.CLAUDE_PLUGIN_ROOT;
+  if (!root) {
+    process.stderr.write("dispatcher: CLAUDE_PLUGIN_ROOT not set\n");
+    process.exit(2);
+  }
+
+  const cfgPath = path.join(root, "plugin-config.json");
+  if (!fs.existsSync(cfgPath)) {
+    process.stderr.write(`dispatcher: missing ${cfgPath}\n`);
+    process.exit(2);
+  }
+  const cfg = parsePluginConfig(fs.readFileSync(cfgPath, "utf-8"));
+
+  switch (event) {
+    case "session-start":
+      await onSessionStart(cfg);
+      break;
+    case "pre-tool-use":
+      await onPreToolUse(cfg);
+      break;
+    case "post-tool-use":
+      await onPostToolUse(cfg);
+      break;
+    case "session-end":
+      await onSessionEnd(cfg);
+      break;
+  }
+  process.exit(0);
+}
+
+async function loadToolkit() {
+  const { existsSync } = fs;
+  const { homedir } = await import("node:os");
+  const { fileURLToPath, pathToFileURL } = await import("node:url");
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    // 1. Bundled: dispatcher at narai-primitives/plugin-hooks/; toolkit at narai-primitives/dist/toolkit/guardrail.js
+    path.join(__dirname, "..", "dist", "toolkit", "guardrail.js"),
+    // 2. Claude Code plugin install
+    process.env.CLAUDE_PLUGIN_DATA
+      ? path.join(process.env.CLAUDE_PLUGIN_DATA, "node_modules", "narai-primitives", "dist", "toolkit", "guardrail.js")
+      : null,
+  ].filter((p) => p !== null);
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    try {
+      return await import(pathToFileURL(p).href);
+    } catch {
+      // try next
+    }
+  }
+  return null;
+}
+
+/**
+ * Lazily load the db audit module from dist. Returns the module namespace
+ * ({ enableAudit, logEvent, scrubSqlSecrets, ... }) or null if unavailable.
+ * Only used when NARAI_AUDIT_PATH is set, so the common path stays cheap.
+ */
+async function loadAudit() {
+  const { existsSync } = fs;
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path.join(__dirname, "..", "dist", "connectors", "db", "lib", "audit.js"),
+    process.env.CLAUDE_PLUGIN_DATA
+      ? path.join(process.env.CLAUDE_PLUGIN_DATA, "node_modules", "narai-primitives", "dist", "connectors", "db", "lib", "audit.js")
+      : null,
+  ].filter((p) => p !== null);
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    try {
+      return await import(pathToFileURL(p).href);
+    } catch {
+      // try next
+    }
+  }
+  return null;
+}
+
+/**
+ * Walk siblings of `pluginDataDir` looking for a `node_modules/narai-primitives`
+ * at `wantedVersion`. Returns the matched node_modules path, or null if no
+ * usable sibling found. Used to skip redundant npm install when N builtin
+ * plugins are loaded in the same Claude Code session.
+ */
+export function findSiblingInstall(pluginDataDir, wantedVersion) {
+  const parent = path.dirname(pluginDataDir);
+  let entries;
+  try {
+    entries = fs.readdirSync(parent, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const candidate = path.join(parent, entry.name);
+    if (candidate === pluginDataDir) continue;
+    const pkgJson = path.join(
+      candidate,
+      "node_modules",
+      "narai-primitives",
+      "package.json",
+    );
+    if (!fs.existsSync(pkgJson)) continue;
+    try {
+      const meta = JSON.parse(fs.readFileSync(pkgJson, "utf-8"));
+      if (meta.version === wantedVersion) {
+        return path.join(candidate, "node_modules");
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+async function onSessionStart(cfg) {
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+  const pluginData = process.env.CLAUDE_PLUGIN_DATA;
+  if (!pluginRoot || !pluginData) return;
+
+  await ensureBootstrap(pluginRoot, pluginData);
+
+  // Best-effort: emit nudge banner if the toolkit is reachable.
+  try {
+    const reminderPath = path.join(
+      pluginData,
+      "node_modules",
+      "narai-primitives",
+      "dist",
+      "toolkit",
+      "plugin",
+      "reminder.js",
+    );
+    if (fs.existsSync(reminderPath)) {
+      // pathToFileURL is required on Windows — Node refuses raw absolute
+      // paths as ESM specifiers (ERR_UNSUPPORTED_ESM_URL_SCHEME).
+      const mod = await import(pathToFileURL(reminderPath).href);
+      const decision = mod.evaluateNudge({ connectors: [cfg.name] });
+      if (decision.nudge) process.stdout.write(decision.banner + "\n");
+    }
+  } catch (err) {
+    process.stderr.write(`dispatcher: nudge failed (${err.message})\n`);
+  }
+
+  // Best-effort: stale-summarize.
+  try {
+    const stalePath = path.join(
+      pluginData,
+      "node_modules",
+      "narai-primitives",
+      "plugin-hooks",
+      "stale-summarize.mjs",
+    );
+    if (fs.existsSync(stalePath)) {
+      process.env.USAGE_CONNECTOR_NAME = cfg.name;
+      await import(pathToFileURL(stalePath).href);
+    }
+  } catch (err) {
+    process.stderr.write(`dispatcher: stale-summarize failed (${err.message})\n`);
+  }
+}
+
+async function onPreToolUse(cfg) {
+  const stdin = await readStdin();
+  if (!stdin) return;
+  let payload;
+  try {
+    payload = JSON.parse(stdin);
+  } catch {
+    return;
+  }
+  // Derive the tool being gated and the text to scan. Bash scans the
+  // command; Write scans the file content; Edit scans the incoming text
+  // (new_string only — old_string is the text being removed). `command`
+  // therefore holds the candidate text for whichever tool fired.
+  let scanTool;
+  let command;
+  if (payload.tool_name === "Bash") {
+    scanTool = "Bash";
+    command = payload.tool_input?.command;
+  } else if (payload.tool_name === "Write") {
+    scanTool = "Write";
+    command = payload.tool_input?.content;
+  } else if (payload.tool_name === "Edit") {
+    scanTool = "Edit";
+    command = payload.tool_input?.new_string;
+  } else {
+    return;
+  }
+  if (typeof command !== "string" || command.length === 0) return;
+
+  const decisions = [];
+
+  // 1. db-guard (Bash only; only if kind=db, and not opted out via user_config).
+  //    The token-blocklist engine is command-shaped and meaningless for file content.
+  if (scanTool === "Bash" && cfg.kind === "db" && process.env.DB_AGENT_GUARDRAILS !== "off") {
+    const guardrailsPath = path.join(
+      process.env.CLAUDE_PLUGIN_ROOT,
+      "hooks",
+      "guardrails.json",
+    );
+    if (fs.existsSync(guardrailsPath)) {
+      try {
+        const toolkit = await loadToolkit();
+        if (toolkit && typeof toolkit.findBlockingRule === "function") {
+          const { findBlockingRule, defaultDenyMessage, loadGuardrailManifest } = toolkit;
+          const manifest = loadGuardrailManifest(guardrailsPath);
+          const match = findBlockingRule(command, [manifest]);
+          if (match) {
+            decisions.push({
+              decision: "deny",
+              reason: defaultDenyMessage(match),
+            });
+          }
+        } else if (effectiveEnforcement(undefined) === "fail_closed") {
+          decisions.push({
+            decision: "deny",
+            reason: "fail-closed enforcement: db guardrail engine is unavailable",
+          });
+        }
+      } catch (err) {
+        process.stderr.write(`dispatcher: db-guard failed (${err.message})\n`);
+        if (effectiveEnforcement(undefined) === "fail_closed") {
+          decisions.push({
+            decision: "deny",
+            reason: `fail-closed enforcement: db guardrail manifest could not be evaluated (${err.message})`,
+          });
+        }
+      }
+    }
+  }
+
+  // 2. user-connector gates from $HOME and cwd. Mirror connector-gate.mjs:
+  // honor NARAI_GATE_DISABLE (comma-separated rule names) so operators
+  // can silence a noisy rule without editing gates.json.
+  const disabled = new Set(
+    (process.env.NARAI_GATE_DISABLE ?? "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+  );
+  // 3. plugin-shipped gates.json at CLAUDE_PLUGIN_ROOT/gates.json — lets
+  // hook-only plugins (e.g. git-connector) ship default rules out-of-the-box.
+  const pluginGatesFile = path.join(process.env.CLAUDE_PLUGIN_ROOT, "gates.json");
+  if (fs.existsSync(pluginGatesFile)) {
+    try {
+      const gateCfg = JSON.parse(fs.readFileSync(pluginGatesFile, "utf-8"));
+      applyGatesManifest(gateCfg, cfg.name, command, disabled, decisions, scanTool);
+    } catch (err) {
+      process.stderr.write(
+        `dispatcher: plugin-root gate scan failed (${err.message})\n`,
+      );
+      if (effectiveEnforcement(undefined) === "fail_closed") {
+        decisions.push({
+          decision: "deny",
+          reason: `fail-closed enforcement: gates manifest at ${pluginGatesFile} could not be parsed`,
+        });
+      }
+    }
+  }
+
+  // 4. user-connector gates from $HOME and cwd.
+  const home = process.env.HOME ?? "";
+  const cwd = process.cwd();
+  for (const root of [home, cwd]) {
+    if (!root) continue;
+    const gatesDir = path.join(root, ".connectors", "connectors");
+    if (!fs.existsSync(gatesDir)) continue;
+    let slugs;
+    try {
+      slugs = fs
+        .readdirSync(gatesDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+    } catch {
+      continue;
+    }
+    for (const slug of slugs) {
+      const gatesFile = path.join(gatesDir, slug, "gates.json");
+      if (!fs.existsSync(gatesFile)) continue;
+      try {
+        const gateCfg = JSON.parse(fs.readFileSync(gatesFile, "utf-8"));
+        applyGatesManifest(gateCfg, slug, command, disabled, decisions, scanTool);
+      } catch (err) {
+        process.stderr.write(
+          `dispatcher: gate scan failed for ${gatesFile} (${err.message})\n`,
+        );
+        if (effectiveEnforcement(undefined) === "fail_closed") {
+          decisions.push({
+            decision: "deny",
+            reason: `fail-closed enforcement: gates manifest at ${gatesFile} could not be parsed`,
+          });
+        }
+      }
+    }
+  }
+
+  if (decisions.length === 0) return;
+  const rank = { deny: 2, ask: 1, allow: 0 };
+  decisions.sort((a, b) => rank[b.decision] - rank[a.decision]);
+  const winner = decisions[0];
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: winner.decision,
+      permissionDecisionReason: winner.reason,
+    },
+  }));
+
+  // Best-effort audit of blocked/escalated decisions. Only runs when an
+  // audit destination is configured, keeping the common allow path cheap.
+  const auditPath = process.env.NARAI_AUDIT_PATH;
+  if (auditPath && (winner.decision === "deny" || winner.decision === "ask")) {
+    try {
+      const audit = await loadAudit();
+      if (audit && typeof audit.logEvent === "function") {
+        audit.enableAudit(auditPath);
+        const scrub = typeof audit.scrubSqlSecrets === "function"
+          ? audit.scrubSqlSecrets
+          : (s) => s;
+        audit.logEvent({
+          event_type: winner.decision === "deny" ? "guardrail_deny" : "guardrail_ask",
+          details: { tool: payload.tool_name, command: scrub(command), reason: winner.reason },
+        });
+      }
+    } catch (err) {
+      process.stderr.write(`dispatcher: decision audit failed (${err.message})\n`);
+    }
+  }
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf-8").trim();
+}
+async function onPostToolUse(cfg) {
+  const pluginData = process.env.CLAUDE_PLUGIN_DATA;
+  if (!pluginData) return;
+  const usagePath = path.join(
+    pluginData,
+    "node_modules",
+    "narai-primitives",
+    "plugin-hooks",
+    "usage-record.mjs",
+  );
+  if (!fs.existsSync(usagePath)) return;
+  process.env.USAGE_CONNECTOR_NAME = cfg.name;
+  if (cfg.binPath) process.env.USAGE_BIN_HINT = cfg.binPath;
+  try {
+    await import(pathToFileURL(usagePath).href);
+  } catch (err) {
+    process.stderr.write(`dispatcher: usage-record failed (${err.message})\n`);
+  }
+}
+async function onSessionEnd(cfg) {
+  const pluginData = process.env.CLAUDE_PLUGIN_DATA;
+  if (!pluginData) return;
+  const summaryPath = path.join(
+    pluginData,
+    "node_modules",
+    "narai-primitives",
+    "plugin-hooks",
+    "session-summary.mjs",
+  );
+  if (!fs.existsSync(summaryPath)) return;
+  // session-summary.mjs only runs its `main()` when it's the CLI entry
+  // point (`import.meta.url === file://${process.argv[1]}`). Importing it
+  // here would be a no-op; spawn it as a subprocess so the guard passes.
+  try {
+    const { spawnSync } = await import("node:child_process");
+    spawnSync("node", [summaryPath], {
+      stdio: "inherit",
+      env: { ...process.env, USAGE_CONNECTOR_NAME: cfg.name },
+    });
+  } catch (err) {
+    process.stderr.write(`dispatcher: session-summary failed (${err.message})\n`);
+  }
+}
+
+/**
+ * Ensure narai-primitives is installed in pluginData. Tries (in order):
+ *   1. Skip if already installed at the right version.
+ *   2. Symlink from a sibling plugin's node_modules.
+ *   3. npm install in pluginData.
+ *
+ * Best-effort: all branches return without throwing. The caller proceeds
+ * to side effects (nudge, stale-summarize, etc.) even when the install
+ * is cached, so recurring per-session behavior fires every run.
+ */
+async function ensureBootstrap(pluginRoot, pluginData) {
+  const rootPkg = path.join(pluginRoot, "package.json");
+  if (!fs.existsSync(rootPkg)) return;
+  let rootMeta;
+  try {
+    rootMeta = JSON.parse(fs.readFileSync(rootPkg, "utf-8"));
+  } catch {
+    return;
+  }
+  // Read the wanted narai-primitives version from the plugin's
+  // `dependencies` block (e.g. `"^2.1.3"`) and strip the semver
+  // prefix so the equality check matches the installed package's
+  // resolved version field (e.g. `"2.1.3"`). The plugin's own
+  // `version` is independent and not interchangeable.
+  const depRange = rootMeta.dependencies?.["narai-primitives"];
+  const wantVersion = depRange?.replace(/^[\^~>=< ]+/, "");
+  if (!wantVersion) return;
+
+  fs.mkdirSync(pluginData, { recursive: true });
+
+  const myInstall = path.join(pluginData, "node_modules", "narai-primitives");
+  if (fs.existsSync(myInstall)) {
+    try {
+      const installed = JSON.parse(
+        fs.readFileSync(path.join(myInstall, "package.json"), "utf-8"),
+      );
+      if (installed.version === wantVersion) return;
+    } catch {
+      // Fall through to re-install.
+    }
+  }
+
+  const sibling = findSiblingInstall(pluginData, wantVersion);
+  if (sibling !== null) {
+    try {
+      const myNodeModules = path.join(pluginData, "node_modules");
+      if (fs.existsSync(myNodeModules)) {
+        fs.rmSync(myNodeModules, { recursive: true, force: true });
+      }
+      fs.symlinkSync(sibling, myNodeModules, "dir");
+      return;
+    } catch {
+      // Fall through to install.
+    }
+  }
+
+  fs.copyFileSync(rootPkg, path.join(pluginData, "package.json"));
+  const { spawnSync } = await import("node:child_process");
+  spawnSync("npm", ["install", "--no-audit", "--no-fund"], {
+    cwd: pluginData,
+    stdio: "inherit",
+  });
+}
+
+/**
+ * Resolve the effective enforcement posture from the global
+ * NARAI_GATE_ENFORCEMENT env var and an optional manifest-level field.
+ * Strictest wins: fail-closed if either requests it, else fail-open.
+ */
+export function effectiveEnforcement(manifestEnforcement) {
+  const env = process.env.NARAI_GATE_ENFORCEMENT;
+  if (env === "fail_closed" || manifestEnforcement === "fail_closed") {
+    return "fail_closed";
+  }
+  return "fail_open";
+}
+
+/**
+ * Apply a parsed gates.json manifest to a command. Rules with invalid
+ * shape, disabled names, or uncompilable patterns are skipped. Anchored
+ * patterns match per-segment so chaining (`echo ok; psql ...`) can't bypass.
+ *
+ * Under fail-closed enforcement (env var or the manifest's `enforcement`
+ * field), a rule whose pattern will not compile becomes a hard deny instead
+ * of being silently skipped — we cannot prove the command is safe.
+ */
+export function applyGatesManifest(manifest, source, text, disabled, decisions, scanTool = "Bash") {
+  const enforcement = effectiveEnforcement(manifest.enforcement);
+  // Bash commands are split on chaining operators so anchored rules apply
+  // per-segment. File content (Write/Edit) is matched as a single unit so
+  // characters like `;` or `|` inside the file do not fragment it.
+  const segments = scanTool === "Bash" ? splitCompound(text) : [text];
+  for (const rule of manifest.rules ?? []) {
+    if (
+      !["deny", "ask", "allow"].includes(rule.decision) ||
+      typeof rule.pattern !== "string"
+    ) continue;
+    if (typeof rule.name === "string" && disabled.has(rule.name)) continue;
+    // A rule applies to a tool only if listed in `applies_to`. Default is
+    // Bash-only, so every existing rule keeps its current behavior and is
+    // skipped on Write/Edit unless it explicitly opts in.
+    const appliesTo = Array.isArray(rule.applies_to) ? rule.applies_to : ["Bash"];
+    if (!appliesTo.includes(scanTool)) continue;
+    let re;
+    try { re = new RegExp(rule.pattern); } catch {
+      if (enforcement === "fail_closed") {
+        decisions.push({
+          decision: "deny",
+          reason: `fail-closed enforcement: ${source} gate rule '${rule.name ?? "rule"}' has an invalid pattern`,
+        });
+      }
+      continue;
+    }
+    for (const segment of segments) {
+      if (re.test(segment)) {
+        decisions.push({
+          decision: rule.decision,
+          reason: rule.reason ?? `${source} gate: ${rule.name ?? "rule"}`,
+        });
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * Split a bash command on chaining operators so anchored gate rules
+ * apply per-segment. Mirrors connector-gate.mjs's behavior.
+ */
+function splitCompound(cmd) {
+  const parts = cmd.split(/\s*(?:&&|\|\||;|\|)\s*/);
+  return parts
+    .map((p) => stripPrefix(p.trim()))
+    .filter((p) => p.length > 0);
+}
+
+function stripPrefix(s) {
+  let cur = s;
+  while (/^[A-Za-z_][A-Za-z0-9_]*=\S*\s+/.test(cur)) {
+    cur = cur.replace(/^[A-Za-z_][A-Za-z0-9_]*=\S*\s+/, "");
+  }
+  return cur.replace(/^(sudo|nice|time)\s+/, "");
+}