The remote or self-hosted runner is the program that starts Claude Code on a machine you host. It now accepts server-supplied subagent definitions in agent_files. A subagent is a helper agent that Claude Code can hand work to. The runner checks these definitions:
no more than 64 entries
each name matches ^[a-z][a-z0-9-]{0,63}$: it starts with a lowercase letter and uses only lowercase letters, digits and hyphens, up to 64 characters
each file's content is at most 1 MiB
no two entries share a name
The runner combines these with the server's agents argument. It writes the result to remote-agents.json, which only the file's owner can read or write (mode 0600), and starts Claude Code with the --agents flag pointing at that file. The system prompt, append-system-prompt and append-subagent-system-prompt values are also written to files and passed as --<key>-file. A system prompt is the standing instructions the model receives before your messages.
The runner also sorts out errors that happen when Claude Code fails to start, such as E2BIG (the arguments were too large). It records the length of the longest argument and the longest environment entry. It now drops environment entries that are malformed or that are variants of names the runner itself controls.
Why
Large agent definitions and prompts now travel in files, not on the command line. This avoids start-up failures when the command line gets too long. When start-up does fail, the records say more about why.
What the documentation says
--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
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
