@clanker-code/pi-subagents 0.10.5 → 0.10.6

package/AGENTS.md

@@ -17,7 +17,17 @@ Every release must:
 3. **Update `README.md` to document any new or changed user-facing features.**
 4. Run and pass: `npm run lint`, `npm run typecheck`, `npm test`, `npm run build`.
 5. Commit and push.
-6. User publishes with `npm publish` from a clean `master` checkout.
+6. Push a `vX.Y.Z` tag. The `release.yml` workflow then publishes to npm and creates a GitHub Release automatically.
+
+One-time npm setup for CI publishing:
+
+```bash
+npm trust github @clanker-code/pi-subagents --repo=clankercode/pi-subagents --file=release.yml
+```
+
+If `npm trust` fails, open `https://www.npmjs.com/package/@clanker-code/pi-subagents/access` and add a GitHub Actions trusted publisher for the `release.yml` workflow.
+
+See the general guide at `~/.llm-general/npm-autopublish-via-ci.md` for other repos.
 
 ## Keeping Upstream In Sync
 

package/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.6] - 2026-06-22
+
+### Changed
+- **Release workflow test** — patch bump to verify the tag-driven CI publish and GitHub Release creation.
+
 ## [0.10.5] - 2026-06-21
 
 ### Changed

package/RELEASE.md

@@ -21,19 +21,25 @@
    git push
    ```
 
-4. **Create a GitHub release**
-   - Tag the commit matching the version:
-     ```bash
-     git tag vX.Y.Z
-     git push origin vX.Y.Z
-     ```
-   - Open the [GitHub releases page](https://github.com/clankercode/pi-subagents/releases) and create a new release for the tag.
-   - Copy the relevant `[x.y.z]` section from `CHANGELOG.md` into the release notes.
-   - Highlight any breaking changes, fork-specific features, or upgrade notes.
-
-5. **Publish to npm**
+4. **Push the version tag**
+   The `release.yml` workflow publishes to npm and creates the GitHub Release automatically:
    ```bash
-   npm publish
+   git tag vX.Y.Z
+   git push origin vX.Y.Z
    ```
 
+5. **Verify**
+   - Check the [Actions run](https://github.com/clankercode/pi-subagents/actions) succeeded.
+   - Confirm the package version appears on npm: `npm view @clanker-code/pi-subagents`.
+   - Confirm the GitHub Release has the changelog notes.
+
+One-time npm trusted-publisher setup:
+```bash
+npm trust github @clanker-code/pi-subagents --repo=clankercode/pi-subagents --file=release.yml
+```
+
+If `npm trust` fails, open `https://www.npmjs.com/package/@clanker-code/pi-subagents/access` and add a GitHub Actions trusted publisher for the `release.yml` workflow.
+
+See `~/.llm-general/npm-autopublish-via-ci.md` for general instructions.
+
 > Note: `prepublishOnly` already runs lint, typecheck, tests, and build before publishing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clanker-code/pi-subagents",
-  "version": "0.10.5",
+  "version": "0.10.6",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "clankercode",
   "license": "MIT",

package/.plans/PLAN-next-changes.md

