pi-usereq 0.5.0 → 0.7.0

package/pi-usereq/docs/WORKFLOW.md

@@ -514,7 +514,7 @@
             - `registerPromptCommands(...)`: register bundled `req-*` prompt commands [`src/index.ts`]
             - `registerAgentTools(...)`: register structured agent tools [`src/index.ts`]
             - `registerConfigCommands(...)`: register configuration commands [`src/index.ts`]
-            - `registerPiNotifyShortcut(...)`: register the configured successful-run sound shortcut when the runtime supports shortcuts [`src/index.ts`]
+            - `registerPiNotifyShortcut(...)`: register the configured sound-level shortcut when the runtime supports shortcuts [`src/index.ts`]
               - `loadProjectConfig(...)`: load the current project config for shortcut registration [`src/index.ts`]
                 - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
                 - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
@@ -561,33 +561,40 @@
             - `refreshContextUsage(...)`: sync the latest context-usage snapshot [`src/core/extension-status.ts`]
               - `RecordingCommandContext.getContextUsage(...)`: return the offline context-usage placeholder [`scripts/lib/recording-extension-api.ts`]
             - `syncPiUsereqStatusTicker(...)`: start or stop the live elapsed ticker [`src/core/extension-status.ts`]
-            - `renderPiUsereqStatus(...)`: render the base/context/elapsed/beep/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+            - `renderPiUsereqStatus(...)`: render the base/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
               - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
               - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics [`src/core/extension-status.ts`]
                 - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
                 - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
-                - `formatContextUsageBar(...)`: render the 10-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
-                  - `resolveContextUsageOverlay(...)`: choose `◀ CLEAR ▶ ` or ` ◀ FULL ▶ ` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
-                  - `formatContextUsageOverlay(...)`: paint the fixed-width overlay with preserved bar background [`src/core/extension-status.ts`]
+                - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
+                  - `resolveContextUsageIconText(...)`: map normalized context usage to the fixed-width gauge icon [`src/core/extension-status.ts`]
                 - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
                   - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
                   - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
-                - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
-          - `runPiNotifyEffects(...)`: dispatch configured terminal beeps and successful-run sound hooks on `agent_end` [`src/core/pi-notify.ts`]
-            - `classifyPiNotifyOutcome(...)`: map assistant stop reasons to `end`, `esc`, or `err` [`src/core/pi-notify.ts`]
+          - `runPiNotifyEffects(...)`: dispatch configured command-notify, sound, and optional Pushover hooks on `agent_end` [`src/core/pi-notify.ts`]
+            - `classifyPiNotifyOutcome(...)`: map assistant stop reasons to `completed`, `interrupted`, or `failed` [`src/core/pi-notify.ts`]
               - `hasAgentEndStopReason(...)`: scan assistant stop reasons inside the `agent_end` payload [`src/core/pi-notify.ts`]
-            - `buildPiNotifyTitle(...)`: build the stable pi-notify title [`src/core/pi-notify.ts`]
-            - `buildPiNotifyBody(...)`: build the stable pi-notify body from the classified outcome [`src/core/pi-notify.ts`]
-            - `notifyPiTerminal(...)`: route terminal notifications by runtime environment when the matching beep flag is enabled [`src/core/pi-notify.ts`]
-              - `notifyWindows(...)`: emit Windows toast notifications [`src/core/pi-notify.ts`]
-              - `notifyOSC99(...)`: emit Kitty OSC 99 notifications [`src/core/pi-notify.ts`]
-              - `notifyOSC9(...)`: emit OSC 9 notifications [`src/core/pi-notify.ts`]
-              - `notifyOSC777(...)`: emit OSC 777 notifications [`src/core/pi-notify.ts`]
-            - `runPiNotifySoundCommand(...)`: execute the configured successful-run sound command when sound is enabled [`src/core/pi-notify.ts`]
+            - `shouldRunPiNotifyCommand(...)`: validate prompt-scoped command-notify prerequisites [`src/core/pi-notify.ts`]
+              - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
+            - `runPiNotifyCommand(...)`: execute `PI_NOTIFY_CMD` with runtime placeholder substitution [`src/core/pi-notify.ts`]
+              - `substitutePiNotifyShellTemplate(...)`: replace installation, prompt, base, time, args, and result placeholders inside the shell template [`src/core/pi-notify.ts`]
+                - `buildPiNotifyRuntimeTemplateValues(...)`: resolve raw prompt-scoped placeholder values [`src/core/pi-notify.ts`]
+                  - `formatPiNotifyBasePath(...)`: render `%%BASE%%` as `~`-relative when possible [`src/core/pi-notify.ts`]
+                  - `formatPiNotifyDuration(...)`: render `%%TIME%%` as `M:SS` [`src/core/pi-notify.ts`]
+                  - `formatPiNotifyResult(...)`: map prompt-end outcomes to `successed|aborted|failed` [`src/core/pi-notify.ts`]
+                - `substitutePiNotifyInstallPath(...)`: replace `%%INSTALLATION_PATH%%` before shell execution [`src/core/pi-notify.ts`]
+                  - `quotePiNotifyInstallPath(...)`: quote the installation path for shell reuse [`src/core/pi-notify.ts`]
+                - `escapePiNotifyShellTemplateValue(...)`: escape prompt-scoped values for double-quoted shell insertion [`src/core/pi-notify.ts`]
+              - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+              - `runPiNotifyShellCommand(...)`: spawn one detached shell command [`src/core/pi-notify.ts`]
+            - `shouldRunPiNotifySound(...)`: validate sound level plus the matching event toggle [`src/core/pi-notify.ts`]
+              - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
+            - `runPiNotifySoundCommand(...)`: execute the configured sound command when the sound level and matching event toggle permit delivery [`src/core/pi-notify.ts`]
               - `resolvePiNotifySoundCommand(...)`: select the configured command for `low`, `mid`, or `high` [`src/core/pi-notify.ts`]
               - `substitutePiNotifyInstallPath(...)`: replace `%%INSTALLATION_PATH%%` before shell execution [`src/core/pi-notify.ts`]
                 - `quotePiNotifyInstallPath(...)`: quote the installation path for shell reuse [`src/core/pi-notify.ts`]
