Parallel agents corrupt Settings.json

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Bug: ~/.claude/settings.json gets corrupted during parallel agent (Task tool) execution

Description

The user-level ~/.claude/settings.json file gets corrupted when running multiple parallel agents via the Task tool. After corruption, Claude Code reports the file is corrupted and requires manual intervention to restore.

Steps to Reproduce

1. Start a Claude Code session with a project that uses the Task tool
2. Launch multiple parallel agents (e.g., 4-5 Task tool calls in a single message using subagent_type="general-purpose")
3. Let the agents run to completion — they typically involve heavy file reads/writes across the codebase
4. During or after execution, ~/.claude/settings.json is reported as corrupted

Expected Behavior

settings.json should remain valid JSON regardless of how many parallel agents are running. File writes to shared config files should be atomic or serialized to prevent race conditions.

Actual Behavior

The file contents become corrupted (malformed JSON), and Claude Code reports the corruption. The user must manually restore the file from a backup or recreate it.

Environment

• OS: Windows 11 Pro (10.0.26200)
• Shell: Git Bash
• Claude Code model: claude-opus-4-6

Likely Cause

Race condition — multiple parallel agent subprocesses attempt to read/write ~/.claude/settings.json concurrently (e.g., updating permission grants). Without file locking or atomic writes, concurrent writes produce malformed JSON.

Workaround

Keep a backup of settings.json and restore it after corruption:

# Create backup while file is good
cp ~/.claude/settings.json ~/.claude/settings.json.backup

# Restore after corruption
cp ~/.claude/settings.json.backup ~/.claude/settings.json

Suggested Fix

• Use atomic file writes (write to temp file, then rename) for settings.json
• Or serialize access with a file lock when multiple agents are running
• Or have each agent subprocess use a read-only copy of settings rather than the shared original

What Should Happen?

Bug: ~/.claude/settings.json gets corrupted during parallel agent (Task tool) execution

Description

The user-level ~/.claude/settings.json file gets corrupted when running multiple parallel agents via the Task tool. After corruption, Claude Code reports the file is corrupted and requires manual intervention to restore.

Steps to Reproduce

1. Start a Claude Code session with a project that uses the Task tool
2. Launch multiple parallel agents (e.g., 4-5 Task tool calls in a single message using subagent_type="general-purpose")
3. Let the agents run to completion — they typically involve heavy file reads/writes across the codebase
4. During or after execution, ~/.claude/settings.json is reported as corrupted

Expected Behavior

settings.json should remain valid JSON regardless of how many parallel agents are running. File writes to shared config files should be atomic or serialized to prevent race conditions.

Actual Behavior

The file contents become corrupted (malformed JSON), and Claude Code reports the corruption. The user must manually restore the file from a backup or recreate it.

Environment

• OS: Windows 11 Pro (10.0.26200)
• Shell: Git Bash
• Claude Code model: claude-opus-4-6

Likely Cause

Race condition — multiple parallel agent subprocesses attempt to read/write ~/.claude/settings.json concurrently (e.g., updating permission grants). Without file locking or atomic writes, concurrent writes produce malformed JSON.

Workaround

Keep a backup of settings.json and restore it after corruption:

# Create backup while file is good
cp ~/.claude/settings.json ~/.claude/settings.json.backup

# Restore after corruption
cp ~/.claude/settings.json.backup ~/.claude/settings.json

Suggested Fix

• Use atomic file writes (write to temp file, then rename) for settings.json
• Or serialize access with a file lock when multiple agents are running
• Or have each agent subprocess use a read-only copy of settings rather than the shared original

Error Messages/Logs

Steps to Reproduce

Bug: ~/.claude/settings.json gets corrupted during parallel agent (Task tool) execution

Description

The user-level ~/.claude/settings.json file gets corrupted when running multiple parallel agents via the Task tool. After corruption, Claude Code reports the file is corrupted and requires manual intervention to restore.

Steps to Reproduce

1. Start a Claude Code session with a project that uses the Task tool
2. Launch multiple parallel agents (e.g., 4-5 Task tool calls in a single message using subagent_type="general-purpose")
3. Let the agents run to completion — they typically involve heavy file reads/writes across the codebase
4. During or after execution, ~/.claude/settings.json is reported as corrupted

Expected Behavior

settings.json should remain valid JSON regardless of how many parallel agents are running. File writes to shared config files should be atomic or serialized to prevent race conditions.

Actual Behavior

The file contents become corrupted (malformed JSON), and Claude Code reports the corruption. The user must manually restore the file from a backup or recreate it.

Environment

• OS: Windows 11 Pro (10.0.26200)
• Shell: Git Bash
• Claude Code model: claude-opus-4-6

Likely Cause

Race condition — multiple parallel agent subprocesses attempt to read/write ~/.claude/settings.json concurrently (e.g., updating permission grants). Without file locking or atomic writes, concurrent writes produce malformed JSON.

Workaround

Keep a backup of settings.json and restore it after corruption:

# Create backup while file is good
cp ~/.claude/settings.json ~/.claude/settings.json.backup

# Restore after corruption
cp ~/.claude/settings.json.backup ~/.claude/settings.json

Suggested Fix

• Use atomic file writes (write to temp file, then rename) for settings.json
• Or serialize access with a file lock when multiple agents are running
• Or have each agent subprocess use a read-only copy of settings rather than the shared original

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.1.59

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_