[BUG] --bare mode drops custom agents from --agents JSON for subagent_type dispatch

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

When using --bare mode, custom agents defined via --agents <json> are not registered as valid subagent_type values for the Agent/Task tool. The --agent <name> flag correctly selects the main agent from the JSON, but sub-agent dispatch within the session fails:

Agent type 'code-specialist' not found.
Available agents: general-purpose, statusline-setup, Explore, Plan

--bare is designed for headless/CI/Docker deployments where all context is provided explicitly. The docs say:

Explicitly provide context via: --system-prompt[-file], --append-system-prompt[-file], --add-dir (CLAUDE.md dirs), --mcp-config, --settings, --agents, --plugin-dir.

Since --bare skips file-based auto-discovery (~/.claude/agents/, CWD/.claude/agents/), the --agents JSON flag is the only mechanism available. But it doesn't register agents for sub-agent dispatch, making multi-agent orchestration impossible in --bare mode.

What Should Happen?

--bare + --agents '{"my-specialist": {...}}' should register my-specialist as a valid subagent_type for the Agent/Task tool, since --agents is the documented explicit mechanism for providing agent definitions in bare mode.

Error Messages/Logs

# CLI capability fingerprint shows agents JSON is loaded but Agent tool doesn't see them:
{"has_agents_json": true, "agents_count": 6,
 "agents_names": ["code-specialist", "context-specialist", "data-specialist",
                   "docs-specialist", "logs-specialist", "orchestrator"]}

# Orchestrator dispatches to named specialist:
{"tool": "Agent", "subagent_type": "code-specialist", "event": "Delegation requested"}

# CLI rejects the custom agent type:
{"content": "Agent type 'code-specialist' not found.
 Available agents: general-purpose, statusline-setup, Explore, Plan", "is_error": true}

Steps to Reproduce

1. Run with --bare and --agents JSON:

``bash
claude --bare --agents '{"my-specialist":{"description":"Test","prompt":"You are a test"}}' agents
``

1. Output shows only 5 built-in agents — my-specialist is missing

1. Compare without --bare (with agent files in ~/.claude/agents/):

``bash
claude agents
``

1. Output includes custom agents from file-based discovery

1. In a running session with --bare --agents <json> --agent orchestrator, the orchestrator tries Agent(subagent_type="my-specialist") and gets the error above

Note: Without --bare, file-based discovery from ~/.claude/agents/*.md correctly registers agents as valid subagent_types. The issue is specifically that --agents JSON does not provide the same registration, which means --bare mode cannot support multi-agent dispatch.

Is this a regression?

No, this never worked

Claude Code Version

2.1.86 (Claude Code)

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Non-interactive/CI environment

Additional Information

Use case: Multi-agent orchestrator running headless in Docker. An orchestrator agent dispatches to named specialists (code-specialist, data-specialist, docs-specialist, etc.) via Agent(subagent_type=...). Each specialist has its own MCP servers resolved at runtime and injected via the --agents JSON. We want to use --bare for faster startup and deterministic behavior but cannot because of this gap.

Workaround: Copy agent .md files to ~/.claude/agents/ for file-based discovery and don't use --bare. This defeats the purpose of bare mode and requires maintaining agent definitions in two places (files for subagent_type discovery + --agents JSON for runtime MCP server configs).

Related closed issues:

• #18895 — SDK programmatic agents ignored by Task tool (stale-closed)
• #19276 — Feature request for custom subagent support in Task tool (stale-closed)