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 package works as a standalone Pi extension. It reuses 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. This 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:@piewf/subagents

No separate pi-extensible-workflows installation is required for the five standalone tools. Install the core workflow extension separately only when you also want workflow orchestration and the optional singleAgent catalog function inside workflow scripts.

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": ... }

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, tools, role, worktree, outputSchema, retries, and timeoutMs. A named role or role override cannot be combined with top-level model, thinking, or tools; put those overrides inside the role object.

subagents_run({
  prompt: "Review the release.",
  role: {
    name: "reviewer",
    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.

Optional workflow composition

The package also registers an optional singleAgent workflow-catalog function. It calls one workflow agent with the same options and returns the bare value directly.

return await singleAgent({
  prompt: "Review the changed files.",
  role: "reviewer",
});

singleAgent is workflow composition, not a standalone lifecycle. It has no mode, durable standalone ID, follow-up, or cross-session restoration point. Use subagents_run when lifecycle controls matter.