[BUG/FR] VS Code terminals are silently capped to 256-color by a default-on feature gate — custom themes render visibly wrong; no opt-out exists (unlike tmux's `CLAUDE_CODE_TMUX_TRUECOLOR`)

Environment

• Claude Code v2.1.207 (native binary), Windows 11 (10.0.26200) + Ubuntu 24.04 cross-checked
• VS Code integrated terminal + Extension Development Host (both affected); plain Linux pty (not affected)
• COLORTERM=truecolor present in all repro environments

What happens

Custom TUI themes (~/.claude/themes/*.json, documented as accepting #rrggbb) render quantized to the 256-color cube in every VS Code terminal. Large fills break hardest — e.g. a warm cream userMessageBackground: #EEE4C8 renders as pink #FFD7D7 (256-palette slot 224), and a dark warm brown #1F1814 renders as dark red #5F0000.

Verified at the byte level: capturing the TUI's raw output shows CC emitting indexed sequences (\x1b[48;5;224m) instead of truecolor (\x1b[48;2;238;228;200m) — while the same terminal renders a hand-written 48;2 swatch perfectly, and the same CC version on a plain Linux pty emits proper 38;2/48;2 truecolor.

Root cause (from the shipped binary)

At startup, after theme/chalk initialization:

if (sv() && Qe("tengu_cobalt_thicket", true)) Swc(true)   // Swc: mt.level = 2

where sv() returns true for VS Code terminals (TERM_PROGRAM === "vscode", or a terminal identity starting with "xterm.js"), and tengu_cobalt_thicket is a remote feature gate defaulting to true. This runs after — and reverses — the earlier startup upgrade that fixed washed-out colors in VS Code terminals (v2.1.78 changelog: "Fixed washed-out Claude orange color in VS Code/Cursor/code-server terminals that don't advertise truecolor support").

Every color then passes through rgbToAnsi256 (6×6×6 cube), which is why off-cube theme values shift hue dramatically.

What doesn't work (all tested)

| Lever | Result |
|---|---|
| COLORTERM=truecolor | ignored — never consulted on this path |
| FORCE_COLOR=3 | ignored — worse, any FORCE_COLOR value disables the TERM-allowlist truecolor upgrade (KTh: process.env.FORCE_COLOR !== void 0 → bail) |
| TERM=xterm-256color / xterm-truecolor | ignored — the upgrade allowlist is only alacritty, contour, foot, ghostty, rio, wezterm, xterm-ghostty, xterm-kitty |
| CLAUDE_CODE_TMUX_TRUECOLOR=1 | tmux-only; the VS Code gate still caps a tmux pane whose env inherits TERM_PROGRAM=vscode |

Repro

1. In a VS Code integrated terminal (any platform), create a custom theme with "userMessageBackground": "#EEE4C8" and select it.
2. Send any message — the user-turn bar renders pink #FFD7D7.
3. Confirm the terminal itself is fine: printf '\x1b[48;2;238;228;200m swatch \x1b[0m\n' renders the correct cream.
4. Confirm CC's emission (inside tmux for capture, or script -qec claude out.log on Linux): grep shows 48;5;N in VS Code-descended environments, 48;2;R;G;B on a plain pty.

Ask

1. An opt-out env var for the VS Code cap, mirroring CLAUDE_CODE_TMUX_TRUECOLOR — e.g. CLAUDE_CODE_VSCODE_TRUECOLOR=1. VS Code's xterm.js has supported truecolor for years; if the gate mitigates a specific xterm.js rendering bug, the opt-out lets unaffected users keep correct colors.
2. Document the cap (terminal-config docs / changelog) — today it silently degrades a documented feature and the resulting hue shifts look like theme-author bugs.
3. Fix the FORCE_COLOR interaction — setting the standard force-more-color variable should never reduce effective color fidelity.

Related: #37215 (closed stale — same symptom class, root cause never identified), #36785 / #59867 / #60788 / #37770 (the tmux clamp family, resolved by the opt-out this issue requests for VS Code).