pi-better-harness 0.16.0 → 0.17.0

package/node_modules/pi-better-sandbox/README.md

@@ -11,7 +11,8 @@ pi install npm:pi-better-sandbox
 Either way you keep starting Pi the way you always have — `pi`. There is
 no launcher or wrapper command. Main starts inactive; Subagents start confined.
 Open `/sandbox` to change either column, or use `/sandbox on` for the current
-Main session. **Save as defaults** persists both profiles.
+Main session. Edits apply immediately and are saved to the current session branch.
+**Ctrl+S** saves both profiles as defaults for new sessions.
 
 ```text
 Sandbox permissions               Main             Subagents
@@ -31,8 +32,7 @@ Network access                    -                On
     > [x] @juicesharp/rpiv-web-tools  2/2
     > [ ] <other installed package>  0/1
 
-↑↓ Select row   ←→ Select column / expand / collapse   Enter Fold   Space Change
-Save as defaults
+↑↓ Select · ←→ Column/fold · Space Toggle · ctrl+s Save default · Enter Fold · Esc Back
 ```
 
 **Subagents · Tools** picks the extension tools a confined subagent may use:
@@ -56,7 +56,7 @@ are; the count is selected/total. Right expands a group. Left collapses a group,
 or moves from a child to its parent and collapses it. Enter folds the selected
 group. Space on a group selects all children when none or only some are selected,
 or deselects them all when all are selected. Every toggle applies on one Space;
-saving looser defaults still needs a second Enter. Only individual tool
+Ctrl+S saves defaults and reports anything loosened. Only individual tool
 entries are saved, never a package/provider wildcard or the open/closed state.
 
 Defaults: `apply_patch`, `web_fetch`, and `web_search` on; everything else off.
@@ -123,7 +123,7 @@ Write, those paths are also protected from removal and renaming.
 Space applies every change immediately, including higher permission levels,
 capabilities switched on, and a sandbox switched off. `ctrl+s` saves the
 defaults from any row on the first press, and the note names anything that
-loosened. Enter on the Save row still saves. The focused
+loosened. Enter only folds tool groups; it never saves defaults. The focused
 row has a full-width background and bold text; the selected Main/Subagents cell
 also uses inverse styling. No model
 tool can change these settings. Other rows toggle Off/On. Detail cells under an
@@ -319,7 +319,7 @@ in your rule set but is held out in that project, with a message saying so.
 Nothing is migrated on disk. A saved `pi-better-sandbox-permissions.json` keeps
 its values: a saved `read-write` is now shown as Write & delete, and a saved
 Subagents Outside project = Read stays Read. Only a fresh configuration, or
