pi-better-model-select 0.1.4 → 0.2.0

package/README.md

@@ -1,12 +1,6 @@
 # pi-better-model-select
 
-A searchable, usage-ranked model picker for [pi](https://pi.dev).
-
-`/bms` opens the effective model list from `models.json` plus the optional BMS-owned
-`models.bms.json` overlay, sorted by how often you pick each model. Start
-typing to filter; press enter to switch the session to the highlighted model.
-Add, update and delete live on ctrl-chords so plain keystrokes always go to the
-search box.
+A searchable model picker for [Pi](https://pi.dev). Switch models, edit model definitions, and save default models and thinking effort. Models you pick most often appear first.
 
 ## Install
 
@@ -14,121 +8,82 @@ search box.
 pi install npm:pi-better-model-select
 ```
 
-If you installed the package under its old name, migrate with:
-
-```bash
-pi remove npm:@msenebald/better-model-select
-pi install npm:pi-better-model-select
-```
-
-## Commands
-
-| Command    | What it does                                        |
-| ---------- | --------------------------------------------------- |
-| `/bms`     | Open the searchable, usage-ranked picker            |
-| `/bms-add` | Jump straight to the add-a-model flow               |
+Run `/bms`, type to filter by name, model ID, or provider, then press Enter to switch models for the current session.
 
-## Keys
+## Commands and shortcuts
 
-| Key        | Action                                              |
-| ---------- | --------------------------------------------------- |
-| `↑` `↓`    | Move through the list                               |
-| *type*     | Fuzzy filter by display name, model id or provider  |
-| `enter`    | Load the highlighted model                          |
-| `ctrl+a`   | Add a model                                         |
-| `ctrl+u`   | Update the highlighted model                        |
-| `ctrl+x`   | Delete the highlighted model                        |
-| `ctrl+o`   | Open BMS options                                    |
-| `ctrl+r`   | Reset usage statistics                              |
-| `esc`      | Close                                               |
+| Command | Action |
+| --- | --- |
+| `/bms` | Open the model picker |
+| `/bms-add` | Add a model |
+| `/bms-defaults` | Configure Pi and subagent defaults |
 
-## Options
+Inside `/bms`:
 
-Press `ctrl+o` in `/bms` to configure:
+| Key | Action |
+| --- | --- |
+| ↑ / ↓ | Move through models |
+| Enter | Use the selected model for this session |
+| Ctrl+D | Choose effort, save as the Pi default, and use it now |
+| Ctrl+G | Open the defaults menu |
+| Ctrl+A / Ctrl+U / Ctrl+X | Add / update / delete a model |
+| Ctrl+O | Set write mode and provider filters |
+| Ctrl+R | Reset usage ranking |
+| Esc | Close |
 
-- **Write mode.** Overlay mode keeps Pi's `models.json` unchanged and stores
-  BMS edits in `models.bms.json`. Direct mode writes add, update and delete
-  operations to `models.json`.
-- **Provider filters.** Enable or disable providers in the `/bms` model list.
-  These filters do not change Pi's `/model` picker or either model file.
+The picker marks the active model with `[current]` and the saved startup model with `[default]`. Only Enter selections count toward usage ranking.
 
-BMS stores these choices in `<agent-dir>/bms-settings.json`.
+## Default models and effort
 
-## Ranking
+New in BMS `0.2.0`: save a model and thinking effort for Pi, a subagent fallback, or an individual agent role.
 
-Every model loaded through `/bms` increments a counter in
-`<agent-dir>/bms-usage.json`. The list sorts by count, then by most recent use,
-then alphabetically — so an unused config starts in plain alphabetical order and
-drifts toward your habits.
+- Use Ctrl+D in `/bms` for the main Pi default.
+- Use `/bms-defaults` for all defaults. The menu starts in user scope; select the scope row to switch to a trusted project's settings.
+- Agent model and effort overrides are independent. You can inherit the parent model while choosing a different effort.
 
-Only `/bms` selections count. Switching via `/model`, `ctrl+p` cycling, or a
-session restore does not, which keeps the ranking a record of deliberate choices
-rather than of how often you restart pi.
+Removing an override restores the agent's own definition and fallback rules. Effort `off` is explicit, not inheritance. The menu shows saved settings and their sources, not running-child state.
 
-Stats for models that disappear from the effective configuration are pruned
-when the picker opens. `ctrl+r` clears everything.
+Run `/reload` after changing agent defaults or per-model effort preferences. Existing children stay unchanged. Test Pi startup defaults in a fresh session, since resumed sessions restore their recorded model and effort.
 
-## Metadata discovery
+### Optional pi-subagents integration
 
-When adding or updating, the extension tries to fill in context window, output
-cap, reasoning support and input modalities from, in order:
+[pi-subagents](https://github.com/nicobailon/pi-subagents) is a separate extension. Install it only if you want subagents:
 
-1. `GET {baseUrl}/model/info` — LiteLLM proxies
-2. `GET {baseUrl}/models/{id}` — OpenAI-style, plus proxy-specific fields
-3. The public LiteLLM model cost map on GitHub
+```bash
+pi install npm:pi-subagents
+```
 
-Each step is best-effort. A plain OpenAI-compatible endpoint usually yields
-nothing from steps 1 and 2, and the flow falls back to name-based heuristics
-with editable defaults. Choose the default write mode from `ctrl+o` in `/bms`. Overlay mode writes to
-`models.bms.json`; direct mode edits Pi's `models.json`. The selected file is re-read immediately before the
-write so a concurrent edit in another pi session is not clobbered.
+BMS discovers its agent roles and edits their saved model and effort defaults. It does not install `pi-subagents` automatically. External runner roles are read-only because their model settings belong to the runner.
 
-## Paths
+Discovery has now been checked with **pi-subagents `0.82.1`**, updated from the original `0.79.0` test. BMS handles the newer bundled entry-point layout. The adapter still uses internal modules, so future package changes may require an update. If discovery fails, **Agent discovery details** shows the error. Pi defaults work without this integration.
 
-All files resolve through pi's `getAgentDir()`, so `PI_CODING_AGENT_DIR` and
-rebranded distributions work without special handling:
+### Supported effort levels
 
-- `<agent-dir>/models.json` is Pi's documented compatible-endpoint configuration.
-- `<agent-dir>/models.bms.json` is the optional overlay owned and loaded by BMS.
-- `<agent-dir>/bms-settings.json` stores the write mode and provider filters.
-- `<agent-dir>/bms-usage.json` stores selection counters.
+BMS uses provider-reported effort lists when available and Pi's capability restrictions where supplied. Otherwise it offers Pi's standard levels, marked as provider support unverified:
 
-Pi does not load `models.bms.json` itself. In overlay mode, BMS merges it over
-`models.json` by provider and model id, then registers the merged providers
-through Pi's extension API. If the same model exists in both files, fields from
-`models.bms.json` win. Existing `models.local.json` overlays from BMS 0.1.x are
-renamed to `models.bms.json` automatically.
+```text
+off · minimal · low · medium · high · xhigh · max
+```
 
-Deleting a model that exists only in `models.json` leaves that file untouched.
-BMS writes `{ "id": "...", "bmsDeleted": true }` to the overlay instead.
-This tombstone keeps generated or externally managed model entries hidden across
-restarts. Delete it from `models.bms.json` to restore the inherited model.
+Add/update also lets you edit supported levels and set a per-model preferred effort. These hints do not change Pi's provider adapters. If Pi clamps an effort, BMS asks before saving the applied level. No paid model probes are made.
 
-Writes are atomic using a temporary file and rename, so an interrupted write
-cannot truncate either configuration file.
+## Where changes are saved
 
-## Development
+Ctrl+O selects the model write mode:
 
-```bash
-npm install
-npm run typecheck
-node --experimental-strip-types --test extensions/lib/picker.test.ts
-pi -e . -p "say OK"      # load the extension without installing it
-```
+| Mode | Behavior |
+| --- | --- |
+| Overlay, the default | Save model edits in `models.bms.json`; leave `models.json` unchanged |
+| Direct | Write model edits to Pi's `models.json` |
 
-## Publishing
+Defaults always go into native Pi `settings.json`, regardless of write mode. User files normally live in `~/.pi/agent`; project defaults use `.pi/settings.json`. BMS respects `PI_CODING_AGENT_DIR` and shows the selected settings paths.
 
-Set the new version in `package.json` and `package-lock.json`, then run:
+Provider filters hide entries only in `/bms`, not Pi's `/model` picker. Default-assignment menus also include authenticated Pi registry models.
 
-```bash
-make publish
-```
+## Further documentation
 
-The target runs the full package gate, checks npm authentication, opens npm's
-browser login when needed, skips the upload if that exact version already
-exists, publishes the public scoped package, and waits for npm to expose the
-new version. npm can take several minutes to process a package. If verification
-times out, rerun `make verify-publish`; do not publish the same version again.
+- [Configuration reference](https://g.han.zone/msenebald/pi-better-model-select/src/branch/main/docs/configuration.md): file paths, precedence, overlays, metadata, and integration limits.
+- [Development and testing](https://g.han.zone/msenebald/pi-better-model-select/src/branch/main/docs/development.md): local loading, isolated tests, checks, and publishing.
 
 ## License
 

package/docs/configuration.md

@@ -0,0 +1,105 @@
+# Configuration reference
+
+See the [README](../README.md) for installation and shortcuts.
+
+## Files
+
+`<agent-dir>` is normally `~/.pi/agent`. BMS uses Pi's `getAgentDir()`, so it respects `PI_CODING_AGENT_DIR`.
+
+| File | Contents |
+| --- | --- |
+| `<agent-dir>/models.json` | Pi model definitions |
+| `<agent-dir>/models.bms.json` | BMS model overlay |
+| `<agent-dir>/bms-settings.json` | Write mode and provider filters |
+| `<agent-dir>/bms-usage.json` | Selection counts and recency |
+| `<agent-dir>/bms-model-metadata.json` | Effort capability hints and their source |
+| `<agent-dir>/settings.json` | User defaults and per-model effort preferences |
+| `<project>/.pi/settings.json` | Project defaults |
+
+## Model write modes
+
+Choose the write mode through Ctrl+O in `/bms`.
+
+- Overlay mode, the default, leaves `models.json` unchanged and writes edits to `models.bms.json`.
+- Direct mode writes add, update, and delete operations to `models.json`.
+
+Pi does not load the overlay itself. BMS merges it over `models.json` by provider and model ID, then registers the merged providers through Pi's extension API. Overlay fields win for duplicate models. BMS automatically renames its old `models.local.json` overlay to `models.bms.json`.
+
+Deleting an inherited model in overlay mode writes a tombstone:
+
+```json
+{ "id": "model-id", "bmsDeleted": true }
+```
+
+Remove that entry from `models.bms.json` to restore the inherited model. Model files are re-read before writes and saved through a temporary file and rename. This does not provide a shared lock against other applications.
+
+Provider filters affect only `/bms`. They do not change Pi's `/model` picker or model definitions. Default-assignment menus ignore the filters and also include authenticated Pi registry models.
+
+## Defaults and precedence
+
+Default settings are independent of the model write mode.
+
+| Setting | Native Pi settings field |
+| --- | --- |
+| Pi model | `defaultProvider`, `defaultModel` |
+| Pi effort | `defaultThinkingLevel` |
+| Per-model preferred effort | `modelThinkingLevels["provider/model"]` |
+| Subagent fallback | `subagents.defaultModel`, `subagents.defaultThinking` |
+| Role override | `subagents.agentOverrides.<name>.model` and `.thinking` |
+
+The defaults menu starts in user scope. Project scope requires a trusted project. Pi defaults use the working directory's `.pi/settings.json`. Agent defaults use the project root resolved by `pi-subagents`, which may differ in nested repositories. The menu shows the paths.
+
+Project settings and provider-specific role overrides may take precedence. BMS shows override sources and warns when a saved Pi default would be shadowed. Saving a Pi default removes the selected model's per-model effort preference in the same scope, so it cannot override the new default.
+
+For agent roles:
+
+- **Inherit parent model** writes `model: "inherit"`.
+- **Remove model override** restores agent-definition and fallback rules.
+- **Automatic** or **Remove effort override** removes that scope's effort preference. It does not force parent effort inheritance. `pi-subagents` has no separate persistent setting for that.
+- **Off** is an explicit effort level, not inheritance.
+
+Changing the Pi default also switches the main session. Subagent assignments do not switch it or increment usage counts. Cancelled or failed model switches leave saved defaults unchanged. If Pi clamps an effort, BMS asks before saving the applied level.
+
+Run `/reload` after changing agent defaults or per-model effort preferences. Running children keep their existing configuration, and subagent model-scope policies still apply at launch. Resumed Pi sessions restore their recorded model and effort. Test startup defaults in a fresh session without CLI model or effort overrides.
+
+Settings writes preserve unrelated fields, reject malformed JSON, and use atomic rename. A `.bms-lock` file serializes BMS settings writers only. After a crash, remove a stale lock only after checking that no BMS writer is active. Updates across model definitions, settings, and capability metadata are not a multi-file transaction.
+
+## Effort levels and metadata
+
+BMS uses explicit provider effort lists when supplied, then native Pi capability restrictions where available. Otherwise it offers Pi's standard levels and labels provider support as unverified:
+
+```text
+off, minimal, low, medium, high, xhigh, max
+```
+
+The metadata adapter recognizes `supported_reasoning_efforts`, `supported_thinking_levels`, and `reasoning_efforts` containing Pi effort names. A generic reasoning flag or `supported_parameters: ["reasoning_effort"]` does not specify supported levels.
+
+Add/update lets you edit the available levels and choose an optional per-model preferred effort. Non-reasoning models offer only `off`; correct the reasoning flag first if the endpoint metadata is wrong. BMS makes no paid model probes.
+
+Capability hints guide menus. They do not change provider adapters or prove an endpoint honors a level. Pi may clamp effort or map it to a token budget. Provider errors remain visible rather than triggering a model fallback.
+
+BMS blocks capability edits that conflict with directly pinned defaults in the inspected user/project settings. Update those defaults first. This check does not audit every inherited agent definition or settings file elsewhere on disk.
+
+When adding or updating models, BMS tries these metadata sources in order:
+
+1. `GET {baseUrl}/model/info` for LiteLLM proxies.
+2. `GET {baseUrl}/models/{id}` for OpenAI-style and proxy-specific fields.
+3. The public LiteLLM model cost map on GitHub.
+
+These requests are best-effort. Missing metadata falls back to name-based heuristics and editable defaults for context window, output limit, reasoning support, and input types.
+
+## Optional pi-subagents integration
+
+[pi-subagents](https://github.com/nicobailon/pi-subagents) is a separate Pi extension. BMS configures its saved model and effort defaults; it does not install it or launch agents to discover roles.
+
+Discovery was originally tested with `0.79.0` and has now been checked against `0.82.1`. BMS supports both the older root entry point and the newer `bundle/index.js` package layout. Discovery still uses internal discovery/runtime modules because the public agents API does not expose role discovery. Future incompatible versions may need an adapter update.
+
+The package must be resolvable from BMS or `<agent-dir>/npm/node_modules`. Discovery includes built-in, package, user, project, and runtime roles when supported by the installed API. Untrusted project agents and settings are excluded. External runner roles are shown read-only; configure their models through the runner's own settings.
+
+If discovery fails, the menu offers **Agent discovery details** with the error. Main Pi defaults remain usable.
+
+## Usage ranking
+
+Only models loaded with Enter in `/bms` count toward ranking. BMS sorts by selection count, then recency, then alphabetically. Default assignments, `/model`, model cycling, and session restores do not count.
+
+BMS prunes statistics for models missing from the effective configuration when the picker opens. Ctrl+R clears all usage statistics.

package/docs/development.md

@@ -0,0 +1,104 @@
+# Development and testing
+
+Run these commands from the repository checkout:
+
+```bash
+npm ci
+npm run gate
+npm run test:smoke  # optional: installed Pi, Python 3 and a POSIX PTY required
+pi --no-extensions -e ./extensions/bms.ts  # temporary load; no install or publish
+```
+
+## Temporary local testing
+
+Use a fresh terminal in this checkout. The command above disables installed
+extensions to avoid loading two copies of BMS. It still uses your real Pi settings,
+so default changes persist. For an isolated test, use a scratch agent directory
+and project directory instead:
+
+```bash
+REPO="$PWD"
+SANDBOX="$(mktemp -d -t bms-local)"
+mkdir -p "$SANDBOX/agent" "$SANDBOX/project/.pi"
+printf '{}\n' > "$SANDBOX/project/.pi/settings.json"
+# Optional: copy your model definitions. Review literal credentials in this file.
+cp "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/models.json" "$SANDBOX/agent/models.json"
+cd "$SANDBOX/project"
+PI_CODING_AGENT_DIR="$SANDBOX/agent" pi --no-extensions -e "$REPO/extensions/bms.ts"
+```
+
+Provider API-key environment variables remain available. The isolated directory
+has no login credentials; use `/login` there if needed. Do not commit credentials
+or scratch settings. To test agent roles, load your installed pi-subagents entry
+explicitly with another `-e` and make the package resolvable in the scratch agent's
+`npm/node_modules`, or use your real agent directory with backups. For the standard
+Pi npm install layout with pi-subagents 0.82.1, before launching:
+
+```bash
+REAL_AGENT="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
+ln -s "$REAL_AGENT/npm" "$SANDBOX/agent/npm"
+PI_CODING_AGENT_DIR="$SANDBOX/agent" pi --no-extensions \
+  -e "$REPO/extensions/bms.ts" -e "$REAL_AGENT/npm/node_modules/pi-subagents/bundle/index.js"
+```
+
+This symlinks installed package code, not your settings or auth files. Do not run
+package installation/update commands in this sandbox, since they would modify the
+shared package directory.
+
+The automated `npm run test:smoke` uses an unreachable dummy endpoint and
+throwaway settings. It checks command registration, the real TUI default-save
+flow, the defaults shortcut, and restoration in a fresh Pi process. No model
+prompts are sent. The regular test suite uses mocked provider metadata and UI.
+
+Manual checks:
+
+1. `/bms`: filter and use Enter. Only the current session should change.
+2. Reopen `/bms`, press Ctrl+D, choose effort and confirm. Check both markers,
+   the footer effort, and the scratch `agent/settings.json`.
+3. Cancel the effort dialog and confirmation. Neither should change defaults.
+4. `/bms-defaults`: select a Pi model, then select the same model again to change
+   only its default effort. Test user and trusted-project scope.
+5. Configure a subagent fallback and a role model/effort. Confirm the parent
+   session stays unchanged. Test explicit model inheritance and removal of each
+   override, then `/reload` and inspect `/subagents-models reviewer`.
+6. Add/update a model. Check provider-reported effort lists, the unverified Pi
+   fallback, manual levels, and the preferred effort. Try removing a level that
+   a directly pinned default uses; BMS should block the conflicting edit.
+7. Exit and start a fresh Pi session with the same scratch paths. Confirm startup
+   model and effort. Do not use `--continue`, `--resume`, or CLI model/effort overrides.
+8. Test a narrow terminal and verify the list, wrapped hints, and search still work.
+
+Quit Pi before deleting the sandbox with `rm -rf "$SANDBOX"`, then return to the
+checkout with `cd "$REPO"`. The test commands do not publish or install BMS.
+
+## Publishing
+
+Publish from `main` after the feature PR is reviewed and merged. Do not publish from the unmerged feature branch.
+
+For the current `0.2.0` release:
+
+```bash
+git switch main
+git pull --ff-only origin main
+npm ci
+npm run gate
+npm run test:smoke
+npm pack --dry-run
+```
+
+Check that the working tree is clean, both package manifests say `0.2.0`, and the package contains `README.md`, `docs/configuration.md`, and `docs/development.md`. Tests and the internal PR draft must not be included. The README links point to `main`, so merge the documentation before publishing.
+
+Then publish to the public npm registry:
+
+```bash
+make publish
+```
+
+For later releases, update both manifests with `npm version <version> --no-git-tag-version`, and include that change in a reviewed PR before publishing.
+
+The target runs the full package gate, checks npm authentication, opens npm's
+browser login when needed, skips the upload if that exact version already
+exists, publishes the public package, and waits for npm to expose the
+new version. npm can take several minutes to process a package. If verification
+times out, rerun `make verify-publish`; do not publish the same version again.
+

package/extensions/bms.ts

@@ -4,10 +4,12 @@
 // with add / update / delete wired to ctrl-chords so plain typing always goes
 // to the search box.
 
-import { DynamicBorder, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Container, Text } from "@earendil-works/pi-tui";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { defaultsFlow, piPreference, setMainDefault } from "./lib/defaults.ts";
+import { readSettings, settingsPath } from "./lib/defaults-store.ts";
+import { pickerDialog } from "./lib/picker-dialog.ts";
 import { addFlow, deleteFlow, updateFlow, type FlowCtx } from "./lib/flows.ts";
-import { ModelPicker, rankModels, type PickerAction } from "./lib/picker.ts";
+import { rankModels } from "./lib/picker.ts";
 import {
   loadConfig,
   loadConfigFile,
@@ -165,6 +167,23 @@ export default function (pi: ExtensionAPI) {
     syncLocalConfig(pi, ctx);
   });
 
+  const report = async (ctx: any, action: () => Promise<void>) => {
+    try { await action(); } catch (error) { ctx.ui.notify(`BMS: ${error}`, "error"); }
+  };
+  const addModel = async (ctx: any) => addFlow(ctx, async (provider, modelId) => {
+    if (syncLocalConfig(pi, ctx)) await report(ctx, () => setMainDefault(pi, ctx, provider, modelId));
+  });
+  pi.registerCommand("bms-defaults", {
+    description: "Configure Pi and subagent default models and effort levels",
+    handler: async (_args, ctx: any) => {
+      if (ctx.mode !== "tui") { ctx.ui.notify("/bms-defaults needs an interactive terminal.", "warning"); return; }
+      await report(ctx, async () => {
+        const config = syncLocalConfig(pi, ctx);
+        if (config) await defaultsFlow(pi, ctx, config);
+      });
+    },
+  });
+
   pi.registerCommand("bms", {
     description: "Better model select — searchable, usage-ranked model picker",
     handler: async (_args, ctx: any) => {
@@ -200,41 +219,31 @@ export default function (pi: ExtensionAPI) {
             "The effective model configuration has no models. Add one now?",
           );
           if (!add) return;
-          await addFlow(ctx as FlowCtx);
+          await report(ctx, () => addModel(ctx));
           continue;
         }
 
-        const action: PickerAction | undefined = await ctx.ui.custom((tui: any, theme: any, _kb: any, done: any) => {
-          const container = new Container();
-          const accent = (s: string) =>
-            typeof theme?.fg === "function" ? theme.fg("accent", s) : s;
-
-          container.addChild(new DynamicBorder(accent));
-          container.addChild(new Text(accent("Better Model Select"), 1, 0));
-
-          const picker = new ModelPicker(
-            rows,
-            theme,
-            () => tui.requestRender(),
-            (a: PickerAction) => done(a),
-          );
-          picker.focused = true;
-          container.addChild(picker);
-          container.addChild(new DynamicBorder(accent));
-
-          return {
-            render: (w: number) => container.render(w),
-            invalidate: () => container.invalidate(),
-            handleInput: (data: string) => picker.handleInput(data),
-          };
-        });
+        try {
+          const preference = piPreference(readSettings(settingsPath(ctx.cwd, "user")), ctx.isProjectTrusted?.() ? readSettings(settingsPath(ctx.cwd, "project")) : {});
+          for (const row of rows) {
+            row.current = ctx.model?.provider === row.provider && ctx.model?.id === row.modelId;
+            row.default = preference.provider === row.provider && preference.model === row.modelId;
+          }
+        } catch (error) { ctx.ui.notify(`Cannot read defaults: ${error}`, "warning"); }
+        const action = await pickerDialog(ctx, rows);
 
         switch (action?.kind) {
           case "load":
             await loadModel(pi, ctx, action.provider, action.modelId);
             return;
+          case "set-default":
+            await report(ctx, () => setMainDefault(pi, ctx, action.provider, action.modelId));
+            break;
+          case "defaults":
+            await report(ctx, () => defaultsFlow(pi, ctx, config));
+            break;
           case "add":
-            await addFlow(ctx as FlowCtx);
+            await report(ctx, () => addModel(ctx));
             break;
           case "update":
             await updateFlow(
@@ -276,6 +285,6 @@ export default function (pi: ExtensionAPI) {
   // Standalone add, kept for muscle memory and non-interactive convenience.
   pi.registerCommand("bms-add", {
     description: "Add a model from a provider's endpoint using the configured write mode",
-    handler: async (_args, ctx: any) => addFlow(ctx as FlowCtx),
+    handler: async (_args, ctx: any) => report(ctx, () => addModel(ctx)),
   });
 }

package/extensions/lib/agents.ts

@@ -0,0 +1,60 @@
+// Optional, isolated adapter: pi-subagents currently has no public discovery RPC.
+// Never vendor a second agent-discovery implementation or execute an agent to list roles.
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export interface AgentRole {
+  name: string;
+  model?: string;
+  thinking?: string | false;
+  runner?: unknown;
+  source?: string;
+  modelSource?: unknown;
+}
+export interface AgentDiscovery {
+  roles: AgentRole[];
+  projectRoot: string;
+  warning?: string;
+}
+/** Resolve the owning package, not the directory of its possibly bundled entry point. */
+export function subagentsPackageRoot(entry: string): string {
+  let directory = dirname(entry);
+  for (;;) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+      if (manifest.name === "pi-subagents") return directory;
+    } catch { /* keep looking above a bundle or other entry-point directory */ }
+    const parent = dirname(directory);
+    if (parent === directory) throw new Error("Cannot locate pi-subagents package root");
+    directory = parent;
+  }
+}
+export async function discoverRoles(cwd: string, pi: any, provider?: string, trusted = false): Promise<AgentDiscovery> {
+  try {
+    // Resolve only from this extension or the user's trusted Pi package directory.
+    const roots = [import.meta.url, pathToFileURL(join(getAgentDir(), "npm", "package.json")).href];
+    let entry: string | undefined;
+    for (const root of roots) {
+      try { entry = createRequire(root).resolve("pi-subagents"); break; } catch { /* optional package */ }
+    }
+    if (!entry) throw new Error("pi-subagents is not resolvable from BMS or the Pi npm package directory");
+    const base = subagentsPackageRoot(entry);
+    const api = await import(pathToFileURL(join(base, "src/agents/agents.js")).href);
+    if (typeof api.discoverAgents !== "function") throw new Error("Unsupported pi-subagents discovery API");
+    api.clearAgentDiscoveryCache?.();
+    const result = api.discoverAgents(cwd, trusted ? "both" : "user", provider, { projectTrusted: trusted });
+    let roles: AgentRole[] = result.agents;
+    try {
+      const runtime = await import(pathToFileURL(join(base, "src/agents/runtime-agent-registry.js")).href);
+      roles = runtime.mergeRuntimeAgents(pi, result, undefined, { cwd, scope: trusted ? "both" : "user", preferredModelProvider: provider, projectTrusted: trusted }).agents;
+    } catch { /* older versions have filesystem agents only */ }
+    // Native Pi and subagents may choose different roots. Use the subagents settings root for agents.
+    const projectRoot = api.findConfiguredProjectRoot?.(cwd) ?? cwd;
+    return { roles: [...roles].sort((a, b) => a.name.localeCompare(b.name)), projectRoot };
+  } catch (error) {
+    return { roles: [], projectRoot: cwd, warning: `Agent discovery unavailable: ${error}. Pi defaults remain available.` };
+  }
+}

package/extensions/lib/defaults-models.ts

@@ -0,0 +1,15 @@
+import { rankModels, type RankedModel } from "./picker.ts";
+import type { ModelsConfig } from "./store.ts";
+
+/** Assignment menus include authenticated registry models, not only custom models.json entries. */
+export function rankModelsForDefaults(config: ModelsConfig, ctx: any): RankedModel[] {
+  const rows = rankModels(config);
+  const seen = new Set(rows.map(row => `${row.provider}/${row.modelId}`));
+  for (const model of ctx.modelRegistry.getAvailable?.() ?? []) {
+    const key = `${model.provider}/${model.id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    rows.push({ provider: model.provider, modelId: model.id, label: model.name ?? model.id, count: 0, lastUsed: 0, reasoning: model.reasoning, contextWindow: model.contextWindow });
+  }
+  return rows;
+}

package/extensions/lib/defaults-store.ts

@@ -0,0 +1,108 @@
+// Defaults use native Pi settings. BMS capability hints live separately from models.json.
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export const EFFORTS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type Effort = typeof EFFORTS[number];
+export type Scope = "user" | "project";
+export type JsonObject = Record<string, any>;
+export function isEffort(value: unknown): value is Effort {
+  return typeof value === "string" && (EFFORTS as readonly string[]).includes(value);
+}
+export function object(value: unknown): JsonObject {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected a JSON object");
+  return value as JsonObject;
+}
+export function readSettings(path: string): JsonObject {
+  if (!existsSync(path)) return {};
+  return object(JSON.parse(readFileSync(path, "utf8")));
+}
+/** Fail closed on malformed files; serialize BMS writers and re-read immediately before patching. */
+export function patchSettings(path: string, patch: (settings: JsonObject) => void): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const lock = `${path}.bms-lock`;
+  const fd = openSync(lock, "wx", 0o600);
+  const tmp = `${path}.bms-${randomUUID()}`;
+  try {
+    const settings = readSettings(path);
+    patch(settings);
+    writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    renameSync(tmp, path);
+  } finally {
+    if (existsSync(tmp)) unlinkSync(tmp);
+    closeSync(fd);
+    unlinkSync(lock);
+  }
+}
+export function settingsPath(cwd: string, scope: Scope, agentDir = getAgentDir()): string {
+  return scope === "user" ? join(agentDir, "settings.json") : join(cwd, ".pi", "settings.json");
+}
+export interface Capability {
+  levels: Effort[];
+  source: "provider" | "manual" | "pi";
+}
+export function metadataPath(): string { return join(getAgentDir(), "bms-model-metadata.json"); }
+export function normalizeEfforts(raw: unknown): Effort[] | undefined {
+  if (!Array.isArray(raw) || !raw.length || !raw.every(isEffort)) return undefined;
+  return EFFORTS.filter(level => raw.includes(level));
+}
+export function capabilities(key: string, model?: { reasoning?: boolean; thinkingLevelMap?: Record<string, unknown> }, path = metadataPath()): { levels: Effort[]; source: string } {
+  const stored = readSettings(path)[key];
+  const levels = normalizeEfforts(stored?.levels);
+  if (levels) return { levels, source: stored.source === "provider" ? "Provider metadata" : stored.source === "manual" ? "Manual override" : "Pi standard levels; provider support unverified" };
+  if (model?.reasoning === false) return { levels: ["off"], source: "Non-reasoning model" };
+  // Native maps explicitly mark unsupported Pi levels with null.
+  if (model?.thinkingLevelMap) {
+    const supported = EFFORTS.filter(level => model.thinkingLevelMap![level] !== null);
+    if (supported.length) return { levels: supported, source: "Pi model capability map" };
+  }
+  return { levels: [...EFFORTS], source: "Pi standard levels; provider support unverified" };
+}
+export function saveCapability(key: string, capability: Capability, path = metadataPath()): void {
+  if (!normalizeEfforts(capability.levels)) throw new Error("Choose at least one valid effort level");
+  patchSettings(path, data => { data[key] = capability; });
+}
+export function setPiDefault(data: JsonObject, provider: string, model: string, effort: Effort | undefined): void {
+  data.defaultProvider = provider;
+  data.defaultModel = model;
+  if (effort === undefined) delete data.defaultThinkingLevel;
+  else data.defaultThinkingLevel = effort;
+  // A per-model startup preference would otherwise beat the newly chosen default.
+  if (data.modelThinkingLevels !== undefined) {
+    const levels = object(data.modelThinkingLevels);
+    delete levels[`${provider}/${model}`];
+  }
+}
+export function setRoleField(data: JsonObject, role: string | undefined, field: "model" | "thinking", value: string | false | undefined): void {
+  if (role && ["__proto__", "constructor", "prototype"].includes(role)) throw new Error("Invalid agent name");
+  const sub = data.subagents === undefined ? data.subagents = {} : object(data.subagents);
+  if (!role) {
+    const key = field === "model" ? "defaultModel" : "defaultThinking";
+    if (value === undefined) delete sub[key];
+    else sub[key] = value;
+    return;
+  }
+  const overrides = sub.agentOverrides === undefined ? sub.agentOverrides = {} : object(sub.agentOverrides);
+  const entry = Object.hasOwn(overrides, role) ? object(overrides[role]) : overrides[role] = {};
+  if (value === undefined) delete entry[field];
+  else entry[field] = value;
+  if (!Object.keys(entry).length) delete overrides[role];
+}
+/** Settings-only projection for the menu, not a claim about a running child. */
+export function roleField(user: JsonObject, project: JsonObject, provider: string | undefined, role: string | undefined, field: "model" | "thinking"): { value: unknown; source: string } {
+  for (const [scope, data] of [["Project", project], ["User", user]] as const) {
+    const sub = data.subagents;
+    if (role) {
+      const scoped = provider && sub?.agentOverridesByProvider?.[provider]?.[role];
+      if (scoped && Object.hasOwn(scoped, field)) return { value: scoped[field], source: `${scope}, provider override` };
+      const regular = sub?.agentOverrides?.[role];
+      if (regular && Object.hasOwn(regular, field)) return { value: regular[field], source: `${scope} role override` };
+    } else {
+      const key = field === "model" ? "defaultModel" : "defaultThinking";
+      if (sub && Object.hasOwn(sub, key)) return { value: sub[key], source: `${scope} fallback` };
+    }
+  }
+  return { value: undefined, source: role ? "Agent-defined / fallback" : "Parent session" };
+}