-                - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+              - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+              - `runPiNotifyShellCommand(...)`: spawn one detached shell command [`src/core/pi-notify.ts`]
     - `replayCommand(...)`: replay a recorded command handler and capture prompt/UI side effects [`scripts/lib/extension-debug-harness.ts`]
       - `registerExtensionOffline(...)`: rebuild the recorded extension registration surface [`scripts/lib/extension-debug-harness.ts`]
       - `RecordingCommandContext(...)`: initialize the recorded command-context UI adapter and deterministic theme-color encoding [`scripts/lib/recording-extension-api.ts`]
@@ -600,7 +607,7 @@
           - External boundaries: `RecordingExtensionAPI.sendUserMessage(...)` records the delivered prompt payload.
         - `configurePiUsereq(...)`: execute the interactive configuration menu [`src/index.ts`]
           - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions plus the display-only config-path row [`src/index.ts`]
-            - `formatProjectConfigPathForMenu(...)`: format the current config path relative to the user home when possible [`src/index.ts`]
+            - `formatProjectConfigPathForMenu(...)`: format the current config path and rewrite a leading `$HOME` token to `~` for menu display [`src/index.ts`]
           - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for top-level and submenu actions [`src/core/settings-menu.ts`]
             - `formatPiUsereqSettingsMenuTitle(...)`: rebuild the menu title with active-theme semantics [`src/core/settings-menu.ts`]
             - `buildPiUsereqSettingsListTheme(...)`: prefer shared CLI settings-list theming and fall back during offline replay [`src/core/settings-menu.ts`]
@@ -608,21 +615,27 @@
             - `buildSettingItems(...)`: map menu choices into settings-list rows and apply optional dim value tones [`src/core/settings-menu.ts`]
           - `saveProjectConfig(...)`: persist menu updates on save-and-close [`src/index.ts`]
           - `setPiUsereqStatusConfig(...)`: cache the saved config for footer rendering [`src/core/extension-status.ts`]
-          - `renderPiUsereqStatus(...)`: render the base/context/elapsed/beep/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
+          - `renderPiUsereqStatus(...)`: render the base/context/elapsed/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
             - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
-            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics [`src/core/extension-status.ts`]
+            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics and sound status fields [`src/core/extension-status.ts`]
               - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
               - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
-              - `formatContextUsageBar(...)`: render the 10-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
+              - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
               - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
                 - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
                 - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
-              - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
-          - `configureStaticCheckMenu(...)`: interactive static-check editor [`src/index.ts`]
-          - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor [`src/index.ts`]
-          - `configurePiNotifyMenu(...)`: interactive pi-notify editor [`src/index.ts`]
-            - `buildPiNotifyMenuChoices(...)`: serialize notification actions for the shared settings menu [`src/index.ts`]
-            - `togglePiNotifyBeepFlag(...)`: toggle one prompt-end beep flag [`src/index.ts`]
+          - `configureStaticCheckMenu(...)`: interactive guided static-check editor [`src/index.ts`]
+          - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor without a status-reference action [`src/index.ts`]
+          - `configurePiNotifyMenu(...)`: interactive notify, sound, and Pushover editor with dedicated event submenus [`src/index.ts`]
+            - `buildPiNotifyMenuChoices(...)`: serialize command-notify, sound, and Pushover blocks plus shared-event submenu launchers [`src/index.ts`]
+              - `buildPiNotifyEventLauncherChoice(...)`: serialize one event-submenu launcher row with a compact enabled-toggle summary [`src/index.ts`]
+              - `buildPiNotifyPushoverRows(...)`: serialize direct Pushover rows plus the shared event-submenu launcher [`src/index.ts`]
+            - `configurePiNotifyEventMenu(...)`: interactive completed/interrupted/failed event editor for one notification transport [`src/index.ts`]
+              - `buildPiNotifyEventMenuChoices(...)`: serialize shared event rows plus submenu reset/save actions [`src/index.ts`]
+              - `resetPiNotifyEventMenuToDefaults(...)`: restore default event toggles for one notification transport [`src/index.ts`]
+              - `resolvePiNotifyEventLabel(...)`: map one event-toggle key to the human-readable menu label [`src/index.ts`]
+              - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
+            - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
     - `replayTool(...)`: replay a recorded tool execute handler and capture content/details [`scripts/lib/extension-debug-harness.ts`]
       - `registerExtensionOffline(...)`: rebuild the recorded extension registration surface [`scripts/lib/extension-debug-harness.ts`]
       - `RecordingCommandContext(...)`: initialize the recorded command-context UI adapter and deterministic theme-color encoding [`scripts/lib/recording-extension-api.ts`]
