@bacnh85/pi-subagent 0.6.1 → 0.7.0

package/agents/general-purpose.md

@@ -2,6 +2,7 @@
 name: general-purpose
 description: General-purpose sub-agent for any delegated task. Use when no specialized agent fits. Good for complex research, multi-step operations, and code modifications.
 tools: read, bash, edit, write, grep, find, ls
+color: yellow
 ---
 
 You are a capable coding assistant running as a sub-agent. Complete the delegated task efficiently and return a concise summary of your findings or changes.

package/agents/reviewer.md

@@ -3,6 +3,8 @@ name: reviewer
 description: Code review specialist. Use for correctness, security, regression, and meaningful test-gap review.
 tools: read, grep, find, ls
 thinking: high
+color: purple
+sandbox: read-only
 ---
 
 You are an independent senior code reviewer. Inspect the requested Git scope with read-only tools.

package/agents/scout.md

@@ -3,6 +3,8 @@ name: scout
 description: Fast codebase recon that returns compressed context for handoff. Use for finding files, understanding structure, locating symbols.
 tools: read, grep, find, ls
 thinking: low
+color: cyan
+sandbox: read-only
 ---
 
 You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.

package/agents/worker.md

@@ -2,6 +2,7 @@
 name: worker
 description: General-purpose coding agent with full tool access. Use only when explicitly requested for isolated implementation.
 thinking: medium
+color: green
 ---
 
 You are a skilled software engineer. Implement the requested task with care and precision.

package/extensions/agents.ts

@@ -13,12 +13,16 @@ import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/
 
 export type AgentScope = "user" | "project" | "both";
 
+export type AgentColor = "red" | "blue" | "green" | "yellow" | "purple" | "orange" | "pink" | "cyan";
+
 export interface AgentConfig {
 	name: string;
 	description: string;
 	tools?: string[];
 	model?: string;
 	thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+	sandbox?: "read-only" | "workspace-write";
+	color?: AgentColor;
 	systemPrompt: string;
 	source: "user" | "project" | "bundled";
 	filePath: string;
@@ -160,6 +164,26 @@ function loadAgentsFromDir(
 			}
 		}
 
