pi-subagents 0.54.0 → 0.55.0

package/src/agents/agents.ts

@@ -22,6 +22,7 @@ import { parseMemoryFrontmatter } from "./agent-memory.ts";
 import { resolveTurnBudgetConfig } from "../runs/shared/turn-budget.ts";
 import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
 import { validatePermissionRules, type PermissionRules } from "../runs/shared/permissions.ts";
+import { parseThinkingLevel, type ThinkingLevel } from "../shared/thinking-ceiling.ts";
 
 export type AgentScope = "user" | "project" | "both";
 
@@ -50,8 +51,11 @@ export function defaultInheritSkills(): boolean {
 
 export interface BuiltinAgentOverrideBase {
 	description?: string;
+	output?: string;
 	outputMode?: OutputMode;
+	defaultReads?: string[];
 	model?: string;
+	modelProvider?: string;
 	fallbackModels?: string[];
 	thinking?: string | false;
 	systemPromptMode: SystemPromptMode;
@@ -73,8 +77,11 @@ export interface BuiltinAgentOverrideBase {
 
 interface BuiltinAgentOverrideConfig {
 	description?: string;
+	output?: string | false;
 	outputMode?: OutputMode;
+	defaultReads?: string[] | false;
 	model?: string | false;
+	defaultProvider?: string | false;
 	fallbackModels?: string[] | false;
 	thinking?: string | false;
 	systemPromptMode?: SystemPromptMode;
@@ -103,6 +110,7 @@ export interface AgentModelSourceInfo {
 	scope: "user" | "project";
 	path: string;
 	model: string;
+	defaultProvider?: string;
 }
 
 export interface AgentConfig {
@@ -118,6 +126,7 @@ export interface AgentConfig {
 	tools?: string[];
 	mcpDirectTools?: string[];
 	model?: string;
+	modelProvider?: string;
 	fallbackModels?: string[];
 	thinking?: string | false;
 	systemPromptMode: SystemPromptMode;
@@ -153,6 +162,7 @@ export interface AgentConfig {
 	extraFields?: Record<string, string>;
 	override?: BuiltinAgentOverrideInfo;
 	modelSource?: AgentModelSourceInfo;
+	maxThinking?: ThinkingLevel;
 }
 
 type ProjectRootResolution = "nearest" | "git-root";
@@ -160,7 +170,9 @@ type ProjectRootResolution = "nearest" | "git-root";
 interface SubagentSettings {
 	overrides: Record<string, BuiltinAgentOverrideConfig>;
 	defaultModel?: string;
+	defaultProvider?: string;
 	defaultThinking?: string;
+	maxThinking?: ThinkingLevel;
 	defaultExtensions?: string[];
 	disableBuiltins?: boolean;
 	disableThinking?: boolean;
@@ -252,6 +264,7 @@ interface AgentDiscoveryResult {
 	agentDiagnostics?: AgentDiscoveryDiagnostic[];
 	projectAgentsDir: string | null;
 	modelScope?: ModelScopeConfig;
+	maxThinking?: ThinkingLevel;
 }
 
 function getUserChainDir(): string {
@@ -621,8 +634,11 @@ function arraysEqual(a: string[] | undefined, b: string[] | undefined): boolean
 function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
 	return {
 		description: agent.description,
+		...(agent.output !== undefined ? { output: agent.output } : {}),
 		...(agent.outputMode !== undefined ? { outputMode: agent.outputMode } : {}),
+		...(agent.defaultReads !== undefined ? { defaultReads: [...agent.defaultReads] } : {}),
 		...(agent.model !== undefined ? { model: agent.model } : {}),
+		...(agent.modelProvider !== undefined ? { modelProvider: agent.modelProvider } : {}),
 		...(agent.fallbackModels ? { fallbackModels: [...agent.fallbackModels] } : {}),
 		...(agent.thinking !== undefined ? { thinking: agent.thinking } : {}),
 		systemPromptMode: agent.systemPromptMode,
@@ -646,8 +662,11 @@ function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
 function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentOverrideConfig {
 	return {
 		...(override.description !== undefined ? { description: override.description } : {}),
+		...(override.output !== undefined ? { output: override.output } : {}),
 		...(override.outputMode !== undefined ? { outputMode: override.outputMode } : {}),
+		...(override.defaultReads !== undefined ? { defaultReads: override.defaultReads === false ? false : [...override.defaultReads] } : {}),
 		...(override.model !== undefined ? { model: override.model } : {}),
+		...(override.defaultProvider !== undefined ? { defaultProvider: override.defaultProvider } : {}),
 		...(override.fallbackModels !== undefined
 			? { fallbackModels: override.fallbackModels === false ? false : [...override.fallbackModels] }
 			: {}),
@@ -827,6 +846,11 @@ function parseBuiltinOverrideEntry(
 		}
 	}
 
+	if ("output" in input) {
+		if ((typeof input.output === "string" && input.output.trim()) || input.output === false) override.output = input.output;
+		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'output'; expected a non-empty string or false.`);
+	}
+
 	if ("outputMode" in input) {
 		if (input.outputMode === "inline" || input.outputMode === "file-only") {
 			override.outputMode = input.outputMode;
@@ -916,9 +940,18 @@ function parseBuiltinOverrideEntry(
 		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'systemPrompt'; expected a string.`);
 	}
 
+	const defaultReads = parseOverrideStringArrayOrFalse(input.defaultReads, { filePath, name, field: "defaultReads" });
+	if (defaultReads !== undefined) override.defaultReads = defaultReads;
+
 	const fallbackModels = parseOverrideStringArrayOrFalse(input.fallbackModels, { filePath, name, field: "fallbackModels" });
 	if (fallbackModels !== undefined) override.fallbackModels = fallbackModels;
 
+	if ("defaultProvider" in input) {
+		if (input.defaultProvider === false) override.defaultProvider = false;
+		else if (typeof input.defaultProvider === "string" && input.defaultProvider.trim()) override.defaultProvider = input.defaultProvider.trim();
+		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'defaultProvider'; expected a non-empty string or false.`);
+	}
+
 	const skills = parseOverrideStringArrayOrFalse(input.skills, { filePath, name, field: "skills" });
 	if (skills !== undefined) override.skills = skills;
 
@@ -965,6 +998,14 @@ function readSubagentSettings(filePath: string | null): SubagentSettings {
 			throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultModel'; expected a non-empty string.`);
 		}
 	}
+	let defaultProvider: string | undefined;
+	if ("defaultProvider" in subagentsObject) {
+		if (typeof subagentsObject.defaultProvider === "string" && subagentsObject.defaultProvider.trim()) {
+			defaultProvider = subagentsObject.defaultProvider.trim();
+		} else {
+			throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultProvider'; expected a non-empty string.`);
+		}
+	}
 	let defaultThinking: string | undefined;
 	if ("defaultThinking" in subagentsObject) {
 		if (typeof subagentsObject.defaultThinking === "string" && subagentsObject.defaultThinking.trim()) {
@@ -973,6 +1014,14 @@ function readSubagentSettings(filePath: string | null): SubagentSettings {
 			throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultThinking'; expected a non-empty string.`);
 		}
 	}
+	let maxThinking: ThinkingLevel | undefined;
+	if ("maxThinking" in subagentsObject) {
+		try {
+			maxThinking = parseThinkingLevel(subagentsObject.maxThinking, `'${filePath}' subagents.maxThinking`);
+		} catch (error) {
+			throw new Error(`Subagent settings in '${filePath}' have invalid 'maxThinking'; expected one of off, minimal, low, medium, high, xhigh, or max.`, { cause: error instanceof Error ? error : undefined });
+		}
+	}
 	let defaultExtensions: string[] | undefined;
 	if ("defaultExtensions" in subagentsObject) {
 		if (!Array.isArray(subagentsObject.defaultExtensions)
@@ -988,7 +1037,9 @@ function readSubagentSettings(filePath: string | null): SubagentSettings {
 	const parsedSettings: SubagentSettings = {
 		overrides: parsed,
 		...(defaultModel !== undefined ? { defaultModel } : {}),
+		...(defaultProvider !== undefined ? { defaultProvider } : {}),
 		...(defaultThinking !== undefined ? { defaultThinking } : {}),
+		...(maxThinking !== undefined ? { maxThinking } : {}),
 		...(defaultExtensions !== undefined ? { defaultExtensions } : {}),
 		...(disableBuiltins !== undefined ? { disableBuiltins } : {}),
 		...(disableThinking !== undefined ? { disableThinking } : {}),
@@ -1004,25 +1055,39 @@ function readSubagentSettings(filePath: string | null): SubagentSettings {
 	return parsedSettings;
 }
 
+function resolveSubagentDefaultProvider(
+	userSettings: SubagentSettings,
+	projectSettings: SubagentSettings,
+	projectSettingsPath: string | null,
+): string | undefined {
+	if (projectSettingsPath && projectSettings.defaultProvider !== undefined) return projectSettings.defaultProvider;
+	return userSettings.defaultProvider;
+}
+
 function resolveSubagentDefaultModel(
 	userSettings: SubagentSettings,
 	projectSettings: SubagentSettings,
 	userSettingsPath: string,
 	projectSettingsPath: string | null,
+	defaultProvider: string | undefined,
 ): AgentModelSourceInfo | undefined {
 	if (projectSettingsPath && projectSettings.defaultModel !== undefined) {
-		return { type: "subagents.defaultModel", scope: "project", path: projectSettingsPath, model: projectSettings.defaultModel };
+		return { type: "subagents.defaultModel", scope: "project", path: projectSettingsPath, model: projectSettings.defaultModel, ...(defaultProvider ? { defaultProvider } : {}) };
 	}
 	return userSettings.defaultModel !== undefined
-		? { type: "subagents.defaultModel", scope: "user", path: userSettingsPath, model: userSettings.defaultModel }
+		? { type: "subagents.defaultModel", scope: "user", path: userSettingsPath, model: userSettings.defaultModel, ...(defaultProvider ? { defaultProvider } : {}) }
 		: undefined;
 }
 
-function applySubagentDefaultModel(agents: AgentConfig[], defaultModel: AgentModelSourceInfo | undefined): AgentConfig[] {
-	if (!defaultModel) return agents;
+function applySubagentDefaultModel(agents: AgentConfig[], defaultModel: AgentModelSourceInfo | undefined, defaultProvider: string | undefined): AgentConfig[] {
+	if (!defaultModel && !defaultProvider) return agents;
 	return agents.map((agent) => {
-		if (agent.model !== undefined) return agent;
-		const next = { ...agent, model: defaultModel.model, modelSource: defaultModel };
+		if (agent.model !== undefined && (agent.modelProvider !== undefined || !defaultProvider)) return agent;
+		const next = {
+			...agent,
+			...(agent.model === undefined && defaultModel ? { model: defaultModel.model, modelSource: defaultModel } : {}),
+			...(defaultProvider ? { modelProvider: defaultProvider } : {}),
+		};
 		const frontmatterFields = agentFrontmatterFields.get(agent);
 		if (frontmatterFields) agentFrontmatterFields.set(next, frontmatterFields);
 		return next;
@@ -1049,6 +1114,20 @@ function applySubagentDefaultThinking(agents: AgentConfig[], defaultThinking: st
 	});
 }
 
+function resolveSubagentMaxThinking(
+	userSettings: SubagentSettings,
+	projectSettings: SubagentSettings,
+	projectSettingsPath: string | null,
+): ThinkingLevel | undefined {
+	if (projectSettingsPath && projectSettings.maxThinking !== undefined) return projectSettings.maxThinking;
+	return userSettings.maxThinking;
+}
+
+function applySubagentMaxThinking(agents: AgentConfig[], maxThinking: ThinkingLevel | undefined): AgentConfig[] {
+	if (maxThinking === undefined) return agents;
+	return agents.map((agent) => agent.maxThinking === maxThinking ? agent : { ...agent, maxThinking });
+}
+
 function resolveSubagentDefaultExtensions(
 	userSettings: SubagentSettings,
 	projectSettings: SubagentSettings,
@@ -1072,11 +1151,12 @@ function applySubagentDefaultExtensions(agents: AgentConfig[], defaultExtensions
 function applySubagentDefaults(
 	agents: AgentConfig[],
 	defaultModel: AgentModelSourceInfo | undefined,
+	defaultProvider: string | undefined,
 	defaultThinking: string | undefined,
 	defaultExtensions: string[] | undefined,
 ): AgentConfig[] {
 	return applySubagentDefaultExtensions(
-		applySubagentDefaultThinking(applySubagentDefaultModel(agents, defaultModel), defaultThinking),
+		applySubagentDefaultThinking(applySubagentDefaultModel(agents, defaultModel, defaultProvider), defaultThinking),
 		defaultExtensions,
 	);
 }
@@ -1103,11 +1183,17 @@ function applyBuiltinOverride(
 	};
 
 	if (override.description !== undefined) next.description = override.description;
+	if (override.output !== undefined) { if (override.output === false) delete next.output; else next.output = override.output; }
 	if (override.outputMode !== undefined) next.outputMode = override.outputMode;
+	if (override.defaultReads !== undefined) { if (override.defaultReads === false) delete next.defaultReads; else next.defaultReads = [...override.defaultReads]; }
 	if (override.model !== undefined) {
 		if (override.model === false) delete next.model; else next.model = override.model;
 		delete next.modelSource;
 	}
+	if (override.defaultProvider !== undefined) {
+		if (override.defaultProvider === false) delete next.modelProvider;
+		else next.modelProvider = override.defaultProvider;
+	}
 	if (override.fallbackModels !== undefined) { if (override.fallbackModels === false) delete next.fallbackModels; else next.fallbackModels = [...override.fallbackModels]; }
 	if (override.thinking !== undefined) { if (override.thinking === false) delete next.thinking; else next.thinking = override.thinking; }
 	if (override.systemPromptMode !== undefined) next.systemPromptMode = override.systemPromptMode;
@@ -1221,15 +1307,24 @@ function applyCustomAgentOverride(
 		mutable().description = override.description;
 		anyFilled = true;
 	}
+	if (override.output !== undefined) {
+		fill("output", ["output"], override.output === false ? undefined : override.output);
+	}
 	if (override.outputMode !== undefined) {
 		fill("outputMode", ["outputMode"], override.outputMode);
 	}
+	if (override.defaultReads !== undefined) {
+		fill("defaultReads", ["defaultReads"], override.defaultReads === false ? undefined : [...override.defaultReads]);
+	}
 	if (override.model !== undefined && !agentHasFrontmatterField(agent, "model")) {
 		const target = mutable();
 		if (override.model === false) delete target.model; else target.model = override.model;
 		delete target.modelSource;
 		anyFilled = true;
 	}
+	if (override.defaultProvider !== undefined) {
+		fill("modelProvider", ["modelProvider", "defaultProvider"], override.defaultProvider === false ? undefined : override.defaultProvider);
+	}
 	if (override.fallbackModels !== undefined) {
 		fill(
 			"fallbackModels",
@@ -1256,17 +1351,7 @@ function applyCustomAgentOverride(
 		fill("acceptanceRole", ["acceptanceRole"], override.acceptanceRole === false ? undefined : override.acceptanceRole);
 	}
 	if (override.disabled !== undefined) {
-		// Unconditional, matching applyBuiltinOverride: custom agents have no
-		// frontmatter concept of `disabled` to protect (unlike model/thinking/
-		// etc., which use `fill()` + agentHasFrontmatterField to defer to the
-		// agent's own file). A guard here previously read `agent.disabled ===
-		// undefined`, which was a no-op before user+project layering existed
-		// (this function only ever ran once, against the pristine base agent,
-		// whose `.disabled` is always undefined for custom agents) but became a
-		// real bug once a user-scope override could run first: the guard then
-		// silently blocked a later project-scope override from ever changing
-		// `disabled`, breaking this PR's own "project wins" precedence for this
-		// one field.
+		// Custom agent files cannot set `disabled`, so project overrides replace user overrides.
 		mutable().disabled = override.disabled;
 		anyFilled = true;
 	}
@@ -1295,7 +1380,7 @@ function applyCustomAgentOverride(
 	}
 
 	if (!anyFilled || !next) return agent;
-	next.override = { ...meta, base: cloneOverrideBase(agent) };
+	next.override = { ...meta, base: agent.override?.base ?? cloneOverrideBase(agent) };
 	const frontmatterFields = agentFrontmatterFields.get(agent);
 	if (frontmatterFields) agentFrontmatterFields.set(next, frontmatterFields);
 	return next;
@@ -1308,13 +1393,7 @@ function applyCustomAgentOverrides(
 	userSettingsPath: string,
 	projectSettingsPath: string | null,
 ): AgentConfig[] {
-	// Both scopes are applied, user first then project, so a project override that
-	// only sets a subset of fields (e.g. just `extensions`) layers on top of the
-	// user's override instead of silently discarding it (#1341 / issue writeup:
-	// "agentOverrides project override drops user-only fields for custom agents").
-	// Per-field precedence still favors project over user: applyCustomAgentOverride
-	// only fills fields present in the override it's given, and project is applied
-	// last, so any field set at both scopes ends up with the project's value.
+	// Apply user then project so project fields win without dropping user-only fields.
 	return agents.map((agent) => {
 		const userOverride = userSettings.overrides[agent.name];
 		const withUserOverride = userOverride
@@ -1332,7 +1411,7 @@ function applyCustomAgentOverrides(
 
 export function buildBuiltinOverrideConfig(
 	base: BuiltinAgentOverrideBase,
-	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "acceptanceRole" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "extensions" | "subagentOnlyExtensions" | "completionGuard" | "toolBudget"> & Partial<Pick<AgentConfig, "description" | "outputMode">>,
+	draft: Pick<AgentConfig, "model" | "modelProvider" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "acceptanceRole" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "extensions" | "subagentOnlyExtensions" | "completionGuard" | "toolBudget"> & Partial<Pick<AgentConfig, "description" | "output" | "outputMode" | "defaultReads">>,
 ): BuiltinAgentOverrideConfig | undefined {
 	const override: BuiltinAgentOverrideConfig = {};
 
@@ -1340,8 +1419,11 @@ export function buildBuiltinOverrideConfig(
 		const description = draft.description.trim();
 		if (description && description !== base.description) override.description = description;
 	}
+	if (draft.output !== base.output) override.output = draft.output ?? false;
 	if (draft.outputMode !== undefined && draft.outputMode !== base.outputMode) override.outputMode = draft.outputMode;
+	if (!arraysEqual(draft.defaultReads, base.defaultReads)) override.defaultReads = draft.defaultReads ? [...draft.defaultReads] : false;
 	if (draft.model !== base.model) override.model = draft.model ?? false;
+	if (draft.modelProvider !== base.modelProvider) override.defaultProvider = draft.modelProvider ?? false;
 	if (!arraysEqual(draft.fallbackModels, base.fallbackModels)) override.fallbackModels = draft.fallbackModels ? [...draft.fallbackModels] : false;
 	if (draft.thinking !== base.thinking) override.thinking = draft.thinking ?? false;
 	if (draft.systemPromptMode !== base.systemPromptMode) override.systemPromptMode = draft.systemPromptMode;
@@ -1931,8 +2013,10 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	const projectSettingsPath = getProjectAgentSettingsPath(cwd);
 	const userSettings = scope === "project" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(userSettingsPath);
 	const projectSettings = scope === "user" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(projectSettingsPath);
-	const defaultModel = resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath);
+	const defaultProvider = resolveSubagentDefaultProvider(userSettings, projectSettings, projectSettingsPath);
+	const defaultModel = resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath, defaultProvider);
 	const defaultThinking = resolveSubagentDefaultThinking(userSettings, projectSettings, projectSettingsPath);
+	const maxThinking = resolveSubagentMaxThinking(userSettings, projectSettings, projectSettingsPath);
 	const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, projectSettingsPath);
 	const modelScope = projectSettings.modelScope ?? userSettings.modelScope;
 	const packageSubagentPaths = collectPackageSubagentPaths(cwd, {
@@ -1942,7 +2026,7 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 
 	const builtinLoaded = loadAgentsFromDefinitionFiles(BUILTIN_AGENT_DEFINITION_FILES, "builtin");
 	const builtinAgents = applyBuiltinOverrides(
-		applySubagentDefaults(builtinLoaded.agents, defaultModel, defaultThinking, defaultExtensions),
+		applySubagentDefaults(builtinLoaded.agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -1952,7 +2036,7 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	const userLoaded = scope === "project" ? [] : [...extraUserAgentDirs(), userDirOld, userDirNew]
 		.map((dir, discoveryPriority) => loadAgentsFromDir(dir, "user", discoveryPriority));
 	const userAgents = applyCustomAgentOverrides(
-		applySubagentDefaults(userLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultThinking, defaultExtensions),
+		applySubagentDefaults(userLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultProvider, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -1961,7 +2045,7 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 
 	const projectLoaded = scope === "user" ? [] : projectAgentDirs.map((dir) => loadAgentsFromDir(dir, "project", dir === projectAgentsDir ? 1 : 0));
 	const projectAgents = applyCustomAgentOverrides(
-		applySubagentDefaults(projectLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultThinking, defaultExtensions),
+		applySubagentDefaults(projectLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultProvider, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -1975,14 +2059,17 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 		}
 	}
 	const packageAgents = applyCustomAgentOverrides(
-		applySubagentDefaults(Array.from(packageMap.values()), defaultModel, defaultThinking, defaultExtensions),
+		applySubagentDefaults(Array.from(packageMap.values()), defaultModel, defaultProvider, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
 		projectSettingsPath,
 	);
-	const agents = mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents, packageAgents)
-		.filter((agent) => agent.disabled !== true);
+	const agents = applySubagentMaxThinking(
+		mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents, packageAgents)
+			.filter((agent) => agent.disabled !== true),
+		maxThinking,
+	);
 
 	const agentDiagnostics = [
 		...builtinLoaded.diagnostics,
@@ -1990,7 +2077,7 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 		...projectLoaded.flatMap((loaded) => loaded.diagnostics),
 		...packageLoaded.flatMap((loaded) => loaded.diagnostics),
 	];
-	return { agents, agentDiagnostics, projectAgentsDir, ...(modelScope !== undefined ? { modelScope } : {}) };
+	return { agents, agentDiagnostics, projectAgentsDir, ...(modelScope !== undefined ? { modelScope } : {}), ...(maxThinking !== undefined ? { maxThinking } : {}) };
 }
 
 export function discoverAgentsAll(cwd: string): {
@@ -2007,6 +2094,7 @@ export function discoverAgentsAll(cwd: string): {
 	projectChainDir: string | null;
 	userSettingsPath: string;
 	projectSettingsPath: string | null;
+	maxThinking?: ThinkingLevel;
 } {
 	const userDirOld = path.join(getAgentDir(), "agents");
 	const userDirNew = path.join(os.homedir(), ".agents");
@@ -2017,14 +2105,16 @@ export function discoverAgentsAll(cwd: string): {
 	const projectSettingsPath = getProjectAgentSettingsPath(cwd);
 	const userSettings = readSubagentSettings(userSettingsPath);
 	const projectSettings = readSubagentSettings(projectSettingsPath);
-	const defaultModel = resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath);
+	const defaultProvider = resolveSubagentDefaultProvider(userSettings, projectSettings, projectSettingsPath);
+	const defaultModel = resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath, defaultProvider);
 	const defaultThinking = resolveSubagentDefaultThinking(userSettings, projectSettings, projectSettingsPath);
+	const maxThinking = resolveSubagentMaxThinking(userSettings, projectSettings, projectSettingsPath);
 	const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, projectSettingsPath);
 	const packageSubagentPaths = collectPackageSubagentPaths(cwd);
 
 	const builtinLoaded = loadAgentsFromDefinitionFiles(BUILTIN_AGENT_DEFINITION_FILES, "builtin");
 	const builtin = applyBuiltinOverrides(
-		applySubagentDefaults(builtinLoaded.agents, defaultModel, defaultThinking, defaultExtensions),
+		applySubagentDefaults(builtinLoaded.agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -2033,7 +2123,7 @@ export function discoverAgentsAll(cwd: string): {
 	const userLoaded = [...extraUserAgentDirs(), userDirOld, userDirNew]
 		.map((dir, discoveryPriority) => loadAgentsFromDir(dir, "user", discoveryPriority));
 	const user = applyCustomAgentOverrides(
-		applySubagentDefaults(userLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultThinking, defaultExtensions),
+		applySubagentDefaults(userLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultProvider, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -2049,7 +2139,7 @@ export function discoverAgentsAll(cwd: string): {
 		}
 	}
 	const packageAgents = applyCustomAgentOverrides(
-		applySubagentDefaults(Array.from(packageMap.values()), defaultModel, defaultThinking, defaultExtensions),
+		applySubagentDefaults(Array.from(packageMap.values()), defaultModel, defaultProvider, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -2065,7 +2155,7 @@ export function discoverAgentsAll(cwd: string): {
 		}
 	}
 	const project = applyCustomAgentOverrides(
-		applySubagentDefaults(Array.from(projectMap.values()), defaultModel, defaultThinking, defaultExtensions),
+		applySubagentDefaults(Array.from(projectMap.values()), defaultModel, defaultProvider, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -2110,5 +2200,20 @@ export function discoverAgentsAll(cwd: string): {
 
 	const userDir = process.env.PI_CODING_AGENT_DIR ? userDirOld : fs.existsSync(userDirNew) ? userDirNew : userDirOld;
 
-	return { builtin, package: packageAgents, user, project, agentDiagnostics, chains, chainDiagnostics, userDir, projectDir, userChainDir, projectChainDir, userSettingsPath, projectSettingsPath };
+	return {
+		builtin: applySubagentMaxThinking(builtin, maxThinking),
+		package: applySubagentMaxThinking(packageAgents, maxThinking),
+		user: applySubagentMaxThinking(user, maxThinking),
+		project: applySubagentMaxThinking(project, maxThinking),
+		agentDiagnostics,
+		chains,
+		chainDiagnostics,
+		userDir,
+		projectDir,
+		userChainDir,
+		projectChainDir,
+		userSettingsPath,
+		projectSettingsPath,
+		...(maxThinking !== undefined ? { maxThinking } : {}),
+	};
 }

package/src/api/external-job-provider.ts

@@ -9,7 +9,7 @@ const MAX_FAILURE_MESSAGE_LENGTH = 4_096;
 const MAX_URL_LENGTH = 4_096;
 
 export type ExternalJobState = "queued" | "running" | "completed" | "failed" | "stopped" | "blocked";
-export type ExternalJobOperation = "start" | "status" | "result" | "reattach";
+export type ExternalJobOperation = "start" | "follow-up" | "status" | "result" | "reattach";
 
 export type ExternalJobOptions = Record<string, unknown>;
 
@@ -24,6 +24,14 @@ export interface ExternalJobStartInput {
 	sessionId?: string;
 }
 
+export interface ExternalJobFollowUpInput extends ExternalJobStartInput {
+	sourceRunId: string;
+	sourceStepIndex: number;
+	parentProviderJobId: string;
+	requestId: string;
+	requestDigest: string;
+}
+
 export interface ExternalJobHandle {
 	providerJobId: string;
 	state: ExternalJobState;
@@ -42,6 +50,7 @@ export interface ExternalJobResult extends ExternalJobHandle {
 export interface ExternalJobProvider {
 	name: string;
 	start(input: ExternalJobStartInput): Promise<ExternalJobHandle> | ExternalJobHandle;
+	followUp?(input: ExternalJobFollowUpInput): Promise<ExternalJobHandle> | ExternalJobHandle;
 	status(providerJobId: string): Promise<ExternalJobHandle> | ExternalJobHandle;
 	result(providerJobId: string): Promise<ExternalJobResult> | ExternalJobResult;
 	reattach(providerJobId: string): Promise<ExternalJobHandle> | ExternalJobHandle;

package/src/api/preflight.ts

@@ -1,4 +1,3 @@
-import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -12,6 +11,7 @@ import { applyThinkingSuffix, resolvePiLaunchToolPlan, type PiLaunchToolPlan } f
 import { injectOutputPathSystemPrompt, normalizeSingleOutputOverride, resolveSingleOutputPath } from "../runs/shared/single-output.ts";
 import { getArtifactPaths, getArtifactsDir } from "../shared/artifacts.ts";
 import { resolveEffectiveThinking } from "../shared/model-info.ts";
+import { assertThinkingWithinCeiling, decodeThinkingCeiling, intersectThinkingCeilings, SUBAGENT_THINKING_CEILING_ENV, type ThinkingLevel } from "../shared/thinking-ceiling.ts";
 import { SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, type ArtifactDirPreference, type ArtifactPaths, type JsonSchemaObject, type OutputMode } from "../shared/types.ts";
 import { capabilityCeilingAgentRestrictionMessage, intersectSubagentCapabilityCeilings, type ResolvedSubagentCapabilityCeiling, type SubagentCapabilityAudit } from "../runs/shared/capability-ceiling.ts";
 import { appendTurnBudgetSystemPrompt } from "../runs/shared/turn-budget.ts";
@@ -21,7 +21,7 @@ import type { ResolvedMcpDirectToolSelection } from "../runs/shared/mcp-direct-t
 import { resolveStepBehavior } from "../shared/settings.ts";
 import { canPreferForkFromSnapshot, resolveSubagentLaunchContext } from "../shared/fork-context.ts";
 import { loadConfig } from "../extension/config.ts";
-import { agentDefinitionDigest, AGENT_DEFINITION_PROJECTION_VERSION, launchBindingDigest } from "../shared/launch-contract.ts";
+import { agentDefinitionDigest, AGENT_DEFINITION_PROJECTION_VERSION, launchBindingDigest, stableJsonDigest } from "../shared/launch-contract.ts";
 import { DIRS, TEMP_ROOT_DIR } from "../shared/types.ts";
 import { processTerminalCandidatePath, processTerminalPath } from "../runs/background/process-terminal.ts";
 import { resultFilePath } from "../runs/background/result-files.ts";
@@ -37,7 +37,8 @@ export type SubagentLaunchContractReasonCode =
 	| "invalid_artifact_dir"
 	| "invalid_cwd"
 	| "unsupported_mode"
-	| "restricted_agent";
+	| "restricted_agent"
+	| "thinking_ceiling";
 
 export interface SubagentLaunchContractDiagnostic {
 	code: SubagentLaunchContractReasonCode | "host_required" | "snapshot_warning";
@@ -53,6 +54,8 @@ export interface SubagentLaunchContractInput {
 	context?: "fresh" | "fork";
 	model?: string;
 	thinking?: string | false;
+	thinkingCeiling?: ThinkingLevel;
+	inheritedThinkingCeiling?: ThinkingLevel;
 	parentModel?: ParentModel;
 	availableModels?: ReadonlyArray<AvailableModelInfo | { provider: string; id: string; fullId?: string; reasoning?: boolean }>;
 	preferredProvider?: string;
@@ -147,6 +150,7 @@ export interface SubagentLaunchContract {
 	model?: string;
 	modelCandidates: string[];
 	thinking?: string;
+	thinkingCeiling?: ThinkingLevel;
 	systemPromptMode: AgentConfig["systemPromptMode"];
 	inheritProjectContext: boolean;
 	inheritSkills: boolean;
@@ -176,20 +180,8 @@ function packageVersion(): string {
 	return parsed.version;
 }
 
-function stableJson(value: unknown): string {
-	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
-	if (value && typeof value === "object") {
-		return `{${Object.entries(value as Record<string, unknown>)
-			.filter(([, entry]) => entry !== undefined)
-			.sort(([a], [b]) => a.localeCompare(b))
-			.map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
-			.join(",")}}`;
-	}
-	return JSON.stringify(value);
-}
-
 function digestContract(contract: Omit<SubagentLaunchContract, "digest">): string {
-	return createHash("sha256").update(stableJson(contract)).digest("hex");
+	return stableJsonDigest(contract);
 }
 
 function normalizeAvailableModels(models: SubagentLaunchContractInput["availableModels"]): AvailableModelInfo[] {
@@ -289,12 +281,18 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 
 	const externalRunner = agent.runner?.type === "external-cli" || agent.runner?.type === "external-job";
 	const availableModels = normalizeAvailableModels(input.availableModels);
-	const preferredProvider = input.preferredProvider ?? input.parentModel?.provider;
+	const preferredProvider = agent.modelProvider ?? input.preferredProvider ?? input.parentModel?.provider;
 	const modelScopes = resolveModelScopesForAgent(discovered.modelScope, agent.name, input.parentModel);
 	const primaryModel = externalRunner
 		? undefined
 		: resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, { scope: modelScopes });
 	const effectiveThinkingConfig = input.thinking !== undefined ? input.thinking : agent.thinking;
+	const thinkingCeiling = externalRunner ? undefined : intersectThinkingCeilings(
+		discovered.maxThinking,
+		input.thinkingCeiling,
+		input.inheritedThinkingCeiling,
+		decodeThinkingCeiling(process.env[SUBAGENT_THINKING_CEILING_ENV]),
+	);
 	const model = externalRunner ? undefined : applyThinkingSuffix(primaryModel, effectiveThinkingConfig, input.thinking !== undefined);
 	const modelCandidates = externalRunner
 		? []
@@ -303,6 +301,16 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 			primaryModelFromParent: inheritsParentModel(input.model, agent.model, input.parentModel),
 		})
 			.map((candidate) => applyThinkingSuffix(candidate, effectiveThinkingConfig, input.thinking !== undefined) ?? candidate);
+	if (!externalRunner) {
+		try {
+			assertThinkingWithinCeiling({ model, configThinking: effectiveThinkingConfig, ceiling: thinkingCeiling, agent: agent.name, runId });
+			for (const candidate of modelCandidates) assertThinkingWithinCeiling({ model: candidate, configThinking: effectiveThinkingConfig, ceiling: thinkingCeiling, agent: agent.name, runId });
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			diagnostics.push({ code: "thinking_ceiling", severity: "error", message });
+			return { ok: false, code: "thinking_ceiling", message, diagnostics };
+		}
+	}
 	let toolPlan: PiLaunchToolPlan;
 	const permissionRules = resolvePermissionRules(loadConfig().permissions, agent.permissions);
 	try {
@@ -372,6 +380,7 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 		...(model ? { model } : {}),
 		modelCandidates,
 		...(resolveEffectiveThinking(model, effectiveThinkingConfig) ? { thinking: resolveEffectiveThinking(model, effectiveThinkingConfig) } : {}),
+		...(thinkingCeiling ? { thinkingCeiling } : {}),
 		systemPromptMode: agent.systemPromptMode,
 		inheritProjectContext: agent.inheritProjectContext,
 		inheritSkills: agent.inheritSkills,

package/src/api/project-panes.ts

@@ -10,6 +10,7 @@ export {
 	createProjectPaneManager,
 	openProjectPane,
 	getProjectPaneStatus,
+	focusProjectPane,
 	closeProjectPane,
 	readProjectPaneBinding,
 	projectPaneBindingPath,
@@ -21,6 +22,7 @@ export {
 	type CloseProjectPaneOptions,
 	type OpenProjectPaneData,
 	type ProjectPaneStatusData,
+	type FocusProjectPaneData,
 	type CloseProjectPaneData,
 	type ProjectPaneRuntime,
 	type ProjectPaneError,