pi-subagents 0.56.0 → 0.58.0

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

@@ -6,7 +6,7 @@ import { registerNativeSupervisorClient } from "../../intercom/native-supervisor
 import { shouldUseNativeFsWatch } from "../../shared/watch-strategy.ts";
 import { decodePermissionRules, permissionDecision, PERMISSION_AUDIT_PATH_ENV, PERMISSION_POLICY_ENV } from "./permissions.ts";
 import { consumeSteerRequestsFromDir, MAX_STEER_QUEUE_SIZE, steerAckPathFromDir, writeSteerAckAt, writeSteerCapabilityAt, writeSteerRequestToDir, type SteerDeliveryStatus, type SteerRequest } from "../background/control-channel.ts";
-import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_STEER_ACK_DIR_ENV, SUBAGENT_STEER_CAPABILITY_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
+import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_INHERIT_GLOBAL_CONTEXT_ENV, SUBAGENT_STEER_ACK_DIR_ENV, SUBAGENT_STEER_CAPABILITY_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
 import { RUNTIME_EXTENSION_ACK_EVENT, RUNTIME_EXTENSION_ACK_PATH_ENV, isRuntimeAcknowledgedExtensionId, writeRuntimeAcknowledgedExtensions } from "./runtime-acknowledged-extensions.ts";
 import { createStructuredOutputToolParameters, STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV, STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
 import {
@@ -20,7 +20,7 @@ import {
 import { TOOL_BUDGET_ENV, TOOL_BUDGET_ZERO_AUTH_ENV, decodeToolBudgetEnv, shouldBlockToolForBudget, toolBudgetBlockedMessage, toolBudgetSoftNudge } from "./tool-budget.ts";
 import type { JsonSchemaObject, ResolvedToolBudget, SubagentState } from "../../shared/types.ts";
 import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
-import { resolveWatchPath } from "../../shared/utils.ts";
+import { getAgentDir, resolveWatchPath } from "../../shared/utils.ts";
 import { registerChildWatchdog } from "../../watchdog/register-child.ts";
 import { CHILD_WATCHDOG_CONFIG_ENV, decodeChildWatchdogConfig } from "../../watchdog/child-status.ts";
 import { requestWatchdogPermission, type WatchdogPermissionRequest, type WatchdogPermissionResult } from "../../watchdog/permission-arbiter.ts";
@@ -68,7 +68,8 @@ const PARENT_ONLY_CUSTOM_MESSAGE_TYPES = new Set([
 	"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 PROJECT_CONTEXT_XML_HEADER = "\n\n<project_context>\n\n";
+const PROJECT_CONTEXT_LEGACY_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:";
 
@@ -148,10 +149,80 @@ function findSectionEnd(prompt: string, startIndex: number, nextHeaders: string[
 }
 
 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)}`;
+	const xmlStartIndex = prompt.indexOf(PROJECT_CONTEXT_XML_HEADER);
+	if (xmlStartIndex !== -1) {
+		const closingTag = "</project_context>";
+		const closingIndex = prompt.indexOf(closingTag, xmlStartIndex + PROJECT_CONTEXT_XML_HEADER.length);
+		if (closingIndex !== -1) {
+			return `${prompt.slice(0, xmlStartIndex)}${prompt.slice(closingIndex + closingTag.length)}`;
+		}
+	}
+	const legacyStartIndex = prompt.indexOf(PROJECT_CONTEXT_LEGACY_HEADER);
+	if (legacyStartIndex === -1) return prompt;
+	const endIndex = findSectionEnd(prompt, legacyStartIndex + PROJECT_CONTEXT_LEGACY_HEADER.length, [SKILLS_HEADER, DATE_HEADER]);
+	return `${prompt.slice(0, legacyStartIndex)}${prompt.slice(endIndex)}`;
+}
+
+const GLOBAL_CONTEXT_FILE_NAMES = new Set(["agents.md", "agents.override.md", "claude.md"]);
+
+function canonicalDirectory(dir: string): string {
+	try {
+		return fs.realpathSync(dir);
+	} catch {
+		return path.resolve(dir);
+	}
+}
+
+function expandContextPath(filePath: string): string {
+	const home = process.env.HOME ?? process.env.USERPROFILE;
+	return filePath === "~"
+		? home ?? filePath
+		: /^~[\\/]/.test(filePath)
+			? path.join(home ?? "~", filePath.slice(2))
+			: filePath;
+}
+
+function isContextFilePath(filePath: string): boolean {
+	return GLOBAL_CONTEXT_FILE_NAMES.has(path.basename(expandContextPath(filePath)).toLowerCase());
+}
+
+function isGlobalContextFile(filePath: string): boolean {
+	const expanded = expandContextPath(filePath);
+	if (!isContextFilePath(filePath)) return false;
+	return canonicalDirectory(path.dirname(expanded)) === canonicalDirectory(getAgentDir());
+}
+
+function stripGlobalInstructionsFromXmlContext(context: string): string {
+	const block = /<project_instructions\s+path=(["'])(.*?)\1\s*>[\s\S]*?<\/project_instructions>\s*/gi;
+	return context.replace(block, (match, _quote: string, filePath: string) => isGlobalContextFile(filePath) ? "" : match);
+}
+
+function stripGlobalInstructionsFromLegacyContext(context: string): string {
+	const sections = [...context.matchAll(/^## ([^\r\n]+)(?:\r?\n|$)/gm)]
+		.filter((match) => isContextFilePath(match[1]!.trim()));
+	let rewritten = "";
+	let cursor = 0;
+	for (let index = 0; index < sections.length; index++) {
+		const section = sections[index]!;
+		const start = section.index!;
+		const end = sections[index + 1]?.index ?? context.length;
+		rewritten += context.slice(cursor, start);
+		if (!isGlobalContextFile(section[1]!.trim())) rewritten += context.slice(start, end);
+		cursor = end;
+	}
+	return `${rewritten}${context.slice(cursor)}`;
+}
+
+export function stripGlobalContext(prompt: string): string {
+	const rewrittenXml = prompt.replace(/<project_context>[\s\S]*?<\/project_context>/gi, (context) => {
+		const rewritten = stripGlobalInstructionsFromXmlContext(context);
+		return /<project_instructions\b/i.test(rewritten) ? rewritten : "";
+	});
+	const legacyStartIndex = rewrittenXml.indexOf(PROJECT_CONTEXT_LEGACY_HEADER);
+	if (legacyStartIndex === -1) return rewrittenXml;
+	const legacyEndIndex = findSectionEnd(rewrittenXml, legacyStartIndex + PROJECT_CONTEXT_LEGACY_HEADER.length, [SKILLS_HEADER, DATE_HEADER]);
+	const legacyContext = rewrittenXml.slice(legacyStartIndex, legacyEndIndex);
+	return `${rewrittenXml.slice(0, legacyStartIndex)}${stripGlobalInstructionsFromLegacyContext(legacyContext)}${rewrittenXml.slice(legacyEndIndex)}`;
 }
 
 export function stripInheritedSkills(prompt: string): string {
@@ -177,12 +248,15 @@ function stripChildBoundaryInstructions(prompt: string): string {
 
 export function rewriteSubagentPrompt(
 	prompt: string,
-	options: { inheritProjectContext: boolean; inheritSkills: boolean; fanoutChild?: boolean },
+	options: { inheritProjectContext: boolean; inheritGlobalContext: boolean; inheritSkills: boolean; fanoutChild?: boolean },
 ): string {
 	let rewritten = prompt;
 	if (!options.inheritProjectContext) {
 		rewritten = stripProjectContext(rewritten);
 	}
+	if (!options.inheritGlobalContext) {
+		rewritten = stripGlobalContext(rewritten);
+	}
 	if (!options.inheritSkills) {
 		rewritten = stripInheritedSkills(rewritten);
 	}
@@ -688,12 +762,14 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 		}
 
 		const inheritProjectContext = readBooleanEnv(SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV);
+		const inheritGlobalContext = readBooleanEnv(SUBAGENT_INHERIT_GLOBAL_CONTEXT_ENV);
 		const inheritSkills = readBooleanEnv(SUBAGENT_INHERIT_SKILLS_ENV);
 		const fanoutChild = readBooleanEnv(SUBAGENT_FANOUT_CHILD_ENV);
 		let rewritten = event.systemPrompt;
-		if (inheritProjectContext !== undefined || inheritSkills !== undefined || fanoutChild !== undefined) {
+		if (inheritProjectContext !== undefined || inheritGlobalContext !== undefined || inheritSkills !== undefined || fanoutChild !== undefined) {
 			rewritten = rewriteSubagentPrompt(event.systemPrompt, {
 				inheritProjectContext: inheritProjectContext ?? true,
+				inheritGlobalContext: inheritGlobalContext ?? true,
 				inheritSkills: inheritSkills ?? true,
 				fanoutChild: fanoutChild === true,
 			});

package/src/shared/fork-context.ts

@@ -37,6 +37,8 @@ interface ForkableSessionManager {
 
 interface ForkContextResolverOptions {
 	openSession?: (path: string, sessionDir?: string) => BranchSessionManager;
+	/** Rewrite a created fork before its path can be used to spawn a child. */
+	pruneSession?: (sessionFile: string) => Promise<void>;
 	/** Decide per child index whether a sanitized transcript must also disable the child's
 	 * thinking. Defaults to true (the pre-existing conservative behavior) when omitted. */
 	forceThinkingOffForIndex?: (index: number) => boolean;
@@ -48,6 +50,7 @@ interface ForkContextResolution {
 }
 
 interface ForkContextResolver {
+	prepareSessionForIndex(index?: number): Promise<void>;
 	sessionFileForIndex(index?: number): string | undefined;
 	thinkingOverrideForIndex(index?: number): "off" | undefined;
 }
@@ -190,6 +193,7 @@ export function createForkContextResolver(
 ): ForkContextResolver {
 	if (resolveSubagentContext(requestedContext) !== "fork") {
 		return {
+			prepareSessionForIndex: async () => {},
 			sessionFileForIndex: () => undefined,
 			thinkingOverrideForIndex: () => undefined,
 		};
@@ -226,6 +230,8 @@ export function createForkContextResolver(
 		"forks",
 	);
 	const cachedResolutions = new Map<number, ForkContextResolution>();
+	const preparedIndexes = new Set<number>();
+	const preparationPromises = new Map<number, Promise<void>>();
 
 	const resolveFork = (index = 0): ForkContextResolution => {
 		const cached = cachedResolutions.get(index);
@@ -274,7 +280,22 @@ export function createForkContextResolver(
 	};
 
 	return {
+		async prepareSessionForIndex(index = 0): Promise<void> {
+			const resolution = resolveFork(index);
+			if (!options.pruneSession || preparedIndexes.has(index)) return;
+			let preparation = preparationPromises.get(index);
+			if (!preparation) {
+				preparation = options.pruneSession(resolution.sessionFile).then(() => {
+					preparedIndexes.add(index);
+				});
+				preparationPromises.set(index, preparation);
+			}
+			await preparation;
+		},
 		sessionFileForIndex(index = 0): string | undefined {
+			if (options.pruneSession && !preparedIndexes.has(index)) {
+				throw new Error(`Pruned fork session ${index} was used before pruning completed.`);
+			}
 			return resolveFork(index).sessionFile;
 		},
 		thinkingOverrideForIndex(index = 0): "off" | undefined {

package/src/shared/formatters.ts

@@ -4,7 +4,7 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { Usage, SingleResult } from "./types.ts";
+import type { Usage, SingleResult, TokenUsage } from "./types.ts";
 import type { ChainStep } from "./settings.ts";
 import { isDynamicParallelStep, isParallelStep } from "./settings.ts";
 import { previewDisplayText, sanitizeDisplayText } from "./display-text.ts";
@@ -17,6 +17,18 @@ export function formatTokens(n: number): string {
 	return n < 1000 ? String(n) : n < 10000 ? `${(n / 1000).toFixed(1)}k` : `${Math.round(n / 1000)}k`;
 }
 
+export function formatTokenUsage(usage: TokenUsage, legacyLabel = "tok"): string {
+	return usage.window !== undefined
+		? `${formatTokens(usage.window)} window · ${formatTokens(usage.total)} spent`
+		: `${formatTokens(usage.total)} ${legacyLabel}`;
+}
+export function formatContextUsage(usage: Pick<TokenUsage, "window" | "windowPeak">, contextLimit: number): string | undefined {
+	if (usage.window === undefined || !Number.isFinite(usage.window) || !Number.isFinite(contextLimit) || contextLimit <= 0) return undefined;
+	const peak = usage.windowPeak !== undefined && Number.isFinite(usage.windowPeak) ? usage.windowPeak : usage.window;
+	const used = Math.max(0, usage.window, peak);
+	return `ctx ${formatTokens(used)}/${formatTokens(contextLimit)} (${Math.round((used / contextLimit) * 100)}%)`;
+}
+
 export function formatModelThinking(model?: string, thinking?: string): string {
 	const parsed = model ? splitKnownThinkingSuffix(model) : undefined;
 	let displayModel = parsed?.baseModel ?? model;

package/src/shared/launch-contract.ts

@@ -43,6 +43,7 @@ export function projectAgentDefinition(agent: AgentConfig): Record<string, unkno
 		systemPrompt: agent.systemPrompt,
 		systemPromptMode: agent.systemPromptMode,
 		inheritProjectContext: agent.inheritProjectContext,
+		inheritGlobalContext: agent.inheritGlobalContext,
 		inheritSkills: agent.inheritSkills,
 		model: agent.model,
 		modelProvider: agent.modelProvider,
@@ -53,6 +54,7 @@ export function projectAgentDefinition(agent: AgentConfig): Record<string, unkno
 		mcpDirectTools: agent.mcpDirectTools,
 		extensions: agent.extensions,
 		subagentOnlyExtensions: agent.subagentOnlyExtensions,
+		mutationTools: agent.mutationTools,
 		skills: agent.skills,
 		skillPath: agent.skillPath,
 		output: agent.output,
@@ -87,6 +89,7 @@ export interface LaunchBindingInput {
 	systemPrompt?: string | null;
 	systemPromptMode?: AgentConfig["systemPromptMode"];
 	inheritProjectContext: boolean;
+	inheritGlobalContext: boolean;
 	inheritSkills: boolean;
 	skills?: string[];
 	tools?: string[];
@@ -113,6 +116,7 @@ export function projectLaunchBinding(input: LaunchBindingInput): Record<string,
 		systemPromptDigest: input.systemPrompt === undefined || input.systemPrompt === null ? undefined : stableJsonDigest(input.systemPrompt),
 		systemPromptMode: input.systemPromptMode,
 		inheritProjectContext: input.inheritProjectContext,
+		inheritGlobalContext: input.inheritGlobalContext,
 		inheritSkills: input.inheritSkills,
 		skills: input.skills,
 		tools: input.tools,