pi-usereq 0.86.0 → 0.88.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.86.0)
+# PI-useReq/pi-usereq (0.88.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
@@ -60,7 +60,7 @@ in sync with the repository. All capabilities are exposed as slash commands and
 - **11 built-in agent tools** - token counting, summarization, compression, construct search, and static-check tools for explicit files or for the configured project surface.
 - **Interactive configuration menu** - `/pi-usereq` manages local (`<base-path>/.pi-usereq.json`) and global (`~/.config/pi-usereq/config.json`) configuration with no manual JSON editing required.
 - **Worktree-isolated runs** - prompt-command executions run in an isolated git worktree (created with `<prefix><project>-<branch>-<YYYYMMDDHHMMSS>` names) and are merged back with a stash-assisted fast-forward on success.
-- **Automatic commit guidance** - `AUTO_GIT_COMMIT=enable` (default) injects structured commit instructions (`<TYPE>(<COMPONENT>): <DESCRIPTION> [useReq]`) into every prompt; disabling it forces read-only git behavior and turns worktree orchestration off.
+- **Automatic commit guidance** - `AUTO_GIT_COMMIT=enable` (default) injects structured commit instructions (`<TYPE>(<COMPONENT>)<BREAKING>: <DESCRIPTION> [useReq]`) into every prompt; disabling it forces read-only git behavior and turns worktree orchestration off.
 - **Notifications** - desktop notify command, sound effects (levels `none`/`low`/`mid`/`high`, default `alt+s` toggle) and Pushover push messages on prompt completion, interruption, or failure.
 - **Runtime status bar** - the extension renders its workflow state, current branch, context usage, elapsed time, and sound level in the pi status line.
 - **Context-occupancy guardrails** - the `Context Files` settings row and every command invocation summary show the measured `[<percent>% context]` occupancy of the enabled context files against the selected model's max input context (or the documented 1,000,000-token fallback); prompt dispatch is aborted before worktree creation when the enabled context files exceed that limit.
@@ -72,7 +72,9 @@ in sync with the repository. All capabilities are exposed as slash commands and
 Each `req-*` command is invoked as `/req-<name> <User Request>` inside pi. Prompt commands first run git validation and the
 prompt-specific required-document checks, then (when `Auto git commit` and `Git worktree` are enabled) switch the session into an
 isolated worktree, render the bundled prompt with the project context, and on success merge the changes back and leave the
-repository clean. `/req-references` and `/req-reset` are non-agentic: they execute directly without starting an LLM session or
+repository clean. Every command prints an on-screen invocation summary (command name, passed arguments, and active
+configuration); the full rendered prompt content is delivered only to the LLM agent and is never displayed on screen.
+`/req-references` and `/req-reset` are non-agentic: they execute directly without starting an LLM session or
 creating a worktree.
 
 > **Clean context between commands** — every `/req-*` orchestration keeps the session context content in place when it
@@ -320,19 +322,19 @@ The extension renders a status field in the pi status line showing: extension id
 - Config-gated slash commands that run the project tools and write the output into the editor: `debug-compress`, `debug-references`, `debug-static-check`, `debug-summarize`, `debug-tokens`.
 - Standalone debug harness: `scripts/pi-usereq-debug.sh` (bash wrapper) and `scripts/debug-extension.ts` with subcommands `inspect`, `session-start`, `command`, `tool`, and `sdk-smoke`.
 - Debug logging writes to the configured `DEBUG_LOG_FILE`, filtered by prompt/tool name and workflow status.
-- **Prompt content logging** — when both `Debug` and `Enable debug prompts` are enabled (the `Debug > Enable debug prompts` menu entry), the exact rendered prompt delivered to the LLM agent through `sendMessage`/`sendUserMessage` is saved under `Log path for prompts` (`DEBUG_PROMPTS_LOG_PATH`, default `/tmp/PI-useReq`). Each run writes one file named `<timestamp>-<command>` (a `YYYYMMDDHHMMSSmmm` timestamp plus the `/req-*` command used, e.g. `20261009072235123-req-implement`) whose content is byte-identical to what reached the model. Prompt logging is subordinate to the global `Debug` flag and to the `Log on status` workflow filter; nothing is written while `Debug` is disabled. Relative log paths resolve against the project root, and trailing slashes are stripped from the configured path.
+- **Prompt content logging** — when both `Debug` and `Enable debug prompts` are enabled (the `Debug > Enable debug prompts` menu entry), the exact rendered prompt delivered to the LLM agent through `sendMessage`/`sendUserMessage` is saved under `Log path for prompts` (`DEBUG_PROMPTS_LOG_PATH`, default `/tmp/PI-useReq`). Each run writes two files named `<timestamp>-<command>-request.md` and `<timestamp>-<command>-prompt.md` (a `YYYYMMDDHHMMSSmmm` write-time timestamp plus the `/req-*` command used, e.g. `20261009072235123-req-implement-request.md` and `20261009072235123-req-implement-prompt.md`). The `-prompt.md` file is byte-identical to the rendered prompt delivered to the model; the `-request.md` file contains the exact on-screen command invocation summary. Prompt logging depends only on the global `Debug` flag plus `Enable debug prompts` (it is exempt from the `Log on status` workflow filter); nothing is written while `Debug` is disabled. Relative log paths resolve against the project root, and trailing slashes are stripped from the configured path.
 
   Because the saved file contains exactly what pi-usereq sent, you can replicate the same send from the `pi` CLI, outside pi-usereq and without the extension installed:
 
   ```bash
   # Replay the exact saved prompt as a one-shot task argument
-  pi -p "$(cat /tmp/PI-useReq/20261009072235123-req-implement)"
+  pi -p "$(cat /tmp/PI-useReq/20261009072235123-req-implement-prompt.md)"
 
   # Feed extra material on stdin while replaying an analysis request
   cat errors.log | pi -p "Analyze these errors and suggest how to fix them"
 
   # Reuse a saved prompt as coding-style guidance through an appended system prompt
-  pi -p "Rewrite this function" --append-system-prompt /tmp/PI-useReq/20261009072235123-req-implement
+  pi -p "Rewrite this function" --append-system-prompt /tmp/PI-useReq/20261009072235123-req-implement-prompt.md
   ```
 
 - **Provider error logging** — when a dispatched `req-*` run receives a provider response with status >= 400, pi-usereq writes the exact failing request payload into `<timestamp>-<command>-error-<status>.json` (raw provider-request JSON), the provider error message text into `<timestamp>-<command>-error-<status>-response.txt`, a byte-for-byte snapshot of the retained execution session into `<timestamp>-<command>-error-<status>-session.jsonl`, and replay metadata into `<timestamp>-<command>-error-<status>-replay.json`, all beside the run's `-request.md` and `-prompt.md` files. The `-replay.json` sidecar carries the provider, base URL, model id, thinking level, context window, max output tokens, the retained execution-session file, and ready-to-use replay commands; `replayCommands.piFork` targets the log-local `-session.jsonl` snapshot, which freezes the transcript exactly at the failing provider request (before any context edit or compaction). You can re-generate the failure for immediate pi CLI debugging:
