pi-usereq 0.12.0 → 0.32.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.12.0";
+export const VERSION = "0.32.0";
 
 import fs from "node:fs";
 import path from "node:path";
@@ -32,6 +32,7 @@ import {
   createStaticCheckLanguageConfig,
   getDefaultConfig,
   getDefaultStaticCheckConfig,
+  getGlobalConfigPath,
   getProjectConfigPath,
   loadConfig,
   normalizeConfigPaths,
@@ -109,6 +110,7 @@ import {
   DEFAULT_DEBUG_LOG_FILE,
   DEFAULT_DEBUG_LOG_ON_STATUS,
   DEFAULT_DEBUG_STATUS_CHANGES,
+  DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED,
   DEFAULT_DEBUG_WORKFLOW_EVENTS,
   logDebugPromptEvent,
   logDebugPromptWorkflowEvent,
@@ -118,6 +120,7 @@ import {
   normalizeDebugLogFile,
   normalizeDebugLogOnStatus,
   normalizeDebugStatusChanges,
+  normalizeDebugToolCommandsEnabled,
   normalizeDebugWorkflowEvents,
   shouldLogDebugPromptWorkflowState,
   type DebugLogOnStatus,
@@ -268,12 +271,131 @@ function loadProjectConfig(cwd: string): UseReqConfig {
 }
 
 /**
- * @brief Persists project configuration from the extension runtime.
- * @details Resolves the project base, normalizes configured directory paths into project-relative form, and delegates persistence to `saveConfig` without serializing runtime-derived path metadata. Runtime is O(n) in config size. Side effects include config-file writes.
+ * @brief Describes the execute-result surface reused by debug tool wrapper commands.
+ * @details Narrows debug slash-command handlers to the same monolithic content-plus-execution wrapper returned by agent tools so editor output and notifications can reuse shared extraction helpers. The alias is compile-time only and introduces no runtime cost.
+ */
+type DebugToolCommandExecuteResult = ReturnType<typeof buildMonolithicToolExecuteResult>;
+
+/**
+ * @brief Tests whether debug tool wrapper commands should be registered for one runtime cwd.
+ * @details Loads the effective project configuration for the supplied cwd and returns `true` only when `DEBUG_TOOL_COMMANDS_ENABLED` resolves to `enable`. Malformed or unreadable config payloads degrade to `false` so extension activation never aborts while deciding whether to register optional debug commands. Runtime is dominated by config I/O. Side effects are limited to filesystem reads.
+ * @param[in] cwd {string} Candidate runtime working directory.
+ * @return {boolean} `true` when debug tool wrapper commands should be registered.
+ * @satisfies REQ-323
+ */
+function shouldRegisterDebugToolCommands(cwd: string): boolean {
+  try {
+    return normalizeDebugToolCommandsEnabled(loadProjectConfig(cwd).DEBUG_TOOL_COMMANDS_ENABLED) === "enable";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @brief Writes one debug tool-wrapper result into the editor and emits a status notification.
+ * @details Extracts the primary monolithic content text from the wrapped tool result, forwards that exact text to the editor, and emits an informational or error notification keyed by the tool exit code. Runtime is O(n) in output length. Side effects include editor-text mutation and UI notifications.
+ * @param[in] ctx {ExtensionCommandContext} Active command context.
+ * @param[in] commandName {string} Invoked debug slash-command name without the leading `/`.
+ * @param[in] result {DebugToolCommandExecuteResult} Wrapped tool execution result.
+ * @return {void} No return value.
+ * @satisfies REQ-324
+ */
+function writeDebugToolCommandResultToEditor(
+  ctx: ExtensionCommandContext,
+  commandName: string,
+  result: DebugToolCommandExecuteResult,
+): void {
+  const outputText = getMonolithicToolText(result);
+  ctx.ui.setEditorText(outputText);
+  const succeeded = result.details.execution.code === 0;
+  ctx.ui.notify(
+    succeeded
+      ? `Wrote /${commandName} output to the editor.`
+      : `FAILED: Wrote /${commandName} output to the editor.`,
+    succeeded ? "info" : "error",
+  );
+}
+
+/**
+ * @brief Executes one config-gated debug tool wrapper slash command.
+ * @details Resolves a live cwd for the invoking command context, refreshes runtime path state, loads the effective project configuration, rejects execution when debug tool wrapper commands are disabled, and otherwise writes the selected wrapped tool output into the editor. Runtime is dominated by the delegated tool runner. Side effects include runtime-path bootstrap, filesystem reads, optional tool side effects, editor-text mutation, and UI notifications.
+ * @param[in] ctx {ExtensionCommandContext} Active command context.
+ * @param[in] commandName {string} Invoked debug slash-command name without the leading `/`.
+ * @param[in] operation {(projectBase: string, config: UseReqConfig) => DebugToolCommandExecuteResult} Wrapped tool executor.
+ * @return {void} No return value.
+ * @throws {ReqError} Throws when debug tool wrapper commands are disabled for the active project.
+ * @satisfies REQ-324, REQ-325
+ */
+function executeDebugToolCommand(
+  ctx: ExtensionCommandContext,
+  commandName: string,
+  operation: (projectBase: string, config: UseReqConfig) => DebugToolCommandExecuteResult,
+): void {
+  const commandCwd = resolveLiveBootstrapCwd(ctx.cwd);
+  syncContextCwdMirror(ctx, commandCwd);
+  bootstrapRuntimePathState(commandCwd, {
+    gitPath: resolveRuntimeGitPath(commandCwd),
+  });
+  const projectBase = getProjectBase(commandCwd);
+  const config = loadProjectConfig(commandCwd);
+  if (normalizeDebugToolCommandsEnabled(config.DEBUG_TOOL_COMMANDS_ENABLED) !== "enable") {
+    const message = `ERROR: /${commandName} is disabled by Debug > Enable debug commands for tools.`;
+    ctx.ui.notify(message, "error");
+    throw new ReqError(message, 1);
+  }
+  writeDebugToolCommandResultToEditor(ctx, commandName, operation(projectBase, config));
+}
+
+/**
+ * @brief Registers config-gated debug slash-command wrappers for selected built-in analysis tools.
+ * @details Registers `debug-compress`, `debug-references`, `debug-static-check`, and `debug-tokens` as extension commands that reuse the same runner paths as the corresponding agent tools and write the resulting monolithic text into the editor instead of the LLM content channel. Re-registering the same commands is idempotent because pi keeps the latest same-extension command definition per name. Runtime is O(1) for registration; handler cost depends on the selected runner. Side effects include command registration.
+ * @param[in] pi {ExtensionAPI} Active extension API instance.
+ * @return {void} No return value.
+ * @satisfies DES-015, REQ-323, REQ-324, REQ-325
+ */
+function registerDebugToolCommands(pi: ExtensionAPI): void {
+  const registerDebugToolCommand = (
+    commandName: string,
+    description: string,
+    operation: (projectBase: string, config: UseReqConfig) => DebugToolCommandExecuteResult,
+  ): void => {
+    pi.registerCommand(commandName, {
+      description,
+      handler: async (_args, ctx) => {
+        executeDebugToolCommand(ctx, commandName, operation);
+      },
+    });
+  };
+
+  registerDebugToolCommand(
+    "debug-compress",
+    "Run compress and write the tool output into the editor",
+    (projectBase, config) => executeMonolithicTool(() => runCompress(projectBase, config)),
+  );
+  registerDebugToolCommand(
+    "debug-references",
+    "Run references and write the tool output into the editor",
+    (projectBase, config) => executeStatusTool(() => runReferences(projectBase, config)),
+  );
+  registerDebugToolCommand(
+    "debug-static-check",
+    "Run static-check and write the tool output into the editor",
+    (projectBase, config) => executeMonolithicTool(() => runProjectStaticCheck(projectBase, config)),
+  );
+  registerDebugToolCommand(
+    "debug-tokens",
+    "Run tokens and write the tool output into the editor",
+    (projectBase, config) => executeMonolithicTool(() => runTokens(projectBase, config)),
+  );
+}
+
+/**
+ * @brief Persists effective project configuration from the extension runtime.
+ * @details Resolves the project base, normalizes configured local directory paths into project-relative form, and delegates split local/global persistence to `saveConfig` without serializing runtime-derived path metadata. Runtime is O(n) in config size. Side effects include config-file writes.
  * @param[in] cwd {string} Current working directory.
- * @param[in] config {UseReqConfig} Configuration to persist.
+ * @param[in] config {UseReqConfig} Effective configuration to persist.
  * @return {void} No return value.
- * @satisfies REQ-146
+ * @satisfies REQ-146, REQ-315
  */
 function saveProjectConfig(cwd: string, config: UseReqConfig): void {
   const projectBase = getProjectBase(cwd);
@@ -281,18 +403,28 @@ 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.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.
+ * @brief Formats the current local config path for top-level menu display.
+ * @details Resolves `<base-path>/.pi-usereq.json` from the cwd-derived project base and reuses the shared runtime-path formatter so the `Show local configuration` row uses the documented `~`-relative display contract. Runtime is O(p) in path length. No external state is mutated.
  * @param[in] cwd {string} Current working directory.
- * @return {string} `~`-relative or absolute config path display value.
+ * @return {string} `~`-relative or absolute local config-path display value.
  * @satisfies REQ-162
  */
-function formatProjectConfigPathForMenu(cwd: string): string {
+function formatLocalConfigPathForMenu(cwd: string): string {
   return formatRuntimePathForDisplay(
     getProjectConfigPath(getProjectBase(cwd)),
   );
 }
 
+/**
+ * @brief Formats the current global config path for top-level menu display.
+ * @details Resolves `~/.config/pi-usereq/config.json` through the shared runtime-path formatter so the `Show global configuration` row uses the documented `~`-relative display contract. Runtime is O(p) in path length. No external state is mutated.
+ * @return {string} `~`-relative or absolute global config-path display value.
+ * @satisfies REQ-319
+ */
+function formatGlobalConfigPathForMenu(): string {
+  return formatRuntimePathForDisplay(getGlobalConfigPath());
+}
+
 /**
  * @brief Builds the standardized terminal rows appended to every configuration menu.
  * @details Returns the canonical value-less `Reset defaults` row so all configuration menus and descendant selector menus share the same terminal ordering contract without rendering `Save and close`. Runtime is O(1). No external state is mutated.
@@ -409,21 +541,46 @@ async function confirmResetChanges(
 }
 
 /**
- * @brief Writes the already-persisted project configuration file text into the editor.
- * @details Reads the current `.pi-usereq.json` file content from disk after the caller has saved any pending configuration changes and forwards that exact persisted text into the editor. Runtime is O(n) in serialized config size. Side effects include filesystem reads and editor-text mutation.
+ * @brief Writes one already-persisted config file text into the editor.
+ * @details Reads the target config file from disk after the caller has saved any pending changes and forwards the exact persisted text into the editor. Runtime is O(n) in serialized config size. Side effects include filesystem reads and editor-text mutation.
+ * @param[in] ctx {ExtensionCommandContext} Active command context.
+ * @param[in] configPath {string} Absolute persisted config path.
+ * @return {void} No return value.
+ */
+function writePersistedConfigToEditor(
+  ctx: ExtensionCommandContext,
+  configPath: string,
+): void {
+  ctx.ui.setEditorText(fs.readFileSync(configPath, "utf8"));
+}
+
+/**
+ * @brief Writes the already-persisted local configuration file text into the editor.
+ * @details Reads `<base-path>/.pi-usereq.json` from disk after the caller has saved any pending local and global configuration changes, then forwards that exact persisted text into the editor. Runtime is O(n) in serialized config size. Side effects include filesystem reads and editor-text mutation.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in] cwd {string} Current working directory.
- * @param[in] _config {UseReqConfig} Unused effective project configuration retained for stable call-site shape.
  * @return {void} No return value.
  * @satisfies REQ-031
  */
-function writePersistedProjectConfigToEditor(
+function writePersistedLocalConfigToEditor(
   ctx: ExtensionCommandContext,
   cwd: string,
-  _config: UseReqConfig,
 ): void {
   const projectBase = getProjectBase(cwd);
-  ctx.ui.setEditorText(fs.readFileSync(getProjectConfigPath(projectBase), "utf8"));
+  writePersistedConfigToEditor(ctx, getProjectConfigPath(projectBase));
+}
+
+/**
+ * @brief Writes the already-persisted global configuration file text into the editor.
+ * @details Reads `~/.config/pi-usereq/config.json` from disk after the caller has saved any pending local and global configuration changes, then forwards that exact persisted text into the editor. Runtime is O(n) in serialized config size. Side effects include filesystem reads and editor-text mutation.
+ * @param[in] ctx {ExtensionCommandContext} Active command context.
+ * @return {void} No return value.
+ * @satisfies REQ-318
+ */
+function writePersistedGlobalConfigToEditor(
+  ctx: ExtensionCommandContext,
+): void {
+  writePersistedConfigToEditor(ctx, getGlobalConfigPath());
 }
 
 /**
@@ -1375,16 +1532,17 @@ function getDebugToolToggleNames(): PiUsereqStartupToolName[] {
 
 /**
  * @brief Restores the debug configuration subtree to its documented defaults.
- * @details Resets global debug enablement, log path, workflow-state filter, dedicated workflow-event logging, and selected tool plus prompt debug toggles without mutating unrelated settings. Runtime is O(1). Side effect: mutates `config`.
+ * @details Resets global debug enablement, log path, tool-wrapper command registration, workflow-state filter, dedicated workflow-event logging, and selected tool plus prompt debug toggles without mutating unrelated settings. Runtime is O(1). Side effect: mutates `config`.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {void} No return value.
- * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-195, REQ-277
+ * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-195, REQ-277, REQ-322
  */
 function resetDebugConfigToDefaults(config: UseReqConfig): void {
   config.DEBUG_ENABLED = "disable";
   config.DEBUG_LOG_FILE = DEFAULT_DEBUG_LOG_FILE;
   config.DEBUG_STATUS_CHANGES = DEFAULT_DEBUG_STATUS_CHANGES;
   config.DEBUG_WORKFLOW_EVENTS = DEFAULT_DEBUG_WORKFLOW_EVENTS;
+  config.DEBUG_TOOL_COMMANDS_ENABLED = DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED;
   config.DEBUG_LOG_ON_STATUS = DEFAULT_DEBUG_LOG_ON_STATUS;
   config.DEBUG_ENABLED_TOOLS = [];
   config.DEBUG_ENABLED_PROMPTS = [];
@@ -1466,10 +1624,10 @@ async function selectDebugLogOnStatus(
 
 /**
  * @brief Builds the shared settings-menu choices for debug logging configuration.
- * @details Serializes global debug controls plus workflow-state, dedicated workflow-event, per-tool, and per-prompt toggles into one submenu, deriving inventories from the canonical tool and prompt lists and dimming locked rows while debug is disabled. Runtime is O(t + p). No external state is mutated.
+ * @details Serializes global debug controls plus tool-wrapper command registration, workflow-state, dedicated workflow-event, per-tool, and per-prompt toggles into one submenu, deriving inventories from the canonical tool and prompt lists and dimming locked rows while debug is disabled. Runtime is O(t + p). No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered debug-menu choices.
- * @satisfies REQ-240, REQ-241, REQ-242, REQ-243, REQ-193, REQ-277
+ * @satisfies REQ-240, REQ-241, REQ-242, REQ-243, REQ-193, REQ-277, REQ-321, REQ-322
  */
 function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   const debugEnabled = config.DEBUG_ENABLED === "enable";
@@ -1492,6 +1650,16 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
       },
       debugEnabled,
     ),
+    buildDebugMenuChoice(
+      {
+        id: "debug-tool-commands-enabled",
+        label: "Enable debug commands for tools",
+        value: normalizeDebugToolCommandsEnabled(config.DEBUG_TOOL_COMMANDS_ENABLED),
+        values: ["enable", "disable"],
+        description: "Enable or disable slash-command wrappers for `compress`, `references`, `static-check`, and `tokens`.",
+      },
+      debugEnabled,
+    ),
     buildDebugMenuChoice(
       {
         id: "debug-log-on-status",
@@ -1551,17 +1719,28 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
 
 /**
  * @brief Runs the interactive Debug submenu.
- * @details Lets the user toggle global debug enablement, edit debug file and workflow filters, toggle dedicated workflow-event logging, mutate per-tool and per-prompt debug selectors, and restore subtree defaults while preserving row focus across re-renders. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
+ * @details Lets the user toggle global debug enablement, tool-wrapper command registration, debug file and workflow filters, dedicated workflow-event logging, per-tool selectors, and per-prompt selectors while preserving row focus across re-renders. Runtime depends on user interaction count. Side effects include UI updates, config mutation, and optional debug command registration.
+ * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {Promise<void>} Promise resolved when the submenu closes.
- * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-192, REQ-193, REQ-195, REQ-277
+ * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-192, REQ-193, REQ-195, REQ-277, REQ-321, REQ-322, REQ-323
  */
 async function configureDebugMenu(
+  pi: ExtensionAPI,
   ctx: ExtensionCommandContext,
   config: UseReqConfig,
   onConfigChange: () => void,
 ): Promise<void> {
+  const updateDebugToolCommandsEnabled = (nextValue: unknown): void => {
+    config.DEBUG_TOOL_COMMANDS_ENABLED = normalizeDebugToolCommandsEnabled(nextValue);
+    onConfigChange();
+    if (config.DEBUG_TOOL_COMMANDS_ENABLED === "enable") {
+      registerDebugToolCommands(pi);
+    }
+    ctx.ui.notify(`Debug tool commands ${config.DEBUG_TOOL_COMMANDS_ENABLED}`, "info");
+  };
+
   let focusedChoiceId: string | undefined;
   while (true) {
     const choice = await showPiUsereqSettingsMenu(ctx, "Debug", buildDebugMenuChoices(config), {
@@ -1574,6 +1753,10 @@ async function configureDebugMenu(
           ctx.ui.notify(`Debug ${config.DEBUG_ENABLED}`, "info");
           return;
         }
+        if (choiceId === "debug-tool-commands-enabled") {
+          updateDebugToolCommandsEnabled(newValue);
+          return;
+        }
         if (choiceId === "debug-status-changes") {
           config.DEBUG_STATUS_CHANGES = normalizeDebugStatusChanges(newValue);
           onConfigChange();
@@ -1634,6 +1817,7 @@ async function configureDebugMenu(
       const resetPreview: ResetConfirmationChange[] = [
         { label: "Debug", previousValue: config.DEBUG_ENABLED, nextValue: "disable" },
         { label: "Log file", previousValue: config.DEBUG_LOG_FILE, nextValue: DEFAULT_DEBUG_LOG_FILE },
+        { label: "Enable debug commands for tools", previousValue: normalizeDebugToolCommandsEnabled(config.DEBUG_TOOL_COMMANDS_ENABLED), nextValue: DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED },
         { label: "Status changes", previousValue: normalizeDebugStatusChanges(config.DEBUG_STATUS_CHANGES), nextValue: DEFAULT_DEBUG_STATUS_CHANGES },
         { label: "Workflow events", previousValue: normalizeDebugWorkflowEvents(config.DEBUG_WORKFLOW_EVENTS), nextValue: DEFAULT_DEBUG_WORKFLOW_EVENTS },
         { label: "Log on status", previousValue: config.DEBUG_LOG_ON_STATUS, nextValue: DEFAULT_DEBUG_LOG_ON_STATUS },
@@ -1669,6 +1853,12 @@ async function configureDebugMenu(
       }
       continue;
     }
+    if (choice === "debug-tool-commands-enabled") {
+      updateDebugToolCommandsEnabled(
+        config.DEBUG_TOOL_COMMANDS_ENABLED === "enable" ? "disable" : "enable",
+      );
+      continue;
+    }
     if (choice === "debug-status-changes") {
       config.DEBUG_STATUS_CHANGES = normalizeDebugStatusChanges(
         config.DEBUG_STATUS_CHANGES === "enable" ? "disable" : "enable",
@@ -2314,7 +2504,7 @@ async function selectPiNotifySoundLevel(
 
 /**
  * @brief Runs the interactive notification-configuration menu.
- * @details Exposes command-notify, sound, and Pushover controls through the shared settings-menu renderer, delegates completed/interrupted/failed toggles to dedicated event submenus, persists boot-sound changes without altering the active runtime sound level, keeps `Enable pushover` locked until both credentials are populated, decodes escaped control-sequence input for `Pushover text`, and preserves row focus across menu re-renders. 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, persists every notification subtree mutation into global configuration, delegates completed/interrupted/failed toggles to dedicated event submenus, preserves boot-sound edits without altering the active runtime sound level, keeps `Enable pushover` locked until both credentials are populated, decodes escaped control-sequence input for `Pushover text`, 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.
@@ -2610,10 +2800,10 @@ async function configurePiNotifyMenu(
 
 /**
  * @brief Registers the configurable notification-sound shortcut when supported.
- * @details Loads the current project config, registers one raw pi shortcut when
+ * @details Loads the current effective config, registers one raw pi shortcut when
  * the runtime exposes `registerShortcut(...)`, cycles only the active runtime
- * sound level on invocation, leaves `.pi-usereq.json` unchanged, refreshes the
- * status bar, and emits one info notification. Runtime is O(1) for registration
+ * sound level on invocation, leaves persisted local and global configuration
+ * unchanged, refreshes the status bar, and emits one info notification. Runtime is O(1) for registration
  * plus one status update per shortcut use. Side effects include shortcut
  * registration and status updates.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
@@ -3325,7 +3515,7 @@ function buildPiUsereqToolToggleChoices(pi: ExtensionAPI, config: UseReqConfig):
 
 /**
  * @brief Runs the interactive active-tool configuration menu.
- * @details Synchronizes runtime active tools with persisted config, renders startup-tool actions through the shared settings-menu UI, preserves the documented per-tool ordering, and updates configuration state in response to selections until the user exits. Runtime depends on user interaction count. Side effects include UI updates, active-tool changes, and config mutation.
+ * @details Synchronizes runtime active tools with the effective config, renders startup-tool actions through the shared settings-menu UI, persists enablement changes into global configuration, preserves the documented per-tool ordering, and updates configuration state in response to selections until the user exits. Runtime depends on user interaction count. Side effects include UI updates, active-tool changes, and config mutation.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
@@ -3599,7 +3789,7 @@ function buildConfiguredStaticCheckLanguageChoices(config: UseReqConfig): PiUser
 
 /**
  * @brief Runs the interactive static-check configuration menu.
- * @details Lets the user add Command entries by guided prompts, remove configured language entries, toggle direct per-language enable flags, and reset the subtree to documented defaults 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 and remove global Command entries, toggle direct local per-language enable flags, and reset the subtree to documented defaults 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.
@@ -3755,11 +3945,11 @@ async function configureStaticCheckMenu(
 
 /**
  * @brief Builds the shared settings-menu choices for the top-level pi-usereq configuration UI.
- * @details Serializes primary configuration actions into right-valued menu rows consumed by the shared settings-menu renderer, including automatic git-commit mode, effective prompt-command worktree state, notification summary, debug summary, locked worktree rows when automatic git commit is disabled, and the display-only config path beside `show-config`. Runtime is O(s) in source-directory count. No external state is mutated.
+ * @details Serializes primary configuration actions into right-valued menu rows consumed by the shared settings-menu renderer, including automatic git-commit mode, effective prompt-command worktree state, notification summary, debug summary, locked worktree rows when automatic git commit is disabled, and display-only local plus global config paths. Runtime is O(s) in source-directory count. No external state is mutated.
  * @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, REQ-190, REQ-191, REQ-197, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240
+ * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-162, REQ-190, REQ-191, REQ-197, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-314, REQ-318, REQ-319, REQ-320
  */
 function buildPiUsereqMenuChoices(
   cwd: string,
@@ -3822,32 +4012,39 @@ function buildPiUsereqMenuChoices(
       id: "static-check",
       label: "Language static code checkers",
       value: formatStaticCheckLanguagesSummary(config),
-      description: "Manage guided Command static-check entries and per-language enable flags.",
+      description: "Manage global Command static-check entries and local per-language enable flags.",
     },
     {
       id: "startup-tools",
       label: "Enable tools",
       value: `${getConfiguredEnabledPiUsereqTools(config).length} enabled`,
-      description: "Manage which configurable tools become active during session_start.",
+      description: "Manage the global configurable tool set activated during session_start.",
     },
     {
       id: "notifications",
       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.",
+      description: "Manage global command-notify, sound, and Pushover settings with dedicated event submenus.",
     },
     {
       id: "debug",
       label: "Debug",
       value: formatDebugMenuSummary(config),
-      description: "Manage debug logging for tools and `req-*` prompt orchestration.",
+      description: "Manage project-local debug logging for tools and `req-*` prompt orchestration.",
+    },
+    {
+      id: "show-local-config",
+      label: "Show local configuration",
+      value: formatLocalConfigPathForMenu(cwd),
+      valueTone: "dim",
+      description: "Persist pending configuration changes and write the exact local config file text into the editor.",
     },
     {
-      id: "show-config",
-      label: "Show configuration",
-      value: formatProjectConfigPathForMenu(cwd),
+      id: "show-global-config",
+      label: "Show global configuration",
+      value: formatGlobalConfigPathForMenu(),
       valueTone: "dim",
-      description: "Persist the current project configuration file and write its exact text into the editor.",
+      description: "Persist pending configuration changes and write the exact global config file text into the editor.",
     },
     ...buildTerminalSettingsMenuChoices({
       resetDefaultsDescription: "Restore the default pi-usereq configuration for the current project base.",
@@ -3905,12 +4102,12 @@ function buildSrcDirRemovalChoices(config: UseReqConfig): PiUsereqSettingsMenuCh
 
 /**
  * @brief Runs the top-level pi-usereq configuration menu.
- * @details Loads project config, exposes docs/test/source/automatic-commit/worktree/static-check/startup-tool/notification/debug actions through the shared settings-menu renderer, forces worktree disablement when automatic git commit is disabled, prevents locked row edits, persists changes on exit, closes immediately after `Show configuration`, and refreshes the single-line status bar. Runtime depends on user interaction count. Side effects include UI updates, config writes, active-tool changes, and editor text updates.
+ * @details Loads the effective merged config, exposes docs/test/source/automatic-commit/worktree/static-check/startup-tool/notification/debug actions through the shared settings-menu renderer, forces worktree disablement when automatic git commit is disabled, prevents locked row edits, persists changes on exit, closes immediately after `Show local configuration` or `Show global configuration`, and refreshes the single-line status bar. Runtime depends on user interaction count. Side effects include UI updates, config writes, active-tool changes, and editor text updates.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @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, REQ-190, REQ-191, REQ-192, REQ-194, REQ-195, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243
+ * @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, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-314, REQ-318, REQ-319, REQ-320
  */
 async function configurePiUsereq(
   pi: ExtensionAPI,
@@ -4120,7 +4317,7 @@ async function configurePiUsereq(
       continue;
     }
     if (choice === "debug") {
-      await configureDebugMenu(ctx, config, persistConfigChange);
+      await configureDebugMenu(pi, ctx, config, persistConfigChange);
       continue;
     }
     if (choice === "reset-defaults") {
@@ -4152,12 +4349,16 @@ async function configurePiUsereq(
       ctx.ui.notify("Restored all default configuration values", "info");
       continue;
     }
-    if (choice === "show-config") {
+    if (choice === "show-local-config" || choice === "show-global-config") {
       persistConfigChange();
       if (config["notify-sound-toggle-shortcut"] !== initialShortcut) {
         ctx.ui.notify("Sound toggle hotkey bind updated; run /reload to apply the new binding", "info");
       }
-      writePersistedProjectConfigToEditor(ctx, ctx.cwd, config);
+      if (choice === "show-local-config") {
+        writePersistedLocalConfigToEditor(ctx, ctx.cwd);
+      } else {
+        writePersistedGlobalConfigToEditor(ctx);
+      }
       return;
     }
   }
@@ -4185,10 +4386,10 @@ function registerConfigCommands(
 
 /**
  * @brief Registers the complete pi-usereq extension.
- * @details Validates installation-owned bundled resources, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, registers configuration commands, registers the configurable 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, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, optional debug-log writes, and timer scheduling.
+ * @details Validates installation-owned bundled resources, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, conditionally registers config-gated debug tool wrapper commands when the current project enables them, registers configuration commands, registers the configurable 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, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, optional debug-log writes, and 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-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-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, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-304, REQ-305, REQ-306, REQ-312, REQ-313
+ * @satisfies DES-002, DES-015, REQ-004, REQ-005, REQ-009, REQ-044, 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-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, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-304, REQ-305, REQ-306, REQ-312, REQ-313, REQ-323, REQ-324, REQ-325
  */
 export default function piUsereqExtension(pi: ExtensionAPI): void {
   const statusController = createPiUsereqStatusController();
@@ -4196,6 +4397,9 @@ export default function piUsereqExtension(pi: ExtensionAPI): void {
   registerReqResetCommand(pi, statusController);
   registerReqReferencesCommand(pi, statusController);
   registerPromptCommands(pi, statusController);
+  if (shouldRegisterDebugToolCommands(getProcessCwdSafe())) {
+    registerDebugToolCommands(pi);
+  }
   registerAgentTools(pi);
   registerConfigCommands(pi, statusController);
   registerPiNotifyShortcut(pi, statusController);

package/tests/attended-results-scenarios.ts

@@ -14,11 +14,13 @@ import { detectLanguage } from "../src/core/generate-markdown.js";
 import { LANGUAGE_TAGS } from "../src/core/find-constructs.js";
 import {
   createStaticCheckLanguageConfig,
-  getProjectConfigPath,
+  getDefaultConfig,
   type UseReqConfig,
 } from "../src/core/config.js";
 import {
   initFixtureRepo,
+  readGlobalConfigJson,
+  readProjectConfigJson,
   runNodeCli,
   runPythonCli,
   runPythonInline,
@@ -450,10 +452,14 @@ function buildProjectScenarios(): AttendedScenario[] {
           normalize: createProjectNormalizer(projectBase),
           cleanup: () => removePath(projectBase),
           postAssert: () => {
-            const payload = JSON.parse(fs.readFileSync(getProjectConfigPath(projectBase), "utf8")) as UseReqConfig;
-            assert.deepEqual(payload["static-check"].Python, createStaticCheckLanguageConfig([
+            const defaultConfig = getDefaultConfig(projectBase);
+            const localPayload = readProjectConfigJson(projectBase) as unknown as Record<string, unknown>;
+            const globalPayload = readGlobalConfigJson() as unknown as Record<string, unknown>;
+            assert.equal((localPayload["static-check"] as Record<string, any>).Python.enabled, "enable");
+            assert.deepEqual((globalPayload["static-check"] as Record<string, any>).Python.checkers, [
+              ...defaultConfig["static-check"].Python.checkers,
               { module: "Command", cmd: "git", params: ["--version"] },
-            ], "enable"));
+            ]);
           },
         };
       },