heedvane 0.2.0 → 0.3.3

package/dist/plan.d.ts

@@ -21,11 +21,6 @@ export interface PlanInput {
     /** Desired skill digest; defaults to the canonical bundled content. */
     skillDigest?: string;
 }
-/** Our MCP stdio registration entry (unscoped package per the plan's decision). */
-export declare function mcpEntry(): {
-    command: string;
-    args: string[];
-};
 interface Desired {
     path: string;
     format: DocFormat;
@@ -42,6 +37,8 @@ export declare function hooksTarget(client: ResolvedClient): {
 export interface ClientContext {
     home: string;
     env: Env;
+    /** Heedvane's MCP connection URL (`connect --org`), registered where the agent takes it. */
+    connector?: string;
 }
 /**
  * Desired write targets per client × capability. This is the desired-state
@@ -52,6 +49,19 @@ export interface ClientContext {
 export declare function desiredEntriesFor(client: ResolvedClient, capability: Capability, context: ClientContext & {
     gating?: HeedGatingConfig["mode"];
 }): Desired[];
+/** The folder of the Node running this install: the hook dispatcher records it, and a local MCP bridge runs its npx. */
+export declare function installingNodeDir(): string;
+/** Heedvane's MCP connection URL for the organization heed.yaml names; none without one. */
+export declare function heedvaneConnector(heedFile: HeedFile): string | 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 declare function mcpContainers(client: ResolvedClient): string[];
+/** The doc's parsed value, or null when the config is absent or unparseable — nothing marker-verified to remove. */
+export declare function parseClientDoc(path: string, format: DocFormat): Record<string, unknown> | null;
+/** The first config of this client still holding an MCP entry an earlier version wrote, and those entries' names. */
+export declare function legacyMcpEntries(client: ResolvedClient): {
+    path: string;
+    names: string[];
+} | undefined;
 /**
  * The client whose hooks this one already runs, when that client's hooks are installed too, by this run or
  * an earlier one: installing both would run every event twice, recorded under two agents. Plan and doctor

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 { dirname, join } from "node:path";
 import { supportedClients, } from "./clients/definitions.js";
 import { hermesPluginFiles } from "./clients/hermes-plugin.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, connectorEntry, connectorUrl, isLegacyEntry, 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];
@@ -59,14 +55,45 @@ 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) });
+        // Windows keeps the bare `npx` its docs show: a `.cmd` path cannot be started without a shell.
+        const entry = context.connector === undefined ? undefined : connectorEntry(client.id, context.connector, process.platform === "win32" ? undefined : installingNodeDir());
+        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
 }
+/** The folder of the Node running this install: the hook dispatcher records it, and a local MCP bridge runs its npx. */
+export function installingNodeDir() {
+    return dirname(process.execPath);
+}
+/** Heedvane's MCP connection URL for the organization heed.yaml names; none without one. */
+export function heedvaneConnector(heedFile) {
+    return heedFile.heedvane.org === undefined ? undefined : connectorUrl(heedFile.heedvane.url, heedFile.heedvane.org);
+}
+/** 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
+    }
+}
+/** The first config of this client still holding an MCP entry an earlier version wrote, and those entries' names. */
+export function legacyMcpEntries(client) {
+    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), isLegacyEntry).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);
@@ -152,8 +179,7 @@ function inspect(d) {
         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" };
@@ -210,11 +236,22 @@ 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 action: write the connection where it is wanted, and remove what an earlier version registered either way. */
+function planMcp(client, desireds) {
+    const legacy = legacyMcpEntries(client);
+    const removal = legacy === undefined ? undefined : { operation: "update", path: legacy.path, backupPath: `${legacy.path}.heedvane.backup`, reason: `replaces ${legacy.names.join(", ")}, which an earlier version registered` };
+    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 };
+}
 /** One client × one capability → its planned action, or null when nothing to plan. */
 function planCapability(client, capability, ctx) {
     if (!ctx.heedFile.install[capability])
@@ -228,21 +265,11 @@ 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) });
+    if (capability === "mcp")
+        return planMcp(client, desireds);
     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)
     const primary = desireds[0];
     const worst = worstHooksResult(desireds);

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"))
         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:"];

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) 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 `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 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\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

@@ -17,7 +17,7 @@ description: Use when a user asks about heedvane hooks status, events, or how th
 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:
 
 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.
+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** — \`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\`.
 
 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.
@@ -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)
 
@@ -156,8 +156,8 @@ 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 ~/.heed/spool"}`);
+    lines.push("  next: npx heedvane doctor for scoped checks");
+    return lines.join("\n");
+}

