pi-subagents 0.32.0 → 0.33.0

package/skills/pi-subagents/SKILL.md

@@ -21,7 +21,7 @@ Use this skill when the parent orchestrator needs to launch a specialized subage
 - **Recon and planning**: use `scout` or `context-builder`, then `planner`
 - **Parallel exploration**: run multiple non-conflicting tasks concurrently
 - **Regular skill specialists**: when discovery shows proactive skill subagent suggestions and the current work is broad enough, launch a small fresh-context fanout that asks one subagent per relevant regularly used skill to apply that skill's perspective to the task
-- **Long-running work**: launch async/background runs and inspect them later; use `timeoutMs` or `maxRuntimeMs` when a foreground or async run needs a hard max runtime
+- **Long-running work**: launch async/background runs and inspect them later; use `timeoutMs` or `maxRuntimeMs` when a foreground or async run needs a hard max runtime, `turnBudget: { maxTurns, graceTurns }` for a soft assistant-turn budget, or `toolBudget: { soft?, hard, block? }` to nudge after a tool-call threshold and then block read/search tools so the child can finalize
 - **Subagent control**: watch needs-attention signals and soft-interrupt only when a delegated run is genuinely blocked
 - **Agent authoring**: create, update, or override agents and chains for a project
 
@@ -194,6 +194,8 @@ For one run, use inline config:
 
 For persistent tweaks, edit `subagents.agentOverrides` in user or project settings. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides.
 
+Model ids do not have to be exact. Separator variations (`claude-haiku-4.5` vs `claude-haiku-4-5`), case (`Claude-Sonnet-4`), and optional trailing date stamps (`claude-haiku-4-5-20251001`) all resolve to the same registry model. Exact `provider/id` wins; a qualified `provider/model` never switches providers. To constrain subagents to a budget or compliance profile, set `subagents.modelScope: { enforce: true, allow: ["anthropic/*", "openai/gpt-5-*"] }` in user or project settings. Out-of-scope models you pass explicitly error and abort; models inherited from frontmatter, `defaultModel`, or the parent session only warn.
+
 ## Prompting role subagents
 
 Builtin role agents inherit the current Pi default model unless you override them. When launching them, write the task prompt as a compact contract, not a long procedural script. Define the destination and let the role choose the efficient path.
@@ -241,6 +243,8 @@ If a provider rejects model IDs with thinking suffixes, use
 builtin thinking defaults globally. A higher-precedence per-agent `thinking`
 override can opt one builtin back in.
 
+Tool description modes live in `~/.pi/agent/extensions/subagent/config.json`, not `subagents` settings. Set `toolDescriptionMode` to `compact` to reduce tool-description prompt cost while keeping the execution, async/wait, child-safety, one-writer, management/action, and artifact/status guardrails. Set it to `custom` to read `subagent-tool-description.md` from the project config dir or agent dir; invalid custom files fall back to full mode and the safety guidance is still appended.
+
 ## Discovery and Scope Rules
 
 Agent files can live in:
@@ -336,7 +340,11 @@ Prefer async mode for every subagent launch. Set `async: true` no matter the tas
 
 Async does not mean parallel writes. Do not edit the same active worktree while an async worker is changing it. Parent-side overlap should be reading, validation prep, synthesis, command planning, or review of unaffected context unless the writer is isolated in a separate worktree.
 
-Do not end your turn immediately after launching an async child if you promised to keep working. Continue the local inspection, synthesis, or validation prep, then check the async run when its result is needed. If there is no independent work left and you would only be running `sleep` or status polling commands to wait, end your turn instead. Pi will deliver the async completion when it arrives.
+Do not end your turn immediately after launching an async child if you promised to keep working. Continue the local inspection, synthesis, or validation prep, then check the async run when its result is needed.
+
+When there is no independent work left and you just need the next async result, **call `wait()`** rather than `sleep`/status-polling loops. `wait()` returns when the next active run finishes or needs attention and keeps the turn alive for normal notification delivery. Use `wait({ all: true })` to drain every active run, `wait({ id: "..." })` to block on one run, and `wait({ timeoutMs })` to cap how long you block.
+
+Prefer `wait()` over ending the turn whenever you must keep going to finish the job — inside a skill that has to run to completion, or in any non-interactive run (`pi -p ...`) where the whole task is a single turn. In those cases ending the turn abandons the still-running children, because there is no next turn to receive their completion. Only end the turn to wait when you are in an interactive session and are certain the user will prompt you again; then Pi will wake you when the run finishes.
 
 ```typescript
 subagent({
@@ -360,7 +368,7 @@ const run = subagent({
 // Continue local inspection, then later call status with the returned id.
 ```
 
