anthropics / anthropics/claude-code

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

Abierto Apto para principiantes
#88,708 0 comentarios 0 reacciones 0 asignados Ver en GitHub
area:sandbox documentation enhancement
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

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.