claude-code - 💡(How to fix) Fix [BUG] Background sessions don't load user agents from ~/.claude/agents/ into the Agent tool registry (related: #41973, #58353) [2 comments, 3 participants]

Preflight Checklist

• I have searched existing issues — closest are #41973 (same symptom in mcp serve mode) and #58353 (same bg session mode, different missing feature). This is the intersection — bg sessions specifically failing to load user agents.
• This is a single bug report.
• I am using the latest version of Claude Code (2.1.140).

What's wrong

Background sessions (i.e. anything spawned by claude daemon / launched as a bg job from an interactive session or from FleetView) expose a different Agent-tool registry than the rest of Claude Code reports for the same user.

• claude agents from any shell correctly reports user agents in ~/.claude/agents/ (3 user + 5 built-in = 8 total).
• Inside a bg session, attempting subagent_type: "<user-agent-name>" via the Agent tool is rejected with:

  Agent type 'utility-bot' not found. Available agents: claude, claude-code-guide, Explore, general-purpose, Plan, statusline-setup

  Note: the "Available agents" list is different from what claude agents reports — it includes claude-code-guide (not in claude agents) and excludes all three user agents.

Effect: any bg-session work that should be routed to a user-defined model-specific agent (e.g. utility-bot → Haiku for docs, developer → Sonnet for code) silently falls back to general-purpose, which defaults to the main session's model (Opus in my case). Result: routine bg work runs on Opus when it should run on Haiku or Sonnet — quietly burning budget.

Hard evidence of the divergence

From the same shell, same user, same machine:

$ claude agents
8 active agents

User agents:
  developer · sonnet
  plan · opus
  utility-bot · haiku

Built-in agents:
  claude · inherit
  Explore · haiku
  general-purpose · inherit
  Plan · inherit
  statusline-setup · sonnet

From inside a bg session, attempting Agent with any user-agent name:

Agent type 'utility-bot' not found. Available agents: claude, claude-code-guide, Explore, general-purpose, Plan, statusline-setup

Differences:

• Bg session sees claude-code-guide — claude agents doesn't list it.
• Bg session does NOT see developer, utility-bot, plan (the user agents).

What should happen

bg sessions should merge ~/.claude/agents/ into the Agent-tool runtime registry the same way interactive sessions do. If that's intentionally divergent for some reason, the behaviour should at least be documented and the claude agents CLI output should match what bg sessions actually see.

Workarounds tried (all failed)

1. settings.json:agents key — REJECTED by schema validator:

   Unrecognized field: agents. Check for typos or refer to the documentation for valid fields

   The schema's top-level additionalProperties: {} is overridden by a strict validator. Only agent (singular, string) is accepted.

2. subagent_type resolved by name only — confirmed deterministic rejection on every invocation. No retry/refresh path from inside the bg session.

3. --agents '<json>' — Per #41973 the same flag also fails to fix the analogous bug in mcp serve mode. I have not personally retested for bg, but the user reports for #41973 align with the symptom.

Suggested fix

In the bg session-template boot path (the code that builds options.agentDefinitions.activeAgents), apply the same ~/.claude/agents/ + project .claude/agents/ discovery that claude agents and interactive sessions already use. The disk-level discovery clearly works (proven by claude agents); only the bg template's wiring of that discovery into the Agent tool resolver is missing.

Concrete repro

1. Add ~/.claude/agents/utility-bot.md:

   ---
   name: utility-bot
   description: Fast, low-context tasks (commit messages, doc updates, formatting).
   model: haiku
   ---
   You are the Utility Bot...

2. Confirm the CLI sees it: claude agents → shows utility-bot · haiku under "User agents".
3. From an interactive session, spawn a bg session (any FleetView/slash flow that triggers claude daemon run --origin transient).
4. In the bg session, call the Agent tool with subagent_type: "utility-bot".
5. Observe: Agent type 'utility-bot' not found. Available agents: claude, claude-code-guide, Explore, general-purpose, Plan, statusline-setup.

Environment

• Claude Code Version: 2.1.140
• Platform: macOS (Darwin 25.5.0)
• Process tree: bg agent under claude daemon ... --origin transient --spawned-by "slash"
• state.json: "template": "bg", "sessionKind": "bg" in the session's JSONL records.
• Env: CLAUDECODE=1, CLAUDE_JOB_DIR=~/.claude/jobs/<id>.

Related

• #41973 — Same root cause class for mcp serve mode (also non-interactive, also strips user agents from the Agent-tool registry).
• #58353 — Same bg session-mode environmental stripping, but for Claude.ai remote connectors instead of user agents. Strongly suggests the broader fix is "bg-template environment parity with interactive".