@tintinweb/pi-subagents 0.5.2 → 0.6.1

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
+
+### Changed
+- **Bumped peer `@mariozechner/pi-coding-agent` to `^0.70.2`** ([#28](https://github.com/tintinweb/pi-subagents/pull/28)) — crosses the v0.68 breaking-change line upstream. Specifically: tools are now passed as `string[]` (was `Tool[]`); `cwd`/`agentDir` are mandatory on `SettingsManager.create()` and `DefaultResourceLoader`; `session_switch` event renamed to `session_before_switch`; `ToolDefinition.params` widens to `unknown` under contextual typing, requiring `defineTool(...)`.
+- **Tool registrations wrapped with `defineTool(...)`** — preserves `TParams` inference so `execute` handlers get properly-typed `params` instead of `unknown`. Applies to the `Agent`, `get_subagent_result`, and `steer_subagent` tools.
+
+### Removed
+- **Cwd-bound tool factory registry** — the internal `TOOL_FACTORIES` closure table and `create{Bash,Edit,Read,Write,Grep,Find,Ls}Tool` imports are gone. Exported helpers renamed: `getToolsForType(type, cwd)` → `getToolNamesForType(type)`, `getMemoryTools(cwd, set)` → `getMemoryToolNames(set)`, `getReadOnlyMemoryTools(cwd, set)` → `getReadOnlyMemoryToolNames(set)` — all returning `string[]` instead of `Tool[]`. The host binds cwd when resolving tool names, so the extension no longer instantiates tools directly.
+
+### Fixed
+- **Subagent `SettingsManager` read wrong project settings in worktree mode** ([#30](https://github.com/tintinweb/pi-subagents/pull/30)) — `SettingsManager.create()` was called without arguments, defaulting `cwd` to `process.cwd()`. When the subagent's effective cwd differed (worktree isolation or explicit `cwd` override), its settings manager read `.pi/settings.json` from the parent's cwd rather than its own, diverging from the loader and session manager. Now passes `effectiveCwd` and `agentDir` explicitly, keeping all three managers consistent.
+
 ## [0.5.2] - 2026-03-26
 
 ### Fixed

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,7 +163,7 @@ 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 |
@@ -272,6 +272,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 +309,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
 
@@ -417,7 +444,7 @@ src/
   index.ts            # Extension entry: tool/command registration, rendering
   types.ts            # Type definitions (AgentConfig, AgentRecord, etc.)
   default-agents.ts   # Embedded default agent configs (general-purpose, Explore, Plan)
-  agent-types.ts      # Unified agent registry (defaults + user), tool factories
+  agent-types.ts      # Unified agent registry (defaults + user), tool name resolution
   agent-runner.ts     # Session creation, execution, graceful max_turns, steer/resume
   agent-manager.ts    # Agent lifecycle, concurrency queue, completion notifications
   cross-extension-rpc.ts # RPC handlers for cross-extension spawn/ping via pi.events

package/dist/agent-runner.js

@@ -1,8 +1,8 @@
 /**
  * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
  */
-import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager, } from "@mariozechner/pi-coding-agent";
-import { getAgentConfig, getConfig, getMemoryTools, getReadOnlyMemoryTools, getToolsForType } from "./agent-types.js";
+import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@mariozechner/pi-coding-agent";
+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";
@@ -110,28 +110,26 @@ export async function runAgent(ctx, type, prompt, options) {
             extras.skillBlocks = loaded;
         }
     }
-    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) => 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);
         }
     }
