@bacnh85/pi-subagent 0.7.0 → 0.8.0

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

@@ -48,6 +48,7 @@ interface AgentCache {
 	scope: AgentScope;
 	agents: AgentConfig[];
 	projectAgentsDir: string | null;
+	diagnostics: AgentDiscoveryDiagnostic[];
 	/** File-level signature per directory (name:mtime:size for each .md file) */
 	dirSignatures: Map<string, string>;
 }
@@ -104,7 +105,22 @@ function loadAgentsFromDir(
 			continue;
 		}
 
-		const { frontmatter, body } = parseFrontmatter<Record<string, unknown>>(content);
+
+
+		let frontmatter: Record<string, unknown>;
+		let body: string;
+		try {
+			const parsed = parseFrontmatter<Record<string, unknown>>(content);
+			frontmatter = parsed.frontmatter;
+			body = parsed.body;
+		} catch (err) {
+			diagnostics.push({
+				filePath,
+				issue: `Failed to parse YAML frontmatter: ${err instanceof Error ? err.message : String(err)}`,
+				severity: "error",
+			});
+			continue;
+		}
 
 		if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") {
 			if (typeof frontmatter.name !== "string" && typeof frontmatter.description !== "string") {
@@ -169,7 +185,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",
 				});
 			}
@@ -225,8 +241,12 @@ function dirSignature(dir: string): string {
 			.filter((e) => e.name.endsWith(".md") && (e.isFile() || e.isSymbolicLink()))
 			.map((e) => {
 				const file = path.join(dir, e.name);
-				const st = fs.statSync(file);
-				return `${e.name}:${st.mtimeMs}:${st.size}`;
+				try {
+					const st = fs.statSync(file);
+					return `${e.name}:${st.mtimeMs}:${st.size}`;
+				} catch {
+					return `${e.name}:broken`;
+				}
 			})
 			.sort();
 		return `exists:${entries.join("|")}`;
@@ -277,7 +297,7 @@ export function discoverAgents(
 			}
 		}
 		if (!stale) {
-			return { agents: _cache.agents, projectAgentsDir: _cache.projectAgentsDir, diagnostics: [] };
+			return { agents: _cache.agents, projectAgentsDir: _cache.projectAgentsDir, diagnostics: _cache.diagnostics };
 		}
 		// Cache is stale — rebuild below
 		_cache = null;
@@ -316,6 +336,7 @@ export function discoverAgents(
 		scope,
 		agents,
 		projectAgentsDir,
+		diagnostics,
 		dirSignatures,
 	};
 

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,
@@ -207,11 +209,15 @@ export default function (pi: ExtensionAPI) {
 				status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
 				result,
 			});
-			if (isFailedResult(result)) request.respond({ id: request.id, ok: false, error: getResultOutput(result) });
-			else request.respond({ id: request.id, ok: true, result });
+			try {
+				if (isFailedResult(result)) request.respond({ id: request.id, ok: false, error: getResultOutput(result) });
+				else request.respond({ id: request.id, ok: true, result });
+			} catch { /* respond channel closed */ }
 		}, (error) => {
 			threadStore.updateThread(thread.id, { status: "failed" });
-			request.respond({ id: request.id, ok: false, error: error instanceof Error ? error.message : String(error) });
+			try {
+				request.respond({ id: request.id, ok: false, error: error instanceof Error ? error.message : String(error) });
+			} catch { /* respond channel closed */ }
 		});
 	});
 
