@trygocode/notify 0.1.3 → 0.1.5

package/README.md

@@ -109,7 +109,7 @@ or staging GoCode server.
 
 | Trigger | Mechanism | Fires when |
 |---|---|---|
-| **(A) Runtime hook** | Cursor `stop` / Claude Code `Stop`+`Notification`+`SubagentStop` / OpenCode `session.idle` plugin | Agent finishes a turn, goes idle, or errors — **automatic, the killer feature** |
+| **(A) Runtime hook** | Cursor `stop` / Claude Code `Stop`+`Notification` / OpenCode `session.idle` plugin | The MAIN agent finishes a turn, goes idle, or errors — **automatic, the killer feature** |
 | **(B) MCP tool** | `gocode_notify` tool the agent calls | You *explicitly* ask "ping me when X is done" mid-task |
 | **(C) Loop shell hook** | one line in your loop's completion/halt path | A Ralph/Homer loop reaches `completed` / `halted` |
 

package/dist/src/claude.js

@@ -2,12 +2,16 @@
 // Claude Code. It does three things, all idempotently and without clobbering the
 // user's existing config:
 //
-//   1. MERGE three fire-and-forget hooks into `~/.claude/settings.json`:
-//        Stop          → "finished"        (a turn completed)
+//   1. MERGE two fire-and-forget hooks into `~/.claude/settings.json`:
+//        Stop          → "finished"        (the MAIN turn completed)
 //        Notification  → "awaiting_input"  (the agent needs the user)
-//        SubagentStop  → "finished"        (a subagent completed)
-//      Each hook shells out to `gocode-notify send … || true` so a failed push
+//      Each hook shells out to `gocode-notify … || true` so a failed push
 //      NEVER blocks the agent's turn (PRD §4.4, §5.3).
+//      NOTE: we deliberately do NOT register a `SubagentStop` hook — a notify
+//      should fire only when the MAIN agent finishes its turn, not on every
+//      internal subagent completion (that produced noisy "Subagent done" pings).
+//      Any prior `SubagentStop` hook of ours is actively stripped on re-setup
+//      (see {@link SUBAGENT_STOP_EVENT} + {@link mergeHooks}).
 //   2. MERGE an `mcpServers` entry pointing at `npx -y @trygocode/notify mcp`.
 //   3. WRITE the on-demand skill to `~/.claude/skills/gocode-notify/SKILL.md`
 //      (the anti-double-ping rule, PRD §5.5).
