@narumitw/pi-subagents 1.0.2 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "1.0.2",
+	"version": "2.0.1",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",
@@ -48,7 +48,7 @@
 		"typescript": "7.0.2"
 	},
 	"dependencies": {
-		"@narumitw/pi-tui-kit": "^0.49.1",
+		"@narumitw/pi-tui-kit": "^0.56.0",
 		"proper-lockfile": "^4.1.2"
 	},
 	"repository": {

package/src/agents/built-ins.ts

@@ -7,58 +7,26 @@ import type { AgentConfig } from "./types.js";
 
 export const BUILT_IN_AGENTS: AgentConfig[] = [
 	{
-		name: "scout",
+		name: "explorer",
 		description:
-			"Read-only codebase reconnaissance; returns concise findings with paths and evidence.",
-		tools: ["read", "grep", "find", "ls", "bash"],
+			"Read-only codebase exploration for specific questions; returns concise findings with paths and evidence.",
+		tools: ["read", "grep", "find", "ls"],
 		capabilityManifest: builtInManifest(["repository-search", "code-evidence"], "read", [
 			"evidence-gathering",
 		]),
+		thinkingLevel: "low",
 		source: "built-in",
-		filePath: "built-in:scout",
+		filePath: "built-in:explorer",
 		systemPrompt: [
-			"You are a scout subagent. Explore the codebase quickly and report grounded findings.",
-			"Do not edit files. Prefer read, grep, find, ls, and safe bash inspection commands.",
+			"You are an explorer subagent. Explore the codebase for specific, well-scoped questions and report grounded findings.",
+			"Do not edit files, run shell commands, or use any tool outside the read-only inspection set.",
+			"Do not install dependencies, run formatters, start servers, run tests, or execute long-running commands.",
 			"Return concise bullets with exact file paths, symbols, and open questions.",
 		].join("\n"),
 	},
-	{
-		name: "planner",
-		description: "Turns reconnaissance into a lean implementation or migration plan.",
-		tools: ["read", "grep", "find", "ls"],
-		capabilityManifest: builtInManifest(
-			["task-decomposition", "implementation-planning", "migration-planning"],
-			"read",
-		),
-		source: "built-in",
-		filePath: "built-in:planner",
-		systemPrompt: [
-			"You are a planner subagent. Produce executable, verifiable plans only.",
-			"Do not modify files. Ground the plan in the repository's actual structure.",
-			"Call out assumptions, risks, sequencing, and verification commands.",
-		].join("\n"),
-	},
-	{
-		name: "reviewer",
-		description: "Independent code review agent that inspects existing verification evidence.",
-		tools: ["read", "grep", "find", "ls", "bash"],
-		capabilityManifest: builtInManifest(
-			["code-review", "evidence-review", "security-baseline"],
-			"read",
-			["independent-review"],
-		),
-		source: "built-in",
-		filePath: "built-in:reviewer",
-		systemPrompt: [
-			"You are a reviewer subagent. Review changes adversarially and assess claims against the code and existing evidence.",
-			"Do not edit files or run tests, builds, benchmarks, formatters, or other long-running verification commands.",
-			"Inspect code, diffs, test definitions, and existing verification evidence. Recommend any additional commands for the main agent to run.",
-			"Report PASS, FAIL, or PARTIAL with evidence, commands inspected, and specific follow-ups.",
-		].join("\n"),
-	},
 	{
 		name: "worker",
-		description: "General-purpose implementation worker with the default Pi tool set.",
+		description: "Bounded implementation and command-execution worker with clear ownership.",
 		capabilityManifest: builtInManifest(
 			["implementation", "command-execution", "repository-modification"],
 			"write",
@@ -67,28 +35,6 @@ export const BUILT_IN_AGENTS: AgentConfig[] = [
 		filePath: "built-in:worker",
 		systemPrompt: workerSystemPrompt(),
 	},
-	{
-		name: "general",
-		description: "Alias for worker; kept for model-generated subagent names.",
-		capabilityManifest: builtInManifest(
-			["implementation", "command-execution", "repository-modification"],
-			"write",
-		),
-		source: "built-in",
-		filePath: "built-in:general",
-		systemPrompt: workerSystemPrompt(),
-	},
-	{
-		name: "general-purpose",
-		description: "Alias for worker; compatible with common subagent naming conventions.",
-		capabilityManifest: builtInManifest(
-			["implementation", "command-execution", "repository-modification"],
-			"write",
-		),
-		source: "built-in",
-		filePath: "built-in:general-purpose",
-		systemPrompt: workerSystemPrompt(),
-	},
 ];
 
 export function getBuiltInAgent(name: string): AgentConfig | undefined {
@@ -117,8 +63,9 @@ function builtInManifest(
 
 function workerSystemPrompt(): string {
 	return [
-		"You are a focused worker subagent running in an isolated Pi process.",
-		"Complete the delegated task directly. Keep scope tight and avoid unrelated changes.",
-		"When done, summarize files changed, commands run, and any remaining risks.",
+		"You are a focused worker subagent running in an isolated Pi child context.",
+		"Complete only the bounded delegated implementation slice and respect its assigned file or responsibility ownership.",
+		"Keep scope tight, avoid unrelated changes, and do not overwrite concurrent work outside your ownership.",
+		"The main agent owns integration and final verification; report changed files, commands run, and remaining risks for that handoff.",
 	].join("\n");
 }

package/src/agents/catalog.ts

@@ -8,7 +8,7 @@ import {
 	type AgentDiscoveryResult,
 	discoverAgents,
 } from "./discovery.js";
-import type { AgentConfig, SubagentSettings } from "./types.js";
+import { type AgentConfig, resolveAgentToolNames, type SubagentSettings } from "./types.js";
 
 export function formatAgentList(
 	agents: AgentConfig[],
@@ -70,6 +70,21 @@ function normalizeCatalogDescription(description: string, maxLength: number): st
 
 type CatalogScope = "user" | "project" | "project-fallback";
 
+function formatDeclaredItems(items: readonly string[] | undefined): string {
+	if (items === undefined) return "undeclared";
+	return items.length > 0 ? items.join(", ") : "none";
+}
+
+function catalogAgentContractMetadata(agent: AgentConfig): string {
+	const manifest = agent.capabilityManifest;
+	return [
+		`capabilities: ${formatDeclaredItems(manifest?.capabilities)}`,
+		`tools: ${formatDeclaredItems(resolveAgentToolNames(agent.tools))}`,
+		`filesystem: ${manifest?.authority?.filesystem ?? "undeclared"}`,
+		`result formats: ${formatDeclaredItems(manifest?.resultFormats)}`,
+	].join("; ");
+}
+
 function catalogAgentLine(
 	agent: AgentConfig,
 	scope: CatalogScope,
@@ -88,7 +103,7 @@ function catalogAgentLine(
 				? "; overrides the default user definition for project/both"
 				: "; scope-specific fallback for the default user override"
 			: "";
-	return `- ${agent.name} [source: ${agent.source}; ${scopeLabel}${collision}] — ${normalizeCatalogDescription(agent.description, maxDescriptionLength)}`;
+	return `- ${agent.name} [source: ${agent.source}; ${scopeLabel}${collision}] [${catalogAgentContractMetadata(agent)}] — ${normalizeCatalogDescription(agent.description, maxDescriptionLength)}`;
 }
 
 /**
@@ -153,6 +168,8 @@ export function formatAgentCatalog(
 	const render = (entries: typeof allEntries, omitted: number): string => {
 		const lines = [
 			"Available agent definitions (metadata only; runtime validation and trust remain authoritative).",
+			"Use capability and tool identifiers exactly as shown when authoring enforced contracts.",
+			"Enforced contract readPaths, writePaths, network, and secrets guarantees are unsupported.",
 		];
 		const userLines = entries
 			.filter((entry) => entry.scope === "user")

package/src/agents/discovery.ts

@@ -179,6 +179,24 @@ function hasOwn(obj: object, key: PropertyKey): boolean {
 	return Object.hasOwn(obj, key);
 }
 
+function applyAgentOverride(
+	agent: AgentConfig,
+	override: NonNullable<SubagentSettings["agents"]>[string],
+): AgentConfig {
+	const nextAgent: AgentConfig = { ...agent };
+	if (hasOwn(override, "tools")) nextAgent.tools = override.tools;
+	if (hasOwn(override, "model")) {
+		nextAgent.model = override.model === null ? undefined : override.model;
+	}
+	if (hasOwn(override, "thinkingLevel")) {
+		nextAgent.thinkingLevel = override.thinkingLevel === null ? undefined : override.thinkingLevel;
+	}
+	if (hasOwn(override, "timeoutMs")) {
+		nextAgent.timeoutMs = override.timeoutMs === null ? undefined : override.timeoutMs;
+	}
+	return nextAgent;
+}
+
 export function discoverAgents(
 	cwd: string,
 	scope: AgentScope,
@@ -217,23 +235,21 @@ export function discoverAgents(
 
 	// Apply user-configured overrides (from /subagents → Agent tool settings) on top of
 	// the final resolved agent map, regardless of agent source.
-	for (const [name, override] of Object.entries(config?.agents ?? {})) {
+	const configuredAgents = config?.agents ?? {};
+	for (const [name, override] of Object.entries(configuredAgents)) {
 		const agent = agentMap.get(name);
 		if (!agent) continue;
-
-		const nextAgent: AgentConfig = { ...agent };
-		if (hasOwn(override, "tools")) nextAgent.tools = override.tools;
-		if (hasOwn(override, "model")) {
-			nextAgent.model = override.model === null ? undefined : override.model;
-		}
-		if (hasOwn(override, "thinkingLevel")) {
-			nextAgent.thinkingLevel =
-				override.thinkingLevel === null ? undefined : override.thinkingLevel;
-		}
-		if (hasOwn(override, "timeoutMs")) {
-			nextAgent.timeoutMs = override.timeoutMs === null ? undefined : override.timeoutMs;
-		}
-		agentMap.set(name, nextAgent);
+		agentMap.set(name, applyAgentOverride(agent, override));
+	}
+	const legacyScoutOverride = configuredAgents.scout;
+	const explorerAgent = agentMap.get("explorer");
+	if (
+		legacyScoutOverride &&
+		explorerAgent &&
+		!hasOwn(configuredAgents, "explorer") &&
+		!agentMap.has("scout")
+	) {
+		agentMap.set("explorer", applyAgentOverride(explorerAgent, legacyScoutOverride));
 	}
 
 	const omittedAgentDefinitions =

package/src/auto-transport.ts

@@ -1,6 +1,6 @@
 import { discoverAgents } from "./agents/discovery.js";
 import type { SubagentSettings } from "./agents/types.js";
-import type { ManagedAgent, TurnOutcome } from "./registry.js";
+import type { AgentMailboxMessage, ManagedAgent, TurnOutcome } from "./registry.js";
 import { isWriteCapable } from "./stateful-safety.js";
 import type { SubagentTransport } from "./transport.js";
 import type {
@@ -48,6 +48,12 @@ export class AutoTransport implements SubagentTransport {
 		};
 	}
 
+	async deliverMessage(agent: ManagedAgent, message: AgentMailboxMessage): Promise<boolean> {
+		const selection = this.selections.get(agent.id);
+		if (!selection) return false;
+		return this.transport(selection.kind).deliverMessage?.(agent, message) ?? false;
+	}
+
 	async release(agent: ManagedAgent): Promise<void> {
 		const selection = this.selections.get(agent.id);
 		this.selections.delete(agent.id);

package/src/child-peer-bridge.ts

@@ -0,0 +1,124 @@
+import net from "node:net";
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { type ChildPeerClient, createChildPeerExtension } from "./child-peer-tools.js";
+import type { AgentMailboxMessage } from "./registry.js";
+
+const MAX_RESPONSE_BYTES = 64 * 1024;
+const REQUEST_TIMEOUT_MS = 2_000;
+
+const captured = captureBridgeEnvironment();
+
+const childPeerBridge: ExtensionFactory = captured
+	? createChildPeerExtension(createProcessPeerClient(captured))
+	: () => undefined;
+
+export default childPeerBridge;
+
+interface CapturedBridgeEnvironment {
+	host: "127.0.0.1";
+	port: number;
+	token: string;
+}
+
+export function captureBridgeEnvironment(): CapturedBridgeEnvironment | undefined {
+	const host = process.env.PI_SUBAGENT_PEER_HOST;
+	const rawPort = process.env.PI_SUBAGENT_PEER_PORT;
+	const token = process.env.PI_SUBAGENT_PEER_TOKEN;
+	delete process.env.PI_SUBAGENT_PEER_HOST;
+	delete process.env.PI_SUBAGENT_PEER_PORT;
+	delete process.env.PI_SUBAGENT_PEER_TOKEN;
+	if (!host && !rawPort && !token) return undefined;
+	const port = Number(rawPort);
+	if (host !== "127.0.0.1" || !Number.isSafeInteger(port) || port < 1 || port > 65_535 || !token) {
+		throw new Error("Invalid pi-subagents peer bridge environment");
+	}
+	return { host, port, token };
+}
+
+function createProcessPeerClient(environment: CapturedBridgeEnvironment): ChildPeerClient {
+	const request = async (input: Record<string, unknown>): Promise<Record<string, unknown>> => {
+		const response = await requestBridge(environment, { ...input, token: environment.token });
+		if (response.ok !== true) {
+			throw new Error(
+				typeof response.error === "string"
+					? response.error
+					: "Subagent peer bridge rejected the request",
+			);
+		}
+		return response;
+	};
+	return {
+		async send(target, message, deduplicationKey) {
+			const response = await request({
+				action: "send",
+				target,
+				message,
+				...(deduplicationKey ? { deduplicationKey } : {}),
+			});
+			if (!isMailboxMessage(response.message)) {
+				throw new Error("Subagent peer bridge returned an invalid message receipt");
+			}
+			return response.message;
+		},
+		async list() {
+			return (await request({ action: "list" })).peers ?? [];
+		},
+		async acknowledge(messageIds, completionIds) {
+			await request({ action: "acknowledge", messageIds, completionIds });
+		},
+	};
+}
+
+function requestBridge(
+	environment: CapturedBridgeEnvironment,
+	request: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+	return new Promise((resolve, reject) => {
+		const socket = net.createConnection({ host: environment.host, port: environment.port });
+		let response = Buffer.alloc(0);
+		let settled = false;
+		const finish = (error?: Error, value?: Record<string, unknown>) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			socket.destroy();
+			if (error) reject(error);
+			else resolve(value ?? {});
+		};
+		const timer = setTimeout(
+			() => finish(new Error("Subagent peer bridge request timed out")),
+			REQUEST_TIMEOUT_MS,
+		);
+		timer.unref();
+		socket.once("connect", () => socket.end(`${JSON.stringify(request)}\n`));
+		socket.on("data", (chunk: Buffer) => {
+			response = Buffer.concat([response, chunk]);
+			if (response.byteLength > MAX_RESPONSE_BYTES) {
+				finish(new Error("Subagent peer bridge response exceeded its size limit"));
+			}
+		});
+		socket.once("error", (error) => finish(error));
+		socket.once("close", () => {
+			if (settled) return;
+			try {
+				const parsed = JSON.parse(response.toString("utf8")) as unknown;
+				if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
+				finish(undefined, parsed as Record<string, unknown>);
+			} catch {
+				finish(new Error("Subagent peer bridge returned malformed JSON"));
+			}
+		});
+	});
+}
+
+function isMailboxMessage(value: unknown): value is AgentMailboxMessage {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const message = value as Record<string, unknown>;
+	return (
+		typeof message.id === "string" &&
+		typeof message.senderId === "string" &&
+		typeof message.recipientId === "string" &&
+		typeof message.content === "string" &&
+		typeof message.createdAt === "number"
+	);
+}

package/src/child-peer-tools.ts

@@ -0,0 +1,132 @@
+import { defineTool, type ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { redactPrivateText } from "./context.js";
+import { MAX_TOOL_MESSAGE_BYTES, truncateUtf8 } from "./limits.js";
+import type { AgentMailboxMessage } from "./registry.js";
+
+const MAX_PEER_MESSAGE_BYTES = 16 * 1024;
+const MAX_DEDUPLICATION_KEY_LENGTH = 256;
+const PEER_ENVELOPE_HEADER =
+	/^Message Type: SUBAGENT_(?:COMPLETION|PEER_MESSAGE)\nProtocol: pi-subagents:v1\nMessage ID: (msg_[^\s]+)\n(?:Completion ID: (completion:[^\s]+)\n)?Sender ID: [^\n]+\n(?:Sender Path: [^\n]+\n)?Payload:\n/u;
+
+export interface ChildPeerClient {
+	send(target: string, message: string, deduplicationKey?: string): Promise<AgentMailboxMessage>;
+	list(): Promise<unknown>;
+	acknowledge(messageIds: readonly string[], completionIds: readonly string[]): Promise<void>;
+}
+
+export function createChildPeerExtension(client: ChildPeerClient): ExtensionFactory {
+	return (pi) => {
+		pi.registerTool(
+			defineTool({
+				name: "subagent_peer_send",
+				label: "Send Peer Message",
+				description:
+					"Send a bounded queue-only message to /root or another retained agent by canonical task path. The runtime binds your sender identity; this tool never starts an idle turn.",
+				promptSnippet: "Send a queue-only message to another retained agent",
+				parameters: Type.Object(
+					{
+						target: Type.String({ minLength: 1, maxLength: 2_048 }),
+						message: Type.String({ minLength: 1, maxLength: MAX_PEER_MESSAGE_BYTES }),
+						deduplicationKey: Type.Optional(
+							Type.String({ minLength: 1, maxLength: MAX_DEDUPLICATION_KEY_LENGTH }),
+						),
+					},
+					{ additionalProperties: false },
+				),
+				async execute(_id, params) {
+					const message = await client.send(params.target, params.message, params.deduplicationKey);
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: `Queued ${message.id} for ${message.recipientId}; delivery does not start an idle turn.`,
+							},
+						],
+						details: {
+							messageId: message.id,
+							recipientId: message.recipientId,
+							createdAt: message.createdAt,
+						},
+					};
+				},
+			}),
+		);
+		pi.registerTool(
+			defineTool({
+				name: "subagent_peer_list",
+				label: "List Peers",
+				description:
+					"List bounded identity and lifecycle metadata for /root and retained agents in this session.",
+				promptSnippet: "List retained peer task paths",
+				parameters: Type.Object({}, { additionalProperties: false }),
+				async execute() {
+					const peers = await client.list();
+					const text = truncateUtf8(JSON.stringify(peers, null, 2), MAX_TOOL_MESSAGE_BYTES).text;
+					return { content: [{ type: "text" as const, text }], details: { peers } };
+				},
+			}),
+		);
+
+		const acknowledgedMessageIds = new Set<string>();
+		const acknowledgedCompletionIds = new Set<string>();
+		pi.on("context", async (event) => {
+			const visible = visibleDeliveryIds(event.messages);
+			const messageIds = [...visible.messageIds].filter((id) => !acknowledgedMessageIds.has(id));
+			const completionIds = [...visible.completionIds].filter(
+				(id) => !acknowledgedCompletionIds.has(id),
+			);
+			if (messageIds.length === 0 && completionIds.length === 0) return;
+			await client.acknowledge(messageIds, completionIds);
+			for (const id of messageIds) acknowledgedMessageIds.add(id);
+			for (const id of completionIds) acknowledgedCompletionIds.add(id);
+		});
+	};
+}
+
+export function formatPeerMessage(message: AgentMailboxMessage, senderPath?: string): string {
+	return truncateUtf8(
+		[
+			`Message Type: ${message.completionId ? "SUBAGENT_COMPLETION" : "SUBAGENT_PEER_MESSAGE"}`,
+			"Protocol: pi-subagents:v1",
+			`Message ID: ${message.id}`,
+			...(message.completionId ? [`Completion ID: ${message.completionId}`] : []),
+			`Sender ID: ${message.senderId}`,
+			...(senderPath ? [`Sender Path: ${senderPath}`] : []),
+			"Payload:",
+			redactPrivateText(message.content),
+		].join("\n"),
+		MAX_TOOL_MESSAGE_BYTES,
+	).text;
+}
+
+export function visibleDeliveryIds(messages: readonly unknown[]): {
+	messageIds: Set<string>;
+	completionIds: Set<string>;
+} {
+	const messageIds = new Set<string>();
+	const completionIds = new Set<string>();
+	for (const message of messages) {
+		for (const text of messageText(message)) {
+			const match = PEER_ENVELOPE_HEADER.exec(text);
+			if (!match) continue;
+			messageIds.add(match[1]);
+			if (match[2]) completionIds.add(match[2]);
+		}
+	}
+	return { messageIds, completionIds };
+}
+
+function messageText(message: unknown): string[] {
+	if (!message || typeof message !== "object" || Array.isArray(message)) return [];
+	const candidate = message as Record<string, unknown>;
+	if (candidate.role !== "user") return [];
+	const content = candidate.content;
+	if (typeof content === "string") return [content];
+	if (!Array.isArray(content)) return [];
+	return content.flatMap((part) => {
+		if (!part || typeof part !== "object" || Array.isArray(part)) return [];
+		const text = (part as Record<string, unknown>).text;
+		return typeof text === "string" ? [text] : [];
+	});
+}

package/src/completion-delivery.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { CompletionDelivery } from "./agents/types.js";
+import { SUBAGENT_COMPLETION_MESSAGE_TYPE } from "./completion-render.js";
 import { redactPrivateText } from "./context.js";
 import { DEFAULT_MAX_CONTEXT_BYTES, MAX_TOOL_MESSAGE_BYTES, truncateUtf8 } from "./limits.js";
 import type { AgentTurnCompletion, ManagedAgent } from "./registry.js";
@@ -16,7 +17,10 @@ interface CompletionMetadata {
 	runId: string;
 	generation: number;
 	agentId: string;
+	taskPath?: string;
+	recipientPath?: string;
 	agent: string;
+	task: string;
 	state: string;
 	transport?: string;
 	structuredResult?: ManagedAgent["structuredResult"];
@@ -25,7 +29,7 @@ interface CompletionMetadata {
 }
 
 interface CompletionMessage {
-	customType: "pi-subagent-completion";
+	customType: typeof SUBAGENT_COMPLETION_MESSAGE_TYPE;
 	content: string;
 	display: true;
 	details:
@@ -107,7 +111,11 @@ export class CompletionDeliveryBroker {
 			if (triggerTurn) this.wakeInFlight = true;
 			this.awaitingParentAck.push(...batch);
 			try {
-				this.pi.sendMessage(message, { deliverAs: "steer", triggerTurn });
+				// Pi treats explicit false as immediate insertion instead of queued steering while streaming.
+				this.pi.sendMessage(message, {
+					deliverAs: "steer",
+					...(triggerTurn ? { triggerTurn: true } : {}),
+				});
 			} catch (primaryError) {
 				this.removeAwaiting(batch);
 				if (triggerTurn) this.wakeInFlight = false;
@@ -202,7 +210,8 @@ function completionIdsFromContext(messages: readonly unknown[]): Set<string> {
 	for (const message of messages) {
 		if (!message || typeof message !== "object" || Array.isArray(message)) continue;
 		const record = message as Record<string, unknown>;
-		if (record.role !== "custom" || record.customType !== "pi-subagent-completion") continue;
+		if (record.role !== "custom" || record.customType !== SUBAGENT_COMPLETION_MESSAGE_TYPE)
+			continue;
 		const details = record.details;
 		if (!details || typeof details !== "object" || Array.isArray(details)) continue;
 		const metadata = details as Record<string, unknown>;
@@ -236,7 +245,7 @@ function buildCompletionMessage(completions: AgentTurnCompletion[]): CompletionM
 	if (completions.length === 1) {
 		const completion = completions[0];
 		return {
-			customType: "pi-subagent-completion",
+			customType: SUBAGENT_COMPLETION_MESSAGE_TYPE,
 			content: buildDetachedCompletionMessage(completion),
 			display: true,
 			details: completionMetadata(completion),
@@ -256,7 +265,7 @@ function buildCompletionMessage(completions: AgentTurnCompletion[]): CompletionM
 		DEFAULT_MAX_CONTEXT_BYTES,
 	).text;
 	return {
-		customType: "pi-subagent-completion",
+		customType: SUBAGENT_COMPLETION_MESSAGE_TYPE,
 		content,
 		display: true,
 		details: {
@@ -273,7 +282,10 @@ function completionMetadata(completion: AgentTurnCompletion): CompletionMetadata
 		runId: completion.runId,
 		generation: completion.generation,
 		agentId: completion.agent.id,
+		...(completion.agent.taskPath ? { taskPath: completion.agent.taskPath } : {}),
+		...(completion.recipientPath ? { recipientPath: completion.recipientPath } : {}),
 		agent: completion.agent.agent,
+		task: sanitizeCompletionLine(completion.task, 256) || "(unknown task)",
 		state: completion.agent.state,
 		...(completion.agent.telemetry?.transport
 			? { transport: completion.agent.telemetry.transport }
@@ -306,6 +318,8 @@ export function buildDetachedCompletionMessage(completion: AgentTurnCompletion):
 			`Run ID: ${completion.runId}`,
 			`Generation: ${completion.generation}`,
 			`Agent ID: ${completion.agent.id}`,
+			...(completion.agent.taskPath ? [`Agent Path: ${completion.agent.taskPath}`] : []),
+			...(completion.recipientPath ? [`Recipient Path: ${completion.recipientPath}`] : []),
 			`Agent: ${agentName}`,
 			`Task: ${task}`,
 			`State: ${completion.agent.state}`,