vibeaudio 0.13.0 → 0.14.0

package/README.md

@@ -12,7 +12,7 @@
 
 > **In a hurry?** `npm i -g vibeaudio`, then `vibe --install-hooks`. Your next prompt has music.
 >
-> **Claude Code only?** Skip npm: `claude plugin marketplace add kiril6/vibeaudio`, then `claude plugin install vibeaudio@vibeaudio` ([details](#as-a-claude-code-plugin)).
+> **Only Claude Code or Codex?** Skip npm. Inside a Claude Code session: `/plugin marketplace add kiril6/vibeaudio`, then `/plugin install vibeaudio@vibeaudio`. For Codex: `codex plugin marketplace add kiril6/vibeaudio`, then `codex plugin add vibeaudio@vibeaudio` ([details](#as-a-plugin-claude-code-and-codex)).
 
 ---
 
@@ -20,6 +20,15 @@
 
 AI coding agents take 15–45 seconds to reason, read files and write code. Staring at a blank cursor feels slow; tabbing away means checking back to see if it's done. VibeAudio fills that gap with music while the agent thinks, and a chime when your output is ready to read.
 
+It is built as **calm technology**, in the sense of Mark Weiser and John Seely Brown's *Designing Calm Technology* (Xerox PARC, 1995): information that stays at the edge of your attention and only comes to the front when it matters. You stop noticing the music, but you notice when it changes.
+
+| Principle | In VibeAudio |
+| :--- | :--- |
+| Inform without demanding attention | The music sits in the background. What you notice is it *stopping*. |
+| Come to the front only when it matters | Chimes for done, failed and "needs you" only. The music doesn't react to every tool call unless you ask it to ([reactive mode](#reactive-mode-opt-in)). |
+| Make the background informative | Layers build as a turn runs long, and a heartbeat joins when an agent keeps failing. That fires in under 1% of turns, by design. |
+| Calm, not alarming | "Needs you" is a soft rising interval, not an alarm. A mute ends on its own after an hour. |
+
 **How it behaves:**
 
 * 🧮 **Pure synthesis, zero MP3s.** Every note, chord and pad is generated in code — no audio assets, no npm dependencies, no `node-gyp`.
@@ -251,8 +260,8 @@ Each tool spells its events its own way, and VibeAudio writes whichever dialect
 
 | | File | Music starts | Music stops + chime | Reactive (opt-in) |
 | :--- | :--- | :--- | :--- | :--- |
-| **Claude Code** | `~/.claude/settings.json` | `UserPromptSubmit` | `Stop` | `PreToolUse` |
-| **Codex** | `~/.codex/hooks.json` | `UserPromptSubmit` | `Stop` | `PreToolUse` |
+| **Claude Code** | `~/.claude/settings.json` (or `$CLAUDE_CONFIG_DIR`) | `UserPromptSubmit` | `Stop` | `PreToolUse` |
+| **Codex** | `~/.codex/hooks.json` (or `$CODEX_HOME`) | `UserPromptSubmit` | `Stop` | `PreToolUse` |
 | **Cursor** | `~/.cursor/hooks.json` | `beforeSubmitPrompt` | `stop` | `preToolUse` |
 | **Grok** | `~/.grok/hooks/vibeaudio.json` | `UserPromptSubmit` | `Stop` | `PreToolUse` |
 | **Gemini CLI** | `~/.gemini/settings.json` | `BeforeAgent` | `AfterAgent` | `BeforeTool` |
@@ -265,7 +274,7 @@ Where an agent reports more than start and stop, VibeAudio listens for that too
 | | Music pauses + "your turn" chime | Music resumes | Failure chime (API error) | Session closes mid-turn (silent) |
 | :--- | :--- | :--- | :--- | :--- |
 | **Claude Code** | `PermissionRequest`, `Elicitation` | `PostToolUse`, `PostToolUseFailure`, `ElicitationResult` | `StopFailure` | `SessionEnd` |
-| **Codex** | `PermissionRequest` | `PostToolUse` | — | — |
+| **Codex** | `PermissionRequest` | `PostToolUse` | — | `SessionEnd`, and `Interrupt` (Esc) |
 | **Gemini CLI** | `Notification` (tool permission) | `AfterTool` | — | `SessionEnd` |
 | **Copilot CLI** | `Notification` (permission prompt) | `PostToolUse`, `PostToolUseFailure` | — | `SessionEnd` |
 | **Qwen Code** | `PermissionRequest` | `PostToolUse`, `PostToolUseFailure` | `StopFailure` | `SessionEnd` |
@@ -283,6 +292,8 @@ Where an agent reports more than start and stop, VibeAudio listens for that too
 | **Claude Code turns that never reach `Stop` still end the music** | An API error or rate limit ends the turn with `StopFailure` instead, which plays the failure chime. Interrupting (Esc, or the stop button in the desktop app) fires no hook at all, so the background player watches the session transcript for Claude Code's interrupt entry and stops silently within half a second — whether the agent was writing or running a tool. A prompt that another hook blocks (a token-saving proxy, say) never reaches `Stop` either, so the same watcher ends the music on Claude Code's "prompt blocked" entry — or never starts it, when the blocker was quicker than we were. Closing the session mid-turn stops it too — but only if that session started the music, so closing an idle terminal never silences another one. |
 | **Codex asks you to trust the hook once** | Codex keeps a per-hook trust hash in `~/.codex/config.toml` and won't run a hook it hasn't been told to trust, so the install isn't live until you approve each one the first time it fires. |
 | **Only Cursor can play the failure chime** | Its stop event reports whether the turn completed, aborted or errored. The others send no verdict, so a turn there always ends on the success chime — VibeAudio won't invent a failure the agent never claimed. |
+| **Upgraded, and a new feature isn't there?** | Hooks are written into your agent's config once, at install time, and an upgrade doesn't touch them. When a new version listens for more events (0.13.1 added Codex's `Interrupt` and `SessionEnd`), `vibe --doctor` and `vibe --status` name what's missing, and `vibe --install-hooks` adds it. |
+| **Moved your config folder?** | VibeAudio follows `CLAUDE_CONFIG_DIR` and `CODEX_HOME` the way the agents do, so hooks (and `/vibe`) go where your agent actually reads them. Set the variable in the shell you run `vibe --install-hooks` from. |
 | **Grok and Copilot CLI get a file of their own** | Each reads every `*.json` in its `hooks/` directory, so VibeAudio writes `vibeaudio.json` rather than merging into anyone else's — which makes uninstalling it a delete, and leaves no backup file behind. Copilot's honours `COPILOT_HOME`. |
 
 </details>
@@ -309,29 +320,45 @@ Sessions with no id in their payload share a single slot, so they behave as one.
 
 > **No restart needed, even mid-session — for Claude Code, Codex, Cursor and Grok.** Each re-reads its hook file every time a hook fires, so changes land on your **next prompt**. A daemon already playing keeps its old settings until that prompt replaces it — at most the tail of one turn. Whether an open Gemini CLI, Copilot CLI, Qwen Code or Windsurf session does the same hasn't been checked, so start a new session there to be sure.
 
-> **The Claude Code desktop app is covered too**, not just the terminal — both read the same `~/.claude/settings.json`. (The separate **Claude Desktop** chat app is a different product with no hooks; that one needs [MCP](#-everything-else-claude-desktop-antigravity-via-mcp).)
+> **The Claude Code desktop app is covered too**, not just the terminal — both read the same `~/.claude/settings.json` (or `$CLAUDE_CONFIG_DIR/settings.json`). (The separate **Claude Desktop** chat app is a different product with no hooks; that one needs [MCP](#-everything-else-claude-desktop-antigravity-via-mcp).)
 
 > **One player is shared.** Prompt two agents at once and the last prompt owns the music. One person, one set of speakers — deliberate, not a limitation being worked around.
 
-### As a Claude Code plugin
+### As a plugin (Claude Code and Codex)
+
+If Claude Code or Codex is the agent you use, the plugin installs the same hooks with no npm step. Inside a Claude Code session, type:
+
+```
+/plugin marketplace add kiril6/vibeaudio
+/plugin install vibeaudio@vibeaudio
+```
 
-If Claude Code is the only agent you use, the plugin installs the same hooks with no npm step:
+Or the same from a terminal:
 
 ```bash
 claude plugin marketplace add kiril6/vibeaudio
 claude plugin install vibeaudio@vibeaudio
 ```
 
-It needs Node 18+ on your `PATH` (the hooks run `node`), and it also adds `/vibeaudio:vibe`, the plugin's spelling of [`/vibe`](#vibe-inside-claude-code). Update with `claude plugin update vibeaudio@vibeaudio`; remove with `claude plugin uninstall vibeaudio@vibeaudio` (music already playing stops on its own within 15 minutes, or run `/vibeaudio:vibe stop` first).
+For Codex:
+
+```bash
+codex plugin marketplace add kiril6/vibeaudio
+codex plugin add vibeaudio@vibeaudio
+```
+
+Codex asks you to approve the plugin's hooks once, as it does for any hook. Update with `codex plugin marketplace upgrade vibeaudio`; remove with `codex plugin remove vibeaudio@vibeaudio`.
+
+The plugin needs Node 18+ on your `PATH` (the hooks run `node`). In Claude Code it also adds `/vibeaudio:vibe`, the plugin's spelling of [`/vibe`](#vibe-inside-claude-code). Update with `claude plugin update vibeaudio@vibeaudio`; remove with `claude plugin uninstall vibeaudio@vibeaudio` (music already playing stops on its own within 15 minutes, or run `/vibeaudio:vibe stop` first).
 
 - **Settings are the same file.** `vibe --genre jazz` and the rest work as always, but the `vibe` command comes from `npm i -g vibeaudio`; the plugin alone puts nothing on your `PATH`. Use `/vibeaudio:vibe genre jazz` instead.
 - **Both at once is safe.** If `--install-hooks` has also been run, the plugin's hooks step aside and the installed ones play, so there's no double chime. Remove the installed hooks first if you want the plugin to own it.
-- **Claude Code only.** Codex, Cursor, Gemini and the others still use `vibe --install-hooks`.
+- **Claude Code and Codex.** Cursor, Gemini and the others still use `vibe --install-hooks`. Copilot CLI and Qwen Code can load the same plugin and it carries their events, but neither has been run with it yet.
 - **Not reactive.** `--reactive` is an `--install-hooks` option; the plugin doesn't carry it.
 
 ### `/vibe` inside Claude Code
 
-Installing the Claude Code hooks also adds a `/vibe` command (`~/.claude/commands/vibe.md`), so you can control the music without leaving the session:
+Installing the Claude Code hooks also adds a `/vibe` command (`~/.claude/commands/vibe.md`, or under `$CLAUDE_CONFIG_DIR`), so you can control the music without leaving the session:
 
 ```text
 /vibe                 what's installed and playing
@@ -455,7 +482,7 @@ Each session is `working`, `stuck` (4 of its last 8 tool calls failed) or `waiti
 {"v":1,"at":1791026130000,"event":"waiting","session":"…","project":"/work/api","tool":"Bash","status":"waiting"}
 ```
 
-Events: `started`, `waiting`, `resumed`, `stuck`, `recovered`, `finished` (with `outcome`: `success` or `failure`), `interrupted`, `ended`. Every line also carries `status`, the machine's state after the event, so a consumer that only cares about the overall state can read that one field. Some examples:
+Events: `started`, `waiting`, `resumed`, `stuck`, `recovered`, `finished` (with `outcome`: `success` or `failure`), `interrupted`, `ended` (with `reason` when `vibe --stop` or `--uninstall-hooks` ended it). Every line also carries `status`, the machine's state after the event, so a consumer that only cares about the overall state can read that one field. Some examples:
 
 ```bash
 # tmux: show the state in the status bar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Procedural focus music while your AI coding tools (Claude Code, Codex, Cursor, Grok, Gemini, Copilot) think — a different arrangement per project.",
   "bin": {
     "vibeaudio": "bin/vibeaudio.js",
@@ -10,7 +10,7 @@
   "scripts": {
     "test": "node test/test-synth.js",
     "start": "node bin/vibeaudio.js",
-    "version": "node -e \"const f='.claude-plugin/plugin.json',j=require('./'+f);j.version=require('./package.json').version;require('fs').writeFileSync(f,JSON.stringify(j,null,2)+'\\n')\" && git add .claude-plugin/plugin.json",
+    "version": "node -e \"const fs=require('fs'),v=require('./package.json').version;for(const f of ['.claude-plugin/plugin.json','.codex-plugin/plugin.json']){const j=JSON.parse(fs.readFileSync(f,'utf8'));j.version=v;fs.writeFileSync(f,JSON.stringify(j,null,2)+'\\n')}\" && git add .claude-plugin/plugin.json .codex-plugin/plugin.json",
     "postinstall": "node scripts/postinstall.js"
   },
   "publishConfig": {

package/src/cli.js

@@ -137,7 +137,8 @@ const VALUE_FLAGS = new Set([
   "-cv", "--chime-volume",
   "--grace",
   "--seed",
-  "--tools"
+  "--tools",
+  "--event"
 ]);
 
 function parseArgs(argv) {
@@ -189,6 +190,7 @@ function parseArgs(argv) {
   let reactive = false;
   let followVolume = false;
   let plugin = false;
+  let hookEvent = null;
   let here_flag = false;
   let dryRun = false;
   let tools = null;
@@ -381,6 +383,14 @@ function parseArgs(argv) {
       continue;
     }
 
+    // Internal, also the plugin's: which event this hook entry is for, so a
+    // hook can ignore events the agent running it does not use that way.
+    if (arg === "--event") {
+      hookEvent = args[i + 1] || null;
+      i += 2;
+      continue;
+    }
+
     if (arg === "--dry-run") {
       dryRun = true;
       i += 1;
@@ -494,6 +504,7 @@ function parseArgs(argv) {
     reactive,
     followVolume,
     plugin,
+    hookEvent,
     dryRun,
     tools,
     typed,
@@ -600,6 +611,7 @@ function installHookTargets(ids, genre, volume, reactive, dryRun = false, typed
     if (events.resume) console.log(`  ${events.resume[0].padEnd(19)}→ music resumes once you've answered`);
     if (events.failure) console.log(`  ${events.failure.padEnd(19)}→ music stops + failure chime (API error)`);
     if (events.end) console.log(`  ${events.end.padEnd(19)}→ music stops if that session started it`);
+    if (events.interrupt) console.log(`  ${events.interrupt.padEnd(19)}→ music stops silently when you interrupt`);
 
     if (id === "claude") {
       const slash = hooks.installSlashCommand({ dryRun });
@@ -687,7 +699,7 @@ function uninstallHookTargets() {
   // `npm rm -g` right after this would take away the only thing that could
   // stop it. Done here rather than in uninstallHooks() so that function stays
   // a pure config edit for tests.
-  if (hooks.stopDaemon()) console.log(`  Stopped the background player that was still running.`);
+  if (hooks.stopDaemon({ reason: "uninstall" })) console.log(`  Stopped the background player that was still running.`);
 }
 
 /**
@@ -770,6 +782,10 @@ function printStatus() {
     if (readVibeHooks(t.file(), t).some(({ command }) => /--genre /.test(command))) {
       console.log(`    \x1b[33m↑ pinned by an older install — vibe --install-hooks makes it follow Sound above\x1b[0m`);
     }
+    const absent = hooks.expectedEvents(id).filter((e) => !installed.some(({ event }) => event === e));
+    if (absent.length) {
+      console.log(`    \x1b[33m+ ${absent.join(", ")} added since this install — vibe --install-hooks picks them up\x1b[0m`);
+    }
   }
 
   // Background player
@@ -883,8 +899,11 @@ function doctorChecks() {
       const tokens = [...command.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)].map((m) => m[1] ?? m[2] ?? m[3]);
       for (const p of tokens.slice(0, 2)) if (!fs.existsSync(p)) missing.add(p);
     }
+    const absent = hooks.expectedEvents(id).filter((e) => !installed.some(({ event }) => event === e));
     if (missing.size) {
       add("fail", label, `points at a file that no longer exists: ${[...missing].join(", ")}`, "vibe --install-hooks");
+    } else if (absent.length) {
+      add("warn", label, `installed by an older version, missing ${absent.join(", ")}`, "vibe --install-hooks");
     } else if (installed.some(({ command }) => /--genre /.test(command))) {
       add("warn", label, "pinned to a genre/volume by an older install, which overrides your saved settings", "vibe --install-hooks");
     } else {
@@ -895,15 +914,20 @@ function doctorChecks() {
     // config.toml under "<file>:<event>:<group>:<index>".
     if (id === "codex") {
       let toml = "";
-      try { toml = fs.readFileSync(path.join(os.homedir(), ".codex", "config.toml"), "utf8"); } catch (e) { /* none yet */ }
+      try { toml = fs.readFileSync(path.join(hooks.codexHome(), "config.toml"), "utf8"); } catch (e) { /* none yet */ }
       const pending = [];
       try {
         const file = t.file();
+        // Codex canonicalizes CODEX_HOME before keying (find_codex_home()), so
+        // a symlinked one - /tmp on macOS - is recorded under its real path.
+        let real = file;
+        try { real = fs.realpathSync(file); } catch (e) { /* checked below */ }
         for (const [event, entries] of Object.entries(JSON.parse(fs.readFileSync(file, "utf8")).hooks || {})) {
           (entries || []).forEach((entry, g) => {
             t.commands(entry).forEach((command, i) => {
-              const key = `${file}:${event.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase()}:${g}:${i}`;
-              if (hooks.VIBE_HOOK_FLAG.test(command || "") && !toml.includes(`"${key}"`)) pending.push(event);
+              const suffix = `:${event.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase()}:${g}:${i}`;
+              const trusted = [file, real].some((f) => toml.includes(`"${f}${suffix}"`));
+              if (hooks.VIBE_HOOK_FLAG.test(command || "") && !trusted) pending.push(event);
             });
           });
         }
@@ -1311,13 +1335,23 @@ function renderToFile(target, genre) {
   console.log(`  \x1b[90mAnother project's sound: run it there, or vibe --seed <n> --render.\x1b[0m\n`);
 }
 
-function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, tools, dryRun, typed = {} }) {
+function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, hookEvent = null, tools, dryRun, typed = {} }) {
   const hooks = require("./hooks");
 
-  // The plugin's hooks and --install-hooks' hooks are the same events: with both
-  // present every prompt would restart the music and every turn chime twice.
-  // The installed ones win because they carry the user's --reactive choice.
-  if (plugin && action.startsWith("hook-") && hooks.userHooksInstalled()) return;
+  if (plugin && action.startsWith("hook-")) {
+    // One plugin, four agents (PLUGIN_AGENTS). Each check is against the
+    // agent actually running this hook, never Claude Code's by default.
+    const agent = hooks.pluginAgent();
+    // The plugin's hooks and --install-hooks' hooks are the same events: with
+    // both present every prompt would restart the music and every turn chime
+    // twice. The installed ones win because they carry the user's --reactive.
+    if (hooks.userHooksInstalled(null, agent)) return;
+    // The plugin's file carries every agent's events; this one may not use
+    // this event this way. Copilot fires PermissionRequest before every
+    // permission check, dialog or not, so taking it as a wait there would
+    // pause the music on every tool call.
+    if (hookEvent && !hooks.expectedEvents(agent).includes(hookEvent)) return;
+  }
 
   switch (action) {
     case "daemon":
@@ -1544,6 +1578,7 @@ async function run() {
     reactive,
     followVolume,
     plugin,
+    hookEvent,
     dryRun,
     tools,
     typed,
@@ -1561,7 +1596,7 @@ async function run() {
 
   if (hookAction) {
     try {
-      return runHookAction(hookAction, { genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, tools, dryRun, typed });
+      return runHookAction(hookAction, { genre, volume, chimeVolume, noChime, reactive, followVolume, plugin, hookEvent, tools, dryRun, typed });
     } catch (e) {
       // Settings problems are the user's to fix — report them, don't stack-trace.
       console.error(`\x1b[31m[vibeaudio] ${e.message}\x1b[0m`);
@@ -1587,8 +1622,9 @@ async function run() {
     const minutes = muteMinutes === null ? DEFAULT_MUTE_MINUTES : muteMinutes;
     const state = setMuted(true, minutes);
     // Muting has to silence what is playing right now, not just the next
-    // prompt - the whole point is that a call is already ringing.
-    const stopped = require("./hooks").stopDaemon();
+    // prompt - the whole point is that a call is already ringing. The turns
+    // in flight are kept: they still finish, log and show in --state.
+    const stopped = require("./hooks").stopDaemon({ keepSessions: true });
 
     console.log(`\x1b[33m🔇 Muted ${muteRemainingText(state)}.\x1b[0m`);
     if (stopped) console.log(`  Stopped the player that was running.`);

package/src/hooks.js

@@ -153,15 +153,35 @@ const MAX_DAEMON_MS = 15 * 60 * 1000;
  * - failure: a turn ending in error *instead of* the stop event
  * - end:     the session closing, which can cut a turn off before stop
  *
+ * - interrupt: the user stopped the turn (Esc), a silent end like `end`
+ *
  * `seed` is the root object to write when the file does not exist yet. Cursor
  * and Copilot require a schema version; Codex rejects unknown root keys
  * outright, so nothing may be added there beyond `hooks`.
  */
+/**
+ * Where Claude Code and Codex keep their config. Both move with an env var,
+ * and a user who sets one has hooks read from there only: writing to the
+ * default path left VibeAudio installed in a file nothing read, and silent.
+ * Claude Code: `CLAUDE_CONFIG_DIR ?? ~/.claude`, NFC-normalized (cn() in
+ * 2.1.195's bundle; settings.json and commands/ both live under it).
+ * Codex: `CODEX_HOME`, empty treated as unset, else `~/.codex`
+ * (find_codex_home(), 0.160 source). Empty is unset for both here, so an
+ * exported-but-blank variable cannot turn the path relative.
+ */
+function claudeConfigDir() {
+  return (process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude")).normalize("NFC");
+}
+
+function codexHome() {
+  return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+}
+
 const TARGETS = {
   claude: {
     name: "Claude Code",
     cmd: "claude",
-    file: () => path.join(os.homedir(), ".claude", "settings.json"),
+    file: () => path.join(claudeConfigDir(), "settings.json"),
     // - wait: PermissionRequest fires when the dialog is shown in the terminal,
     //   the SDK (desktop app, IDEs) and print mode alike - Notification's
     //   permission_prompt is raised by the terminal UI alone, after 6s idle.
@@ -182,19 +202,27 @@ const TARGETS = {
   codex: {
     name: "Codex",
     cmd: "codex",
-    file: () => path.join(os.homedir(), ".codex", "hooks.json"),
+    file: () => path.join(codexHome(), "hooks.json"),
     // PermissionRequest runs only when Codex is about to ask for approval,
-    // with tool_name, and is present in 0.125's binary. Its docs describe
-    // Interrupt and SessionEnd too, but 0.125 has neither - and a strict parser
-    // meeting an event it does not know would take every hook down with it.
+    // with tool_name, and is present in 0.125's binary. SessionEnd arrived in
+    // 0.145 and Interrupt in 0.150 (source of each release tag). Listing them
+    // is safe on older versions: HookEventsToml has never denied unknown
+    // fields (checked 0.125 through 0.160), so an older Codex ignores an
+    // event it does not know - only the file's root is strict. Interrupt runs
+    // on the turn-abort path, not the one that runs Stop, with session_id,
+    // cwd and transcript_path.
     events: {
       start: "UserPromptSubmit",
       stop: "Stop",
       tool: "PreToolUse",
       wait: ["PermissionRequest"],
-      resume: ["PostToolUse"]
+      resume: ["PostToolUse"],
+      interrupt: "Interrupt",
+      end: "SessionEnd"
     },
-    entry: (command) => ({ hooks: [{ type: "command", command, timeout: 5 }] }),
+    // Codex caps SessionEnd and Interrupt hooks at 3s (SESSION_END_MAX_TIMEOUT_SEC,
+    // discovery.rs) and warns on every run when one asks for more.
+    entry: (command, event) => ({ hooks: [{ type: "command", command, timeout: event === "SessionEnd" || event === "Interrupt" ? 3 : 5 }] }),
     commands: (entry) => (entry.hooks || []).map((h) => h.command),
     seed: () => ({}),
     // Codex records a trusted_hash per hook in config.toml and asks before
@@ -346,6 +374,94 @@ function detectTargets() {
   });
 }
 
+/**
+ * Every event an install by this version writes for a target, `tool` aside
+ * (reactive mode only). A hook file is written once and outlives upgrades,
+ * so an event added in a later version - Codex's Interrupt and SessionEnd in
+ * 0.13.1 - never reaches someone who installed before it unless they
+ * reinstall. `--doctor` and `--status` compare against this to say so.
+ */
+function expectedEvents(id) {
+  const ev = TARGETS[id].events;
+  return [ev.start, ev.stop, ...(ev.wait || []), ...(ev.resume || []), ev.failure, ev.end, ev.interrupt].filter(Boolean);
+}
+
+/**
+ * The agents that load this repository as a plugin, and the hooks file each
+ * one reads. Copilot CLI loads `.claude-plugin/` manifests and Qwen Code
+ * converts the plugin on install (copying the folder, substituting
+ * CLAUDE_PLUGIN_ROOT), so both read Claude Code's hooks/hooks.json. Codex
+ * 0.160 would too, but Claude Code's validator rejects an event it does not
+ * know ("hooks.Interrupt: Invalid key in record") and then loads none of the
+ * file, so Codex's Interrupt cannot live there: `.codex-plugin/plugin.json`,
+ * which Codex reads before `.claude-plugin/` and Claude Code never reads,
+ * points Codex at a file of its own. Gemini CLI has its own extension format
+ * and is not one of these.
+ */
+const PLUGIN_FILES = {
+  "hooks/hooks.json": ["claude", "copilot", "qwen"],
+  "hooks/codex.json": ["codex"]
+};
+const PLUGIN_AGENTS = Object.values(PLUGIN_FILES).flat();
+
+const SLOT_ACTION = { start: "hook-start", stop: "hook-stop", failure: "hook-stop", wait: "hook-wait", resume: "hook-resume", end: "hook-end", interrupt: "hook-end" };
+
+/**
+ * Every event the given agents fire, with the one action it runs. One file
+ * can serve several agents, so it carries the union; an event an agent does
+ * not use there is dropped at runtime by `--event` (see runHookAction).
+ * Throws if two agents would need different actions for one event name,
+ * since the file could not serve both.
+ */
+function pluginHookEvents(agents) {
+  const actions = new Map();
+  for (const id of agents) {
+    for (const [slot, value] of Object.entries(TARGETS[id].events)) {
+      if (!SLOT_ACTION[slot]) continue; // `tool` is reactive mode, an --install-hooks option
+      for (const event of [].concat(value)) {
+        const prior = actions.get(event);
+        if (prior && prior !== SLOT_ACTION[slot]) throw new Error(`${event}: ${prior} for one agent, ${SLOT_ACTION[slot]} for ${id}`);
+        actions.set(event, SLOT_ACTION[slot]);
+      }
+    }
+  }
+  return actions;
+}
+
+/**
+ * A plugin hooks file (see PLUGIN_FILES), generated so it cannot drift from
+ * TARGETS. Agents sharing a file share an entry shape, so the first one's is
+ * used. `script` is the CLI's path as the host spells it: Gemini's extension
+ * substitutes ${extensionPath} itself, the others leave CLAUDE_PLUGIN_ROOT to
+ * the shell.
+ */
+function pluginHooksFile(agents, script = "${CLAUDE_PLUGIN_ROOT}/bin/vibeaudio.js") {
+  const hooks = {};
+  for (const [event, action] of pluginHookEvents(agents)) {
+    hooks[event] = [TARGETS[agents[0]].entry(`node "${script}" --${action} --plugin --event ${event}`, event)];
+  }
+  return { hooks };
+}
+
+/**
+ * Which agent is running a plugin hook, from the environment each one sets:
+ * Copilot CLI sets COPILOT_PLUGIN_ROOT (its changelog), Qwen Code sets
+ * QWEN_PROJECT_DIR for every hook (hookRunner.ts), Gemini CLI sets
+ * GEMINI_PROJECT_DIR for its extension's hooks (hookRunner.ts), and Codex sets
+ * PLUGIN_ROOT (discovery.rs). Claude Code sets none of these, only
+ * CLAUDE_PLUGIN_ROOT / CLAUDE_PLUGIN_DATA / CLAUDE_PROJECT_DIR (2.1.195's
+ * bundle). Copilot also sets PLUGIN_ROOT, so it is checked first.
+ * ponytail: a variable exported in the user's own shell would leak into
+ * hooks and misattribute them; none of these names is one a user sets.
+ */
+function pluginAgent(env = process.env) {
+  if (env.COPILOT_PLUGIN_ROOT) return "copilot";
+  if (env.QWEN_PROJECT_DIR) return "qwen";
+  if (env.GEMINI_PROJECT_DIR) return "gemini"; // after Qwen, a fork that sets it too
+  if (env.PLUGIN_ROOT) return "codex";
+  return "claude";
+}
+
 function settingsPath() {
   return TARGETS.claude.file();
 }
@@ -418,14 +534,25 @@ function daemonPlaying() {
 
 /**
  * Stops the player. `keepSessions` leaves the session files alone: the hooks
- * use it because they decide per session what is still going on. Every other
- * stop (--stop, --mute, uninstall) ends everything, or a later tool call would
- * resume music nobody is waiting for.
+ * use it because they decide per session what is still going on, and --mute
+ * because a mute is about sound - the turns are still in flight, and should
+ * still reach --state, --events and --report. --stop and uninstall end
+ * everything, or a later tool call would resume music nobody is waiting for;
+ * each session dropped gets an `ended` event with that `reason`, or an
+ * --events consumer would show it working forever (#24).
  */
-function stopDaemon({ keepSessions = false } = {}) {
+function stopDaemon({ keepSessions = false, reason = "stop" } = {}) {
   const pid = readPid();
   fs.rmSync(PID_FILE, { force: true });
-  if (!keepSessions) fs.rmSync(SESSIONS_DIR, { recursive: true, force: true });
+  if (!keepSessions) {
+    // Removed before its event, so each line's status is what it left behind
+    // and the last one reads idle.
+    for (const s of listSessions()) {
+      fs.rmSync(sessionFile(s.id), { force: true });
+      emitEvent("ended", s.id, s.project, { reason });
+    }
+    fs.rmSync(SESSIONS_DIR, { recursive: true, force: true });
+  }
   if (pid === null || !isOurDaemon(pid)) return false;
 
   try {
@@ -1047,7 +1174,7 @@ function hookEnd(raw) {
   if (!session) return false;
 
   fs.rmSync(sessionFile(id), { force: true });
-  emitEvent("ended", id, session.project);
+  emitEvent(parsePayload(raw).hook_event_name === "Interrupt" ? "interrupted" : "ended", id, session.project);
   if (working(listSessions()).length === 0) {
     stopDaemon({ keepSessions: true });
     fs.rmSync(INTENSITY_FILE, { force: true });
@@ -1107,7 +1234,7 @@ function setHook(hooks, event, command, id) {
   // keeps the existing entries at their original index, which is what Codex
   // keys its per-hook trust records by.
   const kept = (hooks[event] || []).filter((entry) => !isVibeHook(entry, id));
-  kept.push(target(id).entry(command));
+  kept.push(target(id).entry(command, event));
   hooks[event] = kept;
 }
 
@@ -1130,8 +1257,8 @@ function readVibeEntryCount(file, id) {
 }
 
 /** True when --install-hooks has already written our entries for Claude Code. */
-function userHooksInstalled(file = null) {
-  return readVibeEntryCount(file || TARGETS.claude.file(), "claude") > 0;
+function userHooksInstalled(file = null, id = "claude") {
+  return readVibeEntryCount(file || TARGETS[id].file(), id) > 0;
 }
 
 function loadSettings(file, t = null) {
@@ -1246,6 +1373,8 @@ function installHooks(genre = "lofi", volume = 0.4, file = null, { reactive = fa
   }
   if (ev.failure) setHook(settings.hooks, ev.failure, hookCommand("--hook-stop", genre, volume), id);
   if (ev.end) setHook(settings.hooks, ev.end, hookCommand("--hook-end", genre, volume), id);
+  // An interrupt ends the turn the same silent way a closed session does.
+  if (ev.interrupt) setHook(settings.hooks, ev.interrupt, hookCommand("--hook-end", genre, volume), id);
 
   const after = `${JSON.stringify(settings, null, 2)}\n`;
   if (!dryRun) fs.writeFileSync(file, after);
@@ -1261,7 +1390,7 @@ function installHooks(genre = "lofi", volume = 0.4, file = null, { reactive = fa
 const SLASH_MARK = "<!-- vibeaudio:slash-command -->";
 
 function slashCommandFile() {
-  return path.join(os.homedir(), ".claude", "commands", "vibe.md");
+  return path.join(claudeConfigDir(), "commands", "vibe.md");
 }
 
 function slashCommandText() {
@@ -1340,6 +1469,14 @@ function uninstallHooks(file = null, { id = "claude" } = {}) {
 
 module.exports = {
   shellQuote,
+  claudeConfigDir,
+  codexHome,
+  expectedEvents,
+  PLUGIN_FILES,
+  PLUGIN_AGENTS,
+  pluginHookEvents,
+  pluginHooksFile,
+  pluginAgent,
   runDaemon,
   hookStart,
   hookStop,

package/src/player.js

@@ -23,7 +23,10 @@ const { hashString } = require("./synth/generator");
 const { addTension } = require("./synth/tension");
 const pkg = require("../package.json");
 
-const CACHE_ROOT = path.join(os.homedir(), ".vibeaudio", "cache");
+// VIBE_CACHE_DIR is internal: the suite points it at a temp directory, so it
+// neither races live hooks pruning the real cache nor evicts a real project's
+// audio (#38).
+const CACHE_ROOT = process.env.VIBE_CACHE_DIR || path.join(os.homedir(), ".vibeaudio", "cache");
 
 /**
  * The cache key has to change whenever the audio would, or existing users keep
@@ -189,21 +192,23 @@ function ensureCacheDir() {
  */
 function pruneStaleCache() {
   try {
-    for (const entry of fs.readdirSync(CACHE_ROOT, { withFileTypes: true })) {
-      const full = path.join(CACHE_ROOT, entry.name);
-      if (entry.isDirectory() && /^v\d/.test(entry.name) && entry.name !== path.basename(CACHE_DIR)) {
-        fs.rmSync(full, { recursive: true, force: true });
-      } else if (entry.isFile() && entry.name.endsWith(".wav")) {
-        fs.rmSync(full, { force: true });
-      }
-    }
+    removeCacheEntries(path.basename(CACHE_DIR));
   } catch (e) {
     // Pruning is best-effort; a stale cache is not worth failing a run over.
   }
 }
 
+// Only what we write - key directories, and loose WAVs from before keys - and
+// never the root itself: VIBE_CACHE_DIR may name a directory holding more.
+function removeCacheEntries(keep = null) {
+  for (const entry of fs.readdirSync(CACHE_ROOT, { withFileTypes: true })) {
+    const ours = entry.isDirectory() ? /^v\d/.test(entry.name) && entry.name !== keep : entry.isFile() && entry.name.endsWith(".wav");
+    if (ours) fs.rmSync(path.join(CACHE_ROOT, entry.name), { recursive: true, force: true });
+  }
+}
+
 function clearCache() {
-  fs.rmSync(CACHE_ROOT, { recursive: true, force: true });
+  if (fs.existsSync(CACHE_ROOT)) removeCacheEntries();
   return CACHE_ROOT;
 }