Ran into a pretty nasty Claude sub-agent pitfall — sharing as a rant + note: I asked Claude to write a plan before execution. Being “helpful,” it spun up a tiny Claude as a plan agent. Then I just watched my usage get burned all the way to the 5-hour limit… with zero output. (Not just tokens — it actually maxed out the Claude Code 5-hour usage cap.) I asked what happened, and it said : “The plan agent’s output was too long and exceeded the API response limit, so it kept retrying.” Me : “Why didn’t you just have the subagent write it to a markdown file and return the file path?” Claude : “Oh right, good point, why didn’t I think of that.” So I quietly added this to my claude.md :
Tool Usage - Large outputs (>10KB) from subagents or external tools must be written to repo files. Do not return full content directly. - Messages should only include file paths, summaries, key conclusions, and next steps.
Lesson learned: Don’t let subagents return large documents as chat messages. Large outputs should become files. The main agent should only work with references + summaries. Otherwise, what you think is “planning” is actually just exhausting your 5-hour usage cap with retries. submitted by /u/Broad_Ad322
Originally posted by u/Broad_Ad322 on r/ClaudeCode