[BUG] Subagent loops re-reading the same images after Claude Code removes older images from its context, which exhausts usage limits

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Title: Subagent loops re-reading the same images after Claude Code removes older images from its context, which exhausts usage limits

Version: Claude Code 2.1.296, desktop app (Code tab), macOS. Model Opus 5.5, background subagents.

What happened: Two background subagents were each asked to view about 80 PNG page renders with the Read tool and report defects at the end. Once a request neared the image limit, Claude Code removed the oldest images in batches, as described in the prompt-caching docs; this happened about 50 times per agent. After each removal the agent no longer had the early pages, so it started again from the first page. Each agent made about 20 passes, about 1,600–1,700 image reads, over 47 minutes. Every removal also forced a full prompt-cache rebuild, of 70k–300k tokens. Neither agent produced any output. The parent session was idle, waiting for a notification, so nothing stopped them until the account hit its 5-hour usage limit.

Expected:

Detect a subagent re-reading the same unchanged files in a cycle, and stop it or warn the user.
When images are removed from a subagent’s context, tell the agent which ones, so it knows what it has already seen.
Give subagents a usage or turn budget by default, not only through maxTurns in the agent file.
Show the user a warning when one background agent passes a large share of the usage limit.

Workaround in use: a PreToolUse hook that keys on agent_id and refuses image reads after 30 per agent, and any third read of an unchanged file; plus maxTurns on custom agents.

What Should Happen?

Expected:

Detect a subagent re-reading the same unchanged files in a cycle, and stop it or warn the user.
When images are removed from a subagent’s context, tell the agent which ones, so it knows what it has already seen.
Give subagents a usage or turn budget by default, not only through maxTurns in the agent file.
Show the user a warning when one background agent passes a large share of the usage limit.

Error Messages/Logs

Steps to Reproduce

What happened: Two background subagents were each asked to view about 80 PNG page renders with the Read tool and report defects at the end. Once a request neared the image limit, Claude Code removed the oldest images in batches, as described in the prompt-caching docs; this happened about 50 times per agent. After each removal the agent no longer had the early pages, so it started again from the first page. Each agent made about 20 passes, about 1,600–1,700 image reads, over 47 minutes. Every removal also forced a full prompt-cache rebuild, of 70k–300k tokens. Neither agent produced any output. The parent session was idle, waiting for a notification, so nothing stopped them until the account hit its 5-hour usage limit.

Claude Model

Opus

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.1.296

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_