pi-subagents 0.16.1 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-04-16
+
+### Added
+- Builtin agents can now be disabled through `subagents.agentOverrides.<name>.disabled` or the bulk `subagents.disableBuiltins` setting, with `/agents` keeping disabled builtins visible so they can be re-enabled from the manager. This builds on PR `#81`. Thanks @danielcherubini.
+
+### Fixed
+- Builtin disable precedence is now coherent across user and project settings: project overrides beat user overrides, project bulk disable beats user re-enable attempts, and same-scope per-agent overrides can opt an agent out of bulk disable.
+- `/agents` now blocks launching disabled builtins, shows their disabled state in list/detail views and management output, and avoids exposing the builtin-only `disabled` field when editing normal user/project agents.
+- Multi-agent chain launches from `/agents` now collect a task before dispatching instead of emitting an empty task, and settings read failures now surface as read errors instead of being mislabeled as parse failures.
+
 ## [0.16.1] - 2026-04-16
 
 ### Changed

package/README.md

@@ -53,7 +53,7 @@ You can also override selected builtin fields without copying the whole agent. B
 - User scope: `~/.pi/agent/settings.json`
 - Project scope: `.pi/settings.json`
 
-Supported builtin override fields are `model`, `fallbackModels`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `skills`, `tools`, and `systemPrompt`. Project overrides beat user overrides.
+Supported builtin override fields are `model`, `fallbackModels`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `disabled`, `skills`, `tools`, and `systemPrompt`. Project overrides beat user overrides.
 
 **Overriding builtin defaults:**
 
