Add --session option to focus-tab command

Adds the ability to focus a tab by its WT_SESSION GUID, enabling external
processes (like AI coding agents) to programmatically return users to
the correct terminal tab.

Usage: wt focus-tab --session <guid>
   or: wt ft -s <guid>

Changes:
- Added --session/-s option to focus-tab CLI parser
- Extended SwitchToTabArgs with SessionId property
- Added FocusPaneBySessionId() to Tab class to walk pane tree
- Modified _HandleSwitchToTab to lookup by session ID
- Auto-routes to existing window (implicit -w 0) for session targeting
- Added unit tests for --session parsing

Fixes #19783

Author: shanselman

src/cascadia/LocalTests_TerminalApp/CommandlineTest.cpp

@@ -1118,6 +1118,58 @@ namespace TerminalAppLocalTests
             VERIFY_ARE_EQUAL(4u, commandlines.at(0).Argc());
             VERIFY_ARE_EQUAL("wt.exe", commandlines.at(0).Args().at(0));
 
+            for (auto& cmdBlob : commandlines)
+            {
+                const auto result = appArgs.ParseCommand(cmdBlob);
+                Log::Comment(NoThrowString().Format(
+                    L"Exit Message:\n%hs",
+                    appArgs._exitMessage.c_str()));
+                VERIFY_ARE_NOT_EQUAL(0, result);
+                VERIFY_ARE_NOT_EQUAL("", appArgs._exitMessage);
+            }
+        }
+        {
+            Log::Comment(NoThrowString().Format(
+                L"Test focus-tab with --session flag"));
+            AppCommandlineArgs appArgs{};
+            std::vector<const wchar_t*> rawCommands{ L"wt.exe", subcommand, L"-s", L"12345678-1234-1234-1234-123456789abc" };
+            _buildCommandlinesHelper(appArgs, 1u, rawCommands);
+
+            // With --session, there should be NO NewTab prepended (it routes to existing window)
+            VERIFY_ARE_EQUAL(1u, appArgs._startupActions.size());
+
+            auto actionAndArgs = appArgs._startupActions.at(0);
+            VERIFY_ARE_EQUAL(ShortcutAction::SwitchToTab, actionAndArgs.Action());
+            VERIFY_IS_NOT_NULL(actionAndArgs.Args());
+            auto myArgs = actionAndArgs.Args().try_as<SwitchToTabArgs>();
+            VERIFY_IS_NOT_NULL(myArgs);
+            // Verify SessionId is set (non-empty GUID)
+            VERIFY_ARE_NOT_EQUAL(winrt::guid{}, myArgs.SessionId());
+        }
+        {
+            Log::Comment(NoThrowString().Format(
+                L"Test focus-tab with --session long form flag"));
+            AppCommandlineArgs appArgs{};
+            std::vector<const wchar_t*> rawCommands{ L"wt.exe", subcommand, L"--session", L"12345678-1234-1234-1234-123456789abc" };
+            _buildCommandlinesHelper(appArgs, 1u, rawCommands);
+
+            VERIFY_ARE_EQUAL(1u, appArgs._startupActions.size());
+
+            auto actionAndArgs = appArgs._startupActions.at(0);
+            VERIFY_ARE_EQUAL(ShortcutAction::SwitchToTab, actionAndArgs.Action());
+            auto myArgs = actionAndArgs.Args().try_as<SwitchToTabArgs>();
+            VERIFY_IS_NOT_NULL(myArgs);
+            VERIFY_ARE_NOT_EQUAL(winrt::guid{}, myArgs.SessionId());
+        }
+        {
+            Log::Comment(NoThrowString().Format(
+                L"Test that --session excludes -t (target index)"));
+            AppCommandlineArgs appArgs{};
+            std::vector<const wchar_t*> rawCommands{ L"wt.exe", subcommand, L"-s", L"12345678-1234-1234-1234-123456789abc", L"-t", L"2" };
+
+            auto commandlines = AppCommandlineArgs::BuildCommands(rawCommands);
+            VERIFY_ARE_EQUAL(1u, commandlines.size());
+
             for (auto& cmdBlob : commandlines)
             {
                 const auto result = appArgs.ParseCommand(cmdBlob);

src/cascadia/TerminalApp/AppActionHandlers.cpp

@@ -482,6 +482,31 @@ namespace winrt::TerminalApp::implementation
     {
         if (const auto& realArgs = args.ActionArgs().try_as<SwitchToTabArgs>())
         {
+            // Check if we're targeting by session ID
+            if (realArgs.SessionId() != winrt::guid{})
+            {
+                // Find the tab containing this session
+                const auto sessionId = realArgs.SessionId();
+                uint32_t tabIndex = 0;
+                
+                for (const auto& tab : _tabs)
+                {
+                    auto tabImpl = winrt::get_self<implementation::Tab>(tab);
+                    if (tabImpl && tabImpl->FocusPaneBySessionId(sessionId))
+                    {
+                        _SelectTab(tabIndex);
+                        args.Handled(true);
+                        return;
+                    }
+                    tabIndex++;
+                }
+                
+                // Session not found in this window
+                args.Handled(false);
+                return;
+            }
+            
+            // Fall back to tab index
             _SelectTab({ realArgs.TabIndex() });
             args.Handled(true);
         }

src/cascadia/TerminalApp/AppCommandlineArgs.cpp

@@ -372,9 +372,15 @@ void AppCommandlineArgs::_buildFocusTabParser()
         auto* prevOpt = subcommand->add_flag("-p,--previous",
                                              _focusPrevTab,
                                              RS_A(L"CmdFocusTabPrevArgDesc"));
+        auto* sessionOpt = subcommand->add_option("-s,--session",
+                                                  _focusTabSession,
+                                                  RS_A(L"CmdFocusTabSessionArgDesc"));
         nextOpt->excludes(prevOpt);
         indexOpt->excludes(prevOpt);
         indexOpt->excludes(nextOpt);
+        sessionOpt->excludes(indexOpt);
+        sessionOpt->excludes(nextOpt);
+        sessionOpt->excludes(prevOpt);
 
         // When ParseCommand is called, if this subcommand was provided, this
         // callback function will be triggered on the same thread. We can be sure
@@ -384,10 +390,40 @@ void AppCommandlineArgs::_buildFocusTabParser()
             // Build the action from the values we've parsed on the commandline.
             ActionAndArgs focusTabAction{};
 
-            if (_focusTabIndex >= 0)
+            if (!_focusTabSession.empty())
             {
+                // Focus tab by session GUID
                 focusTabAction.Action(ShortcutAction::SwitchToTab);
-                SwitchToTabArgs args{ static_cast<unsigned int>(_focusTabIndex) };
+                SwitchToTabArgs args{};
+                const auto str = winrt::to_hstring(_focusTabSession);
+                // GuidFromPlainString handles GUIDs without braces (e.g. "12345678-...")
+                // GuidFromString handles GUIDs with braces (e.g. "{12345678-...}")
+                // Try plain first (most common from WT_SESSION), fall back to braced
+                winrt::guid id{};
+                try
+                {
+                    id = ::Microsoft::Console::Utils::GuidFromPlainString(str.c_str());
+                }
+                catch (...)
+                {
+                    id = ::Microsoft::Console::Utils::GuidFromString(str.c_str());
+                }
+                args.SessionId(id);
+                focusTabAction.Args(args);
+                _startupActions.push_back(focusTabAction);
+                
+                // When targeting by session ID, route to an existing window on the 
+                // current desktop (if user didn't specify -w explicitly).
+                // The session ID uniquely identifies a pane in some window.
+                if (_windowTarget.empty())
+                {
+                    _windowTarget = "0";
+                }
+            }
+            else if (_focusTabIndex >= 0)
+            {
+                focusTabAction.Action(ShortcutAction::SwitchToTab);
+                SwitchToTabArgs args{ static_cast<unsigned int>(_focusTabIndex), winrt::guid{} };
                 focusTabAction.Args(args);
                 _startupActions.push_back(focusTabAction);
             }
@@ -808,6 +844,7 @@ void AppCommandlineArgs::_resetStateToDefault()
     _focusTabIndex = -1;
     _focusNextTab = false;
     _focusPrevTab = false;
+    _focusTabSession.clear();
 
     _moveFocusDirection = FocusDirection::None;
     _swapPaneDirection = FocusDirection::None;
@@ -1014,9 +1051,14 @@ void AppCommandlineArgs::ValidateStartupCommands()
     // If we parsed no commands, or the first command we've parsed is not a new
     // tab action, prepend a new-tab command to the front of the list.
     // (also, we don't need to do this if the only action is a x-save)
+    // Note: SwitchToTab with a SessionId is excluded because focus-tab --session
+    // targets an existing tab and doesn't need a new tab to be created.
+    // We check for non-empty _windowTarget as a proxy for --session being used,
+    // since --session sets _windowTarget = "0".
     else if (_startupActions.empty() ||
              (_startupActions.front().Action() != ShortcutAction::NewTab &&
-              _startupActions.front().Action() != ShortcutAction::SaveSnippet))
+              _startupActions.front().Action() != ShortcutAction::SaveSnippet &&
+              !(!_windowTarget.empty() && _startupActions.front().Action() == ShortcutAction::SwitchToTab)))
     {
         // Build the NewTab action from the values we've parsed on the commandline.
         NewTerminalArgs newTerminalArgs{};

src/cascadia/TerminalApp/AppCommandlineArgs.h

@@ -121,6 +121,7 @@ class TerminalApp::AppCommandlineArgs final
     int _focusTabIndex{ -1 };
     bool _focusNextTab{ false };
     bool _focusPrevTab{ false };
+    std::string _focusTabSession;  // GUID string for --session targeting
 
     int _focusPaneTarget{ -1 };
     std::string _saveInputName;

src/cascadia/TerminalApp/Resources/en-US/Resources.resw

@@ -318,6 +318,9 @@
   <data name="CmdFocusTabTargetArgDesc" xml:space="preserve">
     <value>Move focus the tab at the given index</value>
   </data>
+  <data name="CmdFocusTabSessionArgDesc" xml:space="preserve">
+    <value>Move focus to the tab containing the given WT_SESSION GUID</value>
+  </data>
   <data name="CmdMovePaneTabArgDesc" xml:space="preserve">
     <value>Move focused pane to the tab at the given index</value>
   </data>

src/cascadia/TerminalApp/Tab.cpp

@@ -933,6 +933,47 @@ namespace winrt::TerminalApp::implementation
         return res;
     }
 
+    // Method Description:
+    // - Attempts to find and focus a pane within this tab by its WT_SESSION GUID.
+    // Arguments:
+    // - sessionId: The session GUID to search for.
+    // Return Value:
+    // - true if the session was found and focused, false otherwise.
+    bool Tab::FocusPaneBySessionId(const winrt::guid& sessionId)
+    {
+        ASSERT_UI_THREAD();
+
+        if (_rootPane == nullptr)
+        {
+            return false;
+        }
+
+        bool found = false;
+        _changingActivePane = true;
+        _rootPane->WalkTree([&](const auto& pane) {
+            if (const auto content = pane->GetContent())
+            {
+                if (const auto termContent = content.try_as<winrt::TerminalApp::TerminalPaneContent>())
+                {
+                    const auto control = termContent.GetTermControl();
+                    if (control)
+                    {
+                        const auto connection = control.Connection();
+                        if (connection && connection.SessionId() == sessionId)
+                        {
+                            _rootPane->FocusPane(pane);
+                            found = true;
+                            return true; // stop walking
+                        }
+                    }
+                }
+            }
+            return false; // keep walking
+        });
+        _changingActivePane = false;
+        return found;
+    }
+
     void Tab::Close()
     {
         ASSERT_UI_THREAD();

src/cascadia/TerminalApp/Tab.h

@@ -57,6 +57,7 @@ namespace winrt::TerminalApp::implementation
         bool NavigateFocus(const winrt::Microsoft::Terminal::Settings::Model::FocusDirection& direction);
         bool SwapPane(const winrt::Microsoft::Terminal::Settings::Model::FocusDirection& direction);
         bool FocusPane(const uint32_t id);
+        bool FocusPaneBySessionId(const winrt::guid& sessionId);
 
         void UpdateSettings(const winrt::Microsoft::Terminal::Settings::Model::CascadiaSettings& settings);
         void UpdateTitle();

src/cascadia/TerminalApp/TerminalPage.cpp

@@ -2258,7 +2258,7 @@ namespace winrt::TerminalApp::implementation
         {
             ActionAndArgs action;
             action.Action(ShortcutAction::SwitchToTab);
-            SwitchToTabArgs switchToTabArgs{ idx.value() };
+            SwitchToTabArgs switchToTabArgs{ idx.value(), winrt::guid{} };
             action.Args(switchToTabArgs);
 
             actions.emplace_back(std::move(action));

src/cascadia/TerminalSettingsModel/ActionArgs.h

@@ -118,7 +118,8 @@ protected:                                                                  \
 
 ////////////////////////////////////////////////////////////////////////////////
 #define SWITCH_TO_TAB_ARGS(X) \
-    X(uint32_t, TabIndex, "index", false, ArgTypeHint::None, 0)
+    X(uint32_t, TabIndex, "index", false, ArgTypeHint::None, 0) \
+    X(winrt::guid, SessionId, "sessionId", false, ArgTypeHint::None, winrt::guid{})
 
 ////////////////////////////////////////////////////////////////////////////////
 #define RESIZE_PANE_ARGS(X) \

src/cascadia/TerminalSettingsModel/ActionArgs.idl

@@ -226,8 +226,10 @@ namespace Microsoft.Terminal.Settings.Model
 
     [default_interface] runtimeclass SwitchToTabArgs : IActionArgs, IActionArgsDescriptorAccess
     {
-        SwitchToTabArgs(UInt32 tabIndex);
+        SwitchToTabArgs();
+        SwitchToTabArgs(UInt32 tabIndex, Guid sessionId);
         UInt32 TabIndex;
+        Guid SessionId;  // WT_SESSION GUID to focus - if set, takes precedence over TabIndex
     };
 
     [default_interface] runtimeclass ResizePaneArgs : IActionArgs, IActionArgsDescriptorAccess