claude-code - 💡(How to fix) Fix [DOCS] Background-session docs omit macOS Full Disk Access behavior for protected home folders

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/agent-view

Section/Topic

Settings, plugins, and MCP servers, How background sessions are hosted, and macOS access to ~/Documents, ~/Desktop, and ~/Downloads

Current Documentation

The docs currently say:

Agent view accepts the same configuration flags as claude for loading settings, plugins, MCP servers, and additional directories. Each flag applies to agent view itself and is passed through to every session you dispatch from it, so a plugin or MCP server you load this way is available in those sessions too.

--add-dir <path> ... Grant file access to an additional directory

The same page also says:

Each background session is its own Claude Code process, managed by the supervisor rather than tied to your terminal.

The permissions docs say:

Files in additional directories follow the same permission rules as the original working directory: they become readable without prompts, and file editing permissions follow the current permission mode.

What's Wrong or Missing?

Changelog v2.1.143 says:

Fixed background-job sessions on macOS getting "Operation not permitted" errors when reading files under ~/Documents, ~/Desktop, or ~/Downloads, even with Full Disk Access granted.

The current docs explain Claude Code's own file-access rules for background sessions and additional directories, but they do not document the macOS privacy layer that still applies to protected home folders.

That leaves three missing pieces:

A. macOS-protected folders are not called out

The docs never say that ~/Documents, ~/Desktop, and ~/Downloads are gated by macOS privacy controls in addition to Claude Code permission rules.

B. The background-session implication is undocumented

agent-view explains that background sessions run as separate Claude Code processes, but it does not connect that fact to protected-folder access on macOS. A reader cannot tell whether --add-dir ~/Documents or reading a file on ~/Desktop from a detached session should work the same way as an attached interactive session.

C. The post-fix behavior is not described

The v2.1.143 fix makes this a user-visible behavior guarantee: when the launching app has Full Disk Access, background sessions can now read those protected folders correctly. That guarantee is not reflected anywhere in the background-session or permissions docs.

Suggested Improvement

Add a short macOS-specific note to agent-view.md, and cross-reference it from permissions.md near the --add-dir / additionalDirectories guidance.

Suggested wording:

On macOS, ~/Documents, ~/Desktop, and ~/Downloads are protected by system privacy controls. Granting Claude Code file access with --add-dir, /add-dir, or additionalDirectories does not bypass that OS check. Background sessions run as separate Claude Code processes and can read those folders only when the launching app (for example Terminal or Claude Desktop) has Full Disk Access. As of v2.1.143, background sessions honor that access correctly.

This would make it clear that Claude's own permission model and macOS privacy permissions are separate, and that the protected-folder behavior applies to background sessions specifically.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

Source: Changelog v2.1.143

Changelog entry: Fixed background-job sessions on macOS getting "Operation not permitted" errors when reading files under ~/Documents, ~/Desktop, or ~/Downloads, even with Full Disk Access granted.