# pi-subagents: Feature Gap Roadmap

> **Date:** 2026-05-12
> **Project:** `@tintinweb/pi-subagents` v0.7.1
> **Reference:** Claude Code source snapshot (claude-code-main)

---

## Overview

This roadmap closes the gap between pi-subagents and the Claude Code subagent system. Each phase is ordered by impact/effort ratio — highest leverage first. Phases are independent and can be tackled in any order; dependencies are noted in each phase.

### Quick Reference

| # | Phase | Effort | Impact | Dependencies | Priority |
|---|---|---|---|---|---|
| 1 | Fork Subagent | 2–3 days | High | None | **P0** |
| 2 | Per-Agent MCP Servers | 2–3 days | High | None | **P1** |
| 3 | Verification Agent | 0.5 days | Medium | None | **P2** |
| 4 | Agent Identity & Coloring | 0.5 days | Medium | None | **P3** |
| 5 | Richer System Prompts | 0.5 days | Medium | None | **P4** |
| 6 | Per-Agent Hooks System | 2 days | Medium | Phase 4 (nice-to-have) | **P5** |
| 7 | Multi-Agent Team System | 1–2 weeks | High | Phases 1, 4, 6 | **P6** |

---

## Phase 1: Fork Subagent

**Priority: P0 · Effort: 2–3 days · Dependencies: None**

The fork subagent is the primary Claude Code delegation pattern. When the LLM omits `subagent_type`, the Agent tool creates a fork child that inherits the parent's full conversation context — system prompt, message history, and tool pool — with byte-identical API request prefixes for prompt cache sharing. Includes a `/fork <directive>` slash command and recursive fork protection.

**Reference**: `claude-code-main/src/tools/AgentTool/forkSubagent.ts`
**Docs**: `docs/phase-01-fork-subagent/`

---

## Phase 2: Per-Agent MCP Server Support

**Priority: P1 · Effort: 2–3 days · Dependencies: None**

Allow agent definitions (both `.md` and defaults) to declare `mcpServers` — MCP servers that are connected when the agent starts and cleaned up when it finishes. Supports both named references to existing parent-session MCP servers and inline definitions. Enables agents to have specialized external service access (database, Slack, browser, etc.) without burdening the parent session.

**Reference**: `claude-code-main/src/tools/AgentTool/runAgent.ts` (`initializeAgentMcpServers`)
**Docs**: `docs/phase-02-mcp-per-agent/`

---

## Phase 3: Verification Agent

**Priority: P2 · Effort: 0.5 days · Dependencies: None**

Add a read-only verification agent type that runs builds, tests, linters, and adversarial probes to produce a PASS/FAIL/PARTIAL verdict. This rounds out the built-in agent set to match Claude Code's 6 agents. The agent uses read-only tools and writes ephemeral test scripts to `/tmp`.

**Reference**: `claude-code-main/src/tools/AgentTool/built-in/verificationAgent.ts`
**Docs**: `docs/phase-03-verification-agent/`

---

## Phase 4: Agent Identity & Coloring

**Priority: P3 · Effort: 0.5 days · Dependencies: None**

Assign colors to running agents in the widget for visual differentiation during parallel execution. Support an optional `color` field in agent frontmatter. Extends `AgentDetails` and the widget renderer.

**Reference**: `claude-code-main/src/tools/AgentTool/agentColorManager.ts`
**Docs**: `docs/phase-04-agent-identity/`

---

## Phase 5: Richer System Prompts

**Priority: P4 · Effort: 0.5 days · Dependencies: None**

Expand the Explore and Plan agent system prompts to match the depth and guidance quality of the Claude Code equivalents. Adds structured planning process, tool usage guidance, output format specifications, and environment-awareness context.

**Reference**: `claude-code-main/src/tools/AgentTool/built-in/planAgent.ts`, `exploreAgent.ts`, `generalPurposeAgent.ts`
**Docs**: `docs/phase-05-rich-prompts/`

---

## Phase 6: Per-Agent Hooks System

**Priority: P5 · Effort: 2 days · Dependencies: Phase 4 (optional — agent identity for hook scoping)**

Allow agent frontmatter to declare lifecycle hooks (`SessionStart`, `SubagentStart`, `UserPromptSubmit`, `Stop`/`SubagentStop`, `PostSampling`) that are registered when the agent starts and cleaned up when it finishes. Builds on the existing `pi.events` lifecycle event system.

**Reference**: `claude-code-main/src/utils/hooks/` (`registerFrontmatterHooks.ts`, `sessionHooks.ts`)
**Docs**: `docs/phase-06-hooks-system/`

---

## Phase 7: Multi-Agent Team System

**Priority: P6 · Effort: 1–2 weeks · Dependencies: Phases 1, 4, 6 (partial — can start with simplified model)**

Full multi-agent collaboration: team creation, inter-agent messaging via a mailbox system, in-process teammate spawning, agent identity and addressing, team file persistence. This is the architecture-defining feature. Start with in-process teammates (same Node.js process, AsyncLocalStorage-based isolation) and add tmux/iTerm2 backends later.

**Reference**: `claude-code-main/src/utils/swarm/`, `src/tasks/InProcessTeammateTask/`, `src/tools/shared/spawnMultiAgent.ts`
**Docs**: `docs/phase-07-multi-agent-team/`

---

## Appendix: Mapping to Claude Code Source

| Area | Claude Code Reference Files |
|---|---|
| Fork Subagent | `src/tools/AgentTool/forkSubagent.ts`, `src/utils/forkedAgent.ts` |
| Per-Agent MCP | `src/tools/AgentTool/runAgent.ts` (`initializeAgentMcpServers`) |
| Built-in Agent Types | `src/tools/AgentTool/built-in/*.ts`, `src/tools/AgentTool/builtInAgents.ts` |
| Agent Identity | `src/tools/AgentTool/agentColorManager.ts` |
| Prompts | `src/tools/AgentTool/built-in/planAgent.ts`, `exploreAgent.ts`, `generalPurposeAgent.ts` |
| Hooks | `src/utils/hooks/registerFrontmatterHooks.ts`, `sessionHooks.ts` |
| Multi-Agent | `src/utils/swarm/`, `src/tasks/InProcessTeammateTask/`, `src/tools/shared/spawnMultiAgent.ts` |
| Agent Definition | `src/tools/AgentTool/loadAgentsDir.ts` |