heedvane 0.0.0-stage → 0.2.0

package/dist/skill/bundle.js

@@ -0,0 +1,102 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { canonicalSkillFiles, skillDigest } from "./content.js";
+import { unlinkOptional, writeFileOptional } from "../best-effort.js";
+/** Where the skill lives for a given skills root (~/.agents/skills). */
+export function skillInstallDir(skillsRoot, name = "heedvane-hooks") {
+    return join(skillsRoot, name);
+}
+/** Backup path for any differing existing skill file. */
+export function skillBackupPath(target) {
+    return `${target}.heedvane.backup`;
+}
+/** The file's current bytes, or undefined when absent. Other read errors propagate. */
+async function readExisting(target) {
+    try {
+        return await readFile(target);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+}
+/** Best-effort restore of anything we already replaced. */
+async function restoreOriginals(originals) {
+    for (const [target, original] of originals) {
+        if (original !== undefined)
+            await writeFileOptional(target, original, 0o644);
+    }
+}
+/** An existing backup already holds the first original; any other write failure is real. */
+function keepExistingBackup(err) {
+    if (err.code !== "EEXIST")
+        throw err;
+}
+/** Back up a differing original, atomic-write the canonical content, verify by read-back. */
+async function installSkillFile(dir, file, ctx) {
+    const target = join(dir, file.relativePath);
+    const existing = await readExisting(target);
+    if (existing !== undefined && existing.toString("utf8") === file.content)
+        return { wrote: false };
+    // Back up the differing original before touching it, unless a backup already holds the first one.
+    if (existing !== undefined) {
+        ctx.originals.set(target, existing);
+        if (ctx.backUp(existing))
+            await writeFile(skillBackupPath(target), existing, { mode: 0o644, flag: "wx" }).catch(keepExistingBackup);
+    }
+    await mkdir(dirname(target), { recursive: true });
+    await writeFileAtomic(target, file.content, { mode: 0o644 });
+    // Read-back verify; restore the original on mismatch and abort the install.
+    const written = await readFile(target, "utf8");
+    if (written !== file.content) {
+        if (existing !== undefined)
+            await writeFile(target, existing, { mode: 0o644 });
+        else
+            await unlinkOptional(target);
+        return { failed: true };
+    }
+    return { wrote: true };
+}
+/**
+ * REA's co-install pattern, applied to the skill bundle: compare canonical
+ * files against disk, back up any differing file as <path>.heedvane.backup,
+ * atomic-write (write-file-atomic), then read back to verify — restore on
+ * mismatch and report 'failed'.
+ */
+export async function installSkill(skillsRoot, files = canonicalSkillFiles(), options = {}) {
+    const dir = skillInstallDir(skillsRoot, options.name);
+    const backUp = options.backUp ?? (() => true);
+    let wroteAny = false;
+    const originals = new Map();
+    try {
+        for (const file of files) {
+            const result = await installSkillFile(dir, file, { originals, backUp });
+            if ("failed" in result)
+                return "failed";
+            if (result.wrote)
+                wroteAny = true;
+        }
+        return wroteAny ? "installed" : "unchanged";
+    }
+    catch {
+        // Best-effort restore of anything we already replaced.
+        await restoreOriginals(originals);
+        return "failed";
+    }
+}
+/** Digest of the currently installed skill files, or null when absent/incomplete. */
+export async function readInstalledSkillDigest(skillsRoot, files = canonicalSkillFiles()) {
+    const dir = skillInstallDir(skillsRoot);
+    const onDisk = [];
+    for (const file of files) {
+        try {
+            onDisk.push({ relativePath: file.relativePath, content: await readFile(join(dir, file.relativePath), "utf8") });
+        }
+        catch {
+            return null; // any missing file means "not installed"
+        }
+    }
+    return skillDigest(onDisk);
+}

package/dist/skill/content.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonical heedvane-hooks skill content, embedded as strings so the
+ * package ships standalone (no fs reads relative to import.meta.url at
+ * 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 interface SkillFile {
+    relativePath: string;
+    content: string;
+}
+/** The canonical file set, ready to install under ~/.agents/skills/heedvane-hooks/. */
+export declare function canonicalSkillFiles(): SkillFile[];
+/** sha256 over the sorted (relativePath + "\\0" + content) concatenation. */
+export declare function skillDigest(files: SkillFile[]): string;

package/dist/skill/content.js

@@ -0,0 +1,182 @@
+import { createHash } from "node:crypto";
+/**
+ * Canonical heedvane-hooks skill content, embedded as strings so the
+ * package ships standalone (no fs reads relative to import.meta.url at
+ * runtime). The physical copies in /skills/heedvane-hooks/ must stay
+ * byte-identical — tests assert that.
+ */
+export const SKILL_MD = `---
+name: heedvane-hooks
+description: Use when a user asks about heedvane hooks status, events, or how their coding agents are monitored — reports live hook installation state and the canonical event contract.
+---
+
+# heedvane-hooks
+
+## 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:
+
+1. **Hook contract** — a harness-neutral event taxonomy (\`pre_tool_use\`, \`post_tool_use\`, …), one JSON envelope, one normalizer. See \`references/events.md\`.
+2. **Per-agent adapters** — native hook config injection where the harness has hooks (Claude, Codex, Gemini, Cursor); MCP registration as the universal fallback (Warp has no native hooks — policy arrives via MCP); an honest skip where neither exists.
+3. **Setup mechanism** — \`heedvane-hook\` CLI: \`init\` / \`setup\` / \`doctor\` / \`uninstall\` with backup → atomic write → read-back verify. Human intent lives in \`~/.heed/heed.yaml\`; machine state in \`~/.heed/state.json\`.
+
+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.
+
+## When to Use
+
+- "Is my heedvane install healthy?" / "why aren't hooks firing?"
+- "What events does heedvane capture?" / "what shape is the payload?"
+- "Which of my agents are monitored?"
+- After the user edits \`~/.heed/heed.yaml\` and wants the change applied/verified.
+
+Do **not** use this skill to author policies — an organization's policies are defined and assigned on the Heedvane server, never in \`heed.yaml\`.
+
+## Checking status
+
+1. Run the doctor (scoped, exit-code-carrying):
+
+   \`\`\`sh
+   npx heedvane doctor --json
+   \`\`\`
+
+   Or unscoped plain text: \`npx heedvane doctor\`. Every failing check carries a \`remediation\` string — surface it verbatim.
+
+2. Read the control file — it is the single source of truth for intent:
+
+   \`\`\`sh
+   cat ~/.heed/heed.yaml
+   \`\`\`
+
+   \`agents: auto\` manages every detected agent; an explicit list filters. \`install.hooks/skill/mcp\` toggles channels per agent.
+
+3. **Never edit agent configs by hand.** \`~/.claude/settings.json\`, \`~/.codex/hooks.json\`, etc. are compiled outputs. Edit \`heed.yaml\`, then re-run:
+
+   \`\`\`sh
+   npx heedvane setup
+   \`\`\`
+
+4. Machine state (installed digests, endpoint, protocol version) is \`~/.heed/state.json\` — CLI-owned, never hand-edit.
+
+## Event contract summary
+
+- 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).
+- Envelope: \`{ "v": 1, "event", "agent", "session", "pane", "receivedAt", "payload": { … } }\` — strings capped at 8 KB, nodes at 500.
+- Per-harness mapping (Claude's PascalCase \`:class\` names → canonical; Codex/Gemini are already snake_case) is tabled in \`references/events.md\`. Read that file before reasoning about any specific payload.
+
+## Steering, approved skills and memory
+
+With 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:
+
+- **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.
+- **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.
+- **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).
+- **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.
+
+- **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>]\`.
+
+Backend failures never block the agent: without Heedvane's answer, the locally checked rules decide, and every enforcement is reported to Heedvane.
+
+## Common Pitfalls
+
+- **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.
+- 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.
+
+## Verification Checklist
+
+- [ ] \`npx heedvane doctor\` exits 0 and every check line shows ok
+- [ ] \`~/.heed/heed.yaml\` parses and says \`schemaVersion: v1\`
+- [ ] \`~/.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\`
+`;
+export const EVENTS_MD = `# Heedvane event contract (v1)
+
+Harness-neutral taxonomy + JSON envelope. One normalizer maps every
+per-source payload into the canonical shape; unknown events pass through
+as \`unknown_event\` rather than being dropped.
+
+## Canonical events (v1)
+
+| Event | Fires when |
+| --- | --- |
+| \`session_start\` | A managed agent session begins |
+| \`session_end\` | The session ends (clean or crash) |
+| \`user_prompt_submit\` | The user submits a prompt |
+| \`pre_tool_use\` | Before a tool call executes |
+| \`post_tool_use\` | After a tool call returns |
+| \`post_tool_use_failure\` | A tool call raises/errors |
+| \`permission_request\` | The agent asks for approval |
+| \`stop\` | The agent turn completes |
+| \`stop_failure\` | The turn aborts with an error |
+| \`subagent_start\` | A subagent/task tool spawns |
+| \`subagent_stop\` | The subagent finishes |
+| \`notification\` | Harness notification (idle, attention, updates) |
+| \`pre_compact\` | Before the harness compacts the conversation |
+
+## Envelope
+
+\`\`\`json
+{
+  "v": 1,
+  "event": "pre_tool_use",
+  "agent": "claude",
+  "session": "sess_01HQ…",
+  "pane": "iterm:tab-3",
+  "receivedAt": "2026-10-10T12:00:00.000Z",
+  "payload": { "tool": "Bash", "input": { "command": "ls" } }
+}
+\`\`\`
+
+Caps (Orca's numbers): strings ≤ 8 KB, ≤ 500 nodes per payload; oversized
+fields are truncated at ingest, never dropped.
+
+## Per-harness mapping
+
+| Canonical | Claude Code / Codex | Gemini CLI | Cursor | Hermes plugin |
+| --- | --- | --- | --- | --- |
+| \`session_start\` | \`SessionStart\` | \`SessionStart\` | \`sessionStart\` | \`on_session_start\` |
+| \`session_end\` | \`SessionEnd\` | \`SessionEnd\` | \`sessionEnd\` | \`on_session_finalize\` |
+| \`user_prompt_submit\` | \`UserPromptSubmit\` | \`BeforeAgent\` | \`beforeSubmitPrompt\` | \`pre_llm_call\` |
+| \`pre_tool_use\` | \`PreToolUse\` | \`BeforeTool\` | \`preToolUse\` | \`pre_tool_call\` |
+| \`post_tool_use\` | \`PostToolUse\` | \`AfterTool\` | \`postToolUse\` | \`post_tool_call\` |
+| \`post_tool_use_failure\` | \`PostToolUseFailure\` | — | — | — |
+| \`permission_request\` | \`PermissionRequest\` | — | — | \`pre_approval_request\` |
+| \`stop\` | \`Stop\` | \`AfterAgent\` | \`stop\` | — |
+| \`stop_failure\` | \`StopFailure\` | — | — | — |
+| \`subagent_start\` | \`SubagentStart\` | — | — | — |
+| \`subagent_stop\` | \`SubagentStop\` | — | \`subagentStop\` | — |
+| \`notification\` | \`Notification\` | \`Notification\` | — | — |
+| \`pre_compact\` | \`PreCompact\` | \`PreCompress\` | — | — |
+
+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.
+
+Payload keys per source keep their harness names inside \`payload\` (e.g.
+Claude's \`tool_input\`, Codex's \`tool_input\`) after normalization of the
+envelope itself; the normalizer never invents fields.
+`;
+/** The canonical file set, ready to install under ~/.agents/skills/heedvane-hooks/. */
+export function canonicalSkillFiles() {
+    return [
+        { relativePath: "SKILL.md", content: SKILL_MD },
+        { relativePath: "references/events.md", content: EVENTS_MD },
+    ];
+}
+/** sha256 over the sorted (relativePath + "\\0" + content) concatenation. */
+export function skillDigest(files) {
+    const hash = createHash("sha256");
+    for (const f of [...files].sort((a, b) => (a.relativePath < b.relativePath ? -1 : 1))) {
+        hash.update(f.relativePath);
+        hash.update("\0");
+        hash.update(f.content);
+    }
+    return hash.digest("hex");
+}

package/dist/skills/approved.d.ts

@@ -0,0 +1,31 @@
+import { type Backend } from "../backend/client.js";
+export interface ApprovedSkill {
+    name: string;
+    sha256: string;
+}
+export interface ApprovedSkillList {
+    syncedAt: string;
+    skills: ApprovedSkill[];
+    /** The sign-in (Backend.identity) that synced it; absent in a list an older version wrote. */
+    identity?: string;
+}
+export declare function approvedSkillsPath(root: string): string;
+/** The cached approved list, or null when no sync has written one. */
+export declare function readApprovedSkills(root: string): Promise<ApprovedSkillList | null>;
+/** The cached list when this very sign-in synced it, else null: another organization's list, one from before identities were kept, and any with no sign-in never apply. */
+export declare function approvedSkillsFor(root: string, backend: Backend | null): Promise<ApprovedSkillList | null>;
+/** Where synced skills go: the shared skills dir and Claude Code's, in the home or in a project. */
+export declare function skillRoots(base: string): string[];
+export interface SyncResult {
+    installed: string[];
+    removed: string[];
+}
+/**
+ * Download the approved list, verify every document against its sha256, install each SKILL.md under
+ * every root, remove the ones we installed that are no longer approved (only when still unmodified),
+ * and cache the list. Throws with the reason when Heedvane does not answer with a valid list.
+ */
+export declare function syncApprovedSkills(backend: Backend, target: {
+    root: string;
+    base: string;
+}): Promise<SyncResult>;

package/dist/skills/approved.js

@@ -0,0 +1,123 @@
+/**
+ * The organization's approved skills on this machine: `npx heedvane skills sync` installs each
+ * approved SKILL.md and caches the list, and the listener denies a skill that is not on it.
+ *
+ * Source: `GET /api/agent/skills` (docs/product/agent-integration/session-skills-and-retention.md),
+ * `{ skills: [{ name, description, revision, sha256, document }] }`, approved revisions only, one per
+ * name. That list is the whitelist; `sha256` is the SHA-256 hex of exactly `document` (UTF-8).
+ */
+import { existsSync } from "node:fs";
+import { readdir, readFile, rename, rmdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { callHeedvane } from "../backend/client.js";
+import { isRecord, sha256Hex } from "../guards.js";
+import { installSkill, skillBackupPath, skillInstallDir } from "../skill/bundle.js";
+export function approvedSkillsPath(root) {
+    return join(root, "approved-skills.json");
+}
+/** The cached approved list, or null when no sync has written one. */
+export async function readApprovedSkills(root) {
+    let text;
+    try {
+        text = await readFile(approvedSkillsPath(root), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    return JSON.parse(text);
+}
+/** The cached list when this very sign-in synced it, else null: another organization's list, one from before identities were kept, and any with no sign-in never apply. */
+export async function approvedSkillsFor(root, backend) {
+    const list = await readApprovedSkills(root);
+    if (list === null || backend === null)
+        return null;
+    const identity = await backend.identity();
+    return identity !== null && list.identity === identity ? list : null;
+}
+/** Where synced skills go: the shared skills dir and Claude Code's, in the home or in a project. */
+export function skillRoots(base) {
+    return [join(base, ".agents", "skills"), join(base, ".claude", "skills")];
+}
+/**
+ * Download the approved list, verify every document against its sha256, install each SKILL.md under
+ * every root, remove the ones we installed that are no longer approved (only when still unmodified),
+ * and cache the list. Throws with the reason when Heedvane does not answer with a valid list.
+ */
+export async function syncApprovedSkills(backend, target) {
+    const served = await fetchApprovedSkills(backend);
+    const roots = skillRoots(target.base);
+    const previous = (await readApprovedSkills(target.root))?.skills ?? [];
+    for (const skill of served) {
+        // A SKILL.md an earlier sync wrote is no one's own file: only a person's original gets a backup.
+        const synced = previous.find((old) => old.name === skill.name)?.sha256;
+        const backUp = (existing) => sha256Hex(existing) !== synced;
+        for (const skillsRoot of roots) {
+            if ((await installSkill(skillsRoot, [{ relativePath: "SKILL.md", content: skill.document }], { name: skill.name, backUp })) === "failed") {
+                throw new Error(`could not write ${join(skillInstallDir(skillsRoot, skill.name), "SKILL.md")}`);
+            }
+        }
+    }
+    const removed = previous.filter((old) => !served.some((skill) => skill.name === old.name));
+    for (const old of removed)
+        await removeIfUnmodified(roots, old);
+    const identity = await backend.identity();
+    const list = { syncedAt: new Date().toISOString(), skills: served.map(({ name, sha256 }) => ({ name, sha256 })), ...(identity === null ? {} : { identity }) };
+    await writeFileAtomic(approvedSkillsPath(target.root), `${JSON.stringify(list, null, 2)}\n`, { mode: 0o600 });
+    return { installed: served.map((skill) => skill.name), removed: removed.map((skill) => skill.name) };
+}
+/** Heedvane's ORG_SKILL_NAME (apps/web/src/lib/org-skills/org-skills.ts). */
+const SKILL_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+function refusalMessage(json) {
+    return isRecord(json) && typeof json["error"] === "string" ? json["error"] : JSON.stringify(json);
+}
+async function fetchApprovedSkills(backend) {
+    const answer = await callHeedvane(backend, { method: "GET", path: "/api/agent/skills", timeoutMs: 15_000 });
+    if (answer === null)
+        throw new Error(`${backend.url} did not answer`);
+    if (answer.status === 401)
+        throw new Error(`${backend.url} refused the organization key (401): save a current one with npx heedvane auth org`);
+    // The plan gate: no list is written, so the previous one (or whenUnknown) stays in force.
+    if (answer.status === 403)
+        throw new Error(`${backend.url} does not serve approved skills to this organization (403): ${refusalMessage(answer.json)}`);
+    if (answer.status !== 200)
+        throw new Error(`${backend.url}/api/agent/skills answered ${answer.status}: ${JSON.stringify(answer.json)}`);
+    const skills = isRecord(answer.json) ? answer.json["skills"] : undefined;
+    if (!Array.isArray(skills))
+        throw new Error("the approved skills answer has no skills list");
+    return skills.map(servedSkill);
+}
+function servedSkill(value) {
+    if (!isRecord(value) || typeof value["name"] !== "string" || typeof value["sha256"] !== "string" || typeof value["document"] !== "string") {
+        throw new Error("an approved skill is missing its name, sha256 or document");
+    }
+    const { name, sha256, document } = value;
+    // The name becomes a directory: only Heedvane's own skill-name form (ORG_SKILL_NAME), which cannot leave the skills root.
+    if (!SKILL_NAME.test(name))
+        throw new Error(`refusing skill name ${JSON.stringify(name)}`);
+    if (sha256Hex(document) !== sha256)
+        throw new Error(`skill ${name}: document does not match its approved sha256`);
+    return { name, sha256, document };
+}
+/**
+ * Undo what sync wrote for a revoked skill: its SKILL.md, only while unmodified. A SKILL.md that was
+ * there before sync is restored from the backup sync took (`skillBackupPath`), and the folder goes only
+ * when nothing else is left in it, so a person's own files are never removed.
+ */
+async function removeIfUnmodified(roots, skill) {
+    for (const skillsRoot of roots) {
+        const dir = skillInstallDir(skillsRoot, skill.name);
+        const file = join(dir, "SKILL.md");
+        if (!existsSync(file) || sha256Hex(await readFile(file, "utf8")) !== skill.sha256)
+            continue;
+        const backup = skillBackupPath(file);
+        if (existsSync(backup))
+            await rename(backup, file);
+        else
+            await unlink(file);
+        if ((await readdir(dir)).length === 0)
+            await rmdir(dir);
+    }
+}

package/dist/skills/check.d.ts

@@ -0,0 +1,21 @@
+import type { Envelope } from "../events/contract.js";
+import type { HeedSkillsConfig } from "../heed-file.js";
+import { type ApprovedSkillList } from "./approved.js";
+import { type Verdict } from "../reply/verdict.js";
+export interface SkillUse {
+    name: string;
+    /** The SKILL.md being read, when the agent names a file. */
+    path?: string;
+}
+export interface SkillCheckContext {
+    config: HeedSkillsConfig;
+    approved: ApprovedSkillList | null;
+    home: string;
+}
+export declare function checkSkill(envelope: Envelope, ctx: SkillCheckContext): Verdict;
+/**
+ * The envelope with `skillSha256`: the hash of the exact bytes of the SKILL.md the event loads (the
+ * file it names, else the first of the project's and the home's copies). Unchanged when it loads no
+ * skill or the file cannot be read; the hook never waits on it.
+ */
+export declare function withSkillSha256(envelope: Envelope, home: string): Envelope;

package/dist/skills/check.js

@@ -0,0 +1,83 @@
+/**
+ * The skill check the listener runs on every `pre_tool_use`: is the skill the agent is about to load on
+ * the organization's approved list? Local only (the cached list), so it costs no network round trip.
+ *
+ * A skill use is Claude Code's `Skill` tool (`tool_input.skill`), or a `Read` of a `SKILL.md` (the skill
+ * is its folder name), the same rule the backend's hook ingestion uses. Writing or editing a SKILL.md
+ * is authoring a skill, not using one, and is never checked.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { isRecord, sha256Hex } from "../guards.js";
+import { skillRoots } from "./approved.js";
+import { ALLOW } from "../reply/verdict.js";
+/** This package's own skill: installed by init, never on an organization's list. */
+const OWN_SKILL = "heedvane-hooks";
+/** The tool events that can load a skill (ingestion's TOOL_EVENTS). */
+const TOOL_EVENTS = new Set(["pre_tool_use", "post_tool_use", "post_tool_use_failure"]);
+/** The skill a tool event loads, or null when it loads none. */
+function skillUse(envelope) {
+    if (!TOOL_EVENTS.has(envelope.event))
+        return null;
+    const input = envelope.payload["tool_input"];
+    if (!isRecord(input))
+        return null;
+    const tool = envelope.payload["tool"];
+    if (tool === "Skill" && typeof input["skill"] === "string")
+        return { name: input["skill"] };
+    if (tool !== "Read")
+        return null;
+    const path = [input["file_path"], input["path"]].find((value) => typeof value === "string");
+    return path !== undefined && basename(path) === "SKILL.md" ? { name: basename(dirname(path)), path } : null;
+}
+export function checkSkill(envelope, ctx) {
+    const use = envelope.event === "pre_tool_use" ? skillUse(envelope) : null;
+    if (use === null || use.name === OWN_SKILL || !ctx.config.enforce)
+        return ALLOW;
+    if (ctx.approved === null)
+        return unknownList(use, ctx.config);
+    const approved = ctx.approved.skills.find((skill) => skill.name === use.name);
+    if (approved === undefined) {
+        return steer(`Skill "${use.name}" is not approved by your organization. Ask an owner or admin to approve it on Heedvane's Skills page, then run \`npx heedvane skills sync\`.`);
+    }
+    if (ctx.config.strict && !matchesApproved(use, approved.sha256, localSkillFiles(use.name, envelope, ctx.home))) {
+        return steer(`Skill "${use.name}" differs from the revision your organization approved. Run \`npx heedvane skills sync\` to restore it.`);
+    }
+    return ALLOW;
+}
+function unknownList(use, config) {
+    const message = `Skill "${use.name}" could not be checked: no approved-skills list is synced on this machine (run \`npx heedvane skills sync\`).`;
+    return config.whenUnknown === "deny" ? steer(message) : { decision: "warn", messages: [message], context: [] };
+}
+function steer(message) {
+    return { decision: "steer", messages: [message], context: [] };
+}
+/** Where the skill could be loaded from: the file the agent named, else the project's and the home's skill dirs. */
+function localSkillFiles(name, envelope, home) {
+    const cwd = typeof envelope.payload["cwd"] === "string" ? envelope.payload["cwd"] : undefined;
+    const bases = cwd === undefined ? [home] : [cwd, home];
+    return bases.flatMap(skillRoots).map((root) => join(root, name, "SKILL.md"));
+}
+function matchesApproved(use, sha256, candidates) {
+    const file = use.path ?? candidates.find((path) => existsSync(path));
+    return file !== undefined && existsSync(file) && sha256Hex(readFileSync(file, "utf8")) === sha256;
+}
+/**
+ * The envelope with `skillSha256`: the hash of the exact bytes of the SKILL.md the event loads (the
+ * file it names, else the first of the project's and the home's copies). Unchanged when it loads no
+ * skill or the file cannot be read; the hook never waits on it.
+ */
+export function withSkillSha256(envelope, home) {
+    const use = skillUse(envelope);
+    if (use === null)
+        return envelope;
+    const file = use.path ?? localSkillFiles(use.name, envelope, home).find((path) => existsSync(path));
+    if (file === undefined)
+        return envelope;
+    try {
+        return { ...envelope, skillSha256: sha256Hex(readFileSync(file)) };
+    }
+    catch {
+        return envelope; // unreadable (gone, a directory, no permission): forwarded without the hash
+    }
+}

package/dist/state.d.ts

@@ -0,0 +1,51 @@
+/**
+ * CLI-owned machine state (<root>/state.json).
+ *
+ * heed.yaml is 100% human-owned; this file is 100% CLI-owned and never hand-edited.
+ * `doctor` compares state.json ↔ live disk ↔ heed.yaml. Written atomically (mode 0600)
+ * so a crash never leaves a half-written state behind.
+ */
+export interface HeedStateEndpoint {
+    port: number;
+    token: string;
+}
+export interface HeedInstalledClient {
+    /** Marker/entry names this install owns in the agent's config. */
+    entries: string[];
+    /** Content digests of the files we wrote, keyed by absolute path. */
+    digests: Record<string, string>;
+}
+export interface HeedState {
+    schemaVersion: 1;
+    protocolVersion: string;
+    endpoint: HeedStateEndpoint;
+    installed: Record<string, HeedInstalledClient>;
+    skill: {
+        version: string;
+        digest: string;
+    } | null;
+}
+/** Error for a state.json that exists but cannot be trusted. Carries the exact remediation. */
+export declare class HeedStateCorruptError extends Error {
+    readonly path: string;
+    constructor(path: string, reason: string);
+}
+export declare function statePath(root: string): string;
+/**
+ * A fresh, empty state for a new install. Endpoint starts unassigned
+ * (port 0 / empty token) until the listener resolves and persists one.
+ */
+export declare function emptyState(skillDigest?: string | null): HeedState;
+/**
+ * Read <root>/state.json. Returns null when the file does not exist.
+ * Throws {@link HeedStateCorruptError} (remediation: "delete <path> or run
+ * npx heedvane doctor") when the file exists but is unparseable or does not
+ * match the HeedState schema.
+ */
+export declare function readState(root: string): Promise<HeedState | null>;
+/**
+ * Atomically write state to <root>/state.json (create parent dirs, mode 0600).
+ * write-file-atomic writes to a sibling temp file and renames, so readers never
+ * observe a partial state.
+ */
+export declare function writeStateAtomic(root: string, state: HeedState): Promise<void>;