@narumitw/pi-subagents 0.42.0 → 0.43.1

package/src/subagents.ts

@@ -13,20 +13,41 @@
  */
 
 import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
-import { discoverAgentCatalog, formatAgentCatalog } from "./agents.js";
+import {
+	type ConsultationCwdPolicy,
+	type ConsultResourcePolicy,
+	type DelegationCwdPolicy,
+	discoverAgentCatalog,
+	formatAgentCatalog,
+	type SubagentSettings,
+} from "./agents.js";
 import { registerSubagentConfigCommand } from "./config-ui.js";
+import { registerSubagentConsult } from "./consult.js";
 import { executeSubagent } from "./execution.js";
+import { registerSubagentInspect } from "./inspect.js";
 import { SubagentParams } from "./params.js";
 import { renderSubagentCall, renderSubagentResult } from "./render.js";
 import type { SubagentDetails } from "./runner.js";
-import { consumeSubagentSettingsNotice, readSubagentSettings } from "./settings.js";
+import {
+	consumeSubagentSettingsNotice,
+	DEFAULT_CONSULT_RESOURCE_POLICY,
+	DEFAULT_CONSULTATION_CWD_POLICY,
+	DEFAULT_DELEGATION_CWD_POLICY,
+	inspectSubagentSettings,
+	readSubagentSettings,
+} from "./settings.js";
 import { registerStatefulSubagents } from "./stateful.js";
 
 export default function (pi: ExtensionAPI) {
 	const settings = readSubagentSettings();
+	let currentSettings: SubagentSettings | undefined = settings;
+	let currentCatalog = "";
 	const blockingEnabled = settings?.blocking?.enabled !== false;
-	const refreshBlockingCatalog = blockingEnabled ? registerBlockingSubagent(pi) : () => undefined;
+	const refreshBlockingCatalog = blockingEnabled
+		? registerBlockingSubagent(pi, () => currentSettings)
+		: () => undefined;
 	let refreshStatefulCatalog: (catalog: string) => void = () => undefined;
+	let refreshConsultCatalog: (catalog: string) => void = () => undefined;
 
 	pi.on("session_start", (_event, ctx) => {
 		// Preserve a one-shot migration notice from extension load while refreshing
@@ -34,43 +55,95 @@ export default function (pi: ExtensionAPI) {
 		const loadNotice = consumeSubagentSettingsNotice();
 		const refreshedSettings = readSubagentSettings();
 		const refreshedNotice = consumeSubagentSettingsNotice();
+		if (!inspectSubagentSettings().error) currentSettings = refreshedSettings;
 		const notice = [
 			...new Set([loadNotice, refreshedNotice].filter((value) => value !== undefined)),
 		].join("\n");
 		if (notice) ctx.ui.notify(notice, "warning");
 
-		const catalog = formatAgentCatalog(
+		currentCatalog = formatAgentCatalog(
 			discoverAgentCatalog(ctx.cwd, ctx.isProjectTrusted(), refreshedSettings),
 		).text;
-		refreshBlockingCatalog(catalog);
-		refreshStatefulCatalog(catalog);
+		refreshBlockingCatalog(currentCatalog);
+		refreshStatefulCatalog(currentCatalog);
+		refreshConsultCatalog(currentCatalog);
 	});
 
 	const statefulRuntime = registerStatefulSubagents(pi, {
 		blockingEnabled,
 		settings: settings?.stateful,
+		getSettings: () => currentSettings,
 	});
 	refreshStatefulCatalog = statefulRuntime.setAgentCatalog;
+	const getBlockingEnabled = () => blockingEnabled;
+	const getConsultResourcePolicy = () =>
+		currentSettings?.consult?.resources ?? DEFAULT_CONSULT_RESOURCE_POLICY;
+	const getConsultationCwdPolicy = () =>
+		currentSettings?.cwdPolicy?.consultation ?? DEFAULT_CONSULTATION_CWD_POLICY;
+	const getDelegationCwdPolicy = () =>
+		currentSettings?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY;
+	registerSubagentInspect(pi, {
+		...statefulRuntime,
+		getBlockingEnabled,
+		getConsultResourcePolicy,
+		getConsultationCwdPolicy,
+		getDelegationCwdPolicy,
+	});
+	if (blockingEnabled) {
+		refreshConsultCatalog = registerSubagentConsult(pi, {
+			getSettings: () => currentSettings,
+		});
+	}
 	registerSubagentConfigCommand(pi, {
 		...statefulRuntime,
-		getBlockingEnabled: () => blockingEnabled,
+		getBlockingEnabled,
+		getConsultResourcePolicy,
+		getConsultationCwdPolicy,
+		getDelegationCwdPolicy,
+		setConsultResourcePolicy(value: ConsultResourcePolicy) {
+			currentSettings = {
+				...(currentSettings ?? {}),
+				consult: { ...(currentSettings?.consult ?? {}), resources: value },
+			};
+			refreshConsultCatalog(currentCatalog);
+		},
+		setConsultationCwdPolicy(value: ConsultationCwdPolicy) {
+			currentSettings = {
+				...(currentSettings ?? {}),
+				cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), consultation: value },
+			};
+			refreshConsultCatalog(currentCatalog);
+		},
+		setDelegationCwdPolicy(value: DelegationCwdPolicy) {
+			currentSettings = {
+				...(currentSettings ?? {}),
+				cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), delegation: value },
+			};
+			refreshBlockingCatalog(currentCatalog);
+			statefulRuntime.refreshSettingsGuidance();
+		},
 	});
 }
 