@@ -633,6 +646,8 @@
         - `buildTokenToolPayload(...)`: construct agent-oriented token JSON with separated source facts, metrics, and guidance [`src/core/token-counter.ts`]
           - `probeRequestedPath(...)`: classify requested paths as readable files, missing inputs, or non-file inputs [`src/core/token-counter.ts`]
           - `countFilesMetrics(...)`: read readable files and extract token, character, byte, line, heading, and optional Doxygen facts [`src/core/token-counter.ts`]
+            - `TokenCounter(...)`: lazily resolve `js-tiktoken` only when token counting executes [`src/core/token-counter.ts`]
+              - `loadJsTiktokenModule(...)`: convert missing tokenizer dependencies into deterministic `ReqError` failures [`src/core/token-counter.ts`]
             - `buildCountFileMetricsResult(...)`: assemble direct-access per-file metrics and metadata [`src/core/token-counter.ts`]
               - `TokenCounter.countTokens(...)`: encode content and count tokens [`src/core/token-counter.ts`]
               - `TokenCounter.countChars(...)`: count characters [`src/core/token-counter.ts`]
@@ -641,17 +656,19 @@
               - `extractPrimaryHeadingText(...)`: extract the first markdown heading when present [`src/core/token-counter.ts`]
               - `extractLeadingDoxygenFields(...)`: extract file-level Doxygen fields when present [`src/core/token-counter.ts`]
                 - `parseDoxygenComment(...)`: parse normalized Doxygen fields [`src/core/doxygen-parser.ts`]
-          - `orderPathsByMetric(...)`: derive stable counted-path orderings for guidance [`src/core/token-counter.ts`]
         - `buildTokenToolExecuteResult(...)`: wrap token payloads into tool content and structured details [`src/index.ts`]
           - `buildTokenToolExecutionStderr(...)`: serialize skipped and error observations into stderr text [`src/index.ts`]
           - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-        - `buildReferenceToolPayload(...)`: construct agent-oriented references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
+        - `buildFailedTokenToolExecuteResult(...)`: normalize pre-payload token failures into the stable structured token-tool response shape [`src/index.ts`]
+          - `normalizeToolFailure(...)`: convert `ReqError` failures into deterministic execution metadata [`src/core/agent-tool-json.ts`]
+          - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
+        - `buildReferenceToolPayload(...)`: construct token-optimized references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
           - `canonicalizeReferencePath(...)`: normalize request and file paths against the project base [`src/core/reference-payload.ts`]
           - `analyzeReferenceFile(...)`: analyze one processable file into structured imports, symbols, and comments [`src/core/reference-payload.ts`]
           - `buildRepositoryTree(...)`: materialize the repository directory tree as structured JSON [`src/core/reference-payload.ts`]
         - `buildReferenceToolExecuteResult(...)`: wrap references payloads into tool content and structured details [`src/index.ts`]
           - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-        - `buildCompressToolPayload(...)`: construct agent-oriented compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
+        - `buildCompressToolPayload(...)`: construct token-optimized compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
           - `analyzeCompressFile(...)`: compress one requested file and attach symbol metadata when available [`src/core/compress-payload.ts`]
             - `compressFileDetailed(...)`: compress one file into structured lines and rendered text [`src/core/compress.ts`]
             - `analyzeCompressedFileSymbols(...)`: extract symbol and Doxygen records for compressed files [`src/core/compress-payload.ts`]
@@ -661,7 +678,7 @@
         - `buildFindToolSchemaDescription(...)`: synthesize find parameter-schema descriptions [`src/index.ts`]
         - `buildFindToolPromptGuidelines(...)`: synthesize agent-oriented find guidance strings [`src/index.ts`]
           - `buildFindToolSupportedTagGuidelines(...)`: emit per-language supported-tag guidance lines [`src/index.ts`]
-        - `buildFindToolPayload(...)`: construct agent-oriented construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
+        - `buildFindToolPayload(...)`: construct token-optimized construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
           - `validateTagFilter(...)`: normalize requested construct tags [`src/core/find-payload.ts`]
           - `validateRegexPattern(...)`: compile the construct-name regex [`src/core/find-payload.ts`]
           - `analyzeFindFile(...)`: analyze one requested file into structured search status and match records [`src/core/find-payload.ts`]
@@ -672,20 +689,20 @@
           - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
         - `runGitPath(...)`: query the resolved git-path value [`src/core/tool-runner.ts`]
         - `runGetBasePath(...)`: query the resolved base-path value [`src/core/tool-runner.ts`]
-        - `buildPathQueryToolPayload(...)`: structure path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
+        - `buildPathQueryToolPayload(...)`: structure token-optimized path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
         - `runFilesStaticCheck(...)`: execute configured checkers for explicit-file requests [`src/core/tool-runner.ts`]
         - `collectProjectStaticCheckSelection(...)`: derive project static-check file selections and fixture exclusions [`src/index.ts`]
         - `runProjectStaticCheck(...)`: execute configured checkers for project source and test selections [`src/core/tool-runner.ts`]
