@trygocode/notify 0.4.0 → 0.5.0

package/README.md

@@ -128,14 +128,14 @@ The installed rule/skill tells the agent **not** to call the MCP tool for
 done/idle/error pings — those are owned by the deterministic hook (A), so you
 never get double-pinged.
 
-> **Cursor `stop.status` → kind mapping (since 0.3.0).** Cursor's `stop` hook
-> carries a `status` field in its stdin JSON. The `on-stop` dispatcher maps it
-> to the right notification kind automatically:
+> **Cursor `stop.status` → kind mapping (since 0.3.0; `aborted` corrected 0.4.0).**
+> Cursor's `stop` hook carries a `status` field in its stdin JSON. The `on-stop`
+> dispatcher maps it to the right notification kind automatically:
 >
 > | Cursor `stop.status` | Notification kind | Meaning |
 > |---|---|---|
 > | `completed` | `finished` | Agent turned cleanly (default — same as before 0.3.0) |
-> | `aborted` | `awaiting_input` | Agent yielded back to you — may need your input |
+> | `aborted` | _(suppressed — no notification)_ | You pressed **Stop** to interrupt the turn — a manual stop sends nothing |
 > | `error` | `error` | Agent hit an error |
 > | absent / unrecognised | `finished` | Back-compatible fallback |
 >
@@ -143,6 +143,28 @@ never get double-pinged.
 > did. The status mapping requires no hook re-installation — run
 > `gocode-notify setup --force` once to apply the updated hook command.
 
