pi-better-subagents 0.17.0 → 0.19.0

package/README.md

@@ -42,8 +42,21 @@ this session and persist across reloads; Ctrl+S saves both as defaults, and
 Reset to defaults clears
 session overrides. `/subagents mode manual|adaptive|coordinator` and
 `/subagents cap <number>` are command equivalents; `/subagents save` persists
-both. Lowering the cap blocks new single and batch launches without stopping
-running work. The navigator's `main` row retains its mode-only controls:
+both. Lowering the cap blocks new single and batch launches, including launches
+still preparing, without stopping running work. Saved configuration changes are
+picked up on subsequent reads; explicit session overrides still take precedence.
+Before every model request, including continuations after tool calls,
+the foreground receives one temporary settings block with the current mode, cap,
+setting sources, revision, and running/reserved/available slots. The latest block
+replaces older snapshots and delegation guidance; it is not saved as conversation
+history. Changes reach the model at its next request, not during an in-flight
+response, and are not broadcast to running children. The cap is a ceiling, not a
+target number of agents. `subagent_settings` inspects the same effective state
+without changing it. Its revision is a stable fingerprint of mode, cap, and
+sources; occupancy changes do not change the revision. Admission rechecks capacity
+when spawning because the snapshot can become stale.
+
+The navigator's `main` row retains its mode-only controls:
 `m` cycles the session mode, `ctrl+s` saves that default, and `x`
 does not stop it. Manual delegates only on explicit user or workflow request, even with a
 plan. Adaptive delegates substantial independent work when useful. Coordinator

package/config.ts

@@ -8,7 +8,7 @@
  * `defaultTools` absent → the built-in SAFE_DEFAULT_TOOLS.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
@@ -89,19 +89,23 @@ export const SAFE_DEFAULT_TOOLS = "read, bash, edit, write, web_search, web_fetc
 export const SAFE_CLEAN_TOOLS = "read, bash";
 
 let cached: SubagentConfig | undefined;
+let cachedIdentity: string | undefined;
+let configOverrideForTests = false;
 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;
+    cachedIdentity = undefined;
+    configOverrideForTests = next !== undefined;
 }
 
 /** 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;
+    setConfigForTests(undefined);
 }
 
 export function configPath(): string {
@@ -128,8 +132,12 @@ function savedConfig(): SubagentConfig {
     return user === undefined ? {} : parseConfig(user);
 }
 
+function bundledConfigPath(): string | undefined {
+    return bundledConfigPathForTests ?? (configPathForTests ? undefined : join(selfDir(), "config.json"));
+}
+
 function bundledConfig(): SubagentConfig {
-    const path = bundledConfigPathForTests ?? (configPathForTests ? undefined : join(selfDir(), "config.json"));
+    const path = bundledConfigPath();
     if (!path) return {};
     try {
         return readConfig(path);
@@ -138,12 +146,31 @@ function bundledConfig(): SubagentConfig {
     }
 }
 
+function configIdentity(): string {
+    const paths = [configPath(), bundledConfigPath(),
+        configPathForTests ? undefined : join(piAgentDir(), "extensions", "pi-better-subagents-config.json")];
+    return JSON.stringify(paths.map(path => {
+        if (!path) return null;
+        try {
+            const stat = statSync(path, { bigint: true });
+            return [path, stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].map(String);
+        } catch (error) {
+            return [path, (error as NodeJS.ErrnoException).code];
+        }
+    }));
+}
+
 /** Saved user choices take precedence; missing/invalid files contribute no keys. */
 export function loadConfig(): SubagentConfig {
-    if (cached) return cached;
+    if (configOverrideForTests) return cached!;
+    const identity = configIdentity();
+    if (cached && cachedIdentity === identity) return cached;
     let user: SubagentConfig = {};
     try { user = savedConfig(); } catch { /* retain package fallback */ }
     cached = { ...bundledConfig(), ...user };
+    // Keep the pre-read identity: migration or a concurrent replacement must
+    // trigger another read rather than label an older value with a newer stat.
+    cachedIdentity = identity;
     return cached;
 }
 
