pi-better-subagents 0.15.0 → 0.16.0

package/README.md

@@ -35,7 +35,7 @@ Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or ne
 
 ## Delegation Modes
 
-`config.json` sets `delegationMode` to `manual`, `adaptive` (default), or
+The user config sets `delegationMode` to `manual`, `adaptive` (default), or
 `coordinator`. `/subagents settings` (or `/subagents`) opens a settings page
 for delegation mode and the concurrent-subagent cap (default 4). Edits apply to
 this session and persist across reloads; Ctrl+S saves both as defaults, and
@@ -51,6 +51,14 @@ uses `agents_catalog` to discover current role descriptions and delegates every
 nontrivial role-owned task, while the foreground coordinates, integrates, and
 verifies. See [usage notes](docs/usage.md#delegation-mode).
 
+Saved defaults live in global `~/.pi/agent/settings.json` under
+`piBetterHarness.subagents` (or under `PI_CODING_AGENT_DIR`) and survive package
+reinstalls and upgrades. The old user config migrates on first use. Global values
+override the package's `config.json`, which remains a compatibility fallback.
+Save existing mode and cap choices with `/subagents save` or Ctrl+S. Put other
+custom config keys in `piBetterHarness.subagents` as well; edits made only inside
+the installed package can be lost on upgrade.
+
 `agents_catalog` shows each role's and named agent's default model and effort,
 such as `role developer "Developer" … default openai/gpt-6.1-sol@high`. Roles are
 listed and passed by short name (`role: "developer"`); the stored id

package/agent-commands.ts

@@ -137,21 +137,23 @@ export function registerAgentCommands(pi: Pick<ExtensionAPI, "registerCommand">,
             return items.length > 0 ? items : null;
         },
         async handler(args: string, ctx: ExtensionCommandContext) {
-            // Every invocation, including help and a dismissed picker. The
-            // context argument is the current session, not the one captured
-            // when the command was registered.
-            deps.propagateCommandContext?.(ctx);
-            return executeAgentsCommand(args, {
-                cwd: ctx.cwd,
-                hasUI: ctx.hasUI,
-                mode: ctx.mode,
-                isProjectTrusted: () => ctx.isProjectTrusted(),
-                ui: ctx.ui,
-            }, deps);
+            return executeAgentsCommandContext(args, ctx, deps);
         },
     });
 }
 