-Inspect async runs with `subagent({ action: "status", id: "..." })` or `subagent({ action: "status" })` for active runs. If a delegated fanout child launches nested runs, the parent status view shows them as a tree and you can target a nested run directly with its nested id.
+Inspect async runs with `subagent({ action: "status", id: "..." })` or `subagent({ action: "status" })` for active runs. Use `subagent({ action: "status", view: "fleet" })` when supervising several active foreground/background runs and `subagent({ action: "status", id: "...", view: "transcript", index: 0 })` when you need the latest child output without digging through artifacts. If a delegated fanout child launches nested runs, the parent status view shows them as a tree and you can target a nested run directly with its nested id.
 
 Use `resume` for follow-up work after a delegated run:
 
@@ -385,6 +393,27 @@ Use diagnostics when setup or child startup looks wrong:
 subagent({ action: "doctor" })
 ```
 
+### Scheduled subagent runs
+
+Scheduled runs defer a subagent launch until a future time. They are opt-in and require `{ "scheduledRuns": { "enabled": true } }` in `~/.pi/agent/extensions/subagent/config.json`. Only schedule explicit delayed runs the user asked for; do not schedule runs speculatively.
+
+```typescript
+// Launch a reviewer in 30 minutes
+subagent({ action: "schedule", agent: "reviewer", task: "Review the diff for correctness issues.", schedule: "+30m", scheduleName: "evening review" })
+
+// Schedule a parallel fanout
+subagent({ action: "schedule", tasks: [{ agent: "scout", task: "Map the auth module" }, { agent: "scout", task: "Map the billing module" }], schedule: "+1h" })
+
+// Inspect, list, and cancel
+subagent({ action: "schedule-list" })
+subagent({ action: "schedule-status", id: "ab12" })
+subagent({ action: "schedule-cancel", id: "ab12" })
+```
+
+`schedule` accepts the same execution fields as a normal async run (`agent`/`tasks`/`chain`, `cwd`, `model`, `output`, `reads`, `progress`, `acceptance`, `timeoutMs`) plus `schedule` (a relative delay like `+10m`/`+2h`/`+1d` or a future ISO timestamp with a timezone such as `2030-01-01T09:00:00Z`) and an optional `scheduleName`. Scheduled runs always launch async with fresh context; `context: "fork"`, `async: false`, and `clarify: true` are rejected. Once the timer fires, the run becomes a normal tracked async run: it appears in the async widget, is inspectable with `subagent({ action: "status" })`, can be awaited with `wait()`, and delivers the normal completion notification.
+
+Schedules are persisted per session and restored after a Pi restart. A job whose scheduled time passed by more than `scheduledRuns.maxLatenessMs` (default 5 minutes) while Pi was unavailable is marked `missed` instead of firing late. `scheduledRuns.maxPending` (default 20) caps pending or running scheduled jobs per session.
+
 Humans can use `/subagents-doctor` for the same read-only report. It checks runtime paths, discovery counts, async support, current session context, and intercom bridge state.
 
 ### Subagent control
@@ -436,8 +465,8 @@ subagent({
 })
 ```
 
-Chains default to clarify mode; set `clarify: false` to skip it. Clarify edits affect only the next run; use management actions, settings, or markdown files for persistent changes.
-For programmatic background launches, use `async: true`. Set `clarify: false` when you want to bypass chain clarification explicitly; `clarify: true` keeps the run foreground for the clarify UI.
+Tool calls launch directly by default. Set `clarify: true` on single, parallel, or chain runs when you want the clarify UI. Clarify edits affect only the next run; use management actions, settings, or markdown files for persistent changes.
+For programmatic background launches, use `async: true`. `clarify: true` keeps the run foreground for the clarify UI.
 
 
 ## Worktree Isolation