-        - `buildStaticCheckToolPayload(...)`: structure static-check request, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
+        - `buildStaticCheckToolPayload(...)`: structure token-optimized static-check summary, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
         - `runGitCheck(...)`: validate runtime repository cleanliness [`src/core/tool-runner.ts`]
-        - `buildGitCheckToolPayload(...)`: structure git-validation status and execution facts [`src/core/agent-tool-json.ts`]
-        - `buildDocsCheckToolPayload(...)`: structure canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
+        - `buildGitCheckToolPayload(...)`: structure token-optimized git-validation status and execution facts [`src/core/agent-tool-json.ts`]
+        - `buildDocsCheckToolPayload(...)`: structure token-optimized canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
         - `runGitWtName(...)`: generate the standardized worktree name [`src/core/tool-runner.ts`]
-        - `buildWorktreeNameToolPayload(...)`: structure worktree-name generation facts [`src/core/agent-tool-json.ts`]
+        - `buildWorktreeNameToolPayload(...)`: structure token-optimized worktree-name generation facts [`src/core/agent-tool-json.ts`]
         - `runGitWtCreate(...)`: create a dedicated worktree and branch [`src/core/tool-runner.ts`]
         - `runGitWtDelete(...)`: delete a dedicated worktree and branch [`src/core/tool-runner.ts`]
-        - `buildWorktreeMutationToolPayload(...)`: structure worktree create/delete facts [`src/core/agent-tool-json.ts`]
-        - `buildToolExecutionSection(...)`: normalize stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
+        - `buildWorktreeMutationToolPayload(...)`: structure token-optimized worktree create-delete facts [`src/core/agent-tool-json.ts`]
+        - `buildToolExecutionSection(...)`: normalize residual stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
         - `normalizeToolFailure(...)`: convert `ReqError` failures into structured execution records [`src/core/agent-tool-json.ts`]
     - `runSdkSmoke(...)`: replay offline `session_start`, probe the official SDK runtime, and compare inventories [`scripts/lib/sdk-smoke.ts`]
       - `replaySessionStart(...)`: capture the offline `session_start` contract [`scripts/lib/extension-debug-harness.ts`]
@@ -780,18 +797,14 @@
           - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
         - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
           - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
-      - `buildSharedRuntimePathFacts(...)`: derive shared runtime path facts for path, git, docs, worktree, and static-check payloads [`src/index.ts`]
-        - `buildRuntimePathContext(...)`: derive installation, execution, base, config, docs, tests, source, and git paths [`src/core/path-context.ts`]
-          - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
-          - `getConfigPath(...)`: derive the `.pi-usereq/config.json` path [`src/core/path-context.ts`]
-        - `buildRuntimePathFacts(...)`: convert runtime paths into payload-facing path strings [`src/core/path-context.ts`]
-          - `formatRuntimePathForDisplay(...)`: serialize user-home-relative paths with environment variables [`src/core/path-context.ts`]
       - `runGitPath(...)`: query the resolved git-path value [`src/core/tool-runner.ts`]
       - `runGetBasePath(...)`: query the resolved base-path value [`src/core/tool-runner.ts`]
-      - `buildPathQueryToolPayload(...)`: structure path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
-      - `buildTokenToolPayload(...)`: construct agent-oriented token JSON with separated source facts, metrics, and guidance [`src/core/token-counter.ts`]
+      - `buildPathQueryToolPayload(...)`: structure token-optimized path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
+      - `buildTokenToolPayload(...)`: construct token-optimized token JSON with direct-access source facts and metrics [`src/core/token-counter.ts`]
         - `probeRequestedPath(...)`: classify requested paths as readable files, missing inputs, or non-file inputs [`src/core/token-counter.ts`]
         - `countFilesMetrics(...)`: read readable files and extract token, character, byte, line, heading, and optional Doxygen facts [`src/core/token-counter.ts`]
+          - `TokenCounter(...)`: lazily resolve `js-tiktoken` only when token counting executes [`src/core/token-counter.ts`]
+            - `loadJsTiktokenModule(...)`: convert missing tokenizer dependencies into deterministic `ReqError` failures [`src/core/token-counter.ts`]
           - `buildCountFileMetricsResult(...)`: assemble direct-access per-file metrics and metadata [`src/core/token-counter.ts`]
             - `TokenCounter.countTokens(...)`: encode content and count tokens [`src/core/token-counter.ts`]
             - `TokenCounter.countChars(...)`: count characters [`src/core/token-counter.ts`]
@@ -800,17 +813,19 @@
             - `extractPrimaryHeadingText(...)`: extract the first markdown heading when present [`src/core/token-counter.ts`]
             - `extractLeadingDoxygenFields(...)`: extract file-level Doxygen fields when present [`src/core/token-counter.ts`]
               - `parseDoxygenComment(...)`: parse normalized Doxygen fields [`src/core/doxygen-parser.ts`]
-        - `orderPathsByMetric(...)`: derive stable counted-path orderings for guidance [`src/core/token-counter.ts`]
       - `buildTokenToolExecuteResult(...)`: wrap token payloads into tool content and structured details [`src/index.ts`]
         - `buildTokenToolExecutionStderr(...)`: serialize skipped and error observations into stderr text [`src/index.ts`]
         - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-      - `buildReferenceToolPayload(...)`: construct agent-oriented references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