@@ -373,7 +375,7 @@ This section describes the Git behavior of the `req-*` commands. The commands ow
   - On success the extension restores the original `base-path` session, applies a stash-assisted fast-forward merge of the worktree branch, and deletes the worktree and branch.
   - On failure or interruption the worktree and branch are **kept** and the workflow is parked in the `error` state so the produced artifacts can be inspected or recovered: run `/req-reset` to restore the original base path and force-remove the generated worktrees and branches.
   - With `Auto git commit = enable` (default), every prompt receives structured commit instructions and commits follow the message template `<TYPE>(<COMPONENT>)<BREAKING>: <DESCRIPTION> [useReq]`. With `Auto git commit = disable`, prompts receive a read-only git restriction and worktree orchestration is forced off.
-  - The extension never rewrites history and never runs destructive cleanup on your behalf.
+  - The extension never rewrites git history; destructive cleanup is limited to the generated worktrees and branches, which only `/req-reset` force-removes (see above).
 
 - Recommended practice:
   - Review the changes produced by each command before pushing them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-usereq",
-  "version": "0.86.0",
+  "version": "0.88.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ogekuri/PI-useReq.git"

package/src/core/pi-notify.ts

@@ -80,10 +80,24 @@ export const DEFAULT_PI_NOTIFY_PUSHOVER_TITLE = "%%PROMT%% @ %%BASE%% [%%TIME%%]
 
 /**
  * @brief Defines the default Pushover text template.
- * @details Prefixes outbound Pushover messages with the terminal outcome token and preserves the raw prompt arguments on the following line so notifications remain traceable to the invoked prompt command. Access complexity is O(1).
- * @satisfies REQ-185
+ * @details Delivers the final LLM agent output as the outbound Pushover message body so completed prompt runs push the last assistant message instead of the invoked command arguments; `buildPiNotifyPushoverBody` falls back to the terminal outcome token when the substituted body resolves empty. Access complexity is O(1).
+ * @satisfies REQ-185, REQ-450
+ */
+export const DEFAULT_PI_NOTIFY_PUSHOVER_TEXT = "%%OUTPUT%%";
+
+/**
+ * @brief Defines the Pushover Message API `message` field limit in characters.
+ * @details Caps substituted Pushover bodies per REQ-445 so over-limit payloads are head-truncated instead of rejected by the provider. Access complexity is O(1).
+ * @satisfies REQ-445
+ */
+export const PI_NOTIFY_PUSHOVER_MESSAGE_LIMIT = 1024;
+
+/**
+ * @brief Defines the deterministic head-truncation marker for over-limit Pushover bodies.
+ * @details Appended after the retained head characters whenever the substituted Pushover body exceeds `PI_NOTIFY_PUSHOVER_MESSAGE_LIMIT`. Access complexity is O(1).
+ * @satisfies REQ-445
  */
