The Agent That Hung: Real Failures in Multi-Agent Orchestration

The AI success story format is well established: prompt goes in, working code comes out, developer is amazed. The failure format is less common. Which is strange, because failures are where the learning actually lives.

Here are four real failures from my multi-agent work. No tidying up, no lessons-learned framing that makes me look wise in retrospect. Just what went wrong. (The session where most of these failures happened — my first million-token session — is documented separately.)

Failure 1: The Visual Refiner That Wouldn’t Stop

During one session — the 16-hour one that cost $187 — I had a visual refinement agent running against a deployed web application. Its job was to take a screenshot, identify visual improvements, make changes, take another screenshot, verify the changes looked correct, and stop.

It didn’t stop.

The agent took a screenshot. Identified improvements. Made changes. Took another screenshot. Found new improvements in the updated screenshot. Made more changes. The cycle repeated. Every iteration, the agent was genuinely identifying real things to improve — but the bar kept moving. A change that fixed one issue introduced a slightly different visual inconsistency. The agent found it and tried to fix that too.

I force-killed it after noticing the token consumption was still running with no output being committed.

The fix I implemented afterward: explicit acceptance criteria passed to visual refinement agents. Not “make it look good” but “make the header background color #1a1a1a, the button radius 6px, and the card padding 16px.” Specific and verifiable. Also: timeouts. Any visual refinement agent that hasn’t completed within N iterations gets stopped with whatever it’s produced so far.

The lesson wasn’t “don’t use visual refinement agents.” It was: open-ended quality goals are infinite. You have to define done.

Failure 2: The Shell Script That Ate My Terminal

This one took hours to diagnose and turned out to be embarrassingly simple.

I’d set up a status line script — a terminal prompt enhancement that showed the current model name, session cost, and context usage in my terminal prompt. Useful, feels professional. I ran it for several sessions without issues.

Then session 7. Terminal commands were hanging. Not failing — hanging. A git status would sit there indefinitely. ls would hang. Even basic shell utilities were freezing.

I blamed Claude Code. I blamed the MCP server configuration. I blamed memory pressure. I rebuilt the session context twice.

The culprit: the status line script was capturing stdout from child processes to extract cost and context information. It did this by wrapping subprocess execution. The wrapper was interfering with how Claude Code spawned its own child processes. When the agent tried to run a bash command, the bash command’s output was being intercepted by the status script, which was waiting for specific patterns that never came, which caused the process to hang indefinitely.

The fix: remove the stdout capture from the status script. Use separate log files instead of intercepting subprocesses.

The lesson: terminal enhancement scripts and AI agent tooling can interact in ways that are completely invisible until they’re completely broken. Test them together before relying on both in a production session.

Failure 3: The MCP Permission Wall

I’d built specialized agents for different tech stacks: a Kotlin agent, a TypeScript agent, a React agent, a DevOps agent. Each had deep knowledge of its domain baked into its instructions. The specialization was real and valuable — the Kotlin agent genuinely made better decisions about Kotlin code than a general-purpose agent.

Then I tried to have a specialized agent create a Jira ticket.

Error. The specialized agent didn’t have access to MCP tools. It could only use the built-in Claude Code tools. Jira integration, GitHub integration, web fetching — all of those required MCP tool access, which was only available to general-purpose agents.

The entire architecture needed a workaround. Specialized agents can do everything in their domain, but they have to hand off anything requiring external integrations to a general-purpose agent. This means task routing logic — figuring out whether a task requires MCP tools and, if so, escalating to a general-purpose wrapper.

The lesson: understand your tool’s permission model before designing your agent architecture. The constraints aren’t always intuitive, and discovering them in the middle of a complex workflow is painful.

Failure 4: The Loop That Didn’t Know It Was Looping

During a session with multiple agents running in a team structure, one agent received a task, started working, hit an error, reported the error to the orchestrator, received the same task again with slightly different framing, hit the same error again, reported it again.

This continued for several cycles before I noticed.

The orchestrator was receiving the error report and re-queuing the task. It wasn’t recognizing that the error from the previous attempt was structural — a missing dependency that no amount of retrying would fix — rather than transient. The retry logic was working as designed. The design was wrong.

The fix: error classification. Transient errors (network timeouts, temporary failures) get retried. Structural errors (missing configuration, dependency errors, permission failures) get escalated immediately rather than retried. The orchestrator needed a way to distinguish “try again” from “I cannot proceed without intervention.”

The Common Thread

Single-agent failures are debuggable. You have one agent, one task, one failure — you read the output and understand what happened.

Multi-agent failures are emergent. They arise from interactions between agents, from timing issues, from permission mismatches that no single agent can see because each agent only has its own perspective. The failure I described in Failure 4 wasn’t visible to either agent involved. The orchestrator thought it was handling an error correctly. The worker thought it was reporting an error correctly. Both were right in isolation. The system was wrong.

The discipline that multi-agent systems require is closer to distributed systems engineering than to single-agent prompt design. You need timeouts, circuit breakers, error classification, failure modes, and escalation paths — not because the agents are bad, but because any system with multiple interacting components will fail in ways that none of those components can independently detect or recover from.

None of my agents failed stupidly. They failed in ways that were reasonable given their individual perspectives. The failures were architectural. (The 18-agent architecture that produced these failures is covered in its own post — along with the design decisions that made it work despite them.)