pi-usereq 0.39.0 → 0.41.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.73"
+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,11 @@ 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-338**: MUST render `none` for the command invocation summary `context files`, `static code checks`, and `enabled tools` fields whenever their respective enabled-item list is empty.
 - **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.
@@ -390,12 +396,12 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-325**: MUST reject `debug-compress`, `debug-references`, `debug-static-check`, `debug-summarize`, and `debug-tokens` execution when `DEBUG_TOOL_COMMANDS_ENABLED=disable`.
 - **REQ-326**: MUST add a top-level `Context Files` row to the `pi-usereq` menu between `Unit tests directory` and `Auto git commit`.
 - **REQ-327**: MUST expose a `Context Files` submenu with separate enable toggles for `REQUIREMENTS.md`, `REFERENCES.md`, and `WORKFLOW.md` in that order.
-- **REQ-328**: MUST persist `context-files-requirements`, `context-files-references`, and `context-files-workflow` as boolean flags in local configuration, each defaulting to enabled.
+- **REQ-328**: MUST persist `context-files-requirements`, `context-files-references`, and `context-files-workflow` as boolean flags in local configuration, each defaulting to disabled.
 - **REQ-329**: MUST replace the `%%CONTEXT_FILES%%` prompt token with one markdown section per enabled context file in the order `REQUIREMENTS.md`, `REFERENCES.md`, `WORKFLOW.md`.
 - **REQ-330**: MUST render each `%%CONTEXT_FILES%%` section as the file-name heading, an HTML `<file name="<docs-dir>/<filename>">` reference with `%%DOC_PATH%%` pre-substituted, and the raw file content inside four-backtick `markdown` fences.
 - **REQ-331**: MUST omit the `%%CONTEXT_FILES%%` section for any disabled flag or missing context file without surfacing an error.
 - **REQ-332**: MUST inject `%%CONTEXT_FILES%%` content verbatim after every other prompt replacement so literal `%%...%%` tokens inside context files are not substituted.
-- **REQ-333**: MUST restore all three `Context Files` flags to enabled when the `Context Files` subtree `Reset defaults` is approved.
+- **REQ-333**: MUST restore all three `Context Files` flags to disabled when the `Context Files` subtree `Reset defaults` is approved.
 
 ## 4. Test Requirements
 - **TST-001**: MUST verify extension activation registers every documented prompt command, agent tool, and configuration command while omitting tool-name slash commands, `test-static-check`, and the removed standalone config-viewer command.
