@tintinweb/pi-subagents 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.2] - 2026-04-28
+
+### Fixed
+- **`Agent` tool fails on Windows with `ENOENT` creating output directory** ([#27](https://github.com/tintinweb/pi-subagents/issues/27) — thanks [@sixnathan](https://github.com/sixnathan) for the diagnosis). The cwd-encoding regex in `output-file.ts` only handled POSIX `/` separators, so on Windows `cwd = "C:\\Users\\foo\\project"` survived unchanged and `path.join(tmpRoot, encoded, …)` produced an invalid nested-absolute path. Now extracts a small `encodeCwd()` helper that handles both `/` and `\\` separators, strips the Windows drive-letter prefix, and preserves UNC server/share segments. The `chmodSync(root, 0o700)` call is also wrapped in a try/catch that swallows errors only on Windows (where chmod is a no-op and can throw on some filesystems); on Unix the error still propagates so umask-defeating `0o700` enforcement is preserved.
+
+## [0.6.1] - 2026-04-25
+
+### Added
+- **Persistent `/agents` → Settings** ([#24](https://github.com/tintinweb/pi-subagents/issues/24)) — the four runtime tuning values (`maxConcurrent`, `defaultMaxTurns`, `graceTurns`, `defaultJoinMode`) now survive pi restarts via a two-file dual-scope model mirroring pi's own `SettingsManager`. Global `~/.pi/agent/subagents.json` provides machine-wide defaults (edit by hand; the menu never writes here); project `<cwd>/.pi/subagents.json` holds per-project overrides (written by `/agents` → Settings). Load merges both with project winning on conflicts. Invalid fields are silently dropped per field; malformed JSON emits a warning to stderr and falls back to defaults so startup always proceeds; write failures downgrade the settings toast to a warning with `(session only; failed to persist)` so changes aren't silently reverted on next restart.
+- **New lifecycle events** — `subagents:settings_loaded` (emitted once at extension init with the merged settings) and `subagents:settings_changed` (emitted on each `/agents` → Settings mutation with the new snapshot and a `persisted: boolean` flag so listeners can react to write failures).
+
+### Fixed
+- **`AGENTS.md` / `CLAUDE.md` / `APPEND_SYSTEM.md` no longer leak into sub-agent prompts** ([#26](https://github.com/tintinweb/pi-subagents/pull/26) — thanks [@mikeyobrien](https://github.com/mikeyobrien) for the diagnosis). Upstream `buildSystemPrompt()` re-appends `contextFiles` and `appendSystemPrompt` *after* our `systemPromptOverride` runs, which silently defeated `prompt_mode: replace` and `isolated: true` — parent project context (e.g. autoresearch-mode blocks) was bleeding into fresh `Explore` / custom sub-agents regardless of frontmatter. Fix uses upstream's `noContextFiles: true` flag (skips the load entirely, introduced in pi 0.68) plus `appendSystemPromptOverride: () => []` (no flag equivalent for append sources). **Behavior change:** subagents no longer implicitly inherit parent `AGENTS.md`/`CLAUDE.md`/`APPEND_SYSTEM.md`. To get parent project context into a subagent, use `prompt_mode: append` (parent's already-built system prompt flows in via `systemPromptOverride`), or `inherit_context: true` (parent conversation), or inline the content into the agent's own frontmatter.
+- **Custom agent discovery respects `PI_CODING_AGENT_DIR`** ([#35](https://github.com/tintinweb/pi-subagents/pull/35), closes [#23](https://github.com/tintinweb/pi-subagents/issues/23) — thanks [@Amolith](https://github.com/Amolith) for the diagnosis). Two remaining hardcoded `~/.pi/agent/agents/` paths in `custom-agents.ts` and `index.ts` bypassed the env var, so users who relocated their agent directory (e.g. via `PI_CODING_AGENT_DIR`) still had global agents loaded from the default location and help text referencing the wrong path. Both now use upstream `getAgentDir()`, consistent with `agent-runner.ts` and `settings.ts`; tilde expansion is handled by upstream.
+
 ## [0.6.0] - 2026-04-24
 
 > **⚠️ Breaking: drops support for `pi` < 0.68.** The upstream `pi-coding-agent` package shipped breaking API changes in v0.68 (and further ones in v0.70). This release migrates to `^0.70.2` and is **not** backward-compatible with hosts on `pi` 0.62–0.67. Users on those versions must upgrade their `pi` installation (`npm install -g @mariozechner/pi-coding-agent@latest`) before updating this extension.
@@ -359,6 +374,9 @@ Initial release.
 - **Thinking level** — per-agent extended thinking control
 - **`/agent` and `/agents` commands**
 
+[0.6.2]: https://github.com/tintinweb/pi-subagents/compare/v0.6.1...v0.6.2
+[0.6.1]: https://github.com/tintinweb/pi-subagents/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/tintinweb/pi-subagents/compare/v0.5.2...v0.6.0
 [0.5.2]: https://github.com/tintinweb/pi-subagents/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/tintinweb/pi-subagents/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/tintinweb/pi-subagents/compare/v0.4.9...v0.5.0

package/README.md

@@ -116,9 +116,9 @@ Agents are discovered from two locations (higher priority wins):
 | Priority | Location | Scope |
 |----------|----------|-------|
 | 1 (highest) | `.pi/agents/<name>.md` | Project — per-repo agents |
-| 2 | `~/.pi/agent/agents/<name>.md` | Global — available everywhere |
+| 2 | `$PI_CODING_AGENT_DIR/agents/<name>.md` (default `~/.pi/agent/agents/<name>.md`) | Global — available everywhere |
 
-Project-level agents override global ones with the same name, so you can customize a global agent for a specific project.
+Project-level agents override global ones with the same name, so you can customize a global agent for a specific project. The global location follows the upstream `PI_CODING_AGENT_DIR` env var — set it to relocate all pi-coding-agent state (agents, skills, settings) to a custom directory.
 
 ### Example: `.pi/agents/auditor.md`
 
@@ -163,10 +163,9 @@ All fields are optional — sensible defaults for everything.
 | `model` | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`) |
 | `thinking` | inherit | off, minimal, low, medium, high, xhigh |
 | `max_turns` | unlimited | Max agentic turns before graceful shutdown. `0` or omit for unlimited |
-| `prompt_mode` | `replace` | `replace`: body is the full system prompt. `append`: body appended to parent's prompt (agent acts as a "parent twin" with optional extra instructions) |
+| `prompt_mode` | `replace` | `replace`: body is the full system prompt (no AGENTS.md / CLAUDE.md inheritance). `append`: body appended to parent's prompt (agent acts as a "parent twin" — inherits parent's AGENTS.md / CLAUDE.md) |
 | `inherit_context` | `false` | Fork parent conversation into agent |
 | `run_in_background` | `false` | Run in background by default |
-| `isolation` | — | `worktree`: run in a temporary git worktree for full repo isolation |
 | `isolated` | `false` | No extension/MCP tools, only built-in |
 | `enabled` | `true` | Set to `false` to disable an agent (useful for hiding a default agent per-project) |
 
@@ -272,6 +271,31 @@ When background agents complete, they notify the main agent. The **join mode** c
 **Configuration:**
 - Configure join mode in `/agents` → Settings → Join mode
 
+## Persistent Settings
+
+Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, default join mode) persist across pi restarts. Two files, merged on load:
+
+- **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults. Edit by hand; the `/agents` menu never writes here.
+- **Project:** `<cwd>/.pi/subagents.json` — per-project overrides. Written by `/agents` → Settings.
+
+**Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`, join mode `smart`).
+
+**Example — global defaults for a beefy machine:**
+
+```bash
+mkdir -p ~/.pi/agent
+cat > ~/.pi/agent/subagents.json <<'EOF'
+{
+  "maxConcurrent": 16,
+  "graceTurns": 10
+}
+EOF
+```
+
+Every project now starts with concurrency 16 and grace 10, without ever touching the menu. Individual projects can still override via `/agents` → Settings.
+
+**Failure behavior:** missing file is silent; malformed JSON logs a `[pi-subagents] Ignoring malformed settings at …` warning to stderr; invalid/out-of-range field values are dropped per-field; write failures downgrade the `/agents` toast to a warning with `(session only; failed to persist)`.
+
 ## Events
 
 Agent lifecycle events are emitted via `pi.events.emit()` so other extensions can react:
@@ -284,6 +308,8 @@ Agent lifecycle events are emitted via `pi.events.emit()` so other extensions ca
 | `subagents:failed` | Agent errored, stopped, or aborted | same as completed + `error`, `status` |
 | `subagents:steered` | Steering message sent | `id`, `message` |
 | `subagents:ready` | Extension loaded and RPC handlers registered | — |
+| `subagents:settings_loaded` | Persisted settings applied at extension init | `settings` (merged global + project) |
+| `subagents:settings_changed` | `/agents` → Settings mutation was applied | `settings`, `persisted` (`boolean` — `false` on write failure) |
 
 ## Cross-Extension RPC
 

package/dist/agent-runner.js

@@ -157,7 +157,12 @@ export async function runAgent(ctx, type, prompt, options) {
     // Still pass noSkills: true since we don't need the skill loader to load them again.
     const noSkills = skills === false || Array.isArray(skills);
     const agentDir = getAgentDir();
-    // Load extensions/skills: true or string[] → load; false → don't
+    // 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,
@@ -165,7 +170,9 @@ export async function runAgent(ctx, type, prompt, options) {
         noSkills,
         noPromptTemplates: true,
         noThemes: true,
+        noContextFiles: true,
         systemPromptOverride: () => systemPrompt,
+        appendSystemPromptOverride: () => [],
     });
     await loader.reload();
     // Resolve model: explicit option > config.model > parent model

package/dist/custom-agents.d.ts

@@ -1,12 +1,12 @@
 /**
- * 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 type { AgentConfig } 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.

package/dist/custom-agents.js

@@ -1,22 +1,21 @@
 /**
- * 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";
 /**
  * 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) {
-    const globalDir = join(homedir(), ".pi", "agent", "agents");
+    const globalDir = join(getAgentDir(), "agents");
     const projectDir = join(cwd, ".pi", "agents");
     const agents = new Map();
     loadFromDir(globalDir, agents, "global"); // lower priority

package/dist/index.js

@@ -10,9 +10,8 @@
  *   /agents                 — Interactive agent management menu
  */
 import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
-import { defineTool } from "@mariozechner/pi-coding-agent";
+import { defineTool, getAgentDir } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
@@ -24,6 +23,7 @@ import { GroupJoinManager } from "./group-join.js";
 import { resolveAgentInvocationConfig, resolveJoinMode } from "./invocation-config.js";
 import { resolveModel } from "./model-resolver.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
+import { applyAndEmitLoaded, saveAndEmitChanged } from "./settings.js";
 import { AgentWidget, describeActivity, formatDuration, formatMs, formatTokens, formatTurns, getDisplayName, getPromptModeLabel, SPINNER, } from "./ui/agent-widget.js";
 // ---- Shared helpers ----
 /** Tool execute return value for a text response. */
@@ -478,7 +478,7 @@ export default function (pi) {
             ...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");
     };
     /** Derive a short model label from a model string. */
@@ -489,6 +489,15 @@ export default function (pi) {
         return name.replace(/-\d{8}$/, "");
     }
     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(defineTool({
         name: "Agent",
@@ -522,7 +531,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({
                 description: 'Optional model override. Accepts "provider/modelId" or fuzzy name (e.g. "haiku", "sonnet"). Omit to use the agent type\'s default.',
@@ -952,7 +961,7 @@ Guidelines:
     }));
     // ---- /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) {
         const projectPath = join(projectAgentsDir(), `${name}.md`);
@@ -1180,7 +1189,7 @@ Guidelines:
     async function ejectAgent(ctx, name, cfg) {
         const location = await ctx.ui.select("Choose location", [
             "Project (.pi/agents/)",
-            "Personal (~/.pi/agent/agents/)",
+            `Personal (${personalAgentsDir()})`,
         ]);
         if (!location)
             return;
@@ -1251,7 +1260,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;
@@ -1286,7 +1295,7 @@ Guidelines:
     async function showCreateWizard(ctx) {
         const location = await ctx.ui.select("Choose location", [
             "Project (.pi/agents/)",
-            "Personal (~/.pi/agent/agents/)",
+            `Personal (${personalAgentsDir()})`,
         ]);
         if (!location)
             return;
@@ -1463,6 +1472,16 @@ ${systemPrompt}
         reloadCustomAgents();
         ctx.ui.notify(`Created ${targetPath}`, "info");
     }
+    function snapshotSettings() {
+        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) {
         const choice = await ctx.ui.select("Settings", [
             `Max concurrency (current: ${manager.getMaxConcurrent()})`,
@@ -1478,7 +1497,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");
@@ -1491,11 +1510,11 @@ ${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");
@@ -1508,7 +1527,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");
@@ -1524,10 +1543,18 @@ ${systemPrompt}
             if (val) {
                 const mode = val.split(" ")[0];
                 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, successMsg) {
+        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); },

package/dist/output-file.d.ts

@@ -5,6 +5,13 @@
  * matching Claude Code's task output file format.
  */
 import type { AgentSession } from "@mariozechner/pi-coding-agent";
+/**
+ * Encode a cwd path as a filesystem-safe directory name. Handles:
+ *   - POSIX:   "/home/user/project"        → "home-user-project"
+ *   - Windows: "C:\Users\foo\project"      → "Users-foo-project"
+ *   - UNC:     "\\\\server\\share\\project"  → "server-share-project"
+ */
+export declare function encodeCwd(cwd: string): string;
 /** Create the output file path, ensuring the directory exists.
  *  Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks/{agentId}.output */
 export declare function createOutputFilePath(cwd: string, agentId: string, sessionId: string): string;

package/dist/output-file.js

@@ -7,13 +7,33 @@
 import { appendFileSync, chmodSync, mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+/**
+ * Encode a cwd path as a filesystem-safe directory name. Handles:
+ *   - POSIX:   "/home/user/project"        → "home-user-project"
+ *   - Windows: "C:\Users\foo\project"      → "Users-foo-project"
+ *   - UNC:     "\\\\server\\share\\project"  → "server-share-project"
+ */
+export function encodeCwd(cwd) {
+    return cwd
+        .replace(/[/\\]/g, "-") // both separators → dash
+        .replace(/^[A-Za-z]:-/, "") // strip Windows drive prefix ("C:-")
+        .replace(/^-+/, ""); // strip leading dashes (POSIX root, UNC)
+}
 /** Create the output file path, ensuring the directory exists.
  *  Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks/{agentId}.output */
 export function createOutputFilePath(cwd, agentId, sessionId) {
-    const encoded = cwd.replace(/\//g, "-").replace(/^-/, "");
+    const encoded = encodeCwd(cwd);
     const root = join(tmpdir(), `pi-subagents-${process.getuid?.() ?? 0}`);
     mkdirSync(root, { recursive: true, mode: 0o700 });
-    chmodSync(root, 0o700);
+    // chmod is a no-op on Windows and throws on some Windows filesystems.
+    // On Unix we still want to enforce 0o700 past umask, so only swallow on Windows.
+    try {
+        chmodSync(root, 0o700);
+    }
+    catch (err) {
+        if (process.platform !== "win32")
+            throw err;
+    }
     const dir = join(root, encoded, sessionId, "tasks");
     mkdirSync(dir, { recursive: true });
     return join(dir, `${agentId}.output`);

package/dist/settings.d.ts

@@ -0,0 +1,56 @@
+import type { JoinMode } from "./types.js";
+export interface SubagentsSettings {
+    maxConcurrent?: number;
+    /**
+     * 0 = unlimited — the extension's single source of truth for that convention:
+     * `normalizeMaxTurns()` in agent-runner.ts treats 0 → `undefined`, and the
+     * `/agents` → Settings input prompt explicitly says "0 = unlimited".
+     */
+    defaultMaxTurns?: number;
+    graceTurns?: number;
+    defaultJoinMode?: JoinMode;
+}
+/** Setter hooks used by applySettings to wire persisted values into in-memory state. */
+export interface SettingsAppliers {
+    setMaxConcurrent: (n: number) => void;
+    setDefaultMaxTurns: (n: number) => void;
+    setGraceTurns: (n: number) => void;
+    setDefaultJoinMode: (mode: JoinMode) => void;
+}
+/** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
+export type SettingsEmit = (event: string, payload: unknown) => void;
+/** Load merged settings: global provides defaults, project overrides. */
+export declare function loadSettings(cwd?: string): SubagentsSettings;
+/**
+ * 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 declare function saveSettings(s: SubagentsSettings, cwd?: string): boolean;
+/** Apply persisted settings to the in-memory state via caller-supplied setters. */
+export declare function applySettings(s: SubagentsSettings, appliers: SettingsAppliers): void;
+/**
+ * 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 declare function persistToastFor(successMsg: string, persisted: boolean): {
+    message: string;
+    level: "info" | "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 declare function applyAndEmitLoaded(appliers: SettingsAppliers, emit: SettingsEmit, cwd?: string): SubagentsSettings;
+/**
+ * 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 declare function saveAndEmitChanged(snapshot: SubagentsSettings, successMsg: string, emit: SettingsEmit, cwd?: string): {
+    message: string;
+    level: "info" | "warning";
+};

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.6.0",
+  "version": "0.6.2",
   "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.70.2",
-    "@mariozechner/pi-coding-agent": "^0.70.2",
-    "@mariozechner/pi-tui": "^0.70.2",
+    "@mariozechner/pi-ai": "^0.70.5",
+    "@mariozechner/pi-coding-agent": "^0.70.5",
+    "@mariozechner/pi-tui": "^0.70.5",
     "@sinclair/typebox": "latest"
   },
   "scripts": {
@@ -38,7 +38,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.3.5",
     "@types/node": "^25.5.0",
-    "typescript": "^5.0.0",
+    "typescript": "^6.0.0",
     "vitest": "^4.0.18"
   },
   "pi": {

package/src/agent-runner.ts

@@ -233,7 +233,12 @@ export async function runAgent(
 
   const agentDir = getAgentDir();
 
-  // Load extensions/skills: true or string[] → load; false → don't
+  // 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,
@@ -241,7 +246,9 @@ export async function runAgent(
     noSkills,
     noPromptTemplates: true,
     noThemes: true,
+    noContextFiles: true,
     systemPromptOverride: () => systemPrompt,
+    appendSystemPromptOverride: () => [],
   });
   await loader.reload();
 

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 { defineTool, type ExtensionAPI, type ExtensionCommandContext, type 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,
@@ -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,6 +548,19 @@ 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(defineTool({
@@ -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({
@@ -1085,7 +1098,7 @@ Guidelines:
   // ---- /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); },

package/src/output-file.ts

@@ -10,13 +10,32 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { AgentSession, AgentSessionEvent } from "@mariozechner/pi-coding-agent";
 
+/**
+ * Encode a cwd path as a filesystem-safe directory name. Handles:
+ *   - POSIX:   "/home/user/project"        → "home-user-project"
+ *   - Windows: "C:\Users\foo\project"      → "Users-foo-project"
+ *   - UNC:     "\\\\server\\share\\project"  → "server-share-project"
+ */
+export function encodeCwd(cwd: string): string {
+  return cwd
+    .replace(/[/\\]/g, "-")        // both separators → dash
+    .replace(/^[A-Za-z]:-/, "")    // strip Windows drive prefix ("C:-")
+    .replace(/^-+/, "");           // strip leading dashes (POSIX root, UNC)
+}
+
 /** Create the output file path, ensuring the directory exists.
  *  Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks/{agentId}.output */
 export function createOutputFilePath(cwd: string, agentId: string, sessionId: string): string {
-  const encoded = cwd.replace(/\//g, "-").replace(/^-/, "");
+  const encoded = encodeCwd(cwd);
   const root = join(tmpdir(), `pi-subagents-${process.getuid?.() ?? 0}`);
   mkdirSync(root, { recursive: true, mode: 0o700 });
-  chmodSync(root, 0o700);
+  // chmod is a no-op on Windows and throws on some Windows filesystems.
+  // On Unix we still want to enforce 0o700 past umask, so only swallow on Windows.
+  try {
+    chmodSync(root, 0o700);
+  } catch (err) {
+    if (process.platform !== "win32") throw err;
+  }
   const dir = join(root, encoded, sessionId, "tasks");
   mkdirSync(dir, { recursive: true });
   return join(dir, `${agentId}.output`);

package/src/settings.ts

@@ -0,0 +1,172 @@
+// 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";
+import type { JoinMode } from "./types.js";
+
+export interface SubagentsSettings {
+  maxConcurrent?: number;
+  /**
+   * 0 = unlimited — the extension's single source of truth for that convention:
+   * `normalizeMaxTurns()` in agent-runner.ts treats 0 → `undefined`, and the
+   * `/agents` → Settings input prompt explicitly says "0 = unlimited".
+   */
+  defaultMaxTurns?: number;
+  graceTurns?: number;
+  defaultJoinMode?: JoinMode;
+}
+
+/** Setter hooks used by applySettings to wire persisted values into in-memory state. */
+export interface SettingsAppliers {
+  setMaxConcurrent: (n: number) => void;
+  setDefaultMaxTurns: (n: number) => void;
+  setGraceTurns: (n: number) => void;
+  setDefaultJoinMode: (mode: JoinMode) => void;
+}
+
+/** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
+export type SettingsEmit = (event: string, payload: unknown) => void;
+
+const VALID_JOIN_MODES: ReadonlySet<string> = new Set<JoinMode>(["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: unknown): SubagentsSettings {
+  if (!raw || typeof raw !== "object") return {};
+  const r = raw as Record<string, unknown>;
+  const out: SubagentsSettings = {};
+  if (
+    Number.isInteger(r.maxConcurrent) &&
+    (r.maxConcurrent as number) >= 1 &&
+    (r.maxConcurrent as number) <= MAX_CONCURRENT_CEILING
+  ) {
+    out.maxConcurrent = r.maxConcurrent as number;
+  }
+  if (
+    Number.isInteger(r.defaultMaxTurns) &&
+    (r.defaultMaxTurns as number) >= 0 &&
+    (r.defaultMaxTurns as number) <= MAX_TURNS_CEILING
+  ) {
+    out.defaultMaxTurns = r.defaultMaxTurns as number;
+  }
+  if (
+    Number.isInteger(r.graceTurns) &&
+    (r.graceTurns as number) >= 1 &&
+    (r.graceTurns as number) <= GRACE_TURNS_CEILING
+  ) {
+    out.graceTurns = r.graceTurns as number;
+  }
+  if (typeof r.defaultJoinMode === "string" && VALID_JOIN_MODES.has(r.defaultJoinMode)) {
+    out.defaultJoinMode = r.defaultJoinMode as JoinMode;
+  }
+  return out;
+}
+
+function globalPath(): string {
+  return join(getAgentDir(), "subagents.json");
+}
+
+function projectPath(cwd: string): string {
+  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: string): SubagentsSettings {
+  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: string = process.cwd()): SubagentsSettings {
+  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: SubagentsSettings, cwd: string = process.cwd()): boolean {
+  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: SubagentsSettings, appliers: SettingsAppliers): void {
+  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: string,
+  persisted: boolean,
+): { message: string; level: "info" | "warning" } {
+  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: SettingsAppliers,
+  emit: SettingsEmit,
+  cwd: string = process.cwd(),
+): SubagentsSettings {
+  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: SubagentsSettings,
+  successMsg: string,
+  emit: SettingsEmit,
+  cwd: string = process.cwd(),
+): { message: string; level: "info" | "warning" } {
+  const persisted = saveSettings(snapshot, cwd);
+  emit("subagents:settings_changed", { settings: snapshot, persisted });
+  return persistToastFor(successMsg, persisted);
+}