pi-usereq 0.39.0 → 0.40.0

package/pi-usereq/docs/REQUIREMENTS.md

@@ -1,8 +1,8 @@
 ---
 title: "PI-useReq Requirements"
 description: Software requirements specification
-version: "0.0.70"
-date: "2026-07-09"
+version: "0.0.71"
+date: "2026-07-10"
 author: "OpenAI Codex"
 scope:
   paths:
@@ -89,6 +89,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **DES-010**: MUST centralize event-driven context snapshots, run-timing state, prompt-orchestration workflow state, and status-bar rendering through shared extension-status helpers.
 - **DES-011**: MUST implement `.github/workflows/release-npm.yml` as a two-job GitHub Actions pipeline where `check-branch` gates `build-release`, preserving changelog-driven GitHub Release creation while adding npm publication.
 - **DES-015**: MUST implement config-gated `debug-compress`, `debug-references`, `debug-static-check`, and `debug-tokens` slash-command wrappers in `src/index.ts` that reuse existing tool-runner execution paths.
+- **DES-016**: MUST deliver rendered bundled-prompt content to the LLM through `sendMessage` as a `display:false` custom message with `triggerTurn:true` and MUST NOT use `sendUserMessage` when `sendMessage` is available.
 
 ### 3.2 Functions
 - **REQ-001**: MUST access bundled prompts, git execution instructions, templates, and guidelines from `<installation-path>/resources` without requiring user-home resource copies before prompt or tool execution.
@@ -157,6 +158,10 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-066**: MUST omit `reset-context` and `context-reset` fields from persisted local and global configuration.
 - **REQ-067**: MUST send every bundled prompt-backed `req-<prompt>` payload into the current active session.
 - **REQ-068**: MUST use one prompt-delivery path that sends bundled prompt-backed `req-<prompt>` payloads through the forked execution session by using only the replacement-session context for post-switch session-bound operations.
+- **REQ-334**: MUST NOT display rendered prompt content on screen when delivering bundled prompt-backed `req-<prompt>` commands and MUST deliver the full rendered content only to the LLM agent.
+- **REQ-335**: MUST display a command invocation summary on screen for every bundled prompt-backed `req-<prompt>` command containing the command name, passed arguments, and active configuration.
+- **REQ-336**: MUST render the command invocation summary with the command name without the `req-` prefix in uppercase and the user request arguments.
+- **REQ-337**: MUST include `docs-dir`, `src-dir`, `tests-dir`, enabled context files, `AUTO_GIT_COMMIT`, effective `GIT_WORKTREE_ENABLED`, `GIT_WORKTREE_PREFIX`, enabled static-check languages, and `enabled-tools` in the command invocation summary.
 - **REQ-008**: MUST provide a `Language static code checkers` submenu that adds global Command entries by guided language flow, removes configured global checker entries, toggles local per-language enablement, and resets static-check configuration.
 - **REQ-160**: MUST hardcode `Command` as the only user-configurable static-check module and omit module-selection UI from static-check configuration menus.
 - **REQ-161**: MUST hide `Dummy` from user-configurable static-check menus while preserving existing-config parsing and debug-driver support for `Dummy` entries.
@@ -506,6 +511,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-065**: MUST verify default startup-tool enablement matches the documented enabled and disabled tool matrix.
 - **TST-110**: MUST verify `Enable tools` toggles, enable-all, disable-all, and reset-defaults persist only in global configuration.
 - **TST-066**: MUST verify `req-<prompt>` commands keep working when extension custom-tool registrations are removed from the runtime inventory.
