pi-subagents 0.11.4 → 0.11.6

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [0.11.6] - 2026-03-20
+
+### Added
+- Added `delegate` builtin agent — a lightweight subagent with no model, output, or default reads. Inherits the parent session's model, making it the natural target for prompt-template delegated execution.
+
+## [0.11.5] - 2026-03-20
+
+### Added
+- Added fork context preamble: tasks run with `context: "fork"` are now wrapped with a default preamble that anchors the subagent to its task, preventing it from continuing the parent conversation. The default is `DEFAULT_FORK_PREAMBLE` in `types.ts`. Internal/programmatic callers can use `wrapForkTask(task, false)` to disable it or pass a custom string (this is not exposed as a tool parameter).
+- Added a prompt-template delegation bridge (`prompt-template-bridge.ts`) on the shared extension event bus. The subagent extension now listens for `prompt-template:subagent:request` and emits correlated `started`/`response`/`update` events, with cwd safety checks and race-safe cancellation handling.
+- Added delegated progress streaming via `prompt-template:subagent:update`, mapped from subagent executor `onUpdate` progress payloads.
+
+### Changed
+- Session lifecycle reset now preserves the latest extension context for event-bus delegated runs.
+- `[fork]` badge is now shown only on the result row, not duplicated on both the tool-call and result rows.
+
 ## [0.11.4] - 2026-03-19
 
 ### Added

package/README.md

@@ -34,7 +34,7 @@ Agents are markdown files with YAML frontmatter that define specialized subagent
 
 Use `agentScope` parameter to control discovery: `"user"`, `"project"`, or `"both"` (default; project takes priority).
 
-**Builtin agents:** The extension ships with ready-to-use agents — `scout`, `planner`, `worker`, `reviewer`, `context-builder`, and `researcher`. They load at lowest priority so any user or project agent with the same name overrides them. Builtin agents appear with a `[builtin]` badge in listings and cannot be modified through management actions (create a same-named user agent to override instead).
+**Builtin agents:** The extension ships with ready-to-use agents — `scout`, `planner`, `worker`, `reviewer`, `context-builder`, `researcher`, and `delegate`. They load at lowest priority so any user or project agent with the same name overrides them. Builtin agents appear with a `[builtin]` badge in listings and cannot be modified through management actions (create a same-named user agent to override instead).
 
 > **Note:** The `researcher` agent uses `web_search`, `fetch_content`, and `get_search_content` tools which require the [pi-web-access](https://github.com/nicobailon/pi-web-access) extension. Install it with `pi install npm:pi-web-access`.
 

package/agents/delegate.md

@@ -0,0 +1,6 @@
+---
+name: delegate
+description: Lightweight subagent that inherits the parent model with no default reads
+---
+
+You are a delegated agent. Execute the assigned task using your tools. Be direct and efficient.

package/index.ts

@@ -27,6 +27,7 @@ import { createSubagentExecutor } from "./subagent-executor.js";
 import { createAsyncJobTracker } from "./async-job-tracker.js";
 import { createResultWatcher } from "./result-watcher.js";
 import { registerSlashCommands } from "./slash-commands.js";
+import { registerPromptTemplateDelegationBridge } from "./prompt-template-bridge.js";
 import {
 	type Details,
 	type ExtensionConfig,
@@ -138,6 +139,27 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		discoverAgents,
 	});
 
+	const promptTemplateBridge = registerPromptTemplateDelegationBridge({
+		events: pi.events,
+		getContext: () => state.lastUiContext,
+		execute: async (requestId, request, signal, ctx, onUpdate) =>
+			executor.execute(
+				requestId,
+				{
+					agent: request.agent,
+					task: request.task,
+					context: request.context,
+					cwd: request.cwd,
+					model: request.model,
+					async: false,
+					clarify: false,
+				},
+				signal,
+				onUpdate,
+				ctx,
+			),
+	});
+
 	const tool: ToolDefinition<typeof SubagentParams, Details> = {
 		name: "subagent",
 		label: "Subagent",
@@ -184,21 +206,20 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 			}
 			const isParallel = (args.tasks?.length ?? 0) > 0;
 			const asyncLabel = args.async === true && !isParallel ? theme.fg("warning", " [async]") : "";
