@arhen/pi-core-subagent 1.3.57 → 1.3.59

package/README.md

@@ -305,13 +305,15 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 
 | Tool | Meaning |
 |---|---|
-| `ask_parent` | blocking question to the leader; parent answers via `reply_subagent` |
+| `ask_parent` | blocking question to the leader; delivered mid-turn as a **steering** message labelled `[URGENT]` or `[not urgent]`, parent answers via `reply_subagent` |
 | `notify_parent` | one-way message to the leader |
 | `send_agent_message` | message to a sibling subagent's mailbox (`to` = its task id, or `"leader"`) |
 | `poll_agent_messages` | drain this subagent's mailbox |
 
 > **Intercom anti-deadlock:** children are told to never block indefinitely on intercom replies — an unanswered `ask_parent` times out after 10 minutes (the child is told to proceed with best judgment), and sibling polls are capped (~5 tries) with the same fallback. Gated siblings (later waves) may not be running yet — waiting on them is the top stall cause, so children are instructed not to.
 
+> **Ask urgency:** `ask_parent` takes `urgent` (default `false`). Both variants steer into the leader's current turn so the question is never deferred to the end of a long turn. `[URGENT]` tells the leader to answer before its next step; `[not urgent]` tells it that the child keeps waiting, so it may finish its current step first. Failures steer for the same reason; completions and aborts queue as follow-ups.
+
 ## Commands
 
 - `/subagents` — list runs; `/subagents peek` (or `ctrl+shift+a`) — browsable pane

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.57",
+	"version": "1.3.59",
 	"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/child.ts

@@ -6,7 +6,7 @@ import type { MailboxMessage } from "./mailbox.ts";
 export const CHILD_TALK_TOOLS = ["ask_parent", "notify_parent", "send_agent_message", "poll_agent_messages"] as const;
 
 export interface ChildHandlers {
-	onAskParent(taskId: string, question: string): Promise<string>;
+	onAskParent(taskId: string, question: string, urgent: boolean): Promise<string>;
 	onNotifyParent(taskId: string, message: string, level: "info" | "warning" | "error"): void;
 	onSendMessage(taskId: string, to: string, text: string): boolean;
 	onPollMailbox(taskId: string): MailboxMessage[];
@@ -18,18 +18,26 @@ export function createChildTools(taskId: string, handlers: ChildHandlers): ToolD
 			name: "ask_parent",
 			label: "Ask Parent",
 			description:
-				"Ask the parent agent a clarifying question and BLOCK until it replies (10 min cap — then proceed with best judgment). Use sparingly — only when you truly cannot proceed without information only the parent has. Prefer figuring it out yourself.",
+				"Ask the parent agent a clarifying question and BLOCK until it replies (10 min cap — then proceed with best judgment). Use sparingly — only when you truly cannot proceed without information only the parent has. Prefer figuring it out yourself. The parent sees the question mid-turn: set urgent when you cannot continue until it answers, leave it unset when the parent may finish its current step first.",
 			promptSnippet: "Ask the parent agent a question when truly blocked.",
 			promptGuidelines: [
 				"Use ask_parent only as a last resort when blocked on information only the parent has.",
 				"Ask one focused question at a time. The parent's reply resumes your work.",
+				"Set urgent: true only when you cannot keep working while waiting; otherwise the parent is told it may answer after its current step.",
 			],
 			parameters: Type.Object({
 				question: Type.String({ description: "A single, focused question for the parent agent" }),
+				urgent: Type.Optional(
+					Type.Boolean({
+						description:
+							"True when nothing else can proceed until the parent answers — it is told to stop and reply now",
+						default: false,
+					}),
+				),
 			}),
 			async execute(_toolCallId, params) {
-				const { question } = params as { question: string };
-				const answer = await handlers.onAskParent(taskId, question);
+				const { question, urgent } = params as { question: string; urgent?: boolean };
+				const answer = await handlers.onAskParent(taskId, question, urgent === true);
 				return { content: [{ type: "text" as const, text: answer || "(parent gave no answer)" }], details: {} };
 			},
 		},

package/src/format.ts

@@ -111,10 +111,17 @@ export function isTalking(task: TaskSnapshot): boolean {
 	return TALK_TOOLS.some((t) => a.startsWith(t));
 }
 let pulsePhase = 0;