+- **TST-121**: MUST verify bundled prompt-backed `req-<prompt>` commands deliver the full rendered prompt content through the fallback `sendUserMessage` channel when the runtime does not expose `sendMessage`.
 - **TST-059**: MUST verify every agent-tool registration defines custom `renderResult` and that compact rendering shows essential invocation parameters while expanded rendering avoids fallback raw-content display.
 - **TST-086**: MUST verify bundled prompt-backed `req-<prompt>` commands abort before prompt dispatch when the persisted execution-session header cwd or `process.cwd()` differs from the expected execution path, and abort before merge when persisted execution-session header metadata or verified worktree artifacts diverge, while stale pre-switch context probes alone do not abort.
 - **TST-113**: MUST verify default local configuration persists `DEBUG_TOOL_COMMANDS_ENABLED=disable`, and the `Debug` submenu renders `Enable debug commands for tools` before `Log file`.

package/pi-usereq/docs/WORKFLOW.md

@@ -575,8 +575,9 @@
             - `buildIgnoredGitStatusPaths(...)`: ignore extension-owned debug-log artifacts during cleanliness verification [`src/core/req-references-command.ts`]
         - `renderPrompt(...)`: render prompt-command payloads with bundled commit-instruction expansion, conditional pi.dev governance guidance, and `%%CONTEXT_FILES%%` context-file injection [`src/core/prompts.ts`]
           - `buildContextFilesBlock(...)`: build the markdown block injected at `%%CONTEXT_FILES%%` from enabled context files in documented order with pre-substituted `%%DOC_PATH%%` file references and four-backtick fences [`src/core/prompts.ts`]
-        - `deliverPromptCommand(...)`: dispatch prompt replay into the current recorded session [`src/index.ts`]
-          - External boundaries: `RecordingExtensionAPI.sendUserMessage(...)` records the delivered prompt payload.
+        - `renderPromptCommandSummary(...)`: render the on-screen command invocation summary with command name, user request arguments, and active configuration fields [`src/core/prompts.ts`]
+        - `deliverPromptCommand(...)`: dispatch the rendered prompt as a hidden `display:false` custom message plus a `display:true` summary into the current recorded session, falling back to `sendUserMessage(...)` when `sendMessage(...)` is unavailable [`src/index.ts`]
+          - External boundaries: `RecordingExtensionAPI.sendMessage(...)` or fallback `RecordingExtensionAPI.sendUserMessage(...)` records the delivered prompt payload plus summary.
         - `configurePiUsereq(...)`: execute the interactive configuration menu [`src/index.ts`]
           - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions including the `Context Files` injection toggle row, effective worktree locking, plus display-only local and global config-path rows [`src/index.ts`]
             - `formatLocalConfigPathForMenu(...)`: format the current local config path with the shared `~`-relative path formatter for menu display [`src/index.ts`]
@@ -879,10 +880,11 @@
         - `writePersistedPromptCommandSessionContext(...)`: store the reusable command-capable replacement-session context for later closure handling [`src/core/prompt-command-state.ts`]
         - `clearPersistedPromptCommandSessionContext(...)`: drop reusable command-context persistence when worktree routing is inactive [`src/core/prompt-command-state.ts`]
       - `logPromptWorkflowEvent(...)`: append selected workflow-activation debug entries [`src/index.ts`]
-      - `deliverPromptCommand(...)`: start dispatch of the rendered prompt into the current active session after execution-session activation is verified, preferring replacement-session `sendUserMessage(...)` when available, returning the delivery promise so the final `running` transition is recorded immediately after handoff begins instead of after the full prompt run completes, and suppressing the documented stale post-restore rejection once the prompt was already accepted [`src/index.ts`]
+      - `renderPromptCommandSummary(...)`: render the on-screen command invocation summary with command name without the `req-` prefix in uppercase, user request arguments, and active configuration fields [`src/core/prompts.ts`]
+      - `deliverPromptCommand(...)`: start dispatch of the rendered prompt as a hidden `display:false` custom message with `triggerTurn:true` plus a `display:true` command invocation summary into the current active session after execution-session activation is verified, preferring replacement-session `sendMessage(...)` when available, falling back to `sendUserMessage(...)` when `sendMessage(...)` is unavailable, returning the delivery promise so the final `running` transition is recorded immediately after handoff begins instead of after the full prompt run completes, and suppressing the documented stale post-restore rejection once the prompt was already accepted [`src/index.ts`]
         - `writePersistedPromptCommandRuntimeState(...)`: mirror the prepared prompt execution plan into process-scoped persistence before the worktree session switch returns control [`src/core/prompt-command-state.ts`]
