oira666_pi-subagent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Jakl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,327 @@
+# Pi Subagent
+
+**Delegate tasks to specialized subagents with configurable context modes (`spawn` / `fork`).**
+
+There are many subagent extensions for pi, this one is mine.
+
+## Why Pi Subagent
+
+**Specialization** — Use tailored agents for specific tasks like refactoring, documentation, or research.
+
+**Context Control** — Choose `spawn` (fresh context) or `fork` (inherit current session context), depending on the task.
+
+**Parallel Execution** — Run multiple agents at once.
+
+**A Simpler Fork** — This extension intentionally keeps the surface area small and predictable compared to heavier implementations. It supports nested delegation with depth/cycle guards, but avoids broader scope-selection complexity. If you want the minimal, “just delegate” experience, this is it.
+
+## Install
+
+### Option 1: Install from npm (recommended)
+
+```bash
+pi install npm:@mjakl/pi-subagent
+```
+
+### Option 2: Install via git
+
+```bash
+pi install git:github.com/mjakl/pi-subagent
+```
+
+### Option 3: Manual Installation
+
+Clone this repository to your Pi extensions directory:
+
+```bash
+cd ~/.pi/agent/extensions
+git clone https://github.com/mjakl/pi-subagent.git
+cd pi-subagent
+npm install
+```
+
+## Configuration
+
+### Delegation Guards (Depth + Cycle Prevention)
+
+By default, this extension enforces two runtime guards:
+
+1. **Depth guard** (`--subagent-max-depth`, default `3`)
+   - Main agent starts at depth `0`
+   - Delegation is allowed while `currentDepth < maxDepth`
+   - With default depth `3`: depth `0`, `1`, and `2` can delegate; depth `3` cannot
+2. **Cycle guard** (`--subagent-prevent-cycles`, default `true`)
+   - Blocks delegating to any agent name already present in the current delegation stack
+   - Prevents self-recursion (`writer -> writer`) and loops (`planner -> reviewer -> planner`)
+
+You can configure depth with either:
+
+- CLI flag: `--subagent-max-depth <n>`
+- Environment variable: `PI_SUBAGENT_MAX_DEPTH=<n>`
+
+`n` must be a non-negative integer.
+
+You can configure cycle prevention with either:
+
+- CLI flag: `--subagent-prevent-cycles` / `--no-subagent-prevent-cycles`
+- Environment variable: `PI_SUBAGENT_PREVENT_CYCLES=true|false`
+
+Internal env vars managed by the extension and propagated to child processes:
+
+- `PI_SUBAGENT_DEPTH`
+- `PI_SUBAGENT_MAX_DEPTH`
+- `PI_SUBAGENT_STACK` (JSON array of ancestor agent names, e.g. `["scout","planner"]`)
+- `PI_SUBAGENT_PREVENT_CYCLES`
+
+Examples:
+
+```bash
+# Default behavior: depth 3 + cycle prevention enabled
+pi
+
+# Restrict to one nested level (main -> child -> grandchild)
+pi --subagent-max-depth 2
+
+# Disable subagent delegation entirely
+pi --subagent-max-depth 0
+
+# Allow depth 3 but disable cycle prevention (not recommended)
+pi --subagent-max-depth 3 --no-subagent-prevent-cycles
+```
+
+### Tool Call Shape
+
+`subagent` always accepts a top-level `tasks` array:
+
+- One task = single-agent delegation
+- Multiple tasks = parallel delegation
+
+Single-task example:
+
+```json
+{ "tasks": [{ "agent": "code-writer", "task": "Implement the API change" }], "mode": "spawn" }
+```
+
+Multi-task example:
+
+```json
+{ "tasks": [{ "agent": "code-writer", "task": "Draft the implementation" }, { "agent": "code-reviwer", "task": "Review the plan" }], "mode": "fork" }
+```
+
+Each task item supports:
+
+- `agent` — subagent name
+- `task` — delegated task text
+- `cwd` — optional working directory override for that task
+
+### Parallel Execution Limits
+
+For multi-task calls, two environment variables control fan-out:
+
+- `PI_SUBAGENT_MAX_PARALLEL_TASKS` — maximum number of tasks allowed in one call (default: `16`)
+- `PI_SUBAGENT_MAX_CONCURRENCY` — maximum number of subagents running at the same time inside that call (default: `8`)
+
+`PI_SUBAGENT_MAX_CONCURRENCY` is effectively clamped to at least `1`.
+
+### Project-local Agent Confirmation
+
+Project-local agents from `.pi/agents/*.md` can be gated by `PI_SUBAGENT_CONFIRM_PROJECT_AGENTS`:
+
+- `true`, `ask`, or `once` (default) — prompt with **Yes once**, **Yes for this session**, or **No**
+- `false` or `never` — skip the prompt and allow project-local agents immediately
+- `session` — allow project-local agents for the rest of the current session without prompting
+
+If you choose **Yes for this session** in the UI, the choice is remembered and you will not be asked again in that session. In non-UI mode, `ask` blocks execution because the extension cannot prompt.
+
+### Context Mode (`spawn` vs `fork`)
+
+`subagent` supports a top-level `mode` switch:
+
+- `spawn` (default) — Child receives only the task string (`Task: ...`). Best for isolated, reproducible work; typically lower token/cost and less context leakage.
+- `fork` — Child receives a forked snapshot of the current session context **plus** the task string. Best for follow-up work that depends on prior context; typically higher token/cost and may include sensitive context.
+
+Quick rule of thumb:
+
+- Start with `spawn` for one-off tasks.
+- Use `fork` when the delegated task depends on the current session's prior discussion, reads, or decisions.
+
+Examples:
+
+```json
+{ "tasks": [{ "agent": "code-writer", "task": "Implement the migration" }], "mode": "spawn" }
+```
+
+```json
+{ "tasks": [{ "agent": "code-reviwer", "task": "Double-check this migration" }], "mode": "fork" }
+```
+
+If omitted, mode defaults to `spawn`.
+
+### Subagent Definitions
+
+Subagents are defined as Markdown files with YAML frontmatter.
+
+**User Agents:** `~/.pi/agent/agents/*.md`
+**Project Agents:** `.pi/agents/*.md`
+**Bundled Fallback Agents:** `agents/code-writer.md`, `agents/code-reviwer.md`, `agents/code-architect.md`
+
+The extension always loads user and project agents first. If a project agent shares a name with a user agent, the project agent wins. The bundled fallback agents are only discovered when no user or project agents are found at all. If you have any user or project agents configured, the bundled defaults are hidden and not discoverable. When project agents are requested, Pi can prompt for confirmation before running them, depending on `PI_SUBAGENT_CONFIRM_PROJECT_AGENTS`.
+
+If nothing is configured yet, these fallback agents are available by default:
+
+- `code-writer` — implementation and refactoring
+- `code-reviwer` — code review and risk finding
+- `code-architect` — technical design and approach selection
+
+Example agent (`~/.pi/agent/agents/writer.md`):
+
+```markdown
+---
+name: writer
+description: Expert technical writer and editor
+model: anthropic/claude-3-5-sonnet
+tools: read, write
+---
+
+You are an expert technical writer. Your task is to improve the clarity and conciseness of the provided text.
+```
+
+Note: this repository includes bundled fallback agents in `agents/code-writer.md`, `agents/code-reviwer.md`, and `agents/code-architect.md`.
+
+### Frontmatter Fields
+
+| Field         | Required | Default                          | Description                                                                                                                                                                |
+| ------------- | -------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`        | Yes      | —                                | Agent identifier used in tool calls (must match exactly)                                                                                                                   |
+| `description` | Yes      | —                                | What the agent does (shown to the main agent)                                                                                                                              |
+| `model`       | No       | Uses the default pi model        | Overrides the model for this agent. You can include a provider prefix (e.g. `anthropic/claude-3-5-sonnet` or `openrouter/claude-3.5-sonnet`) to force a specific provider. |
+| `thinking`    | No       | Uses Pi's default thinking level | Sets the thinking level (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`). Equivalent to `--thinking`.                                                                  |
+| `tools`       | No       | `read,bash,edit,write`           | Comma-separated list of **built-in** tools to enable for this agent. If omitted, defaults apply.                                                                           |
+
+Notes:
+
+- `model` accepts `provider/model` syntax — this is a Pi feature. Use it when multiple providers offer the same model ID.
+- `thinking` uses the same values as Pi's `--thinking` flag; it's recommended to set it explicitly since thinking support varies by model.
+- `tools` only controls built-in tools. Extension tools remain available unless extensions are disabled.
+- The Markdown body below the frontmatter becomes the agent's system prompt and is **appended** to Pi's default system prompt (it does **not** replace it).
+
+### Writing a Good Agent File
+
+- **Description matters** — the main agent uses the `description` to decide which subagent to call, so be specific about what the agent is good at.
+- **Tool scope is optional but helpful** — reducing tools can keep the agent focused, but you can leave defaults if unsure.
+- **Model + thinking is the power combo** — selecting the right model and thinking level is often the biggest quality boost.
+
+### Available Built-in Tools
+
+Available Tools (default: `read`, `bash`, `edit`, `write`):
+
+- `read` — Read file contents
+- `bash` — Execute bash commands
+- `edit` — Edit files with find/replace
+- `write` — Write files (creates/overwrites)
+- `grep` — Search file contents (read-only, off by default)
+- `find` — Find files by glob pattern (read-only, off by default)
+- `ls` — List directory contents (read-only, off by default)
+
+Tip: for a read-only tool selection, use `read,find,ls,grep`. As soon as you include `edit`, `write`, or `bash`, the agent can practically go wild.
+
+## How Communication Works
+
+### The Isolation Model
+
+Each subagent always runs in a **separate `pi` process**:
+
+- ❌ No shared memory/state with the parent process
+- ❌ No visibility into sibling subagents
+- ✅ Its own model/tool/runtime loop
+- ✅ Started with `PI_OFFLINE=1` to skip startup network operations and reduce spawn latency
+
+What it can see depends on `mode`:
+
+- `spawn` (default)
+  - ✅ Receives: subagent system prompt + `Task: ...`
+  - ❌ Does **not** receive parent session history
+- `fork`
+  - ✅ Receives: forked snapshot of current parent session context + `Task: ...`
+
+### What Gets Sent to Subagents
+
+#### `spawn` mode (default)
+
+`subagent({ tasks: [{ agent: "writer", task: "Document the API" }] })` sends:
+
+```
+[System Prompt from ~/.pi/agent/agents/writer.md]
+
+User: Task: Document the API
+```
+
+No parent conversation history is included. In `spawn`, include all required context in `task`.
+
+#### `fork` mode
+
+`subagent({ tasks: [{ agent: "writer", task: "Document the API" }], mode: "fork" })` sends:
+
+```
+[Forked snapshot of current session context]
+[System Prompt from ~/.pi/agent/agents/writer.md]
+
+User: Task: Document the API
+```
+
+Note: `fork` copies session context, not transient runtime-only prompt mutations from the parent process.
+
+### What Comes Back to the Main Agent
+
+| Data                        | Main Agent Sees          | TUI Shows              |
+| --------------------------- | ------------------------ | ---------------------- |
+| Final text output           | ✅ Yes — full, unbounded | ✅ Yes                 |
+| Tool calls made by subagent | ❌ No                    | ✅ Yes (expanded view) |
+| Token usage / cost          | ❌ No                    | ✅ Yes                 |
+| Reasoning/thinking steps    | ❌ No                    | ❌ No                  |
+| Error messages              | ✅ Yes (on failure)      | ✅ Yes                 |
+
+**Key point:** The main agent receives **only the final assistant text** from each subagent. Not the tool calls, not the reasoning, not the intermediate steps. This prevents context pollution while still giving you the results.
+
+### Parallel Mode Behavior
+
+When running multiple agents in parallel:
+
+- Subagents run concurrently up to `PI_SUBAGENT_MAX_CONCURRENCY` (default `8`)
+- The top-level `mode` applies to all tasks in that call
+- Main agent receives a combined result after all finish:
+
+```
+Parallel: 3/3 succeeded
+
+[writer] completed: Full output text here...
+[tester] completed: Full output text here...
+[reviewer] completed: Full output text here...
+```
+
+## Features
+
+- **Auto-Discovery** — Agents are found at startup and their descriptions are injected into the main agent's system prompt.
+- **Context Mode Switch** — `spawn` (fresh context) and `fork` (session snapshot + task) per call.
+- **Depth + Cycle Guards** — Depth limiting and ancestry-cycle checks prevent runaway recursive delegation by default.
+- **Streaming Updates** — Watch subagent progress in real-time as tool calls and outputs stream in.
+- **Nested Delegation** — Subagents can call `subagent` again, subject to depth and cycle guards.
+- **Rich TUI Rendering** — Collapsed/expanded views with usage stats, nested delegation trees, tool call previews, and markdown output.
+- **Security Confirmation** — Project-local agents can require explicit user approval, with one-time and session-wide approval options.
+
+## Project Structure
+
+```
+index.ts    — Extension entry point: lifecycle hooks, tool registration, mode orchestration
+agents.ts   — Agent discovery: reads and parses .md files from user/project directories
+runner.ts   — Process runner: starts `pi` subprocesses in spawn/fork context modes and streams JSON events
+render.ts   — TUI rendering: renderCall and renderResult for the subagent tool
+types.ts    — Shared types and pure helper functions
+```
+
+## Attribution
+
+Inspired by implementations from [vaayne/agent-kit](https://github.com/vaayne/agent-kit) and [mariozechner/pi-mono](https://github.com/badlogic/pi-mono).
+
+## License
+
+MIT

package/agents/code-architect.md

@@ -0,0 +1,24 @@
+---
+name: code-architect
+description: Technical design agent for shaping implementations, APIs, module boundaries, and tradeoffs before coding. Use this agent for plans and architecture decisions.
+thinking: high
+tools: read,bash,grep,find,ls
+---
+
+You are a senior software architect focused on practical design.
+
+Your job is to propose implementation approaches that balance simplicity,
+maintainability, extensibility, and delivery speed.
+
+Guidelines:
+- Start from the current codebase and constraints, not an idealized rewrite.
+- Prefer simple designs with clear ownership and minimal moving parts.
+- Call out tradeoffs, risks, migration concerns, and compatibility implications.
+- Recommend concrete module boundaries, data flow, and rollout steps when useful.
+- Avoid unnecessary abstraction.
+
+In your final response:
+- Present the recommended approach first.
+- Include 1-2 viable alternatives when relevant.
+- Explain why the recommendation fits this codebase.
+- Highlight the biggest implementation risks or unknowns.

package/agents/code-reviwer.md

@@ -0,0 +1,23 @@
+---
+name: code-reviwer
+description: Code review specialist for finding bugs, regressions, edge cases, and maintainability issues. Use this agent to review code, plans, or patches.
+thinking: high
+tools: read,bash,grep,find,ls
+---
+
+You are a skeptical, detail-oriented code reviewer.
+
+Your goal is to identify the most important correctness, reliability, security,
+and maintainability issues in the provided code or plan.
+
+Guidelines:
+- Prioritize concrete issues over stylistic preferences.
+- Look for broken assumptions, missing edge-case handling, risky changes, and test gaps.
+- Prefer concise findings with clear reasoning and likely impact.
+- If the code looks good, say so explicitly instead of inventing problems.
+- Do not edit files; focus on analysis and recommendations.
+
+In your final response:
+- List findings ordered by severity.
+- Include file paths or symbols when possible.
+- If there are no meaningful issues, say "No significant issues found" and mention any residual risks briefly.

package/agents/code-writer.md

@@ -0,0 +1,18 @@
+---
+name: code-writer
+description: Focused implementation agent for writing and refactoring code with small, reliable diffs. Use this agent when you want code changes made directly.
+thinking: medium
+tools: read,bash,edit,write
+---
+
+You are a pragmatic software engineer focused on implementation.
+
+Your job is to turn requirements into small, correct code changes.
+
+Guidelines:
+- Read the relevant files before editing.
+- Prefer minimal diffs that fit the existing style and architecture.
+- Preserve working behavior unless the task explicitly changes it.
+- When details are ambiguous, choose the simplest reasonable implementation and state your assumption.
+- If helpful, run targeted commands to inspect the codebase or validate your changes.
+- In your final response, summarize what you changed, note any assumptions, and mention any validation you performed.

package/agents.ts

@@ -0,0 +1,185 @@
+/**
+ * Agent discovery and configuration.
+ *
+ * Agents are Markdown files with YAML frontmatter that define name, description,
+ * optional model/tools, and a system prompt body.
+ *
+ * Lookup locations:
+ *   - User agents:    ~/.pi/agent/agents/*.md
+ *   - Project agents: .pi/agents/*.md  (walks up from cwd)
+ *   - Bundled agents: ./agents/*.md    (fallback only when no user/project agents exist)
+ */
+
+import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type AgentScope = "user" | "project" | "both";
+export type AgentSource = "user" | "project" | "builtin";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	thinking?: string;
+	systemPrompt: string;
+	source: AgentSource;
+	filePath: string;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+const BUNDLED_AGENTS_DIR = path.join(
+	path.dirname(fileURLToPath(import.meta.url)),
+	"agents",
+);
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/** Walk up from `cwd` looking for a `.pi/agents` directory. */
+function findNearestProjectAgentsDir(cwd: string): string | null {
+	let dir = cwd;
+	while (true) {
+		const candidate = path.join(dir, ".pi", "agents");
+		if (isDirectory(candidate)) return candidate;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+/** Parse a single agent markdown file into an AgentConfig. Returns null on skip. */
+function parseAgentFile(filePath: string, source: AgentSource): AgentConfig | null {
+	let content: string;
+	try {
+		content = fs.readFileSync(filePath, "utf-8");
+	} catch {
+		return null;
+	}
+
+	let parsed: { frontmatter: Record<string, unknown>; body: string };
+	try {
+		parsed = parseFrontmatter<Record<string, unknown>>(content);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		console.warn(`[pi-subagent] Skipping invalid agent file "${filePath}": ${message}`);
+		return null;
+	}
+
+	const frontmatter = parsed.frontmatter ?? {};
+	const body = parsed.body ?? "";
+
+	const name = typeof frontmatter.name === "string" ? frontmatter.name.trim() : "";
+	const description = typeof frontmatter.description === "string" ? frontmatter.description.trim() : "";
+	if (!name || !description) return null;
+
+	let tools: string[] | undefined;
+	if (typeof frontmatter.tools === "string") {
+		const parsedTools = frontmatter.tools
+			.split(",")
+			.map((t) => t.trim())
+			.filter(Boolean);
+		if (parsedTools.length > 0) tools = parsedTools;
+	} else if (Array.isArray(frontmatter.tools)) {
+		const parsedTools = frontmatter.tools
+			.filter((t): t is string => typeof t === "string")
+			.map((t) => t.trim())
+			.filter(Boolean);
+		if (parsedTools.length > 0) tools = parsedTools;
+	} else if (frontmatter.tools !== undefined) {
+		console.warn(
+			`[pi-subagent] Ignoring invalid tools field in "${filePath}". Expected a comma-separated string or string array.`,
+		);
+	}
+
+	return {
+		name,
+		description,
+		tools,
+		model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
+		thinking: typeof frontmatter.thinking === "string" ? frontmatter.thinking : undefined,
+		systemPrompt: body,
+		source,
+		filePath,
+	};
+}
+
+/** Load all agent definitions from a directory. */
+function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
+	if (!fs.existsSync(dir)) return [];
+
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+
+	entries.sort((a, b) => a.name.localeCompare(b.name));
+
+	const agents: AgentConfig[] = [];
+	for (const entry of entries) {
+		if (!entry.name.endsWith(".md")) continue;
+		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+		const agent = parseAgentFile(path.join(dir, entry.name), source);
+		if (agent) agents.push(agent);
+	}
+	return agents;
+}
+
+function dedupeAgents(
+	userAgents: AgentConfig[],
+	projectAgents: AgentConfig[],
+): AgentConfig[] {
+	const agentMap = new Map<string, AgentConfig>();
+	for (const agent of userAgents) agentMap.set(agent.name, agent);
+	for (const agent of projectAgents) agentMap.set(agent.name, agent);
+	return Array.from(agentMap.values());
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Discover all available agents according to the requested scope.
+ *
+ * When scope is "both", project agents override user agents with the same name.
+ * If no user or project agents exist at all, bundled fallback agents are returned.
+ */
+export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
+	const userDir = path.join(os.homedir(), ".pi", "agent", "agents");
+	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+
+	const userAgents = loadAgentsFromDir(userDir, "user");
+	const projectAgents = projectAgentsDir ? loadAgentsFromDir(projectAgentsDir, "project") : [];
+
+	const hasConfiguredAgents = userAgents.length > 0 || projectAgents.length > 0;
+	if (!hasConfiguredAgents) {
+		return {
+			agents: loadAgentsFromDir(BUNDLED_AGENTS_DIR, "builtin"),
+			projectAgentsDir,
+		};
+	}
+
+	if (scope === "user") return { agents: userAgents, projectAgentsDir };
+	if (scope === "project") return { agents: projectAgents, projectAgentsDir };
+	return { agents: dedupeAgents(userAgents, projectAgents), projectAgentsDir };
+}