@oh-my-pi/pi-coding-agent 3.0.1337 → 3.1.1337

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [3.1.1337] - 2026-01-03
+### Added
+
+- Added `spawns` frontmatter field for agent definitions to control which sub-agents can be spawned
+- Added spawn restriction enforcement preventing agents from spawning unauthorized sub-agents
+
+### Fixed
+
+- Fixed duplicate skill loading when the same SKILL.md file was discovered through multiple paths
+
 ## [3.0.1337] - 2026-01-03
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "3.0.1337",
+	"version": "3.1.1337",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"ompConfig": {
@@ -39,9 +39,9 @@
 		"prepublishOnly": "bun run generate-template && bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-agent-core": "3.0.1337",
-		"@oh-my-pi/pi-ai": "3.0.1337",
-		"@oh-my-pi/pi-tui": "3.0.1337",
+		"@oh-my-pi/pi-agent-core": "3.1.1337",
+		"@oh-my-pi/pi-ai": "3.1.1337",
+		"@oh-my-pi/pi-tui": "3.1.1337",
 		"@sinclair/typebox": "^0.34.46",
 		"ajv": "^8.17.1",
 		"chalk": "^5.5.0",

package/src/core/skills.ts

@@ -46,6 +46,30 @@ export interface LoadSkillsFromDirOptions {
 export function loadSkillsFromDir(options: LoadSkillsFromDirOptions): LoadSkillsResult {
 	const skills: Skill[] = [];
 	const warnings: SkillWarning[] = [];
+	const seenPaths = new Set<string>();
+
+	function addSkill(skillFile: string, skillDir: string, dirName: string) {
+		if (seenPaths.has(skillFile)) return;
+		try {
+			const content = readFileSync(skillFile, "utf-8");
+			const { frontmatter } = parseFrontmatter(content);
+			const name = (frontmatter.name as string) || dirName;
+			const description = frontmatter.description as string;
+
+			if (description) {
+				seenPaths.add(skillFile);
+				skills.push({
+					name,
+					description,
+					filePath: skillFile,
+					baseDir: skillDir,
+					source: options.source,
+				});
+			}
+		} catch {
+			// Skip invalid skills
+		}
+	}
 
 	function scanDir(dir: string) {
 		try {
@@ -59,45 +83,14 @@ export function loadSkillsFromDir(options: LoadSkillsFromDirOptions): LoadSkills
 					try {
 						const stat = statSync(skillFile);
 						if (stat.isFile()) {
-							const content = readFileSync(skillFile, "utf-8");
-							const { frontmatter } = parseFrontmatter(content);
-							const name = (frontmatter.name as string) || entry.name;
-							const description = frontmatter.description as string;
-
-							if (description) {
-								skills.push({
-									name,
-									description,
-									filePath: skillFile,
-									baseDir: fullPath,
-									source: options.source,
-								});
-							}
+							addSkill(skillFile, fullPath, entry.name);
 						}
 					} catch {
-						// Skip invalid skills
+						// No SKILL.md in this directory
 					}
-
 					scanDir(fullPath);
 				} else if (entry.isFile() && entry.name === "SKILL.md") {
-					try {
-						const content = readFileSync(fullPath, "utf-8");
-						const { frontmatter } = parseFrontmatter(content);
-						const name = (frontmatter.name as string) || basename(dir);
-						const description = frontmatter.description as string;
-
-						if (description) {
-							skills.push({
-								name,
-								description,
-								filePath: fullPath,
-								baseDir: dir,
-								source: options.source,
-							});
-						}
-					} catch {
-						// Skip invalid skills
-					}
+					addSkill(fullPath, dir, basename(dir));
 				}
 			}
 		} catch (err) {
@@ -117,6 +110,30 @@ export function loadSkillsFromDir(options: LoadSkillsFromDirOptions): LoadSkills
 function scanDirectoryForSkills(dir: string): LoadSkillsResult {
 	const skills: Skill[] = [];
 	const warnings: SkillWarning[] = [];
+	const seenPaths = new Set<string>();
+
+	function addSkill(skillFile: string, skillDir: string, dirName: string) {
+		if (seenPaths.has(skillFile)) return;
+		try {
+			const content = readFileSync(skillFile, "utf-8");
+			const { frontmatter } = parseFrontmatter(content);
+			const name = (frontmatter.name as string) || dirName;
+			const description = frontmatter.description as string;
+
+			if (description) {
+				seenPaths.add(skillFile);
+				skills.push({
+					name,
+					description,
+					filePath: skillFile,
+					baseDir: skillDir,
+					source: "custom",
+				});
+			}
+		} catch {
+			// Skip invalid skills
+		}
+	}
 
 	function scanDir(currentDir: string) {
 		try {
@@ -130,45 +147,14 @@ function scanDirectoryForSkills(dir: string): LoadSkillsResult {
 					try {
 						const stat = statSync(skillFile);
 						if (stat.isFile()) {
-							const content = readFileSync(skillFile, "utf-8");
-							const { frontmatter } = parseFrontmatter(content);
-							const name = (frontmatter.name as string) || entry.name;
-							const description = frontmatter.description as string;
-
-							if (description) {
-								skills.push({
-									name,
-									description,
-									filePath: skillFile,
-									baseDir: fullPath,
-									source: "custom",
-								});
-							}
+							addSkill(skillFile, fullPath, entry.name);
 						}
 					} catch {
-						// Skip invalid skills
+						// No SKILL.md in this directory
 					}
-
 					scanDir(fullPath);
 				} else if (entry.isFile() && entry.name === "SKILL.md") {
-					try {
-						const content = readFileSync(fullPath, "utf-8");
-						const { frontmatter } = parseFrontmatter(content);
-						const name = (frontmatter.name as string) || basename(currentDir);
-						const description = frontmatter.description as string;
-
-						if (description) {
-							skills.push({
-								name,
-								description,
-								filePath: fullPath,
-								baseDir: currentDir,
-								source: "custom",
-							});
-						}
-					} catch {
-						// Skip invalid skills
-					}
+					addSkill(fullPath, currentDir, basename(currentDir));
 				}
 			}
 		} catch (err) {

package/src/core/tools/task/agents.ts

@@ -68,6 +68,26 @@ function parseAgent(fileName: string, content: string, source: AgentSource): Age
 		.map((t) => t.trim())
 		.filter(Boolean);
 
+	// Parse spawns field
+	let spawns: string[] | "*" | undefined;
+	if (frontmatter.spawns !== undefined) {
+		const spawnsRaw = frontmatter.spawns.trim();
+		if (spawnsRaw === "*") {
+			spawns = "*";
+		} else if (spawnsRaw) {
+			spawns = spawnsRaw
+				.split(",")
+				.map((s) => s.trim())
+				.filter(Boolean);
+			if (spawns.length === 0) spawns = undefined;
+		}
+	}
+
+	// Backward compat: infer spawns: "*" when tools includes "task"
+	if (spawns === undefined && tools?.includes("task")) {
+		spawns = "*";
+	}
+
 	const recursive =
 		frontmatter.recursive === undefined ? false : frontmatter.recursive === "true" || frontmatter.recursive === "1";
 
@@ -75,6 +95,7 @@ function parseAgent(fileName: string, content: string, source: AgentSource): Age
 		name: frontmatter.name,
 		description: frontmatter.description,
 		tools: tools && tools.length > 0 ? tools : undefined,
+		spawns,
 		model: frontmatter.model,
 		recursive,
 		systemPrompt: body,

package/src/core/tools/task/bundled-agents/reviewer.md

@@ -1,7 +1,8 @@
 ---
 name: reviewer
 description: Code review specialist for quality and security analysis
-tools: read, grep, find, ls, bash, task, report_finding, submit_review
+tools: read, grep, find, ls, bash, report_finding, submit_review
+spawns: explore
 model: pi/slow, gpt-5.2-codex, gpt-5.2, codex, gpt
 ---
 

package/src/core/tools/task/bundled-agents/task.md

@@ -1,6 +1,7 @@
 ---
 name: task
 description: General-purpose subagent with full capabilities for delegated multi-step tasks
+spawns: explore
 model: default
 ---
 

package/src/core/tools/task/discovery.ts

@@ -106,6 +106,26 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentDefinition[]
 			.map((t) => t.trim())
 			.filter(Boolean);
 
+		// Parse spawns field
+		let spawns: string[] | "*" | undefined;
+		if (frontmatter.spawns !== undefined) {
+			const spawnsRaw = frontmatter.spawns.trim();
+			if (spawnsRaw === "*") {
+				spawns = "*";
+			} else if (spawnsRaw) {
+				spawns = spawnsRaw
+					.split(",")
+					.map((s) => s.trim())
+					.filter(Boolean);
+				if (spawns.length === 0) spawns = undefined;
+			}
+		}
+
+		// Backward compat: infer spawns: "*" when tools includes "task"
+		if (spawns === undefined && tools?.includes("task")) {
+			spawns = "*";
+		}
+
 		const recursive =
 			frontmatter.recursive === undefined
 				? undefined
@@ -115,6 +135,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentDefinition[]
 			name: frontmatter.name,
 			description: frontmatter.description,
 			tools: tools && tools.length > 0 ? tools : undefined,
+			spawns,
 			model: frontmatter.model,
 			recursive,
 			systemPrompt: body,

package/src/core/tools/task/executor.ts

@@ -19,6 +19,7 @@ import {
 	MAX_OUTPUT_BYTES,
 	MAX_OUTPUT_LINES,
 	OMP_BLOCKED_AGENT_ENV,
+	OMP_SPAWNS_ENV,
 	type SingleResult,
 } from "./types";
 
@@ -193,7 +194,12 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 
 	// Add tools if specified
 	if (agent.tools && agent.tools.length > 0) {
-		args.push("--tools", agent.tools.join(","));
+		let toolList = agent.tools;
+		// Auto-include task tool if spawns defined but task not in tools
+		if (agent.spawns !== undefined && !toolList.includes("task")) {
+			toolList = [...toolList, "task"];
+		}
+		args.push("--tools", toolList.join(","));
 	}
 
 	// Resolve and add model
@@ -220,6 +226,15 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		env[OMP_BLOCKED_AGENT_ENV] = agent.name;
 	}
 
+	// Propagate spawn restrictions to subprocess
+	if (agent.spawns === undefined) {
+		env[OMP_SPAWNS_ENV] = ""; // No spawns = deny all
+	} else if (agent.spawns === "*") {
+		env[OMP_SPAWNS_ENV] = "*";
+	} else {
+		env[OMP_SPAWNS_ENV] = agent.spawns.join(",");
+	}
+
 	// Spawn subprocess
 	const proc = spawn(OMP_CMD, args, {
 		cwd,

package/src/core/tools/task/index.ts

@@ -27,6 +27,7 @@ import {
 	MAX_PARALLEL_TASKS,
 	OMP_BLOCKED_AGENT_ENV,
 	OMP_NO_SUBAGENTS_ENV,
+	OMP_SPAWNS_ENV,
 	type TaskToolDetails,
 	taskSchema,
 } from "./types";
@@ -321,6 +322,30 @@ export function createTaskTool(
 					}
 				}
 
+				// Check spawn restrictions from parent
+				const parentSpawns = process.env[OMP_SPAWNS_ENV];
+				const isSpawnAllowed = (agentName: string): boolean => {
+					if (parentSpawns === undefined) return true; // Root = allow all
+					if (parentSpawns === "") return false; // Empty = deny all
+					if (parentSpawns === "*") return true; // Wildcard = allow all
+					const allowed = new Set(parentSpawns.split(",").map((s) => s.trim()));
+					return allowed.has(agentName);
+				};
+
+				for (const task of tasks) {
+					if (!isSpawnAllowed(task.agent)) {
+						const allowed = parentSpawns === "" ? "none (spawns disabled for this agent)" : parentSpawns;
+						return {
+							content: [{ type: "text", text: `Cannot spawn '${task.agent}'. Allowed: ${allowed}` }],
+							details: {
+								projectAgentsDir,
+								results: [],
+								totalDurationMs: Date.now() - startTime,
+							},
+						};
+					}
+				}
+
 				// Initialize progress for all tasks
 				for (let i = 0; i < tasks.length; i++) {
 					const agentCfg = getAgent(agents, tasks[i].agent);

package/src/core/tools/task/types.ts

@@ -33,6 +33,9 @@ export const OMP_NO_SUBAGENTS_ENV = "OMP_NO_SUBAGENTS";
 /** Environment variable containing blocked agent name (self-recursion prevention) */
 export const OMP_BLOCKED_AGENT_ENV = "OMP_BLOCKED_AGENT";
 
+/** Environment variable containing allowed spawn list (propagated to subprocesses) */
+export const OMP_SPAWNS_ENV = "OMP_SPAWNS";
+
 /** Task tool parameters */
 export const taskSchema = Type.Object({
 	context: Type.Optional(Type.String({ description: "Shared context prepended to all task prompts" })),
@@ -74,6 +77,7 @@ export interface AgentDefinition {
 	description: string;
 	systemPrompt: string;
 	tools?: string[];
+	spawns?: string[] | "*";
 	model?: string;
 	recursive?: boolean;
 	source: AgentSource;

package/src/modes/interactive/interactive-mode.ts

@@ -2414,10 +2414,30 @@ export class InteractiveMode {
 
 		const renderSourceText = (text: string): string => text.replace(/\bvia\b/, theme.italic("via"));
 
-		const truncateText = (text: string, maxLen: number): string => {
-			if (text.length <= maxLen) return text;
-			if (maxLen <= 3) return text.slice(0, Math.max(0, maxLen));
-			return `${text.slice(0, maxLen - 3)}...`;
+		const truncateText = (text: string, maxWidth: number): string => {
+			const textWidth = visibleWidth(text);
+			if (textWidth <= maxWidth) return text;
+			if (maxWidth <= 3) {
+				let acc = "";
+				let width = 0;
+				for (const char of text) {
+					const charWidth = visibleWidth(char);
+					if (width + charWidth > maxWidth) break;
+					width += charWidth;
+					acc += char;
+				}
+				return acc;
+			}
+			const targetWidth = maxWidth - 3;
+			let acc = "";
+			let width = 0;
+			for (const char of text) {
+				const charWidth = visibleWidth(char);
+				if (width + charWidth > targetWidth) break;
+				width += charWidth;
+				acc += char;
+			}
+			return `${acc}...`;
 		};
 
 		// Helper to format a section with consistent column alignment
@@ -2438,26 +2458,28 @@ export class InteractiveMode {
 				return { name, sourceText, nameWithSource, desc };
 			});
 
-			const maxNameWidth = Math.min(60, Math.max(...lineItems.map((line) => line.nameWithSource.length)));
+			const maxNameWidth = Math.min(
+				60,
+				Math.max(...lineItems.map((line) => visibleWidth(line.nameWithSource))),
+			);
 			const formattedLines = lineItems.map((line) => {
 				let nameText = line.name;
 				let sourceText = line.sourceText;
 
 				if (sourceText) {
-					let availableForName = maxNameWidth - sourceText.length - 1;
-					if (availableForName < 1) {
-						sourceText = truncateText(sourceText, Math.max(0, maxNameWidth - 4));
-						availableForName = maxNameWidth - sourceText.length - 1;
-					}
-					nameText = truncateText(nameText, Math.max(1, availableForName));
-				} else {
-					nameText = truncateText(nameText, maxNameWidth);
+					const maxSourceWidth = Math.max(0, maxNameWidth - 2);
+					sourceText = truncateText(sourceText, maxSourceWidth);
 				}
+				const sourceWidth = sourceText ? visibleWidth(sourceText) : 0;
+				const availableForName = sourceText
+					? Math.max(1, maxNameWidth - sourceWidth - 1)
+					: maxNameWidth;
+				nameText = truncateText(nameText, availableForName);
 
 				const nameWithSourcePlain = sourceText ? `${nameText} ${sourceText}` : nameText;
 				const sourceRendered = sourceText ? renderSourceText(sourceText) : "";
 				const nameRendered = sourceText ? `${theme.bold(nameText)} ${sourceRendered}` : theme.bold(nameText);
-				const pad = Math.max(0, maxNameWidth - nameWithSourcePlain.length);
+				const pad = Math.max(0, maxNameWidth - visibleWidth(nameWithSourcePlain));
 				const desc = line.desc?.trim();
 				const descPart = desc ? `  ${theme.fg("dim", desc.slice(0, 50) + (desc.length > 50 ? "..." : ""))}` : "";
 				return `  ${nameRendered}${" ".repeat(pad)}${descPart}`;