[DOCS] Sandboxing docs do not explain that hosts allowed via the network prompt are remembered only for the rest of the session

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

• "Run a Bash command" step in the Quickstart (around the first-time approval description)
• "Network isolation" bullet about domain restrictions
• "Troubleshooting" entry about host-not-allowed errors

Current Documentation

In the Quickstart, the "Run a Bash command" step currently says:

Ask Claude to run a command, such as a build or a test suite. By default, commands inside the sandbox can write only to the working directory and the session temp directory. The first time a command needs a new network domain, Claude Code prompts for approval.

The "Network isolation" section currently says:

* Domain restrictions: no domains are pre-allowed. The first time a command needs a new domain, Claude Code prompts for approval. Pre-allow domains with allowedDomains to avoid the prompt.

The "Troubleshooting" section currently says:

* Commands fail with a host-not-allowed error: many CLI tools need to reach specific hosts. Granting permission when prompted adds the host to your allowed list so the tool runs inside the sandbox in future.

What's Wrong or Missing?

Changelog v2.1.191 says:

Improved sandbox network permission dialog: hosts you allow with Yes are now remembered for the rest of the session instead of re-prompting on every connection

The current docs do not document the scope of the "allow" decision in the prompt at all:

A. "Allowed list" is never defined

The troubleshooting entry says granting permission "adds the host to your allowed list so the tool runs inside the sandbox in future," but the docs never define what that list is, how long it persists, where it lives, or how to inspect or clear it. Readers cannot tell from this prose whether "in future" means the rest of the current session or every future session.

B. The contrast with allowedDomains is invisible

allowedDomains in settings is the persistent, file-backed list. The prompt-time "Yes" is a session-scoped allowlist. The docs never draw that line, so users have no way to know that:

• A "Yes" in the dialog avoids re-prompts for the rest of the current session only.
• Once the session ends, the host returns to "needs approval" status.
• To persist the decision across sessions, they have to add the host to sandbox.network.allowedDomains (or a WebFetch(domain:...) rule).

C. The Quickstart and Network isolation bullets omit the dialog behavior entirely

"The first time a command needs a new network domain, Claude Code prompts for approval" describes only the trigger; it says nothing about what answering "Yes" does. That omission only became important once v2.1.191 changed the answer from "per-connection" to "per-session" — without the explicit scope, users cannot tell whether the prompt will reappear on the next connection in the same session.

Suggested Improvement

Update the Quickstart, Network isolation, and Troubleshooting sections to call out the session-scoped memory introduced in v2.1.191. Minimum fix, before/after style:

Before (Quickstart, "Run a Bash command" step):

The first time a command needs a new network domain, Claude Code prompts for approval.

After:

The first time a command needs a new network domain, Claude Code prompts for approval. Hosts you allow with Yes are remembered for the rest of the session, so subsequent connections to the same host within this session do not re-prompt. To allow the host permanently, add it to sandbox.network.allowedDomains in your settings.

Before (Network isolation bullet):

* Domain restrictions: no domains are pre-allowed. The first time a command needs a new domain, Claude Code prompts for approval. Pre-allow domains with allowedDomains to avoid the prompt.

After:

* Domain restrictions: no domains are pre-allowed. The first time a command needs a new domain, Claude Code prompts for approval. Hosts you allow with Yes are remembered for the rest of the session; to allow the host across sessions, add it to allowedDomains in settings or use a WebFetch(domain:...) rule.

Before (Troubleshooting entry):

* Commands fail with a host-not-allowed error: many CLI tools need to reach specific hosts. Granting permission when prompted adds the host to your allowed list so the tool runs inside the sandbox in future.

After:

* Commands fail with a host-not-allowed error: many CLI tools need to reach specific hosts. Selecting Yes in the prompt allows the host for the rest of the current session, so subsequent connections do not re-prompt. To allow the host across sessions, add it to sandbox.network.allowedDomains in your settings (or a WebFetch(domain:...) rule).

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Section | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sandboxing | Quickstart, "Run a Bash command" step | "The first time a command needs a new network domain, Claude Code prompts for approval." — no mention of session-scoped allow |
| https://code.claude.com/docs/en/sandboxing | "Network isolation" | Domain restrictions bullet omits session scope and allowedDomains contrast |
| https://code.claude.com/docs/en/sandboxing | "Troubleshooting" | "host-not-allowed error" entry uses ambiguous "your allowed list" / "in future" wording |

Total scope: 1 page, 3 sections affected.

Version note: The dialog behavior changed in v2.1.191 to remember "Yes" answers for the rest of the session; pre-v2.1.191 builds re-prompted on every connection to a non-allowed host. The docs were not updated to match.