@mrclrchtr/supi-lsp 1.16.1 → 2.0.0

package/README.md

@@ -8,68 +8,59 @@
 
 # @mrclrchtr/supi-lsp
 
-Adds Language Server Protocol support to the [pi coding agent](https://github.com/earendil-works/pi).
+Language Server Protocol runtime library for the [pi coding agent](https://github.com/earendil-works/pi).
 
-## Install
-
-```bash
-pi install npm:@mrclrchtr/supi-lsp
-```
+This is a **library-only** package — it has no pi extension surface and does not register public tools by itself. Public semantic code-intelligence behavior is exposed through `@mrclrchtr/supi-code-intelligence`'s `code_*` tools.
 
-For local development:
+## Install
 
 ```bash
-pi install ./packages/supi-lsp
+npm install @mrclrchtr/supi-lsp
 ```
 
-## What you get
-
-After install, pi gets **10 focused expert tools** for semantic language-server analysis:
+## What this package provides
 
-- `lsp_hover` — semantic type or symbol information at a given position
-- `lsp_definition` — go to definition at a known position
-- `lsp_references` — find all references to a symbol
-- `lsp_implementation` — find implementations of an interface or method
-- `lsp_document_symbols` — semantic declarations for one supported file
-- `lsp_workspace_symbols` — semantic symbol-name lookup across the project
-- `lsp_diagnostics` — current diagnostics for one file or a workspace summary
-- `lsp_rename` — semantic rename planning at a known position
-- `lsp_code_actions` — semantic fixes or refactors at a known position
-- `lsp_recover` — refresh stale diagnostics after workspace changes
-- `/lsp-status` — inspect detected servers, roots, open files, and diagnostics
+`@mrclrchtr/supi-lsp` provides the semantic substrate used by SuPi's code-intelligence stack:
 
-![LSP status overlay](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-lsp-status.png)
+- a session-scoped `SessionLspService`
+- LSP client lifecycle, transport, and workspace routing
+- diagnostics collection, stale-diagnostic recovery, and summaries
+- a shared `SemanticProvider` adapter for the workspace runtime
+- operation-aware semantic refactor planning for first-wave precise text-edit operations
 
-![LSP hover in action](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-lsp-hover.png)
+First-wave refactor mapping in the semantic provider:
 
-Coordinates use **1-based** line and character positions.
+- `rename_symbol` and legacy `rename` alias → `textDocument/rename`
+- `update_imports` → precise organize-imports/source actions only
+- `delete_dead_code` → precise quickfix/refactor-rewrite actions only
+- `rename_file` / `move_file` → explicit unavailable results for now
 
-## Automatic behavior
+The historical LSP status overlay is no longer part of this package. Substrate-owned status UX now lives in `@mrclrchtr/supi-code-intelligence` as the `/supi-ci-status` command.
 
-This package does more than register these tools:
+## Startup performance
 
-- starts detected language servers for the current project
-- rebuilds project-specific prompt guidance based on active servers
-- injects outstanding diagnostics into context before agent turns when issues exist
-- adds inline diagnostics after `write` and `edit` results
-- watches for workspace changes such as `package.json`, lockfile, `tsconfig`, generated types, and source-file edits so recovery can happen when diagnostics go stale
-- warns when configured language-server commands are missing
+Language servers start automatically when a PI session opens. By default, every server with matching source files in the project is started **concurrently** — in polyglot repos or monorepos with multiple language footprints, this parallel startup can cause a significant CPU spike.
 
-## Settings
+**To reduce startup overhead:**
 
-This package registers an **LSP** section in `/supi-settings`.
+- **Disable specific language servers** that you don't need. Only servers whose source files are detected in the project will be started. To explicitly exclude a language:
 
-Available settings:
+  ```json
+  {
+    "lsp": {
+      "servers": {
+        "python": { "enabled": false },
+        "rust": { "enabled": false }
+      }
+    }
+  }
+  ```
 
-- `enabled` — turn all LSP behavior on or off
-- `severity` — inline diagnostic threshold: `1` errors, `2` warnings, `3` info, `4` hints
-- `active` — choose which configured language servers are active; empty means all
-- `exclude` — gitignore-style patterns that suppress diagnostics for matching files
+  Add this to `.pi/supi/config.json` (project) or `~/.pi/agent/supi/config.json` (global). Only the listed language servers are disabled; all others remain active.
 
-Config lives in the standard SuPi config files:
+  > **Note:** The global `lsp.enabled` switch and `lsp.active` allowlist were removed in v0.7.0. LSP is always-on by default. Per-language `lsp.servers.<language>.enabled: false` is the only supported way to opt out. If your config still has `lsp.enabled` or `lsp.active` keys, they are ignored and a deprecation warning will appear at session start.
 
-- global: `~/.pi/agent/supi/config.json`
-- project: `.pi/supi/config.json`
+  Server discovery walks the project tree at depth 3 (skipping `node_modules`, `.git`, `.pnpm`). Every detected language server starts in parallel via `Promise.all`.
 
 ## Architecture
 
@@ -82,13 +73,14 @@ diagnostic capabilities into the shared workspace runtime.
 supi-code-runtime  ← shared contracts + workspace runtime
     ↑
 supi-lsp           ← LSP client + session-scoped service + runtime capabilities
+    ↑
+supi-code-intelligence ← public code_* tools over the semantic substrate
 ```
 
 ## Package surfaces
 
 - `@mrclrchtr/supi-lsp/api` — reusable session-scoped LSP service and related types
-- `@mrclrchtr/supi-lsp/extension` — pi extension entrypoint
-- `@mrclrchtr/supi-lsp/provider/lsp-semantic-provider` — shared SemanticProvider adapter
+- `@mrclrchtr/supi-lsp/provider/lsp-semantic-provider` — shared `SemanticProvider` adapter
 
 Example:
 
@@ -101,19 +93,15 @@ if (state.kind === "ready") {
 }
 ```
 
-`SessionLspService` methods use raw **0-based LSP positions**. The expert tools (`lsp_hover`, `lsp_definition`, etc.) keep the public 1-based coordinate UX.
+`SessionLspService` methods use raw **0-based LSP positions**. Public `code_*` tools keep the user-facing **1-based** coordinate UX.
 
 ## Source
 
-- `src/lsp.ts` — extension wiring, session lifecycle, and `/lsp-status`
+- `src/client/` — LSP client, transport, refresh, and request handling
 - `src/config/` — server config, defaults, capabilities, and exported LSP protocol types
-- `src/session/` — session state, scanning, settings registration, tree persistence, and shared service registry
-- `src/tool/tool-specs.ts` — single source of truth for the public LSP tool surface
-- `src/tool/guidance.ts` — prompt surfaces derived from tool specs
-- `src/tool/register-tools.ts` — focused tool registration driven by tool specs
-- `src/tool/service-actions.ts` — service-backed tool execution and formatting
-- `src/tool/names.ts` — stable tool name constants
-- `src/tool/overrides.ts` — read/write/edit overrides for inline diagnostics
-- `src/ui/` — custom diagnostic message rendering and the status overlay
-- `src/client/`, `src/manager/`, `src/diagnostics/` — runtime engine subsystems
+- `src/diagnostics/` — stale diagnostics, suppression diagnostics, and workspace sentinels
+- `src/manager/` — manager lifecycle, routing, diagnostics, and recovery helpers
+- `src/provider/lsp-semantic-provider.ts` — shared `SemanticProvider` adapter
+- `src/session/` — service registry, runtime registration, scanner, and controller logic
 - `src/api.ts` — reusable developer-facing surface
+- `src/index.ts` — package-root re-export surface

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.16.1",
+  "version": "2.0.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,7 @@
     "settings",
     "configuration"
   ],
+  "type": "module",
   "files": [
     "src/**/*.ts",
     "!__tests__"
@@ -49,12 +50,14 @@
   },
   "main": "src/api.ts",
   "exports": {
+    "./abort-utils": "./src/abort-utils.ts",
     "./api": "./src/api.ts",
     "./config": "./src/config.ts",
     "./context": "./src/context.ts",
     "./debug": "./src/debug-registry.ts",
     "./footer-registry": "./src/footer-registry.ts",
     "./llm": "./src/llm.ts",
+    "./model-selection": "./src/model-selection.ts",
     "./package.json": "./package.json",
     "./path": "./src/path.ts",
     "./report": "./src/report.ts",
@@ -63,6 +66,8 @@
     "./session": "./src/session.ts",
     "./settings": "./src/settings.ts",
     "./settings-ui": "./src/settings-ui.ts",
+    "./spinner-frames": "./src/spinner-frames.ts",
+    "./status-spinner": "./src/status-spinner.ts",
     "./terminal": "./src/terminal.ts",
     "./tool-framework": "./src/tool-framework.ts",
     "./types": "./src/types.ts"

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/abort-utils.ts

@@ -0,0 +1,31 @@
+/**
+ * Abort controller/signal utility helpers.
+ *
+ * @module
+ */
+
+/**
+ * Combine a caller-provided abort controller with a generation timeout signal.
+ *
+ * Returns the combined signal and a cleanup function that removes both
+ * event listeners. Callers must invoke cleanup in a `finally` block
+ * to avoid listener leaks.
+ */
+export function combineAbortSignals(
+  abort: AbortController,
+  timeoutMs: number,
+): { signal: AbortSignal; cleanup: () => void } {
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  const combinedController = new AbortController();
+  const onAbort = () => combinedController.abort();
+  abort.signal.addEventListener("abort", onAbort, { once: true });
+  timeoutSignal.addEventListener("abort", onAbort, { once: true });
+
+  return {
+    signal: combinedController.signal,
+    cleanup: () => {
+      abort.signal.removeEventListener("abort", onAbort);
+      timeoutSignal.removeEventListener("abort", onAbort);
+    },
+  };
+}

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -6,6 +6,8 @@
 // For lighter imports, use one of the domain subpaths directly
 // (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
 
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./abort-utils.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
@@ -17,6 +19,8 @@ export * from "./footer-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./llm.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./model-selection.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./path.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./project.ts";
@@ -29,6 +33,10 @@ export * from "./settings.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./settings-ui.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./spinner-frames.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./status-spinner.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./terminal.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./tool-framework.ts";

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/config/config-settings.ts

@@ -5,6 +5,7 @@
 // to enable auto-generated persistChange. When all items have a configType,
 // the persistChange callback can be omitted.
 
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { SettingItem } from "@earendil-works/pi-tui";
 import type { SettingsScope } from "../settings/settings-registry.ts";
 import { registerSettings } from "../settings/settings-registry.ts";
@@ -60,7 +61,12 @@ export interface ConfigSettingsOptions<T> {
    * persistChange handling. When ALL items declare a configType,
    * the `persistChange` callback can be omitted.
    */
-  buildItems: (settings: T, scope: SettingsScope, cwd: string) => ConfigSettingItem[];
+  buildItems: (
+    settings: T,
+    scope: SettingsScope,
+    cwd: string,
+    ctx?: ExtensionContext,
+  ) => ConfigSettingItem[];
   /**
    * Handle a settings change with scoped persistence helpers.
    *
@@ -141,12 +147,12 @@ export function registerConfigSettings<T>(options: ConfigSettingsOptions<T>): vo
   registerSettings({
     id: options.id,
     label: options.label,
-    loadValues: (scope, cwd) => {
+    loadValues: (scope, cwd, ctx) => {
       const settings = loadSupiConfigForScope(options.section, cwd, options.defaults, {
         scope,
         homeDir: options.homeDir,
       });
-      const items = options.buildItems(settings, scope, cwd);
+      const items = options.buildItems(settings, scope, cwd, ctx);
       cachedItems = items;
       return items;
     },
@@ -173,7 +179,7 @@ export function registerConfigSettings<T>(options: ConfigSettingsOptions<T>): vo
       }
 
       // Auto-generate when all items are declarative
-      const items = cachedItems ?? options.buildItems(options.defaults, scope, cwd);
+      const items = cachedItems ?? options.buildItems(options.defaults, scope, cwd, undefined);
       if (areAllItemsDeclarative(items)) {
         autoPersistChange(settingId, value, helpers, items);
       }

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/config.ts

@@ -1,6 +1,7 @@
 // supi-core config domain — config loading and config-settings helpers.
 export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
+  loadSectionConfig,
   loadSupiConfig,
   loadSupiConfigForScope,
   readJsonFile,

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/footer-registry.ts

@@ -8,7 +8,7 @@
 import { createRegistry } from "./registry-utils.ts";
 
 /** Where the contribution should appear in the footer. */
-export type FooterPlacement = "stats" | "status";
+export type FooterPlacement = "stats" | "stats-end" | "status";
 
 /** A single footer contribution registered by an extension. */
 export interface FooterContribution {

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -6,6 +6,8 @@
 // For lighter imports, use one of the domain subpaths directly
 // (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
 
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./abort-utils.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
@@ -15,6 +17,8 @@ export * from "./debug-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./footer-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./model-selection.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./path.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./project.ts";
@@ -27,6 +31,8 @@ export * from "./settings.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./settings-ui.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./status-spinner.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./terminal.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./tool-framework.ts";

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/model-selection.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared model-selection helpers for SuPi extensions.
+ *
+ * Provides scoped-model listing using PI's `enabledModels` configuration,
+ * matching the same semantics as the `@mrclrchtr/supi-review` model picker.
+ *
+ * @module
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import { type ExtensionContext, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/** A selectable model entry with display metadata. */
+export interface ModelSelection {
+  /** Canonical `provider/model-id` string. */
+  canonicalId: string;
+  /** Provider name, e.g. `"anthropic"`. */
+  provider: string;
+  /** Model id, e.g. `"claude-sonnet-4-5"`. */
+  id: string;
+  // biome-ignore lint/suspicious/noExplicitAny: Model<any> is pi's canonical type
+  model: Model<any>;
+  /** Human-readable label (model name or canonicalId). */
+  label: string;
+  /** Optional description (canonicalId when different from label). */
+  description?: string;
+  /** Whether this model is the current session model. */
+  isCurrent: boolean;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+/** Build the canonical `provider/model-id` string. */
+export function toCanonicalModelId(
+  model: Pick<NonNullable<ExtensionContext["model"]>, "provider" | "id">,
+): string {
+  return `${model.provider}/${model.id}`;
+}
+
+/**
+ * List selectable models from PI's scoped model configuration.
+ *
+ * Only models that match the configured `enabledModels` patterns are offered.
+ * The current session model is included only when it is inside that scoped set.
+ * Returns an empty array when no scoped model patterns are configured.
+ */
+export function getSelectableModels(
+  ctx: Pick<ExtensionContext, "cwd" | "modelRegistry" | "model">,
+  enabledModelPatterns = SettingsManager.create(ctx.cwd).getEnabledModels(),
+): ModelSelection[] {
+  if (!enabledModelPatterns || enabledModelPatterns.length === 0) {
+    return [];
+  }
+
+  const byCanonicalId = new Map<string, ModelSelection>();
+  const availableModels = filterByEnabledModels(
+    enabledModelPatterns,
+    ctx.modelRegistry.getAvailable(),
+  );
+
+  const addModel = (
+    // biome-ignore lint/suspicious/noExplicitAny: Model<any> is pi's canonical type
+    model: Model<any>,
+    isCurrent: boolean,
+  ) => {
+    const canonicalId = toCanonicalModelId(model);
+    const existing = byCanonicalId.get(canonicalId);
+    if (existing) {
+      if (isCurrent) existing.isCurrent = true;
+      return;
+    }
+
+    byCanonicalId.set(canonicalId, {
+      canonicalId,
+      provider: model.provider,
+      id: model.id,
+      model,
+      label: model.name ?? canonicalId,
+      description: canonicalId,
+      isCurrent,
+    });
+  };
+
+  if (ctx.model && matchModelPatterns(ctx.model, enabledModelPatterns)) {
+    addModel(ctx.model, true);
+  }
+
+  for (const model of availableModels) {
+    addModel(
+      model,
+      ctx.model ? toCanonicalModelId(model) === toCanonicalModelId(ctx.model) : false,
+    );
+  }
+
+  return Array.from(byCanonicalId.values()).sort((a, b) => {
+    if (a.isCurrent !== b.isCurrent) return a.isCurrent ? -1 : 1;
+    return a.canonicalId.localeCompare(b.canonicalId);
+  });
+}
+
+// ── Private helpers ────────────────────────────────────────────────────────
+
+function filterByEnabledModels<T extends { provider: string; id: string }>(
+  patterns: string[],
+  models: T[],
+): T[] {
+  return models.filter((model) => matchModelPatterns(model, patterns));
+}
+
+function matchModelPatterns(model: { provider: string; id: string }, patterns: string[]): boolean {
+  return patterns.some((pattern) => matchModelPattern(model, pattern));
+}
+
+function matchModelPattern(model: { provider: string; id: string }, pattern: string): boolean {
+  const canonicalId = `${model.provider}/${model.id}`;
+  if (pattern.includes("/")) {
+    return simpleGlobMatch(canonicalId, pattern);
+  }
+  return simpleGlobMatch(model.id, pattern) || simpleGlobMatch(canonicalId, pattern);
+}
+
+function simpleGlobMatch(text: string, pattern: string): boolean {
+  if (!pattern.includes("*") && !pattern.includes("?")) {
+    return text.toLowerCase() === pattern.toLowerCase();
+  }
+
+  const regex = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*/g, ".*")
+    .replace(/\?/g, ".");
+  return new RegExp(`^${regex}$`, "i").test(text);
+}

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/settings/settings-registry.ts

@@ -3,6 +3,7 @@
 // Extensions declare their settings via `registerSettings()` during their
 // factory function. The generic settings UI reads them via `getRegisteredSettings()`.
 
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { SettingItem } from "@earendil-works/pi-tui";
 import { createRegistry } from "../registry-utils.ts";
 
@@ -14,9 +15,15 @@ export interface SettingsSection {
   /** Human-readable label shown in the UI */
   label: string;
   /** Load current SettingItem[] for the given scope */
-  loadValues: (scope: SettingsScope, cwd: string) => SettingItem[];
+  loadValues: (scope: SettingsScope, cwd: string, ctx?: ExtensionContext) => SettingItem[];
   /** Persist a change back to config */
-  persistChange: (scope: SettingsScope, cwd: string, settingId: string, value: string) => void;
+  persistChange: (
+    scope: SettingsScope,
+    cwd: string,
+    settingId: string,
+    value: string,
+    ctx?: ExtensionContext,
+  ) => void;
 }
 
 const registry = createRegistry<SettingsSection>("settings-registry");

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/settings/settings-ui.ts

@@ -10,10 +10,14 @@ import {
   Input,
   Key,
   matchesKey,
+  type SelectItem,
+  SelectList,
+  type SelectListTheme,
   type SettingItem,
   SettingsList,
   Text,
 } from "@earendil-works/pi-tui";
+import { getSelectableModels } from "../model-selection.ts";
 import {
   getRegisteredSettings,
   type SettingsScope,
@@ -84,10 +88,11 @@ function buildFlatItems(
   sections: SettingsSection[],
   scope: SettingsScope,
   cwd: string,
+  ctx?: ExtensionContext,
 ): SettingItem[] {
   const items: SettingItem[] = [];
   for (const section of sections) {
-    const sectionItems = section.loadValues(scope, cwd);
+    const sectionItems = section.loadValues(scope, cwd, ctx);
     for (const item of sectionItems) {
       items.push({
         ...item,
@@ -115,6 +120,7 @@ function findSectionAndId(
 // ── Component ────────────────────────────────────────────────
 
 interface SettingsOverlayDeps {
+  ctx: ExtensionContext;
   state: OverlayState;
   container: Container;
   settingsList: SettingsList | null;
@@ -125,15 +131,21 @@ interface SettingsOverlayDeps {
 
 function createSettingsList(deps: SettingsOverlayDeps): SettingsList {
   const sections = getRegisteredSettings();
-  const items = buildFlatItems(sections, deps.state.scope, deps.state.cwd);
+  const items = buildFlatItems(sections, deps.state.scope, deps.state.cwd, deps.ctx);
   const onChange = (flatId: string, newValue: string) => {
     const found = findSectionAndId(sections, flatId);
     if (found) {
-      found.section.persistChange(deps.state.scope, deps.state.cwd, found.itemId, newValue);
+      found.section.persistChange(
+        deps.state.scope,
+        deps.state.cwd,
+        found.itemId,
+        newValue,
+        deps.ctx,
+      );
     }
     // Re-read all values to reflect persisted changes, but keep the list
     // instance (and its selectedIndex) intact.
-    const updatedItems = buildFlatItems(sections, deps.state.scope, deps.state.cwd);
+    const updatedItems = buildFlatItems(sections, deps.state.scope, deps.state.cwd, deps.ctx);
     for (const updated of updatedItems) {
       const existing = items.find((i) => i.id === updated.id);
       if (existing && existing.currentValue !== updated.currentValue) {
@@ -182,6 +194,98 @@ function handleScopeToggle(deps: SettingsOverlayDeps): void {
   deps.tui.requestRender();
 }
 
+/** Minimal SelectList theme — uses identity so the parent SettingsList provides styling context. */
+const PASSTHROUGH_THEME: SelectListTheme = {
+  selectedPrefix: (text) => `› ${text}`,
+  selectedText: (text) => text,
+  description: (text) => text,
+  scrollInfo: (text) => text,
+  noMatch: (text) => text,
+};
+
+/**
+ * Create a model picker submenu for settings.
+ *
+ * Shows a scrollable list of selectable models from the scoped model set,
+ * with the current session model annotated `[current]`.  The first entry is
+ * always `"disabled"`.
+ *
+ * @param currentValue - Currently configured canonical model id or `"disabled"`.
+ * @param done - Callback invoked with the selected value, or undefined on cancel.
+ * @param ctx - Extension context for model listing.  When undefined, only
+ *   `"disabled"` is offered.
+ */
+export function createModelPickerSubmenu(
+  currentValue: string,
+  done: (selectedValue?: string) => void,
+  ctx?: ExtensionContext,
+): {
+  render: (width: number) => string[];
+  invalidate: () => void;
+  handleInput: (data: string) => boolean;
+} {
+  const items = buildModelItems(ctx);
+
+  const initialIndex =
+    currentValue === "disabled"
+      ? 0
+      : Math.max(
+          0,
+          items.findIndex((item) => item.value === currentValue),
+        );
+
+  const container = new Container();
+  container.addChild(new Text("  Select suggestion model", 1, 0));
+  container.addChild(new Text("", 1, 0));
+
+  const selectList = new SelectList(items, Math.min(items.length, 15), PASSTHROUGH_THEME);
+
+  if (initialIndex >= 0) {
+    selectList.setSelectedIndex(initialIndex);
+  }
+
+  selectList.onSelect = (item) => done(item.value);
+  selectList.onCancel = () => done();
+
+  container.addChild(selectList);
+  container.addChild(new Text("  ↑↓ navigate • enter select • esc cancel", 1, 0));
+
+  return {
+    render: (width: number) => container.render(width),
+    invalidate: () => container.invalidate(),
+    handleInput: (data: string) => {
+      selectList.handleInput(data);
+      return true;
+    },
+  };
+}
+
+/** Build selectable model items with "disabled" first. */
+function buildModelItems(ctx?: ExtensionContext): SelectItem[] {
+  const items: SelectItem[] = [
+    {
+      value: "disabled",
+      label: "disabled",
+      description: "No prompt suggestions",
+    },
+  ];
+
+  if (!ctx) return items;
+
+  const models = getSelectableModels(ctx);
+
+  for (const model of models) {
+    const suffix = model.isCurrent ? "  [current]" : "";
+    items.push({
+      value: model.canonicalId,
+      label: `${model.canonicalId}${suffix}`,
+      description: model.label !== model.canonicalId ? model.label : undefined,
+    });
+  }
+
+  return items;
+}
+
 // ── Entry point ──────────────────────────────────────────────
 
 export function openSettingsOverlay(ctx: ExtensionContext): void {
@@ -196,6 +300,7 @@ export function openSettingsOverlay(ctx: ExtensionContext): void {
     const container = new Container();
 
     const deps: SettingsOverlayDeps = {
+      ctx,
       state,
       container,
       settingsList: null,