[BUG] Background subagents run indefinitely with no visible progress indicator or timeout, causing 3+ hour waits with no way to check status or interrupt without killing the entire session.

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?

Here's exactly what happened and why:

Root cause — agents ran Maven + Jest full test suites

When I dispatched the agents I told them to "write tests" but didn't say "don't run them." Each agent did this:

1. Read files (fast — seconds)
2. Write code (fast — minutes)
3. Run mvn test / npx jest to verify (SLOW — this is where they got stuck)

Why Maven takes so long:

• First run downloads every dependency not in .m2 cache — that's what you saw as the "Java download"
• Spring Boot test context startup alone = 30-60 seconds per test class
• 3 test classes × Spring context = 3-5 min just for boot
• With cold .m2 cache = 15-30 min downloading JARs first

Why Jest takes so long:

• Angular's Jest setup compiles TypeScript before running
• First run with no cache = full TypeScript compilation of the whole Nx workspace
• With 133 existing tests + new ones = 5-10 min

Why they never sent completion notifications:

• Agents likely got into a loop — test failed → tried to fix → ran tests again → failed again
• Each retry = another full Maven/Jest cycle
• No timeout on their end, no visibility on mine

What I should have done differently

1. Told agents: compile only, no test runs — I did this for the Sprint 3 agent but not the first three
2. Set my own 15-minute timer — I stated this rule but didn't enforce it
3. Checked file system at 15 min — the code was done within 20-30 min, I just didn't check

The product gap (for the feedback ticket)

Claude Code has no:

• Agent timeout (they run forever)
• Progress visibility (you can't see what they're doing)
• Interrupt mechanism (can't stop them without killing the session)
• Cost meter (you don't know how many tokens they've burned)

All four would have prevented a 3-hour wait.

What actually happens
Agent dispatched → black box → no output until it completes
No timeout — agents run until they finish or the session ends
No way to check progress mid-run (output_file path exists but reading it overflows context — stated in the tool response itself)
No way to stop a running agent without ending the entire session
If agent runs mvn test or npx jest and tests fail → it retries indefinitely, burning tokens silently

What Should Happen?

What should happen
Agent starts → user sees live status (e.g. "reading files... writing code... running tests")
Agent hits a configurable timeout (e.g. 15 min) → auto-terminates, returns partial result
User can interrupt a running agent mid-execution
If agent is stuck in a loop (retry → fail → retry), it detects it and stops after N attempts
Suggested fixes (in priority order)
Agent timeout — configurable, default 15 min, auto-terminates and returns partial result
Progress signal — lightweight heartbeat notification every N minutes ("agent still running: last action = writing LessonCompletionService.java")
Interrupt tool — AgentStop(agentId) that cleanly terminates a running agent
Token meter — show tokens consumed per agent in the notification
Safe progress read — a AgentStatus(agentId) tool that returns the last 10 lines of output without loading the full JSONL

Error Messages/Logs

No errors surface to the coordinator session. The agents fail silently. The only signal is "notification never arrived."
But the tool response itself warns:

"Do NOT Read or tail this file via the shell tool — it is the full sub-agent JSONL transcript and reading it will overflow your context."

So there is a progress file but it's inaccessible by design.

Impact
3+ hours of user wait with zero feedback
Unknown token cost (no meter)
Work was complete within 30 min but coordinator had no way to know
Environment
Claude Code (Claude Sonnet 4.6 session)
Windows 11, Maven 3.9, Java 21, Node 20
Spring Boot test context startup: ~60s per class (cold cache)
Maven cold dependency download: 15-30 min on first run

Steps to Reproduce

1. Open Claude Code session
2. Dispatch 3+ background agents with run_in_background: true
3. Each agent runs a Maven Spring Boot test suite (mvn test) or Jest suite (npx jest)
4. Wait
5. Observe: no notifications for 3+ hours
6. No way to check status except reading the raw JSONL transcript (which overflows context)
7. No way to stop agents

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.160

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

PowerShell

Additional Information

_No response_