[BUG] Background bash with heredoc >512 bytes deadlocks — unix socket connections hang

Resolved 💬 3 comments Opened Apr 7, 2026 by birdmanmandbir Closed Apr 7, 2026

What's not working?

When Claude Code runs a background bash command with a heredoc exceeding 512 bytes, the process deadlocks before executing. The command never starts — unix socket connections from the child process are routed to CC's IPC layer instead of their intended destination.

Root cause (same as issue #33768): macOS pipe buffers are only 512 bytes. When bash tries to write a heredoc larger than the buffer, it blocks waiting for a reader — but bash hasn't forked the child process yet, so nothing reads from the pipe. The deadlock prevents the child process (e.g. ei agent run --async) from ever executing or connecting to its unix socket.

Steps to reproduce

  1. Run a background bash command with a heredoc >512 bytes:
ei agent run --async plan-gap-finder "$(cat <<'PROMPT'
...large multi-line content over 512 bytes...
PROMPT
)"
  1. The process starts but hangs — 0% CPU, blocked on syscall
  2. The intended unix socket connection never reaches the target daemon
  3. Short heredocs (<512 bytes) work fine

Confirmed: ei ask --async with short prompts works. ei agent run --async with large heredoc hangs indefinitely. Both run the same daemon code path.

Expected behavior

Background bash commands with large heredocs should execute normally, regardless of heredoc size.

What should happen instead?

  1. Use /bin/bash instead of #!/usr/bin/env bash for heredoc execution (system bash on macOS uses temp files, not pipes)
  2. Use temp files for heredocs instead of pipes (eliminates the buffer size dependency entirely)
  3. Add timeout on heredoc pipe writes so deadlocked heredocs don't hang indefinitely

Notes

  • Issue #33768 documents the same root cause for plugin hooks on macOS with Homebrew bash
  • This affects any background bash command with a heredoc >512 bytes, not just plugins
  • The deadlock prevents the child process from ever starting — unix socket connections from that process go nowhere

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