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 generic preparation hooks, model aliases, settings, resource ceilings, 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. To keep workflows but drop the subagent tools, for example when another extension already provides subagents, exclude dist/subagents/index.js in Pi's settings as shown in Disable bundled features.

Choose Subagents or workflows

The five tools

Interactive inspection

In Pi's TUI, /subagents opens the agents workspace that /agents opens, scoped to the durable standalone runs of the current session; it needs only this extension, not the workflow extension. A full-screen view over Pi shows a "Subagents" header with the count of each state and the total cost, and one row per run in the picker's order: running runs first, then failed, stopped, and completed ones, the latest settled first. A run is named by its label, a repeated label carries the short ID, and a run without a label shows its short ID. The selected run's full transcript fills the rest, drawn with Pi's own message and tool components following Pi's display settings and drawing a skill invocation as Pi's chat does, under a title with its position, name, state, model, tokens, and cost. d shows the run's details instead and d again its transcript: the run ID and the same activity, stall warning, state, model, 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. The view refreshes every second while a run is running or the shown transcript is still being read, and every 5 seconds otherwise. Without a run in the session, /subagents says "No durable subagent runs in this session." and opens nothing, and the workspace closes with the same notice when an action leaves none. One workspace is open at a time: a second /subagents or /agents meanwhile says "The agents workspace is already opening or open." Without a UI, /subagents reports the run summary; in a non-TUI mode with a UI it opens a picker with the run summary and the bulk deletions. Running background runs show live only in the workflow widget below the editor, as a "Subagents" group (quiet while a workspace is open), one row per run with its model, tokens, cost, elapsed time, and quiet or stalled warning; the widget's cursor and enter open /agents on the group or a subagent. Each background run leaves a receipt in the transcript when it settles. This extension draws no live rows of its own: with the workflow extension not loaded or its backgroundWidget: false setting, only those receipts show. Inspection does not launch a new LLM call; lifecycle actions may steer, stop, retry, or delete a run. The timeline in the Subagents group's details shows each run's speed (output tok/s, mean TTFT, tokens in generation time), counted per attempt from assistant messages that finished normally and summed across attempts; TTFT is the time from Pi's turn_start event, which precedes every request, to the first streamed content (the first non-empty text, thinking or tool-call delta). A selected subagent's title shows its persisted average as N tok/s avg; there is no live meter. See the agents workspace.

The sidebar takes 38% of the width and starts hidden below 80 columns (above the transcript on a portrait terminal); tab moves the focus, ↑ and ↓ (also k and j in the sidebar) select a run or scroll the transcript by a line, [ and ] select the previous or next run, a click selects one, ←, →, and space fold the group, s hides or shows the sidebar, ctrl+o expands tool output, page keys, search, and the mouse wheel scroll the transcript, and esc or ctrl+c leaves. a opens the selected node's action menu, and so does enter on the Subagents header. A run offers its registered standalone agent actions, Copy branch and Copy worktree path when it has a worktree, editor controls for the prompt, the live system prompt, and the result, Steer and Stop while running, Retry and, when its request is readable, Edit and retry for failed or stopped runs, Delete once settled, Copy run path, and Copy agent ID; the Subagents header offers Delete all completed and Delete all failed when such runs exist. In the menu ↑/↓ or k/j move, enter runs the selected action, and esc, ←, or h close it. The copies and the editors run in place, with their notice in the status row until the next key. Every other action steps aside: the workspace closes, the action runs with Pi's own dialogs (Stop and every deletion ask for confirmation, Steer opens Pi's editor), and the workspace opens again on the same run, on the new run after Retry, or on the run now at its row after Delete, with the action's notices in the status row. A registered standalone agent action (such as Herdr's) runs detached: the workspace opens again at once, its working message shows in the status row until it settles, a later failure is reported as a notice in that row, and its dialogs are refused with a notice. A run whose worktree still awaits cleanup cannot be deleted. A run's session file is read only when its inspected record names the current Pi session, has a safe ID, and, when it records a cwd, names this project; any other run shows "transcript unavailable" and its file is never opened. New records show on the next refresh, and the message a run active in this Pi process is generating streams in live.

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. In /agents and the /subagents picker, Edit and retry beside Retry, offered when the run's request is readable, opens the prompt in Pi's editor, then asks for a model and a retries count (an empty answer keeps the current value), and retries with them; cancelling any prompt retries nothing. An edited model is prepared like a model of subagents_run, so agent preparation hooks apply to it as they do to a fresh run. A model, or an alias, that does not resolve is rejected before the run directory exists. A model that is not available is rejected there too unless agent preparation hooks are registered, because a hook may change the model: then the run fails if the prepared model is unavailable, as a fresh subagents_run does. A dynamic alias that resolves to an unavailable model is always rejected there, hooks or not. A later Retry of the new run repeats the edited request and model.

Agent options, roles, and settings

subagents_run accepts label, model, tools, skills, extensions, contextFiles, worktree, outputSchema, retries, and timeoutMs plus unknown JSON options for plugins. Thinking uses the model suffix. Role options are interpreted only by the optional roles extension. Resource selectors cannot exceed root or parent capability ceilings.

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

Standalone agents use workflow settings and the same generic preparation contract as workflow agents. Core does not read role files or shared role settings. Enable the optional roles extension in the parent Pi session when role behavior is required.

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. A new worktree runs the worktreeSetup commands from the current workflow settings before the agent starts.

Run records are stored below the agent directory's private subagents/<id>/ directory. Normalized requests, frozen concrete prepared configurations 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.