pi-subagents 0.49.0 → 0.51.0

package/src/shared/prompt-resources.ts

@@ -1,14 +1,7 @@
-import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { parseFrontmatter } from "../agents/frontmatter.ts";
 import { getAgentDir, getProjectConfigDir } from "./utils.ts";
 
-const PROMPT_REF_PATTERN = /^(package|user|project):([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/;
-const PROMPT_VARIABLE_PATTERN = /\{\{(\w+)\}\}/g;
-
-type PromptVariable = string | number | boolean;
-
 export function getPromptDirectories(cwd: string) {
 	return {
 		package: path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "prompts"),
@@ -16,36 +9,3 @@ export function getPromptDirectories(cwd: string) {
 		project: path.join(getProjectConfigDir(cwd), "prompts"),
 	};
 }
-
-function promptVariables(vars: unknown): Record<string, PromptVariable> {
-	if (vars === undefined) return {};
-	if (!vars || typeof vars !== "object" || Array.isArray(vars)) throw new Error("prompts.render vars must be a plain object.");
-	const prototype = Object.getPrototypeOf(vars);
-	if (prototype !== null && prototype !== Object.prototype) throw new Error("prompts.render vars must be a plain object.");
-	for (const [name, value] of Object.entries(vars)) {
-		if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
-			throw new Error(`prompts.render variable '${name}' must be a string, number, or boolean.`);
-		}
-	}
-	return vars as Record<string, PromptVariable>;
-}
-
-export function renderWorkflowPrompt(ref: string, vars: unknown, cwd: string): string {
-	const match = ref.match(PROMPT_REF_PATTERN);
-	if (!match) throw new Error("prompts.render ref must use package:<name>, user:<name>, or project:<name>.");
-	const scope = match[1] as keyof ReturnType<typeof getPromptDirectories>;
-	const name = match[2]!;
-	const filePath = path.join(getPromptDirectories(cwd)[scope], `${name}.md`);
-	let content: string;
-	try {
-		if (!fs.lstatSync(filePath).isFile()) throw new Error("not a regular file");
-		content = fs.readFileSync(filePath, "utf-8");
-	} catch (error) {
-		const detail = error instanceof Error ? error.message : String(error);
-		throw new Error(`Could not read prompt fragment '${ref}': ${detail}`);
-	}
-	const variables = promptVariables(vars);
-	return parseFrontmatter(content).body.trim().replace(PROMPT_VARIABLE_PATTERN, (placeholder, variable: string) => {
-		return Object.hasOwn(variables, variable) ? String(variables[variable]) : placeholder;
-	});
-}

package/src/shared/settings.ts

@@ -64,6 +64,8 @@ export interface SequentialStep {
 	acceptance?: AcceptanceInput;
 	agentContract?: AgentContract;
 	gateOn?: ChainGateLayer;
+	/** Internal workflow child isolation; public workflowScript supplies this on runs.run. */
+	worktree?: boolean;
 }
 
 /** Parallel task item within a parallel step */
@@ -119,24 +121,6 @@ export interface DynamicParallelStep {
 	gateOn?: ChainGateLayer;
 }
 
-/** Approval checkpoint: pause before later chain steps until parent approval. */
-export interface CheckpointStep {
-	checkpoint: string;
-	message?: string;
-	phase?: string;
-	label?: string;
-	agent?: string;
-	task?: string;
-	as?: string;
-	output?: OutputOverrideInput;
-	outputMode?: OutputMode;
-	reads?: string[] | false;
-	progress?: boolean;
-	skill?: string | string[] | false;
-	skills?: string[] | false;
-	model?: string;
-}
-
 /** Parallel step: multiple agents running concurrently */
 export interface ParallelStep {
 	parallel: ParallelTaskItem[];
@@ -149,16 +133,12 @@ export interface ParallelStep {
 }
 
 /** Union type for chain steps */
-export type ChainStep = SequentialStep | ParallelStep | DynamicParallelStep | CheckpointStep;
+export type ChainStep = SequentialStep | ParallelStep | DynamicParallelStep;
 
 // =============================================================================
 // Type Guards
 // =============================================================================
 
-export function isCheckpointStep(step: ChainStep): step is CheckpointStep {
-	return "checkpoint" in step;
-}
-
 export function isParallelStep(step: ChainStep): step is ParallelStep {
 	return "parallel" in step && Array.isArray((step as ParallelStep).parallel);
 }
@@ -169,9 +149,6 @@ export function isDynamicParallelStep(step: ChainStep): step is DynamicParallelS
 
 /** Get all agent names in a step (single for sequential, multiple for parallel) */
 export function getStepAgents(step: ChainStep): string[] {
-	if (isCheckpointStep(step)) {
-		return [];
-	}
 	if (isParallelStep(step)) {
 		return step.parallel.map((t) => t.agent);
 	}
@@ -239,7 +216,6 @@ export function resolveChainTemplates(
 	steps: ChainStep[],
 ): ResolvedTemplates {
 	return steps.map((step, i) => {
-		if (isCheckpointStep(step)) return "";
 		if (isParallelStep(step)) {
 			// Parallel step: resolve each task's template
 			return step.parallel.map((task) => {

package/src/shared/types.ts

@@ -41,7 +41,7 @@ export type WorkflowNodeStatus = "pending" | "running" | "completed" | "failed"
 
 export interface WorkflowGraphNode {
 	id: string;
-	kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent" | "checkpoint";
+	kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent";
 	agent?: string;
 	phase?: string;
 	label: string;
@@ -61,16 +61,6 @@ export interface WorkflowGraphNode {
 	structured?: boolean;
 	acceptanceStatus?: AcceptanceLedgerStatus;
 	error?: string;
-	checkpoint?: ChainCheckpointState;
-}
-
-export interface ChainCheckpointState {
-	name: string;
-	message?: string;
-	status: "pending" | "approved" | "rejected";
-	stepIndex: number;
-	approvedAt?: number;
-	rejectedAt?: number;
 }
 
 export interface WorkflowGraphSnapshot {
@@ -215,7 +205,7 @@ export interface ControlEvent {
 	nestedRunId?: string;
 	nestingPath?: NestedRunAddress["path"];
 	message: string;
-	reason?: "idle" | "completion_guard" | "active_long_running" | "tool_failures" | "supervisor_request" | "time_threshold" | "turn_threshold" | "token_threshold";
+	reason?: "idle" | "completion_guard" | "active_long_running" | "tool_failures" | "supervisor_request" | "time_threshold" | "turn_threshold" | "token_threshold" | "tool_open_threshold";
 	turns?: number;
 	tokens?: number;
 	toolCount?: number;
@@ -224,6 +214,10 @@ export interface ControlEvent {
 	currentPath?: string;
 	elapsedMs?: number;
 	recentFailureSummary?: string;
+	workflowKey?: string;
+	phase?: string;
+	label?: string;
+	taskPreview?: string;
 }
 
 export type SubagentResultStatus = "completed" | "failed" | "paused" | "stopped" | "detached";
@@ -282,7 +276,7 @@ export interface ParallelHandoffGroup {
 export interface ParallelHandoffManifest {
 	version: 1;
 	runId: string;
-	mode: "parallel" | "chain";
+	mode: "single" | "parallel" | "chain";
 	source: "foreground" | "async";
 	cwd: string;
 	createdAt: number;
@@ -1031,6 +1025,7 @@ export interface Details {
 	controlEvents?: ControlEvent[];
 	steering?: SteerActionResult;
 	asyncId?: string;
+	background?: boolean;
 	asyncDir?: string;
 	timeoutMs?: number;
 	deadlineAt?: number;
@@ -1056,7 +1051,6 @@ export interface Details {
 	totalSteps?: number;         // Total steps in chain
 	currentStepIndex?: number;   // 0-indexed current step (for running chains)
 	workflowGraph?: WorkflowGraphSnapshot;
-	checkpoint?: ChainCheckpointState;
 	outputs?: ChainOutputMap;
 	// Aggregated child usage across all agents in the run
 	totalChildUsage?: Usage;
@@ -1086,9 +1080,9 @@ export interface Details {
 	workflow?: {
 		value?: unknown;
 		trace: Array<{
-			operation: "run" | "status";
+			operation: "run" | "status" | "steer";
 			key: string;
-			state: "started" | "completed" | "failed" | "stopped" | "reused";
+			state: "started" | "completed" | "failed" | "detached" | "stopped" | "reused" | "queued" | "delivered" | "missed";
 			agent?: string;
 			runId?: string;
 			phase?: string;
@@ -1265,6 +1259,7 @@ export interface AsyncStartedEvent {
 	sessionRoot?: string;
 	pid?: number;
 	sessionId?: string;
+	completionOwnerId?: string;
 	mode?: SubagentRunMode;
 	agent?: string;
 	agents?: string[];
@@ -1276,7 +1271,6 @@ export interface AsyncStartedEvent {
 	chainStepCount?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
 	workflowGraph?: WorkflowGraphSnapshot;
-	checkpoint?: ChainCheckpointState;
 	launchContractDigest?: string;
 	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
 	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
@@ -1297,6 +1291,11 @@ export type AgentRunnerConfig =
 		command: string;
 		args?: string[];
 		promptDelivery?: "stdin";
+	}
+	| {
+		type: "external-job";
+		provider: string;
+		options?: Record<string, unknown>;
 	};
 
 export interface ExternalCliRunnerStatus {
@@ -1313,6 +1312,35 @@ export interface ExternalCliRunnerStatus {
 	};
 }
 
+export interface ExternalJobRunnerStatus {
+	type: "external-job";
+	provider: string;
+	options: Record<string, unknown>;
+	capabilities: {
+		stop: false;
+		steer: false;
+		resume: false;
+		structuredOutput: false;
+		toolEvents: false;
+	};
+}
+
+export interface ExternalJobStatus {
+	provider: string;
+	providerJobId?: string;
+	promptDigest: string;
+	options: Record<string, unknown>;
+	handleUrl?: string;
+	conversationUrl?: string;
+	resultArtifactPath?: string;
+	state: "queued" | "running" | "completed" | "failed" | "stopped" | "blocked";
+	failureCode?: string;
+	failureMessage?: string;
+	blockingJobId?: string;
+	startedAt?: number;
+	updatedAt?: number;
+}
+
 export interface ExternalProcessStatus {
 	pid?: number;
 	startedAt: number;
@@ -1327,6 +1355,8 @@ export interface ExternalProcessStatus {
 export interface AsyncStatus {
 	lifecycleArtifactVersion?: SubagentLifecycleArtifactVersion;
 	runId: string;
+	/** Parent Pi process/window that owns local completion delivery. */
+	completionOwnerId?: string;
 	/** Host tool-call id retained when it differs from the internal run id. */
 	toolCallId?: string;
 	sessionId?: string;
@@ -1360,12 +1390,13 @@ export interface AsyncStatus {
 	usageBudget?: UsageBudgetState;
 	pid?: number;
 	cwd?: string;
+	/** Parent-resolved child session root retained for trusted restored transcript lookup. */
+	sessionRoot?: string;
 	currentStep?: number;
 	chainStepCount?: number;
 	pendingAppends?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
 	workflowGraph?: WorkflowGraphSnapshot;
-	checkpoint?: ChainCheckpointState;
 	processTerminal?: ProcessTerminalV1;
 	runFanoutBudget?: RunFanoutBudgetSnapshot;
 	runFanoutBudgetDescriptor?: RunFanoutBudgetDescriptor;
@@ -1379,8 +1410,9 @@ export interface AsyncStatus {
 	workflowKey?: string;
 	steps?: Array<{
 		agent: string;
-		runner?: ExternalCliRunnerStatus;
+		runner?: ExternalCliRunnerStatus | ExternalJobRunnerStatus;
 		externalProcess?: ExternalProcessStatus;
+		externalJob?: ExternalJobStatus;
 		/** Resolved launch context for this child step. */
 		context?: "fresh" | "fork";
 		/** Short caller-facing task/goal shown in fleet surfaces when available. */
@@ -1395,7 +1427,6 @@ export interface AsyncStatus {
 		parentWorkflowRunId?: string;
 		outputName?: string;
 		structured?: boolean;
-		checkpoint?: ChainCheckpointState;
 		status: "pending" | "running" | "complete" | "completed" | "failed" | "paused" | "stopped" | "rejected";
 		children?: NestedRunSummary[];
 		sessionFile?: string;
@@ -1464,6 +1495,8 @@ export type AsyncJobStep = NonNullable<AsyncStatus["steps"]>[number] & {
 export interface AsyncJobState {
 	asyncId: string;
 	asyncDir: string;
+	/** Host tool-call id retained when it differs from the internal run id. */
+	toolCallId?: string;
 	/** Parent-resolved launch directory retained for trusted live artifact lookup. */
 	cwd?: string;
 	/** Parent-resolved child session root retained for trusted live transcript lookup. */
@@ -1473,6 +1506,7 @@ export interface AsyncJobState {
 	description?: string;
 	pid?: number;
 	sessionId?: string;
+	completionOwnerId?: string;
 	activityState?: ActivityState;
 	lastActivityAt?: number;
 	currentTool?: string;
@@ -1489,7 +1523,6 @@ export interface AsyncJobState {
 	chainStepCount?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
 	steps?: AsyncJobStep[];
-	checkpoint?: ChainCheckpointState;
 	stepsTotal?: number;
 	runningSteps?: number;
 	completedSteps?: number;
@@ -1567,7 +1600,6 @@ export interface ForegroundResumeRun {
 	/** Originating parent session. Detached exits can outlive the active session. */
 	sessionId?: string;
 	updatedAt: number;
-	checkpoint?: ChainCheckpointState;
 	children: ForegroundResumeChild[];
 }
 
@@ -1660,6 +1692,8 @@ export interface ActiveAsyncCapacitySnapshot {
 export interface SubagentState {
 	baseCwd: string;
 	currentSessionId: string | null;
+	/** Reload-stable identity for this parent Pi process/window. */
+	completionOwnerId?: string;
 	/** Runtime-owned artifact resolution inputs used by Fleet transcript targeting. */
 	artifactDirPreference?: ArtifactDirPreference;
 	/** Runtime authority snapshot used by optional inspector controls. */
@@ -1767,6 +1801,10 @@ export interface RunSyncOptions {
 	interruptSignal?: AbortSignal;
 	timeoutMs?: number;
 	deadlineAt?: number;
+	/** Per-call per-tool timeout (ms), resolved with the agent/config/environment ladder at execution. */
+	toolTimeoutMs?: number;
+	/** Raw global config.toolTimeoutMs, used by the per-child resolver. */
+	configToolTimeoutMs?: number;
 	turnBudget?: ResolvedTurnBudget;
 	usageBudget?: UsageBudgetConfig;
 	/** Enforce maxTurns + graceTurns as a hard model-turn boundary. */
@@ -1831,6 +1869,8 @@ export interface RunSyncOptions {
 	};
 	/** Private live callback for the exact child prompt after runtime acceptance injection. */
 	onEffectivePrompt?: (prompt: string) => void;
+	/** Internal lifecycle hook for the observer shared across retries of one logical child. */
+	onOrcaProgressTabCreated?: (tab: import("../runs/shared/orca-progress-tabs.ts").OrcaProgressTab) => void;
 }
 
 export type IntercomBridgeMode = "off" | "fork-only" | "always";
@@ -1892,6 +1932,11 @@ export const FLEET_KEYBINDING_ACTIONS = [
 export type FleetKeybindingAction = typeof FLEET_KEYBINDING_ACTIONS[number];
 export type FleetKeybindingsConfig = Partial<Record<FleetKeybindingAction, string[]>>;
 
+export interface OrcaProgressTabsConfig {
+	/** Create one Orca terminal tab per running subagent. Experimental and opt-in. */
+	enabled?: boolean;
+}
+
 export interface MainWindowRendererConfig {
 	/** Unit of horizontal space in main chat subagent call/result rows. Omit to preserve current spacing. Set 0 for no extra padding. */
 	horizontalSpacing?: number;
@@ -1901,6 +1946,10 @@ export interface MainWindowRendererConfig {
 
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
+	/** Set the context for launches that omit an explicit context. */
+	defaultSubagentContext?: "fresh" | "fork";
+	/** Optional shortcut that detaches the active foreground single-subagent run. */
+	foregroundDetachShortcut?: string;
 	/** Show the Claude Code-style navigable fleet. Defaults to true. */
 	fleetView?: boolean;
 	/** Place the persistent FleetView above or below the editor. Defaults to belowEditor. */
@@ -1909,14 +1958,14 @@ export interface ExtensionConfig {
 	fleetKeybindings?: FleetKeybindingsConfig;
 	/** Show the under-editor async runs widget. Defaults to true, including when FleetView is enabled. */
 	asyncWidget?: boolean;
-	/** Tool description variant registered for the parent-facing subagent tool. Defaults to full. */
+	/** Tool description variant registered for the parent-facing subagent tool. Defaults to split metadata. */
 	toolDescriptionMode?: ToolDescriptionMode;
-	/** Include legacy append-step and checkpoint controls in the registered tool schema. Defaults to false. */
-	legacyChainControls?: boolean;
 	/** Inline chat rendering for the subagent tool. Defaults to rich. */
 	inlineToolDisplay?: InlineToolDisplay;
 	/** Density controls for the main chat subagent call/result renderer. */
 	mainWindowRenderer?: MainWindowRendererConfig;
+	/** Experimental observer: mirror each native subagent's progress into a new Orca tab. */
+	orcaProgressTabs?: OrcaProgressTabsConfig;
 	forceTopLevelAsync?: boolean;
 	waitTool?: WaitToolConfig;
 	defaultSessionDir?: string;
@@ -1940,6 +1989,15 @@ export interface ExtensionConfig {
 	 * Must be a positive integer; invalid values are ignored.
 	 */
 	timeoutMs?: number;
+	/**
+	 * Optional hard per-tool-call timeout in milliseconds. Bounds a single
+	 * subagent tool call inside the child; the run-level timeout remains
+	 * authoritative. Known-fast built-in tools have a five-minute default when
+	 * this is undefined. Precedence: call param > agent frontmatter > this config >
+	 * PI_SUBAGENT_TOOL_TIMEOUT_MS. Must be a positive integer; invalid values
+	 * are rejected with an error.
+	 */
+	toolTimeoutMs?: number;
 	control?: ControlConfig;
 	completionBatch?: CompletionBatchConfig;
 	turnBudget?: TurnBudgetConfig;
@@ -2040,7 +2098,10 @@ export function resolveTempScopeId(options?: {
 
 const MAX_PARALLEL = 8;
 export const MAX_CONCURRENCY = 4;
-export const TEMP_ROOT_DIR = path.join(os.tmpdir(), `pi-subagents-${resolveTempScopeId()}`);
+const configuredTempRoot = process.env.PI_SUBAGENTS_TEMP_ROOT?.trim();
+export const TEMP_ROOT_DIR = configuredTempRoot
+	? path.resolve(configuredTempRoot)
+	: path.join(os.tmpdir(), `pi-subagents-${resolveTempScopeId()}`);
 export const RESULTS_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-results");
 export const ASYNC_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-runs");
 export const CHAIN_RUNS_DIR = path.join(TEMP_ROOT_DIR, "chain-runs");
@@ -2063,7 +2124,7 @@ export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
 export const POLL_INTERVAL_MS = 250;
 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", "append-step", "approve-checkpoint", "reject-checkpoint", "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", "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

@@ -102,6 +102,7 @@ export function getAgentDir(): string {
 }
 
 const statusCache = new Map<string, { mtime: number; ctime: number; size: number; ino: number; status: AsyncStatus }>();
+const MAX_STATUS_CACHE_ENTRIES = 512;
 
 export function pruneStatusCacheForAsyncRoot(asyncDirRoot: string, runIds: Iterable<string>): number {
 	const root = path.resolve(asyncDirRoot);
@@ -163,6 +164,8 @@ export function readStatus(asyncDir: string): AsyncStatus | null {
 		&& cached.size === stat.size
 		&& cached.ino === stat.ino
 	) {
+		statusCache.delete(statusPath);
+		statusCache.set(statusPath, cached);
 		return cached.status;
 	}
 
@@ -195,6 +198,11 @@ export function readStatus(asyncDir: string): AsyncStatus | null {
 		ino: stat.ino,
 		status,
 	});
+	while (statusCache.size > MAX_STATUS_CACHE_ENTRIES) {
+		const oldest = statusCache.keys().next().value as string | undefined;
+		if (oldest === undefined) break;
+		statusCache.delete(oldest);
+	}
 	return status;
 }
 

package/src/shared/watch-strategy.ts

@@ -0,0 +1,10 @@
+export type FileWatchPurpose =
+	| "result-delivery"
+	| "supervisor-channel"
+	| "async-job-tracker"
+	| "runner-control-inbox"
+	| "child-steering-inbox";
+
+export function shouldUseNativeFsWatch(_purpose: FileWatchPurpose, platform: NodeJS.Platform = process.platform): boolean {
+	return platform !== "darwin";
+}

package/src/slash/slash-commands.ts

@@ -2,8 +2,8 @@ import { randomUUID } from "node:crypto";
 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 TUI } from "@earendil-works/pi-tui";
-import { BUILTIN_AGENT_NAMES, discoverAgents } from "../agents/agents.ts";
+import { Key, matchesKey, truncateToWidth, type Component, type KeyId, type TUI } from "@earendil-works/pi-tui";
+import { BUILTIN_AGENT_NAMES, discoverAgents, findBlockingAgentDiagnostic, resolveAgentName } from "../agents/agents.ts";
 import { resolveExistingReadPaths } from "../shared/settings.ts";
 import {
 	DEFAULT_PROVIDER_MODELS_MAX_AGE_DAYS,
@@ -631,7 +631,7 @@ function slashRunWorkflowScript(key: string, child: Record<string, unknown>): st
 export function registerSlashCommands(
 	pi: ExtensionAPI,
 	state: SubagentState,
-	options: { fleetKeybindings?: FleetKeybindingsConfig } = {},
+	options: { fleetKeybindings?: FleetKeybindingsConfig; foregroundDetachShortcut?: string } = {},
 ): void {
 	let fleetOpen = false;
 	const showFleet = async (ctx: ExtensionContext) => {
@@ -671,8 +671,16 @@ export function registerSlashCommands(
 			const task = firstSpace === -1 ? "" : input.slice(firstSpace + 1).trim();
 
 			if (!state.baseCwd) { ctx.ui.notify("Subagent session cwd is not initialized yet", "error"); return; }
-			const agents = discoverAgents(state.baseCwd, "both").agents;
-			if (!agents.find((a) => a.name === agentName)) { ctx.ui.notify(`Unknown agent: ${agentName}`, "error"); return; }
+			const discovered = discoverAgents(state.baseCwd, "both");
+			const resolvedAgent = resolveAgentName(agentName, discovered.agents);
+			const candidates = resolvedAgent.error
+				? discovered.agents.filter((agent) => resolveAgentName(agentName, [agent]).agent)
+				: 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");
+				return;
+			}
 
 			let finalTask = task;
 			if (inline.reads && Array.isArray(inline.reads) && inline.reads.length > 0) {
@@ -741,33 +749,42 @@ export function registerSlashCommands(
 		handler: async (ctx) => showFleet(ctx),
 	});
 
+	const detachForegroundRun = (args: string, ctx: ExtensionContext): void => {
+		const id = args.trim();
+		let control: ReturnType<typeof selectForegroundDetachControl>;
+		try {
+			control = selectForegroundDetachControl(state, id);
+		} catch (error) {
+			ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			return;
+		}
+		if (!control) {
+			ctx.ui.notify(id ? `No active foreground run found for '${id}'.` : "No active foreground single-subagent run to detach.", "info");
+			return;
+		}
+		if (control.mode !== "single") {
+			ctx.ui.notify("/subagents-detach currently supports single-subagent runs only.", "error");
+			return;
+		}
+		if (!control.detach?.()) {
+			ctx.ui.notify(`Foreground run ${control.runId} is not currently detachable.`, "info");
+			return;
+		}
+		sendSlashText(pi, `Detached foreground run ${control.runId} without terminating its child. Use subagent({ action: "status", id: ${JSON.stringify(control.runId)} }) or subagent_wait({ id: ${JSON.stringify(control.runId)} }) to recover the eventual result. This does not daemonize the process or guarantee survival across Pi reload/restart.`);
+	};
+
 	pi.registerCommand("subagents-detach", {
 		description: "Detach the active foreground single-subagent run without terminating it",
-		handler: async (args, ctx) => {
-			const id = args.trim();
-			let control: ReturnType<typeof selectForegroundDetachControl>;
-			try {
-				control = selectForegroundDetachControl(state, id);
-			} catch (error) {
-				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
-				return;
-			}
-			if (!control) {
-				ctx.ui.notify(id ? `No active foreground run found for '${id}'.` : "No active foreground single-subagent run to detach.", "info");
-				return;
-			}
-			if (control.mode !== "single") {
-				ctx.ui.notify("/subagents-detach currently supports single-subagent runs only.", "error");
-				return;
-			}
-			if (!control.detach?.()) {
-				ctx.ui.notify(`Foreground run ${control.runId} is not currently detachable.`, "info");
-				return;
-			}
-			sendSlashText(pi, `Detached foreground run ${control.runId} without terminating its child. Use subagent({ action: "status", id: ${JSON.stringify(control.runId)} }) or subagent_wait({ id: ${JSON.stringify(control.runId)} }) to recover the eventual result. This does not daemonize the process or guarantee survival across Pi reload/restart.`);
-		},
+		handler: async (args, ctx) => detachForegroundRun(args, ctx),
 	});
 
+	if (options.foregroundDetachShortcut) {
+		pi.registerShortcut(options.foregroundDetachShortcut as KeyId, {
+			description: "Detach the active foreground subagent and keep it running in the background",
+			handler: async (ctx) => detachForegroundRun("", ctx),
+		});
+	}
+
 	pi.registerCommand("subagents-stop", {
 		description: "Stop a current-session async subagent run",
 		handler: async (args, ctx) => {

package/src/slash/slash-live-state.ts

@@ -81,6 +81,7 @@ function buildParallelInitialResult(params: SubagentParamsLike): AgentToolResult
 		content: [{ type: "text", text: tasks.map((task) => `${task.agent}: ${task.task}`).join("\n\n") }],
 		details: {
 			mode: "parallel",
+			...(params.async ? { background: true } : {}),
 			...(params.context ? { context: params.context } : {}),
 			results: tasks.map((task, index) => createPlaceholderResult(task.agent, task.task, "running", index)),
 			progress: tasks.map((task, index) => ({
@@ -136,6 +137,7 @@ function buildChainInitialResult(params: SubagentParamsLike): AgentToolResult<De
 		}],
 		details: {
 			mode: "chain",
+			...(params.async ? { background: true } : {}),
 			...(params.context ? { context: params.context } : {}),
 			results,
 			progress: results.map((result, index) => ({
@@ -164,6 +166,7 @@ function buildSingleInitialResult(params: SubagentParamsLike): AgentToolResult<D
 		content: [{ type: "text", text: task }],
 		details: {
 			mode: "single",
+			...(params.async ? { background: true } : {}),
 			...(params.context ? { context: params.context } : {}),
 			results: [createPlaceholderResult(agent, task, "running", 0)],
 			progress: [{