macOS: TCC-protected folders unreadable — no consent prompt, no remediation in the error, and Read reports EISDIR instead of EPERM

Summary

On macOS, Claude Code cannot read anything under TCC-protected folders
(~/Documents, ~/Desktop, ~/Downloads), no consent prompt is ever
shown, and the failure surfaces as a bare Operation not permitted with no
indication of the cause or the fix. Different tools report the same underlying
denial with different errors, one of which actively misleads diagnosis.

The permission behaviour itself is macOS working as designed. The bug is that
there is no path through it from inside the product, and nothing tells you what
is wrong.

Environment

• Claude Code 2.1.247, launched from Claude Desktop (/Applications/Claude.app)
• macOS 26.4 (Darwin 25.4.0), arm64

Process chain, from ps:

/Applications/Claude.app
  └─ Contents/Helpers/disclaimer
      └─ .../claude-code/2.1.247/claude.app/Contents/MacOS/claude
          └─ /bin/bash          ← where Bash tool commands run

Reproduction

1. Launch Claude Code from Claude Desktop on macOS.
2. Ask it to read any file under ~/Documents.

$ ls ~/Documents
ls: /Users/alex/Documents: Operation not permitted

$ ls ~/Documents/__nonexistent__
ls: /Users/alex/Documents/__nonexistent__: No such file or directory   # control

$ ls ~/workspace
(readable)

Three distinct defects

1. The TCC consent prompt never fires. Normally the first access attempt
makes macOS show *"Claude would like to access files in your Documents
folder"*. That never appears, so there is no in-product way to grant access —
the user must know to go to System Settings and grant Full Disk Access
manually. Most users will not know that, and nothing suggests it.

2. The error carries no cause and no remediation. Operation not permitted
is indistinguishable, to a user, from a missing file, a typo, or a broken tool.
It should be detected and surfaced as something like: *"macOS is blocking access
to ~/Documents. Grant Full Disk Access to /Applications/Claude.app in System
Settings → Privacy & Security, then restart Claude."*

3. Tools disagree about the error, and one of them misleads. For the same
inaccessible path:

• Bash → Operation not permitted (EPERM) — correct
• Read on a directory → EISDIR: illegal operation on a directory — **wrong

cause**, the permission check never surfaces

• Read on a file inside it → EPERM: operation not permitted — correct

The EISDIR on a directory strongly implies the path is reachable and the
problem is that it's a directory. It is not. During this session that error sent
me down a false path, believing one tool had access when none did.

Why this matters more than it looks

~/Documents is where a large share of non-code work lives — Obsidian vaults,
notes, research, spreadsheets. The current behaviour means Claude Code can read
an entire source tree in ~/workspace while being unable to read a single
markdown file two directories away, with no explanation and no way to fix it
from inside the product. The distinction is not about sensitivity; it is purely
which parent folder the file happens to sit in.

Suggested fixes, in priority order

1. Detect EPERM on known TCC-protected paths and print the specific

remediation, naming /Applications/Claude.app as the bundle to grant (not
the nested claude-code helper, and not Terminal — both are easy to get
wrong, and granting the wrong one changes nothing).

1. Trigger the macOS consent prompt on first access so the normal grant flow

works.

1. Fix Read so a permission denial reports as a permission denial rather than

EISDIR.