@trygocode/notify 0.6.10 → 0.6.12

package/README.md

@@ -530,6 +530,33 @@ npm publish, real-device E2E), see
 
 ## Changelog
 
+### 0.6.12
+
+- **Hardening for the 0.6.11 AskQuestion-tool detection** (Codex-reviewed): the
+  stop-time transcript recheck now only runs when there is no per-turn record
+  (removes a double-notify vector on a repeated stop); tool question snippets are
+  sanitized + length-capped like every other snippet; the bounded transcript
+  tail-reader keeps a complete first line when the read lands exactly on a line
+  boundary; snippet field precedence is `questions[0].question → question →
+  prompt → title → text`; and non-object JSONL records (`null`, scalars, arrays)
+  are skipped instead of dereferenced. Same behaviour as 0.6.11, just safer.
+
+### 0.6.11
+
+- **Fixed: the `AskQuestion` TOOL (the A/B/C options card) now notifies you.**
+  This is the *other* way a Cursor agent asks you something — and it was silently
+  missed. When the agent uses the AskQuestion / AskUserQuestion tool, its final
+  message text is just filler ("I'll ask you a quick question"), so the text
+  classifier can't see the question, and Cursor **never fires `postToolUse` for
+  the AskQuestion tool** (a confirmed upstream Cursor bug). The only reliable
+  signal is the transcript, so `on-agent-response` and `on-stop` now read the
+  tail of the turn's transcript, inspect the **latest assistant message**, and if
+  it invoked an AskQuestion tool they send **"Agent needs you"** with the actual
+  question text. A tool ask is definitive — it overrides the text heuristic and
+  even a stored "finished" — and `on-stop` remains the single sender so there are
+  no duplicate pings. The question text is sanitized/length-capped like every
+  other snippet.
+
 ### 0.6.10
 
 - **Accurate `on-stop` status line.** The CLI now prints the notification kind it

package/dist/src/cli.js

@@ -22,6 +22,7 @@ import { uninstall } from "./uninstall.js";
 import { cmdConfig } from "./config.js";
 import { onStop, parseCursorStopStatus, cursorStopStatusToKind, clickTarget, projectLabel, } from "./on_stop.js";
 import { classifyResponse } from "./question_classifier.js";
+import { detectAskToolFromHookStdin } from "./transcript_ask.js";
 import { writeTurnState, conversationIdFromHookStdin, } from "./turn_state.js";
 import { notifyDesktop, requestDesktopPermission, desktopDisabledByEnv, } from "./desktop_notify.js";
 import { resolveNotifySettings } from "./config.js";
@@ -899,7 +900,26 @@ export async function cmdOnAgentResponse(args, deps = {}) {
             return 0;
         }
         const text = extractResponseText(hookStdin);
