@centerforagenticai/pi-delegate

Kind: extension · Status: stable · Pi: latest · Node: >=22.19

What it does

pi-delegate runs specialist agents from a Pi session and returns one result for each run. Work can run independently, through a private supervisor, as an ordered chain, or in a durable driver session.

• Dispatch parallel or ordered workers without filling the main conversation with their transcripts.
• Add a private supervisor that can review and redirect a worker before returning one answer.
• Keep the foreground responsive with background completion wakes, inspection, cancellation, recovery, and escalation.
• Isolate worker changes in Git worktrees and confine writes to approved roots.
• Keep read-only workers useful for inspection: literal /dev/null redirection, file-descriptor duplication, and safe read-only Git forms remain available; Git output, executable-helper, and global config-injection options are refused.
• Use the same production handlers from a Node client, Fabric, or another Pi extension.

Read Using pi-delegate for the complete behavior and examples.

How it fits

The Pi session calls the extension's tools or slash commands. pi-delegate starts direct workers, private supervisor-and-worker pairs, or a durable driver hosted by pi-daemon. It stores bounded run state, then returns the result directly or wakes the owning session when background work finishes.

Install and enable

Installation

Install the public npm package with Pi:

pi install npm:@centerforagenticai/pi-delegate

Restart Pi or run /reload. The package supports the Pi versions shown above and needs Node >=22.19.

The bundled delegate, worker, and publisher agents are available immediately. Install compatible workflow-agent packages separately when you need roles such as scout, planner, reviewer, implementer, or integrator.

Surface

| Kind | Name | Purpose | | --- | --- | --- | | Tool | delegate | Dispatch runs or manage agent and chain definitions. | | Tool | delegate_control | Inspect, collect, steer, follow up, answer, cancel, or recover accepted runs. It appears only when there is work to control. | | Tool | delegate_escalation | List, resolve, or pass up durable worker escalations when escalation is enabled. | | Commands | /delegate, /delegate-help | Dispatch work, list resources, inspect health, or show help. | | Commands | /delegate-cancel, /delegate-inspector | Cancel live work or open the transcript inspector. | | Command | /delegate-only | Enable, disable, or inspect the constrained foreground mode. | | Skills | pi-delegate, authoring-delegate-agents, delegate-only, merge-coordinate, orchestrate-work | Use the tool surface, author agents, operate in delegate-only mode, integrate lanes, and coordinate multi-lane work. | | Agents | delegate, worker, publisher | Built-in dispatch, execution, and gate-and-push roles. | | Exports | package root, ./events, ./fabric, ./escalations, ./skill-resource | Programmatic dispatch, event names, Fabric, escalation, and skill-resource APIs. | | Events | delegate:* | Versioned in-process run lifecycle and control notifications. |

A minimal tool call is delegate({ runs: [{ agent: "reviewer", task: "Review the change." }] }). Read the tool and API reference, runtime API, and event-bus reference for every field and limit.

Configuration

The optional file ~/.pi/agent/config/pi-delegate/config.json controls global defaults. A sibling config.local.json overlays it for machine-local values.

| Area | Built-in behavior | | --- | --- | | Worktrees and duration | No setup hook; no global duration ceiling or floor. | | Tool and skill baseline | No extra global grants. Agent and invocation policy still applies. | | Escalation | Off; the native escalation UI is enabled when escalation is turned on. | | Inspector | Full layout, thinking preview, tool chips, persistent completion view. | | Completion | Background dispatch and early failure notices are enabled. | | Activity ticker | Enabled with deterministic counts; no model call unless a model is configured. | | Prompt-template bridge | Auto-detect whether pi-delegate should handle requests. |

Read Configuration for every key, environment variable, precedence rule, default, limit, and failure mode. Saved agent and chain definitions can contain plaintext environment values; keep secrets in the process environment or a secret manager.

When it runs

The extension registers its main surface when Pi loads it. Ordinary dispatch runs in the background unless the caller sets await: true; completion wakes the owning foreground session. Supervised runs keep a private supervisor loop in process. Driver runs return after pi-daemon accepts the prompt and can outlive the caller.

The extension hooks resources_discover, before_agent_start, session_start, session_shutdown, turn_start, and turn_end. These hooks load the bundled skill, restore bounded state, deliver pending results, refresh the status widget and activity ticker, and reconcile interrupted work. The extension stays idle when no run, pending delivery, or enabled foreground mode needs it. Read Using pi-delegate for the full lifecycle.

Develop

The source is maintained in a private repository and published here as release snapshots; contributions are welcome as pull requests on GitHub, which maintainers carry into the source repository.

npm install
node scripts/public-release-smoke.mjs

Documentation

User and API reference

• Using pi-delegate
• Agent definitions
• Configuration
• Security
• Integrations and migration
• Delegate tool and API
• Programmatic runtime API
• CLI delegation
• Package-shipped agents
• Escalation
• Activity ticker
• Heartbeat
• Fabric mode
• Write confinement
• Run history
• Active delegated-work contract
• Early failure recovery
• Prompt-template bridge
• Prompt-template-model support
• Generated diagram source and SVG
• Architecture and model index
• Architecture context

• Dispatch evidence verification
• Cross-session recovery
• Delegate-only measurement
• Escalation downstream integration
• Escalation shakeout results
• Implementer agent
• Timeout contract
• Phase 1 injection notes
• Phase 3 investigation
• Release process
• Retry-lineage merge design
• Reviewed node execution
• Subagent parity plan
• Verification 566 parity
• Verification 567 lifecycle

License

MIT. See LICENSE.