pi-better-harness 0.10.0 → 0.11.0

package/node_modules/pi-better-subagents/README.md

@@ -43,6 +43,13 @@ 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 `default openai/gpt-6-sol@high`. 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 default openai/gpt-6-sol@high)`.
+
 ## When To Use
 
 Use this package for independent coding, review, research, or verification work that can finish later. Do not use it for steps that need immediate foreground interaction or user clarification.

package/node_modules/pi-better-subagents/agent-inspection.ts

@@ -80,6 +80,23 @@ export interface OperationField {
     inherited: boolean;
 }
 
+export interface DefinitionDefaults {
+    model: string | null;
+    effort: string | null;
+    /** Compact `model@effort` form, as shown in the catalog list and launch notes. */
+    label: string;
+}
+
+/** `model@effort`, `model`, or `effort <level>` when only an effort is set. Undefined when neither is set. */
+export function formatModelEffort(model: string | null | undefined, effort: string | null | undefined): string | undefined {
+    const m = typeof model === "string" && model.trim() !== "" ? model : undefined;
+    const e = typeof effort === "string" && effort.trim() !== "" ? effort : undefined;
+    if (m && e) return `${m}@${e}`;
+    if (m) return m;
+    if (e) return `effort ${e}`;
+    return undefined;
+}
+
 export interface OperationCapabilities {
     grantedByCatalog: false;
     sameAsLegacySpawn: true;
@@ -113,6 +130,8 @@ export interface OperationView {
     instructionMode?: string;
     instructions?: string;
     fields?: { model: OperationField; effort: OperationField; tier: OperationField };
+    /** The definition's own default model and effort (role default, or the agent's override or inherited value). Null when neither is set. */
+    defaults: DefinitionDefaults | null;
     requestedModel: string | null;
     requestedEffort: string | null;
     actualModel: string | null;
@@ -311,6 +330,7 @@ export function presentCatalogEntry(snapshot: CatalogSnapshot, id: string, enric
         instructionMode: inspection.instructionMode,
         instructions: inspection.instructions,
         fields,
+        defaults: definitionDefaults(fields),
         requestedModel: enrichment?.requestedModel ?? fields?.model.value ?? null,
         requestedEffort: enrichment?.requestedEffort ?? (fields?.effort.value ?? null),
         actualModel: enrichment?.actualModel ?? null,
@@ -350,6 +370,7 @@ export function renderOperationView(view: OperationView): string {
         `definitionValid=${yesNo(view.definitionValid)}`,
         `catalogLaunchable=${yesNo(view.catalogLaunchable)}`,
         `launchable=${view.launchable === null ? "unknown" : yesNo(view.launchable)}`,
+        ...(view.defaults ? [`default ${view.defaults.label}`] : []),
     ].join(" ");
     const lines = [
         header,
@@ -397,6 +418,13 @@ export function renderOperationView(view: OperationView): string {
     return lines.join("\n");
 }
 
+function definitionDefaults(fields: OperationView["fields"]): DefinitionDefaults | null {
+    const model = fields?.model.value ?? null;
+    const effort = fields?.effort.value ?? null;
+    const label = formatModelEffort(model, effort);
+    return label ? { model, effort, label } : null;
+}
+
 function field(value: { value: string | null; source: OperationField["source"]; explicit: boolean }): OperationField {
     return {
         value: value.value,

package/node_modules/pi-better-subagents/agents-catalog-tool.ts

@@ -37,7 +37,7 @@ export function agentsCatalogTool(Type: TypeModule, deps: DiscoveryDeps = {}) {
     return {
         name: "agents_catalog" as const,
         label: "Agents catalog",
-        description: "List or inspect role and named-agent definitions, including inheritance, diagnostics, restrictions, and whether launchability is actually known. This tool does not create, import, or edit definitions.",
+        description: "List or inspect role and named-agent definitions, including inheritance, default model and effort, diagnostics, restrictions, and whether launchability is actually known. This tool does not create, import, or edit definitions.",
         promptSnippet: "List and inspect catalog roles and named agents, including inheritance and whether launchability is known.",
         promptGuidelines: [
             "Use agents_catalog to discover roles and named agents before subagent_spawn. It is read-only.",
@@ -46,6 +46,7 @@ export function agentsCatalogTool(Type: TypeModule, deps: DiscoveryDeps = {}) {
             "Ask the user to run /agents create or /agents import-codex for writes. Those commands confirm role, scope, and import replacement.",
             "Launch with the existing subagent_spawn or batch tool. Pass one agent or one role, not both. Two roles for one run need the user to choose one or split the work.",
             "Put an authoritative model or effort on the structured invocation. Do not rely on copying a model name into the child prompt. Explicit invocation and workflow choices override definition defaults.",
+            "Each entry shows its default model@effort when set. Omit model and thinking on the spawn to use it; name one only for a stated reason.",
         ],
         parameters: Type.Object({
             action: Type.String({ description: "list or inspect. No other action is accepted." }),

package/node_modules/pi-better-subagents/batch.mjs

@@ -215,8 +215,8 @@ export function formatBatchLaunchResponse({ batchId, batchName, launched, skippe
         lines.push(
             `Batch ${label} launched ${launched.length} subagent(s):`,
         );
-        for (const { name, id } of launched) {
-            lines.push(`• ${name} → ${id}`);
+        for (const { name, id, modelNote } of launched) {
+            lines.push(`• ${name} → ${id}${modelNote ? ` · ${modelNote}` : ""}`);
         }
     }
 

package/node_modules/pi-better-subagents/catalog-runtime.ts

@@ -4,7 +4,7 @@
  * `spawnSubagentRun`. This module does not grant tools, sandbox modes, or
  * extensions, and it does not read task prose for model choices.
  */
-import { describeDefaultLaunchCapabilities, LEGACY_CAPABILITY_CONTROLS, type LaunchEnricher, type LaunchEnrichment } from "./agent-inspection.ts";
+import { describeDefaultLaunchCapabilities, formatModelEffort, LEGACY_CAPABILITY_CONTROLS, type LaunchEnricher, type LaunchEnrichment } from "./agent-inspection.ts";
 import { resolveSelection, type EffectiveDefinition } from "./catalog-resolver.ts";
 import { defaultUserRoot, loadCatalog, type CatalogSnapshot } from "./catalog-store.ts";
 import { loadConfig, type SubagentConfig } from "./config.ts";
@@ -252,6 +252,57 @@ export async function clarifyCatalogRequest(
     return { status: "resolved", jobs: ordered.map(stripBookkeeping) };
 }
 
+/**
+ * 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 default openai/gpt-6-sol@high)`
+ * - fallback: `model xai/grok-4.7@high (role default openai/gpt-6-sol@high unavailable; foreground fallback)`
+ * - capped effort: `model openai/gpt-6-sol@medium (role default openai/gpt-6-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.
+ */
+export function catalogDefaultNote(
+    record: Pick<CatalogRunRecord, "kind" | "effective" | "modelSelection" | "effortSelection"> | undefined,
+    model: string | undefined,
+    thinking: string | undefined,
+): string | undefined {
+    if (!record) return undefined;
+    const defaultModel = record.effective.model.value;
+    const defaultEffort = record.effective.effort.value;
+    const defaultLabel = formatModelEffort(defaultModel, defaultEffort);
+    if (!defaultLabel) return undefined;
+    const modelSource = record.modelSelection?.source;
+    const modelFallback = defaultModel !== null && modelSource !== undefined && FALLBACK_SOURCES.has(modelSource);
+    const modelDiffers = defaultModel !== null && (modelFallback || !sameModel(defaultModel, model, modelSource));
+    const effortCapped = defaultEffort !== null && record.effortSelection?.adjusted === true && (thinking ?? null) !== defaultEffort;
+    const effortDiffers = defaultEffort !== null && (thinking ?? null) !== defaultEffort;
+    if (!modelDiffers && !effortDiffers) return undefined;
+    const actual = formatModelEffort(model ?? "Pi default", thinking) ?? "Pi default";
+    const causes = [
+        modelFallback ? `${record.kind} default ${defaultLabel} unavailable; ${FALLBACK_LABELS[modelSource!] ?? modelSource} fallback` : `${record.kind} default ${defaultLabel}`,
+        ...(effortCapped ? [`effort capped at ${thinking ?? "the model default"} by the model`] : []),
+    ];
+    return `model ${actual} (${causes.join("; ")})`;
+}
+
+/** Model sources that mean the default could not be used, not that the caller chose another model. */
+const FALLBACK_SOURCES: ReadonlySet<string> = new Set(["tier-candidate", "foreground", "configured-default"]);
+const FALLBACK_LABELS: Record<string, string> = {
+    "tier-candidate": "same-tier",
+    foreground: "foreground",
+    "configured-default": "configured-default",
+};
+
+function sameModel(defaultModel: string, actual: string | undefined, source: string | undefined): boolean {
+    // The resolver launched the definition's own preference: same model, however it was spelled.
+    if (source === "role-default" || source === "agent-override") return true;
+    if (actual === undefined) return false;
+    if (defaultModel === actual) return true;
+    // A providerless default names the id; the resolved provider/id (the id may itself contain "/") still matches.
+    return !defaultModel.includes("/") ? actual.endsWith(`/${defaultModel}`) : false;
+}
+
 export async function prepareCatalogJob(snapshot: CatalogSnapshot, job: CatalogJobFields, host: CatalogHost): Promise<PreparedCatalogJob> {
     const agent = agentIdOf(job);
     const roles = roleIdsOf(job);

package/node_modules/pi-better-subagents/docs/agent-catalog-operations.md

@@ -52,6 +52,8 @@ 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.
 
+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 default openai/gpt-6-sol@high)`. Only the fields the definition sets are compared. The note names the cause: a fallback from an unavailable default reads `(role 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`.
+
 ## Lifecycle attachment
 
 ```ts

package/node_modules/pi-better-subagents/index.ts

@@ -151,6 +151,7 @@ import {
     loadLaunchSnapshot,
     noteCatalogHost,
     prepareCatalogJob,
+    catalogDefaultNote,
     tiersForLaunch,
     type CatalogHost,
     type CatalogJobFields,
@@ -175,6 +176,7 @@ const projectConfigDirName = typeof (PiCodingAgent as { CONFIG_DIR_NAME?: unknow
     : ".pi";
 
 const CATALOG_GUIDELINES = [
+    "With an agent or role, omit model and thinking to launch on its default model and effort, which agents_catalog shows. Name a model or effort only for a stated reason, such as a task or workflow instruction, and never copy one from another role's runs.",
     "When a task, workflow, or skill instruction names a model or effort, translate that authoritative choice into the structured model and thinking arguments before spawning. The runtime does not parse prose, quoted model names, or comparisons, and copying a model into the child prompt does not change the launch.",
     "Optional agent, role, and alias select a catalog definition. Pass one agent id or one role id. Pass an array of role ids when one run was given more than one role: that call asks to choose one or split, and without a UI choice it returns clarification-needed and starts no child. Naming both an agent and a role does the same. One job's choice does not change another job. A named agent displays its defined name. A direct role displays the label allocated from the local run registry. Calls without agent or role keep the existing name and model chain.",
     "Catalog model and effort are resolved before the child starts. An unavailable explicit model or unsupported explicit effort does not launch and does not fall back. The catalog grants no tools, sandbox modes, extensions, or permissions.",
@@ -1551,6 +1553,8 @@ export default function (pi: ExtensionAPI) {
         runtime: string;
         warn: string;
         sandboxDir?: string;
+        /** Set only when a catalog run's model or effort differs from its role or agent default. */
+        modelNote?: string;
     }> {
         assertThinkingLevel(p.thinking);
         const permissionPlan = resolveSubagentPermissions(pi, p.sandbox);
@@ -1766,7 +1770,8 @@ export default function (pi: ExtensionAPI) {
               `${resolution.unmapped.length > 1 ? "these tools" : "this tool"} will NOT exist in the child. ` +
               `Add a toolExtensions entry in config.json.\n`
             : "");
-        return { id, meta, spawned, runtime: runtime + (meta.timing ? `${formatTimingLimits(meta.timing, startedAt)}\n` : ""), warn, sandboxDir };
+        const modelNote = catalogDefaultNote(p.catalog, model, thinking);
+        return { id, meta, spawned, runtime: runtime + (meta.timing ? `${formatTimingLimits(meta.timing, startedAt)}\n` : ""), warn, sandboxDir, modelNote };
     }
 
     // ---- subagent_spawn -------------------------------------------------
@@ -1783,7 +1788,7 @@ export default function (pi: ExtensionAPI) {
             "After subagent_spawn, do NOT call subagent_output or subagent_result in a loop to wait for the result, and do NOT sleep. The run completes on its own and reports back on the next turn.",
             "Call subagent_result after a completion or attention callback, or when the user explicitly asks for the result. Use subagent_output only when the user explicitly asks how a run is progressing; never use either tool to poll.",
             ...SUBAGENT_ORCHESTRATION_GUIDELINES,
-            "The tools param is both the tool allowlist AND what determines which extensions load in the child (e.g. tools='read,bash,web_fetch' loads only the web-tools package). Ask for the tools the task needs and nothing more; clean:true gives a built-ins-only child. Pick a model with the model param (e.g. 'xai/grok-4.5@high'); providerless model patterns are resolved by Pi, while provider/model is deterministic and loads mapped provider extensions.",
+            "The tools param is both the tool allowlist AND what determines which extensions load in the child (e.g. tools='read,bash,web_fetch' loads only the web-tools package). Ask for the tools the task needs and nothing more; clean:true gives a built-ins-only child. Without an agent or role, pick a model with the model param (e.g. 'xai/grok-4.5@high'); providerless model patterns are resolved by Pi, while provider/model is deterministic and loads mapped provider extensions.",
             ...CATALOG_GUIDELINES,
             "By default the subagent is sandboxed. Human settings in /sandbox control file, credential-file, command, and network permissions; sandbox:false cannot override an enabled human profile. Without published settings, legacy write confinement applies. Set callback:false to finish quietly — then read the result on demand via subagent_result.",
             "Every run is timed by the harness: a soft deadline (default 30 min) steers the child to wrap up and wakes you once, the run is stopped after grace_minutes (reason deadline), a hard ceiling (default 90 min) stops it without grace (reason ceiling), and no progress for stuck_minutes (default 10) wakes you once (reason stuck). Set deadline_minutes/max_minutes/stuck_minutes to fit the task instead of writing a time limit into the prompt; do not stop a slow child that is still making progress.",
@@ -1795,8 +1800,8 @@ export default function (pi: ExtensionAPI) {
             agent: Type.Optional(Type.String({ description: "Named agent id (agent.<slug>). Mutually exclusive with role. The navigator shows the defined agent name." })),
             role: catalogRoleSchema("direct role launch"),
             alias: Type.Optional(Type.String({ description: "Per-run display alias for a direct role launch, such as checkout. Not a reusable agent. Colliding aliases gain a numeric suffix." })),
-            model: Type.Optional(Type.String({ description: "Pi model pattern, preferably provider/id, optionally suffixed with @effort (for example openai/gpt-5.5@high). Providerless patterns are resolved by Pi. Default: inherit foreground model. Put authoritative model choices here; do not rely on prompt text." })),
-            thinking: Type.Optional(Type.String({ description: "Reasoning effort for the child: off, minimal, low, medium, high, xhigh, or max (default: Pi/model default)." })),
+            model: Type.Optional(Type.String({ description: "Pi model pattern, preferably provider/id, optionally suffixed with @effort (for example openai/gpt-5.5@high). Providerless patterns are resolved by Pi. Omit to use the agent or role default; without one, inherit the foreground model. Put authoritative model choices here; do not rely on prompt text." })),
+            thinking: Type.Optional(Type.String({ description: "Reasoning effort for the child: off, minimal, low, medium, high, xhigh, or max. Omit to use the agent or role default; without one, the Pi/model default." })),
             tools: Type.Optional(Type.String({ description: "Tool allowlist: comma-separated names the child may use (e.g. 'read,bash,web_fetch'). This ALSO selects which extensions load — only packages backing a requested tool are loaded. Defaults to the configured safe set." })),
             exclude_tools: Type.Optional(Type.String({ description: "Comma-separated tool denylist, applied on top of the allowlist." })),
             clean: Type.Optional(Type.Boolean({ description: "Run a hermetic child with NO extensions at all (only built-ins: read, bash, edit, write). Default false — the extensions backing the requested tools load, so web_fetch and model auth (e.g. xai) work." })),
@@ -1841,21 +1846,22 @@ export default function (pi: ExtensionAPI) {
                         throw new Error(`Choosing split needs ${catalog.jobs.length} subagent slots, but only one was free. Nothing was launched.`);
                     }
                     reserved += extra;
-                    const launched: { name?: string; id: string }[] = [];
+                    const launched: { name?: string; id: string; modelNote?: string }[] = [];
                     for (const job of catalog.jobs) {
-                        const { id } = await spawnSubagentRun(ctx, job);
+                        const { id, modelNote } = await spawnSubagentRun(ctx, job);
                         gate.commit(1);
                         reserved -= 1;
-                        launched.push({ name: job.name, id });
+                        launched.push({ name: job.name, id, modelNote });
                     }
-                    return text(launched.map((item) => `Subagent launched: ${item.name ? `${item.name} ` : ""}id=${item.id}.`).join("\n"));
+                    return text(launched.map((item) => `Subagent launched: ${item.name ? `${item.name} ` : ""}id=${item.id}.${item.modelNote ? ` ${item.modelNote}.` : ""}`).join("\n"));
                 }
                 Object.assign(p, catalog.jobs[0]);
-                const { id, spawned, runtime, warn, sandboxDir } = await spawnSubagentRun(ctx, p);
+                const { id, spawned, runtime, warn, sandboxDir, modelNote } = await spawnSubagentRun(ctx, p);
                 gate.commit(1);
                 reserved = 0;
                 return text(
                     `Subagent launched: ${p.name ? `${p.name} ` : ""}id=${id} (pid ${spawned.pid}).\n` +
+                    (modelNote ? `${modelNote[0]!.toUpperCase()}${modelNote.slice(1)}.\n` : "") +
                     (p.callback === false
                         ? `Running in the background; the foreground is free. It will finish quietly — read the result with subagent_result id=${id}.\n`
                         : `Running in the background; the foreground is free. Its result will be posted back here when it finishes.\n`) +
@@ -1898,7 +1904,7 @@ export default function (pi: ExtensionAPI) {
                 agent: Type.Optional(Type.String({ description: "Named agent id applied to jobs that do not select their own agent or role." })),
                 role: catalogRoleSchema("shared role selector"),
                 alias: Type.Optional(Type.String({ description: "Direct-role alias applied when a job does not set alias." })),
-                model: Type.Optional(Type.String({ description: "Pi model pattern, preferably provider/id, optionally suffixed with @effort (default: inherit foreground model). Put authoritative model choices here; prompt text is not parsed." })),
+                model: Type.Optional(Type.String({ description: "Pi model pattern, preferably provider/id, optionally suffixed with @effort. Omit to use the agent or role default; without one, inherit the foreground model. Put authoritative model choices here; prompt text is not parsed." })),
                 thinking: Type.Optional(Type.String({ description: "Reasoning effort applied to every job: off, minimal, low, medium, high, xhigh, or max." })),
                 tools: Type.Optional(Type.String({ description: "Tool allowlist applied to every job." })),
                 exclude_tools: Type.Optional(Type.String({ description: "Comma-separated tool denylist applied to every job." })),
@@ -1997,7 +2003,7 @@ export default function (pi: ExtensionAPI) {
 
             const names = assignBatchJobNames(p.jobs);
             const batchId = nextBatchId();
-            const launched: { name: string; id: string }[] = [];
+            const launched: { name: string; id: string; modelNote?: string }[] = [];
             const failed: { name: string; reason: string }[] = [];
             const skipped: { name: string }[] = [];
             // How many reject-mode reserved slots are still held (not yet committed/released).
@@ -2035,10 +2041,10 @@ export default function (pi: ExtensionAPI) {
                             name = prepared.assign.name;
                         }
                     }
-                    const { id } = await spawnSubagentRun(ctx, { ...merged, name }, { batchId, batchName: p.batchName });
+                    const { id, modelNote } = await spawnSubagentRun(ctx, { ...merged, name }, { batchId, batchName: p.batchName });
                     gate.commit(1);
                     if (!launchAvailable) reservedRemaining -= 1;
-                    launched.push({ name, id });
+                    launched.push({ name, id, ...(modelNote ? { modelNote } : {}) });
                 } catch (err) {
                     gate.release(1);
                     if (!launchAvailable) reservedRemaining -= 1;

package/node_modules/pi-better-subagents/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",
@@ -55,7 +55,7 @@
     "pi-better-plan": "0.5.0",
     "pi-better-sandbox": "0.7.1",
     "pi-better-ssh": "0.1.1",
-    "pi-better-subagents": "0.7.1",
+    "pi-better-subagents": "0.8.0",
     "smol-toml": "1.9.0",
     "yaml": "^2.9.1"
   },