# Pi Orchestrate

[`@zachwill/pi-orchestrate`](https://www.npmjs.com/package/@zachwill/pi-orchestrate) lets a Pi session delegate work to direct child sessions.

- Each worker gets a focused brief and a separate conversation.
- Workers run independently and return their results to the parent.
- Only the parent can delegate; workers cannot create more workers.

Requires Pi 0.85.0 or newer.

```bash
pi install npm:@zachwill/pi-orchestrate
```

## The model

Each `orchestrate` dispatch creates a fresh worker session with its own transcript. The worker receives a complete brief from the parent but not the parent's conversation.

A worker definition is reusable configuration for the worker's prompt, tools, lifecycle, and optional model settings. The parent remains responsible for the user's complete requested outcome across its own and worker work.

Workers run in the background. `orchestrate` and `interactive_send` return acceptance so the parent can continue useful independent work, including tool calls dispatched alongside the workers. Worker dispatches in the same response form one result group; dispatches in later responses form separate groups.

Results return only to the parent session that started the workers. Results that settle while the parent is busy are queued. After the parent run ends normally, individual results can enter its context as they arrive; a dispatch group resumes the parent after every admitted member settles. The parent can do useful independent work before ending its run, or end promptly when progress needs worker evidence. A rejected, failed, or aborted worker does not cancel its peers; stopping other active workers requires an explicit `worker_abort` request.

Workers have one of two lifecycles:

- A `one-shot` worker returns one result and stops.
- An `interactive` worker returns a result and remains available for follow-up work.

A **worker ID** identifies a worker session. A **run ID** identifies one generation within it. An interactive follow-up creates a new run while preserving the worker ID and prior session context.

Interactive workers remain available across session switches and extension reloads within the same Pi process. Closing one releases its retained session; process shutdown releases any that remain.

Workers keep running when the parent conversation is compacted, and their results return automatically. Restarting Pi does not restore running workers.

## Agent interface

Pi Orchestrate gives the parent five model-facing tools:

| Tool | Purpose |
| --- | --- |
| `orchestrate` | Start a fresh worker with a title and complete brief |
| `interactive_send` | Continue an owned interactive worker that is ready |
| `interactive_close` | Release an owned interactive worker that is ready |
| `worker_abort` | Stop active workers owned by the parent |
| `worker_status` | Inspect the trusted catalog and diagnose the parent's worker state |

The extension supplies the parent with instructions for using these tools.

## Worker definitions

The package includes four fallback definitions in [`examples/workers/`](examples/workers/): `scout` for small factual probes, `investigator` for read-only cross-file research, `worker` for bounded implementation, and `web` for public web research. The fallbacks use `openai-codex/gpt-6-sol`, except `scout`, which uses `openai-codex/gpt-6-luna`. The `web` worker also requires an installed, authenticated Codex CLI.

Definitions are loaded by name in this precedence order:

1. Package fallbacks in `examples/workers/`
2. User definitions in `~/.pi/agent/pi-orchestrate/workers/*.md`
3. Project definitions in `<project>/.pi/pi-orchestrate/workers/*.md`, when Pi trusts the project

A later definition replaces an earlier definition with the same name. Untrusted projects contribute no project definitions. Copy a fallback into a user or project directory to replace it.

A definition is a Markdown file whose basename matches its `name`:

```md
---
name: reviewer
description: Reviews a bounded area and answers follow-up questions.
tools: read, grep, find, ls
lifecycle: interactive
---

Inspect only the assigned scope. Do not modify files. Return concise findings with file paths.
```

The frontmatter is strict:

| Field | Meaning |
| --- | --- |
| `name` | Required definition name; must match the filename |
| `description` | Required catalog description used when choosing a worker |
| `tools` | Required nonempty tool list |
| `lifecycle` | `one-shot` or `interactive`; defaults to `one-shot` |
| `model` | Optional `provider/model` coordinate; omission inherits the parent's model |
| `thinking` | Optional thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` |
| `skills` | Optional exact skill allowlist; `[]` disables skills and omission uses normal discovery |
| `compaction` | Optional Pi compaction settings: `enabled`, `reserveTokens`, and `keepRecentTokens` |

The Markdown body is the worker's nonempty system prompt. `tools` and `skills` accept either YAML arrays or comma-separated strings. Supported Pi tools are `read`, `bash`, `edit`, `write`, `grep`, `find`, and `ls`. Unknown fields and malformed definitions are rejected and appear in catalog diagnostics.

## Trust boundary

Workers run in the parent process and are not security sandboxes. They share its filesystem and environment permissions.

Workers can use global Pi settings, authentication, packages, extensions, skills, and context. Trusted projects may add project-scoped resources. Untrusted projects do not contribute project workers, settings, extensions, skills, or context; global resources remain available.

A definition's `tools` field controls Pi's tool allowlist, not operating-system authority. A worker with `bash` can start external processes, including other agent CLIs. A read-only prompt also does not prevent writes when the worker has a write-capable tool.

Concurrent workers share the same working tree, so overlapping write scopes can collide.