@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/src/agents/agent-management.ts

@@ -1,813 +1,116 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { discoverAgents, discoverAgentsAll } from "./agents.ts";
+import { formatAgentGroups, formatAgentDetail, formatChainDetail } from "./management-format.ts";
+import { handleCreate, handleUpdate, handleDelete } from "./management-persistence.ts";
 import {
-	type AgentConfig,
-	type AgentScope,
-	type AgentSource,
-	type ChainConfig,
-	type ChainStepConfig,
-	defaultInheritProjectContext,
-	defaultInheritSkills,
-	defaultSystemPromptMode,
-	discoverAgents,
-	discoverAgentsAll,
-	buildRuntimeName,
-	frontmatterNameForConfig,
-	parsePackageName,
-} from "./agents.ts";
-import { serializeAgent } from "./agent-serializer.ts";
-import { serializeChain, serializeJsonChain } from "./chain-serializer.ts";
-import { discoverAvailableSkills } from "./skills.ts";
-import { isClaudeCodeModel } from "../runs/shared/claude-code.ts";
+  result,
+  normalizeListScope,
+  discoveryOptions,
+  findEffectiveAgents,
+  findChains,
+  availableNamesText,
+  type ManagementContext,
+  type ManagementParams,
+} from "./management-targets.ts";
+import type { AgentScope } from "../shared/types/config.ts";
 import type { SubagentExecutionResult } from "../shared/types.ts";
-import { resolveEffectiveThinking } from "../shared/model-info.ts";
-
-type ManagementAction = "list" | "get" | "create" | "update" | "delete";
-type ManagementScope = "user" | "project";
-type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry" | "isProjectTrusted">;
-
-interface ManagementParams {
-	action?: string;
-	agent?: string;
-	chainName?: string;
-	agentScope?: string;
-	config?: unknown;
-}
-
-function result(text: string, isError = false): SubagentExecutionResult {
-	return { content: [{ type: "text", text }], isError, details: { mode: "management", results: [] } };
-}
-
-function parseCsv(value: string): string[] {
-	return [...new Set(value.split(",").map((v) => v.trim()).filter(Boolean))];
-}
-
-function configObject(config: unknown): { value?: Record<string, unknown>; error?: string } {
-	let val = config;
-	if (typeof val === "string") {
-		try {
-			val = JSON.parse(val);
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			return { error: `config must be valid JSON: ${message}` };
-		}
-	}
-	if (!val || typeof val !== "object" || Array.isArray(val)) return {};
-	return { value: val as Record<string, unknown> };
-}
-
-function hasKey(obj: Record<string, unknown>, key: string): boolean {
-	return Object.prototype.hasOwnProperty.call(obj, key);
-}
-
-function asDisambiguationScope(scope: unknown): ManagementScope | undefined {
-	if (scope === "user" || scope === "project") return scope;
-	return undefined;
-}
-
-function normalizeListScope(scope: unknown): AgentScope | undefined {
-	if (scope === undefined) return "both";
-	if (scope === "user" || scope === "project" || scope === "both") return scope;
-	return undefined;
-}
-
-function sanitizeName(name: string): string {
-	return name.toLowerCase().trim().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
-}
-
-function parsePackageConfig(value: unknown): { packageName?: string; error?: string } {
-	return parsePackageName(value, "config.package");
-}
-
-function allAgents(d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] }): AgentConfig[] {
-	return [...d.builtin, ...d.package, ...d.user, ...d.project];
-}
-
-function discoveryOptions(ctx: ManagementContext): { projectTrusted: boolean } {
-	return { projectTrusted: ctx.isProjectTrusted() };
+export { handleCreate, handleUpdate } from "./management-persistence.ts";
+
+export function handleList(
+  params: ManagementParams,
+  ctx: ManagementContext,
+): SubagentExecutionResult {
+  const scope = normalizeListScope(params.agentScope);
+  if (scope === undefined) {
+    return result("agentScope must be 'user', 'project', or 'both'.", true);
+  }
+  const discovery = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx), scope);
+  const agents = discoverAgents(ctx.cwd, scope, discoveryOptions(ctx)).agents.sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+  const chains = discovery.chains
+    .filter((chain) => scope === "both" || chain.source === scope)
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const diagnostics = [...discovery.agentDiagnostics, ...discovery.chainDiagnostics];
+  return result(
+    [
+      ...formatAgentGroups(agents),
+      "",
+      "Chains:",
+      ...(chains.length > 0
+        ? chains.map((chain) => `- ${chain.name} (${chain.source}): ${chain.description}`)
+        : ["- (none)"]),
+      ...(diagnostics.length > 0
+        ? [
+            "",
+            "Discovery diagnostics:",
+            ...diagnostics.map((entry) => `- ${entry.filePath}: ${entry.error}`),
+          ]
+        : []),
+    ].join("\n"),
+  );
+}
+function getBlocks(
+  kind: "agent" | "chain",
+  name: string,
+  ctx: ManagementContext,
+  scope: AgentScope,
+): { found: boolean; blocks: string[] } {
+  const matches =
+    kind === "agent" ? findEffectiveAgents(name, ctx, scope) : findChains(name, ctx, scope);
+  if (matches.length === 0) {
+    return {
+      found: false,
+      blocks: [
+        `${kind === "agent" ? "Agent" : "Chain"} '${name}' not found. Available: ${availableNamesText(ctx, kind, scope)}.`,
+      ],
+    };
+  }
+  return {
+    found: true,
+    blocks: matches.map((match) =>
+      "steps" in match ? formatChainDetail(match) : formatAgentDetail(match),
+    ),
+  };
 }
