Token economics: what a multi-agent Claude Code setup really costs

Chapter 8 of 9. Ten subagents is ten context windows. The bill does not care that nine of them were only reading. Prerequisite: Chapter 6. You should already know that a subagent runs in its own context and returns nothing but a text summary. This chapter prices that.

Everything here is against Claude Code 2.1.209, on 2026-07-14. Model prices and the multipliers below move; the mechanism does not.

Search "claude code token cost multi agent setup" and you get two genres of answer. One is a pricing table with no agents in it. The other is a blog post about ten parallel agents with no prices in it. Underneath both sits one piece of arithmetic with three terms: how many context windows you opened, how many turns each of them ran, and what rate per token each of them was billed at.

What a multi-agent Claude Code setup costs

Start with the mechanic. Anthropic's subagent docs are explicit: "Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions." Spawn ten and ten transcripts accumulate in parallel.

Now put the context-window docs beside that. Context accumulates progressively. Each turn's input phase contains the whole prior conversation, so a long agentic loop re-pays input cost on the entire transcript on every single turn. The bill for a ten-turn agent is the sum of ten growing prefixes.

Multiply the two facts together and the fan-out cost falls out. Of the three terms, head count is the first and the least interesting.

Anthropic publishes exactly one multiplier for this. Quote it; do not round it. From the cost docs: "Agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode, because each teammate maintains its own context window and runs as a separate Claude instance." Agent teams are off by default, gated behind CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

Seven, and only under a stated condition. Whatever multiplier you have heard quoted, treat it as a shape rather than a value, because the value is yours to set. Ten Haiku 4.5 subagents at $1/$5 per million tokens is a completely different bill from ten Opus 4.8 subagents at $5/$25, and both are different again from ten Fable 5 instances at $10/$50. The price list spans a tenfold band across the currently selectable family. Your fan-out multiplier is whichever rate you picked from it, raised by however many windows you opened.

The cost docs publish the only real-world anchor Anthropic gives: around $13 per developer per active day, $150 to $250 per developer per month, and under $30 per active day for 90% of users across enterprise deployments.

The tokens you pay before a single agent runs

Open a session, type nothing, and you are already spending.

CLAUDE.md is loaded in full at session start, regardless of length. The memory docs put a budget on that: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." Imports offer no escape hatch either, since "imported files still load and enter the context window at launch."

The constitution this course documents is 430 lines. Its own version footer, at line 335, reads:

# Version: v1.3 — 2026-04-18 — Trimmed to ~140 lines. Detail moved to
# living doc and agent files. Mandatory workflow at top. Hooks enforce checks.

The file has been lying about its own size by a factor of three since April. Nothing compiles a comment. Every session pays for all 430 lines, including the block on video tooling, on a day when the task is a PHP newsletter backend.

The difference with skills is structural. From the skills docs: "Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it." There are 29 skills in this estate. One of them ships a 90KB Python CLI and a SQLite database of nearly four megabytes beside its SKILL.md. None of that weight enters your context window until the skill fires. Twenty-nine skills is cheap. Twenty-nine more sections of constitution would not be.

Tool definitions are the third silent line item. The pricing docs put the tool-use system prompt at 290 tokens on Opus 4.8 with tool_choice set to auto or none, rising to 410 for any or tool, before you add the tokens for the names, descriptions and schemas themselves. MCP widens that surface. The host merges the tools of every connected server into one registry the model can see, per the MCP architecture docs, and Claude Code defers those definitions by default, so only names enter context until a tool is used.

Prompt caching makes the fixed prefix survivable. A cache read costs 0.1x the base input price; a 5-minute cache write costs 1.25x. The rule that falls out of those two numbers is mechanical: keep the prefix byte-identical across requests, because any change invalidates the cache from that point onwards. Edit CLAUDE.md three times in a day and you buy the whole prefix at full price three times in a day.

The cost dial is three fields in the agent's frontmatter

There are 31 subagent files in ~/.claude/agents/. Five run Haiku, twenty-one run Sonnet, five run Opus. The rule that produced that distribution sits in the constitution:

# AGENTS:   Each subagent declares its `model:` in frontmatter. Cheapest
#           model that can do the job: Haiku for deterministic mechanical
#           work, Sonnet for synthesis + code, Opus for genuine reasoning.
#           No global override — frontmatter is source of truth. Reviewers
#           should question Opus selections that don't justify the cost.

"No global override" is a cost rule wearing the clothes of a style rule. The subagent docs say model defaults to inherit, so an omitted line runs the child at whatever the parent is running. In an estate pinned to Fable 5, a missing model: line buys you a Fable-priced subagent doing a Haiku-priced job.

Here are the two extremes of the estate, verbatim. The escalation agent:

---
name: stuck
description: Use this agent whenever any other agent hits a problem it cannot resolve independently — an ambiguous requirement, a conflict between two valid approaches, a decision with significant cost implications, a security concern, or anything that requires human judgment. Use immediately rather than guessing.
tools: Read
model: haiku
maxTurns: 3
---

And the active security prober:

---
name: pentest-agent
description: Use this agent to actively probe a running application for security vulnerabilities before any public launch or major release. Requires a LOCAL or STAGING URL — never a production URL without typed confirmation. Use after security-auditor (static) and verify-app (E2E) have passed. Run proactively as the final gate in the pre-launch checklist.
tools: Bash, Read, WebFetch, Grep, Glob
model: opus
permissionMode: plan
maxTurns: 50
---

Three fields set the price ceiling. model: sets the rate. The fuse is maxTurns:, and across this estate the declared values are 3, 25, 30, 30, 50. An audit-only agent with no Write in its tools: list cannot wander into an edit loop at all.

