[FEATURE] Add `defaultAgent` field to settings for automatic plugin agent activation

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Plugins can ship custom agents, but there is no mechanism to make a plugin agent the default for a project without manually passing --agent every session.

Today, plugin agents rely on Claude's description-based auto-delegation to be invoked. In practice, this is unreliable — Claude frequently handles tasks in the main thread instead of delegating, even when a highly relevant plugin agent is available. The only deterministic alternative is --agent <name>, which requires users to know about it and manually opt in every session.

This creates a gap for domain-specific plugin ecosystems. Consider a team building plugins for different tech stacks:

• frontend-react-plugin — agent with React/Next.js rules, component architecture, state management skills
• python-developer-plugin — agent with Python best practices, project structure, testing and packaging skills
• backend-typescript-plugin — agent with Node/TS patterns, API design, database and infrastructure skills

When a developer installs frontend-react-plugin and opens their React project, the agent should be the default for that session — not sometimes invoked, not probabilistically delegated, but deterministically active. The agent contains the team's rules, conventions, and specialized skills. If it's not used, the plugin provides no value.

The core issue is that the project type — not the user's prompt — should determine which agent is active. For prompts like "fix this bug" or "refactor this", there's nothing in the message that maps to a specific agent description. Auto-delegation is inherently probabilistic in these cases.

Proposed Solution

Add a defaultAgent field to Claude Code settings files (.claude/settings.json, .claude/settings.local.json, or ~/.claude/settings.json).

Project-level (committed, shared with team):

// .claude/settings.json
{
  "defaultAgent": "frontend-react-plugin:react-expert"
}

Personal (gitignored):

// .claude/settings.local.json
{
  "defaultAgent": "frontend-react-plugin:react-expert"
}

Global (all projects):

// ~/.claude/settings.json
{
  "defaultAgent": "python-developer-plugin:python-expert"
}

Behavior:

1. At session start, Claude Code reads defaultAgent from settings (following the existing precedence: local > project > user)
2. If the referenced agent exists (from an installed plugin or .claude/agents/), the session runs as that agent — equivalent to --agent
3. The user's CLAUDE.md and project memory still load normally (same as --agent today)
4. If the agent is not found (plugin not installed), Claude Code shows a warning and falls back to normal behavior
5. --agent flag on the CLI overrides defaultAgent from settings

Why settings and not plugin.json:

It might seem natural to let plugins self-declare as the default agent via their plugin.json. However, this is a security risk — a malicious plugin from a third-party marketplace could hijack every session by declaring itself as default with broad file-detection criteria. The defaultAgent decision must remain with the user or the project maintainer, not the plugin author. This follows the same trust model as enabledPlugins today: the plugin provides capabilities, the user decides to activate them.

Alternative Solutions

1. --agent plugin:agent-name flag

Manual, requires user knowledge, must be passed every session. Not transparent for teams. A developer who forgets the flag gets a degraded experience with no warning.

2. Well-written agent description for auto-delegation

Probabilistic — Claude often ignores it, especially for generic prompts like "fix this bug" or "add a feature". No amount of description tuning makes this deterministic.

3. SessionStart hook printing "always delegate to X"

Hook output is injected as tool output, not system-level context. "Always delegate to agent X" is still a soft instruction Claude can ignore. It's a workaround, not a proper mechanism.

4. /init skill that writes to CLAUDE.md

Requires manual invocation. The /init approach could write defaultAgent to settings.json instead, but this feature request asks for Claude Code to actually read and act on that field.

5. Plugin self-declaring defaultAgent in plugin.json

Security risk. A malicious plugin could hijack sessions by declaring itself as default with broad detection criteria. The activation decision must stay with the user/project, not the plugin.

Priority

Critical - Blocking my work

Feature Category

Configuration and settings

Use Case Example

Our team builds across multiple stacks. We maintain a private plugin marketplace with domain-specific plugins:

team-ai-marketplace/
├── plugins/
│   ├── frontend-react/       → agent + skills for React/Next.js projects
│   ├── python-developer/     → agent + skills for Python projects
│   └── backend-typescript/   → agent + skills for Node/TS backend services

Team workflow:

1. Developers install the plugin for their stack: /plugin install frontend-react@team-ai
2. The project already has .claude/settings.json committed in the repo:

``json
{
"defaultAgent": "frontend-react:react-expert"
}
``

1. Every developer who clones the repo and has the plugin installed automatically gets the right agent — no --agent flag, no CLAUDE.md hacks, no manual steps

For multi-stack monorepos, subdirectory-level settings could scope different agents:

monorepo/
├── .claude/settings.json             → no default (monorepo root)
├── frontend/
│   └── .claude/settings.json         → "defaultAgent": "frontend-react:react-expert"
├── backend/
│   └── .claude/settings.json         → "defaultAgent": "backend-typescript:backend-ts-expert"
└── ml-pipeline/
    └── .claude/settings.json         → "defaultAgent": "python-developer:python-expert"

For individual developers, settings.local.json or ~/.claude/settings.json lets personal preference override the project default without modifying committed files.

The implementation should be straightforward since --agent already does exactly what's needed — this feature request just asks for a settings-based way to specify it, following the same precedence rules that already exist for other settings fields.

Additional Context

Related issues:

• #25834 — Plugin agent skills: frontmatter silently fails (blocks plugin agent effectiveness)

Analogy from other ecosystems:

This is similar to how .nvmrc declares the Node version for a project — the tool is installed separately, but the project declares which version to use. Or how VS Code's settings.json can set "python.defaultInterpreterPath" — the extension provides the capability, the project settings activate it.

Implementation note:

The --agent flag already implements the full behavior (replaces system prompt, loads CLAUDE.md, scopes tools). This feature only adds a new settings field that triggers the same codepath. The CHANGELOG already shows --resume re-uses the --agent value from the previous conversation, so the infrastructure for persisting an agent choice across sessions exists.