@@ -506,6 +512,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`.
@@ -516,6 +523,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-118**: MUST verify the `Context Files` submenu persists the three context-file flags in local configuration with immediate-save, reset, and focus-preserving re-render behavior.
 - **TST-119**: MUST verify `%%CONTEXT_FILES%%` replacement emits one section per enabled existing file in the documented order and omits disabled or missing files.
 - **TST-120**: MUST verify `%%CONTEXT_FILES%%` sections use the file-name heading, the pre-substituted HTML file reference, and four-backtick `markdown` fences around raw content.
+- **TST-122**: MUST verify the command invocation summary renders `none` for `context files`, `static code checks`, and `enabled tools` when no items are enabled in each respective category.
 
 ## 5. Observed Component Model
 

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, rendering `none` for empty context-file, static-check-language, and enabled-tool lists [`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, awaiting and suppressing summary delivery failures before the hidden prompt turn, 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, rendering `none` for empty context-file, static-check-language, and enabled-tool lists [`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, awaiting and suppressing the non-critical summary delivery before the authoritative hidden prompt turn so a rejecting summary never surfaces as an unhandled rejection that could terminate the process before prompt-end closure runs the worktree merge, 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/config.ts

@@ -214,14 +214,14 @@ export const DEFAULT_TESTS_DIR = "tests";
 export const DEFAULT_SRC_DIRS = ["src"];
 /**
  * @brief Defines the default value for every persisted context-file injection flag.
- * @details Each `%%CONTEXT_FILES%%` injection toggle defaults to enabled so the bundled canonical documents remain part of the prompt context unless the user explicitly disables one. Lookup complexity is O(1).
+ * @details Each `%%CONTEXT_FILES%%` injection toggle defaults to disabled so the bundled canonical documents are excluded from the prompt context unless the user explicitly enables one. Lookup complexity is O(1).
  * @satisfies REQ-328
  */
-export const DEFAULT_CONTEXT_FILES_FLAG = true;
+export const DEFAULT_CONTEXT_FILES_FLAG = false;
 
 /**
  * @brief Normalizes one persisted context-file injection flag.
- * @details Returns the documented default (`true`) for missing or non-boolean values and preserves only explicit boolean input, so any malformed persisted entry keeps context-file injection enabled. Runtime is O(1). No external state is mutated.
+ * @details Returns the documented default (`false`) for missing or non-boolean values and preserves only explicit boolean input, so any malformed persisted entry keeps context-file injection disabled. Runtime is O(1). No external state is mutated.
  * @param[in] value {unknown} Candidate persisted context-file flag.
  * @return {boolean} Normalized context-file injection flag.
  * @satisfies REQ-328

package/src/core/prompt-command-runtime.ts

@@ -6,7 +6,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import { ReqError } from "./errors.js";
 import { classifyPiNotifyOutcome, type PiNotifyOutcome } from "./pi-notify.js";
 import {
@@ -20,6 +20,7 @@ import {
   type DebugWorkflowState,
 } from "./debug-runtime.js";
 import { type PromptCommandName } from "./prompt-command-catalog.js";
+export { type PromptCommandName } from "./prompt-command-catalog.js";
 import {
   isSameOrAncestorPath,
   normalizeRelativeDirContract,
@@ -119,14 +120,13 @@ interface PromptCommandActiveContext extends PromptCommandSessionContext {
 
 /**
  * @brief Describes one serializable session entry copied into a materialized execution-session file.
- * @details Captures the stable tree-entry fields needed to write a JSONL session snapshot for cross-cwd session replacement when the origin session file has not been flushed yet. The interface is compile-time only and introduces no runtime cost.
+ * @details Captures the stable tree-entry fields needed to write a JSONL session snapshot for cross-cwd session replacement when the origin session file has not been flushed yet. Mirrors the SDK `SessionEntryBase` shape without an index signature so the SDK `SessionEntry` union remains structurally assignable for passthrough serialization. The interface is compile-time only and introduces no runtime cost.
  */
 interface PromptCommandSessionEntry {
   type: string;
   id: string;
   parentId: string | null;
   timestamp: string;
-  [key: string]: unknown;
 }
 
 /**
@@ -705,7 +705,7 @@ async function switchPromptCommandSession(
     throw new ReqError(`ERROR: Prompt orchestration requires ctx.switchSession() for ${sessionFile}.`, 1);
   }
   let replacementContext: PromptCommandActiveContext | undefined;
-  let switchResult: { cancelled?: boolean } | void;
+  let switchResult: { cancelled?: boolean } | void = undefined;
   try {
     switchResult = await ctx.switchSession(sessionFile, {
       withSession: async (activeContext) => {
@@ -840,9 +840,9 @@ const PROMPT_REQUIRED_DOCS: Record<PromptCommandName, readonly PromptRequiredDoc
  * @details Delegates to `spawnSync`, preserves the supplied working directory, and returns the raw subprocess result used by prompt-command orchestration. Runtime is dominated by external process execution. Side effects include process spawning.
  * @param[in] command {string[]} Executable plus argument vector.
  * @param[in] cwd {string} Working directory for the subprocess.
- * @return {ReturnType<typeof spawnSync>} Captured subprocess result.
+ * @return {SpawnSyncReturns<string>} Captured subprocess result with UTF-8 decoded stdout and stderr.
  */
-function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync> {
+function runCapture(command: string[], cwd: string): SpawnSyncReturns<string> {
   return spawnSync(command[0]!, command.slice(1), {
     cwd,
     encoding: "utf8",

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`. The `context files`, `static code checks`, and `enabled tools` fields render the literal `none` placeholder whenever their respective enabled-item list is empty so the summary never shows a blank value. 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, REQ-338
+ */
+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(", ") || "none";
+  const enabledLanguages = DEFAULT_STATIC_CHECK_LANGUAGES
+    .filter((language) => config["static-check"][language]?.enabled === "enable")
+    .join(", ") || "none";
+  const enabledTools = ([...config["enabled-tools"]]
+    .sort((left, right) =>
+      comparePiUsereqStartupToolNames(
+        left as PiUsereqStartupToolName,
+        right as PiUsereqStartupToolName,
+      ))
+    .join(", ") || "none");
+  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/core/req-references-command.ts

@@ -4,7 +4,7 @@
  * @details Performs slash-command-owned git validation reuse, reference-file generation, targeted staging, fixed-message commit creation, and post-commit cleanliness verification without creating a worktree or starting an LLM session. Runtime is dominated by git subprocess execution plus source-summary generation and one documentation write. Side effects include filesystem writes and git index/history mutation.
  */
 
-import { spawnSync } from "node:child_process";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import path from "node:path";
 import type { UseReqConfig } from "./config.js";
 import { ReqError } from "./errors.js";
@@ -39,9 +39,9 @@ export interface ReqReferencesCommandPlan {
  * @details Delegates to `spawnSync(...)`, preserves the supplied working directory, and returns the raw result so callers can interpret git exit status plus diagnostics deterministically. Runtime is dominated by external process execution. Side effects include subprocess creation.
  * @param[in] command {string[]} Executable plus argument vector.
  * @param[in] cwd {string} Working directory for the subprocess.
- * @return {ReturnType<typeof spawnSync>} Captured subprocess result.
+ * @return {SpawnSyncReturns<string>} Captured subprocess result with UTF-8 stdout and stderr.
  */
-function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync> {
+function runCapture(command: string[], cwd: string): SpawnSyncReturns<string> {
   return spawnSync(command[0]!, command.slice(1), {
     cwd,
     encoding: "utf8",

package/src/core/req-reset-command.ts

@@ -6,7 +6,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import {
   normalizeGitWorktreePrefix,
   type UseReqConfig,
@@ -63,9 +63,9 @@ type ReqResetCommandContext = Parameters<typeof restorePromptCommandExecution>[1
  * @details Delegates to `spawnSync(...)`, preserves the supplied working directory, and returns the raw result so callers can interpret git exit status plus diagnostics deterministically. Runtime is dominated by external process execution. Side effects include subprocess creation.
  * @param[in] command {string[]} Executable plus argument vector.
  * @param[in] cwd {string} Working directory for the subprocess.
- * @return {ReturnType<typeof spawnSync>} Captured subprocess result.
+ * @return {SpawnSyncReturns<string>} Captured subprocess result with UTF-8 stdout and stderr.
  */
-function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync> {
+function runCapture(command: string[], cwd: string): SpawnSyncReturns<string> {
   return spawnSync(command[0]!, command.slice(1), {
     cwd,
     encoding: "utf8",

package/src/core/runtime-project-paths.ts

@@ -5,7 +5,7 @@
  */
 
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import { ReqError } from "./errors.js";
 import { isSameOrAncestorPath } from "./path-context.js";
 
@@ -14,9 +14,9 @@ import { isSameOrAncestorPath } from "./path-context.js";
  * @details Delegates to `spawnSync`, keeps execution synchronous for deterministic command flows, and supports an optional working directory. Runtime is dominated by the spawned git process. Side effects include subprocess creation.
  * @param[in] command {string[]} Git executable plus argument vector.
  * @param[in] cwd {string | undefined} Optional working directory.
- * @return {ReturnType<typeof spawnSync>} Captured subprocess result.
+ * @return {SpawnSyncReturns<string>} Captured subprocess result with UTF-8 stdout and stderr.
  */
-function runGitCapture(command: string[], cwd?: string): ReturnType<typeof spawnSync> {
+function runGitCapture(command: string[], cwd?: string): SpawnSyncReturns<string> {
   return spawnSync(command[0]!, command.slice(1), {
     cwd,
     encoding: "utf8",

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,68 @@ 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. Awaits the non-critical summary delivery and suppresses its failures before dispatching the authoritative hidden prompt turn so a rejecting summary never surfaces as an unhandled rejection that could terminate the process before prompt-end closure runs the worktree merge. Returns the underlying hidden-delivery promise without awaiting the full agent turn so callers can record the `running` workflow transition as soon as prompt handoff is accepted; the returned promise resolves after the hidden prompt message is accepted, which on runtimes whose async replacement-session helpers resolve only after `agent_end` lets prompt-end closure finalize the worktree merge during the awaited delivery. 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") {
+    // The on-screen summary is non-critical; await it and suppress its delivery failures so a
+    // rejecting summary never surfaces as an unhandled rejection that could terminate the
+    // process before the authoritative hidden prompt turn drives prompt-end closure.
+    const summaryDelivery = Promise.resolve(
+      replacementContext.sendMessage(summaryMessage),
+    ).catch(() => {
+      // Intentionally suppressed: the hidden prompt message below is the authoritative turn trigger.
+    });
+    return summaryDelivery.then(() =>
+      replacementContext!.sendMessage!(hiddenPromptMessage, { triggerTurn: true }),
+    ).catch((error) => {
+      if (isStaleExtensionContextError(error)) {
+        return;
+      }
+      throw error;
+    });
+  }
+  if (typeof pi.sendMessage === "function") {
+    // `pi.sendMessage` is a fire-and-forget dispatcher in the pi runtime; chain both deliveries
+    // through one suppressed summary promise so a rejecting summary cannot terminate the process
+    // before the hidden prompt turn drives prompt-end closure.
+    const fallbackSummary = Promise.resolve(
+      pi.sendMessage(summaryMessage),
+    ).catch(() => {
+      // Intentionally suppressed: the hidden prompt message below is the authoritative turn trigger.
+    });
+    return fallbackSummary.then(() => {
+      pi.sendMessage(hiddenPromptMessage, { triggerTurn: true });
+    });
+  }
   if (typeof replacementContext?.sendUserMessage === "function") {
     return Promise.resolve(replacementContext.sendUserMessage(content)).catch((error) => {
       if (isStaleExtensionContextError(error)) {
@@ -1036,7 +1087,7 @@ function logPromptWorkflowEvent(
  * @param[in] projectBase {string} Absolute original project base path.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @param[in] promptName {import("./core/prompt-command-catalog.js").PromptCommandName} Bundled prompt name.
- * @param[in] nextState {DebugWorkflowState} Next workflow state.
+ * @param[in] nextState {import("./core/extension-status.js").PiUsereqWorkflowState} Next workflow state.
  * @return {void} No return value.
  */
 function transitionPromptWorkflowState(
@@ -1045,7 +1096,7 @@ function transitionPromptWorkflowState(
   projectBase: string,
   config: UseReqConfig,
   promptName: import("./core/prompt-command-catalog.js").PromptCommandName,
-  nextState: DebugWorkflowState,
+  nextState: import("./core/extension-status.js").PiUsereqWorkflowState,
 ): void {
   const previousState = statusController.state.workflowState;
   setPiUsereqWorkflowState(statusController, nextState, ctx);
@@ -3073,7 +3124,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,