using-pi-subagents

Using Pi Subagents

Use this skill when deciding whether or how to delegate with the subagent_* tools.

Prefer direct work

Only use a subagent when the work can be split into independent tasks, or when context isolation provides a concrete benefit.

Otherwise, do the work directly.

Keep planning, critical-path work, integration, deterministic checks, authorization decisions, and the final answer in the main agent.

Do the work directly when it is simple, latency-sensitive, tightly coupled to the current context, likely to need user clarification, or faster than preparing and verifying a delegation.

Nested subagents are unsupported.

Spawn one least-privilege job

Use subagent_spawn for one subagent job.

The task defines the child's specialization, objective, constraints, and expected result.

The selected tools define what the child can do.

Select only from read, bash, powershell, edit, write, grep, find, and ls.

Omit tools for the read-only default of read, grep, find, and ls.

Pass an explicit empty list when the child needs no work tools.

Add only the smallest sufficient tool set for the task.

Treat bash and powershell as unrestricted command execution that can also modify the workspace.

Treat edit and write as explicit workspace mutation capabilities.

The runtime always adds subagent_send and child subagent_wait for communication.

The child inherits the main agent's effective provider and model at spawn time.

Spawn rejects model providers registered only by a parent extension and process-local runtime API keys.

Use a child-visible provider with Pi's stored credentials or inherited environment credentials.

Omit thinkingLevel to follow the main agent's effective thinking level.

Set thinkingLevel explicitly only when the task justifies a different level.

The job returns a job ID immediately and publishes one terminal completion.

Prefer delegation when the main agent can perform concrete non-overlapping work before the result is required.