[BUG] CLAUDE_CODE_DISABLE_BACKGROUND_TASKS ignored when spawning multiple subagents

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?

Setting CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 (in settings.json under env) only partially works. When asking Claude to run a single subagent, it correctly runs in the foreground. However, when asking Claude to run multiple subagents (e.g., 3 agents to handle parallel tasks), it ignores the setting and launches them all in the background.

My settings.json env config:

"env": {
    "DISABLE_PROMPT_CACHING": "0",
    "MAX_MCP_OUTPUT_TOKENS": "50000",
    "CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS": "50000",
    "ENABLE_LSP_TOOL": "1",
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "CLAUDE_CODE_DISABLE_BACKGROUND_TASKS": "1"
}

According to the documentation:

To disable all background task functionality, set the CLAUDE_CODE_DISABLE_BACKGROUND_TASKS environment variable to 1.

With the variable set and multiple subagents requested, Claude Code still backgrounds all of them:

├─ Execute TASK-224
│  ⎿  Running in the background
├─ Execute TASK-225
│  ⎿  Running in the background
└─ Execute TASK-226
   ⎿  Running in the background

⏺ 3 build agents launched in parallel

Requesting a single subagent works correctly — it runs in the foreground as expected. The bug only occurs when multiple subagents are spawned.

What Should Happen?

When CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 is set, all subagents should run in the foreground regardless of how many are requested — just as it already works correctly for a single subagent. Multiple subagents should run sequentially in the foreground rather than being launched in parallel as background tasks.

Error Messages/Logs

Steps to Reproduce

1. Set CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 in settings.json under env
2. Launch Claude Code
3. Ask Claude to run a single subagent → ✅ it runs in the foreground correctly
4. Ask Claude to run multiple subagents (e.g., "run 3 agents to handle X, Y, and Z")
5. Observe that all 3 subagents are launched in the background despite the setting

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.76 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

Documentation reference: https://code.claude.com/docs/en/sub-agents#run-subagents-in-foreground-or-background

The docs state: "To disable all background task functionality, set the CLAUDE_CODE_DISABLE_BACKGROUND_TASKS environment variable to 1."

The variable was set via export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 before launching Claude Code, and confirmed with echo, but background subagents are still spawned.