@pi-unipi/ask-user 0.1.11 → 2.0.1

package/README.md

@@ -12,6 +12,8 @@ Ask-user has no user commands. It's an agent tool package — the agent calls it
 
 All workflow skills detect ask-user and use it for decision gates. Instead of the agent deciding on its own, it presents options and waits for your input. This happens naturally during brainstorm, plan, work, and other skills when the agent faces ambiguity.
 
+For workflow handoffs, options can use `action: "new_session"` with a `prefill`. Selecting one opens a launcher where **Compact & run** queues the prefill after compaction (or a short fallback) and **Run directly** queues it immediately. If automatic queuing fails, the prefill is placed in the editor for you to submit manually.
+
 The bundled skill guides the agent to use `ask_user` for high-stakes decisions — architecture choices, database selection, naming decisions, anything with lasting impact.
 
 ## Agent Tool
@@ -43,6 +45,34 @@ ask_user({
 })
 ```
 
+### `new_session` Handoffs
+
+```typescript
+ask_user({
+  question: "Continue with implementation?",
+  options: [
+    {
+      label: "Proceed to work",
+      value: "work",
+      action: "new_session",
+      prefill: "/unipi:work specs:2026-05-06-feature-plan.md",
+    },
+    { label: "Done for now", value: "done", action: "end_turn" },
+  ],
+  allowFreeform: false,
+})
+```
+
+When the user chooses a `new_session` option:
+
+| Launcher choice | Behavior |
+|-----------------|----------|
+| 🧹 Compact & run | Starts context compaction, returns immediately, then queues/submits the prefill as a follow-up message from the compaction callback or a short fallback timer |
+| ▶ Run directly | Queues/submits the prefill immediately as a follow-up message |
+| ✕ Cancel | Cancels the handoff; no message is queued |
+
+The tool result is rendered as `queued compact → ...` or `queued direct → ...`. If automatic delivery fails, ask-user falls back to editor prefill and warns you to press Enter.
+
 ### Keyboard Controls
 
 | Mode | Keys |

package/ask-ui.ts

@@ -5,7 +5,8 @@
  * Uses ctx.ui.custom() callback pattern following question.ts/questionnaire.ts.
  */
 
-import { Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
+import { Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth, type TUI, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
+import type { Theme, AgentToolResult } from "@mariozechner/pi-coding-agent";
 import type { NormalizedOption, AskUserResponse } from "./types.js";
 
 /** Result returned by the ask UI */
@@ -31,9 +32,9 @@ export function renderAskUI(params: {
   allowFreeform: boolean;
   timeout?: number;
 }): (
-  tui: any,
-  theme: any,
-  kb: any,
+  tui: TUI,
+  theme: Theme,
+  kb: import("@mariozechner/pi-coding-agent").KeybindingsManager,
   done: (result: AskUIResult | null) => void,
 ) => {
   render: (width: number) => string[];
@@ -446,9 +447,23 @@ export function renderAskUI(params: {
     function renderOptions(
       lines: string[],
       add: (s: string) => void,
-      theme: any,
+      theme: Theme,
       width: number,
     ) {
+      const addWrappedOptionLine = (prefix: string, content: string) => {
+        const prefixWidth = visibleWidth(prefix);
+        const contentWidth = Math.max(1, width - prefixWidth);
+        const continuationPrefix = " ".repeat(prefixWidth);
+        const wrapped = wrapTextWithAnsi(content, contentWidth);
+        for (let lineIndex = 0; lineIndex < wrapped.length; lineIndex++) {
+          add((lineIndex === 0 ? prefix : continuationPrefix) + wrapped[lineIndex]);
+        }
+      };
+
+      const addWrappedDescription = (description: string) => {
+        addWrappedOptionLine("     ", theme.fg("muted", description));
+      };
+
       for (let i = 0; i < displayOptions.length; i++) {
         const opt = displayOptions[i];
         const isSelected = i === optionIndex;
@@ -466,11 +481,9 @@ export function renderAskUI(params: {
             label = `${opt.label}: "${customText}"`;
           }
           
-          add(
-            prefix +
-              theme.fg(color, `[${box}]`) +
-              " " +
-              theme.fg(isSelected ? "accent" : "text", label),
+          addWrappedOptionLine(
+            prefix + theme.fg(color, `[${box}]`) + " ",
+            theme.fg(isSelected ? "accent" : "text", label),
           );
           
           // Show edit indicator if in edit mode for this option
@@ -492,11 +505,9 @@ export function renderAskUI(params: {
             label = `${opt.label}: "${optCustom}"`;
           }
           
-          add(
-            prefix +
-              theme.fg(color, `[${box}]`) +
-              " " +
-              theme.fg(isSelected ? "accent" : "text", label),
+          addWrappedOptionLine(
+            prefix + theme.fg(color, `[${box}]`) + " ",
+            theme.fg(isSelected ? "accent" : "text", label),
           );
           
           // Show edit indicator if in edit mode for this option
@@ -524,11 +535,11 @@ export function renderAskUI(params: {
             label += theme.fg("dim", " ↗");
           }
           
-          add(
-            prefix +
-              (isSelected
-                ? theme.fg("accent", label)
-                : theme.fg("text", label)),
+          addWrappedOptionLine(
+            prefix,
+            isSelected
+              ? theme.fg("accent", label)
+              : theme.fg("text", label),
           );
           
           // Show edit indicator if in edit mode for this option
@@ -542,7 +553,7 @@ export function renderAskUI(params: {
 
         // Description
         if (opt.description) {
-          add(`     ${theme.fg("muted", opt.description)}`);
+          addWrappedDescription(opt.description);
         }
       }
     }
@@ -561,19 +572,48 @@ export function renderAskUI(params: {
  * Create a renderCall function for the ask_user tool.
  */
 export function createRenderCall() {
-  return (args: any, theme: any, _context: any) => {
-    const question = args.question || "";
-    const options = Array.isArray(args.options) ? args.options : [];
+  return (args: Record<string, unknown>, theme: Theme, _context: unknown) => {
+    const question = (args.question as string) || "";
+    const context = (args.context as string | undefined) || "";
+    const options = Array.isArray(args.options)
+      ? (args.options as Array<Record<string, unknown>>)
+      : [];
     const mode = args.allowMultiple ? "multi-select" : "single-select";
+    const allowFreeform = args.allowFreeform !== false;
     const count = options.length;
 
-    let text =
-      theme.fg("toolTitle", theme.bold("ask_user ")) +
-      theme.fg("muted", question);
+    const lines: string[] = [];
+    lines.push(
+      theme.fg("toolTitle", theme.bold("ask_user")) +
+        theme.fg("dim", ` (${count} option${count !== 1 ? "s" : ""}, ${mode}${allowFreeform ? ", freeform" : ""})`),
+    );
+    if (context) {
+      lines.push(theme.fg("muted", "Context: ") + theme.fg("text", context));
+    }
+    lines.push(theme.fg("muted", "Question: ") + theme.fg("text", question));
+
     if (count > 0) {
-      text += theme.fg("dim", ` (${count} option${count !== 1 ? "s" : ""}, ${mode})`);
+      lines.push(theme.fg("muted", "Options:"));
+      options.forEach((option, index) => {
+        const label = String(option.label ?? option.value ?? `Option ${index + 1}`);
+        const action = typeof option.action === "string" && option.action !== "select"
+          ? theme.fg("dim", ` [${option.action}]`)
+          : "";
+        lines.push(
+          theme.fg("dim", `  ${index + 1}. `) +
+            theme.fg("text", label) +
+            action,
+        );
+        if (typeof option.description === "string" && option.description.trim()) {
+          lines.push(theme.fg("muted", `     ${option.description}`));
+        }
+        if (typeof option.prefill === "string" && option.prefill.trim()) {
+          lines.push(theme.fg("dim", `     prefill: ${option.prefill}`));
+        }
+      });
     }
-    return new Text(text, 0, 0);
+
+    return new Text(lines.join("\n"), 0, 0);
   };
 }
 
@@ -581,14 +621,15 @@ export function createRenderCall() {
  * Create a renderResult function for the ask_user tool.
  */
 export function createRenderResult() {
-  return (result: any, _options: any, theme: any, _context: any) => {
-    const details = result.details;
+  return (result: AgentToolResult<unknown>, _options: unknown, theme: Theme, _context: unknown) => {
+    const details = result.details as Record<string, unknown> | undefined;
     if (!details) {
-      const text = result.content?.[0];
-      return new Text(text?.type === "text" ? text.text : "", 0, 0);
+      const content = result.content as unknown as Array<Record<string, unknown>> | undefined;
+      const text = content?.[0];
+      return new Text(text?.type === "text" ? (text.text as string) : "", 0, 0);
     }
 
-    const response = details.response as AskUserResponse;
+    const response = (details as { response: AskUserResponse }).response;
     if (!response) {
       return new Text(theme.fg("warning", "No response"), 0, 0);
     }
@@ -639,19 +680,39 @@ export function createRenderResult() {
           0,
         );
       case "new_session": {
-        const launchedWith = (response as any).launchedWith;
-        if (launchedWith === "compact") {
+        const prefill = response.prefill || "";
+        if (response.launchStatus === "editor_prefill") {
+          const label = response.launchedWith === "compact"
+            ? "⚠ compact editor prefill → "
+            : "⚠ direct editor prefill → ";
+          return new Text(
+            theme.fg("warning", label) + theme.fg("accent", prefill),
+            0,
+            0,
+          );
+        }
+        if (response.launchStatus === "failed") {
+          const label = response.launchedWith === "compact"
+            ? "handoff failed (compact) → "
+            : "handoff failed (direct) → ";
+          return new Text(
+            theme.fg("error", label) + theme.fg("accent", prefill),
+            0,
+            0,
+          );
+        }
+        if (response.launchedWith === "compact") {
           return new Text(
-            theme.fg("success", "✓ compacted → ") +
-              theme.fg("accent", response.prefill || ""),
+            theme.fg("success", "✓ queued compact → ") +
+              theme.fg("accent", prefill),
             0,
             0,
           );
         }
-        if (launchedWith === "direct") {
+        if (response.launchedWith === "direct") {
           return new Text(
-            theme.fg("success", "✓ running → ") +
-              theme.fg("accent", response.prefill || ""),
+            theme.fg("success", "✓ queued direct → ") +
+              theme.fg("accent", prefill),
             0,
             0,
           );
@@ -659,7 +720,7 @@ export function createRenderResult() {
         return new Text(
           theme.fg("success", "✓ ") +
             theme.fg("muted", "new session") +
-            (response.prefill ? theme.fg("accent", `: ${response.prefill}`) : ""),
+            (prefill ? theme.fg("accent", `: ${prefill}`) : ""),
           0,
           0,
         );

package/commands.ts

@@ -23,7 +23,7 @@ export function registerAskUserCommands(pi: ExtensionAPI): void {
       }
 
       ctx.ui.custom(
-        (tui: any, _theme: any, _keybindings: any, done: any) => {
+        (tui, _theme, _keybindings, done) => {
           const overlay = new AskUserSettingsOverlay();
           overlay.onClose = () => done(undefined);
           return {

package/handoff.ts

@@ -0,0 +1,163 @@
+/**
+ * @pi-unipi/ask-user — new_session handoff helpers
+ *
+ * Queues launcher prefill messages without waiting for LLM follow-up.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { SessionLaunchReason, SessionLaunchStatus } from "./types.js";
+
+/** Compact handoff fallback timer. Keeps the launcher from stalling if callbacks wait for the tool turn to finish. */
+export const COMPACT_HANDOFF_FALLBACK_MS = 1500;
+
+export interface HandoffResult {
+  status: SessionLaunchStatus;
+  reason: SessionLaunchReason;
+  prefill?: string;
+  error?: string;
+}
+
+interface NormalizedPrefill {
+  ok: true;
+  prefill: string;
+} 
+
+interface InvalidPrefill {
+  ok: false;
+  reason: "empty-prefill";
+}
+
+function normalizePrefill(prefill: string | undefined): NormalizedPrefill | InvalidPrefill {
+  const trimmed = (prefill ?? "").trim();
+  if (!trimmed) {
+    return { ok: false, reason: "empty-prefill" };
+  }
+  return { ok: true, prefill: trimmed };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function notify(ctx: ExtensionContext, message: string, level: "info" | "warning" | "error"): void {
+  try {
+    ctx.ui.notify(message, level);
+  } catch {
+    // Notifications are best-effort only; never let status UI break delivery.
+  }
+}
+
+function fallbackToEditor(
+  ctx: ExtensionContext,
+  prefill: string,
+  reason: SessionLaunchReason,
+  error: unknown,
+): HandoffResult {
+  try {
+    ctx.ui.setEditorText(prefill);
+    notify(ctx, "Automatic handoff failed. The command was placed in the editor; press Enter to run it.", "warning");
+    return {
+      status: "editor_prefill",
+      reason,
+      prefill,
+      error: errorMessage(error),
+    };
+  } catch (editorError) {
+    notify(ctx, `Automatic handoff failed and editor fallback failed: ${errorMessage(editorError)}`, "error");
+    return {
+      status: "failed",
+      reason,
+      prefill,
+      error: `${errorMessage(error)}; editor fallback: ${errorMessage(editorError)}`,
+    };
+  }
+}
+
+function deliverFollowUpMessage(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  prefill: string,
+  reason: SessionLaunchReason,
+): HandoffResult {
+  try {
+    pi.sendUserMessage(prefill, { deliverAs: "followUp" });
+    return { status: "queued", reason, prefill };
+  } catch (error) {
+    return fallbackToEditor(ctx, prefill, reason, error);
+  }
+}
+
+export function queueDirectHandoff(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  prefill: string | undefined,
+): HandoffResult {
+  const normalized = normalizePrefill(prefill);
+  if (!normalized.ok) {
+    return { status: "cancelled", reason: normalized.reason };
+  }
+
+  return deliverFollowUpMessage(pi, ctx, normalized.prefill, "direct");
+}
+
+export function queueCompactHandoff(params: {
+  pi: ExtensionAPI;
+  ctx: ExtensionContext;
+  prefill: string | undefined;
+  customInstructions: string;
+}): HandoffResult {
+  const { pi, ctx, customInstructions } = params;
+  const normalized = normalizePrefill(params.prefill);
+  if (!normalized.ok) {
+    return { status: "cancelled", reason: normalized.reason };
+  }
+
+  const { prefill } = normalized;
+  let delivered = false;
+  let fallbackTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const clearFallbackTimer = () => {
+    if (fallbackTimer) {
+      clearTimeout(fallbackTimer);
+      fallbackTimer = undefined;
+    }
+  };
+
+  const deliverOnce = (reason: SessionLaunchReason): HandoffResult | undefined => {
+    if (delivered) {
+      return undefined;
+    }
+    delivered = true;
+    clearFallbackTimer();
+    if (reason === "fallback-timeout") {
+      notify(ctx, "Compaction is still running; queued the selected handoff command via fallback.", "info");
+    }
+    return deliverFollowUpMessage(pi, ctx, prefill, reason);
+  };
+
+  fallbackTimer = setTimeout(() => {
+    deliverOnce("fallback-timeout");
+  }, COMPACT_HANDOFF_FALLBACK_MS);
+
+  try {
+    ctx.compact({
+      customInstructions,
+      onComplete: () => {
+        deliverOnce("compacted");
+      },
+      onError: (error) => {
+        notify(ctx, `Compaction reported an error; continuing handoff anyway: ${errorMessage(error)}`, "warning");
+        deliverOnce("compaction-error");
+      },
+    });
+  } catch (error) {
+    notify(ctx, `Could not start compaction; running selected handoff directly: ${errorMessage(error)}`, "warning");
+    return deliverOnce("compact-start-failed") ?? {
+      status: "queued",
+      reason: "compact-start-failed",
+      prefill,
+    };
+  }
+
+  return { status: "scheduled", reason: "compact-started", prefill };
+}

package/launcher-ui.ts

@@ -5,7 +5,8 @@
  * Offers Compact & run, Run directly, or Cancel.
  */
 
-import { Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import { Key, matchesKey, truncateToWidth, type TUI, visibleWidth } from "@mariozechner/pi-tui";
+import type { Theme, KeybindingsManager } from "@mariozechner/pi-coding-agent";
 import type { SessionLauncherResult } from "./types.js";
 
 /** Launcher option definition */
@@ -30,9 +31,9 @@ const OPTIONS: LauncherOption[] = [
 export function renderLauncherUI(params: {
   prefill: string;
 }): (
-  tui: any,
-  theme: any,
-  kb: any,
+  tui: TUI,
+  theme: Theme,
+  kb: KeybindingsManager,
   done: (result: SessionLauncherResult | null) => void,
 ) => {
   render: (width: number) => string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "0.1.11",
+  "version": "2.0.1",
   "description": "Structured user input tool for Pi coding agent — single-select, multi-select, freeform",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,7 @@
     "index.ts",
     "types.ts",
     "tools.ts",
+    "handoff.ts",
     "ask-ui.ts",
     "launcher-ui.ts",
     "commands.ts",
@@ -31,6 +32,9 @@
     "skills/**/*",
     "README.md"
   ],
+  "scripts": {
+    "test": "node --experimental-strip-types --test tests/**/*.test.ts"
+  },
   "pi": {
     "extensions": [
       "index.ts"

package/skills/ask-user/SKILL.md

@@ -56,7 +56,7 @@ Use the `ask_user` tool to collect structured input from the user.
 | `"select"` | Normal selection (default). Returns immediately. |
 | `"input"` | Enters text input mode. Returns `combined` response with selection + text. |
 | `"end_turn"` | Signals end of agent turn. Returns `end_turn` response kind. |
-| `"new_session"` | Starts a new session. Returns `new_session` response kind with optional `prefill`. Shows a launcher overlay offering **Compact & run** (compacts context first) or **Run directly**. |
+| `"new_session"` | Starts a handoff. Returns `new_session` response kind with optional `prefill`. Shows a launcher overlay offering **Compact & run** (compact first, then queue/submit the prefill) or **Run directly** (queue/submit immediately). The current LLM follow-up is aborted after a successful queue or editor fallback. |
 
 ## Examples
 
@@ -149,7 +149,7 @@ ask_user({
 - "Looks good" returns immediately with selection
 - "I want changes" enters text input mode for the user to explain
 - "Done for now" signals the agent to end its turn
-- "Start fresh" starts a new session with the prefill message
+- "Start fresh" opens the launcher; **Compact & run** or **Run directly** queues the prefill message automatically
 
 ## Session Launcher
 
@@ -157,8 +157,8 @@ When a user selects a `new_session` option, a secondary launcher overlay appears
 
 | Choice | Behavior |
 |--------|----------|
-| 🧹 Compact & run | Compacts current context (via `ctx.compact()`), then returns the prefill command to the LLM |
-| ▶ Run directly | Returns the prefill command to the LLM without compaction |
-| ✕ Cancel | Cancels the session launch |
+| 🧹 Compact & run | Starts `ctx.compact()` without waiting in the tool spinner, then queues/submits the prefill as a follow-up message after compaction or a short fallback timer |
+| ▶ Run directly | Queues/submits the prefill immediately as a follow-up message, without compaction |
+| ✕ Cancel | Cancels the session launch; no prefill is queued |
 
-This two-step flow lets the user manage context window usage before starting a new task.
+The prefill can be a slash command (for example `/unipi:work specs:...`) or any non-empty message. If automatic delivery fails, ask_user places the prefill in the editor and warns the user to press Enter. This two-step flow lets the user manage context window usage before starting a new task while avoiding unnecessary LLM follow-up in the old session.

package/tools.ts

@@ -8,6 +8,7 @@ import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import {
   ASK_USER_TOOLS,
+  COMPACTOR_INSTRUCTION,
   UNIPI_EVENTS,
   emitEvent,
 } from "@pi-unipi/core";
@@ -15,6 +16,7 @@ import type { NormalizedOption, AskUserResponse, SessionLauncherResult } from ".
 import { renderAskUI, createRenderCall, createRenderResult } from "./ask-ui.js";
 import { renderLauncherUI } from "./launcher-ui.js";
 import { getAskUserSettings } from "./config.js";
+import { queueCompactHandoff, queueDirectHandoff } from "./handoff.js";
 
 /**
  * Register ask-user tools.
@@ -36,7 +38,7 @@ export function registerAskUserTools(pi: ExtensionAPI): void {
       "Use allowFreeform: false to restrict to predefined options only.",
       "Use action: 'input' on an option to let the user add custom text before submitting.",
       "Use action: 'end_turn' on an option to let the user signal end of turn.",
-      "Use action: 'new_session' with prefill to let the user start a new session.",
+      "Use action: 'new_session' with prefill to let the user hand off to a queued follow-up message or slash command."
     ],
     parameters: Type.Object({
       question: Type.String({
@@ -77,7 +79,7 @@ export function registerAskUserTools(pi: ExtensionAPI): void {
                 {
                   description:
                     "Special action: 'select' (default), 'input' (text input), " +
-                    "'end_turn' (signal end of turn), 'new_session' (start new session with prefill).",
+                    "'end_turn' (signal end of turn), 'new_session' (queue handoff with prefill).",
                 },
               ),
             ),
@@ -318,12 +320,15 @@ export function registerAskUserTools(pi: ExtensionAPI): void {
           break;
         }
         case "end_turn":
+          // Abort the agent immediately — no LLM follow-up, no wasted tokens.
+          // The tool result is still recorded in session history.
+          ctx.abort();
           contentText = "User chose to end the turn.";
           break;
         case "new_session":
           contentText = response.prefill
-            ? `User chose to start a new session: ${response.prefill}`
-            : "User chose to start a new session.";
+            ? `User chose to hand off to: ${response.prefill}`
+            : "User chose a handoff without a prefill.";
           break;
         case "timed_out":
           contentText = "User did not respond (timed out)";
@@ -353,22 +358,48 @@ export function registerAskUserTools(pi: ExtensionAPI): void {
           };
         }
 
-        if (launcherResult.action === "compact") {
-          try {
-            await new Promise<void>((resolve, reject) => {
-              ctx.compact({
-                customInstructions: `Preparing for new task. Summarize previous work concisely, preserving only what's essential for: ${prefill}`,
-                onComplete: () => resolve(),
-                onError: (err) => reject(err),
-              });
-            });
-          } catch (err) {
-            // Compaction failure shouldn't block the session launch — continue anyway
-          }
+        const handoff = launcherResult.action === "compact"
+          ? queueCompactHandoff({
+              pi,
+              ctx,
+              prefill,
+              // Use the compactor sentinel so @pi-unipi/compactor's zero-LLM
+              // pipeline intercepts. If compactor is not installed, Pi's built-in
+              // LLM-based compaction runs instead.
+              customInstructions: `${COMPACTOR_INSTRUCTION}\nPreparing for new task. Summarize previous work concisely, preserving only what's essential for: ${prefill}`,
+            })
+          : queueDirectHandoff(pi, ctx, prefill);
+
+        if (handoff.status === "cancelled") {
+          return {
+            content: [{ type: "text", text: "Session launch cancelled: no prefill message was provided." }],
+            details: {
+              question,
+              options: normalizedOptions.map((o) => o.label),
+              response: {
+                kind: "cancelled",
+                comment: "Session launcher had no prefill to queue",
+                launchStatus: handoff.status,
+                launchReason: handoff.reason,
+              } as AskUserResponse,
+            },
+          };
         }
 
