Defer agent tool schema (like MCP/skills) + allow per-project agent scoping for plugin-contributed agents

Summary

The Agent tool schema loads every available agent's description + tool list into the system prompt at session start. Unlike MCP tool schemas (deferred via ToolSearch) or skills (SKILL.md body loaded on Skill invocation), agent descriptions are eager-loaded and not deferrable.

Additionally, plugin-contributed agents cannot be scoped to specific projects. User agents (~/.claude/agents/*.md) and project agents (./.claude/agents/*.md) both work — but plugin-contributed agents load globally from enabledPlugins in user-level settings.json, with no per-project mechanism to include or exclude them.

Measurement

On a personal config with 20 agents enabled (9 user-owned + 5 native built-in + 6 plugin-contributed), the Agent tool section in the system prompt is approximately 7,500 characters total: tool preamble (~1.5k chars) + per-agent entries (105–2,000 chars each, median ~300). Estimated ~1.9k tokens at char/4.

A few multi-example-format plugin agents (e.g., frontend-developer:frontend-developer ~2,000 chars) dominate the bulk; most agents are terse 1–2 sentence descriptions. The cost scales with description verbosity more than agent count.

Reference context-generation study (2026-04-17, two real sessions measured via message.usage in JSONL): top per-turn producers are Edit/Write bodies (13–22k), Read results (up to 12.8k), MCP envelopes (2–5k), skill SKILL.md bodies (2.5k). Agent schema sits below these at ~2k but fires at t=0 with no opt-out.

Proposals

A. Deferral. Introduce an AgentSearch tool analogous to ToolSearch. At session start, the Agent tool description shows names + 1-line descriptions (similar to the skill listing). Full agent descriptions + tool lists fetch via AgentSearch select:<agent-name> before dispatch. Mirrors existing MCP deferral; preserves current ergonomics.

Alternative: per-agent loadEagerly: true frontmatter metadata, defaulting to lazy.

B. Per-project plugin agent scoping. Allow project-level .claude/settings.json to declare an enabledAgents or agentFilter list that restricts which plugin-contributed agents appear in the Agent tool schema for that project. This lets users install a large plugin catalog globally without every session paying the full schema cost.

Example project-level .claude/settings.json:

{
  "enabledPluginAgents": [
    "frontend-developer@claude-code-marketplace",
    "accessibility-architect@claudeforge-marketplace"
  ]
}

Or negative filter:

{
  "disabledPluginAgents": ["rapid-prototyper@claudeforge-marketplace"]
}

User-side workaround (current limits)

Pruning individual plugin-contributed agents via enabledPlugins in ~/.claude/settings.json works but is all-or-nothing across projects. Today, 5 near-zero-dispatch plugins were pruned (measured via grep -rh '"subagent_type"' ~/.claude/projects/*/[session].jsonl), dropping ~250–300 tokens per session. A per-project scoping mechanism would serve users who want to keep plugins installed but selectively available.

Related prior art

• ToolSearch for MCP — the same shape would suit agents.
• Project agents at .claude/agents/*.md already work for user-authored agents; the gap is only plugin-contributed ones.