-			const contextLabel = args.context === "fork" ? theme.fg("warning", " [fork]") : "";
 			if (args.chain?.length)
 				return new Text(
-					`${theme.fg("toolTitle", theme.bold("subagent "))}chain (${args.chain.length})${asyncLabel}${contextLabel}`,
+					`${theme.fg("toolTitle", theme.bold("subagent "))}chain (${args.chain.length})${asyncLabel}`,
 					0,
 					0,
 				);
 			if (isParallel)
 				return new Text(
-					`${theme.fg("toolTitle", theme.bold("subagent "))}parallel (${args.tasks!.length})${contextLabel}`,
+					`${theme.fg("toolTitle", theme.bold("subagent "))}parallel (${args.tasks!.length})`,
 					0,
 					0,
 				);
 			return new Text(
-				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent || "?")}${asyncLabel}${contextLabel}`,
+				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent || "?")}${asyncLabel}`,
 				0,
 				0,
 			);
@@ -332,6 +353,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 	const resetSessionState = (ctx: ExtensionContext) => {
 		state.baseCwd = ctx.cwd;
 		state.currentSessionId = ctx.sessionManager.getSessionFile() ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+		state.lastUiContext = ctx;
 		cleanupSessionArtifacts(ctx);
 		resetJobs(ctx);
 	};
@@ -354,6 +376,8 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 		}
 		state.cleanupTimers.clear();
 		state.asyncJobs.clear();
