A JSON file passed to --agents is now protected like a settings…

A JSON file passed to --agents is now protected like a settings file

A JSON file passed to --agents is now protected from edits the same way Claude Code's settings files are

You'll noticeTier: how much it should matter to you

1Useful: my rating, 1 to 5

1Signal: worth watching, 1 to 5

PermissionsArea: what it touches

ImprovementsKind: in v2.1.281, 23 Sep 26

ImprovementsSection of the release

What

--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.

Read from

Names in the bundle--agents

Since it was published

The entry above is what we published on the day. These lines were added later, as Anthropic's own pages caught up, and they sit beside the original rather than replacing it.

Added since 29 Sep 2026 A small documentation edit on Deploy managed settings touched a line naming --agents after this was published. | [`disableSideloadFlags`](/docs/en/settings-reference#disablesideloadflags) | Reject the `--plugin-dir`, `--plugin-url`, `--agents`, and `--mcp-config` flags at startup. In cloud sessions, Claude Code instead starts the session and drops … managed-settings see the edit

Confirmed since 29 Sep 2026 Anthropic's documentation has since written up --agents, on Error reference. The value you passed to `--agents` is invalid, so `claude` exits with code 1 instead of starting the session. When you pass `--safe-mode` or set [`CLAUDE_CODE_SAFE_MODE`](/docs/en/env-vars#variables), Claude Code ignores `--agents` entirel… errors see the edit

How sure we are

Two sources agreeTwo things we can check say the same as this entry.

Anthropic's documentation agreesAnthropic's documentation has since written up --agents, on Error reference.

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

See this entry in the whole of v2.1.281 →

The build it came inv2.1.281

23 Sep 2026 · 1,065 entries, this one is #483.

Use it now72
You'll notice488
Nothing to try yet55
Under the hood450

Either side of it

v2.1.280Older
v2.1.282Newer

Open the release →

Names in this entry

cli--agents
Define custom subagents dynamically via JSON. Accepts the fields listed for CLI-defined subagents. With --print, the value can instead be the path to a JSON file holding the object; the file form requires Claude Code v2.1.281 or later. Claude Code validates the value at startup and exits on an invalid one; see Invalid --agents configuration for the message and for the flags and environment variable that skip the validation. Validation requires Claude Code v2.1.242 or later

Anthropic's note

Upstream's own release notes for v2.1.281 name something this entry names, so the two are probably about the same change. Probably: the pairing is made on a shared name rather than on the words around it.

Improved --agents to accept the path to a JSON file (with -p) as well as inline JSON, and to allow an empty prompt

Is this right?