main

Subagent Extension

Delegate tasks to specialized subagents with isolated context windows and deterministic multi-provider model routing.

Features

  • Isolated context: each subagent runs in a separate pi process.
  • Active-provider-first routing: a child first tries the provider selected by the parent session.
  • Provider fallbacks: configured providers are tried after the active provider, in order.
  • Same-tier model fallbacks: a requested model uses only its explicitly configured fallback versions.
  • Provider/model masks: known-unavailable pairs are skipped before Pi spawns a child process.
  • Parallel and chain workflows: run independent tasks concurrently or pass output between sequential agents.

Model resolution

For an agent with model: claude-opus-5, the extension:

  1. tries the parent session provider with claude-opus-5;
  2. tries that provider with the configured Opus fallback versions;
  3. repeats for subagentProviderPreference providers, in order;
  4. skips exact pairs in subagentProviderModelMasks;
  5. selects the first catalog-visible pair with credentials.

The model catalog says that Pi knows a model ID, not that a Vertex AI project is entitled to invoke it. Use a provider/model mask for models that are catalog-visible but not enabled for your Vertex project.

If no pair is usable, the extension does not spawn Pi. It reports whether each candidate was masked, absent from the catalog, or missing credentials. It does not retry a child that has already started and failed.

Configuration

Configure fallbacks and masks in ~/.pi/agent/settings.json:

{
  "subagentProviderPreference": [
    "anthropic-vertex",
    "google",
    "llama-cpp"
  ],
  "subagentModelFallbacks": {
    "claude-opus-5": ["claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6"],
    "claude-sonnet-5": ["claude-sonnet-4-6", "claude-sonnet-4-5"],
    "claude-haiku-4-5": []
  },
  "subagentProviderModelMasks": {
    "anthropic-vertex": ["claude-opus-5", "claude-opus-4-8"]
  }
}

subagentProviderPreference is the fallback order, not an override of the active session provider. Duplicates are removed, preserving order.

subagentModelFallbacks is explicit and model-family scoped. Do not configure an Opus-to-Sonnet or Sonnet-to-Haiku fallback: model tiers must not be silently downgraded.

subagentProviderModelMasks is provider-specific. The example prevents Opus 5 and Opus 4.8 from being sent to Vertex, but still permits them through github-copilot. Update the mask deliberately after Vertex model entitlements change.

Per-session provider fallback override

The --subagent-providers flag replaces subagentProviderPreference for a session but does not replace model fallbacks or masks:

pi --subagent-providers github-copilot,anthropic-vertex,google

View current configuration

/subagent-config

The command shows the active provider, fallback order, model fallback chains, masks, and model-cache status.

Agent definitions

Agents live in ~/.pi/agent/agents/*.md and specify a model ID without its provider:

---
name: researcher-work
description: Broad technical research through Google Gemini.
tools: read, bash, web_search
model: gemini-3.8-flash
provider: google
---

You are a planning specialist.

provider: is optional. When set, it pins the agent to that exact provider, ignoring the parent session provider and subagentProviderPreference. This is appropriate for a workload with a required billing or access path. A provider-pinned agent may use explicit same-family fallbacks on the pinned provider, but never falls back to another provider.

Current conventions are:

Workload Provider Model
Fast reconnaissance resolved normally claude-haiku-4-5
Planning, implementation, standard analysis resolved normally claude-sonnet-5
Deep analysis and code review resolved normally claude-opus-5
High-volume work triage and broad work research google gemini-3.8-flash

Usage

Single agent

Use scout to find all Tekton tasks.

Chain

Use a chain: scout finds auth code, planner creates a plan from {previous}, then worker implements it.

Parallel work

Run separate reviewer-go and reviewer-security subagents in parallel.

The tool supports single (agent + task), parallel (tasks), and sequential (chain) modes. Project-local agents require agentScope: "project" or "both"; only enable them for trusted repositories.

Troubleshooting

A model is available in Pi but fails on Vertex

Add it to subagentProviderModelMasks.anthropic-vertex and configure a known-enabled version in the same model family under subagentModelFallbacks.

An unexpected provider was selected

Check /subagent-config. The parent session provider is always considered first; change the parent model/provider or set a fallback order with --subagent-providers.

No usable subagent model

Read the tool diagnostic. It identifies masked pairs, catalog-absent models, and models without configured credentials. Run pi --list-models to inspect Pi’s current catalog.