pi-usereq 0.5.0 → 0.7.0

package/src/index.ts

@@ -8,7 +8,7 @@
  * @brief Declares the extension version string.
  * @details The value is exported for external inspection and packaging metadata alignment. Access complexity is O(1).
  */
-export const VERSION = "0.5.0"
+export const VERSION = "0.7.0"
 
 import path from "node:path";
 import type {
@@ -52,6 +52,7 @@ import {
   type FindToolScope,
 } from "./core/find-payload.js";
 import {
+  DEFAULT_SRC_DIRS,
   getDefaultConfig,
   getProjectConfigPath,
   loadConfig,
@@ -61,21 +62,25 @@ import {
   type UseReqConfig,
 } from "./core/config.js";
 import {
+  DEFAULT_PI_NOTIFY_CMD,
+  DEFAULT_PI_NOTIFY_PUSHOVER_TEXT,
+  DEFAULT_PI_NOTIFY_PUSHOVER_TITLE,
+  DEFAULT_PI_NOTIFY_SOUND_HIGH_CMD,
+  DEFAULT_PI_NOTIFY_SOUND_LOW_CMD,
+  DEFAULT_PI_NOTIFY_SOUND_MID_CMD,
   cyclePiNotifySoundLevel,
-  formatPiNotifyBeepStatus,
   formatPiNotifyPushoverStatus,
+  formatPiNotifyStatus,
+  normalizePiNotifyCommand,
   normalizePiNotifyPushoverCredential,
   normalizePiNotifyPushoverPriority,
+  normalizePiNotifyTemplateValue,
   runPiNotifyEffects,
+  type PiNotifyEventRequest,
   type PiNotifyPushoverPriority,
-  type PiNotifyPushoverRequest,
   type PiNotifySoundLevel,
 } from "./core/pi-notify.js";
-import {
-  buildRuntimePathContext,
-  buildRuntimePathFacts,
-  formatRuntimePathForDisplay,
-} from "./core/path-context.js";
+import { formatRuntimePathForDisplay } from "./core/path-context.js";
 import { resolveRuntimeGitPath } from "./core/runtime-project-paths.js";
 import { showPiUsereqSettingsMenu, type PiUsereqSettingsMenuChoice } from "./core/settings-menu.js";
 import {
@@ -108,9 +113,7 @@ import {
 } from "./core/tool-runner.js";
 import { LANGUAGE_TAGS } from "./core/find-constructs.js";
 import {
-  STATIC_CHECK_MODULES,
   getSupportedStaticCheckLanguageSupport,
-  parseEnableStaticCheck,
 } from "./core/static-check.js";
 import { makeRelativeIfContainsProject, shellSplit } from "./core/utils.js";
 
@@ -164,20 +167,6 @@ function getProjectBase(cwd: string): string {
   return path.resolve(cwd);
 }
 
-/**
- * @brief Builds the shared runtime path facts for the current command or tool context.
- * @details Derives installation, execution, base, config, resource, docs, test, source, and optional git paths from the cwd-derived project configuration plus runtime-only repository probing, then converts them into prompt/tool-facing strings. Runtime is O(s + p) where s is configured source-directory count and p is aggregate path length. Side effects are limited to git subprocess execution.
- * @param[in] cwd {string} Current working directory.
- * @param[in] config {UseReqConfig} Effective project configuration.
- * @return {import("./core/path-context.js").RuntimePathFacts} Shared runtime path facts.
- * @satisfies REQ-145, REQ-146
- */
-function buildSharedRuntimePathFacts(cwd: string, config: UseReqConfig): import("./core/path-context.js").RuntimePathFacts {
-  const projectBase = getProjectBase(cwd);
-  const gitPath = resolveRuntimeGitPath(projectBase);
-  return buildRuntimePathFacts(buildRuntimePathContext(projectBase, config, { gitPath }));
-}
-
 /**
  * @brief Loads project configuration for the extension runtime.
  * @details Resolves the project base, loads persisted config, and normalizes configured directory paths without reading or persisting runtime-derived `base-path` or `git-path` metadata. Runtime is dominated by config I/O. Side effects are limited to filesystem reads.
@@ -205,15 +194,17 @@ function saveProjectConfig(cwd: string, config: UseReqConfig): void {
 
 /**
  * @brief Formats the current project config path for top-level menu display.
- * @details Resolves `<base-path>/.pi-usereq/config.json` from the cwd-derived
- * project base and formats it relative to the user home when possible. Runtime
- * is O(p) in path length. No external state is mutated.
+ * @details Resolves `<base-path>/.pi-usereq/config.json` from the cwd-derived project base, reuses the shared runtime-path formatter, and rewrites a leading POSIX `$HOME` token to `~` for the `Show configuration` row only. Runtime is O(p) in path length. No external state is mutated.
  * @param[in] cwd {string} Current working directory.
- * @return {string} User-home-relative or absolute config path display value.
+ * @return {string} `~`-relative or absolute config path display value.
  * @satisfies REQ-162
  */
 function formatProjectConfigPathForMenu(cwd: string): string {
-  return formatRuntimePathForDisplay(getProjectConfigPath(getProjectBase(cwd)));
+  const displayPath = formatRuntimePathForDisplay(getProjectConfigPath(getProjectBase(cwd)));
+  if (displayPath === "$HOME") {
+    return "~";
+  }
+  return displayPath.startsWith("$HOME/") ? `~/${displayPath.slice("$HOME/".length)}` : displayPath;
 }
 
 /**
@@ -263,10 +254,12 @@ function collectProjectStaticCheckSelection(
  * @return {string} Newline-delimited execution diagnostics.
  */
 function buildTokenToolExecutionStderr(payload: TokenToolPayload): string {
-  const skippedLines = payload.guidance.source_observations.skipped_inputs
-    .map((entry) => `skipped: ${entry.canonical_path}: ${entry.reason}`);
-  const errorLines = payload.guidance.source_observations.error_inputs
-    .map((entry) => `error: ${entry.canonical_path}: ${entry.reason}`);
+  const skippedLines = payload.files
+    .filter((entry) => entry.status === "skipped" && entry.error_message)
+    .map((entry) => `skipped: ${entry.canonical_path}: ${entry.error_message!}`);
+  const errorLines = payload.files
+    .filter((entry) => entry.status === "error" && entry.error_message)
+    .map((entry) => `error: ${entry.canonical_path}: ${entry.error_message!}`);
   return [...skippedLines, ...errorLines].join("\n");
 }
 
@@ -284,10 +277,8 @@ function buildTokenToolExecuteResult(
   details: TokenToolPayload & { execution: { code: number; stderr: string } };
 } {
   const details = {
-    request: payload.request,
     summary: payload.summary,
     files: payload.files,
-    guidance: payload.guidance,
     execution: {
       code: payload.summary.counted_file_count > 0 ? 0 : 1,
       stderr: buildTokenToolExecutionStderr(payload),
@@ -296,6 +287,43 @@ function buildTokenToolExecuteResult(
   return buildStructuredToolExecuteResult(details);
 }
 
+/**
+ * @brief Builds the fallback execute result returned when token counting fails before payload construction.
+ * @details Normalizes one thrown `ReqError` into the stable token-tool response shape so missing runtime dependencies or other pre-count failures do not abort extension tool execution. Runtime is O(1). No external state is mutated.
+ * @param[in] error {unknown} Thrown token-tool failure.
+ * @return {{ content: Array<{ type: "text"; text: string }>; details: TokenToolPayload & { execution: { code: number; stderr: string } } }} Structured token-tool failure result.
+ */
+function buildFailedTokenToolExecuteResult(
+  error: unknown,
+): {
+  content: Array<{ type: "text"; text: string }>;
+  details: TokenToolPayload & { execution: { code: number; stderr: string } };
+} {
+  const result = normalizeToolFailure(error);
+  const details = {
+    summary: {
+      processable_file_count: 0,
+      counted_file_count: 0,
+      error_file_count: 0,
+      skipped_file_count: 0,
+      total_token_count: 0,
+      total_character_count: 0,
+      total_byte_count: 0,
+      total_line_count: 0,
+      average_token_count_per_counted_file: 0,
+      average_character_count_per_counted_file: 0,
+      average_byte_count_per_counted_file: 0,
+      average_line_count_per_counted_file: 0,
+    },
+    files: [],
+    execution: {
+      code: result.code,
+      stderr: result.stderr,
+    },
+  };
+  return buildStructuredToolExecuteResult(details);
+}
+
 /**
  * @brief Builds the agent-oriented execute result returned by references tools.
  * @details Mirrors the structured references payload into both the text `content` channel and the machine-readable `details` channel while isolating execution metadata under `execution`. Runtime is O(n) in payload size. No side effects occur.
@@ -310,7 +338,6 @@ function buildReferenceToolExecuteResult(
   details: ReferenceToolPayload & { execution: { code: number; stderr: string } };
 } {
   const details = {
-    request: payload.request,
     summary: payload.summary,
     repository: payload.repository,
     files: payload.files,
@@ -336,7 +363,6 @@ function buildCompressionToolExecuteResult(
   details: CompressToolPayload & { execution: { code: number; stderr: string } };
 } {
   const details = {
-    request: payload.request,
     summary: payload.summary,
     repository: payload.repository,
     files: payload.files,
@@ -423,7 +449,7 @@ function buildFindToolSchemaDescription(scope: FindToolScope): string {
   const inputContract = scope === "explicit-files"
     ? "Input contract: tag + pattern + files[] + optional enableLineNumbers."
     : "Input contract: tag + pattern + optional enableLineNumbers. Scope is the configured src-dir list resolved from the current project configuration.";
-  return `${inputContract} Output contract: JSON object with request, summary, repository, files, and execution. Repository exposes file_canonical_paths and supported_tags_by_language. File entries expose path facts, supported_tags, structured statuses, file_doxygen, and match records with typed line ranges, stripped code lines, and structured Doxygen fields. Regex matches construct names only.`;
+  return `${inputContract} Output contract: JSON object with summary, repository, files, and execution. Static supported-tag matrices are documented in tool registration metadata instead of runtime responses. File entries expose structured statuses, file_doxygen, and match records with typed line ranges, stripped code lines, and structured Doxygen fields. Regex matches construct names only.`;
 }
 
 /**
@@ -437,13 +463,13 @@ function buildFindToolPromptGuidelines(scope: FindToolScope): string[] {
     ? "Scope: explicit source files selected by files[]; caller order is preserved; each item may be project-relative or absolute."
     : "Scope: resolve src-dir from the current project configuration and scan the configured source surface from the current working directory.";
   const outputLine = scope === "explicit-files"
-    ? "Output contract: request + summary + repository + files + execution. Repository exposes requested file scope and supported_tags_by_language; file entries expose status, supported_tags, line ranges, file_doxygen, and matches; match entries expose symbol_kind, signature_text, line ranges, code_lines, stripped_source_text, and structured Doxygen fields."
-    : "Output contract: request + summary + repository + files + execution. Repository exposes source_directory_paths, file_canonical_paths, and supported_tags_by_language; file entries expose status, supported_tags, line ranges, file_doxygen, and matches; match entries expose symbol_kind, signature_text, line ranges, code_lines, stripped_source_text, and structured Doxygen fields.";
+    ? "Output contract: summary + repository + files + execution. Repository exposes requested file scope only when it adds dynamic search context; supported tags remain documented in registration metadata. File entries expose status, line ranges, file_doxygen, and matches; match entries expose symbol_kind, signature_text, line ranges, code_lines, stripped_source_text, and structured Doxygen fields."
+    : "Output contract: summary + repository + files + execution. Repository exposes source_directory_paths and file_canonical_paths when project-scope search context varies; supported tags remain documented in registration metadata. File entries expose status, line ranges, file_doxygen, and matches; match entries expose symbol_kind, signature_text, line ranges, code_lines, stripped_source_text, and structured Doxygen fields.";
   return [
     scopeLine,
     outputLine,
     "Regex rule: pattern is applied to construct names only with JavaScript RegExp search semantics; it never matches construct bodies; use ^...$ for exact-name matching.",
-    "Tag rule: tag is pipe-separated and case-insensitive; unsupported tags are ignored; if no valid tag remains, request.tag_filter_status becomes invalid.",
+    "Tag rule: tag is pipe-separated and case-insensitive; unsupported tags are ignored; if no valid tag remains, the response search_status becomes invalid_tag_filter.",
     "Line-number behavior: enableLineNumbers changes only display_text and stripped_source_text rendering; numeric source_line_number and line_range facts remain dedicated fields.",
     "Failure contract: invalid tag filters, invalid regex patterns, unsupported extensions, unsupported tag-language combinations, no-match files, and analysis failures are surfaced as structured statuses plus optional execution.stderr diagnostics.",
     ...buildFindToolSupportedTagGuidelines(),
@@ -465,7 +491,6 @@ function buildFindToolExecuteResult(
 } {
   const stderr = buildFindToolExecutionStderr(payload);
   const details = {
-    request: payload.request,
     summary: payload.summary,
     repository: payload.repository,
     files: payload.files,
@@ -515,19 +540,6 @@ function getConfiguredEnabledPiUsereqTools(config: UseReqConfig): string[] {
   return enabledTools;
 }
 
-/**
- * @brief Classifies one configurable tool as embedded or extension-owned.
- * @details Uses the runtime `sourceInfo.source` field plus the supported embedded-name subset to produce one stable UI label. Runtime is O(1). No external state is mutated.
- * @param[in] tool {ToolInfo} Runtime tool descriptor.
- * @return {"builtin" | "extension"} Stable tool-kind label.
- */
-function getPiUsereqToolKind(tool: ToolInfo): "builtin" | "extension" {
-  if (tool.sourceInfo?.source === "builtin" && isPiUsereqEmbeddedToolName(tool.name)) {
-    return "builtin";
-  }
-  return "extension";
-}
-
 /**
  * @brief Applies the configured active-tool enablement to the current session.
  * @details Preserves non-configurable active tools, removes every configurable tool from the active set, then re-adds only configured tools that exist in the current runtime inventory. Runtime is O(t). Side effects include `pi.setActiveTools(...)`.
@@ -560,20 +572,19 @@ function applyConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig): v
  * @details Applies session-start-specific resource validation, project-config
  * refresh, and startup-tool enablement before forwarding the originating hook
  * name and payload into the shared `updateExtensionStatus(...)` pipeline.
- * On `agent_end`, also dispatches configured pi-notify beep, sound, and
+ * On `agent_end`, also dispatches configured command-notify, sound, and
  * prompt-specific Pushover effects when the current run originates from a
  * bundled prompt command. Runtime is dominated by configuration loading during
  * `session_start`; all other hooks are O(1). Side effects include resource
  * checks, active-tool mutation, status updates, live-ticker disposal on
- * shutdown, stdout writes, optional child-process spawning, and outbound
- * HTTPS requests.
+ * shutdown, optional child-process spawning, and outbound HTTPS requests.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
  * @param[in] event {unknown} Hook payload forwarded by pi.
  * @param[in] ctx {ExtensionContext} Active extension context.
  * @return {Promise<void>} Promise resolved when hook processing completes.
- * @satisfies REQ-117, REQ-118, REQ-119, REQ-129, REQ-130, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172
+ * @satisfies REQ-117, REQ-118, REQ-119, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187
  */
 async function handleExtensionStatusEvent(
   pi: ExtensionAPI,
@@ -582,6 +593,16 @@ async function handleExtensionStatusEvent(
   event: unknown,
   ctx: ExtensionContext,
 ): Promise<void> {
+  const notifyRequest: PiNotifyEventRequest | undefined = hookName === "agent_end"
+    && statusController.state.activePromptRequest !== undefined
+    && statusController.state.runStartTimeMs !== undefined
+    ? {
+        promptName: statusController.state.activePromptRequest.promptName,
+        promptArgs: statusController.state.activePromptRequest.promptArgs,
+        basePath: path.resolve(ctx.cwd),
+        completionTimeMs: Math.max(0, Date.now() - statusController.state.runStartTimeMs),
+      }
+    : undefined;
   if (hookName === "session_start") {
     ensureBundledResourcesAccessible();
     const config = loadProjectConfig(ctx.cwd);
@@ -591,19 +612,10 @@ async function handleExtensionStatusEvent(
   updateExtensionStatus(statusController, hookName, event, ctx);
   if (hookName === "agent_end") {
     if (statusController.config) {
-      const pushoverRequest: PiNotifyPushoverRequest | undefined = statusController.state.activePromptRequest
-        && statusController.state.lastRunDurationMs !== undefined
-        ? {
-            promptName: statusController.state.activePromptRequest.promptName,
-            promptArgs: statusController.state.activePromptRequest.promptArgs,
-            basePath: path.resolve(ctx.cwd),
-            completionTimeMs: statusController.state.lastRunDurationMs,
-          }
-        : undefined;
       runPiNotifyEffects(
         statusController.config,
         event as { messages: AgentEndEvent["messages"] },
-        pushoverRequest,
+        notifyRequest,
       );
     }
     statusController.state.activePromptRequest = undefined;
@@ -653,131 +665,397 @@ function setConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig, enab
 }
 
 /**
- * @brief Renders a textual reference for configurable-tool configuration and runtime state.
- * @details Lists every configurable tool with configured enablement, runtime activation, builtin-versus-extension classification, source metadata, and optional descriptions. Runtime is O(t). No side effects occur.
- * @param[in] pi {ExtensionAPI} Active extension API instance.
- * @param[in] config {UseReqConfig} Effective project configuration.
- * @return {string} Multiline tool-status report.
+ * @brief Represents one persisted boolean notification-setting key.
+ * @details Restricts menu toggles to the global enable flags and completed/interrupted/failed event toggles used by command-notify, sound, and Pushover configuration. Compile-time only and introduces no runtime cost.
  */
-function renderPiUsereqToolsReference(pi: ExtensionAPI, config: UseReqConfig): string {
-  const tools = getPiUsereqStartupTools(pi);
-  const enabledTools = new Set(getConfiguredEnabledPiUsereqTools(config));
-  const activeTools = new Set(pi.getActiveTools());
-  const lines = [
-    "# configurable active tools",
-    "",
-    `Configured enabled tools: ${enabledTools.size}/${tools.length}`,
-    `Currently active tools: ${tools.filter((tool) => activeTools.has(tool.name)).length}/${tools.length}`,
-    "",
-    "Tools:",
-  ];
+type PiNotifyBooleanConfigKey =
+  | "notify-enabled"
+  | "notify-on-completed"
+  | "notify-on-interrupted"
+  | "notify-on-failed"
+  | "notify-sound-on-completed"
+  | "notify-sound-on-interrupted"
+  | "notify-sound-on-failed"
+  | "notify-pushover-enabled"
+  | "notify-pushover-on-completed"
+  | "notify-pushover-on-interrupted"
+  | "notify-pushover-on-failed";
 
-  for (const tool of tools) {
-    const configured = enabledTools.has(tool.name) ? "enabled" : "disabled";
-    const active = activeTools.has(tool.name) ? "active" : "inactive";
-    const source = tool.sourceInfo ? `${tool.sourceInfo.source}:${tool.sourceInfo.path}` : "unknown";
-    lines.push(`- ${tool.name}`);
-    lines.push(`  kind: ${getPiUsereqToolKind(tool)}`);
-    lines.push(`  configured: ${configured}`);
-    lines.push(`  runtime: ${active}`);
-    lines.push(`  source: ${source}`);
-    if (tool.description) {
-      lines.push(`  description: ${tool.description}`);
-    }
-  }
+/**
+ * @brief Represents one persisted boolean notification event-toggle key.
+ * @details Restricts shared event-submenu mutation helpers to completed/interrupted/failed toggles and excludes global enable flags. Compile-time only and introduces no runtime cost.
+ */
+type PiNotifyEventBooleanConfigKey = Exclude<
+  PiNotifyBooleanConfigKey,
+  "notify-enabled" | "notify-pushover-enabled"
+>;
 
-  return `${lines.join("\n")}\n`;
+/**
+ * @brief Represents one shared prompt-end event identifier used by notification menus.
+ * @details Restricts event-submenu rendering to the canonical completed/interrupted/failed domain shared by command-notify, sound, and Pushover routing. Compile-time only and introduces no runtime cost.
+ */
+type PiNotifyEventId = "completed" | "interrupted" | "failed";
+
+/**
+ * @brief Describes one shared prompt-end event row rendered inside notification event submenus.
+ * @details Binds one canonical event identifier to the human-readable label and terminal-outcome description reused across command-notify, sound, and Pushover event menus. The interface is compile-time only and introduces no runtime cost.
+ */
+interface PiNotifyEventRowDefinition {
+  eventId: PiNotifyEventId;
+  label: string;
+  description: string;
 }
 
 /**
- * @brief Represents one persisted pi-notify beep flag key.
- * @details Restricts menu toggles to the three independent prompt-end beep
- * flags stored in project configuration. Compile-time only and introduces no
- * runtime cost.
+ * @brief Describes one notification-system event submenu contract.
+ * @details Binds the top-level launcher row, submenu title, toast prefix, and completed/interrupted/failed config keys for one notification transport. The interface is compile-time only and introduces no runtime cost.
  */
-type PiNotifyBeepConfigKey =
-  | "notify-beep-on-end"
-  | "notify-beep-on-esc"
-  | "notify-beep-on-error";
+interface PiNotifyEventMenuDefinition {
+  topLevelId: string;
+  topLevelLabel: string;
+  submenuTitle: string;
+  systemLabel: string;
+  keys: Record<PiNotifyEventId, PiNotifyEventBooleanConfigKey>;
+}
 
 /**
- * @brief Flips one persisted pi-notify beep flag.
- * @details Negates the selected prompt-end beep flag in place and returns the resulting boolean value so callers can emit deterministic UI feedback. Runtime is O(1). Side effect: mutates `config`.
+ * @brief Flips one persisted boolean notification setting.
+ * @details Negates the selected configuration flag in place and returns the resulting boolean value so callers can emit deterministic UI feedback. Runtime is O(1). Side effect: mutates `config`.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
- * @param[in] key {PiNotifyBeepConfigKey} Beep flag key to toggle.
+ * @param[in] key {PiNotifyBooleanConfigKey} Boolean configuration key to toggle.
  * @return {boolean} Next enabled state.
  */
-function togglePiNotifyBeepFlag(config: UseReqConfig, key: PiNotifyBeepConfigKey): boolean {
+function togglePiNotifyFlag(config: UseReqConfig, key: PiNotifyBooleanConfigKey): boolean {
   config[key] = !config[key];
   return config[key];
 }
 
+/**
+ * @brief Restores notification-related settings to their documented defaults.
+ * @details Copies the command-notify, sound, and Pushover configuration subtree from a fresh default config into the supplied mutable project config. Runtime is O(1). Side effect: mutates `config`.
+ * @param[in,out] config {UseReqConfig} Mutable configuration object.
+ * @return {void} No return value.
+ * @satisfies REQ-174, REQ-178, REQ-184, REQ-195, REQ-196
+ */
+function resetPiNotifyConfigToDefaults(config: UseReqConfig): void {
+  const defaults = getDefaultConfig("");
+  config["notify-enabled"] = defaults["notify-enabled"];
+  config["notify-on-completed"] = defaults["notify-on-completed"];
+  config["notify-on-interrupted"] = defaults["notify-on-interrupted"];
+  config["notify-on-failed"] = defaults["notify-on-failed"];
+  config["notify-sound"] = defaults["notify-sound"];
+  config["notify-sound-on-completed"] = defaults["notify-sound-on-completed"];
+  config["notify-sound-on-interrupted"] = defaults["notify-sound-on-interrupted"];
+  config["notify-sound-on-failed"] = defaults["notify-sound-on-failed"];
+  config["notify-sound-toggle-shortcut"] = defaults["notify-sound-toggle-shortcut"];
+  config["notify-pushover-enabled"] = defaults["notify-pushover-enabled"];
+  config["notify-pushover-on-completed"] = defaults["notify-pushover-on-completed"];
+  config["notify-pushover-on-interrupted"] = defaults["notify-pushover-on-interrupted"];
+  config["notify-pushover-on-failed"] = defaults["notify-pushover-on-failed"];
+  config["notify-pushover-user-key"] = defaults["notify-pushover-user-key"];
+  config["notify-pushover-api-token"] = defaults["notify-pushover-api-token"];
+  config["notify-pushover-priority"] = defaults["notify-pushover-priority"];
+  config["notify-pushover-title"] = defaults["notify-pushover-title"];
+  config["notify-pushover-text"] = defaults["notify-pushover-text"];
+  config.PI_NOTIFY_CMD = defaults.PI_NOTIFY_CMD;
+  config.PI_NOTIFY_SOUND_LOW_CMD = defaults.PI_NOTIFY_SOUND_LOW_CMD;
+  config.PI_NOTIFY_SOUND_MID_CMD = defaults.PI_NOTIFY_SOUND_MID_CMD;
+  config.PI_NOTIFY_SOUND_HIGH_CMD = defaults.PI_NOTIFY_SOUND_HIGH_CMD;
+}
+
 /**
  * @brief Formats one persisted Pushover priority for menu display.
- * @details Maps the canonical `0|1` priority domain to deterministic menu text reused by the Pushover configuration UI. Runtime is O(1). No external state is mutated.
+ * @details Maps the canonical `0|1` priority domain to deterministic `Normal|High` labels reused by the Pushover configuration UI. Runtime is O(1). No external state is mutated.
  * @param[in] priority {PiNotifyPushoverPriority} Persisted Pushover priority.
  * @return {string} Menu-display label.
- * @satisfies REQ-165
+ * @satisfies REQ-172
  */
 function formatPiNotifyPushoverPriority(priority: PiNotifyPushoverPriority): string {
-  return priority === 1 ? "1=High Priority" : "0=Normal";
+  return priority === 1 ? "High" : "Normal";
+}
+
+/**
+ * @brief Defines the shared prompt-end event rows reused across notification submenus.
+ * @details Encodes the human-readable completed/interrupted/failed labels and terminal-state descriptions required by the command-notify, sound, and Pushover event menus. Access complexity is O(1).
+ * @satisfies REQ-188, REQ-198
+ */
+const PI_NOTIFY_EVENT_ROW_DEFINITIONS: PiNotifyEventRowDefinition[] = [
+  {
+    eventId: "completed",
+    label: "Prompt completed",
+    description: "Toggle delivery when the prompt finishes without interruption or failure.",
+  },
+  {
+    eventId: "interrupted",
+    label: "Prompt interrupted",
+    description: "Toggle delivery when the prompt finishes with assistant stopReason `aborted`.",
+  },
+  {
+    eventId: "failed",
+    label: "Prompt failed",
+    description: "Toggle delivery when the prompt finishes with assistant stopReason `error`.",
+  },
+];
+
+/**
+ * @brief Defines the shared event-submenu contracts for command-notify, sound, and Pushover.
+ * @details Binds each notification transport to its top-level launcher row, submenu title, toast prefix, and completed/interrupted/failed config-key set. Access complexity is O(1).
+ * @satisfies REQ-174, REQ-178, REQ-184, REQ-198
+ */
+const PI_NOTIFY_EVENT_MENU_DEFINITIONS: Record<
+  "notification" | "sound" | "pushover",
+  PiNotifyEventMenuDefinition
+> = {
+  notification: {
+    topLevelId: "notification-events",
+    topLevelLabel: "Notification events",
+    submenuTitle: "Notification events",
+    systemLabel: "Notification",
+    keys: {
+      completed: "notify-on-completed",
+      interrupted: "notify-on-interrupted",
+      failed: "notify-on-failed",
+    },
+  },
+  sound: {
+    topLevelId: "sound-events",
+    topLevelLabel: "Sound events",
+    submenuTitle: "Sound events",
+    systemLabel: "Sound",
+    keys: {
+      completed: "notify-sound-on-completed",
+      interrupted: "notify-sound-on-interrupted",
+      failed: "notify-sound-on-failed",
+    },
+  },
+  pushover: {
+    topLevelId: "pushover-events",
+    topLevelLabel: "Pushover events",
+    submenuTitle: "Pushover events",
+    systemLabel: "Pushover",
+    keys: {
+      completed: "notify-pushover-on-completed",
+      interrupted: "notify-pushover-on-interrupted",
+      failed: "notify-pushover-on-failed",
+    },
+  },
+};
+
+/**
+ * @brief Formats the top-level summary value for one notification event submenu.
+ * @details Counts enabled completed/interrupted/failed toggles for the selected transport and renders the result as `n/3 on` for right-aligned menu display. Runtime is O(1). No external state is mutated.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
+ * @return {string} Compact enabled-toggle summary.
+ * @satisfies REQ-198
+ */
+function formatPiNotifyEventMenuSummary(
+  config: UseReqConfig,
+  eventMenu: PiNotifyEventMenuDefinition,
+): string {
+  const enabledCount = PI_NOTIFY_EVENT_ROW_DEFINITIONS.filter(
+    (row) => config[eventMenu.keys[row.eventId]] === true,
+  ).length;
+  return `${enabledCount}/3 on`;
 }
 
 /**
- * @brief Builds the shared settings-menu choices for Pushover configuration.
- * @details Serializes the Pushover global-disable flag, successful-completion enable flag, credential strings, and priority value into right-valued menu rows consumed by the shared settings-menu renderer. Runtime is O(1). No external state is mutated.
+ * @brief Builds the top-level launcher row for one notification event submenu.
+ * @details Reuses the shared completed/interrupted/failed summary renderer so the `Notifications` menu can expose dedicated event editors for command-notify, sound, and Pushover in a uniform shape. Runtime is O(1). No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
- * @return {PiUsereqSettingsMenuChoice[]} Ordered Pushover-menu choice vector.
- * @satisfies REQ-163, REQ-165, REQ-166, REQ-172
+ * @param[in] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
+ * @return {PiUsereqSettingsMenuChoice} Launcher row for the selected event submenu.
+ * @satisfies REQ-181, REQ-183, REQ-165, REQ-198
  */
-function buildPiNotifyPushoverMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
+function buildPiNotifyEventLauncherChoice(
+  config: UseReqConfig,
+  eventMenu: PiNotifyEventMenuDefinition,
+): PiUsereqSettingsMenuChoice {
+  return {
+    id: eventMenu.topLevelId,
+    label: eventMenu.topLevelLabel,
+    value: formatPiNotifyEventMenuSummary(config, eventMenu),
+    description: `Open the ${eventMenu.submenuTitle} submenu for shared prompt-end delivery events.`,
+  };
+}
+
+/**
+ * @brief Builds the shared settings-menu choices for one notification event submenu.
+ * @details Serializes completed/interrupted/failed rows with right-aligned `on|off` values, then appends `Reset defaults` and `Save and close` for submenu-scoped mutation control. Runtime is O(1). No external state is mutated.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
+ * @return {PiUsereqSettingsMenuChoice[]} Ordered event-submenu choice vector.
+ * @satisfies REQ-188, REQ-193, REQ-198
+ */
+function buildPiNotifyEventMenuChoices(
+  config: UseReqConfig,
+  eventMenu: PiNotifyEventMenuDefinition,
+): PiUsereqSettingsMenuChoice[] {
   return [
+    ...PI_NOTIFY_EVENT_ROW_DEFINITIONS.map((row) => ({
+      id: eventMenu.keys[row.eventId],
+      label: row.label,
+      value: config[eventMenu.keys[row.eventId]] ? "on" : "off",
+      description: `${eventMenu.systemLabel}: ${row.description}`,
+    })),
     {
-      id: "pushover-global-disable",
-      label: "Global disable",
-      value: config["notify-pushover-global-disable"] ? "on" : "off",
-      description: "Suppress all Pushover delivery without changing the successful-prompt enable flag.",
+      id: "reset-defaults",
+      label: "Reset defaults",
+      value: "",
+      description: `Restore the documented default ${eventMenu.systemLabel.toLowerCase()} event toggles.`,
+    },
+    {
+      id: "save-and-close",
+      label: "Save and close",
+      value: "",
+      description: "Return to the notifications menu.",
     },
+  ];
+}
+
+/**
+ * @brief Restores one notification event submenu to its documented defaults.
+ * @details Copies only the completed/interrupted/failed toggles referenced by the supplied submenu contract from a fresh default config into the mutable project config. Runtime is O(1). Side effect: mutates `config`.
+ * @param[in,out] config {UseReqConfig} Mutable configuration object.
+ * @param[in] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
+ * @return {void} No return value.
+ * @satisfies REQ-174, REQ-178, REQ-184, REQ-195
+ */
+function resetPiNotifyEventMenuToDefaults(
+  config: UseReqConfig,
+  eventMenu: PiNotifyEventMenuDefinition,
+): void {
+  const defaults = getDefaultConfig("");
+  for (const key of Object.values(eventMenu.keys) as PiNotifyEventBooleanConfigKey[]) {
+    config[key] = defaults[key];
+  }
+}
+
+/**
+ * @brief Resolves the human-readable event label for one event-toggle config key.
+ * @details Matches the supplied config key against the submenu contract and returns the corresponding completed/interrupted/failed menu label for deterministic notification toasts. Runtime is O(1). No external state is mutated.
+ * @param[in] key {PiNotifyEventBooleanConfigKey} Event-toggle configuration key.
+ * @param[in] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
+ * @return {string} Human-readable event label.
+ * @satisfies REQ-188, REQ-198
+ */
+function resolvePiNotifyEventLabel(
+  key: PiNotifyEventBooleanConfigKey,
+  eventMenu: PiNotifyEventMenuDefinition,
+): string {
+  return PI_NOTIFY_EVENT_ROW_DEFINITIONS.find(
+    (row) => eventMenu.keys[row.eventId] === key,
+  )?.label ?? key;
+}
+
+/**
+ * @brief Runs one dedicated notification event submenu.
+ * @details Reuses the shared settings-menu renderer to toggle completed/interrupted/failed delivery flags, preserve row focus, and apply submenu-scoped reset semantics for command-notify, sound, or Pushover events. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
+ * @param[in] ctx {ExtensionCommandContext} Active command context.
+ * @param[in,out] config {UseReqConfig} Mutable configuration object.
+ * @param[in] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
+ * @return {Promise<void>} Promise resolved when the submenu closes.
+ * @satisfies REQ-188, REQ-192, REQ-193, REQ-195, REQ-198
+ */
+async function configurePiNotifyEventMenu(
+  ctx: ExtensionCommandContext,
+  config: UseReqConfig,
+  eventMenu: PiNotifyEventMenuDefinition,
+): Promise<void> {
+  let focusedChoiceId: string | undefined;
+  while (true) {
+    const choice = await showPiUsereqSettingsMenu(
+      ctx,
+      eventMenu.submenuTitle,
+      buildPiNotifyEventMenuChoices(config, eventMenu),
+      { initialSelectedId: focusedChoiceId },
+    );
+    if (!choice || choice === "save-and-close") {
+      return;
+    }
+    focusedChoiceId = choice;
+    if (choice === "reset-defaults") {
+      resetPiNotifyEventMenuToDefaults(config, eventMenu);
+      ctx.ui.notify(
+        `Restored default ${eventMenu.systemLabel.toLowerCase()} events`,
+        "info",
+      );
+      continue;
+    }
+    const enabled = togglePiNotifyFlag(
+      config,
+      choice as PiNotifyEventBooleanConfigKey,
+    );
+    const eventLabel = resolvePiNotifyEventLabel(
+      choice as PiNotifyEventBooleanConfigKey,
+      eventMenu,
+    );
+    ctx.ui.notify(
+      `${eventMenu.systemLabel} ${eventLabel} ${enabled ? "enabled" : "disabled"}`,
+      "info",
+    );
+  }
+}
+
+/**
+ * @brief Builds the direct Pushover rows rendered inside `Notifications`.
+ * @details Serializes the global enable flag, shared-event submenu launcher, priority, title, text, and credential rows into right-valued menu items appended after the sound-command rows. Runtime is O(1). No external state is mutated.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @return {PiUsereqSettingsMenuChoice[]} Ordered direct Pushover rows.
+ * @satisfies REQ-163, REQ-165, REQ-172, REQ-184, REQ-185, REQ-198
+ */
+function buildPiNotifyPushoverRows(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
+  return [
     {
-      id: "pushover-on-success",
-      label: "Notify on success",
+      id: "notify-pushover-enabled",
+      label: "Enable pushover",
       value: formatPiNotifyPushoverStatus(config),
-      description: "Toggle Pushover delivery after successful prompt completion only.",
+      description: "Enable or disable all Pushover delivery globally.",
     },
+    buildPiNotifyEventLauncherChoice(
+      config,
+      PI_NOTIFY_EVENT_MENU_DEFINITIONS.pushover,
+    ),
     {
-      id: "pushover-user-key",
-      label: "User Key/Delivery Group Key",
-      value: config["notify-pushover-user-key"] || "(empty)",
-      description: "Edit the Pushover user key or delivery group key sent with successful prompt notifications.",
+      id: "notify-pushover-priority",
+      label: "Pushover priority",
+      value: formatPiNotifyPushoverPriority(config["notify-pushover-priority"]),
+      description: "Select whether outbound Pushover messages use Normal or High priority.",
     },
     {
-      id: "pushover-api-token",
-      label: "Token/API Token Key",
-      value: config["notify-pushover-api-token"] || "(empty)",
-      description: "Edit the Pushover application token used for successful prompt notifications.",
+      id: "notify-pushover-title",
+      label: "Pushover title",
+      value: config["notify-pushover-title"],
+      description: "Edit the title template used for outbound Pushover messages.",
     },
     {
-      id: "pushover-priority",
-      label: "Priority",
-      value: formatPiNotifyPushoverPriority(config["notify-pushover-priority"]),
-      description: "Select whether successful prompt notifications use normal or high Pushover priority.",
+      id: "notify-pushover-text",
+      label: "Pushover text",
+      value: config["notify-pushover-text"],
+      description: "Edit the text template used for outbound Pushover messages.",
     },
     {
-      id: "back",
-      label: "Back",
-      value: "",
-      description: "Return to the notifications menu.",
+      id: "notify-pushover-user-key",
+      label: "Pushover User Key/Delivery Group Key",
+      value: config["notify-pushover-user-key"] || "(empty)",
+      description: "Edit the Pushover user key or delivery group key used for outbound requests.",
+    },
+    {
+      id: "notify-pushover-api-token",
+      label: "Pushover Token/API Token Key",
+      value: config["notify-pushover-api-token"] || "(empty)",
+      description: "Edit the Pushover application token used for outbound requests.",
     },
   ];
 }
 
 /**
  * @brief Opens the shared settings-menu selector for Pushover priority.
- * @details Reuses the pi-usereq settings-menu renderer so Pushover priority selection remains stylistically aligned with the existing notification menus and returns the chosen priority or `undefined` on cancel. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
+ * @details Reuses the pi-usereq settings-menu renderer so Pushover priority selection remains stylistically aligned with the notification menus and returns the chosen priority or `undefined` on cancel. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in] currentPriority {PiNotifyPushoverPriority} Persisted priority value.
  * @return {Promise<PiNotifyPushoverPriority | undefined>} Selected priority or `undefined` when cancelled.
- * @satisfies REQ-165
+ * @satisfies REQ-172, REQ-192
  */
 async function selectPiNotifyPushoverPriority(
   ctx: ExtensionCommandContext,
@@ -786,148 +1064,92 @@ async function selectPiNotifyPushoverPriority(
   const choice = await showPiUsereqSettingsMenu(ctx, "Pushover priority", [
     {
       id: "0",
-      label: "0=Normal",
+      label: "Normal",
       value: currentPriority === 0 ? "selected" : "",
-      description: "Send successful prompt notifications with normal Pushover priority.",
+      description: "Send outbound Pushover messages with normal priority `0`.",
     },
     {
       id: "1",
-      label: "1=High Priority",
+      label: "High",
       value: currentPriority === 1 ? "selected" : "",
-      description: "Send successful prompt notifications with high Pushover priority.",
+      description: "Send outbound Pushover messages with high priority `1`.",
     },
-  ]);
+  ], { initialSelectedId: String(currentPriority) });
   if (!choice) {
     return undefined;
   }
   return normalizePiNotifyPushoverPriority(choice);
 }
 
-/**
- * @brief Runs the interactive Pushover-configuration menu.
- * @details Exposes the Pushover global-disable flag, successful-completion enable flag, user key, API token, and priority selector through the shared settings-menu renderer. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
- * @param[in] ctx {ExtensionCommandContext} Active command context.
- * @param[in,out] config {UseReqConfig} Mutable configuration object.
- * @return {Promise<void>} Promise resolved when the menu closes.
- * @satisfies REQ-163, REQ-165, REQ-166, REQ-172
- */
-async function configurePiNotifyPushoverMenu(
-  ctx: ExtensionCommandContext,
-  config: UseReqConfig,
-): Promise<void> {
-  while (true) {
-    const choice = await showPiUsereqSettingsMenu(ctx, "Pushover notifications", buildPiNotifyPushoverMenuChoices(config));
-    if (!choice || choice === "back") {
-      return;
-    }
-    if (choice === "pushover-global-disable") {
-      config["notify-pushover-global-disable"] = !config["notify-pushover-global-disable"];
-      ctx.ui.notify(`Pushover global disable ${config["notify-pushover-global-disable"] ? "enabled" : "disabled"}`, "info");
-      continue;
-    }
-    if (choice === "pushover-on-success") {
-      config["notify-pushover-on-success"] = !config["notify-pushover-on-success"];
-      ctx.ui.notify(`Pushover on success ${config["notify-pushover-on-success"] ? "enabled" : "disabled"}`, "info");
-      continue;
-    }
-    if (choice === "pushover-user-key") {
-      const value = await ctx.ui.input(
-        "User Key/Delivery Group Key",
-        config["notify-pushover-user-key"] || "gzfjjvp1xxmhibqwzh9m7i1zwvf83j",
-      );
-      if (value !== undefined) {
-        config["notify-pushover-user-key"] = normalizePiNotifyPushoverCredential(value);
-        ctx.ui.notify("Updated Pushover user key", "info");
-      }
-      continue;
-    }
-    if (choice === "pushover-api-token") {
-      const value = await ctx.ui.input(
-        "Token/API Token Key",
-        config["notify-pushover-api-token"] || "ah6bf5u2sj63mcvou6qamiabeoubbe",
-      );
-      if (value !== undefined) {
-        config["notify-pushover-api-token"] = normalizePiNotifyPushoverCredential(value);
-        ctx.ui.notify("Updated Pushover API token", "info");
-      }
-      continue;
-    }
-    if (choice === "pushover-priority") {
-      const nextPriority = await selectPiNotifyPushoverPriority(ctx, config["notify-pushover-priority"]);
-      if (nextPriority !== undefined) {
-        config["notify-pushover-priority"] = nextPriority;
-        ctx.ui.notify(`Pushover priority set to ${formatPiNotifyPushoverPriority(nextPriority)}`, "info");
-      }
-    }
-  }
-}
-
 /**
  * @brief Builds the shared settings-menu choices for notification configuration.
- * @details Serializes the current beep flags, selected notify command, hotkey bind, per-level notify commands, and the Pushover submenu entry into right-valued menu rows consumed by the shared settings-menu renderer. Runtime is O(1) plus command-length formatting. No external state is mutated.
+ * @details Serializes command-notify, sound, and Pushover blocks with dedicated shared-event submenu launchers so the settings-menu renderer can expose one unified but modular configuration surface. Runtime is O(1) plus command-length formatting. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered notification-menu choice vector.
- * @satisfies REQ-137, REQ-149, REQ-150, REQ-151, REQ-152, REQ-163, REQ-164, REQ-165, REQ-166, REQ-172
+ * @satisfies REQ-137, REQ-149, REQ-150, REQ-151, REQ-152, REQ-163, REQ-164, REQ-165, REQ-172, REQ-179, REQ-181, REQ-183, REQ-188, REQ-193, REQ-198
  */
 function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   return [
     {
-      id: "toggle-beep-on-success",
-      label: "Toggle beep on success",
-      value: config["notify-beep-on-end"] ? "on" : "off",
-      description: "Toggle terminal beep delivery for successful prompt completion.",
+      id: "notify-enabled",
+      label: "Enable notification",
+      value: formatPiNotifyStatus(config),
+      description: "Enable or disable command-notify delivery globally.",
     },
+    buildPiNotifyEventLauncherChoice(
+      config,
+      PI_NOTIFY_EVENT_MENU_DEFINITIONS.notification,
+    ),
     {
-      id: "toggle-beep-on-escape",
-      label: "Toggle beep on escape",
-      value: config["notify-beep-on-esc"] ? "on" : "off",
-      description: "Toggle terminal beep delivery for escape-triggered prompt abortion.",
+      id: "notify-command",
+      label: "Notify command",
+      value: config.PI_NOTIFY_CMD,
+      description: "Edit the shell command used for command-notify delivery.",
     },
     {
-      id: "toggle-beep-on-error",
-      label: "Toggle beep on error",
-      value: config["notify-beep-on-error"] ? "on" : "off",
-      description: "Toggle terminal beep delivery for error-terminated prompt completion.",
-    },
-    {
-      id: "selected-notify-command",
-      label: "Selected notify command",
+      id: "selected-sound-command",
+      label: "Enable sound",
       value: config["notify-sound"],
-      description: "Select which notify command runs after successful prompt completion.",
+      description: "Select which sound command level is currently active.",
     },
+    buildPiNotifyEventLauncherChoice(
+      config,
+      PI_NOTIFY_EVENT_MENU_DEFINITIONS.sound,
+    ),
     {
       id: "sound-toggle-hotkey-bind",
       label: "Sound toggle hotkey bind",
       value: config["notify-sound-toggle-shortcut"],
-      description: "Edit the keyboard shortcut that cycles the selected notify command.",
+      description: "Edit the keyboard shortcut that cycles the selected sound command.",
     },
     {
-      id: "notify-command-low",
-      label: "Notify command (low vol.)",
+      id: "sound-command-low",
+      label: "Sound command (low vol.)",
       value: config.PI_NOTIFY_SOUND_LOW_CMD,
-      description: "Edit the shell command used when the selected notify command is `low`.",
+      description: "Edit the shell command used when the selected sound command is `low`.",
     },
     {
-      id: "notify-command-mid",
-      label: "Notify command (mid vol.)",
+      id: "sound-command-mid",
+      label: "Sound command (mid vol.)",
       value: config.PI_NOTIFY_SOUND_MID_CMD,
-      description: "Edit the shell command used when the selected notify command is `mid`.",
+      description: "Edit the shell command used when the selected sound command is `mid`.",
     },
     {
-      id: "notify-command-high",
-      label: "Notify command (high vol.)",
+      id: "sound-command-high",
+      label: "Sound command (high vol.)",
       value: config.PI_NOTIFY_SOUND_HIGH_CMD,
-      description: "Edit the shell command used when the selected notify command is `high`.",
+      description: "Edit the shell command used when the selected sound command is `high`.",
     },
+    ...buildPiNotifyPushoverRows(config),
     {
-      id: "pushover-notifications",
-      label: "Pushover notifications",
-      value: formatPiNotifyPushoverStatus(config),
-      description: "Open the Pushover submenu for successful-completion delivery, credentials, priority, and global disable.",
+      id: "reset-defaults",
+      label: "Reset defaults",
+      value: "",
+      description: "Restore the documented notification defaults for command-notify, sound, and Pushover settings.",
     },
     {
-      id: "back",
-      label: "Back",
+      id: "save-and-close",
+      label: "Save and close",
       value: "",
       description: "Return to the parent configuration menu.",
     },
@@ -935,127 +1157,229 @@ function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuCho
 }
 
 /**
- * @brief Opens the shared settings-menu selector for the selected notify command.
- * @details Reuses the pi-usereq settings-menu renderer so notify-command selection remains stylistically aligned with the main configuration UI and returns the chosen sound level or `undefined` on cancel. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
+ * @brief Opens the shared settings-menu selector for the active sound level.
+ * @details Reuses the pi-usereq settings-menu renderer so sound-level selection remains stylistically aligned with the notification menu and returns the chosen sound level or `undefined` on cancel. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
- * @param[in] currentLevel {PiNotifySoundLevel} Currently selected notify command.
+ * @param[in] currentLevel {PiNotifySoundLevel} Currently selected sound level.
  * @return {Promise<PiNotifySoundLevel | undefined>} Selected sound level or `undefined` when cancelled.
- * @satisfies REQ-131, REQ-137, REQ-149, REQ-151, REQ-152, REQ-153, REQ-154
+ * @satisfies REQ-131, REQ-179, REQ-192
  */
 async function selectPiNotifySoundLevel(
   ctx: ExtensionCommandContext,
   currentLevel: PiNotifySoundLevel,
 ): Promise<PiNotifySoundLevel | undefined> {
-  const choice = await showPiUsereqSettingsMenu(ctx, "Selected notify command", [
+  const choice = await showPiUsereqSettingsMenu(ctx, "Enable sound", [
     {
       id: "none",
       label: "none",
       value: currentLevel === "none" ? "selected" : "",
-      description: "Disable external notify-command execution.",
+      description: "Disable sound-command delivery while preserving per-event sound toggles.",
     },
     {
       id: "low",
       label: "low",
       value: currentLevel === "low" ? "selected" : "",
-      description: "Run the low-volume notify command after successful completion.",
+      description: "Use the low-volume sound command when sound delivery is enabled for the current event.",
     },
     {
       id: "mid",
       label: "mid",
       value: currentLevel === "mid" ? "selected" : "",
-      description: "Run the mid-volume notify command after successful completion.",
+      description: "Use the mid-volume sound command when sound delivery is enabled for the current event.",
     },
     {
       id: "high",
       label: "high",
       value: currentLevel === "high" ? "selected" : "",
-      description: "Run the high-volume notify command after successful completion.",
+      description: "Use the high-volume sound command when sound delivery is enabled for the current event.",
     },
-  ]);
+  ], { initialSelectedId: currentLevel });
   return choice ? choice as PiNotifySoundLevel : undefined;
 }
 
 /**
  * @brief Runs the interactive notification-configuration menu.
- * @details Exposes prompt-end beep toggles, selected notify-command selection, hotkey-bind editing, per-level notify-command editors, and the nested Pushover submenu through the shared settings-menu renderer. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
+ * @details Exposes command-notify, sound, and Pushover controls through the shared settings-menu renderer, delegates completed/interrupted/failed toggles to dedicated event submenus, and preserves row focus across menu re-renders. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {Promise<boolean>} `true` when the sound-toggle shortcut changed.
- * @satisfies REQ-129, REQ-131, REQ-133, REQ-134, REQ-137, REQ-149, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-163, REQ-164, REQ-165, REQ-166, REQ-172
+ * @satisfies REQ-131, REQ-133, REQ-134, REQ-137, REQ-163, REQ-164, REQ-165, REQ-172, REQ-179, REQ-181, REQ-183, REQ-184, REQ-188, REQ-192, REQ-193, REQ-195, REQ-196, REQ-198
  */
 async function configurePiNotifyMenu(
   ctx: ExtensionCommandContext,
   config: UseReqConfig,
 ): Promise<boolean> {
   const originalShortcut = config["notify-sound-toggle-shortcut"];
+  let focusedChoiceId: string | undefined;
   while (true) {
-    const choice = await showPiUsereqSettingsMenu(ctx, "notifications", buildPiNotifyMenuChoices(config));
-    if (!choice || choice === "back") {
+    const choice = await showPiUsereqSettingsMenu(
+      ctx,
+      "Notifications",
+      buildPiNotifyMenuChoices(config),
+      { initialSelectedId: focusedChoiceId },
+    );
+    if (!choice || choice === "save-and-close") {
       return config["notify-sound-toggle-shortcut"] !== originalShortcut;
     }
-    if (choice === "toggle-beep-on-success") {
-      const enabled = togglePiNotifyBeepFlag(config, "notify-beep-on-end");
-      ctx.ui.notify(`Beep on success ${enabled ? "enabled" : "disabled"}`, "info");
+    focusedChoiceId = choice;
+    if (choice === "notify-enabled" || choice === "notify-pushover-enabled") {
+      const enabled = togglePiNotifyFlag(config, choice as PiNotifyBooleanConfigKey);
+      const labelMap: Record<string, string> = {
+        "notify-enabled": "Notification",
+        "notify-pushover-enabled": "Pushover",
+      };
+      ctx.ui.notify(`${labelMap[choice]} ${enabled ? "enabled" : "disabled"}`, "info");
       continue;
     }
-    if (choice === "toggle-beep-on-escape") {
-      const enabled = togglePiNotifyBeepFlag(config, "notify-beep-on-esc");
-      ctx.ui.notify(`Beep on escape ${enabled ? "enabled" : "disabled"}`, "info");
+    if (choice === PI_NOTIFY_EVENT_MENU_DEFINITIONS.notification.topLevelId) {
+      await configurePiNotifyEventMenu(
+        ctx,
+        config,
+        PI_NOTIFY_EVENT_MENU_DEFINITIONS.notification,
+      );
       continue;
     }
-    if (choice === "toggle-beep-on-error") {
-      const enabled = togglePiNotifyBeepFlag(config, "notify-beep-on-error");
-      ctx.ui.notify(`Beep on error ${enabled ? "enabled" : "disabled"}`, "info");
+    if (choice === PI_NOTIFY_EVENT_MENU_DEFINITIONS.sound.topLevelId) {
+      await configurePiNotifyEventMenu(
+        ctx,
+        config,
+        PI_NOTIFY_EVENT_MENU_DEFINITIONS.sound,
+      );
       continue;
     }
-    if (choice === "selected-notify-command") {
+    if (choice === PI_NOTIFY_EVENT_MENU_DEFINITIONS.pushover.topLevelId) {
+      await configurePiNotifyEventMenu(
+        ctx,
+        config,
+        PI_NOTIFY_EVENT_MENU_DEFINITIONS.pushover,
+      );
+      continue;
+    }
+    if (choice === "notify-command") {
+      const value = await ctx.ui.input("Notify command", config.PI_NOTIFY_CMD);
+      if (value !== undefined) {
+        config.PI_NOTIFY_CMD = normalizePiNotifyCommand(value, DEFAULT_PI_NOTIFY_CMD);
+        ctx.ui.notify("Updated notify command", "info");
+      }
+      continue;
+    }
+    if (choice === "selected-sound-command") {
       const nextLevel = await selectPiNotifySoundLevel(ctx, config["notify-sound"]);
-      if (nextLevel) {
+      if (nextLevel !== undefined) {
         config["notify-sound"] = nextLevel;
-        ctx.ui.notify(`Selected notify command set to ${nextLevel}`, "info");
+        ctx.ui.notify(`Enable sound set to ${nextLevel}`, "info");
       }
       continue;
     }
     if (choice === "sound-toggle-hotkey-bind") {
-      const value = await ctx.ui.input("Sound toggle hotkey bind", config["notify-sound-toggle-shortcut"]);
+      const value = await ctx.ui.input(
+        "Sound toggle hotkey bind",
+        config["notify-sound-toggle-shortcut"],
+      );
       if (value?.trim()) {
         config["notify-sound-toggle-shortcut"] = value.trim();
-        ctx.ui.notify(`Sound toggle hotkey bind set to ${config["notify-sound-toggle-shortcut"]}`, "info");
+        ctx.ui.notify(
+          `Sound toggle hotkey bind set to ${config["notify-sound-toggle-shortcut"]}`,
+          "info",
+        );
       }
       continue;
     }
-    if (choice === "notify-command-low") {
-      const value = await ctx.ui.input("Notify command (low vol.)", config.PI_NOTIFY_SOUND_LOW_CMD);
-      if (value?.trim()) {
-        config.PI_NOTIFY_SOUND_LOW_CMD = value.trim();
-        ctx.ui.notify("Updated notify command (low vol.)", "info");
+    if (choice === "sound-command-low") {
+      const value = await ctx.ui.input("Sound command (low vol.)", config.PI_NOTIFY_SOUND_LOW_CMD);
+      if (value !== undefined) {
+        config.PI_NOTIFY_SOUND_LOW_CMD = normalizePiNotifyCommand(
+          value,
+          DEFAULT_PI_NOTIFY_SOUND_LOW_CMD,
+        );
+        ctx.ui.notify("Updated sound command (low vol.)", "info");
       }
       continue;
     }
-    if (choice === "notify-command-mid") {
-      const value = await ctx.ui.input("Notify command (mid vol.)", config.PI_NOTIFY_SOUND_MID_CMD);
-      if (value?.trim()) {
-        config.PI_NOTIFY_SOUND_MID_CMD = value.trim();
-        ctx.ui.notify("Updated notify command (mid vol.)", "info");
+    if (choice === "sound-command-mid") {
+      const value = await ctx.ui.input("Sound command (mid vol.)", config.PI_NOTIFY_SOUND_MID_CMD);
+      if (value !== undefined) {
+        config.PI_NOTIFY_SOUND_MID_CMD = normalizePiNotifyCommand(
+          value,
+          DEFAULT_PI_NOTIFY_SOUND_MID_CMD,
+        );
+        ctx.ui.notify("Updated sound command (mid vol.)", "info");
       }
       continue;
     }
-    if (choice === "notify-command-high") {
-      const value = await ctx.ui.input("Notify command (high vol.)", config.PI_NOTIFY_SOUND_HIGH_CMD);
-      if (value?.trim()) {
-        config.PI_NOTIFY_SOUND_HIGH_CMD = value.trim();
-        ctx.ui.notify("Updated notify command (high vol.)", "info");
+    if (choice === "sound-command-high") {
+      const value = await ctx.ui.input("Sound command (high vol.)", config.PI_NOTIFY_SOUND_HIGH_CMD);
+      if (value !== undefined) {
+        config.PI_NOTIFY_SOUND_HIGH_CMD = normalizePiNotifyCommand(
+          value,
+          DEFAULT_PI_NOTIFY_SOUND_HIGH_CMD,
+        );
+        ctx.ui.notify("Updated sound command (high vol.)", "info");
+      }
+      continue;
+    }
+    if (choice === "notify-pushover-priority") {
+      const nextPriority = await selectPiNotifyPushoverPriority(ctx, config["notify-pushover-priority"]);
+      if (nextPriority !== undefined) {
+        config["notify-pushover-priority"] = nextPriority;
+        ctx.ui.notify(`Pushover priority set to ${formatPiNotifyPushoverPriority(nextPriority)}`, "info");
+      }
+      continue;
+    }
+    if (choice === "notify-pushover-title") {
+      const value = await ctx.ui.input("Pushover title", config["notify-pushover-title"]);
+      if (value !== undefined) {
+        config["notify-pushover-title"] = normalizePiNotifyTemplateValue(
+          value,
+          DEFAULT_PI_NOTIFY_PUSHOVER_TITLE,
+        );
+        ctx.ui.notify("Updated Pushover title", "info");
+      }
+      continue;
+    }
+    if (choice === "notify-pushover-text") {
+      const value = await ctx.ui.input("Pushover text", config["notify-pushover-text"]);
+      if (value !== undefined) {
+        config["notify-pushover-text"] = normalizePiNotifyTemplateValue(
+          value,
+          DEFAULT_PI_NOTIFY_PUSHOVER_TEXT,
+        );
+        ctx.ui.notify("Updated Pushover text", "info");
+      }
+      continue;
+    }
+    if (choice === "notify-pushover-user-key") {
+      const value = await ctx.ui.input(
+        "Pushover User Key/Delivery Group Key",
+        config["notify-pushover-user-key"],
+      );
+      if (value !== undefined) {
+        config["notify-pushover-user-key"] = normalizePiNotifyPushoverCredential(value);
+        ctx.ui.notify("Updated Pushover user key", "info");
       }
       continue;
     }
-    if (choice === "pushover-notifications") {
-      await configurePiNotifyPushoverMenu(ctx, config);
+    if (choice === "notify-pushover-api-token") {
+      const value = await ctx.ui.input(
+        "Pushover Token/API Token Key",
+        config["notify-pushover-api-token"],
+      );
+      if (value !== undefined) {
+        config["notify-pushover-api-token"] = normalizePiNotifyPushoverCredential(value);
+        ctx.ui.notify("Updated Pushover API token", "info");
+      }
+      continue;
+    }
+    if (choice === "reset-defaults") {
+      resetPiNotifyConfigToDefaults(config);
+      ctx.ui.notify("Restored notification defaults", "info");
+      continue;
     }
   }
 }
 
 /**
- * @brief Registers the configurable successful-run sound shortcut when supported.
+ * @brief Registers the configurable notification-sound shortcut when supported.
  * @details Loads the current project config, registers one raw pi shortcut when
  * the runtime exposes `registerShortcut(...)`, cycles persisted sound state on
  * invocation, saves the config, refreshes the status bar, and emits one info
@@ -1065,7 +1389,7 @@ async function configurePiNotifyMenu(
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {void} No return value.
- * @satisfies REQ-131, REQ-134, REQ-136
+ * @satisfies REQ-131, REQ-134, REQ-180
  */
 function registerPiNotifyShortcut(
   pi: ExtensionAPI,
@@ -1077,7 +1401,7 @@ function registerPiNotifyShortcut(
   }
   const config = loadProjectConfig(process.cwd());
   shortcutRegistrar.registerShortcut(config["notify-sound-toggle-shortcut"], {
-    description: "Cycle pi-usereq prompt-success sound level",
+    description: "Cycle pi-usereq notification sound level",
     handler: async (ctx) => {
       const nextConfig = loadProjectConfig(ctx.cwd);
       nextConfig["notify-sound"] = cyclePiNotifySoundLevel(nextConfig["notify-sound"]);
@@ -1131,17 +1455,17 @@ function registerAgentTools(pi: ExtensionAPI): void {
   const gitPathSchema = Type.Object(
     {},
     {
-      description: "Input contract: no params. Output contract: JSON object with request, result, and execution. Result exposes path_key, path_value, and path_present for the cwd-derived runtime git root.",
+      description: "Input contract: no params. Output contract: JSON object with result and execution. Result exposes path_value and path_present for the cwd-derived runtime git root.",
     },
   );
   pi.registerTool({
     name: "git-path",
     label: "git-path",
-    description: "Scope: current runtime path. Return a JSON-first payload with request, result, and execution sections. Result exposes the resolved `git-path` value through direct-access fields instead of text-only output.",
+    description: "Scope: current runtime path. Return a token-optimized JSON payload with result and execution sections. Result exposes the resolved `git-path` value through direct-access fields without request echoes.",
     promptSnippet: "Return the structured runtime git-root payload for the current project.",
     promptGuidelines: [
       "Input contract: no params. Scope is the cwd-derived runtime path context.",
-      "Output contract: request + result + execution. Result exposes path_key, path_value, and path_present.",
+      "Output contract: result + execution. Result exposes path_value and path_present.",
       "Behavior contract: git-path is derived at runtime from the current working directory and repository ancestry rules.",
       "Failure contract: configuration-loading failures surface through execution.code and execution.stderr_lines.",
     ],
@@ -1150,14 +1474,12 @@ function registerAgentTools(pi: ExtensionAPI): void {
       ensureBundledResourcesAccessible();
       const projectBase = getProjectBase(process.cwd());
       const config = loadProjectConfig(process.cwd());
-      const runtimePaths = buildSharedRuntimePathFacts(process.cwd(), config);
       const result = runGitPath(projectBase, config);
       const payload = buildPathQueryToolPayload(
         "git-path",
         process.cwd(),
         projectBase,
         result.stdout.trimEnd(),
-        runtimePaths,
         buildToolExecutionSection(result),
       );
       return buildStructuredToolExecuteResult(payload);
@@ -1167,17 +1489,17 @@ function registerAgentTools(pi: ExtensionAPI): void {
   const basePathSchema = Type.Object(
     {},
     {
-      description: "Input contract: no params. Output contract: JSON object with request, result, and execution. Result exposes path_key, path_value, and path_present for the cwd-derived runtime base path.",
+      description: "Input contract: no params. Output contract: JSON object with result and execution. Result exposes path_value and path_present for the cwd-derived runtime base path.",
     },
   );
   pi.registerTool({
     name: "get-base-path",
     label: "get-base-path",
-    description: "Scope: current runtime path. Return a JSON-first payload with request, result, and execution sections. Result exposes the resolved `base-path` value through direct-access fields instead of text-only output.",
+    description: "Scope: current runtime path. Return a token-optimized JSON payload with result and execution sections. Result exposes the resolved `base-path` value through direct-access fields without request echoes.",
     promptSnippet: "Return the structured runtime project-base payload.",
     promptGuidelines: [
       "Input contract: no params. Scope is the cwd-derived runtime path context.",
-      "Output contract: request + result + execution. Result exposes path_key, path_value, and path_present.",
+      "Output contract: result + execution. Result exposes path_value and path_present.",
       "Behavior contract: base-path equals the current working directory used by the extension command or tool.",
       "Failure contract: configuration-loading failures surface through execution.code and execution.stderr_lines.",
     ],
@@ -1185,14 +1507,12 @@ function registerAgentTools(pi: ExtensionAPI): void {
     async execute() {
       const projectBase = getProjectBase(process.cwd());
       const config = loadProjectConfig(process.cwd());
-      const runtimePaths = buildSharedRuntimePathFacts(process.cwd(), config);
       const result = runGetBasePath(projectBase, config);
       const payload = buildPathQueryToolPayload(
         "get-base-path",
         process.cwd(),
         projectBase,
         result.stdout.trimEnd(),
-        runtimePaths,
         buildToolExecutionSection(result),
       );
       return buildStructuredToolExecuteResult(payload);
@@ -1207,7 +1527,7 @@ function registerAgentTools(pi: ExtensionAPI): void {
       ),
     },
     {
-      description: "Input contract: files[]. Output contract: JSON object with request, summary, repository, files, and execution. File entries expose canonical paths, numeric line ranges, imports, symbols, structured Doxygen fields, standalone comments, and structured status facts. Missing or unsupported inputs become skipped entries. The tool fails when no source file can be analyzed.",
+      description: "Input contract: files[]. Output contract: JSON object with summary, repository, files, and execution. File entries expose canonical paths, numeric line ranges, imports, symbols, structured Doxygen fields, standalone comments, and structured status facts. Missing or unsupported inputs become skipped entries. The tool fails when no source file can be analyzed.",
     },
   );
   const multiFileSchema = Type.Object(
@@ -1218,7 +1538,7 @@ function registerAgentTools(pi: ExtensionAPI): void {
       ),
     },
     {
-      description: "Input contract: files[]. Output contract: JSON object with request, summary, files, and execution. File entries expose canonical paths, detected language, configured checker modules, selection status, and error facts.",
+      description: "Input contract: files[]. Output contract: JSON object with summary, files, and execution. File entries expose canonical paths, detected language, configured checker modules, selection status, and error facts.",
     },
   );
   const filesTokensSchema = Type.Object(
@@ -1229,42 +1549,46 @@ function registerAgentTools(pi: ExtensionAPI): void {
       ),
     },
     {
-      description: "Input contract: files[]. Output contract: JSON object with request, summary, files, guidance, and execution. File entries expose path identifiers, access facts, line ranges, sizes, token metrics, and optional heading or Doxygen metadata. Missing or non-file inputs become skipped entries. The tool fails when no processable files remain.",
+      description: "Input contract: files[]. Output contract: JSON object with summary, files, and execution. File entries expose direct-access facts, token metrics, and optional heading or Doxygen metadata. Missing or non-file inputs become skipped entries. The tool fails when no processable files remain.",
     },
   );
 
   pi.registerTool({
     name: "files-tokens",
     label: "files-tokens",
-    description: "Scope: explicit files. Return an LLM-oriented JSON payload with request, summary, files, guidance, and execution sections. File entries expose direct-access path facts, status, line ranges, sizes, token metrics, and optional heading or Doxygen metadata.",
+    description: "Scope: explicit files. Return a token-optimized JSON payload with summary, files, and execution sections. File entries expose direct-access path facts, status, size metrics, and optional heading or Doxygen metadata.",
     promptSnippet: "Return the structured token-analysis payload for caller-selected files.",
     promptGuidelines: [
       "Scope: explicit files selected by files[]; caller order is preserved; each item may be project-relative or absolute.",
-      "Output contract: request + summary + files + guidance + execution. File entries expose canonical paths, absolute paths, existence, file status, line range, line count, byte count, character count, token count, shares, and optional primary-heading or Doxygen file metadata.",
-      "Numeric contract: counts, sizes, shares, and line ranges remain in dedicated numeric fields; descriptive text is limited to stable reasons and guidance labels.",
+      "Output contract: summary + files + execution. File entries expose canonical paths, absolute paths, existence, file status, line range, line count, byte count, character count, token count, shares, and optional primary-heading or Doxygen file metadata.",
+      "Numeric contract: counts, sizes, shares, and line ranges remain in dedicated numeric fields; static request metadata and derived guidance are omitted from runtime responses.",
       "Behavior contract: missing or non-file inputs become skipped entries; read failures become error entries; the tool fails only when no processable files remain.",
     ],
     parameters: filesTokensSchema,
     async execute(_toolCallId, params) {
-      const payload = buildTokenToolPayload({
-        toolName: "files-tokens",
-        scope: "explicit-files",
-        baseDir: process.cwd(),
-        requestedPaths: params.files,
-        encodingName: TOKEN_COUNTER_ENCODING,
-      });
-      return buildTokenToolExecuteResult(payload);
+      try {
+        const payload = buildTokenToolPayload({
+          toolName: "files-tokens",
+          scope: "explicit-files",
+          baseDir: process.cwd(),
+          requestedPaths: params.files,
+          encodingName: TOKEN_COUNTER_ENCODING,
+        });
+        return buildTokenToolExecuteResult(payload);
+      } catch (error) {
+        return buildFailedTokenToolExecuteResult(error);
+      }
     },
   });
 
   pi.registerTool({
     name: "files-references",
     label: "files-references",
-    description: "Scope: explicit source files. Return an LLM-oriented JSON payload with request, summary, repository, files, and execution sections. File entries expose canonical paths, numeric line ranges, imports, symbols, structured Doxygen fields, standalone comments, and structured status facts.",
+    description: "Scope: explicit source files. Return a token-optimized JSON payload with summary, repository, files, and execution sections. File entries expose canonical paths, numeric line ranges, imports, symbols, structured Doxygen fields, standalone comments, and structured status facts.",
     promptSnippet: "Return the structured references payload for caller-selected source files.",
     promptGuidelines: [
       "Scope: explicit source files selected by files[]; caller order is preserved; each item may be project-relative or absolute.",
-      "Output contract: request + summary + repository + files + execution. File entries expose canonical paths, absolute paths, file status, line counts, line ranges, imports, symbols, child relationships, standalone comments, and structured Doxygen metadata.",
+      "Output contract: summary + repository + files + execution. File entries expose canonical paths, absolute paths, file status, line counts, line ranges, imports, symbols, child relationships, standalone comments, and structured Doxygen metadata.",
       "Numeric contract: line counts, line ranges, symbol counts, import counts, comment counts, and Doxygen counts remain in dedicated numeric fields; text is limited to residual comment or signature content that cannot be split safely.",
       "Behavior contract: missing inputs, non-file inputs, and unsupported extensions become structured skipped entries; analysis failures become structured error entries; the tool fails only when no source file can be analyzed.",
     ],
@@ -1289,18 +1613,18 @@ function registerAgentTools(pi: ExtensionAPI): void {
       enableLineNumbers: Type.Optional(Type.Boolean({ description: "When true, `compressed_source_text` and `compressed_lines[].display_text` include original source line-number prefixes" })),
     },
     {
-      description: "Input contract: files[] plus optional enableLineNumbers. Output contract: JSON object with request, summary, repository, files, and execution. File entries expose path identifiers, source and compressed line metrics, structured compressed lines, symbols, structured Doxygen fields, and stable status facts. Missing, unsupported, or invalid inputs become structured skipped entries. The tool fails when no file is compressed.",
+      description: "Input contract: files[] plus optional enableLineNumbers. Output contract: JSON object with summary, repository, files, and execution. File entries expose path identifiers, source and compressed line metrics, structured compressed lines, symbols, structured Doxygen fields, and stable status facts. Missing, unsupported, or invalid inputs become structured skipped entries. The tool fails when no file is compressed.",
     },
   );
 
   pi.registerTool({
     name: "files-compress",
     label: "files-compress",
-    description: "Scope: explicit files. Return an LLM-oriented JSON payload with request, summary, repository, files, and execution sections. File entries expose canonical paths, source and compressed line metrics, structured compressed lines, symbols, structured Doxygen fields, and stable status facts.",
+    description: "Scope: explicit files. Return a token-optimized JSON payload with summary, repository, files, and execution sections. File entries expose canonical paths, source and compressed line metrics, structured compressed lines, symbols, structured Doxygen fields, and stable status facts.",
     promptSnippet: "Return the structured compression payload for caller-selected source files.",
     promptGuidelines: [
       "Scope: explicit source files selected by files[]; caller order is preserved; each item may be project-relative or absolute.",
-      "Output contract: request + summary + repository + files + execution. File entries expose canonical paths, absolute paths, line_number_mode, source line counts, source line ranges, compressed line counts, removed line counts, compressed_lines, compressed_source_text, symbols, and file_doxygen.",
+      "Output contract: summary + repository + files + execution. File entries expose canonical paths, absolute paths, line_number_mode, source line counts, source line ranges, compressed line counts, removed line counts, compressed_lines, compressed_source_text, symbols, and file_doxygen.",
       "Line-number behavior: enableLineNumbers changes only rendered display strings; numeric source_line_number facts remain dedicated fields on compressed_lines for direct access.",
       "Behavior contract: missing inputs, non-file inputs, and unsupported extensions become structured skipped entries; compression failures become structured error entries; symbol-analysis failures retain compressed output with symbol_analysis_status=error; the tool fails only when no file is compressed.",
     ],
@@ -1335,7 +1659,7 @@ function registerAgentTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "files-find",
     label: "files-find",
-    description: "Scope: explicit source files. Return an LLM-oriented JSON payload with request, summary, repository, files, and execution sections. File entries expose structured statuses and match records with typed location, symbol, stripped-code, and Doxygen facts.",
+    description: "Scope: explicit source files. Return a token-optimized JSON payload with summary, repository, files, and execution sections. File entries expose structured statuses and match records with typed location, symbol, stripped-code, and Doxygen facts.",
     promptSnippet: "Return the structured construct-search payload for caller-selected source files.",
     promptGuidelines: buildFindToolPromptGuidelines("explicit-files"),
     parameters: filesFindSchema,
@@ -1356,24 +1680,24 @@ function registerAgentTools(pi: ExtensionAPI): void {
   const referencesSchema = Type.Object(
     {},
     {
-      description: "Input contract: no params. Scope is the configured src-dir list resolved from the current project configuration. Output contract: JSON object with request, summary, repository, files, and execution. Repository exposes the structured directory tree; file entries expose canonical paths, numeric line ranges, imports, symbols, structured Doxygen fields, and status facts. The tool fails when no configured source file can be analyzed.",
+      description: "Input contract: no params. Scope is the configured src-dir list resolved from the current project configuration. Output contract: JSON object with summary, repository, files, and execution. Repository exposes the structured directory tree; file entries expose canonical paths, numeric line ranges, imports, symbols, structured Doxygen fields, and status facts. The tool fails when no configured source file can be analyzed.",
     },
   );
   const tokensSchema = Type.Object(
     {},
     {
-      description: "Input contract: no params. Scope is the configured docs-dir plus canonical docs REQUIREMENTS.md, WORKFLOW.md, and REFERENCES.md. Output contract: same structured JSON shape as files-tokens, plus docs_dir_path and canonical_doc_names in request. Missing canonical docs become skipped entries. The tool fails when no processable canonical docs remain.",
+      description: "Input contract: no params. Scope is the configured docs-dir plus canonical docs REQUIREMENTS.md, WORKFLOW.md, and REFERENCES.md. Output contract: same token-optimized JSON shape as files-tokens. Missing canonical docs become skipped entries. The tool fails when no processable canonical docs remain.",
     },
   );
 
   pi.registerTool({
     name: "references",
     label: "references",
-    description: "Scope: configured project source directories. Return an LLM-oriented JSON payload with request, summary, repository, files, and execution sections. The repository section exposes the structured directory tree; file entries expose canonical paths, numeric line ranges, imports, symbols, structured Doxygen fields, standalone comments, and status facts.",
+    description: "Scope: configured project source directories. Return a token-optimized JSON payload with summary, repository, files, and execution sections. The repository section exposes the structured directory tree; file entries expose canonical paths, numeric line ranges, imports, symbols, structured Doxygen fields, standalone comments, and status facts.",
     promptSnippet: "Return the structured project references payload from the configured source directories.",
     promptGuidelines: [
       "Scope: no params; resolve src-dir from the current project configuration and scan the configured source surface from the current working directory.",
-      "Output contract: request + summary + repository + files + execution. Repository exposes source_directory_paths, file_canonical_paths, and directory_tree; file entries expose canonical paths, line counts, line ranges, imports, symbols, hierarchy, standalone comments, and structured Doxygen metadata.",
+      "Output contract: summary + repository + files + execution. Repository exposes source_directory_paths, file_canonical_paths, and directory_tree; file entries expose canonical paths, line counts, line ranges, imports, symbols, hierarchy, standalone comments, and structured Doxygen metadata.",
       "Configuration contract: output changes with cwd-derived project config, src-dir values, and repository source discovery; the tool does not accept explicit file overrides.",
       "Behavior contract: configured source files are analyzed in deterministic order, analysis failures become structured error entries, and the tool fails when no configured source file can be analyzed.",
     ],
@@ -1397,18 +1721,18 @@ function registerAgentTools(pi: ExtensionAPI): void {
       enableLineNumbers: Type.Optional(Type.Boolean({ description: "When true, `compressed_source_text` and `compressed_lines[].display_text` include original source line-number prefixes" })),
     },
     {
-      description: "Input contract: optional enableLineNumbers boolean. Scope is the configured src-dir list resolved from the current project configuration. Output contract: JSON object with request, summary, repository, files, and execution. File entries expose path identifiers, source and compressed line metrics, structured compressed lines, symbols, structured Doxygen fields, and stable status facts. The tool fails when no configured source file is compressed.",
+      description: "Input contract: optional enableLineNumbers boolean. Scope is the configured src-dir list resolved from the current project configuration. Output contract: JSON object with summary, repository, files, and execution. File entries expose path identifiers, source and compressed line metrics, structured compressed lines, symbols, structured Doxygen fields, and stable status facts. The tool fails when no configured source file is compressed.",
     },
   );
 
   pi.registerTool({
     name: "compress",
     label: "compress",
-    description: "Scope: configured project source directories. Return an LLM-oriented JSON payload with request, summary, repository, files, and execution sections. File entries expose canonical paths, source and compressed line metrics, structured compressed lines, symbols, structured Doxygen fields, and stable status facts.",
+    description: "Scope: configured project source directories. Return a token-optimized JSON payload with summary, repository, files, and execution sections. File entries expose canonical paths, source and compressed line metrics, structured compressed lines, symbols, structured Doxygen fields, and stable status facts.",
     promptSnippet: "Return the structured project compression payload from the configured source directories.",
     promptGuidelines: [
       "Scope: resolve src-dir from the current project configuration and scan the configured source surface from the current working directory.",
-      "Output contract: request + summary + repository + files + execution. Repository exposes source_directory_paths and file_canonical_paths; file entries expose line_number_mode, source line counts, source line ranges, compressed line counts, removed line counts, compressed_lines, compressed_source_text, symbols, and file_doxygen.",
+      "Output contract: summary + repository + files + execution. Repository exposes source_directory_paths and file_canonical_paths; file entries expose line_number_mode, source line counts, source line ranges, compressed line counts, removed line counts, compressed_lines, compressed_source_text, symbols, and file_doxygen.",
       "Configuration contract: output changes with cwd-derived project config, src-dir values, and repository source discovery; the tool does not accept explicit file overrides.",
       "Behavior contract: configured source files are processed in deterministic order, compression failures become structured error entries, symbol-analysis failures retain compressed output with symbol_analysis_status=error, and the tool fails only when no configured source file is compressed.",
     ],
@@ -1443,7 +1767,7 @@ function registerAgentTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "find",
     label: "find",
-    description: "Scope: configured project source directories. Return an LLM-oriented JSON payload with request, summary, repository, files, and execution sections. File entries expose structured statuses and match records with typed location, symbol, stripped-code, and Doxygen facts.",
+    description: "Scope: configured project source directories. Return a token-optimized JSON payload with summary, repository, files, and execution sections. File entries expose structured statuses and match records with typed location, symbol, stripped-code, and Doxygen facts.",
     promptSnippet: "Return the structured construct-search payload from the configured source directories.",
     promptGuidelines: buildFindToolPromptGuidelines("configured-source-directories"),
     parameters: findSchema,
@@ -1468,41 +1792,45 @@ function registerAgentTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "tokens",
     label: "tokens",
-    description: "Scope: canonical docs from the configured docs-dir. Return the same LLM-oriented JSON contract as files-tokens, plus canonical-doc selection metadata in request for REQUIREMENTS.md, WORKFLOW.md, and REFERENCES.md.",
+    description: "Scope: canonical docs from the configured docs-dir. Return the same token-optimized JSON contract as files-tokens, omitting canonical-doc request echoes from runtime responses.",
     promptSnippet: "Return the structured token-analysis payload for canonical documentation files.",
     promptGuidelines: [
       "Scope: no params; resolve docs-dir from project config; target canonical docs REQUIREMENTS.md, WORKFLOW.md, and REFERENCES.md.",
-      "Output contract: request + summary + files + guidance + execution. Request includes docs_dir_path and canonical_doc_names; file entries expose direct-access path facts, line ranges, sizes, token metrics, and optional metadata.",
-      "Numeric contract: counts, sizes, shares, and line ranges remain in dedicated numeric fields; guidance separates source observations, derived recommendations, and actionable next-step hints.",
+      "Output contract: summary + files + execution. Static docs-dir and canonical-doc selection facts remain documented in registration metadata; file entries expose direct-access path facts, line ranges, sizes, token metrics, and optional metadata.",
+      "Numeric contract: counts, sizes, shares, and line ranges remain in dedicated numeric fields; derived guidance is omitted from runtime responses to reduce token cost.",
       "Behavior contract: missing canonical docs become skipped entries; read failures become error entries; the tool fails only when no processable canonical docs remain.",
     ],
     parameters: tokensSchema,
     async execute() {
-      const projectBase = getProjectBase(process.cwd());
-      const config = loadProjectConfig(process.cwd());
-      const docsDir = config["docs-dir"].replace(/[/\\]+$/, "");
-      const canonicalDocNames = ["REQUIREMENTS.md", "WORKFLOW.md", "REFERENCES.md"];
-      const payload = buildTokenToolPayload({
-        toolName: "tokens",
-        scope: "canonical-docs",
-        baseDir: projectBase,
-        requestedPaths: canonicalDocNames.map((name) => path.join(docsDir, name)),
-        docsDir,
-        canonicalDocNames,
-        encodingName: TOKEN_COUNTER_ENCODING,
-      });
-      return buildTokenToolExecuteResult(payload);
+      try {
+        const projectBase = getProjectBase(process.cwd());
+        const config = loadProjectConfig(process.cwd());
+        const docsDir = config["docs-dir"].replace(/[/\\]+$/, "");
+        const canonicalDocNames = ["REQUIREMENTS.md", "WORKFLOW.md", "REFERENCES.md"];
+        const payload = buildTokenToolPayload({
+          toolName: "tokens",
+          scope: "canonical-docs",
+          baseDir: projectBase,
+          requestedPaths: canonicalDocNames.map((name) => path.join(docsDir, name)),
+          docsDir,
+          canonicalDocNames,
+          encodingName: TOKEN_COUNTER_ENCODING,
+        });
+        return buildTokenToolExecuteResult(payload);
+      } catch (error) {
+        return buildFailedTokenToolExecuteResult(error);
+      }
     },
   });
 
   pi.registerTool({
     name: "files-static-check",
     label: "files-static-check",
-    description: "Scope: explicit files. Return a JSON-first payload with request, summary, files, and execution sections. File entries expose canonical paths, detected language, configured checker modules, selection status, and stable error facts.",
+    description: "Scope: explicit files. Return a token-optimized JSON payload with summary, files, and execution sections. File entries expose canonical paths, detected language, configured checker modules, selection status, and stable error facts.",
     promptSnippet: "Return the structured explicit-file static-check payload for the current project configuration.",
     promptGuidelines: [
       "Input contract: files[]. Scope is explicit caller-selected files resolved from the current working directory.",
-      "Output contract: request + summary + files + execution. File entries expose canonical_path, language_name, configured_checker_modules, status, and error_message.",
+      "Output contract: summary + files + execution. File entries expose canonical_path, language_name, configured_checker_modules, status, and error_message.",
       "Configuration contract: checker selection is derived from the cwd-resolved static-check configuration and file extensions only.",
       "Failure contract: execution.code mirrors aggregated checker failures; execution.stdout_lines and execution.stderr_lines preserve residual checker diagnostics.",
     ],
@@ -1510,7 +1838,6 @@ function registerAgentTools(pi: ExtensionAPI): void {
     async execute(_toolCallId, params) {
       const projectBase = getProjectBase(process.cwd());
       const config = loadProjectConfig(process.cwd());
-      const runtimePaths = buildSharedRuntimePathFacts(process.cwd(), config);
       const staticCheckConfig = config["static-check"] ?? {};
       const result = runFilesStaticCheck(params.files, projectBase, config);
       const payload = buildStaticCheckToolPayload(
@@ -1521,7 +1848,6 @@ function registerAgentTools(pi: ExtensionAPI): void {
         [],
         [],
         staticCheckConfig,
-        runtimePaths,
         buildToolExecutionSection(result),
       );
       return buildStructuredToolExecuteResult(payload);
@@ -1531,17 +1857,17 @@ function registerAgentTools(pi: ExtensionAPI): void {
   const staticCheckSchema = Type.Object(
     {},
     {
-      description: "Input contract: no params. Scope is the configured src-dir plus tests-dir selection after fixture exclusion. Output contract: JSON object with request, summary, files, and execution.",
+      description: "Input contract: no params. Scope is the configured src-dir plus tests-dir selection after fixture exclusion. Output contract: JSON object with summary, files, and execution.",
     },
   );
   pi.registerTool({
     name: "static-check",
     label: "static-check",
-    description: "Scope: configured source and test directories. Return a JSON-first payload with request, summary, files, and execution sections. File entries expose selected-path facts, checker coverage, selection status, and residual diagnostics metadata.",
+    description: "Scope: configured source and test directories. Return a token-optimized JSON payload with summary, files, and execution sections. File entries expose selected-path facts, checker coverage, selection status, and residual diagnostics metadata.",
     promptSnippet: "Return the structured project static-check payload for the current configuration.",
     promptGuidelines: [
       "Input contract: no params. Scope is src-dir plus tests-dir from the cwd-derived project configuration.",
-      "Output contract: request + summary + files + execution. Request exposes selection_directory_paths and excluded_directory_paths; file entries expose configured_checker_modules and status.",
+      "Output contract: summary + files + execution. Selection-directory rules remain documented in registration metadata; file entries expose configured_checker_modules and status.",
       "Selection contract: tests/fixtures and <tests-dir>/fixtures are excluded before checker dispatch.",
       "Failure contract: execution.code mirrors aggregated checker failures or selection failures; execution.stderr_lines preserve residual diagnostics.",
     ],
@@ -1549,7 +1875,6 @@ function registerAgentTools(pi: ExtensionAPI): void {
     async execute() {
       const projectBase = getProjectBase(process.cwd());
       const config = loadProjectConfig(process.cwd());
-      const runtimePaths = buildSharedRuntimePathFacts(process.cwd(), config);
       const staticCheckConfig = config["static-check"] ?? {};
       const selectionDirectoryPaths = [...config["src-dir"], config["tests-dir"]];
       const testsDirRel = makeRelativeIfContainsProject(config["tests-dir"], projectBase)
@@ -1577,7 +1902,6 @@ function registerAgentTools(pi: ExtensionAPI): void {
         selectionDirectoryPaths,
         excludedDirectoryPaths,
         staticCheckConfig,
-        runtimePaths,
         execution,
       );
       return buildStructuredToolExecuteResult(payload);
@@ -1587,17 +1911,17 @@ function registerAgentTools(pi: ExtensionAPI): void {
   const gitCheckSchema = Type.Object(
     {},
     {
-      description: "Input contract: no params. Output contract: JSON object with request, result, and execution. Result exposes git-root presence plus clean-versus-error repository status fields.",
+      description: "Input contract: no params. Output contract: JSON object with result and execution. Result exposes git-path presence plus aggregate repository status fields.",
     },
   );
   pi.registerTool({
     name: "git-check",
     label: "git-check",
-    description: "Scope: current runtime path. Return a JSON-first payload with request, result, and execution sections. Result exposes repository validation status through direct fields instead of empty-success text.",
+    description: "Scope: current runtime path. Return a token-optimized JSON payload with result and execution sections. Result exposes repository validation status through direct fields without request echoes.",
     promptSnippet: "Return the structured git-validation payload for the runtime repository.",
     promptGuidelines: [
       "Input contract: no params. Scope is the cwd-derived runtime path context.",
-      "Output contract: request + result + execution. Result exposes git_path_present, status, worktree_status, and head_status.",
+      "Output contract: result + execution. Result exposes git_path_present and aggregate status.",
       "Behavior contract: the tool checks work-tree membership, porcelain cleanliness, and symbolic-or-detached HEAD validity.",
       "Failure contract: execution.code and execution.stderr_lines surface git-path or repository-state errors.",
     ],
@@ -1605,14 +1929,13 @@ function registerAgentTools(pi: ExtensionAPI): void {
     async execute() {
       const projectBase = getProjectBase(process.cwd());
       const config = loadProjectConfig(process.cwd());
-      const runtimePaths = buildSharedRuntimePathFacts(process.cwd(), config);
       let execution;
       try {
         execution = buildToolExecutionSection(runGitCheck(projectBase, config));
       } catch (error) {
         execution = buildToolExecutionSection(normalizeToolFailure(error));
       }
-      const payload = buildGitCheckToolPayload(projectBase, resolveRuntimeGitPath(projectBase), runtimePaths, execution);
+      const payload = buildGitCheckToolPayload(projectBase, resolveRuntimeGitPath(projectBase), execution);
       return buildStructuredToolExecuteResult(payload);
     },
   });
@@ -1620,17 +1943,17 @@ function registerAgentTools(pi: ExtensionAPI): void {
   const docsCheckSchema = Type.Object(
     {},
     {
-      description: "Input contract: no params. Output contract: JSON object with request, summary, files, and execution. File entries expose canonical paths, prompt_command remediation, and presence status for canonical docs.",
+      description: "Input contract: no params. Output contract: JSON object with summary, files, and execution. File entries expose canonical paths, prompt_command remediation, and presence status for canonical docs.",
     },
   );
   pi.registerTool({
     name: "docs-check",
     label: "docs-check",
-    description: "Scope: canonical docs. Return a JSON-first payload with request, summary, files, and execution sections. File entries expose remediation prompt commands and direct presence facts for REQUIREMENTS.md, WORKFLOW.md, and REFERENCES.md.",
+    description: "Scope: canonical docs. Return a token-optimized JSON payload with summary, files, and execution sections. File entries expose remediation prompt commands and direct presence facts for REQUIREMENTS.md, WORKFLOW.md, and REFERENCES.md.",
     promptSnippet: "Return the structured canonical-document validation payload.",
     promptGuidelines: [
       "Input contract: no params. Scope is docs-dir from the cwd-derived project configuration.",
-      "Output contract: request + summary + files + execution. File entries expose file_name, canonical_path, prompt_command, and status.",
+      "Output contract: summary + files + execution. File entries expose file_name, canonical_path, prompt_command, and status.",
       "Specialization trigger: remediation differs per missing canonical file through prompt_command.",
       "Failure contract: execution.code is non-zero when any canonical document is missing; execution.stderr_lines enumerate missing files.",
     ],
@@ -1638,8 +1961,7 @@ function registerAgentTools(pi: ExtensionAPI): void {
     async execute() {
       const projectBase = getProjectBase(process.cwd());
       const config = loadProjectConfig(process.cwd());
-      const runtimePaths = buildSharedRuntimePathFacts(process.cwd(), config);
-      const payload = buildDocsCheckToolPayload(projectBase, config["docs-dir"], runtimePaths);
+      const payload = buildDocsCheckToolPayload(projectBase, config["docs-dir"]);
       return buildStructuredToolExecuteResult(payload);
     },
   });
@@ -1647,17 +1969,17 @@ function registerAgentTools(pi: ExtensionAPI): void {
   const gitWtNameSchema = Type.Object(
     {},
     {
-      description: "Input contract: no params. Output contract: JSON object with request, result, and execution. Result exposes worktree_name and the normative useReq naming format string.",
+      description: "Input contract: no params. Output contract: JSON object with result and execution. Result exposes worktree_name when generation succeeds.",
     },
   );
   pi.registerTool({
     name: "git-wt-name",
     label: "git-wt-name",
-    description: "Scope: current runtime path. Return a JSON-first payload with request, result, and execution sections. Result exposes the generated worktree name plus its normative format as direct fields.",
+    description: "Scope: current runtime path. Return a token-optimized JSON payload with result and execution sections. Result exposes the generated worktree name while static naming rules remain in registration metadata.",
     promptSnippet: "Return the structured worktree-name generation payload.",
     promptGuidelines: [
       "Input contract: no params. Scope is the cwd-derived runtime path context.",
-      "Output contract: request + result + execution. Result exposes worktree_name and format_text.",
+      "Output contract: result + execution. Result exposes worktree_name.",
       "Behavior contract: generation follows useReq-<project>-<sanitized-branch>-<YYYYMMDDHHMMSS>.",
       "Failure contract: execution.code and execution.stderr_lines surface git-path or branch-resolution errors.",
     ],
@@ -1665,14 +1987,13 @@ function registerAgentTools(pi: ExtensionAPI): void {
     async execute() {
       const projectBase = getProjectBase(process.cwd());
       const config = loadProjectConfig(process.cwd());
-      const runtimePaths = buildSharedRuntimePathFacts(process.cwd(), config);
       let execution;
       try {
         execution = buildToolExecutionSection(runGitWtName(projectBase, config));
       } catch (error) {
         execution = buildToolExecutionSection(normalizeToolFailure(error));
       }
-      const payload = buildWorktreeNameToolPayload(projectBase, resolveRuntimeGitPath(projectBase), runtimePaths, execution);
+      const payload = buildWorktreeNameToolPayload(projectBase, resolveRuntimeGitPath(projectBase), execution);
       return buildStructuredToolExecuteResult(payload);
     },
   });
@@ -1682,17 +2003,17 @@ function registerAgentTools(pi: ExtensionAPI): void {
       wtName: Type.String({ description: "Exact target worktree name and branch name" }),
     },
     {
-      description: "Input contract: wtName. Output contract: JSON object with request, result, and execution. Result exposes operation, worktree_name, branch_name, derived worktree_path, and status.",
+      description: "Input contract: wtName. Output contract: JSON object with result and execution. Result exposes worktree_name and derived worktree_path.",
     },
   );
   pi.registerTool({
     name: "git-wt-create",
     label: "git-wt-create",
-    description: "Scope: current runtime path. Return a JSON-first payload with request, result, and execution sections. Result exposes the requested create operation, exact worktree name, derived path, and mutation status.",
+    description: "Scope: current runtime path. Return a token-optimized JSON payload with result and execution sections. Result exposes the exact worktree name and derived path without static operation echoes.",
     promptSnippet: "Return the structured worktree-creation payload for the requested name.",
     promptGuidelines: [
       "Input contract: wtName is required and must match the exact worktree/branch name to create.",
-      "Output contract: request + result + execution. Result exposes operation=create, worktree_name, branch_name, worktree_path, and status.",
+      "Output contract: result + execution. Result exposes worktree_name and worktree_path.",
       "Specialization trigger: worktree_path depends on the runtime git root parent directory.",
       "Failure contract: execution.code and execution.stderr_lines surface invalid-name, git, or finalization errors.",
     ],
@@ -1700,7 +2021,6 @@ function registerAgentTools(pi: ExtensionAPI): void {
     async execute(_toolCallId, params) {
       const projectBase = getProjectBase(process.cwd());
       const config = loadProjectConfig(process.cwd());
-      const runtimePaths = buildSharedRuntimePathFacts(process.cwd(), config);
       let execution;
       try {
         execution = buildToolExecutionSection(runGitWtCreate(projectBase, params.wtName, config));
@@ -1712,7 +2032,6 @@ function registerAgentTools(pi: ExtensionAPI): void {
         projectBase,
         resolveRuntimeGitPath(projectBase),
         params.wtName,
-        runtimePaths,
         execution,
       );
       return buildStructuredToolExecuteResult(payload);
@@ -1724,17 +2043,17 @@ function registerAgentTools(pi: ExtensionAPI): void {
       wtName: Type.String({ description: "Exact target worktree name and branch name" }),
     },
     {
-      description: "Input contract: wtName. Output contract: JSON object with request, result, and execution. Result exposes operation, worktree_name, branch_name, derived worktree_path, and status.",
+      description: "Input contract: wtName. Output contract: JSON object with result and execution. Result exposes worktree_name and derived worktree_path.",
     },
   );
   pi.registerTool({
     name: "git-wt-delete",
     label: "git-wt-delete",
-    description: "Scope: current runtime path. Return a JSON-first payload with request, result, and execution sections. Result exposes the requested delete operation, exact worktree name, derived path, and mutation status.",
+    description: "Scope: current runtime path. Return a token-optimized JSON payload with result and execution sections. Result exposes the exact worktree name and derived path without static operation echoes.",
     promptSnippet: "Return the structured worktree-deletion payload for the requested name.",
     promptGuidelines: [
       "Input contract: wtName is required and must match the exact worktree/branch name to delete.",
-      "Output contract: request + result + execution. Result exposes operation=delete, worktree_name, branch_name, worktree_path, and status.",
+      "Output contract: result + execution. Result exposes worktree_name and worktree_path.",
       "Specialization trigger: worktree_path depends on the runtime git root parent directory.",
       "Failure contract: execution.code and execution.stderr_lines surface missing-target or deletion errors.",
     ],
@@ -1742,7 +2061,6 @@ function registerAgentTools(pi: ExtensionAPI): void {
     async execute(_toolCallId, params) {
       const projectBase = getProjectBase(process.cwd());
       const config = loadProjectConfig(process.cwd());
-      const runtimePaths = buildSharedRuntimePathFacts(process.cwd(), config);
       let execution;
       try {
         execution = buildToolExecutionSection(runGitWtDelete(projectBase, params.wtName, config));
@@ -1754,7 +2072,6 @@ function registerAgentTools(pi: ExtensionAPI): void {
         projectBase,
         resolveRuntimeGitPath(projectBase),
         params.wtName,
-        runtimePaths,
         execution,
       );
       return buildStructuredToolExecuteResult(payload);
@@ -1764,26 +2081,20 @@ function registerAgentTools(pi: ExtensionAPI): void {
 
 /**
  * @brief Builds the shared settings-menu choices for startup-tool management.
- * @details Serializes startup-tool actions into right-valued menu rows consumed by the shared settings-menu renderer. Runtime is O(t) in configurable-tool count. No external state is mutated.
+ * @details Serializes startup-tool actions into right-valued menu rows consumed by the shared settings-menu renderer while omitting the removed status-reference action. Runtime is O(t) in configurable-tool count. No external state is mutated.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered startup-tool menu choices.
- * @satisfies REQ-007, REQ-151, REQ-152, REQ-153, REQ-154
+ * @satisfies REQ-007, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193
  */
 function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   const tools = getPiUsereqStartupTools(pi);
   return [
     {
-      id: "show-tool-status",
-      label: "Show tool status",
-      value: `${getConfiguredEnabledPiUsereqTools(config).length}/${tools.length} enabled`,
-      description: "Open the full startup-tool reference report in the editor.",
-    },
-    {
-      id: "toggle-tool",
-      label: "Toggle tool",
+      id: "enable-tools",
+      label: "Enable tools",
       value: `${getConfiguredEnabledPiUsereqTools(config).length} enabled`,
-      description: "Open the per-tool toggle menu for configurable startup tools.",
+      description: "Open the per-tool enablement menu for configurable startup tools.",
     },
     {
       id: "enable-all-tools",
@@ -1798,14 +2109,14 @@ function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, config: UseReqConfig):
       description: "Disable every configurable startup tool for future session starts.",
     },
     {
-      id: "reset-tool-defaults",
-      label: "Reset configurable-tool defaults",
+      id: "reset-defaults",
+      label: "Reset defaults",
       value: `${normalizeEnabledPiUsereqTools(undefined).length} defaults`,
       description: "Restore the documented default startup-tool selection.",
     },
     {
-      id: "back",
-      label: "Back",
+      id: "save-and-close",
+      label: "Save and close",
       value: "",
       description: "Return to the parent configuration menu.",
     },
@@ -1833,7 +2144,7 @@ function buildPiUsereqToolToggleChoices(pi: ExtensionAPI, config: UseReqConfig):
       id: "back",
       label: "Back",
       value: "",
-      description: "Return to the startup-tools menu.",
+      description: "Return to the Enable tools menu.",
     },
   ];
 }
@@ -1845,23 +2156,22 @@ function buildPiUsereqToolToggleChoices(pi: ExtensionAPI, config: UseReqConfig):
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {Promise<void>} Promise resolved when the menu closes.
- * @satisfies REQ-007, REQ-063, REQ-064, REQ-151, REQ-152, REQ-153, REQ-154
+ * @satisfies REQ-007, REQ-063, REQ-064, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193
  */
 async function configurePiUsereqToolsMenu(pi: ExtensionAPI, ctx: ExtensionCommandContext, config: UseReqConfig): Promise<void> {
   applyConfiguredPiUsereqTools(pi, config);
+  let focusedChoiceId: string | undefined;
   while (true) {
     const tools = getPiUsereqStartupTools(pi);
     const enabledTools = new Set(getConfiguredEnabledPiUsereqTools(config));
-    const choice = await showPiUsereqSettingsMenu(ctx, "startup tools", buildPiUsereqToolsMenuChoices(pi, config));
+    const choice = await showPiUsereqSettingsMenu(ctx, "Enable tools", buildPiUsereqToolsMenuChoices(pi, config), {
+      initialSelectedId: focusedChoiceId,
+    });
 
-    if (!choice || choice === "back") {
+    if (!choice || choice === "save-and-close") {
       return;
     }
-
-    if (choice === "show-tool-status") {
-      ctx.ui.setEditorText(renderPiUsereqToolsReference(pi, config));
-      continue;
-    }
+    focusedChoiceId = choice;
 
     if (choice === "enable-all-tools") {
       setConfiguredPiUsereqTools(pi, config, tools.map((tool) => tool.name));
@@ -1875,14 +2185,14 @@ async function configurePiUsereqToolsMenu(pi: ExtensionAPI, ctx: ExtensionComman
       continue;
     }
 
-    if (choice === "reset-tool-defaults") {
+    if (choice === "reset-defaults") {
       setConfiguredPiUsereqTools(pi, config, normalizeEnabledPiUsereqTools(undefined));
       ctx.ui.notify("Restored default configurable active tools", "info");
       continue;
     }
 
-    if (choice === "toggle-tool") {
-      const selectedToolName = await showPiUsereqSettingsMenu(ctx, "toggle startup tool", buildPiUsereqToolToggleChoices(pi, config));
+    if (choice === "enable-tools") {
+      const selectedToolName = await showPiUsereqSettingsMenu(ctx, "Enable tools", buildPiUsereqToolToggleChoices(pi, config));
       if (!selectedToolName || selectedToolName === "back") {
         continue;
       }
@@ -1900,20 +2210,6 @@ async function configurePiUsereqToolsMenu(pi: ExtensionAPI, ctx: ExtensionComman
   }
 }
 
-/**
- * @brief Formats one static-check configuration entry for UI display.
- * @details Renders command-backed entries as `Command(cmd args...)` and all other modules as `Module(args...)`. Runtime is O(n) in parameter count. No side effects occur.
- * @param[in] entry {StaticCheckEntry} Static-check configuration entry.
- * @return {string} Human-readable entry summary.
- */
-function formatStaticCheckEntry(entry: StaticCheckEntry): string {
-  const params = Array.isArray(entry.params) && entry.params.length > 0 ? ` ${entry.params.join(" ")}` : "";
-  if (entry.module === "Command") {
-    return `${entry.module}(${entry.cmd ?? "?"}${params})`;
-  }
-  return `${entry.module}${params ? `(${entry.params!.join(" ")})` : ""}`;
-}
-
 /**
  * @brief Summarizes configured static-check languages.
  * @details Keeps only languages with at least one configured checker, sorts them, and emits a compact `Language (count)` list. Runtime is O(l log l). No side effects occur.
@@ -1928,80 +2224,38 @@ function formatStaticCheckLanguagesSummary(config: UseReqConfig): string {
   return languages.join(", ") || "(none)";
 }
 
-/**
- * @brief Renders the static-check configuration reference view.
- * @details Produces a markdown-like summary containing configured entries, supported languages, the Command-only user module surface, and canonical example specifications. Runtime is O(l log l). No side effects occur.
- * @param[in] config {UseReqConfig} Effective project configuration.
- * @return {string} Reference text for the editor view.
- */
-function renderStaticCheckReference(config: UseReqConfig): string {
-  const lines = ["# Static-check configuration", "", `Configured languages: ${formatStaticCheckLanguagesSummary(config)}`, ""];
-  const configuredLanguages = Object.entries(config["static-check"])
-    .filter(([, entries]) => Array.isArray(entries) && entries.length > 0)
-    .sort(([left], [right]) => left.localeCompare(right));
-
-  if (configuredLanguages.length === 0) {
-    lines.push("Configured entries: (none)");
-  } else {
-    lines.push("Configured entries:");
-    for (const [language, entries] of configuredLanguages) {
-      lines.push(`- ${language}: ${(entries as StaticCheckEntry[]).map(formatStaticCheckEntry).join(", ")}`);
-    }
-  }
-
-  lines.push("", "Supported languages:");
-  for (const { language, extensions } of getSupportedStaticCheckLanguageSupport()) {
-    lines.push(`- ${language}: ${extensions.join(", ")}`);
-  }
-  lines.push(
-    "",
-    `Supported modules: ${STATIC_CHECK_MODULES.join(", ")}`,
-    "",
-    "Examples:",
-    "- Python=Command,mypy,--strict",
-    "- TypeScript=Command,eslint,--max-warnings,0",
-  );
-  return `${lines.join("\n")}\n`;
-}
-
 /**
  * @brief Builds the shared settings-menu choices for static-check management.
- * @details Serializes Command-oriented static-check actions into right-valued menu rows consumed by the shared settings-menu renderer while omitting user-facing module selection. Runtime is O(1). No external state is mutated.
+ * @details Serializes guided Command-oriented static-check actions into right-valued menu rows consumed by the shared settings-menu renderer while omitting raw-spec and reference-only actions. Runtime is O(1). No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered static-check menu choices.
- * @satisfies REQ-008, REQ-160, REQ-161, REQ-151, REQ-152, REQ-153, REQ-154
+ * @satisfies REQ-008, REQ-150, REQ-160, REQ-161, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193
  */
 function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   const supportedLanguageCount = getSupportedStaticCheckLanguageSupport().length;
   const configuredLanguageCount = Object.values(config["static-check"]).filter((entries) => entries.length > 0).length;
   return [
     {
-      id: "add-entry-supported-language",
-      label: "Add entry for supported language",
+      id: "add-static-check-entry",
+      label: "Add static code checker",
       value: `${supportedLanguageCount} languages`,
-      description: "Select a supported language, then configure the Command static-check executable.",
+      description: "Select a supported language, then configure one Command static-check executable.",
     },
     {
-      id: "add-entry-raw-spec",
-      label: "Add entry from LANG=MODULE[,CMD[,PARAM...]]",
-      value: "raw spec",
-      description: "Enter one raw Command-based static-check specification string in canonical CLI format.",
-    },
-    {
-      id: "remove-language-entry",
-      label: "Remove language entry",
+      id: "remove-static-check-entry",
+      label: "Remove static code checker",
       value: configuredLanguageCount > 0 ? `${configuredLanguageCount} configured` : "(none)",
       description: "Remove every configured static-check entry for one language.",
     },
     {
-      id: "show-supported-languages",
-      label: "Show supported languages",
-      value: `${supportedLanguageCount} languages`,
-      description: "Open the static-check reference report in the editor.",
+      id: "reset-defaults",
+      label: "Reset defaults",
+      value: configuredLanguageCount > 0 ? `${configuredLanguageCount} configured` : "(none)",
+      description: "Remove every configured static-check entry and restore the default empty static-check configuration.",
     },
     {
-      id: "back",
-      label: "Back",
+      id: "save-and-close",
+      label: "Save and close",
       value: "",
       description: "Return to the parent configuration menu.",
     },
@@ -2030,7 +2284,7 @@ function buildSupportedStaticCheckLanguageChoices(config: UseReqConfig): PiUsere
       id: "back",
       label: "Back",
       value: "",
-      description: "Return to the static-check menu.",
+      description: "Return to the Language static code checkers menu.",
     },
   ];
 }
@@ -2055,33 +2309,32 @@ function buildConfiguredStaticCheckLanguageChoices(config: UseReqConfig): PiUser
       id: "back",
       label: "Back",
       value: "",
-      description: "Return to the static-check menu.",
+      description: "Return to the Language static code checkers menu.",
     },
   ];
 }
 
 /**
  * @brief Runs the interactive static-check configuration menu.
- * @details Lets the user inspect support, add Command entries by guided prompts or raw spec strings, and remove configured language entries through the shared settings-menu renderer until the user exits. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
+ * @details Lets the user add Command entries by guided prompts, remove configured language entries, and reset the static-check configuration through the shared settings-menu renderer until the user exits. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {Promise<void>} Promise resolved when the menu closes.
- * @satisfies REQ-008, REQ-160, REQ-161, REQ-151, REQ-152, REQ-153, REQ-154
+ * @satisfies REQ-008, REQ-150, REQ-160, REQ-161, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193, REQ-195
  */
 async function configureStaticCheckMenu(ctx: ExtensionCommandContext, config: UseReqConfig): Promise<void> {
+  let focusedChoiceId: string | undefined;
   while (true) {
-    const staticChoice = await showPiUsereqSettingsMenu(ctx, "static-check", buildStaticCheckMenuChoices(config));
+    const staticChoice = await showPiUsereqSettingsMenu(ctx, "Language static code checkers", buildStaticCheckMenuChoices(config), {
+      initialSelectedId: focusedChoiceId,
+    });
 
-    if (!staticChoice || staticChoice === "back") {
+    if (!staticChoice || staticChoice === "save-and-close") {
       return;
     }
+    focusedChoiceId = staticChoice;
 
-    if (staticChoice === "show-supported-languages") {
-      ctx.ui.setEditorText(renderStaticCheckReference(config));
-      continue;
-    }
-
-    if (staticChoice === "add-entry-supported-language") {
+    if (staticChoice === "add-static-check-entry") {
       const selectedLanguage = await showPiUsereqSettingsMenu(ctx, "static-check language", buildSupportedStaticCheckLanguageChoices(config));
       if (!selectedLanguage || selectedLanguage === "back") {
         continue;
@@ -2109,29 +2362,18 @@ async function configureStaticCheckMenu(ctx: ExtensionCommandContext, config: Us
       continue;
     }
 
-    if (staticChoice === "add-entry-raw-spec") {
-      const spec = await ctx.ui.input("Static-check spec", "Python=Command,true");
-      if (!spec?.trim()) {
-        continue;
-      }
-      try {
-        const [canonicalLang, entry] = parseEnableStaticCheck(spec.trim());
-        config["static-check"][canonicalLang] ??= [];
-        config["static-check"][canonicalLang]!.push(entry);
-        ctx.ui.notify(`Added ${entry.module} checker for ${canonicalLang}`, "info");
-      } catch (error) {
-        ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
-      }
-      continue;
-    }
-
-    if (staticChoice === "remove-language-entry") {
-      const configuredLanguage = await showPiUsereqSettingsMenu(ctx, "remove static-check language", buildConfiguredStaticCheckLanguageChoices(config));
+    if (staticChoice === "remove-static-check-entry") {
+      const configuredLanguage = await showPiUsereqSettingsMenu(ctx, "Remove static code checker", buildConfiguredStaticCheckLanguageChoices(config));
       if (!configuredLanguage || configuredLanguage === "back") {
         continue;
       }
       delete config["static-check"][configuredLanguage];
       ctx.ui.notify(`Removed static-check entries for ${configuredLanguage}`, "info");
+      continue;
+    }
+    if (staticChoice === "reset-defaults") {
+      config["static-check"] = {};
+      ctx.ui.notify("Restored default static code checker configuration", "info");
     }
   }
 }
@@ -2142,7 +2384,7 @@ async function configureStaticCheckMenu(ctx: ExtensionCommandContext, config: Us
  * @param[in] cwd {string} Current working directory.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered top-level menu choices.
- * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-162
+ * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-162, REQ-190, REQ-191, REQ-197
  */
 function buildPiUsereqMenuChoices(
   cwd: string,
@@ -2151,43 +2393,43 @@ function buildPiUsereqMenuChoices(
   return [
     {
       id: "docs-dir",
-      label: "docs-dir",
+      label: "Document directory",
       value: config["docs-dir"],
       description: "Edit the repository-relative directory that stores REQUIREMENTS, WORKFLOW, and REFERENCES documents.",
     },
-    {
-      id: "tests-dir",
-      label: "tests-dir",
-      value: config["tests-dir"],
-      description: "Edit the repository-relative directory used for project test assets and static-check selection.",
-    },
     {
       id: "src-dir",
-      label: "src-dir",
+      label: "Source-code directories",
       value: config["src-dir"].join(", "),
       description: "Manage the repository-relative source directories scanned by project-scope tools.",
     },
+    {
+      id: "tests-dir",
+      label: "Unit tests directory",
+      value: config["tests-dir"],
+      description: "Edit the repository-relative directory used for project test assets and static-check selection.",
+    },
     {
       id: "static-check",
-      label: "static-check",
+      label: "Language static code checkers",
       value: formatStaticCheckLanguagesSummary(config),
-      description: "Manage configured static-check entries and inspect supported languages and modules.",
+      description: "Manage guided Command static-check entries by language.",
     },
     {
       id: "startup-tools",
-      label: "startup tools",
+      label: "Enable tools",
       value: `${getConfiguredEnabledPiUsereqTools(config).length} enabled`,
       description: "Manage which configurable tools become active during session_start.",
     },
     {
       id: "notifications",
-      label: "notifications",
-      value: `beep:${formatPiNotifyBeepStatus(config)} • sound:${config["notify-sound"]}`,
-      description: "Manage terminal beep flags, selected notify command, hotkey bind, per-level notify commands, and the nested Pushover submenu.",
+      label: "Notifications",
+      value: `notification:${formatPiNotifyStatus(config)} • sound:${config["notify-sound"]} • pushover:${formatPiNotifyPushoverStatus(config)}`,
+      description: "Manage command-notify, sound, and Pushover settings with dedicated event submenus.",
     },
     {
       id: "show-config",
-      label: "show-config",
+      label: "Show configuration",
       value: formatProjectConfigPathForMenu(cwd),
       valueTone: "dim",
       description: "Write the current project configuration JSON into the editor without saving additional changes.",
@@ -2212,25 +2454,31 @@ function buildPiUsereqMenuChoices(
  * @details Exposes add and remove actions for `src-dir` entries through right-valued menu rows consumed by the shared settings-menu renderer. Runtime is O(s) in source-directory count. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered source-directory management choices.
- * @satisfies REQ-006, REQ-151, REQ-152, REQ-153, REQ-154
+ * @satisfies REQ-006, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193
  */
 function buildSrcDirMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   return [
     {
       id: "add-src-dir-entry",
-      label: "Add src-dir entry",
+      label: "Add source-code directory",
       value: `${config["src-dir"].length} configured`,
       description: "Append one repository-relative source directory to the current configuration.",
     },
     {
       id: "remove-src-dir-entry",
-      label: "Remove src-dir entry",
+      label: "Remove source-code directory",
       value: config["src-dir"].join(", "),
       description: "Select one configured source directory to remove from the current configuration.",
     },
     {
-      id: "back",
-      label: "Back",
+      id: "reset-defaults",
+      label: "Reset defaults",
+      value: `${DEFAULT_SRC_DIRS.join(", ")}`,
+      description: "Restore the documented default source-directory configuration.",
+    },
+    {
+      id: "save-and-close",
+      label: "Save and close",
       value: "",
       description: "Return to the parent configuration menu.",
     },
@@ -2268,7 +2516,7 @@ function buildSrcDirRemovalChoices(config: UseReqConfig): PiUsereqSettingsMenuCh
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {Promise<void>} Promise resolved when configuration is saved and the menu closes.
- * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-162
+ * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-162, REQ-190, REQ-191, REQ-192, REQ-194, REQ-195
  */
 async function configurePiUsereq(
   pi: ExtensionAPI,
@@ -2284,11 +2532,13 @@ async function configurePiUsereq(
     renderPiUsereqStatus(statusController, ctx);
   };
 
+  let focusedChoiceId: string | undefined;
   while (true) {
     const choice = await showPiUsereqSettingsMenu(
       ctx,
       "pi-usereq",
       buildPiUsereqMenuChoices(ctx.cwd, config),
+      { initialSelectedId: focusedChoiceId },
     );
     if (!choice || choice === "save-and-close") {
       ensureSaved();
@@ -2298,37 +2548,47 @@ async function configurePiUsereq(
       }
       return;
     }
+    focusedChoiceId = choice;
     if (choice === "docs-dir") {
-      const value = await ctx.ui.input("docs-dir", config["docs-dir"]);
+      const value = await ctx.ui.input("Document directory", config["docs-dir"]);
       if (value?.trim()) config["docs-dir"] = value.trim();
       continue;
     }
     if (choice === "tests-dir") {
-      const value = await ctx.ui.input("tests-dir", config["tests-dir"]);
+      const value = await ctx.ui.input("Unit tests directory", config["tests-dir"]);
       if (value?.trim()) config["tests-dir"] = value.trim();
       continue;
     }
     if (choice === "src-dir") {
+      let srcFocusedChoiceId: string | undefined;
       while (true) {
-        const srcAction = await showPiUsereqSettingsMenu(ctx, "src-dir", buildSrcDirMenuChoices(config));
-        if (!srcAction || srcAction === "back") {
+        const srcAction = await showPiUsereqSettingsMenu(ctx, "Source-code directories", buildSrcDirMenuChoices(config), {
+          initialSelectedId: srcFocusedChoiceId,
+        });
+        if (!srcAction || srcAction === "save-and-close") {
           break;
         }
+        srcFocusedChoiceId = srcAction;
         if (srcAction === "add-src-dir-entry") {
-          const value = await ctx.ui.input("New src-dir entry", "src");
+          const value = await ctx.ui.input("New source-code directory", "src");
           if (value?.trim()) {
             config["src-dir"] = [...config["src-dir"], value.trim()];
           }
           continue;
         }
         if (srcAction === "remove-src-dir-entry") {
-          const toRemove = await showPiUsereqSettingsMenu(ctx, "remove src-dir entry", buildSrcDirRemovalChoices(config));
+          const toRemove = await showPiUsereqSettingsMenu(ctx, "Remove source-code directory", buildSrcDirRemovalChoices(config));
           if (toRemove && toRemove !== "back") {
             config["src-dir"] = config["src-dir"].filter((entry) => entry !== toRemove);
             if (config["src-dir"].length === 0) {
               config["src-dir"] = ["src"];
             }
           }
+          continue;
+        }
+        if (srcAction === "reset-defaults") {
+          config["src-dir"] = [...DEFAULT_SRC_DIRS];
+          ctx.ui.notify("Restored default source-code directories", "info");
         }
       }
       continue;
@@ -2348,6 +2608,7 @@ async function configurePiUsereq(
     if (choice === "reset-defaults") {
       config = getDefaultConfig(projectBase);
       applyConfiguredPiUsereqTools(pi, config);
+      ctx.ui.notify("Restored all default configuration values", "info");
       continue;
     }
     if (choice === "show-config") {
@@ -2381,7 +2642,7 @@ function registerConfigCommands(
  * @brief Registers the complete pi-usereq extension.
  * @details Validates installation-owned bundled resources, registers prompt and
  * configuration commands plus agent tools, registers the configurable
- * successful-run sound shortcut when the runtime supports shortcuts, and
+ * notification-sound shortcut when the runtime supports shortcuts, and
  * installs shared wrappers for all supported pi lifecycle hooks so status
  * telemetry, context usage, prompt timing, cumulative runtime, prompt-specific
  * Pushover metadata, and pi-notify effects remain synchronized with runtime
@@ -2391,7 +2652,7 @@ function registerConfigCommands(
  * timer scheduling.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @return {void} No return value.
- * @satisfies DES-002, REQ-004, REQ-005, REQ-009, REQ-044, REQ-045, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-129, REQ-130, REQ-131, REQ-132, REQ-133, REQ-134, REQ-135, REQ-136, REQ-137, REQ-148, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-170, REQ-171, REQ-172
+ * @satisfies DES-002, REQ-004, REQ-005, REQ-009, REQ-044, REQ-045, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-148, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197
  */
 export default function piUsereqExtension(pi: ExtensionAPI): void {
   const statusController = createPiUsereqStatusController();