+const NOTE_CAP = 240;
+function noteSnippet(note: string): string {
+	return note.length > NOTE_CAP ? `${note.slice(0, NOTE_CAP)}…` : note;
+}
 export function compactLines(run: RunSnapshot): string[] {
 	const lines: string[] = [];
 	for (const task of run.tasks.slice(0, MAX_TASKS)) {
 		lines.push(taskLine(task));
+		// a swapped model or toolset changes what the task did, so it cannot stay out of the status view
+		if (task.modelNote) lines.push(`   ↳ Model: ${noteSnippet(task.modelNote)}`);
+		if (task.toolsNote) lines.push(`   ↳ Tools: ${noteSnippet(task.toolsNote)}`);
 	}
 	if (run.tasks.length > MAX_TASKS) lines.push(`… +${run.tasks.length - MAX_TASKS} more`);
 	return lines;
@@ -243,6 +250,17 @@ export function makeTaskNotice(run: RunSnapshot, task: TaskSnapshot, kind: strin
 				: `Session file kept — resume_subagent(runId: "${run.id}", taskId: "${task.id}", model?: ...) revives it with full context. subagent_result for what it produced so far.`,
 	].join("\n");
 }
+export function makeAskNotice(
+	run: RunSnapshot,
+	extra: { taskId?: string; agent?: string; question?: string; urgent?: boolean },
+): string {
+	const who = extra.agent ? `${extra.agent} (${extra.taskId ?? "task"})` : (extra.taskId ?? "a subagent");
+	const reply = `reply_subagent(runId: "${run.id}", taskId: "${extra.taskId ?? ""}", message: ...)`;
+	return extra.urgent
+		? `[URGENT] Subagent ${who} is blocked and cannot continue until you answer: ${extra.question ?? ""}\nAnswer now, before your next step, with ${reply}.`
+		: `[not urgent] Subagent ${who} asks: ${extra.question ?? ""}\nIt waits while you keep working — finish your current step first if you want, then answer with ${reply}.`;
+}
+
 export function makeNotice(run: RunSnapshot, kind: string): string {
 	const lines = [
 		`Background subagent run ${run.id} ${kind}: ${run.tasks.filter((t) => t.status === "completed").length}/${run.tasks.length} succeeded.`,

package/src/index.ts

@@ -299,7 +299,8 @@ export default function (pi: ExtensionAPI) {
 							? `\nApplied IN PLACE (no branch) — ${t.isolationReason ?? "worktree unavailable"}. The changes are already in your working tree.`
 							: "";
 					const wtErr = t.worktreeError ? `\nWorktree: ${t.worktreeError}` : "";
-					return `\n## ${t.agent} ${statusIcon(t.status)}\nGoal: ${truncateText(t.task, 300)}\n${t.error ? `Error: ${t.error}` : t.finalText || "(no output yet)"}${wt}${wtErr}\n${formatUsage(t.usage)}`;
+					const modelNote = t.modelNote ? `\nModel: ${t.modelNote}` : "";
+					return `\n## ${t.agent} ${statusIcon(t.status)}\nGoal: ${truncateText(t.task, 300)}\n${t.error ? `Error: ${t.error}` : t.finalText || "(no output yet)"}${wt}${wtErr}${modelNote}\n${formatUsage(t.usage)}`;
 				}),
 			].join("\n");
 			return { content: [{ type: "text", text: truncateText(text) }], details: { run: cloneRun(run) } };

package/src/manager.ts

@@ -2,7 +2,13 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync
 import { rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, sep } from "node:path";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
