@arhen/pi-core-subagent 1.3.41 → 1.3.43

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.41",
+	"version": "1.3.43",
 	"type": "module",
 	"description": "pi extension: fast in-process subagents with a dependency-graph scheduler (needs edges gate tasks and carry upstream output into dependent prompts), plus background runs, intercom and agent-to-agent mailbox. Leader defines agents inline.",
 	"license": "MIT",

package/src/format.ts

@@ -242,14 +242,20 @@ export function makeSummary(run: RunSnapshot): string {
 		// Edges are named so the leader can compare what it delegated against what came back.
 		const edge = task.needs?.length ? ` (${task.id}, needs ${task.needs.join(", ")})` : ` (${task.id})`;
 		const fileNote = task.agentFile ? ` [${task.agentFile}]` : "";
+		const swap = task.modelNote ? `\nModel: ${task.modelNote}` : "";
 		lines.push(
-			`\n## ${task.agent}${edge}${fileNote} ${statusIcon(task.status)}${task.error ? `\nError: ${task.error}` : `\n${truncateText(task.finalText || "(no output)")}`}${worktreeLine(task, run.tasks)}`,
+			`\n## ${task.agent}${edge}${fileNote} ${statusIcon(task.status)}${swap}${task.error ? `\nError: ${task.error}` : `\n${truncateText(task.finalText || "(no output)")}`}${worktreeLine(task, run.tasks)}`,
 		);
 	}
 	// Ceiling on the WHOLE summary — 16 tasks × 24KB would otherwise flood the parent context.
 	return truncateText(lines.join("\n"));
 }
 /** Per-task notice: one task's outcome, small. Full output stays out of parent context. */