+      - `buildFailedTokenToolExecuteResult(...)`: normalize pre-payload token failures into the stable structured token-tool response shape [`src/index.ts`]
+        - `normalizeToolFailure(...)`: convert `ReqError` failures into deterministic execution metadata [`src/core/agent-tool-json.ts`]
+        - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
+      - `buildReferenceToolPayload(...)`: construct token-optimized references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
         - `canonicalizeReferencePath(...)`: normalize request and file paths against the project base [`src/core/reference-payload.ts`]
         - `analyzeReferenceFile(...)`: analyze one processable file into structured imports, symbols, and comments [`src/core/reference-payload.ts`]
         - `buildRepositoryTree(...)`: materialize the repository directory tree as structured JSON [`src/core/reference-payload.ts`]
       - `buildReferenceToolExecuteResult(...)`: wrap references payloads into tool content and structured details [`src/index.ts`]
         - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-      - `buildCompressToolPayload(...)`: construct agent-oriented compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
+      - `buildCompressToolPayload(...)`: construct token-optimized compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
         - `analyzeCompressFile(...)`: compress one requested file and attach symbol metadata when available [`src/core/compress-payload.ts`]
           - `compressFileDetailed(...)`: compress one file into structured lines and rendered text [`src/core/compress.ts`]
           - `analyzeCompressedFileSymbols(...)`: extract symbol and Doxygen records for compressed files [`src/core/compress-payload.ts`]
@@ -820,7 +835,7 @@
       - `buildFindToolSchemaDescription(...)`: synthesize find parameter-schema descriptions [`src/index.ts`]
       - `buildFindToolPromptGuidelines(...)`: synthesize agent-oriented find guidance strings [`src/index.ts`]
         - `buildFindToolSupportedTagGuidelines(...)`: emit per-language supported-tag guidance lines [`src/index.ts`]
-      - `buildFindToolPayload(...)`: construct agent-oriented construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
+      - `buildFindToolPayload(...)`: construct token-optimized construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
         - `validateTagFilter(...)`: normalize requested construct tags [`src/core/find-payload.ts`]
         - `validateRegexPattern(...)`: compile the construct-name regex [`src/core/find-payload.ts`]
         - `analyzeFindFile(...)`: analyze one requested file into structured search status and match records [`src/core/find-payload.ts`]
@@ -832,16 +847,16 @@
       - `runFilesStaticCheck(...)`: execute configured checkers for explicit-file requests [`src/core/tool-runner.ts`]
       - `collectProjectStaticCheckSelection(...)`: derive project static-check file selections and fixture exclusions [`src/index.ts`]
       - `runProjectStaticCheck(...)`: execute configured checkers for project source and test selections [`src/core/tool-runner.ts`]
-      - `buildStaticCheckToolPayload(...)`: structure static-check request, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
+      - `buildStaticCheckToolPayload(...)`: structure token-optimized static-check summary, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
       - `runGitCheck(...)`: validate runtime repository cleanliness [`src/core/tool-runner.ts`]
-      - `buildGitCheckToolPayload(...)`: structure git-validation status and execution facts [`src/core/agent-tool-json.ts`]
-      - `buildDocsCheckToolPayload(...)`: structure canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
+      - `buildGitCheckToolPayload(...)`: structure token-optimized git-validation status and execution facts [`src/core/agent-tool-json.ts`]
+      - `buildDocsCheckToolPayload(...)`: structure token-optimized canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
       - `runGitWtName(...)`: generate the standardized worktree name [`src/core/tool-runner.ts`]
-      - `buildWorktreeNameToolPayload(...)`: structure worktree-name generation facts [`src/core/agent-tool-json.ts`]
+      - `buildWorktreeNameToolPayload(...)`: structure token-optimized worktree-name generation facts [`src/core/agent-tool-json.ts`]
       - `runGitWtCreate(...)`: create a dedicated worktree and branch [`src/core/tool-runner.ts`]
       - `runGitWtDelete(...)`: delete a dedicated worktree and branch [`src/core/tool-runner.ts`]
-      - `buildWorktreeMutationToolPayload(...)`: structure worktree create/delete facts [`src/core/agent-tool-json.ts`]
-      - `buildToolExecutionSection(...)`: normalize stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
+      - `buildWorktreeMutationToolPayload(...)`: structure token-optimized worktree create-delete facts [`src/core/agent-tool-json.ts`]
+      - `buildToolExecutionSection(...)`: normalize residual stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
       - `normalizeToolFailure(...)`: convert `ReqError` failures into structured execution records [`src/core/agent-tool-json.ts`]
     - `registerConfigCommands(...)`: register interactive configuration commands [`src/index.ts`]
       - `configurePiUsereq(...)`: interactive configuration menu root [`src/index.ts`]
@@ -858,7 +873,7 @@
           - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
         - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
           - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
-    - `registerPiNotifyShortcut(...)`: register the configured successful-run sound shortcut when the runtime supports shortcuts [`src/index.ts`]
+    - `registerPiNotifyShortcut(...)`: register the configured sound-level shortcut when the runtime supports shortcuts [`src/index.ts`]
       - `loadProjectConfig(...)`: load config for shortcut registration [`src/index.ts`]
         - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
         - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