-export const DEFAULT_PI_NOTIFY_PUSHOVER_TEXT = "%%RESULT%%\n%%ARGS%%";
+const PI_NOTIFY_PUSHOVER_TRUNCATION_MARKER = "...[truncated]";
 
 /**
  * @brief Enumerates supported Pushover priorities.
@@ -99,13 +113,15 @@ export type PiNotifyPushoverPriority = (typeof PI_NOTIFY_PUSHOVER_PRIORITIES)[nu
 
 /**
  * @brief Describes one prompt-end request used for command-notify and Pushover substitution.
- * @details Stores the prompt command name, raw prompt arguments, runtime base path, and final prompt duration required to resolve runtime placeholders. The interface is compile-time only and introduces no runtime cost.
+ * @details Stores the prompt command name, raw prompt arguments, runtime base path, final prompt duration, and optional final agent output required to resolve runtime placeholders. `agentOutput` stays optional so non-agentic command callers and offline replays omit it and `%%OUTPUT%%` degrades to the empty string per REQ-444. The interface is compile-time only and introduces no runtime cost.
  */
 export interface PiNotifyEventRequest {
   promptName: string;
   promptArgs: string;
   basePath: string;
   completionTimeMs: number;
+  /** Final LLM agent output printed in the pi CLI; empty when absent per REQ-443, REQ-444. */
+  agentOutput?: string;
 }
 
 /**
@@ -490,10 +506,11 @@ function formatPiNotifyResult(outcome: PiNotifyOutcome): string {
 
 /**
  * @brief Builds the raw runtime placeholder map for one prompt-end request.
- * @details Resolves every placeholder value exactly once so notify-command and Pushover template substitution reuse the same prompt name, base path, elapsed time, argument string, and terminal outcome token. Runtime is O(p) in path length. No external state is mutated.
+ * @details Resolves every placeholder value exactly once so notify-command and Pushover template substitution reuse the same prompt name, base path, elapsed time, argument string, final agent output, and terminal outcome token. Runtime is O(p) in path length. No external state is mutated.
  * @param[in] request {PiNotifyEventRequest} Prompt-end request metadata.
  * @param[in] outcome {PiNotifyOutcome} Classified prompt-end outcome.
- * @return {{ "%%PROMT%%": string; "%%BASE%%": string; "%%TIME%%": string; "%%ARGS%%": string; "%%RESULT%%": string }} Raw placeholder-value map.
+ * @return {{ "%%PROMT%%": string; "%%BASE%%": string; "%%TIME%%": string; "%%ARGS%%": string; "%%OUTPUT%%": string; "%%RESULT%%": string }} Raw placeholder-value map.
+ * @satisfies REQ-169, REQ-186, REQ-443, REQ-444
  */
 function buildPiNotifyRuntimeTemplateValues(
   request: PiNotifyEventRequest,
@@ -504,6 +521,7 @@ function buildPiNotifyRuntimeTemplateValues(
     "%%BASE%%": formatPiNotifyBasePath(request.basePath),
     "%%TIME%%": formatPiNotifyDuration(request.completionTimeMs),
     "%%ARGS%%": request.promptArgs,
+    "%%OUTPUT%%": request.agentOutput ?? "",
     "%%RESULT%%": formatPiNotifyResult(outcome),
   };
 }
