@narumitw/pi-subagents 2.1.4 → 3.0.0

package/src/settings.ts

@@ -1,452 +0,0 @@
-import { randomUUID } from "node:crypto";
-import * as fs from "node:fs";
-import { createRequire } from "node:module";
-import * as path from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import type {
-	AgentConfig,
-	CompletionDelivery,
-	ConsultationCwdPolicy,
-	ConsultResourcePolicy,
-	DelegationCwdPolicy,
-	SubagentAgentConfig,
-	SubagentSettings,
-	SubagentThinkingLevel,
-	SubagentTransportKind,
-} from "./agents/types.js";
-import { MAX_CONFIGURABLE_PARALLEL_TASKS } from "./limits.js";
-import type { DelegationWorkflow } from "./settings/inspection.js";
-import {
-	hasOwn,
-	isPlainObject,
-	isPositiveInteger,
-	normalizeSubagentSettings,
-} from "./settings/schema.js";
-import {
-	pathEntryExists,
-	resolveSubagentSettingsPaths,
-	SUBAGENT_SETTINGS_FILE,
-} from "./settings-reader.js";
-import {
-	isValidStatefulLimit,
-	resolveStatefulLimits,
-	STATEFUL_LIMIT_FIELDS,
-	type StatefulLimitField,
-	type StatefulLimits,
-	statefulLimitDefinition,
-} from "./stateful-limits.js";
-
-export {
-	type BlockingParallelLimitSettingsSnapshot,
-	type CompletionDeliverySettingsSnapshot,
-	type ConsultResourceSettingsSnapshot,
-	type CwdPolicyFieldSnapshot,
-	type CwdPolicySettingsSnapshot,
-	consumeSubagentSettingsNotice,
-	DEFAULT_CONSULT_RESOURCE_POLICY,
-	DEFAULT_CONSULTATION_CWD_POLICY,
-	DEFAULT_DELEGATION_CWD_POLICY,
-	type DelegationWorkflow,
-	type DelegationWorkflowSettingsSnapshot,
-	hasOwn,
-	inspectBlockingParallelLimitSettings,
-	inspectCompletionDeliverySettings,
-	inspectConsultResourceSettings,
-	inspectCwdPolicySettings,
-	inspectDelegationWorkflowSettings,
-	inspectStatefulLimitSettings,
-	inspectStatefulTransportSettings,
-	inspectSubagentSettings,
-	inspectUsageRecordingSettings,
-	normalizeAgentSettings,
-	normalizeSubagentSettings,
-	readSubagentSettings,
-	resolveBlockingMaxParallelTasks,
-	resolveDelegationWorkflow,
-	type StatefulLimitFieldSnapshot,
-	type StatefulLimitSettingsSnapshot,
-	type StatefulTransportSettingsSnapshot,
-	type SubagentSettingsSnapshot,
-	subagentSettingsFilePath,
-	type UsageRecordingSettingsSnapshot,
-} from "./settings-reader.js";
-
-const SETTINGS_FILE = SUBAGENT_SETTINGS_FILE;
-const require = createRequire(import.meta.url);
-
-const SETTINGS_LOCK_FS_ADAPTER = {
-	mkdir: fs.mkdir,
-	mkdirSync: fs.mkdirSync,
-	realpath: fs.realpath,
-	realpathSync: fs.realpathSync,
-	rmdir: fs.rmdir,
-	rmdirSync: fs.rmdirSync,
-	stat: fs.stat,
-	statSync: fs.statSync,
-	utimes: fs.utimes,
-	utimesSync: fs.utimesSync,
-};
-
-export function saveSubagentConfig(settings: SubagentSettings): void {
-	writeSettingsObject(settings);
-}
-
-export function updateDelegationWorkflowSetting(
-	value: Exclude<DelegationWorkflow, "disabled">,
-): void {
-	withSettingsMutationLock(() => {
-		const update = readSettingsObjectForUpdate();
-		const raw = update.document;
-		const blocking = raw.blocking;
-		if (blocking !== undefined && !isPlainObject(blocking)) {
-			throw new Error(`Cannot update invalid ${SETTINGS_FILE} blocking settings`);
-		}
-		const stateful = raw.stateful;
-		if (stateful !== undefined && !isPlainObject(stateful)) {
-			throw new Error(`Cannot update invalid ${SETTINGS_FILE} stateful settings`);
-		}
-		writeSettingsObjectUnlocked(
-			{
-				...raw,
-				blocking: {
-					...(blocking ?? {}),
-					enabled: value !== "async-only",
-				},
-				stateful: {
-					...(stateful ?? {}),
-					enabled: value !== "blocking-only",
-				},
-			},
-			update.replaceCanonical,
-		);
-	});
-}
-
-export function updateStatefulTransportSetting(value: SubagentTransportKind): void {
-	if (!["subprocess", "in-process", "rpc", "auto"].includes(value)) {
-		throw new Error(`Unsupported stateful transport: ${value}`);
-	}
-	withSettingsMutationLock(() => {
-		const update = readSettingsObjectForUpdate();
-		const raw = update.document;
-		const stateful = raw.stateful;
-		if (stateful !== undefined && !isPlainObject(stateful)) {
-			throw new Error(`Cannot update invalid ${SETTINGS_FILE} stateful settings`);
-		}
-		writeSettingsObjectUnlocked(
-			{
-				...raw,
-				stateful: { ...(stateful ?? {}), transport: value },
-			},
-			update.replaceCanonical,
-		);
-	});
-}
-
-export function updateCompletionDeliverySetting(value: CompletionDelivery): void {
-	withSettingsMutationLock(() => {
-		const update = readSettingsObjectForUpdate();
-		const raw = update.document;
-		const stateful = raw.stateful;
-		if (stateful !== undefined && !isPlainObject(stateful)) {
-			throw new Error(`Cannot update invalid ${SETTINGS_FILE} stateful settings`);
-		}
-		writeSettingsObjectUnlocked(
-			{
-				...raw,
-				stateful: {
-					...(stateful ?? {}),
-					completionDelivery: value,
-				},
-			},
-			update.replaceCanonical,
-		);
-	});
-}
-
-export function updateUsageRecordingSetting(enabled: boolean): void {
-	withSettingsMutationLock(() => {
-		const update = readSettingsObjectForUpdate();
-		const raw = update.document;
-		const usageRecording = raw.usageRecording;
-		if (usageRecording !== undefined && !isPlainObject(usageRecording)) {
-			throw new Error(`Cannot update invalid ${SETTINGS_FILE} usageRecording settings`);
-		}
-		writeSettingsObjectUnlocked(
-			{
-				...raw,
-				usageRecording: { ...(usageRecording ?? {}), enabled },
-			},
-			update.replaceCanonical,
-		);
-	});
-}
-
-export function updateBlockingMaxParallelTasksSetting(value: number): void {
-	if (!isPositiveInteger(value) || value > MAX_CONFIGURABLE_PARALLEL_TASKS) {
-		throw new Error(
-			`Maximum parallel tasks must be an integer between 1 and ${MAX_CONFIGURABLE_PARALLEL_TASKS}`,
-		);
-	}
-	withSettingsMutationLock(() => {
-		const update = readSettingsObjectForUpdate();
-		const raw = update.document;
-		const blocking = raw.blocking;
-		if (blocking !== undefined && !isPlainObject(blocking)) {
-			throw new Error(`Cannot update invalid ${SETTINGS_FILE} blocking settings`);
-		}
-		writeSettingsObjectUnlocked(
-			{
-				...raw,
-				blocking: {
-					...(blocking ?? {}),
-					maxParallelTasks: value,
-				},
-			},
-			update.replaceCanonical,
-		);
-	});
-}
-
-export function updateStatefulLimitSetting(
-	field: StatefulLimitField,
-	value: number,
-	expected?: StatefulLimits,
-): void {
-	if (!isValidStatefulLimit(field, value)) {
-		throw new Error(
-			`${field} must be a safe integer greater than or equal to ${statefulLimitDefinition(field).minimum}`,
-		);
-	}
-	withSettingsMutationLock(() => {
-		const update = readSettingsObjectForUpdate();
-		const raw = update.document;
-		const stateful = raw.stateful;
-		if (stateful !== undefined && !isPlainObject(stateful)) {
-			throw new Error(`Cannot update invalid ${SETTINGS_FILE} stateful settings`);
-		}
-		const normalized = normalizeSubagentSettings(raw);
-		if (!normalized) throw new Error(`Cannot update invalid ${SETTINGS_FILE}`);
-		if (expected && !sameStatefulLimits(resolveStatefulLimits(normalized.stateful), expected)) {
-			throw new Error("Detached limit settings changed; reopen settings and retry");
-		}
-		writeSettingsObjectUnlocked(
-			{
-				...raw,
-				stateful: { ...(stateful ?? {}), [field]: value },
-			},
-			update.replaceCanonical,
-		);
-	});
-}
-
-export function updateConsultResourceSetting(value: ConsultResourcePolicy): void {
-	withSettingsMutationLock(() => {
-		const update = readSettingsObjectForUpdate();
-		const raw = update.document;
-		const consult = raw.consult;
-		if (consult !== undefined && !isPlainObject(consult)) {
-			throw new Error(`Cannot update invalid ${SETTINGS_FILE} consult settings`);
-		}
-		writeSettingsObjectUnlocked(
-			{
-				...raw,
-				consult: {
-					...(consult ?? {}),
-					resources: value,
-				},
-			},
-			update.replaceCanonical,
-		);
-	});
-}
-
-export function updateCwdPolicySetting(field: "consultation", value: ConsultationCwdPolicy): void;
-export function updateCwdPolicySetting(field: "delegation", value: DelegationCwdPolicy): void;
-export function updateCwdPolicySetting(
-	field: "consultation" | "delegation",
-	value: ConsultationCwdPolicy | DelegationCwdPolicy,
-): void {
-	withSettingsMutationLock(() => {
-		const update = readSettingsObjectForUpdate();
-		const raw = update.document;
-		const cwdPolicy = raw.cwdPolicy;
-		if (cwdPolicy !== undefined && !isPlainObject(cwdPolicy)) {
-			throw new Error(`Cannot update invalid ${SETTINGS_FILE} cwdPolicy settings`);
-		}
-		writeSettingsObjectUnlocked(
-			{
-				...raw,
-				cwdPolicy: { ...(cwdPolicy ?? {}), [field]: value },
-			},
-			update.replaceCanonical,
-		);
-	});
-}
-
-export type AgentSettingsPatch = {
-	tools?: string[] | undefined;
-	model?: string | null | undefined;
-	thinkingLevel?: SubagentThinkingLevel | null | undefined;
-	timeoutMs?: number | null | undefined;
-};
-
-export function updateAgentToolsSetting(name: string, tools: string[] | undefined): void {
-	updateAgentSettingsPatch({ [name]: { tools } });
-}
-
-export function updateAgentSettingsPatch(patches: Record<string, AgentSettingsPatch>): void {
-	withSettingsMutationLock(() => {
-		const update = readSettingsObjectForUpdate();
-		const raw = update.document;
-		const rawAgents = raw.agents;
-		if (rawAgents !== undefined && !isPlainObject(rawAgents)) {
-			throw new Error(`Cannot update invalid ${SETTINGS_FILE} agent settings`);
-		}
-		const agents = { ...(rawAgents ?? {}) };
-		for (const [name, patch] of Object.entries(patches)) {
-			const rawAgent = hasOwn(agents, name) ? agents[name] : undefined;
-			if (rawAgent !== undefined && !isPlainObject(rawAgent)) {
-				throw new Error(`Cannot update invalid ${SETTINGS_FILE} settings for ${name}`);
-			}
-			const agent = { ...(rawAgent ?? {}) };
-			for (const field of ["tools", "model", "thinkingLevel", "timeoutMs"] as const) {
-				if (!hasOwn(patch, field)) continue;
-				const value = patch[field];
-				if (value === undefined) delete agent[field];
-				else
-					Object.defineProperty(agent, field, {
-						value,
-						enumerable: true,
-						configurable: true,
-						writable: true,
-					});
-			}
-			if (Object.keys(agent).length > 0) {
-				Object.defineProperty(agents, name, {
-					value: agent,
-					enumerable: true,
-					configurable: true,
-					writable: true,
-				});
-			} else {
-				delete agents[name];
-			}
-		}
-
-		const normalized = normalizeSubagentSettings({
-			...raw,
-			...(Object.keys(agents).length > 0 ? { agents } : {}),
-		});
-		if (!normalized) throw new Error(`Cannot update invalid ${SETTINGS_FILE} agent settings`);
-		const updated = { ...raw };
-		if (Object.keys(agents).length > 0) updated.agents = agents;
-		else delete updated.agents;
-		writeSettingsObjectUnlocked(updated, update.replaceCanonical);
-	});
-}
-
-interface SettingsObjectForUpdate {
-	document: Record<string, unknown>;
-	replaceCanonical: boolean;
-}
-
-function readSettingsObjectForUpdate(): SettingsObjectForUpdate {
-	const { canonicalPath, activePath } = resolveSubagentSettingsPaths();
-	if (activePath === undefined) return { document: {}, replaceCanonical: false };
-	const activeFile = path.basename(activePath);
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(fs.readFileSync(activePath, "utf8"));
-	} catch {
-		throw new Error(`Cannot update malformed ${activeFile}`);
-	}
-	if (!isPlainObject(parsed) || !normalizeSubagentSettings(parsed)) {
-		throw new Error(`Cannot update invalid ${activeFile}`);
-	}
-	return { document: parsed, replaceCanonical: activePath === canonicalPath };
-}
-
-function writeSettingsObject(settings: object, replaceCanonical?: boolean): void {
-	withSettingsMutationLock(() => writeSettingsObjectUnlocked(settings, replaceCanonical));
-}
-
-function writeSettingsObjectUnlocked(settings: object, replaceCanonical?: boolean): void {
-	const agentDir = getAgentDir();
-	fs.mkdirSync(agentDir, { recursive: true });
-	const configPath = path.join(agentDir, SETTINGS_FILE);
-	const tempFile = path.join(agentDir, `.${SETTINGS_FILE}.${randomUUID()}.tmp`);
-	// Updates seeded from a missing or legacy document must remain exclusive even if the
-	// canonical path appears after the read and before publication.
-	const firstCanonicalPublication = !(replaceCanonical ?? pathEntryExists(configPath));
-	try {
-		fs.writeFileSync(tempFile, `${JSON.stringify(settings, null, "\t")}\n`, {
-			encoding: "utf8",
-			flag: "wx",
-		});
-		if (firstCanonicalPublication && pathEntryExists(configPath)) {
-			throw new Error(`${SETTINGS_FILE} was created concurrently; reopen settings and retry`);
-		}
-		fs.renameSync(tempFile, configPath);
-	} finally {
-		try {
-			fs.rmSync(tempFile, { force: true });
-		} catch {
-			// Preserve the save result if best-effort temp cleanup fails.
-		}
-	}
-}
-
-function withSettingsMutationLock<T>(mutate: () => T): T {
-	const lockfile = require("proper-lockfile") as typeof import("proper-lockfile");
-	const agentDir = getAgentDir();
-	fs.mkdirSync(agentDir, { recursive: true });
-	const configPath = path.join(agentDir, SETTINGS_FILE);
-	const release = lockfile.lockSync(configPath, {
-		fs: SETTINGS_LOCK_FS_ADAPTER,
-		lockfilePath: `${configPath}.mutation-lock`,
-		realpath: false,
-	});
-	try {
-		return mutate();
-	} finally {
-		release();
-	}
-}
-
-function sameStatefulLimits(left: StatefulLimits, right: StatefulLimits): boolean {
-	return STATEFUL_LIMIT_FIELDS.every((field) => left[field] === right[field]);
-}
-
-export function uniqueToolNames(tools: string[]): string[] {
-	return [...new Set(tools)];
-}
-
-export function sameToolSet(left: string[], right: string[]): boolean {
-	const leftSet = new Set(left);
-	const rightSet = new Set(right);
-	if (leftSet.size !== rightSet.size) return false;
-	return [...leftSet].every((tool) => rightSet.has(tool));
-}
-
-export function resolveSubagentThinkingLevel(
-	agents: readonly Pick<AgentConfig, "name" | "thinkingLevel">[],
-	agentName: string,
-	topLevelThinkingLevel?: SubagentThinkingLevel,
-	localThinkingLevel?: SubagentThinkingLevel,
-): SubagentThinkingLevel | undefined {
-	return (
-		localThinkingLevel ??
-		topLevelThinkingLevel ??
-		agents.find((agent) => agent.name === agentName)?.thinkingLevel
-	);
-}
-
-export function hasAnyAgentOverride(config: SubagentAgentConfig): boolean {
-	return (
-		hasOwn(config, "tools") ||
-		hasOwn(config, "model") ||
-		hasOwn(config, "thinkingLevel") ||
-		hasOwn(config, "timeoutMs")
-	);
-}

