A LaunchAgent gets `Operation not permitted` for `~/Documents` while Terminal works

The same zsh script could list ~/Documents when I ran it in Terminal. Started as a LaunchAgent, it failed with: ls: /Users/administrator/Documents: Operation not permitted The LaunchAgent had the same user ID, the same $HOME , and the same script. That combination makes this look like a Unix permission problem. In this test it was not. The useful discriminator was the launch context: access succeeded from Terminal, failed from launchd , and still succeeded for a path outside the protected folder. I reproduced this on macOS 15.6.1 (Darwin 24.6.0) with a LaunchAgent in gui/501 . The probe was removed after the test. Why chmod is the wrong first check The obvious suspects were file ownership, a wrong home directory, or a job running as another user. The probe printed those facts before touching the files: #!/bin/zsh print -- "user= $( id -un ) uid= $( id -u ) " print -- "home= $HOME pwd= $PWD " /bin/ls " $HOME /Documents" 2>&1 | /usr/bin/head -5 /bin/cat " $HOME /Documents/vinh/working/CLAUDE.md" 2>&1 | /usr/bin/head -1 # Negative control: outside Documents /bin/ls " $HOME /.pf004" 2>&1 | /usr/bin/head -5 The two runs produced this difference: Check Terminal LaunchAgent in gui/501 User / uid administrator / 501 administrator / 501 $HOME /Users/administrator /Users/administrator ls ~/Documents Listed entries Operation not permitted cat inside ~/Documents Read the file Operation not permitted ls ~/.pf004 Listed entries Listed entries The working directory differed, but the script used absolute paths under $HOME , so PWD=/ did not explain the denial. The negative control mattered more: the LaunchAgent could read another directory owned by the same user. Changing ownership or mode bits would not explain why only the launch context changed the result. The owning layer is the privacy context On this machine, the access decision was attached to how the process was launched, not just to uid 501. Terminal had a privacy context that allowed access to the user's Documents folder.