-
-function availableNames(ctx: ManagementContext, kind: "agent" | "chain", scope: AgentScope = "both"): string[] {
-	const d = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx), scope);
-	const items = kind === "agent" ? allAgents(d) : d.chains;
-	return [...new Set(items.map((x) => x.name))].sort((a, b) => a.localeCompare(b));
-}
-
-function findAgents(name: string, ctx: ManagementContext, scope: AgentScope = "both"): AgentConfig[] {
-	const d = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx), scope);
-	const raw = name.trim();
-	const sanitized = sanitizeName(raw);
-	return allAgents(d)
-		.filter((a) => (scope === "both" || a.source === scope) && (a.name === raw || a.name === sanitized))
-		.sort((a, b) => a.source.localeCompare(b.source));
-}
-
-function findChains(name: string, ctx: ManagementContext, scope: AgentScope = "both"): ChainConfig[] {
-	const raw = name.trim();
-	const sanitized = sanitizeName(raw);
-	return discoverAgentsAll(ctx.cwd, discoveryOptions(ctx), scope).chains
-		.filter((c) => (scope === "both" || c.source === scope) && (c.name === raw || c.name === sanitized))
-		.sort((a, b) => a.source.localeCompare(b.source));
-}
-
-function findEffectiveAgents(name: string, ctx: ManagementContext, scope: AgentScope = "both"): AgentConfig[] {
-	const raw = name.trim();
-	const sanitized = sanitizeName(raw);
-	return discoverAgents(ctx.cwd, scope, discoveryOptions(ctx)).agents
-		.filter((a) => a.name === raw || a.name === sanitized);
-}
-
-function nameExistsInScope(ctx: ManagementContext, scope: ManagementScope, name: string, excludePath?: string): boolean {
-	const d = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx), scope);
-	for (const a of scope === "user" ? d.user : d.project) {
-		if (a.name === name && a.filePath !== excludePath) return true;
-	}
-	for (const c of d.chains) {
-		if (c.source === scope && c.name === name && c.filePath !== excludePath) return true;
-	}
-	return false;
-}
-
-function unknownChainAgents(ctx: ManagementContext, steps: ChainStepConfig[]): string[] {
-	const d = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx));
-	const known = new Set(allAgents(d).map((a) => a.name));
-	return [...new Set(steps.map((s) => s.agent).filter((agent): agent is string => typeof agent === "string" && !known.has(agent)))].sort((a, b) => a.localeCompare(b));
-}
-
-function chainStepWarnings(ctx: ManagementContext, steps: ChainStepConfig[]): string[] {
-	const warnings: string[] = [];
-	const available = new Set(discoverAvailableSkills(ctx.cwd, discoveryOptions(ctx)).map((s) => s.name));
-	for (let i = 0; i < steps.length; i++) {
-		const s = steps[i]!;
-		if (s.model && !isClaudeCodeModel(s.model)) {
-			const found = ctx.modelRegistry.getAvailable().some((m) => `${m.provider}/${m.id}` === s.model || m.id === s.model);
-			if (!found) warnings.push(`Warning: step ${i + 1} (${s.agent}): model '${s.model}' is not in the current model registry.`);
-		}
-		if (Array.isArray(s.skills) && s.skills.length > 0) {
-			const missing = s.skills.filter((sk) => !available.has(sk));
-			if (missing.length) warnings.push(`Warning: step ${i + 1} (${s.agent}): skills not found: ${missing.join(", ")}.`);
-		}
-	}
-	return warnings;
-}
-
-function modelWarning(ctx: ManagementContext, model: string | undefined): string | undefined {
-	if (!model || isClaudeCodeModel(model)) return undefined;
-	const found = ctx.modelRegistry.getAvailable().some((m) => `${m.provider}/${m.id}` === model || m.id === model);
-	return found ? undefined : `Warning: model '${model}' is not in the current model registry.`;
-}
-
-function fallbackModelsWarning(ctx: ManagementContext, fallbackModels: string[] | undefined): string | undefined {
-	if (!fallbackModels || fallbackModels.length === 0) return undefined;
-	const available = new Set(ctx.modelRegistry.getAvailable().flatMap((m) => [`${m.provider}/${m.id}`, m.id]));
-	const missing = fallbackModels.filter((model) => !isClaudeCodeModel(model) && !available.has(model));
-	return missing.length ? `Warning: fallback models not in the current model registry: ${missing.join(", ")}.` : undefined;
-}
-
-function skillsWarning(ctx: ManagementContext, skills: string[] | undefined): string | undefined {
-	if (!skills || skills.length === 0) return undefined;
-	const available = new Set(discoverAvailableSkills(ctx.cwd, discoveryOptions(ctx)).map((s) => s.name));
-	const missing = skills.filter((s) => !available.has(s));
-	return missing.length ? `Warning: skills not found: ${missing.join(", ")}.` : undefined;
-}
-
-const SAVED_CHAIN_STEP_KEYS = new Set(["agent", "task", "phase", "label", "as", "outputSchema", "output", "outputMode", "reads", "model", "skills", "progress"]);
-
-function parseStepList(raw: unknown): { steps?: ChainStepConfig[]; error?: string } {
-	if (!Array.isArray(raw)) return { error: "config.steps must be an array." };
-	if (raw.length === 0) return { error: "config.steps must include at least one step." };
-	const steps: ChainStepConfig[] = [];
-	for (let i = 0; i < raw.length; i++) {
-		const item = raw[i];
-		if (!item || typeof item !== "object" || Array.isArray(item)) return { error: `config.steps[${i}] must be an object.` };
-		const s = item as Record<string, unknown>;
-		if (hasKey(s, "skill")) return { error: `config.steps[${i}].skill is not supported; use skills.` };
-		const unknownKeys = Object.keys(s).filter((key) => !SAVED_CHAIN_STEP_KEYS.has(key));
-		if (unknownKeys.length) return { error: `config.steps[${i}] has unknown field${unknownKeys.length === 1 ? "" : "s"}: ${unknownKeys.join(", ")}.` };
-		if (typeof s.agent !== "string" || !s.agent.trim()) return { error: `config.steps[${i}].agent must be a non-empty string.` };
-		const step: ChainStepConfig = { agent: s.agent.trim(), task: typeof s.task === "string" ? s.task : "" };
-		if (hasKey(s, "phase")) {
-			if (typeof s.phase === "string") step.phase = s.phase;
-			else return { error: `config.steps[${i}].phase must be a string.` };
-		}
-		if (hasKey(s, "label")) {
-			if (typeof s.label === "string") step.label = s.label;
-			else return { error: `config.steps[${i}].label must be a string.` };
-		}
-		if (hasKey(s, "as")) {
-			if (typeof s.as === "string") step.as = s.as;
-			else return { error: `config.steps[${i}].as must be a string.` };
-		}
-		if (hasKey(s, "outputSchema")) {
-			if (typeof s.outputSchema === "string") step.outputSchema = s.outputSchema;
-			else return { error: `config.steps[${i}].outputSchema must be a schema file path string for saved chains.` };
-		}
-		if (hasKey(s, "output")) {
-			if (s.output === false) step.output = false;
-			else if (typeof s.output === "string") step.output = s.output;
-			else return { error: `config.steps[${i}].output must be a string or false.` };
-		}
-		if (hasKey(s, "outputMode")) {
-			if (s.outputMode === "inline" || s.outputMode === "file-only") step.outputMode = s.outputMode;
-			else return { error: `config.steps[${i}].outputMode must be 'inline' or 'file-only'.` };
-		}
-		if (hasKey(s, "reads")) {
-			if (s.reads === false) step.reads = false;
-			else if (Array.isArray(s.reads) && s.reads.every((value) => typeof value === "string")) step.reads = s.reads.map((value) => value.trim()).filter(Boolean);
-			else return { error: `config.steps[${i}].reads must be a string array or false.` };
-		}
-		if (hasKey(s, "model")) {
-			if (typeof s.model === "string") step.model = s.model;
-			else return { error: `config.steps[${i}].model must be a string.` };
-		}
-		if (hasKey(s, "skill")) {
-			return { error: `config.steps[${i}].skill is not supported for saved chains; use skills (array or false).` };
-		}
-		if (hasKey(s, "skills")) {
-			if (s.skills === false) step.skills = false;
-			else if (Array.isArray(s.skills) && s.skills.every((value) => typeof value === "string")) step.skills = s.skills.map((value) => value.trim()).filter(Boolean);
-			else return { error: `config.steps[${i}].skills must be a string array or false.` };
-		}
-		if (hasKey(s, "progress")) {
-			if (typeof s.progress === "boolean") step.progress = s.progress;
-			else return { error: `config.steps[${i}].progress must be a boolean.` };
-		}
-		steps.push(step);
-	}
-	return { steps };
-}
-
-function parseTools(raw: string): { tools?: string[]; mcpDirectTools?: string[] } {
-	const tools: string[] = [];
-	const mcpDirectTools: string[] = [];
-	for (const item of parseCsv(raw)) {
-		if (item.startsWith("mcp:")) {
-			const direct = item.slice(4).trim();
-			if (direct) mcpDirectTools.push(direct);
-		} else tools.push(item);
-	}
-	return { tools: tools.length ? tools : undefined, mcpDirectTools: mcpDirectTools.length ? mcpDirectTools : undefined };
-}
-
-const CHAIN_CONFIG_KEYS = new Set(["name", "package", "description", "scope", "steps"]);
-
-function validateChainConfigKeys(cfg: Record<string, unknown>): string | undefined {
-	const unknownKeys = Object.keys(cfg).filter((key) => !CHAIN_CONFIG_KEYS.has(key));
-	return unknownKeys.length ? `config has unknown field${unknownKeys.length === 1 ? "" : "s"}: ${unknownKeys.join(", ")}.` : undefined;
-}
-
-const AGENT_CONFIG_KEYS = new Set([
-	"name", "package", "description", "scope", "systemPrompt", "model", "fallbackModels", "tools", "skills", "extensions", "thinking",
-	"systemPromptMode", "inheritProjectContext", "inheritSkills", "defaultContext", "output", "reads", "progress", "allowSubagents",
-	"maxSubagentDepth", "maxExecutionTimeMs", "maxTokens", "completionGuard",
-]);
-
-function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): string | undefined {
-	const unknownKeys = Object.keys(cfg).filter((key) => !AGENT_CONFIG_KEYS.has(key));
-	if (unknownKeys.length) return `config has unknown field${unknownKeys.length === 1 ? "" : "s"}: ${unknownKeys.join(", ")}.`;
-	if (hasKey(cfg, "systemPrompt")) {
-		if (cfg.systemPrompt === false || cfg.systemPrompt === "") target.systemPrompt = "";
-		else if (typeof cfg.systemPrompt === "string") target.systemPrompt = cfg.systemPrompt;
-		else return "config.systemPrompt must be a string or false when provided.";
-	}
-	if (hasKey(cfg, "model")) {
-		if (cfg.model === false || cfg.model === "") target.model = undefined;
-		else if (typeof cfg.model === "string") target.model = cfg.model.trim() || undefined;
-		else return "config.model must be a string or false when provided.";
-	}
-	if (hasKey(cfg, "fallbackModels")) {
-		if (cfg.fallbackModels === false || cfg.fallbackModels === "") target.fallbackModels = undefined;
-		else if (typeof cfg.fallbackModels === "string") {
-			const models = parseCsv(cfg.fallbackModels);
-			target.fallbackModels = models.length ? models : undefined;
-		} else if (Array.isArray(cfg.fallbackModels)) {
-			const models = cfg.fallbackModels
-				.filter((value): value is string => typeof value === "string")
-				.map((value) => value.trim())
-				.filter(Boolean);
-			target.fallbackModels = models.length ? [...new Set(models)] : undefined;
-		} else return "config.fallbackModels must be a comma-separated string, string array, or false when provided.";
-	}
-	if (hasKey(cfg, "tools")) {
-		if (cfg.tools === false || cfg.tools === "") { target.tools = undefined; target.mcpDirectTools = undefined; }
-		else if (typeof cfg.tools === "string") { const parsed = parseTools(cfg.tools); target.tools = parsed.tools; target.mcpDirectTools = parsed.mcpDirectTools; }
-		else return "config.tools must be a comma-separated string or false when provided.";
-	}
-	if (hasKey(cfg, "skills")) {
-		if (cfg.skills === false || cfg.skills === "") target.skills = undefined;
-		else if (typeof cfg.skills === "string") { const skills = parseCsv(cfg.skills); target.skills = skills.length ? skills : undefined; }
-		else return "config.skills must be a comma-separated string or false when provided.";
-	}
-	if (hasKey(cfg, "extensions")) {
-		if (cfg.extensions === false) target.extensions = undefined;
-		else if (cfg.extensions === "") target.extensions = [];
-		else if (typeof cfg.extensions === "string") target.extensions = parseCsv(cfg.extensions);
-		else return "config.extensions must be a comma-separated string, empty string, or false when provided.";
-	}
-	if (hasKey(cfg, "thinking")) {
-		if (cfg.thinking === false || cfg.thinking === "") target.thinking = undefined;
-		else if (typeof cfg.thinking === "string") target.thinking = cfg.thinking.trim() || undefined;
-		else return "config.thinking must be a string or false when provided.";
-	}
-	if (hasKey(cfg, "systemPromptMode")) {
-		if (cfg.systemPromptMode === "append" || cfg.systemPromptMode === "replace") target.systemPromptMode = cfg.systemPromptMode;
-		else return "config.systemPromptMode must be 'append' or 'replace' when provided.";
-	}
-	if (hasKey(cfg, "inheritProjectContext")) {
-		if (typeof cfg.inheritProjectContext !== "boolean") return "config.inheritProjectContext must be a boolean when provided.";
-		target.inheritProjectContext = cfg.inheritProjectContext;
-	}
-	if (hasKey(cfg, "inheritSkills")) {
-		if (typeof cfg.inheritSkills !== "boolean") return "config.inheritSkills must be a boolean when provided.";
-		target.inheritSkills = cfg.inheritSkills;
-	}
-	if (hasKey(cfg, "defaultContext")) {
-		if (cfg.defaultContext === false || cfg.defaultContext === "") target.defaultContext = undefined;
-		else if (cfg.defaultContext === "fresh" || cfg.defaultContext === "fork") target.defaultContext = cfg.defaultContext;
-		else return "config.defaultContext must be 'fresh', 'fork', or false when provided.";
-	}
-	if (hasKey(cfg, "output")) {
-		if (cfg.output === false || cfg.output === "") target.output = undefined;
-		else if (typeof cfg.output === "string") target.output = cfg.output;
-		else return "config.output must be a string or false when provided.";
-	}
-	if (hasKey(cfg, "reads")) {
-		if (cfg.reads === false || cfg.reads === "") target.defaultReads = undefined;
-		else if (typeof cfg.reads === "string") {
-			const reads = parseCsv(cfg.reads);
-			target.defaultReads = reads.length ? reads : undefined;
-		} else return "config.reads must be a comma-separated string or false when provided.";
-	}
-	if (hasKey(cfg, "progress")) {
-		if (typeof cfg.progress !== "boolean") return "config.progress must be a boolean when provided.";
-		target.defaultProgress = cfg.progress;
-	}
-	if (hasKey(cfg, "allowSubagents")) {
-		if (typeof cfg.allowSubagents !== "boolean") return "config.allowSubagents must be a boolean when provided.";
-		target.allowSubagents = cfg.allowSubagents;
-	}
-	if (hasKey(cfg, "maxSubagentDepth")) {
-		if (cfg.maxSubagentDepth === false || cfg.maxSubagentDepth === "") target.maxSubagentDepth = undefined;
-		else if (typeof cfg.maxSubagentDepth === "number" && Number.isInteger(cfg.maxSubagentDepth) && cfg.maxSubagentDepth >= 0) {
-			target.maxSubagentDepth = cfg.maxSubagentDepth;
-		} else return "config.maxSubagentDepth must be an integer >= 0 or false when provided.";
-	}
-	if (hasKey(cfg, "maxExecutionTimeMs")) {
-		if (cfg.maxExecutionTimeMs === false || cfg.maxExecutionTimeMs === "") target.maxExecutionTimeMs = undefined;
-		else if (typeof cfg.maxExecutionTimeMs === "number" && Number.isInteger(cfg.maxExecutionTimeMs) && cfg.maxExecutionTimeMs >= 1) {
-			target.maxExecutionTimeMs = cfg.maxExecutionTimeMs;
-		} else return "config.maxExecutionTimeMs must be an integer >= 1 or false when provided.";
-	}
-	if (hasKey(cfg, "maxTokens")) {
-		if (cfg.maxTokens === false || cfg.maxTokens === "") target.maxTokens = undefined;
-		else if (typeof cfg.maxTokens === "number" && Number.isInteger(cfg.maxTokens) && cfg.maxTokens >= 1) {
-			target.maxTokens = cfg.maxTokens;
-		} else return "config.maxTokens must be an integer >= 1 or false when provided.";
-	}
-	if (hasKey(cfg, "completionGuard")) {
-		if (typeof cfg.completionGuard !== "boolean") return "config.completionGuard must be a boolean when provided.";
-		target.completionGuard = cfg.completionGuard;
-	}
-	return undefined;
-}
-
-type MutableTarget<T extends { source: AgentSource }> = T & { source: ManagementScope };
-
-function isMutableTarget<T extends { source: AgentSource }>(target: T): target is MutableTarget<T> {
-	return target.source === "user" || target.source === "project";
-}
-
-function resolveTarget<T extends { source: AgentSource; filePath: string }>(
-	kind: "agent" | "chain",
-	name: string,
-	matches: T[],
-	ctx: ManagementContext,
-	scopeHint?: string,
-): MutableTarget<T> | SubagentExecutionResult {
-	const mutable = matches.filter(isMutableTarget);
-	if (mutable.length === 0) {
-		if (matches.length > 0) {
-			return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' is ${matches[0]!.source} and cannot be modified. Create a same-named ${kind} in user or project scope to override it.`, true);
-		}
-		const available = availableNames(ctx, kind);
-		return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' not found. Available: ${available.join(", ") || "none"}.`, true);
-	}
-	if (mutable.length === 1) return mutable[0]!;
-	const scope = asDisambiguationScope(scopeHint);
-	if (!scope) {
-		const paths = mutable.map((m) => `${m.source}: ${m.filePath}`).join("\n");
-		const sources = new Set(mutable.map((entry) => entry.source));
-		return sources.size === 1
-			? result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' has multiple definitions in ${mutable[0]!.source} scope and cannot be modified safely. Remove or rename one definition first.\n${paths}`, true)
-			: result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' exists in both scopes. Specify agentScope: 'user' or 'project'.\n${paths}`, true);
-	}
-	const scoped = mutable.filter((m) => m.source === scope);
-	if (scoped.length === 0) return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' not found in scope '${scope}'.`, true);
-	if (scoped.length > 1) {
-		return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' has multiple definitions in scope '${scope}' and cannot be modified safely. Remove or rename one definition first:\n${scoped.map((entry) => entry.filePath).join("\n")}`, true);
-	}
-	return scoped[0]!;
-}
-
-function renamePath(
-	kind: "agent" | "chain",
-	currentPath: string,
-	newName: string,
-	scope: ManagementScope,
-	ctx: ManagementContext,
-): { filePath?: string; error?: string } {
-	if (nameExistsInScope(ctx, scope, newName, currentPath)) return { error: `Name '${newName}' already exists in ${scope} scope.` };
-	const ext = kind === "agent" ? ".md" : currentPath.endsWith(".chain.json") ? ".chain.json" : ".chain.md";
-	const filePath = path.join(path.dirname(currentPath), `${newName}${ext}`);
-	if (fs.existsSync(filePath) && filePath !== currentPath) {
-		return { error: `File already exists at ${filePath} but is not a valid ${kind} definition. Remove or rename it first.` };
-	}
-	fs.renameSync(currentPath, filePath);
-	return { filePath };
-}
-
-function formatModelDefaults(agent: AgentConfig): string[] {
-	const thinking = resolveEffectiveThinking(agent.model, agent.thinking) ?? agent.thinking;
-	const inherited = "inherited runtime default (unset)";
-	const fallbacks = agent.fallbackModels?.map((model) =>
-		`${model} (thinking: ${resolveEffectiveThinking(model, agent.thinking ?? thinking) ?? inherited})`);
-	return [
-		`Model: ${agent.model ?? "inherited from parent (resolved at launch)"}`,
-		`Thinking: ${thinking ?? inherited}`,
-		`Fallback models: ${fallbacks?.length ? fallbacks.join(", ") : "none configured"}`,
-	];
-}
-
-function formatAgentDetail(agent: AgentConfig): string {
-	const tools = [...(agent.tools ?? []), ...(agent.mcpDirectTools ?? []).map((t) => `mcp:${t}`)];
-	const lines: string[] = [`Agent: ${agent.name} (${agent.source})`, `Path: ${agent.filePath}`, `Description: ${agent.description}`];
-	if (agent.packageName) {
-		lines.push(`Local name: ${frontmatterNameForConfig(agent)}`);
-		lines.push(`Package: ${agent.packageName}`);
-	}
-	lines.push(...formatModelDefaults(agent));
-	if (tools.length) lines.push(`Tools: ${tools.join(", ")}`);
-	if (agent.skills?.length) lines.push(`Skills: ${agent.skills.join(", ")}`);
-	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.defaultContext) lines.push(`Default context: ${agent.defaultContext}`);
-	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.output) lines.push(`Output: ${agent.output}`);
-	if (agent.defaultReads?.length) lines.push(`Reads: ${agent.defaultReads.join(", ")}`);
-	if (agent.defaultProgress) lines.push("Progress: true");
-	if (agent.allowSubagents) lines.push("Allow subagents: true");
-	if (agent.maxSubagentDepth !== undefined) lines.push(`Max subagent depth: ${agent.maxSubagentDepth}`);
-	if (agent.maxExecutionTimeMs !== undefined) lines.push(`Max execution time: ${agent.maxExecutionTimeMs}ms`);
-	if (agent.maxTokens !== undefined) lines.push(`Max tokens: ${agent.maxTokens}`);
-	if (agent.completionGuard !== undefined) lines.push(`Completion guard: ${agent.completionGuard}`);
-	if (agent.systemPrompt.trim()) lines.push("", "System Prompt:", agent.systemPrompt);
-	return lines.join("\n");
-}
-
-function formatChainStepDetail(step: ChainStepConfig, index: number): string[] {
-	const lines: string[] = [];
-	if (step.expand || step.collect) {
-		const parallel = step.parallel && !Array.isArray(step.parallel) && typeof step.parallel === "object" ? step.parallel as { agent?: unknown; task?: unknown; label?: unknown; outputSchema?: unknown } : undefined;
-		const expand = step.expand && typeof step.expand === "object" ? step.expand as { from?: { output?: unknown; path?: unknown }; item?: unknown; key?: unknown; maxItems?: unknown; onEmpty?: unknown } : undefined;
-		const collect = step.collect && typeof step.collect === "object" ? step.collect as { as?: unknown; outputSchema?: unknown } : undefined;
-		lines.push(`${index + 1}. Dynamic fanout${typeof collect?.as === "string" ? ` -> ${collect.as}` : ""}`);
-		if (expand?.from) lines.push(`   Expand: ${String(expand.from.output ?? "?")}${String(expand.from.path ?? "")}`);
-		if (typeof expand?.item === "string") lines.push(`   Item variable: ${expand.item}`);
-		if (typeof expand?.key === "string") lines.push(`   Key: ${expand.key}`);
-		if (typeof expand?.maxItems === "number") lines.push(`   Max items: ${expand.maxItems}`);
-		if (typeof expand?.onEmpty === "string") lines.push(`   On empty: ${expand.onEmpty}`);
-		if (parallel?.agent) lines.push(`   Agent: ${String(parallel.agent)}`);
-		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 (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"}`);
-		return lines;
-	}
-	lines.push(`${index + 1}. ${step.agent}`);
-	if (step.task?.trim()) lines.push(`   Task: ${step.task}`);
-	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.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}`);
-	if (step.skills === false) lines.push("   Skills: false");
-	else if (Array.isArray(step.skills) && step.skills.length > 0) lines.push(`   Skills: ${step.skills.join(", ")}`);
-	if (step.progress !== undefined) lines.push(`   Progress: ${step.progress ? "true" : "false"}`);
-	return lines;
-}
-
-function formatChainDetail(chain: ChainConfig): string {
-	const lines: string[] = [`Chain: ${chain.name} (${chain.source})`, `Path: ${chain.filePath}`, `Description: ${chain.description}`];
-	if (chain.packageName) {
-		lines.push(`Local name: ${frontmatterNameForConfig(chain)}`);
-		lines.push(`Package: ${chain.packageName}`);
-	}
-	lines.push("", "Steps:");
-	for (let i = 0; i < chain.steps.length; i++) {
-		lines.push(...formatChainStepDetail(chain.steps[i]!, i));
-	}
-	return lines.join("\n");
-}
-
-type AgentListRole = "Recon" | "Planning" | "Implementation" | "Review" | "Coordination" | "Specialized" | "Custom/other";
-
-const AGENT_ROLE_HINTS: Record<AgentListRole, string> = {
-	Recon: "Use for read-only codebase mapping, grep/delta sweeps, and external facts.",
-	Planning: "Use when decomposition or an implementation handoff matters.",
-	Implementation: "Use for bounded code/doc changes after scope is clear.",
-	Review: "Use for independent validation, regressions, and drift checks.",
-	Coordination: "Use for generic delegation or high-context decision checks.",
-	Specialized: "Use only when the task matches the skill description.",
-	"Custom/other": "Project/user agents not classified by the builtins.",
-};
-
-function agentListRole(agent: AgentConfig): AgentListRole {
-	const name = agent.name.split(".").at(-1) ?? agent.name;
-	if (["scout", "context-builder", "researcher"].includes(name)) return "Recon";
-	if (name === "planner") return "Planning";
-	if (["worker", "fixer"].includes(name)) return "Implementation";
-	if (name === "reviewer" || name.includes("review")) return "Review";
-	if (["delegate", "oracle"].includes(name)) return "Coordination";
-	if (agent.source === "builtin") return "Specialized";
-	return "Custom/other";
-}
-
-function formatAgentListLine(a: AgentConfig): string {
-	return `- ${a.name} (${a.source}${a.defaultContext ? `, context: ${a.defaultContext}` : ""}): ${a.description}\n  ${formatModelDefaults(a).join("; ")}`;
-}
-
-export function handleList(params: ManagementParams, ctx: ManagementContext): SubagentExecutionResult {
-	const scope = normalizeListScope(params.agentScope);
-	if (!scope) return result("agentScope must be 'user', 'project', or 'both'.", true);
-	const d = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx), scope);
-	const agents = discoverAgents(ctx.cwd, scope, discoveryOptions(ctx)).agents
-		.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 diagnostics = [...d.agentDiagnostics, ...d.chainDiagnostics];
-	const roleOrder: AgentListRole[] = ["Recon", "Planning", "Implementation", "Review", "Coordination", "Specialized", "Custom/other"];
-	const lines: string[] = ["Executable agents (grouped by role):"];
-	if (!agents.length) {
-		lines.push("- (none)");
-	} else {
-		for (const role of roleOrder) {
-			const group = agents.filter((agent) => agentListRole(agent) === role);
-			if (!group.length) continue;
-			lines.push(``, `**${role}** — ${AGENT_ROLE_HINTS[role]}`, ...group.map(formatAgentListLine));
-		}
-	}
-	lines.push(
-		"",
-		"Chains:",
-		...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"]),
-		...(diagnostics.length ? ["", "Discovery diagnostics:", ...diagnostics.map((entry) => `- ${entry.filePath}: ${entry.error}`)] : []),
-	);
-	return result(lines.join("\n"));
-}
-
 function handleGet(params: ManagementParams, ctx: ManagementContext): SubagentExecutionResult {
-	if (!params.agent && !params.chainName) return result("Specify 'agent' or 'chainName' for get.", true);
-	const hasBoth = Boolean(params.agent && params.chainName);
-	const blocks: string[] = [];
-	let anyFound = false;
-	const scope = normalizeListScope(params.agentScope);
-	if (!scope) return result("agentScope must be 'user', 'project', or 'both'.", true);
-	if (params.agent) {
-		const matches = findEffectiveAgents(params.agent, ctx, scope);
-		if (!matches.length) {
-			const msg = `Agent '${params.agent}' not found. Available: ${availableNames(ctx, "agent", scope).join(", ") || "none"}.`;
-			if (!hasBoth) return result(msg, true);
-			blocks.push(msg);
-		} else {
-			anyFound = true;
-			blocks.push(...matches.map(formatAgentDetail));
-		}
-	}
-	if (params.chainName) {
-		const matches = findChains(params.chainName, ctx, scope);
-		if (!matches.length) {
-			const msg = `Chain '${params.chainName}' not found. Available: ${availableNames(ctx, "chain", scope).join(", ") || "none"}.`;
-			if (!hasBoth) return result(msg, true);
-			blocks.push(msg);
-		} else {
-			anyFound = true;
-			blocks.push(...matches.map(formatChainDetail));
-		}
-	}
-	return result(blocks.join("\n\n"), !anyFound);
-}
-
-export function handleCreate(params: ManagementParams, ctx: ManagementContext): SubagentExecutionResult {
-	const parsedConfig = configObject(params.config);
-	if (parsedConfig.error) return result(parsedConfig.error, true);
-	const cfg = parsedConfig.value;
-	if (!cfg) return result("config required for create.", true);
-	if (typeof cfg.name !== "string" || !cfg.name.trim()) return result("config.name is required and must be a non-empty string.", true);
-	if (typeof cfg.description !== "string" || !cfg.description.trim()) return result("config.description is required and must be a non-empty string.", true);
-	const name = sanitizeName(cfg.name);
-	if (!name) return result("config.name is invalid after sanitization. Use letters, numbers, spaces, or hyphens.", true);
-	const parsedPackage = parsePackageConfig(cfg.package);
-	if (parsedPackage.error) return result(parsedPackage.error, true);
-	const runtimeName = buildRuntimeName(name, parsedPackage.packageName);
-	const scopeRaw = cfg.scope ?? "user";
-	if (scopeRaw !== "user" && scopeRaw !== "project") return result("config.scope must be 'user' or 'project'.", true);
-	const scope = scopeRaw as ManagementScope;
-	const isChain = hasKey(cfg, "steps");
-	const options = discoveryOptions(ctx);
-	if (scope === "project" && options.projectTrusted === false) return result("Project scope is not available because this project is untrusted. Run from a trusted project or use scope: 'user'.", true);
-	const d = discoverAgentsAll(ctx.cwd, options);
-	const targetDir = isChain
-		? scope === "user" ? d.userChainDir : d.projectChainDir ?? path.join(ctx.cwd, ".pi", "chains")
-		: scope === "user" ? d.userDir : d.projectDir ?? path.join(ctx.cwd, ".pi", "agents");
-	fs.mkdirSync(targetDir, { recursive: true });
-	if (nameExistsInScope(ctx, scope, runtimeName)) return result(`Name '${runtimeName}' already exists in ${scope} scope. Use update instead.`, true);
-	const targetPath = path.join(targetDir, isChain ? `${runtimeName}.chain.md` : `${runtimeName}.md`);
-	if (fs.existsSync(targetPath)) return result(`File already exists at ${targetPath} but is not a valid ${isChain ? "chain" : "agent"} definition. Remove or rename it first.`, true);
-	const warnings: string[] = [];
-	if (!isChain && d.builtin.some((a) => a.name === runtimeName)) warnings.push(`Note: this shadows the builtin agent '${runtimeName}'.`);
-	if (isChain) {
-		const keyError = validateChainConfigKeys(cfg);
-		if (keyError) return result(keyError, true);
-		const parsed = parseStepList(cfg.steps);
-		if (parsed.error) return result(parsed.error, true);
-		const chain: ChainConfig = { name: runtimeName, localName: name, packageName: parsedPackage.packageName, description: cfg.description.trim(), source: scope, filePath: targetPath, steps: parsed.steps! };
-		fs.writeFileSync(targetPath, serializeChain(chain), "utf-8");
-		const missing = unknownChainAgents(ctx, chain.steps);
-		if (missing.length) warnings.push(`Warning: chain steps reference unknown agents: ${missing.join(", ")}.`);
-		warnings.push(...chainStepWarnings(ctx, chain.steps));
-		return result([`Created chain '${runtimeName}' at ${targetPath}.`, ...warnings].join("\n"));
-	}
-	const agent: AgentConfig = {
-		name: runtimeName,
-		localName: name,
-		packageName: parsedPackage.packageName,
-		description: cfg.description.trim(),
-		source: scope,
-		filePath: targetPath,
-		systemPrompt: "",
-		systemPromptMode: defaultSystemPromptMode(name),
-		inheritProjectContext: defaultInheritProjectContext(name),
-		inheritSkills: defaultInheritSkills(),
-		maxSubagentDepth: 0,
-	};
-	const applyError = applyAgentConfig(agent, cfg);
-	if (applyError) return result(applyError, true);
-	const mw = modelWarning(ctx, agent.model);
-	if (mw) warnings.push(mw);
-	const fmw = fallbackModelsWarning(ctx, agent.fallbackModels);
-	if (fmw) warnings.push(fmw);
-	const sw = skillsWarning(ctx, agent.skills);
-	if (sw) warnings.push(sw);
-	fs.writeFileSync(targetPath, serializeAgent(agent), "utf-8");
-	return result([`Created agent '${runtimeName}' at ${targetPath}.`, ...warnings].join("\n"));
-}
-
-export function handleUpdate(params: ManagementParams, ctx: ManagementContext): SubagentExecutionResult {
-	if (!params.agent && !params.chainName) return result("Specify 'agent' or 'chainName' for update.", true);
-	if (params.agent && params.chainName) return result("Specify either 'agent' or 'chainName', not both.", true);
-	const parsedConfig = configObject(params.config);
-	if (parsedConfig.error) return result(parsedConfig.error, true);
-	const cfg = parsedConfig.value;
-	if (!cfg) return result("config required for update.", true);
-	const warnings: string[] = [];
-	if (params.agent) {
-		const scopeHint = asDisambiguationScope(params.agentScope);
-		const targetOrError = resolveTarget("agent", params.agent, findAgents(params.agent, ctx, scopeHint ?? "both"), ctx, params.agentScope);
-		if ("content" in targetOrError) return targetOrError;
-		const target = targetOrError;
-		const updated: AgentConfig = { ...target };
-		const oldName = target.name;
-		if (hasKey(cfg, "name") && (typeof cfg.name !== "string" || !cfg.name.trim())) return result("config.name must be a non-empty string when provided.", true);
-		if (hasKey(cfg, "description") && (typeof cfg.description !== "string" || !cfg.description.trim())) return result("config.description must be a non-empty string when provided.", true);
-		let newLocalName = target.localName ?? frontmatterNameForConfig(target);
-		if (hasKey(cfg, "name")) {
-			newLocalName = sanitizeName(cfg.name as string);
-			if (!newLocalName) return result("config.name is invalid after sanitization.", true);
-		}
-		let newPackageName = target.packageName;
-		if (hasKey(cfg, "package")) {
-			const parsedPackage = parsePackageConfig(cfg.package);
-			if (parsedPackage.error) return result(parsedPackage.error, true);
-			newPackageName = parsedPackage.packageName;
-		}
-		const applyError = applyAgentConfig(updated, cfg);
-		if (applyError) return result(applyError, true);
-		updated.localName = newLocalName;
-		updated.packageName = newPackageName;
-		updated.name = buildRuntimeName(newLocalName, newPackageName);
-		if (hasKey(cfg, "description")) updated.description = (cfg.description as string).trim();
-		if (hasKey(cfg, "model")) {
-			const mw = modelWarning(ctx, updated.model);
-			if (mw) warnings.push(mw);
-		}
-		if (hasKey(cfg, "fallbackModels")) {
-			const fmw = fallbackModelsWarning(ctx, updated.fallbackModels);
-			if (fmw) warnings.push(fmw);
-		}
-		if (hasKey(cfg, "skills")) {
-			const sw = skillsWarning(ctx, updated.skills);
-			if (sw) warnings.push(sw);
-		}
-		if (updated.name !== oldName) {
-			const renamed = renamePath("agent", target.filePath, updated.name, target.source, ctx);
-			if (renamed.error) return result(renamed.error, true);
-			updated.filePath = renamed.filePath!;
-		}
-		fs.writeFileSync(updated.filePath, serializeAgent(updated), "utf-8");
-		if (updated.name !== oldName) {
-			const refs = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx)).chains.filter((c) => c.steps.some((s) => s.agent === oldName)).map((c) => `${c.name} (${c.source})`);
-			if (refs.length) warnings.push(`Warning: chains still reference '${oldName}': ${refs.join(", ")}.`);
-		}
-		const headline = updated.name === oldName
-			? `Updated agent '${updated.name}' at ${updated.filePath}.`
-			: `Updated agent '${oldName}' to '${updated.name}' at ${updated.filePath}.`;
-		return result([headline, ...warnings].join("\n"));
-	}
-	const scopeHint = asDisambiguationScope(params.agentScope);
-	const targetOrError = resolveTarget("chain", params.chainName!, findChains(params.chainName!, ctx, scopeHint ?? "both"), ctx, params.agentScope);
-	if ("content" in targetOrError) return targetOrError;
-	const target = targetOrError;
-	const keyError = validateChainConfigKeys(cfg);
-	if (keyError) return result(keyError, true);
-	const updated: ChainConfig = { ...target, steps: [...target.steps] };
-	const oldName = target.name;
-	if (hasKey(cfg, "name") && (typeof cfg.name !== "string" || !cfg.name.trim())) return result("config.name must be a non-empty string when provided.", true);
-	if (hasKey(cfg, "description") && (typeof cfg.description !== "string" || !cfg.description.trim())) return result("config.description must be a non-empty string when provided.", true);
-	let newLocalName = target.localName ?? frontmatterNameForConfig(target);
-	if (hasKey(cfg, "name")) {
-		newLocalName = sanitizeName(cfg.name as string);
-		if (!newLocalName) return result("config.name is invalid after sanitization.", true);
-	}
-	let newPackageName = target.packageName;
-	if (hasKey(cfg, "package")) {
-		const parsedPackage = parsePackageConfig(cfg.package);
-		if (parsedPackage.error) return result(parsedPackage.error, true);
-		newPackageName = parsedPackage.packageName;
-	}
-	let parsedSteps: ChainStepConfig[] | undefined;
-	if (hasKey(cfg, "steps")) {
-		const parsed = parseStepList(cfg.steps);
-		if (parsed.error) return result(parsed.error, true);
-		parsedSteps = parsed.steps!;
-	}
-	updated.localName = newLocalName;
-	updated.packageName = newPackageName;
-	updated.name = buildRuntimeName(newLocalName, newPackageName);
-	if (hasKey(cfg, "description")) updated.description = (cfg.description as string).trim();
-	if (parsedSteps) {
-		updated.steps = parsedSteps;
-		const missing = unknownChainAgents(ctx, updated.steps);
-		if (missing.length) warnings.push(`Warning: chain steps reference unknown agents: ${missing.join(", ")}.`);
-		warnings.push(...chainStepWarnings(ctx, updated.steps));
-	}
-	if (updated.name !== oldName) {
-		const renamed = renamePath("chain", target.filePath, updated.name, target.source, ctx);
-		if (renamed.error) return result(renamed.error, true);
-		updated.filePath = renamed.filePath!;
-	}
-	fs.writeFileSync(updated.filePath, updated.filePath.endsWith(".chain.json") ? serializeJsonChain(updated) : serializeChain(updated), "utf-8");
-	const headline = updated.name === oldName
-		? `Updated chain '${updated.name}' at ${updated.filePath}.`
-		: `Updated chain '${oldName}' to '${updated.name}' at ${updated.filePath}.`;
-	return result([headline, ...warnings].join("\n"));
-}
-
-function handleDelete(params: ManagementParams, ctx: ManagementContext): SubagentExecutionResult {
-	if (!params.agent && !params.chainName) return result("Specify 'agent' or 'chainName' for delete.", true);
-	if (params.agent && params.chainName) return result("Specify either 'agent' or 'chainName', not both.", true);
-	const scopeHint = asDisambiguationScope(params.agentScope);
-	if (params.agent) {
-		const targetOrError = resolveTarget("agent", params.agent, findAgents(params.agent, ctx, scopeHint ?? "both"), ctx, params.agentScope);
-		if ("content" in targetOrError) return targetOrError;
-		const target = targetOrError;
-		fs.unlinkSync(target.filePath);
-		const refs = discoverAgentsAll(ctx.cwd, discoveryOptions(ctx)).chains.filter((c) => c.steps.some((s) => s.agent === target.name)).map((c) => `${c.name} (${c.source})`);
-		const lines = [`Deleted agent '${target.name}' at ${target.filePath}.`];
-		if (refs.length) lines.push(`Warning: chains reference deleted agent '${target.name}': ${refs.join(", ")}.`);
-		return result(lines.join("\n"));
-	}
-	const targetOrError = resolveTarget("chain", params.chainName!, findChains(params.chainName!, ctx, scopeHint ?? "both"), ctx, params.agentScope);
-	if ("content" in targetOrError) return targetOrError;
-	const target = targetOrError;
-	fs.unlinkSync(target.filePath);
-	return result(`Deleted chain '${target.name}' at ${target.filePath}.`);
-}
-
-export function handleManagementAction(action: string, params: ManagementParams, ctx: ManagementContext): SubagentExecutionResult {
-	if (params.agentScope !== undefined && normalizeListScope(params.agentScope) === undefined) {
-		return result("agentScope must be 'user', 'project', or 'both'.", true);
-	}
-	switch (action as ManagementAction) {
-		case "list": return handleList(params, ctx);
-		case "get": return handleGet(params, ctx);
-		case "create": return handleCreate(params, ctx);
-		case "update": return handleUpdate(params, ctx);
-		case "delete": return handleDelete(params, ctx);
-		default: return result(`Unknown action: ${action}`, true);
-	}
+  const agent = params.agent ?? "";
+  const chain = params.chainName ?? "";
+  if (agent.length === 0 && chain.length === 0) {
+    return result("Specify 'agent' or 'chainName' for get.", true);
+  }
+  const scope = normalizeListScope(params.agentScope);
+  if (scope === undefined) {
+    return result("agentScope must be 'user', 'project', or 'both'.", true);
+  }
+  const blocks = [
+    ...(agent.length > 0 ? [getBlocks("agent", agent, ctx, scope)] : []),
+    ...(chain.length > 0 ? [getBlocks("chain", chain, ctx, scope)] : []),
+  ];
+  return result(
+    blocks.flatMap((block) => block.blocks).join("\n\n"),
+    !blocks.some((block) => block.found),
+  );
+}
+export function handleManagementAction(
+  action: string,
+  params: ManagementParams,
+  ctx: ManagementContext,
+): SubagentExecutionResult {
+  if (params.agentScope !== undefined && normalizeListScope(params.agentScope) === undefined) {
+    return result("agentScope must be 'user', 'project', or 'both'.", true);
+  }
+  switch (action) {
+    case "list":
+      return handleList(params, ctx);
+    case "get":
+      return handleGet(params, ctx);
+    case "create":
+      return handleCreate(params, ctx);
+    case "update":
+      return handleUpdate(params, ctx);
+    case "delete":
+      return handleDelete(params, ctx);
+    default:
+      return result(`Unknown action: ${action}`, true);
+  }
 }