Why Your Claude Code Subagents Aren't Working — Fixing Context Bleed and Bad Delegation

You set up subagents, gave them careful prompts — and now either Claude never delegates to them, or it does and the results come back worse than doing it yourself. Both failure modes have specific, fixable causes. This guide walks through them in the order you should check.

First, verify the agent is even loaded

Before debugging behavior, rule out the boring stuff:

• The file is in .claude/agents/ (project) or ~/.claude/agents/ (user) with a .md extension.
• The YAML frontmatter parses: opening and closing --- fences, a valid name (lowercase, hyphens), a description, no tab characters. One bad line and the agent silently doesn't exist.
• You've started a fresh session since adding it, and no same-named agent at another level is shadowing it (project beats user).

The quickest check: ask Claude "what subagents do you have available?" If yours isn't listed, the problem is loading, not delegation.

Problem 1: Claude never uses the agent

Delegation is a decision the main session makes by reading agent descriptions — not your system prompts. If your description says "An expert code reviewer with deep knowledge of best practices," Claude has no idea when to use it. Descriptions need trigger conditions, written like instructions to the delegator:

# ❌ A résumé
description: Expert code reviewer with 10+ years of experience
  in software quality.

# ✅ A delegation rule
description: Reviews code changes for bugs and design problems.
  Use PROACTIVELY after writing or modifying code, before
  committing. MUST BE USED for changes touching auth, payments,
  or data deletion.

Phrases like "use proactively" and "must be used when…" measurably increase delegation, because they speak to the exact moment the main session is deciding. If Claude still under-delegates, add a standing rule to CLAUDE.md ("always run the code-reviewer agent before committing") — or invoke the agent explicitly by name, which always works and confirms the agent itself is fine.

Problem 2: the agent runs but produces garbage

This is almost always a context problem, in one of two directions.

The agent knows too little

A subagent starts with a clean context window. It has not read your conversation. It doesn't know what you and the main session decided twenty minutes ago, which files matter, or what "the bug" refers to. When the main session hands over a vague task — "fix the validation issue" — the subagent rediscovers everything from scratch, sometimes wrongly. Fixes:

• In the agent's system prompt, require a briefing: "Expect the task description to include the files involved and acceptance criteria; if missing, state what you need instead of guessing."
• When you delegate manually, pass context explicitly: file paths, the decision already made, the constraint that matters.
• Put durable project facts in CLAUDE.md — subagents working in the project can read it, and it's the one context channel that doesn't depend on the handoff.

The agent returns too much — context bleed in reverse

The opposite failure: the subagent dumps its entire investigation — every file read, every dead end — back into your main session, defeating the isolation that justified the agent. The fix is an output contract in the system prompt: "Return only: a verdict, the evidence for it, and recommended next steps. Do not include file contents or a narration of your process." The difference between an agent that protects your context and one that floods it is usually that one sentence.

Problem 3: the agent can't do its job (tool scoping)

If the frontmatter's tools field is set, the agent gets only those tools. Two ways this goes wrong: the reviewer that can't read files because someone over-restricted it, and the "read-only" auditor that was never restricted at all and edits files mid-review. Match tools to the job — searchers and reviewers get read/grep, implementers add edit and bash — and remember that MCP tools need to be granted too if the agent depends on them. When an agent errors mysteriously, read the transcript: tool-permission failures are usually stated plainly there.

Problem 4: it works, but slower and more expensively than no agent

Subagents have a real overhead: each one boots a fresh context, re-reads whatever it needs, and reports back. For a two-line fix, that overhead exceeds the work. Delegation pays when the task is research-heavy (the agent absorbs forty files so your session doesn't), specialized (the checklist matters), or parallel (independent tasks at once). If your agents feel slow, check you aren't delegating work the main session would finish in one step — and if costs surprise you, read our token-economics guide.

A 5-minute diagnostic, in order

1. Ask Claude to list available subagents. Missing → fix file location/frontmatter.
2. Invoke the agent by name. Works → the description is your problem; sharpen triggers.
3. Read the returned result. Vague → tighten the output contract; wrong → improve the briefing it receives.
4. Check the tools list against what the job requires.
5. Ask whether this task needed an agent at all.

FAQ

Keep reading