@@ -1,183 +0,0 @@
-# Plan: Next pi-subagents improvements
-
-This plan covers four coordinated changes:
-1. **Abort-detach + interruptible/timeout wait** for `get_subagent_result wait:true` (Escape no longer wedges the turn; default 4.5 min timeout).
-2. Configurable `waitTimeoutSeconds` setting (default 270s) exposed in `/agents → Settings`.
-3. `get_subagent_result` peek/tail capability with line numbers, regex filter, and `after` line offset.
-4. Description polish for `inherit_context` and `isolation: "worktree"`.
-
-All changes are scoped to keep diffs minimal and upstream-merge-friendly.
-
-### Key finding (abort-detach)
-Background spawns already do NOT pass the parent abort signal to `manager.spawn()` — only the now-dead foreground path did. So background subagents are already detached from Escape. The Escape-wedge symptom comes from `get_subagent_result wait:true`, which awaits `record.promise` and ignores the parent `signal`. Fix: race the wait against (a) the parent abort `signal` and (b) the configurable timeout, returning current status on either WITHOUT aborting the subagent.
-
----
-
-## 1. Settings foundation: configurable `waitTimeoutSeconds`
-
-### Motivation
-Users want to avoid typical 5-minute LLM cache expiry; 4.5 minutes is a safe default. We also want this exposed in `/agents → Settings` so it is discoverable and adjustable per project.
-
-### Files touched
-- `src/types.ts` — add `waitTimeoutSeconds` to `AgentRecord`? No, this is runtime/config, not per-agent. Keep it in settings only.
-- `src/settings.ts`:
-  - Add `waitTimeoutSeconds?: number` to `SubagentsSettings`.
-  - Add `setWaitTimeoutSeconds: (seconds: number) => void` to `SettingsAppliers`.
-  - Add sanitize rule: integer, min 30, max 3600 (30s–1h). Default 270 (4.5m) when absent.
-  - Add `applySettings` wiring.
-- `src/index.ts`:
-  - Add `let waitTimeoutSeconds = 270` and getter/setter.
-  - Add to `snapshotSettings()`.
-  - Add `/agents → Settings` item with id `waitTimeoutSeconds`.
-  - Wire `applyValue` for `waitTimeoutSeconds` (numeric prompt, 30–3600).
-  - Add to `applyAndEmitLoaded` appliers object.
-  - Pass timeout value into `get_subagent_result` execute closure.
-
-### Return value / UI impact
-- `get_subagent_result` `wait` description: mention current configured timeout.
-- On timeout, return message:
-  ```
-  Agent is still running after 4 minutes 30 seconds.
-  This wait timed out to avoid blocking the parent session longer than the configured limit.
-  Call get_subagent_result with wait: true again to keep waiting, or omit wait to check status.
-  ```
-
-### Tests
-- `test/settings.test.ts` (if exists) or new assertions in `test/settings.test.ts`: sanitize boundaries.
-- New/updated test for `get_subagent_result` timeout behavior using a mocked promise and fake timers.
-
----
-
-## 2. `get_subagent_result` peek parameter
-
-### Motivation
-Agents should be able to cheaply check recent output / logs without fetching the full result or conversation.
-
-### Proposed schema
-```ts
-peek: Type.Optional(
-  Type.Object({
-    lines: Type.Optional(Type.Number({ minimum: 1, description: "Number of trailing lines to return. Default: 20." })),
-    regex: Type.Optional(Type.String({ description: "Optional regex filter. Only lines matching this regex are included." })),
-    after: Type.Optional(Type.Number({ minimum: 0, description: "Return all lines after this 0-based line index. Overrides lines when set." })),
-  }, {
-    description: "Return a peek (tail/filter/update) of the agent result or streaming output file. Ignored when verbose is true.",
-  }),
-),
-```
-
-### Behavior
-- `peek` is ignored when `verbose: true`.
-- If `after` is set, return all lines with index > `after` (or >= `after+1`). Include line numbers.
-- Else, return the last `lines` lines (default 20). Include line numbers.
-- If `regex` is provided, filter matching lines **first**, then apply tail/after semantics. Include line numbers of the original source.
-- Source precedence:
-  1. If agent is running and `record.outputFile` exists, read from the streaming output file. Parse JSONL and extract assistant/toolResult text (most useful live content).
-  2. Else if `record.result` exists, split it into lines.
-  3. Else return: "No output yet."
-
-### Return format
-```
-Showing last 20 lines of agent output (line numbers from full output):
-
-[42] some line
-[43] another line
-...
-
----
-Use verbose: true for the full conversation, or omit peek for the complete result.
-```
-
-If `regex` is used, add: `(filtered by regex: /.../)`.
-If `after` is used, add: `(lines after index N)`.
-
-### Implementation notes
-- Add helper `peekAgentOutput(record, peek)` in a new file or in `src/index.ts` near `get_subagent_result`.
-- For output-file JSONL parsing, reuse/extract from `output-file.ts` or read the file line-by-line.
-- Handle regex parse errors gracefully — return a clear error message.
-- Avoid reading the whole file into memory if possible; for now `readFileSync` is acceptable because output files are bounded by session length and the tail case is common.
-
-### Tests
-- New test file `test/get-subagent-result-peek.test.ts` or extend existing `status-note-wiring.test.ts`:
-  - Peek tail of result.
-  - Peek with regex.
-  - Peek `after` offset.
-  - Peek ignored when verbose true.
-  - Peek on running agent with output file.
-  - Regex parse error handling.
-
----
-
-## 3. Description polish
-
-### `inherit_context`
-Current:
-> "If true, fork parent conversation into the agent. Default: false (fresh context)."
-
-New:
-> "If true, fork the parent conversation into the agent so it sees the chat history. Recommended for questions or requests that require current context. Default: false (fresh context)."
-
-Also update the eject template line in `src/index.ts`.
-
-### `isolation: "worktree"`
-Current:
-> "Set to 'worktree' to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion."
-
-New:
-> "Set to 'worktree' to run the agent in a temporary git worktree that is automatically created from the current repo state at HEAD and removed on completion. Changes are saved to a branch. Requires the working directory to be a git repo with at least one commit."
-
-Also update README.md and `examples/agent-tool-description.md` to match.
-
----
-
-## 4. Coordination / cross-cutting concerns
-
-- `get_subagent_result` description must mention the configurable timeout, e.g.:
-  > "If true, wait for the agent to complete before returning. Blocks up to the configured wait timeout (default 4.5 minutes). If the agent is still running when the timeout is reached, returns current status with instructions to call again. Default: false."
-
-- The settings UI should present `waitTimeoutSeconds` as "Wait timeout (30–3600s, default 270 = 4m30s)".
-
-- Tests for the timeout should use Vitest fake timers so they run fast and deterministically.
-
-- Peek should not duplicate verbose. Keep the contract: `verbose` = full conversation, `peek` = lightweight tail/filter.
-
----
-
-## 5. Things to consider removing / avoiding
-
-Before jumping in, review whether any existing code becomes dead weight:
-
-- The foreground execution path in `src/index.ts` is now dead code after the background-by-default change. We currently left it in place but unreachable. Consider whether to remove it in a separate cleanup pass (it complicates future changes).
-- `run_in_background` param is deprecated but still in the schema. Keep it for prompt compatibility; do not remove.
-- `AgentConfig.runInBackground` frontmatter default is still consulted by `resolveAgentInvocationConfig`. Since `index.ts` now forces `runInBackground = true`, the frontmatter field is effectively ignored. Consider whether to deprecate it in docs or leave it as a no-op.
-
----
-
-## 6. Acceptance criteria
-
-- [ ] `get_subagent_result wait:true` times out after the configured number of seconds and returns a clear message.
-- [ ] Timeout duration is configurable via `/agents → Settings` and persists to `.pi/subagents.json`.
-- [ ] `get_subagent_result` supports `peek` with `lines`, `regex`, and `after`.
-- [ ] `peek` returns line numbers and respects `verbose: true` (is ignored).
-- [ ] `inherit_context` and `isolation` descriptions are updated in tool schema, eject template, README, and example template.
-- [ ] All existing tests pass; new tests cover timeout + peek.
-- [ ] `npm run typecheck` and `npm run lint` clean.
-
----
-
-## 7. Implementation order
-
-1. Add `waitTimeoutSeconds` setting (settings.ts + index.ts wiring).
-2. Implement wait timeout in `get_subagent_result` execute.
-3. Add `peek` parameter + helper.
-4. Update descriptions for `inherit_context` and `isolation`.
-5. Update README + example template.
-6. Write tests.
-7. Run full test/typecheck/lint.
-
---- SUMMARY ---
-
-- Add a configurable `waitTimeoutSeconds` setting (default 270s) wired into `/agents → Settings` and `get_subagent_result wait:true`.
-- Add a `peek` object param to `get_subagent_result` for tail/filter/offset access to result/output-file with line numbers, ignored when `verbose` is true.
-- Polish `inherit_context` and `isolation: "worktree"` descriptions across schema, template, README, and example.
-- Tests, typecheck, lint.

package/.plans/README.md

@@ -1,14 +0,0 @@
-# `.plans/` — local planning scratch
-
-This directory holds ad-hoc plans, notes, and design sketches for this fork. It is gitignored so it does not pollute upstream diffs.
-
-## Conventions
-
-- One plan per file: `PLAN-<short-name>.md`.
-- Plans should include: motivation, files touched, behavior changes, UI/message changes, tests, acceptance criteria, implementation order, and a summary.
-- When a plan graduates to implementation, update the plan file with progress or archive it.
-- Delete obsolete plans to avoid stale guidance.
-
-## Active plans
-
-- `PLAN-next-changes.md` — configurable `get_subagent_result` wait timeout, peek/tail/regex/after parameter, and description polish for `inherit_context` / `isolation: "worktree"`.

package/reviews/proposal-structured-output-schema.md