@@ -491,7 +520,7 @@ Use `oracle` as a smart-friend escalation when the parent needs help with trajec
 
 ## Subagent + Intercom Coordination
 
-`pi-subagents` works without `pi-intercom`. When `pi-intercom` is installed and enabled, the intercom bridge can automatically give child agents a private coordination channel back to the parent session.
+`pi-subagents` includes native supervisor coordination. Child agents can use `contact_supervisor` to ask the exact parent session that spawned them; messages are scoped by parent session id and should not appear in other Pi sessions.
 
 Most agents should not call generic `intercom` directly unless bridge instructions provide a target and `contact_supervisor` is unavailable. Do not invent a target. Prefer the tool from the injected bridge instructions.
 
@@ -510,7 +539,7 @@ Use `contact_supervisor` with `reason: "progress_update"` when:
 Message conventions:
 - `reason: "need_decision"` waits for the parent reply and returns it to the child.
 - `reason: "progress_update"` is non-blocking and should stay concise.
-- Child-side routine completion handoffs are not expected. With the intercom bridge active, parent-side `pi-subagents` sends grouped completion results through `pi-intercom`: one grouped message per foreground parent run and one per completed async result file. Acknowledged foreground delivery returns a compact receipt with artifact/session paths; if unacknowledged, the normal full output is preserved. Grouped messages include child intercom targets, full child summaries, and compact nested summaries under the parent child that launched them.
+- Child-side routine completion handoffs are not expected. Native supervisor messages are for decisions, structured input, and meaningful progress updates while a child is still running.
 
 If bridge instructions provide the child-facing tool, a child can ask:
 
