@pi-unipi/ask-user 0.1.10 → 2.0.0

package/README.md

@@ -1,30 +1,26 @@
 # @pi-unipi/ask-user
 
-Structured user input tool for the Pi coding agent — part of the Unipi suite.
+Structured user input for decision gates. When the agent needs you to pick between options — which database, which approach, which files to change — it calls `ask_user` instead of guessing.
 
-## Features
+Three input modes: single-select (pick one), multi-select (toggle several), freeform (type your own). The agent presents the question, you answer, it continues.
 
-### `ask_user` Tool
+## Commands
 
-Ask the user a question with structured options. Supports three modes:
+Ask-user has no user commands. It's an agent tool package — the agent calls it when it needs input.
 
-- **Single-select** — Pick one option from a list
-- **Multi-select** — Toggle multiple options, then submit
-- **Freeform** — Type a custom answer
+## Special Triggers
 
-### Usage
+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.
 
-The agent calls the tool when it needs user input:
+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.
 
-```typescript
-ask_user({
-  question: "Which database should we use?",
-  options: [
-    { label: "PostgreSQL", description: "Reliable, feature-rich" },
-    { label: "SQLite", description: "Simple, serverless" },
-  ],
-})
-```
+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
+
+| Tool | Description |
+|------|-------------|
+| `ask_user` | Structured user input with options |
 
 ### Parameters
 
