What probably matters to youSection of the release
What
The --agents flag, which defines custom subagents (helper agents Claude can hand work to) when Claude Code starts, is now written --agents <json-or-file>. Until now it took only JSON typed straight onto the command line. If the value does not start with {, Claude Code now treats it as a path to a file and reads the definitions from that file.
Reading from a file only works with --print (-p), the mode that prints a reply and exits instead of opening an interactive session, or in another non-interactive run. In an interactive session, or with --bg, only inline JSON is accepted, and a file path stops Claude Code with this error: "--agents takes a JSON object, or a file path only with --print (-p)."
The file is checked as it is read. Each of these is an error:
the file is missing
the file is too large
the file changed while it was being read
the file has more than one hard link (more than one name pointing at the same data on disk)
When the definitions are invalid, the error message now names the file they came from.
Why
Long agent definitions are easier to keep in a file than to squeeze into one command-line argument, which helps scripts and automated runs. Interactive use is unchanged.
--agentsCreate custom subagentsmodified, high confidenceThe `--agents` flag accepts JSON with a `prompt` field plus these [frontmatter](#supported-frontmatter-fields) fields: `description`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `init…see the edit
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 sinceA small documentation edit on CLI reference touched a line naming --agents after this was published.| `--agents` | Define custom subagents dynamically via JSON. Accepts the [fields listed for CLI-defined subagents](/docs/en/sub-agents#choose-the-subagent-scope). With `--print`, the value can instead be the path to a JSON file holding the…cli-referencesee the edit
Confirmed sinceAnthropic's documentation has since written up --agents, on Deploy managed settings.| [`disableSideloadFlags`](/docs/en/settings-reference#disablesideloadflags) | Reject the `--plugin-dir`, `--plugin-url`, `--agents`, and `--mcp-config` flags at startup. In cloud sessions, Claude Code drops the MCP servers the server deli…managed-settingssee the edit
How sure we are
Two sources agreeTwo things we can check say the same as this entry.
Anthropic's documentation agrees--agents on Create custom subagents
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
