pi-better-subagents 0.11.0 → 0.13.0

package/README.md

@@ -36,10 +36,14 @@ Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or ne
 ## Delegation Modes
 
 `config.json` sets `delegationMode` to `manual`, `adaptive` (default), or
-`coordinator`. `/subagents` displays the active mode, and
-`/subagents mode manual|adaptive|coordinator` changes it for the current
-session without changing config. `/subagents save` writes the current mode as
-the next session's default. The navigator's `main` row opens the same control:
+`coordinator`. `/subagents settings` (or `/subagents`) opens a settings page
+for delegation mode and the concurrent-subagent cap (default 4). Edits apply to
+this session and persist across reloads; Ctrl+S saves both as defaults, and
+Reset to defaults clears
+session overrides. `/subagents mode manual|adaptive|coordinator` and
+`/subagents cap <number>` are command equivalents; `/subagents save` persists
+both. Lowering the cap blocks new single and batch launches without stopping
+running work. The navigator's `main` row retains its mode-only controls:
 `m` cycles the session mode, `ctrl+s` saves that default, and `x`
 does not stop it. Manual delegates only on explicit user or workflow request, even with a
 plan. Adaptive delegates substantial independent work when useful. Coordinator

package/agent-commands.ts

@@ -47,6 +47,7 @@ import {
     type CodexDocument,
 } from "./codex-import.ts";
 import { resolveRoleAssignment } from "./role-assignment.ts";
+import { saveAgentSessionDefaults, withAgentSessionSettings, type AgentSessionOverrides, type AgentSessionSettings } from "./agent-session-settings.ts";
 
 const MODEL_PATTERN = /^[a-z0-9][a-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._+-]*$/;
 const TIER_PATTERN = /^[a-z][a-z0-9-]{0,32}$/;
