Agent team iTerm2 panes not closed on teammate shutdown
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
- Launch Claude Code with
--teammate-mode tmuxin iTerm2 (Python API enabled) - Create an agent team and spawn 2 teammates
- Panes appear correctly (backend:
iterm2) - Shut down both teammates via
shutdown_request - Both agents respond with
shutdown_approved(includingpaneIdandbackendType: iterm2) - Bug: Panes remain open — shell is alive at a prompt, agent process exited
- Close panes manually
- Try to spawn a new team
- 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
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