Docs: sandbox settings reload live mid-session but are omitted from "When edits take effect"

Summary

The settings docs have a "When edits take effect" section listing which keys
reload in a running session. sandbox.* is absent from it — neither in the
reload list nor in the restart-required list. It turns out to reload live, the
same as the keys that are listed, so this is a documentation gap rather than a
bug.

The current text reads:

Claude Code watches your settings files and reloads them when they change, so edits to most keys apply to the running session without a restart. This includes permissions, hooks, and credential helpers like apiKeyHelper. The reload covers user, project, local, and managed settings, and the ConfigChange hook fires for each detected change. A few keys are read once at session start and apply on the next restart instead: - model … - outputStyle …

sandbox appears in neither list. "Most keys" implies it reloads, but a reader
weighing whether a sandbox change needs a restart has no statement to rely on —
and the cost of guessing wrong is high, because a stale-config hypothesis is
indistinguishable from an insufficient-grant hypothesis without a controlled
test.

What I measured

Claude Code 2.1.238, macOS 26.6.1.

| step | action | result |
| --- | --- | --- |
| before | echo probe > $HOME/livecfg-probe.txt | refused — operation not permitted, rc 1 |
| edit | append /Users/<you>/livecfg-probe.txt to sandbox.filesystem.allowWrite in ~/.claude/settings.json | — |
| after | identical command, same session, no restart | rc 0, file written |
| revert | remove the entry again | — |
| after revert | identical command, same session | refused again, rc 1 |

It reloads in both directions, so it is a genuine live reload and not an
additions-only quirk.

Tilde expansion also works and is likewise undocumented. An entry spelled
~/.cache/go-build in the settings file arrives in the session's effective
config as /Users/<you>/.cache/go-build, and a write there succeeds. Whether
~ expands inside an allowlist entry is a natural question when writing one,
and the docs do not answer it.

Suggested change

Two sentences in the "When edits take effect" section:

1. Add sandbox to the list of keys covered by the watch-and-reload behaviour,

alongside permissions and hooks.

1. State that ~ in a filesystem allowlist entry is expanded to the user's home

directory when the config is loaded.

Why it is worth the two sentences

The omission cost real debugging time. Someone testing whether a sandbox grant
was sufficient could not tell "the config never applied" from "the config
applied but the grant is too narrow", because the docs left the first
possibility open. Knowing sandbox reloads live collapses that to one
hypothesis and makes the test conclusive. Anyone reasoning about a sandbox
setting mid-session hits the same fork.