-        - `isStaleExtensionContextError(...)`: classify stale post-restore delivery rejections from replacement-session `sendUserMessage(...)` [`src/core/extension-status.ts`]
-        - External boundaries: replacement-session `sendUserMessage(...)` or fallback `pi.sendUserMessage(...)` delivers the rendered prompt payload into the active `AgentSession`.
+        - `isStaleExtensionContextError(...)`: classify stale post-restore delivery rejections from replacement-session `sendMessage(...)` [`src/core/extension-status.ts`]
+        - External boundaries: replacement-session `sendMessage(...)` or `pi.sendMessage(...)` delivers the hidden rendered prompt payload plus the displayed summary into the active `AgentSession`; fallback replacement-session `sendUserMessage(...)` or `pi.sendUserMessage(...)` delivers the rendered prompt payload when `sendMessage(...)` is unavailable.
       - `abortPromptCommandExecution(...)`: restore the original session-backed base path and delete created worktree resources when command-side preflight or prompt handoff fails [`src/core/prompt-command-runtime.ts`]
         - `restorePromptCommandExecution(...)`: switch back to the original session through replacement-session-aware `ctx.switchSession(sessionPath, { withSession })` handling, reuse the persisted replacement-session context when lifecycle hooks omit `switchSession()`, carry forward the returned replacement-session context for later session-bound work, re-align `process.cwd()` to `base-path`, confirm `process.cwd()` plus the persisted original-session file header cwd when the file is already persisted, append optional workflow-restore debug entries, clear active worktree path facts, and best-effort realign the live `ctx.cwd` mirror when worktree routing was active without failing on stale or getter-only context mirrors [`src/core/prompt-command-runtime.ts`]
           - `resolvePromptCommandSwitchContext(...)`: prefer the live command context or fall back to the persisted replacement-session context keyed by the execution-session file [`src/core/prompt-command-runtime.ts`]

package/src/core/prompts.ts

@@ -6,7 +6,17 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { buildPromptReplacementPaths, DEFAULT_DOCS_DIR, type UseReqConfig } from "./config.js";
+import {
+  buildPromptReplacementPaths,
+  DEFAULT_DOCS_DIR,
+  DEFAULT_STATIC_CHECK_LANGUAGES,
+  resolveEffectiveGitWorktreeEnabled,
+  type UseReqConfig,
+} from "./config.js";
+import {
+  comparePiUsereqStartupToolNames,
+  type PiUsereqStartupToolName,
+} from "./pi-usereq-tools.js";
 import { formatRuntimePathForDisplay, normalizeRelativeDirContract } from "./path-context.js";
 import type {
   PromptCommandExecutionPlan,
@@ -355,3 +365,61 @@ export function renderPrompt(
   }
   return adapted.split("%%CONTEXT_FILES%%").join("");
 }
