pi-subagents 0.56.0 → 0.58.0

package/src/shared/types.ts

@@ -14,6 +14,7 @@ import type { AuthorityPolicyConfig } from "../policy/authority.ts";
 import type { ThinkingLevel } from "./model-info.ts";
 import type { GlobalMissionIndexRecord, MissionRecord, MissionStoreConfig } from "../missions/types.ts";
 import type { ExtensionBindings } from "../runs/shared/extension-bindings.ts";
+import type { WorkflowChildPermitContext } from "./workflow-child-permit.ts";
 
 // ============================================================================
 // Basic Types
@@ -75,16 +76,48 @@ export interface WorkflowGraphSnapshot {
 
 export type WorkflowReceiptState = "complete" | "failed" | "paused" | "stopped";
 
+export type WorkflowTerminalResolution = "settled-awaiting-resume" | "failed-child" | "interrupted-child";
+
+export interface WorkflowTerminalOutcome {
+	state: "partial";
+	reason: "budget_exhausted" | "timeout";
+}
+
+export interface WorkflowRecoveryAction {
+	key: string;
+	call: "runs.run";
+	resume: { workflowRunId: string; key: string; latest: true };
+	taskRequired: true;
+}
+
+export interface WorkflowChildSummaryV1 {
+	version: 1;
+	parentToolCallId: string;
+	workflowRunId: string;
+	inventoryComplete: boolean;
+	workflowState: "queued" | "running" | "completed" | "failed" | "paused" | "stopped";
+	children: Array<{
+		childId: string;
+		runId?: string;
+		agent?: string;
+		model?: string;
+		thinking?: string;
+		state: "pending" | "running" | "completed" | "failed" | "paused" | "stopped" | "rejected" | "detached";
+	}>;
+}
+
 type WorkflowReceiptEntryResumability =
 	| { latestRunId: string; resumability: { state: "resumable" } }
 	| { latestRunId?: string; resumability: { state: "not-resumable"; reason: string } };
 
 export type WorkflowReceiptEntry = WorkflowReceiptEntryResumability & {
 	key: string;
+	terminalOutcome?: WorkflowTerminalOutcome;
 	agent?: string;
 	requestedContext?: "fresh" | "fork";
 	resolvedContext?: "fresh" | "fork" | "mixed";
 	outputReference?: string;
+	externalAdapter?: ExternalCliReceiptMetadata;
 	continuation: { runIds: string[] };
 };
 
@@ -94,6 +127,10 @@ export interface WorkflowReceipt {
 	state: WorkflowReceiptState;
 	createdAt: number;
 	entries: Record<string, WorkflowReceiptEntry>;
+	workflowChildren?: WorkflowChildSummaryV1;
+	workflowResolution?: WorkflowTerminalResolution;
+	terminalOutcome?: WorkflowTerminalOutcome;
+	recovery?: WorkflowRecoveryAction[];
 }
 
 export interface SavedOutputReference {
@@ -166,6 +203,10 @@ export interface TokenUsage {
 	input: number;
 	output: number;
 	total: number;
+	/** Input plus cache-read tokens for the latest assistant turn. */
+	window?: number;
+	/** Largest window observed in this usage scope. */
+	windowPeak?: number;
 }
 
 export type ActivityState = "active_long_running" | "needs_attention";
@@ -352,8 +393,24 @@ export interface FileMutationEffect {
 	evidence?: TrackedMutationEvidence;
 }
 
+export interface SettlementDiagnostic {
+	finalTextPresent: boolean;
+	mutation: {
+		expected: boolean;
+		attempted: boolean;
+		observed: boolean;
+	};
+	requiredOutput?: {
+		kind: "file-only" | "structured";
+		path: string;
+		missing: boolean;
+	};
+	afterCompactionSettlement?: boolean;
+}
+
 export interface EffectsProjection {
 	fileMutation?: FileMutationEffect;
+	settlementDiagnostic?: SettlementDiagnostic;
 }
 
 export interface TrackedMutationSnapshot {
@@ -582,9 +639,11 @@ export interface SteeringRecoveryDescriptor {
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
 	mcpDirectTools?: string[];
+	mutationTools?: string[];
 	systemPrompt?: string;
 	systemPromptMode: "append" | "replace";
 	inheritProjectContext: boolean;
+	inheritGlobalContext: boolean;
 	inheritSkills: boolean;
 	skills?: string[];
 	skillPath?: string[];
@@ -703,6 +762,8 @@ export interface AgentProgress {
 	thinking?: string;
 	inputTokens?: number;
 	outputTokens?: number;
+	window?: number;
+	windowPeak?: number;
 	durationMs: number;
 	error?: string;
 	failedTool?: string;
@@ -1044,6 +1105,8 @@ export interface SingleResult {
 	watchdog?: ChildWatchdogProgress;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	capabilityAudit?: SubagentCapabilityAudit;
+	runner?: ExternalCliRunnerStatus | ExternalJobRunnerStatus;
+	externalProcess?: ExternalProcessStatus;
 }
 
 export interface SpawnBudgetGrant {
@@ -1090,6 +1153,7 @@ export interface WaitCompletion {
 	/** Versioned bounded output archive retained with the durable completion replay. */
 	archivePath?: string;
 	results?: WaitCompletionChild[];
+	workflowChildren?: WorkflowChildSummaryV1;
 }
 
 export interface Details {
@@ -1100,6 +1164,7 @@ export interface Details {
 	/** Run-level context summary. "mixed" when children resolved to different modes. */
 	context?: "fresh" | "fork" | "mixed";
 	results: SingleResult[];
+	workflowChildren?: WorkflowChildSummaryV1;
 	/**
 	 * Terminal completion payloads for runs this subagent_wait call observed
 	 * finishing. Async completions travel as result files that are consumed and
@@ -1375,9 +1440,11 @@ export type AgentRunnerConfig =
 	| { type: "pi" }
 	| {
 		type: "external-cli";
+		adapter?: "codex-exec" | "codex-exec-writer" | "claude-code" | "claude-code-writer" | "cursor-agent" | "cursor-agent-writer";
 		command: string;
 		args?: string[];
 		promptDelivery?: "stdin";
+		capabilities?: ExternalCliCapabilityNarrowing;
 	}
 	| {
 		type: "external-job";
@@ -1385,18 +1452,46 @@ export type AgentRunnerConfig =
 		options?: Record<string, unknown>;
 	};
 
+export type ExternalCliCapabilityNarrowing = Partial<Record<"steer" | "resume" | "structuredOutput" | "toolEvents" | "supervisor" | "forkContext" | "extensionBindings", false>>;
+
+export interface ExternalCliCapabilities {
+	stop: true;
+	steer: false;
+	resume: false;
+	structuredOutput: false;
+	toolEvents: false;
+	supervisor: "unsupported";
+	forkContext: false;
+	extensionBindings: false;
+}
+
+export interface ExternalCliReceiptMetadata {
+	adapter: { id: "external-cli" | "codex-exec" | "codex-exec-writer" | "claude-code" | "claude-code-writer" | "cursor-agent" | "cursor-agent-writer" | "grok-build"; version: 1; executionMode: "one-shot-stdin" | "one-shot-prompt-file" };
+	capabilities: ExternalCliCapabilities;
+	safety?:
+		| { sandbox: "read-only"; approvalPolicy: "never"; ephemeral: true }
+		| { access: "workspace-write"; sandbox: "workspace-write"; approvalPolicy: "never"; ephemeral: true }
+		| { permissionMode: "plan"; tools: "none"; mcp: "empty-strict"; settingSources: "none"; sessionPersistence: false }
+		| { access: "read-only"; authentication: "existing-cli-required"; permissionMode: "plan"; tools: "none"; mcp: "empty-strict"; settingSources: "user"; userSettingsTrust: "required"; sessionPersistence: false }
+		| { access: "workspace-write"; authentication: "existing-cli-required"; permissionMode: "acceptEdits"; tools: "Read,Write,Edit,Glob,Grep"; mcp: "empty-strict"; settingSources: "user"; userSettingsTrust: "required"; sessionPersistence: false }
+		| { access: "read-only"; authentication: "cursor-api-key-or-existing-login"; mode: "ask"; sandbox: "enabled"; workspaceTrust: "existing-required"; sessionReuse: false }
+		| { access: "workspace-write"; authentication: "cursor-api-key-or-existing-login"; mode: "print"; sandbox: "enabled"; workspaceTrust: "existing-required"; sessionReuse: false };
+	outputArtifacts?: { stdoutPath?: string; stderrPath?: string; finalOutputPath?: string };
+	handoff: { mode: "fresh" };
+	supervisor: { mode: "unsupported"; reason: string };
+	nonResumableReason: string;
+}
+
 export interface ExternalCliRunnerStatus {
 	type: "external-cli";
 	command: string;
 	args: string[];
-	promptDelivery: "stdin";
-	capabilities: {
-		stop: true;
-		steer: false;
-		resume: false;
-		structuredOutput: false;
-		toolEvents: false;
-	};
+	promptDelivery: "stdin" | "prompt-file";
+	adapter: ExternalCliReceiptMetadata["adapter"];
+	safety?: ExternalCliReceiptMetadata["safety"];
+	capabilities: ExternalCliCapabilities;
+	unsupportedReasons: Record<Exclude<keyof ExternalCliCapabilities, "stop">, string>;
+	nonResumableReason: string;
 }
 
 export interface ExternalJobRunnerStatus {
@@ -1443,6 +1538,11 @@ export interface ExternalProcessStatus {
 	processSignal?: string | null;
 	stdoutPath: string;
 	stderrPath: string;
+	finalOutputPath?: string;
+	stdoutBytes?: number;
+	stderrBytes?: number;
+	stdoutTruncated?: boolean;
+	stderrTruncated?: boolean;
 }
 
 export interface AsyncStatus {
@@ -1499,6 +1599,7 @@ export interface AsyncStatus {
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	capabilityAudit?: SubagentCapabilityAudit;
 	workflow?: Details["workflow"];
+	workflowChildren?: WorkflowChildSummaryV1;
 	parentWorkflowRunId?: string;
 	workflowKey?: string;
 	/** Set when a durable schedule launched this run, so completions can name their origin. */
@@ -1557,6 +1658,7 @@ export interface AsyncStatus {
 		skills?: string[];
 		model?: string;
 		thinking?: string;
+		contextLimit?: number;
 		thinkingCeiling?: ThinkingLevel;
 		attemptedModels?: string[];
 		modelAttempts?: ModelAttempt[];
@@ -1654,6 +1756,7 @@ export interface AsyncJobState {
 	parentWorkflowRunId?: string;
 	workflowKey?: string;
 	workflow?: Details["workflow"];
+	workflowChildren?: WorkflowChildSummaryV1;
 }
 
 export interface ForegroundResumeChild {
@@ -1671,6 +1774,8 @@ export interface ForegroundResumeChild {
 	currentPath?: string;
 	turnCount?: number;
 	tokens?: number;
+	window?: number;
+	windowPeak?: number;
 	toolCount?: number;
 	exitCode?: number;
 	error?: string;
@@ -1685,6 +1790,14 @@ export interface ForegroundResumeChild {
 	detachedReason?: string;
 	acceptance?: AcceptanceLedger;
 	agentContract?: AgentContract;
+	/** Private bounded launch fields needed to preserve the child contract on resume. */
+	resumeContract?: {
+		outputSchema?: JsonSchemaObject;
+		agentContract?: AgentContract;
+		acceptance?: AcceptanceInput;
+		output?: string | boolean;
+		outputMode?: OutputMode;
+	};
 	launchContractDigest?: string;
 	/** Private retained launch authority. Never project into status or result output. */
 	extensionBindings?: ExtensionBindings;
@@ -1723,6 +1836,8 @@ export interface ForegroundChildControl {
 	tokens?: number;
 	inputTokens?: number;
 	outputTokens?: number;
+	window?: number;
+	windowPeak?: number;
 	model?: string;
 	thinking?: string;
 	toolCount?: number;
@@ -1758,6 +1873,8 @@ export interface ForegroundRunControl {
 	tokens?: number;
 	inputTokens?: number;
 	outputTokens?: number;
+	window?: number;
+	windowPeak?: number;
 	model?: string;
 	thinking?: string;
 	toolCount?: number;
@@ -1808,6 +1925,8 @@ export interface SubagentState {
 	parentSessionFile?: string | null;
 	/** Extension-owned roots trusted for child session transcript reads. */
 	trustedSessionRoots?: string[];
+	/** Pi sessions base that caps exact runtime-recorded session file trust. */
+	trustedSessionFileRoot?: string;
 	/** Live async session roots created by this parent executor, keyed by run id. */
 	liveAsyncSessionRoots?: Map<string, string>;
 	/** Last valid parent session model observed for this session; used when continuation contexts omit ctx.model. */
@@ -1932,6 +2051,8 @@ export interface SubagentChildStatusEvent {
 // ============================================================================
 
 export interface RunSyncOptions {
+	/** Exact discovery provenance for an unknown-agent error; omission uses defensive fallback discovery. */
+	unknownAgentDiagnosticContext?: import("../agents/agents.ts").UnknownAgentDiagnosticContext;
 	/** Opt-in global permission rules; missing tools remain allowed. */
 	permissions?: import("../runs/shared/permissions.ts").PermissionConfig;
 	/** Session id of the direct parent session for permission-system ask forwarding. */
@@ -1943,6 +2064,8 @@ export interface RunSyncOptions {
 	/** Resolved launch context for this child. */
 	context?: "fresh" | "fork";
 	cwd?: string;
+	/** Original cwd input retained for launch diagnostics. */
+	requestedCwd?: string;
 	signal?: AbortSignal;
 	interruptSignal?: AbortSignal;
 	timeoutMs?: number;
@@ -1998,10 +2121,14 @@ export interface RunSyncOptions {
 	thinkingOverride?: AgentConfig["thinking"];
 	thinkingCeiling?: ThinkingLevel;
 	extensionBindings?: ExtensionBindings;
+	/** Package-internal one-use authorization for one foreground workflow child. */
+	workflowChildPermitLaunch?: WorkflowChildPermitContext;
 	/** Registry models available for heuristic bare-model resolution */
-	availableModels?: Array<{ provider: string; id: string; fullId: string }>;
+	availableModels?: Array<{ provider: string; id: string; fullId: string; contextWindow?: number }>;
 	/** Current parent-session provider to prefer for ambiguous bare model ids */
 	preferredModelProvider?: string;
+	/** Parent Pi event host used to snapshot runtime-registered MCP servers before child launch. */
+	runtimeSnapshotHost?: import("../runs/shared/mcp-direct-tool-allowlist.ts").McpRuntimeSnapshotHost;
 	/** Optional subagent model-scope enforcement for fallback candidates */
 	modelScope?: ModelScopeRule | ModelScopeRule[];
 	/** Skills to make available (overrides agent default if provided) */
@@ -2063,6 +2190,11 @@ export interface ScheduledRunsConfig {
 	storeRoot?: string;
 }
 
+export interface ModelExclusionsConfig {
+	/** Default duration in milliseconds. A lower configured value also shortens active cached exclusions. */
+	defaultTtlMs?: number;
+}
+
 export type FleetViewPlacement = "aboveEditor" | "belowEditor";
 
 export const FLEET_KEYBINDING_ACTIONS = [
@@ -2097,10 +2229,24 @@ export interface MainWindowRendererConfig {
 	compactResultMaxLines?: number;
 }
 
+export interface ForkContextConfig {
+	/** Keep the complete fork by default, or summarize large text-only tool results before launch. */
+	mode?: "full" | "pruned";
+	/** Required pruning model when mode is "pruned". */
+	model?: string;
+}
+
+export interface ActiveAsyncCapacityConfig {
+	/** Reclaim failed runner slots after this age when process proof is unknown; false keeps strict retention. */
+	abandonedSlotReleaseAfterMs?: number | false;
+}
+
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
 	/** Set the context for launches that omit an explicit context. */
 	defaultSubagentContext?: "fresh" | "fork";
+	/** Configure how every resolved fork session is prepared before child spawn. */
+	forkContext?: ForkContextConfig;
 	/** Optional shortcut that detaches the active foreground single-subagent run. */
 	foregroundDetachShortcut?: string;
 	/** Show the Claude Code-style navigable fleet. Defaults to true. */
@@ -2111,6 +2257,8 @@ export interface ExtensionConfig {
 	fleetKeybindings?: FleetKeybindingsConfig;
 	/** Show the under-editor async runs widget. Defaults to true, including when FleetView is enabled. */
 	asyncWidget?: boolean;
+	/** Configure the process-wide TTL policy for persisted model exclusions. */
+	modelExclusions?: ModelExclusionsConfig;
 	/** Tool description variant registered for the parent-facing subagent tool. Defaults to split metadata. */
 	toolDescriptionMode?: ToolDescriptionMode;
 	/** Inline chat rendering for the subagent tool. Defaults to rich. */
@@ -2130,6 +2278,8 @@ export interface ExtensionConfig {
 	maxSubagentSpawnsPerRun?: number;
 	/** Optional active top-level async run cap per parent session. Unset or 0 means unlimited. */
 	maxActiveAsyncRunsPerSession?: number;
+	/** Active-capacity cleanup policy. */
+	capacity?: ActiveAsyncCapacityConfig;
 	/** Global cap on simultaneously-running subagent tasks within a single run. Defaults to 20. */
 	globalConcurrencyLimit?: number;
 	/**
@@ -2285,7 +2435,7 @@ export const POLL_INTERVAL_MS = 250;
 export const WIDGET_ANIMATION_INTERVAL_MS = 1000;
 export const MAX_WIDGET_JOBS = 4;
 export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
-export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "guide", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.resolve-decision", "mission.attach-run", "mission.close", "worktree.discard", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "debug.run", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "dismiss", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;
+export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "guide", "validate", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.resolve-decision", "mission.attach-run", "mission.close", "worktree.discard", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "debug.run", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "dismiss", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;
 
 export const DEFAULT_FORK_PREAMBLE =
 	"You are a delegated subagent running from a fork of the parent session. " +

package/src/shared/utils.ts

@@ -1,7 +1,3 @@
-/**
- * General utility functions for the subagent extension
- */
-
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -10,10 +6,6 @@ import { previewDisplayText, sanitizeDisplayText, truncateDisplayText } from "./
 import { formatToolCall } from "./formatters.ts";
 import type { AgentProgress, AsyncStatus, Details, DisplayItem, ErrorInfo, NestedRunSummary, SingleResult, ToolCallSummary, Usage } from "./types.ts";
 
-// ============================================================================
-// File System Utilities
-// ============================================================================
-
 const DEFAULT_CONFIG_DIR_NAME = ".pi";
 const PI_CODING_AGENT_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
 export const PI_CODING_AGENT_PACKAGE_ROOT_ENV = "PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT";
@@ -96,9 +88,10 @@ export function getProjectConfigDir(projectRoot: string): string {
 
 export function getAgentDir(): string {
 	const configured = process.env.PI_CODING_AGENT_DIR;
-	if (configured === "~") return os.homedir();
-	if (configured?.startsWith("~/")) return path.join(os.homedir(), configured.slice(2));
-	return configured || path.join(os.homedir(), getConfigDirName(), "agent");
+	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+	if (configured === "~") return home;
+	if (configured?.startsWith("~/") || configured?.startsWith("~\\")) return path.join(home, configured.slice(2));
+	return configured || path.join(home, getConfigDirName(), "agent");
 }
 
 const statusCache = new Map<string, { mtime: number; ctime: number; size: number; ino: number; status: AsyncStatus }>();
@@ -253,10 +246,7 @@ function getOutputTail(outputFile: string | undefined, maxLines: number = 3): st
 	}
 }
 
-/**
- * Get human-readable last activity time for a file
- */
-	export function getLastActivity(outputFile: string | undefined): string {
+export function getLastActivity(outputFile: string | undefined): string {
 	if (!outputFile) return "";
 	try {
 		const stat = fs.statSync(outputFile);
@@ -265,14 +255,11 @@ function getOutputTail(outputFile: string | undefined, maxLines: number = 3): st
 		if (ago < 60000) return `active ${Math.floor(ago / 1000)}s ago`;
 		return `active ${Math.floor(ago / 60000)}m ago`;
 	} catch {
-		// Last-activity text is best effort; missing files should simply omit the hint.
+		// Last-activity text is best effort; missing files should omit the hint.
 		return "";
 	}
 }
 
-/**
- * Find the latest session file in a directory
- */
 export function findLatestSessionFile(sessionDir: string): string | null {
 	if (!fs.existsSync(sessionDir)) return null;
 	const files = fs.readdirSync(sessionDir)
@@ -289,9 +276,6 @@ export function findLatestSessionFile(sessionDir: string): string | null {
 	return latest ? latest.path : null;
 }
 
-/**
- * Write a prompt to a temporary file
- */
 function writePrompt(agent: string, prompt: string): { dir: string; path: string } {
 	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
 	const p = path.join(dir, `${agent.replace(/[^\w.-]/g, "_")}.md`);
@@ -299,13 +283,6 @@ function writePrompt(agent: string, prompt: string): { dir: string; path: string
 	return { dir, path: p };
 }
 
-// ============================================================================
-// Message Parsing Utilities
-// ============================================================================
-
-/**
- * Get the final text output from a list of messages
- */
 export function getFinalOutput(messages: Message[]): string {
 	const validTextParts: string[] = [];
 	for (let i = messages.length - 1; i >= 0; i--) {

package/src/shared/workflow-child-permit.ts

@@ -0,0 +1,116 @@
+import { stableJsonDigest } from "./launch-contract.ts";
+
+export interface WorkflowChildPermitInput {
+	issuerPackage: string;
+	workflowRunId: string;
+	childKey: string;
+	agent: string;
+	launchContractDigest: string;
+	context: "fresh" | "fork";
+}
+
+export interface WorkflowChildPermitLaunch {
+	workflowRunId: string;
+	childKey: string;
+	agent: string;
+	launchContractDigest: string;
+	context: "fresh" | "fork";
+	runner: "pi";
+}
+
+export interface WorkflowChildPermitContext {
+	permit: WorkflowChildPermit;
+	workflowRunId: string;
+	childKey: string;
+}
+
+export interface WorkflowChildPermit {
+	readonly __workflowChildPermit: unique symbol;
+}
+
+interface WorkflowChildPermitRecord {
+	issuerPackage: string;
+	workflowRunId: string;
+	childKey: string;
+	agent: string;
+	expectedProjectionDigest: string;
+	state: "available" | "claimed" | "consumed";
+}
+
+const records = new WeakMap<object, WorkflowChildPermitRecord>();
+
+function projectionDigest(input: Omit<WorkflowChildPermitLaunch, "workflowRunId">): string {
+	return stableJsonDigest({
+		version: 1,
+		childKey: input.childKey,
+		agent: input.agent,
+		launchContractDigest: input.launchContractDigest,
+		context: input.context,
+		runner: input.runner,
+	});
+}
+
+function required(value: string, label: string): string {
+	if (!value.trim() || value !== value.trim()) throw new Error(`${label} must be a non-empty trimmed string.`);
+	return value;
+}
+
+/** Package-internal first-slice permit. It is opaque, in-memory, and not serializable. */
+export function createWorkflowChildPermit(input: WorkflowChildPermitInput): WorkflowChildPermit {
+	const permit = Object.freeze(Object.create(null)) as WorkflowChildPermit;
+	const record: WorkflowChildPermitRecord = {
+		issuerPackage: required(input.issuerPackage, "issuerPackage"),
+		workflowRunId: required(input.workflowRunId, "workflowRunId"),
+		childKey: required(input.childKey, "childKey"),
+		agent: required(input.agent, "agent"),
+		expectedProjectionDigest: projectionDigest({
+			childKey: input.childKey,
+			agent: input.agent,
+			launchContractDigest: required(input.launchContractDigest, "launchContractDigest"),
+			context: input.context,
+			runner: "pi",
+		}),
+		state: "available",
+	};
+	records.set(permit as object, record);
+	return permit;
+}
+
+export function validateWorkflowChildPermitRoot(permit: WorkflowChildPermit, workflowRunId: string): string | undefined {
+	const record = records.get(permit as object);
+	if (!record) return "Workflow child permit is invalid.";
+	if (record.state !== "available") return "Workflow child permit is already consumed.";
+	if (record.workflowRunId !== workflowRunId) return "Workflow child permit does not match this workflow root.";
+	return undefined;
+}
+
+/** Claim the first distinct launch attempt before validating its model-authored shape. */
+export function claimWorkflowChildPermit(permit: WorkflowChildPermit, workflowRunId: string, childKey: string): string | undefined {
+	const record = records.get(permit as object);
+	if (!record) return "Workflow child permit is invalid.";
+	if (record.state !== "available") return "Workflow child permit is already consumed.";
+	if (record.workflowRunId !== workflowRunId) return "Workflow child permit does not match this workflow root.";
+	record.state = record.childKey === childKey ? "claimed" : "consumed";
+	if (record.childKey !== childKey) return "Workflow child permit child key mismatch.";
+	return undefined;
+}
+
+/** Verify and permanently consume the permit before the one native process spawn. */
+export function consumeWorkflowChildPermit(permit: WorkflowChildPermit, launch: WorkflowChildPermitLaunch): string | undefined {
+	const record = records.get(permit as object);
+	if (!record) return "Workflow child permit is invalid.";
+	if (record.state === "available") return "Workflow child permit launch was not claimed.";
+	if (record.state === "consumed") return "Workflow child permit is already consumed.";
+	if (record.workflowRunId !== launch.workflowRunId) return "Workflow child permit does not match this workflow root.";
+	record.state = "consumed";
+	if (record.childKey !== launch.childKey) return "Workflow child permit child key mismatch.";
+	if (record.agent !== launch.agent) return "Workflow child permit agent mismatch.";
+	if (launch.runner !== "pi") return "Workflow child permit supports native Pi children only.";
+	if (record.expectedProjectionDigest !== projectionDigest(launch)) return "Workflow child permit does not match the final launch projection.";
+	return undefined;
+}
+
+export function workflowChildPermitConsumed(permit: WorkflowChildPermit): boolean {
+	const state = records.get(permit as object)?.state;
+	return state === "claimed" || state === "consumed";
+}

package/src/slash/delegation-adapters.ts

@@ -298,7 +298,6 @@ export function toSubagentDelegationExecutionParams(request: SubagentDelegationR
 		enforceHardTurnLimit: true,
 		toolBudget: request.toolBudget,
 		skill: request.skill,
-		output: false,
 		...(request.result.kind === "structured" ? { outputSchema: request.result.schema } : {}),
 		acceptance: false,
 		artifacts: request.artifacts,

package/src/slash/slash-commands.ts

@@ -3,7 +3,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { keyText, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth, type Component, type KeyId, type TUI } from "@earendil-works/pi-tui";
-import { BUILTIN_AGENT_NAMES, discoverAgents, discoverAgentsAll, findBlockingAgentDiagnostic, resolveAgentName, type AgentConfig, type AgentDiscoveryDiagnostic, type AgentScope } from "../agents/agents.ts";
+import { BUILTIN_AGENT_NAMES, discoverAgents, discoverAgentsAll, findBlockingAgentDiagnostic, formatUnknownAgentError, resolveAgentName, unknownAgentDiagnosticContext, type AgentConfig, type AgentDiscoveryDiagnostic, type AgentScope, type UnknownAgentDiagnosticContext } from "../agents/agents.ts";
 import { listRuntimeAgentConfigs, mergeRuntimeAgents } from "../agents/runtime-agent-registry.ts";
 import { resolveExistingReadPaths } from "../shared/settings.ts";
 import {
@@ -22,6 +22,7 @@ import { listAsyncRuns, formatAsyncRunProgressLabel, type AsyncRunSummary } from
 import { encodeInspectReply, handleInspectRpcArgs, INSPECT_WIDGET_KEY } from "../runs/background/inspect-rpc.ts";
 import { listScheduledRunSummaries } from "../runs/background/scheduled-runs.ts";
 import { SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
+import { FLEET_OPEN_SHORTCUT } from "../shared/shortcuts.ts";
 import type { SlashSubagentResponse, SlashSubagentUpdate } from "./slash-bridge.ts";
 import { registerPromptWorkflowCommands } from "./prompt-workflows.ts";
 import { openSubagentsAdmin } from "./subagents-admin.ts";
@@ -108,9 +109,9 @@ const extractExecutionFlags = (rawArgs: string): { args: string; bg: boolean; fo
 	return { args, bg, fork };
 };
 
-function discoverSlashAgents(pi: ExtensionAPI, cwd: string, scope: AgentScope): { agents: AgentConfig[]; agentDiagnostics?: AgentDiscoveryDiagnostic[] } {
+function discoverSlashAgents(pi: ExtensionAPI, cwd: string, scope: AgentScope): { agents: AgentConfig[]; agentDiagnostics?: AgentDiscoveryDiagnostic[]; unknownAgentDiagnosticContext: UnknownAgentDiagnosticContext } {
 	const discovered = discoverAgents(cwd, scope);
-	if (listRuntimeAgentConfigs(pi).length === 0) return discovered;
+	if (listRuntimeAgentConfigs(pi).length === 0) return { ...discovered, unknownAgentDiagnosticContext: unknownAgentDiagnosticContext(discovered) };
 	const all = discoverAgentsAll(cwd);
 	const configuredAgents: AgentConfig[] = [
 		...all.builtin,
@@ -118,7 +119,8 @@ function discoverSlashAgents(pi: ExtensionAPI, cwd: string, scope: AgentScope):
 		...(scope !== "project" ? all.user : []),
 		...(scope !== "user" ? all.project : []),
 	];
-	return mergeRuntimeAgents(pi, discovered, configuredAgents);
+	const merged = mergeRuntimeAgents(pi, discovered, configuredAgents);
+	return { ...merged, unknownAgentDiagnosticContext: { ...unknownAgentDiagnosticContext(discovered), agents: merged.agents } };
 }
 
 const makeAgentCompletions = (pi: ExtensionAPI, state: SubagentState) => (prefix: string) => {
@@ -693,7 +695,7 @@ export function registerSlashCommands(
 				: resolvedAgent.agent;
 			const diagnostic = findBlockingAgentDiagnostic(agentName, candidates, discovered.agentDiagnostics);
 			if (diagnostic || resolvedAgent.error || !resolvedAgent.agent) {
-				ctx.ui.notify(diagnostic ? `Agent '${agentName}' has invalid configuration: ${diagnostic.error}` : resolvedAgent.error ?? `Unknown agent: ${agentName}`, "error");
+				ctx.ui.notify(diagnostic ? `Agent '${agentName}' has invalid configuration: ${diagnostic.error}` : resolvedAgent.error ?? formatUnknownAgentError(agentName, discovered.unknownAgentDiagnosticContext), "error");
 				return;
 			}
 
@@ -776,7 +778,7 @@ export function registerSlashCommands(
 		handler: async (_args, ctx) => showFleet(ctx),
 	});
 
-	pi.registerShortcut(Key.ctrlAlt("f"), {
+	pi.registerShortcut(FLEET_OPEN_SHORTCUT, {
 		description: "Open subagent fleet inspector",
 		handler: async (ctx) => showFleet(ctx),
 	});