--bg rejects --agents given as a file

Using --bg with --agents pointing at a file now fails; pass the agents as inline JSON instead

Use it nowTier: how much it should matter to you

2Useful: my rating, 1 to 5

1Signal: worth watching, 1 to 5

SessionsArea: what it touches

ImprovementsKind: in v2.1.281, 23 Sep 26

What probably matters to youSection of the release

What

--bg starts a session as a background agent. --agents defines custom subagents (helper agents Claude can hand work to), either as JSON typed directly on the command line or as a file. If you combine --bg with the file form, Claude Code now stops with this error:

"--bg can't read --agents from a file: a background session is interactive, and the file form works only with --print. Pass the agents as inline JSON."

Why

The file form of --agents only works with --print, the non-interactive mode. If you start background sessions with custom subagents, write them out as inline JSON.

Read from

Names in the bundle--agents

What the documentation says

--agents Create custom subagents modified, high confidence The `--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 since 26 Sep 2026 A 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-reference see the edit

Confirmed since 25 Sep 2026 Anthropic'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-settings see 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

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

Use it now39
You'll notice261
Nothing to try yet26
Under the hood217

Either side of it

v2.1.280Older
v2.1.282Newer

Open the release →

Names in this entry

cli--bg
Start the session as a background agent and return immediately. Prints the session ID and management commands. Combine with --exec to run a shell command as a background job instead of a Claude session, or with --agent to run a specific subagent. Checks workspace trust for the directory before it starts. Can't be combined with -p/--print; see the error reference
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
cli--print
Print response without interactive mode (see Agent SDK documentation for programmatic usage details)

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?