Run focused agents with durable controls

Overview

Subagents are for single-shot orchestration, not necessarily one model turn. One subagents_run call creates one agent session from one task; that agent can reason across turns, use tools, and accept steering while it runs.

The built-in tools reuse the same role files, model aliases, settings, resource policy, worktree implementation, and agent-option validation as core workflows, without requiring you to write a workflow script.

Installation and trust

Use Node.js 22.19 or newer. The core package is trusted Pi host code with the same filesystem and process access as Pi. Install it only from a source you trust.

pi install npm:pi-extensible-workflows

This single installation provides workflow orchestration, the reviewLoop starter, and the five standalone subagent tools.

Choose Subagents or workflows

The five tools

Interactive inspection

In Pi's TUI, /subagents opens a picker of durable standalone runs for the current session. Select a run to inspect the same activity, stall warning, state, model, role, tools, attempts, duration, token accounting, cost, and error fields used by /workflow; prompt, request failure, and result details remain bounded, and requests without a role remain role=none. The detail view also exposes registered standalone agent actions, Steer and Stop while running, Retry for failed or stopped runs, and copy/editor controls where applicable. Inspection does not launch a new LLM call; lifecycle actions may steer, stop, or retry a run.

Background example

subagents_run({
  prompt: "Review the current changes.",
  label: "review",
})
// { "id": "...", "state": "running" }

Foreground example

subagents_run({
  prompt: "Summarize README.md.",
  mode: "foreground",
})
// { "id": "...", "state": "completed", "value": ... }

Trajectory browser

Open /workflow trajectory to inspect standalone subagents in Trajectory's local browser UI. Each publisher session shows a sibling SUBAGENTS section beside its workflow runs, scoped to the current Pi session and sorted attention-first: running, failed, stopped, then completed.

The publisher home view includes a subagent Gantt with one lane per subagent and matching tool-timing bars. Select a subagent to open its own view with the transcript event timeline, searchable events, model, tools, accounting, result or failure, and worktree path and branch when available.

While a subagent is running, its view exposes Stop and Steer. Failed or stopped subagents expose Retry; retry starts a fresh subagent with a new ID and follows that ID in the UI. Pause, resume, and checkpoint controls are not shown for subagents.

Execution and lifecycle

mode defaults to background. A background launch returns { id, state: "running" } immediately and can deliver one completion or failure follow-up. A foreground launch waits for a terminal envelope and does not generate the background follow-up.

Public run states are running, completed, failed, and stopped. Foreground cancellation persists a failed record with code CANCELLED. Unknown IDs fail with RUN_NOT_FOUND.

Independent calls can execute concurrently up to the effective workflow concurrency setting, an integer from 1 through 16 with default 8. There is no launch queue: when the limit is full, subagents_run and subagents_retry fail with AGENT_FAILED, so retry after an active run settles.

A new manager does not reconnect a native session that was still running. It reconciles the persisted record to an interruption failure. Use subagents_retry for a fresh run; retry does not restore the old conversation.

Agent options, roles, and settings

subagents_run accepts the same execution options as workflow agent(...): label, model, thinking, skills, extensions, tools, contextFiles, role, worktree, outputSchema, retries, and timeoutMs. role is a name string. Role files provide defaults; top-level model, thinking, tools, skills, extensions, and contextFiles are per-call overrides. Use ["!*", "read", "grep"] to restrict a selector and ["*"] to re-enable all tools after a role restriction.

subagents_run({
  prompt: "Review the release.",
  role: "reviewer",
  model: "cheap-model",
  thinking: "high",
  tools: ["!*", "read", "grep"]
})

Global roles and settings live below <agentDir>/pi-extensible-workflows/, normally ~/.pi/agent/pi-extensible-workflows/. Trusted project roles and settings live below <cwd>/.pi/pi-extensible-workflows/. Set PI_CODING_AGENT_DIR to move the agent directory. See the roles guide and settings reference.

Worktrees, storage, and inspection

Set worktree to create an isolated named Git worktree for the run. The run executes there, inspection exposes its path and branch while materialized, and cleanup runs when the agent settles, stops, or is reconciled. Failed cleanup retains its metadata for a later retry.

Run records are stored below the agent directory's private subagents/<id>/ directory. Normalized requests, launch mode, status, results, and failures remain inspectable after manager restart. Treat this storage as private because requests and results can contain project data.