package/extensions/lib/defaults.ts

@@ -0,0 +1,149 @@
+import { discoverRoles, type AgentRole } from "./agents.ts";
+import { capabilities, isEffort, patchSettings, readSettings, roleField, setPiDefault, setRoleField, settingsPath, type Effort, type JsonObject, type Scope } from "./defaults-store.ts";
+import { pickerDialog } from "./picker-dialog.ts";
+import { rankModelsForDefaults } from "./defaults-models.ts";
+import type { ModelsConfig } from "./store.ts";
+
+export async function chooseEffort(ctx: any, key: string, model?: any, initial?: unknown): Promise<Effort | "automatic" | undefined> {
+  const capability = capabilities(key, model);
+  const levels = [...capability.levels];
+  if (isEffort(initial) && levels.includes(initial)) levels.splice(levels.indexOf(initial), 1), levels.unshift(initial);
+  return ctx.ui.select(`Effort for ${key}\n${capability.source}\nAutomatic removes this scope's preference. Pi/provider may clamp unsupported levels.`, ["automatic", ...levels]);
+}
+export function piPreference(user: JsonObject, project: JsonObject): { provider?: string; model?: string; effort?: Effort; source: string } {
+  const provider = project.defaultProvider ?? user.defaultProvider;
+  const model = project.defaultModel ?? user.defaultModel;
+  const key = `${provider}/${model}`;
+  const effort = project.modelThinkingLevels?.[key] ?? user.modelThinkingLevels?.[key] ?? project.defaultThinkingLevel ?? user.defaultThinkingLevel;
+  return { provider, model, effort, source: project.defaultModel !== undefined || project.defaultProvider !== undefined ? "Project" : "User / automatic" };
+}
+function trusted(pi: any, ctx: any): boolean {
+  return typeof ctx.isProjectTrusted === "function" ? ctx.isProjectTrusted() : typeof pi.isProjectTrusted === "function" && pi.isProjectTrusted();
+}
+function projectSettings(pi: any, ctx: any, cwd: string): JsonObject { return trusted(pi, ctx) ? readSettings(settingsPath(cwd, "project")) : {}; }
+
+/** Switch first; never replace saved defaults when authentication/model selection fails. */
+export async function setMainDefault(pi: any, ctx: any, provider: string, modelId: string, scope: Scope = "user"): Promise<void> {
+  if (scope === "project" && !trusted(pi, ctx)) throw new Error("Project is not trusted");
+  await ctx.modelRegistry.refresh();
+  const model = ctx.modelRegistry.find(provider, modelId);
+  if (!model) throw new Error(`Model ${provider}/${modelId} is not in the active registry`);
+  const user = readSettings(settingsPath(ctx.cwd, "user"));
+  const project = projectSettings(pi, ctx, ctx.cwd);
+  const choice = await chooseEffort(ctx, `${provider}/${modelId}`, model, piPreference(user, project).effort);
+  if (choice === undefined) return;
+  const effort = choice === "automatic" ? undefined : choice;
+  const preview = structuredClone(scope === "user" ? user : project);
+  setPiDefault(preview, provider, modelId, effort);
+  const effective = piPreference(scope === "user" ? preview : user, scope === "project" ? preview : project);
+  const shadowed = effective.provider !== provider || effective.model !== modelId || (effort !== undefined && effective.effort !== effort);
+  if (shadowed && !(await ctx.ui.confirm("Higher-priority settings", "Project or per-model settings override this preference at startup. Save and use your selection in this session anyway?"))) return;
+  if (!(await ctx.ui.confirm("Save and use Pi default?", `${provider}/${modelId}, effort ${choice}\nScope: ${scope}\n${settingsPath(ctx.cwd, scope)}`))) return;
+  // Parse before changing session state. A malformed file must never be overwritten.
+  readSettings(settingsPath(ctx.cwd, scope));
+  const previousModel = ctx.model;
+  const previousEffort = pi.getThinkingLevel();
+  if (!(await pi.setModel(model))) {
+    ctx.ui.notify("Could not switch model. Defaults were not changed.", "warning");
+    return;
+  }
+  const requested = effort ?? effective.effort ?? "medium";
+  try {
+    pi.setThinkingLevel(requested);
+    const applied = pi.getThinkingLevel();
+    if (effort !== undefined && applied !== effort && !(await ctx.ui.confirm("Pi adjusted the effort", `Requested ${effort}; Pi uses ${applied}. Save ${applied} instead?`))) {
+      if (previousModel) await pi.setModel(previousModel);
+      pi.setThinkingLevel(previousEffort);
+      return;
+    }
+    patchSettings(settingsPath(ctx.cwd, scope), data => setPiDefault(data, provider, modelId, effort === undefined ? undefined : applied));
+    ctx.ui.notify(`Using ${provider}/${modelId}, effort ${applied}. Saved ${scope} Pi default.${shadowed ? " Higher-priority startup settings still apply." : ""}`, "info");
+  } catch (error) {
+    if (previousModel) await pi.setModel(previousModel);
+    pi.setThinkingLevel(previousEffort);
+    throw error;
+  }
+}
+
+function display(value: unknown): string {
+  if (value === undefined) return "agent-defined / fallback";
+  if (value === false) return "off";
+  return String(value);
+}
+async function assignModel(ctx: any, config: ModelsConfig, title: string): Promise<{ provider: string; modelId: string } | undefined> {
+  const rows = rankModelsForDefaults(config, ctx);
+  if (!rows.length) { ctx.ui.notify("No models available to assign.", "warning"); return; }
+  const action = await pickerDialog(ctx, rows, title, true);
+  return action?.kind === "load" ? action : undefined;
+}
+export async function defaultsFlow(pi: any, ctx: any, config: ModelsConfig): Promise<void> {
+  let scope: Scope = "user";
+  for (;;) {
+    const discovery = await discoverRoles(ctx.cwd, pi, ctx.model?.provider, trusted(pi, ctx));
+    const user = readSettings(settingsPath(ctx.cwd, "user"));
+    const project = projectSettings(pi, ctx, ctx.cwd);
+    const agentUser = readSettings(settingsPath(discovery.projectRoot, "user"));
+    const agentProject = projectSettings(pi, ctx, discovery.projectRoot);
+    const main = piPreference(user, project);
+    const roles = discovery.roles;
+    const modelFallback = roleField(agentUser, agentProject, ctx.model?.provider, undefined, "model");
+    const thinkingFallback = roleField(agentUser, agentProject, ctx.model?.provider, undefined, "thinking");
+    const options = [
+      `Scope: ${scope} (select to change)`,
+      `Pi session: ${main.provider ?? "auto"}/${main.model ?? "auto"} | ${main.effort ?? "automatic"} [${main.source}]`,
+      `Subagent fallback: ${display(modelFallback.value)} | ${display(thinkingFallback.value)}`,
+      ...roles.map(role => {
+        const model = roleField(agentUser, agentProject, ctx.model?.provider, role.name, "model");
+        const effort = roleField(agentUser, agentProject, ctx.model?.provider, role.name, "thinking");
+        return `${role.name}: ${display(model.value ?? role.model)} | ${display(effort.value ?? role.thinking)} [${model.source}; ${effort.source}]${role.runner ? " [external runner]" : ""}`;
+      }),
+      ...(discovery.warning ? ["Agent discovery details"] : []),
+      "Done",
+    ];
+    const selected = await ctx.ui.select(`BMS defaults\nSaved settings, not running-child state. Agent changes require /reload.\n${scope === "user" ? settingsPath(ctx.cwd, scope) : "Pi: " + settingsPath(ctx.cwd, scope) + "\nAgents: " + settingsPath(discovery.projectRoot, scope)}`, options);
+    if (!selected || selected === "Done") return;
+    const index = options.indexOf(selected);
+    if (index === 0) {
+      if (!trusted(pi, ctx)) { ctx.ui.notify("Project defaults require a trusted project.", "warning"); continue; }
+      scope = scope === "user" ? "project" : "user";
+    } else if (index === 1) {
+      const model = await assignModel(ctx, config, "Choose Pi default model");
+      if (model) await setMainDefault(pi, ctx, model.provider, model.modelId, scope);
+    } else if (selected === "Agent discovery details") {
+      ctx.ui.notify(discovery.warning!, "warning");
+    } else {
+      const role = index === 2 ? undefined : roles[index - 3];
+      await editRole(pi, ctx, config, scope, discovery.projectRoot, role, agentUser, agentProject);
+    }
+  }
+}
+async function editRole(pi: any, ctx: any, config: ModelsConfig, scope: Scope, root: string, role: AgentRole | undefined, user: JsonObject, project: JsonObject): Promise<void> {
+  const title = role?.name ?? "Subagent fallback";
+  const path = settingsPath(root, scope);
+  if (role?.runner) {
+    ctx.ui.notify("External runner defaults are not editable with the Pi registry picker. Use the runner's own configuration.", "warning");
+    return;
+  }
+  const action = await ctx.ui.select(`${title}\nScope: ${scope}. Provider-specific and project overrides may take precedence.\n${path}`, ["Choose model", "Inherit parent model", "Remove model override", "Choose effort", "Remove effort override", "Back"]);
+  if (!action || action === "Back") return;
+  let field: "model" | "thinking" = "model";
+  let value: string | false | undefined;
+  if (action === "Choose model") {
+    const selected = await assignModel(ctx, config, `Choose model for ${title}`);
+    if (!selected) return;
+    value = `${selected.provider}/${selected.modelId}`;
+  } else if (action === "Inherit parent model") value = "inherit";
+  else if (action === "Choose effort") {
+    field = "thinking";
+    const selected = roleField(user, project, ctx.model?.provider, role?.name, "model").value ?? role?.model;
+    const ref = typeof selected === "string" && selected !== "inherit" ? selected.replace(/:(off|minimal|low|medium|high|xhigh|max)$/, "") : `${ctx.model?.provider}/${ctx.model?.id}`;
+    const split = ref.indexOf("/");
+    const model = split > 0 ? ctx.modelRegistry.find(ref.slice(0, split), ref.slice(split + 1)) : undefined;
+    const effort = await chooseEffort(ctx, ref, model);
+    if (effort === undefined) return;
+    value = effort === "automatic" ? undefined : effort;
+  } else if (action === "Remove effort override") field = "thinking";
+  if (!(await ctx.ui.confirm(`Save ${title}?`, `${field}: ${value ?? "remove override"}\n${path}\nReload Pi before relying on the new child defaults. Removing effort restores agent-defined/fallback behavior; it does not force parent inheritance.`))) return;
+  patchSettings(path, data => setRoleField(data, role?.name, field, value));
+  ctx.ui.notify(`Saved ${title} ${field}. Run /reload to refresh subagent defaults.`, "info");
+}