The cheapest thing in the whole system is the escalation path. stuck is Haiku, three turns, read-only, and structurally incapable of doing the work it was summoned to escalate. pentest-agent inverts every one of those: the dearest model, a 50-turn budget, and plan mode wrapped around it. Both files dial danger and cost in the same edit. Only five of the 31 files declare a maxTurns at all. The other twenty-six run to whatever the client allows.

The ANTHROPIC_API_KEY billing trap

This is the one that costs money you did not intend to spend. The bug is in your shell profile.

Claude Code will authenticate from an environment credential. The settings docs describe forceLoginMethod and, in doing so, name the three routes in. When it is set in managed settings, "sessions authenticated by ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or apiKeyHelper are blocked at startup, since an environment credential cannot satisfy the required login method."

Now put that beside the billing rule from the cost docs: "If your organization mixes sign-in methods, each developer is metered according to the one they authenticated with." Subscription sign-in draws from a seat allowance on a rolling five-hour window. Console sign-in bills per token to your organisation.

So the failure is mundane. You export ANTHROPIC_API_KEY in ~/.zshrc to run some SDK script. Weeks later you run claude from that same shell. The session authenticates against the key, the subscription you are paying for sits untouched, and a per-token bill accrues in a Console workspace that Claude Code created for you on first authentication. Nothing errors. Nothing warns.

1. Grep your shell for the credential

   grep -rn 'ANTHROPIC_API_KEY\|ANTHROPIC_AUTH_TOKEN' ~/.zshrc ~/.bashrc ~/.profile. If it is exported unconditionally, every claude launched from that shell is an API-billed session. Scope it to the one script that needs it instead.

2. Check the env block and apiKeyHelper in settings

   env and apiKeyHelper in ~/.claude/settings.json both reach every session and every subprocess. A credential belongs in neither unless API billing is what you want.

3. Read the /usage note carefully

   The docs are blunt about who the session cost figure is for: "The Session block in /usage shows API token usage and is intended for API users. Claude Max and Pro subscribers have usage included in their subscription, so the session cost figure isn't relevant for billing purposes." If you are a subscriber and that dollar figure feels load-bearing, ask which credential you authenticated with.

Organisations get a hard fix: forceLoginMethod in managed settings blocks env-credential sessions at startup. Solo, you get the grep and the discipline to re-run it.

The hook that spends tokens, and the caps that hold it

Not every token you burn is spent by you. One Stop hook in this estate shells out to a second Claude to review the session that just ended. Its constants are its budget:

DAILY_CAP = 10
TRANSCRIPT_BYTE_FLOOR = 500
TRANSCRIPT_CHAR_CAP = 50_000
PROPOSAL_CHAR_CAP = 500
PYTHON = "/opt/homebrew/bin/python3.13"
CLAUDE_BIN = "claude"
MODEL = "haiku"

The call itself is one line:

            [CLAUDE_BIN, "-p", "--model", MODEL, "--max-turns", "5"],

Read those constants as a price list: the cheapest model, five turns, only the last 50,000 characters of transcript, a 500-character output cap, and no more than ten runs per repository per day. The floor is the more interesting number. A transcript under 500 bytes never triggers a review at all, so the hook declines to spend anything on a session where nothing happened.

The guard that matters most is BBBRAIN_STOP_REVIEW_RECURSION=1, set in the child's environment before the review spawns. A token-spending hook that fires on session end can fire itself. Without that flag, the Haiku session's own Stop event spawns another Haiku session, and you have built a fork bomb with a credit card attached.

Why a speed-bump beat a quota reader

The token-burn incident behind this chapter is written up in Archon was burning quota. Three worktrees showed "running" simultaneously. Two had been dispatched without a deliberate decision, and the quota is a rolling five-hour window, so three concurrent runs burn the same window three ways.

The instinct was instrumentation. A usage monitor already existed. It scanned session JSONL against the observed cap and auto-paused at 90% headroom. It works. It also cannot see a session that types archon workflow run directly. That path never reaches the dispatcher it guards.

What shipped instead was a PreToolUse hook on the Bash matcher that pattern-matches the command shape and blocks. No token count, no quota read. In the article's words: "The check I actually needed was not 'how much quota is left?' It was 'am I already running something, and did I mean to fire another one?'" The saving was never measurable in any precise way. What was measurable: no concurrent triple-run since.

There is a sting in the tail. Run grep -c preflight ~/.claude/settings.json today and you get 0. The hook file is still on disk with 21 tests beside it, unregistered to any event, while the constitution goes on describing it as live global enforcement. An unwired hook costs nothing in tokens and costs you the entire guarantee. Nothing in this estate tests for its own wiring.

The transferable rule

Cost in an agentic system is a ceiling you declare, in the file that defines the thing doing the spending.

Every mechanism that can consume tokens should carry its own limit at its own definition site. An agent's model, turn cap and tool allowlist live in five lines of frontmatter. A hook's model, input cap, output cap and daily cap are constants at the top of the script. Omitting the model field has to be forbidden out loud, because inheritance defaults to whatever the parent happens to be running, and in a badly-pinned estate that is the most expensive model in the room.

A dashboard reports what you already spent. It needs accurate state. It lags a turn behind the loop it watches. Runtime state is irrelevant to a ceiling in the frontmatter, so the ceiling holds while you are asleep.

So audit the definition sites, not the receipts. Run grep -L '^model:' ~/.claude/agents/*.md. Every file that command prints is billed at your parent model, whatever that happens to be pinned to this month. All 31 files in this estate print nothing, and that is the only reason the inheritance default is a hypothetical here instead of an invoice.