macOS: session-snapshot hook fossilises iCloud FileProvider corruption when repo is under ~/Documents

Summary

On macOS with iCloud Drive's "Desktop & Documents Folders" sync enabled, the fileproviderd daemon silently reverts shell filesystem operations (mv, rm, git mv, etc.) a few seconds after they complete. The operations appear to succeed — no error, no prompt — and then the working tree is reconciled back to cloud state. Git's index and the filesystem diverge.

When a Claude Code session starts in such a tree, a user-level SessionStart snapshot hook (running git add -A && git commit -q -m "pre-session snapshot ...") can commit the corruption, making the iCloud-sabotaged tree the new HEAD. A subsequent session then sees the reverted state as authoritative.

This is a foot-gun worth defending against in Claude Code itself, even though the snapshot hook is user-authored — because the hook pattern is widely copied, the failure mode is silent, and the FileProvider behaviour is undocumented by Apple.

Environment

• macOS 15 (Darwin 25.4.0)
• Claude Code (VSCode extension), Opus 4.6 1M
• iCloud Drive "Desktop & Documents Folders" sync: enabled
• Affected repo path: ~/Documents/GitHub/<repo>/ (inside FileProvider mount via ~/Library/Mobile Documents/ symlink)

Reproduction

1. Enable "Desktop & Documents Folders" sync in System Settings → Apple ID → iCloud Drive → Options.
2. Clone a git repo into ~/Documents/some-repo.
3. In a Claude Code session: run git mv a.md subdir/a.md and git commit -m "reorg". Commit succeeds cleanly, git log shows the rename.
4. Wait 10–30 seconds. The file re-materialises at a.md (untracked) and subdir/a.md disappears. Git's index still records the move; disk state is reverted.
5. End the session. Start a new Claude Code session in the same repo.
6. Any SessionStart hook that runs git add -A && git commit (e.g. a "pre-session snapshot") fossilises the iCloud-reverted state as a new commit, inverting the previous legitimate commit.

Impact

• Silent data corruption: file reorganisation work is lost with no error or warning.
• Commit history contains misleading commits (a "snapshot" that inverts the immediately preceding legitimate commit).
• Recovery requires understanding both iCloud FileProvider behaviour and git reflog — non-trivial for users who aren't expecting either.
• In my case, the corruption also interrupted a cross-filesystem repo move (mv ~/Documents/GitHub/ecce ~/GitHub/ecce) that was throttled by iCloud sync, leading to a VSCode hang and a "missing Claude executable" error on session restart.

Technical background

iCloud Drive is implemented on macOS 10.15+ as a File Provider extension. Items live in one of three states: dataless (cloud placeholder), materialized, or transient. POSIX rename(2) / unlink(2) mutate the local replica, then fileproviderd asynchronously reconciles to cloud state. Finder drag-out works because it calls NSFileProviderManager with explicit intent; the shell does not, so the daemon has no signal that the change is user-directed and rolls it back.

Apple does not publicly document this behaviour. Community consensus (Apple Developer Forums, Stack Overflow) is "don't put git repos in iCloud-synced folders" but there is no authoritative Apple statement.

References:

• File Provider framework: https://developer.apple.com/documentation/fileprovider
• NSFileProviderManager: https://developer.apple.com/documentation/fileprovider/nsfileprovidermanager
• WWDC21 session 10182 "Host a file provider on macOS": https://developer.apple.com/videos/play/wwdc2021/10182/

Proposed fixes

Minimum: defensive check in shipped hook templates

Any hook template shipped or recommended by Claude Code that runs git add -A should early-exit on macOS if the working directory is inside a FileProvider mount:

if [[ "$(uname)" == "Darwin" ]] && mount | grep -q fileprovider; then
  pwd_real="$(cd "$PWD" && pwd -P)"
  if [[ "$pwd_real" == */Library/Mobile\ Documents/* ]]; then
    echo "claude-code: skipping snapshot — working dir is under iCloud FileProvider sync, which silently reverts shell filesystem ops" >&2
    exit 0
  fi
fi

Better: session-start warning

Surface a clear warning at session start when the working tree is under an iCloud FileProvider mount:

This working tree is under iCloud "Desktop & Documents Folders" sync. Shell filesystem operations (including git) may be silently reverted by the iCloud daemon. Consider moving the repo outside ~/Documents and ~/Desktop.

Best: documented caveat

Add a section to the Claude Code docs ("macOS: iCloud Drive interaction") that explains the failure mode and recommends canonical repo locations outside ~/Documents / ~/Desktop.

Related

Community reports of git corruption in iCloud-synced folders are widespread on Apple Developer Forums and Stack Overflow. Apple has no public statement acknowledging the shell-revert behaviour. The Claude-Code-specific angle here is the interaction with auto-commit hooks, which convert a recoverable iCloud-induced disk state into a permanent commit.