claude-code - 💡(How to fix) Fix [DOCS] Agent view docs omit macOS Privacy & Security identity for background agents

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Background agent macOS permissions and upgrade persistence

Current Documentation

The agent view docs explain that background sessions survive supervisor restarts and auto-updates:

Session state persists on disk through auto-updates and supervisor restarts.

They also explain supervisor restart behavior after the binary changes:

The supervisor watches the installed Claude Code binary on disk and restarts into the new version after the regular auto-updater replaces it.

Separate feature pages document macOS permissions for specific tools, for example computer use:

The first time Claude tries to use your computer, you'll see a prompt to grant two macOS permissions:

But the background agent docs do not explain how background agents appear in macOS Privacy & Security, or whether their permission grants persist across Claude Code upgrades.

What's Wrong or Missing?

Claude Code v2.1.153 changed macOS background agents so they appear as "Claude Code" in Privacy & Security and keep permission grants across upgrades.

The docs currently leave three practical gaps:

A. macOS identity is undocumented

Users looking in System Settings cannot know whether a background agent permission prompt or Privacy & Security entry should appear under their terminal app, an internal helper, or "Claude Code".

B. Upgrade persistence is undocumented

The agent view page says sessions persist through upgrades, but not that macOS Privacy & Security permission grants for background agents persist too.

C. Troubleshooting paths are split by feature

Computer use, channels, and voice dictation pages mention macOS permission panes for their own features, but agent view does not provide a background-agent-specific note.

Suggested Improvement

Add a macOS note to the The supervisor process section or the troubleshooting area:

On macOS, background agents appear as "Claude Code" in System Settings > Privacy & Security. Permission grants for background agents persist across Claude Code upgrades, so upgrading the binary should not require re-granting the same background-agent permissions. If a background session still reports a macOS permission error, check the relevant Privacy & Security pane for "Claude Code" and restart the session after granting access.

Cross-link this from feature pages that already discuss macOS Privacy & Security permissions when the behavior differs for background agents.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Version context: Claude Code v2.1.153 changed macOS background agents to appear as "Claude Code" in Privacy & Security and retain grants across upgrades.

Total scope: 1 primary page plus 2 optional cross-references.