pi-usereq 0.50.0 → 0.55.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.50.0)
+# PI-useReq/pi-usereq (0.55.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+">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-usereq",
-  "version": "0.50.0",
+  "version": "0.55.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ogekuri/PI-useReq.git"
@@ -32,9 +32,9 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-ai": "*",
-    "@mariozechner/pi-coding-agent": "*",
-    "@mariozechner/pi-tui": "*",
+    "@earendil-works/pi-ai": "^0.80.4",
+    "@earendil-works/pi-coding-agent": "^0.80.4",
+    "@earendil-works/pi-tui": "^0.80.4",
     "@sinclair/typebox": "^0.34.49"
   },
   "dependencies": {
@@ -56,6 +56,7 @@
     "protobufjs@7.5.4": true,
     "esbuild": true,
     "koffi": true,
-    "protobufjs": true
+    "protobufjs": true,
+    "@google/genai": true
   }
 }

package/scripts/lib/sdk-smoke.ts

@@ -1,7 +1,7 @@
 /**
  * @file
  * @brief Implements SDK-parity probing and comparison for the standalone debug harness.
- * @details Dynamically loads the official pi SDK when available, inventories extension-owned commands and tools from the runtime surface, normalizes provenance metadata, and compares the result against the offline recorder snapshot. Runtime is O(c + t) in command and tool counts plus the cost of SDK session creation. Side effects are limited to dynamic module loading, optional SDK-managed filesystem reads, and any extension-owned startup behavior triggered by the official runtime.
+ * @details Dynamically loads the official pi SDK when available, inventories extension-owned commands and tools from the runtime surface, passes the 0.80.4+ `authPath` and `modelsPath` `createAgentSession` options, probes support for the new 0.80.4+ event surface, normalizes provenance metadata, and compares the result against the offline recorder snapshot. Runtime is O(c + t + e) in command, tool, and probed-event counts plus the cost of SDK session creation. Side effects are limited to dynamic module loading, optional SDK-managed filesystem reads, and any extension-owned startup behavior triggered by the official runtime.
  */
 
 import path from "node:path";