-        const actionLabel = launcherResult.action === "compact" ? "compacted" : "running";
-        contentText = `User chose to proceed (${actionLabel}): ${prefill}`;
+        if (handoff.status !== "failed") {
+          // Handoff is scheduled/queued or recoverably editor-prefilled; abort the
+          // current turn so the queued command can run without LLM follow-up.
+          ctx.abort();
+        }
+
+        const launchLabel = launcherResult.action === "compact" ? "compact" : "direct";
+        if (handoff.status === "editor_prefill") {
+          contentText = `Queued ${launchLabel} handoff fell back to editor prefill: ${handoff.prefill}`;
+        } else if (handoff.status === "failed") {
+          contentText = `Failed to queue ${launchLabel} handoff: ${handoff.prefill ?? prefill}`;
+        } else {
+          contentText = `Queued ${launchLabel} handoff: ${handoff.prefill ?? prefill}`;
+        }
 
         return {
           content: [{ type: "text", text: contentText }],
@@ -377,7 +408,11 @@ export function registerAskUserTools(pi: ExtensionAPI): void {
             options: normalizedOptions.map((o) => o.label),
             response: {
               ...response,
+              prefill: handoff.prefill ?? prefill,
               launchedWith: launcherResult.action,
+              launchStatus: handoff.status,
+              launchReason: handoff.reason,
+              launchError: handoff.error,
             },
           },
         };

package/types.ts

@@ -40,6 +40,20 @@ export interface AskUserParams {
   timeout?: number;
 }
 
+export type SessionLaunchAction = "compact" | "direct";
+
+export type SessionLaunchStatus = "scheduled" | "queued" | "editor_prefill" | "cancelled" | "failed";
+
+export type SessionLaunchReason =
+  | "direct"
+  | "compact-started"
+  | "compacted"
+  | "compaction-error"
+  | "fallback-timeout"
+  | "compact-start-failed"
+  | "empty-prefill"
+  | "send-failed";
+
 /** Response from ask_user tool */
 export interface AskUserResponse {
   /** Response kind */
@@ -52,6 +66,14 @@ export interface AskUserResponse {
   prefill?: string;
   /** Optional user comment */
   comment?: string;
+  /** Session launcher action, when a new_session handoff was launched */
+  launchedWith?: SessionLaunchAction;
+  /** Session launcher delivery/scheduling status */
+  launchStatus?: SessionLaunchStatus;
+  /** Session launcher status reason */
+  launchReason?: SessionLaunchReason;
+  /** Best-effort error message for handoff fallback/failure paths */
+  launchError?: string;
 }
 
 /** Result from the session launcher UI */