@tintinweb/pi-subagents 0.5.2 → 0.6.1

package/dist/settings.js

@@ -0,0 +1,125 @@
+// Persistence for pi-subagents operational settings.
+// - Global:  ~/.pi/agent/subagents.json (via getAgentDir()) — manual defaults, never written here
+// - Project: <cwd>/.pi/subagents.json — written by /agents → Settings; overrides global on load
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+const VALID_JOIN_MODES = new Set(["async", "group", "smart"]);
+// Sanity ceilings — prevent hand-edited configs from asking for values that
+// make no operational sense (e.g. 1e6 concurrent subagents). Permissive enough
+// that any realistic power-user setting passes through.
+const MAX_CONCURRENT_CEILING = 1024;
+const MAX_TURNS_CEILING = 10_000;
+const GRACE_TURNS_CEILING = 1_000;
+/** Drop fields that don't match the expected shape. Silent — garbage becomes absent. */
+function sanitize(raw) {
+    if (!raw || typeof raw !== "object")
+        return {};
+    const r = raw;
+    const out = {};
+    if (Number.isInteger(r.maxConcurrent) &&
+        r.maxConcurrent >= 1 &&
+        r.maxConcurrent <= MAX_CONCURRENT_CEILING) {
+        out.maxConcurrent = r.maxConcurrent;
+    }
+    if (Number.isInteger(r.defaultMaxTurns) &&
+        r.defaultMaxTurns >= 0 &&
+        r.defaultMaxTurns <= MAX_TURNS_CEILING) {
+        out.defaultMaxTurns = r.defaultMaxTurns;
+    }
+    if (Number.isInteger(r.graceTurns) &&
+        r.graceTurns >= 1 &&
+        r.graceTurns <= GRACE_TURNS_CEILING) {
+        out.graceTurns = r.graceTurns;
+    }
+    if (typeof r.defaultJoinMode === "string" && VALID_JOIN_MODES.has(r.defaultJoinMode)) {
+        out.defaultJoinMode = r.defaultJoinMode;
+    }
+    return out;
+}
+function globalPath() {
+    return join(getAgentDir(), "subagents.json");
+}
+function projectPath(cwd) {
+    return join(cwd, ".pi", "subagents.json");
+}
+/**
+ * Read a settings file. Missing file is silent (returns `{}`). A file that
+ * exists but can't be parsed emits a warning to stderr so users aren't
+ * silently reverted to defaults — and still returns `{}` so startup proceeds.
+ */
+function readSettingsFile(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return sanitize(JSON.parse(readFileSync(path, "utf-8")));
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        console.warn(`[pi-subagents] Ignoring malformed settings at ${path}: ${reason}`);
+        return {};
+    }
+}
+/** Load merged settings: global provides defaults, project overrides. */
+export function loadSettings(cwd = process.cwd()) {
+    return { ...readSettingsFile(globalPath()), ...readSettingsFile(projectPath(cwd)) };
+}
+/**
+ * Write project-local settings. Global is never touched from code.
+ * Returns `true` on success, `false` if the write (or mkdir) failed so the
+ * caller can surface a warning — persistence isn't fatal but isn't silent.
+ */
+export function saveSettings(s, cwd = process.cwd()) {
+    const path = projectPath(cwd);
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(s, null, 2), "utf-8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Apply persisted settings to the in-memory state via caller-supplied setters. */
+export function applySettings(s, appliers) {
+    if (typeof s.maxConcurrent === "number")
+        appliers.setMaxConcurrent(s.maxConcurrent);
+    if (typeof s.defaultMaxTurns === "number")
+        appliers.setDefaultMaxTurns(s.defaultMaxTurns);
+    if (typeof s.graceTurns === "number")
+        appliers.setGraceTurns(s.graceTurns);
+    if (s.defaultJoinMode)
+        appliers.setDefaultJoinMode(s.defaultJoinMode);
+}
+/**
+ * Format the user-facing toast for a settings mutation. Pure function —
+ * routes the success/failure of `saveSettings` into the right message + level
+ * so the UI layer (index.ts) stays a thin wire between input and notification.
+ */
+export function persistToastFor(successMsg, persisted) {
+    return persisted
+        ? { message: successMsg, level: "info" }
+        : { message: `${successMsg} (session only; failed to persist)`, level: "warning" };
+}
+/**
+ * Load merged settings, apply them to in-memory state, and emit the
+ * `subagents:settings_loaded` lifecycle event. Returns the loaded settings so
+ * callers can log/inspect. Extension init wires this once.
+ */
+export function applyAndEmitLoaded(appliers, emit, cwd = process.cwd()) {
+    const settings = loadSettings(cwd);
+    applySettings(settings, appliers);
+    emit("subagents:settings_loaded", { settings });
+    return settings;
+}
+/**
+ * Persist a settings snapshot, emit the `subagents:settings_changed` event
+ * (regardless of persist outcome so listeners see the in-memory change), and
+ * return the toast the UI should display. Event payload carries the `persisted`
+ * flag so listeners can react to write failures.
+ */
+export function saveAndEmitChanged(snapshot, successMsg, emit, cwd = process.cwd()) {
+    const persisted = saveSettings(snapshot, cwd);
+    emit("subagents:settings_changed", { settings: snapshot, persisted });
+    return persistToastFor(successMsg, persisted);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",
@@ -21,9 +21,9 @@
     "autonomous"
   ],
   "dependencies": {
-    "@mariozechner/pi-ai": "^0.62.0",
-    "@mariozechner/pi-coding-agent": "^0.62.0",
-    "@mariozechner/pi-tui": "^0.62.0",
+    "@mariozechner/pi-ai": "^0.70.2",
+    "@mariozechner/pi-coding-agent": "^0.70.2",
+    "@mariozechner/pi-tui": "^0.70.2",
     "@sinclair/typebox": "latest"
   },
   "scripts": {

package/src/agent-runner.ts

@@ -10,10 +10,11 @@ import {
   createAgentSession,
   DefaultResourceLoader,
   type ExtensionAPI,
+  getAgentDir,
   SessionManager,
   SettingsManager,
 } from "@mariozechner/pi-coding-agent";
-import { getAgentConfig, getConfig, getMemoryTools, getReadOnlyMemoryTools, getToolsForType } from "./agent-types.js";
+import { getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
 import { buildParentContext, extractText } from "./context.js";
 import { detectEnv } from "./env.js";
 import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
@@ -183,27 +184,25 @@ export async function runAgent(
     }
   }
 
-  let tools = getToolsForType(type, effectiveCwd);
+  let toolNames = getToolNamesForType(type);
 
   // Persistent memory: detect write capability and branch accordingly.
   // Account for disallowedTools — a tool in the base set but on the denylist is not truly available.
   if (agentConfig?.memory) {
-    const existingNames = new Set(tools.map(t => t.name));
+    const existingNames = new Set(toolNames);
     const denied = agentConfig.disallowedTools ? new Set(agentConfig.disallowedTools) : undefined;
     const effectivelyHas = (name: string) => existingNames.has(name) && !denied?.has(name);
     const hasWriteTools = effectivelyHas("write") || effectivelyHas("edit");
 
     if (hasWriteTools) {
-      // Read-write memory: add any missing memory tools (read/write/edit)
-      const memTools = getMemoryTools(effectiveCwd, existingNames);
-      if (memTools.length > 0) tools = [...tools, ...memTools];
+      // Read-write memory: add any missing memory tool names (read/write/edit)
+      const extraNames = getMemoryToolNames(existingNames);
+      if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
       extras.memoryBlock = buildMemoryBlock(agentConfig.name, agentConfig.memory, effectiveCwd);
     } else {
-      // Read-only memory: only add read tool, use read-only prompt
-      if (!existingNames.has("read")) {
-        const readTools = getReadOnlyMemoryTools(effectiveCwd, existingNames);
-        if (readTools.length > 0) tools = [...tools, ...readTools];
-      }
+      // Read-only memory: only add read tool name, use read-only prompt
+      const extraNames = getReadOnlyMemoryToolNames(existingNames);
+      if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
       extras.memoryBlock = buildReadOnlyMemoryBlock(agentConfig.name, agentConfig.memory, effectiveCwd);
     }
   }
@@ -232,14 +231,24 @@ export async function runAgent(
   // Still pass noSkills: true since we don't need the skill loader to load them again.
   const noSkills = skills === false || Array.isArray(skills);
 
-  // Load extensions/skills: true or string[] → load; false → don't
+  const agentDir = getAgentDir();
+
+  // Load extensions/skills: true or string[] → load; false → don't.
+  // Suppress AGENTS.md/CLAUDE.md and APPEND_SYSTEM.md — upstream's
+  // buildSystemPrompt() re-appends both AFTER systemPromptOverride, which
+  // would defeat prompt_mode: replace and isolated: true. Parent context, if
+  // wanted, reaches the subagent via prompt_mode: append (parentSystemPrompt
+  // is embedded in systemPromptOverride) or inherit_context (conversation).
   const loader = new DefaultResourceLoader({
     cwd: effectiveCwd,
+    agentDir,
     noExtensions: extensions === false,
     noSkills,
     noPromptTemplates: true,
     noThemes: true,
+    noContextFiles: true,
     systemPromptOverride: () => systemPrompt,
+    appendSystemPromptOverride: () => [],
   });
   await loader.reload();
 
@@ -251,21 +260,21 @@ export async function runAgent(
   // Resolve thinking level: explicit option > agent config > undefined (inherit)
   const thinkingLevel = options.thinkingLevel ?? agentConfig?.thinking;
 
-  const sessionOpts: Record<string, unknown> = {
+  const sessionOpts: Parameters<typeof createAgentSession>[0] = {
     cwd: effectiveCwd,
+    agentDir,
     sessionManager: SessionManager.inMemory(effectiveCwd),
-    settingsManager: SettingsManager.create(),
+    settingsManager: SettingsManager.create(effectiveCwd, agentDir),
     modelRegistry: ctx.modelRegistry,
     model,
-    tools,
+    tools: toolNames,
     resourceLoader: loader,
   };
   if (thinkingLevel) {
     sessionOpts.thinkingLevel = thinkingLevel;
   }
 
-  // createAgentSession's type signature may not include thinkingLevel yet
-  const { session } = await createAgentSession(sessionOpts as Parameters<typeof createAgentSession>[0]);
+  const { session } = await createAgentSession(sessionOpts);
 
   // Build disallowed tools set from agent config
   const disallowedSet = agentConfig?.disallowedTools
@@ -275,11 +284,11 @@ export async function runAgent(
   // Filter active tools: remove our own tools to prevent nesting,
   // apply extension allowlist if specified, and apply disallowedTools denylist
   if (extensions !== false) {
-    const builtinToolNames = new Set(tools.map(t => t.name));
+    const builtinToolNameSet = new Set(toolNames);
     const activeTools = session.getActiveToolNames().filter((t) => {
       if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
       if (disallowedSet?.has(t)) return false;
-      if (builtinToolNames.has(t)) return true;
+      if (builtinToolNameSet.has(t)) return true;
       if (Array.isArray(extensions)) {
         return extensions.some(ext => t.startsWith(ext) || t.includes(ext));
       }

package/src/agent-types.ts

@@ -5,33 +5,11 @@
  * User agents override defaults with the same name. Disabled agents are kept but excluded from spawning.
  */
 
-import type { AgentTool } from "@mariozechner/pi-agent-core";
-import {
-  createBashTool,
-  createEditTool,
-  createFindTool,
-  createGrepTool,
-  createLsTool,
-  createReadTool,
-  createWriteTool,
-} from "@mariozechner/pi-coding-agent";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import type { AgentConfig } from "./types.js";
 
-type ToolFactory = (cwd: string) => AgentTool<any>;
-
-const TOOL_FACTORIES: Record<string, ToolFactory> = {
-  read: (cwd) => createReadTool(cwd),
-  bash: (cwd) => createBashTool(cwd),
-  edit: (cwd) => createEditTool(cwd),
-  write: (cwd) => createWriteTool(cwd),
-  grep: (cwd) => createGrepTool(cwd),
-  find: (cwd) => createFindTool(cwd),
-  ls: (cwd) => createLsTool(cwd),
-};
-
-/** All known built-in tool names, derived from the factory registry. */
-export const BUILTIN_TOOL_NAMES = Object.keys(TOOL_FACTORIES);
+/** All known built-in tool names. */
+export const BUILTIN_TOOL_NAMES: string[] = ["read", "bash", "edit", "write", "grep", "find", "ls"];
 
 /** Unified runtime registry of all agents (defaults + user-defined). */
 const agents = new Map<string, AgentConfig>();
@@ -113,35 +91,29 @@ export function isValidType(type: string): boolean {
 const MEMORY_TOOL_NAMES = ["read", "write", "edit"];
 
 /**
- * Get the tools needed for memory management (read, write, edit).
- * Only returns tools that are NOT already in the provided set.
+ * Get memory tool names (read/write/edit) not already in the provided set.
  */
-export function getMemoryTools(cwd: string, existingToolNames: Set<string>): AgentTool<any>[] {
-  return MEMORY_TOOL_NAMES
-    .filter(n => !existingToolNames.has(n) && n in TOOL_FACTORIES)
-    .map(n => TOOL_FACTORIES[n](cwd));
+export function getMemoryToolNames(existingToolNames: Set<string>): string[] {
+  return MEMORY_TOOL_NAMES.filter(n => !existingToolNames.has(n));
 }
 
 /** Tool names needed for read-only memory access. */
 const READONLY_MEMORY_TOOL_NAMES = ["read"];
 
 /**
- * Get only the read tool for read-only memory access.
- * Only returns tools that are NOT already in the provided set.
+ * Get read-only memory tool names not already in the provided set.
  */
-export function getReadOnlyMemoryTools(cwd: string, existingToolNames: Set<string>): AgentTool<any>[] {
-  return READONLY_MEMORY_TOOL_NAMES
-    .filter(n => !existingToolNames.has(n) && n in TOOL_FACTORIES)
-    .map(n => TOOL_FACTORIES[n](cwd));
+export function getReadOnlyMemoryToolNames(existingToolNames: Set<string>): string[] {
+  return READONLY_MEMORY_TOOL_NAMES.filter(n => !existingToolNames.has(n));
 }
 
-/** Get built-in tools for a type (case-insensitive). */
-export function getToolsForType(type: string, cwd: string): AgentTool<any>[] {
+/** Get built-in tool names for a type (case-insensitive). */
+export function getToolNamesForType(type: string): string[] {
   const key = resolveKey(type);
   const raw = key ? agents.get(key) : undefined;
   const config = raw?.enabled !== false ? raw : undefined;
-  const toolNames = config?.builtinToolNames?.length ? config.builtinToolNames : BUILTIN_TOOL_NAMES;
-  return toolNames.filter((n) => n in TOOL_FACTORIES).map((n) => TOOL_FACTORIES[n](cwd));
+  const names = config?.builtinToolNames?.length ? config.builtinToolNames : [...BUILTIN_TOOL_NAMES];
+  return names;
 }
 
 /** Get config for a type (case-insensitive, returns a SubagentTypeConfig-compatible object). Falls back to general-purpose. */

package/src/custom-agents.ts

@@ -1,11 +1,10 @@
 /**
- * custom-agents.ts — Load user-defined agents from project (.pi/agents/) and global (~/.pi/agent/agents/) locations.
+ * custom-agents.ts — Load user-defined agents from project (.pi/agents/) and global ($PI_CODING_AGENT_DIR/agents/, default ~/.pi/agent/agents/) locations.
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { basename, join } from "node:path";
-import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
+import { getAgentDir, parseFrontmatter } from "@mariozechner/pi-coding-agent";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
 import type { AgentConfig, MemoryScope, ThinkingLevel } from "./types.js";
 
@@ -13,13 +12,13 @@ import type { AgentConfig, MemoryScope, ThinkingLevel } from "./types.js";
  * Scan for custom agent .md files from multiple locations.
  * Discovery hierarchy (higher priority wins):
  *   1. Project: <cwd>/.pi/agents/*.md
- *   2. Global:  ~/.pi/agent/agents/*.md
+ *   2. Global:  $PI_CODING_AGENT_DIR/agents/*.md (default: ~/.pi/agent/agents/*.md)
  *
  * Project-level agents override global ones with the same name.
  * Any name is allowed — names matching defaults (e.g. "Explore") override them.
  */
 export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
-  const globalDir = join(homedir(), ".pi", "agent", "agents");
+  const globalDir = join(getAgentDir(), "agents");
   const projectDir = join(cwd, ".pi", "agents");
 
   const agents = new Map<string, AgentConfig>();

package/src/index.ts

@@ -11,9 +11,8 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
-import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { defineTool, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, getAgentDir } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
@@ -25,6 +24,7 @@ import { GroupJoinManager } from "./group-join.js";
 import { resolveAgentInvocationConfig, resolveJoinMode } from "./invocation-config.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
+import { applyAndEmitLoaded, type SubagentsSettings, saveAndEmitChanged } from "./settings.js";
 import { type AgentConfig, type AgentRecord, type JoinMode, type NotificationDetails, type SubagentType } from "./types.js";
 import {
   type AgentActivity,
@@ -430,7 +430,7 @@ export default function (pi: ExtensionAPI) {
     manager.clearCompleted();           // preserve existing behavior
   });
 
-  pi.on("session_switch", () => { manager.clearCompleted(); });
+  pi.on("session_before_switch", () => { manager.clearCompleted(); });
 
   const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc, unsubStop: unsubStopRpc } = registerRpcHandlers({
     events: pi.events,
@@ -534,7 +534,7 @@ export default function (pi: ExtensionAPI) {
       ...defaultDescs,
       ...(customDescs.length > 0 ? ["", "Custom agents:", ...customDescs] : []),
       "",
-      "Custom agents can be defined in .pi/agents/<name>.md (project) or ~/.pi/agent/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.",
+      `Custom agents can be defined in .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.`,
     ].join("\n");
   };
 
@@ -548,9 +548,22 @@ export default function (pi: ExtensionAPI) {
 
   const typeListText = buildTypeListText();
 
+  // Apply persisted settings on startup and emit `subagents:settings_loaded`.
+  // Global + project merged; missing → defaults; corrupt file emits a warning
+  // to stderr and falls back to defaults.
+  applyAndEmitLoaded(
+    {
+      setMaxConcurrent: (n) => manager.setMaxConcurrent(n),
+      setDefaultMaxTurns,
+      setGraceTurns,
+      setDefaultJoinMode,
+    },
+    (event, payload) => pi.events.emit(event, payload),
+  );
+
   // ---- Agent tool ----
 
-  pi.registerTool<any, AgentDetails>({
+  pi.registerTool(defineTool({
     name: "Agent",
     label: "Agent",
     description: `Launch a new agent to handle complex, multi-step tasks autonomously.
@@ -582,7 +595,7 @@ Guidelines:
         description: "A short (3-5 word) description of the task (shown in UI).",
       }),
       subagent_type: Type.String({
-        description: `The type of specialized agent to use. Available types: ${getAvailableTypes().join(", ")}. Custom agents from .pi/agents/*.md (project) or ~/.pi/agent/agents/*.md (global) are also available.`,
+        description: `The type of specialized agent to use. Available types: ${getAvailableTypes().join(", ")}. Custom agents from .pi/agents/*.md (project) or ${getAgentDir()}/agents/*.md (global) are also available.`,
       }),
       model: Type.Optional(
         Type.String({
@@ -964,11 +977,11 @@ Guidelines:
         details,
       );
     },
-  });
+  }));
 
   // ---- get_subagent_result tool ----
 
-  pi.registerTool({
+  pi.registerTool(defineTool({
     name: "get_subagent_result",
     label: "Get Agent Result",
     description:
@@ -1038,11 +1051,11 @@ Guidelines:
 
       return textResult(output);
     },
-  });
+  }));
 
   // ---- steer_subagent tool ----
 
-  pi.registerTool({
+  pi.registerTool(defineTool({
     name: "steer_subagent",
     label: "Steer Agent",
     description:
@@ -1080,12 +1093,12 @@ Guidelines:
         return textResult(`Failed to steer agent: ${err instanceof Error ? err.message : String(err)}`);
       }
     },
-  });
+  }));
 
   // ---- /agents interactive menu ----
 
   const projectAgentsDir = () => join(process.cwd(), ".pi", "agents");
-  const personalAgentsDir = () => join(homedir(), ".pi", "agent", "agents");
+  const personalAgentsDir = () => join(getAgentDir(), "agents");
 
   /** Find the file path of a custom agent by name (project first, then global). */
   function findAgentFile(name: string): { path: string; location: "project" | "personal" } | undefined {
@@ -1324,7 +1337,7 @@ Guidelines:
   async function ejectAgent(ctx: ExtensionCommandContext, name: string, cfg: AgentConfig) {
     const location = await ctx.ui.select("Choose location", [
       "Project (.pi/agents/)",
-      "Personal (~/.pi/agent/agents/)",
+      `Personal (${personalAgentsDir()})`,
     ]);
     if (!location) return;
 
@@ -1386,7 +1399,7 @@ Guidelines:
     // No file (built-in default) — create a stub
     const location = await ctx.ui.select("Choose location", [
       "Project (.pi/agents/)",
-      "Personal (~/.pi/agent/agents/)",
+      `Personal (${personalAgentsDir()})`,
     ]);
     if (!location) return;
 
@@ -1424,7 +1437,7 @@ Guidelines:
   async function showCreateWizard(ctx: ExtensionCommandContext) {
     const location = await ctx.ui.select("Choose location", [
       "Project (.pi/agents/)",
-      "Personal (~/.pi/agent/agents/)",
+      `Personal (${personalAgentsDir()})`,
     ]);
     if (!location) return;
 
@@ -1605,6 +1618,17 @@ ${systemPrompt}
     ctx.ui.notify(`Created ${targetPath}`, "info");
   }
 
+  function snapshotSettings(): SubagentsSettings {
+    return {
+      maxConcurrent: manager.getMaxConcurrent(),
+      // 0 = unlimited — per SubagentsSettings.defaultMaxTurns docstring and
+      // normalizeMaxTurns() in agent-runner.ts (which maps 0 → undefined).
+      defaultMaxTurns: getDefaultMaxTurns() ?? 0,
+      graceTurns: getGraceTurns(),
+      defaultJoinMode: getDefaultJoinMode(),
+    };
+  }
+
   async function showSettings(ctx: ExtensionCommandContext) {
     const choice = await ctx.ui.select("Settings", [
       `Max concurrency (current: ${manager.getMaxConcurrent()})`,
@@ -1620,7 +1644,7 @@ ${systemPrompt}
         const n = parseInt(val, 10);
         if (n >= 1) {
           manager.setMaxConcurrent(n);
-          ctx.ui.notify(`Max concurrency set to ${n}`, "info");
+          notifyApplied(ctx, `Max concurrency set to ${n}`);
         } else {
           ctx.ui.notify("Must be a positive integer.", "warning");
         }
@@ -1631,10 +1655,10 @@ ${systemPrompt}
         const n = parseInt(val, 10);
         if (n === 0) {
           setDefaultMaxTurns(undefined);
-          ctx.ui.notify("Default max turns set to unlimited", "info");
+          notifyApplied(ctx, "Default max turns set to unlimited");
         } else if (n >= 1) {
           setDefaultMaxTurns(n);
-          ctx.ui.notify(`Default max turns set to ${n}`, "info");
+          notifyApplied(ctx, `Default max turns set to ${n}`);
         } else {
           ctx.ui.notify("Must be 0 (unlimited) or a positive integer.", "warning");
         }
@@ -1645,7 +1669,7 @@ ${systemPrompt}
         const n = parseInt(val, 10);
         if (n >= 1) {
           setGraceTurns(n);
-          ctx.ui.notify(`Grace turns set to ${n}`, "info");
+          notifyApplied(ctx, `Grace turns set to ${n}`);
         } else {
           ctx.ui.notify("Must be a positive integer.", "warning");
         }
@@ -1659,11 +1683,24 @@ ${systemPrompt}
       if (val) {
         const mode = val.split(" ")[0] as JoinMode;
         setDefaultJoinMode(mode);
-        ctx.ui.notify(`Default join mode set to ${mode}`, "info");
+        notifyApplied(ctx, `Default join mode set to ${mode}`);
       }
     }
   }
 
+  // Persist the current snapshot, emit `subagents:settings_changed`, and surface
+  // the right toast. Successful saves show info; persistence failures downgrade
+  // to warning so users aren't silently reverted on restart. Event fires regardless
+  // of outcome so listeners see the in-memory change.
+  function notifyApplied(ctx: ExtensionCommandContext, successMsg: string) {
+    const { message, level } = saveAndEmitChanged(
+      snapshotSettings(),
+      successMsg,
+      (event, payload) => pi.events.emit(event, payload),
+    );
+    ctx.ui.notify(message, level);
+  }
+
   pi.registerCommand("agents", {
     description: "Manage agents",
     handler: async (_args, ctx) => { await showAgentsMenu(ctx); },