analysis_windows_hangs.md

Analysis & Recommendation for Maintainers

Following up on the great context provided by @L0rdS474n, I've completed a full audit of all hooks.json files in the repository.

Findings:

The following plugins are confirmed to be missing "async": true for their command-based hooks, which is the direct cause of the Windows startup hang:

1. plugins/hookify/hooks/hooks.json
2. plugins/security-guidance/hooks/hooks.json
3. plugins/explanatory-output-style/hooks/hooks.json
4. plugins/learning-output-style/hooks/hooks.json
5. plugins/ralph-loop/hooks/hooks.json

Technical Root Cause:

On Windows, synchronous subprocess calls (especially during the SessionStart or PreToolUse phases) can block the Node.js event loop before it has established its internal polling for subprocess handles. This results in a deadlocked state where Claude Code is waiting for a process to finish, but the signal that it has finished cannot be processed by the blocked loop.

Next Steps for Maintainers:

Since PR #354 was auto-closed due to policy, I recommend that a team member cherry-pick the following changes to restore Windows stability:

• Add "async": true to every hook entry of type "command" or "shell" in the 5 files listed above.
• Investigate the Trivago connector: As noted by the community, this connector might be inheriting or triggering similar blocking behavior when proxied to Claude Code. If it uses hooks, it likely also needs async: true.

Long-term Fix:

Consider adding a validation check in the claude-plugins system to warn or enforce async: true for hooks that don't need to return a block/allow decision (i.e., side-effect hooks).