[BUG] teammateMode: "tmux" silently falls back to in-process when it2 CLI shortcuts are broken — no error surfaced to user

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?

I am trying to use the new agent team modes in split pane view. I am using iTerm2, with both tmux and it2 installed though i'm trying to use the native iTerm2 panels, and not tmux. However, claude is failing to detect my configuration being split pane and only running the agents via in-process mode.

running it from tmux spawns split panel mode correctly. But running claude directlly in iTerm2 doesn't, even though I have it2 installed, and python api enabled

What Should Happen?

Per the https://code.claude.com/docs/en/agent-teams, the "tmux" setting "enables split-pane mode and auto-detects whether to use tmux or iTerm2 based on your terminal." Since I'm in iTerm2 with it2 installed and working, teammates should spawn in iTerm2 split panes.

Actual behavior:
Teammates silently spawn in in-process mode. No error, no warning, no indication that the iTerm2 backend was attempted and failed.

Root cause (from debugging v2.1.32):
In a previous session, I found that Claude Code's [ITermBackend] isAvailable check was returning false. Using strings on the Claude Code binary revealed debug strings like:
[ITermBackend] isAvailable check: inITerm2=
[ITermBackend] isAvailable: false (not in iTerm2)

The likely cause: Claude Code runs a verification check against it2 CLI shortcuts at startup. The it2 package (v0.1.8) had a Click parameter naming bug in shortcuts.py where it2 split (the shortcut) failed with:
TypeError: register_shortcuts.<locals>.split_shortcut() got an unexpected keyword argument 'session'

While it2 session split (the full command) worked fine. The shortcut functions declared session_id as the parameter name, but Click maps --session to session.

I patched it2 locally (changed session_id → session in all shortcut functions in shortcuts.py). After the patch, it2 split --vertical works correctly and creates panes. But Claude Code still falls back to in-process mode even after restarting (v2.1.33).

Two issues here:

1. Silent fallback — When the iTerm2 backend detection fails, there is no user-facing error or log. The docs claim auto-detection, but the fallback is invisible. Users have no way to know why split panes aren't appearing.
2. Detection may be cached or checking the wrong thing — Even after fixing it2 and restarting Claude Code (now v2.1.33), the iTerm2 backend still isn't used. Either the detection is cached somewhere, or the availability check is testing something other than it2 split.

Error Messages/Logs

Steps to Reproduce

Steps to reproduce:

1. Install it2 CLI, enable iTerm2 Python API
2. Set teammateMode: "tmux" and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1"
3. Launch Claude Code in iTerm2 (NOT inside tmux)
4. Create an agent team and spawn teammates
5. Observe teammates run in-process, not in split panes

Claude Model

Sonnet (default)

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

2.1.33

Platform

Anthropic API

Operating System

macOS Darwin 24.6.0 (arm64)

Terminal/Shell

iTerm2

Additional Information

Environment:

• Claude Code version: 2.1.33 (previously also 2.1.32)
• OS: macOS Darwin 24.6.0 (arm64)
• Terminal: iTerm2 (TERM_PROGRAM=iTerm.app)
• it2 CLI: v0.1.8 (/Users/npinski/.local/bin/it2)
• iTerm2 Python API: enabled
• tmux: 3.6a (installed but NOT running — not inside a tmux session)

Relevant parts of my claude settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "enabledPlugins": {
    "beads@beads-marketplace": true,
    "context7@claude-plugins-official": true,
    "security-guidance@claude-plugins-official": true,
    "pyright-lsp@claude-plugins-official": true,
    "python-expert@awesome-claude-code-plugins": true,
    "linear@claude-plugins-official": true,
    "sentry@claude-plugins-official": true,
    "cartographer@cartographer-marketplace": true
  },
  "teammateMode": "tmux"
}