#### Plugin agent frontmatter #### Limit a field to fixed options
The whole hunk
from line 61, old and new numbered
/
lines
from line 61
6161Detailed system prompt for the agent describing its role, expertise, and behavior.
6262```
6363
64Plugin agents support `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, [`omitClaudeMd`](/docs/en/sub-agents#supported-frontmatter-fields), and `isolation` frontmatter fields. The only valid `isolation` value is `"worktree"`.
64#### Plugin agent frontmatter
6565
66For security reasons, plugin-shipped agents don't support `hooks`, `mcpServers`, or `permissionMode`.
66A plugin agent file uses the same [frontmatter fields as a subagent file](/docs/en/sub-agents#supported-frontmatter-fields), except that Claude Code honors only some of them when the agent comes from a plugin:
6767
68* **Supported**: `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, `omitClaudeMd`, `isolation`, `color`, and `experimental`. The only valid `isolation` value is `"worktree"`.
69* **Not supported, for security reasons**: `hooks`, `mcpServers`, and `permissionMode`. Claude Code ignores these when loading an agent from a plugin. To use them, copy the agent file into `.claude/agents/` or `~/.claude/agents/`.
70* **Not supported**: `initialPrompt`.
71
6872You can put plugin agent files in subfolders of `agents/`. Claude Code [loads them recursively](/docs/en/sub-agents#choose-the-subagent-scope) and joins the plugin name, each subfolder name, and the file name with colons to form the agent's scoped name. For example, `agents/review/security.md` in a plugin named `my-plugin` loads as `my-plugin:review:security`. Two settings change that name:
6973
7074* Frontmatter `name`: it replaces only the file name, so `name: audit` in `agents/review/security.md` loads as `my-plugin:review:audit`
from line 606
602606
603607Keys must be valid identifiers. Each option supports these fields:
604608
605| Field | Required | Description |
606| :------------ | :------- | :-------------------------------------------------------------------------------------------------------------------------------- |
607| `type` | Yes | One of `string`, `number`, `boolean`, `directory`, or `file` |
608| `title` | Yes | Label shown in the configuration dialog |
609| `description` | Yes | Help text shown beneath the field |
610| `sensitive` | No | If `true`, masks input and stores the value in secure storage instead of `settings.json` |
611| `required` | No | If `true`, validation fails when the field is empty |
612| `default` | No | Value used when the user provides nothing |
613| `options` | No | For `string` type, the values the field accepts, shown in `/config` as a picker over them. Requires Claude Code v2.1.271 or later |
614| `multiple` | No | For `string` type, allow an array of strings |
615| `min` / `max` | No | Bounds for `number` type |
609| Field | Required | Description |
610| :------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
611| `type` | Yes | One of `string`, `number`, `boolean`, `directory`, or `file` |
612| `title` | Yes | Label shown in the configuration dialog |
613| `description` | Yes | Help text shown beneath the field |
614| `sensitive` | No | If `true`, masks input and stores the value in secure storage instead of `settings.json` |
615| `required` | No | If `true`, validation fails when the field is empty |
616| `default` | No | Value used when the user provides nothing |
617| `options` | No | For `string` type, the values the field accepts, shown in `/config` as a picker over them. See [Limit a field to fixed options](#limit-a-field-to-fixed-options). Requires Claude Code v2.1.271 or later |
618| `multiple` | No | For `string` type, allow an array of strings |
619| `min` / `max` | No | Bounds for `number` type |
616620
617621Except `sensitive` fields and `multiple` lists, each field of each enabled plugin also appears as a row in the `/config` panel. The rows require Claude Code v2.1.269 or later.
618622
from line 645
641645When more than one source sets the same key, managed settings take precedence, then `--settings`, then user settings. The only source you can remove from this list is user settings: pass [`--setting-sources`](/docs/en/cli-reference#cli-flags) without `user` and Claude Code skips them. Managed settings and `--settings` stay whatever you pass. The SDK's [`settingSources`](/docs/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) option sets the same list.
642646
643647Entries in a project's `.claude/settings.json` or `.claude/settings.local.json` are ignored. Both files live in the workspace, so a cloned repository could supply values there, and those values would flow into plugin hook commands, MCP server configs, LSP commands, and monitor commands. Before v2.1.207, these entries were read. The restriction is specific to `pluginConfigs`: [`enabledPlugins`](/docs/en/settings-reference#enabledplugins) still honors project and local settings.
648
649#### Limit a field to fixed options
650
651Set `options` on a `userConfig` field to make users pick its value from a fixed list.
652
653To limit a `tone` field to three options, list them in `options` and set `default` to one of them:
654
655```json theme={null}
656{
657 "userConfig": {
658 "tone": {
659 "type": "string",
660 "title": "Tone",
661 "description": "Voice for generated replies",
662 "options": ["neutral", "warm", "formal"],
663 "default": "neutral"
664 }
665 }
666}
667```
668
669If you declare `options` on any field, users on Claude Code versions before v2.1.271 can't load the plugin.
670
671When you set `options` on a field, follow these rules:
672
673* Set `type` to `string`
674* Don't set `multiple` or `sensitive` to `true`
675* Set `default` to one of the options
676* If you leave `default` unset, set `required` to `true`
677* List at least one option, each 1 to 64 characters long
678* Don't start or end an option with a space
679* Don't use control characters, invisible characters, characters that change text direction, or spaces other than a regular space in an option
680* Don't list the same option twice, even in a different letter case
681
682If you break any of these rules, the plugin fails to load. Run `claude plugin validate` to see which field breaks which rule.
644683
645684### Channels
646685