pi-usereq 0.85.0 → 0.87.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.85.0)
+# PI-useReq/pi-usereq (0.87.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.85.0",
+  "version": "0.87.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ogekuri/PI-useReq.git"

package/src/core/command-report-entry.ts

@@ -0,0 +1,182 @@
+/**
+ * @file
+ * @brief Persists durable non-agentic command execution reports as custom session entries.
+ * @details Defines the stable custom-entry type, machine-readable report payload, builders for `req-references` outcome lines, and the pi guarded helpers that append the report entry and register its transcript renderer. Custom entries are stored in the session file, excluded from LLM context, rendered live through `entry_appended`, and re-rendered after any session restore, so transient UI-notification collapsing or chat rebuilds never lose the executed-commands outcome report. Runtime is O(n) in report-line count. Side effects are limited to session-entry persistence and renderer registration through the pi extension API.
+ */
+
+import type {
+  CustomEntry,
+  EntryRenderOptions,
+  EntryRenderer,
+  ExtensionAPI,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import type { Component } from "@earendil-works/pi-tui";
+import { formatRuntimePathForDisplay } from "./path-context.js";
+import type { ReqReferencesCommandExecutionResult } from "./req-references-command.js";
+
+/**
+ * @brief Declares the stable custom-entry type used for durable command execution reports.
+ * @details Identifies `pi-usereq` report entries inside the persisted session file so interactive mode renders them through the registered entry renderer after reload, resume, fork, and session switches. Lookup complexity is O(1).
+ */
+export const COMMAND_REPORT_ENTRY_TYPE = "pi-usereq.command-report";
+
+/**
+ * @brief Describes one durable command execution report entry payload.
+ * @details Stores the originating slash-command name, the report severity, the terminal outcome, and the ordered per-operation outcome lines rendered in the transcript. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface CommandReportEntryData {
+  command: string;
+  level: "info" | "error";
+  outcome: "success" | "error";
+  lines: string[];
+}
+
+/**
+ * @brief Describes the loosely-typed pi runtime surface required for durable report entries.
+ * @details Narrows the extension API to the optional `registerEntryRenderer(...)` and `appendEntry(...)` methods consumed by the guarded report helpers so legacy hosts and offline harnesses without custom-entry support degrade silently instead of throwing. The interface is compile-time only and introduces no runtime cost.
+ */
+interface CommandReportEntryRegistrar {
+  registerEntryRenderer?: (
+    customType: string,
+    renderer: EntryRenderer<CommandReportEntryData>,
+  ) => void;
+  appendEntry?: (customType: string, data?: CommandReportEntryData) => void;
+}
+
+/**
+ * @brief Validates one loosely-typed payload as a command report entry payload.
+ * @details Accepts only payloads with a non-empty command string, the documented `info|error` level, the documented `success|error` outcome, and a string-only lines array so malformed session data never reaches the transcript renderer. Runtime is O(n) in line count. No external state is mutated.
+ * @param[in] value {unknown} Candidate persisted payload.
+ * @return {boolean} `true` when the payload satisfies the report entry contract.
+ */
+function isCommandReportEntryData(value: unknown): value is CommandReportEntryData {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value as Partial<CommandReportEntryData>;
+  return typeof candidate.command === "string"
+    && candidate.command.trim() !== ""
+    && (candidate.level === "info" || candidate.level === "error")
+    && (candidate.outcome === "success" || candidate.outcome === "error")
+    && Array.isArray(candidate.lines)
+    && candidate.lines.every((line) => typeof line === "string");
+}
+
+/**
+ * @brief Builds the ordered per-operation outcome lines for one completed `req-references` run.
+ * @details Emits one machine-readable line per executed operation — terminal outcome, references-file regeneration result, guarded git-commit result, and post-run repository cleanliness — so the durable report states exactly which commands ran and with which outcome. Runtime is O(n) in path length. No external state is mutated.
+ * @param[in] executionResult {ReqReferencesCommandExecutionResult} Per-operation outcome facts of the completed run.
+ * @return {string[]} Ordered report lines starting with the terminal outcome.
+ * @satisfies REQ-436, REQ-437, REQ-438
+ */
+export function buildReqReferencesCommandReportLines(
+  executionResult: ReqReferencesCommandExecutionResult,
+): string[] {
+  const referencesDisplayPath = formatRuntimePathForDisplay(executionResult.referencesPath);
+  return [
+    `outcome: success`,
+    `references file ${referencesDisplayPath}: ${
+      executionResult.referencesChanged ? "updated" : "already matched the generated content"
+    }`,
+    `git commit: ${
+      executionResult.commitCreated
+        ? `created "${executionResult.commitMessage}"`
+        : "skipped (references content matched HEAD)"
+    }`,
+    "repository: clean after run",
+  ];
+}
+
+/**
+ * @brief Builds the durable report entry payload for one completed `req-references` run.
+ * @details Pairs the invokable command name with the per-operation outcome lines and the `success` outcome. Runtime is O(n) in report-line count. No external state is mutated.
+ * @param[in] executionResult {ReqReferencesCommandExecutionResult} Per-operation outcome facts of the completed run.
+ * @return {CommandReportEntryData} Report entry payload for session persistence.
+ * @satisfies REQ-436, REQ-437, REQ-438
+ */
+export function buildReqReferencesCommandReportEntryData(
+  executionResult: ReqReferencesCommandExecutionResult,
+): CommandReportEntryData {
+  return {
+    command: "req-references",
+    level: "info",
+    outcome: "success",
+    lines: buildReqReferencesCommandReportLines(executionResult),
+  };
+}
+
+/**
+ * @brief Builds the durable report entry payload for one failed non-agentic command run.
+ * @details Records the invokable command name, the `error` outcome, and the surfaced failure diagnostic so failed runs keep their outcome evidence in the transcript. Runtime is O(n) in message length. No external state is mutated.
+ * @param[in] command {string} Invokable slash-command name that failed.
+ * @param[in] errorMessage {string} Surfaced failure diagnostic.
+ * @return {CommandReportEntryData} Report entry payload for session persistence.
+ */
+export function buildCommandReportErrorEntryData(
+  command: string,
+  errorMessage: string,
+): CommandReportEntryData {
+  return {
+    command,
+    level: "error",
+    outcome: "error",
+    lines: [`outcome: error`, `error: ${errorMessage}`],
+  };
+}
+
+/**
+ * @brief Appends one durable command report entry to the active session when the host supports custom entries.
+ * @details Probes the optional `pi.appendEntry(...)` surface before use so legacy hosts and offline harnesses without custom-entry support skip persistence silently; supported hosts persist the payload as a `custom` session entry that survives session restore while remaining excluded from LLM context. Runtime is O(1) plus delegated session-entry persistence. Side effects include session-file entry persistence on supported hosts.
+ * @param[in] pi {ExtensionAPI} Active extension API instance.
+ * @param[in] data {CommandReportEntryData} Report entry payload to persist.
+ * @return {boolean} `true` when the entry was appended; `false` when the host lacks the custom-entry surface.
+ */
+export function appendCommandReportEntry(pi: ExtensionAPI, data: CommandReportEntryData): boolean {
+  const registrar = pi as ExtensionAPI & CommandReportEntryRegistrar;
+  if (typeof registrar.appendEntry !== "function") {
+    return false;
+  }
+  registrar.appendEntry(COMMAND_REPORT_ENTRY_TYPE, data);
+  return true;
+}
+
+/**
+ * @brief Renders one durable command report entry as a transcript component.
+ * @details Maps the report payload into a themed multi-line `Text` — header colored `error` for failed runs and `accent` otherwise, body lines colored `error` for failed runs and `muted` otherwise — and returns `undefined` for malformed payloads so the host transcript skips undisplayable entries. Runtime is O(n) in aggregate report-line length. No external state is mutated.
+ * @param[in] entry {CustomEntry<CommandReportEntryData>} Persisted custom report entry.
+ * @param[in] _options {EntryRenderOptions} Host render options; retained for renderer-signature compatibility.
+ * @param[in] theme {Theme} Active pi theme used for color tokens.
+ * @return {Component | undefined} Transcript component, or `undefined` when the payload is malformed.
+ */
+function renderCommandReportEntry(
+  entry: CustomEntry<CommandReportEntryData>,
+  _options: EntryRenderOptions,
+  theme: Theme,
+): Component | undefined {
+  if (!isCommandReportEntryData(entry.data)) {
+    return undefined;
+  }
+  const data = entry.data;
+  const isError = data.level === "error";
+  const headerColor = isError ? "error" : "accent";
+  const bodyColor = isError ? "error" : "muted";
+  const header = theme.fg(headerColor, `pi-usereq ${data.command}: execution report`);
+  const body = data.lines.map((line) => theme.fg(bodyColor, line)).join("\n");
+  return new Text(`${header}\n${body}`, 1, 0);
+}
+
+/**
+ * @brief Registers the durable command report transcript renderer when the host supports entry rendering.
+ * @details Probes the optional `pi.registerEntryRenderer(...)` surface before use so legacy hosts and offline harnesses without custom-entry rendering skip registration silently; supported hosts bind the renderer for `pi-usereq.command-report` entries so appended reports render in the live transcript and re-render after every session restore. Runtime is O(1). Side effects include entry-renderer registration on supported hosts.
+ * @param[in] pi {ExtensionAPI} Active extension API instance.
+ * @return {void} No return value.
+ */
+export function registerCommandReportEntryRenderer(pi: ExtensionAPI): void {
+  const registrar = pi as ExtensionAPI & CommandReportEntryRegistrar;
+  if (typeof registrar.registerEntryRenderer !== "function") {
+    return;
+  }
+  registrar.registerEntryRenderer(COMMAND_REPORT_ENTRY_TYPE, renderCommandReportEntry);
+}

package/src/core/pi-notify.ts

@@ -85,6 +85,20 @@ export const DEFAULT_PI_NOTIFY_PUSHOVER_TITLE = "%%PROMT%% @ %%BASE%% [%%TIME%%]
  */
 export const DEFAULT_PI_NOTIFY_PUSHOVER_TEXT = "%%RESULT%%\n%%ARGS%%";
 
+/**
+ * @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
+ */
+const PI_NOTIFY_PUSHOVER_TRUNCATION_MARKER = "...[truncated]";
+
 /**
  * @brief Enumerates supported Pushover priorities.
  * @details Restricts persisted Pushover delivery to the canonical normal and high-priority values accepted by the configuration menu. Access complexity is O(1).
@@ -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,38 @@ 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 so the pushed text remains configurable and deterministic, 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
  */
 function buildPiNotifyPushoverBody(
   config: PiNotifyConfigFields,
   outcome: PiNotifyOutcome,
   request: PiNotifyEventRequest,
 ): string {
-  return substitutePiNotifyTextTemplate(config["notify-pushover-text"], request, outcome);
+  return truncatePiNotifyPushoverBody(
+    substitutePiNotifyTextTemplate(config["notify-pushover-text"], request, outcome),
+  );
 }
 
 /**
@@ -790,7 +825,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,12 +893,12 @@ 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, 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 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,

package/src/index.ts

@@ -174,6 +174,12 @@ import {
   shouldReplayDeferredNotificationsOnSessionStart,
 } from "./core/notification-replay.js";
 import { ensureBundledResourcesAccessible, readBundledPromptDescription } from "./core/resources.js";
+import {
+  appendCommandReportEntry,
+  buildCommandReportErrorEntryData,
+  buildReqReferencesCommandReportEntryData,
+  registerCommandReportEntryRenderer,
+} from "./core/command-report-entry.js";
 import { ReqError } from "./core/errors.js";
 import {
   PI_USEREQ_STATUS_HOOK_NAMES,
@@ -1492,16 +1498,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,
@@ -1563,6 +1603,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);
@@ -2704,7 +2745,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);
@@ -2741,7 +2782,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",
@@ -3493,11 +3534,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, 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, 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, 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.
  * @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-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
  */
 function registerReqReferencesCommand(
   pi: ExtensionAPI,
@@ -3526,6 +3567,7 @@ function registerReqReferencesCommand(
         const executionResult = executeReqReferencesCommandExecution(executionPlan, config);
         setPiUsereqWorkflowState(statusController, "idle", ctx);
         const referencesDisplayPath = formatRuntimePathForDisplay(executionResult.referencesPath);
+        appendCommandReportEntry(pi, buildReqReferencesCommandReportEntryData(executionResult));
         notifyContextSafely(
           ctx,
           executionResult.referencesChanged
@@ -3553,6 +3595,7 @@ function registerReqReferencesCommand(
         statusController.state.activePromptRequest = undefined;
         setPiUsereqWorkflowState(statusController, "error", ctx);
         const message = error instanceof Error ? error.message : String(error);
+        appendCommandReportEntry(pi, buildCommandReportErrorEntryData("req-references", message));
         notifyContextSafely(ctx, message, "error");
         throw error;
       }
@@ -5361,13 +5404,14 @@ function registerConfigCommands(
 
 /**
  * @brief Registers the complete pi-usereq extension.
- * @details Persists the live extension api into process-scoped storage on every bind so model re-application after session replacement binds to the api of the currently active session runner instead of an invalidated captured api, then validates installation-owned bundled resources, schedules a best-effort idle-time shared-tokenizer plus canonical-context-file measurement pre-warm so the first configuration-menu render never pays the one-time `js-tiktoken` module load or first content encodes synchronously, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, conditionally registers config-gated debug tool wrapper commands when the current project enables them, registers configuration commands, registers the configurable notification-sound shortcut when the runtime supports shortcuts, and installs shared wrappers for all supported pi lifecycle hooks so status telemetry, context usage, prompt timing, cumulative runtime, prompt-specific Pushover metadata, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, process-scoped extension-api persistence, optional debug-log writes, and timer scheduling.
+ * @details Persists the live extension api into process-scoped storage on every bind so model re-application after session replacement binds to the api of the currently active session runner instead of an invalidated captured api, registers the durable `pi-usereq.command-report` transcript entry renderer, then validates installation-owned bundled resources, schedules a best-effort idle-time shared-tokenizer plus canonical-context-file measurement pre-warm so the first configuration-menu render never pays the one-time `js-tiktoken` module load or first content encodes synchronously, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, conditionally registers config-gated debug tool wrapper commands when the current project enables them, registers configuration commands, registers the configurable notification-sound shortcut when the runtime supports shortcuts, and installs shared wrappers for all supported pi lifecycle hooks so status telemetry, context usage, prompt timing, cumulative runtime, prompt-specific Pushover metadata, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, process-scoped extension-api persistence, optional debug-log writes, and timer scheduling.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @return {void} No return value.
  * @satisfies DES-002, DES-015, REQ-004, REQ-005, REQ-009, REQ-044, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-304, REQ-305, REQ-306, REQ-312, REQ-313, REQ-323, REQ-324, REQ-325, REQ-326, REQ-327
  */
 export default function piUsereqExtension(pi: ExtensionAPI): void {
   writePersistedPromptCommandRuntimeApi(pi as unknown as PersistedPromptCommandRuntimeApi);
+  registerCommandReportEntryRenderer(pi);
   const statusController = createPiUsereqStatusController();
   ensureBundledResourcesAccessible();
   try {