package/src/spawn-idempotency.ts

@@ -1,68 +0,0 @@
-import { createHash } from "node:crypto";
-import type { AgentScope, SubagentThinkingLevel } from "./agents/types.js";
-import type { CompletionRequirementMode } from "./completion-requirement.js";
-import type { DelegationContract } from "./delegation-contract.js";
-import type { SubagentResultFormat } from "./result-contract.js";
-
-export const MAX_SPAWN_IDEMPOTENCY_KEY_LENGTH = 256;
-
-export interface CanonicalSpawnRequest {
-	agent: string;
-	taskName?: string;
-	task: string;
-	cwd: string;
-	agentScope: AgentScope;
-	thinkingLevel?: SubagentThinkingLevel;
-	timeoutMs?: number;
-	idleTimeoutMs?: number;
-	maxTurns?: number;
-	maxToolCalls?: number;
-	parentId?: string;
-	context?: string;
-	contextSourceIds: readonly string[];
-	workspaceMode: "shared" | "worktree";
-	allowConcurrentWrites: boolean;
-	contract?: DelegationContract;
-	resultFormat: SubagentResultFormat;
-	completionRequirement?: CompletionRequirementMode;
-}
-
-export function hashSpawnRequest(request: CanonicalSpawnRequest): string {
-	return createHash("sha256")
-		.update(
-			JSON.stringify({
-				agent: request.agent,
-				...(request.taskName === undefined ? {} : { taskName: request.taskName }),
-				task: request.task,
-				cwd: request.cwd,
-				agentScope: request.agentScope,
-				thinkingLevel: request.thinkingLevel ?? null,
-				...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
-				...(request.idleTimeoutMs === undefined ? {} : { idleTimeoutMs: request.idleTimeoutMs }),
-				...(request.maxTurns === undefined ? {} : { maxTurns: request.maxTurns }),
-				...(request.maxToolCalls === undefined ? {} : { maxToolCalls: request.maxToolCalls }),
-				parentId: request.parentId ?? null,
-				contextHash: request.context
-					? createHash("sha256").update(request.context).digest("hex")
-					: null,
-				contextSourceIds: [...request.contextSourceIds],
-				workspaceMode: request.workspaceMode,
-				allowConcurrentWrites: request.allowConcurrentWrites,
-				...(request.contract === undefined ? {} : { contract: request.contract }),
-				resultFormat: request.resultFormat,
-				...(request.completionRequirement === "required"
-					? { completionRequirement: "required" }
-					: {}),
-			}),
-		)
-		.digest("hex");
-}
-
-export function assertSpawnIdempotencyKey(value: string | undefined): void {
-	if (value === undefined) return;
-	if (!value || value.length > MAX_SPAWN_IDEMPOTENCY_KEY_LENGTH) {
-		throw new Error(
-			`subagent_spawn idempotencyKey must contain 1-${MAX_SPAWN_IDEMPOTENCY_KEY_LENGTH} characters`,
-		);
-	}
-}

