pi-better-subagents 0.12.0 → 0.13.0

package/README.md

@@ -38,7 +38,8 @@ Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or ne
 `config.json` sets `delegationMode` to `manual`, `adaptive` (default), or
 `coordinator`. `/subagents settings` (or `/subagents`) opens a settings page
 for delegation mode and the concurrent-subagent cap (default 4). Edits apply to
-this session; Save as defaults persists both, and Reset to defaults clears
+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

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/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.

package/docs/agent-catalog-operations.md

@@ -6,7 +6,17 @@ Commands, the read-only discovery tool, and the Codex importer for `pi-agent/v1`
 
 `/agents` is one Pi command. Dialogs use `ctx.ui.select`, `confirm`, `input`, and `editor`. `ctx.hasUI` is false in print and JSON mode. When a choice or confirmation is required there, the command returns `clarification-needed` and writes nothing.
 
-In an interactive TUI, `/agents list` and `/agents show` open a focused catalog view instead of leaving the listing in a persistent widget. Rows align name, effective model, source, and launch state; narrow terminals retain name and model. The model is the resolved actual model when available, otherwise the requested or inherited preference, or `not resolved`. Type to filter by id, name, description, or base role; use Up/Down and Enter to inspect. The detail view puts launchability and its reason first, then source, inherited/overridden settings, and diagnostics. Press `p` in detail to read the complete effective instructions (role plus agent in add mode, agent text in replace mode); this is not the task-specific launch prompt. Up/Down scrolls detail or prompt; Left or Escape returns to detail, then list, clears the filter, then closes. `/agents show <id>` opens that definition directly. Print/JSON callers still receive the complete text and structured result.
+In an interactive TUI, `/agents`, `/agents list`, and `/agents show` open a focused catalog view instead of leaving the listing in a persistent widget. Rows align name, effective model, source, and launch state; narrow terminals retain name and model. The model is the resolved actual model when available, otherwise the requested or inherited preference, or `not resolved`. Type to filter by id, name, description, or base role; use Up/Down and Enter to inspect. The detail view puts launchability and its reason first, then source, inherited/overridden settings, and diagnostics. Press `p` in detail to read the complete effective instructions (role plus agent in add mode, agent text in replace mode); this is not the task-specific launch prompt. Up/Down scrolls detail or prompt; Left or Escape returns to detail, then list, clears the filter, then closes. `/agents show <id>` opens that definition directly. Print/JSON callers still receive the complete text and structured result; bare `/agents` still returns help outside the custom TUI.
+
+### Model and effort edits
+
+When lifecycle supplies `sessionSettings`, press `e` in detail to edit Model or Effort. Up/Down selects the setting and Enter opens its choices. Model choices come from the foreground registry, plus the current preference if unavailable; type to filter model names. Effort choices use the existing catalog effort levels. Escape cancels an unselected choice. Only these two fields are editable; instructions, base role, tier, and execution controls are unchanged.
+
+A selected value immediately appends a custom entry to the current session branch. It does not write a catalog file. Reloading the extension or session restores the active branch's edits. Branches share their common ancestor settings but subsequent edits do not cross to siblings. Role edits flow into named agents that inherit that field. Choosing `Inherit` removes the selected definition's own value, including a saved agent override, instead of storing an explicit null preference. For a role with no parent, that removes its default. Later role/file edits remain live.
+
+Ctrl+S in list, detail, or settings (or Enter on Save as defaults) explicitly saves the selected definition's own model and effort changes. It never copies inherited role fields into an agent. Existing personal/project definitions stay in their winning scope; a bundled definition becomes a personal whole-definition shadow copy, leaving the package file untouched. Project trust, duplicate/invalid-definition checks, validation, and atomic catalog writes still apply. Both successful and failed saves leave branch edits intact. A failed save reports the error without changing the catalog defaults.
+
+New launches and `agents_catalog` discovery use the same session overlay. Explicit per-run model/effort choices still win, a batch retains one immutable snapshot, and active/completed runs do not change. Role effort remains an inherited default with the existing nearest-supported adjustment; named-agent effort remains explicit and blocks when unsupported. The lifecycle wiring required to enable this surface is in [agent-catalog-lifecycle.md](./agent-catalog-lifecycle.md#session-settings-integration).
 
 | Invocation | Effect |
 | --- | --- |

package/docs/usage.md

@@ -18,8 +18,10 @@ Set `delegationMode` in this package's `config.json` to `manual`, `adaptive`, or
 `coordinator` (default `adaptive`). This controls foreground delegation guidance,
 not child permissions or catalog definitions. `/subagents settings` (or simply
 `/subagents`) opens the terminal settings page with mode and concurrent-subagent
-cap controls, saved defaults, Save as defaults, and Reset to defaults. Changes
-apply immediately to this session; Escape closes the page without undoing them.
+cap controls and Reset to defaults. The page uses the same selected-row and
+active-cell styling as `/sandbox`, with one editable value column.
+Edits automatically persist for this session, including across reloads; Escape
+closes the page without undoing them.
 Enter edits the cap as a positive whole number; Escape cancels an unfinished edit.
 Ctrl+S saves both settings as defaults. Sandbox permissions remain in `/sandbox`.
 

package/index.ts

@@ -146,6 +146,7 @@ import {
 import { enforceRegistrySizeCapOnce, runDailyCleanupOnce } from "./cleanup.ts";
 import { assertThinkingLevel, parseModelThinking, type ThinkingLevel } from "./thinking.ts";
 import { createAgentOperations } from "./agent-operations.ts";
+import { createAgentSessionSettings } from "./agent-session-settings.ts";
 import {
     clarifyCatalogRequest,
     createLaunchEnricher,
@@ -1498,6 +1499,8 @@ function catalogRoleSchema(purpose: string) {
 }
 
 export default function (pi: ExtensionAPI) {
+    const agentSessionSettings = createAgentSessionSettings(pi);
+    let catalogModelRegistry: ExtensionContext["modelRegistry"] | undefined;
     let delegationOverride: DelegationMode | undefined;
     let capOverride: number | undefined;
     const activeConcurrencyCap = (): number => capOverride ?? normalizeConcurrencyCap(loadConfig().maxConcurrent);
@@ -1588,8 +1591,12 @@ export default function (pi: ExtensionAPI) {
     }
 
     function catalogHostFrom(ctx: ExtensionContext): CatalogHost {
+        if (typeof ctx.sessionManager?.getBranch === "function") agentSessionSettings.restore(ctx);
+        catalogModelRegistry = ctx.modelRegistry;
         const cfg = loadConfig();
         return {
+            sessionSettings: agentSessionSettings.snapshot(),
+            getSessionSettings: () => agentSessionSettings.snapshot(),
             cwd: ctx.cwd,
             projectTrusted: typeof ctx.isProjectTrusted === "function" ? ctx.isProjectTrusted() : false,
             userRoot: defaultUserRoot(),
@@ -2245,6 +2252,8 @@ export default function (pi: ExtensionAPI) {
 
     const agentOperations = createAgentOperations({
         projectConfigDirName,
+        sessionSettings: agentSessionSettings,
+        editableModels: () => catalogModelRegistry?.getAvailable().map((model) => `${model.provider}/${model.id}`) ?? [],
         propagateCommandContext(commandCtx) {
             noteCatalogHost(catalogHostFrom(commandCtx));
         },
@@ -2255,6 +2264,7 @@ export default function (pi: ExtensionAPI) {
                 hasUI: full.hasUI === true,
                 model: full.model,
                 modelRegistry: full.modelRegistry,
+                sessionManager: full.sessionManager,
                 ui: full.ui ?? { select: async () => undefined },
                 isProjectTrusted: () => full.isProjectTrusted(),
             } as ExtensionContext));
@@ -2263,6 +2273,7 @@ export default function (pi: ExtensionAPI) {
                 projectTrusted: full.isProjectTrusted(),
                 userRoot: defaultUserRoot(),
                 projectConfigDirName,
+                sessionSettings: agentSessionSettings.snapshot(),
             };
         },
         enrich: createLaunchEnricher(),
@@ -2367,6 +2378,8 @@ export default function (pi: ExtensionAPI) {
     });
 
     pi.on("session_tree", async (_event, ctx) => {
+        agentSessionSettings.restore(ctx);
+        try { noteCatalogHost(catalogHostFrom(ctx)); } catch { /* catalog inspection stays undecided */ }
         restoreDelegationMode(ctx);
     });
 
@@ -2374,6 +2387,7 @@ export default function (pi: ExtensionAPI) {
     // alive, resume the ticking widget. Deferred out of the factory per pi's
     // "no background resources at load" rule.
     pi.on("session_start", async (_event, ctx) => {
+        agentSessionSettings.restore(ctx);
         restoreDelegationMode(ctx);
         uiCtx = ctx;
         try { noteCatalogHost(catalogHostFrom(ctx)); } catch { /* catalog inspection stays undecided */ }
@@ -2413,6 +2427,8 @@ export default function (pi: ExtensionAPI) {
     });
 
     pi.on("session_before_switch", () => {
+        agentSessionSettings.clear();
+        catalogModelRegistry = undefined;
         activeCallbackOrigin = undefined;
         cancelCallbackBatch(pi);
         mainAgentStartedAt = undefined;
@@ -2426,6 +2442,8 @@ export default function (pi: ExtensionAPI) {
         // running/orphaned children before dropping the session origin, so they
         // cannot become live process groups with no coordinator.
         stopCurrentSessionSubagents(ctx);
+        agentSessionSettings.clear();
+        catalogModelRegistry = undefined;
         activeCallbackOrigin = undefined;
         if (typeof unsubscribeDelegationRequest === "function") unsubscribeDelegationRequest();
         cancelCallbackBatch(pi);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",

package/settings-page.ts

@@ -20,7 +20,12 @@ export interface SubagentSettingsHandlers {
     reset(): void;
 }
 
-const labels = ["Delegation mode", "Concurrent subagents", "Save as defaults", "Reset to defaults"];
+const labels = ["Delegation mode", "Concurrent subagents", "Reset to defaults"];
+
+function cell(text: string, width: number): string {
+    const clipped = Tui.truncateToWidth(text, width, "");
+    return clipped + " ".repeat(Math.max(0, width - Tui.visibleWidth(clipped)));
+}
 
 export function createSubagentSettingsPage(
     theme: Theme,
@@ -52,9 +57,6 @@ export function createSubagentSettingsPage(
                 input.handleInput("\x05");
                 input.focused = focused;
                 report("");
-            } else if (row === 2) {
-                const result = handlers.save();
-                report(result.message, !result.ok);
             } else {
                 handlers.reset();
                 report("Session settings reset to saved defaults.");
@@ -98,31 +100,41 @@ export function createSubagentSettingsPage(
             else if (Tui.matchesKey(data, Tui.Key.down)) row = Math.min(labels.length - 1, row + 1);
             else if (Tui.matchesKey(data, Tui.Key.enter) || data === " ") action();
             else if (Tui.matchesKey(data, "ctrl+s")) {
-                const selected = row;
-                row = 2;
-                action();
-                row = selected;
+                const result = handlers.save();
+                report(result.message, !result.ok);
             }
             requestRender();
         },
         render(width: number) {
             const settings = handlers.get();
-            const values = [
-                `${settings.mode} (${settings.modeSource})`,
-                `${settings.maxConcurrent} (${settings.capSource})`,
-                "",
-                "",
-            ];
-            const lines = [theme.fg("accent", theme.bold("Subagent settings")), ""];
+            const w = Math.max(1, Math.floor(width));
+            const compact = w < 40;
+            const labelWidth = 26;
+            const valueWidth = Math.max(1, w - labelWidth - 1);
+            const current = [settings.mode, String(settings.maxConcurrent)];
+            const highlight = (text: string, selected: boolean): string => selected
+                ? theme.bg("selectedBg", theme.bold(cell(text, w))) : text;
+            const marker = (selected: boolean) => selected ? "> " : "  ";
+            const lines: string[] = [theme.fg("accent", theme.bold("  Subagent settings")), ""];
             labels.forEach((label, index) => {
-                const text = `${index === row ? ">" : " "} ${label}${values[index] ? `: ${values[index]}` : ""}`;
-                lines.push(index === row ? theme.fg("accent", theme.bold(text)) : text);
+                const selected = index === row;
+                if (index === 2) lines.push("");
+                const title = theme.fg(selected ? "accent" : "text", marker(selected) + label);
+                if (index >= 2) {
+                    lines.push(highlight(title, selected));
+                } else if (compact) {
+                    lines.push(highlight(title, selected));
+                    const active = editing && index === 1 ? input.render(Math.max(1, w - 2))[0]! : current[index]!;
+                    lines.push("  " + (selected && !editing ? theme.inverse(active) : active));
+                } else {
+                    const active = editing && index === 1 ? input.render(valueWidth)[0]! : cell(current[index]!, valueWidth);
+                    lines.push(highlight(cell(title, labelWidth) + " " +
+                        (selected && !editing ? theme.inverse(active) : theme.fg("text", active)), selected));
+                }
             });
-            if (editing) lines.push("", ...input.render(Math.max(1, width)));
-            lines.push("", theme.fg("muted", `Saved defaults: ${settings.defaultMode}, cap ${settings.defaultCap}`));
-            if (message) lines.push(theme.fg(error ? "error" : "success", message));
-            lines.push("", theme.fg("dim", editing ? "Enter apply  Esc cancel" : "Up/Down select  Enter change  Ctrl+S save  Esc close"));
-            return lines.map((line) => Tui.truncateToWidth(line, Math.max(1, width), ""));
+            if (message) lines.push("", theme.fg(error ? "error" : "muted", message));
+            lines.push("", theme.fg("dim", editing ? "Enter Apply · Esc Cancel" : "Up/Down Select · Space/Enter Change · ctrl+s Save default · Esc Back"));
+            return lines.map((line) => Tui.truncateToWidth(line, w, ""));
         },
     };
 }