How pi-subagents works,
and an early routing proposal

01What the thing actually is

A Pi extension — not a subprocess supervisor, not an external service. A child agent is a real Pi session created inside the same Node process: its own model runtime, its own session manager, its own resource loader, its own agent loop. The parent's process hosts all of it.

02The layer cake

The codebase is cut by role, not by feature. Every arrow points downward: a layer may depend on the ones beneath it, never the other way round. That is the whole architectural discipline of the package, and it is what makes the tier feature easy to bolt on — it lands in a layer that nothing else has to know about.

03The life of one spawn

From the moment the model calls subagent to the moment the parent gets a result. The two shaded steps are where the child's model is decided — remember them, because that is where tier routing hooks in.

04Where the model is decided

Two independent doors, one shared vocabulary. The tool door runs when the model calls the subagent tool; the service door runs when another extension spawns an agent programmatically. Both end at the same question: which model does this child run on?

Fuzzy model matching, for reference

resolveModel(input, registry) is what turns "haiku" into a real model. It tries an exact provider/modelId match first, then scores every available model:

exact id or provider/id            → 100
id contains the query               →  60 + (query.length / id.length) * 30
name contains the query             →  40 + (query.length / name.length) * 20
every token appears somewhere       →  20   ← acceptance threshold

Only available models — those with credentials configured — are candidates. The error message when nothing matches lists the available models, because an unlisted model is the usual cause.

05The tier ladder

Pi has no notion of model tiers. Model carries a cost, a context window and a reasoning flag — nothing that says "this model is one notch above that one". So this package supplies the vocabulary itself, as data.

What a rung pattern may be

Batch endpoints (:batch) are never tier targets — a batch request is answered on a 24-hour horizon, which no subagent run can wait for.

06Configuration

// ~/.pi/agent/tiered-subagents.json   or   <project>/.pi/tiered-subagents.json
{
  "enabled": true,          // absent means "on"
  "tiersDown": 1,           // how many rungs to move down
  "groups": [               // absent means the shipped ladder
    {
      "name": "OpenAI GPT-6 family",
      "providers": ["openai", "openai-codex"],
      "match": "^gpt-6(\\.\\d+)?-",
      "tiers": [
        ["gpt-6-astra"],
        ["gpt-6*-sol"],
        ["gpt-6-luna"]
      ]
    }
  ]
}

Agent definitions

Three are embedded (general-purpose, Explore, Plan). User agents are Markdown with YAML frontmatter, discovered at <cwd>/.pi/agents/*.md and ~/.pi/agent/agents/*.md — project beats global, and a user file may shadow a default name.

---
display_name: Fast Reviewer
description: Reviews one file for correctness
tools: read, grep          # a YAML list works too: [read, grep]
model: openai/gpt-6-luna   # optional — the tier policy steps an inherited model down anyway
thinking: low
max_turns: 12
locked: model              # or: locked: [tools, model]
prompt_mode: replace
inherit_context: false
run_in_background: true
enabled: true
---
You are reviewing a single file…

07What this fork changes

The upstream tree is copied 1:1 — same directory layout, same #src/* import map, same file names — as initial source material. The diagram below records an early proposed delta, not six completed modifications. The experimental tier directory also has a barrel file; consult the specification rather than these historical counts for implementation scope.

The diagram and the table below record an early proposal, not what the tree contains today. The experimental src/tier/** patch never compiled, and its design — glob ladders with a price-ranked fallback — is superseded by the specification, which replaces price ranking and user-supplied matchers with family strategies over declared profile data. It was therefore not carried into the import; the runtime is back to upstream's model resolution until the specified design is implemented. See ADR 0002.

08Things worth knowing before you change it

The decisions upstream records as ADRs

The full set is copied into docs/decisions/ and the phase-by-phase history into docs/architecture/history/. These are the ones that constrain where the tier feature can live: