heedvane 0.3.3 → 0.3.4

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/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); 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 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); 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\`.
+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
 
@@ -152,6 +152,9 @@ 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\`.

package/dist/status.js

@@ -23,7 +23,7 @@ export async function statusText() {
         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(`  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,6 +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. */
-export declare function removeLegacyMcpEntries(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>;

package/dist/uninstall.js

@@ -4,11 +4,10 @@
  * 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 } 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 { removeHookFiles } from "./clients/hook-files.js";
 import { applyEntry } from "./apply.js";
 import { isOurHookGroup } from "./config-doc.js";
 import { isHeedvaneEntry, isLegacyEntry, mcpEntryNames } from "./mcp.js";
@@ -16,9 +15,10 @@ import { hooksTarget, isClientDetected, mcpContainers, parseClientDoc } from "./
 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";
+import { endpointPath, pingListener, readEndpoint } from "./listener/endpoint.js";
+import { errorMessage } from "./guards.js";
+import { stopRunningListener } from "./listener/background.js";
+import { FALLBACK_FILE, HOOK_NODE_FILE } from "./hook-fallback.js";
 /** Hook events carrying one of our groups, with the user's own groups that must survive. */
 function ourHookEvents(doc) {
     const hooks = doc["hooks"];
@@ -69,15 +69,18 @@ async function removeMcpEntries(client, target, scope) {
     }
     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) {
+/**
+ * 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 async function removeLegacyMcpEntries(client, match = isLegacyEntry) {
     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 })));
+            items.push(...(await removeMcpEntries(client, { path: target.path, format: target.format }, { doc, match })));
     }
     return items;
 }
@@ -89,7 +92,7 @@ async function removeMarkedEntries(client, target, doc) {
     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. */
+/** One client's config files: parse each and remove our marked entries. */
 async function uninstallClientConfigs(client, items) {
     for (const target of client.configs) {
         if (target.format === "yaml")
@@ -112,12 +115,9 @@ export async function uninstall(input) {
             if (!existsMarker(client))
                 continue;
         }
-        if (client.id !== "hermes") {
-            await uninstallClientConfigs(client, items);
-        }
-        else {
-            items.push(await uninstallHermesPlugin(home));
-        }
+        await uninstallClientConfigs(client, items);
+        if (client.hookFiles !== undefined)
+            items.push(await uninstallHookFiles(client, client.hookFiles));
         // Agent-hook dispatcher scripts owned by this client.
         const script = join(home, ".heed", "agent-hooks", `${client.id}-hook.sh`);
         await unlinkOptional(script);
@@ -126,19 +126,16 @@ export async function uninstall(input) {
     items.push(...(await removeSharedFiles(home, scope !== null)));
     if (input.purgeConfig) {
         await unlinkOptional(join(home, ".heed", "heed.yaml"));
+        await unlinkOptional(join(home, ".heed", "heed.yaml.last-good")); // the listener's copy of it
         items.push({ clientId: "*", name: "heed.yaml (purged)", path: join(home, ".heed", "heed.yaml"), status: "removed" });
     }
     return items;
 }
-/** The Hermes plugin dir, removed only when its plugin.yaml declares our plugin. */
-async function uninstallHermesPlugin(home) {
-    const pluginDir = join(home, ".hermes", "plugins", "heedvane-hooks");
-    const item = { clientId: "hermes", name: "hermes plugin", path: pluginDir };
-    if (await hermesPluginOwned(home)) {
-        await rm(pluginDir, { recursive: true, force: true });
-        return { ...item, status: "removed" };
-    }
-    return existsSync(pluginDir) ? { ...item, status: "skipped", detail: "not ours — left untouched" } : { ...item, status: "absent" };
+/** Hooks written as whole files (Hermes' plugin, Pi's extension), removed only when Heedvane wrote them. */
+async function uninstallHookFiles(client, hookFiles) {
+    const path = hookFiles.path(client.markerPath);
+    const status = await removeHookFiles(hookFiles, path);
+    return { clientId: client.id, name: hookFiles.name, path, status, ...(status === "skipped" ? { detail: "not ours — left untouched" } : {}) };
 }
 /** The skill bundle and state.json every agent shares: a scoped uninstall keeps them. */
 async function removeSharedFiles(home, scoped) {
@@ -148,33 +145,41 @@ async function removeSharedFiles(home, scoped) {
     }
     await rm(skillDir, { recursive: true, force: true });
     await unlinkOptional(statePath(join(home, ".heed")));
+    await unlinkOptional(join(home, ".heed", "agent-hooks", FALLBACK_FILE)); // every dispatcher's, beside their scripts
+    await unlinkOptional(join(home, ".heed", "agent-hooks", HOOK_NODE_FILE));
     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);
+/** Uninstall asks the background listener to stop (POST /shutdown) and waits until it has. */
+export async function stopListener(root) {
+    const unknownPort = (reason) => ({
+        clientId: "*",
+        name: "listener",
+        path: endpointPath(root),
+        status: "failed",
+        detail: `${reason}, so a listener still running cannot be asked to stop; it stops at logout or restart. Delete the file to clear this`,
+    });
+    let endpoint;
+    try {
+        endpoint = await readEndpoint(root);
+    }
+    catch (err) {
+        return unknownPort(`cannot read it (${errorMessage(err)})`);
     }
-    // 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";
+    if (endpoint?.port === 0)
+        return unknownPort("it names no port");
+    if (endpoint === null)
+        return { clientId: "*", name: "listener", path: endpointPath(root), status: "absent" };
+    const item = { clientId: "*", name: "listener", path: `127.0.0.1:${endpoint.port}` };
+    if (!(await pingListener(endpoint)))
+        return { ...item, status: "absent" };
+    const stopped = await stopRunningListener(endpoint);
+    if (stopped === "stopped")
+        return { ...item, status: "removed" };
+    const detail = stopped === "no stop route" ? "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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heedvane",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "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",
@@ -8,15 +8,22 @@
     "heedvane": "dist/cli.js",
     "heedvane-hook": "dist/cli.js"
   },
+  "exports": {
+    "./guard": {
+      "types": "./dist/guard.d.ts",
+      "default": "./dist/guard.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist",
     "skills"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.5"
   },
   "scripts": {
-    "test": "node --experimental-strip-types --disable-warning=ExperimentalWarning --import ./tests/register-ts-resolver.mjs --test \"tests/**/*.test.ts\"",
+    "test": "node --experimental-strip-types --disable-warning=ExperimentalWarning --import ./tests/register-ts-resolver.mjs --import ./tests/temp-cleanup.mjs --test \"tests/**/*.test.ts\"",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json",
     "build": "tsc -p tsconfig.json",

package/skills/heedvane-hooks/SKILL.md

@@ -7,13 +7,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); 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`.
+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
 

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

@@ -57,6 +57,9 @@ 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`.

package/dist/dispatchers/windows.d.ts

@@ -1,15 +0,0 @@
-import type { DispatcherOptions } from "./posix.js";
-/**
- * Windows .cmd launcher (best-effort tier — the plan marks Windows untested until
- * CI covers it). It:
- *   1. in heed.yaml's default `gating.mode: pane`, no-ops unless HEED_SESSION is set; with
- *      `always`, runs in every session (the POSIX dispatcher decides the same way);
- *   2. resolves the shared POSIX dispatcher via the two-tier lookup
- *      (HEED_AGENT_HOOK_ROOT → %HOME% → %USERPROFILE%);
- *   3. prefers running that dispatcher through any POSIX shell on PATH (Git for
- *      Windows / MSYS2 / BusyBox) — hook stdin passes through, so spooling still
- *      works with the listener down;
- *   4. otherwise posts via curl.exe with the same headers as the POSIX dispatcher and prints
- *      the listener's answer (nothing, which lets the agent continue, when it fails).
- */
-export declare function windowsLauncher(agentId: string, options?: Pick<DispatcherOptions, "gating">): string;

package/dist/dispatchers/windows.js

@@ -1,50 +0,0 @@
-import { validateAgentId } from "./snippets.js";
-/**
- * Windows .cmd launcher (best-effort tier — the plan marks Windows untested until
- * CI covers it). It:
- *   1. in heed.yaml's default `gating.mode: pane`, no-ops unless HEED_SESSION is set; with
- *      `always`, runs in every session (the POSIX dispatcher decides the same way);
- *   2. resolves the shared POSIX dispatcher via the two-tier lookup
- *      (HEED_AGENT_HOOK_ROOT → %HOME% → %USERPROFILE%);
- *   3. prefers running that dispatcher through any POSIX shell on PATH (Git for
- *      Windows / MSYS2 / BusyBox) — hook stdin passes through, so spooling still
- *      works with the listener down;
- *   4. otherwise posts via curl.exe with the same headers as the POSIX dispatcher and prints
- *      the listener's answer (nothing, which lets the agent continue, when it fails).
- */
-export function windowsLauncher(agentId, options = {}) {
-    validateAgentId(agentId);
-    const gate = (options.gating ?? "always") === "always" ? "rem heed.yaml gating.mode: always, so every session runs the hooks." : "if not defined HEED_SESSION exit /b 0";
-    return `@echo off
-setlocal EnableExtensions
-rem heedvane-agent-hook launcher for ${agentId} — generated by heedvane-hook. Do not hand-edit.
-rem Marker: heedvane-agent-hook-form
-rem Every path exits 0. The listener's answer (steering, skill check) is printed as the hook output.
-
-${gate}
-
-set "HEED_HOOK_SCRIPT="
-if defined HEED_AGENT_HOOK_ROOT if exist "%HEED_AGENT_HOOK_ROOT%\\agent-hooks\\${agentId}-hook.sh" set "HEED_HOOK_SCRIPT=%HEED_AGENT_HOOK_ROOT%\\agent-hooks\\${agentId}-hook.sh"
-if not defined HEED_HOOK_SCRIPT if defined HOME if exist "%HOME%\\.heed\\agent-hooks\\${agentId}-hook.sh" set "HEED_HOOK_SCRIPT=%HOME%\\.heed\\agent-hooks\\${agentId}-hook.sh"
-if not defined HEED_HOOK_SCRIPT if defined USERPROFILE if exist "%USERPROFILE%\\.heed\\agent-hooks\\${agentId}-hook.sh" set "HEED_HOOK_SCRIPT=%USERPROFILE%\\.heed\\agent-hooks\\${agentId}-hook.sh"
-if not defined HEED_HOOK_SCRIPT exit /b 0
-
-rem Preferred: the shared POSIX dispatcher via any available POSIX shell.
-rem Hook stdin passes through to the script, which spools when the listener is down.
-where sh >nul 2>&1
-if %errorlevel%==0 (
-  sh "%HEED_HOOK_SCRIPT%"
-  exit /b 0
-)
-
-rem No POSIX shell: post via curl.exe with the same headers as the POSIX dispatcher.
-if not defined HEED_AGENT_HOOK_PORT exit /b 0
-if not defined HEED_AGENT_HOOK_TOKEN exit /b 0
-
-set "HEED_HOOK_INPUT=%TEMP%\\heed-hook-%RANDOM%-%RANDOM%.json"
-more > "%HEED_HOOK_INPUT%" 2>nul
-curl.exe -s --fail -X POST "http://127.0.0.1:%HEED_AGENT_HOOK_PORT%/hook/${agentId}" --connect-timeout 0.5 --max-time 1.5 --noproxy 127.0.0.1 -H "Content-Type: application/json" -H "X-Heed-Agent-Hook-Token: %HEED_AGENT_HOOK_TOKEN%" -H "X-Heed-Hook-Version: 1" --data-binary "@%HEED_HOOK_INPUT%"
-del "%HEED_HOOK_INPUT%" >nul 2>&1
-exit /b 0
-`;
-}