+/** Dead on arrival: failed without ever producing assistant text — model/plan/auth/agent-file
+ *  level, so every respawn with the same config fails identically. */
+export function isStartupFailure(task: TaskSnapshot, kind: string): boolean {
+	return kind === "failed" && !task.finalText?.trim();
+}
 export function makeTaskNotice(run: RunSnapshot, task: TaskSnapshot, kind: string): string {
 	const goal = truncateText(task.task, 120);
 	const detail = task.error ? task.error : truncateText(task.finalText || "(no output)", 200);
@@ -260,10 +266,13 @@ export function makeTaskNotice(run: RunSnapshot, task: TaskSnapshot, kind: strin
 	// 403, wrong persona) that override is the likeliest cause, so it has to be
 	// in the notice, not only in the run summary the leader may never read.
 	const src = task.agentFile ? `\nAgent file: ${task.agentFile}${task.model ? ` (model ${task.model})` : ""}` : "";
+	const swap = task.modelNote ? `\nModel: ${task.modelNote}` : "";
 	return [
 		`Task ${task.agent} (${task.id}) ${kind} in run ${run.id}: ${detail}${wt}`,
-		`Goal: ${goal}${src}`,
-		`Use subagent_result(runId: "${run.id}", taskId: "${task.id}") for full output.`,
+		`Goal: ${goal}${src}${swap}`,
+		isStartupFailure(task, kind)
+			? "Never started — stop and diagnose before spawning anything else: a config-level error (model, plan, auth, agent file) fails identically on every respawn."
+			: `Use subagent_result(runId: "${run.id}", taskId: "${task.id}") for full output.`,
 	].join("\n");
 }
 /** Notification: 3 lines max. Full output stays out of parent context. */

package/src/index.ts

@@ -157,7 +157,7 @@ export default function (pi: ExtensionAPI) {
 		// ponytail: this string is billed on every request. No example block — an example
 		// biases the model toward one shape; guidelines + JSON schema describe all of them.
 		description:
-			"Run isolated subagents (own context, own session). You invent each agent: name, optional system prompt, toolset (read-only default, write:true to edit). Use `agent`+`task` for one, `tasks` for many. `needs` declares dependency edges: a task waits for its needs and receives their outputs prepended to its prompt. If a user agent file in `.agents/agents`, `.claude/agents`, or `.pi/agents` (project dirs, then home) has a `description` matching the spawn goal (name + task), that file is authoritative: body = system prompt, frontmatter `model`/`tools` apply, inline prompt/model/tools ignored. No match → the inline definition stands. Write agents run in an isolated git worktree: on completion the result reports the branch + changed files — review, then merge with `git merge --no-ff <branch>` (merged branches are cleaned automatically). Every run is background: the call returns a runId immediately and completion notifies you. Set autoAwait:true when you need the result before your next step — the call parks until the run finishes and returns runId + final result in one response. allowIntercom:true lets children talk to you and each other.",
+			"Run isolated subagents (own context, own session). You invent each agent: name, optional system prompt, toolset (read-only default, write:true to edit). Use `agent`+`task` for one, `tasks` for many. `needs` declares dependency edges: a task waits for its needs and receives their outputs prepended to its prompt. If a user agent file in `.agents/agents`, `.claude/agents`, or `.pi/agents` (project dirs, then home) has a `description` matching the spawn goal (name + task), that file is authoritative: body = system prompt, frontmatter `model`/`tools` apply, inline prompt/model/tools ignored. No match → the inline definition stands. Write agents run in an isolated git worktree: on completion the result reports the branch + changed files — review, then merge with `git merge --no-ff <branch>` (merged branches are cleaned automatically). Every run is background: the call returns a runId immediately and completion notifies you — do NOT park waiting on it. If you have no other work, end your turn; the completion notice wakes you with the results. Set autoAwait:true only when the very next step in the SAME turn consumes the result. allowIntercom:true lets children talk to you and each other.",
 		promptSnippet: "Define and delegate work to specialized subagents.",
 		promptGuidelines: [
 			"Use subagent when independent review, testing, research, or parallel analysis improves quality.",
@@ -167,8 +167,11 @@ export default function (pi: ExtensionAPI) {
 			"End each task with a runnable check, e.g. 'Verify: npx tsc --noEmit && bun test'. A subagent's claim of success is not evidence.",
 			"For write agents (write:true) in a git repo, the child works in an isolated worktree and its changes are committed to a branch — the result reports branch + changed files. Review the diff, then merge with `git merge --no-ff <branch>`; merged branches are cleaned up automatically. Never leave a worktree branch unmerged at the end of the task.",
 			"Define each agent yourself: invented name, focused system prompt, and read-only (default) or write:true. Prefer read-only. A user agent file (`.agents/agents`, `.claude/agents`, `.pi/agents` — project first, then home) whose `description` matches the spawn goal (name + task) takes over: its body is the system prompt, frontmatter `model`/`tools` apply and are validated against the model registry. Matching is by description, not name — name the agent whatever fits the goal.",
-			"When you need a run's result before your next step, spawn with autoAwait:true — the call returns runId + final result in one response. Otherwise spawn background and settle results (await_subagent / subagent_result) before continuing dependent work.",
-			"For long multi-task runs, don't autoAwait the whole run: spawn background, then loop await_subagent with short timeoutMs slices (e.g. 20s), processing whichever tasks completed in each slice while the rest keep running. You get incremental results instead of one big wait.",
+			"Right after a background spawn, call subagent_status(runId) ONCE before any other work — confirm each task is running (or already progressing), not stuck queued or failed at startup. A child that dies on spawn otherwise stays invisible until far later.",
+			"If that first status shows a task failed or never started, fix or respawn immediately; do not move on assuming it runs.",
+			"Never block with nothing to do: if you have no work left after spawning, end your turn. Task completion notifies you and wakes a fresh turn with the results — await_subagent/autoAwait in that situation only burns time and tokens.",
+			"autoAwait:true only when the same turn must consume the result immediately (e.g. you spawn a reviewer and then must act on its verdict before replying). Otherwise spawn background and read results from the completion notice, or subagent_result when you come back.",
+			"await_subagent is for the rare case where you have parallel work of your own and need to sync at a specific point — not the default follow-up to a spawn.",
 			"allowIntercom:true only when a child may need to ask you something.",
 		],
 		parameters: SubagentParams,
@@ -218,7 +221,7 @@ export default function (pi: ExtensionAPI) {
 				content: [
 					{
 						type: "text",
-						text: `Background run started: ${details.run.id} (${details.run.mode}, ${details.run.tasks.length} task${details.run.tasks.length > 1 ? "s" : ""}).\nUse subagent_status / subagent_result / await_subagent / reply_subagent / subagent_cancel to interact.`,
+						text: `Background run started: ${details.run.id} (${details.run.mode}, ${details.run.tasks.length} task${details.run.tasks.length > 1 ? "s" : ""}).\nNext: call subagent_status("${details.run.id}") now to confirm the tasks actually started before doing anything else.\nAfter that, completion will notify you — if you have no other work, end your turn instead of waiting.\nOther tools: subagent_result / reply_subagent / steer_subagent / subagent_cancel.`,
 					},
 				],
 				details,
@@ -300,8 +303,11 @@ export default function (pi: ExtensionAPI) {
 		name: "subagent_status",
 		label: "Subagent Status",
 		description:
-			"Live status of a subagent run (non-blocking): per-task state, plus each child's session file path (JSONL) so you can tail it from outside — e.g. in a terminal multiplexer pane.",
-		promptSnippet: "Check progress of a subagent run.",
+			"Live status of a subagent run (non-blocking): per-task state, plus each child's session file path (JSONL) so you can tail it from outside — e.g. in a terminal multiplexer pane. Call this once right after spawning to verify the children actually started.",
+		promptSnippet: "Check progress of a subagent run; use right after spawn as a health check.",
+		promptGuidelines: [
+			"Health-check every background spawn with one subagent_status(runId) before continuing — catch dead-on-arrival children early instead of at completion time.",
+		],
 		parameters: RunIdParam,
 		async execute(_id, params) {
 			const { runId } = params as { runId: string };
@@ -348,7 +354,10 @@ export default function (pi: ExtensionAPI) {
 		name: "await_subagent",
 		label: "Await Subagent",
 		description:
-			"Block until a run finishes (or timeoutMs elapses). While parked, child→leader messages (asks, notifies, completions) wake the wait and arrive INSIDE the result — the await doubles as the run's intercom drain, no steering queue involved.",
+			"Block until a run finishes (or timeoutMs elapses). Use ONLY when you have work of your own to sync with; if you have nothing else to do, end your turn instead — completion notifies you and wakes a new turn with the results. While parked, child→leader messages (asks, notifies, completions) wake the wait and arrive INSIDE the result.",
+		promptGuidelines: [
+			"Do not call await_subagent right after spawning with no other work pending — end the turn and let the completion notice wake you.",
+		],
 		parameters: AwaitParam,
 		async execute(_id, params) {
 			const { runId, timeoutMs } = params as { runId: string; timeoutMs?: number };

package/src/manager.ts

@@ -22,6 +22,7 @@ import {
 	activitySnippet,
 	describeCall,
 	getFirstText,
+	isStartupFailure,
 	isTalking,
 	makeNotice,
 	makeTaskNotice,
@@ -159,14 +160,26 @@ export function cloneRun(run: RunSnapshot): RunSnapshot {
 	return JSON.parse(JSON.stringify(run)) as RunSnapshot;
 }
 /** Resolve a child model from the pi model registry.
- *  Order: explicit "provider/model-id" or bare id (searched across available
- *  models) → agent file model → parent's current model (ctx.model) → undefined
- *  (createAgentSession falls back to settings). */
+ *  Order: explicit "provider/model-id" or bare id → agent file model → parent's
+ *  current model (ctx.model) → undefined (createAgentSession falls back to settings).
+ *
+ *  A BARE id is ambiguous: `claude-sonnet-5` exists on anthropic, commandcode,
+ *  github-copilot and openrouter at once, and an agent file's `model:` is written
+ *  without a provider. Taking the registry's first match routed children to a
+ *  provider the session never chose (403 MODEL_NOT_IN_PLAN on every spawn), so the
+ *  ACTIVE SESSION's provider is searched first — exact id, then its own prefixed
+ *  form (9router carries `cc/claude-opus-5`, not `claude-opus-5`). */
 export function resolveChildModel(ctx: ExtensionContext, explicit: string | undefined) {
 	if (!explicit?.trim()) return ctx.model; // inherit the parent's active model
 	const ref = explicit.trim();
 	if (!ctx.modelRegistry) return ctx.model; // no registry to check against (tests, headless)
 	const available = ctx.modelRegistry.getAvailable();
+	const sessionProvider = ctx.model?.provider;
+	if (sessionProvider && !ref.includes("/")) {
+		const own = available.filter((m) => m.provider === sessionProvider);
+		const hit = own.find((m) => m.id === ref) ?? own.find((m) => m.id.endsWith(`/${ref}`));
+		if (hit) return hit;
+	}
 	// Model ids can contain slashes (e.g. 9router/cc/claude-opus-5), so a bare id
 	// match and every provider/id split point must be tried, not just the first.
 	const byId = available.find((m) => m.id === ref);
@@ -178,6 +191,48 @@ export function resolveChildModel(ctx: ExtensionContext, explicit: string | unde
 	throw new Error(`Model not found: ${ref}`);
 }
 
+/** One throwaway request against the resolved model. A child that cannot reach its
+ *  model dies on its FIRST turn with no output, after a worktree and a session have
+ *  already been built — and an agent file's `model:` is chosen by a file the leader
+ *  never wrote, so "it resolved" is not evidence it is usable (plan gates, ZDR,
+ *  dead keys all pass resolution). Returns the error text, or undefined when OK. */
+async function probeModel(
+	ctx: ExtensionContext,
+	model: Model<Api>,
+	signal: AbortSignal | undefined,
+): Promise<string | undefined> {
+	try {
+		const reply = await ctx.modelRegistry.complete(
+			model,
+			{ messages: [{ role: "user", content: "ping", timestamp: Date.now() }] },
+			{ maxTokens: 16, signal },
+		);
+		return reply.stopReason === "error" ? (reply.errorMessage ?? "provider returned an error") : undefined;
+	} catch (err) {
+		return err instanceof Error ? err.message : String(err);
+	}
+}
+
+/** Preflight for the model a child is about to run on. Probes only what is not
+ *  already proven: the session's own model answered this very turn. On failure the
+ *  session model is the fallback — the one model known to work right now. */
+export async function ensureUsableModel(
+	ctx: ExtensionContext,
+	model: Model<Api> | undefined,
+	signal: AbortSignal | undefined,
+): Promise<{ model: Model<Api> | undefined; note?: string }> {
+	const session = ctx.model;
+	if (!model || !ctx.modelRegistry) return { model };
+	if (session && model.provider === session.provider && model.id === session.id) return { model };
+	const error = await probeModel(ctx, model, signal);
+	if (!error) return { model };
+	if (!session) throw new Error(`Model ${model.provider}/${model.id} is unusable: ${error}`);
+	return {
+		model: session,
+		note: `${model.provider}/${model.id} failed preflight (${error}); using session model ${session.provider}/${session.id}`,
+	};
+}
+
 /** Extension-registered providers (e.g. 9router) live only in the parent's
  *  in-memory runtime. A child builds its runtime from disk and would lose them,
  *  so replay the parent's registrations before the child resolves auth. */
@@ -462,7 +517,16 @@ export class SubagentManager {
 		this.pi.events.emit(type, { type, timestamp: Date.now(), ...payload });
 	}
 
-	/** Per-task wake-up: queued follow-up so the parent can interleave responses. */
+	/** Only startup failures are forced: they're dead-on-arrival and the leader must
+	 *  notice before it respawns the same broken config. Completed/aborted and even
+	 *  mid-run failures wait for the turn's end (followUp) — they're not urgent and
+	 *  steering every one of them would interrupt the leader mid-tool-call.
+	 *  force = deliver immediately even while streaming (steer). */
+	private deliverMode(kind: string, task: TaskSnapshot): "steer" | "followUp" {
+		return isStartupFailure(task, kind) ? "steer" : "followUp";
+	}
+
+	/** Per-task wake-up: failures steer in immediately, the rest queue as follow-up. */
 	private notifyTask(run: RunSnapshot, task: TaskSnapshot, kind: "completed" | "failed" | "aborted"): void {
 		const body = makeTaskNotice(run, task, kind);
 		// Parked leader (await_subagent) receives completions through the wait — no queue.
@@ -471,7 +535,7 @@ export class SubagentManager {
 			return;
 		}
 		try {
-			this.pi.sendUserMessage(body, { deliverAs: "followUp" });
+			this.pi.sendUserMessage(body, { deliverAs: this.deliverMode(kind, task) });
 		} catch {
 			/* parent mid-stream; consumers can poll subagent_status */
 		}
@@ -479,8 +543,8 @@ export class SubagentManager {
 	}
 
 	/** Wake the parent with a 3-line notice. Full text stays out of context.
-	 *  deliverAs followUp queues the message if the parent is mid-stream
-	 *  (e.g. inside await_subagent) instead of throwing/aborting. */
+	 *  deliverAs queues the message if the parent is mid-stream (e.g. inside
+	 *  await_subagent) instead of throwing/aborting. */
 	private notifyParent(
 		run: RunSnapshot,
 		kind: "completed" | "failed" | "aborted" | "asked",
@@ -800,10 +864,18 @@ export class SubagentManager {
 		try {
 			model = resolveChildModel(ctx, file?.model ?? input.model);
 			validateThinking(model, thinking);
+			// Resolution only proves the id exists. Probe it before anything is built,
+			// and fall back to the session's own model when the probe fails.
+			const checked = await ensureUsableModel(ctx, model, signal);
+			model = checked.model;
+			if (checked.note) {
+				task.modelNote = checked.note;
+				validateThinking(model, thinking);
+			}
 			// Record the model ACTUALLY used — an agent file's `model:` overrides the
 			// requested one, and showing the request in the widget hides that entirely
 			// (a 403 then names a model the leader never asked for).
-			if (model) this.updateTask(run, task, { model: model.id }, ctx, onUpdate);
+			if (model) this.updateTask(run, task, { model: model.id, modelNote: checked.note }, ctx, onUpdate);
 		} catch (err) {
 			this.updateTask(
 				run,

package/src/types.ts

@@ -36,6 +36,9 @@ export interface TaskSnapshot {
 	finalText?: string;
 	error?: string;
 	model?: string;
+	/** Why `model` is not what was requested: preflight failed and the session's
+	 *  model took over. Silent substitution is worse than a slow spawn. */
+	modelNote?: string;
 	thinking?: string;
 	tools?: string[];
 	usage: UsageStats;