[BUG] Claude refuses to write CLAUDE.md when it's a symlink

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?

As per the official documentation having CLAUDE.md as a symlink should be supported, however the internal Update an Write tools refuse to change it directly.

What Should Happen?

Allow writing to CLAUDE.md directly when it's a symlink of adjacent AGENTS.md or change advice away from using a symlink.

Error Messages/Logs

● Update(/tmp/symlink-repro/CLAUDE.md)
  ⎿  Error: Refusing to write through symlink: /tmp/symlink-repro/CLAUDE.md. Resolve the symlink and pass
     the real target path explicitly.
● Write(/tmp/symlink-repro/CLAUDE.md)
  ⎿  Error: Refusing to write through symlink: /tmp/symlink-repro/CLAUDE.md. Resolve the symlink and pass
     the real target path explicitly.

Steps to Reproduce

mkdir /tmp/symlink-repro && cd /tmp/symlink-repro
printf 'real content\n' > AGENTS.md
ln -s AGENTS.md CLAUDE.md

Then, in Claude Code:

1. Read CLAUDE.md — succeeds.
2. Edit CLAUDE.md (any change) — fails with:

Refusing to write through symlink: /tmp/symlink-repro/CLAUDE.md. Resolve the symlink and pass the real target path explicitly.

1. Write to CLAUDE.md — fails with the same message.
2. Read then Edit AGENTS.md (the real target) — succeeds, and the

symlink is left intact and reflects the change when read back through
CLAUDE.md.

Claude Model

Opus

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.1.168

Platform

AWS Bedrock

Operating System

Ubuntu/Debian Linux

Terminal/Shell

VS Code integrated terminal

Additional Information

_No response_