pi-windows-notifier 0.1.1 → 0.3.0

package/README.md

@@ -2,11 +2,15 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md)
 
-Get a Windows notification when Pi needs your attention—or when it's finished responding. The extension shows a toast and plays a system sound for permission requests, structured questions, and completed, interrupted, or failed responses, even while you're looking at another window.
+**Built specifically for Windows. Zero dependencies. Security-first alert sound and notification plugin.**
 
-Notifications stay on your machine and only tell you what happened. They don't include your questions, commands, file paths, or Pi's replies. The extension doesn't approve permissions or answer questions for you.
+Get a Windows notification when Pi needs your attention—or when it's finished responding. Shows a toast and plays a system sound or your own WAV file for permission requests, structured questions, and completed responses, even while you're looking at another window.
 
-[GitHub](https://github.com/C-W-Z/pi-windows-notifier) · [npm](https://www.npmjs.com/package/pi-windows-notifier)
+Notifications stay on your machine. They don't pull questions, commands, file paths, or Pi's replies from your session; you can set your own static notification text. The extension doesn't approve permissions or answer questions for you.
+
+Uses Pi-provided APIs, Node.js built-ins, and the built-in Windows notification and sound APIs—no extra notification library or external audio player to install. The design avoids risky patterns present in many other similar plugins. See [Privacy and process safety](#privacy-and-process-safety) for the protections and their limits.
+
+[Pi package page](https://pi.dev/packages/pi-windows-notifier) · [GitHub](https://github.com/C-W-Z/pi-windows-notifier) · [npm](https://www.npmjs.com/package/pi-windows-notifier)
 
 ## Install
 
@@ -37,11 +41,11 @@ pi remove npm:pi-windows-notifier
 |---|---|---|
 | `permission` | Pi needs you to review a permission request | Exclamation |
 | `question` | A supported question tool is waiting for your answer | Exclamation |
-| `completed` | Pi has finished responding | Asterisk |
+| `completed` | Pi has finished responding | Hand |
 | `aborted` | The response was interrupted | Exclamation |
 | `failed` | The response ended in an error | Exclamation |
 
-The toast title is **Pi**. Notification text and the extension's command messages are currently in Traditional Chinese; there isn't a language setting yet.
+The default toast title is **Pi**, and default messages are in English. You can change the title and message for each event in your config. Command messages are still in Traditional Chinese; there isn't a language switch.
 
 Permission notifications work with `@gotgenes/pi-permission-system`, including requests forwarded from a subagent to its parent session. Requests that are automatically allowed or denied, or covered by an existing session approval, don't trigger a notification.
 
@@ -61,36 +65,131 @@ Some question packages also ring the terminal bell themselves. If you hear an ex
 
 ## Settings
 
-To change the defaults, create `~/.pi/agent/pi-windows-notifier/config.json`. On Windows, that's `.pi\agent\pi-windows-notifier\config.json` inside your user home folder.
+To change the defaults, create `~/.pi/agent/extensions/pi-windows-notifier/config.json`. On Windows, that's `.pi\agent\extensions\pi-windows-notifier\config.json` inside your user home folder. The extension doesn't create or edit this file, and it doesn't read project-level settings.
+
+The new path takes priority. Only when it doesn't exist does the extension read the old `~/.pi/agent/pi-windows-notifier/config.json`; the two files aren't merged. An invalid or unreadable new file disables notifications instead of falling back. To move your settings, place your existing config at the new path and reload. The extension won't move or rewrite either file.
 
-The extension doesn't create or edit this file for you, and it doesn't read project-level settings. If the file doesn't exist, it uses these defaults:
+### Complete config
+
+This example includes the system-sound fields and all five events; file sounds are shown separately below. You can copy it as a starting point, but **you only need to keep the fields you want to change**, along with `schemaVersion: 2`. Each event overrides the shared message below, so the example behaves like the built-in defaults.
 
 ```json
 {
+  "schemaVersion": 2,
   "enabled": true,
+  "defaults": {
+    "toast": {
+      "enabled": true,
+      "title": "Pi",
+      "message": "Pi needs your attention."
+    },
+    "sound": {
+      "enabled": true,
+      "source": {
+        "type": "system",
+        "name": "Exclamation"
+      }
+    }
+  },
   "events": {
-    "permission": { "enabled": true, "sound": true },
-    "question": { "enabled": true, "sound": true },
-    "completed": { "enabled": true, "sound": true },
-    "aborted": { "enabled": true, "sound": true },
-    "failed": { "enabled": true, "sound": true }
+    "permission": {
+      "enabled": true,
+      "toast": { "enabled": true, "title": "Pi", "message": "Permission approval needed" },
+      "sound": { "enabled": true, "source": { "type": "system", "name": "Exclamation" } }
+    },
+    "question": {
+      "enabled": true,
+      "toast": { "enabled": true, "title": "Pi", "message": "Waiting for your answer" },
+      "sound": { "enabled": true, "source": { "type": "system", "name": "Exclamation" } }
+    },
+    "completed": {
+      "enabled": true,
+      "toast": { "enabled": true, "title": "Pi", "message": "Response complete" },
+      "sound": { "enabled": true, "source": { "type": "system", "name": "Hand" } }
+    },
+    "aborted": {
+      "enabled": true,
+      "toast": { "enabled": true, "title": "Pi", "message": "Response interrupted" },
+      "sound": { "enabled": true, "source": { "type": "system", "name": "Exclamation" } }
+    },
+    "failed": {
+      "enabled": true,
+      "toast": { "enabled": true, "title": "Pi", "message": "Response failed" },
+      "sound": { "enabled": true, "source": { "type": "system", "name": "Exclamation" } }
+    }
   }
 }
 ```
 
-You only need to include the values you want to change. For example, to keep completion toasts but turn off their sound:
+### Fields and override rules
+
+Settings are applied in this order: **built-in event defaults → shared `defaults` → individual `events.<event>` settings**. Omitted fields inherit the previous layer. For example, `defaults.toast.message` supplies one message for all events unless an event sets its own message; omit it to keep the built-in event-specific messages.
+
+| Field | What it does |
+|---|---|
+| `schemaVersion` | Set to `2` for this format |
+| `enabled` | Master switch; `false` turns all notifications off |
+| `defaults` | Shared `toast` and `sound` settings; there is no `defaults.enabled` |
+| `events.<event>` | Overrides for `permission`, `question`, `completed`, `aborted`, or `failed` |
+| `events.<event>.enabled` | Turns that entire event on or off |
+| `toast.enabled` | Turns the toast on or off |
+| `toast.title` | Static notification title |
+| `toast.message` | Static notification message |
+| `sound.enabled` | Turns the sound on or off |
+| `sound.source.type` | `"system"` for Windows sound events, or `"file"` for a local WAV |
+| `sound.source.name` | Required for `"system"`: `Asterisk`, `Beep`, `Exclamation`, `Hand`, or `Question`; case-sensitive |
+| `sound.source.path` | Required for `"file"`: an absolute local WAV path, up to 1024 UTF-16 code units |
+
+The `toast` and `sound` fields can appear under either `defaults` or an individual event. **The complete example explicitly sets every event field, so changing `defaults` alone won't change those overrides.** Remove the corresponding event fields if you want them to inherit shared settings. When setting `sound.source`, include `type` and either `name` (system) or `path` (file), never both; it replaces the source as a whole.
+
+- **Toast only**: set `sound.enabled` to `false` and `toast.enabled` to `true`.
+- **Sound only**: set `toast.enabled` to `false` and `sound.enabled` to `true`.
+- If both channels are off, no helper starts. Event settings can override shared channel switches, but can't override a disabled master or event switch.
+
+Without a config file, all events and channels are enabled, the title is Pi, and messages are in English. Completion uses Hand; the other events use Exclamation.
+
+### Text and sound limits
+
+Text is used exactly as written—there are no templates or substitutions from your session. Titles can contain up to 128 UTF-16 code units and messages up to 512; an emoji may count as two. Both must be nonblank, single-line strings without control characters or invalid XML characters. Your text appears in Windows notifications, so don't put secrets in it. It isn't shown by `status` or error messages.
+
+Sound names select **Windows system sound events**, not separate audio files bundled with the package. The sound you hear depends on your Windows sound scheme: different events can use the same sound, or have no sound assigned. You can review or change these mappings in the Windows Sound settings; changes also affect other apps using those events. Choosing a file source changes only this extension, not your Windows sound scheme.
+
+### Custom WAV sounds
+
+For example, use your own sound when a response completes:
 
 ```json
-{ "events": { "completed": { "sound": false } } }
+{
+  "schemaVersion": 2,
+  "events": {
+    "completed": {
+      "sound": {
+        "source": { "type": "file", "path": "C:/Users/you/Sounds/done.wav" }
+      }
+    }
+  }
+}
 ```
 
-The top-level `enabled` switch controls everything. Each event's `enabled` switch controls both its toast and sound; `sound` only controls its sound.
+Use the same `sound.source` object under `defaults` to share a file across events, or choose different files for each event. Remove existing event-specific sources if you want them to inherit `defaults`.
 
-After editing the file, run `/windows-notifier reload`. Unknown fields, invalid values, unreadable files, and files larger than 16 KiB disable notifications until you fix the settings and reload. Error messages won't print the file's contents.
+> The format, path, size, and duration limits are deliberate safety trade-offs: they keep file access and playback bounded without external codec/player selection or network audio sources. This extension favors short notification sounds over a general-purpose media player.
+- Supply an absolute path on a local **fixed drive**, such as `C:/Sounds/done.wav`. Forward slashes work and avoid JSON backslash escaping; with backslashes, write `C:\Sounds\done.wav` as `"C:\\Sounds\\done.wav"` in JSON.
+- Relative paths, `~`, environment-variable expansion, URLs, UNC paths, mapped network drives, device paths, alternate data streams, and reparse points (including ancestor junctions/symlinks) are not supported.
+- Files must be RIFF PCM WAV: mono or stereo, 8- or 16-bit, 8–48 kHz, at most **5 seconds** and **5 MiB**. MP3, compressed WAV, and WAV extensible are not supported. Renaming an MP3 to `.wav` won't work.
+- There is no per-sound volume setting, looping, external player, or bundled audio. Use audio you trust and have permission to use.
+- Paths are validated on reload; files are read and checked only when an enabled sound is actually submitted. A missing, unreadable, unsupported, or oversized file returns `SOUND_FAILED`; the toast is still attempted. There is no fallback to a system sound.
+- File paths are sent to the fixed helper through stdin, not command arguments, and aren't printed by `status` or error messages.
+
+### Apply changes and older configs
+
+After editing the file, run `/reload` or `/windows-notifier reload`. Unknown fields, unsupported versions or sound sources, invalid values, unreadable files, and files larger than 16 KiB disable notifications until you fix the settings and reload. Error messages won't print the file's contents.
+
+The old unversioned format, with a boolean such as `events.completed.sound: false`, still works and is converted in memory without rewriting your file. New channel objects require `schemaVersion: 2`; don't mix old sound booleans with v2 objects.
 
 ## Commands
 
-Run these inside Pi:
+Run these inside Pi. After `/windows-notifier `, press **Tab** to show `status`, `reload`, or `test`, use **↑/↓** to choose, then press **Tab** to accept. Completing `test` adds a space automatically, so you can keep pressing **Tab** to show and accept an event name without typing a space. Partial prefixes such as `test co` also work.
 
 ```text
 /windows-notifier status
@@ -99,32 +198,19 @@ Run these inside Pi:
 /windows-notifier test permission
 ```
 
-- `status` shows the active settings, backend status, queue counters, and diagnostic codes—not your session content.
+- `status` shows channel switches, sound choices, backend status, queue counters, and diagnostic codes—not your custom text, file paths, or session content.
 - `reload` reads the config again and cancels old notification work.
 - `test` sends a completion notification by default. You can also choose `permission`, `question`, `completed`, `aborted`, or `failed`.
 
 **Tests produce real notifications and sounds.** They follow the same switches, queue limits, and rate limits as automatic notifications, so they won't override a disabled event.
 
-## Privacy and process safety
-
-This extension uses Windows' built-in notification and sound APIs through a fixed PowerShell script. You don't need a separate notification server or audio player. There are no network notifications, telemetry, or custom sound files.
-
-- PowerShell is located using an absolute path under the startup environment's `SystemRoot` or `windir`, never the project directory or `PATH`.
-- The helper runs without a shell. It receives only an event type and a sound switch, validates both, and builds the toast from fixed strings. It doesn't interpolate your content into PowerShell commands or XML.
-- The child process gets a limited set of Windows environment variables, not Pi's full environment or API tokens. `-ExecutionPolicy Bypass` applies only to that child; it doesn't grant administrator access or change permanent settings. Execution Policy isn't treated as a security boundary.
-- Only one helper runs at a time. The queue holds at most 16 notifications, launches are at least a second apart, queued work expires after 30 seconds, and the helper has a 10-second timeout. stdout and stderr are each capped at 8 KiB. Permission requests and questions take priority over response notifications.
-- It only attempts to stop its own child process, never every process with the same name. If Windows refuses to stop that process, new helpers wait for it to close instead of piling up.
-- Decisions, finished questions, new runs, reloads, session changes, and shutdown cancel the relevant old work. A toast already shown can't be taken back, and cancellation can race with submission to Windows.
-
-These safeguards assume that Windows' system directories, Pi's startup environment, and installed packages are trustworthy. They don't protect against a malicious extension running in the same process or a compromised user account. Pi's permission system doesn't sandbox extensions at the OS level.
-
 ## FAQ
 
 ### Why aren't notifications showing up?
 
 Windows still has the final say. Do Not Disturb, notification settings, your sound scheme, and muted audio can suppress a toast or sound even after the API accepts it.
 
-The sender may appear as **PowerShell** because the extension uses the `Microsoft.Windows.PowerShell` AppID. The toast itself says **Pi**. Toast audio is disabled and the system sound is played separately to avoid a duplicate sound from this backend. If one fails, the other is still attempted. There is no fallback notification or audio player.
+The sender may appear as **PowerShell** because the extension uses the `Microsoft.Windows.PowerShell` AppID. The toast title defaults to **Pi**, or the title you choose. Toast audio is disabled and the selected sound is played separately to avoid a duplicate sound from this backend. If one fails, the other is still attempted. There is no fallback notification or audio player.
 
 Use `/windows-notifier status` to check these codes:
 
@@ -141,6 +227,22 @@ Use `/windows-notifier status` to check these codes:
 
 Automatic errors show at most one terminal warning per minute. Status uses fixed diagnostic codes rather than raw PowerShell error output.
 
+## Privacy and process safety
+
+This extension uses Windows' built-in notification and sound APIs through a fixed PowerShell script. You don't need a separate notification server or audio player. There are no network notifications, telemetry, downloads, or bundled sound files.
+
+Several feature restrictions are intentional security decisions, not just platform limitations. The safeguards below address command injection, executable lookup hijacking, accidental credential exposure, network-path access, unbounded process creation, and interference with unrelated applications. They are not a guarantee that the extension is vulnerability-free.
+
+- To reduce executable lookup hijacking, PowerShell is located using an absolute path under the startup environment's `SystemRoot` or `windir`, never the project directory or `PATH`.
+- To avoid command/XML injection from config values, the helper runs without a shell. It receives only the event type, validated channel settings (including a local WAV path when configured), and static config text through stdin. Text is inserted using DOM text nodes, not interpolated into PowerShell commands or XML. No session content is passed to it.
+- To reduce accidental credential exposure, the child process gets a limited set of Windows environment variables, not Pi's full environment or API tokens. `-ExecutionPolicy Bypass` applies only to that child; it doesn't grant administrator access or change permanent settings. Execution Policy isn't treated as a security boundary.
+- WAV files are checked for local-drive paths and reparse points, read into size-limited memory, and validated before playback through `System.Media.SoundPlayer`. Playback stays in the same helper and is covered by its timeout and cancellation. File checks are not a sandbox against an attacker concurrently changing filesystem paths.
+- To limit process storms and resource consumption, only one helper runs at a time. The queue holds at most 16 notifications, launches are at least a second apart, queued work expires after 30 seconds, and the helper has a 10-second timeout. stdout and stderr are each capped at 8 KiB. Permission requests and questions take priority over response notifications.
+- To avoid terminating unrelated applications, it only attempts to stop its own child process, never every process with the same name. If Windows refuses to stop that process, new helpers wait for it to close instead of piling up.
+- Decisions, finished questions, new runs, reloads, session changes, and shutdown cancel the relevant old work. A toast already shown can't be taken back, and cancellation can race with submission to Windows.
+
+These safeguards assume that Windows' system directories, Pi's startup environment, and installed packages are trustworthy. They don't protect against a malicious extension running in the same process or a compromised user account. Pi's permission system doesn't sandbox extensions at the OS level.
+
 ## Development
 
 ```bash
@@ -149,7 +251,7 @@ npm run verify
 npm pack --dry-run
 ```
 
-Tests use a fake clock, event bus, and launcher. On Windows, they also check PowerShell syntax and invalid input handling. Normal `npm test` runs don't show toasts or play sounds. See the [verification notes (繁體中文)](docs/verification.md) for the test scope and remaining checks.
+Tests use a fake clock, event bus, and launcher. On Windows, they also check PowerShell syntax, invalid input handling, PCM WAV validation, bounded file reads, and junction rejection. Normal `npm test` runs don't show toasts or play sounds. See the [verification notes (繁體中文)](docs/verification.md) for the test scope and remaining checks.
 
 ## License
 

package/README.zh-TW.md

@@ -2,11 +2,15 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md)
 
-不用一直盯著 Pi。需要你確認權限、回答問題，或模型回應結束時，這個 extension 會跳出 Windows 通知並播放提示音。就算你正在看別的視窗，也會提醒。
+**專為 Windows 設計。0 依賴套件。以安全為優先的提示音與通知插件。**
 
-通知只告訴你發生了什麼事，不會帶出問題、命令、檔案路徑或模型回答，也不會替你批准權限或回答問題。所有提醒都在本機處理。
+需要你確認權限、回答問題，或模型回應結束時，會自動跳出 Windows 通知，並播放系統提示音或你自訂的 WAV 音效。就算你正在看別的視窗也會提醒，讓你不用一直盯著 Pi。
 
-[GitHub](https://github.com/C-W-Z/pi-windows-notifier) · [npm](https://www.npmjs.com/package/pi-windows-notifier)
+通知不會從 session 帶出問題、命令、檔案路徑或模型回答，但你可以設定自己的固定提醒文字。它也不會替你批准權限或回答問題，所有提醒都在本機處理。
+
+使用 Pi 提供的 API、Node.js built-ins 與 Windows 內建通知和音效 API，不必另裝通知函式庫或外部播放器。設計上避開了許多其他同類套件的高風險做法；具體防護與限制見[隱私與程序安全](#隱私與程序安全)。
+
+[Pi 套件頁](https://pi.dev/packages/pi-windows-notifier) · [GitHub](https://github.com/C-W-Z/pi-windows-notifier) · [npm](https://www.npmjs.com/package/pi-windows-notifier)
 
 ## 安裝
 
@@ -35,13 +39,13 @@ pi remove npm:pi-windows-notifier
 
 | 事件 | 通知內容 | Windows 提示音 |
 |---|---|---|
-| `permission` | 需要權限確認 | Exclamation |
-| `question` | 有問題等待回答 | Exclamation |
-| `completed` | 回應已完成 | Asterisk |
-| `aborted` | 回應已中止 | Exclamation |
-| `failed` | 回應失敗 | Exclamation |
+| `permission` | Permission approval needed | Exclamation |
+| `question` | Waiting for your answer | Exclamation |
+| `completed` | Response complete | Hand |
+| `aborted` | Response interrupted | Exclamation |
+| `failed` | Response failed | Exclamation |
 
-彈窗標題是 **Pi**。目前通知文字和指令提示都是繁體中文，還沒有語言切換設定。
+彈窗標題預設是 **Pi**，預設訊息是英文。每個事件都能設定自己的標題與訊息；指令提示仍是繁體中文，沒有整體語言切換設定。
 
 **權限提醒**搭配 `@gotgenes/pi-permission-system` 使用，也支援從 subagent 轉送到父 session 的權限請求。自動允許、自動拒絕，或已經有 session approval 的請求不會提醒。
 
@@ -61,36 +65,131 @@ Pi 的 UI 事件沒有說明是哪個工具開了視窗。因此，只有恰好
 
 ## 設定
 
-想改預設行為時，請自行建立 `~/.pi/agent/pi-windows-notifier/config.json`。在 Windows 上，就是使用者家目錄裡的 `.pi\agent\pi-windows-notifier\config.json`。
+想改預設行為時，請自行建立 `~/.pi/agent/extensions/pi-windows-notifier/config.json`。在 Windows 上，就是使用者家目錄裡的 `.pi\agent\extensions\pi-windows-notifier\config.json`。套件不會替你建立或修改這個檔案，也不讀專案內的設定。
+
+新路徑優先；只有新檔案不存在時，才讀舊的 `~/.pi/agent/pi-windows-notifier/config.json`，兩份設定不會合併。新檔案若無效或無法讀取，會停用通知，不會改讀舊檔。想搬移設定時，請自行將原本的設定檔放到新路徑後 reload；套件不會搬動或改寫任何一份檔案。
 
-套件不會替你建立或修改這個檔案，也不讀專案內的設定。沒有設定檔時，使用以下預設值：
+### 完整設定範例
+
+下面列出系統音效的欄位和五種事件，可以直接複製作為起點；檔案音效範例另列於下方。不過，**實際只要保留想修改的欄位，加上 `schemaVersion: 2` 就好**。每個事件都覆寫了共用訊息，因此這份範例的效果等同內建預設。
 
 ```json
 {
+  "schemaVersion": 2,
   "enabled": true,
+  "defaults": {
+    "toast": {
+      "enabled": true,
+      "title": "Pi",
+      "message": "Pi needs your attention."
+    },
+    "sound": {
+      "enabled": true,
+      "source": {
+        "type": "system",
+        "name": "Exclamation"
+      }
+    }
+  },
   "events": {
-    "permission": { "enabled": true, "sound": true },
-    "question": { "enabled": true, "sound": true },
-    "completed": { "enabled": true, "sound": true },
-    "aborted": { "enabled": true, "sound": true },
-    "failed": { "enabled": true, "sound": true }
+    "permission": {
+      "enabled": true,
+      "toast": { "enabled": true, "title": "Pi", "message": "Permission approval needed" },
+      "sound": { "enabled": true, "source": { "type": "system", "name": "Exclamation" } }
+    },
+    "question": {
+      "enabled": true,
+      "toast": { "enabled": true, "title": "Pi", "message": "Waiting for your answer" },
+      "sound": { "enabled": true, "source": { "type": "system", "name": "Exclamation" } }
+    },
+    "completed": {
+      "enabled": true,
+      "toast": { "enabled": true, "title": "Pi", "message": "Response complete" },
+      "sound": { "enabled": true, "source": { "type": "system", "name": "Hand" } }
+    },
+    "aborted": {
+      "enabled": true,
+      "toast": { "enabled": true, "title": "Pi", "message": "Response interrupted" },
+      "sound": { "enabled": true, "source": { "type": "system", "name": "Exclamation" } }
+    },
+    "failed": {
+      "enabled": true,
+      "toast": { "enabled": true, "title": "Pi", "message": "Response failed" },
+      "sound": { "enabled": true, "source": { "type": "system", "name": "Exclamation" } }
+    }
   }
 }
 ```
 
-只要寫想改的欄位就好。例如保留完成彈窗，但不要播放提示音：
+### 欄位與覆寫規則
+
+設定依序套用：**內建事件預設 → 共用的 `defaults` → 個別 `events.<事件>` 設定**。沒寫的欄位沿用前一層。例如，`defaults.toast.message` 會讓所有事件共用同一則訊息，除非事件另外設定自己的訊息；省略它就能保留內建的各事件文字。
+
+| 欄位 | 用途 |
+|---|---|
+| `schemaVersion` | 使用這個格式時設為 `2` |
+| `enabled` | 總開關，`false` 關閉所有通知 |
+| `defaults` | 共用的 `toast` 和 `sound` 設定，沒有 `defaults.enabled` |
+| `events.<事件>` | 可設定 `permission`、`question`、`completed`、`aborted`、`failed` |
+| `events.<事件>.enabled` | 開啟或關閉整個事件 |
+| `toast.enabled` | 彈窗開關 |
+| `toast.title` | 固定的通知標題 |
+| `toast.message` | 固定的通知訊息 |
+| `sound.enabled` | 音效開關 |
+| `sound.source.type` | `"system"` 使用 Windows 系統音效，`"file"` 使用本機 WAV |
+| `sound.source.name` | `"system"` 必填：`Asterisk`、`Beep`、`Exclamation`、`Hand`、`Question`，大小寫要一致 |
+| `sound.source.path` | `"file"` 必填：本機 WAV 的絕對路徑，最多 1024 個 UTF-16 code units |
+
+`toast` 和 `sound` 欄位都能放在 `defaults` 或個別事件底下。**完整範例已寫出每個事件的所有欄位，只改 `defaults` 不會改到已被事件覆寫的值。** 想讓事件沿用共用設定，請刪除該事件底下對應的欄位。設定 `sound.source` 時必須提供 `type`，以及系統音效的 `name` 或檔案音效的 `path`，不能同時提供兩者；它會整組取代原本的來源。
+
+- **只要彈窗**：將 `sound.enabled` 設為 `false`、`toast.enabled` 設為 `true`。
+- **只要音效**：將 `toast.enabled` 設為 `false`、`sound.enabled` 設為 `true`。
+- 兩個通道都關閉時，不啟動 helper。事件可以覆寫共用通道開關，但不能繞過已關閉的總開關或事件開關。
+
+沒有設定檔時，所有事件與通道都開啟，標題是 Pi，訊息是英文。完成通知使用 Hand，其他事件使用 Exclamation。
+
+### 文字與音效限制
+
+文字會照你寫的內容顯示，不會從 session 帶入變數，也沒有模板替換。標題最多 128 個 UTF-16 code units，訊息最多 512 個；emoji 可能算兩個。兩者都必須是非空白的單行字串，不能包含控制字元或不合法的 XML 字元。自訂文字會出現在 Windows 通知裡，請不要放敏感資訊；它不會顯示在 `status` 或錯誤提示中。
+
+音效名稱選的是 **Windows 系統音效事件**，不是套件內附的不同音效檔。實際聲音取決於 Windows 音效配置；不同事件可能共用同一個聲音，也可能沒有對應音效。你可以在 Windows「音效」設定中查看或修改對應，但修改也會影響使用相同事件的其他程式。改用檔案來源只影響這個 extension，不會修改 Windows 音效配置。
+
+### 自訂 WAV 音效
+
+例如，讓回應完成時播放你自己的音效：
 
 ```json
-{ "events": { "completed": { "sound": false } } }
+{
+  "schemaVersion": 2,
+  "events": {
+    "completed": {
+      "sound": {
+        "source": { "type": "file", "path": "C:/Users/you/Sounds/done.wav" }
+      }
+    }
+  }
+}
 ```
 
-最外層的 `enabled` 是總開關。每個事件的 `enabled` 控制該類彈窗與音效，`sound` 則只控制音效。
+同樣的 `sound.source` 也可以放在 `defaults`，讓多個事件共用檔案，或為每個事件選擇不同音效。想沿用 `defaults` 時，請移除原本事件底下的來源覆寫。
+
+> 格式、路徑、大小與長度限制是刻意的安全取捨：讓檔案存取與播放保持有界，不引入外部 codec／播放器選擇或網路音訊來源。這個 extension 著重短提示音，不是通用媒體播放器。
+- 使用本機**固定磁碟**上的絕對路徑，例如 `C:/Sounds/done.wav`。正斜線可以直接使用，避免 JSON 跳脫；使用反斜線時，`C:\Sounds\done.wav` 在 JSON 要寫成 `"C:\\Sounds\\done.wav"`。
+- 不支援相對路徑、`~`、環境變數展開、URL、UNC 路徑、網路磁碟、裝置路徑、alternate data streams 或 reparse points（包含上層目錄的 junction／symlink）。
+- 檔案必須是 RIFF PCM WAV：mono 或 stereo、8 或 16 bit、8–48 kHz，最多 **5 秒**、**5 MiB**。不支援 MP3、壓縮 WAV 或 WAV extensible；把 MP3 改名成 `.wav` 也不能播放。
+- 不提供個別音量、循環播放、外部播放器或內附音效。請使用可信任且有權使用的音訊。
+- reload 時驗證路徑；只有啟用的音效實際提交時，才讀取並檢查檔案。檔案不存在、無法讀取、格式不支援或超過限制時回報 `SOUND_FAILED`，彈窗仍會嘗試送出，不會改播系統音效。
+- 檔案路徑透過 stdin 送入固定 helper，不放在命令參數，也不顯示在 `status` 或錯誤提示中。
+
+### 套用修改與舊格式相容
 
-修改後執行 `/windows-notifier reload`。如果有未知欄位、值的型別不對、檔案無法讀取或超過 16 KiB，通知會先停用；修正後再 reload 即可。錯誤提示不會印出設定檔內容。
+修改後執行 `/reload` 或 `/windows-notifier reload`。如果有未知欄位、不支援的版本或音效來源、值不合法、檔案無法讀取或超過 16 KiB，通知會先停用；修正後再 reload 即可。錯誤提示不會印出設定檔內容。
+
+原本沒有版本欄位、音效使用 boolean 的格式（例如 `events.completed.sound: false`）仍能使用，只在記憶體裡轉換，不會修改你的檔案。要使用新的通道物件，請加上 `schemaVersion: 2`；不要把舊的音效 boolean 和 v2 物件混在一起。
 
 ## 指令
 
-在 Pi 裡執行：
+在 Pi 裡執行。輸入 `/windows-notifier ` 後按 **Tab**，會列出 `status`、`reload` 或 `test`；用 **↑/↓** 選擇，再按 **Tab** 接受。補完 `test` 會自動加上空白，接著連按 **Tab** 即可列出並接受事件名稱，不必手動輸入空白；也支援 `test co` 這類前綴。
 
 ```text
 /windows-notifier status
@@ -99,24 +198,12 @@ Pi 的 UI 事件沒有說明是哪個工具開了視窗。因此，只有恰好
 /windows-notifier test permission
 ```
 
-- `status`：查看目前設定、backend 狀態、佇列計數和診斷碼，不會顯示 session 內容。
+- `status`：查看通道開關、音效選擇、backend 狀態、佇列計數和診斷碼，不會顯示自訂文字、檔案路徑或 session 內容。
 - `reload`：重新讀取設定，取消舊的通知工作。
 - `test`：預設測試完成通知，也能指定 `permission`、`question`、`completed`、`aborted` 或 `failed`。
 
 **測試會真的跳通知、播放音效。** 和自動通知一樣，它會遵守開關、佇列與限流，不會強行送出已停用的事件。
 
-## 隱私與程序安全
-
-套件透過固定的 PowerShell 腳本呼叫 Windows 內建通知和音效 API，不用另外裝通知服務或播放器。沒有網路通知、遙測或自訂音效檔。
-
-- PowerShell 使用啟動環境的 `SystemRoot`／`windir` 下的絕對路徑，不從專案目錄或 `PATH` 搜尋。
-- helper 不透過 shell 執行，只接收事件類型與音效開關。驗證後使用固定文字建立通知，不把工作內容拼進 PowerShell 命令或 XML。
-- 子程序只拿到必要的 Windows 環境變數，不繼承 Pi 的完整環境或 API tokens。`-ExecutionPolicy Bypass` 只作用於該子程序，不會取得管理員權限或改動永久設定，也不把 Execution Policy 當成安全邊界。
-- 同時最多一個 helper，佇列最多 16 筆，啟動至少間隔一秒。工作等待超過 30 秒會過期，helper 的 timeout 是 10 秒，stdout 和 stderr 各限制 8 KiB。權限和提問比回應結束通知優先。
-- 只嘗試終止自己建立的子程序，不會按名稱關閉其他程序。如果 Windows 不允許終止，就等它結束，不會繼續堆出新的 helper。
-- 權限決策、問題結束、新回應、reload、session 切換和 shutdown 都會取消相關舊工作。已經顯示的 Toast 無法收回，取消和提交給 Windows 之間仍可能發生競態。
-
-這些防護假設 Windows 系統目錄、Pi 啟動環境和已安裝套件可信。它們無法防禦同程序裡的惡意 extension，或已遭入侵的使用者帳號。Pi permission system 並不是 extension 的 OS 沙盒。
 
 ## 常見問題
 
@@ -124,7 +211,7 @@ Pi 的 UI 事件沒有說明是哪個工具開了視窗。因此，只有恰好
 
 Windows 仍然有最終決定權。勿擾模式、通知設定、系統音效方案和靜音，都可能讓已提交的通知沒有彈出或沒有聲音。
 
-因為使用 `Microsoft.Windows.PowerShell` AppID，通知來源可能顯示 **PowerShell**，但彈窗本身會寫 **Pi**。Toast 自帶的音效關閉，提示音另外播放，避免這個 backend 自己重複響兩次。彈窗和音效分開處理，一個失敗仍會嘗試另一個；沒有備用通知方式或播放器。
+因為使用 `Microsoft.Windows.PowerShell` AppID，通知來源可能顯示 **PowerShell**，但彈窗標題預設是 **Pi**，也可以改成你設定的標題。Toast 自帶的音效關閉，提示音另外播放，避免這個 backend 自己重複響兩次。彈窗和音效分開處理，一個失敗仍會嘗試另一個；沒有備用通知方式或播放器。
 
 可以用 `/windows-notifier status` 查看診斷碼：
 
@@ -141,6 +228,22 @@ Windows 仍然有最終決定權。勿擾模式、通知設定、系統音效方
 
 自動通知錯誤最多每分鐘顯示一次終端警告。診斷只使用固定代碼，不會帶出 PowerShell 原始錯誤內容。
 
+## 隱私與程序安全
+
+套件透過固定的 PowerShell 腳本呼叫 Windows 內建通知和音效 API，不用另外裝通知服務或播放器。沒有網路通知、遙測、下載或內附音效檔。
+
+部分功能限制是刻意的安全設計，不只是平台限制。以下防護針對命令注入、執行檔搜尋劫持、憑證意外外洩、網路路徑存取、無界程序建立，以及誤傷其他程式等風險；不代表套件保證沒有漏洞。
+
+- 為降低執行檔搜尋劫持風險，PowerShell 使用啟動環境的 `SystemRoot`／`windir` 下的絕對路徑，不從專案目錄或 `PATH` 搜尋。
+- 為避免設定值造成命令／XML 注入，helper 不透過 shell 執行，只從 stdin 接收事件類型、已驗證的通道設定（含自訂音效的本機 WAV 路徑）與固定設定文字。文字用 DOM text node 加進通知，不拼進 PowerShell 命令或 XML，也不傳入 session 內容。
+- 為降低憑證意外外洩風險，子程序只拿到必要的 Windows 環境變數，不繼承 Pi 的完整環境或 API tokens。`-ExecutionPolicy Bypass` 只作用於該子程序，不會取得管理員權限或改動永久設定，也不把 Execution Policy 當成安全邊界。
+- WAV 播放前會檢查本機磁碟路徑與 reparse points，讀入有大小限制的記憶體並驗證格式，再交給 `System.Media.SoundPlayer`。播放留在同一個 helper，沿用逾時與取消機制；檔案檢查不是防止攻擊者同時修改路徑的 sandbox。
+- 為限制大量程序啟動與資源消耗，同時最多一個 helper，佇列最多 16 筆，啟動至少間隔一秒。工作等待超過 30 秒會過期，helper 的 timeout 是 10 秒，stdout 和 stderr 各限制 8 KiB。權限和提問比回應結束通知優先。
+- 為避免誤關其他程式，只嘗試終止自己建立的子程序，不會按名稱關閉其他程序。如果 Windows 不允許終止，就等它結束，不會繼續堆出新的 helper。
+- 權限決策、問題結束、新回應、reload、session 切換和 shutdown 都會取消相關舊工作。已經顯示的 Toast 無法收回，取消和提交給 Windows 之間仍可能發生競態。
+
+這些防護假設 Windows 系統目錄、Pi 啟動環境和已安裝套件可信。它們無法防禦同程序裡的惡意 extension，或已遭入侵的使用者帳號。Pi permission system 並不是 extension 的 OS 沙盒。
+
 ## 開發
 
 ```bash
@@ -149,7 +252,7 @@ npm run verify
 npm pack --dry-run
 ```
 
-測試使用假時鐘、event bus 和 launcher。Windows 上也會檢查 PowerShell 語法與無效輸入。一般 `npm test` 不會跳彈窗或播放音效；測試範圍與仍需確認的項目見[驗證紀錄](docs/verification.md)。
+測試使用假時鐘、event bus 和 launcher。Windows 上也會檢查 PowerShell 語法、無效輸入、PCM WAV 驗證、有界檔案讀取與 junction 拒絕。一般 `npm test` 不會跳彈窗或播放音效；測試範圍與仍需確認的項目見[驗證紀錄](docs/verification.md)。
 
 ## 授權
 

package/THIRD_PARTY_NOTICES.md

@@ -35,5 +35,5 @@ SOFTWARE.
 ## Other references
 
 - [UniPi notify](https://github.com/Neuron-Mr-White/UniPi/tree/main/packages/notify), reference commit `6ac5da3`: consulted for event/backend separation. No code was copied, and neither UniPi core nor node-notifier is included.
-- [pi-jingle](https://github.com/Git-Monke/pi-jingle), reference commit `7e265ce`: consulted for the idea of event-specific sounds. Its license was not confirmed during development, so no code or audio assets were copied.
+- [pi-jingle](https://github.com/Git-Monke/pi-jingle), reference commit `7e265ce`: consulted for the idea of event-specific sounds. Its license was not confirmed during development, so no code or audio assets were copied. Custom WAV support, path validation, bounded PCM parsing, and tests were implemented independently using Windows/.NET APIs.
 - Pi, pi-permission-system, RPIV/Lean, and Plan mode APIs and source were consulted to verify integration contracts. Their source code is not bundled in this package.

package/docs/verification.md

@@ -3,7 +3,9 @@
 ## 自動驗證
 
 - TypeScript `tsc --noEmit` 與 Node test runner 通過；測試覆蓋設定驗證、權限與提問事件、回應狀態、去重取消、限流佇列、PowerShell launcher、資源清理與發布檔案清單。
-- Windows 測試檢查固定 PowerShell helper 語法及無效輸入；不呼叫 Toast 成功路徑，也不播放系統音效。
+- 設定測試涵蓋 schema v2 合併、舊格式相容、獨立通道、系統音效白名單、本機 WAV 路徑、自訂文字上限與 Unicode／XML 驗證；status 與錯誤提示不展示設定文字或檔案路徑。
+- Windows 測試檢查兩個固定 PowerShell 腳本的語法、無效輸入，以及通道全關閉時的有效輸入；不呼叫 Toast 或音效 API。單通道成功／失敗結果由 mock launcher 驗證。
+- WAV 測試使用自行合成的 PCM 資料，實際呼叫 helper 的讀取與驗證函式：mono／stereo、8／16 bit、五秒邊界、奇數 chunk padding、Unicode／引號／指令樣式檔名、超大／截斷／偽造格式、重複 chunks、缺失檔案、目錄與祖先 junction。這些測試不執行播放函式。
 - 發布包以 npm pack dry-run 核對；僅包含套件 metadata、runtime 原始碼、PowerShell helper、文件及授權。
 
 執行完整檢查：
@@ -16,7 +18,11 @@ npm pack --dry-run
 
 ## 實機驗證範圍
 
-Windows backend 的五類通知（permission、question、completed、aborted、failed）曾逐一送出，並經人工確認有 Toast 彈窗與提示音。
+0.1.x Windows backend 的五類通知（permission、question、completed、aborted、failed）曾逐一送出，並經人工確認有 Toast 彈窗與提示音。
+
+0.2.0 的自訂標題／訊息、Toast-only、sound-only 與新增系統音效選擇尚未完成實際可見／可聽驗收；不以舊版結果推論新 helper 已通過。
+
+新增的自訂 WAV 播放尚未完成實際可聽驗收。手動驗收時，請在全域 config 的 `events.completed.sound.source` 設定 `{ "type": "file", "path": "C:/Sounds/done.wav" }`，使用符合限制的可信任檔案，reload 後執行 `/windows-notifier test completed`。另需確認 sound-only、檔案缺失時 Toast 仍送出，以及播放中 reload／shutdown 的取消行為。這些指令會產生實際通知與聲音。
 
 這項 backend 驗證不等於所有 Pi 整合情境均已端到端驗收。以下項目仍需在實際使用環境確認：
 

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "pi-windows-notifier",
-  "version": "0.1.1",
-  "description": "Pi 的 Windows Toast 與系統提示音：權限、結構化提問及回應結束通知。",
+  "version": "0.3.0",
+  "description": "Windows notifications and sounds for Pi permission requests, questions, and completed, interrupted, or failed responses.",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/C-W-Z/pi-windows-notifier.git"
   },
-  "homepage": "https://github.com/C-W-Z/pi-windows-notifier#readme",
+  "homepage": "https://pi.dev/packages/pi-windows-notifier",
   "bugs": {
     "url": "https://github.com/C-W-Z/pi-windows-notifier/issues"
   },
@@ -23,7 +23,7 @@
   ],
   "files": [
     "src/**/*.ts",
-    "src/windows-notify.ps1",
+    "src/*.ps1",
     "README.md",
     "README.zh-TW.md",
     "docs/verification.md",

package/src/completion.ts

@@ -0,0 +1,42 @@
+import type { AutocompleteItem, AutocompleteProvider } from "@earendil-works/pi-tui";
+import { KINDS } from "./types.ts";
+
+export function notifierArgumentCompletions(prefix: string): AutocompleteItem[] | null {
+  const leading = prefix.match(/^\s*/u)![0];
+  const argument = prefix.slice(leading.length);
+  if (!/\s/u.test(argument)) {
+    const matches = ["status", "reload", "test"].filter(value => value.startsWith(argument));
+    // test 還有下一層參數；補上空白，讓下一次 Tab 能直接補事件名稱。
+    return matches.length ? matches.map(value => ({
+      value: leading + value + (value === "test" ? " " : ""), label: value,
+    })) : null;
+  }
+  const match = argument.match(/^test(\s+)(\S*)$/u);
+  if (!match) return null;
+  const matches = KINDS.filter(kind => kind.startsWith(match[2]));
+  // Pi 會替換整段 argument prefix；必須保留 test 與空白，不只回傳事件名稱。
+  return matches.length ? matches.map(kind => ({ value: leading + "test" + match[1] + kind, label: kind })) : null;
+}
+
+/** 只接管本指令的參數，避免選單關閉後的 Tab 改走 Pi 的強制檔案補全。 */
+export function withNotifierCompletions(current: AutocompleteProvider): AutocompleteProvider {
+  const argumentPrefix = (lines: string[], cursorLine: number, cursorCol: number) =>
+    cursorLine === 0 ? (lines[0] ?? "").slice(0, cursorCol).match(/^\s*\/windows-notifier (.*)$/u)?.[1] : undefined;
+  return {
+    triggerCharacters: current.triggerCharacters,
+    async getSuggestions(lines, cursorLine, cursorCol, options) {
+      const prefix = argumentPrefix(lines, cursorLine, cursorCol);
+      if (prefix === undefined) return current.getSuggestions(lines, cursorLine, cursorCol, options);
+      if (options.signal.aborted) return null;
+      const items = notifierArgumentCompletions(prefix);
+      return items ? { items, prefix } : null;
+    },
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+    },
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      if (argumentPrefix(lines, cursorLine, cursorCol) !== undefined) return true;
+      return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+    },
+  };
+}

package/src/config.ts

@@ -1,10 +1,13 @@
 import { closeSync, fstatSync, openSync, readSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { KINDS, isRecord, type NotificationKind } from "./types.ts";
+import { KINDS, TITLE_LIMIT, MESSAGE_LIMIT, isRecord, onlyKeys, validText, validSoundSource,
+  type NotificationKind, type ToastConfig, type SoundConfig } from "./types.ts";
 
-export interface EventConfig { enabled: boolean; sound: boolean }
+export interface EventConfig { enabled: boolean; toast: ToastConfig; sound: SoundConfig }
+/** 解析後的有效設定；defaults 已合併至各事件，不保留重複設定來源。 */
 export interface Config {
+  schemaVersion: 2;
   enabled: boolean;
   events: Record<NotificationKind, EventConfig>;
 }
@@ -12,41 +15,94 @@ export type ConfigResult =
   | { ok: true; config: Config }
   | { ok: false; code: "CONFIG_INVALID" | "CONFIG_TOO_LARGE" | "CONFIG_READ_FAILED"; config: Config };
 
+const MESSAGES: Record<NotificationKind, string> = {
+  permission: "Permission approval needed", question: "Waiting for your answer", completed: "Response complete",
+  aborted: "Response interrupted", failed: "Response failed",
+};
 export function defaults(): Config {
-  return { enabled: true, events: Object.fromEntries(KINDS.map(kind =>
-    [kind, { enabled: true, sound: true }])) as Config["events"] };
+  return { schemaVersion: 2, enabled: true, events: Object.fromEntries(KINDS.map(kind =>
+    [kind, { enabled: true, toast: { enabled: true, title: "Pi", message: MESSAGES[kind] },
+      sound: { enabled: true, source: { type: "system", name: kind === "completed" ? "Hand" : "Exclamation" } } }])) as Config["events"] };
 }
-function onlyKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
-  return Object.keys(value).every(key => keys.includes(key));
+function applyChannels(target: EventConfig, value: Record<string, unknown>): boolean {
+  if (Object.hasOwn(value, "toast")) {
+    const toast = value.toast;
+    if (!isRecord(toast) || !onlyKeys(toast, ["enabled", "title", "message"])) return false;
+    if (Object.hasOwn(toast, "enabled")) {
+      if (typeof toast.enabled !== "boolean") return false;
+      target.toast.enabled = toast.enabled;
+    }
+    for (const field of ["title", "message"] as const) {
+      if (!Object.hasOwn(toast, field)) continue;
+      const text = toast[field];
+      if (!validText(text, field === "title" ? TITLE_LIMIT : MESSAGE_LIMIT)) return false;
+      target.toast[field] = text;
+    }
+  }
+  if (Object.hasOwn(value, "sound")) {
+    const sound = value.sound;
+    if (!isRecord(sound) || !onlyKeys(sound, ["enabled", "source"])) return false;
+    if (Object.hasOwn(sound, "enabled")) {
+      if (typeof sound.enabled !== "boolean") return false;
+      target.sound.enabled = sound.enabled;
+    }
+    if (Object.hasOwn(sound, "source")) {
+      const source = sound.source;
+      if (!validSoundSource(source)) return false;
+      // source 作為完整單位覆寫，不合併不同來源類型的欄位。
+      target.sound.source = { ...source };
+    }
+  }
+  return true;
 }
 export function parseConfig(value: unknown): ConfigResult {
   const config = defaults();
   const invalid = (): ConfigResult => ({ ok: false, code: "CONFIG_INVALID", config: { ...defaults(), enabled: false } });
-  if (!isRecord(value) || !onlyKeys(value, ["enabled", "events"])) return invalid();
+  if (!isRecord(value)) return invalid();
+  const legacy = !Object.hasOwn(value, "schemaVersion");
+  if (!onlyKeys(value, legacy ? ["enabled", "events"] : ["schemaVersion", "enabled", "defaults", "events"]) ||
+      !legacy && value.schemaVersion !== 2) return invalid();
   if (Object.hasOwn(value, "enabled")) {
     if (typeof value.enabled !== "boolean") return invalid();
     config.enabled = value.enabled;
   }
+  if (!legacy && Object.hasOwn(value, "defaults")) {
+    if (!isRecord(value.defaults) || !onlyKeys(value.defaults, ["toast", "sound"])) return invalid();
+    for (const kind of KINDS) if (!applyChannels(config.events[kind], value.defaults)) return invalid();
+  }
   if (Object.hasOwn(value, "events")) {
     if (!isRecord(value.events) || !onlyKeys(value.events, KINDS)) return invalid();
     for (const kind of KINDS) {
       if (!Object.hasOwn(value.events, kind)) continue;
       const item = value.events[kind];
-      if (!isRecord(item) || !onlyKeys(item, ["enabled", "sound"])) return invalid();
-      for (const field of ["enabled", "sound"] as const) {
-        if (!Object.hasOwn(item, field)) continue;
-        if (typeof item[field] !== "boolean") return invalid();
-        config.events[kind][field] = item[field];
+      if (!isRecord(item) || !onlyKeys(item, legacy ? ["enabled", "sound"] : ["enabled", "toast", "sound"])) return invalid();
+      const target = config.events[kind];
+      if (Object.hasOwn(item, "enabled")) {
+        if (typeof item.enabled !== "boolean") return invalid();
+        target.enabled = item.enabled;
       }
+      if (legacy) {
+        if (Object.hasOwn(item, "sound")) {
+          if (typeof item.sound !== "boolean") return invalid();
+          target.sound.enabled = item.sound;
+        }
+      } else if (!applyChannels(target, item)) return invalid();
     }
   }
   return { ok: true, config };
 }
 export const CONFIG_LIMIT = 16 * 1024;
 export function configPath(): string {
-  return join(homedir(), ".pi", "agent", "pi-windows-notifier", "config.json");
+  return join(homedir(), ".pi", "agent", "extensions", "pi-windows-notifier", "config.json");
+}
+/** 預設先讀新位置，只有檔案不存在才讀舊位置；明確傳入路徑時不讀取其他使用者設定。 */
+export function loadConfig(path?: string, fallbackPath?: string): ConfigResult {
+  const primary = path ?? configPath();
+  const legacy = fallbackPath ?? (path === undefined
+    ? join(homedir(), ".pi", "agent", "pi-windows-notifier", "config.json") : undefined);
+  return readConfig(primary) ?? (legacy ? readConfig(legacy) : undefined) ?? { ok: true, config: defaults() };
 }
-export function loadConfig(path = configPath()): ConfigResult {
+function readConfig(path: string): ConfigResult | undefined {
   let fd: number | undefined;
   try {
     fd = openSync(path, "r");
@@ -62,7 +118,7 @@ export function loadConfig(path = configPath()): ConfigResult {
     try { return parseConfig(JSON.parse(buffer.subarray(0, size).toString("utf8"))); }
     catch { return { ok: false, code: "CONFIG_INVALID", config: { ...defaults(), enabled: false } }; }
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { ok: true, config: defaults() };
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
     return { ok: false, code: "CONFIG_READ_FAILED", config: { ...defaults(), enabled: false } };
   } finally {
     if (fd !== undefined) closeSync(fd);

package/src/launcher.ts

@@ -1,8 +1,8 @@
 import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process";
 import { statSync } from "node:fs";
-import { dirname, win32 } from "node:path";
+import { dirname, join, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
-import { isRecord, type NotificationKind } from "./types.ts";
+import { isRecord, validPayload, type NotificationPayload } from "./types.ts";
 
 export const HELPER_TIMEOUT = 10_000;
 export const OUTPUT_LIMIT = 8 * 1024;
@@ -17,7 +17,7 @@ export interface LaunchResult {
 export interface Backend {
   available: boolean;
   code: string;
-  launch(kind: NotificationKind, sound: boolean, signal: AbortSignal): Promise<LaunchResult>;
+  launch(payload: NotificationPayload, signal: AbortSignal): Promise<LaunchResult>;
 }
 const SCRIPT = fileURLToPath(new URL("./windows-notify.ps1", import.meta.url));
 const ENV_KEYS = ["SystemRoot", "windir", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "TEMP", "TMP", "USERNAME", "USERDOMAIN"];
@@ -43,7 +43,7 @@ export function windowsPaths(env: NodeJS.ProcessEnv): { executable: string; env:
   return { executable: win32.join(clean, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"), env: result };
 }
 function failed(code: LaunchCode): LaunchResult { return { code, toast: false, sound: "failed" }; }
-function parseResult(output: Buffer, exitCode: number | null, sound: boolean): LaunchResult {
+function parseResult(output: Buffer, exitCode: number | null, payload: NotificationPayload): LaunchResult {
   try {
     const parsed: unknown = JSON.parse(output.toString("utf8").trim());
     if (!isRecord(parsed) || Object.keys(parsed).length !== 3 ||
@@ -51,13 +51,14 @@ function parseResult(output: Buffer, exitCode: number | null, sound: boolean): L
         typeof parsed.sound !== "string" || !["played", "disabled", "failed"].includes(parsed.sound)) return failed("HELPER_PROTOCOL");
     const code = parsed.code as LaunchCode;
     const audio = parsed.sound as LaunchResult["sound"];
-    const expected = parsed.toast
-      ? (audio === "failed" ? "SOUND_FAILED" : "OK")
-      : (audio === "failed" ? "BOTH_FAILED" : "TOAST_FAILED");
-    if (audio === "disabled" && sound || audio === "played" && !sound) return failed("HELPER_PROTOCOL");
     if (["INPUT_INVALID", "INTERNAL_ERROR"].includes(code)) {
-      return !parsed.toast && audio === "failed" && exitCode !== 0 ? failed(code) : failed("HELPER_PROTOCOL");
+      return !parsed.toast && audio === "failed" && exitCode === 1 ? failed(code) : failed("HELPER_PROTOCOL");
     }
+    if ((!payload.toast.enabled && parsed.toast) ||
+        (payload.sound.enabled ? audio === "disabled" : audio !== "disabled")) return failed("HELPER_PROTOCOL");
+    const toastFailed = payload.toast.enabled && !parsed.toast;
+    const soundFailed = payload.sound.enabled && audio === "failed";
+    const expected = toastFailed ? (soundFailed ? "BOTH_FAILED" : "TOAST_FAILED") : (soundFailed ? "SOUND_FAILED" : "OK");
     if (code !== expected || exitCode !== (code === "OK" ? 0 : 1)) return failed("HELPER_PROTOCOL");
     return { code, toast: parsed.toast, sound: audio };
   } catch { return failed("HELPER_PROTOCOL"); }
@@ -78,12 +79,16 @@ export function createWindowsBackend(options: BackendOptions = {}): Backend {
   const script = options.scriptPath ?? SCRIPT;
   const isFile = options.isFile ?? (path => { try { return statSync(path).isFile(); } catch { return false; } });
   const available = platform === "win32" && ["x64", "arm64"].includes(arch) &&
-    !!paths && isFile(paths.executable) && isFile(script);
+    !!paths && isFile(paths.executable) && isFile(script) && isFile(join(dirname(script), "windows-sound.ps1"));
   const spawnProcess = options.spawnProcess ?? spawn;
   const code = available ? "OK" : "BACKEND_UNAVAILABLE";
   return {
     available, code,
-    launch(kind, sound, signal) {
+    launch(payload, signal) {
+      if (!validPayload(payload)) return Promise.resolve(failed("INPUT_INVALID"));
+      // 再建立白名單快照，避免呼叫方中途修改設定或額外傳入事件內容。
+      const request: NotificationPayload = { kind: payload.kind, toast: { ...payload.toast },
+        sound: { enabled: payload.sound.enabled, source: { ...payload.sound.source } } };
       if (!available || !paths) return Promise.resolve(failed("BACKEND_UNAVAILABLE"));
       if (signal.aborted) return Promise.resolve(failed("CANCELLED"));
       return new Promise(resolve => {
@@ -130,11 +135,11 @@ export function createWindowsBackend(options: BackendOptions = {}): Backend {
           if (stderrSize > OUTPUT_LIMIT) stop("OUTPUT_LIMIT");
           // 不保存或展示 PowerShell 的原始錯誤文字。
         });
-        child.once("close", exitCode => finish(reason ? failed(reason) : parseResult(output, exitCode, sound)));
+        child.once("close", exitCode => finish(reason ? failed(reason) : parseResult(output, exitCode, request)));
         child.stdin?.on("error", () => stop("LAUNCH_FAILED"));
         child.stdout?.on("error", () => stop("LAUNCH_FAILED"));
         child.stderr?.on("error", () => stop("LAUNCH_FAILED"));
-        try { child.stdin?.end(JSON.stringify({ kind, sound })); }
+        try { child.stdin?.end(JSON.stringify(request)); }
         catch { stop("LAUNCH_FAILED"); }
         if (signal.aborted) onAbort();
       });

package/src/runtime.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { defaults, loadConfig, type ConfigResult } from "./config.ts";
+import { notifierArgumentCompletions, withNotifierCompletions } from "./completion.ts";
 import { createWindowsBackend, windowsPaths, type Backend } from "./launcher.ts";
 import { NotificationScheduler, systemClock, type Clock, type Submission } from "./scheduler.ts";
 import { NotificationState } from "./state.ts";
@@ -107,7 +108,10 @@ export function registerNotifier(pi: ExtensionAPI, options: RuntimeOptions = {})
     if (!target || target.disposed || target.backendCode === "ENV_UNSUPPORTED") return;
     try { handler(target.state); } catch { diagnose(target, "EVENT_INVALID"); }
   };
-  pi.on("session_start", async (_event, context) => { await transition(() => start(context)); });
+  pi.on("session_start", async (_event, context) => {
+    if (context.mode === "tui" && context.hasUI) context.ui.addAutocompleteProvider(withNotifierCompletions);
+    await transition(() => start(context));
+  });
   pi.on("session_shutdown", async () => { await transition(stop); });
   pi.on("tool_execution_start", event => { observe(state => state.toolStart(event)); });
   pi.on("tool_execution_end", event => { observe(state => state.toolEnd(event)); });
@@ -121,6 +125,7 @@ export function registerNotifier(pi: ExtensionAPI, options: RuntimeOptions = {})
 
   pi.registerCommand("windows-notifier", {
     description: "Windows 通知：status、reload、test [permission|question|completed|aborted|failed]",
+    getArgumentCompletions: notifierArgumentCompletions,
     handler: async (args, context) => {
       const parts = args.trim().split(/\s+/u);
       if (parts.length === 1 && parts[0] === "reload") {
@@ -133,7 +138,14 @@ export function registerNotifier(pi: ExtensionAPI, options: RuntimeOptions = {})
         const status = {
           backend: target?.backendCode ?? "NOT_STARTED",
           enabled: target?.result.config.enabled ?? false,
-          events: target?.result.config.events,
+          schemaVersion: target?.result.config.schemaVersion,
+          // 自訂文字與檔案路徑只送入 helper；status 不展示可能含敏感資訊的設定。
+          events: target ? Object.fromEntries(KINDS.map(kind => {
+            const event = target.result.config.events[kind];
+            return [kind, { enabled: event.enabled, toast: { enabled: event.toast.enabled },
+              sound: { enabled: event.sound.enabled, source: event.sound.source.type === "system"
+                ? { ...event.sound.source } : { type: "file" } } }];
+          })) : undefined,
           ...target?.scheduler?.status(),
           diagnostics: [...(target?.diagnostics ?? [])],
         };

package/src/scheduler.ts

@@ -47,7 +47,8 @@ export class NotificationScheduler {
   }
   private enabled(job: NotificationJob): boolean {
     const config = this.config();
-    return !this.closed && this.backend.available && config.enabled && config.events[job.kind].enabled;
+    const event = config.events[job.kind];
+    return !this.closed && this.backend.available && config.enabled && event.enabled && (event.toast.enabled || event.sound.enabled);
   }
   private valid(job: NotificationJob): boolean {
     try { return job.valid(); } catch { return false; }
@@ -114,7 +115,11 @@ export class NotificationScheduler {
   }
   private async deliver(item: Pending, signal: AbortSignal): Promise<void> {
     let result: LaunchResult;
-    try { result = await this.backend.launch(item.job.kind, this.config().events[item.job.kind].sound, signal); }
+    try {
+      const event = this.config().events[item.job.kind];
+      result = await this.backend.launch({ kind: item.job.kind, toast: { ...event.toast },
+        sound: { enabled: event.sound.enabled, source: { ...event.sound.source } } }, signal);
+    }
     catch { result = { code: "LAUNCH_FAILED", toast: false, sound: "failed" }; }
     if (signal.aborted || result.code === "CANCELLED") { item.resolve({ status: "cancelled" }); return; }
     if (result.code !== "OK") this.diagnose(result.code);

package/src/types.ts

@@ -1,6 +1,46 @@
 export const KINDS = ["permission", "question", "completed", "aborted", "failed"] as const;
 export type NotificationKind = (typeof KINDS)[number];
 export type Outcome = "completed" | "aborted" | "error";
+export const SYSTEM_SOUNDS = ["Asterisk", "Beep", "Exclamation", "Hand", "Question"] as const;
+export type SystemSound = (typeof SYSTEM_SOUNDS)[number];
+export const TITLE_LIMIT = 128;
+export const MESSAGE_LIMIT = 512;
+export interface ToastConfig { enabled: boolean; title: string; message: string }
+export const SOUND_PATH_LIMIT = 1024;
+export type SoundSource = { type: "system"; name: SystemSound } | { type: "file"; path: string };
+export interface SoundConfig { enabled: boolean; source: SoundSource }
+export interface NotificationPayload { kind: NotificationKind; toast: ToastConfig; sound: SoundConfig }
+/** 限制單行 XML 文字；保留引號與 XML 字元，由 DOM 安全編碼。 */
+export function validText(value: unknown, limit: number): value is string {
+  return typeof value === "string" && value.trim().length > 0 && value.length <= limit &&
+    !/[\u0000-\u001f\u007f-\u009f\u2028\u2029\ufffe\uffff\ud800-\udfff]/u.test(value);
+}
+export function onlyKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  return Object.keys(value).every(key => keys.includes(key));
+}
+/** 僅接受一般磁碟上的絕對 WAV 路徑；不展開環境變數、家目錄或專案相對路徑。 */
+export function validSoundPath(value: unknown): value is string {
+  if (!validText(value, SOUND_PATH_LIMIT) || !/^[a-z]:[\\/]/iu.test(value) ||
+      /[<>:"|?*]/u.test(value.slice(2)) || !/\.wav$/iu.test(value)) return false;
+  return value.slice(3).split(/[\\/]/u).every(part => part.length > 0 && !/[. ]$/u.test(part) &&
+    !/^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/iu.test(part));
+}
+export function validSoundSource(value: unknown): value is SoundSource {
+  if (!isRecord(value)) return false;
+  return value.type === "system"
+    ? onlyKeys(value, ["type", "name"]) && SYSTEM_SOUNDS.includes(value.name as SystemSound)
+    : value.type === "file" && onlyKeys(value, ["type", "path"]) && validSoundPath(value.path);
+}
+export function validPayload(value: unknown): value is NotificationPayload {
+  if (!isRecord(value) || !onlyKeys(value, ["kind", "toast", "sound"]) ||
+      !KINDS.includes(value.kind as NotificationKind) || !isRecord(value.toast) || !isRecord(value.sound)) return false;
+  const { toast, sound } = value;
+  return onlyKeys(toast, ["enabled", "title", "message"]) && typeof toast.enabled === "boolean" &&
+    validText(toast.title, TITLE_LIMIT) && validText(toast.message, MESSAGE_LIMIT) &&
+    onlyKeys(sound, ["enabled", "source"]) && typeof sound.enabled === "boolean" &&
+    validSoundSource(sound.source) &&
+    (toast.enabled || sound.enabled);
+}
 export interface NotificationJob {
   key: string;
   kind: NotificationKind;

package/src/windows-notify.ps1

@@ -1,37 +1,82 @@
-# 固定 helper：stdin 僅接受事件 enum 與音效開關，不接受任意訊息或命令。
+# 固定 helper：只接受已驗證的通道設定、靜態文字與本機 WAV 路徑，不接受任意命令。
 Set-StrictMode -Version Latest
 $ErrorActionPreference = "Stop"
+[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false, $true)
 [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+. (Join-Path $PSScriptRoot "windows-sound.ps1")
 
 function Write-Result {
   param([string]$Code, [bool]$Toast, [string]$Sound)
   [Console]::Out.WriteLine((@{ code = $Code; toast = $Toast; sound = $Sound } | ConvertTo-Json -Compress))
 }
+function Assert-Keys {
+  param($Value, [string[]]$Keys)
+  if ($Value -isnot [pscustomobject]) { throw "INPUT_INVALID" }
+  $names = @($Value.PSObject.Properties.Name)
+  if ($names.Count -ne $Keys.Count) { throw "INPUT_INVALID" }
+  foreach ($name in $names) {
+    if ($Keys -cnotcontains $name) { throw "INPUT_INVALID" }
+  }
+}
+function Assert-Text {
+  param($Value, [int]$Limit)
+  if ($Value -isnot [string] -or [string]::IsNullOrWhiteSpace($Value) -or $Value.Length -gt $Limit -or
+      $Value -match '[\x00-\x1f\x7f-\x9f\u2028\u2029\ufffe\uffff]') { throw "INPUT_INVALID" }
+  # 同時拒絕未配對的 UTF-16 surrogate；合法 emoji 可保留。
+  [System.Xml.XmlConvert]::VerifyXmlChars($Value) | Out-Null
+}
+
+function Assert-JsonSurrogates {
+  param([string]$Value)
+  # ConvertFrom-Json 會把未配對的 surrogate 換成 replacement character；先檢查原始 JSON escape。
+  foreach ($match in [regex]::Matches($Value, '"(?:[^"\\]|\\.)*"')) {
+    $text = $match.Value
+    for ($i = 1; $i -lt $text.Length - 1; $i++) {
+      if ($text[$i] -cne '\') { continue }
+      if ($text[$i + 1] -cne 'u') { $i++; continue }
+      $code = [Convert]::ToInt32($text.Substring($i + 2, 4), 16)
+      if ($code -ge 0xd800 -and $code -le 0xdbff) {
+        if ($i + 12 -gt $text.Length - 1 -or $text.Substring($i + 6, 2) -cne '\u') { throw "INPUT_INVALID" }
+        $low = [Convert]::ToInt32($text.Substring($i + 8, 4), 16)
+        if ($low -lt 0xdc00 -or $low -gt 0xdfff) { throw "INPUT_INVALID" }
+        $i += 11
+      } elseif ($code -ge 0xdc00 -and $code -le 0xdfff) {
+        throw "INPUT_INVALID"
+      } else { $i += 5 }
+    }
+  }
+}
 
 try {
-  $buffer = New-Object char[] 513
+  $buffer = New-Object char[] 4097
   $size = 0
   while ($size -lt $buffer.Length) {
     $count = [Console]::In.Read($buffer, $size, $buffer.Length - $size)
     if ($count -eq 0) { break }
     $size += $count
   }
-  if ($size -gt 512) { throw "INPUT_INVALID" }
-  $inputData = (-join $buffer[0..($size - 1)]) | ConvertFrom-Json
-  $names = @($inputData.PSObject.Properties.Name)
-  if ($names.Count -ne 2 -or -not ($names -contains "kind") -or -not ($names -contains "sound") -or
-      $inputData.kind -isnot [string] -or $inputData.sound -isnot [bool]) { throw "INPUT_INVALID" }
-  $messages = @{
-    permission = "需要權限確認"
-    question = "有問題等待回答"
-    completed = "回應已完成"
-    aborted = "回應已中止"
-    failed = "回應失敗"
-  }
-  # PowerShell hashtable 預設不區分大小寫，先以 case-sensitive 比較鎖定 enum。
-  if (-not (@("permission", "question", "completed", "aborted", "failed") -ccontains $inputData.kind)) {
-    throw "INPUT_INVALID"
-  }
+  if ($size -eq 0 -or $size -gt 4096) { throw "INPUT_INVALID" }
+  $json = -join $buffer[0..($size - 1)]
+  Assert-JsonSurrogates $json
+  $inputData = $json | ConvertFrom-Json
+  Assert-Keys $inputData @("kind", "toast", "sound")
+  if ($inputData.kind -isnot [string] -or
+      @("permission", "question", "completed", "aborted", "failed") -cnotcontains $inputData.kind) { throw "INPUT_INVALID" }
+  Assert-Keys $inputData.toast @("enabled", "title", "message")
+  if ($inputData.toast.enabled -isnot [bool]) { throw "INPUT_INVALID" }
+  Assert-Text $inputData.toast.title 128
+  Assert-Text $inputData.toast.message 512
+  Assert-Keys $inputData.sound @("enabled", "source")
+  if ($inputData.sound.enabled -isnot [bool]) { throw "INPUT_INVALID" }
+  if ($inputData.sound.source.type -ceq "system") {
+    Assert-Keys $inputData.sound.source @("type", "name")
+    if ($inputData.sound.source.type -isnot [string] -or $inputData.sound.source.name -isnot [string] -or
+        @("Asterisk", "Beep", "Exclamation", "Hand", "Question") -cnotcontains $inputData.sound.source.name) { throw "INPUT_INVALID" }
+  } elseif ($inputData.sound.source.type -ceq "file") {
+    Assert-Keys $inputData.sound.source @("type", "path")
+    if ($inputData.sound.source.type -isnot [string]) { throw "INPUT_INVALID" }
+    Assert-SoundPath $inputData.sound.source.path
+  } else { throw "INPUT_INVALID" }
 }
 catch {
   Write-Result "INPUT_INVALID" $false "failed"
@@ -40,39 +85,53 @@ catch {
 
 $toastOk = $false
 $soundStatus = "disabled"
-try {
-  [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
-  [Windows.UI.Notifications.ToastNotification, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
-  $xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent(
-    [Windows.UI.Notifications.ToastTemplateType]::ToastText02)
-  $nodes = $xml.GetElementsByTagName("text")
-  $nodes.Item(0).AppendChild($xml.CreateTextNode("Pi")) | Out-Null
-  $nodes.Item(1).AppendChild($xml.CreateTextNode($messages[$inputData.kind])) | Out-Null
-  $audio = $xml.CreateElement("audio")
-  $audio.SetAttribute("silent", "true")
-  $xml.DocumentElement.AppendChild($audio) | Out-Null
-  $toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
-  $notifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("Microsoft.Windows.PowerShell")
-  $notifier.Show($toast)
-  $toastOk = $true
+if ($inputData.toast.enabled) {
+  try {
+    [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+    [Windows.UI.Notifications.ToastNotification, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+    $xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent(
+      [Windows.UI.Notifications.ToastTemplateType]::ToastText02)
+    $nodes = $xml.GetElementsByTagName("text")
+    $nodes.Item(0).AppendChild($xml.CreateTextNode($inputData.toast.title)) | Out-Null
+    $nodes.Item(1).AppendChild($xml.CreateTextNode($inputData.toast.message)) | Out-Null
+    $audio = $xml.CreateElement("audio")
+    $audio.SetAttribute("silent", "true")
+    $xml.DocumentElement.AppendChild($audio) | Out-Null
+    $toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
+    $notifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("Microsoft.Windows.PowerShell")
+    $notifier.Show($toast)
+    $toastOk = $true
+  }
+  catch { $toastOk = $false }
 }
-catch { $toastOk = $false }
 
-if ($inputData.sound) {
+if ($inputData.sound.enabled) {
   try {
-    if ($inputData.kind -ceq "completed") { [System.Media.SystemSounds]::Asterisk.Play() }
-    else { [System.Media.SystemSounds]::Exclamation.Play() }
+    if ($inputData.sound.source.type -ceq "file") {
+      Play-LocalWave $inputData.sound.source.path
+    } else {
+      # 固定 switch 不使用反射、動態 member access 或外部播放器。
+      switch -CaseSensitive ($inputData.sound.source.name) {
+        "Asterisk" { [System.Media.SystemSounds]::Asterisk.Play() }
+        "Beep" { [System.Media.SystemSounds]::Beep.Play() }
+        "Exclamation" { [System.Media.SystemSounds]::Exclamation.Play() }
+        "Hand" { [System.Media.SystemSounds]::Hand.Play() }
+        "Question" { [System.Media.SystemSounds]::Question.Play() }
+      }
+      # Play 非同步；有界等待不保證聲音實際送達，也不建立其他播放器。
+      Start-Sleep -Milliseconds 750
+    }
     $soundStatus = "played"
-    # Play 非同步；有界等待不保證聲音實際送達，也不建立其他播放器。
-    Start-Sleep -Milliseconds 750
   }
   catch { $soundStatus = "failed" }
 }
 
-$code = if ($toastOk) {
-  if ($soundStatus -eq "failed") { "SOUND_FAILED" } else { "OK" }
+$toastFailed = $inputData.toast.enabled -and -not $toastOk
+$soundFailed = $inputData.sound.enabled -and $soundStatus -eq "failed"
+$code = if ($toastFailed) {
+  if ($soundFailed) { "BOTH_FAILED" } else { "TOAST_FAILED" }
 } else {
-  if ($soundStatus -eq "failed") { "BOTH_FAILED" } else { "TOAST_FAILED" }
+  if ($soundFailed) { "SOUND_FAILED" } else { "OK" }
 }
 Write-Result $code $toastOk $soundStatus
 if ($code -eq "OK") { exit 0 } else { exit 1 }

package/src/windows-sound.ps1

@@ -0,0 +1,110 @@
+# 本機 WAV 的獨立驗證與有界讀取；不執行路徑，也不使用 URL、COM 或外部播放器。
+function Assert-SoundPath {
+  param($Value)
+  if ($Value -isnot [string] -or $Value.Length -gt 1024 -or
+      $Value -notmatch '^[a-zA-Z]:[\\/]' -or $Value -notmatch '(?i)\.wav$' -or
+      $Value -match '[\x00-\x1f\x7f-\x9f\u2028\u2029\ufffe\uffff]' -or
+      $Value.Substring(2) -match '[<>:"|?*]') { throw "INPUT_INVALID" }
+  [System.Xml.XmlConvert]::VerifyXmlChars($Value) | Out-Null
+  foreach ($part in ($Value.Substring(3) -split '[\\/]')) {
+    if ($part.Length -eq 0 -or $part -match '[. ]$' -or
+        $part -match '(?i)^(con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(\.|$)') { throw "INPUT_INVALID" }
+  }
+}
+
+function Assert-Wave {
+  param([byte[]]$Bytes)
+  # 僅接受 RIFF PCM：mono／stereo、8／16 bit、8–48 kHz，最多五秒。
+  if ($Bytes.Length -lt 44 -or $Bytes.Length -gt 5242880 -or
+      [Text.Encoding]::ASCII.GetString($Bytes, 0, 4) -cne "RIFF" -or
+      [Text.Encoding]::ASCII.GetString($Bytes, 8, 4) -cne "WAVE" -or
+      [BitConverter]::ToUInt32($Bytes, 4) -ne $Bytes.Length - 8) { throw "SOUND_FAILED" }
+  $offset = 12
+  $rate = 0
+  $alignment = 0
+  $dataSize = 0
+  $hasFormat = $false
+  $hasData = $false
+  while ($offset -lt $Bytes.Length) {
+    if ($Bytes.Length - $offset -lt 8) { throw "SOUND_FAILED" }
+    $tag = [Text.Encoding]::ASCII.GetString($Bytes, $offset, 4)
+    $size = [long][BitConverter]::ToUInt32($Bytes, $offset + 4)
+    $start = $offset + 8
+    $end = $start + $size + ($size % 2)
+    if ($end -gt $Bytes.Length) { throw "SOUND_FAILED" }
+    if ($tag -ceq "fmt ") {
+      if ($hasFormat -or ($size -ne 16 -and $size -ne 18)) { throw "SOUND_FAILED" }
+      if ([BitConverter]::ToUInt16($Bytes, $start) -ne 1 -or
+          ($size -eq 18 -and [BitConverter]::ToUInt16($Bytes, $start + 16) -ne 0)) { throw "SOUND_FAILED" }
+      $channels = [BitConverter]::ToUInt16($Bytes, $start + 2)
+      $sampleRate = [BitConverter]::ToUInt32($Bytes, $start + 4)
+      $rate = [BitConverter]::ToUInt32($Bytes, $start + 8)
+      $alignment = [BitConverter]::ToUInt16($Bytes, $start + 12)
+      $bits = [BitConverter]::ToUInt16($Bytes, $start + 14)
+      if (@(1, 2) -notcontains $channels -or @(8, 16) -notcontains $bits -or
+          $sampleRate -lt 8000 -or $sampleRate -gt 48000 -or
+          $alignment -ne $channels * ($bits / 8) -or $rate -ne $sampleRate * $alignment) { throw "SOUND_FAILED" }
+      $hasFormat = $true
+    } elseif ($tag -ceq "data") {
+      if (-not $hasFormat -or $hasData -or $size -eq 0) { throw "SOUND_FAILED" }
+      $dataSize = $size
+      $hasData = $true
+    }
+    $offset = [int]$end
+  }
+  if (-not $hasFormat -or -not $hasData -or $dataSize % $alignment -ne 0 -or
+      $dataSize -gt [long]$rate * 5) { throw "SOUND_FAILED" }
+}
+
+function Read-LocalWave {
+  param([string]$Path)
+  Assert-SoundPath $Path
+  # 拒絕網路磁碟及每一層 reparse point，避免一般 junction／symlink 指向遠端。
+  $fullPath = [IO.Path]::GetFullPath($Path)
+  $drive = [IO.DriveInfo]::new([IO.Path]::GetPathRoot($fullPath))
+  if ($drive.DriveType -ne [IO.DriveType]::Fixed) { throw "SOUND_FAILED" }
+  # 由磁碟根目錄往下檢查，不能先存取可能經由 junction 指向遠端的完整路徑。
+  $root = [IO.Path]::GetPathRoot($fullPath)
+  $current = $root
+  $parts = @("") + ($fullPath.Substring($root.Length) -split '\\')
+  foreach ($part in $parts) {
+    if ($part.Length -gt 0) { $current = [IO.Path]::Combine($current, $part) }
+    $attributes = [IO.File]::GetAttributes($current)
+    if (($attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0 -or
+        ($current -eq $fullPath -and ($attributes -band [IO.FileAttributes]::Directory) -ne 0)) { throw "SOUND_FAILED" }
+  }
+  $stream = $null
+  try {
+    # 開啟後不允許其他程序寫入或刪除；只從同一個 handle 讀入有界記憶體。
+    $stream = [IO.FileStream]::new($fullPath, [IO.FileMode]::Open, [IO.FileAccess]::Read, [IO.FileShare]::Read)
+    if ($stream.Length -lt 44 -or $stream.Length -gt 5242880) { throw "SOUND_FAILED" }
+    $bytes = New-Object byte[] ([int]$stream.Length)
+    $offset = 0
+    while ($offset -lt $bytes.Length) {
+      $count = $stream.Read($bytes, $offset, $bytes.Length - $offset)
+      if ($count -eq 0) { throw "SOUND_FAILED" }
+      $offset += $count
+    }
+    Assert-Wave $bytes
+    # PowerShell 不可逐 byte 展開管線，保持 byte[] 型別。
+    return ,$bytes
+  } finally {
+    if ($null -ne $stream) { $stream.Dispose() }
+  }
+}
+
+function Play-LocalWave {
+  param([string]$Path)
+  $bytes = Read-LocalWave $Path
+  $memory = $null
+  $player = $null
+  try {
+    $memory = [IO.MemoryStream]::new($bytes, $false)
+    $player = [System.Media.SoundPlayer]::new($memory)
+    $player.Load()
+    $player.PlaySync()
+  } finally {
+    if ($null -ne $player) { $player.Dispose() }
+    if ($null -ne $memory) { $memory.Dispose() }
+  }
+}