[DOCS] Plugins reference missing effort, maxTurns, and disallowedTools frontmatter for plugin-shipped agents

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/plugins-reference

Section/Topic

Plugin agent file format and frontmatter schema

Current Documentation

The plugins-reference page shows the plugin agent file format with only name and description in the YAML frontmatter example. The sub-agents page documents maxTurns and disallowedTools for user-created subagents, but the plugins-reference does not list these as supported fields for plugin-shipped agents. The effort field is entirely absent from all documentation.

What's Wrong or Missing?

Changelog v2.1.78 added effort, maxTurns, and disallowedTools frontmatter support for plugin-shipped agents. Plugin developers need to know:

A. effort field is undocumented everywhere

The effort frontmatter field does not appear on any documentation page. Its purpose, valid values, and behavior are unknown to users.

B. Plugin agent frontmatter schema is incomplete

The plugins-reference agent file format example only shows name and description. It should also list effort, maxTurns, and disallowedTools as supported frontmatter fields, with descriptions matching or referencing the sub-agents documentation.

Suggested Improvement

Update the plugin agent frontmatter example and field table in plugins-reference to include:

| Field | Description |
|-------|-------------|
| effort | Controls the model's reasoning effort level |
| maxTurns | Maximum number of agentic turns before the subagent stops |
| disallowedTools | Tools to deny, removed from inherited or specified list |

Add a cross-reference to the sub-agents page for detailed field semantics.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/plugins-reference | Plugin agent file format and frontmatter schema |
| https://code.claude.com/docs/en/sub-agents | Documents maxTurns/disallowedTools for user subagents but not for plugin agents |

Total scope: 2 pages affected

Source: Changelog v2.1.78

Added effort, maxTurns, and disallowedTools frontmatter support for plugin-shipped agents