@@ -158,14 +156,23 @@ export async function runAgent(ctx, type, prompt, options) {
     // When skills is string[], we've already preloaded them into the prompt.
     // 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();
     // Resolve model: explicit option > config.model > parent model
@@ -174,17 +181,17 @@ export async function runAgent(ctx, type, prompt, options) {
     const thinkingLevel = options.thinkingLevel ?? agentConfig?.thinking;
     const sessionOpts = {
         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);
     // Build disallowed tools set from agent config
     const disallowedSet = agentConfig?.disallowedTools
@@ -193,13 +200,13 @@ export async function runAgent(ctx, type, prompt, options) {
     // 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))
+            if (builtinToolNameSet.has(t))
                 return true;
             if (Array.isArray(extensions)) {
                 return extensions.some(ext => t.startsWith(ext) || t.includes(ext));

package/dist/agent-types.d.ts

@@ -4,9 +4,8 @@
  * Merges embedded default agents with user-defined agents from .pi/agents/*.md.
  * 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 type { AgentConfig } from "./types.js";
-/** All known built-in tool names, derived from the factory registry. */
+/** All known built-in tool names. */
 export declare const BUILTIN_TOOL_NAMES: string[];
 /**
  * Register agents into the unified registry.
@@ -29,17 +28,15 @@ export declare function getUserAgentNames(): string[];
 /** Check if a type is valid and enabled (case-insensitive). */
 export declare function isValidType(type: string): boolean;
 /**
- * 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 declare function getMemoryTools(cwd: string, existingToolNames: Set<string>): AgentTool<any>[];
+export declare function getMemoryToolNames(existingToolNames: Set<string>): string[];
 /**
- * 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 declare function getReadOnlyMemoryTools(cwd: string, existingToolNames: Set<string>): AgentTool<any>[];
-/** Get built-in tools for a type (case-insensitive). */
-export declare function getToolsForType(type: string, cwd: string): AgentTool<any>[];
+export declare function getReadOnlyMemoryToolNames(existingToolNames: Set<string>): string[];
+/** Get built-in tool names for a type (case-insensitive). */
+export declare function getToolNamesForType(type: string): string[];
 /** Get config for a type (case-insensitive, returns a SubagentTypeConfig-compatible object). Falls back to general-purpose. */
 export declare function getConfig(type: string): {
     displayName: string;

package/dist/agent-types.js

@@ -4,19 +4,9 @@
  * Merges embedded default agents with user-defined agents from .pi/agents/*.md.
  * User agents override defaults with the same name. Disabled agents are kept but excluded from spawning.
  */
-import { createBashTool, createEditTool, createFindTool, createGrepTool, createLsTool, createReadTool, createWriteTool, } from "@mariozechner/pi-coding-agent";
 import { DEFAULT_AGENTS } from "./default-agents.js";
-const TOOL_FACTORIES = {
-    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 = ["read", "bash", "edit", "write", "grep", "find", "ls"];
 /** Unified runtime registry of all agents (defaults + user-defined). */
 const agents = new Map();
 /**
@@ -87,32 +77,26 @@ export function isValidType(type) {
 /** Tool names required for memory management. */
 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, existingToolNames) {
-    return MEMORY_TOOL_NAMES
-        .filter(n => !existingToolNames.has(n) && n in TOOL_FACTORIES)
-        .map(n => TOOL_FACTORIES[n](cwd));
+export function getMemoryToolNames(existingToolNames) {
+    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, existingToolNames) {
-    return READONLY_MEMORY_TOOL_NAMES
-        .filter(n => !existingToolNames.has(n) && n in TOOL_FACTORIES)
-        .map(n => TOOL_FACTORIES[n](cwd));
+export function getReadOnlyMemoryToolNames(existingToolNames) {
+    return READONLY_MEMORY_TOOL_NAMES.filter(n => !existingToolNames.has(n));
 }
-/** Get built-in tools for a type (case-insensitive). */
-export function getToolsForType(type, cwd) {
+/** Get built-in tool names for a type (case-insensitive). */
+export function getToolNamesForType(type) {
     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. */
 export function getConfig(type) {

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.d.ts

@@ -9,5 +9,5 @@
  * Commands:
  *   /agents                 — Interactive agent management menu
  */
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { type ExtensionAPI } from "@mariozechner/pi-coding-agent";
 export default function (pi: ExtensionAPI): void;

package/dist/index.js

@@ -10,8 +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, getAgentDir } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
@@ -23,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. */
@@ -383,7 +384,7 @@ export default function (pi) {
         currentCtx = ctx;
         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,
         pi,
@@ -477,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. */
@@ -488,8 +489,17 @@ 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({
+    pi.registerTool(defineTool({
         name: "Agent",
         label: "Agent",
         description: `Launch a new agent to handle complex, multi-step tasks autonomously.
@@ -521,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.',
@@ -847,9 +857,9 @@ Guidelines:
             return textResult(`${fallbackNote}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getStatusNote(record.status)}.\n\n` +
                 (record.result?.trim() || "No output."), details);
         },
-    });
+    }));
     // ---- get_subagent_result tool ----
-    pi.registerTool({
+    pi.registerTool(defineTool({
         name: "get_subagent_result",
         label: "Get Agent Result",
         description: "Check status and retrieve results from a background agent. Use the agent ID returned by Agent with run_in_background.",
@@ -908,9 +918,9 @@ Guidelines:
             }
             return textResult(output);
         },
-    });
+    }));
     // ---- steer_subagent tool ----
-    pi.registerTool({
+    pi.registerTool(defineTool({
         name: "steer_subagent",
         label: "Steer Agent",
         description: "Send a steering message to a running agent. The message will interrupt the agent after its current tool execution " +
@@ -948,10 +958,10 @@ 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) {
         const projectPath = join(projectAgentsDir(), `${name}.md`);
@@ -1179,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;
@@ -1250,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;
@@ -1285,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;
@@ -1462,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()})`,
@@ -1477,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");
@@ -1490,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");
@@ -1507,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");
@@ -1523,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/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";
+};