@bacnh85/pi-subagent 0.6.1 → 0.7.1

package/agent-format.md

@@ -21,9 +21,21 @@ description: ...        # Required. When to use this agent.
 tools: read, grep, ...  # Optional. Comma-separated tool names. Defaults to all.
 model: provider/model     # Optional. Defaults to parent's model.
 thinking: low             # Optional: off|minimal|low|medium|high|xhigh|max.
+sandbox: read-only        # Optional: read-only | workspace-write. Auto-derives tool restrictions.
+color: cyan               # Optional: red|blue|green|yellow|purple|orange|pink|cyan.
 ---
 ```
 
+### `sandbox`
+
+- `read-only`: Restricts tools to `read`, `grep`, `find`, `ls`. Overrides any `tools` field.
+- `workspace-write` (default): Uses the agent's `tools` list or defaults to all tools.
+
+### `color`
+
+Display color for the agent name in the TUI thread picker, viewer, and result summary.
+Accepted values: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`.
+
 Only `name` and `description` are required.
 
 ## Body

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(", ")}. Ignoring.`,
+					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

@@ -25,11 +25,12 @@ import {
 	getAgentDir,
 	getMarkdownTheme,
 	ModelRegistry,
+	type ThemeColor,
 } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, SelectList, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
-import { type AgentConfig, type AgentScope, discoverAgents, formatAgentList, invalidateAgentCache } from "./agents.ts";
+import { type AgentColor, type AgentConfig, type AgentScope, discoverAgents, formatAgentList, invalidateAgentCache } from "./agents.ts";
 import {
 	type SubAgentResult,
 	getFinalOutput,
@@ -44,6 +45,7 @@ import {
 	validateAgentTools,
 	truncateParallelOutput,
 	validateExecutionRequest,
+	READ_ONLY_TOOLS,
 	MAX_CONCURRENCY,
 	MAX_PARALLEL_TASKS,
 	MAX_CHAIN_LENGTH,
@@ -153,21 +155,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(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 +194,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 ? AGENT_TO_THEME_COLOR[agent.color as AgentColor] : undefined });
 		void runNamedAgent({
 			agent: request.readOnly ? { ...agent, tools: ["read", "grep", "find", "ls"] } : agent,
 			task: request.task,
@@ -276,6 +291,34 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	/** Map AgentColor (from agent frontmatter) to ThemeColor (for pi TUI). */
+	const AGENT_TO_THEME_COLOR: Record<AgentColor, ThemeColor> = {
+		red: "error",
+		blue: "accent",
+		green: "success",
+		yellow: "warning",
+		purple: "syntaxType",
+		orange: "syntaxString",
+		pink: "customMessageLabel",
+		cyan: "syntaxVariable",
+	};
+
+	/** Resolve agent-defined color to a valid ThemeColor for thread creation. */
+	const agentToThemeColor = (agentName: string): ThemeColor | undefined => {
+		const ctx = currentCtx;
+		if (!ctx) return undefined;
+		const agent = discoverAgents(ctx.cwd, "both", bundledAgentsDir).agents.find(a => a.name === agentName);
+		return agent?.color ? AGENT_TO_THEME_COLOR[agent.color] : undefined;
+	};
+
+	/** Look up agent color by name for TUI rendering. */
+	const resolveAgentColor = (name: string): ThemeColor => {
+		const ctx = currentCtx;
+		if (!ctx) return "accent";
+		const found = discoverAgents(ctx.cwd, "both", bundledAgentsDir).agents.find(a => a.name === name);
+		return found?.color ? AGENT_TO_THEME_COLOR[found.color] : "accent";
+	};
+
 	pi.registerTool({
 		name: "subagent",
 		label: "Subagent",
@@ -425,10 +468,16 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			// Helper: validate and normalise tools for an agent.
-			function resolveChildTools(agentTools: string[] | undefined, readOnly?: boolean): string[] {
+			function resolveChildTools(agentTools: string[] | undefined, sandbox?: string, readOnly?: boolean): string[] {
 				const defaultTools = ["read", "bash", "edit", "write", "grep", "find", "ls"];
-				const rawTools = agentTools ?? defaultTools;
-				const result = validateAgentTools({ tools: rawTools, readOnly });
+				let rawTools = agentTools ?? defaultTools;
+				// sandbox overrides tools: silently strip mutation tools, not an error
+				if (sandbox === "read-only") {
+					rawTools = rawTools.filter(t => READ_ONLY_TOOLS.includes(t));
+					if (rawTools.length === 0) rawTools = [...READ_ONLY_TOOLS];
+				}
+				const effectiveReadOnly = readOnly || sandbox === "read-only";
+				const result = validateAgentTools({ tools: rawTools, readOnly: effectiveReadOnly });
 				if (result.errors.length > 0) {
 					throw new Error(`Tool validation errors: ${result.errors.join("; ")}`);
 				}
@@ -492,7 +541,7 @@ export default function (pi: ExtensionAPI) {
 				try {
 					// Inject parent's API key so --api-key and other runtime overrides work
 					await injectApiKey(resolved.model);
-					tools = resolveChildTools(agent.tools, isReadOnly);
+					tools = resolveChildTools(agent.tools, agent.sandbox, isReadOnly);
 					effectiveTimeoutMs = resolveChildTimeout(timeoutMs, params.timeout);
 					safeCwd = resolveChildCwd(cwd);
 				} catch (err: unknown) {
@@ -541,6 +590,7 @@ export default function (pi: ExtensionAPI) {
 						task: taskWithContext,
 						mode: "chain-step",
 						toolCallId: _toolCallId,
+						color: agentToThemeColor(step.agent),
 					});
 					const result = await runOne(
 						step.agent, taskWithContext, step.cwd,
@@ -632,6 +682,7 @@ export default function (pi: ExtensionAPI) {
 							task: t.task,
 							mode: "parallel-task",
 							toolCallId: _toolCallId,
+							color: agentToThemeColor(t.agent),
 						}),
 					);
 
@@ -746,6 +797,7 @@ export default function (pi: ExtensionAPI) {
 					task: params.task,
 					mode: "single",
 					toolCallId: _toolCallId,
+					color: agentToThemeColor(params.agent),
 				});
 				const result = await runOne(
 					params.agent, params.task, params.cwd,
@@ -816,7 +868,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 +884,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 +900,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);
@@ -866,7 +918,8 @@ export default function (pi: ExtensionAPI) {
 
 			// --- Single ---
 			if (details.mode === "single" && details.results.length === 1) {
-				return renderSingleResult(details.results[0], expanded, theme);
+				const r = details.results[0];
+				return renderSingleResult(r, expanded, theme, resolveAgentColor(r.agent));
 			}
 
 			// --- Chain ---
@@ -895,7 +948,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 +983,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 +1027,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 +1067,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/render.ts

@@ -188,6 +188,7 @@ export function renderSingleResult(
 	result: SubAgentResult,
 	expanded: boolean,
 	theme: { fg: (c: any, t: string) => string; bold: (t: string) => string },
+	agentColor?: string,
 ): Container | Text {
 	const isError = isFailedResult(result);
 	const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
@@ -197,7 +198,7 @@ export function renderSingleResult(
 	if (expanded) {
 		const mdTheme = getMarkdownTheme();
 		const container = new Container();
-		let header = `${icon} ${theme.fg("toolTitle", theme.bold(result.agent))}`;
+		let header = `${icon} ${theme.fg(agentColor ?? "toolTitle", theme.bold(result.agent))}`;
 		if (isError && result.stopReason) {
 			const reasonColor = result.stopReason === "timeout" ? "warning" : "error";
 			header += ` ${theme.fg(reasonColor, `[${result.stopReason}]`)}`;
@@ -239,7 +240,7 @@ export function renderSingleResult(
 	}
 
 	// Collapsed
-	let text = `${icon} ${theme.fg("toolTitle", theme.bold(result.agent))}`;
+	let text = `${icon} ${theme.fg(agentColor ?? "toolTitle", theme.bold(result.agent))}`;
 	if (isError && result.stopReason) {
 		const reasonColor = result.stopReason === "timeout" ? "warning" : "error";
 		text += ` ${theme.fg(reasonColor, `[${result.stopReason}]`)}`;

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.1",
   "description": "In-process subagents for Pi with isolated SDK sessions, parallel and chained delegation, and inspectable threads.",
   "type": "module",
   "license": "MIT",