pi-better-harness 0.9.0 → 0.11.0

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

@@ -13,7 +13,7 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 ## Core Features
 
 - `/goal` runtime for starting, pausing, resuming, completing, and clearing the current objective.
-- `escape` pauses the active goal and your next message resumes it; `/goal pause` stays paused until `/goal resume`. Paused goals are never poked.
+- `escape` pauses the active goal, and it stays paused while you talk to the agent. Say "go" (the agent then calls `goal_resume`), or use `/goal resume` or `alt+g`. `/goal pause` resumes only through `/goal resume` or `alt+g`. The status line shows `goal paused · say "go" or /goal resume`, and paused goals are never poked. On a macOS terminal without Option-as-Meta, `alt+g` types `©`; use `/goal resume` there.
 - Background work that finishes while an `ask_user_question` is pending is handed to the agent right after the answer.
 - A compact goal widget that does not replace Pi's footer.
 - Background activity tracking for subagents and other registered providers.

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-goal",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-goal/src/index.ts

@@ -70,6 +70,34 @@ const MAX_NO_PROGRESS_RETRIES = parseRetryLimit(
  * steering after the whole tool batch, and callback batches are follow-ups
  * that wait for the entire run), so the goal harvests them explicitly.
  */
+/** Model-callable resume, active only while an escape-paused goal waits. */
+export const GOAL_RESUME_TOOL = "goal_resume";
+/** Hotkey that resumes any paused goal, like `/goal resume`. */
+export const GOAL_RESUME_SHORTCUT = "alt+g";
+
+/** When the agent may call `goal_resume`; shared by the tool description and the paused prompt. */
+const GOAL_RESUME_RULE =
+  "Call goal_resume only when the user's latest message clearly says to proceed (for example \"go\", \"continue\", \"ok do it\", \"approved, proceed\"), " +
+  "or answers a decision you explicitly asked for in your previous message with a choice that means proceed. Never call it for questions, \"why...\", \"what about...\", \"let me think\", or discussion.";
+
+/** True when the agent may resume this goal with `goal_resume`. */
+export function agentResumable(goal: GoalSnapshot | null): boolean {
+  return goal?.status === "paused" && goal.pauseReason === "interrupt";
+}
+
+/** Footer status for a paused goal, telling the user how to resume it. */
+export function pausedGoalStatus(goal: GoalSnapshot): string {
+  return agentResumable(goal) ? 'goal paused · say "go" or /goal resume' : "goal paused · /goal resume";
+}
+
+function pausedGoalPrompt(goal: GoalSnapshot): string {
+  return [
+    `Pi Better Goal is paused because the user pressed escape. Goal: ${goal.objective}`,
+    "Treat the user's messages as ordinary conversation: answer them, but do not continue the goal's work until it is resumed.",
+    GOAL_RESUME_RULE,
+  ].join("\n");
+}
+
 const BLOCKING_QUESTION_TOOLS: ReadonlySet<string> = new Set(["ask_user_question"]);
 
 const GOAL_ACTIONS: readonly AutocompleteItem[] = [
@@ -195,6 +223,11 @@ function formatGoal(
     `Elapsed time: ${timing.elapsedSeconds}s`,
     `Observable progress: ${stall?.state ?? "unknown"}`,
     continuationStatus,
+    ...(goal.status === "paused"
+      ? [agentResumable(goal)
+        ? 'Resume: say "go" (the agent calls goal_resume), /goal resume, or alt+g'
+        : "Resume: /goal resume or alt+g"]
+      : []),
   ].join("\n");
 }
 
@@ -304,6 +337,8 @@ export default function (pi: ExtensionAPI): void {
     backgroundDrainTracker = null;
     clearIdleContinuation();
     syncPollingState();
+    syncResumeTool(goal);
+    applyStatus(ctx);
     // Force a full redraw when the dock height changes (absent ↔ visible clock).
     refreshGoalWidget?.(!wasVisible || !isGoalClockVisible(goal));
   };