+
+/**
+ * @brief Defines the custom-message type used for pi-usereq prompt-command screen summaries and hidden LLM prompt delivery.
+ * @details The constant is reused as the `customType` for both the `display:true` command invocation summary and the `display:false` hidden rendered prompt so the TUI renders only the summary while the full prompt reaches the LLM agent through the same custom-message channel. Access complexity is O(1).
+ * @satisfies DES-016, REQ-334
+ */
+export const PROMPT_COMMAND_SUMMARY_CUSTOM_TYPE = "pi-usereq-prompt-command";
+
+/**
+ * @brief Builds the on-screen command invocation summary for one bundled prompt-backed `req-<prompt>` command.
+ * @details Renders the command name without the `req-` prefix in uppercase, the user request arguments, and the active configuration fields (`docs-dir`, `src-dir`, `tests-dir`, enabled context files, `AUTO_GIT_COMMIT`, effective `GIT_WORKTREE_ENABLED`, `GIT_WORKTREE_PREFIX`, enabled static-check languages, and `enabled-tools`) so the TUI shows only a compact summary while the full rendered prompt is delivered hidden to the LLM agent. Static-check languages are emitted in canonical `DEFAULT_STATIC_CHECK_LANGUAGES` order; enabled tools are emitted in documented menu order via `comparePiUsereqStartupToolNames`. Runtime is O(l + t log t) where l is language count and t is enabled-tool count. No external state is mutated.
+ * @param[in] promptName {string} Bundled prompt name without the `req-` prefix.
+ * @param[in] args {string} User request arguments passed to the slash command.
+ * @param[in] config {UseReqConfig} Effective project configuration supplying directory, git, static-check, and tool fields.
+ * @return {string} Multi-line command invocation summary text.
+ * @satisfies REQ-335, REQ-336, REQ-337
+ */
+export function renderPromptCommandSummary(
+  promptName: string,
+  args: string,
+  config: UseReqConfig,
+): string {
+  const contextFiles = CONTEXT_FILE_DESCRIPTORS
+    .filter((descriptor) => config[descriptor.flagKey])
+    .map((descriptor) => descriptor.fileName.replace(/\.md$/, "").toLowerCase())
+    .join(", ");
+  const enabledLanguages = DEFAULT_STATIC_CHECK_LANGUAGES
+    .filter((language) => config["static-check"][language]?.enabled === "enable")
+    .join(", ");
+  const enabledTools = [...config["enabled-tools"]]
+    .sort((left, right) =>
+      comparePiUsereqStartupToolNames(
+        left as PiUsereqStartupToolName,
+        right as PiUsereqStartupToolName,
+      ))
+    .join(", ");
+  const effectiveWorktree = resolveEffectiveGitWorktreeEnabled(
+    config.AUTO_GIT_COMMIT,
+    config.GIT_WORKTREE_ENABLED,
+  );
+  const lines: string[] = [
+    `Command: ${promptName.toUpperCase()}`,
+    "",
+    `User's Request: ${args}`,
+    "",
+    "Configuration:",
+    `- document dir:        ${config["docs-dir"]}`,
+    `- source-code dirs:    ${config["src-dir"].join(", ")}`,
+    `- unit tests dir:      ${config["tests-dir"]}`,
+    `- context files:       ${contextFiles}`,
+    `- auto git commit:     ${config.AUTO_GIT_COMMIT}`,
+    `- git worktree:        ${effectiveWorktree}`,
+    `- worktree prefix:     ${config.GIT_WORKTREE_PREFIX}`,
+    `- static code checks:  ${enabledLanguages}`,
+    `- enabled tools:       ${enabledTools}`,
+  ];
+  return lines.join("\n");
+}

package/src/index.ts

@@ -83,7 +83,11 @@ import {
   normalizeEnabledPiUsereqTools,
   type PiUsereqStartupToolName,
 } from "./core/pi-usereq-tools.js";
