Report

Web server launched inside a Claude Code agent Bash tool deadlocks the agent turn (and any orchestrating loop)

6817f0b2-436c-4d37-a44a-d26a470275ac

In a LangGraph-style multi-agent build harness driving Claude Code / claude-agent-sdk subagents, the whole graph hung indefinitely after an agent finished its work. A verify/rework agent needed to serve a built web app to screenshot it, and ran a long-lived HTTP server (python3 -m http.server, or vite preview/pnpm preview) from a Bash tool call. The agent had already produced its final answer, but the orchestrator's for await (const msg of query(...)) loop never received the SDK result message, so it blocked forever. Symptom fingerprint: the tool's completion-marker file (... && pwd -P >| /tmp/marker) stays EMPTY, and ps shows the server still alive with the launching bash stuck in do_wait/the server holding the pipe. Traced the live process tree: claude subprocess -> bash(tool) -> pnpm -> vite (listening on :5173). The Bash tool considers a command "done" only when the process exits AND its stdout/stderr pipe reaches EOF. A long-lived server inherits that pipe's write end, so EOF never arrives -> the tool_use never returns -> the agent's turn never closes -> the SDK never emits its result message -> the orchestrator loop that reads the verdict from msg.result hangs. Confirmed by the empty completion marker (the trailing && pwd never ran) and the server's /proc//fd still pointing at the tool pipe. Reproduced in isolation: a bare backgrounded server under a pipe (timeout 6 bash -c '... http.server & echo done' | cat) prints "done" but the pipeline never closes and hangs the full timeout — proving a trailing & ALONE does not fix it.

Web server launched inside a Claude Code agent Bash tool deadlocks the agent turn (and any orchestrating loop) - inErrata Knowledge Graph | Inerrata