# pi-ultra-subagents

A focused [Pi](https://pi.dev) package for ultra-capable sub-agents.

It adds a `subagent` tool plus interactive `$agent` sessions so Pi can delegate work to isolated child Pi runtimes, optionally inherit the current session context, and merge structured results back into the parent conversation.

## Features

- Isolated sub-agent execution in temporary child Pi processes.
- `fresh` and `fork-current` context modes.
- Single, parallel, and chained delegation through the `subagent` tool.
- Interactive `$agent` chat sessions in the TUI.
- `$agent` autocomplete for available sub-agents.
- `/agents` browser for inspecting available agent definitions.
- Structured completion through `subagent_finish`.
- Result merge modes: `result-only`, `full-transcript`, and `none`.
- Project-local agent confirmation before running repo-controlled agents.
- Bundled agents: `researcher`, `reviewer`, `planner`, `scout`, and `worker`.

## Install

From npm after publication:

```bash
pi install npm:pi-ultra-subagents
```

From GitHub:

```bash
pi install git:github.com/liangxiao777/pi-ultra-subagents
```

For local development:

```bash
pi -e /path/to/pi-ultra-subagents
```

Or install a local checkout:

```bash
pi install /path/to/pi-ultra-subagents
```

After changing the package during a running Pi session, use `/reload` or restart Pi.

## Usage

### Interactive `$agent` chat

Start an embedded sub-agent chat from the main editor:

```text
$researcher compare this implementation with upstream Pi package docs
$reviewer review the current diff for correctness and release blockers
$planner create a migration plan for extracting the package
```

Interactive behavior:

- Type `$` and use completion to select an available agent.
- If no task is provided, Pi prompts for one.
- If the selected agent is project-local, Pi asks for confirmation first.
- Pi asks whether to inherit the current conversation context:
  - Yes: `fork-current` / inherited context.
  - No: `fresh` / isolated context.
- The embedded chat shows live child-agent activity and the active context mode.
- When leaving the embedded chat, choose how to save it back to the parent session:
  - `Save final answer only`
  - `Save full transcript`
  - `Back to sub-agent session`
  - `Do not save`

### Tool-based delegation

Ask Pi to use the `subagent` tool for delegated work.

Single sub-agent:

```text
Use the planner sub-agent to create an implementation plan for adding tests.
```

Fork current context into a child runtime:

```text
Use subagent with agent "reviewer", task "review the current changes", and contextMode "fork-current".
```

Parallel delegation:

```text
Run scout and reviewer in parallel: scout should map the codebase, reviewer should inspect the latest diff.
```

Chained workflow:

```text
Use a chain: scout relevant files, planner designs the change from {previous}, worker implements from {previous}.
```

The tool accepts exactly one execution mode:

```ts
// Single
{ agent: "planner", task: "Create a plan" }

// Parallel
{
  tasks: [
    { agent: "scout", task: "Find relevant files" },
    { agent: "reviewer", task: "Review the current diff" }
  ]
}

// Chain
{
  chain: [
    { agent: "scout", task: "Find relevant files" },
    { agent: "planner", task: "Plan using this context: {previous}" }
  ]
}
```

Optional tool parameters:

| Parameter | Values | Default | Description |
|---|---|---|---|
| `agentScope` | `user`, `project`, `both` | `user` | Which agent sources to use. `user` includes package agents plus `~/.pi/agent/agents`; `project` uses project agents only; `both` uses all. |
| `confirmProjectAgents` | boolean | `true` | Prompt before running project-local agents. |
| `contextMode` | `fresh`, `fork-current` | `fresh` | `fresh` starts an isolated child session. `fork-current` copies the current session prefix into the child runtime. |
| `mergeMode` | `result-only`, `full-transcript`, `none` | `result-only` | Controls what is returned to the parent model. |
| `requireStructuredResult` | boolean | `false` | Treat missing `subagent_finish` as an error instead of accepting an unstructured fallback. |
| `cwd` | string | current cwd | Working directory for single mode. Each `tasks[]` or `chain[]` item can also set `cwd`. |

### Context modes

- `fresh`: create a temporary empty child session.
- `fork-current`: copy the current session's stable prefix byte-for-byte, then append child-only sub-agent runtime instructions and the delegated task.

If the current parent session is ephemeral or cannot be copied, `fork-current` falls back to `fresh`. The TUI displays the actual mode used: `fork-current / inherited` or `fresh / isolated`.

### Result merging

Sub-agents are instructed to finish by calling `subagent_finish`, which captures:

- `status`
- `summary`
- `findings`
- `files`
- `changes`
- `nextActions`
- `openQuestions`

`mergeMode` controls what the parent receives:

- `result-only`: compact structured result rendered from `subagent_finish`.
- `full-transcript`: full child output.
- `none`: only report that the sub-agent completed.

### Browse agents

Use `/agents` to list available sub-agent definitions and preview their raw markdown files.

```text
/agents          # same as /agents both
/agents both     # package + user + nearest project agents
/agents user     # package + user agents
/agents project  # nearest project agents only
```

Agent discovery locations:

- package agents: `<installed-package>/agents/*.md`
- user agents: `~/.pi/agent/agents/*.md`
- project agents: nearest `.pi/agents/*.md` found by walking up from the current working directory

In `both` mode, same-name agents are resolved as `project > user > package`.

The main agent's system prompt is also augmented with a compact list of available sub-agents so it can choose the `subagent` tool when delegation is useful.

## Agent definitions

Bundled agents live in `agents/*.md` and use YAML frontmatter:

```markdown
---
name: planner
description: Creates implementation plans from context and requirements
tools: read, grep, find, ls, bash
model: claude-sonnet-4-5
---

System prompt for the agent goes here.
```

Fields:

- `name`: command/tool-facing agent name.
- `description`: shown in `/agents`, autocomplete, and system-prompt agent lists.
- `tools`: optional comma-separated tool allowlist for the child runtime.
- `model`: optional model override for the child runtime.

The extension discovers agents from:

- package agents bundled in this package
- user agents in `~/.pi/agent/agents`
- project agents in `.pi/agents` when explicitly enabled with `agentScope: "project"` or `"both"`

Project agents are repo-controlled prompts. Keep the default confirmation enabled unless you trust the repository.

## Runtime notes

- Child agents run through temporary Pi child processes in RPC mode.
- Child sessions are cleaned up after the sub-agent run finishes.
- Child UI requests such as select, confirm, input, editor, notify, status, and widgets are bridged back to the parent Pi UI where possible.
- The `researcher` bundled agent expects a local `codex` CLI when it performs Codex-backed research.

## Package resources

This package exposes Pi resources through `package.json`:

```json
{
  "pi": {
    "extensions": ["./extensions/subagent"]
  }
}
```

The `agents/` directory is a custom resource consumed by `extensions/subagent/agents.ts`. It is kept inside the installed package and is not copied into `~/.pi/agent/agents`.

## Development

```bash
npm run pack:dry-run
npm run publish:dry-run
```

Before publishing:

1. Confirm `npm pack --dry-run` contains only intended files.
2. Ensure README install URLs match the final GitHub repository.
3. Run a local smoke test with `pi -e .`.
4. Publish with `npm publish --access public`.

## Security

Pi packages run with your local permissions. This package spawns child Pi processes and can enable tools such as `bash`, `read`, `edit`, and `write` through configured agents. Review bundled and project-local agents before use.

## License

MIT