@@ -892,38 +907,56 @@
         - `updateExtensionStatus(...)`: refresh stored context usage, elapsed timers, prompt-request state, cumulative runtime, and rendered status text [`src/core/extension-status.ts`]
           - `refreshContextUsage(...)`: sync the latest context-usage snapshot [`src/core/extension-status.ts`]
           - `syncPiUsereqStatusTicker(...)`: start or stop the live elapsed ticker [`src/core/extension-status.ts`]
-          - `renderPiUsereqStatus(...)`: render the base/context/elapsed/beep/sound/pushover footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+          - `renderPiUsereqStatus(...)`: render the base/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
             - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
-            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics plus the Pushover enable field [`src/core/extension-status.ts`]
+            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics and sound status fields [`src/core/extension-status.ts`]
               - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
               - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
-              - `formatContextUsageBar(...)`: render the 10-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
-                - `resolveContextUsageOverlay(...)`: choose `◀ CLEAR ▶ ` or ` ◀ FULL ▶ ` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
-                - `formatContextUsageOverlay(...)`: paint the fixed-width overlay with preserved bar background [`src/core/extension-status.ts`]
+              - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
+                - `resolveContextUsageIconText(...)`: map normalized context usage to the fixed-width gauge icon [`src/core/extension-status.ts`]
               - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
                 - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
                 - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
-              - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
-              - `formatPiNotifyPushoverStatus(...)`: serialize the dedicated Pushover enable flag for the footer [`src/core/pi-notify.ts`]
-        - `runPiNotifyEffects(...)`: dispatch configured terminal beeps, successful-run sound hooks, and optional Pushover API requests on `agent_end` [`src/core/pi-notify.ts`]
-          - `classifyPiNotifyOutcome(...)`: map assistant stop reasons to `end`, `esc`, or `err` [`src/core/pi-notify.ts`]
+        - `runPiNotifyEffects(...)`: dispatch configured command-notify, sound, and optional Pushover API requests on `agent_end` [`src/core/pi-notify.ts`]
+          - `classifyPiNotifyOutcome(...)`: map assistant stop reasons to `completed`, `interrupted`, or `failed` [`src/core/pi-notify.ts`]
             - `hasAgentEndStopReason(...)`: scan assistant stop reasons inside the `agent_end` payload [`src/core/pi-notify.ts`]
-          - `buildPiNotifyTitle(...)`: build the stable pi-notify title [`src/core/pi-notify.ts`]
-          - `buildPiNotifyBody(...)`: build the stable pi-notify body from the classified outcome [`src/core/pi-notify.ts`]
-          - `notifyPiTerminal(...)`: route terminal notifications by runtime environment when the matching beep flag is enabled [`src/core/pi-notify.ts`]
-            - `notifyWindows(...)`: emit Windows toast notifications [`src/core/pi-notify.ts`]
-            - `notifyOSC99(...)`: emit Kitty OSC 99 notifications [`src/core/pi-notify.ts`]
-            - `notifyOSC9(...)`: emit OSC 9 notifications [`src/core/pi-notify.ts`]
-            - `notifyOSC777(...)`: emit OSC 777 notifications [`src/core/pi-notify.ts`]
-          - `runPiNotifySoundCommand(...)`: execute the configured successful-run sound command when sound is enabled [`src/core/pi-notify.ts`]
+          - `shouldRunPiNotifyCommand(...)`: validate prompt-scoped command-notify prerequisites [`src/core/pi-notify.ts`]
+            - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
+          - `runPiNotifyCommand(...)`: execute `PI_NOTIFY_CMD` with runtime placeholder substitution [`src/core/pi-notify.ts`]
+            - `substitutePiNotifyShellTemplate(...)`: replace installation, prompt, base, time, args, and result placeholders inside the shell template [`src/core/pi-notify.ts`]
+              - `buildPiNotifyRuntimeTemplateValues(...)`: resolve raw prompt-scoped placeholder values [`src/core/pi-notify.ts`]
+                - `formatPiNotifyBasePath(...)`: render `%%BASE%%` as `~`-relative when possible [`src/core/pi-notify.ts`]
+                - `formatPiNotifyDuration(...)`: render `%%TIME%%` as `M:SS` [`src/core/pi-notify.ts`]
+                - `formatPiNotifyResult(...)`: map prompt-end outcomes to `successed|aborted|failed` [`src/core/pi-notify.ts`]
+              - `substitutePiNotifyInstallPath(...)`: replace `%%INSTALLATION_PATH%%` before shell execution [`src/core/pi-notify.ts`]
+                - `quotePiNotifyInstallPath(...)`: quote the installation path for shell reuse [`src/core/pi-notify.ts`]
+              - `escapePiNotifyShellTemplateValue(...)`: escape prompt-scoped values for double-quoted shell insertion [`src/core/pi-notify.ts`]
+            - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+            - `runPiNotifyShellCommand(...)`: spawn one detached shell command [`src/core/pi-notify.ts`]
+          - `shouldRunPiNotifySound(...)`: validate sound level plus the matching event toggle [`src/core/pi-notify.ts`]
+            - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
+          - `runPiNotifySoundCommand(...)`: execute the configured sound command when the sound level and matching event toggle permit delivery [`src/core/pi-notify.ts`]
             - `resolvePiNotifySoundCommand(...)`: select the configured command for `low`, `mid`, or `high` [`src/core/pi-notify.ts`]
             - `substitutePiNotifyInstallPath(...)`: replace `%%INSTALLATION_PATH%%` before shell execution [`src/core/pi-notify.ts`]
               - `quotePiNotifyInstallPath(...)`: quote the installation path for shell reuse [`src/core/pi-notify.ts`]
