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 the /workflow dashboard layout for the durable standalone runs of the current session: the run list sits beside the selected run's details at 80 columns or wider, and narrower terminals drill down from the list to the details. The details show the run ID and the same activity, stall warning, state, model, role, tools, attempts, duration, cumulative token accounting, cost, and error fields as a /workflow agent; a running run shows its live activity, which subagents_inspect leaves out. Requests without a role show Role: (none). While a run is active the view refreshes the active runs and the selection every second; runs launched while it is open appear after an action or when it reopens. a or enter opens registered standalone agent actions, editor controls for the prompt, the live system prompt, and the result, Steer and Stop while running, Retry for failed or stopped runs, and the /workflow run actions that apply: Delete, Delete all completed, Delete all failed, Copy run path, and Copy agent ID. Stop and every deletion ask for confirmation, and a run whose worktree still awaits cleanup cannot be deleted. Outside the TUI, /subagents opens a picker with the same run summary and bulk deletions as the /workflow picker. Background runs appear below the editor in the workflow widget's frame, one row per run with its model, tokens, cost, elapsed time, and quiet or stalled warning, and each leaves a receipt in the transcript when it settles. Inspection does not launch a new LLM call; lifecycle actions may steer, stop, retry, or delete 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. Use Agent details to inspect Prompt, Tools, Skills, Extensions, Environment, and Output without selecting a system-prompt event.

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, frozen external settings and role definitions for retries, launch mode, status, results, and failures remain inspectable after manager restart. Historic records without frozen external configuration are not retried with current settings. Treat this storage as private because requests and results can contain project data.