claude-code - 💡(How to fix) Fix [DOCS] Surface plugin-subagent frontmatter limitations (hooks/mcpServers/permissionMode) in main reference, not just a buried Note [1 participants]

Summary

Plugin sub-agents silently ignore the hooks, mcpServers, and permissionMode frontmatter fields. This is documented — but only in a single <Note> box near the scope-priority table on the Sub-agents page. The supported-frontmatter reference table later on the same page lists all fields without any caveat, so a user reading that table to author or port a plugin agent gets no warning.

Where the gap is

The frontmatter reference table (the section users actually consult when copying examples) doesn't mark which fields are plugin-restricted. A plugin author who copies a working agent from ~/.claude/agents/ and drops it into <plugin>/agents/ sees no error — the fields just stop working silently.

Why it matters

hooks, mcpServers, and permissionMode are common, non-obvious-to-omit fields. Today's behavior:

• User-defined agents (~/.claude/agents/, .claude/agents/) — fields honored.
• Plugin agents (<plugin>/agents/) — fields silently ignored at load time.

The "for security reasons" rationale makes sense, but discoverability is the problem.

Suggested fix

One or more of:

1. Add a column or per-row footnote to the supported-frontmatter table marking hooks / mcpServers / permissionMode as plugin-restricted.
2. Move the <Note> to immediately above or inside the frontmatter table where it's harder to skip.
3. Emit a warning at agent-load time when a plugin agent declares one of these fields, instead of silently dropping them.

(3) is the most user-friendly long-term, but (1) or (2) is a low-cost docs win.

Adjacent prior art (not dupes)

• #17688 — Skill-scoped hooks in plugin SKILL.md don't fire (skill-side equivalent of this gap).
• #47898 — Agent tool not available at runtime for plugin-defined agent types despite tools: declaration.
• #52605 — --agent / agent setting docs omit session permissionMode behavior.

This issue is specifically about the docs surface area (and optionally the silent-drop behavior) for plugin-agent frontmatter.

Repro / how I noticed

Authoring an LOTR-themed orchestration plugin (mordor-forge). Several agent definitions use permissionMode: plan and hooks: for soft-nudge behavior. Worked locally as user agents; ported into the plugin tree, fields silently became no-ops. Found the <Note> only after specifically searching docs for "plugin subagents".