+		if (typeof frontmatter.sandbox === "string" && frontmatter.sandbox) {
+			const validSandboxes = ["read-only", "workspace-write"];
+			if (!validSandboxes.includes(frontmatter.sandbox)) {
+				diagnostics.push({
+					filePath,
+					issue: `Invalid sandbox mode "${frontmatter.sandbox}". Valid values: ${validSandboxes.join(", ")}. Using default.`,
+					severity: "warn",
+				});
+			}
+		}
+
+		const VALID_COLORS = ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"] as const;
+		if (typeof frontmatter.color === "string" && frontmatter.color && !VALID_COLORS.includes(frontmatter.color as any)) {
+			diagnostics.push({
+				filePath,
+				issue: `Invalid color "${frontmatter.color}". Valid values: ${VALID_COLORS.join(", ")}. Ignoring.`,
+				severity: "warn",
+			});
+		}
+
 		agents.push({
 			name: frontmatter.name,
 			description: frontmatter.description,
@@ -168,6 +192,12 @@ function loadAgentsFromDir(
 			thinking: typeof frontmatter.thinking === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(frontmatter.thinking)
 				? frontmatter.thinking as AgentConfig["thinking"]
 				: undefined,
+			sandbox: typeof frontmatter.sandbox === "string" && ["read-only", "workspace-write"].includes(frontmatter.sandbox)
+				? frontmatter.sandbox as "read-only" | "workspace-write"
+				: undefined,
+			color: typeof frontmatter.color === "string" && VALID_COLORS.includes(frontmatter.color as any)
+				? frontmatter.color as AgentColor
+				: undefined,
 			systemPrompt: body,
 			source,
 			filePath,

package/extensions/index.ts

@@ -153,21 +153,34 @@ export default function (pi: ExtensionAPI) {
 		threadStore.clear();
 	});
 
-	// Proactively steer agents toward sub-agent delegation when users mention it
-	pi.on("before_agent_start", async (event) => {
-		const prompt = event.prompt.toLowerCase();
-		if (/\b(delegate to|use a subagent|run in parallel|spawn an agent|scout|review this|chain|worker agent)\b/.test(prompt)) {
-			return {
-				systemPrompt:
-					event.systemPrompt +
-					"\n\nThe subagent tool is available for delegating tasks to specialized agents with isolated context. Use /subagent to list available agents. Bundled: scout (fast recon), reviewer (code review), worker (implementation), general-purpose (fallback). Modes: single, parallel (max 8), chain.",
-			};
-		}
-	});
-
 	// Resolve bundled agents directory relative to this extension file
 	const bundledAgentsDir = path.resolve(__dirname, "../agents");
 
+	// Inject available agent catalog into system prompt for semantic auto-delegation
+	pi.on("before_agent_start", async (event) => {
+		const ctx = currentCtx;
+		const discovery = discoverAgents(event.cwd ?? ctx?.cwd ?? process.cwd(), "both", bundledAgentsDir);
+		const catalog = discovery.agents
+			.map((a) => {
+				const modelInfo = a.model ? ` (model: ${a.model})` : " (inherits parent)";
+				const thinkingInfo = a.thinking ? `, thinking: ${a.thinking}` : "";
+				const sandboxInfo = a.sandbox ? `, sandbox: ${a.sandbox}` : "";
+				return `- **${a.name}**: ${a.description}${modelInfo}${thinkingInfo}${sandboxInfo}`;
+			})
+			.join("\n");
+		return {
+			systemPrompt:
+				event.systemPrompt +
+				`\n\n## Available Subagents\n${catalog}\n\n` +
+				"The subagent tool can delegate tasks to these specialized agents with isolated context. " +
+				"Use for read-heavy exploration, parallel analysis, or work that would flood the main context.\n" +
+				"Prefer **scout** for fast read-only exploration. " +
+				"Prefer **reviewer** for code review (high thinking, read-only). " +
+				"Prefer **worker** for implementation (medium thinking, all tools). " +
+				"Modes: single, parallel (max 8 tasks, 4 concurrent), chain.",
+		};
+	});
+
 	// Public one-request/one-response service used by pi-review.
 	pi.events.on(SUBAGENT_REQUEST_EVENT, (raw) => {
 		const request = raw as SubagentRunRequest;
@@ -179,7 +192,7 @@ export default function (pi: ExtensionAPI) {
 			request.respond({ id: request.id, ok: false, error: `Unknown agent: ${request.agent}` });
 			return;
 		}
-		const thread = threadStore.createThread({ agentName: agent.name, task: request.task, mode: "single" });
+		const thread = threadStore.createThread({ agentName: agent.name, task: request.task, mode: "single", color: agent.color });
 		void runNamedAgent({
 			agent: request.readOnly ? { ...agent, tools: ["read", "grep", "find", "ls"] } : agent,
 			task: request.task,
@@ -541,6 +554,7 @@ export default function (pi: ExtensionAPI) {
 						task: taskWithContext,
 						mode: "chain-step",
 						toolCallId: _toolCallId,
+						color: agents.find(a => a.name === step.agent)?.color,
 					});
 					const result = await runOne(
 						step.agent, taskWithContext, step.cwd,
@@ -632,6 +646,7 @@ export default function (pi: ExtensionAPI) {
 							task: t.task,
 							mode: "parallel-task",
 							toolCallId: _toolCallId,
+							color: agents.find(a => a.name === t.agent)?.color,
 						}),
 					);
 
@@ -746,6 +761,7 @@ export default function (pi: ExtensionAPI) {
 					task: params.task,
 					mode: "single",
 					toolCallId: _toolCallId,
+					color: agents.find(a => a.name === params.agent)?.color,
 				});
 				const result = await runOne(
 					params.agent, params.task, params.cwd,
@@ -798,6 +814,14 @@ export default function (pi: ExtensionAPI) {
 		// TUI rendering
 		// ------------------------------------------------------------------
 
+		/** Look up agent color by name for TUI rendering. */
+		const resolveAgentColor = (name: string): string => {
+			const ctx = currentCtx;
+			if (!ctx) return "accent";
+			const found = discoverAgents(ctx.cwd, "both", bundledAgentsDir).agents.find(a => a.name === name);
+			return found?.color ?? "accent";
+		};
+
 		renderCall(args, theme, _context) {
 			const scope: AgentScope = args.agentScope ?? "user";
 			const fg = theme.fg.bind(theme);
@@ -816,7 +840,7 @@ export default function (pi: ExtensionAPI) {
 						"\n  " +
 						fg("muted", `${i + 1}.`) +
 						" " +
-						fg("accent", step.agent) +
+						fg(resolveAgentColor(step.agent), step.agent) +
 						fg("dim", ` ${preview}`);
 				}
 				if (args.chain.length > 3)
@@ -832,7 +856,7 @@ export default function (pi: ExtensionAPI) {
 					fg("muted", ` [${scope}]`);
 				for (const t of args.tasks.slice(0, 3)) {
 					const preview = t.task.length > 40 ? `${t.task.slice(0, 40)}...` : t.task;
-					text += `\n  ${fg("accent", t.agent)}${fg("dim", ` ${preview}`)}`;
+					text += `\n  ${fg(resolveAgentColor(t.agent), t.agent)}${fg("dim", ` ${preview}`)}`;
 				}
 				if (args.tasks.length > 3)
 					text += `\n  ${fg("muted", `... +${args.tasks.length - 3} more`)}`;
@@ -848,7 +872,7 @@ export default function (pi: ExtensionAPI) {
 				: "...";
 			let text =
 				fg("toolTitle", theme.bold("subagent ")) +
-				fg("accent", agentName) +
+				fg(resolveAgentColor(agentName), agentName) +
 				fg("muted", ` [${scope}]`);
 			text += `\n  ${fg("dim", preview)}`;
 			return new Text(text, 0, 0);
@@ -895,7 +919,7 @@ export default function (pi: ExtensionAPI) {
 						container.addChild(
 							new Text(
 								fg("muted", `─── Step ${r.exitCode !== -1 ? "" : "?"}: `) +
-									fg("accent", r.agent) +
+									fg(resolveAgentColor(r.agent), r.agent) +
 									` ${stepIcon}`,
 								0,
 								0,
@@ -930,7 +954,8 @@ export default function (pi: ExtensionAPI) {
 					fg("accent", `${successCount}/${details.results.length} steps`);
 				for (const r of details.results) {
 					const stepIcon = isFailedResult(r) ? fg("error", "✗") : fg("success", "✓");
-					text += `\n  ${stepIcon} ${fg("accent", r.agent)}`;
+					const color = resolveAgentColor(r.agent);
+					text += `\n  ${stepIcon} ${fg(color, r.agent)}`;
 				}
 				const totalUsage = formatUsageStats(aggregateUsage(details.results));
 				if (totalUsage) text += `\n${fg("dim", totalUsage)}`;
@@ -973,7 +998,7 @@ export default function (pi: ExtensionAPI) {
 							: fg("success", "✓");
 						container.addChild(
 							new Text(
-								fg("muted", "─── ") + fg("accent", r.agent) + ` ${taskIcon}`,
+								fg("muted", "─── ") + fg(resolveAgentColor(r.agent), r.agent) + ` ${taskIcon}`,
 								0,
 								0,
 							),
@@ -1013,7 +1038,7 @@ export default function (pi: ExtensionAPI) {
 							: isFailedResult(r)
 								? fg("error", "✗")
 								: fg("success", "✓");
-					text += `\n  ${taskIcon} ${fg("accent", r.agent)}`;
+					text += `\n  ${taskIcon} ${fg(resolveAgentColor(r.agent), r.agent)}`;
 				}
 				if (!isRunning) {
 					const totalUsage = formatUsageStats(aggregateUsage(details.results));

package/extensions/thread-viewer.ts

@@ -123,7 +123,8 @@ export class ThreadViewer {
 		else if (this.thread.mode === "chain-step") modeLabel = t.fg("muted", " [chain]");
 
 		// Header
-		let header = `${icon} ${t.fg("toolTitle", t.bold(this.thread.agentName))}${modeLabel}`;
+		const agentColor = this.thread.color ?? "accent";
+		let header = `${icon} ${t.fg(agentColor, t.bold(this.thread.agentName))}${modeLabel}`;
 		if (status === "running") header += ` ${t.fg("warning", "(running...)")}`;
 		else if (status === "aborted") header += ` ${t.fg("error", "[aborted]")}`;
 		if (result && isErr && result.stopReason && result.stopReason !== "error" && result.stopReason !== "aborted") {

package/extensions/threads.ts

@@ -23,6 +23,7 @@ export interface SubagentThread {
 	status: ThreadStatus;
 	result?: SubAgentResult;
 	toolCallId?: string;
+	color?: string;
 	createdAt: number;
 	updatedAt: number;
 }
@@ -53,6 +54,7 @@ export class ThreadStore {
 		task: string;
 		mode: ThreadMode;
 		toolCallId?: string;
+		color?: string;
 	}): SubagentThread {
 		const id = cryptoGenId();
 		const now = Date.now();
@@ -63,6 +65,7 @@ export class ThreadStore {
 			mode: params.mode,
 			status: "running",
 			toolCallId: params.toolCallId,
+			color: params.color,
 			createdAt: now,
 			updatedAt: now,
 		};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-subagent",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "In-process subagents for Pi with isolated SDK sessions, parallel and chained delegation, and inspectable threads.",
   "type": "module",
   "license": "MIT",