@clanker-code/pi-subagents 0.10.5 → 0.10.7

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)