@arhen/pi-core-subagent 1.3.58 → 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.58",
+	"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

@@ -250,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/manager.ts

@@ -29,6 +29,7 @@ import {
 	getFirstText,
 	isStartupFailure,
 	isTalking,
+	makeAskNotice,
 	makeNotice,
 	makeTaskNotice,
 	SubagentsWidget,
@@ -494,19 +495,21 @@ 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;
@@ -614,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);
@@ -891,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,