-**Save as defaults** after you choose Write, uses the new Subagents default. To
+**Ctrl+S** after you choose Write, uses the new Subagents default. To
 adopt it, open `/sandbox`, set Subagents → Outside project to Write, and save.
 
 `~/.pi/agent/sandbox.json` (`filesystem.allowWrite`, `allowRead`,
@@ -328,12 +328,19 @@ package never reads it, and it has no effect on the harness.
 
 ## Lifecycle
 
-The foreground sandbox is inactive by default. Session overrides do not survive
-startup, new session, resume, fork, or reload. Save as defaults writes both
+The foreground sandbox is inactive by default. Permission edits, including
+Sandbox switches and `/sandbox on|off`, auto-persist as Pi custom entries on the
+current session branch, not as global defaults. Resume, fork, reload and session
+tree navigation restore the latest policy on the active branch. A branch with
+no permission entry and a new session inherit saved global settings. Invalid
+persisted session policy fails closed rather than falling back to defaults.
+Ctrl+S writes both
 profiles to `~/.pi/agent/extensions/pi-better-sandbox-permissions.json` (or the
 corresponding `$PI_CODING_AGENT_DIR`). Existing activation preferences in
 `pi-better-sandbox-preferences.json` migrate when no profile file exists.
 `/sandbox default on|off` remains available and updates Main's saved switch.
+Failed default saves leave the current session's edits intact. Write-deny rules
+retain their separate global persistence through `/sandbox deny` and `/sandbox rules`.
 
 Toggles apply to operations launched after the change. A command already running
 keeps the policy it launched with.

package/node_modules/pi-better-sandbox/commands.ts

@@ -55,8 +55,8 @@ const DISABLE_TITLE = "Disable the foreground write sandbox?";
 
 const DISABLE_MESSAGE = [
     "The built-in bash, write, and edit tools and user-entered ! / !! commands",
-    "will run with normal host write access for the rest of this session. The",
-    "next session applies your persisted foreground sandbox default.",
+    "will run with normal host write access on this session branch, including",
+    "after resume or reload. New sessions apply your saved sandbox default.",
 ].join("\n");
 
 const NO_UI_REJECTION =
@@ -80,6 +80,8 @@ export type SandboxCommandDeps = {
     onStateChange: (status: ForegroundSandboxStatus) => void;
     /** Persist a default and apply it to the current session. */
     setDefault: (enabled: boolean) => ForegroundSandboxStatus;
+    /** Persist the session change before mutating enforcement. */
+    setSessionEnabled?: (enabled: boolean) => ForegroundSandboxStatus;
     openPermissions?: (ctx: ExtensionCommandContext) => Promise<void>;
 };
 
@@ -89,6 +91,7 @@ export function createSandboxCommandHandler({
     denyRules,
     onStateChange,
     setDefault,
+    setSessionEnabled,
     openPermissions,
 }: SandboxCommandDeps) {
     return async function handleSandboxCommand(
@@ -112,7 +115,12 @@ export function createSandboxCommandHandler({
         }
 
         if (subcommand === "on") {
-            const status = controller.enable();
+            let status: ForegroundSandboxStatus;
+            try { status = setSessionEnabled ? setSessionEnabled(true) : controller.enable(); }
+            catch (error) {
+                ctx.ui.notify(`Sandbox state unchanged: ${error instanceof Error ? error.message : String(error)}`, "error");
+                return;
+            }
             onStateChange(status);
             ctx.ui.notify(
                 status.state === "enabled"
@@ -140,7 +148,12 @@ export function createSandboxCommandHandler({
                 ctx.ui.notify("Foreground sandbox left on.", "info");
                 return;
             }
-            const status = controller.disable();
+            let status: ForegroundSandboxStatus;
+            try { status = setSessionEnabled ? setSessionEnabled(false) : controller.disable(); }
+            catch (error) {
+                ctx.ui.notify(`Sandbox state unchanged: ${error instanceof Error ? error.message : String(error)}`, "error");
+                return;
+            }
             onStateChange(status);
             ctx.ui.notify(
                 "Foreground sandbox OFF for this session. Shell commands can now write anywhere.",

package/node_modules/pi-better-sandbox/index.ts

@@ -38,6 +38,7 @@ import { writeSandboxDefault } from "./preferences.ts";
 import { readPermissionSettings, writePermissionSettings } from "./permission-settings.ts";
 import { defaultSandboxPermissions, describeLoosening, type SandboxPermissionSettings } from "./permissions.ts";
 import { openPermissionsPage } from "./permissions-page.ts";
+import { appendSessionPermissions, readSessionPermissions } from "./session-permissions.ts";
 
 import { footerTone, formatFooterStatus } from "./status.ts";
 import { ForegroundSandboxController, type ForegroundSandboxStatus } from "./state.ts";
@@ -98,9 +99,7 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
     // `/sandbox deny ...` and the `/sandbox rules` page.
     const denyRules = new DenyRuleManager({ controller, onStateChange: announce });
 
-    pi.on("session_start", (_event, ctx: ExtensionContext) => {
-        shellPath = resolveShellPath(ctx.cwd);
-        boundary.register(ctx.cwd);
+    const restorePermissions = (ctx: ExtensionContext): void => {
         paintFooter = (status) => {
             ctx.ui.setStatus(
                 FOOTER_KEY,
@@ -108,11 +107,14 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
             );
         };
 
-        // Re-read saved profiles on each session. Malformed policy blocks protected
-        // operations rather than silently widening a restricted session.
+        // Session policy takes precedence over global defaults. Never skip an
+        // invalid latest entry to recover an older, potentially broader policy.
         let settings = defaultSandboxPermissions();
+        let hasSessionPolicy = false;
         try {
-            settings = readPermissionSettings();
+            const sessionPermissions = readSessionPermissions(ctx);
+            hasSessionPolicy = sessionPermissions !== undefined;
+            settings = sessionPermissions ?? readPermissionSettings();
         } catch (error) {
             controller.beginSession(ctx.cwd, true);
             const message = `Sandbox permissions could not be loaded: ${error instanceof Error ? error.message : String(error)}`;
@@ -130,7 +132,7 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
             .map((tool) => tool.sourceInfo?.path).filter((path): path is string => typeof path === "string" && isAbsolute(path))
             .map(runtimeCodeRoot));
         controller.setPermissionSettings(settings);
-        controller.applyDefault(settings.main.enabled);
+        if (!hasSessionPolicy) controller.applyDefault(settings.main.enabled);
 
         // Then the rules are re-read and re-resolved, because the same global
         // template set means different absolute paths in a different project.
@@ -154,7 +156,14 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
                 status.state === "disabled" ? "info" : "warning",
             );
         }
+    };
+
+    pi.on("session_start", (_event, ctx) => {
+        shellPath = resolveShellPath(ctx.cwd);
+        boundary.register(ctx.cwd);
+        restorePermissions(ctx);
     });
+    pi.on("session_tree", (_event, ctx) => restorePermissions(ctx));
 
     pi.on("session_shutdown", () => {
         controller.dispose();
@@ -167,11 +176,18 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
             controller,
             denyRules,
             onStateChange: announce,
+            setSessionEnabled: (enabled) => {
+                const settings = controller.permissionSettings() ?? defaultSandboxPermissions();
+                settings.main.enabled = enabled;
+                appendSessionPermissions(pi, settings);
+                return enabled ? controller.enable() : controller.disable();
+            },
             setDefault: (enabled) => {
                 const settings = controller.permissionSettings() ?? defaultSandboxPermissions();
                 settings.main.enabled = enabled;
                 writePermissionSettings(settings);
                 writeSandboxDefault(enabled ? "on" : "off");
+                appendSessionPermissions(pi, settings);
                 return controller.setPermissionSettings(settings);
             },
             openPermissions: async (ctx) => {
@@ -179,9 +195,12 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
                     getConfig: () => controller.permissionSettings() ?? defaultSandboxPermissions(),
                     // Trusted-tool candidates: what this Pi has actually registered, by owning package.
                     discoverTools: () => discoverTrustedTools(pi.getAllTools?.() ?? []),
-                    change: (settings) => announce(controller.setPermissionSettings(settings)),
+                    change: (settings) => {
+                        appendSessionPermissions(pi, settings);
+                        announce(controller.setPermissionSettings(settings));
+                    },
                     save: (settings) => writePermissionSettings(settings),
-                    // Persisting a looser default needs a second, explicit Enter.
+                    // Report every capability loosened by saving these defaults.
                     loosening: (settings) => {
                         let previous: SandboxPermissionSettings;
                         try { previous = readPermissionSettings(); } catch { previous = defaultSandboxPermissions(); }

package/node_modules/pi-better-sandbox/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-sandbox",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Pi extension with independent Main and Subagents permission profiles, file guards, and OS sandbox enforcement.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-sandbox/permissions-page.ts

@@ -124,7 +124,7 @@ export function createPermissionsPage(
     const itemKey = (item: ToolItem) => item.kind === "group" ? item.id
         : item.kind === "guarded" ? "apply_patch" : JSON.stringify([item.name, item.package]);
     let items = toolItems();
-    const saveRow = () => rows.length + items.length;
+    const lastRow = () => rows.length + items.length - 1;
     let row = 0;
     let column = 0;
     let busy = false;
@@ -136,7 +136,7 @@ export function createPermissionsPage(
     }
 
     async function change(): Promise<void> {
-        if (!settings || busy || row === saveRow()) return;
+        if (!settings || busy) return;
         const next = snapshot(settings);
         if (row >= rows.length) {
             const item = items[row - rows.length]!;
@@ -173,15 +173,14 @@ export function createPermissionsPage(
         busy = true;
         try {
             await handlers.change(snapshot(next));
-            const selected = row >= rows.length && row < saveRow() ? items[row - rows.length] : undefined;
-            const wasSave = row === saveRow();
+            const selected = row >= rows.length ? items[row - rows.length] : undefined;
             const successors = selected ? items.slice(row - rows.length + 1).map(itemKey) : [];
             settings = next;
             items = toolItems();
             const index = selected ? items.findIndex((item) => itemKey(item) === itemKey(selected)) : -1;
             const successor = successors.map((key) => items.findIndex((item) => itemKey(item) === key)).find((at) => at >= 0);
-            row = wasSave ? saveRow() : index >= 0 ? rows.length + index
-                : successor !== undefined ? rows.length + successor : Math.min(row, saveRow());
+            row = index >= 0 ? rows.length + index
+                : successor !== undefined ? rows.length + successor : Math.min(row, lastRow());
             message = "";
             isError = false;
             requestRender();
@@ -215,7 +214,7 @@ export function createPermissionsPage(
     }
 
     function fold(open?: boolean): void {
-        const item = row >= rows.length && row < saveRow() ? items[row - rows.length] : undefined;
+        const item = row >= rows.length ? items[row - rows.length] : undefined;
         const id = item?.kind === "group" ? item.id : item?.kind === "trusted" && open === false ? item.group : undefined;
         if (!id) return;
         if (open ?? !expanded.has(id)) expanded.add(id);
@@ -234,22 +233,20 @@ export function createPermissionsPage(
                 row = Math.max(0, row - 1);
                 requestRender();
             } else if (matchesKey(data, Key.down)) {
-                row = Math.min(saveRow(), row + 1);
+                row = Math.min(lastRow(), row + 1);
                 requestRender();
             } else if (matchesKey(data, Key.left)) {
-                if (row >= rows.length && row < saveRow()) fold(false);
+                if (row >= rows.length) fold(false);
                 else column = 0;
                 requestRender();
             } else if (matchesKey(data, Key.right)) {
-                if (row >= rows.length && row < saveRow()) fold(true);
+                if (row >= rows.length) fold(true);
                 else column = 1;
                 requestRender();
             } else if (matchesKey(data, Key.space)) {
                 void change();
             } else if (matchesKey(data, "ctrl+s")) {
                 void save();
-            } else if (matchesKey(data, Key.enter) && row === saveRow()) {
-                void save();
             } else if (matchesKey(data, Key.enter)) {
                 fold();
             }
@@ -315,13 +312,13 @@ export function createPermissionsPage(
                 output.push(theme.fg("dim", truncateToWidth(`${prefix ? "  " : ""}  Trusted (runs outside the file rules)`, w, "")),
                     theme.fg("dim", truncateToWidth(`${prefix ? "  " : ""}    No other extension tools are installed.`, w, "")));
             }
-            output.push("", line("Save as defaults", "", "", row === saveRow()));
+            output.push("");
             const selected = row < rows.length ? rows[row]!.key : undefined;
-            const tool = row >= rows.length && row < saveRow() ? items[row - rows.length] : undefined;
+            const tool = row >= rows.length ? items[row - rows.length] : undefined;
             const contextual = tool ? (tool.kind === "guarded" ? GUARDED_HINT : TRUSTED_HINT)
                 : selected && settings ? cellHint(selected, settings[columns[column]!]) : undefined;
             for (const hint of [
-                "↑↓ Select · ←→ Column/fold · Space Toggle · ctrl+s Save · Enter Fold · Esc Back",
+                "↑↓ Select · ←→ Column/fold · Space Toggle · ctrl+s Save default · Enter Fold · Esc Back",
                 "Changes apply to new launches. Background tasks follow their launcher.",
                 "Stored credentials: known files only; excludes OS vaults and environment tokens.",
                 "Trusted tools run outside the file rules.",

package/node_modules/pi-better-sandbox/session-permissions.ts

@@ -0,0 +1,24 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { parseSandboxPermissions, type SandboxPermissionSettings } from "./permissions.ts";
+
+export const SESSION_PERMISSION_ENTRY = "pi-better-sandbox-permissions";
+
+/** Only the active branch contributes policy; the newest entry must validate. */
+export function readSessionPermissions(ctx: ExtensionContext): SandboxPermissionSettings | undefined {
+    const entry = [...ctx.sessionManager.getBranch()].reverse().find((entry) =>
+        entry.type === "custom" && entry.customType === SESSION_PERMISSION_ENTRY);
+    if (!entry || entry.type !== "custom") return undefined;
+    const data = entry.data as { version?: unknown; permissions?: unknown } | undefined;
+    if (!data || data.version !== 1) throw new Error("Unsupported sandbox session permissions version.");
+    // Session snapshots have always included Tools. Unlike old global files,
+    // an incomplete snapshot must not gain the default trusted-tool grants.
+    if (!data.permissions || typeof data.permissions !== "object" ||
+        (data.permissions as { subagentTools?: unknown }).subagentTools === undefined) {
+        throw new Error("Sandbox session permissions require explicit subagent tool settings.");
+    }
+    return parseSandboxPermissions(data.permissions);
+}
+
+export function appendSessionPermissions(pi: ExtensionAPI, settings: SandboxPermissionSettings): void {
+    pi.appendEntry(SESSION_PERMISSION_ENTRY, { version: 1, permissions: parseSandboxPermissions(settings) });
+}

package/node_modules/pi-better-sandbox/state.ts

@@ -6,9 +6,8 @@
  * the *effective* status derived from live runtime evidence (which backend this
  * platform actually resolves, not what the package intended).
  *
- * Session overrides are deliberately in-memory only. Every session start —
- * startup, new, resume, fork, reload — calls `beginSession` with the persisted
- * default and clears the previous override.
+ * The extension persists permission snapshots in Pi custom entries and restores
+ * the active branch after `beginSession` resets this in-memory controller.
  */
 
 import { getAgentDir, getPackageDir } from "@earendil-works/pi-coding-agent";
@@ -132,7 +131,7 @@ export class ForegroundSandboxController {
 
     /**
      * Capture the canonical launch directory and apply the persisted default.
-     * A session override never survives a new, resumed, forked, or reloaded session.
+     * The extension then restores any permissions on the active session branch.
      */
     beginSession(cwd: string, defaultEnabled = false): ForegroundSandboxStatus {
         const projectRoot = canonicalizePath(cwd, this.#seams);
@@ -156,7 +155,7 @@ export class ForegroundSandboxController {
         return this.status();
     }
 
-    /** Turn protection off for this session only. Never persisted. */
+    /** Turn protection off for this session; persistence belongs to the extension. */
     disable(): ForegroundSandboxStatus {
         this.#sessionOverride = false;
         this.#policyProblem = undefined;

package/node_modules/pi-better-subagents/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/node_modules/pi-better-subagents/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/node_modules/pi-better-subagents/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/node_modules/pi-better-subagents/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/node_modules/pi-better-subagents/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/node_modules/pi-better-subagents/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/node_modules/pi-better-subagents/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/node_modules/pi-better-subagents/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/node_modules/pi-better-subagents/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/node_modules/pi-better-subagents/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/node_modules/pi-better-subagents/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/node_modules/pi-better-subagents/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/node_modules/pi-better-subagents/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/node_modules/pi-better-subagents/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, ""));
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",
@@ -55,9 +55,9 @@
     "pi-better-background-tasks": "0.6.3",
     "pi-better-goal": "0.6.1",
     "pi-better-plan": "0.5.2",
-    "pi-better-sandbox": "0.8.2",
+    "pi-better-sandbox": "0.9.0",
     "pi-better-ssh": "0.1.1",
-    "pi-better-subagents": "0.12.0",
+    "pi-better-subagents": "0.13.0",
     "smol-toml": "1.9.0",
     "yaml": "^2.9.1"
   },