SecurityValidator.hook.ts hangs when stdin doesn't close properly

[cleong14]

Description

The SecurityValidator.hook.ts PreToolUse hook can hang indefinitely when Claude Code doesn't properly close stdin before invoking the hook.

Root Cause

The hook uses Promise.race to implement a timeout (around line 586 in main()):

const text = await Promise.race([
  Bun.stdin.text(),
  new Promise<string>((_, reject) =>
    setTimeout(() => reject(new Error('timeout')), 100)
  )
]);

The problem: Promise.race timeout rejection does NOT cancel the underlying Bun.stdin.text() read. When stdin never receives an EOF (because Claude Code occasionally fails to close stdin properly), the process hangs forever - the timeout promise rejects but Bun.stdin.text() never resolves, keeping the process alive.

This is a fundamental limitation of JavaScript Promises - rejecting a racing promise doesn't abort the other promise's underlying I/O operation.

Symptoms

• Claude Code shows: running pre-tool use hooks 0 out of 2 done
• Hook never completes
• User must kill the process manually (Ctrl+C or kill)
• Occurs randomly on various Bash/Edit/Write/Read commands

Reproduction

This is intermittent and depends on Claude Code's internal stdin handling. More likely to occur under load or with rapid tool invocations.

To simulate the blocking condition:

mkfifo /tmp/test-fifo
# Open write end without writing (simulates stdin that never closes)
(sleep 30) > /tmp/test-fifo &

# This will hang forever (the bug)
bun run hooks/SecurityValidator.hook.ts < /tmp/test-fifo

Workaround

Wrap the hook with a bash script that uses GNU timeout --signal=KILL to hard-kill processes that block on stdin. SIGTERM doesn't interrupt blocked I/O on macOS FIFOs, but SIGKILL does.

SecurityValidator-wrapper.sh:

#!/bin/bash
TIMEOUT=2
HOOK_SCRIPT="${PAI_DIR:-$HOME/.claude}/hooks/SecurityValidator.hook.ts"

# Find GNU timeout
TIMEOUT_CMD=$(command -v gtimeout || echo timeout)

# Capture stdin with hard kill timeout
STDIN_CONTENT=$("$TIMEOUT_CMD" --signal=KILL "$TIMEOUT" cat /dev/stdin 2>/dev/null) || {
    echo '{"continue": true}'
    exit 0
}

[[ -z "$STDIN_CONTENT" ]] && { echo '{"continue": true}'; exit 0; }

# Run hook with captured content
"$TIMEOUT_CMD" --signal=KILL "$TIMEOUT" bun run "$HOOK_SCRIPT" <<< "$STDIN_CONTENT" || {
    echo '{"continue": true}'
    exit 0
}

Then in settings.json, change:

"command": "bun run ${PAI_DIR}/hooks/SecurityValidator.hook.ts"

to:

"command": "bash ${PAI_DIR}/hooks/SecurityValidator-wrapper.sh"

Proposed Fix

Option A (minimal): Document the workaround and add the wrapper script.

Option B (recommended): Add a helper function that spawns stdin read in a killable subprocess:

async function readStdinWithTimeout(timeoutMs: number): Promise<string | null> {
  const proc = Bun.spawn(['cat'], {
    stdin: 'inherit',
    stdout: 'pipe',
  });
  
  let killed = false;
  const timer = setTimeout(() => {
    killed = true;
    proc.kill();
  }, timeoutMs);
  
  try {
    const text = await new Response(proc.stdout).text();
    clearTimeout(timer);
    return killed ? null : text;
  } catch {
    clearTimeout(timer);
    return null;
  }
}

Environment

• macOS (Darwin)
• Bun 1.x
• Claude Code CLI

Impact

This blocks tool execution requiring manual intervention, severely impacting usability.

[danielmiessler]

Thanks for reporting this! We've been doing a major restructuring of PAI's core systems, including a complete redesign of the hook architecture (consolidated from 22 to ~19 hooks), a rewritten Algorithm (now v0.5.1 with PRD-based verification), removal of the observability system, and numerous path/configuration fixes.

This specific issue is addressed by those changes. We're targeting a v3.0 release soon that will include all of this. We appreciate your patience and your help in identifying these issues — it directly informed our redesign work. Stay tuned!

[kaimagnus]

Thanks for the detailed debugging! The SecurityValidator hook was rewritten for v3.0 (now released), which should resolve the stdin hanging issue. Please upgrade to v3.0 — if you still see hangs, please open a new issue.

[kaimagnus]

Reopening — SecurityValidator.hook.ts still exists in v3.0. The stdin hanging issue may persist. Needs verification.

[kaimagnus]

Fixed in commit 95d65cc. Replaced Bun.stdin.text() (which can't be cancelled by Promise.race) with a streaming reader approach using Bun.stdin.stream().getReader(). Added a hard process.exit(0) timeout at 200ms that kills the process if stdin never closes, ensuring it can't hang indefinitely. Maintains fail-open behavior. Thanks for the excellent root cause analysis! 🙏