@@ -317,14 +352,16 @@ export default function (pi: ExtensionAPI): void {
     backgroundDrainTracker = null;
     clearIdleContinuation();
     syncPollingState();
+    syncResumeTool(null);
+    applyStatus(ctx);
     refreshGoalWidget?.(wasVisible);
   };
 
   /**
-   * An interrupt (escape, or anything else that aborts the running turn) is a
-   * soft pause: it stops autonomous continuation now, and the user's next
-   * conversational message resumes the goal once that exchange settles. Only
-   * `/goal pause` (or an unavailable command/workflow) is a sticky pause.
+   * An interrupt (escape, or anything else that aborts the running turn) pauses
+   * the goal. It stays paused while the user talks: messages are ordinary
+   * conversation. It resumes through `/goal resume`, the hotkey, or the agent's
+   * `goal_resume` once the user clearly says to proceed.
    */
   const pauseGoalOnInterrupt = (ctx: ExtensionContext): void => {
     const goal = getGoal(ctx);
@@ -332,7 +369,7 @@ export default function (pi: ExtensionAPI): void {
       return;
     }
     setGoal(goalWithStatus(goal, "paused", undefined, "interrupt"), ctx, "runtime");
-    notifyGoal(ctx, "Goal paused (interrupted). Send a message to resume it after that exchange, or use /goal pause to keep it paused.");
+    notifyGoal(ctx, 'Goal paused. Say "go" to resume it, or use /goal resume.');
   };
 
   /** Why a paused goal cannot become active again, or null when it can. */
@@ -346,6 +383,28 @@ export default function (pi: ExtensionAPI): void {
     return null;
   };
 