+		promptTemplateBridge.cancelAll();
+		promptTemplateBridge.dispose();
 		if (state.lastUiContext?.hasUI) {
 			state.lastUiContext.ui.setWidget(WIDGET_KEY, undefined);
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",

package/prompt-template-bridge.ts

@@ -0,0 +1,225 @@
+export const PROMPT_TEMPLATE_SUBAGENT_REQUEST_EVENT = "prompt-template:subagent:request";
+export const PROMPT_TEMPLATE_SUBAGENT_STARTED_EVENT = "prompt-template:subagent:started";
+export const PROMPT_TEMPLATE_SUBAGENT_RESPONSE_EVENT = "prompt-template:subagent:response";
+export const PROMPT_TEMPLATE_SUBAGENT_UPDATE_EVENT = "prompt-template:subagent:update";
+export const PROMPT_TEMPLATE_SUBAGENT_CANCEL_EVENT = "prompt-template:subagent:cancel";
+
+export interface PromptTemplateDelegationRequest {
+	requestId: string;
+	agent: string;
+	task: string;
+	context: "fresh" | "fork";
+	model: string;
+	cwd: string;
+}
+
+export interface PromptTemplateDelegationResponse extends PromptTemplateDelegationRequest {
+	messages: unknown[];
+	isError: boolean;
+	errorText?: string;
+}
+
+export interface PromptTemplateDelegationUpdate {
+	requestId: string;
+	currentTool?: string;
+	currentToolArgs?: string;
+	recentOutput?: string;
+	toolCount?: number;
+	durationMs?: number;
+	tokens?: number;
+}
+
+export interface PromptTemplateBridgeEvents {
+	on(event: string, handler: (data: unknown) => void): (() => void) | void;
+	emit(event: string, data: unknown): void;
+}
+
+interface PromptTemplateBridgeResult {
+	isError?: boolean;
+	content?: unknown;
+	details?: {
+		results?: Array<{
+			messages?: unknown[];
+		}>;
+		progress?: Array<{
+			currentTool?: string;
+			currentToolArgs?: string;
+			recentOutput?: string[];
+			toolCount?: number;
+		}>;
+	};
+}
+
+export interface PromptTemplateBridgeOptions<Ctx extends { cwd?: string }> {
+	events: PromptTemplateBridgeEvents;
+	getContext: () => Ctx | null;
+	execute: (
+		requestId: string,
+		request: PromptTemplateDelegationRequest,
+		signal: AbortSignal,
+		ctx: Ctx,
+		onUpdate: (result: PromptTemplateBridgeResult) => void,
+	) => Promise<PromptTemplateBridgeResult>;
+}
+
+export function parsePromptTemplateRequest(data: unknown): PromptTemplateDelegationRequest | undefined {
+	if (!data || typeof data !== "object") return undefined;
+	const value = data as Partial<PromptTemplateDelegationRequest>;
+	if (!value.requestId || !value.agent || !value.task || !value.model || !value.cwd) return undefined;
+	if (value.context !== "fresh" && value.context !== "fork") return undefined;
+	return {
+		requestId: value.requestId,
+		agent: value.agent,
+		task: value.task,
+		context: value.context,
+		model: value.model,
+		cwd: value.cwd,
+	};
+}
+
+export function firstTextContent(content: unknown): string | undefined {
+	if (!Array.isArray(content)) return undefined;
+	for (const part of content) {
+		if (!part || typeof part !== "object") continue;
+		if ((part as { type?: string }).type !== "text") continue;
+		const text = (part as { text?: unknown }).text;
+		if (typeof text === "string" && text.trim()) return text.trim();
+	}
+	return undefined;
+}
+
+function toDelegationUpdate(requestId: string, update: PromptTemplateBridgeResult): PromptTemplateDelegationUpdate | undefined {
+	const progress = update.details?.progress?.[0];
+	if (!progress) return undefined;
+	const lastOutput = progress.recentOutput?.[progress.recentOutput.length - 1];
+	return {
+		requestId,
+		currentTool: progress.currentTool,
+		currentToolArgs: progress.currentToolArgs,
+		recentOutput: lastOutput && lastOutput !== "(running...)" ? lastOutput : undefined,
+		toolCount: progress.toolCount,
+		durationMs: (progress as { durationMs?: number }).durationMs,
+		tokens: (progress as { tokens?: number }).tokens,
+	};
+}
+
+export function registerPromptTemplateDelegationBridge<Ctx extends { cwd?: string }>(
+	options: PromptTemplateBridgeOptions<Ctx>,
+): {
+	cancelAll: () => void;
+	dispose: () => void;
+} {
+	const controllers = new Map<string, AbortController>();
+	const pendingCancels = new Set<string>();
+	const subscriptions: Array<() => void> = [];
+
+	const subscribe = (event: string, handler: (data: unknown) => void): void => {
+		const unsubscribe = options.events.on(event, handler);
+		if (typeof unsubscribe === "function") subscriptions.push(unsubscribe);
+	};
+
+	subscribe(PROMPT_TEMPLATE_SUBAGENT_CANCEL_EVENT, (data) => {
+		if (!data || typeof data !== "object") return;
+		const requestId = (data as { requestId?: unknown }).requestId;
+		if (typeof requestId !== "string") return;
+		const controller = controllers.get(requestId);
+		if (controller) {
+			controller.abort();
+			return;
+		}
+		pendingCancels.add(requestId);
+	});
+
+	subscribe(PROMPT_TEMPLATE_SUBAGENT_REQUEST_EVENT, async (data) => {
+		const request = parsePromptTemplateRequest(data);
+		if (!request) return;
+
+		const ctx = options.getContext();
+		if (!ctx) {
+			const response: PromptTemplateDelegationResponse = {
+				...request,
+				messages: [],
+				isError: true,
+				errorText: "No active extension context for delegated subagent execution.",
+			};
+			options.events.emit(PROMPT_TEMPLATE_SUBAGENT_RESPONSE_EVENT, response);
+			return;
+		}
+
+		if (typeof ctx.cwd === "string" && ctx.cwd !== request.cwd) {
+			const response: PromptTemplateDelegationResponse = {
+				...request,
+				messages: [],
+				isError: true,
+				errorText: `Delegated request cwd mismatch: active context is '${ctx.cwd}' but request asked for '${request.cwd}'. Retry from the target session/cwd.`,
+			};
+			options.events.emit(PROMPT_TEMPLATE_SUBAGENT_RESPONSE_EVENT, response);
+			return;
+		}
+
+		const controller = new AbortController();
+		controllers.set(request.requestId, controller);
+
+		if (pendingCancels.delete(request.requestId)) {
+			controller.abort();
+			const response: PromptTemplateDelegationResponse = {
+				...request,
+				messages: [],
+				isError: true,
+				errorText: "Delegated prompt cancelled.",
+			};
+			options.events.emit(PROMPT_TEMPLATE_SUBAGENT_RESPONSE_EVENT, response);
+			controllers.delete(request.requestId);
+			return;
+		}
+
+		options.events.emit(PROMPT_TEMPLATE_SUBAGENT_STARTED_EVENT, { requestId: request.requestId });
+
+		try {
+			const result = await options.execute(
+				request.requestId,
+				request,
+				controller.signal,
+				ctx,
+				(update) => {
+					const payload = toDelegationUpdate(request.requestId, update);
+					if (!payload) return;
+					options.events.emit(PROMPT_TEMPLATE_SUBAGENT_UPDATE_EVENT, payload);
+				},
+			);
+			const messages = result.details?.results?.[0]?.messages ?? [];
+			const response: PromptTemplateDelegationResponse = {
+				...request,
+				messages,
+				isError: result.isError === true,
+				errorText: result.isError ? firstTextContent(result.content) : undefined,
+			};
+			options.events.emit(PROMPT_TEMPLATE_SUBAGENT_RESPONSE_EVENT, response);
+		} catch (error) {
+			const response: PromptTemplateDelegationResponse = {
+				...request,
+				messages: [],
+				isError: true,
+				errorText: error instanceof Error ? error.message : String(error),
+			};
+			options.events.emit(PROMPT_TEMPLATE_SUBAGENT_RESPONSE_EVENT, response);
+		} finally {
+			controllers.delete(request.requestId);
+		}
+	});
+
+	return {
+		cancelAll: () => {
+			for (const controller of controllers.values()) {
+				controller.abort();
+			}
+			controllers.clear();
+			pendingCancels.clear();
+		},
+		dispose: () => {
+			for (const unsubscribe of subscriptions) unsubscribe();
+			subscriptions.length = 0;
+			pendingCancels.clear();
+		},
+	};
+}

package/subagent-executor.ts

@@ -37,6 +37,7 @@ import {
 	MAX_CONCURRENCY,
 	MAX_PARALLEL,
 	checkSubagentDepth,
+	wrapForkTask,
 } from "./types.js";
 
 interface TaskParam {
@@ -223,6 +224,26 @@ function collectChainSessionFiles(
 	return sessionFiles;
 }
 
+function wrapChainTasksForFork(chain: ChainStep[], context: SubagentParamsLike["context"]): ChainStep[] {
+	if (context !== "fork") return chain;
+	return chain.map((step, stepIndex) => {
+		if (isParallelStep(step)) {
+			return {
+				...step,
+				parallel: step.parallel.map((task) => ({
+					...task,
+					task: wrapForkTask(task.task ?? "{previous}"),
+				})),
+			};
+		}
+		const sequential = step as SequentialStep;
+		return {
+			...sequential,
+			task: wrapForkTask(sequential.task ?? (stepIndex === 0 ? "{task}" : "{previous}")),
+		};
+	});
+}
+
 function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentToolResult<Details> | null {
 	const {
 		params,
@@ -252,8 +273,9 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 	if (hasChain && params.chain) {
 		const normalized = normalizeSkillInput(params.skill);
 		const chainSkills = normalized === false ? [] : (normalized ?? []);
+		const chain = wrapChainTasksForFork(params.chain as ChainStep[], params.context);
 		return executeAsyncChain(id, {
-			chain: params.chain as ChainStep[],
+			chain,
 			agents,
 			ctx: asyncCtx,
 			cwd: params.cwd,
@@ -263,7 +285,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			shareEnabled,
 			sessionRoot,
 			chainSkills,
-			sessionFilesByFlatIndex: collectChainSessionFiles(params.chain as ChainStep[], sessionFileForIndex),
+			sessionFilesByFlatIndex: collectChainSessionFiles(chain, sessionFileForIndex),
 		});
 	}
 
@@ -282,7 +304,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 		const skills = normalizedSkills === false ? [] : normalizedSkills;
 		return executeAsyncSingle(id, {
 			agent: params.agent!,
-			task: params.task!,
+			task: params.context === "fork" ? wrapForkTask(params.task!) : params.task!,
 			agentConfig: a,
 			ctx: asyncCtx,
 			cwd: params.cwd,
@@ -317,8 +339,9 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 	} = data;
 	const normalized = normalizeSkillInput(params.skill);
 	const chainSkills = normalized === false ? [] : (normalized ?? []);
+	const chain = wrapChainTasksForFork(params.chain as ChainStep[], params.context);
 	const chainResult = await executeChain({
-		chain: params.chain as ChainStep[],
+		chain,
 		task: params.task,
 		agents,
 		ctx,
@@ -347,8 +370,9 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 		}
 		const id = randomUUID();
 		const asyncCtx = { pi: deps.pi, cwd: ctx.cwd, currentSessionId: deps.state.currentSessionId! };
+		const asyncChain = wrapChainTasksForFork(chainResult.requestedAsync.chain, params.context);
 		return executeAsyncChain(id, {
-			chain: chainResult.requestedAsync.chain,
+			chain: asyncChain,
 			agents,
 			ctx: asyncCtx,
 			cwd: params.cwd,
@@ -358,7 +382,7 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 			shareEnabled,
 			sessionRoot,
 			chainSkills: chainResult.requestedAsync.chainSkills,
-			sessionFilesByFlatIndex: collectChainSessionFiles(chainResult.requestedAsync.chain, sessionFileForIndex),
+			sessionFilesByFlatIndex: collectChainSessionFiles(asyncChain, sessionFileForIndex),
 		});
 	}
 
@@ -463,7 +487,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			const asyncCtx = { pi: deps.pi, cwd: ctx.cwd, currentSessionId: deps.state.currentSessionId! };
 			const parallelTasks = tasks.map((t, i) => ({
 				agent: t.agent,
-				task: taskTexts[i]!,
+				task: params.context === "fork" ? wrapForkTask(taskTexts[i]!) : taskTexts[i]!,
 				cwd: t.cwd,
 				...(modelOverrides[i] ? { model: modelOverrides[i] } : {}),
 				...(skillOverrides[i] !== undefined ? { skill: skillOverrides[i] } : {}),
@@ -487,6 +511,11 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 	const behaviors = agentConfigs.map((c) => resolveStepBehavior(c, {}));
 	const liveResults: (SingleResult | undefined)[] = new Array(tasks.length).fill(undefined);
 	const liveProgress: (AgentProgress | undefined)[] = new Array(tasks.length).fill(undefined);
+	if (params.context === "fork") {
+		for (let i = 0; i < taskTexts.length; i++) {
+			taskTexts[i] = wrapForkTask(taskTexts[i]!);
+		}
+	}
 	const results = await mapConcurrent(tasks, MAX_CONCURRENCY, async (t, i) => {
 		const overrideSkills = skillOverrides[i];
 		const effectiveSkills = overrideSkills === undefined ? behaviors[i]?.skills : overrideSkills;
@@ -641,7 +670,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 			const asyncCtx = { pi: deps.pi, cwd: ctx.cwd, currentSessionId: deps.state.currentSessionId! };
 			return executeAsyncSingle(id, {
 				agent: params.agent!,
-				task,
+				task: params.context === "fork" ? wrapForkTask(task) : task,
 				agentConfig,
 				ctx: asyncCtx,
 				cwd: params.cwd,
@@ -657,6 +686,9 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		}
 	}
 
+	if (params.context === "fork") {
+		task = wrapForkTask(task);
+	}
 	const cleanTask = task;
 	const outputPath = resolveSingleOutputPath(effectiveOutput, ctx.cwd, params.cwd);
 	task = injectSingleOutputInstruction(task, outputPath);

package/types.ts

@@ -267,6 +267,19 @@ export const POLL_INTERVAL_MS = 250;
 export const MAX_WIDGET_JOBS = 4;
 export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
 
+export const DEFAULT_FORK_PREAMBLE =
+	"You are a delegated subagent with access to the parent session's context for reference. " +
+	"Your sole job is to execute the task below. Do not continue or respond to the prior conversation " +
+	"— focus exclusively on completing this task using your tools.";
+
+export function wrapForkTask(task: string, preamble?: string | false): string {
+	if (preamble === false) return task;
+	const effectivePreamble = preamble ?? DEFAULT_FORK_PREAMBLE;
+	const wrappedPrefix = `${effectivePreamble}\n\nTask:\n`;
+	if (task.startsWith(wrappedPrefix)) return task;
+	return `${wrappedPrefix}${task}`;
+}
+
 // ============================================================================
 // Recursion Depth Guard
 // ============================================================================