-        const verdict = classifyResponse(text);
+        const textVerdict = classifyResponse(text);
+        // The AskQuestion / AskUserQuestion TOOL (the A/B/C options card) leaves the
+        // final `text` as a non-question ("I'll ask you a quick question"), and
+        // Cursor never fires `postToolUse` for it — so the transcript is the only
+        // signal. A tool ask is DEFINITIVE and overrides the text heuristic
+        // (Codex-reviewed 2026-08-31). `unknown` (unreadable transcript) keeps the
+        // text verdict.
+        let askVerdict = { verdict: "unknown" };
+        try {
+            askVerdict = await (deps.detectAskToolImpl ?? detectAskToolFromHookStdin)(hookStdin);
+        }
+        catch {
+            askVerdict = { verdict: "unknown" };
+        }
+        const isAsk = askVerdict.verdict === "ask";
+        const awaiting = isAsk ? true : textVerdict.awaiting;
+        const snippet = isAsk
+            ? askVerdict.snippet ?? textVerdict.snippet ?? "Agent asked you a question"
+            : textVerdict.snippet;
+        const reason = isAsk ? "askquestion_tool" : textVerdict.reason;
         let generationId;
         try {
             const p = JSON.parse(hookStdin);
@@ -912,21 +932,21 @@ export async function cmdOnAgentResponse(args, deps = {}) {
         }
         const record = {
             conversation_id: conversationId,
-            classification: verdict.awaiting ? "awaiting_input" : "finished",
+            classification: awaiting ? "awaiting_input" : "finished",
             created_at: (deps.now ?? Date.now)(),
         };
         if (generationId)
             record.generation_id = generationId;
-        if (verdict.awaiting) {
-            if (verdict.snippet)
-                record.snippet = verdict.snippet;
-            if (verdict.reason)
-                record.reason = verdict.reason;
+        if (awaiting) {
+            if (snippet)
+                record.snippet = snippet;
+            if (reason)
+                record.reason = reason;
         }
         const writeImpl = deps.writeTurnStateImpl ?? writeTurnState;
         await writeImpl(record, { home: deps.home, ttlMs: deps.ttlMs, now: deps.now });
-        const detail = verdict.awaiting
-            ? `classified as awaiting_input (${verdict.reason})`
+        const detail = awaiting
+            ? `classified as awaiting_input (${reason})`
             : "classified as finished";
         if (agent)
             sink({ step: "on-agent-response", ok: true, detail });

package/dist/src/cursor.js

@@ -79,10 +79,15 @@ export const CURSOR_STOP_COMMAND = "npx -y @trygocode/notify@latest on-stop --so
  * "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.
+ * Ends in `|| true` so a failed push NEVER blocks the turn.
+ *
+ * Dedupe key = `cursor-stop` ON PURPOSE (Codex 2026-08-31): stop-time now
+ * detects the AskQuestion TOOL from the transcript and sends its OWN
+ * `awaiting_input` ping (dedupe key `cursor-stop`). If Cursor ever FIXES the
+ * `postToolUse` bug, this hook would fire too — sharing the SAME dedupe key
+ * makes the server coalesce the two into ONE ping instead of double-notifying.
  */
-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 --quiet || true';
+export const CURSOR_ASK_QUESTION_COMMAND = 'npx -y @trygocode/notify@latest send --kind awaiting_input --source cursor --title "Agent needs you" --dedupe-key cursor-stop --quiet || true';
 /**
  * The Cursor `afterAgentResponse` hook command (question detection, 2026-08-31).
  *

package/dist/src/on_stop.js

@@ -38,6 +38,7 @@ import { notifyDesktop, } from "./desktop_notify.js";
 import { decorateTitle, decorateBody } from "./notify_copy.js";
 import { readTurnState, conversationIdFromHookStdin, } from "./turn_state.js";
 import { classifyResponse } from "./question_classifier.js";
+import { detectAskToolFromHookStdin } from "./transcript_ask.js";
 /**
  * Parse the Cursor `stop` hook stdin JSON and extract the `status` field.
  * Best-effort: returns `undefined` on absent/empty/unparseable input or when the
@@ -661,12 +662,36 @@ export async function resolveTurnQuestion(hookStdin, opts = {}) {
     catch {
         record = undefined;
     }
+    // The turn-state record (written by `on-agent-response`) is authoritative when
+    // present — it ALREADY folds in the AskQuestion-tool signal (cli.ts writes
+    // `awaiting_input` with reason `askquestion_tool`). Consuming it exactly once
+    // per turn is what bounds this to a single notification, so when a record
+    // exists we DO NOT re-run the transcript tool check (that redundant recheck was
+    // a double-notify vector on a repeated stop — Codex 2026-08-31).
     if (record) {
         if (record.classification === "awaiting_input") {
             return { awaiting: true, snippet: record.snippet, source: "turn-state" };
         }
         return { awaiting: false, source: "turn-state" };
     }
+    // No record (e.g. `on-agent-response` never ran, or its record expired). The
+    // AskQuestion TOOL (A/B/C card) is still a DEFINITIVE signal Cursor won't
+    // surface any other way, so re-check the transcript's latest assistant turn.
+    // This only runs on the no-record path, so it can't double-fire against the
+    // record above. Best-effort, never throws.
+    try {
+        const ask = await (opts.detectAskToolImpl ?? detectAskToolFromHookStdin)(hookStdin);
+        if (ask.verdict === "ask") {
+            return {
+                awaiting: true,
+                snippet: ask.snippet ?? "Agent asked you a question",
+                source: "askquestion-tool",
+            };
+        }
+    }
+    catch {
+        /* fall through to the text classifier */
+    }
     // Fallback: classify the transcript's last assistant message.
     const readTranscript = opts.readTranscriptText ?? lastAssistantTextFromTranscript;
     let text;

package/dist/src/transcript_ask.js

@@ -0,0 +1,230 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// AskQuestion TOOL detection from the Cursor transcript (2026-08-31).
+//
+// WHY THIS EXISTS. Cursor asks the user in two ways:
+//   (1) free-text in the final message ("Want me to deploy?") — caught by the
+//       text classifier in question_classifier.ts.
+//   (2) the `AskQuestion` / `AskUserQuestion` TOOL — the A/B/C options card. Here
+//       the assistant's final `text` is just a filler line ("I'll ask you a quick
+//       question"), so the text classifier says NOT a question. Worse, Cursor's
+//       `postToolUse` hook NEVER fires for the AskQuestion tool (confirmed
+//       empirically on Cursor 3.16.17 — postToolUse only ever reports
+//       Shell/Grep/Write/MCP), so there is no live hook signal for style (2).
+//
+// THE ONE RELIABLE SIGNAL is the transcript JSONL (its path is in the hook
+// stdin as `transcript_path`). Assistant tool calls are recorded there as
+// `{"type":"tool_use","name":"AskQuestion", ...}` inside the message content.
+//
+// This module reads a BOUNDED tail of that file (a single transcript line can be
+// ~1 MiB, so we cap by bytes, not lines) and inspects ONLY the latest assistant
+// record. If that record contains an AskQuestion/AskUserQuestion tool_use, the
+// turn is DEFINITIVELY a question. We never scan back into a previous turn (an
+// earlier AskQuestion must not re-trigger). Everything is best-effort: any
+// missing / truncated / malformed / oversized transcript returns "unknown" so
+// the caller falls back to the text classifier and the turn is never blocked.
+// ─────────────────────────────────────────────────────────────────────────────
+import fs from "node:fs/promises";
+import { questionSnippet } from "./question_classifier.js";
+/** Tool names that mean "the agent is asking the user to pick / answer". */
+const ASK_TOOL_NAMES = new Set(["askquestion", "askuserquestion", "ask_question"]);
+/** Cap the tail read so one giant transcript line can't blow up memory. */
+export const TRANSCRIPT_TAIL_CAP_BYTES = 8 * 1024 * 1024; // 8 MiB
+/** Pull `transcript_path` out of a hook stdin JSON blob (best-effort). */
+export function transcriptPathFromHookStdin(hookStdin) {
+    if (!hookStdin || hookStdin.trim() === "")
+        return undefined;
+    try {
+        const p = JSON.parse(hookStdin);
+        const v = p.transcript_path ?? p.transcriptPath;
+        if (typeof v === "string" && v.trim() !== "")
+            return v;
+    }
+    catch {
+        /* fall through */
+    }
+    return undefined;
+}
+/**
+ * Read the last `cap` bytes of a file as UTF-8, dropping a leading partial line
+ * (so reverse line-parsing never sees a half-record). Returns undefined on any
+ * IO error. Streams from the END via a positional read — never loads the whole
+ * file, so a multi-MB transcript with a ~1 MiB line stays bounded.
+ */
+export async function readTail(file, cap = TRANSCRIPT_TAIL_CAP_BYTES) {
+    let fh;
+    try {
+        fh = await fs.open(file, "r");
+        const { size } = await fh.stat();
+        const length = Math.min(size, cap);
+        if (length === 0)
+            return "";
+        const start = size - length;
+        // When the cap lands EXACTLY on a line boundary (the byte before `start` is a
+        // newline), the first retained line is COMPLETE and must be kept. Only when
+        // `start` falls mid-line do we drop the partial first line (Codex 2026-08-31).
+        let firstLineIsPartial = start > 0;
+        if (start > 0) {
+            const probe = Buffer.allocUnsafe(1);
+            const { bytesRead: pr } = await fh.read(probe, 0, 1, start - 1);
+            if (pr === 1 && probe[0] === 0x0a /* \n */)
+                firstLineIsPartial = false;
+        }
+        const buf = Buffer.allocUnsafe(length);
+        let offset = 0;
+        while (offset < length) {
+            const { bytesRead } = await fh.read(buf, offset, length - offset, start + offset);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        let tail = buf.subarray(0, offset).toString("utf8");
+        // Drop the (truncated) first line only when `start` fell mid-line.
+        if (firstLineIsPartial) {
+            const nl = tail.indexOf("\n");
+            if (nl < 0)
+                return undefined; // one giant partial line, nothing usable
+            tail = tail.slice(nl + 1);
+        }
+        return tail;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fh) {
+            try {
+                await fh.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}
+/**
+ * Extract a short question snippet from an AskQuestion tool_use `input`.
+ * Cursor shapes vary; try the documented spellings, else undefined.
+ */
+function snippetFromAskInput(input) {
+    if (!input || typeof input !== "object")
+        return undefined;
+    const p = input;
+    // Precedence (Codex 2026-08-31): questions[0].question → top-level question →
+    // prompt → title → text. The nested-array form (AskUserQuestion) wins first,
+    // then the flat top-level spellings in documented order.
+    let raw;
+    const qs = p.questions;
+    if (Array.isArray(qs) && qs.length > 0 && qs[0] && typeof qs[0] === "object") {
+        const q0 = qs[0];
+        for (const k of ["question", "prompt", "title", "text"]) {
+            const v = q0[k];
+            if (typeof v === "string" && v.trim() !== "") {
+                raw = v;
+                break;
+            }
+        }
+    }
+    if (raw === undefined) {
+        for (const k of ["question", "prompt", "title", "text"]) {
+            const v = p[k];
+            if (typeof v === "string" && v.trim() !== "") {
+                raw = v;
+                break;
+            }
+        }
+    }
+    if (raw === undefined)
+        return undefined;
+    // Sanitize + length-cap exactly like the text-classifier snippets (redacts
+    // paths / hex blobs, collapses whitespace, caps at 160 chars) so a huge or
+    // sensitive question can't be sent verbatim in the notification.
+    return questionSnippet(raw);
+}
+/**
+ * Does a message-content value contain an AskQuestion/AskUserQuestion tool_use?
+ * Returns the extracted snippet (possibly undefined) when found, else null.
+ */
+function findAskToolInContent(content) {
+    if (!Array.isArray(content))
+        return null;
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const b = block;
+        // Accept `type: tool_use|tool-call|function` shapes; the NAME is what matters.
+        const name = String(b.name ?? b.toolName ?? b.tool_name ?? "").toLowerCase();
+        if (!name)
+            continue;
+        if (ASK_TOOL_NAMES.has(name)) {
+            const input = b.input ?? b.args ?? b.arguments ?? b.tool_input;
+            return { snippet: snippetFromAskInput(input) };
+        }
+    }
+    return null;
+}
+/** Normalise a transcript record's role (Cursor top-level or Claude nested). */
+function roleOf(rec, nested) {
+    return String(rec.role ?? nested?.role ?? rec.type ?? "").toLowerCase();
+}
+/**
+ * Inspect the LATEST assistant record in the transcript and decide whether it
+ * ended in an AskQuestion tool call. Walks lines in REVERSE:
+ *   • skips blank lines and non-conversational `{type,status}` metadata records;
+ *   • the FIRST assistant record found is "this turn" → inspect it and STOP;
+ *   • if a user/human record is reached before any assistant → `no_ask`
+ *     (the current turn produced no assistant tool call we can see);
+ *   • never continues past the current turn into a prior AskQuestion.
+ * Returns `unknown` only when the transcript can't be read at all.
+ */
+export function detectAskToolInTail(tail) {
+    if (tail === undefined)
+        return { verdict: "unknown" };
+    const lines = tail.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const t = lines[i].trim();
+        if (!t)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(t);
+        }
+        catch {
+            continue; // tolerate a stray non-JSON line
+        }
+        // A valid-JSON but non-object record (e.g. `null`, `42`, `"x"`) is not a
+        // conversational line — skip it instead of dereferencing (would throw).
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            continue;
+        const rec = parsed;
+        const nested = rec.message && typeof rec.message === "object"
+            ? rec.message
+            : undefined;
+        const role = roleOf(rec, nested);
+        if (role === "assistant" || role === "ai" || role === "model") {
+            const content = rec.content ?? nested?.content ?? rec.message;
+            const hit = findAskToolInContent(content);
+            // This IS the latest assistant turn — its verdict is final either way.
+            return hit ? { verdict: "ask", snippet: hit.snippet } : { verdict: "no_ask" };
+        }
+        if (role === "user" || role === "human") {
+            // Reached the user turn before any assistant record → current turn has no
+            // visible assistant tool call. Do NOT look further back.
+            return { verdict: "no_ask" };
+        }
+        // Any other record (tool result, status, meta) → keep scanning backwards.
+    }
+    // No conversational record found in the tail.
+    return { verdict: "unknown" };
+}
+/**
+ * Convenience: read the transcript named in the hook stdin and detect an
+ * AskQuestion tool call in the latest assistant turn. Best-effort; never throws.
+ */
+export async function detectAskToolFromHookStdin(hookStdin, deps = {}) {
+    const p = transcriptPathFromHookStdin(hookStdin);
+    if (!p)
+        return { verdict: "unknown" };
+    const readTailImpl = deps.readTailImpl ?? readTail;
+    const tail = await readTailImpl(p);
+    return detectAskToolInTail(tail);
+}

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.6.10";
+export const VERSION = "0.6.12";

package/package.json

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