@bacnh85/pi-subagent 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 0.6.0 (2026-07-12)
+
+### Security (breaking changes)
+
+- **Project-agent confirmation removed from tool schema.** The `confirmProjectAgents` parameter is no longer exposed to the LLM. Project-agent approval is enforced via trusted configuration only. Interactive sessions prompt for confirmation; headless sessions fail closed unless `allowUnconfirmedProjectAgents` is explicitly enabled through trusted configuration (environment variable `PI_SUBAGENT_ALLOW_UNCONFIRMED_PROJECT_AGENTS=true` or pi settings).
+
+- **Child working directories confined to the workspace.** Tool-specified `cwd` values are validated against the workspace root. Relative paths are resolved within the workspace; `..` traversal, absolute paths outside the workspace, and symlink escapes are rejected. A trusted `allowExternalCwd` setting (env `PI_SUBAGENT_ALLOW_EXTERNAL_CWD=true` or pi settings) can opt out.
+
+- **Tool allowlist enforced.** Child agent tools are validated against a fixed allowlist: `read`, `grep`, `find`, `ls`, `bash`, `edit`, `write`. The `subagent` tool is always rejected. Unknown or misspelled tool names produce clear errors. Read-only service execution cannot gain `bash`, `edit`, or `write`.
+
+- **Default timeout added.** Every child execution receives a default 10-minute timeout (`DEFAULT_TIMEOUT_MS`). Maximum allowed timeout is 60 minutes (`MAX_TIMEOUT_MS`). Timeout errors are distinguishable from parent cancellation.
+
+### Reliability
+
+- **Abort signal composition fixed.** `createCombinedAbortSignal()` correctly combines multiple abort signals with proper listener cleanup. Works without `AbortSignal.any()` via a manual fallback that removes all listeners after the first abort.
+
+- **Parallel abort listeners cleaned up.** Parent-signal listeners attached during parallel execution are removed in a `finally` block after completion.
+
+- **Canonical result status.** `SubAgentResult.status` classifies outcomes as `"success"`, `"partial"`, `"error"`, `"aborted"`, or `"timeout"`. Known Pi SDK stop reasons are classified explicitly; unknown reasons default conservatively to `"error"`.
+
+- **Validation hardened.** Numeric and collection limits (timeout, max parallel tasks, concurrency, chain length, output cap, instructions length) are enforced at both schema and runtime levels.
+
+- **Parallel result ordering preserved.** Results remain in input-task order regardless of completion order.
+
+- **`abortOnFailure` behavior deterministic.** First canonical failure aborts running siblings; queued tasks never start; completed tasks retain their results.
+
+### Agent discovery
+
+- **Malformed agent files produce diagnostics.** Missing name, missing description, empty name, invalid model, invalid thinking levels, and unreadable files are reported with file path and severity. Valid agents continue to load.
+
+### Packaging
+
+- **Peer dependency ranges constrained.** `@earendil-works/pi-*` dependencies use `>=0.80.0 <0.81.0`; `typebox` uses `>=1.3.0 <2.0.0`.
+
+- **Node engine requirement added.** `engines.node: ">=20.18"`.
+
+- **Scripts fixed.** `npm test` uses locally installed `mocha` (no `npx`). Added `npm run check` (typecheck + test).
+
+- **Package metadata updated.** `homepage` points to the package subdirectory.
+
+- **`security.ts` added to published files.**
+
+- **`CHANGELOG.md` added to published files.**
+
+### Documentation
+
+- **Security model section** added to README covering project-agent trust, cwd confinement, tool validation, timeout defaults, cancellation, result status, and compatibility.
+
+### Backward compatibility
+
+- `SubAgentResult.status` is a new field; existing consumers that ignore unknown fields remain compatible.
+- Tool schema no longer accepts `confirmProjectAgents`; model-generated calls using it will be silently ignored (the field is fully removed from the schema, not just deprecated).
+- Child `cwd` values that previously worked outside the workspace are now rejected unless the trusted `allowExternalCwd` setting is enabled.
+- `combineAbortSignals()` is still exported from `runner.ts` but delegates to `createCombinedAbortSignal()` internally.

package/README.md