@@ -228,9 +234,12 @@ export default function (pi: ExtensionAPI) {
 				const list = formatAgentList(fresh.agents, 20);
 				const extra = list.remaining > 0 ? `\n  ... +${list.remaining} more` : "";
 				const dirs = fresh.projectAgentsDir ? `project: ${fresh.projectAgentsDir}` : "no project agents dir";
+				const diagText = fresh.diagnostics.length > 0
+					? "\n\nWarnings:\n" + fresh.diagnostics.map(d => `  - [${d.severity}] ${d.filePath}: ${d.issue}`).join("\n")
+					: "";
 				pi.sendMessage({
 					customType: "pi-subagent",
-					content: `Agent definitions reloaded.\n\nAvailable agents (${fresh.agents.length}):\n  ${list.text}${extra}\n\nDirectories searched:\n  user: ${path.join(getAgentDir(), "agents")}\n  ${dirs}\n  bundled: ${bundledAgentsDir}`,
+					content: `Agent definitions reloaded.\n\nAvailable agents (${fresh.agents.length}):\n  ${list.text}${extra}${diagText}\n\nDirectories searched:\n  user: ${path.join(getAgentDir(), "agents")}\n  ${dirs}\n  bundled: ${bundledAgentsDir}`,
 					display: true,
 				});
 				ctx.ui.notify("Agent definitions reloaded", "info");
@@ -242,9 +251,12 @@ export default function (pi: ExtensionAPI) {
 				const list = formatAgentList(discovery.agents, 20);
 				const extra = list.remaining > 0 ? `\n  ... +${list.remaining} more` : "";
 				const dirs = discovery.projectAgentsDir ? `\n  project: ${discovery.projectAgentsDir}` : "";
+				const diagText = discovery.diagnostics.length > 0
+					? "\n\nWarnings:\n" + discovery.diagnostics.map(d => `  - [${d.severity}] ${d.filePath}: ${d.issue}`).join("\n")
+					: "";
 				pi.sendMessage({
 					customType: "pi-subagent",
-					content: `Available agents (${discovery.agents.length}):\n  ${list.text}${extra}\n\nScopes searched:\n  user: ${path.join(getAgentDir(), "agents")}${dirs}\n  bundled: ${bundledAgentsDir}\n\nUse /subagent <name> for agent details, /subagent reload to refresh.`,
+					content: `Available agents (${discovery.agents.length}):\n  ${list.text}${extra}${diagText}\n\nScopes searched:\n  user: ${path.join(getAgentDir(), "agents")}${dirs}\n  bundled: ${bundledAgentsDir}\n\nUse /subagent <name> for agent details, /subagent reload to refresh.`,
 					display: true,
 				});
 				return;
@@ -281,14 +293,45 @@ export default function (pi: ExtensionAPI) {
 			const list = formatAgentList(discovery.agents, 20);
 			const extra = list.remaining > 0 ? `\n  ... +${list.remaining} more` : "";
 			const dirs = discovery.projectAgentsDir ? `\n  project: ${discovery.projectAgentsDir}` : "";
+			const diagText = discovery.diagnostics.length > 0
+				? "\n\nWarnings:\n" + discovery.diagnostics.map(d => `  - [${d.severity}] ${d.filePath}: ${d.issue}`).join("\n")
+				: "";
 			pi.sendMessage({
 				customType: "pi-subagent",
-				content: `Available agents (${discovery.agents.length}):\n  ${list.text}${extra}\n\nScopes searched:\n  user: ${path.join(getAgentDir(), "agents")}${dirs}\n  bundled: ${bundledAgentsDir}\n\nUse /subagent <name> for agent details, /subagent reload to refresh.`,
+				content: `Available agents (${discovery.agents.length}):\n  ${list.text}${extra}${diagText}\n\nScopes searched:\n  user: ${path.join(getAgentDir(), "agents")}${dirs}\n  bundled: ${bundledAgentsDir}\n\nUse /subagent <name> for agent details, /subagent reload to refresh.`,
 				display: true,
 			});
 		},
 	});
 