package/dist/uninstall.d.ts

@@ -20,4 +20,6 @@ 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. */
+export declare function removeLegacyMcpEntries(client: ResolvedClient): Promise<UninstallItem[]>;
 export declare function uninstall(input: UninstallInput): Promise<UninstallItem[]>;

package/dist/uninstall.js

@@ -4,18 +4,21 @@
  * byte-identical. heed.yaml is NEVER touched (the user's file) unless
  * --purge-config is passed, and even then it is deleted, not rewritten.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { join } from "node:path";
 import { supportedClients } from "./clients/definitions.js";
 import { hermesPluginOwned } from "./clients/hermes-plugin.js";
 import { applyEntry } from "./apply.js";
-import { isOurHookGroup, parseDoc } from "./config-doc.js";
-import { isHeedvaneEntry } from "./mcp.js";
-import { hooksTarget, isClientDetected } from "./plan.js";
+import { isOurHookGroup } from "./config-doc.js";
+import { isHeedvaneEntry, isLegacyEntry, mcpEntryNames } from "./mcp.js";
+import { hooksTarget, isClientDetected, mcpContainers, parseClientDoc } from "./plan.js";
 import { skillInstallDir } from "./skill/bundle.js";
 import { statePath } from "./state.js";
 import { unlinkOptional } from "./best-effort.js";
+import { pingListener, readEndpoint } from "./listener/endpoint.js";
+import { SHUTDOWN_ROUTE } from "./listener/server.js";
+import { setTimeout as delay } from "node:timers/promises";
 /** Hook events carrying one of our groups, with the user's own groups that must survive. */
 function ourHookEvents(doc) {
     const hooks = doc["hooks"];
@@ -25,28 +28,6 @@ function ourHookEvents(doc) {
         .filter(([, groups]) => Array.isArray(groups) && groups.some(isOurHookGroup))
         .map(([event, groups]) => ({ event, theirs: groups.filter((group) => !isOurHookGroup(group)) }));
 }
-function ourMcpEntryNames(doc, containerKeys) {
-    const names = [];
-    for (const key of containerKeys) {
-        const c = doc[key];
-        if (c === null || typeof c !== "object" || Array.isArray(c))
-            continue;
-        for (const [k, v] of Object.entries(c)) {
-            if (isHeedvaneEntry(k, v))
-                names.push(`${key}::${k}`);
-        }
-    }
-    return names;
-}
-/** The doc's parsed value, or null when the config is absent or unparseable — nothing marker-verified to remove. */
-function parseClientDoc(path, format) {
-    try {
-        return parseDoc(readFileSync(path, "utf8"), format).value;
-    }
-    catch {
-        return null; // absent or unparseable — nothing marker-verified to remove
-    }
-}
 /**
  * Remove our hook groups from every event of one parsed config except those in `keep`, leaving the
  * user's own groups. Setup passes the events it installs, so a key an earlier version wrote under a
@@ -78,16 +59,34 @@ export async function removeDeferredHookGroups(client) {
     const doc = parseClientDoc(target.path, target.format);
     return doc === null ? [] : removeOurHookGroups(client, target, { doc, keep: new Set() });
 }
+/** Remove the MCP entries `match` accepts from one parsed config; one item per removal. */
+async function removeMcpEntries(client, target, scope) {
+    const items = [];
+    for (const qualified of mcpEntryNames(scope.doc, mcpContainers(client), scope.match)) {
+        const [containerKey, entryName] = qualified.split("::");
+        const res = await applyEntry(target, { containerKey, remove: entryName });
+        items.push({ clientId: client.id, name: `MCP ${entryName}`, path: target.path, status: res.status === "update" ? "removed" : "failed", detail: res.reason });
+    }
+    return items;
+}
+/** Setup's half for MCP: the entries an earlier version registered (the local helper, the connection's earlier name), removed from every config. */
+export async function removeLegacyMcpEntries(client) {
+    const items = [];
+    for (const target of client.configs) {
+        if (target.format === "yaml")
+            continue;
+        const doc = parseClientDoc(target.path, target.format);
+        if (doc !== null)
+            items.push(...(await removeMcpEntries(client, { path: target.path, format: target.format }, { doc, match: isLegacyEntry })));
+    }
+    return items;
+}
 /** Remove every marker-verified entry of one config file; one item per removal. */
 async function removeMarkedEntries(client, target, doc) {
     // Both kinds can live in the same file (claude settings.json carries
     // hooks AND mcpServers) — remove ours from every container.
     const items = await removeOurHookGroups(client, target, { doc, keep: new Set() });
-    for (const qualified of ourMcpEntryNames(doc, [client.mcpServersKey, "mcp_servers", "mcp"])) {
-        const [containerKey, entryName] = qualified.split("::");
-        const res = await applyEntry(target, { containerKey, remove: entryName });
-        items.push({ clientId: client.id, name: `MCP ${entryName}`, path: target.path, status: res.status === "update" ? "removed" : "failed", detail: res.reason });
-    }
+    items.push(...(await removeMcpEntries(client, target, { doc, match: isHeedvaneEntry })));
     return items;
 }
 /** One non-hermes client's config files: parse each and remove our marked entries. */
@@ -150,10 +149,34 @@ async function removeSharedFiles(home, scoped) {
     await rm(skillDir, { recursive: true, force: true });
     await unlinkOptional(statePath(join(home, ".heed")));
     return [
+        await stopListener(join(home, ".heed")),
         { clientId: "*", name: "skill bundle", path: skillDir, status: "removed" },
         { clientId: "*", name: "state.json", path: statePath(join(home, ".heed")), status: "removed" },
     ];
 }
+/** How long uninstall waits for the listener to stop answering after asking it to stop. */
+const STOP_WAIT_MS = 3_000;
+const STOP_POLL_MS = 100;
+/** The background listener answers hooks that are gone now: ask it to stop (POST /shutdown) and wait until it has. */
+async function stopListener(root) {
+    const endpoint = await readEndpoint(root).catch(() => null);
+    const item = { clientId: "*", name: "listener", path: `127.0.0.1:${endpoint?.port ?? 0}` };
+    if (endpoint === null || !(await pingListener(endpoint)))
+        return { ...item, status: "absent" };
+    const asked = await fetch(`http://127.0.0.1:${endpoint.port}${SHUTDOWN_ROUTE}`, {
+        method: "POST",
+        headers: { "x-heed-agent-hook-token": endpoint.token },
+        signal: AbortSignal.timeout(STOP_WAIT_MS),
+    }).catch(() => null);
+    for (let waited = 0; waited < STOP_WAIT_MS; waited += STOP_POLL_MS) {
+        if (!(await pingListener(endpoint)))
+            return { ...item, status: "removed" };
+        await delay(STOP_POLL_MS);
+    }
+    // A listener from 0.2.0 or earlier has no stop route (404); it ends at logout or restart.
+    const detail = asked?.status === 404 ? "an older listener is still running; it stops at logout or restart" : "the listener did not stop; it stops at logout or restart";
+    return { ...item, status: "failed", detail };
+}
 function existsMarker(client) {
     return isClientDetected(client);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heedvane",
-  "version": "0.2.0",
+  "version": "0.3.3",
   "description": "Heedvane for coding agents: one command installs steering, guardrails, team memory and skill checks into Claude Code, Codex, Cursor, Gemini CLI and more.",
   "private": false,
   "type": "module",

package/skills/heedvane-hooks/SKILL.md

@@ -10,7 +10,7 @@ description: Use when a user asks about heedvane hooks status, events, or how th
 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:
 
 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.
+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** — `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`.
 
 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.
@@ -73,7 +73,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.
 
@@ -84,4 +84,4 @@ 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

package/skills/heedvane-hooks/references/events.md

@@ -61,8 +61,8 @@ 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/mcp-server.d.ts

@@ -1,9 +0,0 @@
-export interface McpIo {
-    write: (line: string) => void;
-    log: (line: string) => void;
-}
-export declare function statusText(): Promise<string>;
-/** Entry point for the `mcp` subcommand. */
-export declare function runMcpStdio(io: Pick<McpIo, "write"> & {
-    log?: (line: string) => void;
-}): void;