@@ -1,135 +0,0 @@
-# Proposal: Structured JSON Output for Subagents
-
-**Date:** 2026-06-19  
-**Status:** Proposal / draft  
-**Related:** `reviews/subagent-features-comparison.md`
-
-## Problem
-
-Today, subagents return free-form text. The parent model must parse the text to extract lists, file paths, decisions, or any other structured data before it can feed results into the next tool or agent. This is slow, unreliable, and becomes a bottleneck when chaining multiple agents together.
-
-## Goal
-
-Add an optional `output_schema` parameter to the `Agent` tool. When supplied, the agent must return JSON matching the schema. The extension validates the output and surfaces either the parsed object or a clear validation error.
-
-The feature must be strictly opt-in: the default is free-form text, and agents should only use structured output when the caller explicitly needs it.
-
-## Design
-
-### Tool parameter
-
-Add to the `Agent` tool schema:
-
-```ts
-output_schema: Type.Optional(
-  Type.Union([Type.String(), Type.Object({})], {
-    description:
-      'Optional JSON Schema the agent\'s final answer must match. "": free-form text (recommended default; only use this when the consumer needs structured data).',
-  })
-),
-```
-
-- Accepts either a JSON Schema object or a JSON-stringified schema.
-- Default is `undefined` / `""` → free-form text, no validation.
-- The schema type is JSON Schema, the same standard already used for tool-call schemas in pi.
-
-### Frontmatter support
-
-Optionally allow agent `.md` files to pin a default schema:
-
-```yaml
----
-output_schema:
-  type: object
-  properties:
-    files:
-      type: array
-      items:
-        type: object
-        properties:
-          path: { type: string }
-          reason: { type: string }
-        required: [path, reason]
-  required: [files]
----
-```
-
-The caller-supplied `output_schema` overrides the frontmatter value. This lets custom agent types advertise a structured contract without every caller repeating it.
-
-### Prompt injection
-
-When `output_schema` is non-empty, append a concise instruction to the agent system prompt:
-
-> Your final answer must be a single JSON object matching the provided JSON Schema. Do not wrap the JSON in markdown fences, do not add commentary outside the JSON, and do not emit any text after the JSON object.
-
-### Validation
-
-On agent completion:
-
-1. Extract the last JSON object from the final assistant message.
-2. If the output is wrapped in markdown fences, strip them.
-3. Validate the parsed object against the JSON Schema using a lightweight validator (e.g. `ajv` or TypeBox's `Value.Check`).
-4. If validation fails:
-   - Mark the agent status as `failed`.
-   - Return an error message containing the schema validation errors and a snippet of the raw output.
-5. If validation passes:
-   - Include the parsed object in the result under a `structured` field.
-   - Keep the normal textual result preview so the notification UI stays readable.
-
-### Result shape
-
-For a structured agent, the result should expose:
-
-```json
-{
-  "ok": true,
-  "data": { "files": [...] },
-  "preview": "Found 5 auth-related files..."
-}
-```
-
-For failures:
-
-```json
-{
-  "ok": false,
-  "error": "Output did not match the provided JSON Schema",
-  "validationErrors": [...],
-  "rawPreview": "..."
-}
-```
-
-### Notification and join modes
-
-Structured output does not change the notification path. Background agents still send steering-style notifications. The XML payload can include a `<structured-output>` block with the serialized JSON so the parent model can reason about it directly.
-
-### Interaction with existing features
-
-- **Worktree isolation:** unchanged; the structured result is still returned through the normal completion path.
-- **Scheduling:** scheduled agents may use `output_schema` so recurring jobs produce machine-readable results.
-- **Resume:** resuming a structured agent does not re-validate old output; only the final completion is validated.
-- **Cross-extension RPC:** `output_schema` is serializable JSON and can be passed through the RPC spawn envelope.
-
-## Acceptance criteria
-
-- [ ] `Agent` tool accepts optional `output_schema` as JSON Schema object or string.
-- [ ] Default behavior remains free-form text; no validation when omitted.
-- [ ] Frontmatter supports optional `output_schema`.
-- [ ] System prompt instructs the agent to emit only matching JSON.
-- [ ] Output is parsed and validated strictly on completion.
-- [ ] Validation failures produce a clear error with the raw output snippet.
-- [ ] Validation successes expose parsed data in result notifications and RPC responses.
-- [ ] Tests cover valid schema, invalid schema, fenced JSON, and missing schema cases.
-- [ ] `npm run typecheck` and `npm run lint` pass.
-
-## Open questions
-
-1. Should we add a small built-in helper agent type that demonstrates structured output (e.g. `json-explorer`)?
-2. Should `output_schema` be surfaced in `/agents` agent-type descriptions so the orchestrator knows which agents return structured data?
-3. Should failed validation trigger automatic retry with a steering message, or fail fast?
-
-## Rationale
-
-JSON Schema was chosen because it is the same standard already used for pi tool definitions. Agents and users do not need to learn a new format, and existing tooling (TypeBox, `ajv`) integrates cleanly.
-
-Strict validation keeps the contract trustworthy. If a consumer asks for structured output, receiving invalid data is worse than receiving no data, because the consumer is likely to feed it into code that assumes correctness.

package/reviews/recursive-subagent-widget-preview.html

@@ -1,137 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>Recursive Subagents Widget Preview</title>
-  <style>
-    :root {
-      color-scheme: dark;
-      --bg: #0b1020;
-      --panel: #121a2d;
-      --terminal: #070b13;
-      --line: #29364f;
-      --text: #dbe7ff;
-      --muted: #7f8daa;
-      --dim: #566176;
-      --accent: #82aaff;
-      --green: #8bdc9f;
-      --yellow: #ffd479;
-      --red: #ff7f8f;
-      --cyan: #7ee7f5;
-      --purple: #c099ff;
-    }
-    * { box-sizing: border-box; }
-    body {
-      margin: 0;
-      background: radial-gradient(circle at 20% 0%, #1b2b50 0, transparent 35%), var(--bg);
-      color: var(--text);
-      font: 14px/1.45 ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-    }
-    main { max-width: 1220px; margin: 0 auto; padding: 32px; }
-    h1 { font-size: 28px; margin: 0 0 8px; }
-    h2 { font-size: 18px; margin: 28px 0 12px; color: #f0f5ff; }
-    h3 { font-size: 14px; margin: 0 0 10px; color: var(--accent); text-transform: uppercase; letter-spacing: .08em; }
-    p { color: #b9c6df; margin: 0 0 14px; }
-    .grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 18px; align-items: start; }
-    .card { background: color-mix(in srgb, var(--panel) 92%, white 8%); border: 1px solid var(--line); border-radius: 16px; padding: 18px; box-shadow: 0 12px 40px rgba(0,0,0,.25); }
-    .recommended { border-color: color-mix(in srgb, var(--accent) 70%, white 10%); box-shadow: 0 0 0 1px rgba(130,170,255,.15), 0 18px 55px rgba(22,41,82,.5); }
-    .terminal { background: var(--terminal); border: 1px solid #1e2a3e; border-radius: 12px; padding: 12px 14px; font: 13px/1.35 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; white-space: pre; overflow: hidden; min-height: 260px; }
-    .term-title { display: flex; gap: 6px; align-items: center; margin-bottom: 10px; color: var(--muted); font: 12px ui-monospace, monospace; }
-    .dot { width: 9px; height: 9px; border-radius: 999px; display: inline-block; }
-    .green { color: var(--green); } .yellow { color: var(--yellow); } .red { color: var(--red); } .cyan { color: var(--cyan); } .purple { color: var(--purple); }
-    .muted { color: var(--muted); } .dim { color: var(--dim); } .accent { color: var(--accent); }
-    .legend { display: flex; flex-wrap: wrap; gap: 10px; margin-top: 10px; color: var(--muted); font-size: 12px; }
-    .plan { display: grid; grid-template-columns: 1.2fr .8fr; gap: 18px; }
-    ol, ul { margin: 0; padding-left: 20px; color: #c4cee2; }
-    li { margin: 6px 0; }
-    .pill { display: inline-flex; align-items: center; gap: 6px; padding: 3px 8px; border-radius: 999px; background: #1b2740; border: 1px solid #344260; color: #cfd9ef; font-size: 12px; }
-    .wide { grid-column: 1 / -1; }
-    @media (max-width: 980px) { .grid, .plan { grid-template-columns: 1fr; } }
-  </style>
-</head>
-<body>
-  <main>
-    <h1>Recursive Subagents Widget — Plan + Visual Preview</h1>
-    <p>Verified issue: the current widget is flat and bound to one manager instance. It does not assemble a durable parent → child → grandchild tree from recursive agent metadata.</p>
-
-    <section class="plan">
-      <div class="card">
-        <h2>Implementation plan, once design is approved</h2>
-        <ol>
-          <li>Create a small tree model layer: records keyed by id, linked by <code>parentAgentId</code>, sorted by start time/status.</li>
-          <li>Teach lifecycle events / shared manager state to surface descendants to the root widget, not only direct children.</li>
-          <li>Add configurable widget modes: <code>compact</code> (Option A), <code>rich</code> (Option B), and <code>auto</code>.</li>
-          <li>Use the focused path view (Option C) when rendering from inside a subagent, or as an optional display mode later.</li>
-          <li>Add deterministic tests for parent → child → grandchild rendering, overflow, width truncation, completed/error linger, and mode switching.</li>
-          <li>Keep status bar compact: aggregate running/queued counts across the full tree.</li>
-        </ol>
-      </div>
-      <div class="card">
-        <h2>Acceptance criteria</h2>
-        <ul>
-          <li>Grandchildren and deeper descendants are visible.</li>
-          <li>Users can choose compact vs rich rendering in settings.</li>
-          <li>Subagents can see their location in the larger recursive tree.</li>
-          <li>Width/height bounded; no TUI overflow.</li>
-          <li>Running activity remains live and readable.</li>
-          <li>Completed/error states linger briefly in context.</li>
-        </ul>
-      </div>
-    </section>
-
-    <h2>Design options</h2>
-    <div class="grid">
-      <article class="card">
-        <h3>Mode: Compact tree</h3>
-        <div class="terminal"><div class="term-title"><span class="dot" style="background:#ff5f57"></span><span class="dot" style="background:#ffbd2e"></span><span class="dot" style="background:#28c840"></span><span>Agents widget</span></div><span class="accent">● Agents</span>
-├─ <span class="green">⠋</span> <b>Plan</b>  split task <span class="dim">· ↻3 · 2 tools · 1m 12s</span>
-│  ├─ <span class="green">⠹</span> <b>Explore</b>  inspect UI <span class="dim">· reading…</span>
-│  └─ <span class="yellow">✓</span> <b>auditor</b>  review paths <span class="dim">· 42s</span>
-└─ <span class="green">⠼</span> <b>general-purpose</b>  write tests <span class="dim">· editing…</span></div>
-        <p><b>Use as:</b> configurable mode <code>compact</code>. <b>Pros:</b> dense, low-risk, close to current widget. <b>Cons:</b> less rich for deep trees.</p>
-      </article>
-
-      <article class="card recommended">
-        <h3>Mode: Rich tree (default)</h3>
-        <div class="terminal"><div class="term-title"><span class="dot" style="background:#ff5f57"></span><span class="dot" style="background:#ffbd2e"></span><span class="dot" style="background:#28c840"></span><span>Agents widget</span></div><span class="accent">● Agents</span> <span class="muted">3 running · 1 queued · depth 3/4</span>
-├─ <span class="green">⠋</span> <b>Plan</b> <span class="purple">opus</span> <span class="muted">split task</span>
-│  <span class="dim">⎿ ↻3≤20 · 4 tools · 22.8k token (38%) · 1m 12s</span>
-│  ├─ <span class="green">⠹</span> <b>Explore</b> <span class="muted">inspect widget data flow</span>
-│  │  <span class="dim">⎿ reading agent-widget.ts · 14.2s</span>
-│  │  └─ <span class="green">⠼</span> <b>general-purpose</b> <span class="muted">trace manager ownership</span>
-│  │     <span class="dim">⎿ searching tests · 4.8s</span>
-│  └─ <span class="yellow">✓</span> <b>auditor</b> <span class="muted">review plan</span> <span class="dim">· 31s</span>
-├─ <span class="cyan">◦</span> <b>Explore</b> <span class="muted">queued after concurrency cap</span>
-└─ <span class="red">✗</span> <b>Plan</b> <span class="muted">old attempt</span> <span class="red">error: model unavailable</span></div>
-        <p><b>Use as:</b> configurable mode <code>rich</code>, recommended default. <b>Pros:</b> best visibility; activity/stats are readable; relationships are obvious. <b>Cons:</b> needs careful overflow rules.</p>
-      </article>
-
-      <article class="card">
-        <h3>Focused subagent location view</h3>
-        <div class="terminal"><div class="term-title"><span class="dot" style="background:#ff5f57"></span><span class="dot" style="background:#ffbd2e"></span><span class="dot" style="background:#28c840"></span><span>Agents widget</span></div><span class="accent">● Agents</span> <span class="muted">7 total · showing active branch</span>
-├─ <span class="green">⠋</span> <b>Plan</b>  split task <span class="dim">· 1m 12s</span>
-│  └─ <span class="green">⠹</span> <b>Explore</b>  inspect UI <span class="dim">· reading…</span>
-│     └─ <span class="green">⠼</span> <b>general-purpose</b>  trace manager <span class="dim">· searching…</span>
-├─ <span class="dim">+2 completed siblings hidden</span>
-└─ <span class="dim">+2 queued / stale descendants hidden</span></div>
-        <p><b>Use as:</b> view shown inside a subagent session to answer “where am I in the tree?” It can also become a selectable mode later. <b>Pros:</b> very compact under load.</p>
-      </article>
-    </div>
-
-    <section class="card wide" style="margin-top:18px;">
-      <h2>Settled direction so far</h2>
-      <p><span class="pill">rich default</span> <span class="pill">compact setting</span> <span class="pill">focused subagent view</span></p>
-      <p>Build one recursive tree model, then render it through multiple views. The root TUI widget can use <code>rich</code>, <code>compact</code>, or <code>auto</code>. A subagent-local widget can render the focused path view so the agent/operator sees the current subagent’s location in the whole delegation tree.</p>
-      <ul>
-        <li><b>Header:</b> aggregate full-tree counts and max observed depth.</li>
-        <li><b>Rich node:</b> connector + status icon/spinner + agent type + model/tag chips + description, plus detail line.</li>
-        <li><b>Compact node:</b> same tree structure, one line per agent, fewer stats.</li>
-        <li><b>Focused node:</b> ancestor path + current active branch + hidden sibling summaries.</li>
-        <li><b>Overflow:</b> collapse by subtree: <code>└─ +4 descendants hidden (2 running, 1 queued, 1 finished)</code>.</li>
-        <li><b>Fallback:</b> orphan records render under <code>Other agents</code> with a dim warning marker.</li>
-      </ul>
-    </section>
-  </main>
-</body>
-</html>

package/reviews/subagent-features-comparison.md

@@ -1,350 +0,0 @@
-# Subagent Feature Landscape — A Comparison for `pi-subagents`
-
-**Date:** 2026-06-18  
-**Scope:** Survey the subagent / multi-agent features shipping in leading coding agents and CLIs, extract the most useful and innovative ideas, and compare them to the current `pi-subagents` implementation.
-
-This document is meant to be a single reference for deciding which features are worth adopting, improving, or deliberately avoiding in `pi-subagents`.
-
----
-
-## 1. Feature taxonomy
-
-Across the tools surveyed, the interesting subagent capabilities cluster into a handful of categories:
-
-| Category | What it covers |
-|----------|----------------|
-| **Spawn model** | Tool-based (`Agent`), natural-language auto-delegation, `@agent` forcing, API/SDK spawn |
-| **Context isolation** | Fresh context vs. inherited conversation; context-window utilization signals |
-| **Tool & extension scoping** | Per-agent tool allowlists/denylists, sandbox mode (read-only, etc.), extension isolation |
-| **Concurrency & parallelism** | Background queue, max threads, parallel worktrees, join/group strategies |
-| **Orchestration** | Parent-driven fan-out, coordinator/agent-teams, shared task lists, self-coordination |
-| **Communication** | One-way result reporting, mid-run steering, peer-to-peer messaging |
-| **Scheduling** | Cron / interval / one-shot scheduled agents, CI-triggered agents |
-| **Lifecycle intervention** | Graceful max-turns wrap-up, hard abort, resume, hooks/quality gates |
-| **Sandbox / isolation** | Worktree isolation, container sandboxes, browser-agent isolation |
-| **Configuration** | Markdown + YAML, TOML, programmatic `agents` map, skills preloading |
-| **UI / observability** | Persistent widget, conversation viewer, styled notifications, token meters |
-| **Governance** | Model allowlists, approval gates, audit events, cross-extension RPC |
-
----
-
-## 2. Tool-by-tool survey
-
-### 2.1 Claude Code — subagents
-
-Claude Code implements subagents as a first-class `Agent` tool.
-
-**Key capabilities**
-
-- **Three definition styles:** programmatic `AgentDefinition` in the SDK, filesystem agents in `.claude/agents/*.md`, and a built-in `general-purpose` agent that is always available.
-- **Markdown + YAML agents:** each file has frontmatter (`name`, `description`, optional `tools`) plus a system prompt body. Project-scoped agents override user-scoped agents.
-- **Tool scoping:** agents receive a curated `tools` array; omitting it inherits the parent thread’s tools (including MCP). `disallowedTools` can block the `Agent` tool itself.
-- **Nested subagents:** as of Claude Code v2.1.172, subagents can spawn their own subagents. Foreground subagents can spawn at any depth; background subagents cannot spawn beyond depth 5.
-- **Fresh context by default:** the subagent’s context window starts empty; the only parent-to-child channel is the `Agent` tool’s prompt string.
-- **Lifecycle hooks:** shell hooks fire on events such as `SubagentStop` / `Stop`, letting users inject quality gates or external review steps.
-
-**What stands out**
-
-- The filesystem-based agent definition is simple and version-controllable.
-- The model can auto-delegate based on the agent’s `description`.
-- Nested subagents give genuine recursive delegation.
-
-**Sources:** [Claude Code subagent docs](https://code.claude.com/docs/en/agent-sdk/subagents), [PubNub best-practices write-up](https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/)
-
-### 2.2 Claude Code — Agent Teams (experimental)
-
-Agent Teams are a different, heavier abstraction from ordinary subagents: they coordinate multiple independent Claude Code sessions rather than nested tool calls.
-
-**Key capabilities**
-
-- **Peer-to-peer messaging:** teammates message each other directly, not just through the parent.
-- **Shared task list:** the team coordinates through a shared task list with self-coordination.
-- **Lead / teammate model:** the main session is the lead; teammates are spawned on request or when the model decides it needs help.
-- **Quality-gate hooks:** `TeammateIdle`, `TaskCreated`, and `TaskCompleted` hooks can block idle/creation/completion with exit code 2 and send feedback.
-- **Graceful shutdown:** the lead can ask a teammate to shut down; the teammate may approve or reject.
-- **Shared directories:** team workspace directories are cleaned up automatically on session end.
-
-**What stands out**
-
-- This is the most sophisticated *team* abstraction among the surveyed tools: agents are true peers with a task board and direct messaging.
-- Quality-gate hooks are a genuine governance primitive.
-
-**Sources:** [Claude Code agent teams docs](https://code.claude.com/docs/en/agent-teams)
-
-### 2.3 OpenAI Codex
-
-Codex treats subagent workflows as explicit, user-requested parallel fan-outs.
-
-**Key capabilities**
-
-- **Explicit orchestration:** Codex spawns, routes follow-up instructions, waits for results, and closes agent threads only when the user asks for subagents.
-- **Built-in + custom agents:** ships `default`, `worker`, and `explorer` plus user-defined TOML agents under `.codex/agents/`.
-- **Global `[agents]` settings:** `max_threads` (default 6), `max_depth` (default 1), `job_max_runtime_seconds`.
-- **Per-agent config:** `model`, `model_reasoning_effort`, `sandbox_mode` (`read-only`), `developer_instructions`.
-- **Sandbox modes:** read-only exploration agents, with broader sandbox-agent support in the Agents SDK.
-- **Agents SDK integration:** the CLI can be exposed as an MCP server and orchestrated from the OpenAI Agents SDK.
-- **`spawn_agents_on_csv`:** batch-style fan-out over a CSV of inputs, with per-worker timeouts.
-
-**What stands out**
-
-- The TOML config is more structured than Markdown frontmatter but less readable as a document.
-- `max_threads`/`max_depth` are simple, effective global governors.
-- Explicit orchestration keeps the user in control but requires intentional prompting.
-
-**Sources:** [Codex subagents docs](https://developers.openai.com/codex/subagents), [Codex subagent concepts](https://developers.openai.com/codex/concepts/subagents), [Codex Agents SDK guide](https://developers.openai.com/codex/guides/agents-sdk), [Simon Willison’s notes](https://simonwillison.net/2026/Mar/16/codex-subagents/)
-
-### 2.4 Google Gemini CLI
-
-Gemini CLI describes subagents as specialists the main agent can “hire.”
-
-**Key capabilities**
-
-- **Subagents-as-tools:** each subagent is exposed to the main agent as a callable tool with the same name.
-- **Built-in agents:** `codebase_investigator`, `cli_help`, `generalist_agent`, and an experimental `browser_agent`.
-- **Custom agents:** Markdown + YAML frontmatter under `.gemini/agents/*.md` or `~/.gemini/agents/*.md`.
-- **`@agent_name` forcing:** prefix a prompt with `@agent_name` to force delegation to that agent.
-- **Parallel execution:** multiple subagents (or instances of the same subagent) can run concurrently.
-- **Isolated context loops:** each subagent operates in its own context loop.
-- **No recursion:** subagents cannot call other subagents, preventing runaway agent loops.
-- **Agent Skills:** skills are self-contained directories following the [Agent Skills](https://agentskills.io) open standard, discovered from built-ins, extensions, user, and workspace tiers.
-- **Browser-agent sandboxing:** adjusts behavior under macOS seatbelt and Docker/Podman; can connect to a host Chrome over remote debugging.
-
-**What stands out**
-
-- The `@agent` syntax is a fast, ergonomic forcing mechanism.
-- Treating subagents as tools makes the mental model very simple.
-- The built-in browser agent is a genuinely useful default specialist.
-
-**Note:** As of June 2026, Gemini CLI is being superseded by Antigravity CLI for unpaid users.
-
-**Sources:** [Gemini CLI subagents docs](https://geminicli.com/docs/core/subagents/), [Gemini CLI skills docs](https://geminicli.com/docs/cli/skills/), [Google Developers Blog announcement](https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/)
-
-### 2.5 Cursor
-
-Cursor 2.4 introduced subagents as parallel, specialized workers inside the editor and CLI.
-
-**Key capabilities**
-
-- **Independent parallel agents:** each subagent has its own context window and can run alongside the main agent.
-- **Default subagents:** included defaults for codebase research, terminal commands, and parallel work streams.
-- **Custom subagents:** users can define custom prompts, tool access, and models.
-- **Skills:** reusable skill definitions that can be attached to agents.
-- **IDE integration:** subagents run inside the same editor session as the main agent.
-
-**What stands out**
-
-- Cursor’s main differentiator is the tight IDE integration: subagents can work while the user keeps editing.
-- The combination of subagents + skills is aimed at repeatable team workflows.
-
-**Sources:** [Cursor 2.4 changelog](https://cursor.com/changelog/2-4), [Cursor subagents guide](https://www.aimakers.co/blog/cursor-2-4-subagents/)
-
-### 2.6 Cline / Kilo Code
-
-Cline is an open-source VS Code extension and CLI with a plan/act workflow. Kilo Code is a hard fork with an explicit focus on multi-agent teams.
-
-**Key capabilities**
-
-- **Plan / Act modes:** separate planning from execution.
-- **Coordinator agents:** a coordinator delegates to specialists with their own tools and context.
-- **Schedules:** agents can be run on cron for recurring automations.
-- **Parallel isolated worktrees:** Kilo advertises “parallel isolated worktrees” for safe concurrent edits.
-- **Skills / `.clinerules`:** repo-local rules and skills teach the agent standards and conventions.
-- **MCP + plugins:** extend tools via MCP and the Cline SDK.
-- **Agent Manager / Portal:** Kilo provides a single portal to supervise local and cloud agents across IDE/CLI.
-
-**What stands out**
-
-- Cline/Kilo is the only open-source entry besides `pi-subagents` that combines scheduling, parallel worktrees, and coordinator/specialist teams.
-- The plan/act split is a useful UX primitive for risky or multi-step tasks.
-
-**Sources:** [Cline homepage](https://cline.bot/), [Kilo Code homepage](https://kilo.ai/)
-
-### 2.7 Roo Code
-
-Roo Code is an open-source VS Code extension built around *modes*.
-
-**Key capabilities**
-
-- **Modes as agents:** each mode is a persona/role with its own instructions and assigned model (`Code`, `Architect`, `Ask`, `Debug`, `Orchestrator`, …).
-- **Orchestrator mode:** a strategic workflow orchestrator that breaks complex tasks into discrete subtasks and delegates them to specialized modes.
-- **Multi-provider support:** OpenAI, Anthropic, local models via LiteLLM.
-- **Context indexing:** Roo Code uses indexing and prompt management to maintain context across modes.
-
-**What stands out**
-
-- The Orchestrator mode is an elegant lightweight team abstraction: modes are cheap to define and the orchestrator mode handles routing.
-- At the time of writing, parallel execution of specialists is still an open enhancement request; delegation is primarily sequential.
-
-**Sources:** [Roo Code GitHub](https://github.com/RooCodeInc/Roo-Code), [Xebia multi-agent workflow write-up](https://xebia.com/blog/multi-agent-workflow-with-roo-code/)
-
-### 2.8 Aider
-
-Aider does not have subagents in the Claude Code sense, but its **architect mode** is an interesting adjacent pattern.
-
-**Key capabilities**
-
-- **Architect / editor model split:** the architect model (often a reasoning model like o1/Opus) proposes a solution, then a separate editor model turns that proposal into concrete file edits.
-- **Chat modes:** `code`, `ask`, `architect`, `help`; modes can be sticky or per-message.
-- **Git-first workflow:** every change is committed automatically.
-
-**What stands out**
-
-- This is *specialization by model* rather than *specialization by agent*. It proves that splitting reasoning from execution can improve quality without full agent orchestration.
-- It is cheaper and simpler than a multi-agent runtime, but less flexible.
-
-**Sources:** [Aider chat modes docs](https://aider.chat/docs/usage/modes.html), [Aider vs Claude Code 2026](https://www.developersdigest.tech/blog/aider-vs-claude-code-2026-update)
-
-### 2.9 Continue.dev
-
-Continue.dev is an open-source coding agent (CLI, VS Code, JetBrains) with a strong focus on repeatable, team-level agent workflows.
-
-**Key capabilities**
-
-- **Agents for PR/CI workflows:** automated code review, PR checks, and development workflows on every pull request.
-- **Hub:** centralized configuration, shared custom agents, and secure API-key management.
-- **Audit and monitoring:** agent actions and decisions are observable for teams.
-
-**What stands out**
-
-- Continue is less about runtime subagent spawning and more about packaging agents as reusable team services.
-- The hub/audit model is worth studying for any extension that wants to scale across an organization.
-
-**Sources:** [Continue.dev agents](https://www.continue.dev/agents), [Continue agents blog](https://blog.continue.dev/what-are-continue-agents-any-workflow-your-teams-way/)
-
-### 2.10 OpenHands
-
-OpenHands is an open-source, model-agnostic cloud platform for coding agents.
-
-**Key capabilities**
-
-- **Cloud / headless agents:** run agents in isolated sandboxes on a VM or in the cloud.
-- **Multi-agent collaboration:** supports multiple agents working together on large refactors.
-- **Triggers and schedules:** GitHub, Slack, PagerDuty, cron-style scheduling even when the user’s machine is off.
-- **SDK + REST API:** embed agents into products or internal platforms.
-- **Governance:** access controls, audit trails, cost guardrails.
-
-**What stands out**
-
-- OpenHands is the most enterprise-oriented: it is about fleet management, not just a single CLI session.
-- The combination of multi-agent collaboration + scheduled triggers + governance is the direction many teams will eventually want.
-
-**Sources:** [OpenHands homepage](https://openhands.dev/), [OpenHands SDK docs](https://docs.openhands.dev/sdk)
-
----
-
-## 3. Feature matrix
-
-| Capability | Claude Code subagents | Claude Code Agent Teams | Codex | Gemini CLI | Cursor | Cline / Kilo | Roo Code | `pi-subagents` |
-|---|---|---|---|---|---|---|---|---|
-| **Spawn style** | `Agent` tool | Lead / teammate sessions | Explicit user prompt | Tool-like `@agent` | Tool/IDE action | Coordinator delegate | Orchestrator mode | `Agent` tool |
-| **Custom agent config** | `.claude/agents/*.md` | Same + teammate profiles | `.codex/agents/*.toml` | `.gemini/agents/*.md` | Custom prompts + skills | `.clinerules` / skills | Mode files | `.pi/agents/*.md` |
-| **Built-in agents** | `general-purpose`, `Explore`, `Plan` | N/A (team roles) | `default`, `worker`, `explorer` | `codebase_investigator`, `cli_help`, `generalist_agent`, `browser_agent` | Research, terminal, parallel | Coordinator + specialists | Code, Architect, Ask, Debug, Orchestrator | `general-purpose`, `Explore`, `Plan` |
-| **Tool scoping** | `tools`, `disallowedTools` | Per-teammate tools | `sandbox_mode`, per-agent tools | `tools`, wildcards | Custom tool access | Yes | Yes | `tools`, `disallowed_tools`, `ext:` selectors, `isolated` |
-| **Concurrency control** | Background/foreground, nesting depth | Multiple teammates | `max_threads`, `max_depth` | Parallel instances | Up to 10 concurrent ops | Parallel isolated worktrees | Sequential primarily | `maxConcurrent` queue, recursive depth limit |
-| **Context model** | Fresh by default, optional inherit | Fully independent sessions | Fresh threads | Isolated context loops | Own context window | Own context | Indexed prompt mgmt | Fresh by default, optional `inherit_context` |
-| **Mid-run steering** | No (stop/abort only) | Yes (messages, shutdown) | No | No | No | ? | ? | `steer_subagent` |
-| **Scheduling** | No | No | `spawn_agents_on_csv` / SDK | No | No | Cron schedules | No | Cron, interval, one-shot |
-| **Worktree / sandbox isolation** | No built-in worktree | Shared team dirs | Sandbox agents (container) | Browser sandboxing | No | Parallel worktrees | No | `isolation: "worktree"` |
-| **Join / group results** | Summarized inline | Shared task list | Wait + consolidate | Summarized inline | Main agent collates | ? | ? | `smart` / `async` / `group` join modes |
-| **Resume sessions** | No | Session resumption | ? | No | ? | ? | ? | Yes (`resume`) |
-| **Lifecycle hooks** | `SubagentStop`, `Stop`, etc. | `TeammateIdle`, `TaskCreated`, `TaskCompleted` | ? | No | No | ? | ? | Event bus (`subagents:*`) |
-| **Cross-extension RPC** | No | No | MCP server exposure | No | No | MCP/SKD | No | `pi.events` RPC (`spawn`, `stop`, `ping`) |
-| **Persistent memory** | No | No | No | No | ? | ? | ? | Project / local / user `MEMORY.md` |
-| **UI / observability** | Inline Claude Code UI | Inline Claude Code UI | CLI output | CLI output | IDE widget | IDE + portal | VS Code UI | Persistent widget, conversation viewer, styled notifications |
-| **Model governance** | Model override per agent | Per-teammate model | `model`, `model_reasoning_effort` | Model selection | Per-subagent model | Multi-provider | Multi-provider | Fuzzy selection, `enabledModels` scope check |
-
-*Empty cells mean the capability was not documented or is not a first-class feature.*
-
----
-
-## 4. How `pi-subagents` compares
-
-### 4.1 Where `pi-subagents` is already strong
-
-- **Filesystem-first custom agents:** the Markdown + YAML frontmatter model matches Claude Code and Gemini CLI, which is the most user-friendly of the config formats.
-- **Rich tool scoping:** `tools`, `disallowed_tools`, `extensions`, `exclude_extensions`, and `ext:<extension>/<tool>` selectors are more granular than most competitors.
-- **Background orchestration:** concurrency queue, background-by-default, and configurable join modes (`smart`/`async`/`group`) are not common; Claude Code and Codex do not expose join strategies.
-- **Mid-run steering:** `steer_subagent` is a genuine differentiator; none of the surveyed tools except Claude Code Agent Teams offer a comparable intervention primitive.
-- **Scheduling:** built-in cron / interval / one-shot scheduling is rare; only Cline/Kilo and OpenHands advertise it.
-- **Worktree isolation:** `isolation: "worktree"` with automatic branch preservation is a powerful primitive for safe parallel writes; Codex/Cursor/Gemini do not offer it out of the box.
-- **Cross-extension RPC + event bus:** letting other pi extensions spawn, stop, and observe subagents via `pi.events` is unique in this survey.
-- **Persistent memory + skill preloading:** project/local/user memory scopes and automatic skill injection are ahead of the simpler config-only agents in Codex/Gemini.
-- **UI polish:** the persistent widget, conversation viewer, token-meter, and styled notifications are richer than the CLI-only competitors.
-- **Graceful max-turns:** the wrap-up-then-abort behavior is a nice user-experience touch.
-
-### 4.2 Notable gaps relative to competitors
-
-- **Agent teams / peer-to-peer collaboration:** Claude Code Agent Teams’ shared task list, direct teammate messaging, and quality-gate hooks are not replicated. `pi-subagents` is strictly parent-child.
-- **Explicit orchestration primitives:** Codex’s `spawn_agents_on_csv`, batch timeouts, and Agents SDK integration make large fan-outs more ergonomic. `pi-subagents` requires the parent LLM to drive every spawn.
-- **Built-in browser agent:** Gemini CLI ships a `browser_agent`; `pi-subagents` can only get browsing through an MCP extension or tool.
-- **Sandbox modes:** Codex’s `sandbox_mode: read-only` / container sandbox agents provide stronger safety guarantees than tool allowlists alone.
-- **Coordinator / orchestrator mode:** Roo Code’s Orchestrator mode and Cline/Kilo’s coordinator agents are lightweight ways to auto-route tasks. `pi-subagents` relies on the parent model to pick `subagent_type`.
-- **Aider-style architect/editor split:** this is a cheap, high-leverage specialization pattern that does not require a full subagent runtime.
-- **Audit / hub model:** Continue.dev and OpenHands emphasize team-level configuration, audit trails, and cost guardrails, which `pi-subagents` does not address.
-
-### 4.3 Where the design philosophies diverge
-
-- **Claude Code / `pi-subagents`** emphasize *task routing and permission shaping* — the parent decides who gets which tools.
-- **Codex** emphasizes *explicit parallel spawning and result collection* — the user must ask for a team.
-- **Gemini CLI** treats subagents *as tools* with simple `@agent` forcing.
-- **Cline/Kilo** and **OpenHands** push toward *persistent, schedulable, cloud-scale agent teams*.
-
-`pi-subagents` currently sits closest to Claude Code, but with scheduling, worktree isolation, and cross-extension RPC as its own differentiators.
-
----
-
-## 5. Interesting features worth borrowing
-
-Based on the survey, the highest-value additions to consider for `pi-subagents` are:
-
-1. **Coordinator / orchestrator agent type**  
-   A built-in mode whose job is to break a large task into subtasks and fan them out to other agents. This would reduce the burden on the parent model and make multi-agent workflows feel more automatic.
-
-2. **Batch fan-out primitive**  
-   Something like Codex’s `spawn_agents_on_csv` or a “map over files/packages” helper would make it easy to run the same agent across many inputs in parallel.
-
-3. **Shared task list / agent-team mode**  
-   Optional peer-to-peer messaging and a shared task board would move `pi-subagents` from parent-child delegation to true team collaboration.
-
-4. **Quality-gate hooks**  
-   Shell hooks at `task-created`, `task-completed`, `agent-idle`, etc., would let teams enforce policies without writing a full extension.
-
-5. **Sandbox mode abstraction**  
-   Beyond worktree isolation, a `sandbox_mode: read-only` (and eventually container) option would make read-only agents safer and more discoverable.
-
-6. **Built-in browser agent**  
-   A default `browser` agent type, even if implemented via a headless browser tool, would match Gemini CLI and Cursor.
-
-7. **Architect/editor model split**  
-   A config option to run a planning model first and a cheaper editing model second could improve complex edits without the cost of full agent orchestration.
-
-8. **Audit / cost events**  
-   Richer event payloads (cost per agent, per project, per user) would make `pi-subagents` more attractive for team usage.
-
----
-
-## 6. References
-
-- [Claude Code subagent SDK docs](https://code.claude.com/docs/en/agent-sdk/subagents)
-- [PubNub — Best practices for Claude Code subagents](https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/)
-- [Claude Code agent teams docs](https://code.claude.com/docs/en/agent-teams)
-- [OpenAI Codex — Subagents](https://developers.openai.com/codex/subagents)
-- [OpenAI Codex — Subagent concepts](https://developers.openai.com/codex/concepts/subagents)
-- [OpenAI Codex — Use with the Agents SDK](https://developers.openai.com/codex/guides/agents-sdk)
-- [Simon Willison — Use subagents and custom agents in Codex](https://simonwillison.net/2026/Mar/16/codex-subagents/)
-- [Gemini CLI subagents docs](https://geminicli.com/docs/core/subagents/)
-- [Gemini CLI skills docs](https://geminicli.com/docs/cli/skills/)
-- [Google Developers Blog — Subagents have arrived in Gemini CLI](https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/)
-- [Cursor 2.4 changelog](https://cursor.com/changelog/2-4)
-- [Cursor 2.4 subagents guide](https://www.aimakers.co/blog/cursor-2-4-subagents/)
-- [Cline homepage](https://cline.bot/)
-- [Kilo Code homepage](https://kilo.ai/)
-- [Roo Code GitHub](https://github.com/RooCodeInc/Roo-Code)
-- [Xebia — Multi-agent workflow with Roo Code](https://xebia.com/blog/multi-agent-workflow-with-roo-code/)
-- [Aider chat modes docs](https://aider.chat/docs/usage/modes.html)
-- [Aider vs Claude Code 2026](https://www.developersdigest.tech/blog/aider-vs-claude-code-2026-update)
-- [Continue.dev agents](https://www.continue.dev/agents)
-- [Continue.dev — What are Continue agents?](https://blog.continue.dev/what-are-continue-agents-any-workflow-your-teams-way/)
-- [OpenHands homepage](https://openhands.dev/)
-- [OpenHands SDK docs](https://docs.openhands.dev/sdk)
-- [Medium — Multi-agent comparison: Codex, Claude Code, Gemini CLI](https://medium.com/@aristojeff/what-are-multi-agent-systems-and-subagents-a-comparison-of-codex-claude-code-and-gemini-cli-304376584f51)