From e55a6e745ef76af497a71e4b445bec1088698a72 Mon Sep 17 00:00:00 2001
From: Sahil-SS9 <218421507+Sahil-SS9@users.noreply.github.com>
Date: Sun, 28 Jun 2026 13:03:34 +0100
Subject: [PATCH] fix: kill entire process tree on Windows to prevent GUI
 program hang (#54201)

---
 tools/terminal_tool.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/tools/terminal_tool.py b/tools/terminal_tool.py
index 44ef03af78878..953715d83498b 100644
--- a/tools/terminal_tool.py
+++ b/tools/terminal_tool.py
@@ -976,6 +976,8 @@ def _transform_sudo_command(command: str | None) -> tuple[str | None, str | None
 PTY mode: Set pty=true for interactive CLI tools (Codex, Claude Code, Python REPL).
 
 Do NOT use vim/nano/interactive tools without pty=true — they hang without a pseudo-terminal. Pipe git output to cat if it might page.
+
+On Windows, launching GUI .exe programs directly in foreground mode will hang the session because the GUI process inherits the stdout pipe and never exits. Use `powershell -Command "Start-Process 'C:\\path\\to\\program.exe'"` instead — PowerShell exits immediately after launching the GUI program.
 """
 
 # Global state for environment lifecycle management