--agents is an option you can give when starting Claude Code, and it can point at a JSON file. When it does, Claude Code now records both the path you gave and the file's real location after following any shortcuts (symlinks). Any attempt to edit that file is then treated like an edit to a protected settings file.
When Claude Code works out where a settings .json file lives, it now also follows symlinks, including for files that do not exist yet.
Why
Claude cannot quietly rewrite the file that defines your --agents configuration during a session, just as it cannot freely rewrite your settings. Following symlinks means a shortcut pointing at the file does not get around that protection.
How sure we are
One source agreesOne thing we can check says the same as this entry.
Anthropic's release notes agreeImproved --agents to accept the path to a JSON file (with -p) as well as inline JSON, and to allow an empty prompt
