pi-subagents 0.32.0 → 0.33.0

package/src/shared/types.ts

@@ -7,6 +7,7 @@ import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
 import type { FSWatcher } from "node:fs";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ModelScopeConfig } from "../runs/shared/model-scope.ts";
 
 // ============================================================================
 // Basic Types
@@ -88,6 +89,47 @@ export interface Usage {
 	turns: number;
 }
 
+export interface TurnBudgetConfig {
+	maxTurns: number;
+	graceTurns?: number;
+}
+
+export interface ResolvedTurnBudget {
+	maxTurns: number;
+	graceTurns: number;
+}
+
+export interface ToolBudgetConfig {
+	soft?: number;
+	hard: number;
+	block?: string[] | "*";
+}
+
+export interface ResolvedToolBudget {
+	soft?: number;
+	hard: number;
+	block: string[] | "*";
+}
+
+export type ToolBudgetOutcome = "within-budget" | "soft-reached" | "hard-blocked";
+
+export interface ToolBudgetState extends ResolvedToolBudget {
+	outcome: ToolBudgetOutcome;
+	toolCount: number;
+	softReachedAt?: number;
+	hardReachedAt?: number;
+	blockedTool?: string;
+}
+
+export type TurnBudgetOutcome = "within-budget" | "wrap-up-requested" | "exceeded";
+
+export interface TurnBudgetState extends ResolvedTurnBudget {
+	outcome: TurnBudgetOutcome;
+	turnCount: number;
+	wrapUpRequestedAtTurn?: number;
+	exceededAtTurn?: number;
+}
+
 export interface TokenUsage {
 	input: number;
 	output: number;
@@ -120,6 +162,25 @@ export interface ResolvedControlConfig {
 	notifyChannels: ControlNotificationChannel[];
 }
 
+/**
+ * Smart completion batching for async-completion notifications. Successful
+ * sibling completions are held briefly so they arrive as one grouped message;
+ * failure and attention signals bypass grouping and always fire immediately.
+ */
+export interface CompletionBatchConfig {
+	enabled?: boolean;
+	/** Idle window after each arrival; resets on every new item. */
+	debounceMs?: number;
+	/** Hard cap measured from the first item in a group. */
+	maxWaitMs?: number;
+	/** Shorter idle window for straggler groups. */
+	stragglerDebounceMs?: number;
+	/** Shorter hard cap for straggler groups. */
+	stragglerMaxWaitMs?: number;
+	/** Arrivals within this window after an emit join a straggler group. */
+	stragglerWindowMs?: number;
+}
+
 export interface ControlEvent {
 	type: ControlEventType;
 	from?: ActivityState;
@@ -149,7 +210,7 @@ export type SubagentLifecycleArtifactVersion = typeof SUBAGENT_LIFECYCLE_ARTIFAC
 
 export type PublicNestedStepSummary = Pick<
 	NestedStepSummary,
-	"agent" | "status" | "sessionFile" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "startedAt" | "endedAt" | "error" | "timedOut"
+	"agent" | "status" | "sessionFile" | "transcriptPath" | "transcriptError" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "toolBudget" | "toolBudgetBlocked" | "startedAt" | "endedAt" | "error" | "timedOut"
 > & {
 	children?: PublicNestedRunSummary[];
 };
@@ -162,7 +223,7 @@ export type CostSummary = {
 
 export type PublicNestedRunSummary = Pick<
 	NestedRunSummary,
-	"id" | "parentRunId" | "parentStepIndex" | "parentAgent" | "depth" | "path" | "asyncDir" | "sessionId" | "sessionFile" | "intercomTarget" | "ownerIntercomTarget" | "leafIntercomTarget" | "ownerState" | "mode" | "state" | "agent" | "agents" | "currentStep" | "chainStepCount" | "parallelGroups" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "totalTokens" | "totalCost" | "startedAt" | "endedAt" | "lastUpdate" | "error" | "timeoutMs" | "deadlineAt" | "timedOut"
+	"id" | "parentRunId" | "parentStepIndex" | "parentAgent" | "depth" | "path" | "asyncDir" | "sessionId" | "sessionFile" | "intercomTarget" | "ownerIntercomTarget" | "leafIntercomTarget" | "ownerState" | "mode" | "state" | "agent" | "agents" | "currentStep" | "chainStepCount" | "parallelGroups" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "toolBudget" | "toolBudgetBlocked" | "totalTokens" | "totalCost" | "startedAt" | "endedAt" | "lastUpdate" | "error" | "timeoutMs" | "deadlineAt" | "timedOut" | "turnBudget" | "turnBudgetExceeded" | "wrapUpRequested"
 > & {
 	steps?: PublicNestedStepSummary[];
 	children?: PublicNestedRunSummary[];
@@ -400,6 +461,11 @@ export interface SingleResult {
 	detachedReason?: string;
 	interrupted?: boolean;
 	timedOut?: boolean;
+	turnBudget?: TurnBudgetState;
+	turnBudgetExceeded?: boolean;
+	wrapUpRequested?: boolean;
+	toolBudget?: ToolBudgetState;
+	toolBudgetBlocked?: boolean;
 	messages?: Message[];
 	usage: Usage;
 	model?: string;
@@ -424,6 +490,8 @@ export interface SingleResult {
 	structuredOutputPath?: string;
 	structuredOutputSchemaPath?: string;
 	acceptance?: AcceptanceLedger;
+	transcriptPath?: string;
+	transcriptError?: string;
 	children?: NestedRunSummary[];
 }
 
@@ -438,6 +506,8 @@ export interface Details {
 	timeoutMs?: number;
 	deadlineAt?: number;
 	timedOut?: boolean;
+	turnBudget?: ResolvedTurnBudget;
+	toolBudget?: ResolvedToolBudget;
 	progress?: AgentProgress[];
 	progressSummary?: ProgressSummary;
 	artifacts?: {
@@ -470,6 +540,7 @@ export interface ArtifactPaths {
 	inputPath: string;
 	outputPath: string;
 	jsonlPath: string;
+	transcriptPath: string;
 	metadataPath: string;
 }
 
@@ -478,6 +549,7 @@ export interface ArtifactConfig {
 	includeInput: boolean;
 	includeOutput: boolean;
 	includeJsonl: boolean;
+	includeTranscript?: boolean;
 	includeMetadata: boolean;
 	cleanupDays: number;
 }
@@ -508,6 +580,8 @@ export interface NestedStepSummary {
 	agent: string;
 	status: "pending" | "running" | "complete" | "completed" | "failed" | "paused";
 	sessionFile?: string;
+	transcriptPath?: string;
+	transcriptError?: string;
 	activityState?: ActivityState;
 	lastActivityAt?: number;
 	currentTool?: string;
@@ -519,6 +593,11 @@ export interface NestedStepSummary {
 	endedAt?: number;
 	error?: string;
 	timedOut?: boolean;
+	turnBudget?: TurnBudgetState;
+	turnBudgetExceeded?: boolean;
+	wrapUpRequested?: boolean;
+	toolBudget?: ToolBudgetState;
+	toolBudgetBlocked?: boolean;
 	children?: NestedRunSummary[];
 }
 
@@ -557,6 +636,11 @@ export interface NestedRunSummary extends NestedRunAddress {
 	timeoutMs?: number;
 	deadlineAt?: number;
 	timedOut?: boolean;
+	turnBudget?: TurnBudgetState;
+	turnBudgetExceeded?: boolean;
+	wrapUpRequested?: boolean;
+	toolBudget?: ToolBudgetState;
+	toolBudgetBlocked?: boolean;
 	error?: string;
 }
 
@@ -582,6 +666,7 @@ export interface AsyncStartedEvent {
 	workflowGraph?: WorkflowGraphSnapshot;
 	timeoutMs?: number;
 	deadlineAt?: number;
+	turnBudget?: TurnBudgetState;
 	nestedRoute?: NestedRouteInfo;
 }
 
@@ -599,12 +684,19 @@ export interface AsyncStatus {
 	currentPath?: string;
 	turnCount?: number;
 	toolCount?: number;
+	steerCount?: number;
+	lastSteerAt?: number;
 	startedAt: number;
 	endedAt?: number;
 	lastUpdate?: number;
 	timeoutMs?: number;
 	deadlineAt?: number;
 	timedOut?: boolean;
+	turnBudget?: TurnBudgetState;
+	turnBudgetExceeded?: boolean;
+	wrapUpRequested?: boolean;
+	toolBudget?: ToolBudgetState;
+	toolBudgetBlocked?: boolean;
 	pid?: number;
 	cwd?: string;
 	currentStep?: number;
@@ -621,6 +713,8 @@ export interface AsyncStatus {
 		status: "pending" | "running" | "complete" | "completed" | "failed" | "paused";
 		children?: NestedRunSummary[];
 		sessionFile?: string;
+		transcriptPath?: string;
+		transcriptError?: string;
 		activityState?: ActivityState;
 		lastActivityAt?: number;
 		currentTool?: string;
@@ -636,6 +730,11 @@ export interface AsyncStatus {
 		durationMs?: number;
 		exitCode?: number | null;
 		timedOut?: boolean;
+		turnBudget?: TurnBudgetState;
+		turnBudgetExceeded?: boolean;
+		wrapUpRequested?: boolean;
+		toolBudget?: ToolBudgetState;
+		toolBudgetBlocked?: boolean;
 		tokens?: TokenUsage;
 		skills?: string[];
 		model?: string;
@@ -643,6 +742,8 @@ export interface AsyncStatus {
 		attemptedModels?: string[];
 		modelAttempts?: ModelAttempt[];
 		totalCost?: CostSummary;
+		steerCount?: number;
+		lastSteerAt?: number;
 		error?: string;
 		structuredOutput?: unknown;
 		structuredOutputPath?: string;
@@ -674,6 +775,8 @@ export interface AsyncJobState {
 	currentPath?: string;
 	turnCount?: number;
 	toolCount?: number;
+	steerCount?: number;
+	lastSteerAt?: number;
 	mode?: SubagentRunMode;
 	agents?: string[];
 	currentStep?: number;
@@ -690,6 +793,11 @@ export interface AsyncJobState {
 	timeoutMs?: number;
 	deadlineAt?: number;
 	timedOut?: boolean;
+	turnBudget?: TurnBudgetState;
+	turnBudgetExceeded?: boolean;
+	wrapUpRequested?: boolean;
+	toolBudget?: ToolBudgetState;
+	toolBudgetBlocked?: boolean;
 	sessionDir?: string;
 	outputFile?: string;
 	totalTokens?: TokenUsage;
@@ -704,6 +812,13 @@ export interface ForegroundResumeChild {
 	index: number;
 	sessionFile?: string;
 	status: SubagentResultStatus;
+	exitCode?: number;
+	finalOutput?: string;
+	artifactPaths?: ArtifactPaths;
+	transcriptPath?: string;
+	transcriptError?: string;
+	detachedReason?: string;
+	updatedAt?: number;
 }
 
 export interface ForegroundResumeRun {
@@ -748,8 +863,6 @@ export interface SubagentState {
 	completionSeen: Map<string, number>;
 	watcher: FSWatcher | null;
 	watcherRestartTimer: ReturnType<typeof setTimeout> | null;
-	companionSuggestionStartupShown?: boolean;
-	companionSuggestionListShown?: boolean;
 	resultFileCoalescer: {
 		schedule(file: string, delayMs?: number): boolean;
 		clear(): void;
@@ -801,10 +914,13 @@ export interface RunSyncOptions {
 	interruptSignal?: AbortSignal;
 	timeoutMs?: number;
 	deadlineAt?: number;
+	turnBudget?: ResolvedTurnBudget;
+	toolBudget?: ResolvedToolBudget;
 	allowIntercomDetach?: boolean;
 	intercomEvents?: IntercomEventBus;
 	onUpdate?: (r: import("@earendil-works/pi-agent-core").AgentToolResult<Details>) => void;
 	onControlEvent?: (event: ControlEvent) => void;
+	onDetachedExit?: (result: SingleResult) => void;
 	controlConfig?: ResolvedControlConfig;
 	intercomSessionName?: string;
 	orchestratorIntercomTarget?: string;
@@ -828,6 +944,8 @@ export interface RunSyncOptions {
 	availableModels?: Array<{ provider: string; id: string; fullId: string }>;
 	/** Current parent-session provider to prefer for ambiguous bare model ids */
 	preferredModelProvider?: string;
+	/** Optional subagent model-scope enforcement for fallback candidates */
+	modelScope?: ModelScopeConfig;
 	/** Skills to make available (overrides agent default if provided) */
 	skills?: string[];
 	structuredOutput?: {
@@ -869,25 +987,18 @@ export interface ProactiveSkillSubagentsConfig {
 	preferredAgent?: string;
 }
 
-export type CompanionSuggestionPackage = "pi-prompt-template-model" | "pi-intercom";
-export type CompanionSuggestionSurface = "session_start" | "list" | "doctor";
-
-export interface CompanionSuggestionPackageConfig {
-	enabled?: boolean;
-	surfaces?: CompanionSuggestionSurface[];
-	dismissed?: {
-		user?: boolean;
-		workspaces?: string[];
-	};
-}
+export type ToolDescriptionMode = "full" | "compact" | "custom";
 
-export interface CompanionSuggestionsConfig {
+export interface ScheduledRunsConfig {
 	enabled?: boolean;
-	packages?: Partial<Record<CompanionSuggestionPackage, CompanionSuggestionPackageConfig>>;
+	maxLatenessMs?: number;
+	maxPending?: number;
 }
 
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
+	/** Tool description variant registered for the parent-facing subagent tool. Defaults to full. */
+	toolDescriptionMode?: ToolDescriptionMode;
 	forceTopLevelAsync?: boolean;
 	defaultSessionDir?: string;
 	singleRunOutputBaseDir?: string;
@@ -896,6 +1007,9 @@ export interface ExtensionConfig {
 	/** Global cap on simultaneously-running subagent tasks within a single run. Defaults to 20. */
 	globalConcurrencyLimit?: number;
 	control?: ControlConfig;
+	completionBatch?: CompletionBatchConfig;
+	turnBudget?: TurnBudgetConfig;
+	toolBudget?: ToolBudgetConfig;
 	parallel?: TopLevelParallelConfig;
 	chain?: ExtensionChainConfig;
 	worktreeSetupHook?: string;
@@ -903,7 +1017,7 @@ export interface ExtensionConfig {
 	worktreeBaseDir?: string;
 	intercomBridge?: IntercomBridgeConfig;
 	proactiveSkillSubagents?: ProactiveSkillSubagentsConfig | false;
-	companionSuggestions?: CompanionSuggestionsConfig | false;
+	scheduledRuns?: ScheduledRunsConfig;
 }
 
 // ============================================================================
@@ -920,6 +1034,7 @@ export const DEFAULT_ARTIFACT_CONFIG: ArtifactConfig = {
 	includeInput: true,
 	includeOutput: true,
 	includeJsonl: false,
+	includeTranscript: true,
 	includeMetadata: true,
 	cleanupDays: 7,
 };
@@ -996,7 +1111,7 @@ export const POLL_INTERVAL_MS = 250;
 export const MAX_WIDGET_JOBS = 4;
 export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
 export const DEFAULT_MAX_SUBAGENT_SPAWNS_PER_SESSION = 40;
-export const SUBAGENT_ACTIONS = ["list", "get", "models", "create", "update", "delete", "status", "interrupt", "resume", "append-step", "doctor"] as const;
+export const SUBAGENT_ACTIONS = ["list", "get", "models", "create", "update", "delete", "eject", "disable", "enable", "reset", "status", "interrupt", "resume", "steer", "append-step", "doctor", "schedule", "schedule-list", "schedule-status", "schedule-cancel"] as const;
 
 export const DEFAULT_FORK_PREAMBLE =
 	"You are a delegated subagent running from a fork of the parent session. " +

package/src/slash/prompt-workflows.ts

@@ -0,0 +1,330 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { parseFrontmatter } from "../agents/frontmatter.ts";
+import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
+import type { ChainStep } from "../shared/settings.ts";
+import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
+
+interface PromptWorkflow {
+	name: string;
+	description: string;
+	body: string;
+	filePath: string;
+	agent: string;
+	context?: "fresh" | "fork";
+	model?: string;
+	skill?: string | string[] | false;
+	cwd?: string;
+	worktree?: boolean;
+	chain?: string;
+}
+
+type PromptWorkflowRunner = (params: SubagentParamsLike, ctx: ExtensionContext) => Promise<void>;
+
+const RESERVED_COMMAND_NAMES = new Set([
+	"chain-prompts",
+	"prompt-workflow",
+	"run",
+	"chain",
+	"parallel",
+	"run-chain",
+	"subagents-doctor",
+	"subagents-models",
+]);
+
+function packagePromptsDir(): string {
+	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "prompts");
+}
+
+function promptDirs(cwd: string): string[] {
+	return [
+		packagePromptsDir(),
+		path.join(getAgentDir(), "prompts"),
+		path.join(getProjectConfigDir(cwd), "prompts"),
+	];
+}
+
+function readPromptFiles(cwd: string): string[] {
+	const files: string[] = [];
+	for (const dir of promptDirs(cwd)) {
+		let entries: fs.Dirent[];
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (entry.isFile() && entry.name.endsWith(".md")) files.push(path.join(dir, entry.name));
+		}
+	}
+	return files;
+}
+
+function firstNonEmptyLine(value: string): string {
+	return value.split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? "Prompt workflow";
+}
+
+function stringField(frontmatter: Record<string, string>, key: string): string | undefined {
+	const value = frontmatter[key]?.trim();
+	return value ? value : undefined;
+}
+
+function booleanField(frontmatter: Record<string, string>, key: string): boolean | undefined {
+	const value = frontmatter[key]?.trim().toLowerCase();
+	if (value === "true" || value === "yes" || value === "1") return true;
+	if (value === "false" || value === "no" || value === "0") return false;
+	return undefined;
+}
+
+function parseSkill(value: string | undefined): string | string[] | false | undefined {
+	if (!value) return undefined;
+	if (value === "false") return false;
+	const parts = value.split(",").map((part) => part.trim()).filter(Boolean);
+	return parts.length > 1 ? parts : parts[0];
+}
+
+function parseAgent(frontmatter: Record<string, string>): string {
+	const subagent = stringField(frontmatter, "subagent");
+	if (!subagent || subagent === "true") return "delegate";
+	return subagent;
+}
+
+function loadPromptWorkflow(filePath: string): PromptWorkflow | undefined {
+	const content = fs.readFileSync(filePath, "utf-8");
+	const { frontmatter, body } = parseFrontmatter(content);
+	const name = path.basename(filePath, ".md");
+	if (!name || RESERVED_COMMAND_NAMES.has(name)) return undefined;
+	const model = stringField(frontmatter, "model");
+	const skill = parseSkill(stringField(frontmatter, "skill"));
+	const cwd = stringField(frontmatter, "cwd");
+	const chain = stringField(frontmatter, "chain");
+	return {
+		name,
+		description: stringField(frontmatter, "description") ?? firstNonEmptyLine(body),
+		body,
+		filePath,
+		agent: parseAgent(frontmatter),
+		...(booleanField(frontmatter, "inheritContext") === true || booleanField(frontmatter, "fork") === true ? { context: "fork" as const } : {}),
+		...(booleanField(frontmatter, "fresh") === true ? { context: "fresh" as const } : {}),
+		...(model ? { model } : {}),
+		...(skill !== undefined ? { skill } : {}),
+		...(cwd ? { cwd } : {}),
+		...(booleanField(frontmatter, "worktree") === true ? { worktree: true } : {}),
+		...(chain ? { chain } : {}),
+	};
+}
+
+export function discoverPromptWorkflows(cwd: string): PromptWorkflow[] {
+	const workflows = new Map<string, PromptWorkflow>();
+	for (const file of readPromptFiles(cwd)) {
+		const workflow = loadPromptWorkflow(file);
+		if (workflow) workflows.set(workflow.name, workflow);
+	}
+	return [...workflows.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function shellWords(input: string): string[] {
+	const words: string[] = [];
+	let current = "";
+	let quote: "'" | '"' | undefined;
+	let escaped = false;
+	for (const ch of input) {
+		if (escaped) {
+			current += ch;
+			escaped = false;
+			continue;
+		}
+		if (ch === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (quote) {
+			if (ch === quote) quote = undefined;
+			else current += ch;
+			continue;
+		}
+		if (ch === "'" || ch === '"') {
+			quote = ch;
+			continue;
+		}
+		if (/\s/.test(ch)) {
+			if (current) {
+				words.push(current);
+				current = "";
+			}
+			continue;
+		}
+		current += ch;
+	}
+	if (current) words.push(current);
+	return words;
+}
+
+function substituteArgs(template: string, args: string[]): string {
+	const all = args.join(" ");
+	return template
+		.replace(/\$ARGUMENTS/g, all)
+		.replace(/\$@/g, all)
+		.replace(/\$\{(\d+):-([^}]*)\}/g, (_match, index: string, fallback: string) => args[Number(index) - 1] || fallback)
+		.replace(/\$(\d+)/g, (_match, index: string) => args[Number(index) - 1] ?? "");
+}
+
+function parseRuntimeOptions(words: string[]): { args: string[]; agentOverride?: string; fork?: boolean; fresh?: boolean; worktree?: boolean; bg?: boolean } {
+	const args: string[] = [];
+	let agentOverride: string | undefined;
+	let fork = false;
+	let fresh = false;
+	let worktree = false;
+	let bg = false;
+	for (let i = 0; i < words.length; i++) {
+		const word = words[i]!;
+		if (word === "--fork") {
+			fork = true;
+			continue;
+		}
+		if (word === "--fresh") {
+			fresh = true;
+			continue;
+		}
+		if (word === "--worktree") {
+			worktree = true;
+			continue;
+		}
+		if (word === "--bg" || word === "--async") {
+			bg = true;
+			continue;
+		}
+		if (word === "--subagent") {
+			agentOverride = words[++i];
+			continue;
+		}
+		const eq = word.match(/^--subagent(?:=|:)(.+)$/);
+		if (eq) {
+			agentOverride = eq[1];
+			continue;
+		}
+		args.push(word);
+	}
+	return { args, agentOverride, fork, fresh, worktree, bg };
+}
+
+function splitChainDeclaration(input: string): { declaration: string; argsText: string } {
+	const delimiter = input.indexOf(" -- ");
+	if (delimiter === -1) return { declaration: input.trim(), argsText: "" };
+	return { declaration: input.slice(0, delimiter).trim(), argsText: input.slice(delimiter + 4).trim() };
+}
+
+function splitPromptChain(input: string): string[] {
+	return input.split(" -> ").map((part) => part.trim()).filter(Boolean);
+}
+
+function workflowParams(workflow: PromptWorkflow, args: string[], runtime: ReturnType<typeof parseRuntimeOptions>): SubagentParamsLike {
+	const task = substituteArgs(workflow.body, args).trim();
+	const context = runtime.fork ? "fork" : runtime.fresh ? "fresh" : workflow.context;
+	return {
+		agent: runtime.agentOverride ?? workflow.agent,
+		task,
+		clarify: false,
+		agentScope: "both",
+		...(context ? { context } : {}),
+		...(workflow.model ? { model: workflow.model } : {}),
+		...(workflow.skill !== undefined ? { skill: workflow.skill } : {}),
+		...(workflow.cwd ? { cwd: workflow.cwd } : {}),
+		...(runtime.worktree || workflow.worktree ? { worktree: true } : {}),
+		...(runtime.bg ? { async: true } : {}),
+	};
+}
+
+function workflowChainStep(workflow: PromptWorkflow, args: string[], runtime: ReturnType<typeof parseRuntimeOptions>): ChainStep {
+	const params = workflowParams(workflow, args, runtime);
+	return {
+		agent: params.agent ?? "delegate",
+		task: params.task,
+		...(params.model ? { model: params.model } : {}),
+		...(params.skill !== undefined ? { skill: params.skill } : {}),
+		...(params.cwd ? { cwd: params.cwd } : {}),
+	};
+}
+
+function findWorkflow(workflows: PromptWorkflow[], name: string): PromptWorkflow | undefined {
+	return workflows.find((workflow) => workflow.name === name);
+}
+
+function formatWorkflowList(workflows: PromptWorkflow[]): string {
+	if (workflows.length === 0) return "No prompt workflows found in package, user, or project prompts.";
+	return [
+		"Prompt workflows:",
+		...workflows.map((workflow) => `- ${workflow.name}: ${workflow.description} (${workflow.filePath})`),
+	].join("\n");
+}
+
+export function registerPromptWorkflowCommands(input: {
+	pi: ExtensionAPI;
+	run: PromptWorkflowRunner;
+}): void {
+	const { pi, run } = input;
+
+	pi.registerCommand("prompt-workflow", {
+		description: "Run a prompt template through native pi-subagents: /prompt-workflow <name> [args]",
+		handler: async (rawArgs, ctx) => {
+			const words = shellWords(rawArgs);
+			const name = words.shift();
+			const workflows = discoverPromptWorkflows(ctx.cwd);
+			if (!name || name === "list") {
+				pi.sendMessage({ content: formatWorkflowList(workflows), display: true });
+				return;
+			}
+			const workflow = findWorkflow(workflows, name);
+			if (!workflow) {
+				ctx.ui.notify(`Unknown prompt workflow: ${name}`, "error");
+				return;
+			}
+			const runtime = parseRuntimeOptions(words);
+			try {
+				if (workflow.chain) {
+					const chainNames = splitPromptChain(workflow.chain);
+					const chain = chainNames.map((stepName) => {
+						const step = findWorkflow(workflows, stepName);
+						if (!step) throw new Error(`Unknown prompt workflow in chain '${workflow.name}': ${stepName}`);
+						return workflowChainStep(step, runtime.args, runtime);
+					});
+					await run({ chain, task: runtime.args.join(" "), clarify: false, agentScope: "both", ...(runtime.bg ? { async: true } : {}) }, ctx);
+					return;
+				}
+				await run(workflowParams(workflow, runtime.args, runtime), ctx);
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+
+	pi.registerCommand("chain-prompts", {
+		description: "Run prompt templates as a native subagent chain: /chain-prompts analyze -> fix -- args",
+		handler: async (rawArgs, ctx) => {
+			const { declaration, argsText } = splitChainDeclaration(rawArgs);
+			const workflows = discoverPromptWorkflows(ctx.cwd);
+			if (!declaration || declaration === "list") {
+				pi.sendMessage({ content: formatWorkflowList(workflows), display: true });
+				return;
+			}
+			const runtime = parseRuntimeOptions(shellWords(argsText));
+			const names = splitPromptChain(declaration);
+			if (names.length === 0) {
+				ctx.ui.notify("Usage: /chain-prompts prompt-a -> prompt-b -- args", "error");
+				return;
+			}
+			try {
+				const chain = names.map((name) => {
+					const workflow = findWorkflow(workflows, name);
+					if (!workflow) throw new Error(`Unknown prompt workflow: ${name}`);
+					return workflowChainStep(workflow, runtime.args, runtime);
+				});
+				await run({ chain, task: runtime.args.join(" "), clarify: false, agentScope: "both", ...(runtime.bg ? { async: true } : {}) }, ctx);
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+}