anthropics / anthropics/claude-code
Docs: sandbox settings reload live mid-session but are omitted from "When edits take effect"
- Lenguaje dominante
- Python
- Estrellas
- 145k
- Forks
- 23.1k
- Métricas de merge de PR
- Métricas de PR pendientes
Descripción
## 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//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//.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`.
2. 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.
Guía de contribución
No hay ninguna guía de contribución indexada para este repositorio
Línea de trabajo
Start in the documentation's "When edits take effect" section and compare the current reload and restart-required lists with the issue text. Add `sandbox` to the live-reload examples and document `~` expansion in filesystem allowlist entries; the section should clearly answer both questions without implying a restart is needed.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Área
- documentation
- Tipo de issue
- Documentación
- Dificultad
- 1/5
- Tiempo estimado
- Menos de una hora
- Estado de actividad
- Activo
- Claridad
- Bien especificado
- Aptitud para principiantes
- 78/100