Auto-updates silently break ~/Documents access on macOS (TCC denial without dialog)

Summary

Each Claude Code auto-update on macOS installs the binary at a new versioned path (~/.local/share/claude/versions/<version>). Because the binary is signed with the hardened runtime and has its own bundle identifier (com.anthropic.claude-code), macOS TCC treats every new version as a separate TCC subject. The previous version's grants do not carry over, and Terminal's TCC permissions (Documents/Downloads/Full Disk Access) do not propagate to the child binary.

The result: after auto-update, any attempt to read ~/Documents, ~/Downloads, or ~/Desktop from Claude Code returns silent EPERM. No permission dialog appears because CLI binaries cannot trigger TCC UI prompts in non-foreground / headless contexts. The user has no signal that anything broke — tools simply fail.

Environment

• macOS 25.4.0 (Darwin) / Apple Silicon
• Claude Code 2.1.141 (also seen on 2.1.137, .138, .139, .140)
• Terminal.app with Full Disk Access granted
• Long-running tmux sessions accessed via remote control

Reproduction

1. Grant Terminal.app Full Disk Access.
2. Run Claude Code, access ~/Documents — works (an explicit per-binary TCC entry exists for that version).
3. Wait for auto-update to install a new version.
4. From the same Terminal/tmux session, try to read ~/Documents again.
5. Observe: Operation not permitted. No dialog. No prompt. Silent failure.

$ ls ~/Documents/
ls: /Users/<user>/Documents/: Operation not permitted

$ sqlite3 ~/Library/Application\ Support/com.apple.TCC/TCC.db \
    "SELECT client, service, auth_value FROM access WHERE client LIKE '%claude%';"
.../claude/versions/2.1.138|kTCCServiceSystemPolicyDocumentsFolder|2
.../claude/versions/2.1.139|kTCCServiceSystemPolicyDocumentsFolder|2
.../claude/versions/2.1.140|kTCCServiceSystemPolicyDocumentsFolder|2
# .141 has no entry — silent deny

Root cause

The installer's choice to use a versioned binary path (versions/<version>) is fundamentally incompatible with how macOS TCC tracks command-line tools. TCC stores grants keyed by full binary path for non-bundled signed binaries — so every new version is a new TCC subject, no matter that the bundle identifier (com.anthropic.claude-code) and Team ID are stable. The hardened runtime flag prevents inheriting permissions from the parent Terminal.

Impact

For users with long-running remote/headless setups (tmux, mosh, ssh, Screen Sharing) — exactly the workflow that makes Claude Code valuable as an always-on assistant — every auto-update silently disables file-system access until the user notices, finds the new versioned path, and manually adds it to Full Disk Access in System Settings. There's no error visible in the UI, no notification, and no path to self-recovery without the user knowing about macOS TCC internals.