# @dreki-gg/pi-subagent

## Unreleased

### ⚠ BREAKING CHANGES

* Replace named-agent execution with prompt-native Pi subprocess runs.
* Accept full `prompt` text with an optional inert `label` and explicit model, thinking, tools, and cwd controls.
* Remove `list_agents`, `/create-agent`, `/run-agent`, agent scopes, project-agent confirmation, bundled prompts, the prompt-authoring skill, persona handoffs, and Cursor ACP support.
* Move workflow RPC events from `subagents:rpc:v1:*` to `subagents:rpc:v2:*`. Workflow steps use `prompt` and optional `label`.

## [0.20.0](https://github.com/jalbarrang/pi-subagent/compare/v0.19.0...v0.20.0) (2026-08-25)


### Features

* infer the claude backend from a bare claude-* model ([#17](https://github.com/jalbarrang/pi-subagent/issues/17)) ([2bc012b](https://github.com/jalbarrang/pi-subagent/commit/2bc012b4a3dc3d6599873de54a089873f99462bd))

## [0.19.0](https://github.com/jalbarrang/pi-subagent/compare/v0.18.0...v0.19.0) (2026-08-07)


### Features

* add selectable execution backends (pi default, claude) ([7c57f05](https://github.com/jalbarrang/pi-subagent/commit/7c57f05e68f594a44075b5f1811709ad02122f0e))

## [0.18.0](https://github.com/jalbarrang/pi-subagent/compare/v0.17.0...v0.18.0) (2026-08-05)


### Features

* add context-isolated /btw side questions ([6c639fc](https://github.com/jalbarrang/pi-subagent/commit/6c639fc88f0d8ce89e5a5ad6e55460156868a417))
* coordinate and bound subagent execution ([09cb3d5](https://github.com/jalbarrang/pi-subagent/commit/09cb3d52a4f759d18f17fcbce767e662f67af616))

## [0.17.0](https://github.com/jalbarrang/pi-subagent/compare/v0.16.1...v0.17.0) (2026-08-01)


### ⚠ BREAKING CHANGES

* make subagent execution prompt-native

### Code Refactoring

* make subagent execution prompt-native ([ac0eaf9](https://github.com/jalbarrang/pi-subagent/commit/ac0eaf940c7ea167264ffb9339cf07a4d788cd53))

## [0.16.1](https://github.com/jalbarrang/pi-subagent/compare/v0.16.0...v0.16.1) (2026-07-27)


### Bug Fixes

* prevent recursive subagent delegation ([cb06a8a](https://github.com/jalbarrang/pi-subagent/commit/cb06a8ab930c695651b89bb39d1e96b31480c67d))

## [0.16.0](https://github.com/jalbarrang/pi-subagent/compare/v0.15.1...v0.16.0) (2026-07-20)


### Features

* **workflow:** persist run snapshots to a caller-chosen runsDir ([cebf7d4](https://github.com/jalbarrang/pi-subagent/commit/cebf7d4ccac5a08db0e74be01381cebc384e2338))

## [0.15.1](https://github.com/jalbarrang/pi-subagent/compare/v0.15.0...v0.15.1) (2026-07-20)


### Bug Fixes

* **workflow:** resolve package paths so workflow phases can run package agents ([bbd3882](https://github.com/jalbarrang/pi-subagent/commit/bbd38825260923124f0cd5cb838be389d7ec6377))

## [0.15.0](https://github.com/jalbarrang/pi-subagent/compare/v0.14.1...v0.15.0) (2026-07-20)


### Features

* **workflow:** expose phase progress snapshots ([ea0d6b1](https://github.com/jalbarrang/pi-subagent/commit/ea0d6b1c0a09c09421046fbb28e827dc4ddcbf5e))

## [0.14.1](https://github.com/jalbarrang/pi-subagent/compare/v0.14.0...v0.14.1) (2026-07-19)


### Bug Fixes

* **cursor:** fail cleanly when cursor-agent is not installed ([884d98d](https://github.com/jalbarrang/pi-subagent/commit/884d98df8b36610a4d109e0a09d143f6e2cb616a))

## [0.14.0](https://github.com/jalbarrang/pi-subagent/compare/v0.13.0...v0.14.0) (2026-07-19)


### Features

* add reviewed workflow RPC bridge ([e41b9cb](https://github.com/jalbarrang/pi-subagent/commit/e41b9cb5390335fca03813120aa05558337a1eff))

## [0.13.0](https://github.com/jalbarrang/pi-subagent/compare/v0.12.0...v0.13.0) (2026-07-12)


### Features

* update prompts ([d8a0597](https://github.com/jalbarrang/pi-subagent/commit/d8a05971d5cf840fa7ac7e02ad4871d9bde3f2ea))

## [0.12.0](https://github.com/jalbarrang/pi-subagent/compare/v0.11.3...v0.12.0) (2026-07-12)


### Features

* replace reviewer prompt with scout/consult/worker families ([196de12](https://github.com/jalbarrang/pi-subagent/commit/196de120007d27e93e12374bcc56cb6c44c2007e))

## [0.11.3](https://github.com/jalbarrang/pi-subagent/compare/v0.11.2...v0.11.3) (2026-07-12)


### Bug Fixes

* **deps:** bump dependencies to latest ([#3](https://github.com/jalbarrang/pi-subagent/issues/3)) ([20ea751](https://github.com/jalbarrang/pi-subagent/commit/20ea751163d3178634d5ac33ff1c25a10ec37b81))

## [0.11.2](https://github.com/jalbarrang/pi-subagent/compare/v0.11.1...v0.11.2) (2026-07-11)


### Bug Fixes

* declare zod as a direct dependency ([5f981bb](https://github.com/jalbarrang/pi-subagent/commit/5f981bb5c56750721c4aaf646739d771877d9bb7))

## 0.11.0

### Minor Changes

- Model routing guidance and visible model attribution.

  - `spawn-subagents` skill: new "Model routing" section — route each subagent task to the model whose strengths match the work (bulk token burn → cheap, user-facing → tasteful, reviews → strongest), honor a user model routing policy from AGENTS.md when one exists, and escalate without asking when a cheaper model's output misses the bar.
  - Reasoning defaults: Opus-backed judgment/coding agents (advisor, planner, reviewer, validator, bug-prover, ux-designer) now run `thinking: high` instead of low/medium — reasoning effort applies per step, and high is the quality/cost sweet spot. Scouts stay low for cheap bulk recon.
  - Result rendering: the model that ran each task is now shown next to the agent name in single, parallel, and chain headers (dim ` · model`), and in the working message while a run is active — so per-model quality is auditable at a glance. Parallel running placeholders resolve the model up front (task override → call default → agent default), so attribution shows while tasks are still running, not just after completion.
  - `scout` and `docs-scout` default models move from `gpt-5.4-mini` to `gpt-5.6-luna` — near-Terra coding quality at the lowest benchmarked cost per task.

## 0.10.0

### Minor Changes

- db4b119: Add a Cursor ACP backend: set a subagent's model to `cursor:<model>` (e.g. `cursor:composer-2.5`) to run the task on Cursor's agent via the Agent Client Protocol instead of spawning a `pi` process. Routing happens in one shared dispatcher, so it works across single / parallel / chain modes and the `/run-agent` command with an unchanged result shape. Permission requests are auto-approved; the `tools` allowlist and `thinking` level do not apply to `cursor:` models. Requires `cursor-agent` installed and authenticated (`agent login`).

## 0.9.2

### Patch Changes

- Tighten subagent prompts and the write-an-agent skill. The skill gains a "Prompt hygiene (anti-rot)" section (invariants over incidents, one owner per fact, every line must change behavior) plus matching review-checklist items, and the reviewer/worker/planner prompts state the consult handoff shape once instead of in three duplicated blocks. No behavior change.

## 0.9.1

### Patch Changes

- Refactor plan-mode to conversational planning with JSONL task storage and HTML output. Replace steps with task records, add atomic writes, Pug-based plan.html generation, and migrate manifest to JSONL. Update subagent prompts.

## 0.9.0

### Minor Changes

- [`99bc4e7`](https://github.com/dreki-gg/pi-extensions/commit/99bc4e7abb9f468ebd6705a56ed1c2a801dd466e) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Add `list_agents` tool and `/create-agent` command to help the LLM discover available agents before spawning and scaffold new project-local agent prompts.

## 0.8.4

### Patch Changes

- [`376864c`](https://github.com/dreki-gg/pi-extensions/commit/376864c37cefa47530363b47055311269c1724a8) Thanks [@jalbarrang](https://github.com/jalbarrang)! - feat(subagent): show live tool-aware status in working message during /run-agent

  Previously `/run-agent` only showed a transient notification, leaving users with no visibility into what the background agent was doing (especially after a fork-at session switch that visually looks like a reload). Now the working message updates in real-time as the agent works:

  - `scout · starting...`
  - `scout · reading …/src/utils.ts`
  - `scout · $ bun test --filter...`
  - `scout · editing …/config.json`
  - `scout · thinking...`

  Added `onToolExecutionStart` callback to `spawnPiAgent` and `runAgent` to surface `tool_execution_start` events from the JSON stream.

## 0.8.3

### Patch Changes

- [`6f0b219`](https://github.com/dreki-gg/pi-extensions/commit/6f0b219ac357ce1607a7a8211fd1c66bd35c62f1) Thanks [@jalbarrang](https://github.com/jalbarrang)! - fix(subagent): resolve TDZ crash when onMessage/onToolResult callbacks fire before spawnResult is assigned

  Previously, `runSingleAgent` declared `const spawnResult = await spawnPiAgent({...})` and referenced `spawnResult` inside the `onMessage`/`onToolResult` callbacks. Since callbacks fire during the await (before the const is assigned), this caused a `ReferenceError: Cannot access 'spawnResult' before initialization`. Now uses `let` with a guard to safely accumulate messages when the result is not yet available.

## 0.8.2

### Patch Changes

- [`32797ff`](https://github.com/dreki-gg/pi-extensions/commit/32797ff18d968e22c6c44e95c46e3393d8928cef) Thanks [@jalbarrang](https://github.com/jalbarrang)! - feat(plan-mode): add Windows compatibility — replace Unix shell commands with cross-platform Bun/Node APIs

  Plan-mode no longer shells out to `cat`, `bash`, or `mkdir` via `pi.exec()`. File I/O now uses `Bun.file()` / `Bun.write()` and `node:fs/promises` `mkdir`, making the extension fully cross-platform. Destructive and safe command pattern lists now include Windows equivalents (`del`, `rd`, `copy`, `move`, `powershell`, `dir`, `where`, `tasklist`, etc.).

  Also fixes Windows compatibility in three other packages:

  - **browser-tools**: `spawn` now uses `shell: true` on Windows so `.cmd` wrappers resolve correctly; `shellEscape` uses double-quote style on Windows; install guidance is platform-aware (Homebrew shown only on macOS).
  - **subagent**: `spawn` uses `shell: true` on Windows when the command is bare `pi`, allowing `pi.cmd` resolution.
  - **lsp**: `globalConfigPath()` now uses `os.homedir()` on Windows instead of the unreliable `process.env.HOME`.

## 0.8.1

### Patch Changes

- [`d133c3d`](https://github.com/dreki-gg/pi-extensions/commit/d133c3da917e7e5def568d27d6cde8ae8a6c00d2) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Mark pi peer dependencies as optional so npm does not auto-install pi internals when installing extension packages.

## 0.8.0

### Minor Changes

- [`3a246f3`](https://github.com/dreki-gg/pi-extensions/commit/3a246f3fd55b900ebfcfbea2eff2a7ab9f9f94cf) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Refactor agent distribution from custom `pi.agents` to standard `pi.prompts`

  - Rename `agents/` directory to `prompts/` to follow pi's standard resource type
  - Use `pi.prompts` in package.json instead of non-standard `pi.agents`
  - Remove legacy bundled-directory fallback — agent prompts are now resolved via pi's package manager
  - Remove `/delegate-agents` command (unused; `/run-agent` and `subagent` tool cover all usage)
  - Extract shared spawn logic into `spawn-utils.ts`, eliminating cross-file duplication between `agent-runner.ts` and `index.ts`
  - Remove dead exports (`formatAgentList`, `buildSynthesisPrompt`, `SYNTHESIS_INSTRUCTION`)
  - Clean up unused imports
  - Maintainability score improved from 70.7 (moderate) to 90.6 (good)
  - Model configuration (`model`, `thinking`, `tools` frontmatter) is unchanged

## 0.7.0

### Minor Changes

- [`0be7b68`](https://github.com/dreki-gg/pi-extensions/commit/0be7b6877e9874b46c756b58c99d599db623ef11) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Remove the `/delegate` command from `@dreki-gg/pi-subagent`.

  - keep the `subagent` tool as the primary orchestration surface
  - keep `/run-agent` for direct named-agent runs
  - keep `/delegate-agents` for agent management
  - update docs and the `spawn-subagents` skill to point rigid multi-step flows toward prompt templates and direct `subagent` chain/parallel usage instead of `/delegate`

### Patch Changes

- [`0be7b68`](https://github.com/dreki-gg/pi-extensions/commit/0be7b6877e9874b46c756b58c99d599db623ef11) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Migrate TypeBox usage and session replacement flows for Pi 0.69 compatibility.

  - switch extension imports from `@sinclair/typebox` to `typebox`
  - update package peer dependencies to require `typebox`
  - move subagent `/run-agent` fork-at follow-up work into `withSession` so post-fork operations use the replacement session safely
  - add command argument completions for `/run-agent`, `/delegate-agents`, `/preset`, `/mode`, and `/plan`
  - align local development dependencies with Pi 0.69 for typechecking and compatibility checks

## 0.6.0

### Minor Changes

- [`5e853af`](https://github.com/dreki-gg/pi-extensions/commit/5e853af054a31c4bf87d80f944513e537a39201d) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Sync the extensions repo with Pi 0.68.0 and improve direct agent runs.

  - `@dreki-gg/pi-context7`: remove stale alias docs and align compatibility tests with the canonical tool names actually exported.
  - `@dreki-gg/pi-modes`: use `before_agent_start.systemPromptOptions.selectedTools` when available so mode prompt text reflects the active prompt tool set.
  - `@dreki-gg/pi-subagent`: add `/run-agent`, support `sessionStrategy: fork-at` in agent frontmatter, default bundled `worker` and `reviewer` to forked direct runs, and add a custom renderer for run summaries.

## 0.5.0

### Minor Changes

- [`4f2f148`](https://github.com/dreki-gg/pi-extensions/commit/4f2f148488e32ff43f97216a5c221fd9d1716a11) Thanks [@jalbarrang](https://github.com/jalbarrang)! - added agents to the registry so my fork is able to discover subagent files

## 0.4.0

### Minor Changes

- [`52d744e`](https://github.com/dreki-gg/pi-extensions/commit/52d744e34f593a7bd6b907d67d5e245ef63b6079) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Improve bundled agent resolution and `/delegate` workflow control in `@dreki-gg/pi-subagent`.

  - Add explicit agent source tracking for bundled, user, and project agents.
  - Resolve agents with layered precedence: bundled → user → project.
  - Add `agentScope` support to delegated execution so workflows can opt into user, project, or both agent layers.
  - Add `/delegate` argument parsing for `--scope`, `--workflow`, and `--yes-project-agents`.
  - Add a confirmation step before running project-local agents from `/delegate` or the `subagent` tool when UI is available.
  - Replace the old `subagent-workflows` skill with `spawn-subagents`, which steers the assistant toward conversational `subagent` usage and keeps `/delegate` as an explicit gated workflow option.

## 0.3.1

### Patch Changes

- [`144498f`](https://github.com/dreki-gg/pi-extensions/commit/144498fd9c23cb5060fb5171e56ff722ebf0c4f2) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Fix two bugs in the `subagent` tool surfaced when spawning long-running reviewer agents:

  - **Bun standalone binary spawn failure**: `getPiInvocation` now detects Bun's virtual filesystem paths (`/$bunfs/...`) in `process.argv[1]` and falls back to invoking the compiled binary directly. Previously, spawned subagents would fail with errors like `/$bunfs/root/pi doesn't exist in this environment` because the virtual path was passed verbatim to `spawn`.
  - **Parallel summary truncation**: `parallel` mode no longer truncates each child agent's final output to 100 characters in the tool result summary. Long reviews from editorial/scout agents are now returned in full so callers don't need to scrape temp files or re-run agents to see their work.

## 0.3.0

### Minor Changes

- [`a114ecc`](https://github.com/dreki-gg/pi-extensions/commit/a114eccd78f4c45501bcbf32e0e202c80f258755) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Merged `@dreki-gg/pi-delegate` into `@dreki-gg/pi-subagent`. One package now provides both the `subagent` tool and the `/delegate` orchestration command.

  ### What's new in `@dreki-gg/pi-subagent`

  - `/delegate` command — synthesize conversation into a task, pick a workflow, execute with scouts/planner/worker/reviewer
  - `/delegate-agents` command — list, customize, or reset bundled agents
  - 6 bundled agents: scout, docs-scout, planner, worker, reviewer, ux-designer
  - `spawn-subagents` skill for conversational subagent orchestration
  - 3 prompt templates: implement, scout-and-plan, implement-and-review

  ### Bundled agent discovery

  Agents are now read directly from the package's `agents/` directory. User overrides in `~/.pi/agent/agents/` still take precedence by name. No file copying on session start.

  Priority order: bundled (lowest) → user → project (highest).

  ### `@dreki-gg/pi-delegate` is deprecated

  All functionality has moved to `@dreki-gg/pi-subagent`. Remove `pi-delegate` and use `pi-subagent` instead:

  ```bash
  pi remove npm:@dreki-gg/pi-delegate
  pi install npm:@dreki-gg/pi-subagent
  ```

## 0.2.0

### Minor Changes

- [#22](https://github.com/dreki-gg/pi-extensions/pull/22) [`d5c55f5`](https://github.com/dreki-gg/pi-extensions/commit/d5c55f533c6e1ec65fcc1cce19537cf91854b122) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Support `thinking` frontmatter field in agent definitions to set reasoning effort level.

  - Read `thinking` from agent `.md` frontmatter and pass `--thinking <level>` to spawned pi processes
  - Update all bundled agents to use OpenAI models with thinking levels
  - Add `ux-designer` agent for frontend UI design with anti-Codex aesthetic guidelines

## 0.1.3

### Patch Changes

- [`0d6fee9`](https://github.com/dreki-gg/pi-extensions/commit/0d6fee9417cbc5874ce5d212b5e6c1f2e42f5192) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Use provider-qualified model IDs in agent frontmatter to work around upstream pi model resolution bug where bare IDs (e.g. `gpt-5.4`) can resolve to the wrong provider (e.g. `azure-openai-responses` instead of `openai`).

## 0.1.2

### Patch Changes

- [`53809f8`](https://github.com/dreki-gg/pi-extensions/commit/53809f83cdf054d1eb58c577903a1d2619a2a654) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Add repository.url to package.json for npm provenance verification

## 0.1.1

### Patch Changes

- [`b1e603c`](https://github.com/dreki-gg/pi-extensions/commit/b1e603c9dab1837eed39880c0455b553deab5cb0) Thanks [@jalbarrang](https://github.com/jalbarrang)! - init packages