@astrofoundry/pi-astro 0.9.0 → 0.10.0

package/README.md

@@ -62,7 +62,7 @@ pi                # launch; confirm [Extensions] lists astro-agents, claude-glob
 - `multi-edit` — registers the enhanced `edit` tool
 - `gemini-image` — registers `gemini_image` tool (requires a Gemini API key; prompts and saves on first use)
 - `security-guard` — blocks/prompts destructive bash commands and sensitive file access; configure at `~/.pi/agent/security-guard.json` (example written on first run); `/security-guard status|reload|test`
-- `notify-on-stop` — runs a shell command when the agent finishes a turn (sound, voice, desktop notification). macOS default: plays the Glass system sound **and** speaks "Agent done" via `say` using the **`Samantha (Enhanced)`** voice. Linux default: `notify-send "pi" "Agent done"`. Override the voice with `PI_STOP_NOTIFY_VOICE=<voice-name>` (macOS only; e.g. `Alex`, `Karen`, `Daniel (Enhanced)`). Replace the full command with `PI_STOP_NOTIFY='afplay /System/Library/Sounds/Glass.aiff && say "Done"'`. Disable everything with `PI_STOP_NOTIFY_OFF=1`. `/notify status|test|off`.
+- `notify-on-stop` — runs a shell command when the agent finishes a turn (sound, voice, desktop notification). **Default: off.** Enable with `/notify on` (state persists in `~/.pi/agent/notify-on-stop.json`); disable with `/notify off`. macOS default command: plays the Glass system sound **and** speaks "Agent done" via `say` using the **`Samantha (Enhanced)`** voice. Linux default: `notify-send "pi" "Agent done"`. Override the voice with `PI_STOP_NOTIFY_VOICE=<voice-name>` (macOS only; e.g. `Alex`, `Karen`, `Daniel (Enhanced)`). Replace the full command with `PI_STOP_NOTIFY='afplay /System/Library/Sounds/Glass.aiff && say "Done"'`. Hard-kill (overrides `/notify on`) with `PI_STOP_NOTIFY_OFF=1`. Commands: `/notify [on|off|status|test]`. See [extensions/notify-on-stop/README.md](extensions/notify-on-stop/README.md) for full details.
   - **macOS voice install (required once for the default):** open **System Settings → Accessibility → Spoken Content → System Voice → Manage Voices…**, expand **English**, check **Samantha (Enhanced)**, click **Done** to download (~500 MB – 1 GB). Verify with `say -v "Samantha (Enhanced)" hi`. If the voice is missing, `say` errors silently and you'll only hear the Glass sound.
 - `vscode-image` — only active inside VS Code's integrated terminal (`TERM_PROGRAM=vscode`). Switches pi-tui's image output to the **Kitty graphics protocol** so images returned by tools like `gemini_image` render as real pixels instead of the `[Image: …]` text fallback. **Requires enabling `Terminal › Integrated: Enable Images` in VS Code settings** (off by default); restart the integrated terminal after flipping it. Disable with `PI_VSCODE_IMAGE_OFF=1`. `/vscode-image` prints current status.
 - `claude-globals` — auto-injects `~/.claude/CLAUDE.md` into every pi session's system prompt

package/extensions/notify-on-stop/README.md

