Claude plugin agents capability rows lag the current sub-agents contract (color/initialPrompt/experimental.cacheTtl; permissionMode/mcpServers/hooks ignored for plugin subagents; anchored plugin-scoped matchers)

[ScriptedAlchemy]

Context

The Claude adapter emits no agents/ component (#100 stage-2 G5 gate, PR #220, #107 revision 3), and packages/agent-bundle/src/adapters/capabilities/claude-2.1.250.json → plugin.agents records the deferred frontmatter contract as 15 unavailable rows: background, component, description, disallowedTools, effort, hooks, isolationWorktree, maxTurns, mcpServers, memory, model, name, permissionMode, skills, tools.

Auditing those rows against the uploaded sub-agents reference shows the contract has moved. Whoever re-admits the component (or refreshes the capability evidence at the next re-pin) needs the following; nothing here is a runtime bug today.

Drift against sub-agents-3.md

Configure subagents › Write subagent files › Supported frontmatter fields (L289–322):

• New fields with no capability row: color (red|blue|green|yellow|purple|orange|pink|cyan), initialPrompt (main-session agents via --agent), experimental.cacheTtl (5m/1h, ≥2.1.248, read only from subagent files).
• Ignored for plugin subagents: permissionMode, mcpServers, and hooks are each documented as "Ignored for plugin subagents". The three rows currently describe them as deferred authored fields; when re-admitted they should be lowered as unsupported on Claude plugins (a diagnostic), not emitted.
• name constraints: lowercase letters and hyphens; must not contain : (reserved for plugin-scoped plugin:agent identifiers) — a file with such a name is not loaded (≥2.1.218). Hooks receive this value as agent_type.
• tools: "To preload Skills into context, use the skills field rather than listing Skill here"; a list where no entry resolves to a tool fails to launch.
• model: adds fable and full model IDs; inherit is explicit.
• maxTurns: output marked partial and resumable (≥2.1.246).

Subagent files Claude Code skips (L324–341): plugin subagents with no name or unparseable frontmatter still load under their filename (unlike project/user agents, which are skipped). claude plugin validate <dir>/agents is the pre-session check (≥2.1.233).

Envelopes and matchers — verified OK

• SubagentStart input (hooks-2.md → SubagentStart › SubagentStart input, L2295–2307): agent_id, agent_type. SubagentStop input (SubagentStop input, L2329–2350): stop_hook_active, agent_id, agent_type, agent_transcript_path, last_assistant_message, plus background_tasks/session_crons. packages/agent-bundle/src/events/projection.ts:347-366 requires exactly these (agent_transcript_path/last_assistant_message as string | null).
• Matcher value for plugin subagents is the scoped identifier my-plugin:reviewer; because it contains : it is evaluated as an unanchored regex and should be anchored ^my-plugin:reviewer$ (hooks-2.md → SubagentStart, L2290–2292; sub-agents-3.md → Project-level hooks for subagent events, L757–792). When the compiler starts emitting agent/start/agent/stop routes with an agent-name selector, the Claude lowering must produce the anchored scoped form.
• Frontmatter Stop hooks are converted to SubagentStop at runtime (Hooks in subagent frontmatter, L715–755); frontmatter hooks require workspace trust for project-level agents (≥2.1.218).

Proposed

• Add color, initialPrompt, experimental.cacheTtl rows (state unavailable, same gate) and rewrite the permissionMode/mcpServers/hooks rows' reasons to cite "Ignored for plugin subagents".
• Record the agent_type scoped-identifier/anchoring rule under hooks.matchers so the eventual agent/* selector lowering has pinned evidence.
• Keep the component deferred unless a separate increment is scheduled.

Related

• Claude Code 2.1.257 lineage gaps: SubagentStart names no parent; a subagent's hooks name no parent #422 (Claude lineage gaps around SubagentStart), fix(claude): validate plugin.json and marketplace.json explicitly; read the --json report on 2.1.259+ #474.