@bacnh85/pi-subagent 0.7.0 → 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/extensions/agents.ts

@@ -169,7 +169,7 @@ function loadAgentsFromDir(
 			if (!validSandboxes.includes(frontmatter.sandbox)) {
 				diagnostics.push({
 					filePath,
-					issue: `Invalid sandbox mode "${frontmatter.sandbox}". Valid values: ${validSandboxes.join(", ")}. Using default.`,
+					issue: `Invalid sandbox mode "${frontmatter.sandbox}". Valid values: ${validSandboxes.join(", ")}. Ignoring.`,
 					severity: "warn",
 				});
 			}

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,
@@ -159,7 +161,7 @@ export default function (pi: ExtensionAPI) {
 	// 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 discovery = discoverAgents(ctx?.cwd ?? process.cwd(), "both", bundledAgentsDir);
 		const catalog = discovery.agents
 			.map((a) => {
 				const modelInfo = a.model ? ` (model: ${a.model})` : " (inherits parent)";
@@ -192,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", color: agent.color });
+		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,
@@ -289,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",
@@ -438,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("; ")}`);
 				}
@@ -505,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) {
@@ -554,7 +590,7 @@ export default function (pi: ExtensionAPI) {
 						task: taskWithContext,
 						mode: "chain-step",
 						toolCallId: _toolCallId,
-						color: agents.find(a => a.name === step.agent)?.color,
+						color: agentToThemeColor(step.agent),
 					});
 					const result = await runOne(
 						step.agent, taskWithContext, step.cwd,
@@ -646,7 +682,7 @@ export default function (pi: ExtensionAPI) {
 							task: t.task,
 							mode: "parallel-task",
 							toolCallId: _toolCallId,
-							color: agents.find(a => a.name === t.agent)?.color,
+							color: agentToThemeColor(t.agent),
 						}),
 					);
 
@@ -761,7 +797,7 @@ export default function (pi: ExtensionAPI) {
 					task: params.task,
 					mode: "single",
 					toolCallId: _toolCallId,
-					color: agents.find(a => a.name === params.agent)?.color,
+					color: agentToThemeColor(params.agent),
 				});
 				const result = await runOne(
 					params.agent, params.task, params.cwd,
@@ -814,14 +850,6 @@ 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);
@@ -890,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 ---

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-subagent",
-  "version": "0.7.0",
+  "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",