-import { renderPrompt } from "./core/prompts.js";
+import {
+  PROMPT_COMMAND_SUMMARY_CUSTOM_TYPE,
+  renderPrompt,
+  renderPromptCommandSummary,
+} from "./core/prompts.js";
 import {
   abortPromptCommandExecution,
   activatePromptCommandExecution,
@@ -906,21 +910,53 @@ function executeStatusTool(operation: () => ToolResult): ReturnType<typeof build
 
 /**
  * @brief Starts delivery of one rendered prompt into the current active session.
- * @details Prefers the replacement-session `sendUserMessage(...)` helper exposed by `withSession(...)` callbacks after session replacement so post-switch prompt delivery never reuses stale pre-switch session-bound extension objects. Returns the underlying delivery promise without awaiting it so callers can record the `running` workflow transition as soon as prompt handoff is accepted instead of waiting for the full agent turn to complete on runtimes whose async replacement-session helpers resolve only after `agent_end`. When pi later invalidates that replacement-session context during successful prompt-end restoration, the helper suppresses the documented stale-extension-context rejection because the prompt was already accepted and late rethrow would surface a false orchestration failure. Falls back to `pi.sendUserMessage(...)` only for non-replacement flows or runtimes that do not expose replacement-session helpers. Runtime is O(n) in prompt length. Side effects are limited to user-message delivery.
+ * @details Prefers the replacement-session `sendMessage(...)` helper exposed by `withSession(...)` callbacks after session replacement so post-switch prompt delivery never reuses stale pre-switch session-bound extension objects. Delivers the rendered prompt as a `display:false` custom message with `triggerTurn:true` so the full content reaches the LLM agent without appearing on screen, and emits a `display:true` command invocation summary so the TUI shows only the compact summary. Returns the underlying hidden-delivery promise without awaiting it so callers can record the `running` workflow transition as soon as prompt handoff is accepted instead of waiting for the full agent turn to complete on runtimes whose async replacement-session helpers resolve only after `agent_end`. When pi later invalidates that replacement-session context during successful prompt-end restoration, the helper suppresses the documented stale-extension-context rejection because the prompt was already accepted and late rethrow would surface a false orchestration failure. Falls back to `sendUserMessage(...)` only for non-replacement flows or runtimes that do not expose `sendMessage`. Runtime is O(n) in prompt length. Side effects are limited to hidden prompt delivery plus on-screen summary display.
  * @param[in] pi {ExtensionAPI} Handler-scoped extension API instance retained as the fallback dispatcher.
  * @param[in] content {string} Rendered prompt markdown.
+ * @param[in] summary {string} Command invocation summary text displayed on screen.
  * @param[in] context {unknown} Optional replacement-session helper context.
  * @return {Promise<void>} Promise representing eventual prompt-delivery completion.
- * @satisfies REQ-004, REQ-067, REQ-068, REQ-227, REQ-281
+ * @satisfies REQ-004, REQ-067, REQ-068, REQ-227, REQ-281, REQ-334, REQ-335, DES-016
  */
 function deliverPromptCommand(
   pi: ExtensionAPI,
   content: string,
+  summary: string,
   context?: unknown,
 ): Promise<void> {
   const replacementContext = context as {
+    sendMessage?: (
+      message: { customType: string; content: string; display: boolean },
+      options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+    ) => Promise<void> | void;
     sendUserMessage?: (message: string) => Promise<void> | void;
   } | undefined;
+  const summaryMessage = {
+    customType: PROMPT_COMMAND_SUMMARY_CUSTOM_TYPE,
+    content: summary,
+    display: true,
+  };
+  const hiddenPromptMessage = {
+    customType: PROMPT_COMMAND_SUMMARY_CUSTOM_TYPE,
+    content,
+    display: false,
+  };
+  if (typeof replacementContext?.sendMessage === "function") {
+    replacementContext.sendMessage(summaryMessage);
+    return Promise.resolve(
+      replacementContext.sendMessage(hiddenPromptMessage, { triggerTurn: true }),
+    ).catch((error) => {
+      if (isStaleExtensionContextError(error)) {
+        return;
+      }
+      throw error;
+    });
+  }
+  if (typeof pi.sendMessage === "function") {
+    pi.sendMessage(summaryMessage);
+    pi.sendMessage(hiddenPromptMessage, { triggerTurn: true });
+    return Promise.resolve();
+  }
   if (typeof replacementContext?.sendUserMessage === "function") {
     return Promise.resolve(replacementContext.sendUserMessage(content)).catch((error) => {
       if (isStaleExtensionContextError(error)) {
@@ -3073,7 +3109,12 @@ function registerPromptCommands(
             },
           );
           renderPiUsereqStatus(statusController, promptContext);
-          const promptDelivery = deliverPromptCommand(pi, content, promptContext);
+          const commandSummary = renderPromptCommandSummary(
+            promptName,
+            args,
+            config,
+          );
+          const promptDelivery = deliverPromptCommand(pi, content, commandSummary, promptContext);
           transitionPromptWorkflowState(
             statusController,
             promptContext,