Claude Code Subagents Burning Tokens? Bound the Fan-Out

If Claude Code subagents are draining usage faster than expected, first run /usage, then open /agents and /tasks to see what is still running. Stop only the agent you no longer need, inspect its partial work, and relaunch at most one bounded replacement. For future runs, give every custom subagent a narrow tool allowlist, a cheaper model when appropriate, and a maxTurns limit.

Do not assume that every fast usage spike is a bug. Each parallel worker has its own context, and Anthropic says agent-team usage scales with the number of active teammates and can reach roughly seven times a standard session in plan mode. The avoidable waste comes from broad prompts, too many concurrent workers, duplicate scopes, blind retries, and abandoned background work.

Diagnose the Fan-Out Before Stopping Anything

The goal is not to ban delegation. A focused subagent can keep noisy logs, searches, or test output out of the main context. The goal is to make the number of workers, their scope, and their stopping condition observable.

Prerequisites

Record the current state before changing it:

claude --version
git status --short
git diff --stat

Inside Claude Code, run:

/usage
/agents
/tasks

Expected result: you know the Claude Code version, current usage breakdown, active subagents, background tasks, and whether any worker has already changed files.

On current Claude Code builds, /usage can attribute recent usage to subagents, skills, plugins, and individual MCP servers. Treat that local breakdown as diagnostic evidence, not as an invoice. Subscription usage and API billing use different accounting surfaces.

Step 1: Stop One Agent, Not the Whole Session

Use the Running tab in /agents to inspect the live subagents in the current conversation. Use /tasks for background work and stop the specific item whose scope is obsolete, duplicated, or clearly wrong.

Avoid testing Ctrl+C while valuable background work is running. Anthropic documents global background-agent kill behavior, and fresh July 2026 bug reports describe a single interrupt or a steering message terminating unrelated subagents. A targeted stop leaves the remaining work intact.

Expected result: the selected agent stops, other needed work continues, and the main session remains available for inspection.

If the panel cannot stop the right worker, save the current state before using a global interrupt:

git status --short
git diff --name-only

Then copy any useful partial report from the agent transcript. Do not immediately launch the same prompt again.

Step 2: Audit Partial Work Before Retrying

A stopped or failed editing agent may have changed files without returning a final summary. This is especially important after an API overload or a lost background agent.

Review only the current worktree:

git status --short
git diff --stat
git diff

For a large diff, inspect the files the agent said it owned first. Run the smallest relevant test before deciding whether to keep the work.

Expected result: every changed file is either understood and retained, or left for deliberate human review. You do not pay for a replacement agent to rediscover completed work.

Do not use broad cleanup commands to recover. If several editing agents must work in parallel, give them separate Git worktrees so one failed worker cannot leave another worker's checkout in an ambiguous state. See How to Run Parallel Claude Code Agents With Git Worktrees.

Step 3: Create a Bounded Read-Only Subagent

Project subagents live in .claude/agents/. Create .claude/agents/bounded-researcher.md:

---
name: bounded-researcher
description: Research one named code area and return a concise evidence report
tools: Read, Grep, Glob
model: sonnet
permissionMode: plan
maxTurns: 20
---

Inspect only the paths named in the delegation prompt.
Do not edit files or run commands.
Return at most five findings with exact file paths and line numbers.
State what you did not inspect.
Stop when the requested evidence is collected

Restart the session or open /agents so Claude Code loads the new definition.

Expected result: the subagent can read and search the named code, cannot edit or execute shell commands, and stops after at most 20 agentic turns. If the parent runs in auto mode, Anthropic notes that the parent permission mode takes precedence, but the explicit tool allowlist still keeps the role narrow.

maxTurns limits a single custom subagent. It does not impose a global quota on how many agents the main conversation may start. Control that fan-out in the delegation prompt.

Step 4: Give the Parent a Concurrency Budget

Use a prompt that makes the budget and scopes explicit:

Use at most three bounded-researcher subagents.
Give each one a disjoint directory and one concrete question.
Run no agent in the background.
Do not start a replacement until all three reports are reviewed.
Return one deduplicated table of findings, evidence paths, and unknowns.
Stop after the table. Do not edit files

Expected result: at most three workers run, no two own the same directory, and the parent consolidates results before doing more work.

This is a prompt contract, not a hard runtime setting. Watch /agents during the first run. If Claude exceeds the requested budget, stop the extra worker and reduce the next request to one subagent.

Step 5: Choose Subagents or Agent Teams Deliberately

Subagents and agent teams solve different problems:

Claude Code's current documentation says subagents cannot spawn other subagents. If you observe what looks like nested fan-out, verify whether the main conversation started more workers, an experimental agent team is active, or a forked workflow is involved before reporting a nesting bug.

For routine tasks, prefer one conversation or one subagent. Reserve an agent team for work whose independent branches justify separate context windows.

Step 6: Measure Before and After

Run one representative task with the old workflow and one with the bounded workflow. Record:

• Claude Code version and model

• number of subagents or teammates

• wall-clock duration

• /usage session totals and subagent share

• duplicate findings or repeated file reads

• files changed and tests run

Keep the repository and prompt scope the same. Do not compare one trivial task with one architecture migration.

Expected result: the bounded run uses fewer concurrent workers and produces a complete, deduplicated result. A faster or cheaper result is useful only if it preserves the required evidence and verification.

Common Failure Modes

Why This Works

Parallel work multiplies contexts. Every active agent reads instructions, repository context, tool results, and its own conversation. Small, non-overlapping scopes reduce repeated reading. A cheaper model and a turn cap bound each worker. Foreground execution makes completion visible, while targeted stopping avoids discarding unrelated work.

The same structure explains why How to Expose the Ollama Service API to Your Network attracts durable traffic: the page mirrors a specific problem, answers it immediately, provides reproducible checks, shows expected results, separates similar failure boundaries, and explains why the fix works. This guide applies that structure to agent fan-out instead of copying the Ollama topic.

For broader usage diagnosis, see How to Diagnose Claude Code Usage Limit Spikes. For local attribution, see Claude Code JSONL Logs: Measure Token Usage Safely. For the opposite problem, see Claude Code Opus 5 Not Using Subagents? Fix Delegation.

Run One Bounded Read-Only Action

Set up Aident Loadout in your coding agent by pasting:

Follow https://aident.ai/SETUP.md

Then ask:

Check my Aident Loadout account and Vault status.
Find the connected read-only GitHub issue search Action.
Inspect its current schema and preflight it.
Search anthropics/claude-code for open issues about subagent token usage,
background agents, interrupts, steering, or API overload from the last 30 days.
Return at most ten issues with title, opened date, comments, reactions, status,
and URL. Do not create or edit issues, change files, or request a provider key.
Stop after ten results

Expected result: at most ten current issue records, zero provider writes, and one bounded evidence set for deciding whether your symptom is known. That is the measurable CTA.

Sources

• Manage costs effectively, Anthropic Claude Code documentation, accessed August 1, 2026

• Create custom subagents, Anthropic Claude Code documentation, accessed August 1, 2026

• Run agents in parallel, Anthropic Claude Code documentation, accessed August 1, 2026

• Orchestrate teams of Claude Code sessions, Anthropic Claude Code documentation, accessed August 1, 2026

• Claude Code changelog, Anthropic, accessed August 1, 2026

• Ctrl+C stops all subagents, issue opened July 31, 2026

• Steering the main chat kills background subagents, issue opened July 25, 2026

• Subagents terminate on API 529, issue opened July 30, 2026

• Per-subagent token usage tracking, feature request opened February 2, 2026

• Be careful running Claude Code subagents, community report published August 1, 2026

Refresh this guide when Anthropic changes agent-team cost guidance, background-agent interruption behavior, subagent usage attribution, or custom-agent limits.