@pi-agents/orchid 0.1.0-beta.0

package/src/subagents/runs/shared/single-output.ts

@@ -0,0 +1,164 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { OutputMode, SavedOutputReference } from "../../shared/types.ts";
+
+export interface SingleOutputSnapshot {
+	exists: boolean;
+	mtimeMs?: number;
+	size?: number;
+}
+
+export function normalizeSingleOutputOverride(
+	output: string | boolean | undefined,
+	defaultOutput: string | undefined,
+): string | false | undefined {
+	if (output === false || output === "false") return false;
+	if (output === true || output === "true") return defaultOutput;
+	if (typeof output === "string" && output.length > 0) return output;
+	return undefined;
+}
+
+export function resolveSingleOutputPath(
+	output: string | boolean | undefined,
+	runtimeCwd: string,
+	requestedCwd?: string,
+): string | undefined {
+	if (typeof output !== "string" || !output || output === "false" || output === "true") return undefined;
+	if (path.isAbsolute(output)) return output;
+	const baseCwd = requestedCwd
+		? (path.isAbsolute(requestedCwd) ? requestedCwd : path.resolve(runtimeCwd, requestedCwd))
+		: runtimeCwd;
+	return path.resolve(baseCwd, output);
+}
+
+export function injectSingleOutputInstruction(task: string, outputPath: string | undefined): string {
+	if (!outputPath) return task;
+	return `${task}\n\n---\n**Output:** Write your findings to: ${outputPath}`;
+}
+
+function countLines(text: string): number {
+	if (!text) return 0;
+	const newlineMatches = text.match(/\r\n|\r|\n/g);
+	return (newlineMatches?.length ?? 0) + (/[\r\n]$/.test(text) ? 0 : 1);
+}
+
+function formatByteSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	const units = ["KB", "MB", "GB", "TB"];
+	let value = bytes / 1024;
+	let unitIndex = 0;
+	while (value >= 1024 && unitIndex < units.length - 1) {
+		value /= 1024;
+		unitIndex++;
+	}
+	return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+
+export function formatSavedOutputReference(savedPath: string, fullOutput: string): SavedOutputReference {
+	const absolutePath = path.resolve(savedPath);
+	const bytes = Buffer.byteLength(fullOutput, "utf-8");
+	const lines = countLines(fullOutput);
+	return {
+		path: absolutePath,
+		bytes,
+		lines,
+		message: `Output saved to: ${absolutePath} (${formatByteSize(bytes)}, ${lines} ${lines === 1 ? "line" : "lines"}). Read this file if needed.`,
+	};
+}
+
+export function validateFileOnlyOutputMode(outputMode: OutputMode | undefined, outputPath: string | undefined, context: string): string | undefined {
+	if (outputMode === "file-only" && !outputPath) {
+		return `${context} sets outputMode: "file-only" but does not configure an output file. Set output to a path or use outputMode: "inline".`;
+	}
+	return undefined;
+}
+
+export function captureSingleOutputSnapshot(outputPath: string | undefined): SingleOutputSnapshot | undefined {
+	if (!outputPath) return undefined;
+	try {
+		const stat = fs.statSync(outputPath);
+		return { exists: true, mtimeMs: stat.mtimeMs, size: stat.size };
+	} catch {
+		// The snapshot is advisory; resolveSingleOutput reports concrete read/write failures.
+		return { exists: false };
+	}
+}
+
+function persistSingleOutput(
+	outputPath: string | undefined,
+	fullOutput: string,
+): { savedPath?: string; error?: string } {
+	if (!outputPath) return {};
+	try {
+		fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+		fs.writeFileSync(outputPath, fullOutput, "utf-8");
+		return { savedPath: outputPath };
+	} catch (err) {
+		return { error: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+export function resolveSingleOutput(
+	outputPath: string | undefined,
+	fallbackOutput: string,
+	beforeRun: SingleOutputSnapshot | undefined,
+): { fullOutput: string; savedPath?: string; saveError?: string } {
+	if (!outputPath) return { fullOutput: fallbackOutput };
+
+	let changedSinceStart = false;
+	try {
+		const stat = fs.statSync(outputPath);
+		changedSinceStart = !beforeRun?.exists
+			|| stat.mtimeMs !== beforeRun.mtimeMs
+			|| stat.size !== beforeRun.size;
+	} catch (error) {
+		const code = error && typeof error === "object" && "code" in error ? (error as { code?: unknown }).code : undefined;
+		if (code !== "ENOENT" && code !== "ENOTDIR") {
+			return {
+				fullOutput: fallbackOutput,
+				saveError: `Failed to inspect output file: ${error instanceof Error ? error.message : String(error)}`,
+			};
+		}
+	}
+
+	if (changedSinceStart) {
+		try {
+			return { fullOutput: fs.readFileSync(outputPath, "utf-8"), savedPath: outputPath };
+		} catch (error) {
+			return {
+				fullOutput: fallbackOutput,
+				saveError: `Failed to read changed output file: ${error instanceof Error ? error.message : String(error)}`,
+			};
+		}
+	}
+
+	const save = persistSingleOutput(outputPath, fallbackOutput);
+	if (save.savedPath) return { fullOutput: fallbackOutput, savedPath: save.savedPath };
+	return { fullOutput: fallbackOutput, saveError: save.error };
+}
+
+export function finalizeSingleOutput(params: {
+	fullOutput: string;
+	truncatedOutput?: string;
+	outputPath?: string;
+	outputMode?: OutputMode;
+	exitCode: number;
+	savedPath?: string;
+	outputReference?: SavedOutputReference;
+	saveError?: string;
+}): { displayOutput: string; savedPath?: string; outputReference?: SavedOutputReference; saveError?: string } {
+	let displayOutput = params.truncatedOutput || params.fullOutput;
+	if (params.exitCode === 0 && params.savedPath) {
+		const outputReference = params.outputReference ?? formatSavedOutputReference(params.savedPath, params.fullOutput);
+		if (params.outputMode === "file-only") {
+			return { displayOutput: outputReference.message, savedPath: params.savedPath, outputReference };
+		}
+		displayOutput += `\n\n${outputReference.message}`;
+		return { displayOutput, savedPath: params.savedPath, outputReference };
+	}
+	if (params.exitCode === 0 && params.saveError && params.outputPath) {
+		displayOutput += `\n\nOutput file error: ${params.outputPath}\n${params.saveError}`;
+		return { displayOutput, saveError: params.saveError };
+	}
+	return { displayOutput };
+}

package/src/subagents/runs/shared/subagent-control.ts

@@ -0,0 +1,226 @@
+import {
+	type ActivityState,
+	type ControlConfig,
+	type ControlEvent,
+	type ControlEventType,
+	type ControlNotificationChannel,
+	type ResolvedControlConfig,
+} from "../../shared/types.ts";
+
+const CONTROL_EVENT_TYPES: ControlEventType[] = ["active_long_running", "needs_attention"];
+const CONTROL_NOTIFICATION_CHANNELS: ControlNotificationChannel[] = ["event", "async", "intercom"];
+const DEFAULT_NOTIFY_ON: ControlEventType[] = ["active_long_running", "needs_attention"];
+
+export const DEFAULT_CONTROL_CONFIG: ResolvedControlConfig = {
+	enabled: true,
+	needsAttentionAfterMs: 60_000,
+	activeNoticeAfterMs: 240_000,
+	failedToolAttemptsBeforeAttention: 3,
+	notifyOn: DEFAULT_NOTIFY_ON,
+	notifyChannels: CONTROL_NOTIFICATION_CHANNELS,
+};
+
+function parsePositiveInt(value: unknown): number | undefined {
+	if (typeof value !== "number") return undefined;
+	if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) return undefined;
+	return value;
+}
+
+function parseControlList<T extends string>(value: unknown, allowed: readonly T[]): T[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	if (value.length === 0) return [];
+	const allowedSet = new Set(allowed);
+	const parsed = value.filter((entry): entry is T => typeof entry === "string" && allowedSet.has(entry as T));
+	return parsed.length > 0 ? Array.from(new Set(parsed)) : undefined;
+}
+
+export function resolveControlConfig(
+	globalConfig?: ControlConfig,
+	override?: ControlConfig,
+): ResolvedControlConfig {
+	const enabled = override?.enabled ?? globalConfig?.enabled ?? DEFAULT_CONTROL_CONFIG.enabled;
+	const needsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs)
+		?? parsePositiveInt(globalConfig?.needsAttentionAfterMs)
+		?? DEFAULT_CONTROL_CONFIG.needsAttentionAfterMs;
+	const activeNoticeAfterMs = parsePositiveInt(override?.activeNoticeAfterMs)
+		?? parsePositiveInt(globalConfig?.activeNoticeAfterMs)
+		?? DEFAULT_CONTROL_CONFIG.activeNoticeAfterMs;
+	const activeNoticeAfterTurns = parsePositiveInt(override?.activeNoticeAfterTurns)
+		?? parsePositiveInt(globalConfig?.activeNoticeAfterTurns);
+	const activeNoticeAfterTokens = parsePositiveInt(override?.activeNoticeAfterTokens)
+		?? parsePositiveInt(globalConfig?.activeNoticeAfterTokens);
+	const failedToolAttemptsBeforeAttention = parsePositiveInt(override?.failedToolAttemptsBeforeAttention)
+		?? parsePositiveInt(globalConfig?.failedToolAttemptsBeforeAttention)
+		?? DEFAULT_CONTROL_CONFIG.failedToolAttemptsBeforeAttention;
+	const notifyOn = parseControlList(override?.notifyOn, CONTROL_EVENT_TYPES)
+		?? parseControlList(globalConfig?.notifyOn, CONTROL_EVENT_TYPES)
+		?? DEFAULT_CONTROL_CONFIG.notifyOn;
+	const notifyChannels = parseControlList(override?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
+		?? parseControlList(globalConfig?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
+		?? DEFAULT_CONTROL_CONFIG.notifyChannels;
+	return {
+		enabled,
+		needsAttentionAfterMs,
+		activeNoticeAfterMs,
+		activeNoticeAfterTurns,
+		activeNoticeAfterTokens,
+		failedToolAttemptsBeforeAttention,
+		notifyOn: [...notifyOn],
+		notifyChannels: [...notifyChannels],
+	};
+}
+
+export function deriveActivityState(input: {
+	config: ResolvedControlConfig;
+	startedAt: number;
+	lastActivityAt?: number;
+	now?: number;
+}): ActivityState | undefined {
+	if (!input.config.enabled) return undefined;
+	const now = input.now ?? Date.now();
+	const lastActivity = input.lastActivityAt ?? input.startedAt;
+	const ageMs = Math.max(0, now - lastActivity);
+	return ageMs > input.config.needsAttentionAfterMs ? "needs_attention" : undefined;
+}
+
+export function buildControlEvent(input: {
+	type?: ControlEventType;
+	from?: ActivityState;
+	to: ActivityState;
+	runId: string;
+	agent: string;
+	index?: number;
+	ts?: number;
+	lastActivityAt?: number;
+	message?: string;
+	reason?: ControlEvent["reason"];
+	turns?: number;
+	tokens?: number;
+	toolCount?: number;
+	currentTool?: string;
+	currentToolDurationMs?: number;
+	currentPath?: string;
+	elapsedMs?: number;
+	recentFailureSummary?: string;
+}): ControlEvent {
+	const ts = input.ts ?? Date.now();
+	const type = input.type ?? (input.to === "active_long_running" ? "active_long_running" : "needs_attention");
+	const elapsedMs = input.elapsedMs ?? (input.lastActivityAt ? Math.max(0, ts - input.lastActivityAt) : undefined);
+	const elapsedSeconds = elapsedMs !== undefined ? Math.floor(elapsedMs / 1000) : undefined;
+	const message = input.message ?? (type === "active_long_running"
+		? `${input.agent} is still active but long-running`
+		: elapsedSeconds !== undefined
+			? `${input.agent} needs attention (no observed activity for ${elapsedSeconds}s)`
+			: `${input.agent} needs attention`);
+	return {
+		type,
+		...(input.from ? { from: input.from } : {}),
+		to: input.to,
+		ts,
+		runId: input.runId,
+		agent: input.agent,
+		...(input.index !== undefined ? { index: input.index } : {}),
+		message,
+		reason: input.reason ?? (type === "active_long_running" ? "active_long_running" : "idle"),
+		...(input.turns !== undefined ? { turns: input.turns } : {}),
+		...(input.tokens !== undefined ? { tokens: input.tokens } : {}),
+		...(input.toolCount !== undefined ? { toolCount: input.toolCount } : {}),
+		...(input.currentTool ? { currentTool: input.currentTool } : {}),
+		...(input.currentToolDurationMs !== undefined ? { currentToolDurationMs: input.currentToolDurationMs } : {}),
+		...(input.currentPath ? { currentPath: input.currentPath } : {}),
+		...(elapsedMs !== undefined ? { elapsedMs } : {}),
+		...(input.recentFailureSummary ? { recentFailureSummary: input.recentFailureSummary } : {}),
+	};
+}
+
+export function shouldNotifyControlEvent(config: ResolvedControlConfig, event: ControlEvent): boolean {
+	return config.enabled && config.notifyOn.includes(event.type);
+}
+
+export function controlNotificationKey(event: ControlEvent, childIntercomTarget?: string): string {
+	const childKey = childIntercomTarget ?? (event.index !== undefined ? `${event.runId}:${event.index}` : event.runId);
+	return `${childKey}:${event.type}:${event.reason ?? "idle"}`;
+}
+
+export function claimControlNotification(config: ResolvedControlConfig, event: ControlEvent, seenKeys: Set<string>, childIntercomTarget?: string): boolean {
+	if (!shouldNotifyControlEvent(config, event)) return false;
+	const key = controlNotificationKey(event, childIntercomTarget);
+	if (seenKeys.has(key)) return false;
+	seenKeys.add(key);
+	return true;
+}
+
+function formatLongRunningFacts(event: ControlEvent): string | undefined {
+	const facts: string[] = [];
+	if (event.elapsedMs !== undefined) facts.push(`elapsed ${Math.floor(Math.max(0, event.elapsedMs) / 1000)}s`);
+	if (event.turns !== undefined) facts.push(`${event.turns} turns`);
+	if (event.tokens !== undefined) facts.push(`${event.tokens} tokens`);
+	if (event.toolCount !== undefined) facts.push(`${event.toolCount} tools`);
+	if (event.currentTool) facts.push(`tool ${event.currentTool}${event.currentToolDurationMs !== undefined ? ` ${Math.floor(Math.max(0, event.currentToolDurationMs) / 1000)}s` : ""}`);
+	if (event.currentPath) facts.push(`path ${event.currentPath}`);
+	return facts.length > 0 ? facts.join(" | ") : undefined;
+}
+
+export function formatControlNoticeMessage(event: ControlEvent, childIntercomTarget?: string): string {
+	const runTarget = event.runId;
+	if (event.reason === "completion_guard") {
+		return [
+			`Subagent failed: ${event.agent}`,
+			`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+			`Signal: ${event.message}`,
+			"Next: read the output artifact or session from the subagent result, then retry with a more explicit implementation prompt or handle the fix directly.",
+			childIntercomTarget ? `Run intercom target (may be inactive): ${childIntercomTarget}` : undefined,
+		].filter((line): line is string => Boolean(line)).join("\n");
+	}
+
+	const nudgeCommand = childIntercomTarget
+		? `intercom({ action: "send", to: "${childIntercomTarget}", message: "What are you blocked on? Reply with the smallest next step or ask for a decision." })`
+		: undefined;
+	if (event.type === "active_long_running") {
+		const facts = formatLongRunningFacts(event);
+		return [
+			`Subagent active but long-running: ${event.agent}`,
+			`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+			`Signal: ${event.message}`,
+			facts ? `Facts: ${facts}` : undefined,
+			"Hint: Inspect status, then nudge if the work seems stuck.",
+			childIntercomTarget
+				? `Nudge: ${nudgeCommand}`
+				: "Nudge: no child message route registered",
+			`Status: subagent({ action: "status", id: "${runTarget}" })`,
+			`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
+		].filter((line): line is string => Boolean(line)).join("\n");
+	}
+
+	return [
+		`Subagent needs attention: ${event.agent}`,
+		`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+		`Signal: ${event.message}`,
+		event.recentFailureSummary ? `Recent failures: ${event.recentFailureSummary}` : undefined,
+		"Hint: Inspect status first unless the run is clearly blocked.",
+		childIntercomTarget
+			? `Nudge: ${nudgeCommand}`
+			: "Nudge: no child message route registered",
+		`Status: subagent({ action: "status", id: "${runTarget}" })`,
+		`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
+	].filter((line): line is string => Boolean(line)).join("\n");
+}
+
+export function formatControlIntercomMessage(event: ControlEvent, childIntercomTarget?: string): string {
+	const statusLabel = event.reason === "completion_guard"
+		? "subagent failed"
+		: event.type === "active_long_running"
+			? "subagent active but long-running"
+			: "subagent needs attention";
+	return [
+		statusLabel,
+		"",
+		event.reason === "completion_guard"
+			? `${event.agent} failed in run ${event.runId}.`
+			: event.type === "active_long_running"
+				? `${event.agent} is still active but long-running in run ${event.runId}.`
+				: `${event.agent} needs attention in run ${event.runId}.`,
+		"",
+		formatControlNoticeMessage(event, childIntercomTarget),
+	].join("\n");
+}

package/src/subagents/runs/shared/subagent-prompt-runtime.ts

@@ -0,0 +1,170 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { SUBAGENT_FANOUT_CHILD_ENV } from "./pi-args.ts";
+
+const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
+const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
+export const SUBAGENT_INTERCOM_SESSION_NAME_ENV = "PI_SUBAGENT_INTERCOM_SESSION_NAME";
+
+export const CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS = [
+	"You are a child subagent, not the parent orchestrator.",
+	"The parent session owns delegation, orchestration, review fanout, and follow-up worker launches.",
+	"Ignore prior parent-only orchestration instructions in inherited conversation history.",
+	"Do not propose or run subagents. Complete only your assigned role-specific task with the tools available to you.",
+	"If you need to edit files, call the actual edit/write tools. Do not print tool-call syntax, patches, or pseudo-tool calls as text.",
+].join("\n");
+
+export const CHILD_FANOUT_BOUNDARY_INSTRUCTIONS = [
+	"You are a child subagent with explicit fanout responsibility for this assigned task.",
+	"The parent session owns final orchestration, acceptance, and follow-up implementation launches.",
+	"You may use the `subagent` tool only for the fanout work explicitly requested in this task.",
+	"Do not broaden yourself into general parent orchestration. Do not launch follow-up workers unless the task explicitly asks for that.",
+	"The maxSubagentDepth cap still applies and may block further fanout.",
+	"If you need to edit files, call the actual edit/write tools. Do not print tool-call syntax, patches, or pseudo-tool calls as text.",
+].join("\n");
+
+const PARENT_ONLY_CUSTOM_MESSAGE_TYPES = new Set([
+	"subagent-orchestration-instructions",
+	"subagent-slash-result",
+	"subagent-notify",
+	"subagent_control_notice",
+	"subagent-control",
+	"subagent-control-notice",
+]);
+const SUBAGENT_ORCHESTRATION_SKILL_NAME_PATTERN = /<name>\s*pi-subagents\s*<\/name>/;
+const PROJECT_CONTEXT_HEADER = "\n\n# Project Context\n\nProject-specific instructions and guidelines:\n\n";
+const SKILLS_HEADER = "\n\nThe following skills provide specialized instructions for specific tasks.";
+const DATE_HEADER = "\nCurrent date:";
+
+function readBooleanEnv(name: string): boolean | undefined {
+	const value = process.env[name];
+	if (value === undefined) return undefined;
+	return value !== "0";
+}
+
+function findSectionEnd(prompt: string, startIndex: number, nextHeaders: string[]): number {
+	let endIndex = prompt.length;
+	for (const header of nextHeaders) {
+		const index = prompt.indexOf(header, startIndex);
+		if (index !== -1 && index < endIndex) {
+			endIndex = index;
+		}
+	}
+	return endIndex;
+}
+
+export function stripProjectContext(prompt: string): string {
+	const startIndex = prompt.indexOf(PROJECT_CONTEXT_HEADER);
+	if (startIndex === -1) return prompt;
+	const endIndex = findSectionEnd(prompt, startIndex + PROJECT_CONTEXT_HEADER.length, [SKILLS_HEADER, DATE_HEADER]);
+	return `${prompt.slice(0, startIndex)}${prompt.slice(endIndex)}`;
+}
+
+export function stripInheritedSkills(prompt: string): string {
+	const startIndex = prompt.indexOf(SKILLS_HEADER);
+	if (startIndex === -1) return prompt;
+	const endIndex = findSectionEnd(prompt, startIndex + SKILLS_HEADER.length, [DATE_HEADER]);
+	return `${prompt.slice(0, startIndex)}${prompt.slice(endIndex)}`;
+}
+
+export function stripSubagentOrchestrationSkill(prompt: string): string {
+	return prompt
+		.replace(/\n{0,2}<skill\s+name=["']pi-subagents["'][^>]*>[\s\S]*?<\/skill>\n{0,2}/g, "\n\n")
+		.replace(/[ \t]*<skill>\s*[\s\S]*?<\/skill>\s*/g, (block) => SUBAGENT_ORCHESTRATION_SKILL_NAME_PATTERN.test(block) ? "" : block);
+}
+
+function stripChildBoundaryInstructions(prompt: string): string {
+	let rewritten = prompt;
+	for (const boundary of [CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS, CHILD_FANOUT_BOUNDARY_INSTRUCTIONS]) {
+		rewritten = rewritten.split(boundary).join("");
+	}
+	return rewritten.replace(/^(?:[ \t]*\r?\n)+/, "");
+}
+
+export function rewriteSubagentPrompt(
+	prompt: string,
+	options: { inheritProjectContext: boolean; inheritSkills: boolean; fanoutChild?: boolean },
+): string {
+	let rewritten = prompt;
+	if (!options.inheritProjectContext) {
+		rewritten = stripProjectContext(rewritten);
+	}
+	if (!options.inheritSkills) {
+		rewritten = stripInheritedSkills(rewritten);
+	}
+	rewritten = stripSubagentOrchestrationSkill(rewritten);
+	rewritten = stripChildBoundaryInstructions(rewritten);
+	const boundary = options.fanoutChild ? CHILD_FANOUT_BOUNDARY_INSTRUCTIONS : CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS;
+	return `${boundary}\n\n${rewritten}`;
+}
+
+function isParentOnlySubagentMessage(message: unknown): boolean {
+	const m = message as { role?: string; customType?: string };
+	return m?.role === "custom"
+		&& typeof m.customType === "string"
+		&& PARENT_ONLY_CUSTOM_MESSAGE_TYPES.has(m.customType);
+}
+
+function isSubagentToolResultMessage(message: unknown): boolean {
+	const m = message as { role?: string; toolName?: string };
+	return m?.role === "toolResult" && m.toolName === "subagent";
+}
+
+function isSubagentToolCallBlock(block: unknown): boolean {
+	const b = block as { type?: string; name?: string };
+	return b?.type === "toolCall" && b.name === "subagent";
+}
+
+function stripAssistantSubagentToolCallBlocks(message: unknown): unknown | undefined {
+	const m = message as { role?: string; content?: unknown };
+	if (m?.role !== "assistant" || !Array.isArray(m.content)) return message;
+	const filteredContent = m.content.filter((block) => !isSubagentToolCallBlock(block));
+	if (filteredContent.length === m.content.length) return message;
+	if (filteredContent.length === 0) return undefined;
+	return { ...m, content: filteredContent };
+}
+
+export function stripParentOnlySubagentMessages(messages: unknown[]): unknown[] {
+	let changed = false;
+	const filtered: unknown[] = [];
+	for (const message of messages) {
+		if (isParentOnlySubagentMessage(message) || isSubagentToolResultMessage(message)) {
+			changed = true;
+			continue;
+		}
+		const stripped = stripAssistantSubagentToolCallBlocks(message);
+		if (stripped === undefined) {
+			changed = true;
+			continue;
+		}
+		if (stripped !== message) changed = true;
+		filtered.push(stripped);
+	}
+	return changed ? filtered : messages;
+}
+
+export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
+	pi.on("context", (event) => {
+		const messages = stripParentOnlySubagentMessages(event.messages);
+		if (messages === event.messages) return undefined;
+		return { messages };
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		const intercomSessionName = process.env[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
+		if (intercomSessionName && typeof pi.setSessionName === "function") {
+			pi.setSessionName(intercomSessionName);
+		}
+
+		const inheritProjectContext = readBooleanEnv(SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV);
+		const inheritSkills = readBooleanEnv(SUBAGENT_INHERIT_SKILLS_ENV);
+		const fanoutChild = readBooleanEnv(SUBAGENT_FANOUT_CHILD_ENV);
+		if (inheritProjectContext === undefined && inheritSkills === undefined && fanoutChild === undefined) return;
+		const rewritten = rewriteSubagentPrompt(event.systemPrompt, {
+			inheritProjectContext: inheritProjectContext ?? true,
+			inheritSkills: inheritSkills ?? true,
+			fanoutChild: fanoutChild === true,
+		});
+		if (rewritten === event.systemPrompt) return;
+		return { systemPrompt: rewritten };
+	});
+}