@ferris1225/pi-subagents 0.16.0 → 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. Unlike the total timeout, 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), aborts, or total timeouts. 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.0",
+  "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

@@ -12,7 +12,6 @@
  * runaway recursion and keeps child context windows clean.
  */
 
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
@@ -31,7 +30,6 @@ import { buildDelegationDirective } from "./prompt.ts";
 import { runSetup } from "./setup.ts";
 import {
 	currentSubagentDepth,
-	getFinalOutput,
 	getResultOutput,
 	isFailedResult,
 	reviewVerdict,
@@ -126,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);
@@ -137,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");
 }
@@ -193,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({
@@ -214,10 +215,11 @@ 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,
 
-		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			monitor.beginTurn();
 			let config = await loadConfig(configPath);
 			// Pick up concurrency changes from /subagents-setup without a restart.
@@ -251,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");
@@ -437,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);
@@ -517,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

@@ -4,8 +4,7 @@
  * written to a temp file and passed via `--append-system-prompt` (which accepts a
  * file path). The task itself is sent through the child's stdin pipe, not another
  * temp file or command-line argument. Child stdout is a JSON-lines event stream;
- * we accumulate assistant messages from `message_end` events and stream partial
- * output back via onUpdate.
+ * we accumulate assistant messages from `message_end` events.
  *
  * Adapted from the official pi example `examples/extensions/subagent`.
  */
@@ -16,7 +15,6 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Message } from "@earendil-works/pi-ai";
 import type { AgentConfig, AgentSource } from "./agents.ts";
 import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
@@ -28,8 +26,6 @@ import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
 /** Default thinking level for sub-agents. pi clamps it to the resolved model's support. */
 export const SUBAGENT_THINKING_LEVEL: ThinkingLevel = DEFAULT_THINKING_LEVEL;
 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;
 export const SUBAGENT_KILL_GRACE_MS = 5_000;
 /** Default idle watchdog: terminate a child whose stdout goes silent for this
  * many milliseconds. 0 disables it. The actual value comes from config
@@ -70,8 +66,6 @@ export interface SubagentDetails {
 	background?: boolean;
 }
 
-export type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
-
 export type SubagentLiveEvent =
 	| { kind: "status"; status: "queued" | "running" | "done" | "failed" }
 	| { kind: "usage"; usage: UsageStats; model?: string }
@@ -134,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.
@@ -165,7 +164,6 @@ export function isModelLevelFailure(result: SingleResult): boolean {
 	if (result.errorMessage?.includes("idle timeout")) return true;
 	// The model produced text: the failure belongs to the task, not the model.
 	if (getFinalOutput(result.messages)) return false;
-	if (result.errorMessage?.includes("timed out")) return false;
 	// Require evidence the failure came from the model/provider (an error
 	// message or stderr), not from the child process failing to start.
 	return result.messages.length > 0 || result.stderr.trim().length > 0;
@@ -173,31 +171,14 @@ 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)";
 }
 
-export async function mapWithConcurrencyLimit<TIn, TOut>(
-	items: TIn[],
-	concurrency: number,
-	fn: (item: TIn, index: number) => Promise<TOut>,
-): Promise<TOut[]> {
-	if (items.length === 0) return [];
-	const limit = Math.max(1, Math.min(concurrency, items.length));
-	const results: TOut[] = new Array(items.length);
-	let nextIndex = 0;
-	const workers = new Array(limit).fill(null).map(async () => {
-		while (true) {
-			const current = nextIndex++;
-			if (current >= items.length) return;
-			results[current] = await fn(items[current], current);
-		}
-	});
-	await Promise.all(workers);
-	return results;
-}
-
 async function writePromptToTempFile(agentName: string, prompt: string): Promise<{ dir: string; filePath: string }> {
 	const dir = await mkdtemp(join(tmpdir(), "pi-subagents-"));
 	const safeName = agentName.replace(/[^\w.-]+/g, "_");
@@ -261,13 +242,10 @@ export interface RunSingleOptions {
 	cwd?: string;
 	/** Thinking level passed to the child pi process. */
 	thinkingLevel?: ThinkingLevel;