@@ -580,6 +609,23 @@ subagent({
 subagent({ action: "delete", agent: "code-analysis.my-agent" })
 ```
 
+### Eject, disable, enable, and reset
+
+```typescript
+// Copy a bundled builtin/package agent to user scope as an editable custom file.
+subagent({ action: "eject", agent: "reviewer" })
+subagent({ action: "eject", agent: "reviewer", agentScope: "project" })
+
+// Hide an agent from runtime discovery without deleting it (reversible).
+subagent({ action: "disable", agent: "reviewer" })
+subagent({ action: "enable", agent: "reviewer", agentScope: "project" })
+
+// Delete the scope's custom agent file and/or settings override, restoring the bundled default.
+subagent({ action: "reset", agent: "reviewer" })
+```
+
+`eject` copies a builtin or package agent verbatim into the user (default) or project agent dir so it can be customized without hunting package files; the copy shadows the original by runtime name. `disable` writes a reversible `agentOverrides.<name>.disabled: true` entry to the user or project settings file. `enable` removes that `disabled` field while keeping any other override fields. `reset` removes the scope's custom file and settings override to restore the bundled default, and refuses if no bundled default exists (use `delete` for purely custom agents). All four take optional `agentScope: "user" | "project"`; project overrides win over user ones, so target the project scope to undo a project-scope disable.
+
 Use management actions when the system needs to create or edit subagents on
 demand without dropping into raw file editing.
 
@@ -628,14 +674,13 @@ fixes worth doing now. Parent agents can also apply the same recipes directly
 with `subagent(...)` when the user describes the workflow in natural language
 instead of invoking a slash command.
 
-If `pi-prompt-template-model` is installed, additional user prompt templates can delegate into
-`pi-subagents`. This is useful when a slash command should always run through a
-particular agent or with forked context.
+Additional user prompt templates can delegate into `pi-subagents` through the native `/prompt-workflow` and `/chain-prompts` commands. This is useful when a slash command should always run through a particular agent or with forked context. Prompt frontmatter can set `subagent`, `model`, `skill`, `cwd`, `worktree`, `fresh`, `fork`, or `inheritContext` for the native adapter.
 
-If `subagent({ action: "list" })`, `/subagents-doctor`, or a startup message recommends
-`pi-intercom` or `pi-prompt-template-model`, offer to run the shown `pi install npm:<package>`
-command only after user approval. To hide future recommendations, use
-`/subagents-companions hide <package> workspace` or `... user`.
+## Extension RPC
+
+Other Pi extensions can call `pi-subagents` through the in-process event bus. The stable v1 channels are `subagents:rpc:v1:ready`, `subagents:rpc:v1:request`, and per-request replies at `subagents:rpc:v1:reply:<requestId>`. Envelopes use `{ version: 1, requestId, method, params }`, and replies use `{ version: 1, requestId, success, data | error }`.
+
+Methods: `ping`, `status`, `spawn`, `interrupt`, and `stop`. `spawn` is async-only and rejects management actions, `async: false`, or `clarify: true`; it reuses the normal executor, so discovery, validation, session attribution, spawn limits, child-safety depth, artifacts, and async status are shared with the `subagent` tool. `status` and `interrupt` map to the normal control actions. `stop` targets running async runs through the existing timeout control channel. `pi.events` is process-local, so separate Pi processes and child subagents need lifecycle artifact files or `pi-intercom` instead.
 
 ## Important Constraints
 
@@ -659,6 +704,17 @@ command only after user approval. To hide future recommendations, use
 
 Launch every subagent asynchronously by default. Use `async: true` for scouts, researchers, workers, reviewers, validators, oracle checks, one-off delegates, chains, and parallel groups unless you intentionally need a foreground/blocking run. The parent should keep moving: inspect code while scouts run, prepare validation while a worker implements, do a local diff pass while reviewers review, and synthesize or verify while a fix worker applies accepted feedback. Async is the default orchestration posture; foreground runs are the explicit opt-out.
 
+### Use wait() to block until async runs finish
+
+When you have launched async runs and have no independent work left but must keep going to finish the task, call `wait()`. It blocks the current turn until the next run completes or needs attention, keeps the turn alive for normal notification delivery, then returns.
+
+- `wait()` — return when the next active async run in this session finishes or needs attention.
+- `wait({ all: true })` — block until every active async run in this session finishes or one needs attention.
+- `wait({ id: "..." })` — block on one run (id or prefix).
+- `wait({ timeoutMs })` — cap the block; the runs keep going if it elapses.
+
+`wait()` is the correct way to keep N workers in flight: launch N, call `wait()`, react to the result, launch a replacement if needed, then call `wait()` again. Use `wait({ all: true })` only when you intentionally want to drain the fleet to zero. Reserve ending-the-turn-to-wait for interactive sessions where the user will prompt you again; in a skill that must complete or a non-interactive `pi -p` run there is no next turn, so `wait()` is required to avoid abandoning live children.
+
 ### Keep writes single-threaded by default
 
 A strong pattern is one main decision-maker plus advisory/research/review/validation subagents around it. Use `oracle` for advice and `worker` for the actual write path. Parallelize reading, review, validation, and synthesis support, not normal writes, unless you deliberately isolate writers with worktrees. A child that writes should report what changed, what was left undone, commands run with exit codes, validation evidence, surprises, and any decisions that need parent approval.

package/src/agents/agent-management.ts

@@ -16,6 +16,9 @@ import {
 	buildRuntimeName,
 	frontmatterNameForConfig,
 	parsePackageName,
+	mergeBuiltinAgentOverride,
+	removeBuiltinAgentOverride,
+	removeBuiltinAgentOverrideFields,
 } from "./agents.ts";
 import { serializeAgent } from "./agent-serializer.ts";
 import { serializeChain, serializeJsonChain } from "./chain-serializer.ts";
@@ -26,12 +29,13 @@ import {
 import { parseFrontmatter } from "./frontmatter.ts";
 import { toModelInfo } from "../shared/model-info.ts";
 import { resolveSubagentModelOverride, type ParentModel } from "../runs/shared/model-fallback.ts";
-import type { Details, ExtensionConfig } from "../shared/types.ts";
+import { validateToolBudgetConfig } from "../runs/shared/tool-budget.ts";
+import type { Details, ExtensionConfig, ToolBudgetConfig } from "../shared/types.ts";
 import { getProjectConfigDir } from "../shared/utils.ts";
 
-type ManagementAction = "list" | "get" | "models" | "create" | "update" | "delete";
+type ManagementAction = "list" | "get" | "models" | "create" | "update" | "delete" | "eject" | "disable" | "enable" | "reset";
 type ManagementScope = "user" | "project";
-type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & { model?: ExtensionContext["model"]; config?: ExtensionConfig; companionSuggestionLines?: () => string[] };
+type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & { model?: ExtensionContext["model"]; config?: ExtensionConfig };
 
 interface ManagementParams {
 	action?: string;
@@ -72,6 +76,12 @@ function asDisambiguationScope(scope: unknown): ManagementScope | undefined {
 	return undefined;
 }
 
+function actionScope(scope: unknown, action: ManagementAction): { scope?: ManagementScope; error?: AgentToolResult<Details> } {
+	if (scope === undefined) return { scope: "user" };
+	const parsed = asDisambiguationScope(scope);
+	return parsed ? { scope: parsed } : { error: result(`agentScope must be 'user' or 'project' for ${action}.`, true) };
+}
+
 function normalizeListScope(scope: unknown): AgentScope | undefined {
 	if (scope === undefined) return "both";
 	if (scope === "user" || scope === "project" || scope === "both") return scope;
@@ -113,6 +123,19 @@ function findChains(name: string, cwd: string, scope: AgentScope = "both"): Chai
 		.sort((a, b) => a.source.localeCompare(b.source));
 }
 
+const AGENT_SOURCE_PRECEDENCE: Record<AgentSource, number> = { builtin: 0, package: 1, user: 2, project: 3 };
+
+// Returns the highest-precedence agent for a name (project > user > package > builtin,
+// matching mergeAgentsForScope for "both"), including disabled agents so disable/enable/reset
+// can locate agents that runtime discovery filters out.
+function pickEffectiveAgent(d: ReturnType<typeof discoverAgentsAll>, name: string): AgentConfig | undefined {
+	const raw = name.trim();
+	const sanitized = sanitizeName(raw);
+	const matches = allAgents(d).filter((a) => a.name === raw || a.name === sanitized);
+	if (matches.length === 0) return undefined;
+	return matches.reduce((best, agent) => (AGENT_SOURCE_PRECEDENCE[agent.source] > AGENT_SOURCE_PRECEDENCE[best.source] ? agent : best));
+}
+
 function nameExistsInScope(cwd: string, scope: ManagementScope, name: string, excludePath?: string): boolean {
 	const d = discoverAgentsAll(cwd);
 	for (const a of scope === "user" ? d.user : d.project) {
@@ -245,6 +268,7 @@ function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<string,
 		changed("completionGuard");
 		if (cfg.completionGuard === true) fields.add("completionGuard");
 	}
+	if (hasKey(cfg, "toolBudget")) changed("toolBudget");
 
 	return fields;
 }
@@ -302,6 +326,11 @@ function parseStepList(raw: unknown): { steps?: ChainStepConfig[]; error?: strin
 			if (typeof s.progress === "boolean") step.progress = s.progress;
 			else return { error: `config.steps[${i}].progress must be a boolean.` };
 		}
+		if (hasKey(s, "toolBudget")) {
+			const validation = validateToolBudgetConfig(s.toolBudget, `config.steps[${i}].toolBudget`);
+			if (validation.error) return { error: validation.error };
+			step.toolBudget = s.toolBudget as ChainStepConfig["toolBudget"];
+		}
 		steps.push(step);
 	}
 	return { steps };
@@ -413,6 +442,14 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		if (typeof cfg.completionGuard !== "boolean") return "config.completionGuard must be a boolean when provided.";
 		target.completionGuard = cfg.completionGuard;
 	}
+	if (hasKey(cfg, "toolBudget")) {
+		if (cfg.toolBudget === false || cfg.toolBudget === "") target.toolBudget = undefined;
+		else {
+			const validation = validateToolBudgetConfig(cfg.toolBudget, "config.toolBudget");
+			if (validation.error) return validation.error;
+			target.toolBudget = cfg.toolBudget as ToolBudgetConfig;
+		}
+	}
 	return undefined;
 }
 
@@ -484,6 +521,8 @@ function formatAgentDetail(agent: AgentConfig): string {
 	if (agent.defaultProgress) lines.push("Progress: true");
 	if (agent.maxSubagentDepth !== undefined) lines.push(`Max subagent depth: ${agent.maxSubagentDepth}`);
 	if (agent.completionGuard === false) lines.push("Completion guard: false");
+	if (agent.toolBudget) lines.push(`Tool budget: ${JSON.stringify(agent.toolBudget)}`);
+	if (agent.memory) lines.push(`Memory: ${agent.memory.scope} scope, path: ${agent.memory.path}`);
 	if (agent.systemPrompt.trim()) lines.push("", "System Prompt:", agent.systemPrompt);
 	return lines.join("\n");
 }
@@ -504,6 +543,7 @@ function formatChainStepDetail(step: ChainStepConfig, index: number): string[] {
 		if (typeof parallel?.label === "string") lines.push(`   Label: ${parallel.label}`);
 		if (typeof parallel?.task === "string" && parallel.task.trim()) lines.push(`   Task: ${parallel.task}`);
 		if (parallel?.outputSchema) lines.push("   Structured output: true");
+		if (parallel && "toolBudget" in parallel) lines.push(`   Tool budget: ${JSON.stringify((parallel as { toolBudget?: unknown }).toolBudget)}`);
 		if (collect?.outputSchema) lines.push("   Collect schema: true");
 		if (step.concurrency !== undefined) lines.push(`   Concurrency: ${step.concurrency}`);
 		if (step.failFast !== undefined) lines.push(`   Fail fast: ${step.failFast ? "true" : "false"}`);
@@ -514,6 +554,7 @@ function formatChainStepDetail(step: ChainStepConfig, index: number): string[] {
 	if (step.output === false) lines.push("   Output: false");
 	else if (step.output) lines.push(`   Output: ${step.output}`);
 	if (step.outputMode) lines.push(`   Output mode: ${step.outputMode}`);
+	if (step.toolBudget) lines.push(`   Tool budget: ${JSON.stringify(step.toolBudget)}`);
 	if (step.reads === false) lines.push("   Reads: false");
 	else if (Array.isArray(step.reads) && step.reads.length > 0) lines.push(`   Reads: ${step.reads.join(", ")}`);
 	if (step.model) lines.push(`   Model: ${step.model}`);
@@ -549,7 +590,6 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 		config: ctx.config?.proactiveSkillSubagents,
 		discoverAvailableSkills: () => discoverAvailableSkills(ctx.cwd),
 	});
-	const companionSuggestions = ctx.companionSuggestionLines?.() ?? [];
 	const lines = [
 		"Executable agents:",
 		...(agents.length
@@ -559,7 +599,6 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 		"Chains:",
 		...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"]),
 		...(proactiveSuggestions.length ? ["", ...proactiveSuggestions] : []),
-		...(companionSuggestions.length ? ["", ...companionSuggestions] : []),
 		...(diagnostics.length ? ["", "Chain diagnostics:", ...diagnostics.map((entry) => `- ${entry.filePath}: ${entry.error}`)] : []),
 	];
 	return result(lines.join("\n"));
@@ -867,6 +906,135 @@ function handleDelete(params: ManagementParams, ctx: ManagementContext): AgentTo
 	return result(`Deleted chain '${target.name}' at ${target.filePath}.`);
 }
 
+function handleEject(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
+	if (!params.agent) return result("Specify 'agent' for eject.", true);
+	const raw = params.agent.trim();
+	const sanitized = sanitizeName(raw);
+	const parsedScope = actionScope(params.agentScope, "eject");
+	if (parsedScope.error) return parsedScope.error;
+	const scope = parsedScope.scope!;
+	const d = discoverAgentsAll(ctx.cwd);
+	const source = [...d.package, ...d.builtin].find((a) => a.name === raw || a.name === sanitized);
+	if (!source) {
+		return result(`Agent '${raw}' not found or is not a bundled/package agent. eject copies a builtin or package agent to ${scope} scope so it can be customized. Available: ${availableNames(ctx.cwd, "agent").join(", ") || "none"}.`, true);
+	}
+	const runtimeName = source.name;
+	const existingCustom = (scope === "user" ? d.user : d.project).find((a) => a.name === runtimeName);
+	if (existingCustom) {
+		return result(`Agent '${runtimeName}' is already a custom ${scope} agent at ${existingCustom.filePath}. Edit it with { action: "update", agent: "${runtimeName}" } or delete it first.`, true);
+	}
+	if (nameExistsInScope(ctx.cwd, scope, runtimeName)) {
+		return result(`An agent or chain named '${runtimeName}' already exists in ${scope} scope. Remove or rename it first.`, true);
+	}
+	const projectConfigDir = getProjectConfigDir(ctx.cwd);
+	const targetDir = scope === "user" ? d.userDir : d.projectDir ?? path.join(projectConfigDir, "agents");
+	fs.mkdirSync(targetDir, { recursive: true });
+	const targetPath = path.join(targetDir, `${runtimeName}.md`);
+	if (fs.existsSync(targetPath)) {
+		return result(`File already exists at ${targetPath} but is not a valid agent definition. Remove or rename it first.`, true);
+	}
+	let content: string;
+	try {
+		content = fs.readFileSync(source.filePath, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return result(`Failed to read source agent at ${source.filePath}: ${message}`, true);
+	}
+	fs.writeFileSync(targetPath, content, "utf-8");
+	return result(`Ejected agent '${runtimeName}' from ${source.source} to ${scope} scope at ${targetPath}. Edit it there to customize; it shadows the bundled ${source.source} agent of the same name.`);
+}
+
+function handleDisable(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
+	if (!params.agent) return result("Specify 'agent' for disable.", true);
+	const raw = params.agent.trim();
+	const parsedScope = actionScope(params.agentScope, "disable");
+	if (parsedScope.error) return parsedScope.error;
+	const scope = parsedScope.scope!;
+	const d = discoverAgentsAll(ctx.cwd);
+	if (scope === "project" && d.projectSettingsPath === null) {
+		return result("Project override is not available here: no project config root (.pi or .agents) was found above the cwd. Use agentScope: 'user' or run from inside a project.", true);
+	}
+	const effective = pickEffectiveAgent(d, raw);
+	if (!effective) {
+		return result(`Agent '${raw}' not found. Available: ${availableNames(ctx.cwd, "agent").join(", ") || "none"}.`, true);
+	}
+	const runtimeName = effective.name;
+	const settingsPath = mergeBuiltinAgentOverride(ctx.cwd, runtimeName, scope, { disabled: true });
+	const after = pickEffectiveAgent(discoverAgentsAll(ctx.cwd), raw);
+	if (after?.disabled === true) {
+		return result(`Disabled agent '${runtimeName}' via ${scope} settings override at ${settingsPath}. It is now hidden from runtime discovery and { action: "list" }.`);
+	}
+	return result(`Wrote a disabled override for '${runtimeName}' at ${settingsPath}, but the agent is still enabled. A higher-precedence ${after?.override?.scope ?? "project"} override is likely winning. Try agentScope: '${after?.override?.scope ?? "project"}'.`, true);
+}
+
+function handleEnable(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
+	if (!params.agent) return result("Specify 'agent' for enable.", true);
+	const raw = params.agent.trim();
+	const parsedScope = actionScope(params.agentScope, "enable");
+	if (parsedScope.error) return parsedScope.error;
+	const scope = parsedScope.scope!;
+	const d = discoverAgentsAll(ctx.cwd);
+	if (scope === "project" && d.projectSettingsPath === null) {
+		return result("Project override is not available here: no project config root (.pi or .agents) was found above the cwd. Use agentScope: 'user' or run from inside a project.", true);
+	}
+	const effective = pickEffectiveAgent(d, raw);
+	if (!effective) {
+		return result(`Agent '${raw}' not found. Available: ${availableNames(ctx.cwd, "agent").join(", ") || "none"}.`, true);
+	}
+	const runtimeName = effective.name;
+	const { path: settingsPath, removed } = removeBuiltinAgentOverrideFields(ctx.cwd, runtimeName, scope, ["disabled"]);
+	const after = pickEffectiveAgent(discoverAgentsAll(ctx.cwd), raw);
+	if (after && after.disabled !== true) {
+		if (removed) return result(`Enabled agent '${runtimeName}' (removed disabled override at ${settingsPath}).`);
+		return result(`Agent '${runtimeName}' is already enabled.`);
+	}
+	if (after?.override?.scope && after.override.scope !== scope) {
+		return result(`Agent '${runtimeName}' is still disabled via a ${after.override.scope} scope override at ${after.override.path}. Specify agentScope: '${after.override.scope}' to enable it.`, true);
+	}
+	return result(`Agent '${runtimeName}' is still disabled after removing the ${scope} disabled override. It may be hidden via subagents.disableBuiltins in ${after?.override?.scope ?? scope} settings at ${after?.override?.path ?? settingsPath}.`, true);
+}
+
+function handleReset(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
+	if (!params.agent) return result("Specify 'agent' for reset.", true);
+	const raw = params.agent.trim();
+	const sanitized = sanitizeName(raw);
+	const parsedScope = actionScope(params.agentScope, "reset");
+	if (parsedScope.error) return parsedScope.error;
+	const scope = parsedScope.scope!;
+	const d = discoverAgentsAll(ctx.cwd);
+	if (scope === "project" && d.projectSettingsPath === null) {
+		return result("Project override is not available here: no project config root (.pi or .agents) was found above the cwd. Use agentScope: 'user' or run from inside a project.", true);
+	}
+	const bundled = [...d.package, ...d.builtin].find((a) => a.name === raw || a.name === sanitized);
+	if (!bundled) {
+		const custom = [...d.user, ...d.project].find((a) => a.name === raw || a.name === sanitized);
+		if (custom) {
+			return result(`Agent '${raw}' has no bundled default to reset to. Use { action: "delete", agent: "${custom.name}" } to remove the custom ${custom.source} agent.`, true);
+		}
+		return result(`Agent '${raw}' not found. Available: ${availableNames(ctx.cwd, "agent").join(", ") || "none"}.`, true);
+	}
+	const runtimeName = bundled.name;
+	const custom = (scope === "user" ? d.user : d.project).find((a) => a.name === raw || a.name === sanitized);
+	const lines: string[] = [];
+	if (custom) {
+		fs.unlinkSync(custom.filePath);
+		lines.push(`Deleted custom ${scope} agent file at ${custom.filePath}.`);
+	}
+	const overrideRemoval = removeBuiltinAgentOverride(ctx.cwd, runtimeName, scope);
+	if (overrideRemoval.removed) lines.push(`Removed ${scope} settings override at ${overrideRemoval.path}.`);
+	if (lines.length === 0) {
+		const otherScope = scope === "user" ? "project" : "user";
+		const otherCustom = (otherScope === "user" ? d.user : d.project).find((a) => a.name === raw || a.name === sanitized);
+		const hasOtherOverride = bundled.override?.scope === otherScope;
+		const note = (otherCustom || hasOtherOverride)
+			? ` Customization exists in ${otherScope} scope; specify agentScope: '${otherScope}' to reset it.`
+			: "";
+		return result(`Agent '${runtimeName}' has no ${scope} customization to reset.${note} It is at its bundled ${bundled.source} default.`);
+	}
+	lines.push(`Reset agent '${runtimeName}' to its bundled ${bundled.source} default.`);
+	return result(lines.join("\n"));
+}
+
 export function handleManagementAction(action: string, params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	switch (action as ManagementAction) {
 		case "list": return handleList(params, ctx);
@@ -875,6 +1043,10 @@ export function handleManagementAction(action: string, params: ManagementParams,
 		case "create": return handleCreate(params, ctx);
 		case "update": return handleUpdate(params, ctx);
 		case "delete": return handleDelete(params, ctx);
+		case "eject": return handleEject(params, ctx);
+		case "disable": return handleDisable(params, ctx);
+		case "enable": return handleEnable(params, ctx);
+		case "reset": return handleReset(params, ctx);
 		default: return result(`Unknown action: ${action}`, true);
 	}
 }