@@ -46,14 +50,33 @@ export const MCP_SERVER_ENTRY = {
  * plain `finished` ping — exactly one notification per turn. The pre-T-C6 form
  * was `send --kind finished --source claude_code …`; both old and new commands
  * contain the {@link HOOK_MARKERS} tokens, so old installs upgrade idempotently
- * and uninstall cleanly. `Notification`/`SubagentStop` stay on the plain `send`
- * (they are not turn-completion events and never auto-push).
+ * and uninstall cleanly. `Notification` stays on the plain `send` (it is not a
+ * turn-completion event and never auto-pushes).
+ *
+ * We intentionally register ONLY `Stop` + `Notification`. `SubagentStop` is NOT
+ * here on purpose — see {@link SUBAGENT_STOP_EVENT}.
  */
 export const CLAUDE_HOOK_COMMANDS = {
     Stop: 'npx -y @trygocode/notify on-stop --source claude_code --dedupe-key "$CLAUDE_SESSION_ID-stop" || true',
     Notification: 'npx -y @trygocode/notify send --kind awaiting_input --source claude_code --title "Agent needs you" --dedupe-key "$CLAUDE_SESSION_ID-notify" || true',
-    SubagentStop: 'npx -y @trygocode/notify send --kind finished --source claude_code --title "Subagent done" --dedupe-key "$CLAUDE_SESSION_ID-subagent" || true',
 };
+/**
+ * The Claude event we DELIBERATELY do not register and actively scrub on every
+ * setup. We used to fire a `finished` push on `SubagentStop` ("Subagent done"),
+ * but a notification should only land when the MAIN agent finishes its turn —
+ * not for each internal subagent. `mergeHooks` strips any prior copy of OUR
+ * command from this event so existing installs are migrated clean on re-setup,
+ * and `uninstallClaudeConfig` also covers it (the uninstall strip is event-set
+ * agnostic). Kept as a named constant so the scrub list is single-sourced.
+ */
+export const SUBAGENT_STOP_EVENT = "SubagentStop";
+/**
+ * Events we make sure carry NONE of our hooks after a merge — events we no
+ * longer install but may have written in a prior version. `mergeHooks` walks
+ * this set and strips our commands from each, so re-running `setup` migrates an
+ * old install (with a stale "Subagent done" hook) to the current clean shape.
+ */
+const DEPRECATED_HOOK_EVENTS = [SUBAGENT_STOP_EVENT];
 /**
  * Substrings that together identify a hook command as OURS. Used for idempotent
  * merge (replace, don't duplicate) and for surgical uninstall (remove exactly
@@ -176,12 +199,28 @@ function ourHookGroup(command) {
  */
 function mergeHooks(settings) {
     const hooks = isRecord(settings.hooks) ? settings.hooks : {};
+    // Install (or refresh) the events we DO want.
     for (const [event, command] of Object.entries(CLAUDE_HOOK_COMMANDS)) {
         const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
         const preserved = stripOurHooks(existing).groups;
         preserved.push(ourHookGroup(command));
         hooks[event] = preserved;
     }
+    // Migrate old installs: strip OUR command from any event we no longer install
+    // (e.g. the retired `SubagentStop` "Subagent done" ping). We only remove our
+    // own entries — a user's own hook on the same event is preserved. An event
+    // left with no groups is deleted so we don't leave an empty array behind.
+    for (const event of DEPRECATED_HOOK_EVENTS) {
+        if (!Array.isArray(hooks[event]))
+            continue;
+        const cleaned = stripOurHooks(hooks[event]).groups;
+        if (cleaned.length === 0) {
+            delete hooks[event];
+        }
+        else {
+            hooks[event] = cleaned;
+        }
+    }
     settings.hooks = hooks;
 }
 /** Merge our MCP server entry into `settings.mcpServers`. Mutates in place. */
@@ -247,7 +286,14 @@ export async function uninstallClaudeConfig(opts) {
             let changed = false;
             if (isRecord(settings.hooks)) {
                 const hooks = settings.hooks;
-                for (const event of Object.keys(CLAUDE_HOOK_COMMANDS)) {
+                // Scrub our hooks from the events we install AND from deprecated events
+                // we no longer install but may have written in a prior version (e.g. the
+                // retired `SubagentStop` ping) — otherwise an uninstall would orphan it.
+                const eventsToScrub = [
+                    ...Object.keys(CLAUDE_HOOK_COMMANDS),
+                    ...DEPRECATED_HOOK_EVENTS,
+                ];
+                for (const event of eventsToScrub) {
                     if (!Array.isArray(hooks[event]))
                         continue;
                     const { groups: kept, removed } = stripOurHooks(hooks[event]);

package/dist/src/on_stop.js

@@ -106,12 +106,12 @@ export async function onStop(opts = {}) {
                 timestamp: opts.timestamp,
                 home: opts.home,
             });
-            await logLine(`auto-push path → ${push.outcome} (settings: ${resolved.source})`);
+            await logLine(`auto-push path → ${push.outcome} (source: ${source}, settings: ${resolved.source})`);
             return { mode: "push", settingsSource: resolved.source, push, repo, detail: push.detail };
         }
         // ── Step 3b: auto-push off → the plain `finished` notification (legacy flow). ──
         if (opts.dryRun) {
-            await logLine(`dry-run: would send finished (auto-push off, settings: ${resolved.source})`);
+            await logLine(`dry-run: would send finished (auto-push off, source: ${source}, settings: ${resolved.source})`);
             return { mode: "dry-run-send", settingsSource: resolved.source, repo };
         }
         const payload = { kind: "finished", source };
@@ -120,7 +120,7 @@ export async function onStop(opts = {}) {
         if (opts.dedupeKey)
             payload.dedupe_key = opts.dedupeKey;
         const sent = await sendImpl(payload);
-        await logLine(`send path → finished ${sent.ok ? "delivered" : "failed"} (settings: ${resolved.source})`);
+        await logLine(`send path → finished ${sent.ok ? "delivered" : "failed"} (source: ${source}, settings: ${resolved.source})`);
         return { mode: "send", settingsSource: resolved.source, send: sent, repo };
     }
     catch (err) {

package/dist/src/opencode.js

@@ -77,33 +77,135 @@ export const OPENCODE_STOP_COMMAND = "npx -y @trygocode/notify on-stop --source
  */
 const PLUGIN_MARKERS = ["gocode-notify", "--source opencode"];
 /**
- * The `session.idle` plugin written to `<config-dir>/plugin/gocode-notify.js`.
+ * Best-effort predicate: does an OpenCode `session.status` payload's `status`
+ * value mean "the agent finished this turn"?
+ *
+ * The `status` value has shifted shape across OpenCode versions — a bare string
+ * (`"idle"`) and an object (`{ type | state | status: "idle" }`). We normalise
+ * to a lowercase string and treat any idle/done/complete/finish word as
+ * end-of-turn, while explicitly REJECTING busy/working/running/active/stream/
+ * pending states so we never ping mid-turn.
+ *
+ * Exported so the generated plugin's behaviour is unit-testable in isolation
+ * (the plugin body inlines the identical logic — keep the two in lockstep; the
+ * `opencode.test.ts` "statusIsIdle parity" test guards against drift).
+ */
+export function opencodeStatusIsIdle(status) {
+    if (status == null)
+        return false;
+    const raw = typeof status === "string"
+        ? status
+        : isRecord(status)
+            ? (status.type ?? status.state ?? status.status ?? "")
+            : "";
+    const s = String(raw).toLowerCase();
+    if (!s)
+        return false;
+    if (s.includes("busy") ||
+        s.includes("work") ||
+        s.includes("run") ||
+        s.includes("active") ||
+        s.includes("stream") ||
+        s.includes("pending")) {
+        return false;
+    }
+    return (s.includes("idle") ||
+        s.includes("done") ||
+        s.includes("complete") ||
+        s.includes("finish"));
+}
+/**
+ * The end-of-turn plugin written to `<config-dir>/plugin/gocode-notify.js`.
+ *
  * An OpenCode plugin exports an async factory returning `{ event }`; we fire the
- * shared `on-stop` dispatcher fire-and-forget on `session.idle`. The child is
- * detached + unref'd with stdio ignored so it NEVER blocks the session, and any
- * spawn error is swallowed (belt-and-braces with the command's own `|| true`).
+ * shared `on-stop` dispatcher fire-and-forget when a session finishes a turn.
+ *
+ * IMPORTANT — why we listen to TWO events:
+ *   - `session.idle` is the original "turn finished" signal, but as of recent
+ *     OpenCode builds (≥ ~1.14) it is **deprecated** and no longer reliably
+ *     emitted in the GUI (upstream moved to `session.status`). Riding it alone
+ *     meant "Cursor pings me, OpenCode doesn't".
+ *   - `session.status` (payload `{ sessionID, status }`) is the modern signal.
+ *     It fires on EVERY status change, so we only treat it as end-of-turn when
+ *     the status is the idle/finished state (best-effort shape detection — the
+ *     `status` value has been a string and an object across versions).
+ *
+ * We subscribe to BOTH so the plugin works on old AND new OpenCode. A small
+ * per-session debounce (DEDUPE_MS) coalesces the idle+status pair for the same
+ * turn so we never spawn `on-stop` twice; the server's `--dedupe-key` is the
+ * second line of defence. The child is detached + unref'd with stdio ignored so
+ * it NEVER blocks the session, and any spawn error is swallowed (belt-and-braces
+ * with the command's own `|| true`).
  */
-export const OPENCODE_PLUGIN_CONTENT = `// gocode-notify — OpenCode session.idle plugin (auto-generated by @trygocode/notify).
+export const OPENCODE_PLUGIN_CONTENT = `// gocode-notify — OpenCode end-of-turn plugin (auto-generated by @trygocode/notify).
 // Fires exactly one fire-and-forget phone notification when an OpenCode session
-// goes idle (the OpenCode equivalent of Claude \`Stop\` / Cursor \`stop\`) by
+// finishes a turn (the OpenCode equivalent of Claude \`Stop\` / Cursor \`stop\`) by
 // shelling out to the shared gocode-notify \`on-stop\` dispatcher. It NEVER blocks
 // the session: the child is detached + unref'd, stdio ignored, errors swallowed.
 //
+// Listens to BOTH \`session.idle\` (legacy, deprecated in newer OpenCode) and
+// \`session.status\` (modern end-of-turn signal). A per-session debounce stops the
+// two from double-firing for the same turn. See tools/gocode-notify/src/opencode.ts.
+//
 // Stable markers (do not edit): gocode-notify --source opencode
 // Managed by @trygocode/notify — \`npx @trygocode/notify uninstall\` removes this file.
 import { spawn } from "node:child_process";
 
+// Per-session last-fire timestamps so idle+status for the SAME turn coalesce.
+const lastFiredAt = new Map();
+const DEDUPE_MS = 4000;
+
+function fire() {
+  try {
+    const child = spawn(
+      ${JSON.stringify(OPENCODE_STOP_COMMAND)},
+      { shell: true, detached: true, stdio: "ignore" },
+    );
+    child.unref();
+  } catch {
+    // never block the session on a notification failure
+  }
+}
+
+// Best-effort: does this \`session.status\` payload mean "the agent finished"?
+// The status value has been a bare string ("idle") and an object ({type|state|
+// status: "idle"}) across OpenCode versions; treat any of those idle-ish shapes
+// as end-of-turn, and explicitly IGNORE busy/working/running states.
+function statusIsIdle(status) {
+  if (status == null) return false;
+  const s = (typeof status === "string"
+    ? status
+    : (status.type ?? status.state ?? status.status ?? "")
+  ).toString().toLowerCase();
+  if (!s) return false;
+  if (s.includes("busy") || s.includes("work") || s.includes("run") ||
+      s.includes("active") || s.includes("stream") || s.includes("pending")) {
+    return false;
+  }
+  return s.includes("idle") || s.includes("done") ||
+         s.includes("complete") || s.includes("finish");
+}
+
+function maybeFire(sessionID) {
+  const key = sessionID || "_";
+  const now = Date.now();
+  const prev = lastFiredAt.get(key) ?? 0;
+  if (now - prev < DEDUPE_MS) return; // coalesce idle+status for one turn
+  lastFiredAt.set(key, now);
+  fire();
+}
+
 export const GocodeNotify = async () => ({
   event: async ({ event }) => {
-    if (!event || event.type !== "session.idle") return;
-    try {
-      const child = spawn(
-        ${JSON.stringify(OPENCODE_STOP_COMMAND)},
-        { shell: true, detached: true, stdio: "ignore" },
-      );
-      child.unref();
-    } catch {
-      // never block the session on a notification failure
+    if (!event) return;
+    const props = event.properties ?? {};
+    if (event.type === "session.idle") {
+      maybeFire(props.sessionID);
+      return;
+    }
+    if (event.type === "session.status") {
+      if (statusIsIdle(props.status)) maybeFire(props.sessionID);
+      return;
     }
   },
 });

package/dist/src/rule-content.js

@@ -8,7 +8,7 @@
 //   1. The frontmatter block (Claude SKILL.md `name:`+`description:` vs Cursor
 //      rule `description:`+`alwaysApply:`).
 //   2. The parenthetical naming WHICH runtime hook owns the automatic pings
-//      (Claude fires `Stop`+`Notification`+`SubagentStop`; Cursor fires `stop`).
+//      (Claude fires `Stop`+`Notification`; Cursor fires `stop`).
 //
 // Centralising the prose here means the anti-double-ping invariant ("the hooks
 // own the automatic done/idle/error pings — only call the MCP tool when the user
@@ -58,7 +58,7 @@ name: gocode-notify
 description: On-demand phone notifications via the GoCode app. Use ONLY when the user EXPLICITLY asks to be pinged/notified when something finishes (e.g. "text me when the build is done").
 ---`;
 /** How Claude Code's automatic-ping hooks are named in the double-notify warning. */
-export const CLAUDE_HOOK_DESCRIPTION = "Claude Code `Stop` + `Notification` +\n`SubagentStop`";
+export const CLAUDE_HOOK_DESCRIPTION = "Claude Code `Stop` + `Notification`";
 /**
  * Cursor rule frontmatter (PRD §5.5). `alwaysApply: false` + a trigger-y
  * description so Cursor surfaces it on "notify me / ping me / let me know when".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trygocode/notify",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Free phone notifications for any coding agent (Cursor, Claude Code, OpenCode, Ralph/Homer) via the GoCode app.",
   "license": "MIT",
   "type": "module",