-	/** Optional total timeout; zero (the default) disables it. Intended for tests and controlled callers. */
-	timeoutMs?: number;
 	/** Idle timeout in ms: terminate the child if its stdout produces no activity
 	 * for this duration. 0 (the default) disables the idle watchdog. */
 	idleTimeoutMs?: number;
 	signal?: AbortSignal;
-	onUpdate?: OnUpdateCallback;
 	onLive?: (e: SubagentLiveEvent) => void;
 	makeDetails: (results: SingleResult[]) => SubagentDetails;
 	env?: NodeJS.ProcessEnv;
@@ -281,10 +259,8 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 		task,
 		cwd,
 		thinkingLevel = SUBAGENT_THINKING_LEVEL,
-		timeoutMs = SUBAGENT_TIMEOUT_MS,
 		idleTimeoutMs = SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS,
 		signal,
-		onUpdate,
 		onLive,
 		makeDetails,
 	} = options;
@@ -324,13 +300,6 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 		thinking: thinkingLevel,
 	};
 
-	const emitUpdate = (): void => {
-		onUpdate?.({
-			content: [{ type: "text", text: getFinalOutput(currentResult.messages) || "(running...)" }],
-			details: makeDetails([currentResult]),
-		});
-	};
-
 	try {
 		if (agent.systemPrompt.trim()) {
 			const tmp = await writePromptToTempFile(agent.name, agent.systemPrompt);
@@ -340,7 +309,6 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 		}
 
 		let wasAborted = false;
-		let timedOut = false;
 
 		// Increment depth so nested sub-agents can be guarded against runaway recursion.
 		const childDepth = currentSubagentDepth(options.env) + 1;
@@ -361,7 +329,6 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 			let closed = false;
 			let termSent = false;
 			let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
-			let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
 			let abortHandler: (() => void) | undefined;
 			let lastActivityAt = Date.now();
 			let idleTimer: ReturnType<typeof setInterval> | undefined;
@@ -370,7 +337,6 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 				if (closed) return;
 				closed = true;
 				if (forceKillTimer) clearTimeout(forceKillTimer);
-				if (timeoutTimer) clearTimeout(timeoutTimer);
 				if (idleTimer) clearInterval(idleTimer);
 				if (signal && abortHandler) signal.removeEventListener("abort", abortHandler);
 				resolve(code ?? 1);
@@ -461,12 +427,10 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 							onLive({ kind: "usage", usage: { ...currentResult.usage }, model: currentResult.model });
 						} catch { /* never throw from event handling */ }
 					}
-					emitUpdate();
 				}
 
 				if (event.type === "tool_result_end" && event.message) {
 					currentResult.messages.push(event.message as Message);
-					emitUpdate();
 				}
 			};
 			// Send the task through the child stdin pipe instead of the process
@@ -502,7 +466,6 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 				const failed =
 					code !== 0 ||
 					wasAborted ||
-					timedOut ||
 					(signal?.aborted ?? false) ||
 					currentResult.stopReason === "error" ||
 					currentResult.stopReason === "aborted";
@@ -526,22 +489,12 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 				finish(1);
 			});
 
-			if (timeoutMs > 0) {
-				timeoutTimer = setTimeout(() => {
-					timedOut = true;
-					currentResult.stopReason = "error";
-					currentResult.errorMessage = `Subagent timed out after ${Math.ceil(timeoutMs / 1000)} seconds.`;
-					terminate();
-				}, timeoutMs);
-			}
-
 			if (idleTimeoutMs > 0) {
 				const checkInterval = Math.min(10_000, Math.floor(idleTimeoutMs / 3));
 				idleTimer = setInterval(() => {
 					if (closed) return;
 					if (Date.now() - lastActivityAt >= idleTimeoutMs) {
 						if (idleTimer) clearInterval(idleTimer);
-						timedOut = true;
 						currentResult.stopReason = "error";
 						currentResult.errorMessage = `Subagent idle timeout: no activity for ${Math.ceil(idleTimeoutMs / 1000)} seconds.`;
 						terminate();
@@ -561,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 {