docs: reframe sub-agents as per-agent-optimized delegation

Author: ofriw

website/docs/context-engineering.mdx

@@ -201,11 +201,13 @@ The practical framing: **AGENTS.md** holds what the agent should always know —
 
 ## Sub-Agents
 
-Sub-agents run in completely separate context windows. A sub-agent might consume 50K–150K tokens researching a codebase, but return only a 2K–5K synthesis to the orchestrator.
+Sub-agents are **delegated agents** — independent instances that run in separate context windows under the direction of an orchestrator. Each sub-agent operates on its own task slice, and the orchestrator consumes only the returned synthesis rather than inheriting the full working trace.
 
-**Context effect:** the prompt forks work into a separate window; only the returned synthesis enters the parent near the active turn. The parent pays for that synthesis, not the raw search trail, file reads, and partial interpretations. This keeps the orchestrator clean while making the return boundary intentionally lossy.
+**Context effect:** the prompt forks work into separate windows; each sub-agent carries its own context lifecycle, and only its synthesis returns to the orchestrator. The parent pays for that synthesis, not the raw search trail, file reads, and partial interpretations. This isolation keeps the orchestrator clean while making the return boundary intentionally lossy.
 
-Think of a sub-agent like a function call for agents. The prompt is the parameter: "Find all JWT authentication code and explain the current implementation." The synthesis is the return value: "JWT implementation found at src/auth/jwt.ts using Passport.js..." You pay for work in both contexts, but the parent receives the compact result instead of inheriting the whole research journey.
+Sub-agents are the agentic analogue of a function call: the dispatch prompt is the parameter ("Find all JWT authentication code and explain the current implementation") and the synthesis is the return value ("JWT implementation found at src/auth/jwt.ts using Passport.js..."). You pay to process tokens in all participating contexts, but the orchestrator receives compact results instead of inheriting every delegate's full journey.
+
+What makes sub-agents a first-class orchestration primitive — beyond context isolation — is **per-agent optimization**. With the right harness, each delegate can run on the LLM best suited to its sub-task: [pi](https://pi.dev) + [pi-agenticoding](https://github.com/agenticoding/pi-agenticoding) lets you route each sub-agent to the model that matches its cost-accuracy profile. Similarly, Claude Code, Codex, and OpenCode let you customize the system prompt per sub-agent, so each delegate carries only the instructions it needs for its slice of work. Regardless of the mechanism, the payoff is the same: **orchestrating a single task via multiple specialized agents** instead of overloading one context.
 
 <DiagramFrame
   kicker="Context management"
@@ -218,17 +220,25 @@ Think of a sub-agent like a function call for agents. The prompt is the paramete
   <SubAgentFanoutDiagram />
 </DiagramFrame>
 
-The tradeoffs:
+### Benefits and Costs
+
+**Benefits:**
+- **Proper delegation** — the orchestrator assigns each sub-task to an independent agent rather than doing all work in one overloaded context
+- **LLM optimization per task** — pi + pi-agenticoding routes each delegate to the model best suited to its slice (e.g. high-throughput for research, precision-tuned for review)
+- **System prompt customization per agent** — Claude Code, Codex, and OpenCode let you tailor the system prompt to each delegate's role
+- **Parallel execution** — independent sub-tasks run concurrently instead of serially
+- **Cleaner orchestrator** — only syntheses cross back, keeping the parent window focused on coordination
 
-- **No shared state** — each sub-agent starts fresh, so you pay the context-file loading cost again
-- **Synthesis can lose nuance** — the 2K summary omits details the parent might have needed
-- **Cost multiplied** — every sub-agent is a separate API call with its own token consumption
+**Costs:**
+- **No shared state** — each sub-agent starts fresh, so context-file loading cost is paid again per delegate
+- **Synthesis can lose nuance** — the compact return omits details the orchestrator might have needed
+- **Token cost multiplied** — every sub-agent is a separate API call with its own consumption
 - **No nesting** — sub-agents cannot spawn sub-agents; the orchestrator is always the root
-- **10 parallel cap** — Claude Code limits concurrent sub-agents to 10
+- **Concurrency cap** — Claude Code limits concurrent sub-agents to 10
 
-The trade-off is token cost, not accuracy. You pay to process tokens in both contexts, but the orchestrator stays clean. That often improves first-iteration accuracy enough to save tokens compared with multiple correction cycles from a polluted parent context.
+These are token-cost tradeoffs in exchange for delegation and specialization — the right tradeoff when per-agent optimization improves outcome quality faster than the added token spend costs.
 
-Sub-agents are ideal for heavy research, multi-file analysis, and exploratory tasks where the journey matters less than the destination. They can also generate independent plans or implementations when you want to compare options before applying one result.
+Sub-agents are ideal for delegating independent research, multi-file analysis, and exploratory tasks to the agent best suited for each slice, and for generating independent plans or implementations across specialized models when you want to compare options before applying one result.
 
 ## Context Compaction
 
@@ -309,8 +319,8 @@ Eager loading is simple but charges the full catalog to every request. Deferred
 **Skills: procedure content arrives only when activated**
 A lightweight catalog supports discovery; the selected workflow enters near the active turn. Manual activation favors reliability, while model activation favors convenience.
 
-**Sub-agents: raw exploration stays outside the parent**
-A sub-agent can consume 150K tokens internally while returning only a small synthesis. Use separate windows for research trails and multi-file exploration when the parent needs conclusions rather than the full journey.
+**Sub-Agents: delegation via isolated windows with per-agent optimization**
+A sub-agent can consume 150K tokens internally while returning only a small synthesis. Use delegation to assign sub-tasks to agents optimized per slice — the right LLM and system prompt for each work item — while the orchestrator stays focused on coordination.
 
 **Compaction: working room is recovered by losing detail**
 A summary replaces accumulated history, so facts needed later may disappear. External checkpoint files provide exact recall; a fresh context restores inference quality.

website/docs/reliability-levers.md

@@ -114,7 +114,7 @@ unnecessary dependent transformations and handoffs.
 <OrchestrationLeverDiagram />
 </DiagramFrame>
 
-Orchestration also removes dependencies. Run independent research in parallel sub-agents rather than one long serial thread. Separate implementation from review when they need different judgment. Stop before code turns a human decision into structure. [Sub-agents](./context-engineering.mdx#sub-agents) are useful because they isolate noisy work and return compact results.
+Orchestration also removes dependencies. Run independent research in parallel sub-agents rather than one long serial thread. Separate implementation from review when they need different judgment. Stop before code turns a human decision into structure. [Sub-agents](./context-engineering.mdx#sub-agents) change orchestration by letting a single task be decomposed across multiple specialized agents — each running on the LLM and system prompt optimized for its slice — rather than overloading one context, isolating noisy work and reducing dependency length in the parent chain.
 
 This lever does not fix missing facts or an unclear success condition. Better shape only helps when each unit is grounded and judgeable.