pi-subagents-lite 1.4.1 → 1.4.2

package/README.md

@@ -35,7 +35,7 @@ Names like `Agent`, `StopAgent`, `AgentStatus`, `run_in_background`, `worktree_p
 - **Live widget** — persistent status bar with running/completed agents, full and compact modes
 - **Result viewer** — fullscreen markdown with stats
 - **Worktrees** — run agents in a git worktree via `worktree_path`
-- **Output logs** — `tail -f` friendly, ISO-timestamped
+- **Output logs** — `tail -f` friendly, ISO-timestamped with configurable thinking buffer (OFF, 80, 200, 500, 1000 chars). Flush rounds to sentence boundaries.
 
 ## Install
 
@@ -112,7 +112,7 @@ Stop a running agent by ID.
 |---|---|---|
 | `agent_id` | ✅ | The agent ID returned by `Agent` at spawn |
 
-IDs come from the `Agent` result, the `StopAgent` error (lists all running IDs), or `/agents` → **Running agents**.
+IDs come from the `Agent` result, the `StopAgent` error (lists all running IDs), or `/agents` → **Running agents**. Display format is `id (type)` (e.g. `a1b2c3 (Explore)`).
 
 ### `AgentStatus`
 
@@ -244,13 +244,13 @@ When `includeContextFiles` is `true` (default), AGENTS.md files from the project
 Management menu with four sections:
 
 - **Running agents** — status and description; per-agent actions (view snapshot, result, error; steer; stop) and bulk stop
-- **Spawn agent** — manually spawn without the LLM. Pick a type, enter a prompt, tune options (model, thinking, max turns, max tokens, grace turns, background), then spawn. Options pre-fill from agent config.
+- **Spawn agent** — manually spawn without the LLM. Pick a type (with search), enter a prompt, tune options (model, thinking, max turns, max tokens, grace turns, background), then spawn. Options pre-fill from agent config.
 - **Settings**
   - **Model settings** — global default, per-type overrides, session overrides, clear all
   - **Spawn options** — force background, grace turns, default max turns, default thinking, disable default agents
   - **System prompt** — mode, custom prompt file, include AGENTS.md, load skills/extensions implicitly
-  - **Concurrency** — default limit, per-provider and per-model slots, reset to defaults
-  - **Widget settings** — force compact, max lines, description length, ctrl+o shortcut, usage stats (toggle tools, turns, input/output tokens, context %, cost, time)
+  - **Concurrency** — default limit, per-provider and per-model slots (with search), reset to defaults
+  - **Widget settings** — force compact, max lines, description length, thinking buffer size, ctrl+o shortcut, usage stats (toggle tools, turns, input/output tokens, context %, cost, time)
 
 ## Interface
 
@@ -333,6 +333,7 @@ With **Cost display** ON, stats show dollar cost (`✓ Builder·2🛠 ·5⟳ ·
 | `widgetDescLengthCompact` | `30` | Max description length in compact mode. |
 | `widgetCompact` | `false` | Force compact mode regardless of ctrl+o state. |
 | `widgetShortcut` | `false` | When ON, ctrl+o (tool expansion toggle) syncs with widget compact mode. When OFF, compact is manual via `widgetCompact`. |
+| `outputThinkingBufferSize` | `200` | Thinking buffer ring size in chars. `0` = OFF. Flushes to output log at sentence boundaries. |
 
 ### Stats visibility
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents-lite",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "Lightweight sub-agents for pi — spawn specialized agents with isolated sessions, tools, and models.",
   "keywords": [
     "pi-package",
@@ -28,11 +28,12 @@
     "url": "https://github.com/AlexParamonov/pi-subagents-lite/issues"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.74.0",
-    "@earendil-works/pi-coding-agent": ">=0.74.0",
-    "@earendil-works/pi-tui": ">=0.74.0"
+    "@earendil-works/pi-ai": "^0.80.1",
+    "@earendil-works/pi-coding-agent": "^0.80.1",
+    "@earendil-works/pi-tui": "^0.80.1"
   },
   "dependencies": {
+    "@earendil-works/pi-agent-core": "^0.80.1",
     "@sinclair/typebox": "^0.34.49"
   },
   "files": [

package/src/agents/agent-manager.ts

@@ -98,6 +98,7 @@ export class AgentManager {
     onComplete?: OnAgentComplete,
     concurrency?: ConcurrencyConfig,
     onStart?: OnAgentStart,
+    private bufferSize: number = 0,
   ) {
     this.onComplete = onComplete;
     this.onStart = onStart;
@@ -258,7 +259,7 @@ export class AgentManager {
     record.lifecycle.startedAt = Date.now();
 
     // Create output log for this agent (creates file + writes [USER] entry)
-    record.execution.outputLog = new AgentOutputLog(id, prompt);
+    record.execution.outputLog = new AgentOutputLog(id, prompt, undefined, this.bufferSize);
     record.display.outputFile = record.execution.outputLog.path;
 
     this.onStart?.(record);

package/src/agents/agent-status.ts

@@ -12,11 +12,11 @@ import { SHORT_ID_LENGTH } from "../types.js";
 import { getManager } from "../shell.js";
 
 /**
- * Format a single agent record as "type·short_id·status".
+ * Format a single agent record as "short_id (type) status".
  */
 function formatAgent(record: AgentRecord): string {
   const shortId = record.id.slice(0, SHORT_ID_LENGTH);
-  return `${record.display.type}·${shortId}·${record.lifecycle.status}`;
+  return `${shortId} (${record.display.type}) ${record.lifecycle.status}`;
 }
 
 /**

package/src/agents/output-file.ts

@@ -12,6 +12,19 @@ import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-
 import { formatTokens } from "./usage.js";
 import { summarizeToolArgs } from "../ui/format.js";
 
+
+/** Find the last sentence boundary in text. Returns the index of the
+ * terminal punctuation character, or -1 if none found. */
+function findLastSentenceBoundary(text: string): number {
+  // Search backward for the most recent sentence-ending punctuation
+  for (let i = text.length - 1; i >= 0; i--) {
+    const ch = text[i];
+    if ([".", "!", "?", ",", "\n"].includes(ch)) {
+      return i;
+    }
+  }
+  return -1;
+}
 /** Max content length for full tool result display — longer results get a summary line. */
 const MAX_TOOL_RESULT_DISPLAY_LENGTH = 500;
 
@@ -111,12 +124,14 @@ function formatToolResult(toolName: string, content: ReadonlyArray<Record<string
 function formatMessageLine(
   role: "ASSISTANT" | "TOOL" | "USER",
   content: string | ReadonlyArray<Record<string, unknown>> | undefined,
+  skipThinkingCount: number = 0,
 ): string {
   if (typeof content === "string") {
     return splitAndPrefix(content, role);
   }
 
   if (Array.isArray(content)) {
+    let thinkingSkipped = 0;
     return content
       .map((item) => {
         if (item.type === "text" && typeof item.text === "string") {
@@ -126,6 +141,10 @@ function formatMessageLine(
           return formatToolItem(item);
         }
         if (item.type === "thinking" && typeof item.thinking === "string") {
+          if (thinkingSkipped < skipThinkingCount) {
+            thinkingSkipped++;
+            return ""; // Already streamed, skip
+          }
           const text = item.redacted ? "[redacted]" : item.thinking;
           return splitAndPrefix(text, "THINKING");
         }
@@ -136,7 +155,6 @@ function formatMessageLine(
 
   return "";
 }
-
 /**
  * Subscribe to session events and flush new messages to the output file
  * on each turn_end. Returns a cleanup function that writes the DONE line
@@ -148,15 +166,28 @@ export function streamToOutputFile(
   session: AgentSession,
   path: string,
   stats?: { turnCount: number; toolUseCount: number; totalTokens: number; cost: number },
+  bufferSize: number = 0,
 ): () => void {
   let writtenCount = 1; // initial user prompt already written
+  let thinkingBuffer = "";
+  let streamedThinkingBlocks = 0; // thinking blocks written live; skipped in the final flush
+  let streamedThinkingChars = 0; // track total chars streamed for deduplication
+  let thinkingBlockInProgress = false; // true between thinking_start and thinking_end
+
+  const flushThinkingBuffer = () => {
+    if (thinkingBuffer.length > 0) {
+      safeAppend(path, splitAndPrefix(thinkingBuffer, "THINKING"));
+      streamedThinkingChars += thinkingBuffer.length;
+      thinkingBuffer = "";
+    }
+  };
 
   const flush = () => {
     const messages = session.messages;
     while (writtenCount < messages.length) {
       const msg = messages[writtenCount];
       if (msg.role === "assistant") {
-        const lines = formatMessageLine("ASSISTANT", msg.content as any);
+        const lines = formatMessageLine("ASSISTANT", msg.content as any, streamedThinkingBlocks);
         if (lines) safeAppend(path, lines);
       } else if (msg.role === "user") {
         const text = extractUserText(msg.content as any);
@@ -176,11 +207,60 @@ export function streamToOutputFile(
   };
 
   const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
-    if (event.type === "turn_end") flush();
+    if (event.type === "turn_end") {
+      flushThinkingBuffer();
+      // If thinking_end never fired, treat this as if it did to avoid duplicates
+      if (thinkingBlockInProgress) {
+        streamedThinkingBlocks++;
+        thinkingBlockInProgress = false;
+      }
+      flush();
+    }
+
+    if (bufferSize > 0 && event.type === "message_update") {
+      const assistantEvent = event.assistantMessageEvent;
+      if (assistantEvent.type === "thinking_start") {
+        // Reset counter for new thinking block
+        streamedThinkingChars = 0;
+        thinkingBlockInProgress = true;
+      } else if (assistantEvent.type === "thinking_delta") {
+        thinkingBuffer += assistantEvent.delta;
+        if (thinkingBuffer.length >= bufferSize || thinkingBuffer.includes("\n")) {
+          // Round down to nearest sentence boundary when possible
+          if (thinkingBuffer.length >= bufferSize) {
+            const boundary = findLastSentenceBoundary(thinkingBuffer);
+            if (boundary >= 0) {
+              const flushText = thinkingBuffer.slice(0, boundary + 1);
+              thinkingBuffer = thinkingBuffer.slice(boundary + 1);
+              safeAppend(path, splitAndPrefix(flushText, "THINKING"));
+              streamedThinkingChars += flushText.length;
+            } else {
+              // No sentence boundary found, flush at buffer limit
+              flushThinkingBuffer();
+            }
+          } else {
+            // Newline found before buffer limit
+            flushThinkingBuffer();
+          }
+        }
+      } else if (assistantEvent.type === "thinking_end") {
+        // thinking_end carries the full block. Flush the buffered tail first
+        // (counted in streamedThinkingChars), then stream whatever remains.
+        flushThinkingBuffer();
+        if (assistantEvent.content && assistantEvent.content.length > streamedThinkingChars) {
+          const remaining = assistantEvent.content.slice(streamedThinkingChars);
+          safeAppend(path, splitAndPrefix(remaining, "THINKING"));
+          streamedThinkingChars = assistantEvent.content.length;
+        }
+        streamedThinkingBlocks++;
+        thinkingBlockInProgress = false;
+      }
+    }
   });
 
   return () => {
     // Final flush
+    flushThinkingBuffer();
     flush();
 
     // Write DONE line
@@ -219,10 +299,12 @@ export class AgentOutputLog {
   readonly path: string;
   private cleanup?: () => void;
   private statsRef?: OutputFinalStats;
+  private bufferSize: number;
 
-  constructor(agentId: string, prompt: string, baseDir?: string) {
+  constructor(agentId: string, prompt: string, baseDir?: string, bufferSize: number = 0) {
     this.path = createOutputFilePath(agentId, baseDir);
     writeInitialEntry(this.path, prompt);
+    this.bufferSize = bufferSize;
   }
 
   /**
@@ -232,7 +314,7 @@ export class AgentOutputLog {
    */
   attach(session: AgentSession): void {
     this.statsRef = { turnCount: 0, toolUseCount: 0, totalTokens: 0, cost: 0 };
-    this.cleanup = streamToOutputFile(session, this.path, this.statsRef);
+    this.cleanup = streamToOutputFile(session, this.path, this.statsRef, this.bufferSize);
   }
 
   /**

package/src/agents/tool-execution.ts

@@ -113,8 +113,13 @@ export async function executeAgentTool(
   if (rawWorktreePath && rawWorktreePath.trim() !== "") {
     try {
       const parentCwd = getSessionCtx()?.cwd ?? ctx.cwd;
-      const validation = await validateWorktreePath(getPiInstance(), rawWorktreePath, parentCwd);
+      const warnings: string[] = [];
+      const onWarning = (msg: string) => { warnings.push(msg); };
+      const validation = await validateWorktreePath(getPiInstance(), rawWorktreePath, parentCwd, onWarning);
       if (!validation.ok) {
+        for (const msg of warnings) {
+          if (ctx.ui?.notify) ctx.ui.notify(`[pi-subagents-lite] ${msg}`, "warning");
+        }
         return errorResult(validation.error);
       }
       validatedWorktreePath = validation.resolvedPath;
@@ -198,7 +203,7 @@ export async function executeAgentTool(
 
 /**
  * Build a compact list of running (or queued) agents.
- * Format: "type·short_id, type·short_id" — one line, easy for LLM to parse.
+ * Format: "short_id (type), short_id (type)" — one line, easy for LLM to parse.
  */
 function formatRunningAgents(): string {
   const agents = getManager()!.listAgents().filter(
@@ -208,7 +213,7 @@ function formatRunningAgents(): string {
   if (agents.length === 0) return "none";
 
   return agents
-    .map((a) => `${a.display.type}·${a.id.slice(0, SHORT_ID_LENGTH)}`)
+    .map((a) => `${a.id.slice(0, SHORT_ID_LENGTH)} (${a.display.type})`)
     .join(", ");
 }
 

package/src/config/config-store.ts

@@ -76,6 +76,8 @@ export interface ResolvedAgentSettings {
   readonly showContext: boolean;
   /** Whether to show elapsed time in widget stats line. */
   readonly showTime: boolean;
+  /** Buffer size for streaming thinking blocks to output file. 0 = disabled. */
+  readonly outputThinkingBufferSize: number;
 }
 
 /** Side-effect targets, injected after construction. */
@@ -140,6 +142,7 @@ export class ConfigStore {
       showOutput: a.showOutput !== false,
       showContext: a.showContext !== false,
       showTime: a.showTime !== false,
+      outputThinkingBufferSize: a.outputThinkingBufferSize ?? 0,
     };
   }
 
@@ -271,6 +274,10 @@ export class ConfigStore {
       setShowOutput: (enabled: boolean) => this.setAgentVisibility("showOutput", enabled),
       setShowContext: (enabled: boolean) => this.setAgentVisibility("showContext", enabled),
       setShowTime: (enabled: boolean) => this.setAgentVisibility("showTime", enabled),
+      setOutputThinkingBufferSize: (size: number): void => {
+        this.config.agent.outputThinkingBufferSize = size;
+        this.persist();
+      },
     },
     widget: {
       setCompact: (enabled: boolean): void => {

package/src/config/types.ts

@@ -23,4 +23,5 @@ export const CONFIG_AGENT_NON_MODEL_KEYS = [
   "loadSkillsImplicitly",
   "loadExtensionsImplicitly",
   "disableDefaultAgents",
+  "outputThinkingBufferSize",
 ];

package/src/events.ts

@@ -39,13 +39,15 @@ export function ensureManagerAndWidget(): void {
     const newManager = new AgentManager(
       undefined, // onComplete wired below
       getStore().concurrency as unknown as ConstructorParameters<typeof AgentManager>[1],
+      undefined,
+      getStore().agent.outputThinkingBufferSize,
     );
     setManager(newManager);
     // Sync the manager as a config side-effect target (concurrency setters call setConcurrency).
     getStore().setDeps({ manager: newManager });
 
     // Now create coordinator with the real manager
-    const coordinator = new SpawnCoordinator(newManager, getPiInstance());
+    const coordinator = new SpawnCoordinator(newManager);
     setCoordinator(coordinator);
 
     // Wire the manager's onComplete to the coordinator

package/src/models/model-precedence.ts

@@ -56,6 +56,8 @@ export interface SubagentsConfig {
     widgetDescLengthFull?: number;
     /** Max description length in widget compact mode. Default: 30. */
     widgetDescLengthCompact?: number;
+    /** When > 0, thinking deltas stream to output file during message_update events. Default: 0 (disabled). */
+    outputThinkingBufferSize?: number;
     [agentType: string]: string | null | undefined | boolean | number;
   };
   concurrency: {

package/src/spawn/spawn-coordinator.ts

@@ -1,4 +1,5 @@
 import { getStatusNote } from "../status-note.js";
+import { getWidget } from "../shell.js";
 /**
  * spawn-coordinator.ts — Spawn-and-track coordination for subagents.
  *
@@ -14,7 +15,6 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import type { AgentRecord, SpawnConfig, ToolActivity } from "../types.js";
 import type { AgentManager, SpawnOptions } from "../agents/agent-manager.js";
 import { buildAgentDetails } from "../agents/tool-execution.js";
-import { getWidget } from "../shell.js";
 
 // ============================================================================
 // Types
@@ -64,12 +64,13 @@ export class SpawnCoordinator {
   /** Active nudge timer. */
   private nudgeTimer: ReturnType<typeof setTimeout> | null = null;
 
-  /** The pi API reference for sending messages. */
+  /** Latest ExtensionAPI reference, refreshed on each spawn() call. */
   private pi: ExtensionAPI | null = null;
 
-  constructor(private manager: AgentManager, pi?: ExtensionAPI) {
-    if (pi) this.pi = pi;
-  }
+  /** Set during dispose to prevent nudge emission after session replacement. */
+  private disposed = false;
+
+  constructor(private manager: AgentManager) {}
 
   /**
    * Spawn + wire tracking + (foreground) await.
@@ -80,9 +81,6 @@ export class SpawnCoordinator {
     ctx: ExtensionContext,
     intent: SpawnIntent,
   ): Promise<SpawnResult> {
-    // Store pi for nudge emission
-    this.pi = pi;
-
     // Create live view BEFORE spawn so callbacks can close over it
     const liveView: LiveView = {
       activeTools: new Map(),
@@ -116,6 +114,9 @@ export class SpawnCoordinator {
       this.backgroundAgentIds.add(agentId);
     }
 
+    // Store latest pi reference for nudge delivery
+    this.pi = pi;
+
     const record = this.manager.getRecord(agentId)!;
 
     if (!intent.runInBackground) {
@@ -183,7 +184,7 @@ export class SpawnCoordinator {
     this.pendingNudges.clear();
     this.liveViews.clear();
     this.backgroundAgentIds.clear();
-    this.pi = null;
+    this.disposed = true;
   }
 
   // ── Private ──
@@ -208,25 +209,39 @@ export class SpawnCoordinator {
 
   /** Emit an individual nudge for a completed background agent. */
   private emitIndividualNudge(agentId: string): void {
+    // Skip if disposed — prevents stale pi usage after session replacement
+    if (this.disposed) return;
+
+    // Skip if no pi instance yet (no spawn has occurred)
+    if (!this.pi) {
+      console.warn(`subagent nudge skipped for ${agentId}: no pi instance available (no spawn has occurred yet)`);
+      return;
+    }
+
     const record = this.manager.getRecord(agentId);
-    if (!record || !this.pi) return;
+    if (!record) return;
 
     const details = buildAgentDetails(record, {
       includeStats: true,
       includeStatus: true,
     });
 
-    this.pi.sendMessage(
-      {
-        customType: "subagent-result",
-        content: `[Subagent "${record.display.type}" ${record.lifecycle.status}]\n\n${record.result ?? ""} ${getStatusNote(record.lifecycle.status)}`,
-        details,
-        display: true,
-      },
-      {
-        deliverAs: "steer",
-        triggerTurn: true,
-      },
-    );
+    try {
+      this.pi.sendMessage(
+        {
+          customType: "subagent-result",
+          content: `[Subagent "${record.display.type}" ${record.lifecycle.status}]\n\n${record.result ?? ""} ${getStatusNote(record.lifecycle.status)}`,
+          details,
+          display: true,
+        },
+        {
+          deliverAs: "steer",
+          triggerTurn: true,
+        },
+      );
+    } catch (error) {
+      // Defense-in-depth: pi may be stale after session replacement/reload.
+      console.warn(`subagent nudge failed for ${agentId}:`, error);
+    }
   }
 }

package/src/spawn/worktree-validator.ts

@@ -60,6 +60,7 @@ async function getGitCommonDir(
   pi: PiExec,
   cwd: string,
   notInRepoError: string,
+  onWarning?: (msg: string) => void,
 ): Promise<{ ok: true; commonDir: string } | { ok: false; error: string }> {
   try {
     const result = await pi.exec("git", ["rev-parse", "--git-common-dir"], { cwd, timeout: GIT_EXEC_TIMEOUT_MS });
@@ -72,7 +73,11 @@ async function getGitCommonDir(
     if (msg.includes("ENOENT") || msg.includes("not found")) {
       return { ok: false, error: WORKTREE_VALIDATION_ERRORS.GIT_NOT_FOUND };
     }
-    return { ok: false, error: WORKTREE_VALIDATION_ERRORS.GIT_TIMEOUT };
+    if (msg.includes("timed out") || msg.includes("timeout")) {
+      return { ok: false, error: WORKTREE_VALIDATION_ERRORS.GIT_TIMEOUT };
+    }
+    onWarning?.(`git rev-parse --git-common-dir failed in ${cwd}: ${msg}`);
+    return { ok: false, error: `worktree_path validation failed: git rev-parse failed: ${msg}` };
   }
 }
 
@@ -97,6 +102,7 @@ export async function validateWorktreePath(
   pi: PiExec,
   worktreePath: string,
   parentCwd: string,
+  onWarning?: (msg: string) => void,
 ): Promise<WorktreeValidationResult> {
   // Step 1: Empty / whitespace → treat as omitted
   if (!worktreePath || worktreePath.trim() === "") {
@@ -128,10 +134,10 @@ export async function validateWorktreePath(
   }
 
   // Step 5: Get and compare git-common-dir for parent and target
-  const parentResult = await getGitCommonDir(pi, parentCwd, WORKTREE_VALIDATION_ERRORS.PARENT_NOT_IN_GIT_REPO);
+  const parentResult = await getGitCommonDir(pi, parentCwd, WORKTREE_VALIDATION_ERRORS.PARENT_NOT_IN_GIT_REPO, onWarning);
   if (!parentResult.ok) return parentResult;
 
-  const targetResult = await getGitCommonDir(pi, realPath, WORKTREE_VALIDATION_ERRORS.NOT_IN_GIT_REPO);
+  const targetResult = await getGitCommonDir(pi, realPath, WORKTREE_VALIDATION_ERRORS.NOT_IN_GIT_REPO, onWarning);
   if (!targetResult.ok) return targetResult;
 
   // Compare common dirs — must share the same repo

package/src/ui/agent-widget.ts

@@ -14,7 +14,7 @@ import {
 import { formatMs, buildStatsParts, getDisplayName, truncateDesc, type StatsVisibility } from "./format.js";
 import type { LiveView } from "../spawn/spawn-coordinator.js";
 
-// Re-export Theme so existing consumers (model-selector, result-viewer) don't break
+// Re-export Theme so existing consumers (searchable-select, result-viewer) don't break
 export type { Theme } from "./types.js";
 
 // ---- Constants ----

package/src/ui/menu/helpers.ts

@@ -1,19 +1,19 @@
 /**
  * helpers.ts — Shared helpers for menu modules:
  * theme builders for SettingsList/SelectList, numeric validation,
- * model-option building, and a swappable delegating component.
+ * model-option building, a swappable delegating component, and a
+ * searchable pick-list submenu factory.
  */
-
 import type { Component, SettingsListTheme } from "@earendil-works/pi-tui";
-import type { ModelOption } from "../../models/model-selector.js";
+import { SearchableSelectDialog, type SelectOption } from "../searchable-select.js";
 import { parseModelKey } from "../../utils.js";
 
 /**
- * Build ModelOption[] from raw "provider/model-id" strings.
+ * Build SelectOption[] from raw "provider/model-id" strings.
  * Includes "(inherits parent)" as the first option.
  */
-export function buildModelOptions(rawOptions: string[]): ModelOption[] {
-  const items: ModelOption[] = [
+export function buildModelOptions(rawOptions: string[]): SelectOption[] {
+  const items: SelectOption[] = [
     { value: "(inherits parent)", label: "(inherits parent)", provider: "" },
   ];
 
@@ -33,7 +33,7 @@ export function buildSettingsListTheme(theme: { fg(color: string, text: string):
   return {
     label: (text, selected) => selected ? theme.fg("accent", text) : text,
     value: (text, selected) => selected ? theme.fg("accent", text) : theme.fg("muted", text),
-    description: (text) => theme.fg("muted", text),
+    description: (text) => theme.fg("dim", text),
     // Use "→ " (2 chars) to match non-selected prefix "  " (2 spaces)
     // This prevents menu items from shifting left/right when cursor moves
     cursor: theme.fg("accent", "→ "),
@@ -91,3 +91,33 @@ export function buildSelectListTheme(theme: { fg(color: string, text: string): s
   };
 }
 
+/**
+ * Build a searchable pick-list submenu backed by SearchableSelectDialog.
+ *
+ * Hides the delegator-forward-declaration dance shared by every menu that
+ * needs "type to filter, Enter to pick" over a flat option list
+ * (provider/model/type/worktree selection). onSelect may return a Component
+ * to chain into next (e.g. a numeric-input submenu); returning void leaves
+ * the submenu as-is so the caller can close it via done().
+ */
+export function createSearchableSelect(
+  items: SelectOption[],
+  callbacks: { onSelect: (value: string) => Component | void; onCancel: () => void },
+  theme: any,
+): Component {
+  let delegator: ReturnType<typeof createDelegatingComponent>;
+  const selector = new SearchableSelectDialog(
+    items,
+    null,
+    {
+      onSelect: (value) => {
+        const next = callbacks.onSelect(value);
+        if (next) delegator.setActive(next);
+      },
+      onCancel: callbacks.onCancel,
+    },
+    theme,
+  );
+  delegator = createDelegatingComponent(selector);
+  return delegator;
+}