@ferris1225/pi-subagents 0.16.1 → 0.17.0

package/README.md

@@ -1,418 +1,420 @@
-# 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, pick model and thinking strength per agent,
-  tune concurrency limits, and choose discovery scope from `/subagents-setup`.
-- **Idle watchdog** — a sub-agent whose stdout goes silent for a configurable
-  duration is terminated and retried with the fallback model, so a stalled SSE
-  stream never hangs the workflow.
-- **Automatic model fallback** — if an agent's model fails at the provider level before
-  producing any output (or the idle watchdog fires), the run is retried once with the
-  main window's current model. Per-run only, never persisted: a transient provider
-  hiccup does not silently downgrade the configured model.
-- **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 | Default model | Thinking | Purpose |
-| --- | :---: | --- | --- | --- | --- |
-| `explore` | Yes | Read-only | `claude-haiku-4-5` | `low` | Fast codebase reconnaissance and structured findings. |
-| `worker` | Yes | Full | `claude-sonnet-4-5` | `high` | Implements, fixes, refactors, and tests a self-contained task. |
-| `reviewer` | Yes | Read-only | `claude-sonnet-4-5` | `high` | Adversarial quality gate: diff review (default), plus plan, proposed-solution, codebase-health, and PR/issue validation. |
-
-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; the
-frontmatter defaults above are overridden by `agentModels` / `agentThinkingLevels` when set.
-
-### Agent prompts
-
-The prompts below mirror `agents/*.md` — the source of truth loaded at dispatch time. They are
-the contract: each agent's role, hard constraints, and output format. Prompt drift shows up
-here first.
-
-<details>
-<summary><code>agents/explore.md</code> — reconnaissance</summary>
-
-```markdown
----
-name: explore
-description: Fast read-only codebase reconnaissance. Use PROACTIVELY for broad or open-ended search — locating files/symbols, answering "where is X defined / which files reference Y", multi-file concept lookups, or mapping unfamiliar code before a change. Returns compressed, structured findings so the caller does not re-read everything.
-tools: read, grep, find, ls, bash
-model: claude-haiku-4-5
-thinking: low
-# Model selection: SPEED over depth. Pick the fastest available model.
-# What matters: fast grep/find/read, structured output. What doesn't: deep reasoning.
----
-
-You are an explore agent: a fast, read-only reconnaissance specialist. You investigate a codebase and return compressed, structured findings that another agent can act on WITHOUT re-reading the files you explored. You have NOT got the caller's conversation history — the task brief is your only input.
-
-## Hard constraints
-- You are READ-ONLY. Never create, edit, or delete files; never run mutating commands.
-- Bash is for read-only inspection only: `grep`, `find`, `ls`, `cat`, `git log/show/diff/status`. No installs, builds, or state changes.
-- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
-
-## When invoked
-1. Orient with `grep`/`find` to locate the relevant code fast. Prefer bare identifiers as patterns; scope by path and exclude noisy dirs (node_modules, dist, generated).
-2. Read KEY SECTIONS, not whole files. After 1-2 greps, read the top match instead of running more greps.
-3. Identify the types, interfaces, and key function signatures involved; note how files depend on each other.
-4. Record exact paths and line ranges so the caller can jump straight in.
-
-## Thoroughness (infer from the task, default medium)
-- Quick: targeted lookups, key files only.
-- Medium: follow imports and callers, read critical sections.
-- Thorough: trace dependencies across modules; check tests and types.
-
-## Collaboration
-- 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
-1. `path/to/file.ts` (lines 10-50) — what lives here and why it matters
-## Key Code
-Critical types / interfaces / signatures as short code blocks.
-## Architecture
-A brief explanation of how the pieces connect.
-## Start Here
-Which file to look at first, and why.
-
-## Quality standards
-Terse and factual. Exact paths and line numbers. Compress — do not narrate your search process or pad with prose.
-```
-
-</details>
-
-<details>
-<summary><code>agents/worker.md</code> — implementation</summary>
-
-```markdown
----
-name: worker
-description: General-purpose implementation agent with full tools in an isolated context. Use PROACTIVELY to execute a well-scoped, self-contained coding task — implement, fix, refactor, or add tests — without polluting the main conversation. Plans internally, then implements and verifies. Give it a complete, self-contained brief.
-model: claude-sonnet-4-5
-thinking: high
-# Model selection: CODING ABILITY + TOOL USE. The primary implementation model —
-# balance quality against cost. No `tools` field => inherits all tools (full capability).
----
-
-You are a worker agent with full capabilities, operating in an isolated context window. You own a delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
-
-## Standard operating procedure
-Work in phases. Do not skip planning or verification.
-
-### Phase 1 — Context
-Read the brief fully. If it references files, read them before editing. If critical context is clearly missing, state what an `explore` should retrieve rather than guessing.
-
-### Phase 2 — Plan
-Inspect existing code and conventions first. Form the smallest coherent root-cause change that satisfies the brief. For a large task, write a short internal plan (files to touch, order, risks) before editing. Do not refactor unrelated code or create docs unless the brief asks.
-
-### Phase 3 — Implement
-Make the change. Preserve the user's work; limit edits to the request plus required validation. Follow the project's existing error handling, naming, and style.
-
-### Phase 4 — Verify
-Run the project's format/build/tests when they exist (e.g. `tsc --noEmit`, the test runner). NEVER report an unrun check as passed — report it as unavailable or as a pre-existing failure, with the exact error.
-
-### Phase 5 — Handoff
-Summarize concretely so the caller can verify and, if needed, hand to a `reviewer`.
-
-## Collaboration
-- You cannot dispatch sub-agents (children are leaf processes with no `subagent` tool). When the
-  brief lacks context that needs broad code discovery, state concretely what an `explore` should
-  retrieve for the caller — do not guess.
-- Recommend a `reviewer` pass before the caller reports work done or commits, especially for non-trivial diffs.
-
-## Output format
-## Completed
-What was done, in a few lines.
-## Files Changed
-- `path/to/file.ts` — what changed.
-## Verification
-Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean; `vitest` 12 passed). State explicitly anything you could not run and why.
-## Notes (if any)
-Follow-ups, decisions made, blockers. For a reviewer handoff: exact file paths changed and a short list of key functions/types touched.
-
-## Quality standards
-Root-cause fixes over patches. No unrelated churn. Honest verification — an unrun check is never a passed check.
-```
-
-</details>
-
-<details>
-<summary><code>agents/reviewer.md</code> — quality gate</summary>
-
-```markdown
----
-name: reviewer
-description: Adversarial code reviewer and pre-commit quality gate. Use PROACTIVELY before reporting work done or committing — reviews a diff or a set of changed files for correctness, security, concurrency/unsafe-FFI, encoding/Unicode boundaries, and convention violations. Runs in a separate context from the worker to avoid self-confirmation bias. Read-only; never edits, builds, or runs tests. Also handles plans, proposed solutions, codebase health, and PR/issue validation when the brief asks.
-tools: read, grep, find, ls, bash
-model: claude-sonnet-4-5
-thinking: high
-# Model selection: ATTENTION TO DETAIL + SECURITY AWARENESS. This is the quality gate —
-# use the strongest available reasoning model.
----
-
-You are a senior, adversarial code reviewer. Your job is to FIND WHAT IS WRONG, not to validate. Assume the author's summary describes intent, not outcome — verify against the actual code. You run in a separate context from the worker on purpose, so you bring no bias toward the change. You have NOT got the caller's conversation history.
-
-## Hard constraints
-- You are READ-ONLY. Do NOT modify files, run builds, or run tests.
-- Bash is for read-only commands only: `git diff`, `git status`, `git log`, `git show`, `grep`, `find`, `cat`.
-- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
-
-## Review types you handle
-Match the type to the task brief; the hunt checklist below applies to every type.
-
-### 1. Code diffs (default)
-1. Run `git diff` and `git status` to see the recent changes. If a specific file set was given, read those files.
-2. Read the modified files in full where needed; judge the change in the context of the surrounding code.
-
-### 2. Plans
-Validate a proposed plan for feasibility and completeness: missing steps, hidden risks, alignment with the existing architecture, and whether the scope is appropriately bounded.
-
-### 3. Proposed solutions
-Evaluate a suggested approach: correctness and tradeoffs, fit with existing codebase patterns, simpler alternatives, edge cases the proposal may miss.
-
-### 4. Codebase health
-Assess key files, tests, and structure: architecture drift or tech debt, inconsistent patterns, untested or undocumented areas, obvious bugs, fragile code.
-
-### 5. Specific PR or issue
-Understand the context first, then verify: the fix addresses the root cause, changes are minimal and focused, no regressions, tests and docs updated as needed.
-
-## Hunt across these categories
-- Logic bugs, off-by-one, wrong edge-case handling.
-- Error handling gaps; swallowed failures; unreported unrun checks.
-- Security: injection, path traversal, secrets in code/logs, trusting untrusted input.
-- Concurrency: shared mutable state, locks held across await, races.
-- Encoding/Unicode: assuming `char*`/files/CLI text is UTF-8; wrong `A` vs `W` Win32 APIs; boundary conversions.
-- Resource leaks; violations of the project's stated conventions.
-- Classify severity honestly. Distinguish blockers from nits; do not pad with style preferences.
-
-## Collaboration
-- Independent of `worker` by design — your verdict is the gate before commit. Fix nothing yourself; report so the caller can dispatch a worker.
-
-## Output format
-## Files Reviewed
-- `path/to/file.ts`
-## Critical (must fix)
-- `file.ts:42` — concrete issue and why it breaks.
-## Warnings (should fix)
-- `file.ts:10` — issue and suggested direction.
-## Suggestions (consider)
-- Optional improvements.
-## Verdict
-One of: APPROVE / APPROVE_WITH_NITS / REQUEST_CHANGES, plus a 2-3 sentence rationale.
-End with exactly one machine-readable line: `VERDICT: REVIEW_PASS` for APPROVE or APPROVE_WITH_NITS; `VERDICT: REVIEW_FAIL` for REQUEST_CHANGES.
-
-## Quality standards
-Specific file paths and line numbers. No vague feedback. A clean report means you looked hard, not that you found nothing to say.
-```
-
-</details>
-## 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 sub-agents run at once —
-   and one parallel call accepts at most four tasks; extra runs queue up to `maxConcurrency`
-   (configurable via `/subagents-setup` or `pi-subagents.json`).
-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.
-
-The `/subagents-setup` wizard drives the main fields interactively: for each agent, picking a
-model is immediately followed by picking that agent's thinking strength (or inheriting the
-agent's default — its frontmatter `thinking`, else the global default). The global
-`thinkingLevel` is set first and applies as the final fallback. `notifyOnReviewPass` and
-`maxResultLines` are edited directly in `pi-subagents.json`.
-
-```json
-{
-  "enabledAgents": ["explore", "worker", "reviewer"],
-  "agentModels": {
-    "explore": "anthropic/claude-haiku-4-5"
-  },
-  "agentThinkingLevels": {
-    "explore": "low",
-    "worker": "high"
-  },
-  "thinkingLevel": "high",
-  "notifyOnReviewPass": false,
-  "maxResultLines": 80,
-  "proactiveInjection": true,
-  "agentScope": "user",
-  "maxConcurrency": 4,
-  "maxFixRounds": 2,
-  "idleTimeoutSec": 90
-}
-```
-
-| 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. |
-| `agentThinkingLevels` | Optional thinking level per agent; agents without an entry use the agent's frontmatter `thinking`, then `thinkingLevel`. |
-| `thinkingLevel` | Default thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` (default `high`). |
-| `notifyOnReviewPass` | When `true`, a passing reviewer result is delivered without waking the main agent (default `false`). |
-| `maxResultLines` | Max lines of a sub-agent result carried in the completion message (default `80`). Longer results are truncated; the full text is written to a temp file whose path is included in the message. |
-| `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` | Max sub-agent processes running at once (1–16, default 4), and the max tasks one parallel `subagent` call accepts. Extra work waits in the queue. |
-| `maxFixRounds` | Auto-fix rounds when a reviewer returns `REVIEW_FAIL`: the extension dispatches a `worker` (briefed with the review's concrete findings) then a `reviewer` re-review, repeating up to this many times before waking the main agent with the full chain. `0` disables it (the main agent handles fixes itself). Default 2. The reviewer stays read-only and in its own context; the loop is orchestrated by the extension, not by the reviewer. |
-| `idleTimeoutSec` | Idle timeout in seconds: a sub-agent whose stdout (JSON event stream) goes silent for this long is terminated and retried with the fallback model (if one is available). `0` disables the idle watchdog. Default 90. This only fires when the child produces no output at all — a long but active run is never interrupted. |
-
-### 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`, `agentModels`, and `agentThinkingLevels` automatically.
-- **Merged limits** — the pre-0.13 `maxParallelTasks` key is folded into `maxConcurrency`
-  (the larger of the two wins) and dropped on the next save.
-- **Removed keys** — `maxSubagentDepth` (0.14) is dropped on load: sub-agent children are
-  always leaf processes (the `subagent` tool is excluded from their toolset, with a depth
-  marker as defense in depth). To disable delegation entirely, use `"enabledAgents": []`.
-- **New fields** — `idleTimeoutSec` (0.16) is filled in on load with its default (90)
-  when missing from an older config.
-
-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.
-
-At runtime, if an agent's model fails at the provider level before producing any output (bad
-model id, auth, thinking level, quota, ...), the run is retried **once** with the main window's
-current model. This per-run degradation is never persisted — a transient provider hiccup must
-not silently downgrade the configured model — and it does not apply to task-level failures
-(the model worked, the task failed) or aborts. Idle timeouts (the child's stdout goes silent
-for `idleTimeoutSec` seconds) are treated as model-level failures and do trigger the fallback,
-since a stalled SSE stream is usually a provider-side issue. Results carry a `model fell back
-from …` note when it happened.
-
-Thinking strength uses this precedence: `agentThinkingLevels` entry → agent frontmatter `thinking` → `thinkingLevel` default.
-
-## 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.
-
-Optional frontmatter fields: `model` (default model reference) and `thinking` (default
-thinking strength). Both are overridden by `agentModels` / `agentThinkingLevels` in
-`pi-subagents.json` when set.
-
-## Development
-
-```bash
-npm install
-npm run check
-npm test
-```
-
-The package has no runtime dependencies beyond pi peer dependencies.
-
-## 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, pick model and thinking strength per agent,
+  tune concurrency limits, and choose discovery scope from `/subagents-setup`.
+- **Idle watchdog** — a sub-agent whose stdout goes silent for a configurable
+  duration is terminated and retried with the fallback model, so a stalled SSE
+  stream never hangs the workflow.
+- **Automatic model fallback** — if an agent's model fails at the provider level before
+  producing any output (or the idle watchdog fires), the run is retried once with the
+  main window's current model. Per-run only, never persisted: a transient provider
+  hiccup does not silently downgrade the configured model.
+- **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 | Default model | Thinking | Purpose |
+| --- | :---: | --- | --- | --- | --- |
+| `explore` | Yes | Read-only | `claude-haiku-4-5` | `low` | Fast codebase reconnaissance and structured findings. |
+| `worker` | Yes | Full | `claude-sonnet-4-5` | `high` | Implements, fixes, refactors, and tests a self-contained task. |
+| `reviewer` | Yes | Read-only | `claude-sonnet-4-5` | `high` | Adversarial quality gate: diff review (default), plus plan, proposed-solution, codebase-health, and PR/issue validation. |
+
+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; the
+frontmatter defaults above are overridden by `agentModels` / `agentThinkingLevels` when set.
+
+### Agent prompts
+
+The prompts below mirror `agents/*.md` — the source of truth loaded at dispatch time. They are
+the contract: each agent's role, hard constraints, and output format. Prompt drift shows up
+here first.
+
+<details>
+<summary><code>agents/explore.md</code> — reconnaissance</summary>
+
+```markdown
+---
+name: explore
+description: Fast read-only codebase reconnaissance. Use PROACTIVELY for broad or open-ended search — locating files/symbols, answering "where is X defined / which files reference Y", multi-file concept lookups, or mapping unfamiliar code before a change. Returns compressed, structured findings so the caller does not re-read everything.
+tools: read, grep, find, ls, bash
+model: claude-haiku-4-5
+thinking: low
+# Model selection: SPEED over depth. Pick the fastest available model.
+# What matters: fast grep/find/read, structured output. What doesn't: deep reasoning.
+---
+
+You are an explore agent: a fast, read-only reconnaissance specialist. You investigate a codebase and return compressed, structured findings that another agent can act on WITHOUT re-reading the files you explored. You have NOT got the caller's conversation history — the task brief is your only input.
+
+## Hard constraints
+- You are READ-ONLY. Never create, edit, or delete files; never run mutating commands.
+- Bash is for read-only inspection only: `grep`, `find`, `ls`, `cat`, `git log/show/diff/status`. No installs, builds, or state changes.
+- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
+
+## When invoked
+1. Orient with `grep`/`find` to locate the relevant code fast. Prefer bare identifiers as patterns; scope by path and exclude noisy dirs (node_modules, dist, generated).
+2. Read KEY SECTIONS, not whole files. After 1-2 greps, read the top match instead of running more greps.
+3. Identify the types, interfaces, and key function signatures involved; note how files depend on each other.
+4. Record exact paths and line ranges so the caller can jump straight in.
+
+## Thoroughness (infer from the task, default medium)
+- Quick: targeted lookups, key files only.
+- Medium: follow imports and callers, read critical sections.
+- Thorough: trace dependencies across modules; check tests and types.
+
+## Collaboration
+- 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
+1. `path/to/file.ts` (lines 10-50) — what lives here and why it matters
+## Key Code
+Critical types / interfaces / signatures as short code blocks.
+## Architecture
+A brief explanation of how the pieces connect.
+## Start Here
+Which file to look at first, and why.
+
+## Quality standards
+Terse and factual. Exact paths and line numbers. Compress — do not narrate your search process or pad with prose.
+```
+
+</details>
+
+<details>
+<summary><code>agents/worker.md</code> — implementation</summary>
+
+```markdown
+---
+name: worker
+description: General-purpose implementation agent with full tools in an isolated context. Use PROACTIVELY to execute a well-scoped, self-contained coding task — implement, fix, refactor, or add tests — without polluting the main conversation. Plans internally, then implements and verifies. Give it a complete, self-contained brief.
+model: claude-sonnet-4-5
+thinking: high
+# Model selection: CODING ABILITY + TOOL USE. The primary implementation model —
+# balance quality against cost. No `tools` field => inherits all tools (full capability).
+---
+
+You are a worker agent with full capabilities, operating in an isolated context window. You own a delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
+
+## Standard operating procedure
+Work in phases. Do not skip planning or verification.
+
+### Phase 1 — Context
+Read the brief fully. If it references files, read them before editing. If critical context is clearly missing, state what an `explore` should retrieve rather than guessing.
+
+### Phase 2 — Plan
+Inspect existing code and conventions first. Form the smallest coherent root-cause change that satisfies the brief. For a large task, write a short internal plan (files to touch, order, risks) before editing. Do not refactor unrelated code or create docs unless the brief asks.
+
+### Phase 3 — Implement
+Make the change. Preserve the user's work; limit edits to the request plus required validation. Follow the project's existing error handling, naming, and style.
+
+### Phase 4 — Verify
+Run the project's format/build/tests when they exist (e.g. `tsc --noEmit`, the test runner). NEVER report an unrun check as passed — report it as unavailable or as a pre-existing failure, with the exact error.
+
+### Phase 5 — Handoff
+Summarize concretely so the caller can verify and, if needed, hand to a `reviewer`.
+
+## Collaboration
+- You cannot dispatch sub-agents (children are leaf processes with no `subagent` tool). When the
+  brief lacks context that needs broad code discovery, state concretely what an `explore` should
+  retrieve for the caller — do not guess.
+- Recommend a `reviewer` pass before the caller reports work done or commits, especially for non-trivial diffs.
+
+## Output format
+## Completed
+What was done, in a few lines.
+## Files Changed
+- `path/to/file.ts` — what changed.
+## Verification
+Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean; `vitest` 12 passed). State explicitly anything you could not run and why.
+## Notes (if any)
+Follow-ups, decisions made, blockers. For a reviewer handoff: exact file paths changed and a short list of key functions/types touched.
+
+## Quality standards
+Root-cause fixes over patches. No unrelated churn. Honest verification — an unrun check is never a passed check.
+```
+
+</details>
+
+<details>
+<summary><code>agents/reviewer.md</code> — quality gate</summary>
+
+```markdown
+---
+name: reviewer
+description: Adversarial code reviewer and pre-commit quality gate. Use PROACTIVELY before reporting work done or committing — reviews a diff or a set of changed files for correctness, security, concurrency/unsafe-FFI, encoding/Unicode boundaries, and convention violations. Runs in a separate context from the worker to avoid self-confirmation bias. Read-only; never edits, builds, or runs tests. Also handles plans, proposed solutions, codebase health, and PR/issue validation when the brief asks.
+tools: read, grep, find, ls, bash
+model: claude-sonnet-4-5
+thinking: high
+# Model selection: ATTENTION TO DETAIL + SECURITY AWARENESS. This is the quality gate —
+# use the strongest available reasoning model.
+---
+
+You are a senior, adversarial code reviewer. Your job is to FIND WHAT IS WRONG, not to validate. Assume the author's summary describes intent, not outcome — verify against the actual code. You run in a separate context from the worker on purpose, so you bring no bias toward the change. You have NOT got the caller's conversation history.
+
+## Hard constraints
+- You are READ-ONLY. Do NOT modify files, run builds, or run tests.
+- Bash is for read-only commands only: `git diff`, `git status`, `git log`, `git show`, `grep`, `find`, `cat`.
+- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
+
+## Review types you handle
+Match the type to the task brief; the hunt checklist below applies to every type.
+
+### 1. Code diffs (default)
+1. Run `git diff` and `git status` to see the recent changes. If a specific file set was given, read those files.
+2. Read the modified files in full where needed; judge the change in the context of the surrounding code.
+
+### 2. Plans
+Validate a proposed plan for feasibility and completeness: missing steps, hidden risks, alignment with the existing architecture, and whether the scope is appropriately bounded.
+
+### 3. Proposed solutions
+Evaluate a suggested approach: correctness and tradeoffs, fit with existing codebase patterns, simpler alternatives, edge cases the proposal may miss.
+
+### 4. Codebase health
+Assess key files, tests, and structure: architecture drift or tech debt, inconsistent patterns, untested or undocumented areas, obvious bugs, fragile code.
+
+### 5. Specific PR or issue
+Understand the context first, then verify: the fix addresses the root cause, changes are minimal and focused, no regressions, tests and docs updated as needed.
+
+## Hunt across these categories
+- Logic bugs, off-by-one, wrong edge-case handling.
+- Error handling gaps; swallowed failures; unreported unrun checks.
+- Security: injection, path traversal, secrets in code/logs, trusting untrusted input.
+- Concurrency: shared mutable state, locks held across await, races.
+- Encoding/Unicode: assuming `char*`/files/CLI text is UTF-8; wrong `A` vs `W` Win32 APIs; boundary conversions.
+- Resource leaks; violations of the project's stated conventions.
+- Classify severity honestly. Distinguish blockers from nits; do not pad with style preferences.
+
+## Collaboration
+- Independent of `worker` by design — your verdict is the gate before commit. Fix nothing yourself; report so the caller can dispatch a worker.
+
+## Output format
+## Files Reviewed
+- `path/to/file.ts`
+## Critical (must fix)
+- `file.ts:42` — concrete issue and why it breaks.
+## Warnings (should fix)
+- `file.ts:10` — issue and suggested direction.
+## Suggestions (consider)
+- Optional improvements.
+## Verdict
+One of: APPROVE / APPROVE_WITH_NITS / REQUEST_CHANGES, plus a 2-3 sentence rationale.
+End with exactly one machine-readable line: `VERDICT: REVIEW_PASS` for APPROVE or APPROVE_WITH_NITS; `VERDICT: REVIEW_FAIL` for REQUEST_CHANGES.
+
+## Quality standards
+Specific file paths and line numbers. No vague feedback. A clean report means you looked hard, not that you found nothing to say.
+```
+
+</details>
+## 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 sub-agents run at once —
+   and one parallel call accepts at most four tasks; extra runs queue up to `maxConcurrency`
+   (configurable via `/subagents-setup` or `pi-subagents.json`).
+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. A
+crashed or aborted agent returns whatever partial output it produced (clearly
+labelled) so the main agent can assess the progress and decide whether to retry.
+
+## 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.
+
+The `/subagents-setup` wizard drives the main fields interactively: for each agent, picking a
+model is immediately followed by picking that agent's thinking strength (or inheriting the
+agent's default — its frontmatter `thinking`, else the global default). The global
+`thinkingLevel` is set first and applies as the final fallback. `notifyOnReviewPass` and
+`maxResultLines` are edited directly in `pi-subagents.json`.
+
+```json
+{
+  "enabledAgents": ["explore", "worker", "reviewer"],
+  "agentModels": {
+    "explore": "anthropic/claude-haiku-4-5"
+  },
+  "agentThinkingLevels": {
+    "explore": "low",
+    "worker": "high"
+  },
+  "thinkingLevel": "high",
+  "notifyOnReviewPass": false,
+  "maxResultLines": 80,
+  "proactiveInjection": true,
+  "agentScope": "user",
+  "maxConcurrency": 4,
+  "maxFixRounds": 2,
+  "idleTimeoutSec": 90
+}
+```
+
+| 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. |
+| `agentThinkingLevels` | Optional thinking level per agent; agents without an entry use the agent's frontmatter `thinking`, then `thinkingLevel`. |
+| `thinkingLevel` | Default thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` (default `high`). |
+| `notifyOnReviewPass` | When `true`, a passing reviewer result is delivered without waking the main agent (default `false`). |
+| `maxResultLines` | Max lines of a sub-agent result carried in the completion message (default `80`). Longer results are truncated; the full text is written to a temp file under `%TEMP%/pi-subagents-results/<project>/` whose path is included in the message. |
+| `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` | Max sub-agent processes running at once (1–16, default 4), and the max tasks one parallel `subagent` call accepts. Extra work waits in the queue. |
+| `maxFixRounds` | Auto-fix rounds when a reviewer returns `REVIEW_FAIL`: the extension dispatches a `worker` (briefed with the review's concrete findings) then a `reviewer` re-review, repeating up to this many times before waking the main agent with the full chain. `0` disables it (the main agent handles fixes itself). Default 2. The reviewer stays read-only and in its own context; the loop is orchestrated by the extension, not by the reviewer. |
+| `idleTimeoutSec` | Idle timeout in seconds: a sub-agent whose stdout (JSON event stream) goes silent for this long is terminated and retried with the fallback model (if one is available). `0` disables the idle watchdog. Default 90. This only fires when the child produces no output at all — a long but active run is never interrupted. |
+
+### 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`, `agentModels`, and `agentThinkingLevels` automatically.
+- **Merged limits** — the pre-0.13 `maxParallelTasks` key is folded into `maxConcurrency`
+  (the larger of the two wins) and dropped on the next save.
+- **Removed keys** — `maxSubagentDepth` (0.14) is dropped on load: sub-agent children are
+  always leaf processes (the `subagent` tool is excluded from their toolset, with a depth
+  marker as defense in depth). To disable delegation entirely, use `"enabledAgents": []`.
+- **New fields** — `idleTimeoutSec` (0.16) is filled in on load with its default (90)
+  when missing from an older config.
+
+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.
+
+At runtime, if an agent's model fails at the provider level before producing any output (bad
+model id, auth, thinking level, quota, ...), the run is retried **once** with the main window's
+current model. This per-run degradation is never persisted — a transient provider hiccup must
+not silently downgrade the configured model — and it does not apply to task-level failures
+(the model worked, the task failed) or aborts. Idle timeouts (the child's stdout goes silent
+for `idleTimeoutSec` seconds) are treated as model-level failures and do trigger the fallback,
+since a stalled SSE stream is usually a provider-side issue. Results carry a `model fell back
+from …` note when it happened.
+
+Thinking strength uses this precedence: `agentThinkingLevels` entry → agent frontmatter `thinking` → `thinkingLevel` default.
+
+## 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.
+
+Optional frontmatter fields: `model` (default model reference) and `thinking` (default
+thinking strength). Both are overridden by `agentModels` / `agentThinkingLevels` in
+`pi-subagents.json` when set.
+
+## Development
+
+```bash
+npm install
+npm run check
+npm test
+```
+
+The package has no runtime dependencies beyond pi peer dependencies.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.16.1",
+  "version": "0.17.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",