+import {
+	type Api,
+	type AssistantMessage,
+	clampThinkingLevel,
+	getSupportedThinkingLevels,
+	type Model,
+} from "@earendil-works/pi-ai";
 import {
 	type AgentSessionEvent,
 	createAgentSession,
@@ -23,6 +29,7 @@ import {
 	getFirstText,
 	isStartupFailure,
 	isTalking,
+	makeAskNotice,
 	makeNotice,
 	makeTaskNotice,
 	SubagentsWidget,
@@ -160,21 +167,19 @@ export function resolveChildModel(ctx: ExtensionContext, explicit: string | unde
 const PROBE_THINKING_LEVELS: ThinkingLevel[] = ["low", "minimal", "medium", "high", "xhigh", "max"];
 
 /**
- * Thinking level for the usability probe: the one the task asked for, else the cheapest
- * the model accepts. Providers that require adaptive thinking reject a probe without one
- * (9router claude models answer `thinking.type.disabled is not supported`), which used to
- * make every preflight fail and fall back to the session model.
+ * Thinking level for the usability probe: exactly what the child session will send — the clamped
+ * requested level, or the cheapest the model accepts when none was requested. Probing without a
+ * level makes adaptive-thinking providers reject the request (9router claude models answer
+ * "thinking.type.disabled is not supported"), which used to make every preflight fail and fall
+ * back to the session model.
  */
 function probeThinking(model: Model<Api>, thinking?: string): ThinkingLevel | undefined {
-	if (thinking && thinking !== "off") return thinking as ThinkingLevel;
 	if (!model.reasoning) return undefined;
-	const map = model.thinkingLevelMap;
-	if (!map) return "low";
-	for (const level of PROBE_THINKING_LEVELS) {
-		const mapped = map[level as keyof typeof map];
-		if (mapped !== null && mapped !== undefined) return level;
-	}
-	return undefined;
+	const supported = getSupportedThinkingLevels(model);
+	if (thinking && thinking !== "off") return clampThinkingLevel(model, thinking as ThinkingLevel);
+	// the child clamps an unsupported "off" up to its cheapest level, so probe that instead
+	if (thinking === "off") return supported.includes("off") ? undefined : supported[0];
+	return PROBE_THINKING_LEVELS.find((level) => supported.includes(level));
 }
 
 async function probeModel(
@@ -325,10 +330,10 @@ export class SubagentManager {
 		return false;
 	}
 
-	clearWidget(ctx: ExtensionContext): void {
+	clearWidget(ctx?: ExtensionContext): void {
 		this.widgetRuns = [];
 		this.widgetTui = null;
-		if (ctx.hasUI) {
+		if (ctx?.hasUI) {
 			try {
 				ctx.ui.setWidget("subagents", undefined);
 			} catch {}
@@ -490,24 +495,32 @@ export class SubagentManager {
 	private notifyParent(
 		run: RunSnapshot,
 		kind: "completed" | "failed" | "aborted" | "asked",
-		extra?: { taskId?: string; question?: string },
+		extra?: { taskId?: string; agent?: string; question?: string; urgent?: boolean },
 	): void {
 		if (kind !== "asked" && run.awaited) return;
 		// single-task completed run: the task notice already said everything (failure paths may not have notified per-task)
 		if (kind === "completed" && run.tasks.length === 1 && run.notifyPerTask) return;
-		const body =
-			kind === "asked"
-				? `A subagent is asking you a question (task ${extra?.taskId}): ${extra?.question ?? ""}\nReply with reply_subagent(runId: "${run.id}", taskId: "${extra?.taskId}", message: ...).`
-				: makeNotice(run, kind);
+		const body = kind === "asked" ? makeAskNotice(run, extra ?? {}) : makeNotice(run, kind);
+		// asks steer: the leader sees the question during its turn and the urgent flag tells it whether to
+		// answer now or after the current step. Failures steer for the same reason — a broken result must
+		// not be consumed. Completions and aborts queue as follow-ups.
 		try {
-			this.pi.sendUserMessage(body, { deliverAs: kind === "failed" ? "steer" : "followUp" });
+			this.pi.sendUserMessage(body, {
+				deliverAs: kind === "completed" || kind === "aborted" ? "followUp" : "steer",
+			});
 		} catch {}
-		this.emit("subagent:notification", { runId: run.id, kind, body });
+		this.emit("subagent:notification", { runId: run.id, taskId: extra?.taskId, kind, body });
 	}
 
 	private widgetTui: TUI | null = null;
+
+	/** Settled runs are history (subagent_status/result still reach them) — the widget shows live work only. */
+	private pruneSettledWidget(): void {
+		this.widgetRuns = this.widgetRuns.filter((r) => !TERMINAL.includes(r.status));
+	}
 	private upsertWidgetRun(run: RunSnapshot | undefined): void {
-		if (!run) return;
+		this.pruneSettledWidget();
+		if (!run || TERMINAL.includes(run.status)) return;
 		const idx = this.widgetRuns.findIndex((r) => r.id === run.id);
 		if (idx >= 0) this.widgetRuns[idx] = run;
 		else this.widgetRuns.push(run);
@@ -547,12 +560,17 @@ export class SubagentManager {
 				this.widgetTimers.delete(run.id);
 			}
 		}
-		if (!run || this.widgetRuns.length === 0) return;
-		if (ctx?.hasUI) {
-			this.ensureWidget(ctx);
-			this.widgetTui?.requestRender();
+		this.pruneSettledWidget();
+		if (this.widgetRuns.length === 0) {
+			if (this.widgetTui) this.clearWidget(ctx);
+		} else {
+			if (ctx?.hasUI) {
+				this.ensureWidget(ctx);
+				this.widgetTui?.requestRender();
+			}
+			this.maybePulse(ctx);
 		}
-		this.maybePulse(ctx);
+		if (!run) return;
 
 		onUpdate?.({
 			content: [
@@ -599,14 +617,14 @@ export class SubagentManager {
 
 	private makeChildHandlers(run: RunSnapshot, task: TaskSnapshot, ctx: ExtensionContext): ChildHandlers {
 		return {
-			onAskParent: async (_taskId, question) => {
+			onAskParent: async (_taskId, question, urgent) => {
 				if (TERMINAL.includes(task.status)) {
 					return "(your task has already ended — stop work and return immediately)";
 				}
 				this.updateTask(run, task, { status: "awaiting_parent" }, ctx);
 
 				if (!this.collectParked(run.id, { kind: "ask", taskId: task.id, agent: task.agent, text: question })) {
-					this.notifyParent(run, "asked", { taskId: task.id, question });
+					this.notifyParent(run, "asked", { taskId: task.id, agent: task.agent, question, urgent });
 				}
 
 				const reply = await this.awaitParentReply(run.id, task.id, PARENT_REPLY_TIMEOUT_MS);
@@ -876,7 +894,7 @@ export class SubagentManager {
 			const worktreeNote = wt
 				? ` You work in an isolated git worktree (branch ${wt.branch})${task.stackedOn ? `, stacked on ${task.stackedOn} (its changes are already in your tree)` : ""}. Never run git commands that switch branches, create branches, or move the worktree (git switch/checkout/branch/worktree). The extension commits your changes when you finish. git status/diff are fine for inspecting your own changes. node_modules is a SHARED symlink to the main checkout: never install, upgrade, or delete dependencies (no npm/bun/yarn/pnpm install, no \`rm -rf node_modules\`) — those writes escape your worktree and damage the user's project. If the task truly needs a dependency change, edit the manifest only and say so in your answer.`
 				: "";
-			const subagentInstruction = `You are running as a subagent. Your bash tool already executes in the project working directory — never prefix commands with \`cd\`. Do not call subagent/delegation tools unless the parent explicitly asks. Return a concise final answer. You MAY use ask_parent only when truly blocked on information only the parent has; notify_parent for one-way updates; send_agent_message/poll_agent_messages to coordinate with siblings. Your mailbox address and siblings: ${task.roster ?? "(none)"}. Use the exact task ids (e.g. task_2) as send_agent_message targets. Siblings run independently and may start late or finish early — never block indefinitely on their replies: poll at most 5 times, then proceed with your best judgment. A gated sibling (marked ↳ waits in the graph) may not be running yet; do not wait for it. An unanswered ask_parent times out after 10 minutes — proceed with your best judgment then. When your work is done, call notify_parent ONCE with a concise result summary — key findings, verdicts, file:line evidence — so the leader can start consuming your output before the run finishes.${worktreeNote}`;
+			const subagentInstruction = `You are running as a subagent. Your bash tool already executes in the project working directory — never prefix commands with \`cd\`. Do not call subagent/delegation tools unless the parent explicitly asks. Return a concise final answer. You MAY use ask_parent only when truly blocked on information only the parent has (set urgent: true only when nothing else can proceed while you wait); notify_parent for one-way updates; send_agent_message/poll_agent_messages to coordinate with siblings. Your mailbox address and siblings: ${task.roster ?? "(none)"}. Use the exact task ids (e.g. task_2) as send_agent_message targets. Siblings run independently and may start late or finish early — never block indefinitely on their replies: poll at most 5 times, then proceed with your best judgment. A gated sibling (marked ↳ waits in the graph) may not be running yet; do not wait for it. An unanswered ask_parent times out after 10 minutes — proceed with your best judgment then. When your work is done, call notify_parent ONCE with a concise result summary — key findings, verdicts, file:line evidence — so the leader can start consuming your output before the run finishes.${worktreeNote}`;
 
 			const loader = new DefaultResourceLoader({
 				cwd: childCwd,