@@ -53,6 +53,7 @@ export interface SdkContractSnapshot {
   tools: NormalizedToolRecord[];
   activeTools: string[];
   runtimeShape: string;
+  supportedEvents: string[];
 }
 
 /**
@@ -96,6 +97,60 @@ interface SdkApiLike {
   getActiveTools?: () => string[];
 }
 
+/**
+ * @brief Lists the 0.80.4+ pi event names probed for host support by the SDK parity probe.
+ * @details The probe registers a no-op handler for each new-event name on the extension runtime and treats a returned unsubscribe function as proof that the host emits the event, mirroring the capability contract used by prompt-end finalization. Lookup complexity is O(1).
+ * @satisfies REQ-356
+ */
+const PI_EVENT_SURFACE_PROBE_NAMES = [
+  "agent_settled",
+  "project_trust",
+  "session_info_changed",
+  "session_compact_failed",
+  "before_provider_headers",
+  "after_provider_response",
+  "ui_prompt_start",
+  "ui_prompt_end",
+  "thinking_level_select",
+] as const;
+
+/**
+ * @brief Probes the official SDK runtime for support of the 0.80.4+ pi event surface.
+ * @details Locates an object exposing an `on(...)` registration method on the `extensionsResult.runtime` surface, registers a no-op handler for each new-event name, and records those whose registration returns an unsubscribe function (the 0.80.4+ contract). Handlers are unsubscribed immediately after the probe and unsupported or unavailable surfaces yield an empty list. Runtime is O(e) in probed event count. No external state is mutated.
+ * @param[in] createAgentSessionResult {unknown} Raw `createAgentSession(...)` result.
+ * @return {string[]} Names of supported new pi events, possibly empty.
+ * @satisfies REQ-356
+ */
+function probePiEventSurface(createAgentSessionResult: unknown): string[] {
+  if (!createAgentSessionResult || typeof createAgentSessionResult !== "object") {
+    return [];
+  }
+  const candidateRoot = createAgentSessionResult as Record<string, unknown>;
+  const runtime = (candidateRoot.extensionsResult as Record<string, unknown> | undefined)?.runtime;
+  const host = runtime && typeof runtime === "object" ? runtime as Record<string, unknown> : undefined;
+  const onMethod = host?.on;
+  if (typeof onMethod !== "function") {
+    return [];
+  }
+  const probeHost = host as unknown as {
+    on(event: string, handler: (event: unknown, ctx: unknown) => unknown): unknown;
+  };
+  const supported: string[] = [];
+  for (const eventName of PI_EVENT_SURFACE_PROBE_NAMES) {
+    let unsubscribe: unknown;
+    try {
+      unsubscribe = probeHost.on(eventName, () => undefined);
+    } catch {
+      unsubscribe = undefined;
+    }
+    if (typeof unsubscribe === "function") {
+      supported.push(eventName);
+      (unsubscribe as () => void)();
+    }
+  }
+  return supported;
+}
+
 /**
  * @brief Normalizes one path relative to the requested project root.
  * @details Converts absolute paths under the project root to slash-normalized relative paths and leaves non-project or pseudo-path values unchanged. Runtime is O(p) in path length. No external state is mutated.
@@ -414,18 +469,18 @@ export function buildParityReport(offline: OfflineContractSnapshot, sdk: SdkCont
 
 /**
  * @brief Loads the official pi SDK runtime and extracts the extension-owned command and tool inventories.
- * @details Dynamically imports `@mariozechner/pi-coding-agent`, creates a `DefaultResourceLoader` with the requested extension path, creates an SDK session, extracts inventory methods from the returned runtime surface, and filters to extension-owned commands and tools only. Runtime is dominated by SDK startup. Side effects include SDK-managed resource loading and extension startup behavior.
+ * @details Dynamically imports `@earendil-works/pi-coding-agent`, creates a `DefaultResourceLoader` with the requested extension path, creates an SDK session with the 0.80.4+ `authPath` and `modelsPath` options, extracts inventory methods from the returned runtime surface, probes support for the new 0.80.4+ event surface, and filters to extension-owned commands and tools only. Runtime is dominated by SDK startup. Side effects include SDK-managed resource loading and extension startup behavior.
  * @param[in] cwd {string | undefined} Requested working directory.
  * @param[in] extensionPath {string | undefined} Requested extension entry path.
  * @return {Promise<SdkContractSnapshot>} Normalized SDK inventory snapshot.
  * @throws {ReqError} Throws when the SDK package is unavailable, runtime extraction fails, or session creation fails.
- * @satisfies REQ-050, REQ-056, REQ-058
+ * @satisfies REQ-050, REQ-056, REQ-058, REQ-356
  */
 export async function probeSdkRuntime(cwd?: string, extensionPath?: string): Promise<SdkContractSnapshot> {
   const paths = resolveHarnessPaths(cwd, extensionPath);
   let sdkModule: Record<string, unknown>;
   try {
-    sdkModule = await import("@mariozechner/pi-coding-agent") as Record<string, unknown>;
+    sdkModule = await import("@earendil-works/pi-coding-agent") as Record<string, unknown>;
   } catch (error) {
     throw new ReqError(`Error: SDK parity loading failed: ${error instanceof Error ? error.message : String(error)}`, 1);
   }
@@ -454,6 +509,8 @@ export async function probeSdkRuntime(cwd?: string, extensionPath?: string): Pro
       resourceLoader,
       sessionManager: SessionManager.inMemory(),
       settingsManager: typeof SettingsManager?.inMemory === "function" ? SettingsManager.inMemory({}) : undefined,
+      authPath: path.join(paths.cwd, ".pi-usereq-agent-auth.json"),
+      modelsPath: path.join(paths.cwd, ".pi-usereq-agent-models.json"),
     });
   } catch (error) {
     throw new ReqError(`Error: SDK parity loading failed: ${error instanceof Error ? error.message : String(error)}`, 1);
@@ -485,6 +542,7 @@ export async function probeSdkRuntime(cwd?: string, extensionPath?: string): Pro
     tools,
     activeTools,
     runtimeShape: extracted.runtimeShape,
+    supportedEvents: probePiEventSurface(createAgentSessionResult),
   };
 }
 

package/src/core/extension-status.ts

@@ -12,9 +12,9 @@ import type {
   ContextUsage,
   ExtensionContext,
   ThemeColor,
-} from "@mariozechner/pi-coding-agent";
+} from "@earendil-works/pi-coding-agent";
 import type { UseReqConfig } from "./config.js";
