@trygocode/notify 0.1.4 → 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/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.4",
+  "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",