@trygocode/notify 0.6.8 → 0.6.9

package/README.md

@@ -530,6 +530,25 @@ npm publish, real-device E2E), see
 
 ## Changelog
 
+### 0.6.9
+
+- **Fixed: native Cursor questions now notify you again.** When the Cursor agent
+  (not Claude-in-Cursor) ends its turn by asking you something ("Want me to
+  deploy this?", "Should I continue?"), you now get an **"Agent needs you"**
+  ping instead of a plain "finished". Cursor's `stop` hook can't tell "asked a
+  question" from "finished" (it always reports `completed`), and its native
+  question hook (`AskQuestion` via `postToolUse`) never fires — an upstream bug.
+  So we now install an `afterAgentResponse` hook that **classifies the turn's
+  final message** and hands a short-lived, conversation-keyed state record to
+  `on-stop`, which stays the single notification owner. Precision-first
+  classifier: fires on real asks (direct openers like "Want me to…" even without
+  a "?", explicit "please confirm/approve" requests) and stays quiet on courtesy
+  sign-offs ("anything else?"), code blocks, and rhetorical headings.
+- **Auto-push + question:** if the turn both changed files (auto-push commits and
+  pushes them) *and* asked a question, **both** the phone push and the desktop
+  banner now read "Agent needs you" with the question snippet — the work is still
+  committed/pushed, you're just told it's waiting on you.
+
 ### 0.6.8
 
 - **Fixed: Claude questions inside Cursor now notify.** When Claude Code runs

package/dist/src/cli.js

@@ -21,6 +21,8 @@ import { setup } from "./setup.js";
 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 { writeTurnState, conversationIdFromHookStdin, } from "./turn_state.js";
 import { notifyDesktop, requestDesktopPermission, desktopDisabledByEnv, } from "./desktop_notify.js";
 import { resolveNotifySettings } from "./config.js";
 import { deriveRepoIdentity } from "./repo_key.js";
@@ -40,6 +42,7 @@ export const COMMANDS = [
     "config",
     "on-stop",
     "on-notification",
+    "on-agent-response",
     "launch",
 ];
 /** Aliases that route to a canonical command in {@link runAsync}. */
@@ -104,6 +107,7 @@ export function printHelp() {
         "  config     Get/set Notify settings (get | set <key> <value> | pull)",
         "  on-stop    End-of-turn dispatcher (auto-push or finished ping)",
         "  on-notification  Needs-input hook dispatcher (embedded-Cursor aware)",
+        "  on-agent-response  Classify a turn's final text (question vs done) for on-stop",
         "  launch     Hand a big task off to your GoCode server (alias: autopilot)",
         "",
         "  -h, --help       Show this help",
@@ -834,6 +838,109 @@ export async function cmdOnNotification(args, deps = {}) {
         forwarded.push("--server", server);
     return (deps.sendCommandImpl ?? cmdSend)(forwarded, deps);
 }
+/**
+ * Extract the agent's final message text from a Cursor `afterAgentResponse` hook
+ * payload. Cursor puts the full assistant message in `text`; we accept a couple
+ * of defensive spellings. Returns "" when absent/unparseable. Never throws.
+ */
+export function extractResponseText(hookStdin) {
+    if (!hookStdin || hookStdin.trim() === "")
+        return "";
+    try {
+        const parsed = JSON.parse(hookStdin);
+        if (!parsed || typeof parsed !== "object")
+            return "";
+        const p = parsed;
+        for (const k of ["text", "response", "message", "content"]) {
+            const v = p[k];
+            if (typeof v === "string" && v.trim() !== "")
+                return v;
+        }
+    }
+    catch {
+        return "";
+    }
+    return "";
+}
+/**
+ * Handle Cursor's `afterAgentResponse` hook. This is the CLASSIFIER half of the
+ * question-notification design (Codex-reviewed 2026-08-31): it does NOT send a
+ * notification. It reads the agent's final `text`, decides whether the turn is a
+ * QUESTION (awaiting user input) or a plain completion, and writes a tiny
+ * per-turn record keyed by `conversation_id`. The `stop` hook — the single
+ * notification owner — then reads that record and sends exactly one notification
+ * of the right kind (`error` > `awaiting_input` > `finished`).
+ *
+ * WHY a state file instead of sending here: `stop` owns settings resolution,
+ * auto-push, abort-suppression, dedupe, deep-linking and the desktop banner.
+ * Sending from here would either duplicate `stop`'s notification or bypass all
+ * that machinery. Classify-and-hand-off keeps ONE notification per turn.
+ *
+ * Non-blocking + total: always exits 0, never throws (a failed classify/write
+ * just means `stop` falls back to its status/transcript heuristics).
+ */
+export async function cmdOnAgentResponse(args, deps = {}) {
+    const flags = parseFlags(args);
+    const agent = isAgentDriven(flags);
+    const quiet = flagBool(flags, "quiet");
+    const sink = deps.sink ?? stdoutSink;
+    try {
+        const hookStdin = deps.hookStdin !== undefined ? deps.hookStdin : await (deps.readStdin ?? readStdinIfPipe)();
+        const conversationId = conversationIdFromHookStdin(hookStdin);
+        // Without a conversation key, `stop` can't correlate — nothing to hand off.
+        if (!conversationId) {
+            if (agent)
+                sink({ step: "on-agent-response", ok: true, detail: "no conversation id — skipped" });
+            else if (!quiet)
+                console.log("✓ on-agent-response: no conversation id — skipped");
+            return 0;
+        }
+        const text = extractResponseText(hookStdin);
+        const verdict = classifyResponse(text);
+        let generationId;
+        try {
+            const p = JSON.parse(hookStdin);
+            const g = p.generation_id ?? p.generationId;
+            if (typeof g === "string" && g.trim() !== "")
+                generationId = g.trim();
+        }
+        catch {
+            /* advisory only */
+        }
+        const record = {
+            conversation_id: conversationId,
+            classification: verdict.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;
+        }
+        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})`
+            : "classified as finished";
+        if (agent)
+            sink({ step: "on-agent-response", ok: true, detail });
+        else if (!quiet)
+            console.log(`✓ on-agent-response: ${detail}`);
+    }
+    catch (err) {
+        // Never block the turn — degrade to a logged no-op.
+        if (agent)
+            sink({
+                step: "on-agent-response",
+                ok: true,
+                detail: `ignored error: ${err instanceof Error ? err.message : String(err)}`,
+            });
+    }
+    return 0;
+}
 /**
  * Handle `gocode-notify launch "<task>" [--repo owner/repo] [--branch suffix]
  * [--prd-file path.md] [--model "Profile"] [--runner-kind K] [--server URL]
@@ -973,6 +1080,8 @@ export async function runAsync(argv) {
         return cmdOnStop(argv.slice(1));
     if (cmd === "on-notification")
         return cmdOnNotification(argv.slice(1));
+    if (cmd === "on-agent-response")
+        return cmdOnAgentResponse(argv.slice(1));
     if (cmd === "launch" || cmd === "autopilot")
         return cmdLaunch(argv.slice(1));
     return run(argv);

package/dist/src/cursor.js

@@ -83,6 +83,28 @@ export const CURSOR_STOP_COMMAND = "npx -y @trygocode/notify@latest on-stop --so
  * `--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 --quiet || true';
+/**
+ * The Cursor `afterAgentResponse` hook command (question detection, 2026-08-31).
+ *
+ * THE REAL FIX for "questions don't notify." Empirically (427k captured Cursor
+ * 3.16.17 hook events), the `AskQuestion` `postToolUse` hook NEVER fires (the
+ * upstream bug is still live) and Cursor has no `Notification` event, so the
+ * `stop` hook alone can't tell "asked a question" from "finished." The
+ * `afterAgentResponse` hook, however, carries the agent's final message `text` —
+ * the ONLY signal that reveals a question.
+ *
+ * This command runs the `on-agent-response` CLASSIFIER: it does NOT send a
+ * notification. It classifies the turn (question vs completion) and writes a tiny
+ * per-turn record keyed by `conversation_id`. The `stop` hook (the single
+ * notification owner) reads that record and sends exactly one notification of the
+ * right kind (`error` > `awaiting_input` > `finished`). Splitting classify from
+ * send keeps ONE notification per turn while preserving all of on-stop's
+ * settings/auto-push/abort/deeplink/desktop machinery.
+ *
+ * Ends in `|| true` so it can never block the turn; `--quiet` so Cursor never
+ * sees non-JSON stdout.
+ */
+export const CURSOR_AGENT_RESPONSE_COMMAND = "npx -y @trygocode/notify@latest on-agent-response --source cursor --quiet || 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
@@ -268,6 +290,40 @@ function mergeAskQuestionHook(config) {
     hooks.postToolUse = preserved;
     config.hooks = hooks;
 }
+/**
+ * True when an `afterAgentResponse` entry is one we wrote. Cursor uses the
+ * direct `{ command }` shape for this event. Identified by our stable command
+ * markers (name token + `--source cursor`), so idempotent merge + surgical
+ * uninstall work across version bumps.
+ */
+function isOurAgentResponseHook(h) {
+    if (!isRecord(h) || typeof h.command !== "string")
+        return false;
+    return isOurCommand(h.command);
+}
+/** Strip OUR entries out of the `afterAgentResponse` array. Never mutates input. */
+function stripOurAgentResponseHooks(entries) {
+    const kept = entries.filter((h) => !isOurAgentResponseHook(h));
+    return { entries: kept, removed: kept.length !== entries.length };
+}
+/**
+ * Merge our `afterAgentResponse` classifier hook (question detection) into the
+ * hooks config, preserving the user's own `afterAgentResponse` entries and
+ * `version`. Strips any prior copy of OUR command (idempotent) then appends a
+ * single fresh entry. Mutates `config` in place.
+ */
+function mergeAgentResponseHook(config) {
+    if (typeof config.version !== "number")
+        config.version = 1;
+    const hooks = isRecord(config.hooks) ? config.hooks : {};
+    const existing = Array.isArray(hooks.afterAgentResponse)
+        ? hooks.afterAgentResponse
+        : [];
+    const preserved = stripOurAgentResponseHooks(existing).entries;
+    preserved.push({ command: CURSOR_AGENT_RESPONSE_COMMAND });
+    hooks.afterAgentResponse = 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 : {};
@@ -291,6 +347,7 @@ export async function writeCursorConfig(runtime, opts) {
         const hooksConfig = (await readJsonObject(hooksPath)) ?? {};
         mergeStopHook(hooksConfig);
         mergeAskQuestionHook(hooksConfig);
+        mergeAgentResponseHook(hooksConfig);
         await writeJsonFile(hooksPath, hooksConfig);
         written.push(hooksPath);
         const mcpPath = cursorMcpPath(opts);
@@ -306,7 +363,7 @@ export async function writeCursorConfig(runtime, opts) {
             runtime: name,
             written,
             skipped: false,
-            detail: "merged current-schema stop + postToolUse(AskQuestion) hooks + MCP entry; wrote rule",
+            detail: "merged current-schema stop + afterAgentResponse(question) + postToolUse(AskQuestion) hooks + MCP entry; wrote rule",
         };
     }
     catch (err) {
@@ -354,6 +411,16 @@ export async function uninstallCursorConfig(opts) {
                         delete hooks.postToolUse;
                 }
             }
+            if (Array.isArray(hooks.afterAgentResponse)) {
+                const { entries: kept, removed: r } = stripOurAgentResponseHooks(hooks.afterAgentResponse);
+                if (r) {
+                    changed = true;
+                    if (kept.length > 0)
+                        hooks.afterAgentResponse = kept;
+                    else
+                        delete hooks.afterAgentResponse;
+                }
+            }
             if (Object.keys(hooks).length === 0)
                 delete hooksConfig.hooks;
             if (changed) {

package/dist/src/on_stop.js

@@ -36,6 +36,8 @@ import { appendLog, send } from "./send.js";
 import { checkDedupLock } from "./dedup_lock.js";
 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";
 /**
  * Parse the Cursor `stop` hook stdin JSON and extract the `status` field.
  * Best-effort: returns `undefined` on absent/empty/unparseable input or when the
@@ -568,6 +570,119 @@ export function autopilotOwnsTurn(env = process.env) {
     const v = raw.trim().toLowerCase();
     return v !== "" && v !== "0" && v !== "false" && v !== "no" && v !== "off";
 }
+/**
+ * Read the last assistant message text from a Cursor transcript JSONL, so the
+ * classifier can run at stop-time when the `afterAgentResponse` turn-state record
+ * is missing (e.g. that hook process failed). Best-effort — returns undefined on
+ * any problem. Never throws. Cursor agent transcripts store role/content records;
+ * we take the LAST assistant/model message's text.
+ */
+export async function lastAssistantTextFromTranscript(hookStdin) {
+    if (!hookStdin || hookStdin.trim() === "")
+        return undefined;
+    let transcriptPath;
+    try {
+        const p = JSON.parse(hookStdin);
+        const v = p.transcript_path ?? p.transcriptPath;
+        if (typeof v === "string" && v.trim() !== "")
+            transcriptPath = v;
+    }
+    catch {
+        return undefined;
+    }
+    if (!transcriptPath)
+        return undefined;
+    let raw;
+    try {
+        raw = await fs.readFile(transcriptPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let lastText;
+    for (const line of raw.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(t);
+        }
+        catch {
+            continue;
+        }
+        const nested = rec.message && typeof rec.message === "object"
+            ? rec.message
+            : undefined;
+        const role = String(rec.role ?? nested?.role ?? rec.type ?? "").toLowerCase();
+        if (role !== "assistant" && role !== "ai" && role !== "model")
+            continue;
+        let content = "";
+        const src = rec.content ?? rec.text ?? nested?.content;
+        if (typeof src === "string")
+            content = src;
+        else if (Array.isArray(src)) {
+            for (const b of src) {
+                if (typeof b === "string")
+                    content += b + "\n";
+                else if (b && typeof b === "object" && typeof b.text === "string")
+                    content += String(b.text) + "\n";
+            }
+        }
+        if (content.trim() !== "")
+            lastText = content; // keep scanning → LAST wins
+    }
+    return lastText;
+}
+/**
+ * Decide whether this stop turn should notify as a QUESTION (`awaiting_input`).
+ *
+ * Primary source: the per-turn record written by the Cursor `afterAgentResponse`
+ * hook (keyed by conversation_id), CONSUMED here so it drives at most one ping.
+ * Fallback: if no fresh record exists, classify the last assistant message from
+ * the transcript named in the hook stdin. Returns `{ awaiting:false }` when there
+ * is no signal (then on-stop sends its normal `finished`). Never throws.
+ *
+ * Only meaningful for Cursor (Claude Code has its own dedicated `Notification`
+ * question hook), so callers gate this on `source === "cursor"`.
+ */
+export async function resolveTurnQuestion(hookStdin, opts = {}) {
+    const convId = conversationIdFromHookStdin(hookStdin);
+    const readImpl = opts.readTurnStateImpl ?? readTurnState;
+    let record;
+    try {
+        record = await readImpl(convId, {
+            home: opts.home,
+            ttlMs: opts.ttlMs,
+            now: opts.now,
+            consume: true,
+        });
+    }
+    catch {
+        record = undefined;
+    }
+    if (record) {
+        if (record.classification === "awaiting_input") {
+            return { awaiting: true, snippet: record.snippet, source: "turn-state" };
+        }
+        return { awaiting: false, source: "turn-state" };
+    }
+    // Fallback: classify the transcript's last assistant message.
+    const readTranscript = opts.readTranscriptText ?? lastAssistantTextFromTranscript;
+    let text;
+    try {
+        text = await readTranscript(hookStdin);
+    }
+    catch {
+        text = undefined;
+    }
+    if (!text)
+        return { awaiting: false, source: "none" };
+    const verdict = classifyResponse(text);
+    return verdict.awaiting
+        ? { awaiting: true, snippet: verdict.snippet, source: "transcript-fallback" }
+        : { awaiting: false, source: "transcript-fallback" };
+}
 /**
  * The end-of-turn dispatcher (PRD §2.2). Resolves settings, then either delegates
  * to the auto-push flow (which sends its own notification) OR fires the plain
@@ -714,6 +829,34 @@ export async function onStop(opts = {}) {
         });
         const settings = resolved.settings;
         const autoPushOn = settings.auto_push?.enabled === true;
+        // ── Question detection, resolved ONCE per turn (Cursor, 2026-08-31). ──
+        // Cursor's `stop` status can't tell "asked a question" from "finished". The
+        // `afterAgentResponse` hook classified the turn and left a per-turn record.
+        // Consume it HERE (once) so BOTH the auto-push path and the plain-send path
+        // share the same verdict — never double-consuming the record. Precedence:
+        // error (status) > awaiting_input (record) > finished. Only for Cursor; an
+        // `error` status skips it (a real error outranks a question). Not consumed in
+        // --dry-run (so a dry run never eats a real turn's record).
+        let turnIsQuestion = false;
+        let turnQuestionSnippet;
+        if (source === "cursor" && earlyHookStatus !== "error" && !opts.dryRun) {
+            const resolveQ = opts.resolveTurnQuestionImpl ?? resolveTurnQuestion;
+            try {
+                const verdict = await resolveQ(opts.hookStdin, {
+                    home: opts.home,
+                    ttlMs: opts.turnStateTtlMs,
+                    now: opts.now,
+                });
+                if (verdict.awaiting) {
+                    turnIsQuestion = true;
+                    turnQuestionSnippet = verdict.snippet;
+                    await logLine(`turn is a QUESTION (${verdict.source})`);
+                }
+            }
+            catch {
+                /* keep normal finished/push behaviour */
+            }
+        }
         // ── Step 3a: auto-push owns the notification for this turn. ──
         if (autoPushOn) {
             const pushImpl = opts.pushImpl ?? pushOnStop;
@@ -724,6 +867,9 @@ export async function onStop(opts = {}) {
                 project: projectLabel(repo, cwd),
                 dedupeKey: opts.dedupeKey,
                 dryRun: opts.dryRun,
+                // When the turn ended in a question, the push still commits the work but
+                // its SUCCESS notification reads as "Agent needs you" (Codex P1).
+                ...(turnIsQuestion ? { questionOverride: { snippet: turnQuestionSnippet } } : {}),
                 server: opts.server,
                 fetchImpl: opts.fetchImpl,
                 timeoutMs: opts.timeoutMs,
@@ -736,10 +882,20 @@ export async function onStop(opts = {}) {
             // in that case send the normal completion/error fallback so enabling
             // auto-push never makes an otherwise valid end-of-turn notification vanish.
             if (push.notified !== true && !opts.dryRun) {
-                const fallbackKind = push.outcome === "commit-failed" || push.outcome === "push-rejected" ||
+                let fallbackKind = push.outcome === "commit-failed" || push.outcome === "push-rejected" ||
                     push.outcome === "conflict-aborted"
                     ? "error"
                     : cursorStopStatusToKind(earlyHookStatus);
+                // Question precedence (error > awaiting_input > finished): if the push
+                // was a benign no-op (clean-tree etc.) AND this Cursor turn was a
+                // question (resolved once above), notify as a question, not a plain
+                // finish. Never overrides an error outcome.
+                let fallbackQuestionSnippet;
+                if (fallbackKind !== "error" && turnIsQuestion) {
+                    fallbackKind = "awaiting_input";
+                    fallbackQuestionSnippet = turnQuestionSnippet;
+                    await logLine(`auto-push no-op + QUESTION → awaiting_input fallback`);
+                }
                 const fallbackPayload = { kind: fallbackKind, source };
                 const fallbackProject = projectLabel(repo, cwd);
                 if (fallbackProject)
@@ -754,7 +910,11 @@ export async function onStop(opts = {}) {
                     fallbackPayload.chat = chatTitle;
                 const fallbackBody = fallbackKind === "error" && push.detail
                     ? push.detail
-                    : undefined;
+                    : fallbackKind === "awaiting_input"
+                        ? fallbackQuestionSnippet
+                        : undefined;
+                if (fallbackKind === "awaiting_input")
+                    fallbackPayload.title = "Agent needs you";
                 if (fallbackBody)
                     fallbackPayload.body = fallbackBody;
                 const desktopBanner = {
@@ -791,11 +951,23 @@ export async function onStop(opts = {}) {
             if (push.notified === true) {
                 const project = projectLabel(repo, cwd);
                 const isError = push.outcome === "conflict-aborted" || push.outcome === "push-rejected";
-                const pushKind = isError ? "error" : "finished";
+                // A question turn that ALSO auto-pushed: the phone push already sent
+                // `awaiting_input` ("Agent needs you") via `questionOverride`, so the
+                // desktop banner must mirror that — NOT say "finished" (Codex P2,
+                // 2026-08-31). Error still outranks a question.
+                const pushKind = isError
+                    ? "error"
+                    : turnIsQuestion
+                        ? "awaiting_input"
+                        : "finished";
                 // Decorate WORD-FOR-WORD like the phone push (PRD §3): the auto-push
                 // path leaves `title` to the server default per kind, and folds the
                 // project into title + body exactly as `dispatcher._decorated_*` does.
-                const rawBody = push.detail || (isError ? "Auto-push needs you" : `Pushed to ${push.branch ?? "branch"}`);
+                const rawBody = isError
+                    ? push.detail || "Auto-push needs you"
+                    : turnIsQuestion
+                        ? turnQuestionSnippet || push.detail || `Pushed to ${push.branch ?? "branch"}`
+                        : push.detail || `Pushed to ${push.branch ?? "branch"}`;
                 desktop = await fireDesktop(settings, {
                     title: decorateTitle({ kind: pushKind, source, project }),
                     body: decorateBody({ kind: pushKind, body: rawBody, project }),
@@ -813,7 +985,16 @@ export async function onStop(opts = {}) {
         //   absent     → finished          (back-compat: no stdin or unrecognised status)
         // Reuse the status already parsed at Step 0.5 (single parse per turn).
         const hookStatus = earlyHookStatus;
-        const sendKind = cursorStopStatusToKind(hookStatus);
+        let sendKind = cursorStopStatusToKind(hookStatus);
+        // Apply the once-per-turn question verdict resolved above (error > question >
+        // finished). `turnIsQuestion` is only ever true for a Cursor, non-error,
+        // non-dry-run turn, so this never mis-classifies a completion or an error.
+        let questionSnippet;
+        if (sendKind !== "error" && turnIsQuestion) {
+            sendKind = "awaiting_input";
+            questionSnippet = turnQuestionSnippet;
+            await logLine(`turn QUESTION → awaiting_input ping`);
+        }
         if (opts.dryRun) {
             await logLine(`dry-run: would send ${sendKind} (auto-push off, source: ${source}, settings: ${resolved.source})`);
             return { mode: "dry-run-send", settingsSource: resolved.source, repo };
@@ -848,6 +1029,13 @@ export async function onStop(opts = {}) {
         const project = projectLabel(repo, cwd);
         if (project)
             payload.project = project;
+        // A question ping gets the "Agent needs you" title + the sanitized question
+        // snippet as its body, so the phone/desktop reads as a QUESTION not a finish.
+        if (sendKind === "awaiting_input") {
+            payload.title = "Agent needs you";
+            if (questionSnippet)
+                payload.body = questionSnippet;
+        }
         if (opts.dedupeKey)
             payload.dedupe_key = opts.dedupeKey;
         // Deep-link target: the synced chat's id (so tapping the push opens the
@@ -872,7 +1060,9 @@ export async function onStop(opts = {}) {
         // ("Agent finished" / …) flows through identically on both surfaces.
         const desktopBanner = {
             title: decorateTitle({ kind: sendKind, source, project }),
-            body: decorateBody({ kind: sendKind, project, chat: chatTitle }),
+            body: sendKind === "awaiting_input"
+                ? decorateBody({ kind: sendKind, body: questionSnippet, project, chat: chatTitle })
+                : decorateBody({ kind: sendKind, project, chat: chatTitle }),
             kind: sendKind,
         };
         const [sent, desktop] = await Promise.all([

package/dist/src/push.js

@@ -287,17 +287,31 @@ export async function pushOnStop(opts = {}) {
                 detail: errorBody,
             };
         }
-        // ── Step 9: success → ONE finished notification carrying the commit summary. ──
+        // ── Step 9: success → ONE notification carrying the commit summary. ──
+        // If this Cursor turn ended in a QUESTION, the notification must read as
+        // "Agent needs you" (awaiting_input) even though we still pushed the work —
+        // the user's next action is answering, not admiring the push (Codex P1,
+        // 2026-08-31). Otherwise it's the normal finished push notification.
         const subject = subjectOf(composed.message);
         const where = sha ? `${branch} @ ${sha}` : branch;
-        const res = await sendImpl({
-            kind: "finished",
-            title: `Auto-pushed to ${branch}`,
-            body: `${subject} — ${where}`,
-            source,
-            project: opts.project,
-            dedupe_key: opts.dedupeKey,
-        });
+        const isQuestion = opts.questionOverride !== undefined;
+        const res = await sendImpl(isQuestion
+            ? {
+                kind: "awaiting_input",
+                title: "Agent needs you",
+                body: opts.questionOverride?.snippet ?? `Pushed to ${where}`,
+                source,
+                project: opts.project,
+                dedupe_key: opts.dedupeKey,
+            }
+            : {
+                kind: "finished",
+                title: `Auto-pushed to ${branch}`,
+                body: `${subject} — ${where}`,
+                source,
+                project: opts.project,
+                dedupe_key: opts.dedupeKey,
+            });
         await logLine(`pushed ${files.length} file(s) to ${remote} ${where} (${composed.generator})`);
         return {
             outcome: "pushed",

package/dist/src/question_classifier.js

@@ -0,0 +1,225 @@
+// Question / awaiting-input classifier for an agent's final response text.
+//
+// WHY THIS EXISTS
+// Cursor gives us NO clean boolean for "the agent asked the user a question and
+// is now waiting." Empirically (427k captured Cursor 3.16.17 hook events, 2026-08):
+//   • The `AskQuestion` tool NEVER fires through `postToolUse` (the documented
+//     upstream bug is still live), so the historical question hook is dead.
+//   • Cursor has no `Notification` event.
+//   • The `stop` hook reports only `status: completed | aborted | error` — a turn
+//     that ENDS by asking a question still reports `completed`, identical to a
+//     turn that finished the work. So on-stop always sent "finished" and every
+//     question looked like a completion (the exact "questions don't notify" bug).
+// The ONLY signal is the CONTENT of the agent's final message, delivered in the
+// `afterAgentResponse` hook's `text` field. This module classifies that text.
+//
+// DESIGN (Codex review 2026-08-31): PRECISION-FIRST. The user strongly prefers
+// NO false/noisy notifications. A false "finished" on a real question is only a
+// missed-question (recoverable — the chat is still there), but a false "Agent
+// needs you" on a plain completion is NOISE the user hates. So we fire
+// awaiting_input ONLY when the FINAL meaningful clause of the message is a
+// direct, actionable question or an explicit blocking request — never because
+// some earlier sentence, a heading, a URL, or a code sample contains a "?".
+//
+// Zero runtime deps — pure string logic, no I/O. Fully unit-testable.
+/**
+ * Phrases that, when they OPEN the final clause, mark it as a direct ask to
+ * proceed — even if punctuation is loose. Matched case-insensitively at the
+ * START of the final clause (after trimming list bullets / emphasis). These are
+ * the real "want me to do X?" asks the user cares about.
+ */
+const DIRECT_QUESTION_OPENERS = [
+    "want me to",
+    "would you like",
+    "do you want",
+    "should i",
+    "shall i",
+    "do you want me to",
+    "would you prefer",
+    "which would you",
+    "which do you",
+    "how would you like",
+    "what would you like",
+    "can you confirm",
+    "could you confirm",
+    "are you ok with",
+    "is it ok if",
+    "is that ok",
+    "does that work",
+    "does this look",
+    "did you want",
+];
+/**
+ * Explicit blocking requests that mean "I will not proceed until you respond,"
+ * even when they do NOT end in a question mark. Matched anywhere in the final
+ * clause (case-insensitive). Kept tight to avoid false positives.
+ */
+const EXPLICIT_CONFIRMATION_PATTERNS = [
+    /\bplease\s+confirm\b/i,
+    /\bplease\s+(let me know|advise|choose|pick|select|decide)\b/i,
+    /\bi\s+need\s+your\s+(approval|confirmation|input|decision|sign-?off)\b/i,
+    /\b(need|awaiting|waiting on|waiting for)\s+your\s+(approval|confirmation|input|decision|go-?ahead|sign-?off)\b/i,
+    /\bchoose\s+(one|an option|between)\b/i,
+    /\breply\s+with\b/i,
+    /\blet me know (which|whether|if you'?d like|if you want)\b/i,
+    /\bconfirm\s+(before|and i'?ll|and then)\b/i,
+];
+/**
+ * Generic courtesy / sign-off lines that END in a question mark or look like an
+ * ask but are NOT a real blocking question — the agent is done and merely being
+ * polite. These must NEVER fire an awaiting_input ping (user hates the noise).
+ */
+const COURTESY_NONQUESTIONS = [
+    /^let me know if (you|there)/i,
+    /^let me know if you (need|want|have)/i,
+    /^(is there )?anything else/i,
+    /^happy to (help|assist|dig|explain)/i,
+    /^feel free to/i,
+    /^hope (this|that) helps/i,
+    // "…anything else?" family — a polite sign-off, NOT a blocking question, no
+    // matter which opener precedes it (Would you like / Do you need / Can I help /
+    // Is there / Want me to help with … anything else?).
+    /\banything else\b[^?]*\??$/i,
+    /^(do you|would you like|can i|shall i|should i)\b[^?]*\bhelp\b[^?]*\?$/i,
+    /^(let me know|just say the word|say the word)\b/i,
+];
+/**
+ * Strip fenced code blocks, inline code, block quotes, markdown headings, URLs,
+ * and horizontal rules from `text` so the classifier reasons about PROSE only.
+ * A "?" inside a code sample, a URL query string, or a rhetorical `## Heading?`
+ * must not be mistaken for the agent asking the user something.
+ */
+export function stripNonProse(text) {
+    let t = text;
+    // Fenced code blocks ``` ... ``` (including language tag). Non-greedy, multi-line.
+    t = t.replace(/```[\s\S]*?```/g, " ");
+    // Indented/tilde fences ~~~ ... ~~~.
+    t = t.replace(/~~~[\s\S]*?~~~/g, " ");
+    // Inline code `...`.
+    t = t.replace(/`[^`]*`/g, " ");
+    // URLs (http/https) — a trailing ? in a query string is not a question.
+    t = t.replace(/https?:\/\/\S+/gi, " ");
+    // Markdown link/image targets (…)(url) — drop the parenthesised target.
+    t = t.replace(/\]\([^)]*\)/g, "] ");
+    // Horizontal rules.
+    t = t.replace(/^\s*([-*_])\1{2,}\s*$/gm, " ");
+    return t;
+}
+/**
+ * Extract the FINAL meaningful prose clause of a response — the sentence or list
+ * item the agent ends on. This is what determines whether the turn is a question:
+ * the agent's PARTING line. We:
+ *   1. strip non-prose (code/URLs/quotes/headings),
+ *   2. drop blank lines and pure markdown-heading lines,
+ *   3. take the last non-empty line,
+ *   4. from that line, take the last sentence (split on . ! ? but keep a trailing ?).
+ * Returns "" when there is no prose to reason about.
+ */
+export function finalClause(text) {
+    const prose = stripNonProse(text);
+    const lines = prose
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        // drop bullets/numbering + emphasis so an opener like "- **Want me to…**" matches
+        .map((l) => l.replace(/^[-*+]\s+/, "").replace(/^\d+[.)]\s+/, ""))
+        .filter((l) => l !== "")
+        // drop pure heading lines (## ...) and blockquote markers (> ...)
+        .filter((l) => !/^#{1,6}\s/.test(l) && !/^>\s?/.test(l));
+    if (lines.length === 0)
+        return "";
+    const lastLine = lines[lines.length - 1].replace(/[*_`]+/g, "").trim();
+    if (lastLine === "")
+        return "";
+    // Take the last sentence of the last line. Split on sentence terminators but
+    // preserve the terminator context so "…done. Want me to X?" → "Want me to X?".
+    const parts = lastLine.split(/(?<=[.!?])\s+/);
+    const last = parts[parts.length - 1]?.trim() ?? lastLine;
+    return last;
+}
+/** Lowercased, punctuation-tolerant prefix test for the direct-question openers. */
+function startsWithDirectOpener(clause) {
+    const c = clause.toLowerCase().replace(/^[^a-z]+/, ""); // drop leading emoji/space
+    return DIRECT_QUESTION_OPENERS.some((opener) => c.startsWith(opener));
+}
+/** True when the clause is a generic courtesy sign-off we must NOT ping for. */
+function isCourtesyNonQuestion(clause) {
+    return COURTESY_NONQUESTIONS.some((re) => re.test(clause.trim()));
+}
+/**
+ * Build a short, SAFE notification snippet from the question clause: collapse
+ * whitespace, strip anything that looks like a filesystem path or secret-ish
+ * token, and cap length so a phone lock-screen never leaks repo internals or
+ * overflows. Returns undefined when nothing sensible remains.
+ */
+export function questionSnippet(clause, maxLen = 160) {
+    let s = clause.replace(/\s+/g, " ").trim();
+    if (s === "")
+        return undefined;
+    // Redact absolute-ish paths (…/a/b/c) and long hex/token blobs from the body.
+    s = s.replace(/(?:\/[\w.-]+){2,}\/?/g, "…").replace(/\b[0-9a-f]{16,}\b/gi, "…");
+    s = s.replace(/\s+/g, " ").trim();
+    if (s === "")
+        return undefined;
+    if (s.length > maxLen)
+        s = s.slice(0, maxLen - 1).trimEnd() + "…";
+    return s;
+}
+/**
+ * Classify an agent's final response `text` as awaiting-input (a question the
+ * user must answer) or not. Precision-first: fires ONLY on a terminal direct
+ * question or an explicit blocking request. Never throws.
+ *
+ * Rules (in order):
+ *   1. Empty / non-prose-only text → NOT awaiting.
+ *   2. Final clause is a generic courtesy sign-off → NOT awaiting (even if it
+ *      ends in "?", e.g. "Anything else you need?").
+ *   3. Final clause opens with a direct-question opener ("Want me to…", "Should
+ *      I…") — even without a "?" (loose punctuation) — OR ends in "?" while being
+ *      interrogative → awaiting (direct question).
+ *   4. Final clause matches an explicit confirmation/approval request → awaiting.
+ *   5. Otherwise → NOT awaiting.
+ */
+export function classifyResponse(text) {
+    if (!text || text.trim() === "")
+        return { awaiting: false };
+    const clause = finalClause(text);
+    if (clause === "")
+        return { awaiting: false };
+    // (2) Generic courtesy sign-off — never a blocking question.
+    if (isCourtesyNonQuestion(clause))
+        return { awaiting: false };
+    const endsWithQuestionMark = /\?\s*$/.test(clause);
+    const opensDirect = startsWithDirectOpener(clause);
+    // (3) Direct question: a recognised opener ("Want me to…", "Should I…") is a
+    //     real ask-to-proceed EVEN IF the model dropped the "?" (punctuation is
+    //     loose). We still exclude the courtesy "…anything else" family (handled
+    //     at step 2 above), so this only fires on a genuine actionable opener.
+    if (opensDirect) {
+        return {
+            awaiting: true,
+            reason: "terminal_direct_question",
+            snippet: questionSnippet(clause),
+        };
+    }
+    if (endsWithQuestionMark) {
+        const c = clause.toLowerCase().replace(/^[^a-z]+/, "");
+        const interrogativeLead = /^(do|does|did|are|is|was|were|can|could|will|would|should|shall|have|has|which|what|when|where|who|why|how)\b/.test(c) || opensDirect;
+        if (interrogativeLead) {
+            return {
+                awaiting: true,
+                reason: "terminal_direct_question",
+                snippet: questionSnippet(clause),
+            };
+        }
+    }
+    // (4) Explicit blocking confirmation/approval request (may lack a "?").
+    if (EXPLICIT_CONFIRMATION_PATTERNS.some((re) => re.test(clause))) {
+        return {
+            awaiting: true,
+            reason: "explicit_confirmation_request",
+            snippet: questionSnippet(clause),
+        };
+    }
+    // (5) Not a question we should ping for.
+    return { awaiting: false };
+}

package/dist/src/turn_state.js

@@ -0,0 +1,222 @@
+// Per-turn state hand-off between the Cursor `afterAgentResponse` hook and the
+// `stop` hook (Codex-reviewed design, 2026-08-31).
+//
+// THE PROBLEM
+// Cursor fires TWO hooks at the end of a turn: `afterAgentResponse` (carries the
+// agent's final message `text`) and `stop` (carries only status, no text). Only
+// `afterAgentResponse` can tell us whether the turn ended by ASKING A QUESTION,
+// but `stop` is the single notification owner (it resolves settings, runs
+// auto-push, handles abort/dedupe/deep-link/desktop). So `afterAgentResponse`
+// must CLASSIFY the turn and hand the verdict to `stop`, which then sends
+// exactly ONE notification of the right kind (error > awaiting_input > finished).
+//
+// THE MECHANISM
+// `afterAgentResponse` writes a tiny per-turn record keyed by conversation_id.
+// `stop` reads the FRESH record for that conversation, decides the kind, then
+// CONSUMES (deletes) it. A record is written for EVERY response (question or
+// completion) so a stale question record is always overwritten by the next turn.
+//
+// SAFETY (guardrail: never block the turn, never throw):
+//   • atomic write via temp-file + rename (never a half-written record read by
+//     a racing `stop`);
+//   • dir 0700, file 0600;
+//   • short freshness window (default 30s) — a record older than that is ignored
+//     and cleaned up, so a question record left behind when `stop` never fires
+//     can never mis-fire a future turn;
+//   • primarily keyed by conversation_id (NOT exact generation identity) because
+//     `stop`'s payload may not echo the same generation_id; generation_id is
+//     stored as advisory/debug only;
+//   • opportunistic stale-record sweep on every read/write.
+//
+// Zero runtime deps beyond Node built-ins. The fs layer is injectable so this is
+// unit-testable with no real filesystem.
+import { createHash } from "node:crypto";
+import { promises as nodeFs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { gocodeDir } from "./creds.js";
+/** Default freshness window (ms): a record older than this is ignored + swept. */
+export const DEFAULT_TURN_STATE_TTL_MS = 30_000;
+/** Directory holding per-turn records (`~/.gocode/turn-state/`). */
+export function turnStateDir(opts) {
+    return path.join(gocodeDir(opts), "turn-state");
+}
+/**
+ * Absolute path to the record file for `conversationId`. The id is hashed
+ * (sha256 prefix) so the filename is filesystem-safe regardless of the id's
+ * characters. One file per conversation → the latest turn always overwrites the
+ * previous, so a stale question record can never survive into the next turn.
+ */
+export function turnStatePath(conversationId, opts) {
+    const hash = createHash("sha256").update(conversationId).digest("hex").slice(0, 24);
+    return path.join(turnStateDir(opts), `${hash}.json`);
+}
+function realFs() {
+    return {
+        readFile: (f, e) => nodeFs.readFile(f, e),
+        writeFile: (f, d, o) => nodeFs.writeFile(f, d, o),
+        rename: (a, b) => nodeFs.rename(a, b),
+        mkdir: (d, o) => nodeFs.mkdir(d, o),
+        rm: (f, o) => nodeFs.rm(f, o),
+        readdir: (d) => nodeFs.readdir(d),
+        stat: async (f) => {
+            const s = await nodeFs.stat(f);
+            return { mtimeMs: s.mtimeMs };
+        },
+    };
+}
+/**
+ * Sweep records older than the freshness window. Best-effort + total: never
+ * throws. Called opportunistically by read/write so an abandoned record (e.g. a
+ * `stop` that never fired) can't linger and mis-fire a later turn.
+ */
+export async function sweepStaleTurnState(opts = {}) {
+    const fs = opts.fsImpl ?? realFs();
+    const ttl = opts.ttlMs ?? DEFAULT_TURN_STATE_TTL_MS;
+    const now = (opts.now ?? Date.now)();
+    const dir = turnStateDir(opts);
+    let files;
+    try {
+        files = await fs.readdir(dir);
+    }
+    catch {
+        return; // no dir yet → nothing to sweep
+    }
+    await Promise.all(files
+        .filter((f) => f.endsWith(".json"))
+        .map(async (f) => {
+        const full = path.join(dir, f);
+        try {
+            const st = await fs.stat(full);
+            if (now - st.mtimeMs > ttl)
+                await fs.rm(full, { force: true });
+        }
+        catch {
+            // ignore per-file errors — sweeping is best-effort
+        }
+    }));
+}
+/**
+ * Persist the per-turn classification for `conversationId`, atomically. Writes a
+ * temp file then renames it over the target so a racing `stop` read never sees a
+ * half-written record. Best-effort + total: never throws (a failed write just
+ * means `stop` falls back to its transcript/status heuristics).
+ */
+export async function writeTurnState(record, opts = {}) {
+    if (!record.conversation_id || record.conversation_id.trim() === "")
+        return;
+    const fs = opts.fsImpl ?? realFs();
+    const dir = turnStateDir(opts);
+    const target = turnStatePath(record.conversation_id, opts);
+    const tmp = `${target}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+        await fs.writeFile(tmp, JSON.stringify(record), { mode: 0o600 });
+        await fs.rename(tmp, target);
+    }
+    catch {
+        // Best-effort: try to clean up the temp file, then give up silently.
+        try {
+            await fs.rm(tmp, { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    // Opportunistic sweep so abandoned records never accumulate.
+    await sweepStaleTurnState(opts).catch(() => undefined);
+}
+/**
+ * Read (and by default CONSUME) the fresh per-turn record for `conversationId`.
+ * Returns undefined when there is no record, it is stale (> ttl), or it is
+ * unreadable/corrupt — in every such case `stop` falls back to its normal
+ * status/transcript heuristics. Never throws.
+ *
+ * `consume` (default true): delete the record after a successful read so it can
+ * only drive ONE notification. Pass false for a non-destructive peek (tests).
+ */
+export async function readTurnState(conversationId, opts = {}) {
+    if (!conversationId || conversationId.trim() === "")
+        return undefined;
+    const fs = opts.fsImpl ?? realFs();
+    const ttl = opts.ttlMs ?? DEFAULT_TURN_STATE_TTL_MS;
+    const now = (opts.now ?? Date.now)();
+    const file = turnStatePath(conversationId, opts);
+    let raw;
+    try {
+        raw = await fs.readFile(file, "utf8");
+    }
+    catch {
+        return undefined; // ENOENT (common) or unreadable → no record
+    }
+    let rec;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed.conversation_id === "string" &&
+            (parsed.classification === "awaiting_input" || parsed.classification === "finished") &&
+            typeof parsed.created_at === "number") {
+            rec = parsed;
+        }
+    }
+    catch {
+        rec = undefined; // corrupt → treat as absent
+    }
+    // Delete-after-read (consume) so a record drives at most one notification —
+    // AND so a corrupt/stale record is cleared rather than re-evaluated forever.
+    const shouldConsume = opts.consume !== false;
+    if (shouldConsume) {
+        try {
+            await fs.rm(file, { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    // Freshness gate AFTER consume: a stale record is ignored (and now removed).
+    if (!rec || now - rec.created_at > ttl || now - rec.created_at < -ttl) {
+        await sweepStaleTurnState(opts).catch(() => undefined);
+        return undefined;
+    }
+    return rec;
+}
+/**
+ * Extract the Cursor `conversation_id` (primary key) from a hook stdin payload.
+ * Accepts the documented spellings so both `afterAgentResponse` and `stop`
+ * resolve the SAME key. Falls back to the transcript filename (minus `.jsonl`)
+ * which both hooks carry, so a payload missing `conversation_id` still matches.
+ * Returns undefined when nothing usable is present. Never throws.
+ */
+export function conversationIdFromHookStdin(hookStdin) {
+    if (!hookStdin || hookStdin.trim() === "")
+        return undefined;
+    let p;
+    try {
+        const parsed = JSON.parse(hookStdin);
+        if (!parsed || typeof parsed !== "object")
+            return undefined;
+        p = parsed;
+    }
+    catch {
+        return undefined;
+    }
+    const str = (...vals) => {
+        for (const v of vals)
+            if (typeof v === "string" && v.trim() !== "")
+                return v.trim();
+        return undefined;
+    };
+    const direct = str(p.conversation_id, p.conversationId, p.session_id, p.sessionId);
+    if (direct)
+        return direct;
+    const transcriptPath = str(p.transcript_path, p.transcriptPath);
+    if (transcriptPath) {
+        const base = path.basename(transcriptPath).replace(/\.jsonl$/i, "");
+        return base || undefined;
+    }
+    return undefined;
+}
+/** Home dir helper (kept local so this module has no import cycle). */
+export function homeDir() {
+    return os.homedir();
+}

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

package/package.json

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