@@ -74,7 +74,9 @@ All builtin agents inherit project instruction files (`AGENTS.md`, `CLAUDE.md`,
 
 **Via `/agents` UI** — press `e` on any builtin agent (like `reviewer`), then toggle `inheritProjectContext` to `false` and save. This creates an override that you can edit or remove later without modifying the builtin definition itself.
 
-Overridden builtins show badges like `[builtin+user]` or `[builtin+project]` to indicate they have customizations applied.
+Set `disabled: true` inside an agent override to hide one builtin from runtime discovery while still keeping it visible in `/agents` so you can re-enable it later. For bulk control, set `subagents.disableBuiltins: true` in `settings.json`; project scope beats user scope, and an explicit same-scope override can opt one builtin back in with `disabled: false` or any other override fields.
+
+Overridden builtins show badges like `[builtin+user]` or `[builtin+project]`. Disabled builtins show `off` badges in the manager so they are easy to spot and re-enable.
 
 > **Note:** The `researcher` agent uses `web_search`, `fetch_content`, and `get_search_content` tools which require the [pi-web-access](https://github.com/nicobailon/pi-web-access) extension. Install it with `pi install npm:pi-web-access`.
 

package/agent-management.ts

@@ -338,6 +338,7 @@ export function formatAgentDetail(agent: AgentConfig): string {
 	lines.push(`System prompt mode: ${agent.systemPromptMode}`);
 	lines.push(`Inherit project context: ${agent.inheritProjectContext ? "true" : "false"}`);
 	lines.push(`Inherit skills: ${agent.inheritSkills ? "true" : "false"}`);
+	if (agent.source === "builtin") lines.push(`Disabled: ${agent.disabled ? "true" : "false"}`);
 	if (agent.extensions !== undefined) lines.push(`Extensions: ${agent.extensions.length ? agent.extensions.join(", ") : "(none)"}`);
 	if (agent.thinking) lines.push(`Thinking: ${agent.thinking}`);
 	if (agent.output) lines.push(`Output: ${agent.output}`);
@@ -371,7 +372,7 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 	const d = discoverAgentsAll(ctx.cwd);
 	const agents = allAgents(d).filter((a) => scope === "both" || a.source === "builtin" || a.source === scope).sort((a, b) => a.name.localeCompare(b.name));
 	const chains = d.chains.filter((c) => scope === "both" || c.source === scope).sort((a, b) => a.name.localeCompare(b.name));
-	const lines = ["Agents:", ...(agents.length ? agents.map((a) => `- ${a.name} (${a.source}): ${a.description}`) : ["- (none)"]), "", "Chains:", ...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"])];
+	const lines = ["Agents:", ...(agents.length ? agents.map((a) => `- ${a.name} (${a.source}${a.disabled ? ", disabled" : ""}): ${a.description}`) : ["- (none)"]), "", "Chains:", ...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"])];
 	return result(lines.join("\n"));
 }
 

package/agent-manager-detail.ts

@@ -64,6 +64,9 @@ function buildDetailLines(
 	lines.push(renderFieldLine("Prompt mode:", agent.systemPromptMode, contentWidth, theme));
 	lines.push(renderFieldLine("Project ctx:", agent.inheritProjectContext ? "on" : "off", contentWidth, theme));
 	lines.push(renderFieldLine("Skills ctx:", agent.inheritSkills ? "on" : "off", contentWidth, theme));
+	if (agent.source === "builtin") {
+		lines.push(renderFieldLine("Disabled:", agent.disabled ? "on" : "off", contentWidth, theme));
+	}
 	if (agent.override) {
 		const overrideLabel = `${agent.override.scope} · ${formatPath(agent.override.path)}`;
 		lines.push(renderFieldLine("Override:", overrideLabel, contentWidth, theme));
@@ -139,7 +142,9 @@ export function renderDetail(
 ): string[] {
 	const lines: string[] = [];
 	const scopeBadge = agent.source === "builtin"
-		? (agent.override ? `[builtin+${agent.override.scope}]` : "[builtin]")
+		? (agent.disabled
+			? (agent.override ? `[builtin off+${agent.override.scope}]` : "[builtin off]")
+			: (agent.override ? `[builtin+${agent.override.scope}]` : "[builtin]"))
 		: agent.source === "project"
 			? "[proj]"
 			: "[user]";
@@ -164,8 +169,12 @@ export function renderDetail(
 
 	const footer = agent.source === "builtin"
 		? agent.override
-			? " [l]aunch  [e]dit override  [v] raw/resolved  [↑↓] scroll  [esc] back "
-			: " [l]aunch  [e]create override  [v] raw/resolved  [↑↓] scroll  [esc] back "
+			? (agent.disabled
+				? " [e]dit override  [v] raw/resolved  [↑↓] scroll  [esc] back "
+				: " [l]aunch  [e]dit override  [v] raw/resolved  [↑↓] scroll  [esc] back ")
+			: (agent.disabled
+				? " [e]create override  [v] raw/resolved  [↑↓] scroll  [esc] back "
+				: " [l]aunch  [e]create override  [v] raw/resolved  [↑↓] scroll  [esc] back ")
 		: " [l]aunch  [e]dit  [v] raw/resolved  [↑↓] scroll  [esc] back ";
 	lines.push(renderFooter(footer, width, theme));
 	return lines;

package/agent-manager-edit.ts

@@ -48,6 +48,7 @@ function fieldValueMatchesBase(field: EditField, state: EditState): boolean {
 		case "systemPromptMode": return state.draft.systemPromptMode === base.systemPromptMode;
 		case "inheritProjectContext": return state.draft.inheritProjectContext === base.inheritProjectContext;
 		case "inheritSkills": return state.draft.inheritSkills === base.inheritSkills;
+		case "disabled": return state.draft.disabled === base.disabled;
 		case "tools": return arraysEqual(toolList(state.draft), toolList(base));
 		case "skills": return arraysEqual(state.draft.skills, base.skills);
 		case "prompt": return state.draft.systemPrompt === base.systemPrompt;
@@ -65,6 +66,7 @@ function resetFieldToBase(field: EditField, state: EditState): void {
 		case "systemPromptMode": state.draft.systemPromptMode = base.systemPromptMode; break;
 		case "inheritProjectContext": state.draft.inheritProjectContext = base.inheritProjectContext; break;
 		case "inheritSkills": state.draft.inheritSkills = base.inheritSkills; break;
+		case "disabled": state.draft.disabled = base.disabled; break;
 		case "tools": state.draft.tools = base.tools ? [...base.tools] : undefined; state.draft.mcpDirectTools = base.mcpDirectTools ? [...base.mcpDirectTools] : undefined; break;
 		case "skills": state.draft.skills = base.skills ? [...base.skills] : undefined; break;
 		case "prompt": state.draft.systemPrompt = base.systemPrompt; state.promptEditor = createEditorState(base.systemPrompt); break;
@@ -92,6 +94,7 @@ function renderFieldValue(field: EditField, state: EditState): string {
 		case "systemPromptMode": return draft.systemPromptMode ?? defaultSystemPromptMode(draft.name);
 		case "inheritProjectContext": return draft.inheritProjectContext ? "on" : "off";
 		case "inheritSkills": return draft.inheritSkills ? "on" : "off";
+		case "disabled": return draft.disabled ? "on" : "off";
 		case "tools": return formatTools(draft);
 		case "extensions": return draft.extensions !== undefined ? (draft.extensions.length > 0 ? draft.extensions.join(", ") : "") : "(all)";
 		case "skills": return draft.skills && draft.skills.length > 0 ? draft.skills.join(", ") : "";
@@ -128,6 +131,7 @@ function applyFieldValue(field: EditField, state: EditState, value: string): voi
 		case "reads": draft.defaultReads = parseCommaList(value); break;
 		case "inheritProjectContext":
 		case "inheritSkills":
+		case "disabled":
 		case "progress":
 		case "interactive":
 		case "prompt":
@@ -256,9 +260,10 @@ export function handleEditInput(screen: EditScreen, state: EditState, data: stri
 		if (data === "m") { openModelPicker(state, models); return { nextScreen: "edit-field" }; }
 		if (data === "t") { openThinkingPicker(state); return { nextScreen: "edit-field" }; }
 		if (data === "s") { openSkillPicker(state, skills); return { nextScreen: "edit-field" }; }
-		if (data === " " && (field === "inheritProjectContext" || field === "inheritSkills" || field === "progress" || field === "interactive")) {
+		if (data === " " && (field === "inheritProjectContext" || field === "inheritSkills" || field === "disabled" || field === "progress" || field === "interactive")) {
 			if (field === "inheritProjectContext") state.draft.inheritProjectContext = !state.draft.inheritProjectContext;
 			if (field === "inheritSkills") state.draft.inheritSkills = !state.draft.inheritSkills;
+			if (field === "disabled") state.draft.disabled = !state.draft.disabled;
 			if (field === "progress") state.draft.defaultProgress = !state.draft.defaultProgress;
 			if (field === "interactive") state.draft.interactive = !state.draft.interactive;
 			return;
@@ -268,7 +273,7 @@ export function handleEditInput(screen: EditScreen, state: EditState, data: stri
 			if (field === "thinking") { openThinkingPicker(state); return { nextScreen: "edit-field" }; }
 			if (field === "skills") { openSkillPicker(state, skills); return { nextScreen: "edit-field" }; }
 			if (field === "prompt") { state.promptEditor = createEditorState(state.draft.systemPrompt ?? ""); return { nextScreen: "edit-prompt" }; }
-			if (field === "inheritProjectContext" || field === "inheritSkills" || field === "progress" || field === "interactive") return;
+			if (field === "inheritProjectContext" || field === "inheritSkills" || field === "disabled" || field === "progress" || field === "interactive") return;
 			state.fieldMode = "text"; state.fieldEditor = createEditorState(renderFieldValue(field, state)); return { nextScreen: "edit-field" };
 		}
 		return;
@@ -341,11 +346,14 @@ export function renderEdit(screen: EditScreen, state: EditState, width: number,
 				? "Project Ctx"
 				: field === "inheritSkills"
 					? "Skills Ctx"
+					: field === "disabled"
+						? "Disabled"
 					: `${field[0]!.toUpperCase()}${field.slice(1)}`;
 		const rawLabel = pad(`${fieldLabel}:`, labelWidth);
 		const labelText = state.overrideBase && !fieldValueMatchesBase(field, state) ? theme.fg("accent", rawLabel) : rawLabel; let valueText = renderFieldValue(field, state);
 		if (field === "inheritProjectContext") { const toggle = state.draft.inheritProjectContext ? theme.fg("success", "[x]") : "[ ]"; valueText = `${toggle} ${state.draft.inheritProjectContext ? "on" : "off"}`; lines.push(row(` ${prefix}${labelText} ${pad(truncateToWidth(valueText, valueWidth), valueWidth)}`, width, theme)); continue; }
 		if (field === "inheritSkills") { const toggle = state.draft.inheritSkills ? theme.fg("success", "[x]") : "[ ]"; valueText = `${toggle} ${state.draft.inheritSkills ? "on" : "off"}`; lines.push(row(` ${prefix}${labelText} ${pad(truncateToWidth(valueText, valueWidth), valueWidth)}`, width, theme)); continue; }
+		if (field === "disabled") { const toggle = state.draft.disabled ? theme.fg("warning", "[x]") : "[ ]"; valueText = `${toggle} ${state.draft.disabled ? "on" : "off"}`; lines.push(row(` ${prefix}${labelText} ${pad(truncateToWidth(valueText, valueWidth), valueWidth)}`, width, theme)); continue; }
 		if (field === "progress") { const toggle = state.draft.defaultProgress ? theme.fg("success", "[x]") : "[ ]"; valueText = `${toggle} ${state.draft.defaultProgress ? "on" : "off"}`; lines.push(row(` ${prefix}${labelText} ${pad(truncateToWidth(valueText, valueWidth), valueWidth)}`, width, theme)); continue; }
 		if (field === "interactive") { const toggle = state.draft.interactive ? theme.fg("success", "[x]") : "[ ]"; valueText = `${toggle} ${state.draft.interactive ? "on" : "off"}`; lines.push(row(` ${prefix}${labelText} ${pad(truncateToWidth(valueText, valueWidth), valueWidth)}`, width, theme)); continue; }
 		let displayValue = truncateToWidth(valueText, valueWidth);

package/agent-manager-list.ts

@@ -10,6 +10,7 @@ export interface ListAgent {
 	model?: string;
 	source: AgentSource;
 	overrideScope?: "user" | "project";
+	disabled?: boolean;
 	kind: "agent" | "chain";
 	stepCount?: number;
 }
@@ -191,7 +192,7 @@ export function renderList(
 		const innerW = width - 2;
 		const nameWidth = 16;
 		const modelWidth = 12;
-		const scopeWidth = 17;
+		const scopeWidth = 21;
 
 		for (let i = 0; i < visible.length; i++) {
 			const agent = visible[i]!;
@@ -212,7 +213,9 @@ export function renderList(
 			const scopeLabel = agent.kind === "chain"
 				? "[chain]"
 				: agent.source === "builtin"
-					? (agent.overrideScope ? `[builtin+${agent.overrideScope}]` : "[builtin]")
+					? (agent.disabled
+						? (agent.overrideScope ? `[builtin off+${agent.overrideScope}]` : "[builtin off]")
+						: (agent.overrideScope ? `[builtin+${agent.overrideScope}]` : "[builtin]"))
 					: agent.source === "project"
 						? "[proj]"
 						: "[user]";

package/agent-manager.ts

@@ -43,7 +43,7 @@ interface NameInputState { mode: "new-agent" | "clone-agent" | "clone-chain" | "
 interface StatusMessage { text: string; type: "error" | "info"; }
 interface OverrideScopeState { selectedScope: "user" | "project"; allowProject: boolean; }
 
-const BUILTIN_OVERRIDE_FIELDS: EditField[] = ["model", "fallbackModels", "thinking", "systemPromptMode", "inheritProjectContext", "inheritSkills", "tools", "skills", "prompt"];
+const BUILTIN_OVERRIDE_FIELDS: EditField[] = ["model", "fallbackModels", "thinking", "systemPromptMode", "inheritProjectContext", "inheritSkills", "disabled", "tools", "skills", "prompt"];
 
 function cloneConfig(config: AgentConfig): AgentConfig {
 	return {
@@ -59,6 +59,7 @@ function cloneConfig(config: AgentConfig): AgentConfig {
 				...config.override,
 				base: {
 					...config.override.base,
+					disabled: config.override.base.disabled,
 					fallbackModels: config.override.base.fallbackModels ? [...config.override.base.fallbackModels] : undefined,
 					skills: config.override.base.skills ? [...config.override.base.skills] : undefined,
 					tools: config.override.base.tools ? [...config.override.base.tools] : undefined,
@@ -124,8 +125,9 @@ export class AgentManagerComponent implements Component {
 
 	private getAgentEntry(id: string | null): AgentEntry | undefined { if (!id) return undefined; return this.agents.find((entry) => entry.id === id); }
 	private getChainEntry(id: string | null): ChainEntry | undefined { if (!id) return undefined; return this.chains.find((entry) => entry.id === id); }
-	private listAgents(): ListAgent[] { const a = this.agents.map((entry) => ({ id: entry.id, name: entry.config.name, description: entry.config.description, model: entry.config.model, source: entry.config.source, overrideScope: entry.config.override?.scope, kind: "agent" as const })); const c = this.chains.map((entry) => ({ id: entry.id, name: entry.config.name, description: entry.config.description, source: entry.config.source, kind: "chain" as const, stepCount: entry.config.steps.length })); return [...a, ...c]; }
+	private listAgents(): ListAgent[] { const a = this.agents.map((entry) => ({ id: entry.id, name: entry.config.name, description: entry.config.description, model: entry.config.model, source: entry.config.source, overrideScope: entry.config.override?.scope, disabled: entry.config.disabled, kind: "agent" as const })); const c = this.chains.map((entry) => ({ id: entry.id, name: entry.config.name, description: entry.config.description, source: entry.config.source, kind: "chain" as const, stepCount: entry.config.steps.length })); return [...a, ...c]; }
 	private clearStatus(): void { this.statusMessage = undefined; }
+	private disabledAgentEntries(ids: string[]): AgentEntry[] { return ids.map((id) => this.getAgentEntry(id)).filter((entry): entry is AgentEntry => Boolean(entry?.config.disabled)); }
 
 	private resolveBuiltinOverrideBase(entry: AgentEntry): BuiltinAgentOverrideBase {
 		if (entry.config.override) return entry.config.override.base;
@@ -136,6 +138,7 @@ export class AgentManagerComponent implements Component {
 			systemPromptMode: entry.config.systemPromptMode,
 			inheritProjectContext: entry.config.inheritProjectContext,
 			inheritSkills: entry.config.inheritSkills,
+			disabled: entry.config.disabled,
 			systemPrompt: entry.config.systemPrompt,
 			skills: entry.config.skills ? [...entry.config.skills] : undefined,
 			tools: entry.config.tools ? [...entry.config.tools] : undefined,
@@ -185,11 +188,6 @@ export class AgentManagerComponent implements Component {
 		this.screen = "parallel-builder";
 	}
 	private enterTaskInput(ids: string[], backScreen: ManagerScreen = "list"): void {
-		if (ids.length > 1) {
-			const names = ids.map((id) => { const e = this.getAgentEntry(id); return e ? e.config.name : id; });
-			this.done({ action: "chain", agents: names, task: "", skipClarify: false });
-			return;
-		}
 		this.chainAgentIds = ids; this.chainLaunchId = null; this.parallelMode = false; this.taskBackScreen = backScreen; this.taskEditor = createEditorState(); this.skipClarify = true; this.screen = "task-input";
 	}
 	private enterSavedChainLaunch(entry: ChainEntry): void { this.chainLaunchId = entry.id; this.chainAgentIds = []; this.parallelMode = false; this.taskBackScreen = "chain-detail"; this.taskEditor = createEditorState(); this.skipClarify = true; this.screen = "task-input"; }
@@ -507,6 +505,13 @@ export class AgentManagerComponent implements Component {
 						const tasks = this.parallelState.slots.map((slot) => ({ agent: slot.agentName, task: slot.customTask || sharedTask }));
 						this.done({ action: "parallel", tasks, skipClarify: this.skipClarify }); return;
 					}
+					if (this.chainAgentIds.length > 1) {
+						const agents = this.chainAgentIds
+							.map((id) => this.getAgentEntry(id)?.config.name)
+							.filter((name): name is string => Boolean(name));
+						if (agents.length !== this.chainAgentIds.length) { this.screen = "list"; this.tui.requestRender(); return; }
+						this.done({ action: "chain", agents, task: this.taskEditor.buffer, skipClarify: this.skipClarify }); return;
+					}
 					const name = this.getAgentEntry(this.chainAgentIds[0] ?? null)?.config.name;
 					if (!name) { this.screen = "list"; this.tui.requestRender(); return; }
 					this.done({ action: "launch", agent: name, task: this.taskEditor.buffer, skipClarify: this.skipClarify }); return;
@@ -562,8 +567,24 @@ export class AgentManagerComponent implements Component {
 			case "clone": if (this.getAgentEntry(action.id)) this.enterNameInput("clone-agent", action.id); else if (this.getChainEntry(action.id)) this.enterNameInput("clone-chain", action.id); return;
 			case "new": this.enterTemplateSelect(); return;
 			case "delete": { if (this.isBuiltin(action.id)) { this.statusMessage = { text: "Builtin agents cannot be deleted. Clone to user scope to override.", type: "error" }; return; } this.confirmDeleteId = action.id; this.screen = "confirm-delete"; return; }
-			case "run-chain": this.enterTaskInput(action.ids); return;
-			case "run-parallel": this.enterParallelBuilder(action.ids); return;
+			case "run-chain": {
+				const disabled = this.disabledAgentEntries(action.ids);
+				if (disabled.length > 0) {
+					this.statusMessage = { text: `Disabled builtin agents cannot run: ${disabled.map((entry) => entry.config.name).join(", ")}. Edit the override to re-enable them.`, type: "error" };
+					return;
+				}
+				this.enterTaskInput(action.ids);
+				return;
+			}
+			case "run-parallel": {
+				const disabled = this.disabledAgentEntries(action.ids);
+				if (disabled.length > 0) {
+					this.statusMessage = { text: `Disabled builtin agents cannot run: ${disabled.map((entry) => entry.config.name).join(", ")}. Edit the override to re-enable them.`, type: "error" };
+					return;
+				}
+				this.enterParallelBuilder(action.ids);
+				return;
+			}
 			case "close": this.done(undefined); return;
 		}
 	}
@@ -579,7 +600,11 @@ export class AgentManagerComponent implements Component {
 			this.enterEdit(entry);
 			return;
 		}
-		if (action.type === "launch") { this.enterTaskInput([entry.id], "detail"); return; }
+		if (action.type === "launch") {
+			if (entry.config.disabled) return;
+			this.enterTaskInput([entry.id], "detail");
+			return;
+		}
 	}
 
 	private handleChainDetailAction(action: ChainDetailAction, entry: ChainEntry): void {
@@ -605,6 +630,12 @@ export class AgentManagerComponent implements Component {
 			case "task-input": {
 				if (this.chainLaunchId) { const entry = this.getChainEntry(this.chainLaunchId); const title = entry ? `Chain: ${entry.config.name}` : "Chain"; return renderTaskInput(title, this.taskEditor, this.skipClarify, w, this.theme); }
 				if (this.parallelMode && this.parallelState) return renderTaskInput(formatParallelTitle(this.parallelState.slots), this.taskEditor, this.skipClarify, w, this.theme);
+				if (this.chainAgentIds.length > 1) {
+					const names = this.chainAgentIds
+						.map((id) => this.getAgentEntry(id)?.config.name)
+						.filter((name): name is string => Boolean(name));
+					return renderTaskInput(`Chain: ${names.join(" → ")}`, this.taskEditor, this.skipClarify, w, this.theme);
+				}
 				const name = this.getAgentEntry(this.chainAgentIds[0] ?? null)?.config.name ?? "Agent";
 				return renderTaskInput(`Run: ${name}`, this.taskEditor, this.skipClarify, w, this.theme);
 			}

package/agents.ts

@@ -35,6 +35,7 @@ export interface BuiltinAgentOverrideBase {
 	systemPromptMode: SystemPromptMode;
 	inheritProjectContext: boolean;
 	inheritSkills: boolean;
+	disabled?: boolean;
 	systemPrompt: string;
 	skills?: string[];
 	tools?: string[];
@@ -48,6 +49,7 @@ export interface BuiltinAgentOverrideConfig {
 	systemPromptMode?: SystemPromptMode;
 	inheritProjectContext?: boolean;
 	inheritSkills?: boolean;
+	disabled?: boolean;
 	systemPrompt?: string;
 	skills?: string[] | false;
 	tools?: string[] | false;
@@ -80,10 +82,18 @@ export interface AgentConfig {
 	defaultProgress?: boolean;
 	interactive?: boolean;
 	maxSubagentDepth?: number;
+	disabled?: boolean;
 	extraFields?: Record<string, string>;
 	override?: BuiltinAgentOverrideInfo;
 }
 
+interface SubagentSettings {
+	overrides: Record<string, BuiltinAgentOverrideConfig>;
+	disableBuiltins?: boolean;
+}
+
+const EMPTY_SUBAGENT_SETTINGS: SubagentSettings = { overrides: {} };
+
 export interface ChainStepConfig {
 	agent: string;
 	task: string;
@@ -150,6 +160,7 @@ function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
 		systemPromptMode: agent.systemPromptMode,
 		inheritProjectContext: agent.inheritProjectContext,
 		inheritSkills: agent.inheritSkills,
+		disabled: agent.disabled,
 		systemPrompt: agent.systemPrompt,
 		skills: agent.skills ? [...agent.skills] : undefined,
 		tools: agent.tools ? [...agent.tools] : undefined,
@@ -167,6 +178,7 @@ function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentO
 		...(override.systemPromptMode !== undefined ? { systemPromptMode: override.systemPromptMode } : {}),
 		...(override.inheritProjectContext !== undefined ? { inheritProjectContext: override.inheritProjectContext } : {}),
 		...(override.inheritSkills !== undefined ? { inheritSkills: override.inheritSkills } : {}),
+		...(override.disabled !== undefined ? { disabled: override.disabled } : {}),
 		...(override.systemPrompt !== undefined ? { systemPrompt: override.systemPrompt } : {}),
 		...(override.skills !== undefined ? { skills: override.skills === false ? false : [...override.skills] } : {}),
 		...(override.tools !== undefined ? { tools: override.tools === false ? false : [...override.tools] } : {}),
@@ -197,9 +209,17 @@ export function getProjectAgentSettingsPath(cwd: string): string | null {
 
 function readSettingsFileStrict(filePath: string): Record<string, unknown> {
 	if (!fs.existsSync(filePath)) return {};
+	let raw: string;
+	try {
+		raw = fs.readFileSync(filePath, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to read settings file '${filePath}': ${message}`, { cause: error });
+	}
+
 	let parsed: unknown;
 	try {
-		parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+		parsed = JSON.parse(raw);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		throw new Error(`Failed to parse settings file '${filePath}': ${message}`, { cause: error });
@@ -282,6 +302,14 @@ function parseBuiltinOverrideEntry(
 		}
 	}
 
+	if ("disabled" in input) {
+		if (typeof input.disabled === "boolean") {
+			override.disabled = input.disabled;
+		} else {
+			throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'disabled'; expected a boolean.`);
+		}
+	}
+
 	if ("systemPrompt" in input) {
 		if (typeof input.systemPrompt === "string") override.systemPrompt = input.systemPrompt;
 		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'systemPrompt'; expected a string.`);
@@ -299,20 +327,32 @@ function parseBuiltinOverrideEntry(
 	return Object.keys(override).length > 0 ? override : undefined;
 }
 
-function readBuiltinOverrides(filePath: string | null): Record<string, BuiltinAgentOverrideConfig> {
-	if (!filePath || !fs.existsSync(filePath)) return {};
+function readSubagentSettings(filePath: string | null): SubagentSettings {
+	if (!filePath) return EMPTY_SUBAGENT_SETTINGS;
 	const settings = readSettingsFileStrict(filePath);
 	const subagents = settings.subagents;
-	if (!subagents || typeof subagents !== "object" || Array.isArray(subagents)) return {};
-	const agentOverrides = (subagents as Record<string, unknown>).agentOverrides;
-	if (!agentOverrides || typeof agentOverrides !== "object" || Array.isArray(agentOverrides)) return {};
+	if (!subagents || typeof subagents !== "object" || Array.isArray(subagents)) return EMPTY_SUBAGENT_SETTINGS;
+
+	const subagentsObject = subagents as Record<string, unknown>;
+	let disableBuiltins: boolean | undefined;
+	if ("disableBuiltins" in subagentsObject) {
+		if (typeof subagentsObject.disableBuiltins === "boolean") {
+			disableBuiltins = subagentsObject.disableBuiltins;
+		} else {
+			throw new Error(`Subagent settings in '${filePath}' have invalid 'disableBuiltins'; expected a boolean.`);
+		}
+	}
 
 	const parsed: Record<string, BuiltinAgentOverrideConfig> = {};
+	const agentOverrides = subagentsObject.agentOverrides;
+	if (!agentOverrides || typeof agentOverrides !== "object" || Array.isArray(agentOverrides)) {
+		return { overrides: parsed, disableBuiltins };
+	}
 	for (const [name, value] of Object.entries(agentOverrides)) {
 		const override = parseBuiltinOverrideEntry(name, value, filePath);
 		if (override) parsed[name] = override;
 	}
-	return parsed;
+	return { overrides: parsed, disableBuiltins };
 }
 
 function applyBuiltinOverride(
@@ -333,6 +373,7 @@ function applyBuiltinOverride(
 	if (override.systemPromptMode !== undefined) next.systemPromptMode = override.systemPromptMode;
 	if (override.inheritProjectContext !== undefined) next.inheritProjectContext = override.inheritProjectContext;
 	if (override.inheritSkills !== undefined) next.inheritSkills = override.inheritSkills;
+	if (override.disabled !== undefined) next.disabled = override.disabled;
 	if (override.systemPrompt !== undefined) next.systemPrompt = override.systemPrompt;
 	if (override.skills !== undefined) next.skills = override.skills === false ? undefined : [...override.skills];
 	if (override.tools !== undefined) {
@@ -346,29 +387,40 @@ function applyBuiltinOverride(
 
 function applyBuiltinOverrides(
 	builtinAgents: AgentConfig[],
-	userOverrides: Record<string, BuiltinAgentOverrideConfig>,
-	projectOverrides: Record<string, BuiltinAgentOverrideConfig>,
+	userSettings: SubagentSettings,
+	projectSettings: SubagentSettings,
 	userSettingsPath: string,
 	projectSettingsPath: string | null,
 ): AgentConfig[] {
+	const projectBulkDisabled = projectSettings.disableBuiltins === true && projectSettingsPath !== null;
+	const userBulkDisabled = projectSettings.disableBuiltins === undefined && userSettings.disableBuiltins === true;
+
 	return builtinAgents.map((agent) => {
-		const projectOverride = projectOverrides[agent.name];
+		const projectOverride = projectSettings.overrides[agent.name];
 		if (projectOverride && projectSettingsPath) {
 			return applyBuiltinOverride(agent, projectOverride, { scope: "project", path: projectSettingsPath });
 		}
 
-		const userOverride = userOverrides[agent.name];
+		if (projectBulkDisabled && projectSettingsPath) {
+			return applyBuiltinOverride(agent, { disabled: true }, { scope: "project", path: projectSettingsPath });
+		}
+
+		const userOverride = userSettings.overrides[agent.name];
 		if (userOverride) {
 			return applyBuiltinOverride(agent, userOverride, { scope: "user", path: userSettingsPath });
 		}
 
+		if (userBulkDisabled) {
+			return applyBuiltinOverride(agent, { disabled: true }, { scope: "user", path: userSettingsPath });
+		}
+
 		return agent;
 	});
 }
 
 export function buildBuiltinOverrideConfig(
 	base: BuiltinAgentOverrideBase,
-	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools">,
+	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools">,
 ): BuiltinAgentOverrideConfig | undefined {
 	const override: BuiltinAgentOverrideConfig = {};
 
@@ -378,6 +430,7 @@ export function buildBuiltinOverrideConfig(
 	if (draft.systemPromptMode !== base.systemPromptMode) override.systemPromptMode = draft.systemPromptMode;
 	if (draft.inheritProjectContext !== base.inheritProjectContext) override.inheritProjectContext = draft.inheritProjectContext;
 	if (draft.inheritSkills !== base.inheritSkills) override.inheritSkills = draft.inheritSkills;
+	if (draft.disabled !== base.disabled) override.disabled = draft.disabled ?? false;
 	if (draft.systemPrompt !== base.systemPrompt) override.systemPrompt = draft.systemPrompt;
 	if (!arraysEqual(draft.skills, base.skills)) override.skills = draft.skills ? [...draft.skills] : false;
 
@@ -621,7 +674,6 @@ function resolveNearestProjectAgentDirs(cwd: string): { readDirs: string[]; pref
 		preferredDir,
 	};
 }
-
 const BUILTIN_AGENTS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "agents");
 
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
@@ -630,11 +682,13 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	const { readDirs: projectAgentDirs, preferredDir: projectAgentsDir } = resolveNearestProjectAgentDirs(cwd);
 	const userSettingsPath = getUserAgentSettingsPath();
 	const projectSettingsPath = getProjectAgentSettingsPath(cwd);
+	const userSettings = scope === "project" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(userSettingsPath);
+	const projectSettings = scope === "user" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(projectSettingsPath);
 
 	const builtinAgents = applyBuiltinOverrides(
 		loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"),
-		scope === "project" ? {} : readBuiltinOverrides(userSettingsPath),
-		scope === "user" ? {} : readBuiltinOverrides(projectSettingsPath),
+		userSettings,
+		projectSettings,
 		userSettingsPath,
 		projectSettingsPath,
 	);
@@ -644,7 +698,8 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	const userAgents = [...userAgentsOld, ...userAgentsNew];
 
 	const projectAgents = scope === "user" ? [] : projectAgentDirs.flatMap((dir) => loadAgentsFromDir(dir, "project"));
-	const agents = mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents);
+	const agents = mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents)
+		.filter((agent) => agent.disabled !== true);
 
 	return { agents, projectAgentsDir };
 }
@@ -664,11 +719,13 @@ export function discoverAgentsAll(cwd: string): {
 	const { readDirs: projectDirs, preferredDir: projectDir } = resolveNearestProjectAgentDirs(cwd);
 	const userSettingsPath = getUserAgentSettingsPath();
 	const projectSettingsPath = getProjectAgentSettingsPath(cwd);
+	const userSettings = readSubagentSettings(userSettingsPath);
+	const projectSettings = readSubagentSettings(projectSettingsPath);
 
 	const builtin = applyBuiltinOverrides(
 		loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"),
-		readBuiltinOverrides(userSettingsPath),
-		readBuiltinOverrides(projectSettingsPath),
+		userSettings,
+		projectSettings,
 		userSettingsPath,
 		projectSettingsPath,
 	);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",