[DOCS] clarify allowUnixSockets brokering across the sandbox netns

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

sandbox.network.allowUnixSockets configuration

Current Documentation

The sandboxing page introduces sandbox.network.allowUnixSockets as a list of Unix socket paths and notes that Linux uses bubblewrap with socat listed as a required package. The field name and the socat dependency together imply host↔sandbox socket brokering, but I couldn't find any text on the page (or elsewhere in the Claude Code docs) that describes the lifecycle — what triggers the forwarder, when it runs, what preconditions the socket must meet, or whether the user is expected to invoke socat themselves.

What's Wrong or Missing?

Assuming the intent is host↔sandbox brokering (which the socat dependency implies), the docs don't answer two questions that matter for anyone trying to use allowUnixSockets in practice:

1. What triggers the forwarder setup, and at what point in the session lifecycle does it happen?
2. What role does socat play — is a user-side socat invocation required, or does the harness invoke it internally? Does the socket need to exist at a specific moment relative to session start, have specific ownership/mode, etc.?

In practice, a pre-existing host-side listener on an allow-listed path is not reachable from inside the sandbox — so either I'm missing a step the docs don't mention, or the feature doesn't yet do what the name suggests. Reproduction:

Host setup (before launching the sandboxed session):

$ rm -f /tmp/claude/vigil-signing.sock
$ eval "$(ssh-agent -a /tmp/claude/vigil-signing.sock)"
Agent pid 2109779
$ ssh-add ~/.ssh/vigil-signing
Identity added: /home/grault/.ssh/vigil-signing (chris@vigil-signing)

Session settings:

"sandbox": {
  "network": {
    "allowUnixSockets": ["/tmp/claude/vigil-signing.sock"]
  }
}

SSH_AUTH_SOCK=/tmp/claude/vigil-signing.sock is exported into the session.

Inside the sandbox:

=== env ===
SSH_AUTH_SOCK=/tmp/claude/vigil-signing.sock
SSH_AGENT_PID=

=== ls -l $SSH_AUTH_SOCK ===
srw------- 1 grault grault 0 Apr 15 03:08 /tmp/claude/vigil-signing.sock

=== ss -xl | grep vigil-signing ===
(no matches; exit 1)

=== ssh-add -L ===
Error connecting to agent: Operation not permitted
(exit 2)

The socket node is visible with correct ownership and mode, but no listener is present in the sandbox netns and connect(2) is refused. Either a setup step is missing from the docs, or the forwarder isn't wired up for this session shape — and the current documentation doesn't give enough detail to tell which.

Environment: Linux, WSL2 kernel 6.6.87.2-microsoft-standard-WSL2; socat installed.

Suggested Improvement

Add a section under the sandboxing page covering allowUnixSockets that states:

1. Who runs the forwarder (harness or user), when in the session lifecycle, and against what preconditions (e.g., socket must exist at session start; specific ownership/permissions required).
2. socat's role — whether users ever need to invoke it themselves, or whether it's an internal harness dependency.
3. An end-to-end supported recipe for a common use case — e.g., connecting an in-sandbox ssh-add / git commit -S to a host-side ssh-agent listener.

Impact

Medium - Makes feature difficult to understand

Additional Context

Downstream context: we're trying to use this to enable signed git commits from sandboxed developer sessions. Without clear semantics, it's not possible to tell whether the current failure is a misconfiguration, an unsupported use case, or a regression — which leaves downstream configs unable to either rely on the feature or cleanly retire their attempts to use it.