-function registerBlockingSubagent(pi: ExtensionAPI): (catalog: string) => void {
+function registerBlockingSubagent(
+	pi: ExtensionAPI,
+	getSettings: () => SubagentSettings | undefined,
+): (catalog: string) => void {
 	let catalog = "";
-	const baseDescription = [
-		"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(" ");
+	const baseDescription = () =>
+		[
+			"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. Use subagent_consult instead for one synchronous child that must be executor-constrained to read-only tools.",
+			'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.',
+			`Working-directory target policy: ${getSettings()?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY}. This controls launch targets and protected project resources, not filesystem access or sandboxing.`,
+		].join(" ");
 	const definition: ToolDefinition<typeof SubagentParams, SubagentDetails> = {
 		name: "subagent",
 		label: "Blocking Subagent",
-		description: appendAgentCatalog(baseDescription, catalog),
+		description: appendAgentCatalog(baseDescription(), catalog),
 		promptSnippet:
 			"Run blocking isolated subagents only when their outputs are required before the main agent can continue.",
 		promptGuidelines: [
@@ -86,7 +159,7 @@ function registerBlockingSubagent(pi: ExtensionAPI): (catalog: string) => void {
 		parameters: SubagentParams,
 
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			return executeSubagent(toolCallId, params, signal, onUpdate, ctx);
+			return executeSubagent(toolCallId, params, signal, onUpdate, ctx, getSettings());
 		},
 
 		renderCall(args, theme) {
@@ -105,7 +178,7 @@ function registerBlockingSubagent(pi: ExtensionAPI): (catalog: string) => void {
 	});
 	return (nextCatalog: string) => {
 		catalog = nextCatalog;
-		definition.description = appendAgentCatalog(baseDescription, catalog);
+		definition.description = appendAgentCatalog(baseDescription(), catalog);
 		pi.registerTool<typeof SubagentParams, SubagentDetails>(definition);
 	};
 }
@@ -118,8 +191,14 @@ export { parsePositiveInteger } from "./execution.js";
 export { formatTokens, formatUsageStats } from "./render.js";
 export { buildPiArgs } from "./runner.js";
 export {
+	DEFAULT_CONSULT_RESOURCE_POLICY,
+	DEFAULT_CONSULTATION_CWD_POLICY,
+	DEFAULT_DELEGATION_CWD_POLICY,
 	inspectCompletionDeliverySettings,
+	inspectConsultResourceSettings,
+	inspectCwdPolicySettings,
 	inspectDelegationWorkflowSettings,
+	inspectSubagentSettings,
 	normalizeAgentSettings,
 	normalizeSubagentSettings,
 	readSubagentSettings,
@@ -130,5 +209,7 @@ export {
 	uniqueToolNames,
 	updateAgentToolsSetting,
 	updateCompletionDeliverySetting,
+	updateConsultResourceSetting,
+	updateCwdPolicySetting,
 	updateDelegationWorkflowSetting,
 } from "./settings.js";

package/src/subprocess-transport.ts

@@ -1,4 +1,9 @@
-import { type AgentConfig, discoverAgents, type SubagentThinkingLevel } from "./agents.js";
+import {
+	type AgentConfig,
+	discoverAgents,
+	type SubagentSettings,
+	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";
@@ -12,11 +17,17 @@ export function resolveStatefulSubprocessThinkingLevel(
 	return resolveSubagentThinkingLevel(agents, record.agent, record.thinkingLevel);
 }
 
+export interface SubprocessTransportOptions {
+	getSettings?: () => SubagentSettings | undefined;
+}
+
 export class SubprocessTransport implements SubagentTransport {
 	readonly kind = "subprocess" as const;
 
+	constructor(private readonly options: SubprocessTransportOptions = {}) {}
+
 	async runTurn(record: ManagedAgent, task: string, signal: AbortSignal): Promise<TurnOutcome> {
-		const settings = readSubagentSettings();
+		const settings = this.options.getSettings ? this.options.getSettings() : readSubagentSettings();
 		const discovery = discoverAgents(record.cwd, record.agentScope ?? "user", settings);
 		const agent = discovery.agents.find((candidate) => candidate.name === record.agent);
 		const boundedTask = buildStatefulTurnPrompt(record, task);
@@ -38,6 +49,12 @@ export class SubprocessTransport implements SubagentTransport {
 			resolveStatefulTurnTimeout(agent),
 			undefined,
 			makeDetails,
+			undefined,
+			{
+				projectTrust:
+					record.target?.trust.projectTrusted ??
+					(record.agentScope === "project" || record.agentScope === "both"),
+			},
 		);
 		return {
 			output: getResultFinalOutput(single),