+  /**
+   * The one resume path shared by `/goal resume`, the hotkey, and `goal_resume`:
+   * reactivate the paused goal and queue its continuation.
+   */
+  const resumeGoal = (
+    ctx: ExtensionContext,
+    source: GoalEntrySource,
+  ): { ok: true; goal: GoalSnapshot } | { ok: false; message: string } => {
+    const current = getGoal(ctx);
+    if (!current || current.status !== "paused") {
+      return { ok: false, message: "Only paused goals can be resumed." };
+    }
+    const blocker = resumeBlocker(current);
+    if (blocker) {
+      return { ok: false, message: blocker };
+    }
+    const goal = goalWithStatus(current, "active");
+    setGoal(goal, ctx, source);
+    queueGoalContinuation(goal, ctx);
+    return { ok: true, goal };
+  };
+
   const boundCommandReady = (goal: GoalSnapshot, ctx: ExtensionContext): boolean => {
     if (!goal.command || commandAvailable(pi, goal.command)) return true;
     setGoal(goalWithStatus(goal, "paused"), ctx, "runtime");
@@ -503,36 +562,62 @@ export default function (pi: ExtensionAPI): void {
       clearIdleContinuation();
     }
 
-    if (ctx.hasUI) {
-      const goal = getGoal(ctx);
-      const continuation = goal ? currentContinuationState(ctx, goal.goalId) : null;
-      const goalStall = observeGoalStall(goal, continuation, {
-        foregroundRunning,
-        backgroundRunning: latestSnapshot?.backgroundRunning ?? false,
-      });
-      let waitingOnAnswer = 0;
+    applyStatus(ctx);
+
+    return snapshot;
+  };
+
+  /** Footer status from the goal state and the latest activity snapshot. */
+  const statusText = (ctx: ExtensionContext, snapshot: ActivitySnapshot | null): string | undefined => {
+    const goal = getGoal(ctx);
+    let waitingOnAnswer = 0;
+    if (snapshot) {
       for (const activeAtStart of pendingQuestions.values()) {
         waitingOnAnswer += finishedSinceQuestion(activeAtStart, snapshot).length;
       }
-      const status = waitingOnAnswer > 0
-        ? `${waitingOnAnswer} background done; waiting on your answer`
-        : snapshot.backgroundRunning
-        ? `bg ${snapshot.activeBackgroundCount}${snapshot.unhealthyBackgroundCount ? `, ${snapshot.unhealthyBackgroundCount} unhealthy` : ""}`
-        : continuation?.blocked
-          ? "waiting: no progress"
-          : goalStall?.state === "stalled"
-            ? "goal stalled"
-          : undefined;
-      try {
-        ctx.ui.setStatus(EXTENSION_NAME, status);
-      } catch {
-        // UI status is best-effort only.
-      }
     }
-
-    return snapshot;
+    if (waitingOnAnswer > 0) return `${waitingOnAnswer} background done; waiting on your answer`;
+    const background = snapshot?.backgroundRunning
+      ? `bg ${snapshot.activeBackgroundCount}${snapshot.unhealthyBackgroundCount ? `, ${snapshot.unhealthyBackgroundCount} unhealthy` : ""}`
+      : undefined;
+    if (goal?.status === "paused") return background ? `${pausedGoalStatus(goal)} · ${background}` : pausedGoalStatus(goal);
+    if (background) return background;
+    const continuation = goal ? currentContinuationState(ctx, goal.goalId) : null;
+    if (continuation?.blocked) return "waiting: no progress";
+    const goalStall = observeGoalStall(goal, continuation, {
+      foregroundRunning,
+      backgroundRunning: snapshot?.backgroundRunning ?? false,
+    });
+    return goalStall?.state === "stalled" ? "goal stalled" : undefined;
   };
 
+  function applyStatus(ctx: ExtensionContext): void {
+    if (!ctx.hasUI) return;
+    try {
+      ctx.ui.setStatus(EXTENSION_NAME, statusText(ctx, latestSnapshot));
+    } catch {
+      // UI status is best-effort only.
+    }
+  }
+
+  /**
+   * `goal_resume` is in the model's tool list only while an escape-paused goal
+   * waits. Pi activates newly registered tools by default, so this also removes
+   * it at session start. Only this one tool is toggled; other extensions' tool
+   * choices are left as they are.
+   */
+  function syncResumeTool(goal: GoalSnapshot | null): void {
+    if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+    try {
+      const active = pi.getActiveTools();
+      const wanted = agentResumable(goal);
+      if (active.includes(GOAL_RESUME_TOOL) === wanted) return;
+      pi.setActiveTools(wanted ? [...active, GOAL_RESUME_TOOL] : active.filter((name) => name !== GOAL_RESUME_TOOL));
+    } catch {
+      // Tool activation is unavailable before Pi binds the session; the tool also refuses on its own.
+    }
+  }
+
   const collectIfPossible = (): void => {
     const ctx = currentCtx;
     if (!ctx) {
@@ -675,18 +760,11 @@ export default function (pi: ExtensionAPI): void {
       }
 
       if (trimmed === "resume") {
-        if (!current || current.status !== "paused") {
-          notifyGoal(ctx, "Only paused goals can be resumed.", "warning");
-          return;
-        }
-        const blocker = resumeBlocker(current);
-        if (blocker) {
-          notifyGoal(ctx, blocker, "error");
+        const result = resumeGoal(ctx, "command");
+        if (!result.ok) {
+          notifyGoal(ctx, result.message, current?.status === "paused" ? "error" : "warning");
           return;
         }
-        const goal = goalWithStatus(current, "active");
-        setGoal(goal, ctx, "command");
-        queueGoalContinuation(goal, ctx);
         notifyGoal(ctx, "Goal resumed.");
         return;
       }
@@ -789,6 +867,44 @@ export default function (pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerTool({
+    name: GOAL_RESUME_TOOL,
+    label: "Resume Goal",
+    description:
+      "Resume the goal the user paused with escape, exactly like /goal resume. " + GOAL_RESUME_RULE,
+    promptSnippet: "Resume the escape-paused goal, only on the user's clear go-ahead.",
+    parameters: Type.Object({
+      reason: Type.Optional(Type.String({ description: "Short quote or summary of the user's go-ahead." })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const reason = (params as { reason?: string }).reason;
+      const current = getGoal(ctx);
+      if (!agentResumable(current)) {
+        const text = current?.status === "paused"
+          ? "This goal was paused with /goal pause or by the runtime. Only the user can resume it, with /goal resume."
+          : "No goal is paused, so there is nothing to resume.";
+        return { content: [{ type: "text", text }], details: { ok: false, goal: current } };
+      }
+      const result = resumeGoal(ctx, "tool");
+      if (!result.ok) {
+        return { content: [{ type: "text", text: `Goal stays paused. ${result.message}` }], details: { ok: false, goal: getGoal(ctx) } };
+      }
+      return {
+        content: [{ type: "text", text: "Goal resumed. Its continuation runs after this turn." }],
+        details: { ok: true, goal: result.goal, ...(reason ? { reason } : {}) },
+      };
+    },
+  });
+
+  pi.registerShortcut?.(GOAL_RESUME_SHORTCUT, {
+    description: "Resume the paused goal",
+    handler: (ctx) => {
+      currentCtx = ctx;
+      const result = resumeGoal(ctx, "command");
+      notifyGoal(ctx, result.ok ? "Goal resumed." : result.message, result.ok ? "info" : "warning");
+    },
+  });
+
   pi.registerCommand("better-activity", {
     description: "Show foreground/background activity known to pi-better-goal",
     handler: async (_args, ctx) => {
@@ -849,6 +965,7 @@ export default function (pi: ExtensionAPI): void {
       notifyGoal(ctx, "Goal paused: invoke its skill directly before resuming.", "error");
     }
     pi.events.emit(EVENT_READY, { version: EXTENSION_VERSION });
+    syncResumeTool(getGoal(ctx));
     installGoalWidget(ctx);
     latestSnapshot = await publishSnapshot(ctx);
     syncPollingState();
@@ -874,23 +991,9 @@ export default function (pi: ExtensionAPI): void {
         }
       }
     }
+    // A paused goal stays paused while the user talks: the message is ordinary
+    // conversation. Only /goal resume, the hotkey, or goal_resume resume it.
     const goal = getGoal(ctx);
-    if (goal?.status === "paused" && goal.pauseReason === "interrupt") {
-      // Conversational input after an interrupt means the user has taken the
-      // wheel, not stopped the goal: reactivate it so continuation resumes once
-      // this exchange settles. Pi's built-in commands (/settings, /model, ...)
-      // and extension commands never reach this handler.
-      const blocker = resumeBlocker(goal);
-      if (blocker) {
-        notifyGoal(ctx, `Goal stays paused. ${blocker}`, "warning");
-        return;
-      }
-      const resumed = goalWithStatus(goal, "active");
-      setGoal(resumed, ctx, "runtime");
-      resetContinuationState(resumed);
-      notifyGoal(ctx, "Goal resumed; it continues after this exchange.");
-      return;
-    }
     if (goal?.status === "active") {
       resetContinuationState(goal);
     }
@@ -901,8 +1004,9 @@ export default function (pi: ExtensionAPI): void {
     const goal = currentGoalSnapshot(ctx);
     const owner = getWorkflow(ctx);
     const snapshot = await publishSnapshot(ctx);
+    const pausedInstruction = agentResumable(goal) ? pausedGoalPrompt(goal!) : "";
     if (!isPokeable(goal) && !owner) {
-      return;
+      return pausedInstruction ? { systemPrompt: `${event.systemPrompt}\n\n${pausedInstruction}` } : undefined;
     }
 
     const questionInstruction = snapshot.backgroundRunning
@@ -923,7 +1027,11 @@ export default function (pi: ExtensionAPI): void {
         return { systemPrompt: `${event.systemPrompt}\n\nWorkflow ${owner.name} is unavailable. Stop work and ask the user to restore or reinvoke the skill.` };
       }
       return {
-        systemPrompt: `${event.systemPrompt}\n\nActive workflow: ${owner.name} (${owner.path}). Its task plan owns planning and the parent is a coordinator, not a product-code implementer. Follow the workflow instructions below, including on resumed turns:\n\n${instructions}` +
+        systemPrompt: `${event.systemPrompt}\n\n` +
+          (pausedInstruction
+            ? `${pausedInstruction}\nWhile the goal is paused, this overrides the workflow instructions below: do not advance the workflow until the goal is resumed.\n\n`
+            : "") +
+          `Active workflow: ${owner.name} (${owner.path}). Its task plan owns planning and the parent is a coordinator, not a product-code implementer. Follow the workflow instructions below, including on resumed turns:\n\n${instructions}` +
           (isPokeable(goal) ? `\n\nActive objective: ${goal.objective}. Complete it only after the workflow completion audit.` : "") +
           (questionInstruction ? `\n\n${questionInstruction.trim()}` : ""),
       };

package/node_modules/pi-better-goal/src/types.ts

@@ -66,10 +66,12 @@ export interface ActivitySnapshot {
 export type GoalStatus = "active" | "paused" | "budgetLimited" | "complete";
 
 /**
- * Why a paused goal is paused. `interrupt` marks a soft pause from escape (or
- * any other abort of the running turn): the user's next conversational message
- * resumes it. A paused goal without a reason (`/goal pause`, an unavailable
- * command or workflow) stays paused until `/goal resume`.
+ * Why a paused goal is paused. `interrupt` marks a pause from escape (or any
+ * other abort of the running turn). Every pause is sticky: user messages never
+ * resume a goal on their own. An `interrupt` pause may be resumed by the agent
+ * with `goal_resume` when the user clearly says to proceed. A paused goal
+ * without a reason (`/goal pause`, an unavailable command or workflow) resumes
+ * only through `/goal resume` or the resume hotkey.
  */
 export type GoalPauseReason = "interrupt";
 

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.9.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",
@@ -51,11 +51,11 @@
   },
   "dependencies": {
     "pi-better-background-tasks": "0.6.0",
-    "pi-better-goal": "0.4.1",
+    "pi-better-goal": "0.5.0",
     "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"
   },