+	/** 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 +481,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("; ")}`);
 				}
@@ -476,6 +525,8 @@ export default function (pi: ExtensionAPI) {
 						agent: agentName,
 						task,
 						exitCode: 1,
+						status: "error",
+						stopReason: "error",
 						messages: [],
 						stderr: `Unknown agent: "${agentName}". Available: ${available}.`,
 						usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
@@ -491,6 +542,8 @@ export default function (pi: ExtensionAPI) {
 						agent: agentName,
 						task,
 						exitCode: 1,
+						status: "error",
+						stopReason: "error",
 						messages: [],
 						stderr: `Model not found for agent "${agentName}". Tried: ${tried}. Parent model: ${parentInfo}. Check agent definition and pi model configuration.`,
 						usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
@@ -505,7 +558,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) {
@@ -514,6 +567,8 @@ export default function (pi: ExtensionAPI) {
 						agent: agentName,
 						task,
 						exitCode: 1,
+						status: "error",
+						stopReason: "error",
 						messages: [],
 						stderr: `Validation error: ${errorMsg}`,
 						usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
@@ -547,14 +602,14 @@ export default function (pi: ExtensionAPI) {
 
 				for (let i = 0; i < params.chain.length; i++) {
 					const step = params.chain[i];
-					const taskWithContext = step.task.replace(/\{previous\}/g, previousOutput);
+					const taskWithContext = step.task.replace(/\{previous\}/g, () => previousOutput);
 
 					const thread = threadStore.createThread({
 						agentName: step.agent,
 						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 +701,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),
 						}),
 					);
 
@@ -689,6 +744,7 @@ export default function (pi: ExtensionAPI) {
 										agent: t.agent,
 										task: t.task,
 										exitCode: 1,
+										status: "error",
 										messages: [],
 										stderr: "",
 										usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
@@ -761,7 +817,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 +870,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 +938,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/extensions/runner.ts

@@ -148,6 +148,8 @@ export async function runSubAgent(options: {
 			result.stopReason = isTimeout ? "timeout" : "aborted";
 			result.errorMessage = combinedSignal.reason instanceof Error ? combinedSignal.reason.message : "Sub-agent aborted before start";
 			result.status = classifyStopReason(result.stopReason, !isTimeout, isTimeout);
+			cleanupCombined?.();
+			if (timeoutId) clearTimeout(timeoutId);
 			return result;
 		}
 
@@ -167,6 +169,7 @@ export async function runSubAgent(options: {
 		let cleanupEventAbort: (() => void) | undefined;
 		let abortedBySignal = false;
 		let timedOut = false;
+		let eventUnsubscribe: (() => void) | undefined;
 
 		try {
 			// Wire combined abort signal to session
@@ -191,7 +194,8 @@ export async function runSubAgent(options: {
 					fn();
 				};
 
-				const unsubscribe = session.subscribe((event) => {
+				let unsubscribe: (() => void) | undefined;
+				unsubscribe = session.subscribe((event) => {
 					try {
 						switch (event.type) {
 							case "message_end": {
@@ -223,7 +227,7 @@ export async function runSubAgent(options: {
 									result.messages = event.messages as unknown as Message[];
 								}
 								finish(() => {
-									unsubscribe();
+									unsubscribe?.();
 									resolve();
 								});
 								break;
@@ -231,18 +235,19 @@ export async function runSubAgent(options: {
 						}
 					} catch (err) {
 						finish(() => {
-							unsubscribe();
+							unsubscribe?.();
 							reject(err);
 						});
 					}
 				});
+				eventUnsubscribe = unsubscribe;
 
 				// Resolve on abort so the eventPromise doesn't hang
 				const onAbortResolve = () => {
 					finish(() => {
 						result.exitCode = 1;
 						if (!result.errorMessage) result.errorMessage = "Sub-agent aborted";
-						unsubscribe();
+						unsubscribe?.();
 						resolve();
 					});
 				};
@@ -279,6 +284,7 @@ export async function runSubAgent(options: {
 			cleanupAbort?.();
 			cleanupEventAbort?.();
 			cleanupCombined();
+			eventUnsubscribe?.();
 			if (timeoutId) clearTimeout(timeoutId);
 			try {
 				session.dispose();

package/extensions/service.ts

@@ -7,6 +7,7 @@ import {
 	normalizeTimeout,
 	resolveSafeCwd,
 	MAX_INSTRUCTIONS_LENGTH,
+	READ_ONLY_TOOLS,
 } from "./security.ts";
 
 export const SUBAGENT_REQUEST_EVENT = "pi-subagent:run";
@@ -53,8 +54,13 @@ export async function runNamedAgent(options: {
 	const effectiveTimeoutMs = normalizeTimeout({ requested: options.timeout }).timeoutMs;
 
 	// Security: validate tools against allowlist.
-	const rawTools = options.agent.tools ?? ["read", "bash", "edit", "write", "grep", "find", "ls"];
-	const toolValidation = validateAgentTools({ tools: rawTools });
+	let rawTools = options.agent.tools ?? ["read", "bash", "edit", "write", "grep", "find", "ls"];
+	// Enforce read-only sandbox: strip mutating and execution tools
+	if (options.agent.sandbox === "read-only") {
+		rawTools = rawTools.filter(t => READ_ONLY_TOOLS.includes(t));
+		if (rawTools.length === 0) rawTools = [...READ_ONLY_TOOLS];
+	}
+	const toolValidation = validateAgentTools({ tools: rawTools, readOnly: options.agent.sandbox === "read-only" });
 	if (toolValidation.errors.length > 0) {
 		throw new Error(`Tool validation errors for agent "${options.agent.name}": ${toolValidation.errors.join("; ")}`);
 	}

package/extensions/thread-viewer.ts

@@ -226,6 +226,7 @@ export class ThreadViewer {
 				? Math.max(0, total - (maxVisible - 1))
 				: 0;
 		const offset = Math.max(0, Math.min(this.scrollOffset, maxOffset));
+		this.scrollOffset = offset;
 
 		// Reserve space for scroll indicators
 		const aboveShown = offset > 0;

package/package.json

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