Agent team iTerm2 panes not closed on teammate shutdown

Open 💬 4 comments Opened Feb 9, 2026 by rupjae

Description

When using --teammate-mode tmux with the iTerm2 backend, teammate panes are not closed when agents shut down. The agent process exits, the shutdown is acknowledged (including the paneId), but the iTerm2 split pane remains open with a dead shell.

This also causes a cascading issue: if the orphaned pane is closed manually (or via AppleScript), Claude Code's internal pane tracking becomes stale. Subsequent team spawns fail with Session '<old-pane-id>' not found because it tries to split from the now-deleted pane. The only recovery is restarting Claude Code entirely.

Reproduction

  1. Launch Claude Code with --teammate-mode tmux in iTerm2 (Python API enabled)
  2. Create an agent team and spawn 2 teammates
  3. Panes appear correctly (backend: iterm2)
  4. Shut down both teammates via shutdown_request
  5. Both agents respond with shutdown_approved (including paneId and backendType: iterm2)
  6. Bug: Panes remain open — shell is alive at a prompt, agent process exited
  7. Close panes manually
  8. Try to spawn a new team
  9. Bug: Spawn fails with Failed to create iTerm2 split pane: Error: Session '<stale-pane-id>' not found

Expected behavior

When a teammate shuts down, Claude Code should call async_close() on the iTerm2 session/pane using the Python API. The pane ID is already available in the shutdown response.

Verified that iterm2.Session.async_close() works correctly for this:

import iterm2

async def main(connection):
    app = await iterm2.async_get_app(connection)
    window = app.current_terminal_window
    session = tab.current_session
    new_session = await session.async_split_pane(vertical=True)
    # ... later on shutdown:
    await new_session.async_close()  # <-- this works, pane closes cleanly

iterm2.run_until_complete(main)

Environment

  • Claude Code 2.1.37
  • macOS (Darwin 25.3.0, arm64)
  • iTerm2 with Python API enabled
  • --teammate-mode tmux (auto-detects iTerm2 backend)

Related issues

  • #24261 — Stale pane state causing spawn failures (same cascading consequence)
  • #23615 — Pane spawning layout issues

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