package/extensions/lib/effort-editor.ts

@@ -0,0 +1,69 @@
+import type { FlowCtx } from "./flows.ts";
+import { capabilities, EFFORTS, isEffort, metadataPath, normalizeEfforts, patchSettings, readSettings, saveCapability, settingsPath, type Capability, type Effort } from "./defaults-store.ts";
+
+export interface EffortDraft { capability: Capability; preferred?: Effort }
+export async function editModelEfforts(ctx: FlowCtx, key: string, reasoning: boolean, reported?: Effort[]): Promise<EffortDraft | undefined> {
+  const existing = capabilities(key, { reasoning });
+  let levels = !reasoning ? ["off" as const] : reported ?? existing.levels;
+  let source: Capability["source"] = reported ? "provider" : existing.source === "Manual override" ? "manual" : "pi";
+  if (reasoning) {
+    const mode = await ctx.ui.select(`Available efforts for ${key}\n${reported ? "Provider metadata" : existing.source}`, ["Use listed levels", "Configure manually"]);
+    if (!mode) return;
+    if (mode === "Configure manually") {
+      const raw = await ctx.ui.input(`Comma-separated Pi efforts: ${EFFORTS.join(", ")}`, levels.join(", "));
+      if (raw === undefined) return;
+      const parsed = normalizeEfforts(raw.split(",").map(value => value.trim()));
+      if (!parsed) { ctx.ui.notify("Choose one or more valid Pi effort levels. Nothing changed.", "warning"); return; }
+      levels = parsed;
+      source = "manual";
+    }
+  }
+  const previous = readSettings(settingsPath(ctx.cwd ?? process.cwd(), "user")).modelThinkingLevels?.[key];
+  const options = ["automatic", ...levels];
+  if (isEffort(previous) && levels.includes(previous)) options.splice(options.indexOf(previous), 1), options.unshift(previous);
+  const preferred = await ctx.ui.select(`Preferred effort when Pi loads ${key}\nCurrent: ${previous ?? "automatic"}. Saved in user modelThinkingLevels, independently of agent role defaults.`, options);
+  if (preferred === undefined) return;
+  return { capability: { levels, source }, preferred: isEffort(preferred) ? preferred : undefined };
+}
+/** Do not silently invalidate saved defaults when editing model capability hints. */
+export function effortConflicts(data: Record<string, any>, key: string, levels: readonly Effort[], preferred?: Effort): string[] {
+  const conflicts: string[] = [];
+  const check = (label: string, effort: unknown) => {
+    if (isEffort(effort) && !levels.includes(effort)) conflicts.push(`${label}: ${effort}`);
+  };
+  check("Per-model preference", preferred);
+  if (`${data.defaultProvider}/${data.defaultModel}` === key) check("Pi default", preferred ?? data.defaultThinkingLevel);
+  const sub = data.subagents;
+  if (sub?.defaultModel === key) check("Subagent fallback", sub.defaultThinking);
+  const scan = (entries: Record<string, any> | undefined, prefix: string) => {
+    for (const [name, entry] of Object.entries(entries ?? {})) {
+      if (entry.model === key) check(`${prefix}${name}`, entry.thinking);
+    }
+  };
+  scan(sub?.agentOverrides, "Agent ");
+  for (const [provider, entries] of Object.entries(sub?.agentOverridesByProvider ?? {})) scan(entries as any, `${provider} agent `);
+  return conflicts;
+}
+export function saveModelEfforts(ctx: FlowCtx & { cwd?: string }, key: string, draft: EffortDraft): boolean {
+  const userPath = settingsPath(ctx.cwd ?? process.cwd(), "user");
+  const projectPath = settingsPath(ctx.cwd ?? process.cwd(), "project");
+  const project = ctx.isProjectTrusted?.() ? readSettings(projectPath) : {};
+  const conflicts = [
+    ...effortConflicts(readSettings(userPath), key, draft.capability.levels, draft.preferred),
+    ...effortConflicts(project, key, draft.capability.levels, project.modelThinkingLevels?.[key] ?? draft.preferred).map(value => `Project ${value}`),
+  ];
+  if (conflicts.length) {
+    ctx.ui.notify(`Effort update blocked. Change these defaults in /bms-defaults first: ${conflicts.join("; ")}`, "warning");
+    return false;
+  }
+  // Validate the capability file before writing a preference in a different file.
+  readSettings(metadataPath());
+  patchSettings(userPath, data => {
+    const levels = data.modelThinkingLevels ??= {};
+    if (!levels || typeof levels !== "object" || Array.isArray(levels)) throw new Error("Invalid modelThinkingLevels settings");
+    if (draft.preferred === undefined) delete levels[key];
+    else levels[key] = draft.preferred;
+  });
+  saveCapability(key, draft.capability);
+  return true;
+}