package/src/stateful-agent-view.ts

@@ -1,85 +0,0 @@
-import { MAX_TOOL_MESSAGE_BYTES, truncateUtf8 } from "./limits.js";
-import type { ManagedAgent } from "./registry.js";
-
-export function formatStatefulAgentLine(agent: ManagedAgent, now = Date.now()): string {
-	const elapsedSeconds = Math.max(0, Math.floor((now - agent.updatedAt) / 1000));
-	const task = agent.currentTask ? ` — ${sanitizeStatusLine(agent.currentTask, 80)}` : "";
-	const unread = agent.mailbox.filter((message) => !message.readAt).length;
-	const indent = "  ".repeat(agent.depth);
-	return `${indent}${sanitizeStatusLine(agent.taskPath ?? agent.id, 256)} · ${sanitizeStatusLine(agent.agent, 128)} · ${agentStateLabel(agent.state)} · updated ${elapsedSeconds}s ago · ${unread} unread${task}`;
-}
-
-export function summarizeStatefulAgent(agent: ManagedAgent) {
-	return {
-		id: agent.id,
-		taskName: agent.taskName,
-		taskPath: agent.taskPath,
-		agent: agent.agent,
-		parentId: agent.parentId,
-		rootId: agent.rootId,
-		depth: agent.depth,
-		children: [...agent.children],
-		state: agent.state,
-		createdAt: agent.createdAt,
-		updatedAt: agent.updatedAt,
-		cwd: agent.cwd,
-		workspaceMode: agent.workspaceMode ?? "shared",
-		thinkingLevel: agent.thinkingLevel,
-		timeoutMs: agent.timeoutMs,
-		currentTimeoutMs: agent.currentTimeoutMs,
-		idleTimeoutMs: agent.idleTimeoutMs,
-		currentIdleTimeoutMs: agent.currentIdleTimeoutMs,
-		maxTurns: agent.maxTurns,
-		currentMaxTurns: agent.currentMaxTurns,
-		maxToolCalls: agent.maxToolCalls,
-		currentMaxToolCalls: agent.currentMaxToolCalls,
-		currentTask: agent.currentTask
-			? truncateUtf8(agent.currentTask, MAX_TOOL_MESSAGE_BYTES).text
-			: undefined,
-		historyCount: agent.history.length,
-		unreadMessages: agent.mailbox.filter((message) => !message.readAt).length,
-		context: {
-			turns: agent.contextTurns ?? 0,
-			sources: agent.contextSourceIds?.length ?? 0,
-			bytes: agent.contextBytes ?? 0,
-			truncated: agent.contextTruncated === true,
-		},
-		resultFormat: agent.resultFormat ?? "text",
-		completionRequirements: (agent.completionRequirements ?? []).map((record) => ({
-			...record,
-		})),
-		structuredResult: agent.structuredResult,
-		termination: agent.termination,
-		outcome: agent.outcome,
-		executionPlan: agent.executionPlan,
-		capabilityGrant: agent.capabilityGrant,
-		semanticCompatibility: agent.semanticCompatibility,
-		semanticSnapshotDigest: agent.semanticSnapshot?.digest,
-		telemetry: agent.telemetry,
-		error: agent.error ? truncateUtf8(agent.error, MAX_TOOL_MESSAGE_BYTES).text : undefined,
-		target: agent.target,
-		policy: agent.policy,
-	};
-}
-
-function agentStateLabel(state: ManagedAgent["state"]): string {
-	switch (state) {
-		case "running":
-			return "working";
-		case "completed":
-			return "finished";
-		default:
-			return state;
-	}
-}
-
-function sanitizeStatusLine(value: string, maxLength: number): string {
-	return (
-		value
-			.slice(0, maxLength)
-			// biome-ignore lint/suspicious/noControlCharactersInRegex: Escape untrusted terminal controls.
-			.replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ")
-			.replace(/\s+/gu, " ")
-			.trim()
-	);
-}