@@ -68,6 +69,9 @@ export interface AgentCommandDeps {
     now?: () => string;
     /** Resolution unit injects availability, actual model/effort, and launchability. */
     enrich?: LaunchEnricher;
+    sessionSettings?: AgentSessionSettings;
+    /** Available foreground registry models, as provider/id. */
+    editableModels?: () => readonly string[];
     /**
      * Live slash-command context, before list/inspect/create/reload/import.
      * Lifecycle refreshes the foreground model and settings here. Direct
@@ -112,6 +116,7 @@ interface CatalogLocation {
     projectTrusted: boolean;
     projectConfigDirName?: string;
     bundledRoot?: string;
+    sessionSettings?: AgentSessionOverrides;
 }
 
 interface ParsedArgs {
@@ -149,6 +154,7 @@ export function registerAgentCommands(pi: Pick<ExtensionAPI, "registerCommand">,
 
 export async function executeAgentsCommand(args: string, host: AgentCommandHost, deps: AgentCommandDeps = {}): Promise<AgentCommandResult> {
     const parsed = parseCommandArgs(args);
+    if (parsed.positionals.length === 0 && parsed.flags.size === 0 && host.mode === "tui" && host.hasUI && host.ui.custom) parsed.positionals.push("list");
     if (parsed.unknown.length > 0 || parsed.missing.length > 0) {
         const detail = [
             ...parsed.unknown.map((flag) => `Unknown flag --${flag}.`),
@@ -161,8 +167,8 @@ export async function executeAgentsCommand(args: string, host: AgentCommandHost,
     }
     const command = parsed.positionals[0]!;
     const loc = location(host, deps);
-    if (command === "list") return finishInspection(host, await runList(parsed, loc, deps));
-    if (command === "show" || command === "inspect") return finishInspection(host, await runShow(command, parsed, host, loc, deps));
+    if (command === "list") return finishInspection(host, await runList(parsed, loc, deps), deps);
+    if (command === "show" || command === "inspect") return finishInspection(host, await runShow(command, parsed, host, loc, deps), deps);
     if (command === "reload") return finish(host, await runReload(parsed, loc, deps));
     if (command === "create") return finish(host, await runCreate(parsed, host, loc, deps));
     if (command === "import-codex") return finish(host, await runImport(parsed, host, loc, deps));
@@ -215,7 +221,7 @@ async function runList(parsed: ParsedArgs, loc: CatalogLocation, deps: AgentComm
 
 async function runReload(parsed: ParsedArgs, loc: CatalogLocation, deps: AgentCommandDeps): Promise<AgentCommandResult> {
     if (parsed.positionals.length > 1) return result("error", "reload", false, "reload does not take extra arguments.");
-    const listed = presentCatalog(refreshCatalog(loc), deps.enrich);
+    const listed = presentCatalog(withAgentSessionSettings(refreshCatalog(loc), loc.sessionSettings), deps.enrich);
     return {
         ...result("ok", "reload", false, `Reloaded revision ${listed.revision} for inspection. The next launch reads the files again on its own; this command is not a prerequisite.\n${listed.text}`),
         diagnostics: listed.diagnostics,
@@ -662,11 +668,12 @@ function location(host: AgentCommandHost, deps: AgentCommandDeps): CatalogLocati
         projectTrusted: host.isProjectTrusted(),
         projectConfigDirName: deps.projectConfigDirName,
         bundledRoot: deps.bundledRoot,
+        sessionSettings: deps.sessionSettings?.snapshot(),
     };
 }
 
 function readCatalog(loc: CatalogLocation): CatalogSnapshot {
-    return loadCatalog(loc);
+    return withAgentSessionSettings(loadCatalog(loc), loc.sessionSettings);
 }
 
 function untrusted(command: string): AgentCommandResult {
@@ -707,16 +714,37 @@ function finish(host: AgentCommandHost, commandResult: AgentCommandResult): Agen
     return commandResult;
 }
 
-async function finishInspection(host: AgentCommandHost, commandResult: AgentCommandResult): Promise<AgentCommandResult> {
+async function finishInspection(host: AgentCommandHost, commandResult: AgentCommandResult, deps: AgentCommandDeps): Promise<AgentCommandResult> {
     if (commandResult.ok && host.mode === "tui" && host.hasUI && host.ui.custom) {
         const catalog = commandResult.data && typeof commandResult.data === "object" && "entries" in commandResult.data
             ? commandResult.data as ReturnType<typeof presentCatalog> : undefined;
         const view = catalog ? undefined : commandResult.data as OperationView;
-        const entries = catalog ?? { entries: [view], diagnostics: commandResult.diagnostics, revision: "", text: "" };
+        const entries = catalog ?? { entries: [view!], diagnostics: commandResult.diagnostics, revision: "", text: "" };
         try {
             host.ui.setWidget?.("agents-catalog", undefined);
             await host.ui.custom<void>((tui, theme, _keys, done) =>
-                createCatalogComponent(entries, theme, () => tui.requestRender(), () => done(), view?.id), { overlay: true });
+                createCatalogComponent(entries, theme, () => tui.requestRender(), () => done(), view?.id, deps.sessionSettings ? {
+                    get: () => presentCatalog(readCatalog(location(host, deps)), deps.enrich),
+                    models: () => deps.editableModels?.() ?? [],
+                    settings: () => deps.sessionSettings!.snapshot(),
+                    change: (id, key, value) => deps.sessionSettings!.change(id, key, value),
+                    save(id) {
+                        const loc = location(host, deps);
+                        const saved = saveAgentSessionDefaults(loadCatalog(loc), id, deps.sessionSettings!.snapshot(), loc);
+                        if (saved.ok) {
+                            commandResult.wrote = true;
+                            commandResult.path = saved.path;
+                            commandResult.scope = saved.scope;
+                        }
+                        return { ok: saved.ok, message: saved.ok ? `Defaults saved (${saved.scope}): ${id}.` : saved.diagnostics.map((item) => item.message).join(" ") };
+                    },
+                } : undefined), { overlay: true });
+            if (deps.sessionSettings) {
+                const current = readCatalog(location(host, deps));
+                const refreshed = view ? presentCatalogEntry(current, view.id, deps.enrich) : presentCatalog(current, deps.enrich);
+                commandResult.data = refreshed;
+                commandResult.message = refreshed.text;
+            }
             return commandResult;
         } catch {
             // A non-interactive host may expose custom() without supporting overlays.

package/agent-session-settings.ts

@@ -0,0 +1,89 @@
+/** Branch-local catalog preferences. Null removes a definition's own value. */
+import { EFFORT_LEVELS, type CatalogDefinition, type PortablePreferences, type ThinkingLevel } from "./catalog-schema.ts";
+import { contentDigest, saveDefinition, type CatalogSnapshot, type LoadCatalogInput, type SaveResult } from "./catalog-store.ts";
+
+export const AGENT_SESSION_SETTINGS_ENTRY = "pi-better-subagents-agent-settings";
+export type AgentSettingKey = "model" | "effort";
+export type AgentSessionOverrides = Readonly<Record<string, Readonly<{ model?: string | null; effort?: ThinkingLevel | null }>>>;
+export interface AgentSessionContext {
+    sessionManager?: { getBranch?(): readonly unknown[] };
+}
+export interface AgentSessionSettings {
+    restore(ctx: AgentSessionContext): void;
+    snapshot(): AgentSessionOverrides;
+    change(id: string, key: AgentSettingKey, value: string | null): void;
+    clear(): void;
+}
+
+function valid(id: unknown, key: unknown, value: unknown): boolean {
+    return typeof id === "string" && /^(role|agent)\.[a-z0-9]+(?:[.-][a-z0-9]+)*$/.test(id) &&
+        (key === "model" || key === "effort") && (value === null || typeof value === "string" &&
+            (key === "model" ? /^[a-z0-9][a-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._+-]*$/.test(value)
+                : (EFFORT_LEVELS as readonly string[]).includes(value)));
+}
+
+/** The host must restore from the current context before constructing catalog hosts. */
+export function createAgentSessionSettings(pi: { appendEntry(customType: string, data: unknown): void }): AgentSessionSettings {
+    let overrides: AgentSessionOverrides = Object.freeze({});
+    const apply = (id: string, key: AgentSettingKey, value: string | null) => {
+        overrides = Object.freeze({ ...overrides, [id]: Object.freeze({ ...overrides[id], [key]: value }) });
+    };
+    return {
+        snapshot: () => overrides,
+        clear() { overrides = Object.freeze({}); },
+        restore(ctx) {
+            overrides = Object.freeze({});
+            const branch = ctx.sessionManager?.getBranch?.();
+            if (!Array.isArray(branch)) return;
+            for (const entry of branch) {
+                if (!entry || entry.type !== "custom" || entry.customType !== AGENT_SESSION_SETTINGS_ENTRY) continue;
+                const data = entry.data;
+                if (data?.version !== 1 || !valid(data.id, data.key, data.value)) continue;
+                apply(data.id, data.key, data.value);
+            }
+        },
+        change(id, key, value) {
+            if (!valid(id, key, value)) throw new Error("Choose a catalog id and a valid model or effort. Nothing changed.");
+            // Append first: a persistence failure must not become an ephemeral edit.
+            pi.appendEntry(AGENT_SESSION_SETTINGS_ENTRY, { version: 1, id, key, value });
+            apply(id, key, value);
+        },
+    };
+}
+
+/** Copy only preferences; never repair or bypass a catalog validation failure. */
+export function sessionPreferences(definition: CatalogDefinition, settings: AgentSessionOverrides = {}): PortablePreferences {
+    const own = { ...(definition.kind === "role" ? definition.defaults : definition.overrides) };
+    const patch = settings[definition.id];
+    for (const key of ["model", "effort"] as const) {
+        if (!patch || !Object.hasOwn(patch, key)) continue;
+        if (patch[key] === null) delete own[key];
+        else if (patch[key] !== undefined) Object.assign(own, { [key]: patch[key] });
+    }
+    return own;
+}
+
+/** A launch batch retains this immutable overlay, even if the UI changes later. */
+export function withAgentSessionSettings(snapshot: CatalogSnapshot, settings?: AgentSessionOverrides): CatalogSnapshot {
+    if (!settings || Object.keys(settings).length === 0) return snapshot;
+    const ordered = Object.fromEntries(Object.keys(settings).sort().map((id) => [id, Object.freeze({
+        ...(Object.hasOwn(settings[id]!, "model") ? { model: settings[id]!.model } : {}),
+        ...(Object.hasOwn(settings[id]!, "effort") ? { effort: settings[id]!.effort } : {}),
+    })]));
+    const digest = contentDigest(JSON.stringify([snapshot.digest, ordered]));
+    return Object.freeze({ ...snapshot, digest, revision: digest, sessionSettings: Object.freeze(ordered) });
+}
+
+/** Save selected own preferences only. Never flatten inherited role settings. */
+export function saveAgentSessionDefaults(snapshot: CatalogSnapshot, id: string, settings: AgentSessionOverrides, location: LoadCatalogInput): SaveResult {
+    const entry = snapshot.roles.get(id) ?? snapshot.agents.get(id);
+    if (!entry?.definition || !entry.structurallyValid || entry.duplicate) {
+        return { ok: false, diagnostics: [{ severity: "error", code: "agents-save", message: `Cannot save ${id}: repair the catalog definition first. Session edits are unchanged.`, blocking: true, structural: false }] };
+    }
+    const definition = structuredClone(entry.definition);
+    const preferences = sessionPreferences(definition, settings);
+    if (definition.kind === "role") definition.defaults = preferences;
+    else definition.overrides = preferences;
+    // The store validates and writes atomically, including trust and symlink checks.
+    return saveDefinition({ ...location, definition, scope: entry.scope === "project" ? "project" : "user", replace: entry.scope !== "bundled" });
+}

package/agents-catalog-tool.ts

@@ -6,6 +6,7 @@
 import { presentCatalog, presentCatalogEntry, type LaunchEnricher } from "./agent-inspection.ts";
 import { canonicalCatalogId } from "./catalog-schema.ts";
 import { defaultUserRoot, loadCatalog } from "./catalog-store.ts";
+import { withAgentSessionSettings, type AgentSessionOverrides, type AgentSessionSettings } from "./agent-session-settings.ts";
 
 type TypeModule = {
     Object: (value: unknown) => unknown;
@@ -19,6 +20,7 @@ export interface DiscoveryHost {
     userRoot: string;
     projectConfigDirName?: string;
     bundledRoot?: string;
+    sessionSettings?: AgentSessionOverrides;
 }
 
 export interface DiscoveryDeps {
@@ -26,6 +28,7 @@ export interface DiscoveryDeps {
     bundledRoot?: string;
     projectConfigDirName?: string;
     enrich?: LaunchEnricher;
+    sessionSettings?: AgentSessionSettings;
     resolveHost?: (ctx: { cwd: string; isProjectTrusted(): boolean }) => DiscoveryHost;
 }
 
@@ -67,15 +70,16 @@ export function agentsCatalogTool(Type: TypeModule, deps: DiscoveryDeps = {}) {
                 return toolError(`agents_catalog action must be list or inspect, got ${JSON.stringify(action ?? "")}. It does not create, import, reload, or launch. Nothing was written.`);
             }
             const host = resolveHost(ctx, deps);
+            const snapshot = withAgentSessionSettings(loadCatalog(host), host.sessionSettings ?? deps.sessionSettings?.snapshot());
             if (action === "list") {
-                const listed = presentCatalog(loadCatalog(host), deps.enrich);
+                const listed = presentCatalog(snapshot, deps.enrich);
                 return {
                     content: [{ type: "text" as const, text: listed.text }],
                     details: { action, wrote: false, revision: listed.revision, entries: listed.entries, diagnostics: listed.diagnostics },
                 };
             }
             if (!params.id?.trim()) return toolError("inspect needs a role name or agent id. Call agents_catalog with action list to see them. Nothing was written.");
-            const view = presentCatalogEntry(loadCatalog(host), canonicalCatalogId(params.id), deps.enrich);
+            const view = presentCatalogEntry(snapshot, canonicalCatalogId(params.id), deps.enrich);
             return {
                 content: [{ type: "text" as const, text: view.text }],
                 details: { action, wrote: false, view },

package/catalog-resolver.ts

@@ -18,6 +18,7 @@ import {
     type ThinkingLevel,
 } from "./catalog-schema.ts";
 import type { CatalogEntry, CatalogScope, CatalogSnapshot } from "./catalog-store.ts";
+import { sessionPreferences } from "./agent-session-settings.ts";
 
 export interface FieldValue<T> {
     value: T | null;
@@ -223,6 +224,7 @@ function resolveRole(snapshot: CatalogSnapshot, roleId: string): Resolution {
         return blockedEntry(snapshot, entry, entry.diagnostics);
     }
     const definition = entry.definition;
+    const preferences = sessionPreferences(definition, snapshot.sessionSettings);
     const launchable = entry.schemaLaunchable;
     const diagnostics = launchable
         ? [...entry.diagnostics]
@@ -245,9 +247,9 @@ function resolveRole(snapshot: CatalogSnapshot, roleId: string): Resolution {
             description: definition.description,
             instructionMode: "role",
             instructions: definition.body,
-            model: fieldFromRole(definition.defaults.model),
-            effort: fieldFromRole(definition.defaults.effort),
-            tier: fieldFromRole(definition.defaults.tier),
+            model: fieldFromRole(preferences.model),
+            effort: fieldFromRole(preferences.effort),
+            tier: fieldFromRole(preferences.tier),
             launchable,
             diagnostics,
             source: originOf(entry),
@@ -332,6 +334,8 @@ function baseEffective(
     } | undefined,
 ): EffectiveDefinition {
     const mode = agent.instructionMode;
+    const overrides = sessionPreferences(agent, snapshot.sessionSettings);
+    const defaults = inheritance ? sessionPreferences(inheritance.role, snapshot.sessionSettings) : {};
     const instructions = inheritance
         ? combineInstructions(inheritance.role.body, agent.body, mode)
         : agent.body;
@@ -343,9 +347,9 @@ function baseEffective(
         roleId: agent.roleId,
         instructionMode: mode,
         instructions,
-        model: inheritance ? inheritField(agent.overrides, inheritance.role.defaults, "model") : absentField(),
-        effort: inheritance ? inheritField(agent.overrides, inheritance.role.defaults, "effort") : absentField(),
-        tier: inheritance ? inheritField(agent.overrides, inheritance.role.defaults, "tier") : absentField(),
+        model: inheritance ? inheritField(overrides, defaults, "model") : absentField(),
+        effort: inheritance ? inheritField(overrides, defaults, "effort") : absentField(),
+        tier: inheritance ? inheritField(overrides, defaults, "tier") : absentField(),
         launchable: inheritance?.launchable ?? false,
         diagnostics,
         source: originOf(entry),

package/catalog-runtime.ts

@@ -23,6 +23,7 @@ import { allocateCatalogLabel } from "./catalog-identity.ts";
 import { resolveRoleAssignment, type RoleAssignment } from "./role-assignment.ts";
 import { configureTierPolicy, DEFAULT_TIER_POLICY, type TierPolicy, type TierSpec } from "./tier-policy.ts";
 import { canonicalAgentId, canonicalRoleId, shortRoleName, type Diagnostic, type ThinkingLevel } from "./catalog-schema.ts";
+import { withAgentSessionSettings, type AgentSessionOverrides } from "./agent-session-settings.ts";
 
 export interface CatalogHost {
     cwd: string;
@@ -38,6 +39,9 @@ export interface CatalogHost {
     select?: (title: string, options: string[]) => Promise<string | undefined>;
     /** Passed through only when the caller already has a registry root. Omitted in production. */
     registryDir?: string;
+    sessionSettings?: AgentSessionOverrides;
+    /** Live UI edits; read once when admitting a launch snapshot. */
+    getSessionSettings?: () => AgentSessionOverrides;
 }
 
 export interface CatalogJobFields {
@@ -142,17 +146,19 @@ export function noteCatalogHost(next: CatalogHost): void {
         foregroundModel: "foregroundModel" in next ? next.foregroundModel : previous?.foregroundModel,
         configuredDefaultModel: "configuredDefaultModel" in next ? next.configuredDefaultModel : previous?.configuredDefaultModel,
         tiers: "tiers" in next ? next.tiers : previous?.tiers,
+        sessionSettings: next.sessionSettings,
+        getSessionSettings: next.getSessionSettings,
     };
 }
 
 export function loadLaunchSnapshot(host: CatalogHost): CatalogSnapshot {
-    return loadCatalog({
+    return withAgentSessionSettings(loadCatalog({
         cwd: host.cwd,
         projectTrusted: host.projectTrusted,
         userRoot: host.userRoot ?? defaultUserRoot(),
         bundledRoot: host.bundledRoot,
         projectConfigDirName: host.projectConfigDirName,
-    });
+    }), host.getSessionSettings?.() ?? host.sessionSettings);
 }
 
 export function createLaunchEnricher(): LaunchEnricher {

package/catalog-store.ts

@@ -28,6 +28,7 @@ import {
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import type { AgentSessionOverrides } from "./agent-session-settings.ts";
 import {
     CATALOG_SCHEMA_VERSION,
     DiagnosticCodes,
@@ -108,6 +109,8 @@ export interface CatalogSnapshot {
     /** Same-scope duplicates. They occupy the id without selecting a filesystem-order winner. */
     blocked: readonly CatalogEntry[];
     diagnostics: readonly Diagnostic[];
+    /** Immutable, branch-local preferences; never written by loadCatalog. */
+    sessionSettings?: AgentSessionOverrides;
 }
 
 export interface SaveResult {

package/catalog-ui.ts

@@ -1,7 +1,17 @@
-import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { Input, SelectList, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { OperationField, OperationList, OperationView } from "./agent-inspection.ts";
+import { EFFORT_LEVELS } from "./catalog-schema.ts";
+import type { AgentSessionOverrides, AgentSettingKey } from "./agent-session-settings.ts";
 
-type Theme = { fg(color: string, text: string): string };
+type Theme = { fg(color: string, text: string): string; bg?(color: string, text: string): string; bold?(text: string): string; inverse?(text: string): string };
+
+export interface CatalogEditor {
+    get(): OperationList;
+    models(): readonly string[];
+    settings(): AgentSessionOverrides;
+    change(id: string, key: AgentSettingKey, value: string | null): void;
+    save(id: string): { ok: boolean; message: string };
+}
 
 function stateLabel(entry: OperationView): string {
     if (entry.launchable === false) return "blocked";
@@ -84,11 +94,65 @@ export function createCatalogComponent(
     requestRender: () => void,
     close: () => void,
     initialId?: string,
+    editor?: CatalogEditor,
 ) {
     let selectedId = initialId ?? catalog.entries[0]?.id;
-    let mode: "list" | "detail" | "prompt" = initialId ? "detail" : "list";
+    let mode: "list" | "detail" | "prompt" | "settings" = initialId ? "detail" : "list";
     let query = "";
     let scroll = 0;
+    let settingRow = 0;
+    let picker: SelectList | undefined;
+    let filterPicker: ((filter: string) => void) | undefined;
+    let pickerKey: AgentSettingKey | undefined;
+    const search = new Input();
+    let focused = false;
+    let message = "";
+    let error = false;
+    const highlight = (text: string, width: number) => theme.bg?.("selectedBg", theme.bold?.(cell(text, width)) ?? cell(text, width)) ?? theme.fg("accent", text);
+    function report(text: string, failed = false) { message = text; error = failed; requestRender(); }
+    function refresh() { if (editor) catalog = editor.get(); }
+    function save() {
+        if (!editor || !selected()) return;
+        try {
+            const result = editor.save(selected()!.id);
+            refresh();
+            report(result.message, !result.ok);
+        } catch (cause) { report(String(cause instanceof Error ? cause.message : cause), true); }
+    }
+    function edit() {
+        const current = selected();
+        if (!current || !editor) return;
+        if (!current.definitionValid) { report("Repair the catalog definition before editing.", true); return; }
+        const key: AgentSettingKey = settingRow === 0 ? "model" : "effort";
+        const values = key === "model" ? [...new Set([...(editor.models()), ...(current.fields?.model.value ? [current.fields.model.value] : [])])].sort() : [...EFFORT_LEVELS];
+        const items = [{ value: "", label: "Inherit" }, ...values.map((value) => ({ value, label: value }))];
+        pickerKey = key;
+        search.setValue("");
+        search.focused = focused && key === "model";
+        const pickerTheme: ConstructorParameters<typeof SelectList>[2] = {
+            selectedPrefix: (text) => theme.fg("accent", text),
+            selectedText: (text) => theme.inverse?.(text) ?? theme.fg("accent", text),
+            description: (text) => theme.fg("dim", text),
+            scrollInfo: (text) => theme.fg("dim", text),
+            noMatch: (text) => theme.fg("warning", text),
+        };
+        const onSelect = (item: { value: string }) => {
+            try {
+                editor.change(current.id, key, item.value || null);
+                refresh();
+                picker = undefined;
+                search.focused = false;
+                report("Session settings updated.");
+            } catch (cause) { report(cause instanceof Error ? cause.message : String(cause), true); }
+        };
+        filterPicker = (filter) => {
+            picker = new SelectList(items.filter((item) => item.label.toLowerCase().includes(filter.toLowerCase())), 12, pickerTheme);
+            picker.onCancel = () => { picker = undefined; search.focused = false; };
+            picker.onSelect = onSelect;
+        };
+        filterPicker("");
+        picker!.setSelectedIndex(Math.max(0, items.findIndex((item) => item.value === current.fields?.[key].value)));
+    }
     const filtered = () => catalog.entries.filter((entry) =>
         [entry.id, entry.identity.name, entry.identity.description, entry.role?.id]
             .some((value) => value?.toLowerCase().includes(query.toLowerCase())));
@@ -100,6 +164,8 @@ export function createCatalogComponent(
     let lastDetailWidth = 80;
 
     return {
+        get focused() { return focused; },
+        set focused(value: boolean) { focused = value; search.focused = value && !!picker && pickerKey === "model"; },
         render(width: number): string[] {
             const safeWidth = Math.max(1, width);
             lastDetailWidth = safeWidth;
@@ -109,9 +175,32 @@ export function createCatalogComponent(
             const detailLines = current ? detailRows(current, safeWidth) : [];
             const selectedIndex = rows.findIndex((entry) => entry.id === selectedId);
             const start = Math.max(0, Math.min(selectedIndex - 6, rows.length - 14));
-            const lines = mode !== "list" && current ? [
+            if (picker) return [
+                theme.fg("accent", `Agents / ${pickerKey}`), "",
+                ...(pickerKey === "model" ? search.render(safeWidth) : []),
+                ...picker.render(safeWidth),
+                ...(message ? [theme.fg(error ? "error" : "muted", message)] : []),
+            ].map(line);
+            const lines = mode === "settings" && current ? [
+                theme.fg("accent", `Agents / ${current.identity.name || current.id}`), "",
+                ...["Model", "Effort"].flatMap((label, index) => {
+                    const key = index === 0 ? "model" : "effort";
+                    const field = current.fields?.[key];
+                    const own = editor?.settings()[current.id];
+                    const ownSession = Object.hasOwn(own ?? {}, key);
+                    const roleSession = field?.inherited && Object.hasOwn(editor?.settings()[current.role?.id ?? ""] ?? {}, key);
+                    const origin = ownSession && own?.[key] === null ? "inherit / session" : ownSession ? "session" : roleSession ? "inherited / session" : field?.inherited ? "inherited" : "catalog";
+                    const value = `${field?.value ?? "(unset)"}  ${origin}`;
+                    const text = `${settingRow === index ? "> " : "  "}${label.padEnd(18)} ${value}`;
+                    if (safeWidth < 42) {
+                        const title = `${settingRow === index ? "> " : "  "}${label}`;
+                        return [settingRow === index ? highlight(title, safeWidth) : title, ...wrapLine(value, Math.max(1, safeWidth - 2)).map((line) => `  ${line}`)];
+                    }
+                    return [settingRow === index ? highlight(text, safeWidth) : text];
+                }),
+            ] : mode !== "list" && current ? [
                 theme.fg("accent", mode === "prompt" ? "Agents / prompt" : "Agents / inspect"),
-                theme.fg("dim", mode === "prompt" ? "← details  ·  ↑↓ scroll  ·  Esc close" : "p prompt  ·  ← list  ·  ↑↓ scroll  ·  Esc close"),
+                theme.fg("dim", mode === "prompt" ? "← details  ·  ↑↓ scroll  ·  Esc close" : `${editor ? "e settings  ·  " : ""}p prompt  ·  ← list  ·  ↑↓ scroll  ·  Esc close`),
                 "",
                 ...detailLines.slice(scroll, scroll + 22).map((text, i) =>
                     i === 0 && scroll === 0 ? theme.fg("accent", text) : text),
@@ -127,25 +216,37 @@ export function createCatalogComponent(
                     const active = selectedId === entry.id;
                     const marker = active ? "›" : " ";
                     const text = `${marker} ${catalogColumns(entry, safeWidth)}`;
-                    return active ? theme.fg("accent", text) : text;
+                    return active ? highlight(text, safeWidth) : text;
                 }),
                 ...(rows.length === 0 ? ["  No matching definitions"] : []),
                 ...(rows.length > 14 ? [theme.fg("dim", `  ${start + 1}-${Math.min(start + 14, rows.length)} of ${rows.length}`)] : []),
                 ...catalog.diagnostics.slice(0, 2).map((diagnostic) => theme.fg("warning", `! ${diagnostic.message}`)),
                 ...(catalog.diagnostics.length > 2 ? [theme.fg("warning", `! ${catalog.diagnostics.length - 2} more catalog diagnostics`)] : []),
             ];
+            if (editor && mode !== "prompt") lines.push("", theme.fg("dim", mode === "settings" ? "Up/Down Select · Enter Change · ctrl+s Save defaults · Esc Back" : "ctrl+s Save selected defaults"));
+            if (message) lines.push("", theme.fg(error ? "error" : "muted", message));
             return lines.map(line);
         },
         handleInput(data: string): void {
             const rows = filtered();
+            if (picker) {
+                if (pickerKey === "model" && !(["up", "down", "enter", "escape"] as const).some((key) => matchesKey(data, key))) {
+                    search.handleInput(data);
+                    filterPicker?.(search.getValue());
+                } else picker.handleInput(data);
+                requestRender();
+                return;
+            }
+            if (editor && matchesKey(data, "ctrl+s")) { save(); return; }
             if (matchesKey(data, "escape") || matchesKey(data, "left")) {
-                if (mode === "prompt") { mode = "detail"; scroll = 0; }
+                if (mode === "prompt" || mode === "settings") { mode = "detail"; scroll = 0; }
                 else if (mode === "detail") { mode = "list"; scroll = 0; }
                 else if (query) { query = ""; selectedId = catalog.entries[0]?.id; }
                 else { close(); return; }
             } else if (matchesKey(data, "up") || matchesKey(data, "down")) {
                 const delta = matchesKey(data, "down") ? 1 : -1;
-                if (mode !== "list" && selected()) scroll = Math.max(0, Math.min(detailRows(selected()!, lastDetailWidth).length - 1, scroll + delta));
+                if (mode === "settings") settingRow = Math.max(0, Math.min(1, settingRow + delta));
+                else if (mode !== "list" && selected()) scroll = Math.max(0, Math.min(detailRows(selected()!, lastDetailWidth).length - 1, scroll + delta));
                 else if (rows.length) selectedId = rows[Math.max(0, Math.min(rows.length - 1, rows.findIndex((entry) => entry.id === selectedId) + delta))]?.id;
             } else if (matchesKey(data, "enter") && mode === "list" && selected()) {
                 mode = "detail";
@@ -153,6 +254,11 @@ export function createCatalogComponent(
             } else if ((data === "p" || data === "P") && mode === "detail" && selected()) {
                 mode = "prompt";
                 scroll = 0;
+            } else if (editor && (data === "e" || data === "E") && mode === "detail" && selected()) {
+                mode = "settings";
+                settingRow = 0;
+            } else if (mode === "settings" && (matchesKey(data, "enter") || data === " ")) {
+                try { edit(); } catch (cause) { report(cause instanceof Error ? cause.message : String(cause), true); }
             } else if (mode === "list" && matchesKey(data, "backspace")) {
                 query = query.slice(0, -1);
                 selectedId = filtered()[0]?.id;
@@ -162,6 +268,6 @@ export function createCatalogComponent(
             }
             requestRender();
         },
-        invalidate() {},
+        invalidate() { picker?.invalidate(); search.invalidate(); },
     };
 }

package/config.ts

@@ -21,7 +21,7 @@ export interface SubagentConfig extends TimingSettings {
     delegationMode?: DelegationMode | null;
     defaultModel?: string | null;
     defaultTools?: string | null;
-    /** Max subagents allowed to run at once. */
+    /** Default concurrency cap; /subagents cap overrides it for the current session. */
     maxConcurrent?: number | null;
     /**
      * Tool name → extension package(s) that provide it. Drives which extension
@@ -74,6 +74,14 @@ export interface SubagentConfig extends TimingSettings {
 /** Concurrency cap when config.json sets none. */
 export const DEFAULT_MAX_CONCURRENT = 4;
 
+export function isConcurrencyCap(value: unknown): value is number {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+export function normalizeConcurrencyCap(value: unknown): number {
+    return isConcurrencyCap(value) ? value : DEFAULT_MAX_CONCURRENT;
+}
+
 /** Built-in default tool set when config.json sets nothing. */
 export const SAFE_DEFAULT_TOOLS = "read, bash, edit, write, web_search, web_fetch";
 /** Safe default for a hermetic (clean) child where extension tools don't exist. */
@@ -123,6 +131,25 @@ export function writeDelegationMode(mode: DelegationMode, path = configPath()):
     if (path === configPath()) cached = current;
 }
 
+/** Save human-facing defaults together, preserving unrelated configuration. */
+export function writeSubagentSettings(settings: { delegationMode: DelegationMode; maxConcurrent: number }, path = configPath()): void {
+    if (!isDelegationMode(settings.delegationMode)) throw new Error("Invalid delegation mode.");
+    if (!isConcurrencyCap(settings.maxConcurrent)) throw new Error("Concurrent subagents must be a positive whole number.");
+    let current: Record<string, unknown> = {};
+    try {
+        const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Config must be a JSON object.");
+        current = parsed as Record<string, unknown>;
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    Object.assign(current, settings);
+    const pending = `${path}.${process.pid}.tmp`;
+    writeFileSync(pending, `${JSON.stringify(current, null, 2)}\n`);
+    renameSync(pending, path);
+    if (path === configPath()) cached = current as SubagentConfig;
+}
+
 /** Normalize a comma/space tool list to pi's bare comma form: "a, b" → "a,b". */
 export function normalizeTools(list: string): string {
     return list.split(",").map((t) => t.trim()).filter(Boolean).join(",");

package/delegation.ts

@@ -1,5 +1,7 @@
 export type DelegationMode = "manual" | "adaptive" | "coordinator";
 
+export const DELEGATION_MODES = ["manual", "adaptive", "coordinator"] as const;
+
 export const DELEGATION_MODE_REQUEST = "pi-better-subagents:delegation-mode-request";
 
 export function isDelegationMode(value: unknown): value is DelegationMode {

package/docs/agent-catalog-lifecycle.md

@@ -39,3 +39,26 @@ Navigator rows keep the display name, model, and effort. Details include the run
 ## Inspection
 
 The extension registers `/agents` and `agents_catalog` through `createAgentOperations`. The launch enricher calls `assessCatalog` / `assessSelection` with the current model registry, project trust, and user catalog root. It reports the existing spawn controls and `grantedByCatalog: false`. If the registry or snapshot is not the one just loaded, launchability stays unknown instead of being reported as launchable.
+
+## Session Settings
+
+`createAgentSessionSettings` restores model and effort overrides from the active
+Pi session branch. The extension restores before catalog-dependent work and on
+`session_start` and `session_tree`; switch and shutdown clear transient state
+without appending reset entries. Edits survive reload, resume, and fork, while
+new sessions start from catalog defaults.
+
+The catalog host supplies a live `getSessionSettings` getter so inspection
+reflects edits made while the overlay is open. `loadLaunchSnapshot` reads that
+getter once and freezes the overlay for each batch. Later edits cannot alter
+already-admitted jobs. Model choices come from the current Pi model registry.
+
+Ctrl+S saves only the selected definition's own preferences, never flattened
+inherited settings. Bundled roles are copied to user scope; existing user and
+project definitions are saved in their own scope with the store's trust,
+validation, and atomic-write checks. Plain `loadCatalog` remains disk-only so
+saving selects the current winning definition rather than a stale overlay.
+
+Headless callers can inject a session controller or immutable
+`CatalogHost.sessionSettings`. Hosts without these hooks retain inspection-only
+UI and the prior launch behavior.