package/extensions/lib/flows.ts

@@ -3,6 +3,7 @@
 // Each mutation follows the saved write mode, then re-reads the target file
 // before saving so another pi session's edit is not silently clobbered.
 
+import { editModelEfforts, saveModelEfforts, type EffortDraft } from "./effort-editor.ts";
 import {
   DEFAULT_CONTEXT_WINDOW,
   DEFAULT_MAX_TOKENS,
@@ -29,6 +30,8 @@ import {
 
 // Minimal shape of the pi extension command context we rely on.
 export interface FlowCtx {
+  cwd?: string;
+  isProjectTrusted?: () => boolean;
   ui: {
     notify: (message: string, level: string) => void;
     select: (message: string, options: string[]) => Promise<string | undefined>;
@@ -92,7 +95,7 @@ async function selectInput(
 
 // ----- add -----------------------------------------------------------------
 
-export async function addFlow(ctx: FlowCtx): Promise<void> {
+export async function addFlow(ctx: FlowCtx, onAdded?: (provider: string, modelId: string) => Promise<void>): Promise<void> {
   const config = loadConfig(ctx);
   if (!config) return;
   const providers = config.providers ?? {};
@@ -177,6 +180,9 @@ export async function addFlow(ctx: FlowCtx): Promise<void> {
   if (input === undefined) return;
   crumbs.push(`Input: ${input.join("+")}`);
 
+  const effortDraft = await editModelEfforts(ctx, `${providerName}/${modelId}`, reasoning, meta.effortLevels);
+  if (!effortDraft) return;
+
   const targetFile = selectedWriteTarget();
   const ok = await ctx.ui.confirm(
     `${header()}Add this model to "${providerName}"?`,
@@ -198,6 +204,7 @@ export async function addFlow(ctx: FlowCtx): Promise<void> {
     ctx.ui.notify(`Model "${modelId}" is already configured in ${providerName}.`, "warning");
     return;
   }
+  if (!saveModelEfforts(ctx, `${providerName}/${modelId}`, effortDraft)) return;
   ensureProviderSettings(freshTarget, freshEffective, providerName);
   upsertModel(freshTarget, providerName, {
     id: modelId,
@@ -209,6 +216,7 @@ export async function addFlow(ctx: FlowCtx): Promise<void> {
   });
   saveConfig(freshTarget, targetFile);
   ctx.ui.notify(`Added "${modelId}" to ${providerName} in ${targetFile}.`, "info");
+  if (onAdded && await ctx.ui.confirm("Set as Pi default?", "Configure this model and effort as the default for new sessions?")) await onAdded(providerName, modelId);
 }
 
 // ----- update --------------------------------------------------------------
@@ -276,7 +284,20 @@ export async function updateFlow(
     );
   }
 
+  let effortDraft: EffortDraft | undefined;
   const fields: Field[] = [
+    {
+      key: "bmsEfforts",
+      label: "Available / preferred efforts",
+      current: "edit capability levels and Pi per-model preference",
+      suggest: meta.effortLevels?.join(", "),
+      edit: async () => {
+        const draft = await editModelEfforts(ctx, `${providerName}/${existing.id}`, Boolean(changes.get("reasoning") ?? existing.reasoning), meta.effortLevels);
+        if (!draft) return;
+        effortDraft = draft;
+        return `${draft.capability.levels.join(", ")}; preferred ${draft.preferred ?? "automatic"}`;
+      },
+    },
     {
       key: "name",
       label: "Display name",
@@ -363,6 +384,10 @@ export async function updateFlow(
     const value = await field.edit(() => `Model: ${existing.id} [${providerName}]\n`);
     if (value === undefined) continue; // ESC in the field editor — back to list
     changes.set(field.key, value);
+    if (field.key === "reasoning") {
+      effortDraft = undefined;
+      changes.delete("bmsEfforts");
+    }
   }
 
   if (changes.size === 0) {
@@ -388,7 +413,12 @@ export async function updateFlow(
     ctx.ui.notify(`Model "${existing.id}" no longer exists in ${providerName}.`, "error");
     return;
   }
-  Object.assign(modelEntry, Object.fromEntries(changes));
+  if (changes.has("reasoning") && !effortDraft) {
+    effortDraft = await editModelEfforts(ctx, `${providerName}/${existing.id}`, Boolean(changes.get("reasoning")), meta.effortLevels);
+    if (!effortDraft) return;
+  }
+  if (effortDraft && !saveModelEfforts(ctx, `${providerName}/${existing.id}`, effortDraft)) return;
+  Object.assign(modelEntry, Object.fromEntries([...changes].filter(([key]) => key !== "bmsEfforts")));
   ensureProviderSettings(freshTarget, freshEffective, providerName);
   upsertModel(freshTarget, providerName, modelEntry);
   saveConfig(freshTarget, targetFile);

package/extensions/lib/meta.ts

@@ -5,11 +5,20 @@
 // endpoint yields nothing and the caller falls back to explicit defaults.
 
 import type { ModelsConfig } from "./store.ts";
+import { normalizeEfforts, type Effort } from "./defaults-store.ts";
+
+/** Only explicit enumerations count. supported_parameters alone is not an effort list. */
+export function metadataEfforts(metadata: Record<string, any>): Effort[] | undefined {
+  return normalizeEfforts(metadata.supported_reasoning_efforts)
+    ?? normalizeEfforts(metadata.supported_thinking_levels)
+    ?? normalizeEfforts(metadata.reasoning_efforts);
+}
 
 export const DEFAULT_CONTEXT_WINDOW = 128000;
 export const DEFAULT_MAX_TOKENS = 32768;
 
 export interface ModelMeta {
+  effortLevels?: Effort[];
   contextWindow?: number;
   maxTokens?: number;
   reasoning?: boolean;
@@ -55,6 +64,7 @@ export async function fetchModelMeta(
   key: string,
   modelId: string,
 ): Promise<ModelMeta> {
+  let effortLevels: Effort[] | undefined;
   let metaContext: number | undefined;
   let metaMaxTokens: number | undefined;
   let metaReasoning: boolean | undefined;
@@ -87,6 +97,8 @@ export async function fetchModelMeta(
       );
       if (match?.model_info) {
         const mi = match.model_info as Record<string, any>;
+        effortLevels = metadataEfforts(mi);
+        if (typeof mi.supports_reasoning === "boolean") metaReasoning = mi.supports_reasoning;
         metaContext = mi.max_input_tokens ?? mi.max_tokens;
         // Only trust an explicit output cap — LiteLLM's generic `max_tokens`
         // is often a default (e.g. 4096/128000), not the model's real cap.
@@ -106,8 +118,8 @@ export async function fetchModelMeta(
     // Not a LiteLLM proxy or endpoint unavailable — ignore.
   }
 
-  // 2) OpenAI-style per-model GET
-  if (metaContext === undefined) {
+  // 2) OpenAI-style per-model GET, also used when token metadata lacks effort information.
+  if (metaContext === undefined || effortLevels === undefined) {
     try {
       const modelRes = await fetch(`${base}/models/${encodeURIComponent(modelId)}`, {
         headers: authHeaders,
@@ -117,9 +129,10 @@ export async function fetchModelMeta(
         const b = (await modelRes.json()) as Record<string, any>;
         // OpenAI /v1/models/{id} does not return token limits, but some proxies
         // add custom fields like max_context_length or max_model_tokens.
-        metaContext =
-          b.max_context_length ?? b.max_input_tokens ?? b.context_window ?? b.max_tokens;
-        metaMaxTokens = b.max_output_tokens ?? b.max_completion_tokens ?? metaContext;
+        effortLevels ??= metadataEfforts(b);
+        if (typeof b.reasoning === "boolean") metaReasoning ??= b.reasoning;
+        metaContext ??= b.max_context_length ?? b.max_input_tokens ?? b.context_window ?? b.max_tokens;
+        metaMaxTokens ??= b.max_output_tokens ?? b.max_completion_tokens;
       }
     } catch {
       // Endpoint not supported — ignore.
@@ -140,7 +153,7 @@ export async function fetchModelMeta(
           if (!entry) continue;
           metaContext = entry.max_input_tokens ?? entry.max_tokens;
           metaMaxTokens = entry.max_output_tokens ?? entry.max_tokens;
-          metaReasoning =
+          metaReasoning ??=
             entry.mode === "reasoning" || entry.reasoning === true || heuristicReasoning;
           if (entry.input_cost_per_token > 0 || entry.output_cost_per_token > 0) {
             metaInput = entry.supports_vision ? ["text", "image"] : ["text"];
@@ -165,7 +178,8 @@ export async function fetchModelMeta(
   return {
     contextWindow: metaContext,
     maxTokens: metaMaxTokens,
-    reasoning: metaReasoning,
+    reasoning: effortLevels?.some(level => level !== "off") ? true : metaReasoning,
+    effortLevels,
     input: metaInput,
   };
 }

package/extensions/lib/picker-dialog.ts

@@ -0,0 +1,21 @@
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Container, Text } from "@earendil-works/pi-tui";
+import { ModelPicker, type PickerAction, type RankedModel } from "./picker.ts";
+
+export async function pickerDialog(ctx: any, rows: RankedModel[], title = "Better Model Select", assignment = false): Promise<PickerAction | undefined> {
+  return ctx.ui.custom((tui: any, theme: any, _kb: any, done: any) => {
+    const container = new Container();
+    const accent = (text: string) => typeof theme?.fg === "function" ? theme.fg("accent", text) : text;
+    container.addChild(new DynamicBorder(accent));
+    container.addChild(new Text(accent(title), 1, 0));
+    const picker = new ModelPicker(rows, theme, () => tui.requestRender(), done, assignment);
+    picker.focused = true;
+    container.addChild(picker);
+    container.addChild(new DynamicBorder(accent));
+    return {
+      render: (width: number) => container.render(width),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => picker.handleInput(data),
+    };
+  });
+}

package/extensions/lib/picker.ts

@@ -19,6 +19,8 @@ import { loadUsage, usageKey, type ModelsConfig } from "./store.ts";
 
 export type PickerAction =
   | { kind: "load"; provider: string; modelId: string }
+  | { kind: "set-default"; provider: string; modelId: string }
+  | { kind: "defaults" }
   | { kind: "add" }
   | { kind: "update"; provider?: string; modelId?: string }
   | { kind: "delete"; provider?: string; modelId?: string }
@@ -34,6 +36,8 @@ export interface RankedModel {
   lastUsed: number;
   contextWindow?: number;
   reasoning: boolean;
+  current?: boolean;
+  default?: boolean;
 }
 
 /**
@@ -77,6 +81,8 @@ function formatContext(n?: number): string {
 
 export function toSelectItem(row: RankedModel): SelectItem {
   const bits: string[] = [row.modelId, `[${row.provider}]`];
+  if (row.current) bits.push("[current]");
+  if (row.default) bits.push("[default]");
   const ctxLabel = formatContext(row.contextWindow);
   if (ctxLabel) bits.push(`ctx ${ctxLabel}`);
   if (row.reasoning) bits.push("reasoning");
@@ -109,7 +115,7 @@ export function selectListTheme(theme: any): SelectListTheme {
 }
 
 const HINT =
-  "↑↓ move  •  enter load  •  ctrl+a add  •  ctrl+u update  •  ctrl+x delete  •  ctrl+o options  •  ctrl+r reset  •  esc close";
+  "↑↓ move  •  enter load  •  ctrl+a add  •  ctrl+u update  •  ctrl+x delete  •  ctrl+d default  •  ctrl+g agent defaults  •  ctrl+o options  •  ctrl+r reset  •  esc close";
 
 export class ModelPicker extends Container implements Focusable {
   private search: Input;
@@ -123,6 +129,7 @@ export class ModelPicker extends Container implements Focusable {
   private theme: any;
   private onChange: () => void;
   private done: (action: PickerAction) => void;
+  private assignment: boolean;
 
   private _focused = false;
   get focused(): boolean {
@@ -139,11 +146,13 @@ export class ModelPicker extends Container implements Focusable {
     theme: any,
     onChange: () => void,
     done: (action: PickerAction) => void,
+    assignment = false,
   ) {
     super();
     this.theme = theme;
     this.onChange = onChange;
     this.done = done;
+    this.assignment = assignment;
     this.rows = rows;
     this.filtered = rows;
 
@@ -163,7 +172,7 @@ export class ModelPicker extends Container implements Focusable {
     this.list = this.buildList(rows);
 
     this.countText = new Text(fg("dim", this.countLabel()), 1, 0);
-    this.hintText = new Text(fg("dim", HINT), 1, 0);
+    this.hintText = new Text(fg("dim", assignment ? "↑↓ move  •  enter assign  •  esc back" : HINT), 1, 0);
 
     this.addChild(this.search);
     this.addChild(this.list);
@@ -234,6 +243,13 @@ export class ModelPicker extends Container implements Focusable {
 
   handleInput(data: string): void {
     if (matchesKey(data, "escape")) return this.done({ kind: "close" });
+    if (!this.assignment && matchesKey(data, "ctrl+g")) return this.done({ kind: "defaults" });
+    if (!this.assignment && matchesKey(data, "ctrl+d")) {
+      const row = this.currentRow();
+      if (row) this.done({ kind: "set-default", provider: row.provider, modelId: row.modelId });
+      return;
+    }
+    if (this.assignment && ["ctrl+a", "ctrl+o", "ctrl+r", "ctrl+u", "ctrl+x", "ctrl+d", "ctrl+g"].some(key => matchesKey(data, key as any))) return;
     if (matchesKey(data, "ctrl+a")) return this.done({ kind: "add" });
     if (matchesKey(data, "ctrl+o")) return this.done({ kind: "options" });
     if (matchesKey(data, "ctrl+r")) return this.done({ kind: "reset" });

package/extensions/lib/store.ts

@@ -146,7 +146,7 @@ export function mergeConfigs(base: ModelsConfig, local: ModelsConfig): ModelsCon
 export function loadConfig(ctx: {
   ui: { notify: (m: string, l: string) => void };
 }): ModelsConfig | null {
-  const base = loadConfigFile(ctx, "models.json");
+  const base = loadConfigFile(ctx, "models.json", true);
   if (!base) return null;
   if (loadSettings().writeMode === "direct") return base;
   migrateLegacyOverlay();

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "pi-better-model-select",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "module",
-  "description": "Better model select for pi — /bms opens a searchable model picker sorted by how often you actually use each model, with inline add, update and delete.",
+  "description": "Searchable, usage-ranked model picker for Pi with model management, default model and thinking effort selection, and per-role subagent defaults.",
   "keywords": [
     "pi-package",
     "pi-extension",
     "bms",
     "model-select",
     "model-manager",
+    "model-defaults",
+    "thinking-effort",
+    "subagents",
     "model-picker",
     "search",
     "fuzzy",
@@ -22,6 +25,8 @@
     "extensions/",
     "!extensions/**/*.test.ts",
     "README.md",
+    "docs/configuration.md",
+    "docs/development.md",
     "LICENSE"
   ],
   "pi": {
@@ -31,6 +36,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
+    "test:smoke": "python3 scripts/smoke-local.py",
     "test": "node --experimental-strip-types --test extensions/lib/*.test.ts",
     "check:pack": "npm pack --dry-run --ignore-scripts >/dev/null",
     "gate": "npm run typecheck && npm test && npm run check:pack"