@@ -0,0 +1,114 @@
+# notify-on-stop
+
+Plays a sound, speaks a message, or fires a desktop notification every time the pi agent finishes a turn (`agent_end` event). Cuts the "is it done yet?" tab-switching tax.
+
+Ships as part of [`@astrofoundry/pi-astro`](../../README.md). No extra install.
+
+## Default: off
+
+The extension does **nothing** by default. Enable it once with:
+
+```
+/notify on
+```
+
+State is persisted to `~/.pi/agent/notify-on-stop.json` and survives session restarts and `chezmoi apply`. To turn it back off:
+
+```
+/notify off
+```
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/notify on` | Enable for this and future sessions. Persists. |
+| `/notify off` | Disable for this and future sessions. Persists. |
+| `/notify` or `/notify status` | Print current state and the resolved command |
+| `/notify test` | Run the resolved command immediately, regardless of on/off state |
+
+Argument autocomplete is wired — type `/notify ` and tab-cycle.
+
+## Defaults per platform
+
+When enabled, the extension runs:
+
+| Platform | Command |
+|---|---|
+| macOS | `afplay /System/Library/Sounds/Glass.aiff && say -v "Samantha (Enhanced)" "Agent done"` |
+| Linux | `notify-send "pi" "Agent done"` (only if `notify-send` exists on `PATH`) |
+| Windows / other | Nothing — wire your own command via `PI_STOP_NOTIFY` |
+
+Errors from the notify command are swallowed — a broken sound or missing voice will never surface in pi output.
+
+## macOS voice setup (one-time)
+
+The default speaks via the `Samantha (Enhanced)` voice. If it isn't installed, the `say` command silently fails and you only hear the Glass sound. Install it once:
+
+1. **System Settings → Accessibility → Spoken Content → System Voice → Manage Voices…**
+2. Expand **English**, check **Samantha (Enhanced)**, click **Done** (downloads ~500 MB – 1 GB).
+3. Verify: `say -v "Samantha (Enhanced)" hi`.
+
+If you'd rather skip the install, override with `PI_STOP_NOTIFY_VOICE` or replace the whole command via `PI_STOP_NOTIFY` — see below.
+
+## Configuration (env vars)
+
+Env vars control **what** runs, not **whether**. The on/off toggle is `/notify on|off`.
+
+Set in your shell rc (`.zshrc`/`.bashrc`) so they apply to every pi session.
+
+### `PI_STOP_NOTIFY` — replace the full command
+
+Wins over the platform default. Wins over `PI_STOP_NOTIFY_VOICE`.
+
+```bash
+# Just play the sound, no speech
+export PI_STOP_NOTIFY='afplay /System/Library/Sounds/Glass.aiff'
+
+# Speak something custom
+export PI_STOP_NOTIFY='say "Pi just finished, get back here"'
+
+# Linux: dunst / libnotify
+export PI_STOP_NOTIFY='notify-send "pi" "Done" -u low'
+```
+
+### `PI_STOP_NOTIFY_VOICE` — change only the macOS voice
+
+Used when you keep the default Glass+say behaviour but prefer a different voice. Ignored on Linux/Windows. Ignored when `PI_STOP_NOTIFY` is set.
+
+```bash
+export PI_STOP_NOTIFY_VOICE="Alex"
+export PI_STOP_NOTIFY_VOICE="Daniel (Enhanced)"
+export PI_STOP_NOTIFY_VOICE="Karen"
+```
+
+List available voices: `say -v ?`.
+
+### `PI_STOP_NOTIFY_OFF=1` — hard kill
+
+Overrides the persisted on/off state. Useful for CI / headless runs where you want the extension globally muted regardless of the state file.
+
+```bash
+export PI_STOP_NOTIFY_OFF=1
+```
+
+## Quick recipes
+
+| Goal | What to do |
+|---|---|
+| Enable | `/notify on` |
+| Disable | `/notify off` |
+| Test the command without changing state | `/notify test` |
+| Sound only, no voice | `PI_STOP_NOTIFY='afplay /System/Library/Sounds/Glass.aiff'` |
+| Voice only, no sound | `PI_STOP_NOTIFY='say "Done"'` |
+| Different macOS voice | `PI_STOP_NOTIFY_VOICE="Alex"` |
+| Custom desktop notification | `PI_STOP_NOTIFY='terminal-notifier -title pi -message Done -sound Glass'` |
+| Hard-mute everywhere | `export PI_STOP_NOTIFY_OFF=1` |
+
+## Troubleshooting
+
+- **`/notify on` says "no command resolves on this platform"** — Windows or unknown platform. Set `PI_STOP_NOTIFY` to your own command.
+- **Nothing happens on macOS even though `/notify status` shows `on`** — the Samantha (Enhanced) voice is probably missing. Either install it (above) or set `PI_STOP_NOTIFY_VOICE` to a voice you have. Run `/notify test` to see whether the command itself runs.
+- **Nothing happens on Linux** — install `libnotify` (`apt install libnotify-bin`) or override `PI_STOP_NOTIFY`.
+- **`/notify status` shows the right command but nothing happens** — the command is launched via `/bin/sh` with a 10-second timeout, and all errors are silenced. Run the command directly in a shell to see the real error.
+- **Env-var changes don't take effect** — env vars are read once when the extension loads. Restart pi after changing them. The on/off state, by contrast, applies immediately.

package/extensions/notify-on-stop/index.test.ts

@@ -5,7 +5,6 @@ const execMock = vi.fn();
 vi.mock("node:child_process", () => ({
     exec: (cmd: string, opts: unknown, cb?: unknown) => {
         execMock(cmd, opts, cb);
-        // Return a chainable fake child with on/stdout/stderr
         const fake = {
             on: vi.fn(),
             stdout: { on: vi.fn() },
@@ -15,15 +14,39 @@ vi.mock("node:child_process", () => ({
     },
 }));
 
+const fakeFiles = new Map<string, string>();
+
+vi.mock("node:fs", () => ({
+    existsSync: (p: string) => fakeFiles.has(p),
+    readFileSync: (p: string) => {
+        const value = fakeFiles.get(p);
+        if (value === undefined) throw new Error(`ENOENT: ${p}`);
+        return value;
+    },
+    writeFileSync: (p: string, data: string) => {
+        fakeFiles.set(p, data);
+    },
+    mkdirSync: vi.fn(),
+}));
+
 type Handler = (event: unknown, ctx: unknown) => void | Promise<void>;
 type CommandHandler = (args: string, ctx: unknown) => Promise<void> | void;
 
-function makePi(): {
+interface FakePi {
     handlers: Record<string, Handler>;
-    commands: Map<string, { handler: CommandHandler }>;
+    commands: Map<string, { handler: CommandHandler; getArgumentCompletions?: (p: string) => unknown }>;
     on: (event: string, h: Handler) => void;
-    registerCommand: (name: string, opts: { description?: string; handler: CommandHandler }) => void;
-} {
+    registerCommand: (
+        name: string,
+        opts: {
+            description?: string;
+            handler: CommandHandler;
+            getArgumentCompletions?: (p: string) => unknown;
+        },
+    ) => void;
+}
+
+function makePi(): FakePi {
     const handlers: Record<string, Handler> = {};
     const commands = new Map();
     return {
@@ -33,7 +56,10 @@ function makePi(): {
             handlers[event] = h;
         },
         registerCommand: (name, opts) => {
-            commands.set(name, { handler: opts.handler });
+            commands.set(name, {
+                handler: opts.handler,
+                getArgumentCompletions: opts.getArgumentCompletions,
+            });
         },
     };
 }
@@ -48,6 +74,11 @@ function setPlatform(p: NodeJS.Platform): void {
     Object.defineProperty(process, "platform", { value: p, configurable: true });
 }
 
+function seedEnabled(enabled: boolean): void {
+    const stateFile = `${process.env.HOME}/.pi/agent/notify-on-stop.json`;
+    fakeFiles.set(stateFile, JSON.stringify({ enabled }));
+}
+
 describe("notify-on-stop", () => {
     const origCmd = process.env.PI_STOP_NOTIFY;
     const origOff = process.env.PI_STOP_NOTIFY_OFF;
@@ -56,6 +87,7 @@ describe("notify-on-stop", () => {
     beforeEach(() => {
         vi.resetModules();
         execMock.mockReset();
+        fakeFiles.clear();
         delete process.env.PI_STOP_NOTIFY;
         delete process.env.PI_STOP_NOTIFY_OFF;
         delete process.env.PI_STOP_NOTIFY_VOICE;
@@ -71,174 +103,215 @@ describe("notify-on-stop", () => {
         else process.env.PI_STOP_NOTIFY_VOICE = origVoice;
     });
 
-    it("runs default command on agent_end (macOS): afplay + say with Samantha (Enhanced)", async () => {
+    it("defaults to off — agent_end runs nothing on a fresh install", async () => {
         setPlatform("darwin");
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
         pi.handlers.agent_end({}, makeCtx());
-        expect(execMock).toHaveBeenCalled();
-        const cmd = execMock.mock.calls[0][0] as string;
-        expect(cmd).toMatch(/^afplay \/System\/Library\/Sounds\/Glass\.aiff && say -v /);
-        expect(cmd).toContain("'Samantha (Enhanced)'");
-        expect(cmd).toContain("'Agent done'");
+        expect(execMock).not.toHaveBeenCalled();
     });
 
-    it("PI_STOP_NOTIFY_VOICE overrides the default voice (macOS)", async () => {
+    it("/notify on persists enabled=true and starts firing on agent_end (macOS default)", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY_VOICE = "Alex";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("on", ctx);
+        expect(fakeFiles.get(`${process.env.HOME}/.pi/agent/notify-on-stop.json`)).toContain('"enabled": true');
         pi.handlers.agent_end({}, makeCtx());
         const cmd = execMock.mock.calls[0][0] as string;
-        expect(cmd).toContain("say -v 'Alex'");
-        expect(cmd).not.toContain("Samantha");
+        expect(cmd).toMatch(/^afplay \/System\/Library\/Sounds\/Glass\.aiff && say -v /);
+        expect(cmd).toContain("'Samantha (Enhanced)'");
     });
 
-    it("PI_STOP_NOTIFY_VOICE with apostrophes is POSIX-safely quoted", async () => {
+    it("/notify off persists enabled=false and stops firing on agent_end", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY_VOICE = "O'Neill";
+        seedEnabled(true);
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("off", ctx);
+        expect(fakeFiles.get(`${process.env.HOME}/.pi/agent/notify-on-stop.json`)).toContain('"enabled": false');
         pi.handlers.agent_end({}, makeCtx());
-        const cmd = execMock.mock.calls[0][0] as string;
-        expect(cmd).toContain("say -v 'O'\\''Neill'");
+        expect(execMock).not.toHaveBeenCalled();
+        expect(ctx.ui.notify).toHaveBeenCalledWith("notify: off (persisted)", "info");
     });
 
-    it("PI_STOP_NOTIFY_VOICE with only whitespace falls back to default voice (macOS)", async () => {
+    it("state survives across extension reloads", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY_VOICE = "   ";
+        seedEnabled(true);
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
         pi.handlers.agent_end({}, makeCtx());
-        const cmd = execMock.mock.calls[0][0] as string;
-        expect(cmd).toContain("'Samantha (Enhanced)'");
+        expect(execMock).toHaveBeenCalled();
     });
 
-    it("PI_STOP_NOTIFY_VOICE is ignored when PI_STOP_NOTIFY overrides the full command", async () => {
+    it("PI_STOP_NOTIFY_OFF=1 hard-kills even when enabled is true", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY = "my custom --cmd";
-        process.env.PI_STOP_NOTIFY_VOICE = "Alex";
+        seedEnabled(true);
+        process.env.PI_STOP_NOTIFY_OFF = "1";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
         pi.handlers.agent_end({}, makeCtx());
-        expect(execMock.mock.calls[0][0]).toBe("my custom --cmd");
+        expect(execMock).not.toHaveBeenCalled();
     });
 
-    it("PI_STOP_NOTIFY_VOICE has no effect on Linux default", async () => {
-        setPlatform("linux");
-        process.env.PI_STOP_NOTIFY_VOICE = "Alex";
+    it("/notify status reflects on/off", async () => {
+        setPlatform("darwin");
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        pi.handlers.agent_end({}, makeCtx());
-        const cmd = execMock.mock.calls[0][0] as string;
-        expect(cmd).toMatch(/notify-send/);
-        expect(cmd).not.toContain("say");
-        expect(cmd).not.toContain("Alex");
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("status", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/notify: off/), "info");
+        await pi.commands.get("notify")!.handler("on", ctx);
+        await pi.commands.get("notify")!.handler("status", ctx);
+        expect(ctx.ui.notify).toHaveBeenLastCalledWith(expect.stringMatching(/notify: on .* will run /), "info");
     });
 
-    it("runs custom PI_STOP_NOTIFY over default", async () => {
+    it("/notify status reports hard-kill via env var", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY = "my custom --cmd";
+        seedEnabled(true);
+        process.env.PI_STOP_NOTIFY_OFF = "1";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        pi.handlers.agent_end({}, makeCtx());
-        expect(execMock.mock.calls[0][0]).toBe("my custom --cmd");
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("status", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/PI_STOP_NOTIFY_OFF=1/), "info");
     });
 
-    it("does NOT run anything when PI_STOP_NOTIFY_OFF=1", async () => {
+    it("/notify test runs the command immediately even when disabled", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY_OFF = "1";
+        process.env.PI_STOP_NOTIFY = "test-cmd";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        pi.handlers.agent_end({}, makeCtx());
-        expect(execMock).not.toHaveBeenCalled();
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("test", ctx);
+        expect(execMock.mock.calls[0][0]).toBe("test-cmd");
     });
 
-    it("does nothing on an unsupported platform with no env", async () => {
+    it("/notify test warns when nothing configured (unsupported platform)", async () => {
         setPlatform("win32");
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        pi.handlers.agent_end({}, makeCtx());
-        expect(execMock).not.toHaveBeenCalled();
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("test", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/nothing configured/), "warning");
     });
 
-    it("Linux default uses notify-send", async () => {
-        setPlatform("linux");
+    it("/notify on warns if no command resolves on this platform", async () => {
+        setPlatform("win32");
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("on", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(
+            expect.stringMatching(/notify: on, but no command resolves/),
+            "warning",
+        );
+    });
+
+    it("PI_STOP_NOTIFY overrides the default command", async () => {
+        setPlatform("darwin");
+        seedEnabled(true);
+        process.env.PI_STOP_NOTIFY = "my custom --cmd";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
         pi.handlers.agent_end({}, makeCtx());
-        expect(execMock.mock.calls[0][0]).toMatch(/notify-send/);
+        expect(execMock.mock.calls[0][0]).toBe("my custom --cmd");
     });
 
-    it("trims whitespace on PI_STOP_NOTIFY and ignores empty strings", async () => {
+    it("PI_STOP_NOTIFY_VOICE overrides the macOS default voice", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY = "   ";
+        seedEnabled(true);
+        process.env.PI_STOP_NOTIFY_VOICE = "Alex";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
         pi.handlers.agent_end({}, makeCtx());
-        expect(execMock.mock.calls[0][0]).toMatch(/afplay/);
+        const cmd = execMock.mock.calls[0][0] as string;
+        expect(cmd).toContain("say -v 'Alex'");
+        expect(cmd).not.toContain("Samantha");
     });
 
-    it("/notify status reports current command", async () => {
+    it("PI_STOP_NOTIFY_VOICE with apostrophes is POSIX-safely quoted", async () => {
         setPlatform("darwin");
+        seedEnabled(true);
+        process.env.PI_STOP_NOTIFY_VOICE = "O'Neill";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        const ctx = makeCtx();
-        await pi.commands.get("notify")!.handler("status", ctx);
-        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/afplay/), "info");
+        pi.handlers.agent_end({}, makeCtx());
+        const cmd = execMock.mock.calls[0][0] as string;
+        expect(cmd).toContain("say -v 'O'\\''Neill'");
     });
 
-    it("/notify status reports disabled when PI_STOP_NOTIFY_OFF", async () => {
+    it("PI_STOP_NOTIFY_VOICE with only whitespace falls back to default voice", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY_OFF = "1";
+        seedEnabled(true);
+        process.env.PI_STOP_NOTIFY_VOICE = "   ";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        const ctx = makeCtx();
-        await pi.commands.get("notify")!.handler("", ctx);
-        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/disabled/), "info");
+        pi.handlers.agent_end({}, makeCtx());
+        const cmd = execMock.mock.calls[0][0] as string;
+        expect(cmd).toContain("'Samantha (Enhanced)'");
     });
 
-    it("/notify test runs the command immediately", async () => {
+    it("PI_STOP_NOTIFY_VOICE is ignored when PI_STOP_NOTIFY overrides the full command", async () => {
         setPlatform("darwin");
-        process.env.PI_STOP_NOTIFY = "test-cmd";
+        seedEnabled(true);
+        process.env.PI_STOP_NOTIFY = "my custom --cmd";
+        process.env.PI_STOP_NOTIFY_VOICE = "Alex";
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        const ctx = makeCtx();
-        await pi.commands.get("notify")!.handler("test", ctx);
-        expect(execMock.mock.calls[0][0]).toBe("test-cmd");
+        pi.handlers.agent_end({}, makeCtx());
+        expect(execMock.mock.calls[0][0]).toBe("my custom --cmd");
     });
 
-    it("/notify test warns when nothing configured", async () => {
-        setPlatform("win32");
+    it("Linux default uses notify-send", async () => {
+        setPlatform("linux");
+        seedEnabled(true);
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        const ctx = makeCtx();
-        await pi.commands.get("notify")!.handler("test", ctx);
-        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/nothing configured/), "warning");
+        pi.handlers.agent_end({}, makeCtx());
+        expect(execMock.mock.calls[0][0]).toMatch(/notify-send/);
     });
 
-    it("/notify off gives persistence guidance", async () => {
+    it("argument autocomplete returns on/off/status/test", async () => {
         setPlatform("darwin");
         const mod = await import("./index.ts");
         const pi = makePi();
         mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
-        const ctx = makeCtx();
-        await pi.commands.get("notify")!.handler("off", ctx);
-        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/PI_STOP_NOTIFY_OFF/), "info");
+        const completions = pi.commands.get("notify")!.getArgumentCompletions!("");
+        expect(completions).toEqual(
+            expect.arrayContaining([
+                { value: "on", label: "on" },
+                { value: "off", label: "off" },
+                { value: "status", label: "status" },
+                { value: "test", label: "test" },
+            ]),
+        );
+    });
+
+    it("argument autocomplete returns null when no candidate matches", async () => {
+        setPlatform("darwin");
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const completions = pi.commands.get("notify")!.getArgumentCompletions!("zzz");
+        expect(completions).toBeNull();
     });
 });

package/extensions/notify-on-stop/index.ts

@@ -1,4 +1,7 @@
 import { exec } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
 const ENV_CMD = "PI_STOP_NOTIFY";
@@ -8,6 +11,25 @@ const TIMEOUT_MS = 10_000;
 const DEFAULT_VOICE = "Samantha (Enhanced)";
 const MACOS_SPOKEN_MESSAGE = "Agent done";
 
+const STATE_DIR = path.join(os.homedir(), ".pi", "agent");
+const STATE_FILE = path.join(STATE_DIR, "notify-on-stop.json");
+
+interface PersistedState {
+    enabled: boolean;
+}
+
+function readEnabled(): boolean {
+    if (!fs.existsSync(STATE_FILE)) return false;
+    const raw = fs.readFileSync(STATE_FILE, "utf8");
+    const parsed = JSON.parse(raw) as PersistedState;
+    return parsed.enabled === true;
+}
+
+function writeEnabled(enabled: boolean): void {
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+    fs.writeFileSync(STATE_FILE, `${JSON.stringify({ enabled }, null, 2)}\n`);
+}
+
 function shellQuote(value: string): string {
     return `'${value.replace(/'/g, "'\\''")}'`;
 }