@@ -162,10 +189,10 @@ export function writeSubagentSettings(settings: { delegationMode: DelegationMode
 
 function writeConfigSettings(settings: Partial<SubagentConfig>, path: string): void {
     if (path === configPath()) savedConfig();
-    const current = updateHarnessSetting("subagents", previous => ({
+    updateHarnessSetting("subagents", previous => ({
         ...(previous === undefined ? {} : parseConfig(previous)), ...settings,
     }), { agentDir: () => dirname(path) });
-    if (path === configPath()) cached = { ...bundledConfig(), ...current };
+    if (path === configPath()) setConfigForTests(undefined);
 }
 
 /** Normalize a comma/space tool list to pi's bare comma form: "a, b" → "a,b". */

package/delegation.ts

@@ -15,7 +15,7 @@ export function normalizeDelegationMode(value: unknown): DelegationMode {
 export function delegationPrompt(mode: DelegationMode): string {
     switch (mode) {
         case "manual":
-            return "Delegation mode: manual. Do not proactively delegate work. Use subagents only when the user explicitly asks for delegation or an active workflow explicitly requires it. A structured plan or plan mode does not override this restriction; perform planned work in the foreground unless explicitly required otherwise.";
+            return "Delegation mode: manual. Do not proactively delegate work to subagents. Use subagents only when the user explicitly asks for delegation or an active workflow explicitly requires it. A structured plan or plan mode does not override this restriction. This restricts subagent delegation, not execution concurrency: independent foreground tools and background tasks still follow the Harness execution policy.";
         case "coordinator":
             return "Delegation mode: coordinator. The foreground coordinates, integrates, and verifies. Call agents_catalog to discover current available roles and inspect their descriptions. Pass a role to subagent_spawn by its short name, as listed (role: \"developer\"). Delegate every nontrivial task covered by an available role according to its current description; do not assume bundled roles are unchanged. Keep orchestration, cross-role decisions, unowned or ambiguous work, integration, and final verification in the foreground. Inspect results and failures before concluding; do not poll for running children.";
         case "adaptive":

package/docs/usage.md

@@ -97,6 +97,7 @@ thresholds continue to take precedence for subagent health.
 |------|---------|--------------|
 | `subagent_spawn` | never | Launch a task in a background subagent; returns a run id at once. Params: `prompt`, `name`, `model`, `tools` (allowlist), `exclude_tools`, `sandbox`, `sandbox_dir`, `callback`, `clean`, `cwd`, `git_clone_workspace`, `approve`, `allow_nested`, and the [timing](#run-timing-deadline-ceiling-stuck) overrides `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`. |
 | `subagent_spawn_batch` | never | Launch several independent subagents at once. Each job becomes a normal run. Params: `batchName`, `shared` (options applied to every job), `jobs[]` (each needs `prompt`; same optional params as `subagent_spawn`), `onCapacity` (`reject` or `launch-available`). |
+| `subagent_settings` | never | Read-only effective settings and capacity snapshot. No parameters. Returns `delegationMode`, `maxConcurrent`, per-setting `sources` (`session` or `config`), a stable settings `revision`, `runningCount`, `pendingCount`, `occupiedSlots`, and `availableSlots`. The limit is a ceiling, not a target; spawn admission rechecks live capacity. |
 | `subagent_list` | never | Compact current-session list (default 10 rows / 1 KiB page). Params: `all` (machine-global / foreign session), `limit` (default 10, max 100), `cursor`, `max_bytes` (max 4 KiB), `status` (`running`, `completed`, `failed`, `killed`, `exited`, durable `orphaned`, `lost`). Incident counts are compact; no spend/tool histories. |
 | `subagent_output` | never | Bounded current-session excerpt (default 1 KiB / 10 lines). Params: `id`, `lines` (`tail_lines` is a deprecated alias), `cursor` (a returned `nextCursor`, `statusCursor`, or `incidentCursor`), `max_bytes` (max 4 KiB; raw 16 KiB default, 64 KiB max), `mode` (`raw` pages retained log bytes), `include` (`["cost"]`, `["tools"]`, or both: opt-in spend and tool-count lines), `all` (foreign-session id). Missing/unreadable logs are gaps, not empty healthy output. |
 | `subagent_result` | never | Finished-run answer for the current session (2048-byte page). Params: `id`, `cursor` (a returned `nextCursor` continues the answer; `statusCursor` / `incidentCursor` also accepted), `max_bytes` (maximum 8192 bytes), `lines` (optional line cap per answer page), `mode` (`raw`), `include` (`["cost"]`, `["tools"]`, or both), `all` (foreign-session id). Failures and exceptional lifecycle facts come before progress; no tool-name histories. TUI folding is display-only. |

package/effective-settings.ts

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import { delegationPrompt, type DelegationMode } from "./delegation.ts";
+
+export const SUBAGENT_SETTINGS_CONTEXT = "pi-better-subagents-settings";
+
+export interface EffectiveSubagentSettings {
+    revision: string;
+    delegationMode: DelegationMode;
+    maxConcurrent: number;
+    sources: { delegationMode: "session" | "config"; maxConcurrent: "session" | "config" };
+    runningCount: number;
+    pendingCount: number;
+    occupiedSlots: number;
+    availableSlots: number;
+}
+
+export function effectiveSubagentSettings(
+    settings: Pick<EffectiveSubagentSettings, "delegationMode" | "maxConcurrent" | "sources">,
+    runningCount: number,
+    pendingCount: number,
+): EffectiveSubagentSettings {
+    const revision = createHash("sha256").update(JSON.stringify([
+        settings.delegationMode, settings.maxConcurrent, settings.sources.delegationMode, settings.sources.maxConcurrent,
+    ])).digest("hex").slice(0, 12);
+    const occupiedSlots = runningCount + pendingCount;
+    return { ...settings, revision, runningCount, pendingCount, occupiedSlots,
+        availableSlots: Math.max(0, settings.maxConcurrent - occupiedSlots) };
+}
+
+export function formatSubagentSettings(settings: EffectiveSubagentSettings): string {
+    return [
+        `Subagent settings: revision ${settings.revision}`,
+        `Delegation: ${settings.delegationMode} (${settings.sources.delegationMode})`,
+        `Concurrency limit: ${settings.maxConcurrent} (${settings.sources.maxConcurrent})`,
+        `Running: ${settings.runningCount}; reserved: ${settings.pendingCount}`,
+        `Occupied slots: ${settings.occupiedSlots}`,
+        `Available slots: ${settings.availableSlots}`,
+        "The limit is a ceiling, not a target. Launch ready, independent, useful work within available capacity. " +
+            "This is a point-in-time snapshot; spawn admission rechecks capacity. Lowering the limit does not stop existing runs.",
+        delegationPrompt(settings.delegationMode),
+    ].join("\n");
+}
+
+export function subagentSettingsTool(Type: any, read: () => EffectiveSubagentSettings) {
+    return {
+        name: "subagent_settings",
+        label: "Subagent Settings",
+        description: "Inspect effective subagent delegation mode, concurrency limit, setting sources, revision, and running/reserved/available slots. Read-only; does not change settings or launch work. The limit is a ceiling, not a target.",
+        parameters: Type.Object({}),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        outputSchema: Type.Object({
+            revision: Type.String(), delegationMode: Type.String(), maxConcurrent: Type.Number({ minimum: 1, multipleOf: 1 }),
+            sources: Type.Object({ delegationMode: Type.String(), maxConcurrent: Type.String() }),
+            runningCount: Type.Number({ minimum: 0, multipleOf: 1 }), pendingCount: Type.Number({ minimum: 0, multipleOf: 1 }),
+            occupiedSlots: Type.Number({ minimum: 0, multipleOf: 1 }), availableSlots: Type.Number({ minimum: 0, multipleOf: 1 }),
+        }),
+        async execute() {
+            const settings = read();
+            return { content: [{ type: "text" as const, text: formatSubagentSettings(settings) }],
+                details: settings, structuredContent: settings };
+        },
+    };
+}

package/index.ts

@@ -37,6 +37,7 @@ import { parseRun, readRunTranscript, resetParseRunCursor, type Usage } from "./
 import { finalizeRun as finalizeRunCore } from "./finalization.ts";
 import { loadConfig, writeDelegationMode, writeSubagentSettings, isConcurrencyCap, normalizeConcurrencyCap, normalizeTools, resolveExtensionPath, selfDir, SAFE_DEFAULT_TOOLS, SAFE_CLEAN_TOOLS } from "./config.ts";
 import { createSubagentSettingsPage } from "./settings-page.ts";
+import { effectiveSubagentSettings, formatSubagentSettings, subagentSettingsTool, SUBAGENT_SETTINGS_CONTEXT } from "./effective-settings.ts";
 import { STEER_FILE_ENV, readSteerReceipt } from "./child-steer.ts";
 import {
     decideTiming,
@@ -53,7 +54,8 @@ import {
     type TimingStopReason,
 } from "./timing.ts";
 import { readAppendedLines, type LogCursor } from "./log-cursor.ts";
-import { DELEGATION_MODES, DELEGATION_MODE_REQUEST, delegationPrompt, isDelegationMode, normalizeDelegationMode, type DelegationMode } from "./delegation.ts";
+import { DELEGATION_MODES, DELEGATION_MODE_REQUEST, isDelegationMode, normalizeDelegationMode, type DelegationMode } from "./delegation.ts";
+import { appendExecutionPolicy } from "./shared-execution-policy.ts";
 import { resolveExtensions, extensionArgs } from "./extensions.ts";
 import { prepareTaskRuntime } from "./task-policy.ts";
 import { canonicalizePath, takeRecoverySnapshot } from "./shared-sandbox-core.ts";
@@ -185,6 +187,7 @@ const SUBAGENT_TOOLS = [
     "subagent_spawn",
     "subagent_spawn_batch",
     "subagent_list",
+    "subagent_settings",
     "subagent_output",
     "subagent_stop",
     "subagent_result",
@@ -203,6 +206,7 @@ const CATALOG_GUIDELINES = [
 ];
 
 const SUBAGENT_ORCHESTRATION_GUIDELINES = [
+    "Follow the Harness execution policy for concurrency; the active delegation mode determines whether to use subagents, not whether independent background commands can overlap.",
     "When a structured plan is active, follow the current delegation mode. Track delegated and foreground deliverables only when delegation is permitted and actually underway; continue unblocked foreground work and integrate results before marking work complete.",
     "Do not treat launching a subagent as completion of the parent milestone; relevant terminal results must be inspected and integrated before verification or completion.",
 ];
@@ -1520,6 +1524,13 @@ export default function (pi: ExtensionAPI) {
         pi.appendEntry("pi-better-subagents-delegation", { version: 1, mode: null });
     };
     const activeDelegationMode = (): DelegationMode => delegationOverride ?? normalizeDelegationMode(loadConfig().delegationMode);
+    const countRunning = () =>
+        listActiveMetasForParent(process.pid).filter((meta) => effectiveStatus(meta) === "running").length;
+    const effectiveSettings = () => effectiveSubagentSettings({
+        delegationMode: activeDelegationMode(), maxConcurrent: activeConcurrencyCap(),
+        sources: { delegationMode: delegationOverride ? "session" : "config",
+            maxConcurrent: capOverride !== undefined ? "session" : "config" },
+    }, countRunning(), getSharedCapacityGate(countRunning).pending);
     const saveSettings = (): { ok: boolean; message: string } => {
         try {
             writeSubagentSettings({ delegationMode: activeDelegationMode(), maxConcurrent: activeConcurrencyCap() });
@@ -1844,6 +1855,13 @@ export default function (pi: ExtensionAPI) {
 
         let spawned: ReturnType<typeof spawnDetached>;
         try {
+            // Reservations prevent competing admissions, but do not grandfather
+            // unstarted work after a cap reduction. No await separates this live
+            // occupancy check, child creation, and the running metadata below.
+            const maxConcurrent = activeConcurrencyCap();
+            if (countRunning() >= maxConcurrent) {
+                throw new Error(`Max concurrent subagents (${maxConcurrent}) reached. Stop or let some finish first.`);
+            }
             spawned = spawnDetached({ file: cmd.file, fileArgs: cmd.fileArgs, cwd, logPath: logPathFor(id),
                 env: { [STEER_FILE_ENV]: steerPathFor(id) } });
         } catch (error) {
@@ -1954,8 +1972,6 @@ export default function (pi: ExtensionAPI) {
             if (blankSelector) throw new Error(blankSelector);
 
             const maxConcurrent = activeConcurrencyCap();
-            const countRunning = () =>
-                listActiveMetasForParent(process.pid).filter((m) => effectiveStatus(m) === "running").length;
             // Shared with batch-spawn: reserve before any async work so an interleaved
             // batch cannot oversubscribe after this check and before writeMeta.
             const gate = getSharedCapacityGate(countRunning);
@@ -2091,8 +2107,6 @@ export default function (pi: ExtensionAPI) {
             };
 
             const cfg = loadConfig();
-            const countRunning = () =>
-                listActiveMetasForParent(process.pid).filter((m) => effectiveStatus(m) === "running").length;
             const launchAvailable = p.onCapacity === "launch-available";
             // Shared with single-spawn. Reservations count against maxConcurrent so a
             // concurrent single spawn cannot take a slot the batch already admitted.
@@ -2246,6 +2260,7 @@ export default function (pi: ExtensionAPI) {
         getActiveOrigin: (ctx?: unknown) => activeCallbackOrigin ?? verifiedOriginFromContext(ctx as ExtensionContext | undefined),
     };
     pi.registerTool(subagentListTool(Type, toolSession));
+    pi.registerTool(subagentSettingsTool(Type, effectiveSettings));
     pi.registerTool(subagentOutputTool(Type, toolSession));
     const acceptanceResultTool = subagentResultTool(Type, toolSession);
     pi.registerTool(acceptanceResultTool);
@@ -2286,13 +2301,16 @@ export default function (pi: ExtensionAPI) {
     const openSettings = async (ctx: ExtensionCommandContext): Promise<void> => {
         if (ctx.mode === "tui" && ctx.hasUI && typeof ctx.ui.custom === "function") {
             await ctx.ui.custom<void>((tui, theme, _kb, done) => createSubagentSettingsPage(theme, {
-                get: () => ({
-                    mode: activeDelegationMode(), maxConcurrent: activeConcurrencyCap(),
-                    modeSource: delegationOverride ? "session" : "config",
-                    capSource: capOverride !== undefined ? "session" : "config",
-                    defaultMode: normalizeDelegationMode(loadConfig().delegationMode),
-                    defaultCap: normalizeConcurrencyCap(loadConfig().maxConcurrent),
-                }),
+                get: () => {
+                    const settings = effectiveSettings();
+                    return {
+                        mode: settings.delegationMode, maxConcurrent: settings.maxConcurrent,
+                        modeSource: settings.sources.delegationMode,
+                        capSource: settings.sources.maxConcurrent,
+                        defaultMode: normalizeDelegationMode(loadConfig().delegationMode),
+                        defaultCap: normalizeConcurrencyCap(loadConfig().maxConcurrent),
+                    };
+                },
                 changeMode, changeCap, save: saveSettings, reset: resetSettings,
             }, () => { refreshBackgroundWorkNavigator(ctx); tui.requestRender(); }, () => done()));
         } else {
@@ -2352,9 +2370,18 @@ export default function (pi: ExtensionAPI) {
     pi.registerTool(discoveryTool as Parameters<ExtensionAPI["registerTool"]>[0]);
 
     pi.on("before_agent_start", (event) => ({
-        systemPrompt: `${event.systemPrompt}\n\n${delegationPrompt(activeDelegationMode())}`,
+        systemPrompt: `${appendExecutionPolicy(event.systemPrompt)}\n\nUse the latest Subagent settings context block as the authoritative delegation mode and capacity snapshot. Its delegation guidance replaces earlier mode-specific guidance, including guidance in a plan. Inspect subagent_settings when needed; never treat the concurrency limit as a target number of agents.`,
     }));
 
+    pi.on("context", (event) => {
+        const settings = effectiveSettings();
+        return { messages: [
+            ...event.messages.filter(message => message.role !== "custom" || message.customType !== SUBAGENT_SETTINGS_CONTEXT),
+            { role: "custom" as const, customType: SUBAGENT_SETTINGS_CONTEXT,
+                content: formatSubagentSettings(settings), display: false, details: settings, timestamp: Date.now() },
+        ] };
+    });
+
     // ---- live-status lifecycle -----------------------------------------
     pi.on("agent_start", async (_event, ctx) => {
         setCallbackBatchContext(pi, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",

package/shared-execution-policy.ts

@@ -0,0 +1,19 @@
+// Generated from packages/pi-better-harness/extensions/execution-policy.ts. Do not edit directly.
+/** Harness-wide scheduling guidance, vendored so standalone extensions share it. */
+const EXECUTION_POLICY = [
+  "Harness execution policy: concurrency is separate from subagent delegation.",
+  "Before multi-unit work, identify ready, authorized, independent units, actual prerequisites, shared mutable resources, and capacity or availability constraints. Represent independently verifiable deliverables (such as each host migration) separately in the plan; do not hide them in one serial rollout step or create dependencies merely from list order.",
+  "Start all ready, authorized, non-conflicting units concurrently within known resource limits before waiting for any one to finish. Reassess ready work after launches and results; continue unblocked foreground work instead of polling running tasks. Do not equate one background launch with scheduling all ready work.",
+  "Serialize only for a concrete dependency, conflicting writes or ownership, resource or concurrency limit, documented rollout gate, or explicit availability requirement. Record the reason in the plan or explain it to the user. Do not invent a canary or host-by-host availability requirement.",
+  "If concurrency raises an unresolved material operational trade-off (for example, draining all hosts could leave no available runners), ask the user once before the affected operations. Continue independent preparation meanwhile. Existing authorization, safety checks, workflow prerequisites, and human-approved rollout constraints remain binding; urgency does not waive them.",
+  "Choose the execution mechanism after deciding what can run together: foreground tools for small, tightly coupled, or interactive work; subagents for bounded independent reasoning or implementation when the active delegation mode permits; background tasks for independent long-running commands or waits. Manual delegation forbids proactive subagents, not concurrent foreground tools or background commands. Use available batch or parallel tool interfaces where appropriate and inspect every launch receipt for failures or skipped work.",
+  "A unit waiting or failing does not block other ready independent units unless the evidence shows a shared blocker. Preserve each unit's guards and rollback boundary. Before completing verification, the plan, or the goal, inspect and integrate every relevant terminal result or failure; launch is not completion.",
+].join("\n");
+
+export function appendExecutionPolicy(systemPrompt: string): string {
+  // Inspect the prompt, not module-global state: vendored copies have separate
+  // module identities, and every fresh turn or reload needs the policy again.
+  return systemPrompt.includes(EXECUTION_POLICY)
+    ? systemPrompt
+    : `${systemPrompt}\n\n${EXECUTION_POLICY}`;
+}