heedvane 0.2.1 → 0.3.4

package/dist/plan.js

@@ -6,18 +6,14 @@
  * --dry-run printout and the apply step.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { supportedClients, } from "./clients/definitions.js";
-import { hermesPluginFiles } from "./clients/hermes-plugin.js";
+import { signsInWithOrgKey } from "./backend/credentials.js";
 import { entryValue, isOurHookGroup, parseDoc, readEntry, TOP_LEVEL, valuesEqual } from "./config-doc.js";
 import { genericSnippet } from "./dispatchers/snippets.js";
-import { MCP_ENTRY_ARGS, desiredServer } from "./mcp.js";
+import { HEEDVANE_SERVER_NAME, MCP_NEEDS_ORG, MCP_OFF_METRICS_ONLY, ORG_KEY_ENV, comparableEntry, connectorEntry, connectorOrganization, connectorUrl, entryUrls, isConnectorEntry, isHeedvaneEntry, isHelperEntry, isLegacyEntry, keyConnectorEntry, mcpEntryNames } from "./mcp.js";
 import { canonicalSkillFiles, skillDigest } from "./skill/content.js";
 import { errorMessage } from "./guards.js";
-/** Our MCP stdio registration entry (unscoped package per the plan's decision). */
-export function mcpEntry() {
-    return { command: "npx", args: [...MCP_ENTRY_ARGS] };
-}
 /** A client's primary hooks config target, resolved. */
 export function hooksTarget(client) {
     const target = client.configs.find((t) => t.purpose === "hooks") ?? client.configs[0];
@@ -31,18 +27,14 @@ function mcpTarget(client) {
 /**
  * Desired write targets per client × capability. This is the desired-state
  * compiler heed.yaml → concrete files; doctor reuses it via a callback so
- * it never needs apply.ts. `env` is accepted for API stability — the client's
- * config paths arrive already resolved against it.
+ * it never needs apply.ts. The client's config paths arrive already resolved
+ * against `env`; its HEEDVANE_ORG_KEY picks the software-factory MCP connection.
  */
 export function desiredEntriesFor(client, capability, context) {
-    const home = context.home;
-    void context.env;
     const targets = [];
     if (capability === "hooks") {
-        if (client.id === "hermes") {
-            // Hermes gets a native plugin, not a hooks.json entry.
-            return hermesDesiredFiles(home, context.gating);
-        }
+        if (client.hookFiles !== undefined)
+            return hookFilesDesired(client, client.hookFiles, context.gating);
         // Real harness shape: the `hooks` container is keyed by event name, and
         // we patch per-event so a user's own hook entries are never clobbered.
         const target = hooksTarget(client);
@@ -59,14 +51,114 @@ export function desiredEntriesFor(client, capability, context) {
     }
     if (capability === "mcp") {
         const target = mcpTarget(client);
-        if (!target)
-            return targets;
-        // Codex (TOML) carries an explicit generous startup timeout for npx cold starts.
-        targets.push({ path: target.path, format: target.format, containerKey: client.mcpServersKey, entryName: "heedvane", entry: desiredServer(client.id) });
+        const entry = context.connector === undefined ? undefined : connectionEntry(client.id, { ...context, connector: context.connector });
+        if (target !== undefined && entry !== undefined)
+            targets.push({ path: target.path, format: target.format, containerKey: client.mcpServersKey, entryName: HEEDVANE_SERVER_NAME, entry });
         return targets;
     }
     return targets; // skill has no per-client config entry
 }
+/**
+ * On a software factory (HEEDVANE_ORG_KEY set, or an organization key saved with `auth org`), the entry that sends the
+ * key from HEEDVANE_ORG_KEY; else the one that signs in in the browser. The saved key counts too, so connect, auth org
+ * and doctor agree in whatever order and environment they run.
+ */
+function connectionEntry(clientId, context) {
+    const isFactory = Boolean(context.env[ORG_KEY_ENV]?.trim()) || signsInWithOrgKey(join(context.home, ".heed"));
+    const factory = isFactory ? keyConnectorEntry(clientId, context.connector) : undefined;
+    return factory ?? connectorEntry(clientId, context.connector, context.nodeDir);
+}
+/** The folder of the Node running this install: the hook dispatcher records it, and a local MCP bridge runs its npx. */
+function installingNodeDir() {
+    return dirname(process.execPath);
+}
+/** The folder whose npx runs a local MCP bridge on `platform`; none on Windows, which keeps the bare `npx` its docs show (a `.cmd` path cannot be started without a shell). */
+export function bridgeNodeDir(platform) {
+    return platform === "win32" ? undefined : installingNodeDir();
+}
+/**
+ * Why heed.yaml registers no MCP connection, the one owner of that decision: metrics only, whose promise the
+ * connection's tools would break (they send questions and repository names), or no organization. None when it does.
+ */
+export function connectionOff(heedFile) {
+    if (heedFile.heedvane.dataMode === "metrics-only")
+        return "metrics-only";
+    return heedFile.heedvane.org === undefined ? "no-organization" : undefined;
+}
+/** Heedvane's MCP connection URL for the organization heed.yaml names, unless {@link connectionOff} says there is none. */
+export function heedvaneConnector(heedFile) {
+    const { url, org } = heedFile.heedvane;
+    return org === undefined || connectionOff(heedFile) !== undefined ? undefined : connectorUrl(url, org);
+}
+/** What to tell a person who asked for the MCP connection but gets none, and why; nothing when it is registered. */
+export function connectionNote(heedFile) {
+    const off = heedFile.install.mcp ? connectionOff(heedFile) : undefined;
+    if (off === undefined)
+        return undefined;
+    return off === "metrics-only" ? MCP_OFF_METRICS_ONLY : MCP_NEEDS_ORG;
+}
+/** The organization an earlier version's connection (`heedvane-findings`) names at `server`, so connect can replace it without --org. */
+export function legacyOrganization(clients, server) {
+    for (const client of clients) {
+        for (const target of client.configs) {
+            const doc = target.format === "yaml" ? null : parseClientDoc(target.path, target.format);
+            for (const qualified of doc === null ? [] : mcpEntryNames(doc, mcpContainers(client), isLegacyEntry)) {
+                const [container, name] = qualified.split("::");
+                const org = connectorOrganization(doc[container][name], server);
+                if (org !== undefined)
+                    return org;
+            }
+        }
+    }
+    return undefined;
+}
+/** The MCP containers a client's configs can hold our entries in (Codex's TOML and OpenCode's `mcp` beside the usual key). */
+export function mcpContainers(client) {
+    return [client.mcpServersKey, "mcp_servers", "mcp"];
+}
+/** The doc's parsed value, or null when the config is absent or unparseable — nothing marker-verified to remove. */
+export function parseClientDoc(path, format) {
+    try {
+        return parseDoc(readFileSync(path, "utf8"), format).value;
+    }
+    catch {
+        return null; // absent or unparseable — nothing marker-verified to remove
+    }
+}
+/** True when the client's MCP config holds Heedvane's connection, not only a user's entry that shares its name. */
+export function hasOwnConnection(client) {
+    const target = mcpTarget(client);
+    const doc = target === undefined ? null : parseClientDoc(target.path, target.format);
+    return doc !== null && mcpEntryNames(doc, mcpContainers(client), isConnectorEntry).length > 0;
+}
+/** Whether Heedvane's connection in this client's MCP config is in the key form (mcp.ts `keyConnectorEntry`), for whatever server and organization it names. */
+export function sendsOrgKey(client) {
+    const target = mcpTarget(client);
+    const doc = target === undefined ? null : parseClientDoc(target.path, target.format);
+    return doc !== null && mcpEntryNames(doc, mcpContainers(client), isConnectorEntry).some((qualified) => {
+        const [container, name] = qualified.split("::");
+        const entry = doc[container][name];
+        return entryUrls(entry).some((url) => valuesEqual(entry, keyConnectorEntry(client.id, url)));
+    });
+}
+/** The first config of this client still holding an MCP entry an earlier version wrote, and those entries' names. */
+export function legacyMcpEntries(client) {
+    return mcpEntriesMatching(client, isLegacyEntry);
+}
+/** The first config of this client holding any Heedvane MCP entry, today's or an earlier version's, and their names. */
+export function heedvaneMcpEntries(client) {
+    return mcpEntriesMatching(client, isHeedvaneEntry);
+}
+/** The first config of this client holding MCP entries `match` accepts, and their names. */
+function mcpEntriesMatching(client, match) {
+    for (const target of client.configs) {
+        const doc = target.format === "yaml" ? null : parseClientDoc(target.path, target.format);
+        const names = doc === null ? [] : mcpEntryNames(doc, mcpContainers(client), match).map((qualified) => qualified.split("::")[1]);
+        if (names.length > 0)
+            return { path: target.path, names };
+    }
+    return undefined;
+}
 /** Our one hook for an event, in the shape the client's hooks file holds it. */
 function hookEntry(client) {
     const command = genericSnippet(client.id);
@@ -113,14 +205,15 @@ function installsClient(client, scope) {
     const { agents } = scope.heedFile;
     return isClientDetected(client) && (agents === "auto" || agents.includes(client.id));
 }
-function hermesDesiredFiles(home, gating) {
-    // Hermes gets a native plugin (kind: standalone) instead of hooks.json.
-    return hermesPluginFiles(gating).map((f) => ({
-        path: join(home, ".hermes", "plugins", "heedvane-hooks", f.relativePath),
-        format: "json", // plugin.yaml is written verbatim, not patched
+/** The whole files a client's hooks are (Hermes' plugin, Pi's extension): written verbatim, not patched into a config. */
+function hookFilesDesired(client, hookFiles, gating) {
+    const path = hookFiles.path(client.markerPath);
+    return hookFiles.files(gating ?? "always").map((file) => ({
+        path: join(path, file.relativePath),
+        format: "json",
         containerKey: "",
-        entryName: f.relativePath,
-        entry: f.content,
+        entryName: file.relativePath === "" ? basename(path) : file.relativePath,
+        entry: file.content,
     }));
 }
 /** Read-only inspection: what operation would satisfy the desired entry at its path? */
@@ -129,7 +222,7 @@ function inspect(d) {
     if (!existsSync(path))
         return { operation: "create", path };
     const backupPath = `${path}.heedvane.backup`;
-    // Whole-file desired entries (hermes plugin files) compare byte-wise; they are not configs to parse.
+    // Whole-file desired entries (definitions.ts `hookFiles`) compare byte-wise; they are not configs to parse.
     if (containerKey === "") {
         return readFileSync(path, "utf8") === desired ? { operation: "unchanged", path } : { operation: "update", path, backupPath };
     }
@@ -148,12 +241,11 @@ function inspect(d) {
     const current = readEntry(doc, containerKey, entryName);
     if (current === undefined)
         return { operation: "create", path, backupPath };
-    if (!valuesEqual(current, entryValue(containerKey, current, desired)))
+    if (!valuesEqual(comparableEntry(current), comparableEntry(entryValue(containerKey, current, desired))))
         return { operation: "update", path, backupPath };
     return { operation: "unchanged", path };
 }
-function inspectMcp(client, home, env) {
-    const desireds = desiredEntriesFor(client, "mcp", { home, env });
+function inspectMcp(desireds) {
     // A client with multiple MCP targets (codex hooks.json + config.toml) is
     // only "aligned" when every target is; the action reports the worst path.
     let worst = { operation: "unchanged" };
@@ -187,11 +279,9 @@ function inspectSkill(home, client, desiredDigest) {
     const backupPath = join(dir, "SKILL.md.heedvane.backup");
     return same ? { operation: "unchanged", path: skillMd } : { operation: "update", path: skillMd, backupPath };
 }
-/** Hooks ride the client's native capability, or hermes' plugin-install channel. */
-function supportsCapability(client, capability) {
-    if (client.capabilities.includes(capability))
-        return true;
-    return capability === "hooks" && client.id === "hermes" && client.capabilities.includes("plugin-install");
+/** The client's native capability, or hooks written as whole files (definitions.ts `hookFiles`). */
+export function supportsCapability(client, capability) {
+    return client.capabilities.includes(capability) || (capability === "hooks" && client.hookFiles !== undefined);
 }
 function skipAction(client, reason, path) {
     return { clientId: client.id, kind: "skip", operation: "skip", path: path ?? client.markerPath, reason };
@@ -210,11 +300,43 @@ function worstHooksResult(desireds) {
     return worst;
 }
 function noHooksSkip(client) {
-    return skipAction(client, `${client.id}: no native hooks — policies arrive via MCP`, client.configs[0]?.path ?? client.markerPath);
+    return skipAction(client, `${client.id}: no native hooks`, client.configs[0]?.path ?? client.markerPath);
 }
 function deferredHooksSkip(client, deferredTo) {
     return skipAction(client, `${client.id}: runs ${deferredTo.displayName}'s hooks, which are installed — a second install would run each event twice`, client.configs[0]?.path);
 }
+/**
+ * The MCP entries connect removes: under metrics only every Heedvane entry, today's too; without an organization the
+ * local helper, which has no tools any more (a connection under its earlier name still works, and nothing would replace
+ * it); otherwise everything an earlier version registered.
+ */
+export function mcpLeftovers(heedFile) {
+    const off = connectionOff(heedFile);
+    if (off === "metrics-only")
+        return isHeedvaneEntry;
+    if (off === "no-organization")
+        return isHelperEntry;
+    return isLegacyEntry;
+}
+/** The MCP action: write the connection where it is wanted, and remove the {@link mcpLeftovers} either way. */
+function planMcp(client, desireds, heedFile) {
+    const off = connectionOff(heedFile);
+    const leftover = mcpEntriesMatching(client, mcpLeftovers(heedFile));
+    const removal = leftover === undefined ? undefined : { operation: "remove", path: leftover.path, backupPath: `${leftover.path}.heedvane.backup`, reason: leftoverReason(leftover.names, off) };
+    if (desireds.length === 0)
+        return removal === undefined ? null : { clientId: client.id, kind: "mcp", ...removal };
+    const r = inspectMcp(desireds);
+    if (r.operation === "unchanged" && removal !== undefined)
+        return { clientId: client.id, kind: "mcp", ...removal };
+    return { clientId: client.id, kind: "mcp", operation: r.operation, path: r.path ?? desireds[0].path, backupPath: r.backupPath, reason: r.reason };
+}
+function leftoverReason(names, off) {
+    if (off === "metrics-only")
+        return `removes ${names.join(", ")}: ${MCP_OFF_METRICS_ONLY}`;
+    if (off === "no-organization")
+        return `removes ${names.join(", ")}, the local helper an earlier version registered; ${MCP_NEEDS_ORG}`;
+    return `replaces ${names.join(", ")}, which an earlier version registered`;
+}
 /** One client × one capability → its planned action, or null when nothing to plan. */
 function planCapability(client, capability, ctx) {
     if (!ctx.heedFile.install[capability])
@@ -228,22 +350,12 @@ function planCapability(client, capability, ctx) {
         const r = inspectSkill(ctx.home, client, ctx.desiredSkillDigest);
         return { clientId: client.id, kind: "skill", operation: r.operation, path: r.path ?? join(ctx.home, ".agents", "skills", "heedvane-hooks", "SKILL.md"), backupPath: r.backupPath };
     }
-    const desireds = desiredEntriesFor(client, capability, { home: ctx.home, env: ctx.env, gating: ctx.heedFile.gating.mode });
+    const desireds = desiredEntriesFor(client, capability, { home: ctx.home, env: ctx.env, gating: ctx.heedFile.gating.mode, connector: heedvaneConnector(ctx.heedFile), nodeDir: ctx.nodeDir });
+    if (capability === "mcp")
+        return planMcp(client, desireds, ctx.heedFile);
     if (desireds.length === 0)
         return null;
-    if (capability === "mcp") {
-        const r = inspectMcp(client, ctx.home, ctx.env);
-        const primary = desireds[0];
-        return {
-            clientId: client.id,
-            kind: "mcp",
-            operation: r.operation,
-            path: r.path ?? primary.path,
-            backupPath: r.backupPath,
-            reason: r.reason,
-        };
-    }
-    // hooks (including the hermes whole-file plugin shape)
+    // hooks (including whole hook files)
     const primary = desireds[0];
     const worst = worstHooksResult(desireds);
     return {
@@ -263,7 +375,7 @@ export function planActions(input) {
     const { home, platform, env, heedFile } = input;
     const actions = [];
     const desiredSkillDigest = input.skillDigest ?? skillDigest(canonicalSkillFiles());
-    const ctx = { home, env, heedFile, forced: new Set(input.forced), desiredSkillDigest };
+    const ctx = { home, env, heedFile, forced: new Set(input.forced), desiredSkillDigest, nodeDir: bridgeNodeDir(platform) };
     for (const client of supportedClients({ home, platform: platform, env })) {
         if (!installsClient(client, ctx)) {
             // Listed in heed.yaml but not on this machine.
@@ -283,6 +395,6 @@ export function planActions(input) {
 /** Count of distinct agents that would receive a write for a kind. */
 export function wouldInstallCount(actions, kind) {
     return new Set(actions
-        .filter((a) => a.kind === kind && (a.operation === "create" || a.operation === "update"))
+        .filter((a) => a.kind === kind && (a.operation === "create" || a.operation === "update" || a.operation === "remove"))
         .map((a) => a.clientId)).size;
 }

package/dist/render.js

@@ -4,21 +4,20 @@
  */
 import { basename } from "node:path";
 import { wouldInstallCount } from "./plan.js";
+import { connectorEntry } from "./mcp.js";
 /** What Heedvane installs into an agent, e.g. "hooks + MCP + skill". */
 export function capabilitySummary(client) {
     const parts = [];
-    if (client.capabilities.includes("hooks"))
+    if (client.capabilities.includes("hooks") || client.hookFiles !== undefined)
         parts.push("hooks");
-    if (client.capabilities.includes("mcp"))
+    // Heedvane's MCP connection goes only into agents with a remote-server shape (not Claude Desktop).
+    if (client.capabilities.includes("mcp") && connectorEntry(client.id, "") !== undefined)
         parts.push("MCP");
     if (client.capabilities.includes("skill"))
         parts.push("skill");
-    const hookless = client.events.length === 0 && client.capabilities.includes("mcp");
-    if (hookless) {
-        // e.g. Warp: "MCP + skill — no native hooks; policies via MCP"
-        return `${parts.join(" + ")} — no native hooks; policies via MCP`;
-    }
-    return parts.join(" + ");
+    const summary = parts.join(" + ");
+    // e.g. Warp: "MCP + skill — no native hooks"
+    return client.events.length === 0 && client.capabilities.includes("mcp") ? `${summary} — no native hooks` : summary;
 }
 export function renderDetection(rows) {
     const lines = ["  Detected on this machine:"];
@@ -38,6 +37,7 @@ const VERB = {
     create: "added",
     update: "updated",
     unchanged: "already current",
+    remove: "removed",
     skip: "skipped",
 };
 function kindLabel(kind) {

package/dist/reply/harness-output.d.ts

@@ -42,9 +42,18 @@ export type HarnessOutput = Record<string, never> | {
 } | {
     action: "block";
     message: string;
+} | {
+    block: true;
+    reason: string;
 } | {
     context: string;
 };
+/**
+ * The top-level output field each agent shows the person without steering (checked 2026-10-20): Claude Code's, Codex's
+ * (learn.chatgpt.com/docs/hooks) and Gemini CLI's (geminicli.com/docs/hooks/reference) `systemMessage`. Cursor shows
+ * `user_message` only with a denial, and Hermes' plugin hooks have no such field, so they have none here.
+ */
+export declare const USER_NOTICE_FIELD: Readonly<Record<string, string>>;
 /** The events a stop block or halt applies to. */
 export declare const STOP_EVENTS: ReadonlySet<string>;
 /**

package/dist/reply/harness-output.js

@@ -13,6 +13,12 @@ const CLAUDE_EVENT_NAMES = {
 export const ADDITIONAL_CONTEXT_BUDGET = 9_500;
 /** Between the pieces of one answer's context. */
 export const CONTEXT_SEPARATOR = "\n\n";
+/**
+ * The top-level output field each agent shows the person without steering (checked 2026-10-20): Claude Code's, Codex's
+ * (learn.chatgpt.com/docs/hooks) and Gemini CLI's (geminicli.com/docs/hooks/reference) `systemMessage`. Cursor shows
+ * `user_message` only with a denial, and Hermes' plugin hooks have no such field, so they have none here.
+ */
+export const USER_NOTICE_FIELD = { claude: "systemMessage", codex: "systemMessage", gemini: "systemMessage" };
 /** The events a stop block or halt applies to. */
 export const STOP_EVENTS = new Set(["stop", "subagent_stop"]);
 const CLAUDE_STEERING = {
@@ -35,6 +41,8 @@ const CLAUDE_STEERING = {
  * - Hermes (hermes-agent.nousresearch.com/docs/user-guide/features/hooks): its plugin's `pre_tool_call`
  *   blocks with `{action: "block", message}`, which Hermes ignores without a message; `pre_llm_call`
  *   adds `{context}` to the turn. It has no stop hook.
+ * - Pi (pi.dev, docs/extensions.md): Heedvane's guard (src/guard.ts) sends a tool call as Claude Code's PreToolUse and
+ *   hands `{block: true, reason}` to Pi's `tool_call` event, Pi's core `beforeToolCall` or Pi Durable `beforeTool`.
  */
 const HARNESS_STEERING = {
     claude: CLAUDE_STEERING,
@@ -58,6 +66,11 @@ const HARNESS_STEERING = {
         deny: (_name, reason) => (reason === "" ? {} : { action: "block", message: reason }),
         context: (name, text) => (name === "pre_llm_call" ? { context: text } : null),
     },
+    pi: {
+        names: { pre_tool_use: "PreToolUse" },
+        deny: (_name, reason) => ({ block: true, reason }),
+        context: () => null,
+    },
 };
 /**
  * The stdout JSON for the envelope's agent and event. A `steer` always enforces where the harness can:

package/dist/reply/reply.js

@@ -24,7 +24,8 @@ export async function replyFor(envelope, ctx, extras = {}) {
     const startBlock = await sessionStartBlock(request, ctx, { policy, teamMemory: extras.teamMemory });
     const steered = steeringBackend(envelope, ctx, policy);
     const local = steered === null ? ALLOW : localVerdict(request, policy?.rules ?? []);
-    if (steered !== null)
+    // Metrics only: the event's content never leaves this machine, so only the fixed rules above judge it.
+    if (steered !== null && ctx.config.dataMode !== "metrics-only")
         judgeInBackground(request, { backend: steered, enforcedLocally: new Set((local.enforcements ?? []).map((enforced) => enforced.ruleId)) }, ctx);
     reportDeliveries(envelope, local.enforcements ?? [], { status: "enforced", delivery: "local", report: ctx.report });
     const delivered = steered === null ? ALLOW : deliverViolations(envelope, ctx);

package/dist/skill/content.d.ts

@@ -4,8 +4,8 @@
  * runtime). The physical copies in /skills/heedvane-hooks/ must stay
  * byte-identical — tests assert that.
  */
-export declare const SKILL_MD = "---\nname: heedvane-hooks\ndescription: Use when a user asks about heedvane hooks status, events, or how their coding agents are monitored \u2014 reports live hook installation state and the canonical event contract.\n---\n\n# heedvane-hooks\n\n## Overview\n\nHeedvane hooks give coding agents (Claude Code, Codex, Gemini CLI, Cursor, Warp, OpenCode, Hermes) a shared steering/guardrail/analysis channel without touching their internals. Three strictly separated layers:\n\n1. **Hook contract** \u2014 a harness-neutral event taxonomy (`pre_tool_use`, `post_tool_use`, \u2026), one JSON envelope, one normalizer. See `references/events.md`.\n2. **Per-agent adapters** \u2014 native hook config injection where the harness has hooks (Claude, Codex, Gemini, Cursor); MCP registration as the universal fallback (Warp has no native hooks \u2014 policy arrives via MCP); an honest skip where neither exists.\n3. **Setup mechanism** \u2014 `heedvane-hook` CLI: `init` / `setup` / `doctor` / `uninstall` with backup \u2192 atomic write \u2192 read-back verify. Human intent lives in `~/.heed/heed.yaml`; machine state in `~/.heed/state.json`.\n\nWhich sessions run the hooks follows `heed.yaml` `gating.mode`: with `always` (the default) every session is governed, with `pane` only sessions launched with `HEED_SESSION` set. The dispatcher script (for Hermes, its plugin) decides, from the mode `setup` bakes into it, and always exits 0. Observability never blocks the agent.\n\n## When to Use\n\n- \"Is my heedvane install healthy?\" / \"why aren't hooks firing?\"\n- \"What events does heedvane capture?\" / \"what shape is the payload?\"\n- \"Which of my agents are monitored?\"\n- After the user edits `~/.heed/heed.yaml` and wants the change applied/verified.\n\nDo **not** use this skill to author policies \u2014 an organization's policies are defined and assigned on the Heedvane server, never in `heed.yaml`.\n\n## Checking status\n\n1. Run the doctor (scoped, exit-code-carrying):\n\n   ```sh\n   npx heedvane doctor --json\n   ```\n\n   Or unscoped plain text: `npx heedvane doctor`. Every failing check carries a `remediation` string \u2014 surface it verbatim.\n\n2. Read the control file \u2014 it is the single source of truth for intent:\n\n   ```sh\n   cat ~/.heed/heed.yaml\n   ```\n\n   `agents: auto` manages every detected agent; an explicit list filters. `install.hooks/skill/mcp` toggles channels per agent.\n\n3. **Never edit agent configs by hand.** `~/.claude/settings.json`, `~/.codex/hooks.json`, etc. are compiled outputs. Edit `heed.yaml`, then re-run:\n\n   ```sh\n   npx heedvane setup\n   ```\n\n4. Machine state (installed digests, endpoint, protocol version) is `~/.heed/state.json` \u2014 CLI-owned, never hand-edit.\n\n## Event contract summary\n\n- Canonical events (v1, snake_case): `session_start`, `session_end`, `user_prompt_submit`, `pre_tool_use`, `post_tool_use`, `post_tool_use_failure`, `permission_request`, `stop`, `stop_failure`, `subagent_start`, `subagent_stop`, `notification`, `pre_compact`. Unknown harness events pass through as `unknown_event` (never dropped).\n- Envelope: `{ \"v\": 1, \"event\", \"agent\", \"session\", \"pane\", \"receivedAt\", \"payload\": { \u2026 } }` \u2014 strings capped at 8 KB, nodes at 500.\n- Per-harness mapping (Claude's PascalCase `:class` names \u2192 canonical; Codex/Gemini are already snake_case) is tabled in `references/events.md`. Read that file before reasoning about any specific payload.\n\n## Steering, approved skills and memory\n\nWith the listener running (`npx heedvane listener start`) and a sign-in (`npx heedvane login`; CI and headless machines: `npx heedvane auth org` with the key on stdin), the listener answers each hook with a verdict instead of only recording it:\n\n- **Steering:** every rule of the organization that matches is enforced: a tool call is denied or a stop is blocked, with the rule's message as the reason. A session's stops are blocked at most four times in a row; the next one ends the turn so the person sees why, and no later stop of that session is blocked. No hook waits on Heedvane. Command and path rules are synced to the listener at each session start and checked locally, so they hold even when Heedvane is slow or down. Heedvane judges every event in the background, and a rule it finds violated blocks the agent's next tool call or stop.\n- **Organization instructions:** the organization's non-negotiable rules are added as context at session start or with each prompt. They cannot be turned off, and the rules named with them enforce them.\n- **Approved skills:** `npx heedvane skills sync` installs the organization's approved skills into `~/.agents/skills` and `~/.claude/skills` and caches the list in `~/.heed/approved-skills.json`. Using any other skill (the Skill tool, or reading its `SKILL.md`) is denied; writing a skill is not. `heed.yaml` `heedvane.skills` sets `enforce`, `strict` (also compare file hashes) and `whenUnknown` (what to do before the first sync or while the listener is down).\n- **Private memory** (local only, never sent to Heedvane): at session start the hook adds `~/.heed/memory/MEMORY.md` (every repository) and `~/.heed/memory/<owner>/<name>.md` (this repository) as context, so every agent sees them. To save a private memory, append a short line to the right file.\n\n- **Team memory:** at session start the hook adds a table of contents of this repository's team memory (folders and titles, never the text). Browse and read it with `npx heedvane memory list [folder]`, `npx heedvane memory show <id>` and `npx heedvane memory search \"<question>\" [--folder <folder>]`.\n\nBackend failures never block the agent: without Heedvane's answer, the locally checked rules decide, and every enforcement is reported to Heedvane.\n\n## Common Pitfalls\n\n- **Do not rewrite `~/.claude/settings.json` (or any agent config) manually while hooks are installed.** Hand edits fight the compiler; the next `setup` will either back up your change or report the file invalid. Edit `heed.yaml` instead.\n- **Spool files are diagnostics, not policy.** When the listener is unreachable, hook payloads spool to `~/.heed/spool/` (5 MB cap, 7-day TTL) so nothing is lost \u2014 but spool presence is not enforcement, and clearing it loses observability history only.\n- Warp gets policies **via MCP only** \u2014 that is the designed happy path, not an error to fix.\n- If `doctor` reports `invalid` on a config, the file does not parse; heedvane never overwrites malformed configs. Fix or move the file aside yourself, then re-run.\n- Re-running `setup` after no changes reports \"already current\" \u2014 idempotence is a feature, not a stalled run.\n\n## Verification Checklist\n\n- [ ] `npx heedvane doctor` exits 0 and every check line shows ok\n- [ ] `~/.heed/heed.yaml` parses and says `schemaVersion: v1`\n- [ ] `~/.heed/state.json` skill digest matches the installed skill\n- [ ] A new agent session (launched with `HEED_SESSION` set, or any session with `gating.mode: always`) produces events in the listener log or `~/.heed/spool/`\n- [ ] Backups exist: `<config>.heedvane.backup` next to every patched config\n- [ ] `/heedvane-status` in a fresh agent session reports the same agents as `doctor`\n";
-export declare const EVENTS_MD = "# Heedvane event contract (v1)\n\nHarness-neutral taxonomy + JSON envelope. One normalizer maps every\nper-source payload into the canonical shape; unknown events pass through\nas `unknown_event` rather than being dropped.\n\n## Canonical events (v1)\n\n| Event | Fires when |\n| --- | --- |\n| `session_start` | A managed agent session begins |\n| `session_end` | The session ends (clean or crash) |\n| `user_prompt_submit` | The user submits a prompt |\n| `pre_tool_use` | Before a tool call executes |\n| `post_tool_use` | After a tool call returns |\n| `post_tool_use_failure` | A tool call raises/errors |\n| `permission_request` | The agent asks for approval |\n| `stop` | The agent turn completes |\n| `stop_failure` | The turn aborts with an error |\n| `subagent_start` | A subagent/task tool spawns |\n| `subagent_stop` | The subagent finishes |\n| `notification` | Harness notification (idle, attention, updates) |\n| `pre_compact` | Before the harness compacts the conversation |\n\n## Envelope\n\n```json\n{\n  \"v\": 1,\n  \"event\": \"pre_tool_use\",\n  \"agent\": \"claude\",\n  \"session\": \"sess_01HQ\u2026\",\n  \"pane\": \"iterm:tab-3\",\n  \"receivedAt\": \"2026-10-10T12:00:00.000Z\",\n  \"payload\": { \"tool\": \"Bash\", \"input\": { \"command\": \"ls\" } }\n}\n```\n\nCaps (Orca's numbers): strings \u2264 8 KB, \u2264 500 nodes per payload; oversized\nfields are truncated at ingest, never dropped.\n\n## Per-harness mapping\n\n| Canonical | Claude Code / Codex | Gemini CLI | Cursor | Hermes plugin |\n| --- | --- | --- | --- | --- |\n| `session_start` | `SessionStart` | `SessionStart` | `sessionStart` | `on_session_start` |\n| `session_end` | `SessionEnd` | `SessionEnd` | `sessionEnd` | `on_session_finalize` |\n| `user_prompt_submit` | `UserPromptSubmit` | `BeforeAgent` | `beforeSubmitPrompt` | `pre_llm_call` |\n| `pre_tool_use` | `PreToolUse` | `BeforeTool` | `preToolUse` | `pre_tool_call` |\n| `post_tool_use` | `PostToolUse` | `AfterTool` | `postToolUse` | `post_tool_call` |\n| `post_tool_use_failure` | `PostToolUseFailure` | \u2014 | \u2014 | \u2014 |\n| `permission_request` | `PermissionRequest` | \u2014 | \u2014 | `pre_approval_request` |\n| `stop` | `Stop` | `AfterAgent` | `stop` | \u2014 |\n| `stop_failure` | `StopFailure` | \u2014 | \u2014 | \u2014 |\n| `subagent_start` | `SubagentStart` | \u2014 | \u2014 | \u2014 |\n| `subagent_stop` | `SubagentStop` | \u2014 | `subagentStop` | \u2014 |\n| `notification` | `Notification` | `Notification` | \u2014 | \u2014 |\n| `pre_compact` | `PreCompact` | `PreCompress` | \u2014 | \u2014 |\n\nHermes' `on_session_end` fires once per turn despite its name, so it passes\nthrough as `unknown_event`, as does `post_approval_response`. Cursor's session\nis its `conversation_id`.\n\nWarp emits no native events at all \u2014 it has no hooks. Policy for Warp\narrives via MCP tool calls; nothing in this table applies to it.\n\nPayload keys per source keep their harness names inside `payload` (e.g.\nClaude's `tool_input`, Codex's `tool_input`) after normalization of the\nenvelope itself; the normalizer never invents fields.\n";
+export declare const SKILL_MD = "---\nname: heedvane-hooks\ndescription: Use when a user asks about heedvane hooks status, events, or how their coding agents are monitored \u2014 reports live hook installation state and the canonical event contract.\n---\n\n# heedvane-hooks\n\n## Overview\n\nHeedvane hooks give coding agents (Claude Code, Codex, Gemini CLI, Cursor, Warp, OpenCode, Hermes, Pi) a shared steering/guardrail/analysis channel without touching their internals. Three strictly separated layers:\n\n1. **Hook contract** \u2014 a harness-neutral event taxonomy (`pre_tool_use`, `post_tool_use`, \u2026), one JSON envelope, one normalizer. See `references/events.md`.\n2. **Per-agent adapters** \u2014 native hook config injection where the harness has hooks (Claude, Codex, Gemini, Cursor); Heedvane's MCP connection in every agent (Claude Desktop through the mcp-remote bridge); an honest skip where an agent has no hooks (Warp).\n3. **Setup mechanism** \u2014 `npx heedvane`: `connect` / `setup` / `doctor` / `uninstall` with backup \u2192 atomic write \u2192 read-back verify. Human intent lives in `~/.heed/heed.yaml`; machine state in `~/.heed/state.json`.\n\nWhich sessions run the hooks follows `heed.yaml` `gating.mode`: with `always` (the default) every session is governed, with `pane` only sessions launched with `HEED_SESSION` set. The dispatcher script (for Hermes, its plugin; for Pi, Heedvane's guard extension) decides, from the mode `setup` bakes into it, and always exits 0. Observability never blocks the agent.\n\n## When to Use\n\n- \"Is my heedvane install healthy?\" / \"why aren't hooks firing?\"\n- \"What events does heedvane capture?\" / \"what shape is the payload?\"\n- \"Which of my agents are monitored?\"\n- After the user edits `~/.heed/heed.yaml` and wants the change applied/verified.\n\nDo **not** use this skill to author policies \u2014 an organization's policies are defined and assigned on the Heedvane server, never in `heed.yaml`.\n\n## Checking status\n\n1. Run the doctor (scoped, exit-code-carrying):\n\n   ```sh\n   npx heedvane doctor --json\n   ```\n\n   Or unscoped plain text: `npx heedvane doctor`. Every failing check carries a `remediation` string \u2014 surface it verbatim.\n\n2. Read the control file \u2014 it is the single source of truth for intent:\n\n   ```sh\n   cat ~/.heed/heed.yaml\n   ```\n\n   `agents: auto` manages every detected agent; an explicit list filters. `install.hooks/skill/mcp` toggles channels per agent.\n\n3. **Never edit agent configs by hand.** `~/.claude/settings.json`, `~/.codex/hooks.json`, etc. are compiled outputs. Edit `heed.yaml`, then re-run:\n\n   ```sh\n   npx heedvane setup\n   ```\n\n4. Machine state (installed digests, endpoint, protocol version) is `~/.heed/state.json` \u2014 CLI-owned, never hand-edit.\n\n## Event contract summary\n\n- Canonical events (v1, snake_case): `session_start`, `session_end`, `user_prompt_submit`, `pre_tool_use`, `post_tool_use`, `post_tool_use_failure`, `permission_request`, `stop`, `stop_failure`, `subagent_start`, `subagent_stop`, `notification`, `pre_compact`. Unknown harness events pass through as `unknown_event` (never dropped).\n- Envelope: `{ \"v\": 1, \"event\", \"agent\", \"session\", \"pane\", \"receivedAt\", \"payload\": { \u2026 } }` \u2014 strings capped at 8 KB, nodes at 500.\n- Per-harness mapping (Claude's PascalCase `:class` names \u2192 canonical; Codex/Gemini are already snake_case) is tabled in `references/events.md`. Read that file before reasoning about any specific payload.\n\n## Steering, approved skills and memory\n\nWith the listener running (`npx heedvane listener start`) and a sign-in (`npx heedvane login`; CI and headless machines: `npx heedvane auth org` with the key on stdin), the listener answers each hook with a verdict instead of only recording it:\n\n- **Steering:** every rule of the organization that matches is enforced: a tool call is denied or a stop is blocked, with the rule's message as the reason. A session's stops are blocked at most four times in a row; the next one ends the turn so the person sees why, and no later stop of that session is blocked. No hook waits on Heedvane. Command and path rules are synced to the listener at each session start and checked locally, so they hold even when Heedvane is slow or down. Heedvane judges every event in the background, and a rule it finds violated blocks the agent's next tool call or stop.\n- **Organization instructions:** the organization's non-negotiable rules are added as context at session start or with each prompt. They cannot be turned off, and the rules named with them enforce them.\n- **Approved skills:** `npx heedvane skills sync` installs the organization's approved skills into `~/.agents/skills` and `~/.claude/skills` and caches the list in `~/.heed/approved-skills.json`. Using any other skill (the Skill tool, or reading its `SKILL.md`) is denied; writing a skill is not. `heed.yaml` `heedvane.skills` sets `enforce`, `strict` (also compare file hashes) and `whenUnknown` (what to do before the first sync or while the listener is down).\n- **Private memory** (local only, never sent to Heedvane): at session start the hook adds `~/.heed/memory/MEMORY.md` (every repository) and `~/.heed/memory/<owner>/<name>.md` (this repository) as context, so every agent sees them. To save a private memory, append a short line to the right file.\n\n- **Team memory:** at session start the hook adds a table of contents of this repository's team memory (folders and titles, never the text). Browse and read it with `npx heedvane memory list [folder]`, `npx heedvane memory show <id>` and `npx heedvane memory search \"<question>\" [--folder <folder>]`.\n\nBackend failures never block the agent: without Heedvane's answer, the locally checked rules decide, and every enforcement is reported to Heedvane.\n\n## Common Pitfalls\n\n- **Do not rewrite `~/.claude/settings.json` (or any agent config) manually while hooks are installed.** Hand edits fight the compiler; the next `setup` will either back up your change or report the file invalid. Edit `heed.yaml` instead.\n- **Spool files are diagnostics, not policy.** When the listener is unreachable, hook payloads spool to `~/.heed/spool/` (5 MB cap, 7-day TTL) so nothing is lost \u2014 but spool presence is not enforcement, and clearing it loses observability history only.\n- Warp has no native hooks, so Heedvane adds only its MCP connection and the skill there \u2014 that is expected, not an error to fix.\n- If `doctor` reports `invalid` on a config, the file does not parse; heedvane never overwrites malformed configs. Fix or move the file aside yourself, then re-run.\n- Re-running `setup` after no changes reports \"already current\" \u2014 idempotence is a feature, not a stalled run.\n\n## Verification Checklist\n\n- [ ] `npx heedvane doctor` exits 0 and every check line shows ok\n- [ ] `~/.heed/heed.yaml` parses and says `schemaVersion: v1`\n- [ ] `~/.heed/state.json` skill digest matches the installed skill\n- [ ] A new agent session (launched with `HEED_SESSION` set, or any session with `gating.mode: always`) produces events in the listener log or `~/.heed/spool/`\n- [ ] Backups exist: `<config>.heedvane.backup` next to every patched config\n- [ ] `npx heedvane status` reports state.json ok and the listener's endpoint\n";
+export declare const EVENTS_MD = "# Heedvane event contract (v1)\n\nHarness-neutral taxonomy + JSON envelope. One normalizer maps every\nper-source payload into the canonical shape; unknown events pass through\nas `unknown_event` rather than being dropped.\n\n## Canonical events (v1)\n\n| Event | Fires when |\n| --- | --- |\n| `session_start` | A managed agent session begins |\n| `session_end` | The session ends (clean or crash) |\n| `user_prompt_submit` | The user submits a prompt |\n| `pre_tool_use` | Before a tool call executes |\n| `post_tool_use` | After a tool call returns |\n| `post_tool_use_failure` | A tool call raises/errors |\n| `permission_request` | The agent asks for approval |\n| `stop` | The agent turn completes |\n| `stop_failure` | The turn aborts with an error |\n| `subagent_start` | A subagent/task tool spawns |\n| `subagent_stop` | The subagent finishes |\n| `notification` | Harness notification (idle, attention, updates) |\n| `pre_compact` | Before the harness compacts the conversation |\n\n## Envelope\n\n```json\n{\n  \"v\": 1,\n  \"event\": \"pre_tool_use\",\n  \"agent\": \"claude\",\n  \"session\": \"sess_01HQ\u2026\",\n  \"pane\": \"iterm:tab-3\",\n  \"receivedAt\": \"2026-10-10T12:00:00.000Z\",\n  \"payload\": { \"tool\": \"Bash\", \"input\": { \"command\": \"ls\" } }\n}\n```\n\nCaps (Orca's numbers): strings \u2264 8 KB, \u2264 500 nodes per payload; oversized\nfields are truncated at ingest, never dropped.\n\n## Per-harness mapping\n\n| Canonical | Claude Code / Codex | Gemini CLI | Cursor | Hermes plugin |\n| --- | --- | --- | --- | --- |\n| `session_start` | `SessionStart` | `SessionStart` | `sessionStart` | `on_session_start` |\n| `session_end` | `SessionEnd` | `SessionEnd` | `sessionEnd` | `on_session_finalize` |\n| `user_prompt_submit` | `UserPromptSubmit` | `BeforeAgent` | `beforeSubmitPrompt` | `pre_llm_call` |\n| `pre_tool_use` | `PreToolUse` | `BeforeTool` | `preToolUse` | `pre_tool_call` |\n| `post_tool_use` | `PostToolUse` | `AfterTool` | `postToolUse` | `post_tool_call` |\n| `post_tool_use_failure` | `PostToolUseFailure` | \u2014 | \u2014 | \u2014 |\n| `permission_request` | `PermissionRequest` | \u2014 | \u2014 | `pre_approval_request` |\n| `stop` | `Stop` | `AfterAgent` | `stop` | \u2014 |\n| `stop_failure` | `StopFailure` | \u2014 | \u2014 | \u2014 |\n| `subagent_start` | `SubagentStart` | \u2014 | \u2014 | \u2014 |\n| `subagent_stop` | `SubagentStop` | \u2014 | `subagentStop` | \u2014 |\n| `notification` | `Notification` | `Notification` | \u2014 | \u2014 |\n| `pre_compact` | `PreCompact` | `PreCompress` | \u2014 | \u2014 |\n\nPi's guard (the extension `connect` installs, or `heedvane/guard` in code built on Pi) sends only\n`pre_tool_use`, as Claude Code's `PreToolUse` with Claude Code's tool names.\n\nHermes' `on_session_end` fires once per turn despite its name, so it passes\nthrough as `unknown_event`, as does `post_approval_response`. Cursor's session\nis its `conversation_id`.\n\nWarp emits no native events at all \u2014 it has no hooks, so nothing in this\ntable applies to it.\n\nPayload keys per source keep their harness names inside `payload` (e.g.\nClaude's `tool_input`, Codex's `tool_input`) after normalization of the\nenvelope itself; the normalizer never invents fields.\n";
 export interface SkillFile {
     relativePath: string;
     content: string;

package/dist/skill/content.js

@@ -14,13 +14,13 @@ description: Use when a user asks about heedvane hooks status, events, or how th
 
 ## Overview
 
-Heedvane hooks give coding agents (Claude Code, Codex, Gemini CLI, Cursor, Warp, OpenCode, Hermes) a shared steering/guardrail/analysis channel without touching their internals. Three strictly separated layers:
+Heedvane hooks give coding agents (Claude Code, Codex, Gemini CLI, Cursor, Warp, OpenCode, Hermes, Pi) a shared steering/guardrail/analysis channel without touching their internals. Three strictly separated layers:
 
 1. **Hook contract** — a harness-neutral event taxonomy (\`pre_tool_use\`, \`post_tool_use\`, …), one JSON envelope, one normalizer. See \`references/events.md\`.
-2. **Per-agent adapters** — native hook config injection where the harness has hooks (Claude, Codex, Gemini, Cursor); MCP registration as the universal fallback (Warp has no native hooks — policy arrives via MCP); an honest skip where neither exists.
-3. **Setup mechanism** — \`heedvane-hook\` CLI: \`init\` / \`setup\` / \`doctor\` / \`uninstall\` with backup → atomic write → read-back verify. Human intent lives in \`~/.heed/heed.yaml\`; machine state in \`~/.heed/state.json\`.
+2. **Per-agent adapters** — native hook config injection where the harness has hooks (Claude, Codex, Gemini, Cursor); Heedvane's MCP connection in every agent (Claude Desktop through the mcp-remote bridge); an honest skip where an agent has no hooks (Warp).
+3. **Setup mechanism** — \`npx heedvane\`: \`connect\` / \`setup\` / \`doctor\` / \`uninstall\` with backup → atomic write → read-back verify. Human intent lives in \`~/.heed/heed.yaml\`; machine state in \`~/.heed/state.json\`.
 
-Which sessions run the hooks follows \`heed.yaml\` \`gating.mode\`: with \`always\` (the default) every session is governed, with \`pane\` only sessions launched with \`HEED_SESSION\` set. The dispatcher script (for Hermes, its plugin) decides, from the mode \`setup\` bakes into it, and always exits 0. Observability never blocks the agent.
+Which sessions run the hooks follows \`heed.yaml\` \`gating.mode\`: with \`always\` (the default) every session is governed, with \`pane\` only sessions launched with \`HEED_SESSION\` set. The dispatcher script (for Hermes, its plugin; for Pi, Heedvane's guard extension) decides, from the mode \`setup\` bakes into it, and always exits 0. Observability never blocks the agent.
 
 ## When to Use
 
@@ -80,7 +80,7 @@ Backend failures never block the agent: without Heedvane's answer, the locally c
 
 - **Do not rewrite \`~/.claude/settings.json\` (or any agent config) manually while hooks are installed.** Hand edits fight the compiler; the next \`setup\` will either back up your change or report the file invalid. Edit \`heed.yaml\` instead.
 - **Spool files are diagnostics, not policy.** When the listener is unreachable, hook payloads spool to \`~/.heed/spool/\` (5 MB cap, 7-day TTL) so nothing is lost — but spool presence is not enforcement, and clearing it loses observability history only.
-- Warp gets policies **via MCP only** — that is the designed happy path, not an error to fix.
+- Warp has no native hooks, so Heedvane adds only its MCP connection and the skill there — that is expected, not an error to fix.
 - If \`doctor\` reports \`invalid\` on a config, the file does not parse; heedvane never overwrites malformed configs. Fix or move the file aside yourself, then re-run.
 - Re-running \`setup\` after no changes reports "already current" — idempotence is a feature, not a stalled run.
 
@@ -91,7 +91,7 @@ Backend failures never block the agent: without Heedvane's answer, the locally c
 - [ ] \`~/.heed/state.json\` skill digest matches the installed skill
 - [ ] A new agent session (launched with \`HEED_SESSION\` set, or any session with \`gating.mode: always\`) produces events in the listener log or \`~/.heed/spool/\`
 - [ ] Backups exist: \`<config>.heedvane.backup\` next to every patched config
-- [ ] \`/heedvane-status\` in a fresh agent session reports the same agents as \`doctor\`
+- [ ] \`npx heedvane status\` reports state.json ok and the listener's endpoint
 `;
 export const EVENTS_MD = `# Heedvane event contract (v1)
 
@@ -152,12 +152,15 @@ fields are truncated at ingest, never dropped.
 | \`notification\` | \`Notification\` | \`Notification\` | — | — |
 | \`pre_compact\` | \`PreCompact\` | \`PreCompress\` | — | — |
 
+Pi's guard (the extension \`connect\` installs, or \`heedvane/guard\` in code built on Pi) sends only
+\`pre_tool_use\`, as Claude Code's \`PreToolUse\` with Claude Code's tool names.
+
 Hermes' \`on_session_end\` fires once per turn despite its name, so it passes
 through as \`unknown_event\`, as does \`post_approval_response\`. Cursor's session
 is its \`conversation_id\`.
 
-Warp emits no native events at all — it has no hooks. Policy for Warp
-arrives via MCP tool calls; nothing in this table applies to it.
+Warp emits no native events at all — it has no hooks, so nothing in this
+table applies to it.
 
 Payload keys per source keep their harness names inside \`payload\` (e.g.
 Claude's \`tool_input\`, Codex's \`tool_input\`) after normalization of the

package/dist/status.d.ts

@@ -0,0 +1 @@
+export declare function statusText(): Promise<string>;

package/dist/status.js

@@ -0,0 +1,29 @@
+/** `npx heedvane status`: a quick summary of this machine's install (state.json, the listener). */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { HeedStateCorruptError, readState } from "./state.js";
+import { readEndpoint } from "./listener/endpoint.js";
+export async function statusText() {
+    const home = process.env.HEED_HOME ?? homedir();
+    const root = join(home, ".heed");
+    const lines = [`heedvane hooks status (home: ${home})`];
+    try {
+        const state = await readState(root);
+        if (state !== null) {
+            const skill = state.skill?.digest.slice(0, 12) ?? "not installed";
+            lines.push(`  state.json: ok (protocol v${state.protocolVersion}, skill ${skill})`);
+        }
+        else {
+            lines.push("  state.json: absent (run npx heedvane init)");
+        }
+    }
+    catch (error) {
+        if (!(error instanceof HeedStateCorruptError))
+            throw error;
+        lines.push(`  state.json: ${error.message}`);
+    }
+    const endpoint = await readEndpoint(root);
+    lines.push(`  listener: ${endpoint ? `endpoint.env present (port ${endpoint.port})` : `not configured — events spool to ${join(root, "spool")}`}`);
+    lines.push("  next: npx heedvane doctor for scoped checks");
+    return lines.join("\n");
+}

package/dist/steering/rules.js

@@ -13,7 +13,9 @@
  * injects instructions before its first sync, and with Heedvane down.
  */
 import { readFile } from "node:fs/promises";
-import { isAbsolute, join, matchesGlob, normalize, relative } from "node:path";
+import { isAbsolute, join, normalize, relative } from "node:path";
+// A namespace import: matchesGlob is Node 22.5's, and naming it in an import fails the whole CLI at load on 22.0 to 22.4.
+import * as nodePath from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { callHeedvane } from "../backend/client.js";
 import { isRecord } from "../guards.js";
@@ -109,7 +111,7 @@ function matches(rule, input, cwd) {
     const touched = touchedFile(input, cwd);
     // Normalized first, so `./././` padding cannot push a real file past the length bound.
     const path = touched === null ? null : normalize(touched);
-    return path !== null && path.length <= MAX_MATCHED_PATH && rule.patterns.some((glob) => matchesGlob(path, glob));
+    return path !== null && path.length <= MAX_MATCHED_PATH && rule.patterns.some((glob) => nodePath.matchesGlob(path, glob));
 }
 /** The file a tool event touches, relative to `cwd` when inside it (Heedvane's `touchedFile`). */
 function touchedFile(input, cwd) {

package/dist/uninstall.d.ts

@@ -20,4 +20,11 @@ export declare function removeStaleHookGroups(client: ResolvedClient, target: {
 }): Promise<UninstallItem[]>;
 /** When hooksDeferredTo skips a client whose hooks an earlier run installed, remove our hook groups so events do not fire twice. */
 export declare function removeDeferredHookGroups(client: ResolvedClient): Promise<UninstallItem[]>;
+/**
+ * Setup's half for MCP: the entries an earlier version registered (the local helper, the connection's earlier name),
+ * removed from every config; under metrics only (`match` = isHeedvaneEntry), today's connection too.
+ */
+export declare function removeLegacyMcpEntries(client: ResolvedClient, match?: (name: string, entry: unknown) => boolean): Promise<UninstallItem[]>;
 export declare function uninstall(input: UninstallInput): Promise<UninstallItem[]>;
+/** Uninstall asks the background listener to stop (POST /shutdown) and waits until it has. */
+export declare function stopListener(root: string): Promise<UninstallItem>;