claude-code - 💡(How to fix) Fix [DOCS] Sandbox settings missing `sandbox.network.allowMachLookup` documentation for macOS [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

sandbox.network configuration keys for macOS sandboxing

Current Documentation

The settings reference currently enumerates these sandbox network keys, but does not mention sandbox.network.allowMachLookup:

| network.allowUnixSockets | Unix socket paths accessible in sandbox (for SSH agents, etc.) | network.allowAllUnixSockets | Allow all Unix socket connections in sandbox. Default: false | network.allowLocalBinding | Allow binding to localhost ports (macOS only). Default: false | network.allowedDomains | Array of domains to allow for outbound network traffic. Supports wildcards (e.g., *.example.com). | network.allowManagedDomainsOnly | (Managed settings only) Only allowedDomains and WebFetch(domain:...) allow rules from managed settings are respected. | network.httpProxyPort | HTTP proxy port used if you wish to bring your own proxy. | network.socksProxyPort | SOCKS5 proxy port used if you wish to bring your own proxy.

The Agent SDK TypeScript reference also lists the network config shape without this property:

type SandboxNetworkConfig = {
  allowedDomains?: string[];
  allowManagedDomainsOnly?: boolean;
  allowLocalBinding?: boolean;
  allowUnixSockets?: string[];
  allowAllUnixSockets?: boolean;
  httpProxyPort?: number;
  socksProxyPort?: number;
};

Changelog v2.1.97 adds a user-facing sandbox behavior entry:

Improved sandbox: sandbox.network.allowMachLookup now takes effect on macOS

What's Wrong or Missing?

Changelog v2.1.97 confirms that sandbox.network.allowMachLookup is a real sandbox setting with macOS-specific behavior, but the Claude Code docs do not currently document this key anywhere in the settings or Agent SDK sandbox configuration references.

That leaves users without the information they need to use the setting correctly:

• what value shape it accepts
• what macOS Mach services it is intended to allow
• whether it applies only to sandboxed Bash subprocesses
• what security tradeoffs or cautions apply

Suggested Improvement

Add sandbox.network.allowMachLookup to the sandbox network configuration documentation in the settings reference and Agent SDK references.

Suggested content outline:

1. Add the new key to the sandbox.network table in settings
2. Document its type, default, and macOS-only scope
3. Explain what kind of Mach lookup access it grants inside the sandbox
4. Add a short example showing where it belongs in the sandbox.network object
5. Add a security note similar to the existing allowUnixSockets / weaker-isolation warnings if this setting can broaden sandbox escape or data-exfiltration surface

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 6 pages affected

Source: Changelog v2.1.97

Exact changelog entry: Improved sandbox: sandbox.network.allowMachLookup now takes effect on macOS