What To Do When a Claude Code Subagent Gets Stuck

The symptom: the lead just stops talking

You gave Claude Code a job, it decided to split the work, and it dispatched a batch of subagents. Then the terminal went quiet. Ten minutes pass. No spinner changes, no error, no new line. The process is still alive, CPU use still twitches now and then, but nothing prints. You are left staring at a blinking cursor, deciding whether to wait or kill the session and start over.

This is a common complaint about running subagents, widely reported by users: a session that goes silent with no error, an agent that is hanging with no visible timeout, a subagent that just hangs and never comes back. The good news is that this failure has a documented cause rather than a mysterious one, and a short list of things to check before you assume the session is dead.

Why one stalled subagent holds up the whole lead

Claude Code's subagent feature follows what Anthropic calls the orchestrator worker pattern: a lead agent breaks a job into pieces and hands each piece to a subagent, which starts with a fresh, isolated context window and reports back once it finishes, not continuously. The lead cannot keep going while those subagents work.

Anthropic's own account of building a system this way states plainly that synchronous execution creates bottlenecks, because the lead waits for every subagent in a batch to return before acting on any of them. That is why a single stuck worker freezes everything. Dispatch three subagents and have two finish in thirty seconds while the third runs five minutes longer, and the lead still has nothing to show you, because it is waiting on the batch as a whole. Underneath, one subagent out of three is the problem, and the lead cannot move past it without that result.

• The lead waits for every subagent in a batch before it can continue.
• A subagent reports back once, when it finishes, not continuously.
• Nothing printing is not the same as nothing happening.

Is it actually working, or waiting on a permission prompt?

The first thing to rule out is the most ordinary one. Claude Code ships six permission modes, and the default for most interactive sessions, as of version 2.1.283, is called auto: a second classifier model reviews each action and lets harmless ones through on its own. A write to a protected path is not harmless by that classifier's rules, and it is never auto-approved outside the separate bypassPermissions mode. A subagent that hits one of those sits waiting for a human to say yes, and that prompt can be sitting several screens up if you were not watching when it appeared.

Scroll back through the whole buffer before you touch anything else. If a permission prompt is waiting on a keypress, answering it is the whole fix: the lead was never stuck, it was paused on you. This also explains why a destructive command, an rm or an rmdir on a path Claude Code treats as critical, is refused in every mode including bypassPermissions. That refusal prints an error, so it rules out one possibility rather than causing the quiet hang you are looking at.

• Scroll up through the entire terminal buffer, not just the last screen.
• Auto mode still asks a human before a protected-path write.
• A refused destructive command prints an error. A silent hang is something else.

Has the batch hit a shared usage limit?

A subagent is not a separate account. Claude Code's documentation states a subagent's requests count toward the same usage limit as the main conversation, so several subagents at once burn through that shared ceiling faster than one agent alone would. If you have had more than one session open, or several subagents in parallel, check whether you are close to a limit before assuming the subagent itself has failed.

A throttled request does not always surface as a clean message in every client, so silence can be the honest symptom. Several unrelated sessions on the same account going quiet at once points at the shared limit rather than one broken subagent. The fix is waiting for the reset or queuing the next prompt for when it comes back, not debugging the task itself.

• A subagent's requests draw on the same usage limit as the main session.
• Running several subagents in parallel reaches that ceiling faster than one agent alone.
• Several sessions stalling at once, on one account, points at the shared limit.

Is it looping instead of hanging?

A process still consuming CPU is doing something, even if not useful. Open a process monitor and watch the Claude Code process for thirty seconds. Steady, repeating CPU activity with no new output often means a subagent is stuck in a loop: retrying a failing command, or re-reading the same large file, rather than waiting on you or a model response.

A loop is worth interrupting sooner than a genuine wait, because it will not resolve on its own. If CPU use is flat and near zero instead, the process really is idle, which points back toward a permission prompt or a usage limit.

• Steady, repeating CPU activity with no new output usually means a loop.
• Near-zero CPU use points at something waiting, a prompt or a throttled request.
• A genuine loop will not resolve on its own. Interrupt it.

How to interrupt it without losing what it already did

If you have ruled out a permission prompt, a usage limit, and a loop, and the batch has genuinely stalled, interrupt it. Ctrl-C stops the current turn in Claude Code and hands control back to you. What you lose is the conversation itself: the subagent's fresh context window, and whatever reasoning it was holding, goes with it the moment you interrupt.

What you do not necessarily lose is the work already written to disk. A subagent edits real files in your project, and a file it saved before stalling stays saved. Run git status and git diff right after you interrupt, before restarting anything, so you can see exactly what landed and what did not. Keep whatever is useful, discard the rest, and give the next attempt a narrower task.

• Ctrl-C ends the stuck turn. The subagent's in-memory context is gone the moment you do it.
• Files already written to disk before the stall are not undone.
• Check git status and git diff immediately, before you restart.

Keeping the next one from doing this

Claude Code sets no timeout on a subagent's call today, so nothing in the tool itself will cut off a stalled worker for you. A few habits reduce how often that matters.

Keep each subagent's job bounded: one file, one function, one clearly finished state, rather than an open-ended instruction it keeps reinterpreting. Anthropic's own account of this pattern names an early failure mode where the lead dispatched far more subagents than a query needed; a narrow task is also less likely to wander into a long retry loop. Write the brief down before you dispatch it, the way you would for a contractor: what done looks like, which files are in scope, what to do if unsure. A written brief lets a different agent pick the job back up cleanly after an interrupt.

Decide your own check-in interval, since Claude Code sets none, and do not nest subagents deeper than the job needs. Claude Code allows up to three layers of subagents spawning subagents by default, and each extra layer is another place a stall can hide, with the same synchronous wait compounding at every level.

• Give each subagent a bounded, checkable task, not an open-ended one.
• Write the brief before you dispatch it: scope, done state, what to do if stuck.
• Nothing in Claude Code will interrupt a stalled subagent for you.
• Keep delegation shallow. Each nested layer is another place a stall can hide.

Where a Forkbench squad handles this differently

Claude Code's subagents are real and work well for what they are built for: one session, one vendor, delegating inside its own conversation. The limit is structural, not a flaw. Because everything happens inside one conversation, the only window onto a stalled worker is that session's own silence, and the only way to act on it is to interrupt the whole conversation.

A Forkbench squad moves the same lead and helpers idea onto a board instead of into one conversation. A task a lead hands to a helper is claimed as a lease, not held open in shared memory: if the pane running that helper closes, the lease releases at once and the task goes back to ready. A helper that is still alive but genuinely stuck, rather than merely closed, is caught by a 120-second heartbeat the lease depends on, and if a whole Thread's board goes quiet for too long, a stall alert fires rather than leaving you to notice on your own.

The difference shows up at this exact moment: each helper runs as its own session and shows as a chip on the lead's tab with its own state, so a stalled one is seen at a glance, not inferred from a conversation that stopped printing. That does not make a vendor's own subagent feature faster. It is a different layer, for when delegation itself needs to be visible and recoverable rather than private to one session.

• A claimed task is a lease. Closing the pane releases it immediately.
• A 120-second heartbeat catches a helper that is alive but stuck.
• A stall alert fires when a board has gone quiet too long.
• Each helper has its own visible pulse, so a stalled one is seen.