-              - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
-          - `runPiNotifyPushoverRequest(...)`: POST the successful prompt payload to the Pushover Message API when credentials and flags permit delivery [`src/core/pi-notify.ts`]
+            - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+            - `runPiNotifyShellCommand(...)`: spawn one detached shell command [`src/core/pi-notify.ts`]
+          - `shouldRunPiNotifyPushover(...)`: validate global Pushover enablement, the matching event toggle, and required credentials [`src/core/pi-notify.ts`]
+            - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
+          - `runPiNotifyPushoverRequest(...)`: POST the prompt-end payload to the Pushover Message API when credentials and flags permit delivery [`src/core/pi-notify.ts`]
             - `buildPiNotifyPushoverPayload(...)`: serialize token, user, title, priority, and message fields [`src/core/pi-notify.ts`]
-            - `buildPiNotifyPushoverTitle(...)`: compose `<prompt> @ <base-path> [<time>]` for successful completion [`src/core/pi-notify.ts`]
-            - `buildPiNotifyPushoverBody(...)`: reuse the raw prompt argument payload [`src/core/pi-notify.ts`]
+              - `buildPiNotifyPushoverTitle(...)`: resolve the configured Pushover title template [`src/core/pi-notify.ts`]
+                - `substitutePiNotifyTextTemplate(...)`: replace prompt-scoped placeholders inside the title template [`src/core/pi-notify.ts`]
+                  - `buildPiNotifyRuntimeTemplateValues(...)`: resolve raw prompt-scoped placeholder values [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyBasePath(...)`: render `%%BASE%%` as `~`-relative when possible [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyDuration(...)`: render `%%TIME%%` as `M:SS` [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyResult(...)`: map prompt-end outcomes to `successed|aborted|failed` [`src/core/pi-notify.ts`]
+              - `buildPiNotifyPushoverBody(...)`: resolve the configured Pushover text template [`src/core/pi-notify.ts`]
+                - `substitutePiNotifyTextTemplate(...)`: replace prompt-scoped placeholders inside the text template [`src/core/pi-notify.ts`]
+                  - `buildPiNotifyRuntimeTemplateValues(...)`: resolve raw prompt-scoped placeholder values [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyBasePath(...)`: render `%%BASE%%` as `~`-relative when possible [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyDuration(...)`: render `%%TIME%%` as `M:SS` [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyResult(...)`: map prompt-end outcomes to `successed|aborted|failed` [`src/core/pi-notify.ts`]
   - `configurePiUsereq(...)`: interactive configuration menu runtime root [`src/index.ts`]
     - `loadProjectConfig(...)`: load config and normalize persisted directory paths for command context [`src/index.ts`]
       - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
@@ -937,7 +970,7 @@
         - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
     - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
     - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions plus the display-only config-path row [`src/index.ts`]
-      - `formatProjectConfigPathForMenu(...)`: format the current config path relative to the user home when possible [`src/index.ts`]
+      - `formatProjectConfigPathForMenu(...)`: format the current config path and rewrite a leading `$HOME` token to `~` for menu display [`src/index.ts`]
     - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for top-level and submenu actions [`src/core/settings-menu.ts`]
       - `formatPiUsereqSettingsMenuTitle(...)`: rebuild the menu title with active-theme semantics [`src/core/settings-menu.ts`]
       - `buildPiUsereqSettingsListTheme(...)`: prefer shared CLI settings-list theming and fall back during offline replay [`src/core/settings-menu.ts`]
@@ -948,40 +981,28 @@
       - `saveConfig(...)`: persist config JSON [`src/core/config.ts`]
         - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
     - `setPiUsereqStatusConfig(...)`: cache the just-saved docs/tests/src and pi-notify values for status rendering [`src/core/extension-status.ts`]
-    - `renderPiUsereqStatus(...)`: render the base/context/elapsed/beep/sound/pushover footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
+    - `renderPiUsereqStatus(...)`: render the base/context/elapsed/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
       - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
-      - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics plus the Pushover enable field [`src/core/extension-status.ts`]
+      - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics and sound status fields [`src/core/extension-status.ts`]
         - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
         - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
-        - `formatContextUsageBar(...)`: render the 10-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
-          - `resolveContextUsageOverlay(...)`: choose `◀ CLEAR ▶ ` or ` ◀ FULL ▶ ` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
-          - `formatContextUsageOverlay(...)`: paint the fixed-width overlay with preserved bar background [`src/core/extension-status.ts`]
+        - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
+          - `resolveContextUsageIconText(...)`: map normalized context usage to the fixed-width gauge icon [`src/core/extension-status.ts`]
         - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
           - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
           - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
-        - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
-    - `configureStaticCheckMenu(...)`: interactive static-check editor [`src/index.ts`]
+    - `configureStaticCheckMenu(...)`: interactive guided static-check editor [`src/index.ts`]
       - `formatStaticCheckLanguagesSummary(...)`: summarize configured checker languages [`src/index.ts`]
-      - `renderStaticCheckReference(...)`: render static-check reference text [`src/index.ts`]
-        - `formatStaticCheckLanguagesSummary(...)`: summarize configured checker languages [`src/index.ts`]
-        - `formatStaticCheckEntry(...)`: format one configured checker entry [`src/index.ts`]
+      - `buildStaticCheckMenuChoices(...)`: serialize guided add/remove/reset static-check actions [`src/index.ts`]
+      - `buildSupportedStaticCheckLanguageChoices(...)`: serialize supported languages with configured counts [`src/index.ts`]
         - `getSupportedStaticCheckLanguageSupport(...)`: enumerate supported languages and extensions [`src/core/static-check.ts`]
           - `getSupportedStaticCheckLanguages(...)`: enumerate canonical supported languages [`src/core/static-check.ts`]
-      - `buildSupportedStaticCheckLanguageChoices(...)`: serialize supported languages with configured counts [`src/index.ts`]
       - `shellSplit(...)`: parse optional parameter input [`src/core/utils.ts`]
-      - `parseEnableStaticCheck(...)`: parse `LANG=Command,CMD[,PARAM...]` specification [`src/core/static-check.ts`]
-        - `splitCsvLikeTokens(...)`: split comma-like spec payload with quoting support [`src/core/static-check.ts`]
-        - `formatStaticCheckModules(...)`: render valid user modules for error paths [`src/core/static-check.ts`]
-    - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor [`src/index.ts`]
+    - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor without a status-reference action [`src/index.ts`]
       - `applyConfiguredPiUsereqTools(...)`: enforce configured active-tool set [`src/index.ts`]
         - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
           - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
         - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
-      - `renderPiUsereqToolsReference(...)`: render configurable active-tool reference text [`src/index.ts`]
-        - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
-        - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
-          - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
-        - `getPiUsereqToolKind(...)`: classify builtin versus extension tools for UI rendering [`src/index.ts`]
       - `setConfiguredPiUsereqTools(...)`: persist selected enabled tools in memory [`src/index.ts`]
         - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
         - `applyConfiguredPiUsereqTools(...)`: enforce configured active-tool set [`src/index.ts`]
@@ -989,13 +1010,19 @@
             - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
           - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
       - `buildPiUsereqToolToggleChoices(...)`: serialize per-tool startup-toggle rows [`src/index.ts`]
-        - `getPiUsereqToolKind(...)`: classify builtin versus extension tools for UI rendering [`src/index.ts`]
-    - `configurePiNotifyMenu(...)`: interactive pi-notify editor [`src/index.ts`]
-      - `buildPiNotifyMenuChoices(...)`: serialize notification actions plus the nested Pushover submenu entry for the shared settings menu [`src/index.ts`]
-      - `togglePiNotifyBeepFlag(...)`: toggle one prompt-end beep flag [`src/index.ts`]
-      - `configurePiNotifyPushoverMenu(...)`: interactive Pushover editor nested under the notifications menu [`src/index.ts`]
-        - `buildPiNotifyPushoverMenuChoices(...)`: serialize Pushover global-disable, enable, credential, and priority actions [`src/index.ts`]
-        - `selectPiNotifyPushoverPriority(...)`: present the `0=Normal` and `1=High Priority` selector [`src/index.ts`]
+    - `configurePiNotifyMenu(...)`: interactive notify, sound, and Pushover editor with dedicated event submenus [`src/index.ts`]
+      - `buildPiNotifyMenuChoices(...)`: serialize command-notify, sound, and Pushover blocks plus shared-event submenu launchers [`src/index.ts`]
+        - `buildPiNotifyEventLauncherChoice(...)`: serialize one event-submenu launcher row with a compact enabled-toggle summary [`src/index.ts`]
+        - `buildPiNotifyPushoverRows(...)`: serialize direct Pushover rows plus the shared event-submenu launcher [`src/index.ts`]
+      - `configurePiNotifyEventMenu(...)`: interactive completed/interrupted/failed event editor for one notification transport [`src/index.ts`]
+        - `buildPiNotifyEventMenuChoices(...)`: serialize shared event rows plus submenu reset/save actions [`src/index.ts`]
+        - `resetPiNotifyEventMenuToDefaults(...)`: restore default event toggles for one notification transport [`src/index.ts`]
+        - `resolvePiNotifyEventLabel(...)`: map one event-toggle key to the human-readable menu label [`src/index.ts`]
+        - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
+      - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
+      - `selectPiNotifySoundLevel(...)`: present the `Enable sound` selector [`src/index.ts`]
+      - `selectPiNotifyPushoverPriority(...)`: present the `Normal|High` priority selector [`src/index.ts`]
+      - `resetPiNotifyConfigToDefaults(...)`: restore notification settings to documented defaults [`src/index.ts`]
     - `getDefaultConfig(...)`: restore default config on reset [`src/core/config.ts`]
       - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
     - `applyConfiguredPiUsereqTools(...)`: re-apply active tools after reset [`src/index.ts`]