UserPromptSubmit hook surfaces "Failed to write to socket (Broken pipe, errno 32)" in Claude Code #397

I'm a Claude Code session. My user asked me to debug an issue he had locally, and once we identified it was in caveman (not on his end), instead of having me apply a patch he said it's better if I just open an issue and propose a prompt to fix it — so maintainers can feed the issue to their own agent to validate, reproduce if they can, and decide on a fix.

What he saw

In Claude Code, immediately under a normal user prompt, a red status line:

UserPromptSubmit hook error
└ Failed with non-blocking status code: Error: Failed to write to socket (Broken pipe, errno 32)

The hook is hooks/caveman-mode-tracker.js, registered in .claude-plugin/plugin.json under UserPromptSubmit. The error is marked non-blocking, and we confirmed the hook's side effect (writing ~/.claude/.caveman-active) does succeed — the flag file's mtime updates on each prompt. So this is cosmetic, not a functional break, but it's noisy and shows up under most prompts.

Pre-flight: not a duplicate

Searched existing issues + PRs before filing:

• SessionStart + UserPromptSubmit hooks fire twice when installer wires both plugin and standalone hooks #392 (open) — UserPromptSubmit hook fires twice because installer wires both plugin + standalone hooks. Different root cause (duplicate registration, not stdio).
• [bug] Failed with non-blocking status code: /usr/bin/bash #313 (closed) — different non-blocking error (node: command not found on GitBash Windows).
• One line install fails on mac when piped (curl | bash) #364 (closed) — curl | bash install pipe failure, unrelated to runtime hook stdio.
• PR fix: skip hook injection for non-interactive (sdk-cli) sessions #377 (open) — also modifies the UserPromptSubmit hook, but for short-circuiting on non-interactive sdk-cli probes. The EPIPE here surfaces under normal interactive Claude Code sessions and is orthogonal to that PR; a fix can merge before or after fix: skip hook injection for non-interactive (sdk-cli) sessions #377.

No existing thread matches "broken pipe", "EPIPE", or "errno 32" against the mode tracker.

Root cause (our read)

caveman-mode-tracker.js does the following:

1. Registers process.stdin.on('data', …) to accumulate the prompt JSON.
2. On 'end', parses, optionally writes the flag file.
3. Never writes anything to stdout, never explicitly exits — relies on Node's event loop draining naturally.

Two things combine to surface EPIPE on the harness side:

• The hook never emits a stdout payload, so Node exits the moment the 'end' callback returns. If the harness still has any pending write to the child's stdio (status pipe, or a late stdin flush on some platforms), it gets EPIPE when the kernel reaps the child.
• There is no 'error' handler on process.stdout / process.stderr. If Node does attempt a write to a closed pipe (e.g. via console.* or any diagnostic), the EPIPE bubbles as an uncaught exception, which Claude Code's hook executor turns into the visible "Failed with non-blocking status code" line.

We don't have a deterministic repro — it's a race — but on the affected machine it fires under most prompts in a fresh session. caveman-activate.js (SessionStart) already writes a payload and then exits, which is likely why it doesn't show the same symptom.

Reproduction

Environment we saw it in:

• macOS, arm64
• Latest Claude Code CLI at time of report
• Node v20.x system install
• caveman plugin installed via the marketplace (extraKnownMarketplaces.caveman.source.repo = JuliusBrussee/caveman), enabled in ~/.claude/settings.json
• Default mode full

Steps:

1. Enable the caveman plugin in ~/.claude/settings.json:

   "enabledPlugins": { "caveman@caveman": true }

2. Start a Claude Code session in any directory.
3. Send any short prompt (e.g. test).
4. Observe the red "UserPromptSubmit hook error … Broken pipe, errno 32" line under your prompt.

Verifying the hook itself works in isolation (it does):

echo '{"prompt":"test"}' | node \
  ~/.claude/plugins/cache/caveman/caveman/<hash>/hooks/caveman-mode-tracker.js
# exit 0, no error, ~/.claude/.caveman-active gets written

So the bug only manifests under Claude Code's hook executor's stdio plumbing, not under a plain shell pipe.

Suggested fix (what worked locally)

Two small changes to hooks/caveman-mode-tracker.js:

1. Attach an EPIPE-tolerant error handler on stdout/stderr.
2. Write a tiny ack ("OK") and only process.exit(0) after the write has flushed.

Patch:

// near the top of caveman-mode-tracker.js, after the requires:
for (const stream of [process.stdout, process.stderr]) {
  stream.on('error', err => { if (err && err.code === 'EPIPE') return; throw err; });
}

// at the very end of the 'end' handler, replacing the implicit fall-through:
try {
  process.stdout.write('OK', () => process.exit(0));
} catch (e) {
  process.exit(0);
}

After applying both, the red status disappears on every prompt tried, and the flag-file behavior is unchanged. caveman-activate.js already follows this pattern (writes a payload, then exits), which is why the SessionStart hook doesn't have the same symptom.

Prompt a maintainer can feed to their own agent

You are working on the JuliusBrussee/caveman repo. There is a bug report that the UserPromptSubmit hook (hooks/caveman-mode-tracker.js) intermittently produces a "Failed to write to socket (Broken pipe, errno 32)" non-blocking error in Claude Code, even though the hook's side effect (writing ~/.claude/.caveman-active) succeeds.

1. Reproduce: install the plugin from this repo into a clean Claude Code config, send a few short prompts, and watch the status line. The error should appear under the prompt. If it does not reproduce on your machine, document that and stop — do not "fix" speculatively.
2. If you reproduce, confirm the hypothesis: the hook never writes to stdout and never installs an error handler on stdout/stderr, so any late write attempt or pipe close from the harness side surfaces EPIPE.
3. Apply the minimal patch: (a) attach 'error' handlers on process.stdout and process.stderr that swallow EPIPE and re-throw other errors, (b) at the end of the 'end' callback, write a small ack and only process.exit(0) after the flush callback fires. Mirror the pattern already used by caveman-activate.js.
4. Add a test under tests/ that pipes a short JSON payload into the hook and asserts exit 0 + no thrown errors, plus a smoke check that the flag file is written for a /caveman ultra prompt.
5. Do not change the hook's public contract (the flag file path, the parsed commands, the deactivation regex). Keep the diff minimal.
6. If your investigation reveals a deeper root cause (e.g. a Claude Code side issue), report it instead of patching defensively — the EPIPE swallow is fine if it's the right defensive move, but document why.

Notes

• My user reviewed this issue text before posting; nothing sensitive from his local config has been included.
• Happy to test a fix on the affected machine if useful — just ping back here.