Repository navigation
Document concurrent config-write safety under parallel workers (re: anthropics/claude-code#29217) #5
Description
Why this matters for this template
The whole point of this template is fanning out to parallel worktree-isolated workers. Upstream anthropics/claude-code#29217 reports that ~/.claude.json (global config) can be corrupted by non-atomic concurrent writes from multiple processes/subagents (forensics there show many distinct userID hashes writing the same file). That's exactly the access pattern this template encourages, so adopters deserve a clear note on the risk and mitigations.
What I measured (so the doc is grounded, not alarmist)
Probed on Claude Code v2.1.153, Linux/WSL2:
- 6 parallel subagents × 8 tool calls + 1 worktree-isolated subagent + the main session (~50 tool calls in a 3–8s window).
- Result:
~/.claude.jsonstayed valid JSON, grew normally, 0.corrupted.*files, backups healthy. A hard WSL crash mid-write also left it valid. - Conclusion: #29217 did not reproduce on v2.1.153/WSL2 (it was reported on v2.1.59–62,
platform:windows, and is closed-stale). So on current versions it appears safe at modest concurrency — but it's version/-platform dependent and not something the template can fix.
Same probe also clarified the worktree/settings story (useful to document):
- Worktrees are created at
<repo>/.claude/worktrees/agent-<id>on their own branch and auto-removed on completion. - Each worktree gets its own checked-out
.claude/settings.json, so permission-grant writes are isolated per worker (no cross-worker contention on that file). - Subagents auto-approve and persist non-allowlisted commands into that worktree-local copy (observed
uname -asucceed; allow count grew mid-run) — discarded with the worktree. - The harness owns
settings.jsonat runtime: it rewrote the main working-tree copy to its own session list (observed 59→36 entries). The committed file is the source of truth.
Suggested doc additions (e.g. in ARCHITECTURE.md "Limits" or a new note)
- Link #29217; state config-file corruption under heavy concurrency is an upstream Claude Code concern the template can only document + mitigate, not fix.
- Mitigations: keep
max_parallel_workersmodest (2–3, already advised); don't run other CC sessions / the Desktop app from the same home dir during a run; keep Claude Code updated (the bug appears not to reproduce on recent versions). - Residual risk to call out: because the harness mutates the working-tree
settings.jsonmid-run, an implementer doinggit add -Acould stage a grant-driftedsettings.jsoninto its PR. Mitigation: the pre-approved allow-list (separate PR) minimizes added grants; and/or add an implementer instruction to never stage.claude/settings*.json, or a pre-commit guard.
Found while using the template; full probe notes in the project's TEMPLATE_FEEDBACK log.
Activity
robercano commentedon Jul 1, 2026
🤖 Proposed implementation plan
Size: S (docs + one implementer guardrail) · Document + mitigate; the underlying bug is upstream and can't be fixed here.
Goal
Tell adopters honestly where concurrent config writes can bite under parallel workers, and close the one residual risk this template actually controls: a worker staging a harness-mutated
settings.jsoninto its PR.Files to change
docs/ARCHITECTURE.md— extend the existing "Limits to respect" section with a short "Concurrent config writes" subsection..claude/agents/implementer.md— add one explicit "never stage.claude/settings*.json" rule to the workflow..claude/scripts/no-stage-settings.sh+ aPreToolUse/commit note — a tiny guard that fails if.claude/settings*.jsonis staged. Propose but keep behind a decision (see open question).Concrete content
ARCHITECTURE.md subsection — grounded, not alarmist (mirrors the probe already logged in the issue):
anthropics/claude-code#29217; state plainly this is an upstream Claude Code concern (non-atomic concurrent writes to~/.claude.json) that the template can document + mitigate, not fix.max_parallel_workersat 2–3 (already advised atgates.json:45and here in Limits); don't run other CC sessions / the Desktop app from the same home dir during a run; keep Claude Code updated.Residual risk this template owns (the actionable part): the harness rewrites the working-tree
.claude/settings.jsonmid-run with its own session grant list (thesettings.json_READMEalready documents this and thegit update-index --cacheinforecipe to commit a clean copy). A worker doinggit add -Acould therefore stage a grant-driftedsettings.jsoninto its PR.implementer.md— "Nevergit add.claude/settings.json/settings.local.json; ifgit statusshows it modified,git restore --stagedit. The committed copy is source of truth."Acceptance
markdownlint docs/clean.shellcheck .claude/scripts/no-stage-settings.shclean and it exits non-zero only when asettings*.jsonis staged.Open question for you
Do you want just the doc + implementer rule (zero runtime risk), or also the pre-commit guard script? I lean doc + rule first; the guard can follow if drift is ever observed.
Cross-refs
Relates to the settings-ownership note already in
.claude/settings.json_READMEand to #9 (worktree-local settings isolation).docs(architecture): align max_parallel_workers guidance (#5 review)
docs(architecture): document concurrent config-write safety (#5)
Merge pull request #27 from robercano/feat/issue-5-concurrency-doc