npm - @ferris1225/pi-subagents - Versions diffs - 0.6.0 → 0.8.0 - Mend

@ferris1225/pi-subagents 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md CHANGED Viewed

@@ -1,174 +1,191 @@
-# pi-subagents
-[![npm version](https://img.shields.io/npm/v/@ferris1225/pi-subagents?color=blue)](https://www.npmjs.com/package/@ferris1225/pi-subagents)
-[![downloads](https://img.shields.io/npm/dm/@ferris1225/pi-subagents)](https://www.npmjs.com/package/@ferris1225/pi-subagents)
-[![license](https://img.shields.io/npm/l/@ferris1225/pi-subagents)](./LICENSE)
-![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
-![pi](https://img.shields.io/badge/pi-extension-orange)
-English | [中文](./README-zh.md)
-A focused [pi](https://pi.dev) extension that gives the main model **sub-agents it will
-actually use**: `explore`, `worker`, and `reviewer` (plus an opt-in `plan`), each running
-in an isolated `pi` process. The differentiator is not the agents themselves — it is the
-**proactive dispatch injection** that makes the model delegate on its own, so you can
-delete the dispatch/review rules from your global `AGENTS.md`.
-## Why pi-subagents?
-Pi ships no sub-agents on purpose. The community fills the gap two ways, and both miss:
-- **Too heavy** — frameworks with 9 agents, chain pipelines, worktree swarms, and a
-  slash-command for everything. Powerful, but a lot of machinery to carry.
-- **Too quiet** — a bare `subagent` tool that the model *rarely calls*, because pi only
-  shows the parent model the tool, never the per-agent descriptions. So the agents sit
-  idle unless you force them in a global prompt.
-`pi-subagents` takes the middle path:
-| Advantage | What it means for you |
-|-----------|----------------------|
-| **Actually gets used** | A `before_agent_start` hook injects the agent catalog + a dispatch/review directive into the system prompt every turn, reinforced by tool `promptGuidelines` and `Use PROACTIVELY when …` descriptions. This is the lever the heavy frameworks rely on too — we just make it the default. |
-| **Right-sized** | 3 focused agents (+1 opt-in), not 9. No chain/worktree/swarm machinery. Single and parallel modes only. |
-| **Replaces your AGENTS.md rules** | The injected directive is a self-contained replacement for the "Sub-agent Dispatch" and "Review, Verification & Commit" sections. Install it, then delete those sections. |
-| **True isolation** | Each agent is a separate `pi` process (`--no-session`), so delegated work never pollutes the main context. |
-| **Read-only where it matters** | `explore`, `plan`, and `reviewer` are read-only. The `reviewer` runs in a *separate* context to avoid self-confirmation bias. |
-| **Selection-only setup** | No typing of values: a checkbox module picker and a fuzzy-filter, paginated model picker. |
-| **Sensible model defaults** | Per-agent model override; if you skip one, it uses the **main session's current model**. Unavailable saved overrides are repaired and persisted automatically. |
-| **Leaf sub-agents** | Child processes never receive the `subagent` tool, so delegation cannot recurse or run away. |
-| **Zero runtime deps** | Pure pi extension, peer dependencies only, no build step. |
-## Install
-```bash
-pi install npm:@ferris1225/pi-subagents
-```
-Requires pi **≥ 0.80.6** — sub-agent thinking levels use the `--thinking` values
-introduced by that version.
-Then run the setup wizard (selection-only):
-```text
-/subagents-setup
-```
-## Agents
-| Agent | Default | Tools | Role |
-|-------|:-------:|-------|------|
-| `explore` | ✅ | read-only | Fast codebase reconnaissance; returns compressed findings for handoff. |
-| `worker` | ✅ | all | Implements / fixes / refactors / tests a self-contained task. **Plans internally.** |
-| `reviewer` | ✅ | read-only | Adversarial pre-commit review in a separate context. |
-| `plan` | opt-in | read-only | A separate, human-reviewable implementation plan. A worker already plans internally, so this is only for when you want the plan as its own artifact. |
-Each agent is a Markdown file (`agents/*.md`: YAML frontmatter + body as system prompt).
-Override any of them by dropping a file with the same `name` into `~/.pi/agent/agents/`
-(user) or `.pi/agents/` (project).
-## How proactive dispatch works
-Pi never shows the parent model the per-agent descriptions — it only sees the `subagent`
-tool. Three levers fix that:
-1. **`before_agent_start` injection** — every turn, the enabled agents plus a
-   dispatch/review directive are appended to the parent system prompt.
-2. **Tool `promptSnippet` / `promptGuidelines`** — reinforce "when to delegate" whenever
-   the tool is active.
-3. **`Use PROACTIVELY when …`** descriptions — the trigger phrasing proven across the
-   Claude Code agent ecosystem.
-The directive encourages a clean flow: **`explore` → `worker` → `reviewer`**, parallel
-fan-out for independent tasks, and trust-but-verify handoffs. Because runs are backgrounded,
-start dependent steps only after the preceding result is delivered.
-## Configuration
-Stored at `~/.pi/agent/pi-subagents.json` (honors `PI_CODING_AGENT_DIR`):
-```json
-{
-  "enabledAgents": ["explore", "worker", "reviewer"],
-  "agentModels": { "explore": "anthropic/claude-haiku-4-5" },
-  "thinkingLevel": "max",
-  "proactiveInjection": true,
-  "agentScope": "user"
-}
-```
-- `enabledAgents` — which agents are discoverable and injected.
-- `agentModels` — per-agent model override (`"provider/model-id"`). If a saved model is unavailable, it is replaced with the current main-window model and written back to this file.
-- `thinkingLevel` — sub-agent reasoning strength: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` (default).
-- `proactiveInjection` — toggle the system-prompt injection.
-- `agentScope` — `"user"` (default), `"project"`, or `"both"`.
-**Model precedence** for each agent:
-```
-available agentModels[name]  →  current session model  →  the agent's frontmatter default
-```
-If a configured model is no longer available, it is switched to the current main-window model and persisted before the next run.
-## Usage
-The main model calls `subagent` on its own, but you can also ask directly:
-```text
-# single
-Use the explore sub-agent to map how authentication is wired up.
-# parallel (independent tasks)
-Run these in parallel sub-agents: explore the API layer, and explore the DB layer.
-```
-Tool shape:
-```jsonc
-// single
-{ "agent": "worker", "task": "<self-contained brief>" }
-// parallel
-{ "tasks": [ { "agent": "explore", "task": "..." }, { "agent": "explore", "task": "..." } ] }
-```
-Every run starts in the background. The tool immediately ends the current main-agent turn,
-so the editor is ready for another request without pressing Escape. The completed output is
-shown and added to the context before a later user prompt. Escape only interrupts foreground
-work after launch; session switch, reload, or exit cancels remaining background processes.
-## Live status & notifications
-While sub-agents run, a widget above the editor shows one line per run — status
-icon, agent, model, token usage, elapsed time — plus a second, indented line
-with what the agent is doing right now: `thinking`, `responding`,
-`read src/index.ts`, `bash npm test`, … (never a raw JSON args blob).
-`responding` means the model is streaming normal text, **not** writing to the filesystem.
-When a run finishes (done **or** failed), its row disappears from the widget and
-the main window gets a notification with the final summary
-(`✓ worker · openai/gpt-5 · ↑12.4k ↓3.1k · 47s`). Its completed result message
-is the durable record in the conversation and context for a later request.
-Sub-agents use the configured thinking level (default `--thinking max`);
-pi clamps it adaptively to what the resolved model supports
-(`max → xhigh → high → … → off`), so weaker models degrade gracefully.
-The task is sent through stdin; only the agent system prompt uses a short-lived
-file. Child output is streamed in memory. Runs have no default time limit;
-explicit cancellation cleans up the process tree.
-## Development
-```bash
-npm install
-npm run check   # tsc --noEmit
-npm test        # vitest
-```
-## See also
-- [pi-querit-search](https://www.npmjs.com/package/pi-querit-search) — live web search &
-  page fetching for pi, by the same author.
-## License
-MIT
+# pi-subagents
+[![npm version](https://img.shields.io/npm/v/@ferris1225/pi-subagents?color=blue)](https://www.npmjs.com/package/@ferris1225/pi-subagents)
+[![downloads](https://img.shields.io/npm/dm/@ferris1225/pi-subagents)](https://www.npmjs.com/package/@ferris1225/pi-subagents)
+[![license](https://img.shields.io/npm/l/@ferris1225/pi-subagents)](./LICENSE)
+![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
+![pi](https://img.shields.io/badge/pi-extension-orange)
+Focused background delegation for [pi](https://pi.dev). `pi-subagents` adds a small set of
+specialized agents that run in isolated child processes, report results back to the main
+agent, and keep the workflow moving without manual polling.
+## Highlights
+- **Automatic delegation guidance** — injects the enabled agent catalog and routing rules into
+  the main agent's system prompt.
+- **Isolated execution** — every sub-agent runs in its own `pi` process with `--no-session`.
+- **Automatic continuation** — a completed result is sent to the main session as a custom
+  message and automatically starts a follow-up turn. If the main agent is busy, the result
+  waits in the follow-up queue.
+- **Parallel fan-out** — run independent tasks together, with a bounded background queue.
+- **Live progress** — a TUI widget shows each agent's status, activity, model, usage, and
+  elapsed time; completion also produces a concise notification.
+- **Per-agent configuration** — enable agents, select models, set thinking strength, tune
+  concurrency limits, and choose discovery scope from `/subagents-setup`.
+- **Leaf processes** — child agents cannot access the `subagent` tool, so delegation cannot
+  recurse.
+## Install
+```bash
+pi install npm:@ferris1225/pi-subagents
+```
+Requires pi **>= 0.80.6**.
+After installation, open the setup wizard in an interactive TUI session:
+```text
+/subagents-setup
+```
+The default configuration enables `explore`, `worker`, and `reviewer`.
+## Included agents
+| Agent | Default | Access | Purpose |
+| --- | :---: | --- | --- |
+| `explore` | Yes | Read-only | Fast codebase reconnaissance and structured findings. |
+| `worker` | Yes | Full | Implements, fixes, refactors, and tests a self-contained task. |
+| `reviewer` | Yes | Read-only | Independent adversarial review of a diff before completion. |
+Agents are Markdown files in `agents/`. Each file contains YAML frontmatter and a system
+prompt. User and project scopes can override a built-in agent with the same name.
+## Workflow
+A typical flow is:
+```text
+main agent
+    │
+    ├─ subagent(explore / worker / reviewer)
+    │       └─ isolated pi child process
+    │                 └─ result message
+    │
+    └─ automatic follow-up turn with the result
+```
+1. The main agent calls `subagent` with a self-contained brief.
+2. The tool returns immediately and ends that foreground tool turn, leaving the editor ready
+   for input.
+3. The child process works independently. By default up to four queued runs execute at
+   once and a single parallel request may contain up to eight tasks; both limits are
+   configurable (`maxConcurrency` / `maxParallelTasks`).
+4. On completion or failure, the extension sends a durable result message to the main
+   session. That message automatically wakes the main agent, or waits until its current turn
+   finishes.
+5. The main agent uses the result to verify the work and continue dependent steps. No later
+   user prompt is required to collect a result.
+Switching sessions, reloading, or shutting down cancels remaining background runs.
+## Usage
+The main agent is encouraged to delegate automatically, but you can also ask directly:
+```text
+Use explore to map how authentication is wired up.
+Ask worker to implement the API change after the exploration is complete.
+Run reviewer on the final diff before reporting completion.
+```
+### Single task
+```json
+{
+  "agent": "worker",
+  "task": "Implement the requested change. Inspect the existing conventions, update tests, and report the files changed and checks run."
+}
+```
+Optional `cwd` selects the working directory for that child.
+### Parallel tasks
+Use parallel mode only for independent work:
+```json
+{
+  "tasks": [
+    { "agent": "explore", "task": "Map the API layer and its tests." },
+    { "agent": "explore", "task": "Map the database layer and its tests." }
+  ]
+}
+```
+Start dependent work after the relevant result has been delivered to the main agent.
+## Configuration
+Configuration is stored at `~/.pi/agent/pi-subagents.json`. The location follows
+`PI_CODING_AGENT_DIR` when set.
+```json
+{
+  "enabledAgents": ["explore", "worker", "reviewer"],
+  "agentModels": {
+    "explore": "anthropic/claude-haiku-4-5"
+  },
+  "thinkingLevel": "max",
+  "proactiveInjection": true,
+  "agentScope": "user",
+  "maxConcurrency": 4,
+  "maxParallelTasks": 8,
+  "maxSubagentDepth": 1
+}
+```
+| Field | Description |
+| --- | --- |
+| `enabledAgents` | Agent names exposed to discovery and prompt injection. An empty array disables all agents. |
+| `agentModels` | Optional `provider/model-id` override per agent. |
+| `thinkingLevel` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. |
+| `proactiveInjection` | Whether to add the delegation directive to the main system prompt. |
+| `agentScope` | `user`, `project`, or `both`; controls which user/project agent directories are discovered. |
+| `maxConcurrency` | How many sub-agent processes run at once (1–16, default 4). Extra work waits in the queue. |
+| `maxParallelTasks` | Maximum tasks accepted by one parallel `subagent` call (1–32, default 8). |
+| `maxSubagentDepth` | Depth at which the `subagent` tool is no longer registered (default 1: the main session delegates, children are leaf processes). `0` disables the tool entirely. Read once at extension load. |
+### Configuration migration
+The config file migrates itself on load — no manual steps after an upgrade:
+- **Schema upgrades** — a config written by an older version (missing newer keys or
+  holding invalid values) is normalized and saved back with the new fields filled in.
+- **Removed agents** — agents no longer shipped (e.g. the old `plan` agent) are stripped
+  from `enabledAgents` and `agentModels` automatically.
+Model selection uses this precedence:
+```text
+configured agent model → current main-session model → agent frontmatter model
+```
+Unavailable configured models are replaced with a usable current-session model when possible
+and the repaired configuration is saved.
+## Agent discovery and overrides
+- Built-in agents are shipped with the package.
+- User agents live in `~/.pi/agent/agents/`.
+- Project agents live in the nearest `.pi/agents/` directory.
+- For duplicate names, project overrides user and user overrides built-in.
+Use a matching Markdown filename and `name` field to replace a built-in agent. Keep the task
+brief explicit: include the goal, relevant paths, constraints, and expected handoff.
+## Development
+```bash
+npm install
+npm run check
+npm test
+```
+The package has no runtime dependencies beyond pi peer dependencies.
+## License
+MIT

package/agents/explore.md CHANGED Viewed

@@ -26,7 +26,7 @@ You are an explore agent: a fast, read-only reconnaissance specialist. You inves
 - Thorough: trace dependencies across modules; check tests and types.
 ## Collaboration
-- Your output feeds `plan` or `worker`. Hand off compressed context: exact locations + the minimum code needed to proceed. Flag anything ambiguous so the caller can decide.
+- Your output feeds `worker` (or the main agent directly). Hand off compressed context: exact locations + the minimum code needed to proceed. Flag anything ambiguous so the caller can decide.
 ## Output format
 ## Files Retrieved

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.6.0",
-  "description": "Focused sub-agent delegation for pi: explore / plan / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
+  "version": "0.8.0",
+  "description": "Focused sub-agent delegation for pi: explore / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -18,7 +18,6 @@
     "src",
     "agents",
     "README.md",
-    "README-zh.md",
     "LICENSE"
   ],
   "pi": {

package/src/background.ts CHANGED Viewed

@@ -14,7 +14,7 @@ interface PendingTask {
 }
 export class BackgroundTaskQueue {
-	private readonly concurrency: number;
+	private concurrency: number;
 	private readonly pending: PendingTask[] = [];
 	private readonly active = new Set<AbortController>();
 	private stopped = false;
@@ -23,6 +23,16 @@ export class BackgroundTaskQueue {
 		this.concurrency = Math.max(1, concurrency);
 	}
+	/**
+	 * Update the concurrency limit (e.g. after a config change). Raising it
+	 * immediately starts more queued work; lowering it takes effect as running
+	 * tasks finish — already-running tasks are never interrupted.
+	 */
+	setConcurrency(concurrency: number): void {
+		this.concurrency = Math.max(1, concurrency);
+		this.drain();
+	}
 	enqueue(task: BackgroundTask, onCancelled?: () => void): AbortController {
 		const controller = new AbortController();
 		if (this.stopped) {

package/src/config.ts CHANGED Viewed

@@ -5,19 +5,31 @@
  * and honors PI_CODING_AGENT_DIR). Parsing is defensive: invalid fields fall back
  * to defaults instead of throwing, so a hand-edited or partially-written file can
  * never break the extension at runtime.
+ *
+ * Schema upgrades happen transparently on load: a config written by an older
+ * version (missing newer keys, holding removed agents, or containing invalid
+ * values) is normalized and persisted back with the new fields filled in.
  */
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 /** Full catalog of agents shipped with the package (selectable in /subagents-setup). */
-export const BUILTIN_AGENT_NAMES = ["explore", "plan", "worker", "reviewer"] as const;
+export const BUILTIN_AGENT_NAMES = ["explore", "worker", "reviewer"] as const;
 export type BuiltinAgentName = (typeof BUILTIN_AGENT_NAMES)[number];
-/** Agents enabled out of the box. `plan` ships but is opt-in: a worker plans internally. */
+/** Agents enabled out of the box. */
 export const DEFAULT_ENABLED_AGENTS: readonly string[] = ["explore", "worker", "reviewer"];
+/**
+ * Agents that used to ship but were removed. normalizeConfig strips them from
+ * enabledAgents/agentModels so upgraded installs clean their config automatically
+ * (the schema-upgrade save in loadConfig then persists the cleanup).
+ */
+export const REMOVED_AGENT_NAMES: readonly string[] = ["plan"];
 export const AGENT_SCOPE_VALUES = ["user", "project", "both"] as const;
 export type AgentScope = (typeof AGENT_SCOPE_VALUES)[number];
@@ -28,6 +40,22 @@ export const DEFAULT_THINKING_LEVEL: ThinkingLevel = "max";
 export const CONFIG_FILE_NAME = "pi-subagents.json";
+/** How many sub-agent processes may run at once. Default: 4. */
+export const DEFAULT_MAX_CONCURRENCY = 4;
+/** Upper bound accepted for maxConcurrency (defensive clamp). */
+export const MAX_CONCURRENCY_LIMIT = 16;
+/** How many tasks a single parallel `subagent` call may contain. Default: 8. */
+export const DEFAULT_MAX_PARALLEL_TASKS = 8;
+/** Upper bound accepted for maxParallelTasks (defensive clamp). */
+export const MAX_PARALLEL_TASKS_LIMIT = 32;
+/**
+ * Depth at which the subagent tool stops being available. 1 = the main session
+ * delegates and child processes are leaves; 0 disables the tool entirely.
+ */
+export const DEFAULT_MAX_SUBAGENT_DEPTH = 1;
+/** Upper bound accepted for maxSubagentDepth (defensive clamp). */
+export const MAX_SUBAGENT_DEPTH_LIMIT = 4;
 export interface SubagentsConfig {
 	/** Agent names that are discoverable and injected. Default: explore, worker, reviewer. */
 	enabledAgents: string[];
@@ -39,6 +67,12 @@ export interface SubagentsConfig {
 	proactiveInjection: boolean;
 	/** Which agent directories to discover from. Default: "user". */
 	agentScope: AgentScope;
+	/** Max sub-agent processes running at once (extra work queues). Default: 4. */
+	maxConcurrency: number;
+	/** Max tasks accepted by one parallel `subagent` call. Default: 8. */
+	maxParallelTasks: number;
+	/** Depth at which the subagent tool is no longer registered. Default: 1. */
+	maxSubagentDepth: number;
 }
 export const DEFAULT_CONFIG: SubagentsConfig = {
@@ -47,6 +81,9 @@ export const DEFAULT_CONFIG: SubagentsConfig = {
 	thinkingLevel: DEFAULT_THINKING_LEVEL,
 	proactiveInjection: true,
 	agentScope: "user",
+	maxConcurrency: DEFAULT_MAX_CONCURRENCY,
+	maxParallelTasks: DEFAULT_MAX_PARALLEL_TASKS,
+	maxSubagentDepth: DEFAULT_MAX_SUBAGENT_DEPTH,
 };
 export function getConfigPath(agentDir: string = getAgentDir()): string {
@@ -68,6 +105,12 @@ function isModelReference(value: unknown): value is string {
 	return slash > 0 && slash < normalized.length - 1 && !/\s/u.test(normalized);
 }
+/** Clamp a raw value to a positive integer within [1, upper]; undefined when invalid. */
+function clampCount(value: unknown, upper: number): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+	return Math.max(1, Math.min(upper, Math.round(value)));
+}
 /**
  * Merge a raw parsed JSON value over the defaults, dropping invalid fields.
  * Exported for tests.
@@ -81,6 +124,9 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		thinkingLevel: DEFAULT_CONFIG.thinkingLevel,
 		proactiveInjection: DEFAULT_CONFIG.proactiveInjection,
 		agentScope: DEFAULT_CONFIG.agentScope,
+		maxConcurrency: DEFAULT_CONFIG.maxConcurrency,
+		maxParallelTasks: DEFAULT_CONFIG.maxParallelTasks,
+		maxSubagentDepth: DEFAULT_CONFIG.maxSubagentDepth,
 	};
 	if (Array.isArray(raw.enabledAgents)) {
@@ -88,11 +134,15 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 			(name): name is string => typeof name === "string" && name.trim().length > 0,
 		);
 		// An explicitly empty array is honored (disables all agents); otherwise keep valid names.
-		config.enabledAgents = [...new Set(names.map((name) => name.trim()))];
+		// Agents removed from the package (e.g. plan) are stripped from upgraded configs.
+		config.enabledAgents = [...new Set(names.map((name) => name.trim()))].filter(
+			(name) => !REMOVED_AGENT_NAMES.includes(name),
+		);
 	}
 	if (isRecord(raw.agentModels)) {
 		for (const [key, value] of Object.entries(raw.agentModels)) {
+			if (REMOVED_AGENT_NAMES.includes(key.trim())) continue;
 			if (isModelReference(value)) config.agentModels[key.trim()] = value.trim();
 		}
 	}
@@ -109,33 +159,71 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		config.agentScope = raw.agentScope;
 	}
+	const maxConcurrency = clampCount(raw.maxConcurrency, MAX_CONCURRENCY_LIMIT);
+	if (maxConcurrency !== undefined) config.maxConcurrency = maxConcurrency;
+	const maxParallelTasks = clampCount(raw.maxParallelTasks, MAX_PARALLEL_TASKS_LIMIT);
+	if (maxParallelTasks !== undefined) config.maxParallelTasks = maxParallelTasks;
+	// 0 is meaningful here (disables the tool), so clamp to [0, limit] instead.
+	if (typeof raw.maxSubagentDepth === "number" && Number.isFinite(raw.maxSubagentDepth)) {
+		config.maxSubagentDepth = Math.max(0, Math.min(MAX_SUBAGENT_DEPTH_LIMIT, Math.round(raw.maxSubagentDepth)));
+	}
 	return config;
 }
+function defaultConfig(): SubagentsConfig {
+	return { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_CONFIG.enabledAgents], agentModels: {} };
+}
 /**
  * Load config. A missing file is a normal state and yields the defaults (not an error).
  * A corrupt file also falls back to defaults rather than throwing, so startup never breaks.
+ * A file from an older version (missing newer keys or holding removed agents) is
+ * normalized and persisted back, so the on-disk config stays current.
  */
 export async function loadConfig(configPath: string = getConfigPath()): Promise<SubagentsConfig> {
 	let text: string;
 	try {
 		text = await readFile(configPath, "utf8");
-	} catch (error) {
-		if (isNodeError(error) && error.code === "ENOENT") {
-			return { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_CONFIG.enabledAgents] };
-		}
-		// Unreadable for another reason: fall back to defaults but do not crash startup.
-		return { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_CONFIG.enabledAgents] };
+	} catch {
+		// Missing or unreadable: fall back to defaults but do not crash startup.
+		return defaultConfig();
 	}
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(text);
 	} catch {
-		return { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_CONFIG.enabledAgents] };
+		return defaultConfig();
+	}
+	const config = normalizeConfig(parsed);
+	// Schema upgrade: persist the normalized shape when the file gained fields
+	// (new version) or dropped invalid/removed ones.
+	if (JSON.stringify(config) !== JSON.stringify(parsed)) {
+		try {
+			await saveConfig(config, configPath);
+		} catch {
+			// Non-fatal: keep the in-memory config for this run.
+		}
 	}
-	return normalizeConfig(parsed);
+	return config;
+}
+/**
+ * Synchronous load for the extension's init-time decisions (e.g. the recursion
+ * guard). Runs before any async context is available; never migrates or saves.
+ */
+export function loadConfigSync(configPath: string = getConfigPath()): SubagentsConfig {
+	try {
+		return normalizeConfig(JSON.parse(readFileSync(configPath, "utf8")));
+	} catch {
+		return defaultConfig();
+	}
 }
 /**
@@ -159,10 +247,6 @@ export async function saveConfig(
 	});
 }
-function isNodeError(error: unknown): error is NodeJS.ErrnoException {
-	return error instanceof Error;
-}
 export function errorMessage(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }

package/src/index.ts CHANGED Viewed

@@ -2,7 +2,7 @@
  * pi-subagents — focused sub-agent delegation for pi.
  *
  * Registers:
- *   - a `subagent` tool that runs explore/plan/worker/reviewer agents as isolated
+ *   - a `subagent` tool that runs explore/worker/reviewer agents as isolated
  *     `pi` child processes (single or parallel),
  *   - a `/subagents-setup` command for selection-only configuration,
  *   - a `before_agent_start` hook that injects a delegation directive into the
@@ -18,14 +18,11 @@ import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { discoverAgents, type AgentConfig } from "./agents.ts";
 import { BackgroundTaskQueue } from "./background.ts";
-import { getConfigPath, loadConfig, saveConfig } from "./config.ts";
+import { getConfigPath, loadConfig, loadConfigSync, saveConfig } from "./config.ts";
 import { repairUnavailableModelOverrides } from "./models.ts";
 import { buildDelegationDirective } from "./prompt.ts";
 import { runSetup } from "./setup.ts";
 import {
-	MAX_CONCURRENCY,
-	MAX_PARALLEL_TASKS,
-	MAX_SUBAGENT_DEPTH,
 	currentSubagentDepth,
 	getFinalOutput,
 	getResultOutput,
@@ -112,15 +109,23 @@ function formatUsage(usage: UsageStats): string {
 export default function (pi: ExtensionAPI): void {
 	const configPath = getConfigPath(getAgentDir());
-	const backgroundQueue = new BackgroundTaskQueue(MAX_CONCURRENCY);
+	// Init-time decisions need the config synchronously; the full (migrating)
+	// async load runs per tool call.
+	const initialConfig = loadConfigSync(configPath);
+	const backgroundQueue = new BackgroundTaskQueue(initialConfig.maxConcurrency);
 	let sessionActive = true;
-	// Recursion guard: child sub-agents are leaf processes and cannot delegate again.
-	if (currentSubagentDepth() >= MAX_SUBAGENT_DEPTH) {
+	// Recursion guard: sub-agents at the configured depth are leaf processes and
+	// cannot delegate again. maxSubagentDepth 0 disables the tool entirely.
+	if (currentSubagentDepth() >= initialConfig.maxSubagentDepth) {
+		const reason =
+			initialConfig.maxSubagentDepth === 0
+				? "disabled by maxSubagentDepth 0 in pi-subagents.json"
+				: "disabled in nested sub-agent processes";
 		pi.registerCommand("subagents-setup", {
-			description: "Configure pi-subagents (disabled in nested sub-agent processes)",
+			description: `Configure pi-subagents (${reason})`,
 			handler: async (_args, ctx) => {
-				ctx.ui.notify("pi-subagents setup is unavailable inside a nested sub-agent.", "warning");
+				ctx.ui.notify(`pi-subagents setup is unavailable here (${reason}).`, "warning");
 			},
 		});
 		return;
@@ -144,26 +149,28 @@ export default function (pi: ExtensionAPI): void {
 		label: "Subagent",
 		description: [
 			"Delegate a discrete, self-contained task to a specialized sub-agent running in an ISOLATED context window.",
-			"Agents: explore (read-only codebase recon), plan (implementation plan, opt-in), worker (implement/fix/refactor/test, full tools), reviewer (adversarial pre-commit review, read-only).",
+			"Agents: explore (read-only codebase recon), worker (implement/fix/refactor/test, full tools), reviewer (adversarial pre-commit review, read-only).",
 			"Modes: single ({agent, task}) or parallel ({tasks: [{agent, task}, ...]}).",
-			"It starts agents in the background and immediately returns control to the main window; completed results arrive in a later user prompt.",
+			"It starts agents in the background and immediately returns control to the main window; completion messages automatically wake the main agent to continue.",
 			"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output)."
 		].join(" "),
 		promptSnippet:
-			"Start background subagents: explore (read-only search), worker (implement), reviewer (adversarial review); completed results arrive in a later prompt.",
+			"Start background subagents: explore (read-only search), worker (implement), reviewer (adversarial review); completion automatically resumes the main agent.",
 		promptGuidelines: [
 			"Use subagent to delegate discrete, self-contained tasks so the main context stays clean; do orchestration and verification yourself.",
 			"Use subagent with agent 'explore' for broad or open-ended code search before large changes.",
 			"Use subagent with agent 'worker' to implement a well-scoped task; it plans internally.",
 			"Use subagent with agent 'reviewer' for a fresh read-only review before reporting work done or committing.",
-			"subagent launches work in the background and ends the current turn; do not assume a result is available until a later user prompt.",
-			"Run independent tasks in parallel by passing a tasks array to subagent; start dependent work only after its result arrives.",
+			"subagent launches work in the background and ends the current turn; when a result arrives, the main agent is automatically resumed with it.",
+			"Run independent tasks in parallel by passing a tasks array to subagent; let the automatically resumed main agent start dependent work after results arrive.",
 		],
 		parameters: SubagentParams,
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			monitor.beginTurn();
 			let config = await loadConfig(configPath);
+			// Pick up concurrency changes from /subagents-setup without a restart.
+			backgroundQueue.setConcurrency(config.maxConcurrency);
 			const repairedModels = repairUnavailableModelOverrides(ctx, config.agentModels);
 			if (repairedModels.changed) {
 				config = { ...config, agentModels: repairedModels.agentModels };
@@ -183,8 +190,8 @@ export default function (pi: ExtensionAPI): void {
 				}
 			}
-			// Finished runs leave the widget immediately. Their final findings arrive
-			// as a custom message before the next foreground prompt.
+			// Finished runs leave the widget immediately. Their final findings are sent
+			// back as a custom message that automatically starts a follow-up turn.
 			const finishRun = (runId: number, status: "done" | "failed"): void => {
 				monitor.setStatus(runId, status); // stamps endedAt for the elapsed time
 				const run = monitor.removeRun(runId);
@@ -297,7 +304,9 @@ export default function (pi: ExtensionAPI): void {
 								content: `### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}\n\n${getResultOutput(result)}`,
 								display: true,
 							},
-							{ deliverAs: "nextTurn" },
+							// The result is both durable context and a wake-up signal. If the
+							// main agent is busy, followUp queues it until the current turn ends.
+							{ deliverAs: "followUp", triggerTurn: true },
 						);
 					},
 					() => finishRun(runId, "failed"),
@@ -307,16 +316,19 @@ export default function (pi: ExtensionAPI): void {
 			};
 			// Sub-agents intentionally detach from the foreground turn. This makes the
-			// editor available immediately; completed findings arrive before the next prompt.
+			// editor available immediately; completion messages later wake the main agent.
 			if (params.tasks && params.tasks.length > 0) {
-				if (params.tasks.length > MAX_PARALLEL_TASKS) {
-					return {
-						content: [
-							{ type: "text", text: `Too many parallel tasks (${params.tasks.length}). Max is ${MAX_PARALLEL_TASKS}.` },
-						],
-						details: makeDetails("parallel", true)([]),
-					};
-				}
+			if (params.tasks.length > config.maxParallelTasks) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Too many parallel tasks (${params.tasks.length}). Max is ${config.maxParallelTasks} (configurable via /subagents-setup).`,
+						},
+					],
+					details: makeDetails("parallel", true)([]),
+				};
+			}
 				const results = params.tasks.map((task) => startBackground(task.agent, task.task, task.cwd));
 				const started = results.filter((result) => result.exitCode === -1).length;
@@ -327,7 +339,7 @@ export default function (pi: ExtensionAPI): void {
 							type: "text",
 							text:
 								started > 0
-									? `Started ${started} background subagent${started === 1 ? "" : "s"}. Completed results will be added before a later user prompt.`
+									? `Started ${started} background subagent${started === 1 ? "" : "s"}. Results will automatically resume the main agent when ready.`
 									: failures.map((result) => getResultOutput(result)).join("\n"),
 						},
 					],
@@ -346,7 +358,7 @@ export default function (pi: ExtensionAPI): void {
 				};
 			}
 			return {
-				content: [{ type: "text", text: `Started ${result.agent} in the background. Its completed result will be added before a later user prompt.` }],
+				content: [{ type: "text", text: `Started ${result.agent} in the background. Its result will automatically resume the main agent when ready.` }],
 				details: makeDetails("single", true)([result]),
 				terminate: true,
 			};

package/src/prompt.ts CHANGED Viewed

@@ -17,7 +17,6 @@ import { formatCatalogEntry } from "./agents.ts";
 /** Compact role routing hints, emitted only for roles that are enabled. */
 const ROLE_ROUTING: Record<string, string> = {
 	explore: "explore — broad/open-ended code search, \"where is X\", multi-file lookups (read-only, cheap).",
-	plan: "plan — a separate, human-reviewable implementation plan before any code (read-only).",
 	worker: "worker — implement/fix/refactor/test a well-scoped task (full tools; plans internally).",
 	reviewer: "reviewer — adversarial pre-commit review of a diff (read-only; independent context).",
 };
@@ -38,18 +37,18 @@ export function buildDelegationDirective(agents: AgentConfig[]): string {
 ## Sub-agent delegation (pi-subagents)
 You have a \`subagent\` tool that starts specialized agents in ISOLATED background processes.
-It immediately ends the current main-agent turn so the user can keep working. Completed
-findings are added before a later user prompt; do not assume a launched result is available
-in the same turn.
+It immediately ends the current main-agent turn so the user can keep working. When a child
+finishes, its result is sent back as a message that automatically resumes the main agent;
+if the main agent is busy, the result waits as a follow-up.
 Available agents:
 ${catalog}
 ${routing ? `Routing:\n${routing}\n` : ""}Dispatch discipline:
-- Default to delegating every discrete task to a sub-agent; use completed findings in a later user turn for orchestration and verification.
+- Default to delegating every discrete task to a sub-agent; use the automatically delivered findings for orchestration and verification.
 - Only handle inline: pure Q&A, a single trivial edit/lookup, or when the user explicitly says to do it directly. When in doubt, delegate.
 - For an already-known or trivial target, use a direct search/read tool (e.g. grep/find/read) — do not over-delegate a one-line lookup.
-${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `tasks` array, and track them with your todo list. Launch dependent work only after its prerequisite result arrives (e.g. explore, then worker, then reviewer).\n" : ""}- Brief each sub-agent as self-contained: goal, exact paths, constraints, expected output. It has NO memory of this conversation.
+${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `tasks` array, and track them with your todo list. Let the automatically resumed main agent launch dependent work only after its prerequisite result arrives (e.g. explore, then worker, then reviewer).\n" : ""}- Brief each sub-agent as self-contained: goal, exact paths, constraints, expected output. It has NO memory of this conversation.
 - Treat delegated agents as leaf workers: do not ask a sub-agent to dispatch another sub-agent; child processes do not have this tool.
 - Trust but verify: a sub-agent's summary describes intent, not outcome. Check the actual changes/results before reporting work done.

package/src/setup.ts CHANGED Viewed

@@ -14,6 +14,8 @@ import {
 	BUILTIN_AGENT_NAMES,
 	DEFAULT_CONFIG,
 	DEFAULT_ENABLED_AGENTS,
+	DEFAULT_MAX_CONCURRENCY,
+	DEFAULT_MAX_PARALLEL_TASKS,
 	THINKING_LEVEL_VALUES,
 	type AgentScope,
 	type SubagentsConfig,
@@ -31,7 +33,6 @@ const INHERIT = "__inherit__";
 /** Short, selection-friendly descriptions for the built-in agents. */
 const MODULE_HINTS: Record<string, string> = {
 	explore: "read-only codebase recon (fast model)",
-	plan: "implementation plan before code (opt-in)",
 	worker: "implement / fix / refactor / test (full tools)",
 	reviewer: "adversarial pre-commit review (read-only)",
 };
@@ -129,6 +130,29 @@ async function pickInjection(ctx: ExtensionCommandContext, current: boolean): Pr
 	return choice.startsWith("On");
 }
+/** Preset steps offered for the two numeric limits (selection-only wizard). */
+const CONCURRENCY_STEPS = [1, 2, 3, 4, 6, 8, 12, 16];
+const PARALLEL_TASK_STEPS = [2, 4, 6, 8, 12, 16, 24, 32];
+async function pickCount(
+	ctx: ExtensionCommandContext,
+	title: string,
+	steps: readonly number[],
+	current: number,
+	defaultValue: number,
+): Promise<number | undefined> {
+	const values = [...new Set([...steps, current])].sort((a, b) => a - b);
+	const options = values.map((value) => {
+		const tags = [value === current ? "current" : "", value === defaultValue ? "default" : ""]
+			.filter(Boolean)
+			.join(", ");
+		return tags ? `${value} (${tags})` : String(value);
+	});
+	const choice = await ctx.ui.select(title, options);
+	if (choice === undefined) return undefined;
+	return Number.parseInt(choice, 10);
+}
 async function pickScope(ctx: ExtensionCommandContext, current: AgentScope): Promise<AgentScope | undefined> {
 	const labels: Record<AgentScope, string> = {
 		user: "user — built-in + ~/.pi/agent/agents (default)",
@@ -190,12 +214,33 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 	const scope = await pickScope(ctx, base.agentScope);
 	if (scope === undefined) return notifyCancelled(ctx);
+	const maxConcurrency = await pickCount(
+		ctx,
+		"Max sub-agents running at once? (extra work queues)",
+		CONCURRENCY_STEPS,
+		base.maxConcurrency,
+		DEFAULT_MAX_CONCURRENCY,
+	);
+	if (maxConcurrency === undefined) return notifyCancelled(ctx);
+	const maxParallelTasks = await pickCount(
+		ctx,
+		"Max tasks in one parallel subagent call?",
+		PARALLEL_TASK_STEPS,
+		base.maxParallelTasks,
+		DEFAULT_MAX_PARALLEL_TASKS,
+	);
+	if (maxParallelTasks === undefined) return notifyCancelled(ctx);
 	const next: SubagentsConfig = {
 		enabledAgents: enabled,
 		agentModels: repairStaleModels(ctx, models),
 		thinkingLevel,
 		proactiveInjection: injection,
 		agentScope: scope,
+		maxConcurrency,
+		maxParallelTasks,
+		maxSubagentDepth: base.maxSubagentDepth,
 	};
 	await saveConfig(next, configPath);
 	ctx.ui.notify(`pi-subagents configured. Saved to ${configPath}`, "info");
@@ -208,6 +253,8 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 		"Change thinking strength",
 		"Toggle proactive injection",
 		"Change agent scope",
+		"Change max concurrent sub-agents",
+		"Change max parallel tasks",
 		"Full re-setup",
 	]);
 	if (choice === undefined) return notifyCancelled(ctx);
@@ -236,6 +283,26 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 		const scope = await pickScope(ctx, config.agentScope);
 		if (scope === undefined) return notifyCancelled(ctx);
 		next.agentScope = scope;
+	} else if (choice.startsWith("Change max concurrent")) {
+		const maxConcurrency = await pickCount(
+			ctx,
+			"Max sub-agents running at once? (extra work queues)",
+			CONCURRENCY_STEPS,
+			config.maxConcurrency,
+			DEFAULT_MAX_CONCURRENCY,
+		);
+		if (maxConcurrency === undefined) return notifyCancelled(ctx);
+		next.maxConcurrency = maxConcurrency;
+	} else if (choice.startsWith("Change max parallel")) {
+		const maxParallelTasks = await pickCount(
+			ctx,
+			"Max tasks in one parallel subagent call?",
+			PARALLEL_TASK_STEPS,
+			config.maxParallelTasks,
+			DEFAULT_MAX_PARALLEL_TASKS,
+		);
+		if (maxParallelTasks === undefined) return notifyCancelled(ctx);
+		next.maxParallelTasks = maxParallelTasks;
 	}
 	await saveConfig(next, configPath);

package/src/spawn.ts CHANGED Viewed

@@ -20,12 +20,13 @@ import type { Message } from "@earendil-works/pi-ai";
 import type { AgentConfig, AgentSource } from "./agents.ts";
 import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
-export const MAX_PARALLEL_TASKS = 8;
-export const MAX_CONCURRENCY = 4;
+/**
+ * Limits are configurable: see maxConcurrency / maxParallelTasks /
+ * maxSubagentDepth in config.ts (defaults 4 / 8 / 1, via /subagents-setup
+ * or pi-subagents.json).
+ */
 /** Default thinking level for sub-agents. pi clamps it to the resolved model's support. */
 export const SUBAGENT_THINKING_LEVEL: ThinkingLevel = DEFAULT_THINKING_LEVEL;
-/** Child processes are leaf agents: they never receive the subagent tool. */
-export const MAX_SUBAGENT_DEPTH = 1;
 export const DEPTH_ENV_VAR = "PI_SUBAGENT_DEPTH";
 /** No default deadline: sub-agents may run until completion or explicit cancellation. */
 export const SUBAGENT_TIMEOUT_MS = 0;

package/README-zh.md DELETED Viewed

@@ -1,158 +0,0 @@
-# pi-subagents
-[![npm version](https://img.shields.io/npm/v/@ferris1225/pi-subagents?color=blue)](https://www.npmjs.com/package/@ferris1225/pi-subagents)
-[![downloads](https://img.shields.io/npm/dm/@ferris1225/pi-subagents)](https://www.npmjs.com/package/@ferris1225/pi-subagents)
-[![license](https://img.shields.io/npm/l/@ferris1225/pi-subagents)](./LICENSE)
-![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
-![pi](https://img.shields.io/badge/pi-extension-orange)
-[English](./README.md) | 中文
-一个聚焦的 [pi](https://pi.dev) 扩展，给主模型提供**它真的会去用**的 sub-agent：
-`explore`、`worker`、`reviewer`（外加可选的 `plan`），每个都跑在独立的 `pi` 进程里。
-真正的差异点不是 agent 本身，而是**主动派发注入**——让模型自己主动去委派任务，
-于是你可以把全局 `AGENTS.md` 里那两段派发/审查规则删掉。
-## 为什么选 pi-subagents？
-pi 故意不内置 sub-agent。社区的补位方案分两种，但都没踩中：
-- **太重** —— 9 个 agent、链式流水线、worktree 集群、到处都是 slash 命令。强大，但机器太多。
-- **太安静** —— 只给一个 `subagent` 工具，模型**很少主动调用**，因为 pi 只把工具本身展示给主模型，
-  从不展示每个 agent 的描述。于是除非你在全局提示词里强制，否则这些 agent 一直吃灰。
-`pi-subagents` 走中间路线：
-| 优势 | 对你意味着什么 |
-|------|----------------|
-| **真的会被用** | `before_agent_start` hook 每轮把 agent 清单 + 派发/审查指令注入系统提示词，再由 tool `promptGuidelines` 和 `Use PROACTIVELY when …` 描述加强。这正是重型框架依赖的那根杠杆——我们只是把它变成默认行为。 |
-| **体量合适** | 3 个聚焦的 agent（+1 可选），不是 9 个。没有链式/worktree/集群机器。只有 single 和 parallel 两种模式。 |
-| **替代你的 AGENTS.md 规则** | 注入的指令是 "Sub-agent Dispatch" 和 "Review, Verification & Commit" 两段的自包含替代。装上它，然后把那两段删掉。 |
-| **真隔离** | 每个 agent 都是独立 `pi` 进程（`--no-session`），委派出去的活绝不污染主上下文。 |
-| **该只读就只读** | `explore`、`plan`、`reviewer` 都是只读。`reviewer` 跑在**独立**上下文，避免自我确认偏差。 |
-| **纯选择式配置** | 不用手敲值：勾选式模块选择器 + 模糊过滤、可翻页的模型选择器。 |
-| **合理的模型默认** | 每 agent 可单独覆盖模型；不选就**用主窗口当前 session 的模型**。配置中的不可用模型会自动修复并写回。 |
-| **子代理是叶节点** | 子进程不会获得 `subagent` 工具，因此不会递归派发或无限运行。 |
-| **零运行时依赖** | 纯 pi 扩展，仅 peer 依赖，无需构建步骤。 |
-## 安装
-```bash
-pi install npm:@ferris1225/pi-subagents
-```
-要求 pi **≥ 0.80.6**——子代理思考强度使用该版本引入的 `--thinking` 参数值。
-然后运行配置向导（纯选择）：
-```text
-/subagents-setup
-```
-## Agent 一览
-| Agent | 默认启用 | 工具 | 职责 |
-|-------|:--------:|------|------|
-| `explore` | ✅ | 只读 | 快速代码侦察；返回压缩后的发现以便交接。 |
-| `worker` | ✅ | 全部 | 实现/修复/重构/测试一个自包含任务。**内部先规划后动手。** |
-| `reviewer` | ✅ | 只读 | 在独立上下文做对抗式提交前审查。 |
-| `plan` | 可选 | 只读 | 产出可人工审阅的独立实现计划。worker 本就会内部规划，所以只在你需要把计划作为独立产物时才用它。 |
-每个 agent 都是一个 Markdown 文件（`agents/*.md`：YAML frontmatter + 正文作为 system prompt）。
-想覆盖任意一个，只需把同名 `name` 的文件放进 `~/.pi/agent/agents/`（用户级）或 `.pi/agents/`（项目级）。
-## 主动派发是怎么工作的
-pi 从不把每个 agent 的描述展示给主模型——它只看到 `subagent` 这个工具。三根杠杆解决这一点：
-1. **`before_agent_start` 注入** —— 每一轮，把启用的 agent 加上一段派发/审查指令追加进父模型系统提示词。
-2. **tool `promptSnippet` / `promptGuidelines`** —— 在工具激活时持续强化「何时该委派」。
-3. **`Use PROACTIVELY when …` 描述** —— 在 Claude Code agent 生态被验证过的触发措辞。
-这段指令会引导出一条干净的流程：**`explore` → `worker` → `reviewer`**，独立任务并行扇出，
-以及「信任但需验证」的交接。由于子代理在后台运行，依赖前序结果的步骤必须等结果送达后再启动。
-## 配置
-存放在 `~/.pi/agent/pi-subagents.json`（尊重 `PI_CODING_AGENT_DIR`）：
-```json
-{
-  "enabledAgents": ["explore", "worker", "reviewer"],
-  "agentModels": { "explore": "anthropic/claude-haiku-4-5" },
-  "thinkingLevel": "max",
-  "proactiveInjection": true,
-  "agentScope": "user"
-}
-```
-- `enabledAgents` —— 哪些 agent 可被发现并注入。
-- `agentModels` —— 每 agent 的模型覆盖（`"provider/model-id"`）。如果已保存的模型不可用，会切换到主窗口当前模型并写回此文件。
-- `thinkingLevel` —— 子代理思考强度：`off`、`minimal`、`low`、`medium`、`high`、`xhigh` 或 `max`（默认）。
-- `proactiveInjection` —— 开关系统提示词注入。
-- `agentScope` —— `"user"`（默认）、`"project"` 或 `"both"`。
-**每个 agent 的模型优先级**：
-```
-可用的 agentModels[name]  →  当前 session 模型  →  agent frontmatter 里的默认
-```
-如果配置的模型不再可用，会切换到主窗口当前模型，并在下一次运行前写回配置文件。
-## 使用
-主模型会自己调用 `subagent`，你也可以直接要求：
-```text
-# 单个
-用 explore sub-agent 梳理一下认证是怎么接起来的。
-# 并行（独立任务）
-用并行 sub-agent 跑这两件：探索 API 层，以及探索 DB 层。
-```
-工具参数形态：
-```jsonc
-// 单个
-{ "agent": "worker", "task": "<自包含的任务简报>" }
-// 并行
-{ "tasks": [ { "agent": "explore", "task": "..." }, { "agent": "explore", "task": "..." } ] }
-```
-所有子代理默认在后台启动。工具会立即结束当前主代理回合，编辑器可直接继续输入，
-无需按 Escape；完成输出会显示出来，并在后续用户请求前加入上下文。启动完成后，
-Escape 只中止前台工作；切换会话、`/reload` 或退出才会清理仍在运行的后台进程。
-## 实时状态与通知
-子代理运行期间，编辑器上方的挂件为每个运行显示一行状态（图标、agent、模型、
-token 用量、耗时），其下缩进一行显示它正在做什么：`thinking`、`responding`、
-`read src/index.ts`、`bash npm test`……（不会是一坨 JSON 参数）。
-`responding` 表示模型正在流式输出普通文本，**不**表示向文件系统写入。
-运行结束（成功**或**失败）时，该行立即从挂件消失，主窗口收到一条通知，
-给出最终摘要（`✓ worker · openai/gpt-5 · ↑12.4k ↓3.1k · 47s`）。完成结果消息
-才是对话中持久保留、并会供后续请求使用的记录。
-子代理使用配置的思考强度（默认 `--thinking max`）；pi 会按目标模型实际支持
-的级别自适应降级（`max → xhigh → high → … → off`），弱模型也能平稳运行。
-任务内容通过 stdin 传递，只有 agent system prompt 使用短生命周期临时文件。
-子进程输出在内存中流式处理；默认不设运行时限，只有显式中止时才清理整个进程树。
-## 开发
-```bash
-npm install
-npm run check   # tsc --noEmit
-npm test        # vitest
-```
-## 相关项目
-- [pi-querit-search](https://www.npmjs.com/package/pi-querit-search) —— 为 pi 提供实时网络搜索与网页抓取，同一作者。
-## 许可证
-MIT

package/agents/plan.md DELETED Viewed

@@ -1,41 +0,0 @@
----
-name: plan
-description: Implementation planning for non-trivial changes (opt-in). Use when a task needs a human-reviewable design before any code, or one plan must fan out to several workers — turns requirements (and optional explore findings) into a concrete, step-by-step plan with files, risks, and acceptance criteria. Read-only; never edits. Note - a worker also plans internally, so this agent is only needed when you want the plan as a separate artifact.
-tools: read, grep, find, ls, bash
-model: claude-sonnet-4-5
-# Model selection: REASONING + STRUCTURE. Use a strong reasoning model.
----
-You are a planning specialist. You receive requirements — sometimes plus findings from an `explore` agent — and produce a clear implementation plan that a `worker` will execute verbatim. You have NOT got the caller's conversation history.
-## Hard constraints
-- You must NOT make any changes. Only read, analyze, and plan.
-- Bash is read-only: `grep`, `find`, `ls`, `cat`, `git log/show/diff`. No installs, builds, or edits.
-- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
-## When invoked
-1. Restate the goal in one sentence. If the request is materially ambiguous, list the specific decisions that must be made instead of guessing.
-2. Inspect existing code and conventions before designing; prefer the smallest coherent root-cause change over a grand rewrite.
-3. Produce small, ordered, independently-verifiable steps. Each step names the file/function to touch and the change.
-4. Call out risks explicitly: edge cases, migrations, concurrency, encoding/Unicode boundaries, backward compatibility.
-## Collaboration
-- Consumes `explore` output when provided; if context is missing, say what an explore should retrieve.
-- Feeds `worker`: keep steps concrete enough to execute without re-deriving the design.
-## Output format
-## Goal
-One sentence.
-## Plan
-1. Step — specific file/function to modify and what changes.
-## Files to Modify
-- `path/to/file.ts` — what changes and why.
-## New Files (if any)
-- `path/to/new.ts` — responsibility.
-## Risks
-What to watch out for, and how to mitigate.
-## Acceptance
-How to verify correctness: commands, tests, expected behavior.
-## Quality standards
-Concrete and minimal. No prose to fill space. Every step is actionable and verifiable.