PostToolUse hook fails on Windows: ${CLAUDE_PLUGIN_ROOT} path exceeds MAX_PATH

[bs966933-tech]

Bug

The PostToolUse: Write|Edit|MultiEdit hook in hooks/hooks.json fires on every file edit in Claude Code and fails:

C:\Users\<user>\AppData\Local\Python\pythoncore-3.14-64\python.exe: can't open file
'C:\Users\<user>\AppData\Roaming\Claude\local-agent-mode-sessions\<session-uuid>\<sub-uuid>\rpm\plugin_<ULID>\scripts\check-sql-files.py':
[Errno 2] No such file or directory

The script exists at that path (confirmed via dir/ls), but Windows-native python.exe cannot open it. Every Write/Edit/MultiEdit surfaces a blocking error in Claude Code, breaking the editing flow.

Environment

• Windows 11
• Claude Code desktop
• Plugin: cockroachdb@claude-plugins-official v0.1.9
• Python: 3.14.3 (Windows native, pythoncore-3.14-64)

Root cause

Claude Code resolves ${CLAUDE_PLUGIN_ROOT} to a per-session sandbox path that nests two UUIDs and a ULID:

C:\Users\<user>\AppData\Roaming\Claude\local-agent-mode-sessions\<UUID>\<UUID>\rpm\plugin_<ULID>\

That prefix is ~170 chars. Plus scripts\check-sql-files.py it's ~250 chars — right against Windows' MAX_PATH (260). Windows long-paths support requires HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled = 1, which is off by default.

So Python's open() fails with Errno 2 even though ls (Cygwin layer) shows the file.

Impact

Affects every Windows user without LongPathsEnabled. The cockroachdb plugin's SQL anti-pattern lint silently breaks the entire Edit flow rather than just failing the check. The PreToolUse hook calling validate-sql.py has the same fragility, just fires less often.

Suggested fixes (any one of these resolves it)

1. Wrap the hook so script-not-found exits 0, never blocks. A lint hook should never break editing.
2. Inline the check: for scripts this small, embed the regex check directly in the hooks.json command so no path resolution is needed.
3. Use python not python3 on Windows: the python3 shim under AppData\Local\Microsoft\WindowsApps adds an indirection layer.
4. Document the Windows long-path requirement in README.

Local workaround

Remove the PostToolUse block from hooks/hooks.json to stop the noise. Loses the lint feature but unblocks editing.

---

Reported via Claude Code session, plugin install path:
C:\Users\<user>\.claude\plugins\cache\claude-plugins-official\cockroachdb\0.1.9

[viragtripathi]

Thanks for the detailed report. Confirmed and fixed.

Root cause

The PostToolUse hook (matcher Write|Edit|MultiEdit) and the PreToolUse hook both invoked python3 with the full ${CLAUDE_PLUGIN_ROOT} script path. On Windows that path lives in a deeply nested plugin cache, and once it goes past the 260 character MAX_PATH limit, python cannot open the script and exits with the can't open file ... [Errno 2] error you saw. Because the PostToolUse matcher is broad, that surfaced on essentially every edit. I reproduced the same failure signature to confirm the mechanism.

Fix (#21)

The hooks now run a small inline bootstrap that loads the script with runpy and, on Windows, prefixes the path with the \\?\ long-path escape that bypasses MAX_PATH. The bootstrap has no long path to open itself, so it cannot hit the limit, and a trailing ; exit 0 means a failed bootstrap is a no-op rather than an error on every edit. The existing scripts stay in place, so the safety checks actually run on Windows now instead of failing quietly.

Your other suggestions are covered too: CONTRIBUTING now documents this pattern so new hooks do not reintroduce the problem, and the README has a short Windows note. On the python3 vs python point, that is a separate concern from MAX_PATH (your environment had a working python3), so we kept python3 and documented the PATH expectation rather than adding a fragile per-shell interpreter switch.

You no longer need to enable Windows long-path support for the hooks to work.

Closing as fixed in #21. Thanks again for the clear write-up and the suggested fixes.