@narumitw/pi-subagents 0.25.0 → 0.26.0

package/src/subagents.ts

@@ -14,37 +14,33 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerSubagentConfigCommand } from "./config-ui.js";
-import { SubagentParams } from "./params.js";
 import { executeSubagent } from "./execution.js";
+import { SubagentParams } from "./params.js";
 import { renderSubagentCall, renderSubagentResult } from "./render.js";
 import type { SubagentDetails } from "./runner.js";
-import { registerStatefulSubagents } from "./stateful.js";
 import { consumeSubagentSettingsNotice, readSubagentSettings } from "./settings.js";
+import { registerStatefulSubagents } from "./stateful.js";
 
 export default function (pi: ExtensionAPI) {
 	pi.registerTool<typeof SubagentParams, SubagentDetails>({
 		name: "subagent",
-		label: "Subagent",
+		label: "Blocking Subagent",
 		description: [
-			"Delegate tasks to specialized subagents with isolated context.",
+			"Run specialized subagents as a blocking operation with isolated contexts.",
+			"The call blocks the main agent until every worker and optional aggregator finishes, so queued steering waits.",
 			"Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder).",
 			"Parallel mode may include an aggregator fan-in step that receives all task outputs.",
 			'Default agent scope is "user" (from ~/.pi/agent/agents).',
 			'To enable project-local agents in .pi/agents, pass agentScope: "both" (or "project") as a top-level argument for that call.',
 		].join(" "),
 		promptSnippet:
-			"Decide whether to spawn 0, 1, or multiple subagents for independent research, review, verification, or multi-step work in isolated Pi processes.",
+			"Run blocking isolated subagents only when their outputs are required before the main agent can continue.",
 		promptGuidelines: [
 			"Use subagent only when delegation fits; the main agent should decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
-			"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work needed for the main agent's next action.",
-			"A single blocking subagent call should be used only when independent context, high-volume output isolation, or an external review is worth waiting for; otherwise do the task in the main agent.",
-			"For one-shot parallel work, use a single subagent call with tasks instead of repeated subagent_spawn calls, even when the user explicitly requests multiple agents.",
-			"When subagent_spawn is available, use it only for a concrete bounded subtask that can run independently alongside useful main-agent work and has a parallel, isolation, or specialization benefit; otherwise keep the work in the main agent.",
-			"After subagent_spawn returns, do useful non-overlapping work immediately. Call subagent_wait sparingly, only when the immediate next critical-path step requires the result and is blocked until it arrives; do not wait repeatedly by reflex.",
-			"Consume and synthesize available subagent_spawn completion messages; interrupt or close agents that are no longer needed.",
-			"Use subagent parallel mode with 2-4 parallel read-only subagents when work has broad independent branches; prefer scout or reviewer for fan-out and add an aggregator when synthesis helps.",
-			"Use more than 4 subagent tasks only when clearly justified by distinct independent branches, and stay within the existing hard max 8 parallel tasks.",
-			"Do not use subagent parallel mode for write-heavy implementation touching the same files or shared state; serialize those changes in the main agent or one worker.",
+			"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work the main agent can perform directly.",
+			"Use the blocking subagent tool only when delegated outputs are required before the main agent's next action and waiting is intentional; the main agent cannot process queued steering until the call returns.",
+			"Use a blocking subagent single, parallel, chain, or fan-in call only when synchronous context or output isolation is worth making the main agent unavailable while it runs.",
+			"If a blocking parallel subagent call is genuinely required, keep tasks independent, stay within the hard max 8, and avoid write-heavy implementation touching the same files or shared state.",
 			'Do not use subagent with project-local agents unless the user explicitly wants project agents or sets agentScope to "project" or "both"; keep confirmation enabled for untrusted repositories.',
 			"When using subagent, write self-contained tasks with file paths, context, expected output, and whether the subagent may edit files.",
 		],
@@ -78,18 +74,22 @@ export default function (pi: ExtensionAPI) {
 		if (notice) ctx.ui.notify(notice, "warning");
 	});
 
-	registerSubagentConfigCommand(pi);
-	registerStatefulSubagents(pi);
+	const statefulRuntime = registerStatefulSubagents(pi);
+	registerSubagentConfigCommand(pi, statefulRuntime);
 }
+export { parsePositiveInteger } from "./execution.js";
 export { formatTokens, formatUsageStats } from "./render.js";
 export { buildPiArgs } from "./runner.js";
 export {
+	inspectCompletionDeliverySettings,
 	normalizeAgentSettings,
 	normalizeSubagentSettings,
 	readSubagentSettings,
 	resolveSubagentThinkingLevel,
-	saveSubagentConfig,
 	sameToolSet,
+	saveSubagentConfig,
+	subagentSettingsFilePath,
 	uniqueToolNames,
+	updateAgentToolsSetting,
+	updateCompletionDeliverySetting,
 } from "./settings.js";
-export { parsePositiveInteger } from "./execution.js";

package/src/subprocess-transport.ts

@@ -1,19 +1,20 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { discoverAgents } from "./agents.js";
+import { type AgentConfig, discoverAgents, type SubagentThinkingLevel } from "./agents.js";
 import type { ManagedAgent, TurnOutcome } from "./registry.js";
 import { getResultFinalOutput, runSingleAgent, type SubagentDetails } from "./runner.js";
 import { readSubagentSettings, resolveSubagentThinkingLevel } from "./settings.js";
-import {
-	buildStatefulTurnPrompt,
-	resolveStatefulTurnTimeout,
-} from "./stateful-prompt.js";
+import { buildStatefulTurnPrompt, resolveStatefulTurnTimeout } from "./stateful-prompt.js";
 import type { SubagentTransport } from "./transport.js";
 
+export function resolveStatefulSubprocessThinkingLevel(
+	agents: readonly Pick<AgentConfig, "name" | "thinkingLevel">[],
+	record: Pick<ManagedAgent, "agent" | "thinkingLevel">,
+): SubagentThinkingLevel | undefined {
+	return resolveSubagentThinkingLevel(agents, record.agent, record.thinkingLevel);
+}
+
 export class SubprocessTransport implements SubagentTransport {
 	readonly kind = "subprocess" as const;
 
-	constructor(private readonly ctx: ExtensionContext) {}
-
 	async runTurn(record: ManagedAgent, task: string, signal: AbortSignal): Promise<TurnOutcome> {
 		const settings = readSubagentSettings();
 		const discovery = discoverAgents(record.cwd, record.agentScope ?? "user", settings);
@@ -33,7 +34,7 @@ export class SubprocessTransport implements SubagentTransport {
 			undefined,
 			undefined,
 			signal,
-			resolveSubagentThinkingLevel(discovery.agents, record.agent),
+			resolveStatefulSubprocessThinkingLevel(discovery.agents, record),
 			resolveStatefulTurnTimeout(agent),
 			undefined,
 			makeDetails,