[DOCS] Sandbox docs omit `sandbox.allowAppleEvents` macOS opt-in setting

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/sandboxing

Section/Topic

Sandbox settings table and macOS OS-level enforcement / limitations sections.

Current Documentation

The settings page lists sandbox keys such as:

network.allowMachLookup | Additional XPC/Mach service names the sandbox may look up (macOS only). Supports a single trailing * for prefix matching. Needed for tools that communicate via XPC such as the iOS Simulator or Playwright.

The sandboxing guide explains filesystem isolation, network isolation, macOS sandbox profiles, limitations, and troubleshooting. It does not mention Apple Events or the sandbox.allowAppleEvents key.

What's Wrong or Missing?

Claude Code v2.1.181 adds a new setting:

Added sandbox.allowAppleEvents opt-in setting that lets sandboxed commands send Apple Events on macOS

This is currently discoverable only from the changelog. Users trying to run sandboxed commands that need Apple Events, such as automation using osascript or app-control workflows, do not have documentation for:

A. The exact setting name and shape

The settings table does not list sandbox.allowAppleEvents, so users cannot tell whether the value is boolean, managed-only, macOS-only, merged across scopes, or related to the existing network.allowMachLookup key.

B. The security trade-off

Apple Events are a sensitive macOS automation capability. The docs should explain what enabling the opt-in allows and when it is appropriate, similar to the warnings for weaker nested sandboxing and weaker network isolation.

C. The relationship to osascript / browser auth fixes

The same v2.1.181 release also fixes open, osascript, and browser-based auth flows on macOS by adding the Apple Events entitlement. The sandbox docs do not explain when users need the new sandbox setting versus when the entitlement fix is enough.

Suggested Improvement

Add sandbox.allowAppleEvents to the sandbox settings table, for example:

allowAppleEvents | (macOS only) Allow sandboxed commands to send Apple Events to other applications. Default: false. Enable only for workflows that need app automation, such as osascript, browser handoff, or terminal/app integration. This expands what sandboxed commands can control on the local machine. | true

Add a short macOS note to the sandboxing guide:

By default, sandboxed commands cannot send Apple Events. If a trusted workflow needs to automate another macOS app, set sandbox.allowAppleEvents: true. Keep it disabled for untrusted commands because Apple Events can control other applications.

If there are known interactions with network.allowMachLookup or excludedCommands, cross-link those from the note.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sandboxing | Sandbox configuration and macOS limitation sections | Primary page for sandbox behavior |
| https://code.claude.com/docs/en/settings | Sandbox settings table | Lists neighboring sandbox keys but omits allowAppleEvents |

Version: Claude Code v2.1.181 added sandbox.allowAppleEvents.