Claude Code Windows Symlink Permission Issue Investigation

Problem Discovery

While using Claude Code for code review, I launched multiple background sub-agents to work in parallel. After completion, I noticed a strange phenomenon:

├─ superpowers:code-reviewer (Review code quality) · 58 tool uses · 0 tokens ⎿ Done
├─ Agent (Review UI/UX design) · 34 tool uses · 0 tokens ⎿ Done
├─ Explore (Explore project structure) · 12 tool uses · 0 tokens ⎿ Done

The sub-agent clearly executed 58 tool calls, how could it be 0 tokens?

Phase 1: Suspecting Race Condition

Initially through analyzing temporary files, I discovered:

Metric	Value
Total output files	89
Empty files (0 bytes)	82 (92%)
Non-empty files	7 (8%)

Combined with transcript file showing 41397 tokens actually generated, I initially thought this was caused by race condition:

T0: Sub-agent completes
T1: completeAgentTask() called
T2: void evictTaskOutput(taskId)  ← Doesn't wait
T3: enqueueAgentNotification() sends notification
T4: Main session reads output file → File is empty
T5: Disk flush completes (too late)

I detailed this hypothesis in the Issue.

Phase 2: Validation Found Anomaly

To validate, I launched multiple background sub-agents again for testing. Result:

All sub-agent output files were 0 bytes!

This was too uniform to be a race condition. Race conditions should sometimes succeed and sometimes fail, but here it was 100% failure.

Phase 3: Discovering the Real Cause

I checked the file type:

ls -la *.output
# -rw-r--r-- 1 user 0 ... xxx.output
# Regular empty file

Looking at the source code, I found initTaskOutputAsSymlink() function:

Tries to create symlink from output file to transcript
Falls back to creating empty file on failure

Key discovery: Creating symlinks on Windows requires special permissions!

Testing PowerShell:

New-Item -ItemType SymbolicLink -Path "link" -Target "target"
# Error: This operation requires administrator privileges.

Confirmed: Windows by default doesn't allow regular users to create symlinks, requires Developer Mode.

Phase 4: Enabling Developer Mode

Enable Windows Developer Mode:

Settings → Update & Security → For developers → Developer mode

After retesting:

ls -la *.output
# lrwxrwxrwx 1 user 120 ... xxx.output -> agent-xxx.jsonl
# Now a symlink, pointing to transcript file
 
wc -c *.output
# 1498 xxx.output  ← Has content now!

Problem solved!

Final Conclusion

Original Hypothesis	Actual Cause
Race condition	❌ Wrong
Windows symlink permission issue	✅ Correct

Root cause:

Windows by default doesn't allow regular users to create symlinks
CLI silently falls back to empty file when symlink creation fails
No user prompt about permission issue or solution

Submissions

Issue #55263

Added the real cause analysis to the Issue and provided a workaround:

Windows users can try enabling Developer Mode:

Settings → Update & Security → For developers → Developer mode

PR #56334

Submitted documentation improvement, adding Windows Developer Mode note in README:

Note for Windows users: Some features require symlink support. Enable Developer Mode if you encounter issues with background agents.

This PR received APPROVED from a community user.

Lessons Learned

Debugging Methodology

Elimination - Verify hypotheses one by one
Statistical data analysis - 92% empty file rate too uniform, not like race condition
Check file type - ls -la showing file type was key clue
Verify hypothesis - Problem solved after enabling Developer Mode
Gradual deepening - From code analysis → behavior observation → permission verification

Truth Over Face

Initially thought the cause was race condition. But when evidence pointed elsewhere, needed to admit error and supplement with the real cause.

Truth and integrity matter more than reputation.