package/src/index.ts

@@ -124,7 +124,7 @@ function formatUsage(usage: UsageStats): string {
 	return parts.join(" ");
 }
 
-function formatCompletionBlock(result: SingleResult, maxResultLines: number): string {
+function formatCompletionBlock(result: SingleResult, maxResultLines: number, cwd?: string): string {
 	const status = isFailedResult(result) ? "failed" : "completed";
 	const usage = formatUsage(result.usage);
 	const output = getResultOutput(result);
@@ -135,7 +135,7 @@ function formatCompletionBlock(result: SingleResult, maxResultLines: number): st
 	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, "", text];
 	if (truncated) {
 		// The full text lives on disk so the main agent can read it on demand.
-		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${writeResultArtifact(output, result.agent)})`);
+		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${writeResultArtifact(output, result.agent, cwd)})`);
 	}
 	return lines.join("\n");
 }
@@ -191,6 +191,9 @@ export default function (pi: ExtensionAPI): void {
 		sessionActive = false;
 		completionBatcher.dispose();
 		backgroundQueue.cancelAll();
+		// Clear the monitor so stale runs from this session never leak into the
+		// next one (the module-level singleton survives across sessions).
+		monitor.clear();
 	});
 
 	pi.registerTool({
@@ -212,6 +215,7 @@ export default function (pi: ExtensionAPI): void {
 			"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; 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.",
+			"NEVER sleep, wait, poll, or call other tools alongside subagent — it ends the turn immediately. The main agent is auto-resumed when results arrive; manual waiting only blocks the turn and delays delivery.",
 		],
 		parameters: SubagentParams,
 
@@ -249,6 +253,7 @@ export default function (pi: ExtensionAPI): void {
 				monitor.setStatus(runId, status); // stamps endedAt for the elapsed time
 				const run = opts?.retain ? monitor.findRun(runId) : monitor.removeRun(runId);
 				if (!run) return; // already finished — stay idempotent
+				if (opts?.retain) monitor.setRetained(runId, true);
 				if (opts?.silent || !sessionActive) return;
 				const icon = status === "done" ? "✓" : "✗";
 				ctx.ui.notify(`${icon} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
@@ -435,7 +440,7 @@ export default function (pi: ExtensionAPI): void {
 						if (!sessionActive) return;
 						const items: CompletionMessageItem[] = chain.map((r) => ({
 							agent: r.agent,
-							block: formatCompletionBlock(r, config.maxResultLines),
+							block: formatCompletionBlock(r, config.maxResultLines, ctx.cwd),
 							triggerTurn: true,
 						}));
 						sendCompletionGroup(items);
@@ -515,7 +520,7 @@ export default function (pi: ExtensionAPI): void {
 						if (!sessionActive) return;
 						const completion: CompletionMessageItem = {
 							agent: result.agent,
-							block: formatCompletionBlock(result, config.maxResultLines),
+							block: formatCompletionBlock(result, config.maxResultLines, ctx.cwd),
 							triggerTurn: completionTriggersTurn(result, config.notifyOnReviewPass),
 						};
 						if (failed) {

package/src/monitor.ts

@@ -42,6 +42,10 @@ export interface RunView {
 	relationLabel?: string;
 	/** Free-form note shown in the widget next to the status label (e.g. "auto-fix chain running"). */
 	annotation?: string;
+	/** True when a finished run is intentionally kept in the widget (e.g. an
+	 * auto-fix chain parent whose chain is still running). beginTurn preserves
+	 * retained runs so they are not swept between turns. */
+	retained?: boolean;
 }
 
 /** Optional chain metadata for runs spawned by an auto-fix loop. */
@@ -298,7 +302,12 @@ export class MonitorStore {
 	beginTurn(): void {
 		// Clear finished runs from a previous turn, but keep any still-active
 		// (queued/running) ones so a concurrent sub-agent call is not wiped.
-		this.runs = this.runs.filter((r) => r.status === "queued" || r.status === "running");
+		// Retained runs (e.g. an auto-fix chain parent whose chain is still
+		// running) are also preserved — their status is "done" but they must
+		// stay visible until the chain resolves.
+		this.runs = this.runs.filter(
+			(r) => r.status === "queued" || r.status === "running" || r.retained,
+		);
 		this.notify();
 	}
 
@@ -357,11 +366,27 @@ export class MonitorStore {
 		this.notify();
 	}
 
+	/** Mark a run as retained (kept in the widget despite being finished). */
+	setRetained(id: number, retained: boolean): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.retained = retained;
+		this.notify();
+	}
+
 	/** Look up a run by id without removing it. */
 	findRun(id: number): RunView | undefined {
 		return this.find(id);
 	}
 
+	/** Remove all runs (used on session shutdown so stale state never leaks
+	 * into the next session). Does not reset the id counter so in-flight
+	 * finishRun calls from the old session remain safe no-ops. */
+	clear(): void {
+		this.runs = [];
+		this.notify();
+	}
+
 	/** Remove a run (finished runs leave the widget). Returns the removed run. */
 	removeRun(id: number): RunView | undefined {
 		const index = this.runs.findIndex((r) => r.id === id);

package/src/prompt.ts

@@ -41,6 +41,10 @@ It immediately ends the current main-agent turn so the user can keep working. Wh
 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.
 
+NEVER run sleep, wait, or polling commands (e.g. Start-Sleep, sleep, timeout) to wait for
+a sub-agent — the turn already ended and the main agent is auto-resumed when results arrive.
+Manual waiting blocks the turn, delays result delivery, and wastes the user's time.
+
 Available agents:
 ${catalog}
 

package/src/spawn.ts

@@ -128,9 +128,14 @@ export function truncateResultOutput(output: string, maxLines: number): Truncate
 	return { text: kept.join("\n"), truncated: true };
 }
 
-/** Persist the full result where the main agent can read it on demand. Returns the file path. */
-export function writeResultArtifact(output: string, agentName: string): string {
-	const dir = join(tmpdir(), "pi-subagents-results");
+/** Persist the full result where the main agent can read it on demand. Returns the file path.
+ * Results are grouped under a per-project subdirectory so concurrent projects don't
+ * litter a single flat folder. */
+export function writeResultArtifact(output: string, agentName: string, cwd?: string): string {
+	const projectSlug = cwd
+		? basename(cwd).replace(/[^\w.-]+/g, "_") || "default"
+		: "default";
+	const dir = join(tmpdir(), "pi-subagents-results", projectSlug);
 	mkdirSync(dir, { recursive: true });
 	const safeName = agentName.replace(/[^\w.-]+/g, "_");
 	// A random suffix keeps same-millisecond writes from clobbering each other.
@@ -166,7 +171,10 @@ export function isModelLevelFailure(result: SingleResult): boolean {
 
 export function getResultOutput(result: SingleResult): string {
 	if (isFailedResult(result)) {
-		return result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
+		const error = result.errorMessage || result.stderr;
+		const partial = getFinalOutput(result.messages);
+		if (error && partial) return `${error}\n\n--- Partial output ---\n${partial}`;
+		return error || partial || "(no output)";
 	}
 	return getFinalOutput(result.messages) || "(no output)";
 }
@@ -506,12 +514,13 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 
 		currentResult.exitCode = exitCode;
 		if (wasAborted) {
+			currentResult.stopReason = "aborted";
+			currentResult.errorMessage ??= "Subagent was aborted";
 			if (onLive) {
 				try {
 					onLive({ kind: "status", status: "failed" });
 				} catch { /* never throw from event handling */ }
 			}
-			throw new Error("Subagent was aborted");
 		}
 		return currentResult;
 	} finally {