package/src/stateful-config.ts

@@ -1,13 +0,0 @@
-import type { CompletionDelivery, SubagentTransportKind } from "./agents/types.js";
-
-export function resolveStatefulTransportKind(
-	value: SubagentTransportKind | undefined,
-): SubagentTransportKind {
-	return value ?? "subprocess";
-}
-
-export function resolveCompletionDelivery(
-	value: CompletionDelivery | undefined,
-): CompletionDelivery {
-	return value ?? "next-turn";
-}

package/src/stateful-guidance.ts

@@ -1,29 +0,0 @@
-export function createSpawnPromptGuidelines(blockingEnabled = true): string[] {
-	return [
-		"Do not use subagent_spawn for simple or critical-path work that the main agent can perform directly. The main agent retains overall planning, immediate critical-path work, integration, final verification, and the final answer.",
-		"Before one ordinary subagent_spawn, identify concrete useful non-overlapping main-agent work you can start immediately and a supported completion integration path. If none exists, perform the task directly instead of calling subagent_spawn.",
-		"Give subagent_spawn a concise unique taskName using lowercase letters, digits, and underscores so the retained agent has a stable canonical task path.",
-		"Set subagent_spawn thinkingLevel to the lowest sufficient thinking level for the delegated task: use off or minimal for extraction, formatting, or mechanical work; low for straightforward bounded work; medium for ordinary multi-step research or implementation; high for complex debugging, design, review, or cross-file analysis; xhigh for highly ambiguous, cross-system, or high-risk analysis; and max only for the hardest tasks when quality clearly outweighs latency and cost. Omit subagent_spawn thinkingLevel only to preserve the agent or child default.",
-		"Set subagent_spawn timeoutMs to the shortest realistic work deadline for the task difficulty; use idleTimeoutMs for stalled work and maxTurns or maxToolCalls to stop repeated work without progress. Scope the task to the smallest named files or questions. When setting subagent_spawn maxTurns or maxToolCalls, leave sufficient headroom for discovery, evidence reads, and final synthesis; otherwise omit them instead of guessing speculative tight values. Split oversized tasks instead of extending budgets merely to compensate for broad scope.",
-		"For an ordinary subagent_spawn, omit contract; use a delegation contract only when explicit acceptance, authority, evidence, or admission semantics are required.",
-		"Do not set subagent_spawn contract enforcement to enforce with requestedAuthority readPaths, writePaths, network, or secrets; those guarantees are unsupported and reject before child launch, while capabilities and tools remain enforceable.",
-		"If subagent_spawn rejects an unsupported guarantee, retry once with those fields removed or enforcement set to audit only when they were advisory; when any field is a required security boundary, stop instead of weakening it.",
-		"Read the current pi-subagents session-guidance message before choosing detached completion behavior. With next-turn delivery, use subagent_spawn only when the current response does not depend on its result unless useful overlap ends with an intentional subagent_await. With auto-resume delivery, final-answer-dependent detached work may continue asynchronously.",
-		'Track every final-answer-dependent subagent_spawn by setting completionRequirement to "required" and retaining its returned agentId or taskPath; treat interim output as progress, and synthesize only after every corresponding completion message is visible or terminal.',
-		"Keep ordinary review in the main agent with a review skill and deterministic checks; use subagent_spawn for detached review only when consequential independent verification has concrete parallel value.",
-		"Use a single subagent_spawn for a bounded implementation slice with clear ownership only when it can run beside the identified main-agent work.",
-		"Use a single subagent_spawn without concurrent main-agent work only for an explicit user-requested specialist model, tool profile, or isolation boundary.",
-		...(blockingEnabled
-			? [
-					"The subagent tool is deprecated; do not select it merely because synchronous output is required. Prefer subagent_spawn with supported completion delivery, and use subagent_await only after useful overlapping main-agent work is complete and an intentional join is required.",
-					"Use deprecated subagent instead of subagent_spawn only for an existing caller or an explicit user request whose blocking chain, fan-in, panel, or workflow semantics do not yet have a detached replacement; queued steering cannot be processed until it returns.",
-				]
-			: []),
-		"Add another subagent_spawn only for truly independent work with safe workspace concurrency and disjoint write ownership; shared workspaces permit concurrent writes by default, so use workspaceMode worktree when repository isolation is required. The main agent still owns integration.",
-		"After subagent_spawn returns, immediately continue the identified local task; do not merely announce the spawn, wait, poll, or end the response while useful local work remains.",
-		"When completionRequirement required subagent_spawn work remains active after local work is exhausted, emit at most one brief progress sentence and end the turn; do not repeat waiting updates or use the requested final format, verdict, or conclusion until every required completion is visible or terminal. Current Pi versions do not enforce a hard pre-display barrier.",
-		"Do not duplicate assigned work from subagent_spawn while its retained agent is running; use a bounded parent fallback only after its completion reports failure or insufficient evidence.",
-		'Consume and synthesize available subagent_spawn completion messages; use subagent_manage with action "interrupt" or "close" for agents that are no longer needed.',
-		'Completion from subagent_spawn is delivered automatically. Do not poll with subagent_inspect or subagent_mailbox action "read", repeatedly check progress, or duplicate the delegated work.',
-	];
-}