@@ -37,12 +33,52 @@ ask_user({
 | `allowFreeform` | boolean? | true | Allow freeform text input |
 | `timeout` | number? | — | Auto-dismiss after N ms |
 
+### Example
+
+```typescript
+ask_user({
+  question: "Which database should we use?",
+  options: [
+    { label: "PostgreSQL", description: "Reliable, feature-rich" },
+    { label: "SQLite", description: "Simple, serverless" },
+  ],
+})
+```
+
+### `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 |
 |------|------|
-| Single-select | ↑↓ navigate, Enter select, Esc cancel |
-| Multi-select | ↑↓ navigate, Space toggle, Enter submit, Esc cancel |
+| Single-select | Up/Down navigate, Enter select, Esc cancel |
+| Multi-select | Up/Down navigate, Space toggle, Enter submit, Esc cancel |
 | Freeform | Type text, Enter submit, Esc back |
 
 ### TUI Display
@@ -57,7 +93,7 @@ ask_user({
    Option C
    Type something...
 
- ↑↓ navigate • Enter select • Esc cancel
+ Up/Down navigate, Enter select, Esc cancel
 ─────────────────────────────
 ```
 
@@ -66,34 +102,19 @@ ask_user({
 ─────────────────────────────
  Which features to enable?
 ─────────────────────────────
- > [✓] Logging
+ > [x] Logging
    [ ] Metrics
-   [✓] Tracing
+   [x] Tracing
    [ ] Type something...
 
- ↑↓ navigate • Space toggle • Enter submit • Esc cancel
+ Up/Down navigate, Space toggle, Enter submit, Esc cancel
 ─────────────────────────────
 ```
 
-## Installation
-
-```bash
-pi install npm:@pi-unipi/ask-user
-```
-
-Or install the full Unipi suite:
-
-```bash
-pi install npm:@pi-unipi/unipi
-```
-
-## Bundled Skill
+## Configurables
 
-The package includes a skill that guides the agent to use `ask_user` for high-stakes decisions. The skill is automatically discovered when the extension loads.
+Ask-user has no configuration. Input mode is determined by the `allowMultiple` and `allowFreeform` parameters the agent passes.
 
-## Dependencies
+## License
 
-- `@pi-unipi/core` — Shared constants and utilities
-- `@mariozechner/pi-coding-agent` — Pi extension API
-- `@mariozechner/pi-tui` — TUI components
-- `@sinclair/typebox` — Schema validation
+MIT

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,7 +447,7 @@ export function renderAskUI(params: {
     function renderOptions(
       lines: string[],
       add: (s: string) => void,
-      theme: any,
+      theme: Theme,
       width: number,
     ) {
       for (let i = 0; i < displayOptions.length; i++) {
@@ -561,8 +562,8 @@ 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 || "";
+  return (args: Record<string, unknown>, theme: Theme, _context: unknown) => {
+    const question = (args.question as string) || "";
     const options = Array.isArray(args.options) ? args.options : [];
     const mode = args.allowMultiple ? "multi-select" : "single-select";
     const count = options.length;
@@ -581,14 +582,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);
     }
@@ -638,14 +640,52 @@ export function createRenderResult() {
           0,
           0,
         );
-      case "new_session":
+      case "new_session": {
+        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", "✓ queued compact → ") +
+              theme.fg("accent", prefill),
+            0,
+            0,
+          );
+        }
+        if (response.launchedWith === "direct") {
+          return new Text(
+            theme.fg("success", "✓ queued direct → ") +
+              theme.fg("accent", prefill),
+            0,
+            0,
+          );
+        }
         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,
         );
+      }
       default:
         return new Text(
           theme.fg("text", JSON.stringify(response)),

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

@@ -0,0 +1,143 @@
+/**
+ * @pi-unipi/ask-user — Session Launcher TUI
+ *
+ * Secondary overlay shown when user selects a new_session option.
+ * Offers Compact & run, Run directly, or Cancel.
+ */
+
+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 */
+interface LauncherOption {
+  label: string;
+  icon: string;
+  action: SessionLauncherResult["action"];
+}
+
+const OPTIONS: LauncherOption[] = [
+  { label: "Compact & run", icon: "🧹", action: "compact" },
+  { label: "Run directly", icon: "▶", action: "direct" },
+  { label: "Cancel", icon: "✕", action: "cancel" },
+];
+
+/**
+ * Render the session launcher UI.
+ *
+ * Simple single-select picker with 3 fixed options.
+ * No editor, no timeout, no multi-select.
+ */
+export function renderLauncherUI(params: {
+  prefill: string;
+}): (
+  tui: TUI,
+  theme: Theme,
+  kb: KeybindingsManager,
+  done: (result: SessionLauncherResult | null) => void,
+) => {
+  render: (width: number) => string[];
+  invalidate: () => void;
+  handleInput: (data: string) => void;
+} {
+  return (_tui, theme, _kb, done) => {
+    const { prefill } = params;
+
+    // State
+    let optionIndex = 0;
+    let cachedLines: string[] | undefined;
+
+    function refresh() {
+      cachedLines = undefined;
+      _tui.requestRender();
+    }
+
+    function handleInput(data: string) {
+      // Navigation
+      if (matchesKey(data, Key.up)) {
+        optionIndex = Math.max(0, optionIndex - 1);
+        refresh();
+        return;
+      }
+      if (matchesKey(data, Key.down)) {
+        optionIndex = Math.min(OPTIONS.length - 1, optionIndex + 1);
+        refresh();
+        return;
+      }
+
+      // Enter: select
+      if (matchesKey(data, Key.enter)) {
+        const opt = OPTIONS[optionIndex];
+        done({ action: opt.action, prefill });
+        return;
+      }
+
+      // Escape: cancel
+      if (matchesKey(data, Key.escape)) {
+        done(null);
+        return;
+      }
+    }
+
+    function render(width: number): string[] {
+      if (cachedLines) return cachedLines;
+
+      const lines: string[] = [];
+      const innerWidth = Math.max(40, width - 2);
+      const border = (s: string) => theme.fg("accent", s);
+
+      function padVisible(content: string, targetWidth: number): string {
+        const vw = visibleWidth(content);
+        const pad = Math.max(0, targetWidth - vw);
+        return content + " ".repeat(pad);
+      }
+
+      const add = (s: string) =>
+        lines.push(
+          border("│") +
+            padVisible(truncateToWidth(s, innerWidth), innerWidth) +
+            border("│"),
+        );
+      const addEmpty = () =>
+        lines.push(border("│") + " ".repeat(innerWidth) + border("│"));
+
+      // Top border
+      lines.push(border(`╭${"─".repeat(innerWidth)}╮`));
+
+      // Header: show prefill command (truncated)
+      const headerPrefix = " 🚀 ";
+      const maxPrefillWidth = innerWidth - headerPrefix.length - 1;
+      const truncatedPrefill = truncateToWidth(prefill || "(no command)", maxPrefillWidth);
+      add(theme.fg("accent", headerPrefix) + theme.fg("text", truncatedPrefill));
+      addEmpty();
+
+      // Options
+      for (let i = 0; i < OPTIONS.length; i++) {
+        const opt = OPTIONS[i];
+        const isSelected = i === optionIndex;
+        const prefix = isSelected ? theme.fg("accent", "> ") : "  ";
+        const label = `${opt.icon} ${opt.label}`;
+        const color = isSelected ? "accent" : "text";
+        add(prefix + theme.fg(color, label));
+      }
+
+      // Footer hint
+      addEmpty();
+      add(theme.fg("dim", " ↑↓ navigate • Enter select • Esc cancel"));
+
+      // Bottom border
+      lines.push(border(`╰${"─".repeat(innerWidth)}╯`));
+
+      cachedLines = lines;
+      return lines;
+    }
+
+    return {
+      render,
+      invalidate: () => {
+        cachedLines = undefined;
+      },
+      handleInput,
+    };
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "0.1.10",
+  "version": "2.0.0",
   "description": "Structured user input tool for Pi coding agent — single-select, multi-select, freeform",
   "type": "module",
   "license": "MIT",
@@ -23,13 +23,18 @@
     "index.ts",
     "types.ts",
     "tools.ts",
+    "handoff.ts",
     "ask-ui.ts",
+    "launcher-ui.ts",
     "commands.ts",
     "config.ts",
     "settings-tui.ts",
     "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`. |
+| `"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,4 +149,16 @@ 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
+
+When a user selects a `new_session` option, a secondary launcher overlay appears with three choices:
+
+| Choice | Behavior |
+|--------|----------|
+| 🧹 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 |
+
+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,12 +8,15 @@ 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";
-import type { NormalizedOption, AskUserResponse } from "./types.js";
+import type { NormalizedOption, AskUserResponse, SessionLauncherResult } from "./types.js";
 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.
@@ -35,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({
@@ -76,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).",
                 },
               ),
             ),
@@ -317,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)";
@@ -331,6 +337,87 @@ export function registerAskUserTools(pi: ExtensionAPI): void {
           contentText = "No response";
       }
 
+      // Session launcher intercept: when user selects new_session, offer compact/direct/cancel
+      if (response.kind === "new_session") {
+        const prefill = response.prefill || "";
+        const launcherResult = await ctx.ui.custom<SessionLauncherResult | null>(
+          renderLauncherUI({ prefill }),
+        );
+
+        if (!launcherResult || launcherResult.action === "cancel") {
+          return {
+            content: [{ type: "text", text: "User cancelled the session launch" }],
+            details: {
+              question,
+              options: normalizedOptions.map((o) => o.label),
+              response: {
+                kind: "cancelled",
+                comment: "Session launcher cancelled",
+              } as AskUserResponse,
+            },
+          };
+        }
+
+        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,
+            },
+          };
+        }
+
+        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 }],
+          details: {
+            question,
+            options: normalizedOptions.map((o) => o.label),
+            response: {
+              ...response,
+              prefill: handoff.prefill ?? prefill,
+              launchedWith: launcherResult.action,
+              launchStatus: handoff.status,
+              launchReason: handoff.reason,
+              launchError: handoff.error,
+            },
+          },
+        };
+      }
+
       return {
         content: [{ type: "text", text: contentText }],
         details: {

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,20 @@ 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 */
+export interface SessionLauncherResult {
+  action: "compact" | "direct" | "cancel";
+  prefill: string;
 }
 
 /** Normalized option with resolved value */