-import type { PiNotifySoundLevel } from "./pi-notify.js";
+import type { PiNotifyOutcome, PiNotifySoundLevel } from "./pi-notify.js";
 import type { PromptCommandExecutionPlan } from "./prompt-command-runtime.js";
 import {
   restorePersistedPromptCommandRuntimeStateForSession,
@@ -77,6 +77,7 @@ export const PI_USEREQ_STATUS_HOOK_NAMES = [
   "before_agent_start",
   "agent_start",
   "agent_end",
+  "agent_settled",
   "turn_start",
   "turn_end",
   "message_start",
@@ -124,6 +125,8 @@ export interface PiUsereqStatusState {
   runtimeSoundLevel: PiNotifySoundLevel | undefined;
   pendingPromptRequest: PiUsereqPromptRequest | undefined;
   activePromptRequest: PiUsereqPromptRequest | undefined;
+  pendingFinalizationOutcome: PiNotifyOutcome | undefined;
+  agentSettledEventSupported: boolean | undefined;
 }
 
 /**
@@ -680,6 +683,8 @@ export function createPiUsereqStatusController(): PiUsereqStatusController {
       runtimeSoundLevel: undefined,
       pendingPromptRequest: undefined,
       activePromptRequest: undefined,
+      pendingFinalizationOutcome: undefined,
+      agentSettledEventSupported: undefined,
     },
     tickHandle: undefined,
   };
@@ -802,7 +807,7 @@ export function setPiUsereqWorkflowState(
 
 /**
  * @brief Updates mutable status state for one intercepted lifecycle hook.
- * @details Refreshes stored context usage on every hook, resets or restores persisted elapsed counters during `session_start`, loads the active runtime sound level from persisted config during `session_start`, restores persisted prompt-command metadata when the active session matches a forked execution session, resynchronizes that metadata on later lifecycle hooks so post-switch workflow transitions performed by the initiating command handler become visible to the replacement-session runtime, resets workflow state to `idle` for documented session-start reasons, starts run timing on `agent_start`, promotes pending prompt-request metadata into the active run, captures non-aborted run duration on `agent_end`, accumulates successful runtime into `Σ`, preserves in-memory prompt-command state plus process-scoped persistence across switch-triggered `session_shutdown`, tolerates stale post-replacement render contexts, synchronizes the live ticker, and re-renders the status bar with the runtime extension identity prefix when configuration is available. Runtime is O(n) in `agent_end` message count and otherwise O(1). Side effects include in-memory state mutation, interval scheduling, process-scoped persistence mutation, and footer-status updates.
+ * @details Refreshes stored context usage on every hook, resets or restores persisted elapsed counters during `session_start`, loads the active runtime sound level from persisted config during `session_start`, restores persisted prompt-command metadata when the active session matches a forked execution session, resynchronizes that metadata on later lifecycle hooks so post-switch workflow transitions performed by the initiating command handler become visible to the replacement-session runtime, resets workflow state to `idle` for documented session-start reasons, starts run timing on `agent_start`, promotes pending prompt-request metadata into the active run, captures non-aborted run duration on `agent_end` or `agent_settled`, accumulates successful runtime into `Σ`, preserves in-memory prompt-command state plus process-scoped persistence across switch-triggered `session_shutdown`, tolerates stale post-replacement render contexts, synchronizes the live ticker, and re-renders the status bar with the runtime extension identity prefix when configuration is available. Runtime is O(n) in `agent_end` message count and otherwise O(1). Side effects include in-memory state mutation, interval scheduling, process-scoped persistence mutation, and footer-status updates.
  * @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
  * @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
  * @param[in] event {unknown} Hook payload forwarded from the wrapper.
@@ -851,9 +856,15 @@ export function updateExtensionStatus(
     controller.state.pendingPromptRequest = undefined;
   }
 
-  if (hookName === "agent_end" && controller.state.runStartTimeMs !== undefined) {
+  if (
+    (hookName === "agent_end" || hookName === "agent_settled")
+    && controller.state.runStartTimeMs !== undefined
+  ) {
     const durationMs = nowMs - controller.state.runStartTimeMs;
-    if (!didAgentEndAbort((event as AgentEndEvent).messages ?? [])) {
+    const agentEndMessages = hookName === "agent_end"
+      ? (event as AgentEndEvent).messages ?? []
+      : [];
+    if (!didAgentEndAbort(agentEndMessages)) {
       controller.state.lastRunDurationMs = durationMs;
       controller.state.totalRunDurationMs = controller.state.totalRunDurationMs === undefined
         ? durationMs

package/src/core/pi-notify.ts

@@ -8,7 +8,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import * as https from "node:https";
-import type { AgentEndEvent } from "@mariozechner/pi-coding-agent";
+import type { AgentEndEvent } from "@earendil-works/pi-coding-agent";
 import { getInstallationPath, normalizePathSlashes } from "./path-context.js";
 import type { UseReqConfig } from "./config.js";
 

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

@@ -28,7 +28,7 @@ import {
   setRuntimeGitPath,
   setRuntimeWorktreePathState,
 } from "./path-context.js";
-import { SessionManager } from "@mariozechner/pi-coding-agent";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
 import { resolveRuntimeGitPath } from "./runtime-project-paths.js";
 import {
   clearPersistedPromptCommandSessionContext,
@@ -1945,11 +1945,11 @@ export async function finalizePromptCommandExecution(
 /**
  * @brief Maps one `agent_end` payload into the canonical prompt-worktree finalization outcome.
  * @details Delegates to the shared notification outcome classifier so worktree merge and fork-session retention decisions stay aligned with prompt-end notification routing. Runtime is O(m) in assistant message count. No external state is mutated.
- * @param[in] event {Pick<import("@mariozechner/pi-coding-agent").AgentEndEvent, "messages">} Agent-end payload subset.
+ * @param[in] event {Pick<import("@earendil-works/pi-coding-agent").AgentEndEvent, "messages">} Agent-end payload subset.
  * @return {PiNotifyOutcome} Canonical prompt-end outcome.
  */
 export function classifyPromptCommandOutcome(
-  event: Pick<import("@mariozechner/pi-coding-agent").AgentEndEvent, "messages">,
+  event: Pick<import("@earendil-works/pi-coding-agent").AgentEndEvent, "messages">,
 ): PiNotifyOutcome {
   return classifyPiNotifyOutcome(event);
 }

package/src/core/prompts.ts

@@ -1,7 +1,7 @@
 /**
  * @file
  * @brief Renders bundled pi-usereq prompts for the current project context.
- * @details Applies placeholder substitution, legacy tool-name rewrites, and conditional pi.dev governance guidance before prompt text is sent to the agent. Runtime is linear in prompt size plus replacement count. Side effects are limited to filesystem reads used for manifest checks and bundled prompt loading.
+ * @details Applies placeholder substitution, legacy tool-name rewrites, and conditional pi.dev governance guidance before prompt text is sent to the agent. Runtime is linear in prompt size plus replacement count. Side effects are limited to filesystem reads used for the coding-agent-docs directory check and bundled prompt loading.
  */
 
 import fs from "node:fs";
@@ -61,8 +61,8 @@ const PI_DEV_AWARE_PROMPT_NAMES = new Set<string>([
   "refactor",
 ]);
 /**
- * @brief Stores the repository-relative pi.dev manifest path used in prompt guidance.
- * @details The constant lets rendered prompts cite the authoritative documentation manifest with a deterministic path. Lookup complexity is O(1).
+ * @brief Stores the repository-relative optional pi.dev manifest path used in prompt guidance.
+ * @details The constant lets rendered prompts cite the authoritative documentation manifest when present with a deterministic path. The governance block is not gated on this file; it is an optional contract source. Lookup complexity is O(1).
  */
 const PI_DEV_MANIFEST_PROMPT_PATH = "docs/pi.dev/agent-document-manifest.json";
 /**
@@ -82,37 +82,36 @@ const PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH = `${PI_DEV_DOCS_PROMPT_PATH}/coding-
 const PI_DEV_SOURCE_PROMPT_PATH = "pi.dev-src/pi-mono";
 /**
  * @brief Defines the injected pi.dev governance guidance block.
- * @details The block requires read-only handling for documentation and pi client sources, manifest-first review, coding-agent-document compliance, and pi client source validation for ambiguous or bug-fix interface work. Construction happens once at module load. Access complexity is O(1).
+ * @details The block requires read-only handling for documentation and pi client sources, coding-agent-document review, coding-agent-document compliance, optional manifest-referenced document handling, and pi client source validation for ambiguous or bug-fix interface work. Construction happens once at module load. Access complexity is O(1).
  * @satisfies REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
  */
 const PI_DEV_CONFORMANCE_BLOCK = [
   "- Treat every path under `docs/` as read-only; do NOT modify "
-    + `\`${PI_DEV_MANIFEST_PROMPT_PATH}\` or any other documentation file.`,
+    + "any documentation file, including those under `docs/pi.dev/`.",
   "- Treat every path under `pi.dev-src/` as read-only; do NOT modify "
     + `\`${PI_DEV_SOURCE_PROMPT_PATH}\` or any other pi client source.`,
   "- If the task creates or modifies software that interfaces with the "
-    + `pi.dev CLI, read \`${PI_DEV_MANIFEST_PROMPT_PATH}\` and every `
-    + "document path it references before analysis, implementation, "
-    + "verification, or bug fixing.",
-  `- Treat \`${PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH}/\` and documents `
-    + `referenced by \`${PI_DEV_MANIFEST_PROMPT_PATH}\` as the `
+    + `pi.dev CLI, review \`${PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH}/\` `
+    + "before analysis, implementation, verification, or bug fixing.",
+  `- Treat \`${PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH}/\` as the `
     + "authoritative read-only interface contract; new or modified "
     + "pi.dev CLI integrations MUST comply with the APIs they describe.",
-  `- Treat manifest document paths as relative to \`${PI_DEV_DOCS_PROMPT_PATH}/\`.`,
-  "- If manifest or "
-    + `\`${PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH}/\` guidance is `
+  `- If \`${PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH}/\` guidance is `
     + "ambiguous for extension-to-pi-client interface behavior, validate "
     + `the produced source code by analyzing \`${PI_DEV_SOURCE_PROMPT_PATH}\`.`,
   "- For bug fixes or problem resolution influenced by extension-to-pi-client "
     + "interface implementations, validate the produced source code by "
     + `analyzing \`${PI_DEV_SOURCE_PROMPT_PATH}\`.`,
+  `- If \`${PI_DEV_MANIFEST_PROMPT_PATH}\` exists under \`${PI_DEV_DOCS_PROMPT_PATH}/\`, `
+    + "treat every document path it references as part of the read-only "
+    + "interface contract.",
 ].join("\n");
 
 /**
  * @brief Builds the conditional pi.dev governance block for one rendered prompt.
- * @details Emits the manifest-driven governance rules only when the selected bundled prompt can analyze or mutate source code and the project root contains the pi.dev manifest. Time complexity O(1). No filesystem writes.
+ * @details Emits the coding-agent-document-driven governance rules only when the selected bundled prompt can analyze or mutate source code and the project root contains the `docs/pi.dev/coding-agent-docs/` directory; the manifest file is optional and its absence does not suppress the block. Time complexity O(1). No filesystem writes.
  * @param[in] promptName {string} Bundled prompt identifier.
- * @param[in] projectBase {string} Absolute project root used for manifest existence checks.
+ * @param[in] projectBase {string} Absolute project root used for coding-agent-docs directory existence checks.
  * @return {string} Markdown bullet block or the empty string when injection is not applicable.
  * @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
  */
@@ -120,8 +119,8 @@ function buildPiDevConformanceBlock(promptName: string, projectBase: string): st
   if (!PI_DEV_AWARE_PROMPT_NAMES.has(promptName)) {
     return "";
   }
-  const manifestPath = path.join(projectBase, PI_DEV_MANIFEST_PROMPT_PATH);
-  if (!fs.existsSync(manifestPath) || !fs.statSync(manifestPath).isFile()) {
+  const codingAgentDocsPath = path.join(projectBase, PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH);
+  if (!fs.existsSync(codingAgentDocsPath) || !fs.statSync(codingAgentDocsPath).isDirectory()) {
     return "";
   }
   return PI_DEV_CONFORMANCE_BLOCK;
@@ -132,7 +131,7 @@ function buildPiDevConformanceBlock(promptName: string, projectBase: string): st
  * @details Inserts the block immediately after the `## Behavior` heading so downstream agents evaluate the rule before workflow steps. Leaves prompts unchanged when no behavior section exists or the block is already present. Time complexity O(n).
  * @param[in] text {string} Prompt markdown after placeholder replacement.
  * @param[in] promptName {string} Bundled prompt identifier.
- * @param[in] projectBase {string} Absolute project root used for manifest existence checks.
+ * @param[in] projectBase {string} Absolute project root used for coding-agent-docs directory existence checks.
  * @return {string} Prompt markdown with zero or one injected conformance block.
  * @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
  */

package/src/core/settings-menu.ts

@@ -4,8 +4,8 @@
  * @details Wraps `SettingsList` in one extension-command helper that exposes right-aligned current values, built-in circular scrolling, bottom-line descriptions, and a deterministic bridge for offline test harnesses. Runtime is O(n) in visible choice count plus user interaction cost. Side effects are limited to transient custom-UI rendering.
  */
 
-import { getSettingsListTheme, type ThemeColor, type ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
-import { Container, SettingsList, Text, type Component, type SettingItem, type SettingsListTheme } from "@mariozechner/pi-tui";
+import { getSettingsListTheme, type ThemeColor, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Container, SettingsList, Text, type Component, type SettingItem, type SettingsListTheme } from "@earendil-works/pi-tui";
 
 /**
  * @brief Describes one selectable pi-usereq settings-menu choice.

package/src/index.ts

@@ -18,8 +18,8 @@ import type {
   ExtensionCommandContext,
   ExtensionContext,
   ToolInfo,
-} from "@mariozechner/pi-coding-agent";
-import { Text } from "@mariozechner/pi-tui";
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import {
   buildMonolithicToolExecuteResult,
@@ -153,6 +153,7 @@ import {
   setPiUsereqWorkflowState,
   shouldPreservePromptCommandStateOnShutdown,
   updateExtensionStatus,
+  type PiUsereqPromptRequest,
   type PiUsereqStatusController,
   type PiUsereqStatusHookName,
 } from "./core/extension-status.js";
@@ -1247,9 +1248,138 @@ function applyConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig): v
   pi.setActiveTools(allTools.map((tool) => tool.name).filter((toolName) => nextActive.has(toolName)));
 }
 
+/**
+ * @brief Probes whether the running pi host emits the `agent_settled` event and caches the result on the status controller state.
+ * @details The 0.80.4+ `ExtensionAPI.on(...)` contract returns an unsubscribe function, and `agent_settled` is introduced in that same release; therefore a registration that returns a callable proves the host supports the event, while a `void` registration means a legacy host that never emits it. The probe registers a no-op handler once per status controller, unsubscribes it when the new contract returns a function, and caches the boolean so all later lookups are O(1). No external state is retained beyond the controller-scoped cached boolean.
+ * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller that caches the probed capability.
+ * @param[in] pi {ExtensionAPI} Active extension API instance used to probe event registration.
+ * @return {boolean} `true` when the host emits `agent_settled`, `false` on legacy hosts.
+ * @satisfies REQ-354, REQ-355
+ */
+function isPiAgentSettledEventSupported(
+  statusController: PiUsereqStatusController,
+  pi: ExtensionAPI,
+): boolean {
+  if (statusController.state.agentSettledEventSupported !== undefined) {
+    return statusController.state.agentSettledEventSupported;
+  }
+  const probeHost = pi as ExtensionAPI & {
+    on(event: string, handler: (event: unknown, ctx: unknown) => unknown): unknown;
+  };
+  const registration = probeHost.on("agent_settled", () => undefined);
+  const supported = typeof registration === "function";
+  if (supported) {
+    (registration as () => void)();
+  }
+  statusController.state.agentSettledEventSupported = supported;
+  return supported;
+}
+
+/**
+ * @brief Finalizes a matched successful worktree-backed prompt at the current lifecycle point.
+ * @details Executes the deferred stash-assisted merge, transcript preservation, base-path restore, and worktree plus branch deletion through `finalizePromptCommandExecution(...)`, surfaces `error` or warning-only notifications, clears the pending finalization outcome plus prompt state, and transitions workflow state through `merging` to `idle`. Reused by the `agent_settled` handler on 0.80.4+ hosts and directly by the `agent_end` fallback on legacy hosts that never emit `agent_settled`. Runtime is dominated by git finalization. Side effects include branch merges, worktree deletion, notifications, and workflow-state transitions.
+ * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller whose pending and active prompt state is cleared.
+ * @param[in] promptRequest {PiUsereqPromptRequest} Matched successful worktree-backed prompt execution plan.
+ * @param[in] ctx {ExtensionContext} Active extension context used for finalization and notifications.
+ * @return {Promise<void>} Promise resolved when finalization and state transitions complete.
+ * @satisfies REQ-208, REQ-228, REQ-229, REQ-230, REQ-282, REQ-291, REQ-292, REQ-354, REQ-355
+ */
+async function finalizeMatchedPromptSuccess(
+  statusController: PiUsereqStatusController,
+  promptRequest: PiUsereqPromptRequest,
+  ctx: ExtensionContext,
+): Promise<void> {
+  const debugConfig = statusController.config;
+  let promptContext = ctx;
+  let finalization:
+    | {
+      mergeAttempted: boolean;
+      mergeSucceeded: boolean;
+      cleanupSucceeded: boolean;
+      errorMessage?: string;
+      warningMessage?: string;
+      activeContext?: unknown;
+    }
+    | undefined;
+  try {
+    finalization = await finalizePromptCommandExecution(
+      promptRequest,
+      promptContext,
+      debugConfig
+        ? { config: debugConfig, workflowState: statusController.state.workflowState }
+        : undefined,
+    );
+    promptContext = (finalization.activeContext ?? promptContext) as typeof ctx;
+  } catch (error) {
+    promptContext = (getPromptCommandErrorContext(error) ?? promptContext) as typeof ctx;
+    let errorMessage = error instanceof Error ? error.message : String(error);
+    let cleanupSucceeded = false;
+    try {
+      promptContext = (await restorePromptCommandExecution(
+        promptRequest,
+        promptContext,
+        debugConfig
+          ? { config: debugConfig, workflowState: statusController.state.workflowState }
+          : undefined,
+      ) ?? promptContext) as typeof ctx;
+      cleanupSucceeded = true;
+    } catch (restoreError) {
+      promptContext = (getPromptCommandErrorContext(restoreError) ?? promptContext) as typeof ctx;
+      errorMessage = restoreError instanceof Error ? restoreError.message : String(restoreError);
+    }
+    finalization = {
+      mergeAttempted: false,
+      mergeSucceeded: false,
+      cleanupSucceeded,
+      errorMessage,
+    };
+  }
+  if (
+    finalization.errorMessage
+    && (!finalization.cleanupSucceeded || !finalization.mergeSucceeded)
+  ) {
+    if (debugConfig) {
+      transitionPromptWorkflowState(
+        statusController,
+        promptContext,
+        promptRequest.basePath,
+        debugConfig,
+        promptRequest.promptName,
+        "error",
+      );
+    } else {
+      setPiUsereqWorkflowState(statusController, "error", promptContext);
+    }
+    notifyContextSafely(promptContext, finalization.errorMessage, "error");
+  }
+  if (
+    finalization.warningMessage
+    && finalization.cleanupSucceeded
+    && finalization.mergeSucceeded
+    && !finalization.errorMessage
+  ) {
+    notifyContextSafely(promptContext, finalization.warningMessage, "info");
+  }
+  statusController.state.pendingFinalizationOutcome = undefined;
+  statusController.state.pendingPromptRequest = undefined;
+  statusController.state.activePromptRequest = undefined;
+  if (debugConfig) {
+    transitionPromptWorkflowState(
+      statusController,
+      promptContext,
+      promptRequest.basePath,
+      debugConfig,
+      promptRequest.promptName,
+      "idle",
+    );
+  } else {
+    setPiUsereqWorkflowState(statusController, "idle", promptContext);
+  }
+}
+
 /**
  * @brief Handles one intercepted pi lifecycle hook for pi-usereq status updates.
- * @details Applies session-start-specific resource validation, project-config refresh, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. 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, restores the original session-backed `base-path` for every matched worktree-backed completion by reusing persisted replacement-session command contexts when event contexts omit `switchSession()`, executes the stash-assisted merge-and-delete finalization path for every matched successful worktree-backed completion even when a later busy-command rejection already moved workflow state to `error`, 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 `agent_end` 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, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. 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.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
@@ -1373,65 +1503,14 @@ async function handleExtensionStatusEvent(
         );
       }
       if (shouldFinalizeMatchedSuccess) {
-        if (debugConfig) {
-          transitionPromptWorkflowState(
-            statusController,
-            promptContext,
-            activePromptRequest.basePath,
-            debugConfig,
-            activePromptRequest.promptName,
-            "merging",
-          );
-        } else {
-          setPiUsereqWorkflowState(statusController, "merging", promptContext);
-        }
-        let finalization:
-          | {
-            mergeAttempted: boolean;
-            mergeSucceeded: boolean;
-            cleanupSucceeded: boolean;
-            errorMessage?: string;
-            warningMessage?: string;
-            activeContext?: unknown;
-          }
-          | undefined;
-        try {
-          finalization = await finalizePromptCommandExecution(
-            activePromptRequest,
-            promptContext,
-            debugConfig
-              ? { config: debugConfig, workflowState: statusController.state.workflowState }
-              : undefined,
-          );
-          promptContext = (finalization.activeContext ?? promptContext) as typeof ctx;
-        } catch (error) {
-          promptContext = (getPromptCommandErrorContext(error) ?? promptContext) as typeof ctx;
-          let errorMessage = error instanceof Error ? error.message : String(error);
-          let cleanupSucceeded = false;
-          try {
-            promptContext = (await restorePromptCommandExecution(
-              activePromptRequest,
-              promptContext,
-              debugConfig
-                ? { config: debugConfig, workflowState: statusController.state.workflowState }
-                : undefined,
-            ) ?? promptContext) as typeof ctx;
-            cleanupSucceeded = true;
-          } catch (restoreError) {
-            promptContext = (getPromptCommandErrorContext(restoreError) ?? promptContext) as typeof ctx;
-            errorMessage = restoreError instanceof Error ? restoreError.message : String(restoreError);
-          }
-          finalization = {
-            mergeAttempted: false,
-            mergeSucceeded: false,
-            cleanupSucceeded,
-            errorMessage,
-          };
-        }
-        if (
-          finalization.errorMessage
-          && (!finalization.cleanupSucceeded || !finalization.mergeSucceeded)
-        ) {
+        if (isPiAgentSettledEventSupported(statusController, pi)) {
+          // Defer the restore switch, merge, and worktree deletion to
+          // `agent_settled`. The pi 0.80.4+ `switchSession` implementation
+          // awaits the active agent run to become idle before replacing the
+          // session, and that idle transition only happens at `agent_settled`.
+          // Calling `switchSession` here would deadlock the `agent_end` handler
+          // and leave the workflow parked in `merging` forever.
+          statusController.state.pendingFinalizationOutcome = outcome;
           if (debugConfig) {
             transitionPromptWorkflowState(
               statusController,
@@ -1439,20 +1518,21 @@ async function handleExtensionStatusEvent(
               activePromptRequest.basePath,
               debugConfig,
               activePromptRequest.promptName,
-              "error",
+              "merging",
             );
           } else {
-            setPiUsereqWorkflowState(statusController, "error", promptContext);
+            setPiUsereqWorkflowState(statusController, "merging", promptContext);
           }
-          notifyContextSafely(promptContext, finalization.errorMessage, "error");
-        }
-        if (
-          finalization.warningMessage
-          && finalization.cleanupSucceeded
-          && finalization.mergeSucceeded
-          && !finalization.errorMessage
-        ) {
-          notifyContextSafely(promptContext, finalization.warningMessage, "info");
+        } else {
+          // Legacy hosts never emit `agent_settled`, so no idle-waiting
+          // `switchSession` deadlock exists; finalize the matched success
+          // directly at `agent_end` to avoid parking in `merging` forever.
+          statusController.state.pendingFinalizationOutcome = outcome;
+          await finalizeMatchedPromptSuccess(
+            statusController,
+            activePromptRequest,
+            promptContext,
+          );
         }
       } else if (closureFailureMessage !== undefined) {
         // Worktree-backed run that ended interrupted, failed, aborted, or
@@ -1500,7 +1580,7 @@ async function handleExtensionStatusEvent(
           notifyContextSafely(promptContext, error instanceof Error ? error.message : String(error), "error");
         }
       }
-      if (closureFailureMessage === undefined) {
+      if (closureFailureMessage === undefined && !shouldFinalizeMatchedSuccess) {
         statusController.state.pendingPromptRequest = undefined;
         statusController.state.activePromptRequest = undefined;
         if (debugConfig) {
@@ -1518,6 +1598,17 @@ async function handleExtensionStatusEvent(
       }
     }
   }
+  if (hookName === "agent_settled") {
+    const settledPromptRequest = statusController.state.activePromptRequest;
+    const pendingOutcome = statusController.state.pendingFinalizationOutcome;
+    if (
+      settledPromptRequest !== undefined
+      && settledPromptRequest.worktreeDir !== undefined
+      && pendingOutcome === "completed"
+    ) {
+      await finalizeMatchedPromptSuccess(statusController, settledPromptRequest, ctx);
+    }
+  }
   if (hookName === "session_shutdown") {
     if (shutdownPromptRequest !== undefined && statusController.config) {
       logPromptWorkflowEvent(