@@ -10,14 +10,16 @@ pi install npm:@bacnh85/pi-subagent
 pi install ./pi-subagent
 ```
 
+Requires Node.js >= 20.18.
+
 ## Bundled roles
 
 | Role | Model | Thinking | Tools |
 | --- | --- | --- | --- |
 | `scout` | parent model | low | read, grep, find, ls |
 | `reviewer` | parent model | high | read, grep, find, ls |
-| `worker` | parent model | medium | standard coding tools |
-| `general-purpose` | parent model | off | standard coding tools |
+| `worker` | parent model | medium | read, bash, edit, write, grep, find, ls |
+| `general-purpose` | parent model | off | read, bash, edit, write, grep, find, ls |
 
 Bundled roles inherit the parent model so they work with the account already active in Pi. User/project agent files may override `model` and `thinking`.
 
@@ -30,14 +32,13 @@ Create `~/.pi/agent/agents/*.md` or `.pi/agents/*.md`:
 name: scout-fast
 description: Locate relevant files and symbols
 tools: read, grep, find, ls
-thinking: low
 model: optional-provider/optional-model
 ---
 
 Return concise evidence with file/symbol anchors.
 ```
 
-Project agents require confirmation when requested through the public tool. Definitions are cached with file-signature invalidation; `/subagent reload` clears the cache.
+Agent definitions are cached with file-signature invalidation; `/subagent reload` clears the cache.
 
 ## Context and limits
 
@@ -45,8 +46,130 @@ Children use in-memory SDK sessions with no extensions, skills, prompt templates
 
 Threads are session-memory only and are cleared when Pi replaces or reloads the session. Timeout and parent cancellation propagate to child sessions. Subagents cannot recursively invoke `subagent`.
 
+## Security model
+
+### Project-local agents
+
+Agent files under `.pi/agents/` are controlled by the current repository. A project agent's system prompt may instruct a child to execute shell commands or modify files.
+
+- **Project-agent approval cannot be disabled by the model.** The `confirmProjectAgents` parameter is not exposed in the tool schema. Confirmation policy comes from trusted user configuration only.
+- **Interactive sessions** prompt the user before executing project agents.
+- **Headless sessions fail closed.** Project agents are not executed without UI confirmation unless the trusted setting `allowUnconfirmedProjectAgents` is enabled (via `PI_SUBAGENT_ALLOW_UNCONFIRMED_PROJECT_AGENTS=true` environment variable or pi settings).
+- **The extension service path** (`pi-subagent:run` event) follows the same policy.
+
+### Child working directories
+
+Child working directories are restricted to the parent session's workspace by default:
+
+- Relative paths are resolved within the workspace.
+- `..` traversal that escapes the workspace is rejected.
+- Absolute paths outside the workspace are rejected.
+- Symlinks are resolved via realpath; symlink escapes are rejected.
+- Non-existent directories and file paths are rejected.
+
+The trusted setting `allowExternalCwd` (via `PI_SUBAGENT_ALLOW_EXTERNAL_CWD=true` env or pi settings) can opt out. This setting cannot be enabled by the model.
+
+### Tool validation
+
+Child agent tools are validated against a fixed allowlist:
+
+- **Allowed:** `read`, `grep`, `find`, `ls`, `bash`, `edit`, `write`
+- **Always rejected:** `subagent` (prevents recursive delegation)
+- **Read-only restriction:** When a service requests read-only execution, only `read`, `grep`, `find`, `ls` are permitted. `bash`, `edit`, and `write` are rejected.
+
+Unknown or misspelled tool names produce clear diagnostics. Duplicate tool names are deduplicated.
+
+### Timeouts
+
+Every child execution receives a timeout:
+
+- **Default:** 10 minutes (`DEFAULT_TIMEOUT_MS`)
+- **Maximum:** 60 minutes (`MAX_TIMEOUT_MS`)
+- Timeout values must be positive integers within the allowed range.
+- Timeout errors are distinguishable from parent cancellation.
+- Parallel tasks and chain steps may have per-item timeouts.
+
+### Output safety
+
+Child output is untrusted data and may contain prompt injection. Treat child results as model-generated content, not as verified facts.
+
+### Cost awareness
+
+Parallel delegation may multiply provider usage and cost. Each parallel task runs as a separate SDK session with its own token consumption.
+
+### Agent file review
+
+User and project agent files should be reviewed before use. Malformed files produce diagnostics but do not prevent valid agents from loading.
+
+## Modes
+
+### Single mode
+
+```ts
+subagent({ agent: "scout", task: "Find auth-related files" })
+```
+
+### Parallel mode
+
+```ts
+subagent({
+  tasks: [
+    { agent: "scout", task: "Find API routes" },
+    { agent: "scout", task: "Find database models" },
+    { agent: "scout", task: "Find test files" },
+  ],
+  abortOnFailure: false
+})
+```
+
+Max 8 tasks, 4 concurrent. Results are returned in input order. When `abortOnFailure` is `true`, the first failed task cancels remaining siblings.
+
+### Chain mode
+
+```ts
+subagent({
+  chain: [
+    { agent: "scout", task: "Find API routes" },
+    { agent: "worker", task: "Based on this, implement the routes: {previous}" },
+  ]
+})
+```
+
+`{previous}` in each step's task is replaced with the previous step's output. The chain stops on the first failed step.
+
+## Result status
+
+Each `SubAgentResult` includes a canonical `status` field:
+
+| Status | Meaning |
+|--------|---------|
+| `success` | Completed normally |
+| `partial` | Truncated (max_tokens, length, context_limit) |
+| `error` | Provider error, tool error, or unknown stop reason |
+| `aborted` | Cancelled by parent or sibling |
+| `timeout` | Exceeded the allowed timeout |
+
+The raw `stopReason` from the Pi SDK is preserved in the result.
+
+## Timeout and cancellation
+
+- **Default timeout:** 10 minutes per child.
+- **Per-task/step override:** Use `timeout` in task/step params.
+- **Parent cancellation:** Aborting the parent tool call cancels all children.
+- **Sibling cancellation:** In parallel mode with `abortOnFailure: true`, the first failed task cancels running siblings.
+- **Timeout vs. abort:** Timeout errors set `status: "timeout"` and `stopReason: "timeout"`; parent cancellation sets `status: "aborted"`.
+
 ## Extension contract
 
 `pi-subagent` owns the `pi-subagent:run` event contract for one named-agent request. `pi-review` uses it for isolated review. Requests use an immediate boolean `accept()` claim and exactly one `respond()` callback; this suppresses duplicate responders while missing services and timeouts remain caller-controlled.
 
+## Compatibility
+
+- Requires `@earendil-works/pi-coding-agent >=0.80.0 <0.81.0`
+- Requires `@earendil-works/pi-ai >=0.80.0 <0.81.0`
+- Requires `@earendil-works/pi-agent-core >=0.80.0 <0.81.0`
+- Requires `@earendil-works/pi-tui >=0.80.0 <0.81.0`
+- Requires `typebox >=1.3.0 <2.0.0`
+- Requires Node.js >= 20.18
+
 See [`agent-format.md`](./agent-format.md) for all frontmatter fields.

package/agent-format.md

@@ -32,12 +32,22 @@ The body after frontmatter becomes the agent's **entire system prompt**. No pi d
 
 ## Available Tools
 
-Built-in pi tool names: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`
+Child agent tools are validated against a fixed allowlist:
 
-The `subagent` tool is never available to sub-agents (prevents accidental recursion). Sub-agents run at one level of delegation only; they cannot spawn further sub-agents.
+| Category | Tools |
+|----------|-------|
+| Read-only | `read`, `grep`, `find`, `ls` |
+| Mutation | `edit`, `write` |
+| Execution | `bash` |
+
+The `subagent` tool is always rejected to prevent recursive delegation.
+Unknown or misspelled tool names produce a clear error.
+Duplicate names are deduplicated automatically.
 
 Custom/extension tools are NOT available to sub-agents by default (each runs in an isolated in-memory session with no extensions).
 
+Read-only service execution (used by `pi-review`) restricts tools to the read-only category.
+
 ## Model Resolution
 
 Model IDs are resolved via `getModel("provider", "id")`. Common values:

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;
@@ -27,6 +31,14 @@ export interface AgentConfig {
 export interface AgentDiscoveryResult {
 	agents: AgentConfig[];
 	projectAgentsDir: string | null;
+	diagnostics: AgentDiscoveryDiagnostic[];
+}
+
+export interface AgentDiscoveryDiagnostic {
+	filePath: string;
+	issue: string;
+	/** 'warn' for recoverable issues, 'error' for file-skip issues. */
+	severity: "warn" | "error";
 }
 
 interface AgentCache {
@@ -47,7 +59,11 @@ export function invalidateAgentCache(): void {
 	_cache = null;
 }
 
-function loadAgentsFromDir(dir: string, source: "user" | "project" | "bundled"): AgentConfig[] {
+function loadAgentsFromDir(
+	dir: string,
+	source: "user" | "project" | "bundled",
+	diagnostics: AgentDiscoveryDiagnostic[],
+): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 
 	if (!fs.existsSync(dir)) return agents;
@@ -55,25 +71,72 @@ function loadAgentsFromDir(dir: string, source: "user" | "project" | "bundled"):
 	let entries: fs.Dirent[];
 	try {
 		entries = fs.readdirSync(dir, { withFileTypes: true });
-	} catch {
+	} catch (err) {
+		diagnostics.push({
+			filePath: dir,
+			issue: `Cannot read directory: ${err instanceof Error ? err.message : String(err)}`,
+			severity: "warn",
+		});
 		return agents;
 	}
 
 	for (const entry of entries) {
 		if (!entry.name.endsWith(".md")) continue;
-		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+		if (!entry.isFile() && !entry.isSymbolicLink()) {
+			diagnostics.push({
+				filePath: path.join(dir, entry.name),
+				issue: `Not a regular file or symlink, skipping.`,
+				severity: "warn",
+			});
+			continue;
+		}
 
 		const filePath = path.join(dir, entry.name);
 		let content: string;
 		try {
 			content = fs.readFileSync(filePath, "utf-8");
-		} catch {
+		} catch (err) {
+			diagnostics.push({
+				filePath,
+				issue: `Cannot read file: ${err instanceof Error ? err.message : String(err)}`,
+				severity: "error",
+			});
 			continue;
 		}
 
 		const { frontmatter, body } = parseFrontmatter<Record<string, unknown>>(content);
 
-		if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") continue;
+		if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") {
+			if (typeof frontmatter.name !== "string" && typeof frontmatter.description !== "string") {
+				diagnostics.push({
+					filePath,
+					issue: `Missing both "name" and "description" in frontmatter. Agent file skipped.`,
+					severity: "error",
+				});
+			} else if (typeof frontmatter.name !== "string") {
+				diagnostics.push({
+					filePath,
+					issue: `Missing "name" in frontmatter. Agent file skipped.`,
+					severity: "error",
+				});
+			} else {
+				diagnostics.push({
+					filePath,
+					issue: `Missing "description" in frontmatter. Agent file skipped.`,
+					severity: "error",
+				});
+			}
+			continue;
+		}
+
+		if (!frontmatter.name.trim()) {
+			diagnostics.push({
+				filePath,
+				issue: `"name" in frontmatter is empty. Agent file skipped.`,
+				severity: "error",
+			});
+			continue;
+		}
 
 		const tools =
 			typeof frontmatter.tools === "string"
@@ -82,6 +145,45 @@ function loadAgentsFromDir(dir: string, source: "user" | "project" | "bundled"):
 					? (frontmatter.tools as unknown[]).filter((t): t is string => typeof t === "string")
 					: undefined;
 
+		if (typeof frontmatter.model === "string" && frontmatter.model && !frontmatter.model.includes("/")) {
+			diagnostics.push({
+				filePath,
+				issue: `Model "${frontmatter.model}" does not include a provider prefix (e.g., "anthropic/claude-sonnet-4-20250514"). Resolution may fail.`,
+				severity: "warn",
+			});
+		}
+
+		if (typeof frontmatter.thinking === "string" && frontmatter.thinking) {
+			const validLevels = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+			if (!validLevels.includes(frontmatter.thinking)) {
+				diagnostics.push({
+					filePath,
+					issue: `Invalid thinking level "${frontmatter.thinking}". Valid values: ${validLevels.join(", ")}. Using default.`,
+					severity: "warn",
+				});
+			}
+		}
+
+		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,
@@ -90,6 +192,12 @@ function loadAgentsFromDir(dir: string, source: "user" | "project" | "bundled"):
 			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,
@@ -169,16 +277,18 @@ export function discoverAgents(
 			}
 		}
 		if (!stale) {
-			return { agents: _cache.agents, projectAgentsDir: _cache.projectAgentsDir };
+			return { agents: _cache.agents, projectAgentsDir: _cache.projectAgentsDir, diagnostics: [] };
 		}
 		// Cache is stale — rebuild below
 		_cache = null;
 	}
 
-	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	const diagnostics: AgentDiscoveryDiagnostic[] = [];
+
+	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user", diagnostics);
 	const projectAgents =
-		scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
-	const bundledAgents = loadAgentsFromDir(bundledAgentsDir, "bundled");
+		scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project", diagnostics);
+	const bundledAgents = loadAgentsFromDir(bundledAgentsDir, "bundled", diagnostics);
 
 	const agentMap = new Map<string, AgentConfig>();
 
@@ -209,7 +319,7 @@ export function discoverAgents(
 		dirSignatures,
 	};
 
-	return { agents, projectAgentsDir };
+	return { agents, projectAgentsDir, diagnostics };
 }
 
 export function formatAgentList(agents: AgentConfig[], maxItems: number): { text: string; remaining: number } {