@ryan_nookpi/pi-extension-subagent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonghak Seo
+
+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,242 @@
+# subagent
+
+Asynchronous subagent delegation for [pi](https://github.com/earendil-works/pi). Run specialist agents in dedicated child sessions, optionally pass selected main-session context, and receive results as follow-up messages.
+
+> [!WARNING]
+> Subagents run headlessly without approval prompts. Claude-runtime agents use permission bypass, and pi-runtime agents can use every tool listed in their agent definition. This extension is not a sandbox. Use it only in trusted repositories with trusted prompts and agent definitions.
+
+## Requirements
+
+- pi 0.80.6 or later (tested with 0.80.6)
+- For `runtime: claude` with the default `claudeRuntime: "sdk"`: supported Anthropic authentication such as `ANTHROPIC_API_KEY`; see the [official Claude Agent SDK documentation](https://platform.claude.com/docs/en/agent-sdk/overview)
+- For `runtime: claude` with `claudeRuntime: "cli"`: the `claude` executable on `PATH` and an authenticated Claude Code installation
+
+## Install
+
+```bash
+pi install npm:@ryan_nookpi/pi-extension-subagent
+```
+
+## Quick start
+
+### 1. Create an agent
+
+Agents are Markdown files with YAML frontmatter. Create `~/.pi/agent/agents/worker.md` for a global agent, or `.pi/agents/worker.md` inside one project:
+
+```markdown
+---
+name: worker
+description: Implements requested changes
+model: anthropic/claude-sonnet-4-6
+thinking: medium
+tools: read,bash,edit,write
+runtime: pi
+---
+
+Implement the requested changes and verify them.
+```
+
+`name` and `description` are required. Optional fields are:
+
+- `runtime`: `pi` (default) or `claude`
+- `model`: runtime-compatible model ID
+- `thinking`: `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`
+- `tools`: comma-separated tool names
+
+Omitted model, thinking, and tools values use that runtime's defaults.
+
+### 2. Confirm discovery
+
+From the interactive pi UI:
+
+```text
+/subagents
+```
+
+From an AI tool call, pass a command string to the `subagent` tool:
+
+```json
+{ "command": "subagent agents" }
+```
+
+The `subagent ...` examples in this README are **tool command strings**, not terminal commands. Do not run them in Bash.
+
+### 3. Launch a run
+
+Interactive user command:
+
+```text
+/sub:isolate worker implement the requested change and run tests
+```
+
+Equivalent AI tool call:
+
+```json
+{ "command": "subagent run worker --isolated -- implement the requested change and run tests" }
+```
+
+Runs are asynchronous in interactive mode. Wait for the automatic completion or failure follow-up instead of immediately polling `status` or `detail`.
+
+## Agent discovery
+
+Definitions are loaded from the following locations. Later sources override earlier agents with the same name:
+
+1. `$PI_CODING_AGENT_DIR/agents/*.md` (normally `~/.pi/agent/agents/*.md`)
+2. Nearest `.claude/agents/**/*.md`
+3. Nearest `.pi/agents/*.md`
+
+Project `.claude/agents` files are discovered recursively. Project `.pi/agents` files are discovered only in the selected directory.
+
+## Context modes and lifecycle
+
+- `--isolated` starts a dedicated child session without copying the main conversation. It is the default for `subagent` tool launches.
+- `--main` adds selected main-session context to the child task.
+- `/sub:isolate` selects isolated context; `/sub:main` selects main context.
+- `>>` and `>` use main-session context.
+- Continuing a run preserves its original context mode and child session. Supplying `--main` or `--isolated` to `continue` does not retroactively change it.
+
+Pi replaces and invalidates extension runtimes during `/new`, `/resume`, `/fork`, and reload. Active child processes are therefore aborted during `session_shutdown`, and the old session records why they stopped. Wait for active runs before replacing the parent session. This follows pi's [official extension lifecycle guidance](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md#long-lived-resources-and-shutdown).
+
+## Tool interface
+
+The extension registers two main-session tools:
+
+- `list-agents`: return discovered agent definitions and runtime settings
+- `subagent`: accept one CLI-style command string
+
+```text
+subagent help
+subagent agents
+subagent runs
+subagent run <agent> [--main|--isolated] -- <task>
+subagent continue <runId> [--agent <agent>] [--main|--isolated] -- <task>
+subagent batch [--main|--isolated] --agent <agent> --task <task> [--agent <agent> --task <task> ...]
+subagent chain [--main|--isolated] --agent <agent> --task <task> [--agent <agent> --task <task> ...]
+subagent status <runId>
+subagent detail <runId>
+subagent abort <runId|runId,runId|all>
+subagent remove <runId|runId,runId|all>
+```
+
+`batch` runs independent tasks in parallel. Quote tasks containing spaces:
+
+```json
+{
+  "command": "subagent batch --main --agent worker --task \"implement feature A\" --agent reviewer --task \"review feature B\""
+}
+```
+
+`chain` runs steps sequentially and gives each step the previous result as reference:
+
+```json
+{
+  "command": "subagent chain --isolated --agent worker --task \"implement the change\" --agent reviewer --task \"review the implementation\""
+}
+```
+
+Use `status` and `detail` only for explicit, one-off inspection. Repeated polling is unnecessary because completion is delivered automatically.
+
+## Slash commands
+
+- `/subagents` — list discovered agents and settings
+- `/sub:main [agent|alias|runId] <task>` — launch with main-session context or continue a run
+- `/sub:isolate [agent|alias|runId] <task>` — launch in isolated context or continue a run
+- `/sub:peek [runId]` — show the latest response; defaults to the latest run
+- `/sub:open [runId]` — open session replay; defaults to the latest run
+- `/sub:history` — show all run history, including removed runs
+- `/sub:rm [runId]` — remove a run; defaults to the latest and aborts it if necessary
+- `/sub:clear [all]` — clear finished runs, or every run with `all`
+- `/sub:abort [runId|all]` — abort the latest running run, one run, or all running runs
+
+When an agent is omitted, launch commands use `defaultAgent`.
+
+## Interactive shortcuts
+
+| Shortcut | Behavior |
+| --- | --- |
+| `>> [agent\|runId] <task>` | Visible run using main-session context |
+| `> [agent\|runId] <task>` | Hidden run using main-session context; interactive UI only |
+| `#<runId> <task>` | Continue a run |
+| `>><symbol> <task>` | Visible run using the agent mapped in `symbolMap` |
+| `><symbol> <task>` | Hidden run using the mapped agent |
+| `<>runId` | Compact form of `/sub:peek runId` |
+| `<< [runId\|runId,runId]` | Abort selected running runs or clear selected finished runs; without arguments, abort the latest running run |
+| `<<< [all]` | Clear finished runs; use `all` to clear every run |
+
+Hidden runs do not add start or completion messages to the main transcript. Read their output with `/sub:peek`, `<>runId`, or `/sub:open`. A plain `>` shortcut requires a space before its task; configured symbol shortcuts do not.
+
+## Escalation from pi-runtime agents
+
+Pi-runtime subagent sessions receive an `ask_master` tool. It lets a child report a decision that the parent must make, then immediately terminates that child run. The parent receives the escalation as a follow-up.
+
+Use `ask_master` only when the child cannot safely proceed, such as before a destructive operation or an unresolved architecture decision. Claude-runtime agents do not receive this tool; they report blockers in their final text instead.
+
+## Configuration
+
+Global configuration belongs under `subagent` in `$PI_CODING_AGENT_DIR/settings.json` (normally `~/.pi/agent/settings.json`):
+
+```json
+{
+  "subagent": {
+    "claudeRuntime": "sdk",
+    "defaultAgent": "worker",
+    "symbolMap": {
+      "?": "searcher",
+      "!": "reviewer"
+    }
+  }
+}
+```
+
+A nearest project `.pi/subagent.json` overrides global values:
+
+```json
+{
+  "defaultAgent": "worker",
+  "symbolMap": {
+    "?": "searcher"
+  }
+}
+```
+
+- `claudeRuntime`: `sdk` (default) or `cli`; applies only to agents with `runtime: claude`
+- `defaultAgent`: agent used when a launch omits its agent; defaults to `worker` and must match a discovered definition
+- `symbolMap`: one-character shortcuts mapped to non-empty agent names; a valid project map replaces the global map as a whole, while a malformed project map falls back to the valid global map
+
+### Context guard override
+
+`PI_SUBAGENT_CONTEXT_GUARD_TOKENS` overrides the proactive context limit for pi-runtime children. Set it to a positive integer to apply that ceiling to every pi model. Set it to `0` or an empty value to disable the proactive guard and rely on native compaction or provider overflow handling.
+
+## Troubleshooting
+
+### `Configured defaultAgent "worker" was not found`
+
+Create a `worker` definition from the quick start, choose an existing agent explicitly, or change `defaultAgent`. Run `/subagents` to verify discovery before launching.
+
+### Claude SDK authentication failure
+
+Confirm the environment used to start pi has valid Anthropic authentication, such as `ANTHROPIC_API_KEY`. The SDK runtime does not require the Claude Code CLI.
+
+### `spawn claude ENOENT`
+
+`claudeRuntime` is set to `cli`, but the `claude` executable is not on `PATH`. Install and authenticate Claude Code, or switch back to `claudeRuntime: "sdk"`.
+
+### Hidden shortcut produces no transcript message
+
+That is intentional. Hidden `>` runs are human-only UI jobs. Inspect them with `/sub:peek`, `<>runId`, or `/sub:open`.
+
+## Security and trust boundary
+
+- Claude SDK execution uses `permissionMode: "bypassPermissions"` with `allowDangerouslySkipPermissions`; Claude CLI execution uses `--dangerously-skip-permissions`.
+- Pi-runtime children are headless and have unrestricted access to the tools declared by their agent.
+- Project agent definitions are repository-controlled instructions. Review `.pi/agents` and `.claude/agents` before running this extension in an unfamiliar repository.
+- Restrict each agent's `tools` list to what it needs. Avoid broad shell or write access for read-only review agents.
+- `--isolated` separates conversation context; it does not provide filesystem, process, credential, or network isolation.
+
+## Stability
+
+This is a `0.1.x` release. The commands, configuration keys, agent frontmatter, and behaviors documented here are the supported surface. Internal TypeScript modules included in the npm tarball are implementation details and may change during the `0.x` series. Compatibility is currently tested against pi 0.80.6.
+
+## License
+
+MIT

package/above-widget.ts

@@ -0,0 +1,20 @@
+/**
+ * Legacy above-editor pixel subagent widget is disabled.
+ *
+ * All subagent runs are rendered by widget.ts in the above-editor run status widget regardless of launch source.
+ */
+
+import type { SubagentStore } from "./store.js";
+import type { WidgetRenderCtx } from "./widget.js";
+
+export function updatePixelWidget(store: SubagentStore, ctx?: Pick<WidgetRenderCtx, "hasUI" | "ui"> | null): void {
+	const activeCtx = ctx ?? store.pixelWidgetCtx;
+	if (!activeCtx?.hasUI) return;
+	store.pixelWidgetCtx = activeCtx;
+	activeCtx.ui?.setWidget("pixel-subagents", undefined);
+}
+
+export function cleanupPixelTimer(): void {
+	// no-op: legacy pixel widget is disabled
+	return;
+}

package/agents.ts

@@ -0,0 +1,233 @@
+/**
+ * Agent discovery and configuration
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import {
+	AGENT_THINKING_LEVELS,
+	type AgentThinkingLevel,
+	normalizeModel,
+	normalizeThinkingLevel,
+	normalizeTools,
+} from "./utils/agent-utils.js";
+
+export const THINKING_LEVELS = AGENT_THINKING_LEVELS;
+
+export type AgentRuntime = "pi" | "claude";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	thinking?: AgentThinkingLevel;
+	systemPrompt: string;
+	source: "user" | "project";
+	filePath: string;
+	runtime: AgentRuntime;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+interface LoadAgentsOptions {
+	recursive?: boolean;
+	format?: "pi" | "claude";
+}
+
+const COMMON_SUBAGENT_NO_RECURSION_RULE = [
+	"Global Runtime Rule (subagent):",
+	"- Never invoke the `subagent` tool.",
+	"- Never trigger subagent commands/shorthands such as `/sub:*`, `>>`, or `>`.",
+	"- If delegation is requested, explain that recursive subagent invocation is disabled and continue with available tools.",
+].join("\n");
+
+const COMMON_SUBAGENT_ESCALATION_GUIDELINE = [
+	"ask_master Guideline:",
+	"- The `ask_master` tool asks the master for a decision. WARNING: calling it terminates your session immediately.",
+	"- Use `ask_master` when:",
+	"  - You encounter ambiguity that cannot be resolved from the task context or codebase",
+	"  - A decision has significant impact (deletion, architecture change, deployment) and you are unsure of the correct choice",
+	"  - You discover unexpected issues that fundamentally change the scope of the task",
+	"  - Task instructions conflict with each other and you need clarification",
+	"- DO NOT use `ask_master` for:",
+	"  - Routine decisions within your domain expertise",
+	"  - Issues you can resolve with available tools and context",
+	"  - Minor style, formatting, or naming choices",
+	"  - Pre-existing problems unrelated to the current task",
+	"- When calling, always include:",
+	"  - Clear description of the blocker or decision needed",
+	"  - Options you have considered with pros/cons",
+	"  - Your recommendation, if you have one",
+].join("\n");
+
+const COMMON_CLAUDE_RUNTIME_ESCALATION_GUIDELINE = [
+	"Blocker Reporting Guideline:",
+	"- If you encounter a blocker that you cannot resolve with available tools and context,",
+	"  report it as plain text at the end of your response.",
+	"- Do NOT attempt to call tools that are not available in your environment (e.g. ask_master).",
+	"- Include: a clear description of the blocker, options you considered, and your recommendation.",
+].join("\n");
+
+function attachCommonSubagentRule(systemPrompt: string, runtime: AgentRuntime = "pi"): string {
+	let prompt = systemPrompt.trimEnd();
+	if (!prompt.includes("Global Runtime Rule (subagent):")) {
+		prompt = prompt ? `${prompt}\n\n${COMMON_SUBAGENT_NO_RECURSION_RULE}` : COMMON_SUBAGENT_NO_RECURSION_RULE;
+	}
+	if (runtime === "claude") {
+		if (!prompt.includes("Blocker Reporting Guideline:")) {
+			prompt = prompt
+				? `${prompt}\n\n${COMMON_CLAUDE_RUNTIME_ESCALATION_GUIDELINE}`
+				: COMMON_CLAUDE_RUNTIME_ESCALATION_GUIDELINE;
+		}
+	} else {
+		if (!prompt.includes("ask_master Guideline:")) {
+			prompt = prompt ? `${prompt}\n\n${COMMON_SUBAGENT_ESCALATION_GUIDELINE}` : COMMON_SUBAGENT_ESCALATION_GUIDELINE;
+		}
+	}
+	return prompt;
+}
+
+function listMarkdownFiles(dir: string, recursive: boolean): string[] {
+	const files: string[] = [];
+	const stack: string[] = [dir];
+
+	while (stack.length > 0) {
+		const currentDir = stack.pop() as string;
+		let entries: fs.Dirent[];
+		try {
+			entries = fs.readdirSync(currentDir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+
+		for (const entry of entries) {
+			const fullPath = path.join(currentDir, entry.name);
+			if (entry.isDirectory()) {
+				if (recursive) stack.push(fullPath);
+				continue;
+			}
+
+			if (!entry.name.endsWith(".md")) continue;
+			if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+			files.push(fullPath);
+		}
+	}
+
+	files.sort((a, b) => a.localeCompare(b));
+	return files;
+}
+
+function loadAgentsFromDir(dir: string, source: "user" | "project", options: LoadAgentsOptions = {}): AgentConfig[] {
+	const agents: AgentConfig[] = [];
+	const recursive = options.recursive ?? false;
+	const format = options.format ?? "pi";
+
+	if (!fs.existsSync(dir)) {
+		return agents;
+	}
+
+	const files = listMarkdownFiles(dir, recursive);
+	for (const filePath of files) {
+		let content: string;
+		try {
+			content = fs.readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+		if (!frontmatter.name || !frontmatter.description) continue;
+
+		const tools = normalizeTools(frontmatter.tools, format);
+		const model = normalizeModel(frontmatter.model, format);
+		const thinking = normalizeThinkingLevel(frontmatter.thinking);
+		const runtime: AgentRuntime = frontmatter.runtime === "claude" ? "claude" : "pi";
+
+		agents.push({
+			name: frontmatter.name,
+			description: frontmatter.description,
+			tools,
+			model,
+			thinking,
+			systemPrompt: attachCommonSubagentRule(body, runtime),
+			source,
+			filePath,
+			runtime,
+		});
+	}
+
+	return agents;
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		const candidate = path.join(currentDir, ".pi", "agents");
+		if (isDirectory(candidate)) return candidate;
+
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+
+function findNearestClaudeAgentsDir(cwd: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		const candidate = path.join(currentDir, ".claude", "agents");
+		if (isDirectory(candidate)) return candidate;
+
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+
+export function discoverAgents(cwd: string): AgentDiscoveryResult {
+	const userDir = path.join(getAgentDir(), "agents");
+	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+	const claudeAgentsDir = findNearestClaudeAgentsDir(cwd);
+
+	const userAgents = loadAgentsFromDir(userDir, "user", { format: "pi" });
+	const projectPiAgents = projectAgentsDir ? loadAgentsFromDir(projectAgentsDir, "project", { format: "pi" }) : [];
+	const projectClaudeAgents = claudeAgentsDir
+		? loadAgentsFromDir(claudeAgentsDir, "project", { format: "claude", recursive: true })
+		: [];
+
+	// Priority: user < .claude/agents < .pi/agents
+	const projectAgents = [...projectClaudeAgents, ...projectPiAgents];
+
+	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);
+
+	const projectSources = [projectAgentsDir, claudeAgentsDir].filter((dir): dir is string => Boolean(dir));
+
+	return {
+		agents: Array.from(agentMap.values()),
+		projectAgentsDir: projectSources.length > 0 ? projectSources.join(", ") : null,
+	};
+}
+
+export function formatAgentList(agents: AgentConfig[], maxItems: number): { text: string; remaining: number } {
+	if (agents.length === 0) return { text: "none", remaining: 0 };
+	const listed = agents.slice(0, maxItems);
+	const remaining = agents.length - listed.length;
+	return {
+		text: listed.map((a) => `${a.name} (${a.source}): ${a.description}`).join("; "),
+		remaining,
+	};
+}

package/claude-args.ts

@@ -0,0 +1,103 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { mapPiToolsToClaude } from "./utils/agent-utils.js";
+
+export interface ClaudeArgsConfig {
+	prompt: string;
+	tools: string[];
+	model?: string;
+	thinking?: string;
+	resumeSessionId?: string;
+	cwd?: string;
+	mcpConfigPath?: string;
+	systemPromptFile?: string;
+}
+
+const MCP_CONFIG_CANDIDATES = [".mcp.json"] as const;
+
+export function mapThinkingToClaudeEffort(piThinking: string): "low" | "medium" | "high" | "max" | undefined {
+	switch (piThinking) {
+		case "off":
+		case "minimal":
+			return "low";
+		case "low":
+			return "medium";
+		case "medium":
+			return "high";
+		case "high":
+		case "xhigh":
+			return "max";
+		case "max":
+			return "max";
+		default:
+			return undefined;
+	}
+}
+
+export function findProjectMcpConfig(cwd: string): string | undefined {
+	let currentDir = path.resolve(cwd);
+
+	while (true) {
+		for (const candidate of MCP_CONFIG_CANDIDATES) {
+			const fullPath = path.join(currentDir, candidate);
+			try {
+				if (fs.statSync(fullPath).isFile()) return fullPath;
+			} catch {}
+		}
+
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return undefined;
+		currentDir = parentDir;
+	}
+}
+
+export function buildClaudeArgs(config: ClaudeArgsConfig): string[] {
+	const args: string[] = [
+		"-p",
+		"--output-format",
+		"stream-json",
+		"--include-partial-messages",
+		"--verbose",
+		"--dangerously-skip-permissions",
+	];
+
+	const claudeTools = mapPiToolsToClaude(config.tools);
+
+	if (claudeTools.length > 0) {
+		args.push("--tools", claudeTools.join(","));
+		args.push("--allowedTools", claudeTools.join(","));
+	}
+
+	args.push("--strict-mcp-config");
+
+	if (config.mcpConfigPath) {
+		args.push("--mcp-config", config.mcpConfigPath);
+	} else if (config.cwd) {
+		const discovered = findProjectMcpConfig(config.cwd);
+		if (discovered) {
+			args.push("--mcp-config", discovered);
+		}
+	}
+
+	if (config.model) {
+		const normalized = config.model.replace(/^anthropic\//, "");
+		args.push("--model", normalized);
+	}
+
+	if (config.thinking) {
+		const effort = mapThinkingToClaudeEffort(config.thinking);
+		if (effort) args.push("--effort", effort);
+	}
+
+	if (config.resumeSessionId) {
+		args.push("--resume", config.resumeSessionId);
+	}
+
+	if (config.systemPromptFile) {
+		args.push("--append-system-prompt-file", config.systemPromptFile);
+	}
+
+	args.push(config.prompt);
+
+	return args;
+}