pi-better-subagents 0.9.3 → 0.11.0

package/README.md

@@ -12,6 +12,7 @@ Use `pi-better-subagents` when you want Pi to launch independent agent work with
 
 ## Core Features
 - Non-blocking subagent launches, with an optional role and named-agent catalog (`docs/agent-catalog.md`, `docs/agent-catalog-lifecycle.md`).
+- Typed foreground `subagent_spawn_batch` launch receipts for native Pi codemode (Pi 0.99.1+), preserving direct tool calls, per-run callbacks, and batch capacity/catalog guarantees. See [codemode batch launches](docs/usage.md#codemode-batch-launches).
 - Default OS write sandboxing on macOS and Linux.
 - Explicit tool allowlists for child sessions.
 - Durable logs, result retrieval, and [failure observations](docs/failure-observations.md) independent of lifecycle status. A live child handles its own tool errors; the parent is woken only for actionable incidents, and children can classify handled failures with `failure_disposition`.
@@ -37,21 +38,24 @@ Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or ne
 `config.json` sets `delegationMode` to `manual`, `adaptive` (default), or
 `coordinator`. `/subagents` displays the active mode, and
 `/subagents mode manual|adaptive|coordinator` changes it for the current
-session without changing config. Manual delegates only on explicit user or workflow request, even with a
+session without changing config. `/subagents save` writes the current mode as
+the next session's default. The navigator's `main` row opens the same control:
+`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
 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).
 
 `agents_catalog` shows each role's and named agent's default model and effort,
-such as `role developer "Developer" … default openai/gpt-6-sol@high`. Roles are
+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
 `role.developer` also works, and named agents keep their full id
 (`agent: "agent.payments"`). To launch on that default, omit
 `model` and `thinking` on a role or agent spawn; name one only for a stated
 reason. When a launch's model or effort differs from the default, its launch
 line says so, for example
-`model openai/gpt-6-astra@high (role developer default openai/gpt-6-sol@high)`.
+`model openai/gpt-6-astra@high (role developer default openai/gpt-6.1-sol@high)`.
 
 ## When To Use
 

package/agent-commands.ts

@@ -123,7 +123,7 @@ interface ParsedArgs {
 
 export function registerAgentCommands(pi: Pick<ExtensionAPI, "registerCommand">, deps: AgentCommandDeps = {}): void {
     pi.registerCommand("agents", {
-        description: "List, inspect, create, reload, or import Codex agent definitions",
+        description: "[list|show|create|reload|import-codex] — List, inspect, create, reload, or import agent definitions",
         getArgumentCompletions(prefix: string) {
             const commands = ["list", "inspect", "show", "create", "reload", "import-codex", "help"];
             const first = prefix.trim().split(/\s+/)[0] ?? "";

package/batch.mjs

@@ -14,6 +14,64 @@ import { assertTimingParams } from "./timing.ts";
 
 const VALID_CAPACITY_MODES = new Set(["reject", "launch-available"]);
 
+/** Public codemode receipt; details alone are not returned to nested callers. */
+export const batchLaunchOutputSchema = {
+    type: "object",
+    properties: {
+        status: { type: "string", enum: ["launched", "partial", "not-launched", "clarification-needed"] },
+        batchId: { type: "string" },
+        batchName: { type: "string" },
+        launched: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: { job: { type: "integer", minimum: 1 }, name: { type: "string" }, id: { type: "string" }, modelNote: { type: "string" } },
+                required: ["job", "name", "id"],
+                additionalProperties: false,
+            },
+        },
+        failed: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: { job: { type: "integer", minimum: 1 }, name: { type: "string" }, reason: { type: "string" } },
+                required: ["job", "name", "reason"],
+                additionalProperties: false,
+            },
+        },
+        skipped: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: { job: { type: "integer", minimum: 1 }, name: { type: "string" } },
+                required: ["job", "name"],
+                additionalProperties: false,
+            },
+        },
+        message: { type: "string" },
+        choices: { type: "array", items: { type: "string" } },
+    },
+    required: ["status", "launched", "failed", "skipped"],
+    additionalProperties: false,
+};
+
+/** Launch success is not run completion; partial receipts retain every created run. */
+export function batchLaunchResult({ batchId, batchName, launched, skipped, failed }) {
+    const receipt = {
+        status: launched.length === 0 ? "not-launched" : failed.length || skipped.length ? "partial" : "launched",
+        batchId,
+        ...(batchName !== undefined ? { batchName } : {}),
+        launched,
+        failed,
+        skipped,
+    };
+    return {
+        content: [{ type: "text", text: formatBatchLaunchResponse(receipt) }],
+        details: receipt,
+        structuredContent: receipt,
+    };
+}
+
 /**
  * Overlay per-job options on top of shared options. Only defined keys are
  * inherited; booleans keep their false values.

package/catalog-runtime.ts

@@ -256,9 +256,9 @@ export async function clarifyCatalogRequest(
  * Launch-line note for a catalog run whose effective model or effort differs
  * from the role or agent default. The wording names the cause, so a fallback
  * or a capped effort is not mistaken for a caller override:
- * - override: `model openai/gpt-6-astra@high (role developer default openai/gpt-6-sol@high)`
- * - fallback: `model xai/grok-4.7@high (role developer default openai/gpt-6-sol@high unavailable; foreground fallback)`
- * - capped effort: `model openai/gpt-6-sol@medium (role developer default openai/gpt-6-sol@high; effort capped at medium by the model)`
+ * - override: `model openai/gpt-6-astra@high (role developer default openai/gpt-6.1-sol@high)`
+ * - fallback: `model xai/grok-4.7@high (role developer default openai/gpt-6.1-sol@high unavailable; foreground fallback)`
+ * - capped effort: `model openai/gpt-6.1-sol@medium (role developer default openai/gpt-6.1-sol@high; effort capped at medium by the model)`
  * Undefined for a non-catalog run, a definition with no default, or a launch
  * that matches the default. Only the fields the definition sets are compared.
  */

package/catalog-schema.ts

@@ -72,10 +72,10 @@ export const PARSER_LIMITS = {
  * runtime already uses. Tiers are catalog policy, not benchmark rankings.
  */
 export const APPROVED_ROLE_DEFAULTS = [
-    { id: "role.researcher", name: "Researcher", model: "openai/gpt-6-sol", effort: "medium", tier: "balanced" },
+    { id: "role.researcher", name: "Researcher", model: "openai/gpt-6.1-sol", effort: "medium", tier: "balanced" },
     { id: "role.explorer", name: "Explorer", model: "openai/gpt-6-luna", effort: "medium", tier: "efficient" },
-    { id: "role.product-manager", name: "Product Manager", model: "openai/gpt-6-sol", effort: "medium", tier: "balanced" },
-    { id: "role.developer", name: "Developer", model: "openai/gpt-6-sol", effort: "high", tier: "balanced" },
+    { id: "role.product-manager", name: "Product Manager", model: "openai/gpt-6.1-sol", effort: "medium", tier: "balanced" },
+    { id: "role.developer", name: "Developer", model: "openai/gpt-6.1-sol", effort: "high", tier: "balanced" },
     { id: "role.reviewer", name: "Reviewer", model: "openai/gpt-6-astra", effort: "medium", tier: "frontier" },
     { id: "role.architect", name: "Architect", model: "openai/gpt-6-astra", effort: "high", tier: "frontier" },
 ] as const;

package/config.ts

@@ -8,12 +8,12 @@
  * `defaultTools` absent → the built-in SAFE_DEFAULT_TOOLS.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, writeFileSync } 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 type { DelegationMode } from "./delegation.ts";
+import { isDelegationMode, type DelegationMode } from "./delegation.ts";
 import type { TimingSettings } from "./timing.ts";
 
 export interface SubagentConfig extends TimingSettings {
@@ -80,24 +80,49 @@ 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 configPathForTests: 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 {
+    configPathForTests = path;
+    cached = undefined;
+}
+
+export function configPath(): string {
+    return configPathForTests ?? join(dirname(fileURLToPath(import.meta.url)), "config.json");
+}
+
 /** Load config.json from the extension directory. Missing/invalid → {}. */
 export function loadConfig(): SubagentConfig {
     if (cached) return cached;
     try {
-        const dir = dirname(fileURLToPath(import.meta.url));
-        cached = JSON.parse(readFileSync(join(dir, "config.json"), "utf-8")) as SubagentConfig;
+        cached = JSON.parse(readFileSync(configPath(), "utf-8")) as SubagentConfig;
     } catch {
         cached = {};
     }
     return cached;
 }
 
+/** Write delegationMode into config.json, preserving every other key. */
+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;
+}
+
 /** Normalize a comma/space tool list to pi's bare comma form: "a, b" → "a,b". */
 export function normalizeTools(list: string): string {
     return list.split(",").map((t) => t.trim()).filter(Boolean).join(",");

package/docs/agent-catalog-operations.md

@@ -52,7 +52,7 @@ Codex applies the agent file's model and `model_reasoning_effort` ahead of the c
 
 `agents_catalog` accepts `list` and `inspect` only. It uses the same inspection view as `/agents show`. It has no write path. Launch remains `subagent_spawn` or the batch tool, with at most one `agent` or `role` selector. Those selectors are lifecycle's wiring, not this tool.
 
-A list line names a role by its short name (`role developer "Developer" …`), the form the `role` field takes; the inspect header, `identity.id`, and the structured `id` keep the stored id `role.developer`. Named agents show their full `agent.<slug>` id in both. Each list line and the inspect header end with the definition's default model and effort when one is set, such as `default openai/gpt-6-sol@high`: a role's own default, or a named agent's override or inherited role default. The structured view carries the same value as `defaults: { model, effort, label }`, or `null` when neither is set. A spawn that omits `model` and `thinking` uses it. When a catalog launch's model or effort differs from it, the launch line (and each batch job line) adds a note such as `model openai/gpt-6-astra@high (role developer default openai/gpt-6-sol@high)`; a named agent's note reads `agent default …`. Only the fields the definition sets are compared. The note names the cause: a fallback from an unavailable default reads `(role developer default openai/gpt-6-sol@high unavailable; foreground fallback)` (or `same-tier` / `configured-default`), and an effort the model cannot run adds `effort capped at <level> by the model`.
+A list line names a role by its short name (`role developer "Developer" …`), the form the `role` field takes; the inspect header, `identity.id`, and the structured `id` keep the stored id `role.developer`. Named agents show their full `agent.<slug>` id in both. Each list line and the inspect header end with the definition's default model and effort when one is set, such as `default openai/gpt-6.1-sol@high`: a role's own default, or a named agent's override or inherited role default. The structured view carries the same value as `defaults: { model, effort, label }`, or `null` when neither is set. A spawn that omits `model` and `thinking` uses it. When a catalog launch's model or effort differs from it, the launch line (and each batch job line) adds a note such as `model openai/gpt-6-astra@high (role developer default openai/gpt-6.1-sol@high)`; a named agent's note reads `agent default …`. Only the fields the definition sets are compared. The note names the cause: a fallback from an unavailable default reads `(role developer default openai/gpt-6.1-sol@high unavailable; foreground fallback)` (or `same-tier` / `configured-default`), and an effort the model cannot run adds `effort capped at <level> by the model`.
 
 ## Lifecycle attachment
 

package/docs/agent-catalog.md

@@ -16,7 +16,7 @@ id: role.developer
 name: Developer
 description: Implements a requested change in the existing system.
 defaults:
-  model: openai/gpt-6-sol
+  model: openai/gpt-6.1-sol
   effort: high
   tier: balanced
 ---
@@ -100,10 +100,10 @@ Model availability, same-tier fallback, and nearest-effort adjustment are not de
 
 | Role | Stored id | Name | Model | Effort | Tier |
 | --- | --- | --- | --- | --- | --- |
-| `researcher` | `role.researcher` | Researcher | `openai/gpt-6-sol` | medium | balanced |
+| `researcher` | `role.researcher` | Researcher | `openai/gpt-6.1-sol` | medium | balanced |
 | `explorer` | `role.explorer` | Explorer | `openai/gpt-6-luna` | medium | efficient |
-| `product-manager` | `role.product-manager` | Product Manager | `openai/gpt-6-sol` | medium | balanced |
-| `developer` | `role.developer` | Developer | `openai/gpt-6-sol` | high | balanced |
+| `product-manager` | `role.product-manager` | Product Manager | `openai/gpt-6.1-sol` | medium | balanced |
+| `developer` | `role.developer` | Developer | `openai/gpt-6.1-sol` | high | balanced |
 | `reviewer` | `role.reviewer` | Reviewer | `openai/gpt-6-astra` | medium | frontier |
 | `architect` | `role.architect` | Architect | `openai/gpt-6-astra` | high | frontier |
 

package/docs/agent-model-resolution.md

@@ -10,7 +10,7 @@ Normative rules are R3, R4, R8, and the resolver half of R10. Prose parsing and
 - It does not grant tools, sandbox modes, extensions, or presets. Inspection copies the catalog `capabilities` object (`grantedByCatalog: false`).
 - It does not call a provider. Availability is one `getAvailable()` snapshot from the foreground registry. `find()` only explains that a known model is outside that set.
 - It does not retry, and it does not substitute after a child has started. `automaticRetry` and `substitutionAfterStart` are false. `startupFailure.action` is `surface-error-no-retry-no-substitution`. A later provider initialization failure is a lifecycle error.
-- It does not invent tier candidates. Built-in tiers name the approved models and have empty candidate lists. `openai/gpt-6-sol`, `openai/gpt-6-luna`, and `openai/gpt-6-astra` are not substitutes.
+- It does not invent tier candidates. Built-in tiers name the approved models and have empty candidate lists. `openai/gpt-6.1-sol`, `openai/gpt-6-luna`, and `openai/gpt-6-astra` are not substitutes.
 
 ## Precedence