# Subagent

Breaks a window's cost down per subagent and flags right-sizing candidates.

---

Claude Code spawns subagents through the Task tool, and their turns land under the parent session. Folded into one parent total, a heavy research session's subagent spend hides where the tokens actually went. On one real session TokenJam measured 66% of spend across ~147 subagents, invisible above the DB. Subagent breaks a window's cost down per subagent and flags right-sizing candidates.

```bash
tj optimize subagent
```

## Claude Code only

The analyzer groups spans by `(session_id, sub_agent_id)`. That `sub_agent_id` is populated only by the Claude Code backfill path, derived from the on-disk transcript. Spans from other runtimes (Codex, the Python SDK, generic OTLP) carry no subagent id and are excluded.

## What it flags

Each `(session, sub_agent_id)` group with cost at or above $0.05 (a noise floor) is checked against two independent structural criteria:

| Flag | Criteria |
|---|---|
| `over_powered` | Ran on an Opus-tier model, produced fewer than 2,000 output tokens, and made 5 or fewer tool calls. The Downsize heuristic scoped to one subagent. |
| `over_provisioned` | Handed a large context (input plus cache-read tokens at or above 50,000) yet produced fewer than 2,000 output tokens. The prompt it was dispatched with is likely larger than the task needed. |

A single subagent can carry both flags. The analyzer reads aggregate token counts only, so no content capture is required.

## How to read the output

The finding reports, for the window: how many subagents ran and across how many sessions; how much of the total cost ran inside subagents at all before any flagging (`subagent_cost_usd` / `percent_of_cost`); the spend concentrated in flagged candidates (`flagged_cost_usd`); the top subagents by cost; and the top flagged candidates with their flags. Rendering follows the same plan-tier convention as the rest of `tj optimize` — API plans see the dollar share, subscription and local plans see the token share.

## Honesty caveat

This is a descriptive breakdown with candidate flags, not a savings promise. `estimated_recoverable_usd` is deliberately left unset; the analyzer surfaces the spend sitting in flagged subagents rather than assert a recovery. The confidence is `heuristic`, and the flagging caveat mirrors Downsize:

> Candidate-flagging heuristic, not a quality judgment. Review the flagged subagents before changing how you dispatch them or which model they use.

It never claims the flagged subagent's task would have succeeded on a cheaper model or with a smaller prompt. It claims only that the structural shape matches a class worth a closer look.

## See also

- [Downsize](/docs/optimize-downsize) — the same heuristic scoped to whole sessions
- [Cost visibility](/docs/optimize-cost-visibility) — where your quota goes and what you reclaimed