fix: address Copilot feedback on terminal focus behavior

- Add optional focus parameter to both snacks and native provider open() methods
- Extract shared logic into ensure_terminal_visible_no_focus() helper function
- Fix ensure_visible() to truly not focus by passing focus=false to providers
- Fix toggle_open_no_focus() to use the same consistent no-focus behavior
- Maintain backward compatibility by defaulting focus parameter to true
- Return to original window in native provider when focus=false

Addresses feedback about ensure_visible() contradicting its intent by calling
provider.open() which always focused the terminal.

Change-Id: I11635699095df7284232b7c959ade1e11c41dbc4
Signed-off-by: Thomas Kosiewski <tk@coder.com>

Author: ThomasK33

README.md

@@ -283,7 +283,7 @@ For most users, the default configuration is sufficient:
     -- Connection Management
     connection_wait_delay = 200,                -- Wait time after connection before sending queued @ mentions (ms)
     connection_timeout = 10000,                 -- Max time to wait for Claude Code connection (ms)
-    queue_timeout = 3000,                       -- Max time to keep @ mentions in queue (ms)
+    queue_timeout = 5000,                       -- Max time to keep @ mentions in queue (ms)
 
     -- Terminal Configuration
     terminal = {

dev-config.lua

@@ -48,7 +48,7 @@ return {
     -- Connection Management
     -- connection_wait_delay = 200,                -- Wait time after connection before sending queued @ mentions (ms)
     -- connection_timeout = 10000,                 -- Max time to wait for Claude Code connection (ms)
-    -- queue_timeout = 3000,                       -- Max time to keep @ mentions in queue (ms)
+    -- queue_timeout = 5000,                       -- Max time to keep @ mentions in queue (ms)
 
     -- Diff Integration
     -- diff_opts = {

lua/claudecode/terminal.lua

@@ -151,6 +151,27 @@ local function get_claude_command_and_env(cmd_args)
   return cmd_string, env_table
 end
 
+--- Common helper to open terminal without focus if not already visible
+--- @param opts_override table|nil Optional config overrides
+--- @param cmd_args string|nil Optional command arguments
+--- @return boolean True if terminal was opened or already visible
+local function ensure_terminal_visible_no_focus(opts_override, cmd_args)
+  local provider = get_provider()
+  local active_bufnr = provider.get_active_bufnr()
+
+  if is_terminal_visible(active_bufnr) then
+    -- Terminal is already visible, do nothing
+    return true
+  end
+
+  -- Terminal is not visible, open it without focus
+  local effective_config = build_config(opts_override)
+  local cmd_string, claude_env_table = get_claude_command_and_env(cmd_args)
+
+  provider.open(cmd_string, claude_env_table, effective_config, false) -- false = don't focus
+  return true
+end
+
 --- Configures the terminal module.
 -- Merges user-provided terminal configuration with defaults and sets the terminal command.
 -- @param user_term_config table (optional) Configuration options for the terminal.
@@ -240,39 +261,14 @@ end
 -- @param opts_override table (optional) Overrides for terminal appearance (split_side, split_width_percentage).
 -- @param cmd_args string|nil (optional) Arguments to append to the claude command.
 function M.toggle_open_no_focus(opts_override, cmd_args)
-  local provider = get_provider()
-
-  -- Check if terminal is already visible
-  local active_bufnr = provider.get_active_bufnr()
-  if is_terminal_visible(active_bufnr) then
-    -- Terminal is already visible, do nothing
-    return
-  end
-
-  -- Terminal is not visible, open it without focus
-  local effective_config = build_config(opts_override)
-  local cmd_string, claude_env_table = get_claude_command_and_env(cmd_args)
-
-  provider.open(cmd_string, claude_env_table, effective_config)
+  ensure_terminal_visible_no_focus(opts_override, cmd_args)
 end
 
 --- Ensures terminal is visible without changing focus. Creates if necessary, shows if hidden.
 -- @param opts_override table (optional) Overrides for terminal appearance (split_side, split_width_percentage).
 -- @param cmd_args string|nil (optional) Arguments to append to the claude command.
 function M.ensure_visible(opts_override, cmd_args)
-  local provider = get_provider()
-  local effective_config = build_config(opts_override)
-  local cmd_string, claude_env_table = get_claude_command_and_env(cmd_args)
-
-  -- Check if terminal exists and is visible
-  local active_bufnr = provider.get_active_bufnr()
-  if is_terminal_visible(active_bufnr) then
-    -- Terminal is already visible, do nothing
-    return
-  end
-
-  -- Terminal is not visible or doesn't exist, create/show it
-  provider.open(cmd_string, claude_env_table, effective_config)
+  ensure_terminal_visible_no_focus(opts_override, cmd_args)
 end
 
 --- Toggles the Claude terminal open or closed (legacy function - use simple_toggle or focus_toggle).

lua/claudecode/terminal/native.lua

@@ -45,10 +45,14 @@ local function is_valid()
   return true
 end
 
-local function open_terminal(cmd_string, env_table, effective_config)
+local function open_terminal(cmd_string, env_table, effective_config, focus)
+  focus = focus == nil and true or focus -- Default to true for backward compatibility
+
   if is_valid() then -- Should not happen if called correctly, but as a safeguard
-    vim.api.nvim_set_current_win(winid)
-    vim.cmd("startinsert")
+    if focus then
+      vim.api.nvim_set_current_win(winid)
+      vim.cmd("startinsert")
+    end
     return true
   end
 
@@ -121,8 +125,13 @@ local function open_terminal(cmd_string, env_table, effective_config)
   vim.bo[bufnr].bufhidden = "wipe" -- Wipe buffer when hidden (e.g., window closed)
   -- buftype=terminal is set by termopen
 
-  vim.api.nvim_set_current_win(winid)
-  vim.cmd("startinsert")
+  if focus then
+    vim.api.nvim_set_current_win(winid)
+    vim.cmd("startinsert")
+  else
+    -- Return to original window if not focusing
+    vim.api.nvim_set_current_win(original_win)
+  end
 
   if config.show_native_term_exit_tip and not tip_shown then
     vim.notify("Native terminal opened. Press Ctrl-\\ Ctrl-N to return to Normal mode.", vim.log.levels.INFO)
@@ -251,9 +260,14 @@ end
 --- @param cmd_string string
 --- @param env_table table
 --- @param effective_config table
-function M.open(cmd_string, env_table, effective_config)
+--- @param focus boolean|nil
+function M.open(cmd_string, env_table, effective_config, focus)
+  focus = focus == nil and true or focus -- Default to true for backward compatibility
+
   if is_valid() then
-    focus_terminal()
+    if focus then
+      focus_terminal()
+    end
   else
     -- Check if there's an existing Claude terminal we lost track of
     local existing_buf, existing_win = find_existing_claude_terminal()
@@ -263,9 +277,11 @@ function M.open(cmd_string, env_table, effective_config)
       winid = existing_win
       -- Note: We can't recover the job ID easily, but it's less critical
       logger.debug("terminal", "Recovered existing Claude terminal")
-      focus_terminal()
+      if focus then
+        focus_terminal()
+      end
     else
-      if not open_terminal(cmd_string, env_table, effective_config) then
+      if not open_terminal(cmd_string, env_table, effective_config, focus) then
         vim.notify("Failed to open Claude terminal using native fallback.", vim.log.levels.ERROR)
       end
     end

lua/claudecode/terminal/snacks.lua

@@ -43,12 +43,14 @@ end
 
 --- @param config table
 --- @param env_table table
+--- @param focus boolean|nil
 --- @return table
-local function build_opts(config, env_table)
+local function build_opts(config, env_table, focus)
+  focus = focus == nil and true or focus -- Default to true for backward compatibility
   return {
     env = env_table,
-    start_insert = true,
-    auto_insert = true,
+    start_insert = focus,
+    auto_insert = focus,
     auto_close = false,
     win = {
       position = config.split_side,
@@ -66,27 +68,32 @@ end
 --- @param cmd_string string
 --- @param env_table table
 --- @param config table
-function M.open(cmd_string, env_table, config)
+--- @param focus boolean|nil
+function M.open(cmd_string, env_table, config, focus)
   if not is_available() then
     vim.notify("Snacks.nvim terminal provider selected but Snacks.terminal not available.", vim.log.levels.ERROR)
     return
   end
 
+  focus = focus == nil and true or focus -- Default to true for backward compatibility
+
   if terminal and terminal:buf_valid() then
-    terminal:focus()
-    local term_buf_id = terminal.buf
-    if term_buf_id and vim.api.nvim_buf_get_option(term_buf_id, "buftype") == "terminal" then
-      -- Check if window is valid before calling nvim_win_call
-      if terminal.win and vim.api.nvim_win_is_valid(terminal.win) then
-        vim.api.nvim_win_call(terminal.win, function()
-          vim.cmd("startinsert")
-        end)
+    if focus then
+      terminal:focus()
+      local term_buf_id = terminal.buf
+      if term_buf_id and vim.api.nvim_buf_get_option(term_buf_id, "buftype") == "terminal" then
+        -- Check if window is valid before calling nvim_win_call
+        if terminal.win and vim.api.nvim_win_is_valid(terminal.win) then
+          vim.api.nvim_win_call(terminal.win, function()
+            vim.cmd("startinsert")
+          end)
+        end
       end
     end
     return
   end
 
-  local opts = build_opts(config, env_table)
+  local opts = build_opts(config, env_table, focus)
   local term_instance = Snacks.terminal.open(cmd_string, opts)
   if term_instance and term_instance:buf_valid() then
     setup_terminal_events(term_instance, config)