+/** Slash commands and settings shortcuts must resolve against the same live context. */
+export function executeAgentsCommandContext(args: string, ctx: ExtensionCommandContext, deps: AgentCommandDeps = {}): Promise<AgentCommandResult> {
+    deps.propagateCommandContext?.(ctx);
+    return executeAgentsCommand(args, {
+        cwd: ctx.cwd,
+        hasUI: ctx.hasUI,
+        mode: ctx.mode,
+        isProjectTrusted: () => ctx.isProjectTrusted(),
+        ui: ctx.ui,
+    }, deps);
+}
+
 export async function executeAgentsCommand(args: string, host: AgentCommandHost, deps: AgentCommandDeps = {}): Promise<AgentCommandResult> {
     const parsed = parseCommandArgs(args);
     if (parsed.positionals.length === 0 && parsed.flags.size === 0 && host.mode === "tui" && host.hasUI && host.ui.custom) parsed.positionals.push("list");

package/agent-operations.ts

@@ -18,17 +18,19 @@
 import { agentsCatalogTool, type DiscoveryDeps } from "./agents-catalog-tool.ts";
 import {
     executeAgentsCommand,
+    executeAgentsCommandContext,
     registerAgentCommands,
     type AgentCommandDeps,
     type AgentCommandHost,
     type AgentCommandResult,
 } from "./agent-commands.ts";
 import { resolveRoleAssignment, type RoleAssignment, type RoleAssignmentDecision } from "./role-assignment.ts";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
 export interface AgentOperationsDeps extends AgentCommandDeps, DiscoveryDeps {}
 
 export interface AgentOperationsHandle {
+    openCatalog(ctx: ExtensionCommandContext): Promise<void>;
     registerCommands(pi: Pick<ExtensionAPI, "registerCommand">): void;
     createDiscoveryTool(Type: Parameters<typeof agentsCatalogTool>[0]): ReturnType<typeof agentsCatalogTool>;
     executeCommand(args: string, host: AgentCommandHost): Promise<AgentCommandResult>;
@@ -40,6 +42,9 @@ export interface AgentOperationsHandle {
 
 export function createAgentOperations(deps: AgentOperationsDeps = {}): AgentOperationsHandle {
     return {
+        async openCatalog(ctx) {
+            await executeAgentsCommandContext("", ctx, deps);
+        },
         registerCommands(pi) {
             registerAgentCommands(pi, deps);
         },

package/config.ts

@@ -1,6 +1,6 @@
 /**
- * Extension config — a single `config.json` next to this file sets defaults for
- * every subagent, each overridable per `subagent_spawn` call.
+ * User config overrides the shipped `config.json` defaults for every subagent,
+ * each overridable per `subagent_spawn` call. Saves never edit installed files.
  *
  *   { "defaultModel": "xai/grok-4.5", "defaultTools": "read, bash, web_fetch" }
  *
@@ -8,13 +8,14 @@
  * `defaultTools` absent → the built-in SAFE_DEFAULT_TOOLS.
  */
 
-import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { SELF_SPEC } from "./extensions.ts";
 import { isDelegationMode, type DelegationMode } from "./delegation.ts";
 import type { TimingSettings } from "./timing.ts";
+import { harnessSettingsPath, readHarnessSetting, updateHarnessSetting } from "./shared-harness-settings.ts";
 
 export interface SubagentConfig extends TimingSettings {
     /** Foreground delegation policy; /subagents mode overrides this for the current session. */
@@ -89,65 +90,82 @@ export const SAFE_CLEAN_TOOLS = "read, bash";
 
 let cached: SubagentConfig | undefined;
 let configPathForTests: string | undefined;
+let bundledConfigPathForTests: string | undefined;
 
 /** Test seam. Pass undefined to reload config.json on the next loadConfig call. */
 export function setConfigForTests(next: SubagentConfig | undefined): void {
     cached = next;
 }
 
-/** Test seam. Save and load use this file instead of the package config.json. */
-export function setConfigPathForTests(path: string | undefined): void {
+/** Test seam. Isolate user config, optionally supplying a package fallback. */
+export function setConfigPathForTests(path: string | undefined, bundledPath?: string): void {
     configPathForTests = path;
+    bundledConfigPathForTests = bundledPath;
     cached = undefined;
 }
 
 export function configPath(): string {
-    return configPathForTests ?? join(dirname(fileURLToPath(import.meta.url)), "config.json");
+    return harnessSettingsPath(configSeams());
 }
 
-/** Load config.json from the extension directory. Missing/invalid → {}. */
-export function loadConfig(): SubagentConfig {
-    if (cached) return cached;
+function configSeams() {
+    return { agentDir: () => configPathForTests ? dirname(configPathForTests) : piAgentDir() };
+}
+
+function readConfig(path: string): SubagentConfig {
+    return parseConfig(JSON.parse(readFileSync(path, "utf-8")));
+}
+
+function parseConfig(parsed: unknown): SubagentConfig {
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Config must be a JSON object.");
+    return parsed as SubagentConfig;
+}
+
+function savedConfig(): SubagentConfig {
+    const user = readHarnessSetting("subagents", configSeams(), configPathForTests ? undefined : {
+        path: join(piAgentDir(), "extensions", "pi-better-subagents-config.json"), parse: parseConfig,
+    });
+    return user === undefined ? {} : parseConfig(user);
+}
+
+function bundledConfig(): SubagentConfig {
+    const path = bundledConfigPathForTests ?? (configPathForTests ? undefined : join(selfDir(), "config.json"));
+    if (!path) return {};
     try {
-        cached = JSON.parse(readFileSync(configPath(), "utf-8")) as SubagentConfig;
+        return readConfig(path);
     } catch {
-        cached = {};
+        return {};
     }
+}
+
+/** Saved user choices take precedence; missing/invalid files contribute no keys. */
+export function loadConfig(): SubagentConfig {
+    if (cached) return cached;
+    let user: SubagentConfig = {};
+    try { user = savedConfig(); } catch { /* retain package fallback */ }
+    cached = { ...bundledConfig(), ...user };
     return cached;
 }
 
-/** Write delegationMode into config.json, preserving every other key. */
+/** Save the navigator's mode-only default without replacing the saved cap. */
 export function writeDelegationMode(mode: DelegationMode, path = configPath()): void {
     if (!isDelegationMode(mode)) throw new Error(`Invalid delegation mode: ${String(mode)}`);
-    let current: SubagentConfig = {};
-    try {
-        const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) current = parsed as SubagentConfig;
-    } catch { /* missing file starts as an empty config */ }
-    current.delegationMode = mode;
-    const pending = `${path}.${process.pid}.tmp`;
-    writeFileSync(pending, `${JSON.stringify(current, null, 2)}\n`);
-    renameSync(pending, path);
-    if (path === configPath()) cached = current;
+    writeConfigSettings({ delegationMode: mode }, path);
 }
 
 /** Save human-facing defaults together, preserving unrelated configuration. */
 export function writeSubagentSettings(settings: { delegationMode: DelegationMode; maxConcurrent: number }, path = configPath()): void {
     if (!isDelegationMode(settings.delegationMode)) throw new Error("Invalid delegation mode.");
     if (!isConcurrencyCap(settings.maxConcurrent)) throw new Error("Concurrent subagents must be a positive whole number.");
-    let current: Record<string, unknown> = {};
-    try {
-        const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Config must be a JSON object.");
-        current = parsed as Record<string, unknown>;
-    } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-    }
-    Object.assign(current, settings);
-    const pending = `${path}.${process.pid}.tmp`;
-    writeFileSync(pending, `${JSON.stringify(current, null, 2)}\n`);
-    renameSync(pending, path);
-    if (path === configPath()) cached = current as SubagentConfig;
+    writeConfigSettings(settings, path);
+}
+
+function writeConfigSettings(settings: Partial<SubagentConfig>, path: string): void {
+    if (path === configPath()) savedConfig();
+    const current = updateHarnessSetting("subagents", previous => ({
+        ...(previous === undefined ? {} : parseConfig(previous)), ...settings,
+    }), { agentDir: () => dirname(path) });
+    if (path === configPath()) cached = { ...bundledConfig(), ...current };
 }
 
 /** Normalize a comma/space tool list to pi's bare comma form: "a, b" → "a,b". */

package/docs/usage.md

@@ -14,7 +14,8 @@ launch is the result · completion triggers fetch · the foreground never blocks
 
 ## Delegation Mode
 
-Set `delegationMode` in this package's `config.json` to `manual`, `adaptive`, or
+Set `delegationMode` in the user config described under
+[Tool scoping](#tool-scoping-allowlist) to `manual`, `adaptive`, or
 `coordinator` (default `adaptive`). This controls foreground delegation guidance,
 not child permissions or catalog definitions. `/subagents settings` (or simply
 `/subagents`) opens the terminal settings page with mode and concurrent-subagent
@@ -438,7 +439,17 @@ Precedence, highest first: the per-call `tools` param → `config.json`
 web_fetch`; just `read, bash` in a `clean` child). `exclude_tools` subtracts on
 top.
 
-`config.json` (next to the extension) also sets:
+User configuration lives in
+`~/.pi/agent/settings.json` under `piBetterHarness.subagents` (under
+`PI_CODING_AGENT_DIR` when set). The old user config migrates on first use.
+Its keys override the package's `config.json`,
+which is still read as a compatibility fallback. Settings saves write only the
+user file, so saved mode and cap survive reinstalls and upgrades without freezing
+other shipped defaults. To retain custom keys from an older package-local config,
+copy those keys into the user file before upgrading. Already-overwritten values
+cannot be recovered automatically.
+
+The effective config also sets:
 
 - `defaultModel` — model for spawns that don't specify one (`null` = inherit the
   foreground model).

package/index.ts

@@ -2300,7 +2300,11 @@ export default function (pi: ExtensionAPI) {
         }
     };
     const contribution = { id: "subagents", label: "Subagents", command: "/subagents settings", open: openSettings };
-    const registerSettings = () => pi.events?.emit("harness-settings:register", contribution);
+    const agentsContribution = { id: "agents", label: "Agents", command: "/agents", open: agentOperations.openCatalog };
+    const registerSettings = () => {
+        pi.events?.emit("harness-settings:register", contribution);
+        pi.events?.emit("harness-settings:register", agentsContribution);
+    };
     const unsubscribeSettingsRequest = pi.events?.on?.("harness-settings:request", registerSettings);
     registerSettings();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",
@@ -61,6 +61,7 @@
     "@earendil-works/pi-tui": "*"
   },
   "dependencies": {
+    "proper-lockfile": "^4.1.2",
     "smol-toml": "1.9.0",
     "yaml": "^2.9.1"
   }

package/shared-callback-batcher.ts

@@ -1,8 +1,12 @@
 // Generated from packages/callback-batcher/index.ts. Do not edit directly.
-import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import {
+  harnessSettingsPath,
+  readHarnessSetting,
+  updateHarnessSetting,
+  type HarnessSettingsSeams,
+} from "./shared-harness-settings.ts";
 
 export type CallbackSource = "subagent" | "background-task";
 export type CallbackDetailTool = "subagent_result" | "bg_task_status";
@@ -13,9 +17,7 @@ export interface CallbackSettingsContext {
   ui?: { notify(message: string, type: "error"): void };
 }
 
-export interface CallbackSettingsSeams {
-  agentDir?: () => string;
-}
+export type CallbackSettingsSeams = HarnessSettingsSeams;
 
 export interface CallbackSettings {
   mode: CallbackDeliveryMode;
@@ -36,7 +38,12 @@ function validCallbackPreferences(value: unknown): value is { version: 1; mode:
     && data.version === 1 && isDeliveryMode(data.mode);
 }
 
-function callbackPreferencesPath(seams: CallbackSettingsSeams): string {
+function parseCallbackPreferences(value: unknown): { version: 1; mode: CallbackDeliveryMode } {
+  if (!validCallbackPreferences(value)) throw new Error('Expected { version: 1, mode: "hold" | "steer" }');
+  return value;
+}
+
+function legacyCallbackPreferencesPath(seams: CallbackSettingsSeams): string {
   return join((seams.agentDir ?? getAgentDir)(), "extensions", CALLBACK_PREFERENCES_FILE);
 }
 
@@ -64,41 +71,27 @@ function getSessionDefault(ctx: CallbackSettingsContext, seams: CallbackSettings
     if (ctx.sessionManager) defaults.set(ctx.sessionManager, { sessionId, mode });
     return { mode, source: "default" };
   };
-  const path = callbackPreferencesPath(seams);
-  let text: string;
+  const path = harnessSettingsPath(seams);
   try {
-    text = readFileSync(path, "utf8");
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return snapshot("hold");
-    throw new Error(`Cannot read callback default at ${path}: ${String(error)}`, { cause: error });
-  }
-  try {
-    const data: unknown = JSON.parse(text);
-    if (!validCallbackPreferences(data)) throw new Error('Expected { version: 1, mode: "hold" | "steer" }');
-    return snapshot(data.mode);
+    const data = readHarnessSetting<{ version: 1; mode: CallbackDeliveryMode }>("callbacks", seams, {
+      path: legacyCallbackPreferencesPath(seams),
+      parse: parseCallbackPreferences,
+    });
+    return snapshot(data === undefined ? "hold" : parseCallbackPreferences(data).mode);
   } catch (error) {
-    throw new Error(`Invalid callback default at ${path}: ${String(error)}`, { cause: error });
+    const prefix = (error as NodeJS.ErrnoException).code ? "Cannot read" : "Invalid";
+    throw new Error(`${prefix} callback default at ${path}: ${String(error)}`, { cause: error });
   }
 }
 
 /** Saves only the future-session default; never changes the active branch or batcher. */
 export function saveCallbackDefault(mode: CallbackDeliveryMode, seams: CallbackSettingsSeams = {}): void {
   if (!isDeliveryMode(mode)) throw new Error("Invalid callback delivery mode. Nothing saved.");
-  const dir = join((seams.agentDir ?? getAgentDir)(), "extensions");
-  const path = join(dir, CALLBACK_PREFERENCES_FILE);
-  const tmp = join(dir, `.${CALLBACK_PREFERENCES_FILE}.${randomUUID()}.tmp`);
-  let created = false;
+  const path = harnessSettingsPath(seams);
   try {
-    mkdirSync(dir, { recursive: true });
-    const fd = openSync(tmp, "wx", 0o600);
-    created = true;
-    try { writeFileSync(fd, `${JSON.stringify({ version: 1, mode })}\n`); }
-    finally { closeSync(fd); }
-    renameSync(tmp, path);
+    updateHarnessSetting("callbacks", () => ({ version: 1, mode }), seams);
   } catch (error) {
     throw new Error(`Cannot save callback default at ${path}: ${String(error)}`, { cause: error });
-  } finally {
-    if (created) rmSync(tmp, { force: true });
   }
 }
 

package/shared-harness-settings.ts

@@ -0,0 +1,114 @@
+// Generated from packages/harness-settings/index.ts. Do not edit directly.
+import { existsSync, lstatSync, realpathSync, readFileSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+// Match Pi's settings lock without depending on a private SDK import.
+const lockfile = createRequire(import.meta.url)("proper-lockfile") as {
+  lockSync(path: string, options: { realpath: boolean }): () => void;
+};
+const NAMESPACE = "piBetterHarness";
+export interface HarnessSettingsSeams { agentDir?: () => string }
+
+export function harnessSettingsPath(seams: HarnessSettingsSeams = {}): string {
+  return join((seams.agentDir ?? getAgentDir)(), "settings.json");
+}
+
+function object(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be a JSON object.`);
+  return value as Record<string, unknown>;
+}
+
+function readSettings(path: string): Record<string, unknown> {
+  try { return object(JSON.parse(readFileSync(path, "utf8")), `Settings at ${path}`); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+function section(settings: Record<string, unknown>): Record<string, unknown> {
+  return Object.hasOwn(settings, NAMESPACE) ? object(settings[NAMESPACE], NAMESPACE) : {};
+}
+
+function acquire(path: string): () => void {
+  for (let attempt = 0; attempt < 10; attempt++) {
+    try { return lockfile.lockSync(path, { realpath: false }); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ELOCKED" || attempt === 9) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+    }
+  }
+  throw new Error(`Cannot lock settings at ${path}`);
+}
+
+function lockedRead(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  const release = acquire(path);
+  try { return readSettings(path); } finally { release(); }
+}
+
+function writeDestination(path: string): string {
+  let stat;
+  try { stat = lstatSync(path); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return path;
+    throw error;
+  }
+  // Keep managed dotfiles links intact. A dangling link fails rather than being replaced.
+  return stat.isSymbolicLink() ? realpathSync(path) : path;
+}
+
+function mutate<T>(seams: HarnessSettingsSeams, change: (values: Record<string, unknown>) => T): T {
+  const path = harnessSettingsPath(seams);
+  mkdirSync((seams.agentDir ?? getAgentDir)(), { recursive: true });
+  const release = acquire(path);
+  let pending: string | undefined;
+  try {
+    // Read inside the lock so another session's settings are never replaced by a stale snapshot.
+    const settings = readSettings(path);
+    const values = section(settings);
+    const result = change(values);
+    settings[NAMESPACE] = values;
+    const destination = writeDestination(path);
+    pending = `${destination}.${randomUUID()}.tmp`;
+    writeFileSync(pending, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    renameSync(pending, destination);
+    return result;
+  } finally {
+    try { if (pending) rmSync(pending, { force: true }); } finally { release(); }
+  }
+}
+
+export function readHarnessSetting<T = unknown>(
+  key: string,
+  seams: HarnessSettingsSeams = {},
+  legacy?: { path: string; parse: (value: unknown) => T },
+): T | undefined {
+  const values = section(lockedRead(harnessSettingsPath(seams)));
+  if (Object.hasOwn(values, key)) return values[key] as T;
+  if (!legacy) return undefined;
+  let raw: string;
+  try { raw = readFileSync(legacy.path, "utf8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+  const migrated = legacy.parse(JSON.parse(raw));
+  return mutate(seams, current => {
+    if (!Object.hasOwn(current, key)) current[key] = migrated;
+    return current[key] as T;
+  });
+}
+
+export function updateHarnessSetting<T>(
+  key: string, update: (current: unknown) => T, seams: HarnessSettingsSeams = {},
+): T {
+  return mutate(seams, values => {
+    const next = update(values[key]);
+    values[key] = next;
+    return next;
+  });
+}