+> **Question detection — "Agent needs you" (since 0.5.0).** When the agent
+> **pauses to ask you a question** (as opposed to finishing its work), the
+> package fires an `awaiting_input` ping titled **"Agent needs you"** instead of
+> a misleading `finished`. The available signal differs per runtime:
+>
+> | Runtime | Question signal | Status |
+> |---|---|---|
+> | **Claude Code** | dedicated `Notification` hook → `awaiting_input` | ✅ Live — questions show as questions |
+> | **OpenCode** | `permission.asked` plugin event → `awaiting_input` | ✅ Live — OpenCode genuinely exposes a "needs you" signal |
+> | **Cursor** | `postToolUse` hook scoped to the `AskQuestion` tool → `awaiting_input` | ⏳ Installed but **dormant** — see note |
+>
+> **Cursor caveat:** Cursor currently exposes **no** "agent needs input" event
+> (its docs list `Notification` as unsupported), and there is a
+> [confirmed-open Cursor bug](https://forum.cursor.com/t/askquestion-tool-does-not-trigger-cursor-hooks/152230)
+> where the `AskQuestion` tool fires **zero** hooks. So a Cursor question is
+> indistinguishable from a completion at the only signal we get (the `stop`
+> hook), and you'll receive `finished` until Cursor ships their fix. We install
+> the `postToolUse(AskQuestion)` hook **now** so that the moment Cursor fixes
+> the bug, question detection **auto-activates with no new install** for everyone
+> already running `@trygocode/notify@latest`. Run `gocode-notify setup --force`
+> once to wire it in.
+
 > **OpenCode's hook (A)** is a small `session.idle` plugin written to
 > `~/.config/opencode/plugin/gocode-notify.js`; on each `session.idle` event it
 > fire-and-forgets `gocode-notify on-stop --source opencode` (the same
@@ -507,6 +529,33 @@ npm publish, real-device E2E), see
 
 ## Changelog
 
+### 0.5.0
+
+- **Question detection across ALL IDEs — "Agent needs you" vs "finished".** When
+  the agent **pauses to ask you a question**, you now get an `awaiting_input`
+  ("Agent needs you") notification instead of a misleading `finished`, on every
+  supported runtime that exposes a question signal:
+  - **Claude Code** — already wired (`Notification` hook); unchanged.
+  - **OpenCode** — NEW: the plugin now listens to `permission.asked` (the moment
+    the agent raises a request) and fires `awaiting_input`. OpenCode genuinely
+    exposes a "the agent needs the user" signal via permission events. (We listen
+    to `permission.asked` only, not `permission.updated`/`replied`, which also
+    fire after the user answers.)
+  - **Cursor** — NEW (dormant): installs a `postToolUse` hook scoped to the
+    `AskQuestion` / `AskUserQuestion` tool. Cursor has a
+    [confirmed-open bug](https://forum.cursor.com/t/askquestion-tool-does-not-trigger-cursor-hooks/152230)
+    where that tool fires zero hooks, and Cursor exposes no `Notification` event,
+    so the hook is dormant today — but it **auto-activates with no new install**
+    the moment Cursor ships their fix. Until then, Cursor keeps its `finished`
+    fallback.
+- **Corrected the documented Cursor `aborted` mapping.** The README table
+  previously (incorrectly) showed `aborted → awaiting_input`; the actual
+  behaviour (since the 0.4.0 fix) is that a manual **Stop** press (`aborted`)
+  sends **no notification at all**. A user force-stop is now clearly
+  distinguished from a genuine IDE question.
+- Run `gocode-notify setup --force` once to wire the new hooks into Cursor +
+  OpenCode.
+
 ### 0.4.0
 
 - **New: branded desktop notifications (on by default).** Every event that pings

package/dist/src/cursor.js

@@ -2,11 +2,15 @@
 // Cursor. It does three things, all idempotently and without clobbering the
 // user's existing config:
 //
-//   1. MERGE a fire-and-forget `stop` hook into `~/.cursor/hooks.json`:
-//        stop → "finished" (the agent completed a turn).
-//      The command shells out to `gocode-notify send … || true` so a failed push
+//   1. MERGE two fire-and-forget hooks into `~/.cursor/hooks.json`:
+//        stop                       → "finished"       (the agent completed a turn)
+//        postToolUse(AskQuestion)   → "awaiting_input" (the agent asked a question)
+//      The commands shell out to `gocode-notify … || true` so a failed push
 //      NEVER blocks the agent's turn (PRD §4.4, §5.4). The file's `version` is
-//      preserved (or set to 1 when creating it fresh).
+//      preserved (or set to 1 when creating it fresh). The postToolUse question
+//      hook is DORMANT until Cursor fixes their AskQuestion tool-hook-skip bug
+//      (forum 152230/161836) — installing it now means it auto-activates with no
+//      new install once upstream lands. See CURSOR_ASK_QUESTION_COMMAND.
 //   2. MERGE an `mcpServers` entry into `~/.cursor/mcp.json` pointing at
 //      `npx -y @trygocode/notify mcp`.
 //   3. WRITE the on-demand rule to `~/.cursor/rules/gocode-notify.md` (the
@@ -57,6 +61,48 @@ export const MCP_SERVER_ENTRY = {
 // version on every turn, so users self-update seamlessly. (Matchers below key on
 // the `@trygocode/notify` substring, which `@latest` preserves.)
 export const CURSOR_STOP_COMMAND = "npx -y @trygocode/notify@latest on-stop --source cursor --dedupe-key cursor-stop || true";
+/**
+ * The Cursor `postToolUse` question hook (T-CUR3) — the ONLY available signal for
+ * "the Cursor agent asked the user a question and is now waiting." It fires a
+ * plain `awaiting_input` ping ("Agent needs you"), the SAME kind Claude Code's
+ * dedicated `Notification` hook fires, so a real question surfaces as a QUESTION
+ * notification on the phone/desktop instead of a misleading `finished`.
+ *
+ * ⚠️ DORMANT-BY-NECESSITY (2026-06-18): Cursor has a CONFIRMED-OPEN upstream bug
+ * where the `AskQuestion` / `AskUserQuestion` tool fires ZERO hooks — `preToolUse`
+ * and `postToolUse` are documented to fire "for all tools" but are skipped for
+ * this one tool specifically (Cursor staff confirmed, no workaround; forum
+ * threads 152230 + 161836). So today this hook will simply never fire, and the
+ * `stop`-hook `finished` fallback remains the user's notification. The moment
+ * Cursor ships their fix this hook AUTO-ACTIVATES with NO new install — every
+ * user already running `@trygocode/notify@latest` gets correct question
+ * detection for free. We install it now so we're ahead of the fix.
+ *
+ * Cursor question detection has no other path: Cursor exposes NO `Notification`
+ * event (docs: `Notification | - | No`), and the `stop` hook's
+ * `status: completed|aborted|error` cannot distinguish "asked a question" from
+ * "finished the work." This dormant tool hook is the best available approximation
+ * and becomes a real signal once upstream lands.
+ *
+ * Ends in `|| true` so a failed push NEVER blocks the turn; carries a distinct
+ * `--dedupe-key` so it coalesces with itself but not with the `stop` ping.
+ */
+export const CURSOR_ASK_QUESTION_COMMAND = 'npx -y @trygocode/notify@latest send --kind awaiting_input --source cursor --title "Agent needs you" --dedupe-key cursor-ask-question || true';
+/**
+ * Tool names that mean "the agent is asking the user a question." Used as the
+ * `postToolUse` matcher (a regex alternation). Cursor maps Claude Code tool
+ * names to Cursor names, and the question tool has shipped under several names
+ * across versions/runtimes (`AskQuestion` in the IDE, `AskUserQuestion` in some
+ * builds, `ask_question` in the CLI). We match ALL of them so the hook works the
+ * instant Cursor wires any of them to `postToolUse`.
+ */
+export const CURSOR_ASK_QUESTION_TOOLS = [
+    "AskQuestion",
+    "AskUserQuestion",
+    "ask_question",
+];
+/** The `matcher` regex string written into the `postToolUse` entry. */
+export const CURSOR_ASK_QUESTION_MATCHER = `^(${CURSOR_ASK_QUESTION_TOOLS.join("|")})$`;
 /**
  * Substrings that together identify a `stop` hook entry as OURS. Used for
  * idempotent merge (replace, don't duplicate) and for surgical uninstall (remove
@@ -143,12 +189,34 @@ async function writeJsonFile(file, value) {
     await fs.mkdir(path.dirname(file), { recursive: true });
     await fs.writeFile(file, JSON.stringify(value, null, 2) + "\n");
 }
+/** True when a command string is one of ours (BOTH a name token AND the source). */
+function isOurCommand(cmd) {
+    return cmd.includes(HOOK_SOURCE_TOKEN) && HOOK_NAME_TOKENS.some((t) => cmd.includes(t));
+}
 /** True when a single `stop` hook entry (`{ command }`) is one we wrote. */
 function isOurStopHook(h) {
     if (!isRecord(h) || typeof h.command !== "string")
         return false;
-    const cmd = h.command;
-    return cmd.includes(HOOK_SOURCE_TOKEN) && HOOK_NAME_TOKENS.some((t) => cmd.includes(t));
+    return isOurCommand(h.command);
+}
+/**
+ * True when a `postToolUse` group (`{ matcher?, hooks: [{ command }] }`) is one
+ * we wrote — its `hooks` array contains a command carrying OUR markers. Cursor's
+ * tool-hook shape nests commands one level deeper than the flat `stop` array, so
+ * we look inside `hooks[].command`.
+ */
+function isOurToolHookGroup(g) {
+    if (!isRecord(g) || !Array.isArray(g.hooks))
+        return false;
+    return g.hooks.some((h) => isRecord(h) && typeof h.command === "string" && isOurCommand(h.command));
+}
+/**
+ * Strip OUR groups out of a `postToolUse` array. Returns the cleaned array plus
+ * whether anything of ours was removed. Never mutates the input.
+ */
+function stripOurToolHooks(entries) {
+    const kept = entries.filter((g) => !isOurToolHookGroup(g));
+    return { entries: kept, removed: kept.length !== entries.length };
 }
 /**
  * Strip OUR entries out of the `stop` array. Returns the cleaned array plus
@@ -175,6 +243,30 @@ function mergeStopHook(config) {
     hooks.stop = preserved;
     config.hooks = hooks;
 }
+/**
+ * Merge our `postToolUse` AskQuestion hook into the hooks config (T-CUR3),
+ * preserving the user's own `postToolUse` groups. Strips any prior copy of OUR
+ * group (idempotent / version-safe) then appends a single fresh group scoped to
+ * the question tools via {@link CURSOR_ASK_QUESTION_MATCHER}. Mutates `config` in
+ * place. Cursor's tool-hook shape is `{ matcher, hooks: [{ type, command }] }`.
+ *
+ * This hook is dormant until Cursor fixes the AskQuestion tool-hook-skip bug (see
+ * {@link CURSOR_ASK_QUESTION_COMMAND}) — installing it now means it auto-activates
+ * with no new install once upstream lands.
+ */
+function mergeAskQuestionHook(config) {
+    if (typeof config.version !== "number")
+        config.version = 1;
+    const hooks = isRecord(config.hooks) ? config.hooks : {};
+    const existing = Array.isArray(hooks.postToolUse) ? hooks.postToolUse : [];
+    const preserved = stripOurToolHooks(existing).entries;
+    preserved.push({
+        matcher: CURSOR_ASK_QUESTION_MATCHER,
+        hooks: [{ type: "command", command: CURSOR_ASK_QUESTION_COMMAND }],
+    });
+    hooks.postToolUse = preserved;
+    config.hooks = hooks;
+}
 /** Merge our MCP server entry into `mcp.mcpServers`. Mutates in place. */
 function mergeMcp(mcp) {
     const servers = isRecord(mcp.mcpServers) ? mcp.mcpServers : {};
@@ -197,6 +289,7 @@ export async function writeCursorConfig(runtime, opts) {
         const hooksPath = cursorHooksPath(opts);
         const hooksConfig = (await readJsonObject(hooksPath)) ?? {};
         mergeStopHook(hooksConfig);
+        mergeAskQuestionHook(hooksConfig);
         await writeJsonFile(hooksPath, hooksConfig);
         written.push(hooksPath);
         const mcpPath = cursorMcpPath(opts);
@@ -212,7 +305,10 @@ export async function writeCursorConfig(runtime, opts) {
             runtime: name,
             written,
             skipped: false,
-            detail: "merged stop hook + MCP entry; wrote rule",
+            detail: "merged stop + postToolUse(AskQuestion) hooks + MCP entry; wrote rule. " +
+                "NOTE: the AskQuestion question hook is DORMANT — Cursor currently fires no " +
+                "hooks for the AskQuestion tool (upstream bug), so question notifications " +
+                "fall back to 'finished' until Cursor ships their fix (auto-activates then).",
         };
     }
     catch (err) {
@@ -250,6 +346,16 @@ export async function uninstallCursorConfig(opts) {
                         delete hooks.stop;
                 }
             }
+            if (Array.isArray(hooks.postToolUse)) {
+                const { entries: kept, removed: r } = stripOurToolHooks(hooks.postToolUse);
+                if (r) {
+                    changed = true;
+                    if (kept.length > 0)
+                        hooks.postToolUse = kept;
+                    else
+                        delete hooks.postToolUse;
+                }
+            }
             if (Object.keys(hooks).length === 0)
                 delete hooksConfig.hooks;
             if (changed) {

package/dist/src/opencode.js

@@ -8,14 +8,20 @@
 //                           "command": ["npx","-y","@trygocode/notify","mcp"],
 //                           "enabled": true }
 //      `command` is a single ARRAY (binary + args), plus `type` + `enabled`.
-//   2. WRITE a `session.idle` plugin to `<config-dir>/plugin/gocode-notify.js`.
-//      OpenCode has NO stop-hook command array; instead a plugin subscribes to
-//      the `session.idle` event (the OpenCode equivalent of Cursor `stop` /
-//      Claude `Stop`) and fires the SHARED `on-stop` dispatcher:
-//        gocode-notify on-stop --source opencode --dedupe-key opencode-idle || true
-//      The child is detached + unref'd and errors are swallowed (`|| true`), so a
-//      notification/push failure can never block the session — exactly one ping
-//      per idle, in lockstep with Claude/Cursor (same `on-stop` dispatcher).
+//   2. WRITE an event plugin to `<config-dir>/plugin/gocode-notify.js` that
+//      subscribes to TWO event classes:
+//        a) END-OF-TURN — `session.idle` (legacy) + `session.status` (modern),
+//           the OpenCode equivalent of Cursor `stop` / Claude `Stop`. Fires the
+//           SHARED `on-stop` dispatcher → a `finished` ping.
+//        b) QUESTION — `permission.asked` (the "asking now" edge), the OpenCode
+//           equivalent of Claude's `Notification` hook. Fires a plain
+//           `awaiting_input` ping ("Agent needs you") so a real question shows as
+//           a QUESTION, not a misleading `finished`. (Cursor has NO such event;
+//           OpenCode genuinely exposes it via permission events. We do NOT listen
+//           to permission.updated/replied — those also fire after the user
+//           answers and would re-ping a resolved question.)
+//      Each child is detached + unref'd and errors are swallowed (`|| true`), so a
+//      notification/push failure can never block the session.
 //
 // The on-demand rule/skill (Claude SKILL.md / Cursor rule) is SKIPPED for
 // OpenCode: OpenCode has no auto-loaded standalone per-file rule mechanism (the
@@ -72,6 +78,21 @@ export const OPENCODE_MCP_ENTRY = {
 // resolved version forever and never auto-updates (npm/cli#6664). Pinning
 // `@latest` makes the hook always fetch the newest publish so users self-update.
 export const OPENCODE_STOP_COMMAND = "npx -y @trygocode/notify@latest on-stop --source opencode --dedupe-key opencode-idle || true";
+/**
+ * The shell command the plugin fires when OpenCode raises a PERMISSION request —
+ * the OpenCode equivalent of "the agent needs the user" (Claude's `Notification`
+ * hook / the Cursor AskQuestion hook). Unlike Cursor, OpenCode genuinely exposes
+ * this signal: the `permission.asked` event fires the instant the agent pauses to
+ * ask the user to approve/answer something. We map it to a plain `awaiting_input`
+ * ping ("Agent needs you") — the SAME kind Claude Code fires — so a real question
+ * surfaces as a QUESTION notification, not a misleading `finished`. (We listen to
+ * `permission.asked` ONLY, never `permission.updated`/`permission.replied`, which
+ * also fire AFTER the user answers and would re-ping a resolved question.)
+ *
+ * Ends in `|| true` so a failed push can never block the session; carries a
+ * distinct `--dedupe-key` so it coalesces with itself but not with the idle ping.
+ */
+export const OPENCODE_ASK_COMMAND = 'npx -y @trygocode/notify@latest send --kind awaiting_input --source opencode --title "Agent needs you" --dedupe-key opencode-permission || true';
 /**
  * Substrings that together identify our plugin file as OURS. Used to keep
  * uninstall surgical: we only delete the plugin file when BOTH markers are
@@ -157,13 +178,15 @@ 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;
+// Separate per-session debounce for permission/question events so a rapid burst
+// of permission.asked events for one prompt coalesces into a single ping, while
+// staying INDEPENDENT of the end-of-turn debounce (a question must not be
+// suppressed by a recent finished ping — different event class).
+const lastAskedAt = new Map();
 
-function fire() {
+function fire(command) {
   try {
-    const child = spawn(
-      ${JSON.stringify(OPENCODE_STOP_COMMAND)},
-      { shell: true, detached: true, stdio: "ignore" },
-    );
+    const child = spawn(command, { shell: true, detached: true, stdio: "ignore" });
     child.unref();
   } catch {
     // never block the session on a notification failure
@@ -195,13 +218,39 @@ function maybeFire(sessionID) {
   const prev = lastFiredAt.get(key) ?? 0;
   if (now - prev < DEDUPE_MS) return; // coalesce idle+status for one turn
   lastFiredAt.set(key, now);
-  fire();
+  fire(${JSON.stringify(OPENCODE_STOP_COMMAND)});
+}
+
+// The agent paused to ask the user (permission.asked). Fire an "Agent needs
+// you" question ping. Debounced separately from the end-of-turn ping so a burst
+// of asks for one prompt coalesces into one.
+function maybeAsk(sessionID) {
+  const key = sessionID || "_";
+  const now = Date.now();
+  const prev = lastAskedAt.get(key) ?? 0;
+  if (now - prev < DEDUPE_MS) return;
+  lastAskedAt.set(key, now);
+  fire(${JSON.stringify(OPENCODE_ASK_COMMAND)});
 }
 
 export const GocodeNotify = async () => ({
   event: async ({ event }) => {
     if (!event) return;
     const props = event.properties ?? {};
+    // QUESTION signal — the agent is waiting on the user (OpenCode's real
+    // "needs you" event; Cursor has no equivalent). Fired BEFORE the idle/status
+    // checks so a permission request is never misread as a plain end-of-turn.
+    //
+    // We listen ONLY to \`permission.asked\` — the moment the agent RAISES a
+    // request. We deliberately do NOT listen to \`permission.updated\` /
+    // \`permission.replied\`: those are state transitions that ALSO fire AFTER the
+    // user answers, which would re-emit "Agent needs you" once the question is
+    // already resolved — exactly the false-notification class this fix exists to
+    // avoid. \`permission.asked\` is the unambiguous "asking now" edge.
+    if (event.type === "permission.asked") {
+      maybeAsk(props.sessionID);
+      return;
+    }
     if (event.type === "session.idle") {
       maybeFire(props.sessionID);
       return;
@@ -332,7 +381,7 @@ export async function writeOpenCodeConfig(runtime, opts) {
             runtime: name,
             written,
             skipped: false,
-            detail: "merged mcp.gocode-notify entry; wrote session.idle plugin (rule skipped — OpenCode has no standalone rule file)",
+            detail: "merged mcp.gocode-notify entry; wrote end-of-turn + permission(question) plugin (rule skipped — OpenCode has no standalone rule file)",
         };
     }
     catch (err) {

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Single source of truth for the CLI version. Keep in sync with package.json.
-export const VERSION = "0.4.0";
+export const VERSION = "0.5.0";

package/package.json

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