@@ -555,13 +573,13 @@ export function substitutePiNotifyInstallPath(command: string, installationPath:
 
 /**
  * @brief Substitutes runtime placeholders inside one shell-command template.
- * @details Applies shell-quoted installation-path substitution plus shell-escaped prompt, base-path, elapsed-time, raw-argument, and outcome-result substitution expected by `PI_NOTIFY_CMD`. Runtime is O(n) in template length. No external state is mutated.
+ * @details Applies shell-quoted installation-path substitution plus shell-escaped prompt, base-path, elapsed-time, raw-argument, final-output, and outcome-result substitution expected by `PI_NOTIFY_CMD`. Runtime is O(n) in template length. No external state is mutated.
  * @param[in] template {string} Raw shell-command template.
  * @param[in] request {PiNotifyEventRequest} Prompt-end request metadata.
  * @param[in] outcome {PiNotifyOutcome} Classified prompt-end outcome.
  * @param[in] installationPath {string} Absolute extension installation path.
  * @return {string} Runtime-ready shell command.
- * @satisfies REQ-169, REQ-199
+ * @satisfies REQ-169, REQ-199, REQ-443, REQ-444
  */
 function substitutePiNotifyShellTemplate(
   template: string,
@@ -579,12 +597,12 @@ function substitutePiNotifyShellTemplate(
 
 /**
  * @brief Substitutes runtime placeholders inside one text template.
- * @details Applies raw prompt name, home-relative base path, elapsed time, raw prompt arguments, and terminal outcome text without shell escaping so Pushover payloads preserve literal text. Runtime is O(n) in template length. No external state is mutated.
+ * @details Applies raw prompt name, home-relative base path, elapsed time, raw prompt arguments, final agent output, and terminal outcome text without shell escaping so Pushover payloads preserve literal text. Runtime is O(n) in template length. No external state is mutated.
  * @param[in] template {string} Raw text template.
  * @param[in] request {PiNotifyEventRequest} Prompt-end request metadata.
  * @param[in] outcome {PiNotifyOutcome} Classified prompt-end outcome.
  * @return {string} Placeholder-resolved text string.
- * @satisfies REQ-186, REQ-187, REQ-199
+ * @satisfies REQ-186, REQ-187, REQ-199, REQ-443, REQ-444
  */
 function substitutePiNotifyTextTemplate(
   template: string,
@@ -766,21 +784,40 @@ function buildPiNotifyPushoverTitle(
   return substitutePiNotifyTextTemplate(config["notify-pushover-title"], request, outcome);
 }
 
+/**
+ * @brief Head-truncates one substituted Pushover body to the Pushover Message API limit.
+ * @details Returns the body unchanged when it fits `PI_NOTIFY_PUSHOVER_MESSAGE_LIMIT` and otherwise keeps the head characters that leave room for `PI_NOTIFY_PUSHOVER_TRUNCATION_MARKER` so over-limit bodies stay deterministic and provider-acceptable. Runtime is O(1). No external state is mutated.
+ * @param[in] body {string} Fully substituted Pushover body text.
+ * @return {string} Body within the Pushover `message` character limit.
+ * @satisfies REQ-445
+ */
+function truncatePiNotifyPushoverBody(body: string): string {
+  if (body.length <= PI_NOTIFY_PUSHOVER_MESSAGE_LIMIT) {
+    return body;
+  }
+  return body.slice(0, PI_NOTIFY_PUSHOVER_MESSAGE_LIMIT - PI_NOTIFY_PUSHOVER_TRUNCATION_MARKER.length)
+    + PI_NOTIFY_PUSHOVER_TRUNCATION_MARKER;
+}
+
 /**
  * @brief Builds the Pushover message body for one prompt-end request.
- * @details Resolves the configured `notify-pushover-text` template with raw runtime placeholder substitution so the pushed text remains configurable and deterministic. Runtime is O(n) in template length. No external state is mutated.
+ * @details Resolves the configured `notify-pushover-text` template with raw runtime placeholder substitution, falls back to the terminal outcome token when the fully substituted body resolves empty so Pushover delivery never targets an empty `message` field, then head-truncates over-limit bodies to the Pushover Message API `message` limit. Runtime is O(n) in template length. No external state is mutated.
  * @param[in] config {PiNotifyConfigFields} Effective notification configuration.
  * @param[in] outcome {PiNotifyOutcome} Classified prompt-end outcome.
  * @param[in] request {PiNotifyEventRequest} Prompt-end request metadata.
- * @return {string} Pushover message body.
- * @satisfies REQ-185, REQ-186, REQ-187, REQ-199
+ * @return {string} Pushover message body within the 1024-character API limit.
+ * @satisfies REQ-185, REQ-186, REQ-187, REQ-199, REQ-443, REQ-444, REQ-445, REQ-450
  */
 function buildPiNotifyPushoverBody(
   config: PiNotifyConfigFields,
   outcome: PiNotifyOutcome,
   request: PiNotifyEventRequest,
 ): string {
-  return substitutePiNotifyTextTemplate(config["notify-pushover-text"], request, outcome);
+  const substitutedBody = substitutePiNotifyTextTemplate(config["notify-pushover-text"], request, outcome);
+  const resolvedBody = substitutedBody.trim().length > 0
+    ? substitutedBody
+    : formatPiNotifyResult(outcome);
+  return truncatePiNotifyPushoverBody(resolvedBody);
 }
 
 /**
@@ -790,7 +827,7 @@ function buildPiNotifyPushoverBody(
  * @param[in] outcome {PiNotifyOutcome} Classified prompt-end outcome.
  * @param[in] request {PiNotifyEventRequest} Prompt-end request metadata.
  * @return {URLSearchParams} Encoded Pushover request payload.
- * @satisfies REQ-167, REQ-172, REQ-185, REQ-186, REQ-199
+ * @satisfies REQ-167, REQ-172, REQ-185, REQ-186, REQ-199, REQ-443, REQ-444, REQ-445
  */
 function buildPiNotifyPushoverPayload(
   config: PiNotifyConfigFields,
@@ -858,19 +895,35 @@ export function setPiNotifySpawnForTests(spawnImpl: PiNotifySpawn | undefined):
 
 /**
  * @brief Dispatches prompt-end notify, sound, and Pushover effects for one agent-end payload.
- * @details Classifies the terminal outcome, executes `PI_NOTIFY_CMD` when command-notify prerequisites are satisfied, executes the configured sound command when sound prerequisites are satisfied, and dispatches the native Pushover request when Pushover prerequisites are satisfied. Runtime is O(m + c + b) in message count, command length, and Pushover payload size. Side effects include child-process spawning and outbound HTTPS requests.
+ * @details Classifies the terminal outcome from the `agent_end` payload and delegates to `runPiNotifyEffectsForOutcome(...)`; `%%OUTPUT%%` resolves from the caller-supplied final agent output and Pushover bodies are head-truncated to the provider message limit. Runtime is O(m + c + b) in message count, command length, and Pushover payload size. Side effects include child-process spawning and outbound HTTPS requests.
  * @param[in] config {PiNotifyConfigFields} Effective notification configuration.
  * @param[in] event {Pick<AgentEndEvent, "messages">} Agent-end payload subset.
  * @param[in] request {PiNotifyEventRequest | undefined} Optional prompt-end request metadata used for command-notify and Pushover substitution.
  * @return {void} No return value.
- * @satisfies REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-199
+ * @satisfies REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-199, REQ-443, REQ-444, REQ-445
  */
 export function runPiNotifyEffects(
   config: PiNotifyConfigFields,
   event: Pick<AgentEndEvent, "messages">,
   request?: PiNotifyEventRequest,
 ): void {
-  const outcome = classifyPiNotifyOutcome(event);
+  runPiNotifyEffectsForOutcome(config, classifyPiNotifyOutcome(event), request);
+}
+
+/**
+ * @brief Dispatches prompt-end notify, sound, and Pushover effects for one explicit prompt-end outcome.
+ * @details Executes `PI_NOTIFY_CMD` when command-notify prerequisites are satisfied, executes the configured sound command when sound prerequisites are satisfied, and dispatches the native Pushover request when Pushover prerequisites are satisfied; `%%OUTPUT%%` resolves from the caller-supplied final agent output or command process output, and Pushover bodies head-truncate to the provider message limit with an outcome-token fallback for empty bodies. Agentic callers classify the outcome from the `agent_end` payload through `runPiNotifyEffects(...)`; non-agentic `req-references` and `req-reset` command callers pass the explicit completed or failed outcome per REQ-447. Runtime is O(c + b) in command length and Pushover payload size. Side effects include child-process spawning and outbound HTTPS requests.
+ * @param[in] config {PiNotifyConfigFields} Effective notification configuration.
+ * @param[in] outcome {PiNotifyOutcome} Explicit prompt-end outcome.
+ * @param[in] request {PiNotifyEventRequest | undefined} Optional prompt-end request metadata used for command-notify and Pushover substitution.
+ * @return {void} No return value.
+ * @satisfies REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-199, REQ-443, REQ-444, REQ-445, REQ-447, REQ-450
+ */
+export function runPiNotifyEffectsForOutcome(
+  config: PiNotifyConfigFields,
+  outcome: PiNotifyOutcome,
+  request?: PiNotifyEventRequest,
+): void {
   if (shouldRunPiNotifyCommand(config, outcome, request)) {
     runPiNotifyCommand(config, outcome, request as PiNotifyEventRequest);
   }

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

@@ -59,6 +59,29 @@ export interface ReqResetCommandExecutionResult {
   errorMessage?: string;
 }
 
+/**
+ * @brief Builds the per-operation outcome lines of one `req-reset` run for `%%OUTPUT%%` notification substitution.
+ * @details Emits one machine-readable line per recovery or cleanup fact — terminal outcome, execution-transcript preservation, `base-path` restoration, removed generated worktree count, removed generated branch count — and appends the surfaced error diagnostic for failed runs so prompt-end notification effects carry exactly the output produced during the process. Runtime is O(1). No external state is mutated.
+ * @param[in] executionResult {ReqResetCommandExecutionResult} Recovery and cleanup outcome facts of the attempted run.
+ * @return {string[]} Ordered outcome lines starting with the terminal outcome.
+ * @satisfies REQ-449
+ */
+export function buildReqResetCommandOutcomeLines(
+  executionResult: ReqResetCommandExecutionResult,
+): string[] {
+  const lines = [
+    `outcome: ${executionResult.errorMessage ? "error" : "success"}`,
+    `transcript preserved: ${executionResult.transcriptPreserved ? "yes" : "no"}`,
+    `base-path restored: ${executionResult.restoredBasePath ? "yes" : "no"}`,
+    `worktrees removed: ${executionResult.removedWorktreeDirs.length}`,
+    `branches removed: ${executionResult.removedBranchNames.length}`,
+  ];
+  if (executionResult.errorMessage) {
+    lines.push(`error: ${executionResult.errorMessage}`);
+  }
+  return lines;
+}
+
 /**
  * @brief Describes the session-bound context surface reused during `req-reset` recovery.
  * @details Reuses the session-switching contract already accepted by `restorePromptCommandExecution(...)` so the dedicated reset command can restore the original session without depending on concrete pi runtime classes. The alias is compile-time only and introduces no runtime cost.

package/src/index.ts

@@ -61,7 +61,9 @@ import {
   normalizePiNotifyTemplateValue,
   parsePiNotifyControlSequenceText,
   runPiNotifyEffects,
+  runPiNotifyEffectsForOutcome,
   type PiNotifyEventRequest,
+  type PiNotifyOutcome,
   type PiNotifyPushoverPriority,
   type PiNotifySoundLevel,
 } from "./core/pi-notify.js";
@@ -118,6 +120,7 @@ import {
 } from "./core/req-references-command.js";
 import {
   REQ_RESET_COMMAND_DESCRIPTION,
+  buildReqResetCommandOutcomeLines,
   executeReqResetCommandExecution,
   prepareReqResetCommandExecution,
   type ReqResetCommandExecutionResult,
@@ -178,6 +181,7 @@ import {
   appendCommandReportEntry,
   buildCommandReportErrorEntryData,
   buildReqReferencesCommandReportEntryData,
+  buildReqReferencesCommandReportLines,
   registerCommandReportEntryRenderer,
 } from "./core/command-report-entry.js";
 import { ReqError } from "./core/errors.js";
@@ -1239,6 +1243,32 @@ function notifyContextSafely(
   }
 }
 
+/**
+ * @brief Dispatches prompt-end notification effects for one non-agentic command outcome.
+ * @details Builds the effective notification configuration subset with the active runtime sound level and forwards the explicit completed or failed outcome plus the command-produced process output into `runPiNotifyEffectsForOutcome(...)`, so `req-references` and `req-reset` completions feed the same command-notify, sound, and Pushover gates as `agent_end` runs. Runtime is O(1) plus delegated effect cost. Side effects include optional child-process spawning and outbound HTTPS requests.
+ * @param[in] statusController {PiUsereqStatusController} Mutable status controller supplying the active runtime sound level.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] outcome {PiNotifyOutcome} Explicit terminal command outcome.
+ * @param[in] request {PiNotifyEventRequest} Prompt-end request metadata carrying the command process output.
+ * @return {void} No return value.
+ * @satisfies REQ-447, REQ-448, REQ-449
+ */
+function dispatchNonAgenticCommandNotifyEffects(
+  statusController: PiUsereqStatusController,
+  config: UseReqConfig,
+  outcome: PiNotifyOutcome,
+  request: PiNotifyEventRequest,
+): void {
+  runPiNotifyEffectsForOutcome(
+    {
+      ...config,
+      "notify-sound": getPiUsereqRuntimeSoundLevel(statusController),
+    },
+    outcome,
+    request,
+  );
+}
+
 /**
  * @brief Emits the final context-retention reminder info notification for a successfully completed `/req-*` orchestration.
  * @details Builds one message stating that the session context content was retained, recommending a clean-context session start before the next `/req-*` command, and appending the current context-usage percentage when the controller holds a normalized snapshot. Delivers exclusively through `notifyContextSafely(...)`, so stale replacement-session contexts are suppressed, and performs no session message send and no session switch. Runtime is O(1). Side effect is user notification delivery only when the supplied context is still active.
@@ -1498,16 +1528,50 @@ async function finalizeMatchedPromptSuccess(
   }
 }
 
+/**
+ * @brief Extracts the final agent output text for prompt-end `%%OUTPUT%%` substitution.
+ * @details Scans the `agent_end` payload messages backwards for the last assistant message and concatenates its `type === "text"` content blocks while skipping `thinking` and tool-call blocks, returning the empty string for non-agent payloads and for last assistant messages without text blocks so non-agentic command notifications never substitute stale output. Runtime is O(m + n) in message and text-block count. No external state is mutated.
+ * @param[in] event {unknown} Raw `agent_end` lifecycle event payload.
+ * @return {string} Concatenated final assistant text blocks, or the empty string when unavailable.
+ * @satisfies REQ-443, REQ-444
+ */
+function buildAgentEndOutputText(event: unknown): string {
+  const messages = (event as { messages?: unknown } | undefined)?.messages;
+  if (!Array.isArray(messages)) {
+    return "";
+  }
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index] as { role?: unknown; content?: unknown } | undefined;
+    if (typeof message !== "object" || message === null || message.role !== "assistant") {
+      continue;
+    }
+    const content = Array.isArray(message.content) ? message.content : [];
+    let output = "";
+    for (const block of content) {
+      if (
+        typeof block === "object"
+        && block !== null
+        && (block as { type?: unknown }).type === "text"
+        && typeof (block as { text?: unknown }).text === "string"
+      ) {
+        output += (block as { text: string }).text;
+      }
+    }
+    return output;
+  }
+  return "";
+}
+
 /**
  * @brief Handles one intercepted pi lifecycle hook for pi-usereq status updates.
- * @details Applies session-start-specific resource validation, project-config refresh, idle-time shared-tokenizer and context-file measurement pre-warm, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. After the status update, captures the exact `before_provider_request` provider payload for the live active or pending prompt run by reloading the prompt debug gating configuration from the prompt run's original `base-path` (worktree-backed checkouts do not contain the untracked `.pi-usereq.json`, so the cwd-derived cached config would silently disable capture), flushes the process-scoped captured payload as one `<timestamp>-<req-command>-error-<status>` file whenever `after_provider_response` reports a status >= 400 or whenever one finalized `message_end` assistant error message carries a leading HTTP status >= 400 (the provider-independent fallback for provider APIs whose SDK clients throw before emitting `after_provider_response` for non-2xx statuses) without requiring live workflow state, and discards the capture at prompt-run end so stale payloads never reach later runs. Before `agent_start`, re-verifies any prepared prompt execution session switch. On `agent_end`, dispatches configured command-notify, sound, and prompt-specific Pushover effects, logs dedicated workflow-closure diagnostics, classifies the prompt outcome, and for every matched successful worktree-backed completion defers the restore switch, stash-assisted merge, and worktree deletion to `agent_settled` when the running pi host supports that 0.80.4+ event (because its `switchSession` awaits the active agent run to become idle and would deadlock inside `agent_end`), or executes the finalization directly at `agent_end` when the host does not emit `agent_settled`. On `agent_settled`, reuses persisted replacement-session command contexts when event contexts omit `switchSession()`, executes the deferred stash-assisted merge-and-delete finalization path, emits a warning-only notification when restored `base-path` changes are reapplied after merge, tolerates stale replacement-session notification contexts after session replacement, retains the worktree plus notifies closure failure for interrupted or failed outcomes, logs selected prompt workflow transitions, and transitions workflow state through `merging`, `error`, and `idle` as required. On `session_shutdown`, captures pre-update prompt snapshots so workflow-shutdown diagnostics and same-runtime command continuation preserve the active prompt workflow state across switch-triggered rebinding, then disposes the shared controller. Runtime is dominated by configuration loading during `session_start` and git finalization during matched successful closure handling; all other hooks are O(1). Side effects include resource checks, active-tool mutation, active-session replacement, status updates, live-ticker disposal on shutdown, optional child-process spawning, outbound HTTPS requests, branch merges, worktree deletion, and optional debug-log writes.
+ * @details Applies session-start-specific resource validation, project-config refresh, idle-time shared-tokenizer and context-file measurement pre-warm, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. After the status update, captures the exact `before_provider_request` provider payload for the live active or pending prompt run by reloading the prompt debug gating configuration from the prompt run's original `base-path` (worktree-backed checkouts do not contain the untracked `.pi-usereq.json`, so the cwd-derived cached config would silently disable capture), flushes the process-scoped captured payload as one `<timestamp>-<req-command>-error-<status>` file whenever `after_provider_response` reports a status >= 400 or whenever one finalized `message_end` assistant error message carries a leading HTTP status >= 400 (the provider-independent fallback for provider APIs whose SDK clients throw before emitting `after_provider_response` for non-2xx statuses) without requiring live workflow state, and discards the capture at prompt-run end so stale payloads never reach later runs. Before `agent_start`, re-verifies any prepared prompt execution session switch. On `agent_end`, dispatches configured command-notify, sound, and prompt-specific Pushover effects with the final assistant output text feeding `%%OUTPUT%%` placeholder substitution, logs dedicated workflow-closure diagnostics, classifies the prompt outcome, and for every matched successful worktree-backed completion defers the restore switch, stash-assisted merge, and worktree deletion to `agent_settled` when the running pi host supports that 0.80.4+ event (because its `switchSession` awaits the active agent run to become idle and would deadlock inside `agent_end`), or executes the finalization directly at `agent_end` when the host does not emit `agent_settled`. On `agent_settled`, reuses persisted replacement-session command contexts when event contexts omit `switchSession()`, executes the deferred stash-assisted merge-and-delete finalization path, emits a warning-only notification when restored `base-path` changes are reapplied after merge, tolerates stale replacement-session notification contexts after session replacement, retains the worktree plus notifies closure failure for interrupted or failed outcomes, logs selected prompt workflow transitions, and transitions workflow state through `merging`, `error`, and `idle` as required. On `session_shutdown`, captures pre-update prompt snapshots so workflow-shutdown diagnostics and same-runtime command continuation preserve the active prompt workflow state across switch-triggered rebinding, then disposes the shared controller. Runtime is dominated by configuration loading during `session_start` and git finalization during matched successful closure handling; all other hooks are O(1). Side effects include resource checks, active-tool mutation, active-session replacement, status updates, live-ticker disposal on shutdown, optional child-process spawning, outbound HTTPS requests, branch merges, worktree deletion, and optional debug-log writes.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
  * @param[in] event {unknown} Hook payload forwarded by pi.
  * @param[in] ctx {ExtensionContext} Active extension context.
  * @return {Promise<void>} Promise resolved when hook processing completes.
- * @satisfies REQ-117, REQ-118, REQ-119, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-208, REQ-209, REQ-221, REQ-228, REQ-229, REQ-230, REQ-244, REQ-245, REQ-246, REQ-247, REQ-276, REQ-277, REQ-278, REQ-279, REQ-280, REQ-291, REQ-292, REQ-421, REQ-422, REQ-425, REQ-440
+ * @satisfies REQ-117, REQ-118, REQ-119, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-208, REQ-209, REQ-221, REQ-228, REQ-229, REQ-230, REQ-244, REQ-245, REQ-246, REQ-247, REQ-276, REQ-277, REQ-278, REQ-279, REQ-280, REQ-291, REQ-292, REQ-421, REQ-422, REQ-425, REQ-440, REQ-443, REQ-444
  */
 async function handleExtensionStatusEvent(
   pi: ExtensionAPI,
@@ -1569,6 +1633,7 @@ async function handleExtensionStatusEvent(
         promptArgs: activePromptRequest.promptArgs,
         basePath: activePromptRequest.basePath,
         completionTimeMs: Math.max(0, Date.now() - statusController.state.runStartTimeMs),
+        agentOutput: buildAgentEndOutputText(event),
       }
     : undefined;
   updateExtensionStatus(statusController, hookName, event, ctx);
@@ -2710,7 +2775,7 @@ async function configurePiNotifyEventMenu(
  * @details Serializes the global enable flag, shared-event submenu launcher, priority, title, text, and credential rows into right-valued menu items appended after the sound-command rows, dims and disables the enable row until both credentials are populated, renders the locked value as `configure user/token keys first`, and escapes control characters for the single-line `Pushover text` value. Runtime is O(n) in the rendered text-template length. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered direct Pushover rows.
- * @satisfies REQ-163, REQ-165, REQ-172, REQ-184, REQ-185, REQ-198, REQ-234, REQ-235
+ * @satisfies REQ-163, REQ-165, REQ-172, REQ-184, REQ-185, REQ-198, REQ-234, REQ-235, REQ-443, REQ-444, REQ-446
  */
 function buildPiNotifyPushoverRows(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   const pushoverCredentialsReady = hasPiNotifyPushoverCredentials(config);
@@ -2747,7 +2812,7 @@ function buildPiNotifyPushoverRows(config: UseReqConfig): PiUsereqSettingsMenuCh
       id: "notify-pushover-text",
       label: "Pushover text",
       value: formatPiNotifyControlSequenceText(config["notify-pushover-text"]),
-      description: "Edit the text template used for outbound Pushover messages.",
+      description: "Edit the text template used for outbound Pushover messages. Tokens: %%PROMT%% %%BASE%% %%TIME%% %%ARGS%% %%OUTPUT%% %%RESULT%%.",
     },
     {
       id: "notify-pushover-user-key",
@@ -3424,11 +3489,11 @@ function resolveReqResetPromptRequest(
 
 /**
  * @brief Registers the specialized `req-reset` slash command.
- * @details Registers the non-agentic prompt-recovery command that accepts any current workflow state, reuses persisted prompt runtime state when available, restores the original session-backed `base-path`, force-removes matching generated worktrees plus branches, clears recoverable prompt state when restoration succeeds, and notifies pi without starting an LLM session or creating a worktree. Runtime is dominated by session restoration plus git cleanup. Side effects include command registration, status-controller mutation, active-session replacement, worktree deletion, branch deletion, and user notifications.
+ * @details Registers the non-agentic prompt-recovery command that accepts any current workflow state, reuses persisted prompt runtime state when available, restores the original session-backed `base-path`, force-removes matching generated worktrees plus branches, clears recoverable prompt state when restoration succeeds, notifies pi without starting an LLM session or creating a worktree, and dispatches prompt-end notification effects carrying the command process output as `%%OUTPUT%%`. Runtime is dominated by session restoration plus git cleanup. Side effects include command registration, status-controller mutation, active-session replacement, worktree deletion, branch deletion, user notifications, and optional prompt-end notify, sound, and Pushover dispatch.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {void} No return value.
- * @satisfies REQ-304, REQ-305, REQ-306, REQ-307, REQ-308, REQ-309, REQ-310, REQ-311, REQ-312, REQ-313, REQ-441
+ * @satisfies REQ-304, REQ-305, REQ-306, REQ-307, REQ-308, REQ-309, REQ-310, REQ-311, REQ-312, REQ-313, REQ-441, REQ-447, REQ-449
  */
 function registerReqResetCommand(
   pi: ExtensionAPI,
@@ -3436,7 +3501,8 @@ function registerReqResetCommand(
 ): void {
   pi.registerCommand("req-reset", {
     description: REQ_RESET_COMMAND_DESCRIPTION,
-    handler: async (_args, ctx) => {
+    handler: async (args, ctx) => {
+      const commandStartMs = Date.now();
       const promptRequest = resolveReqResetPromptRequest(statusController);
       const resetModelSelection = promptRequest?.originalModel
         ?? resolveCurrentModelSelection((ctx as unknown as PromptModelSelectionContextSurface).model);
@@ -3470,6 +3536,13 @@ function registerReqResetCommand(
         const message = error instanceof Error ? error.message : String(error);
         setPiUsereqWorkflowState(statusController, "error", resetContext);
         notifyContextSafely(resetContext, message, "error");
+        dispatchNonAgenticCommandNotifyEffects(statusController, config, "failed", {
+          promptName: "req-reset",
+          promptArgs: args,
+          basePath: projectBase,
+          completionTimeMs: Math.max(0, Date.now() - commandStartMs),
+          agentOutput: message,
+        });
         throw error;
       }
 
@@ -3484,6 +3557,13 @@ function registerReqResetCommand(
       if (executionResult.errorMessage) {
         setPiUsereqWorkflowState(statusController, "error", resetContext);
         notifyContextSafely(resetContext, executionResult.errorMessage, "error");
+        dispatchNonAgenticCommandNotifyEffects(statusController, config, "failed", {
+          promptName: "req-reset",
+          promptArgs: args,
+          basePath: projectBase,
+          completionTimeMs: Math.max(0, Date.now() - commandStartMs),
+          agentOutput: buildReqResetCommandOutcomeLines(executionResult).join("\n"),
+        });
         throw new ReqError(executionResult.errorMessage, 1);
       }
 
@@ -3492,6 +3572,13 @@ function registerReqResetCommand(
         ? `SUCCESS: req-reset restored base-path and removed ${executionResult.removedWorktreeDirs.length} worktree(s) plus ${executionResult.removedBranchNames.length} branch(es).`
         : `SUCCESS: req-reset removed ${executionResult.removedWorktreeDirs.length} worktree(s) plus ${executionResult.removedBranchNames.length} branch(es) and restored idle state.`;
       notifyContextSafely(resetContext, successMessage, "info");
+      dispatchNonAgenticCommandNotifyEffects(statusController, config, "completed", {
+        promptName: "req-reset",
+        promptArgs: args,
+        basePath: projectBase,
+        completionTimeMs: Math.max(0, Date.now() - commandStartMs),
+        agentOutput: buildReqResetCommandOutcomeLines(executionResult).join("\n"),
+      });
       notifyContextRetentionReminder(statusController, resetContext);
     },
   });
@@ -3499,11 +3586,11 @@ function registerReqResetCommand(
 
 /**
  * @brief Registers the specialized `req-references` slash command.
- * @details Registers the non-agentic references-maintenance command that rejects non-`idle` invocations by transitioning workflow state to `error` before direct execution, otherwise reuses slash-command-owned git validation, transitions workflow state through `checking|running|idle`, regenerates `REFERENCES.md` directly from configured source directories, stages only the generated file, creates the fixed-message git commit, verifies repository cleanliness, appends one durable `pi-usereq.command-report` session entry recording the executed operations with their outcomes so the report renders in the transcript and survives session restore, and emits execution notifications that conform to the operations actually performed — one stating whether the references file was updated or already matched the generated content and one stating whether the fixed-message commit was created or skipped — regardless of the update and commit outcomes, without starting an LLM session or creating a worktree. Runtime is dominated by git subprocess execution plus source-summary generation. Side effects include command registration, status-controller mutation, filesystem writes, git index/history mutation, session-entry persistence, and user notifications.
+ * @details Registers the non-agentic references-maintenance command that rejects non-`idle` invocations by transitioning workflow state to `error` before direct execution, otherwise reuses slash-command-owned git validation, transitions workflow state through `checking|running|idle`, regenerates `REFERENCES.md` directly from configured source directories, stages only the generated file, creates the fixed-message git commit, verifies repository cleanliness, appends one durable `pi-usereq.command-report` session entry recording the executed operations with their outcomes so the report renders in the transcript and survives session restore, emits execution notifications that conform to the operations actually performed — one stating whether the references file was updated or already matched the generated content and one stating whether the fixed-message commit was created or skipped — regardless of the update and commit outcomes, dispatches prompt-end notification effects carrying the per-operation process output as `%%OUTPUT%%`, all without starting an LLM session or creating a worktree. Runtime is dominated by git subprocess execution plus source-summary generation. Side effects include command registration, status-controller mutation, filesystem writes, git index/history mutation, session-entry persistence, user notifications, and optional prompt-end notify, sound, and Pushover dispatch.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {void} No return value.
- * @satisfies REQ-200, REQ-221, REQ-224, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-436, REQ-437, REQ-438, REQ-441
+ * @satisfies REQ-200, REQ-221, REQ-224, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-436, REQ-437, REQ-438, REQ-441, REQ-447, REQ-448
  */
 function registerReqReferencesCommand(
   pi: ExtensionAPI,
@@ -3511,7 +3598,8 @@ function registerReqReferencesCommand(
 ): void {
   pi.registerCommand("req-references", {
     description: REQ_REFERENCES_COMMAND_DESCRIPTION,
-    handler: async (_args, ctx) => {
+    handler: async (args, ctx) => {
+      const commandStartMs = Date.now();
       if (statusController.state.workflowState !== "idle") {
         rejectNonIdleReqCommand(statusController, ctx);
       }
@@ -3554,6 +3642,13 @@ function registerReqReferencesCommand(
             : `SUCCESS: req-references completed with a clean repository (${executionResult.referencesChanged ? "references updated" : "references unchanged"}; ${executionResult.commitCreated ? "commit created" : "commit skipped"}).`,
           "info",
         );
+        dispatchNonAgenticCommandNotifyEffects(statusController, config, "completed", {
+          promptName: "req-references",
+          promptArgs: args,
+          basePath: projectBase,
+          completionTimeMs: Math.max(0, Date.now() - commandStartMs),
+          agentOutput: buildReqReferencesCommandReportLines(executionResult).join("\n"),
+        });
         notifyContextRetentionReminder(statusController, ctx);
       } catch (error) {
         statusController.state.pendingPromptRequest = undefined;
@@ -3562,6 +3657,13 @@ function registerReqReferencesCommand(
         const message = error instanceof Error ? error.message : String(error);
         appendCommandReportEntry(pi, buildCommandReportErrorEntryData("req-references", message));
         notifyContextSafely(ctx, message, "error");
+        dispatchNonAgenticCommandNotifyEffects(statusController, config, "failed", {
+          promptName: "req-references",
+          promptArgs: args,
+          basePath: projectBase,
+          completionTimeMs: Math.max(0, Date.now() - commandStartMs),
+          agentOutput: message,
+        });
         throw error;
       }
     },