feat(hooks): add WSL desktop notification support via PowerShell + BurntToast (#1019)

* fix(hooks): add WSL desktop notification support via PowerShell + BurntToast

Adds WSL (Windows Subsystem for Linux) desktop notification support to the
existing desktop-notify hook. The hook now detects WSL, finds available
PowerShell (7 or Windows PowerShell), checks for BurntToast module, and
sends Windows toast notifications.

New functions:
- isWSL(): detects WSL environment
- findPowerShell(): finds PowerShell 7 or Windows PowerShell on WSL
- isBurntToastAvailable(): checks if BurntToast module is installed
- notifyWindows(): sends Windows toast notification via BurntToast

If BurntToast is not installed, logs helpful tip for installation.
Falls back silently on non-WSL/non-macOS platforms.

* docs(hooks): update desktop-notify description to include WSL

Updates the hook description in hooks.json to reflect the newly
added WSL notification support alongside macOS.

* fix(hooks): capture stderr properly in notifyWindows

Change stdio to ['ignore', 'pipe', 'pipe'] so stderr is captured
and can be logged on errors. Without this, result.stderr is null
and error logs show 'undefined' instead of the actual error.

* fix(hooks): quote PowerShell path in install tip for shell safety

The PowerShell path contains spaces and needs to be quoted
when displayed as a copy-pasteable command.

* fix(hooks): remove external repo URL from tip message

BurntToast module is a well-known Microsoft module but per project
policy avoiding unvetted external links in user-facing output.

* fix(hooks): probe WSL interop PATH before hardcoded paths

Adds 'pwsh.exe' and 'powershell.exe' as candidates to leverage
WSL's Windows interop PATH resolution, making the hook work with
non-default WSL mount prefixes or Windows drives.

* perf(hooks): memoize isWSL detection at module load

Avoids reading /proc/version twice (once in run(), once in findPowerShell())
by computing the result once when the module loads.

* perf(hooks): reduce PowerShell spawns from 3 to 1 per notification

Merge findPowerShell version check and isBurntToastAvailable check
into a single notifyWindows call. Now just tries to send directly;
if it fails, tries next PowerShell path. Version field was unused.

Net effect: up to 3 spawns reduced to 1 in the happy path.

* fix(hooks): remove duplicate notifyWindows declaration

There were two notifyWindows function declarations due to incomplete
refactoring. Keeps only the version that returns true/false for the
call site. Node.js would throw SyntaxError with 'use strict'.

* fix(hooks): improve error handling and detection robustness

- Increase PowerShell detection timeout from 1s to 3s to avoid false
  negatives on slower/cold WSL interop startup
- Return error reason from notifyWindows to distinguish BurntToast
  module not found vs other PowerShell errors
- Log actionable error details instead of always showing install tip

---------

Co-authored-by: boss <boss@example.com>

hooks/hooks.json

@@ -310,7 +310,7 @@
             "timeout": 10
           }
         ],
-        "description": "Send macOS desktop notification with task summary when Claude responds"
+        "description": "Send desktop notification (macOS/WSL) with task summary when Claude responds"
       }
     ],
     "SessionEnd": [

scripts/hooks/desktop-notify.js

@@ -3,9 +3,11 @@
  * Desktop Notification Hook (Stop)
  *
  * Sends a native desktop notification with the task summary when Claude
- * finishes responding.  Currently supports macOS (osascript); other
- * platforms exit silently.  Windows (PowerShell) and Linux (notify-send)
- * support is planned.
+ * finishes responding.  Supports:
+ *   - macOS: osascript (native)
+ *   - WSL: PowerShell 7 or Windows PowerShell + BurntToast module
+ *
+ * On WSL, if BurntToast is not installed, logs a tip for installation.
  *
  * Hook ID : stop:desktop-notify
  * Profiles: standard, strict
@@ -19,6 +21,64 @@ const { isMacOS, log } = require('../lib/utils');
 const TITLE = 'Claude Code';
 const MAX_BODY_LENGTH = 100;
 
+/**
+ * Memoized WSL detection at module load (avoids repeated /proc/version reads).
+ */
+let isWSL = false;
+if (process.platform === 'linux') {
+  try {
+    isWSL = require('fs').readFileSync('/proc/version', 'utf8').toLowerCase().includes('microsoft');
+  } catch {
+    isWSL = false;
+  }
+}
+
+/**
+ * Find available PowerShell executable on WSL.
+ * Returns first accessible path, or null if none found.
+ */
+function findPowerShell() {
+  if (!isWSL) return null;
+
+  const candidates = [
+    'pwsh.exe',        // WSL interop resolves from Windows PATH
+    'powershell.exe',  // WSL interop for Windows PowerShell
+    '/mnt/c/Program Files/PowerShell/7/pwsh.exe',      // PowerShell 7 (default install)
+    '/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe', // Windows PowerShell
+  ];
+
+  for (const path of candidates) {
+    try {
+      const result = spawnSync(path, ['-Command', 'exit 0'],
+        { stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000 });
+      if (result.status === 0) {
+        return path;
+      }
+    } catch {
+      // continue
+    }
+  }
+  return null;
+}
+
+/**
+ * Send a Windows Toast notification via PowerShell BurntToast.
+ * Returns { success: boolean, reason: string|null }.
+ * reason is null on success, or contains error detail on failure.
+ */
+function notifyWindows(pwshPath, title, body) {
+  const safeBody = body.replace(/'/g, "''");
+  const safeTitle = title.replace(/'/g, "''");
+  const command = `Import-Module BurntToast; New-BurntToastNotification -Text '${safeTitle}', '${safeBody}'`;
+  const result = spawnSync(pwshPath, ['-Command', command],
+    { stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 });
+  if (result.status === 0) {
+    return { success: true, reason: null };
+  }
+  const errorMsg = result.error ? result.error.message : result.stderr?.toString();
+  return { success: false, reason: errorMsg || `exit ${result.status}` };
+}
+
 /**
  * Extract a short summary from the last assistant message.
  * Takes the first non-empty line and truncates to MAX_BODY_LENGTH chars.
@@ -53,20 +113,34 @@ function notifyMacOS(title, body) {
   }
 }
 
-// TODO: future platform support
-// function notifyWindows(title, body) { ... }
-// function notifyLinux(title, body) { ... }
-
 /**
  * Fast-path entry point for run-with-flags.js (avoids extra process spawn).
  */
 function run(raw) {
   try {
-    if (!isMacOS) return raw;
-
     const input = raw.trim() ? JSON.parse(raw) : {};
     const summary = extractSummary(input.last_assistant_message);
-    notifyMacOS(TITLE, summary);
+
+    if (isMacOS) {
+      notifyMacOS(TITLE, summary);
+    } else if (isWSL) {
+      const ps = findPowerShell();
+      if (ps) {
+        const { success, reason } = notifyWindows(ps, TITLE, summary);
+        if (success) {
+          // notification sent successfully
+        } else if (reason && reason.toLowerCase().includes('burnttoast')) {
+          // BurntToast module not found
+          log('[DesktopNotify] Tip: Install BurntToast module to enable notifications');
+        } else if (reason) {
+          // Other PowerShell/notification error - log for debugging
+          log(`[DesktopNotify] Notification failed: ${reason}`);
+        }
+      } else {
+        // No PowerShell found
+        log('[DesktopNotify] Tip: Install BurntToast module in PowerShell for notifications');
+      }
+    }
   } catch (err) {
     log(`[DesktopNotify] Error: ${err.message}`);
   }