@trygocode/notify 0.4.0 → 0.6.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,61 @@ npm publish, real-device E2E), see
 
 ## Changelog
 
+### 0.6.0
+
+- **Real native macOS "Allow Notifications" dialog (signed helper).** GoCode now
+  ships a tiny **Developer-ID-signed** macOS app bundle (`GoCodeNotifier.app`,
+  Team `88DC7KFY7M`) inside the package. On macOS, `gocode-notify permissions`
+  (and the post-`setup` nudge) now pop the **real system Allow/Don't-Allow
+  permission modal** — the thing a plain `npx`/`osascript` helper can't do —
+  instead of only opening System Settings and asking you to hunt for the toggle.
+  Once allowed, desktop banners post as a **first-class, authorized** app
+  (proper attribution + a real click-to-open-your-IDE action).
+  - **How it ships:** the bundle is **pre-signed at build time** by the
+    maintainer (`native/macos/build_and_sign.sh`) and committed to `assets/`, so
+    end-users need **no Xcode, no Developer ID, no compile step** — the one-line
+    install is unchanged. The signature survives the npm pack/extract round-trip.
+  - **Two macOS rules it honors (both required for the dialog to appear):** the
+    helper is copied to a **stable** location (`~/.gocode/desktop/`) — never
+    `/tmp` — and is always launched via **LaunchServices** (`open`), never by
+    exec'ing the inner binary (direct-exec auto-denies and the denial sticks).
+  - **Hot-path stays fast:** fire-and-forget banners read a cached auth status
+    (`~/.gocode/desktop/.auth-status`), so a notification never does a slow live
+    permission round-trip. The signed banner is used only once you've granted;
+    otherwise it transparently falls back to the legacy applet banner.
+  - **Own identity:** the signed helper uses bundle id `com.gocode.notify.helper`
+    (distinct from the legacy applet's `com.gocode.notify.desktop`) so it owns
+    its own row in System Settings → Notifications.
+  - **Linux/Windows unchanged.** This is a macOS-only enhancement; other
+    platforms keep their existing branded-banner paths.
+
+### 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/assets/GoCodeNotifier.app/Contents/Info.plist

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <!-- CFBundleIdentifier MUST stay stable across rebuilds: macOS keys the user's
+       notification-authorization grant off it, so changing it would forget the
+       Allow. This is DISTINCT from the legacy applet's `com.gocode.notify.desktop`
+       on purpose: the signed helper owns its own identity in System Settings →
+       Notifications so a poisoned/denied state on the old shared id can't block
+       the signed app's grant. Mirrors HELPER_BUNDLE_ID in mac_helper.ts. -->
+  <key>CFBundleIdentifier</key>
+  <string>com.gocode.notify.helper</string>
+  <key>CFBundleName</key>
+  <string>GoCode</string>
+  <key>CFBundleDisplayName</key>
+  <string>GoCode</string>
+  <key>CFBundleExecutable</key>
+  <string>GoCodeNotifier</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleShortVersionString</key>
+  <string>1.0.0</string>
+  <key>CFBundleVersion</key>
+  <string>1</string>
+  <!-- LSUIElement: a faceless background helper — no Dock icon, no menu bar. -->
+  <key>LSUIElement</key>
+  <true/>
+  <key>LSMinimumSystemVersion</key>
+  <string>11.0</string>
+  <key>CFBundleIconFile</key>
+  <string>AppIcon</string>
+  <key>NSHumanReadableCopyright</key>
+  <string>© BIGSMS Pty Ltd</string>
+</dict>
+</plist>

package/assets/GoCodeNotifier.app/Contents/_CodeSignature/CodeResources

@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>files</key>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<data>
+		GbhU1RfeSzs8A7x841vrx8S9NpM=
+		</data>
+	</dict>
+	<key>files2</key>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			80/V6KfdsY5g+nVZNtqimRwukW+CXDnk+bV0NlYa75w=
+			</data>
+		</dict>
+	</dict>
+	<key>rules</key>
+	<dict>
+		<key>^Resources/</key>
+		<true/>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^version.plist$</key>
+		<true/>
+	</dict>
+	<key>rules2</key>
+	<dict>
+		<key>.*\.dSYM($|/)</key>
+		<dict>
+			<key>weight</key>
+			<real>11</real>
+		</dict>
+		<key>^(.*/)?\.DS_Store$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>2000</real>
+		</dict>
+		<key>^(Frameworks|SharedFrameworks|PlugIns|Plug-ins|XPCServices|Helpers|MacOS|Library/(Automator|Spotlight|LoginItems))/</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^.*</key>
+		<true/>
+		<key>^Info\.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^PkgInfo$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^[^/]+$</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^embedded\.provisionprofile$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^version\.plist$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+	</dict>
+</dict>
+</plist>

package/dist/src/cli.js

@@ -21,7 +21,7 @@ import { setup } from "./setup.js";
 import { uninstall } from "./uninstall.js";
 import { cmdConfig } from "./config.js";
 import { onStop } from "./on_stop.js";
-import { notifyDesktop } from "./desktop_notify.js";
+import { notifyDesktop, requestDesktopPermission } from "./desktop_notify.js";
 import { gatherDoctor, formatDoctor } from "./doctor.js";
 /** Subcommands the finished CLI will expose (see PRD §4.1). */
 export const COMMANDS = [
@@ -31,6 +31,7 @@ export const COMMANDS = [
     "setup",
     "status",
     "doctor",
+    "permissions",
     "mcp",
     "uninstall",
     "config",
@@ -93,6 +94,7 @@ export function printHelp() {
         "  setup      Pair + detect runtimes + write configs",
         "  status     Report credentials / server / detected runtimes",
         "  doctor     Self-diagnostic checklist with exact fix commands",
+        "  permissions  Request macOS desktop-notification permission (opens Settings)",
         "  mcp        Run as an MCP server over stdio",
         "  uninstall  Remove entries this tool added",
         "  config     Get/set Notify settings (get | set <key> <value> | pull)",
@@ -366,6 +368,48 @@ export async function cmdTest(args, deps = {}) {
         console.error(`gocode-notify test: ${detail}.`);
     return 1;
 }
+/**
+ * Handle `gocode-notify permissions` (alias `perms`). Makes the OS
+ * notification-permission UI appear so the user grants GoCode desktop banners
+ * with a click instead of hunting through Settings.
+ *
+ * On macOS this now pops the REAL native Allow/Deny modal via the Developer-ID-
+ * signed helper bundled in the package (see {@link requestDesktopPermission}); if
+ * the signed helper is unavailable or you previously denied, it falls back to
+ * registering the branded bundle, opening System Settings → Notifications, and
+ * firing a priming banner. Always exits 0 — best-effort convenience, never a gate.
+ */
+export async function cmdPermissions(args, deps = {}) {
+    const flags = parseFlags(args);
+    const agent = isAgentDriven(flags);
+    const sink = deps.sink ?? stdoutSink;
+    const res = await requestDesktopPermission({
+        home: deps.home,
+        timeoutMs: deps.timeoutMs,
+        timestamp: deps.timestamp,
+    });
+    if (agent) {
+        // `ok` reflects whether the NOTIFICATION path actually worked (the priming
+        // banner fired) — NOT merely that we opened Settings. On macOS, opening
+        // Settings is only a partial remediation; reporting ok:true off it alone
+        // would be false-success telemetry for automation consuming the sink.
+        sink({
+            step: "permissions",
+            ok: res.primed,
+            detail: res.message,
+        });
+    }
+    else {
+        console.log(`🔔 ${res.message}`);
+        if (res.platform === "darwin" && !res.primed) {
+            // Only show the Settings-hunt hint when we did NOT manage a real grant
+            // (e.g. previously denied, or the signed helper wasn't available).
+            console.log("   (If no dialog appeared, enable “Allow Notifications” for GoCode in\n" +
+                "    System Settings → Notifications — it’s now one tap away.)");
+        }
+    }
+    return 0;
+}
 /**
  * Handle `gocode-notify status [--server URL]`. Prints a coherent report of
  * credentials / server reachability / detected runtimes (PRD §4.1, §8). Purely
@@ -462,6 +506,28 @@ export async function cmdSetup(args, deps = {}) {
             console.log(`  ${step.ok ? "✓" : "✗"} ${step.step}: ${step.detail}`);
         }
     }
+    // On macOS, proactively trigger the notification-permission flow so the user
+    // doesn't have to hunt for the GoCode toggle: register the branded bundle,
+    // open System Settings → Notifications, and fire a priming banner. Skipped in
+    // agent-driven mode (no human to grant it) and when setup didn't succeed.
+    // Best-effort — never flips the setup exit code (a permission nudge failing
+    // must not make `setup` report failure).
+    if (!agent && result.ok && process.platform === "darwin") {
+        try {
+            const perm = await requestDesktopPermission({
+                home: deps.home,
+                timeoutMs: deps.timeoutMs,
+            });
+            console.log("");
+            console.log(`  🔔 Desktop notifications: ${perm.message}`);
+        }
+        catch (err) {
+            // Never let a permission nudge fail the setup — but DO leave a breadcrumb
+            // so an unexpected throw here isn't completely invisible to the user.
+            console.log("");
+            console.log(`  🔔 Desktop notifications: couldn't run the permission nudge (${err instanceof Error ? err.message : String(err)}). Run \`gocode-notify permissions\` manually.`);
+        }
+    }
     return result.ok ? 0 : 1;
 }
 /**
@@ -689,6 +755,8 @@ export async function runAsync(argv) {
         return cmdStatus(argv.slice(1));
     if (cmd === "doctor")
         return cmdDoctor(argv.slice(1));
+    if (cmd === "permissions" || cmd === "perms")
+        return cmdPermissions(argv.slice(1));
     if (cmd === "setup")
         return cmdSetup(argv.slice(1));
     if (cmd === "mcp")

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) {