@@ -34,14 +56,16 @@ function resolveCommand(): string | undefined {
 
 function runNotify(cmd: string): void {
     const child = exec(cmd, { shell: "/bin/sh", timeout: TIMEOUT_MS });
-    // Swallow errors so a broken notify command never surfaces into pi output.
     child.on("error", () => {});
     child.stderr?.on("data", () => {});
     child.stdout?.on("data", () => {});
 }
 
 export default function notifyOnStopExtension(pi: ExtensionAPI): void {
+    let enabled = readEnabled();
+
     pi.on("agent_end", () => {
+        if (!enabled) return;
         const cmd = resolveCommand();
         if (!cmd) return;
         runNotify(cmd);
@@ -49,31 +73,60 @@ export default function notifyOnStopExtension(pi: ExtensionAPI): void {
 
     pi.registerCommand("notify", {
         description:
-            "Stop-notify status/test. Usage: /notify [status|test|off]. Configure via env PI_STOP_NOTIFY (full override) or PI_STOP_NOTIFY_VOICE (macOS default voice); disable with PI_STOP_NOTIFY_OFF=1.",
+            "Stop-notify control. Usage: /notify [on|off|status|test]. State persists in ~/.pi/agent/notify-on-stop.json. Defaults to off; PI_STOP_NOTIFY_OFF=1 hard-kills regardless.",
+        getArgumentCompletions: (prefix) => {
+            const items = ["on", "off", "status", "test"];
+            const lower = prefix.toLowerCase();
+            const matches = items
+                .filter((value) => value.startsWith(lower))
+                .map((value) => ({ value, label: value }));
+            return matches.length > 0 ? matches : null;
+        },
         handler: async (args, ctx) => {
             const sub = args.trim().toLowerCase() || "status";
+
             if (sub === "test") {
                 const cmd = resolveCommand();
                 if (!cmd) {
-                    ctx.ui.notify("notify: nothing configured / disabled", "warning");
+                    ctx.ui.notify("notify: nothing configured (no platform default and no PI_STOP_NOTIFY)", "warning");
                     return;
                 }
                 runNotify(cmd);
                 ctx.ui.notify(`notify: ran "${cmd}"`, "info");
                 return;
             }
-            if (sub === "off") {
+
+            if (sub === "on") {
+                enabled = true;
+                writeEnabled(true);
+                const cmd = resolveCommand();
                 ctx.ui.notify(
-                    `notify: to disable persistently, set ${ENV_OFF}=1 in your shell rc; this session's behavior is driven by env at startup.`,
-                    "info",
+                    cmd
+                        ? `notify: on — will run "${cmd}" on agent_end`
+                        : `notify: on, but no command resolves on this platform (set PI_STOP_NOTIFY)`,
+                    cmd ? "info" : "warning",
                 );
                 return;
             }
+
+            if (sub === "off") {
+                enabled = false;
+                writeEnabled(false);
+                ctx.ui.notify("notify: off (persisted)", "info");
+                return;
+            }
+
             const cmd = resolveCommand();
+            const hardKilled = process.env[ENV_OFF] === "1";
+            const stateLabel = hardKilled
+                ? `off (PI_STOP_NOTIFY_OFF=1)`
+                : enabled
+                  ? "on"
+                  : "off";
             ctx.ui.notify(
-                cmd
-                    ? `notify: will run "${cmd}" on agent_end`
-                    : `notify: disabled (no default for this platform or ${ENV_OFF}=1)`,
+                cmd && enabled && !hardKilled
+                    ? `notify: ${stateLabel} — will run "${cmd}" on agent_end`
+                    : `notify: ${stateLabel}${cmd ? "" : " (no command resolves on this platform)"}`,
                 "info",
             );
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Personal pi customizations (extensions, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"