feat: implement alternate buffer toggling and unit tests

Co-authored-by: mkorwel <matt.korwel@gmail.com>

.gemini/skills/async-pr-review/scripts/async-review.sh

@@ -1,190 +1,194 @@
 #!/bin/bash
 
 notify() {
-  local title="$1"
-  local message="$2"
-  local pr="$3"
+  local title="${1}"
+  local message="${2}"
+  local pr="${3}"
   # Terminal escape sequence
-  printf "\e]9;%s | PR #%s | %s\a" "$title" "$pr" "$message"
+  printf "\e]9;%s | PR #%s | %s\a" "${title}" "${pr}" "${message}"
   # Native macOS notification
-  if [[ "$(uname)" == "Darwin" ]]; then
-    osascript -e "display notification \"$message\" with title \"$title\" subtitle \"PR #$pr\""
+  os_type="$(uname || true)"
+  if [[ "${os_type}" == "Darwin" ]]; then
+    osascript -e "display notification \"${message}\" with title \"${title}\" subtitle \"PR #${pr}\""
   fi
 }
 
-pr_number=$1
-if [[ -z "$pr_number" ]]; then
+pr_number="${1}"
+if [[ -z "${pr_number}" ]]; then
   echo "Usage: async-review <pr_number>"
   exit 1
 fi
 
-base_dir=$(git rev-parse --show-toplevel 2>/dev/null)
-if [[ -z "$base_dir" ]]; then
+base_dir="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "${base_dir}" ]]; then
   echo "❌ Must be run from within a git repository."
   exit 1
 fi
 
 # Use the repository's local .gemini/tmp directory for ephemeral worktrees and logs
-pr_dir="$base_dir/.gemini/tmp/async-reviews/pr-$pr_number"
-target_dir="$pr_dir/worktree"
-log_dir="$pr_dir/logs"
+pr_dir="${base_dir}/.gemini/tmp/async-reviews/pr-${pr_number}"
+target_dir="${pr_dir}/worktree"
+log_dir="${pr_dir}/logs"
 
-cd "$base_dir" || exit 1
+cd "${base_dir}" || exit 1
 
-mkdir -p "$log_dir"
-rm -f "$log_dir/setup.exit" "$log_dir/final-assessment.exit" "$log_dir/final-assessment.md"
+mkdir -p "${log_dir}"
+rm -f "${log_dir}/setup.exit" "${log_dir}/final-assessment.exit" "${log_dir}/final-assessment.md"
 
-echo "🧹 Cleaning up previous worktree if it exists..." | tee -a "$log_dir/setup.log"
-git worktree remove -f "$target_dir" >> "$log_dir/setup.log" 2>&1 || true
-git branch -D "gemini-async-pr-$pr_number" >> "$log_dir/setup.log" 2>&1 || true
-git worktree prune >> "$log_dir/setup.log" 2>&1 || true
+echo "🧹 Cleaning up previous worktree if it exists..." | tee -a "${log_dir}/setup.log"
+git worktree remove -f "${target_dir}" >> "${log_dir}/setup.log" 2>&1 || true
+git branch -D "gemini-async-pr-${pr_number}" >> "${log_dir}/setup.log" 2>&1 || true
+git worktree prune >> "${log_dir}/setup.log" 2>&1 || true
 
-echo "📡 Fetching PR #$pr_number..." | tee -a "$log_dir/setup.log"
-if ! git fetch origin -f "pull/$pr_number/head:gemini-async-pr-$pr_number" >> "$log_dir/setup.log" 2>&1; then
-  echo 1 > "$log_dir/setup.exit"
-  echo "❌ Fetch failed. Check $log_dir/setup.log"
-  notify "Async Review Failed" "Fetch failed." "$pr_number"
+echo "📡 Fetching PR #${pr_number}..." | tee -a "${log_dir}/setup.log"
+if ! git fetch origin -f "pull/${pr_number}/head:gemini-async-pr-${pr_number}" >> "${log_dir}/setup.log" 2>&1; then
+  echo 1 > "${log_dir}/setup.exit"
+  echo "❌ Fetch failed. Check ${log_dir}/setup.log"
+  notify "Async Review Failed" "Fetch failed." "${pr_number}"
   exit 1
 fi
 
-if [[ ! -d "$target_dir" ]]; then
-  echo "🧹 Pruning missing worktrees..." | tee -a "$log_dir/setup.log"
-  git worktree prune >> "$log_dir/setup.log" 2>&1
-  echo "🌿 Creating worktree in $target_dir..." | tee -a "$log_dir/setup.log"
-  if ! git worktree add "$target_dir" "gemini-async-pr-$pr_number" >> "$log_dir/setup.log" 2>&1; then
-    echo 1 > "$log_dir/setup.exit"
-    echo "❌ Worktree creation failed. Check $log_dir/setup.log"
-    notify "Async Review Failed" "Worktree creation failed." "$pr_number"
+if [[ ! -d "${target_dir}" ]]; then
+  echo "🧹 Pruning missing worktrees..." | tee -a "${log_dir}/setup.log"
+  git worktree prune >> "${log_dir}/setup.log" 2>&1
+  echo "🌿 Creating worktree in ${target_dir}..." | tee -a "${log_dir}/setup.log"
+  if ! git worktree add "${target_dir}" "gemini-async-pr-${pr_number}" >> "${log_dir}/setup.log" 2>&1; then
+    echo 1 > "${log_dir}/setup.exit"
+    echo "❌ Worktree creation failed. Check ${log_dir}/setup.log"
+    notify "Async Review Failed" "Worktree creation failed." "${pr_number}"
     exit 1
   fi
 else
-  echo "🌿 Worktree already exists." | tee -a "$log_dir/setup.log"
+  echo "🌿 Worktree already exists." | tee -a "${log_dir}/setup.log"
 fi
-echo 0 > "$log_dir/setup.exit"
+echo 0 > "${log_dir}/setup.exit"
 
-cd "$target_dir" || exit 1
+cd "${target_dir}" || exit 1
 
-echo "🚀 Launching background tasks. Logs saving to: $log_dir"
+echo "🚀 Launching background tasks. Logs saving to: ${log_dir}"
 
 echo "  ↳ [1/5] Grabbing PR diff..."
-rm -f "$log_dir/pr-diff.exit"
-{ gh pr diff "$pr_number" > "$log_dir/pr-diff.diff" 2>&1; echo $? > "$log_dir/pr-diff.exit"; } &
+rm -f "${log_dir}/pr-diff.exit"
+{ gh pr diff "${pr_number}" > "${log_dir}/pr-diff.diff" 2>&1; echo $? > "${log_dir}/pr-diff.exit"; } &
 
 echo "  ↳ [2/5] Starting build and lint..."
-rm -f "$log_dir/build-and-lint.exit"
-{ { npm run clean && npm ci && npm run format && npm run build && npm run lint:ci && npm run typecheck; } > "$log_dir/build-and-lint.log" 2>&1; echo $? > "$log_dir/build-and-lint.exit"; } &
+rm -f "${log_dir}/build-and-lint.exit"
+{ { npm run clean && npm ci && npm run format && npm run build && npm run lint:ci && npm run typecheck; } > "${log_dir}/build-and-lint.log" 2>&1; echo $? > "${log_dir}/build-and-lint.exit"; } &
 
 # Dynamically resolve gemini binary (fallback to your nightly path)
-GEMINI_CMD=$(which gemini || echo "$HOME/.gcli/nightly/node_modules/.bin/gemini")
+GEMINI_CMD="$(command -v gemini || echo "${HOME}/.gcli/nightly/node_modules/.bin/gemini")"
+# shellcheck disable=SC2312
 POLICY_PATH="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/policy.toml"
 
 echo "  ↳ [3/5] Starting Gemini code review..."
-rm -f "$log_dir/review.exit"
-{ "$GEMINI_CMD" --policy "$POLICY_PATH" -p "/review-frontend $pr_number" > "$log_dir/review.md" 2>&1; echo $? > "$log_dir/review.exit"; } &
+rm -f "${log_dir}/review.exit"
+{ "${GEMINI_CMD}" --policy "${POLICY_PATH}" -p "/review-frontend ${pr_number}" > "${log_dir}/review.md" 2>&1; echo $? > "${log_dir}/review.exit"; } &
 
 echo "  ↳ [4/5] Starting automated tests (waiting for build and lint)..."
-rm -f "$log_dir/npm-test.exit"
+rm -f "${log_dir}/npm-test.exit"
 { 
-  while [ ! -f "$log_dir/build-and-lint.exit" ]; do sleep 1; done
-  if [ "$(cat "$log_dir/build-and-lint.exit")" == "0" ]; then
-    gh pr checks "$pr_number" > "$log_dir/ci-checks.log" 2>&1
+  while [[ ! -f "${log_dir}/build-and-lint.exit" ]]; do sleep 1; done
+  read -r build_exit < "${log_dir}/build-and-lint.exit" || build_exit=""
+  if [[ "${build_exit}" == "0" ]]; then
+    gh pr checks "${pr_number}" > "${log_dir}/ci-checks.log" 2>&1
     ci_status=$?
     
-    if [ "$ci_status" -eq 0 ]; then
-      echo "CI checks passed. Skipping local npm tests." > "$log_dir/npm-test.log"
-      echo 0 > "$log_dir/npm-test.exit"
-    elif [ "$ci_status" -eq 8 ]; then
-      echo "CI checks are still pending. Skipping local npm tests to avoid duplicate work. Please check GitHub for final results." > "$log_dir/npm-test.log"
-      echo 0 > "$log_dir/npm-test.exit"
+    if [[ "${ci_status}" -eq 0 ]]; then
+      echo "CI checks passed. Skipping local npm tests." > "${log_dir}/npm-test.log"
+      echo 0 > "${log_dir}/npm-test.exit"
+    elif [[ "${ci_status}" -eq 8 ]]; then
+      echo "CI checks are still pending. Skipping local npm tests to avoid duplicate work. Please check GitHub for final results." > "${log_dir}/npm-test.log"
+      echo 0 > "${log_dir}/npm-test.exit"
     else
-      echo "CI checks failed. Failing checks:" > "$log_dir/npm-test.log"
-      gh pr checks "$pr_number" --json name,bucket -q '.[] | select(.bucket=="fail") | .name' >> "$log_dir/npm-test.log" 2>&1
+      echo "CI checks failed. Failing checks:" > "${log_dir}/npm-test.log"
+      gh pr checks "${pr_number}" --json name,bucket -q '.[] | select(.bucket=="fail") | .name' >> "${log_dir}/npm-test.log" 2>&1
       
-      echo "Attempting to extract failing test files from CI logs..." >> "$log_dir/npm-test.log"
-      pr_branch=$(gh pr view "$pr_number" --json headRefName -q '.headRefName' 2>/dev/null)
-      run_id=$(gh run list --branch "$pr_branch" --workflow ci.yml --json databaseId -q '.[0].databaseId' 2>/dev/null)
+      echo "Attempting to extract failing test files from CI logs..." >> "${log_dir}/npm-test.log"
+      pr_branch="$(gh pr view "${pr_number}" --json headRefName -q '.headRefName' 2>/dev/null || true)"
+      run_id="$(gh run list --branch "${pr_branch}" --workflow ci.yml --json databaseId -q '.[0].databaseId' 2>/dev/null || true)"
       
       failed_files=""
-      if [[ -n "$run_id" ]]; then
-        failed_files=$(gh run view "$run_id" --log-failed 2>/dev/null | grep -o -E '(packages/[a-zA-Z0-9_-]+|integration-tests|evals)/[a-zA-Z0-9_/-]+\.test\.ts(x)?' | sort | uniq)
+      if [[ -n "${run_id}" ]]; then
+        failed_files="$(gh run view "${run_id}" --log-failed 2>/dev/null | grep -o -E '(packages/[a-zA-Z0-9_-]+|integration-tests|evals)/[a-zA-Z0-9_/-]+\.test\.ts(x)?' | sort | uniq || true)"
       fi
       
-      if [[ -n "$failed_files" ]]; then
-        echo "Found failing test files from CI:" >> "$log_dir/npm-test.log"
-        for f in $failed_files; do echo "  - $f" >> "$log_dir/npm-test.log"; done
-        echo "Running ONLY failing tests locally..." >> "$log_dir/npm-test.log"
+      if [[ -n "${failed_files}" ]]; then
+        echo "Found failing test files from CI:" >> "${log_dir}/npm-test.log"
+        for f in ${failed_files}; do echo "  - ${f}" >> "${log_dir}/npm-test.log"; done
+        echo "Running ONLY failing tests locally..." >> "${log_dir}/npm-test.log"
         
         exit_code=0
-        for file in $failed_files; do
-           if [[ "$file" == packages/* ]]; then
-             ws_dir=$(echo "$file" | cut -d'/' -f1,2)
+        for file in ${failed_files}; do
+           if [[ "${file}" == packages/* ]]; then
+             ws_dir="$(echo "${file}" | cut -d'/' -f1,2)"
            else
-             ws_dir=$(echo "$file" | cut -d'/' -f1)
+             ws_dir="$(echo "${file}" | cut -d'/' -f1)"
            fi
-           rel_file=${file#$ws_dir/}
+           rel_file="${file#"${ws_dir}"/}"
            
-           echo "--- Running $rel_file in workspace $ws_dir ---" >> "$log_dir/npm-test.log"
-           if ! npm run test:ci -w "$ws_dir" -- "$rel_file" >> "$log_dir/npm-test.log" 2>&1; then
+           echo "--- Running ${rel_file} in workspace ${ws_dir} ---" >> "${log_dir}/npm-test.log"
+           if ! npm run test:ci -w "${ws_dir}" -- "${rel_file}" >> "${log_dir}/npm-test.log" 2>&1; then
              exit_code=1
            fi
         done
-        echo $exit_code > "$log_dir/npm-test.exit"
+        echo "${exit_code}" > "${log_dir}/npm-test.exit"
       else
-        echo "Could not extract specific failing files. Skipping full local test suite as it takes too long. Please check CI logs manually." >> "$log_dir/npm-test.log"
-        echo 1 > "$log_dir/npm-test.exit"
+        echo "Could not extract specific failing files. Skipping full local test suite as it takes too long. Please check CI logs manually." >> "${log_dir}/npm-test.log"
+        echo 1 > "${log_dir}/npm-test.exit"
       fi
     fi
   else
-    echo "Skipped due to build-and-lint failure" > "$log_dir/npm-test.log"
-    echo 1 > "$log_dir/npm-test.exit"
+    echo "Skipped due to build-and-lint failure" > "${log_dir}/npm-test.log"
+    echo 1 > "${log_dir}/npm-test.exit"
   fi
 } &
 
 echo "  ↳ [5/5] Starting Gemini test execution (waiting for build and lint)..."
-rm -f "$log_dir/test-execution.exit"
+rm -f "${log_dir}/test-execution.exit"
 { 
-  while [ ! -f "$log_dir/build-and-lint.exit" ]; do sleep 1; done
-  if [ "$(cat "$log_dir/build-and-lint.exit")" == "0" ]; then
-    "$GEMINI_CMD" --policy "$POLICY_PATH" -p "Analyze the diff for PR $pr_number using 'gh pr diff $pr_number'. Instead of running the project's automated test suite (like 'npm test'), physically exercise the newly changed code in the terminal (e.g., by writing a temporary script to call the new functions, or testing the CLI command directly). Verify the feature's behavior works as expected. IMPORTANT: Do NOT modify any source code to fix errors. Just exercise the code and log the results, reporting any failures clearly. Do not ask for user confirmation." > "$log_dir/test-execution.log" 2>&1; echo $? > "$log_dir/test-execution.exit"
+  while [[ ! -f "${log_dir}/build-and-lint.exit" ]]; do sleep 1; done
+  read -r build_exit < "${log_dir}/build-and-lint.exit" || build_exit=""
+  if [[ "${build_exit}" == "0" ]]; then
+    "${GEMINI_CMD}" --policy "${POLICY_PATH}" -p "Analyze the diff for PR ${pr_number} using 'gh pr diff ${pr_number}'. Instead of running the project's automated test suite (like 'npm test'), physically exercise the newly changed code in the terminal (e.g., by writing a temporary script to call the new functions, or testing the CLI command directly). Verify the feature's behavior works as expected. IMPORTANT: Do NOT modify any source code to fix errors. Just exercise the code and log the results, reporting any failures clearly. Do not ask for user confirmation." > "${log_dir}/test-execution.log" 2>&1; echo $? > "${log_dir}/test-execution.exit"
   else
-    echo "Skipped due to build-and-lint failure" > "$log_dir/test-execution.log"
-    echo 1 > "$log_dir/test-execution.exit"
+    echo "Skipped due to build-and-lint failure" > "${log_dir}/test-execution.log"
+    echo 1 > "${log_dir}/test-execution.exit"
   fi
 } &
 
 echo "✅ All tasks dispatched!"
-echo "You can monitor progress with: tail -f $log_dir/*.log"
-echo "Read your review later at: $log_dir/review.md"
+echo "You can monitor progress with: tail -f ${log_dir}/*.log"
+echo "Read your review later at: ${log_dir}/review.md"
 
 # Polling loop to wait for all background tasks to finish
 tasks=("pr-diff" "build-and-lint" "review" "npm-test" "test-execution")
 log_files=("pr-diff.diff" "build-and-lint.log" "review.md" "npm-test.log" "test-execution.log")
 
 declare -A task_done
-for t in "${tasks[@]}"; do task_done[$t]=0; done
+for t in "${tasks[@]}"; do task_done[${t}]=0; done
 
 all_done=0
-while [[ $all_done -eq 0 ]]; do
+while [[ "${all_done}" -eq 0 ]]; do
   clear
   echo "=================================================="
-  echo "🚀 Async PR Review Status for PR #$pr_number"
+  echo "🚀 Async PR Review Status for PR #${pr_number}"
   echo "=================================================="
   echo ""
   
   all_done=1
   for i in "${!tasks[@]}"; do
-    t="${tasks[$i]}"
+    t="${tasks[${i}]}"
     
-    if [[ -f "$log_dir/$t.exit" ]]; then
-      exit_code=$(cat "$log_dir/$t.exit")
-      if [[ "$exit_code" == "0" ]]; then
-        echo "  ✅ $t: SUCCESS"
+    if [[ -f "${log_dir}/${t}.exit" ]]; then
+      read -r task_exit < "${log_dir}/${t}.exit" || task_exit=""
+      if [[ "${task_exit}" == "0" ]]; then
+        echo "  ✅ ${t}: SUCCESS"
       else
-        echo "  ❌ $t: FAILED (exit code $exit_code)"
+        echo "  ❌ ${t}: FAILED (exit code ${task_exit})"
       fi
-      task_done[$t]=1
+      task_done[${t}]=1
     else
-      echo "  ⏳ $t: RUNNING"
+      echo "  ⏳ ${t}: RUNNING"
       all_done=0
     fi
   done
@@ -195,47 +199,47 @@ while [[ $all_done -eq 0 ]]; do
   echo "=================================================="
   
   for i in "${!tasks[@]}"; do
-    t="${tasks[$i]}"
-    log_file="${log_files[$i]}"
+    t="${tasks[${i}]}"
+    log_file="${log_files[${i}]}"
     
-    if [[ ${task_done[$t]} -eq 0 ]]; then
-      if [[ -f "$log_dir/$log_file" ]]; then
+    if [[ "${task_done[${t}]}" -eq 0 ]]; then
+      if [[ -f "${log_dir}/${log_file}" ]]; then
         echo ""
-        echo "--- $t ---"
-        tail -n 5 "$log_dir/$log_file"
+        echo "--- ${t} ---"
+        tail -n 5 "${log_dir}/${log_file}"
       fi
     fi
   done
   
-  if [[ $all_done -eq 0 ]]; then
+  if [[ "${all_done}" -eq 0 ]]; then
     sleep 3
   fi
 done
 
 clear
 echo "=================================================="
-echo "🚀 Async PR Review Status for PR #$pr_number"
+echo "🚀 Async PR Review Status for PR #${pr_number}"
 echo "=================================================="
 echo ""
 for t in "${tasks[@]}"; do
-  exit_code=$(cat "$log_dir/$t.exit")
-  if [[ "$exit_code" == "0" ]]; then
-    echo "  ✅ $t: SUCCESS"
+  read -r task_exit < "${log_dir}/${t}.exit" || task_exit=""
+  if [[ "${task_exit}" == "0" ]]; then
+    echo "  ✅ ${t}: SUCCESS"
   else
-    echo "  ❌ $t: FAILED (exit code $exit_code)"
+    echo "  ❌ ${t}: FAILED (exit code ${task_exit})"
   fi
 done
 echo ""
 
 echo "⏳ Tasks complete! Synthesizing final assessment..."
-if ! "$GEMINI_CMD" --policy "$POLICY_PATH" -p "Read the review at $log_dir/review.md, the automated test logs at $log_dir/npm-test.log, and the manual test execution logs at $log_dir/test-execution.log. Summarize the results, state whether the build and tests passed based on $log_dir/build-and-lint.exit and $log_dir/npm-test.exit, and give a final recommendation for PR $pr_number." > "$log_dir/final-assessment.md" 2>&1; then
-  echo $? > "$log_dir/final-assessment.exit"
+if ! "${GEMINI_CMD}" --policy "${POLICY_PATH}" -p "Read the review at ${log_dir}/review.md, the automated test logs at ${log_dir}/npm-test.log, and the manual test execution logs at ${log_dir}/test-execution.log. Summarize the results, state whether the build and tests passed based on ${log_dir}/build-and-lint.exit and ${log_dir}/npm-test.exit, and give a final recommendation for PR ${pr_number}." > "${log_dir}/final-assessment.md" 2>&1; then
+  echo $? > "${log_dir}/final-assessment.exit"
   echo "❌ Final assessment synthesis failed!"
-  echo "Check $log_dir/final-assessment.md for details."
-  notify "Async Review Failed" "Final assessment synthesis failed." "$pr_number"
+  echo "Check ${log_dir}/final-assessment.md for details."
+  notify "Async Review Failed" "Final assessment synthesis failed." "${pr_number}"
   exit 1
 fi
 
-echo 0 > "$log_dir/final-assessment.exit"
-echo "✅ Final assessment complete! Check $log_dir/final-assessment.md"
-notify "Async Review Complete" "Review and test execution finished successfully." "$pr_number"
+echo 0 > "${log_dir}/final-assessment.exit"
+echo "✅ Final assessment complete! Check ${log_dir}/final-assessment.md"
+notify "Async Review Complete" "Review and test execution finished successfully." "${pr_number}"

.gemini/skills/async-pr-review/scripts/check-async-review.sh

@@ -1,22 +1,22 @@
 #!/bin/bash
-pr_number=$1
+pr_number="${1}"
 
-if [[ -z "$pr_number" ]]; then
+if [[ -z "${pr_number}" ]]; then
   echo "Usage: check-async-review <pr_number>"
   exit 1
 fi
 
-base_dir=$(git rev-parse --show-toplevel 2>/dev/null)
-if [[ -z "$base_dir" ]]; then
+base_dir="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "${base_dir}" ]]; then
   echo "❌ Must be run from within a git repository."
   exit 1
 fi
 
-log_dir="$base_dir/.gemini/tmp/async-reviews/pr-$pr_number/logs"
+log_dir="${base_dir}/.gemini/tmp/async-reviews/pr-${pr_number}/logs"
 
-if [[ ! -d "$log_dir" ]]; then
+if [[ ! -d "${log_dir}" ]]; then
   echo "STATUS: NOT_FOUND"
-  echo "❌ No logs found for PR #$pr_number in $log_dir"
+  echo "❌ No logs found for PR #${pr_number} in ${log_dir}"
   exit 0
 fi
 
@@ -34,32 +34,32 @@ all_done=true
 echo "STATUS: CHECKING"
 
 for task_info in "${tasks[@]}"; do
-  IFS="|" read -r task_name log_file <<< "$task_info"
+  IFS="|" read -r task_name log_file <<< "${task_info}"
   
-  file_path="$log_dir/$log_file"
-  exit_file="$log_dir/$task_name.exit"
+  file_path="${log_dir}/${log_file}"
+  exit_file="${log_dir}/${task_name}.exit"
 
-  if [[ -f "$exit_file" ]]; then
-    exit_code=$(cat "$exit_file")
-    if [[ "$exit_code" == "0" ]]; then
-      echo "✅ $task_name: SUCCESS"
+  if [[ -f "${exit_file}" ]]; then
+    read -r exit_code < "${exit_file}" || exit_code=""
+    if [[ "${exit_code}" == "0" ]]; then
+      echo "✅ ${task_name}: SUCCESS"
     else
-      echo "❌ $task_name: FAILED (exit code $exit_code)"
-      echo "   Last lines of $file_path:"
-      tail -n 3 "$file_path" | sed 's/^/      /'
+      echo "❌ ${task_name}: FAILED (exit code ${exit_code})"
+      echo "   Last lines of ${file_path}:"
+      tail -n 3 "${file_path}" | sed 's/^/      /' || true
     fi
-  elif [[ -f "$file_path" ]]; then
-    echo "⏳ $task_name: RUNNING"
+  elif [[ -f "${file_path}" ]]; then
+    echo "⏳ ${task_name}: RUNNING"
     all_done=false
   else
-    echo "➖ $task_name: NOT STARTED"
+    echo "➖ ${task_name}: NOT STARTED"
     all_done=false
   fi
 done
 
-if $all_done; then
+if [[ "${all_done}" == "true" ]]; then
   echo "STATUS: COMPLETE"
-  echo "LOG_DIR: $log_dir"
+  echo "LOG_DIR: ${log_dir}"
 else
   echo "STATUS: IN_PROGRESS"
-fi
+fi

docs/cli/plan-mode.md

@@ -39,7 +39,9 @@ To start Plan Mode while using Gemini CLI:
   the rotation when Gemini CLI is actively processing or showing confirmation
   dialogs.
 
-- **Command:** Type `/plan` in the input box.
+- **Command:** Type `/plan [goal]` in the input box. The `[goal]` is optional;
+  for example, `/plan implement authentication` will switch to Plan Mode and
+  immediately submit the prompt to the model.
 
 - **Natural Language:** Ask Gemini CLI to "start a plan for...". Gemini CLI
   calls the

docs/get-started/gemini-3.md

@@ -1,6 +1,6 @@
 # Gemini 3 Pro and Gemini 3 Flash on Gemini CLI
 
-Gemini 3 Pro and Gemini 3 Flash are available on Gemini CLI for all users!
+Learn about how you can use Gemini 3 Pro and Gemini 3 Flash on Gemini CLI.
 
 <!-- prettier-ignore -->
 > [!NOTE]

docs/reference/configuration.md

@@ -1287,6 +1287,18 @@ their corresponding top-level category object in your `settings.json` file.
   - **Description:** Maximum number of directories to search for memory.
   - **Default:** `200`
 
+- **`context.memoryBoundaryMarkers`** (array):
+  - **Description:** File or directory names that mark the boundary for
+    GEMINI.md discovery. The upward traversal stops at the first directory
+    containing any of these markers. An empty array disables parent traversal.
+  - **Default:**
+
+    ```json
+    [".git"]
+    ```
+
+  - **Requires restart:** Yes
+
 - **`context.includeDirectories`** (array):
   - **Description:** Additional directories to include in the workspace context.
     Missing directories will be skipped with a warning.
@@ -1354,6 +1366,14 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `true`
   - **Requires restart:** Yes
 
+- **`tools.shell.backgroundCompletionBehavior`** (enum):
+  - **Description:** Controls what happens when a background shell command
+    finishes. 'silent' (default): quietly exits in background. 'inject':
+    automatically returns output to agent. 'notify': shows brief message in
+    chat.
+  - **Default:** `"silent"`
+  - **Values:** `"silent"`, `"inject"`, `"notify"`
+
 - **`tools.shell.pager`** (string):
   - **Description:** The pager command to use for shell output. Defaults to
     `cat`.

docs/reference/keyboard-shortcuts.md

@@ -86,12 +86,13 @@ available combinations.
 
 #### Text Input
 
-| Command                    | Action                                                     | Keys                                                                                |
-| -------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `input.submit`             | Submit the current prompt.                                 | `Enter`                                                                             |
-| `input.newline`            | Insert a newline without submitting.                       | `Ctrl+Enter`<br />`Cmd/Win+Enter`<br />`Alt+Enter`<br />`Shift+Enter`<br />`Ctrl+J` |
-| `input.openExternalEditor` | Open the current prompt or the plan in an external editor. | `Ctrl+X`                                                                            |
-| `input.paste`              | Paste from the clipboard.                                  | `Ctrl+V`<br />`Cmd/Win+V`<br />`Alt+V`                                              |
+| Command                    | Action                                                                    | Keys                                                                                |
+| -------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `input.submit`             | Submit the current prompt.                                                | `Enter`                                                                             |
+| `input.queueMessage`       | Queue the current prompt to be processed after the current task finishes. | `Tab`                                                                               |
+| `input.newline`            | Insert a newline without submitting.                                      | `Ctrl+Enter`<br />`Cmd/Win+Enter`<br />`Alt+Enter`<br />`Shift+Enter`<br />`Ctrl+J` |
+| `input.openExternalEditor` | Open the current prompt or the plan in an external editor.                | `Ctrl+X`                                                                            |
+| `input.paste`              | Paste from the clipboard.                                                 | `Ctrl+V`<br />`Cmd/Win+V`<br />`Alt+V`                                              |
 
 #### App Controls
 

evals/subagents.eval.ts

@@ -13,8 +13,21 @@ import { evalTest, TEST_AGENTS } from './test-helper.js';
 
 const INDEX_TS = 'export const add = (a: number, b: number) => a + b;\n';
 
+// A minimal package.json is used to provide a realistic workspace anchor.
+// This prevents the agent from making incorrect assumptions about the environment
+// and helps it properly navigate or act as if it is in a standard Node.js project.
+const MOCK_PACKAGE_JSON = JSON.stringify(
+  {
+    name: 'subagent-eval-project',
+    version: '1.0.0',
+    type: 'module',
+  },
+  null,
+  2,
+);
+
 function readProjectFile(
-  rig: { testDir?: string },
+  rig: { testDir: string | null },
   relativePath: string,
 ): string {
   return fs.readFileSync(path.join(rig.testDir!, relativePath), 'utf8');
@@ -117,15 +130,7 @@ describe('subagent eval test cases', () => {
     files: {
       ...TEST_AGENTS.TESTING_AGENT.asFile(),
       'index.ts': INDEX_TS,
-      'package.json': JSON.stringify(
-        {
-          name: 'subagent-eval-project',
-          version: '1.0.0',
-          type: 'module',
-        },
-        null,
-        2,
-      ),
+      'package.json': MOCK_PACKAGE_JSON,
     },
     assert: async (rig, _result) => {
       const toolLogs = rig.readToolLogs() as Array<{
@@ -164,15 +169,7 @@ describe('subagent eval test cases', () => {
       ...TEST_AGENTS.TESTING_AGENT.asFile(),
       'index.ts': INDEX_TS,
       'README.md': 'TODO: update the README.\n',
-      'package.json': JSON.stringify(
-        {
-          name: 'subagent-eval-project',
-          version: '1.0.0',
-          type: 'module',
-        },
-        null,
-        2,
-      ),
+      'package.json': MOCK_PACKAGE_JSON,
     },
     assert: async (rig, _result) => {
       const toolLogs = rig.readToolLogs() as Array<{
@@ -190,4 +187,105 @@ describe('subagent eval test cases', () => {
       );
     },
   });
+
+  /**
+   * Checks that the main agent can correctly select the appropriate subagent
+   * from a large pool of available subagents (10 total).
+   */
+  evalTest('USUALLY_PASSES', {
+    name: 'should select the correct subagent from a pool of 10 different agents',
+    prompt: 'Please add a new SQL table migration for a user profile.',
+    files: {
+      ...TEST_AGENTS.DOCS_AGENT.asFile(),
+      ...TEST_AGENTS.TESTING_AGENT.asFile(),
+      ...TEST_AGENTS.DATABASE_AGENT.asFile(),
+      ...TEST_AGENTS.CSS_AGENT.asFile(),
+      ...TEST_AGENTS.I18N_AGENT.asFile(),
+      ...TEST_AGENTS.SECURITY_AGENT.asFile(),
+      ...TEST_AGENTS.DEVOPS_AGENT.asFile(),
+      ...TEST_AGENTS.ANALYTICS_AGENT.asFile(),
+      ...TEST_AGENTS.ACCESSIBILITY_AGENT.asFile(),
+      ...TEST_AGENTS.MOBILE_AGENT.asFile(),
+      'package.json': MOCK_PACKAGE_JSON,
+    },
+    assert: async (rig, _result) => {
+      const toolLogs = rig.readToolLogs() as Array<{
+        toolRequest: { name: string };
+      }>;
+      await rig.expectToolCallSuccess(['database-agent']);
+
+      // Ensure the generalist and other irrelevant specialists were not invoked
+      const uncalledAgents = [
+        'generalist',
+        TEST_AGENTS.DOCS_AGENT.name,
+        TEST_AGENTS.TESTING_AGENT.name,
+        TEST_AGENTS.CSS_AGENT.name,
+        TEST_AGENTS.I18N_AGENT.name,
+        TEST_AGENTS.SECURITY_AGENT.name,
+        TEST_AGENTS.DEVOPS_AGENT.name,
+        TEST_AGENTS.ANALYTICS_AGENT.name,
+        TEST_AGENTS.ACCESSIBILITY_AGENT.name,
+        TEST_AGENTS.MOBILE_AGENT.name,
+      ];
+
+      for (const agentName of uncalledAgents) {
+        expect(toolLogs.some((l) => l.toolRequest.name === agentName)).toBe(
+          false,
+        );
+      }
+    },
+  });
+
+  /**
+   * Checks that the main agent can correctly select the appropriate subagent
+   * from a large pool of available subagents, even when many irrelevant MCP tools are present.
+   *
+   * This test includes stress tests the subagent delegation with ~80 tools.
+   */
+  evalTest('USUALLY_PASSES', {
+    name: 'should select the correct subagent from a pool of 10 different agents with MCP tools present',
+    prompt: 'Please add a new SQL table migration for a user profile.',
+    setup: async (rig) => {
+      rig.addTestMcpServer('workspace-server', 'google-workspace');
+    },
+    files: {
+      ...TEST_AGENTS.DOCS_AGENT.asFile(),
+      ...TEST_AGENTS.TESTING_AGENT.asFile(),
+      ...TEST_AGENTS.DATABASE_AGENT.asFile(),
+      ...TEST_AGENTS.CSS_AGENT.asFile(),
+      ...TEST_AGENTS.I18N_AGENT.asFile(),
+      ...TEST_AGENTS.SECURITY_AGENT.asFile(),
+      ...TEST_AGENTS.DEVOPS_AGENT.asFile(),
+      ...TEST_AGENTS.ANALYTICS_AGENT.asFile(),
+      ...TEST_AGENTS.ACCESSIBILITY_AGENT.asFile(),
+      ...TEST_AGENTS.MOBILE_AGENT.asFile(),
+      'package.json': MOCK_PACKAGE_JSON,
+    },
+    assert: async (rig, _result) => {
+      const toolLogs = rig.readToolLogs() as Array<{
+        toolRequest: { name: string };
+      }>;
+      await rig.expectToolCallSuccess(['database-agent']);
+
+      // Ensure the generalist and other irrelevant specialists were not invoked
+      const uncalledAgents = [
+        'generalist',
+        TEST_AGENTS.DOCS_AGENT.name,
+        TEST_AGENTS.TESTING_AGENT.name,
+        TEST_AGENTS.CSS_AGENT.name,
+        TEST_AGENTS.I18N_AGENT.name,
+        TEST_AGENTS.SECURITY_AGENT.name,
+        TEST_AGENTS.DEVOPS_AGENT.name,
+        TEST_AGENTS.ANALYTICS_AGENT.name,
+        TEST_AGENTS.ACCESSIBILITY_AGENT.name,
+        TEST_AGENTS.MOBILE_AGENT.name,
+      ];
+
+      for (const agentName of uncalledAgents) {
+        expect(toolLogs.some((l) => l.toolRequest.name === agentName)).toBe(
+          false,
+        );
+      }
+    },
+  });
 });

evals/test-helper.ts

@@ -61,6 +61,10 @@ export async function internalEvalTest(evalCase: EvalCase) {
     try {
       rig.setup(evalCase.name, evalCase.params);
 
+      if (evalCase.setup) {
+        await evalCase.setup(rig);
+      }
+
       if (evalCase.files) {
         await setupTestFiles(rig, evalCase.files);
       }
@@ -371,6 +375,7 @@ export interface EvalCase {
   prompt: string;
   timeout?: number;
   files?: Record<string, string>;
+  setup?: (rig: TestRig) => Promise<void> | void;
   /** Conversation history to pre-load via --resume. Each entry is a message object with type, content, etc. */
   messages?: Record<string, unknown>[];
   /** Session ID for the resumed session. Auto-generated if not provided. */

packages/a2a-server/src/config/config.test.ts

@@ -424,7 +424,22 @@ describe('loadConfig', () => {
       });
     });
 
-    describe('authentication fallback', () => {
+    describe('authentication logic', () => {
+      const setupConfigMock = (refreshAuthMock: ReturnType<typeof vi.fn>) => {
+        vi.mocked(Config).mockImplementation(
+          (params: unknown) =>
+            ({
+              ...(params as object),
+              initialize: vi.fn(),
+              waitForMcpInit: vi.fn(),
+              refreshAuth: refreshAuthMock,
+              getExperiments: vi.fn().mockReturnValue({ flags: {} }),
+              getRemoteAdminSettings: vi.fn(),
+              setRemoteAdminSettings: vi.fn(),
+            }) as unknown as Config,
+        );
+      };
+
       beforeEach(() => {
         vi.stubEnv('USE_CCPA', 'true');
         vi.stubEnv('GEMINI_API_KEY', '');
@@ -434,182 +449,77 @@ describe('loadConfig', () => {
         vi.unstubAllEnvs();
       });
 
-      it('should fall back to COMPUTE_ADC in Cloud Shell if LOGIN_WITH_GOOGLE fails', async () => {
-        vi.stubEnv('CLOUD_SHELL', 'true');
-        vi.mocked(isHeadlessMode).mockReturnValue(false);
-        const refreshAuthMock = vi.fn().mockImplementation((authType) => {
-          if (authType === AuthType.LOGIN_WITH_GOOGLE) {
-            throw new FatalAuthenticationError('Non-interactive session');
-          }
-          return Promise.resolve();
-        });
-
-        // Update the mock implementation for this test
-        vi.mocked(Config).mockImplementation(
-          (params: unknown) =>
-            ({
-              ...(params as object),
-              initialize: vi.fn(),
-              waitForMcpInit: vi.fn(),
-              refreshAuth: refreshAuthMock,
-              getExperiments: vi.fn().mockReturnValue({ flags: {} }),
-              getRemoteAdminSettings: vi.fn(),
-              setRemoteAdminSettings: vi.fn(),
-            }) as unknown as Config,
-        );
-
-        await loadConfig(mockSettings, mockExtensionLoader, taskId);
-
-        expect(refreshAuthMock).toHaveBeenCalledWith(
-          AuthType.LOGIN_WITH_GOOGLE,
-        );
-        expect(refreshAuthMock).toHaveBeenCalledWith(AuthType.COMPUTE_ADC);
-      });
-
-      it('should not fall back to COMPUTE_ADC if not in cloud environment', async () => {
-        vi.mocked(isHeadlessMode).mockReturnValue(false);
-        const refreshAuthMock = vi.fn().mockImplementation((authType) => {
-          if (authType === AuthType.LOGIN_WITH_GOOGLE) {
-            throw new FatalAuthenticationError('Non-interactive session');
-          }
-          return Promise.resolve();
-        });
-
-        vi.mocked(Config).mockImplementation(
-          (params: unknown) =>
-            ({
-              ...(params as object),
-              initialize: vi.fn(),
-              waitForMcpInit: vi.fn(),
-              refreshAuth: refreshAuthMock,
-              getExperiments: vi.fn().mockReturnValue({ flags: {} }),
-              getRemoteAdminSettings: vi.fn(),
-              setRemoteAdminSettings: vi.fn(),
-            }) as unknown as Config,
-        );
-
-        await expect(
-          loadConfig(mockSettings, mockExtensionLoader, taskId),
-        ).rejects.toThrow('Non-interactive session');
-
-        expect(refreshAuthMock).toHaveBeenCalledWith(
-          AuthType.LOGIN_WITH_GOOGLE,
-        );
-        expect(refreshAuthMock).not.toHaveBeenCalledWith(AuthType.COMPUTE_ADC);
-      });
-
-      it('should skip LOGIN_WITH_GOOGLE and use COMPUTE_ADC directly in headless Cloud Shell', async () => {
-        vi.stubEnv('CLOUD_SHELL', 'true');
-        vi.mocked(isHeadlessMode).mockReturnValue(true);
-
+      it('should attempt COMPUTE_ADC by default and bypass LOGIN_WITH_GOOGLE if successful', async () => {
         const refreshAuthMock = vi.fn().mockResolvedValue(undefined);
-
-        vi.mocked(Config).mockImplementation(
-          (params: unknown) =>
-            ({
-              ...(params as object),
-              initialize: vi.fn(),
-              waitForMcpInit: vi.fn(),
-              refreshAuth: refreshAuthMock,
-              getExperiments: vi.fn().mockReturnValue({ flags: {} }),
-              getRemoteAdminSettings: vi.fn(),
-              setRemoteAdminSettings: vi.fn(),
-            }) as unknown as Config,
-        );
+        setupConfigMock(refreshAuthMock);
 
         await loadConfig(mockSettings, mockExtensionLoader, taskId);
 
+        expect(refreshAuthMock).toHaveBeenCalledWith(AuthType.COMPUTE_ADC);
         expect(refreshAuthMock).not.toHaveBeenCalledWith(
           AuthType.LOGIN_WITH_GOOGLE,
         );
-        expect(refreshAuthMock).toHaveBeenCalledWith(AuthType.COMPUTE_ADC);
       });
 
-      it('should skip LOGIN_WITH_GOOGLE and use COMPUTE_ADC directly if GEMINI_CLI_USE_COMPUTE_ADC is true', async () => {
-        vi.stubEnv('GEMINI_CLI_USE_COMPUTE_ADC', 'true');
-        vi.mocked(isHeadlessMode).mockReturnValue(false); // Even if not headless
-
-        const refreshAuthMock = vi.fn().mockResolvedValue(undefined);
-
-        vi.mocked(Config).mockImplementation(
-          (params: unknown) =>
-            ({
-              ...(params as object),
-              initialize: vi.fn(),
-              waitForMcpInit: vi.fn(),
-              refreshAuth: refreshAuthMock,
-              getExperiments: vi.fn().mockReturnValue({ flags: {} }),
-              getRemoteAdminSettings: vi.fn(),
-              setRemoteAdminSettings: vi.fn(),
-            }) as unknown as Config,
-        );
+      it('should fallback to LOGIN_WITH_GOOGLE if COMPUTE_ADC fails and interactive mode is available', async () => {
+        vi.mocked(isHeadlessMode).mockReturnValue(false);
+        const refreshAuthMock = vi.fn().mockImplementation((authType) => {
+          if (authType === AuthType.COMPUTE_ADC) {
+            return Promise.reject(new Error('ADC failed'));
+          }
+          return Promise.resolve();
+        });
+        setupConfigMock(refreshAuthMock);
 
         await loadConfig(mockSettings, mockExtensionLoader, taskId);
 
-        expect(refreshAuthMock).not.toHaveBeenCalledWith(
+        expect(refreshAuthMock).toHaveBeenCalledWith(AuthType.COMPUTE_ADC);
+        expect(refreshAuthMock).toHaveBeenCalledWith(
           AuthType.LOGIN_WITH_GOOGLE,
         );
-        expect(refreshAuthMock).toHaveBeenCalledWith(AuthType.COMPUTE_ADC);
       });
 
-      it('should throw FatalAuthenticationError in headless mode if no ADC fallback available', async () => {
+      it('should throw FatalAuthenticationError in headless mode if COMPUTE_ADC fails', async () => {
         vi.mocked(isHeadlessMode).mockReturnValue(true);
 
-        const refreshAuthMock = vi.fn().mockResolvedValue(undefined);
-
-        vi.mocked(Config).mockImplementation(
-          (params: unknown) =>
-            ({
-              ...(params as object),
-              initialize: vi.fn(),
-              waitForMcpInit: vi.fn(),
-              refreshAuth: refreshAuthMock,
-              getExperiments: vi.fn().mockReturnValue({ flags: {} }),
-              getRemoteAdminSettings: vi.fn(),
-              setRemoteAdminSettings: vi.fn(),
-            }) as unknown as Config,
-        );
+        const refreshAuthMock = vi.fn().mockImplementation((authType) => {
+          if (authType === AuthType.COMPUTE_ADC) {
+            return Promise.reject(new Error('ADC not found'));
+          }
+          return Promise.resolve();
+        });
+        setupConfigMock(refreshAuthMock);
 
         await expect(
           loadConfig(mockSettings, mockExtensionLoader, taskId),
         ).rejects.toThrow(
-          'Interactive terminal required for LOGIN_WITH_GOOGLE. Run in an interactive terminal or set GEMINI_CLI_USE_COMPUTE_ADC=true to use Application Default Credentials.',
+          'COMPUTE_ADC failed: ADC not found. (LOGIN_WITH_GOOGLE fallback skipped due to headless mode. Run in an interactive terminal to use OAuth.)',
         );
 
-        expect(refreshAuthMock).not.toHaveBeenCalled();
+        expect(refreshAuthMock).toHaveBeenCalledWith(AuthType.COMPUTE_ADC);
+        expect(refreshAuthMock).not.toHaveBeenCalledWith(
+          AuthType.LOGIN_WITH_GOOGLE,
+        );
       });
 
-      it('should include both original and fallback error when COMPUTE_ADC fallback fails', async () => {
-        vi.stubEnv('CLOUD_SHELL', 'true');
+      it('should include both original and fallback error when LOGIN_WITH_GOOGLE fallback fails', async () => {
         vi.mocked(isHeadlessMode).mockReturnValue(false);
 
         const refreshAuthMock = vi.fn().mockImplementation((authType) => {
-          if (authType === AuthType.LOGIN_WITH_GOOGLE) {
-            throw new FatalAuthenticationError('OAuth failed');
-          }
           if (authType === AuthType.COMPUTE_ADC) {
             throw new Error('ADC failed');
           }
+          if (authType === AuthType.LOGIN_WITH_GOOGLE) {
+            throw new FatalAuthenticationError('OAuth failed');
+          }
           return Promise.resolve();
         });
-
-        vi.mocked(Config).mockImplementation(
-          (params: unknown) =>
-            ({
-              ...(params as object),
-              initialize: vi.fn(),
-              waitForMcpInit: vi.fn(),
-              refreshAuth: refreshAuthMock,
-              getExperiments: vi.fn().mockReturnValue({ flags: {} }),
-              getRemoteAdminSettings: vi.fn(),
-              setRemoteAdminSettings: vi.fn(),
-            }) as unknown as Config,
-        );
+        setupConfigMock(refreshAuthMock);
 
         await expect(
           loadConfig(mockSettings, mockExtensionLoader, taskId),
         ).rejects.toThrow(
-          'OAuth failed. Fallback to COMPUTE_ADC also failed: ADC failed',
+          'OAuth failed. The initial COMPUTE_ADC attempt also failed: ADC failed',
         );
       });
     });

packages/a2a-server/src/config/config.ts

@@ -25,7 +25,6 @@ import {
   ExperimentFlags,
   isHeadlessMode,
   FatalAuthenticationError,
-  isCloudShell,
   PolicyDecision,
   PRIORITY_YOLO_ALLOW_ALL,
   type TelemetryTarget,
@@ -43,7 +42,6 @@ export async function loadConfig(
   taskId: string,
 ): Promise<Config> {
   const workspaceDir = process.cwd();
-  const adcFilePath = process.env['GOOGLE_APPLICATION_CREDENTIALS'];
 
   const folderTrust =
     settings.folderTrust === true ||
@@ -192,7 +190,7 @@ export async function loadConfig(
   await config.waitForMcpInit();
   startupProfiler.flush(config);
 
-  await refreshAuthentication(config, adcFilePath, 'Config');
+  await refreshAuthentication(config, 'Config');
 
   return config;
 }
@@ -263,75 +261,51 @@ function findEnvFile(startDir: string): string | null {
 
 async function refreshAuthentication(
   config: Config,
-  adcFilePath: string | undefined,
   logPrefix: string,
 ): Promise<void> {
   if (process.env['USE_CCPA']) {
     logger.info(`[${logPrefix}] Using CCPA Auth:`);
+
+    logger.info(`[${logPrefix}] Attempting COMPUTE_ADC first.`);
     try {
-      if (adcFilePath) {
-        path.resolve(adcFilePath);
-      }
-    } catch (e) {
-      logger.error(
-        `[${logPrefix}] USE_CCPA env var is true but unable to resolve GOOGLE_APPLICATION_CREDENTIALS file path ${adcFilePath}. Error ${e}`,
+      await config.refreshAuth(AuthType.COMPUTE_ADC);
+      logger.info(`[${logPrefix}] COMPUTE_ADC successful.`);
+    } catch (adcError) {
+      const adcMessage =
+        adcError instanceof Error ? adcError.message : String(adcError);
+      logger.info(
+        `[${logPrefix}] COMPUTE_ADC failed or not available: ${adcMessage}`,
       );
-    }
 
-    const useComputeAdc = process.env['GEMINI_CLI_USE_COMPUTE_ADC'] === 'true';
-    const isHeadless = isHeadlessMode();
-    const shouldSkipOauth = isHeadless || useComputeAdc;
+      const useComputeAdc =
+        process.env['GEMINI_CLI_USE_COMPUTE_ADC'] === 'true';
+      const isHeadless = isHeadlessMode();
 
-    if (shouldSkipOauth) {
-      if (isCloudShell() || useComputeAdc) {
-        logger.info(
-          `[${logPrefix}] Skipping LOGIN_WITH_GOOGLE due to ${isHeadless ? 'headless mode' : 'GEMINI_CLI_USE_COMPUTE_ADC'}. Attempting COMPUTE_ADC.`,
-        );
-        try {
-          await config.refreshAuth(AuthType.COMPUTE_ADC);
-          logger.info(`[${logPrefix}] COMPUTE_ADC successful.`);
-        } catch (adcError) {
-          const adcMessage =
-            adcError instanceof Error ? adcError.message : String(adcError);
-          throw new FatalAuthenticationError(
-            `COMPUTE_ADC failed: ${adcMessage}. (Skipped LOGIN_WITH_GOOGLE due to ${isHeadless ? 'headless mode' : 'GEMINI_CLI_USE_COMPUTE_ADC'})`,
-          );
-        }
-      } else {
+      if (isHeadless || useComputeAdc) {
+        const reason = isHeadless
+          ? 'headless mode'
+          : 'GEMINI_CLI_USE_COMPUTE_ADC=true';
         throw new FatalAuthenticationError(
-          `Interactive terminal required for LOGIN_WITH_GOOGLE. Run in an interactive terminal or set GEMINI_CLI_USE_COMPUTE_ADC=true to use Application Default Credentials.`,
+          `COMPUTE_ADC failed: ${adcMessage}. (LOGIN_WITH_GOOGLE fallback skipped due to ${reason}. Run in an interactive terminal to use OAuth.)`,
         );
       }
-    } else {
+
+      logger.info(
+        `[${logPrefix}] COMPUTE_ADC failed, falling back to LOGIN_WITH_GOOGLE.`,
+      );
       try {
         await config.refreshAuth(AuthType.LOGIN_WITH_GOOGLE);
       } catch (e) {
-        if (
-          e instanceof FatalAuthenticationError &&
-          (isCloudShell() || useComputeAdc)
-        ) {
-          logger.warn(
-            `[${logPrefix}] LOGIN_WITH_GOOGLE failed. Attempting COMPUTE_ADC fallback.`,
+        if (e instanceof FatalAuthenticationError) {
+          const originalMessage = e instanceof Error ? e.message : String(e);
+          throw new FatalAuthenticationError(
+            `${originalMessage}. The initial COMPUTE_ADC attempt also failed: ${adcMessage}`,
           );
-          try {
-            await config.refreshAuth(AuthType.COMPUTE_ADC);
-            logger.info(`[${logPrefix}] COMPUTE_ADC fallback successful.`);
-          } catch (adcError) {
-            logger.error(
-              `[${logPrefix}] COMPUTE_ADC fallback failed: ${adcError}`,
-            );
-            const originalMessage = e instanceof Error ? e.message : String(e);
-            const adcMessage =
-              adcError instanceof Error ? adcError.message : String(adcError);
-            throw new FatalAuthenticationError(
-              `${originalMessage}. Fallback to COMPUTE_ADC also failed: ${adcMessage}`,
-            );
-          }
-        } else {
-          throw e;
         }
+        throw e;
       }
     }
+
     logger.info(
       `[${logPrefix}] GOOGLE_CLOUD_PROJECT: ${process.env['GOOGLE_CLOUD_PROJECT']}`,
     );

packages/cli/src/acp/acpClient.test.ts

@@ -39,7 +39,6 @@ import { loadCliConfig, type CliArgs } from '../config/config.js';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { ApprovalMode } from '@google/gemini-cli-core/src/policy/types.js';
-import { SHELL_TOOL_NAME } from '@google/gemini-cli-core';
 
 vi.mock('../config/config.js', () => ({
   loadCliConfig: vi.fn(),
@@ -657,32 +656,8 @@ describe('Session', () => {
         execute: vi.fn().mockResolvedValue({ llmContent: 'Tool Result' }),
       }),
     };
-    const mockShellTool = {
-      name: SHELL_TOOL_NAME,
-      kind: 'execute',
-      build: vi.fn().mockReturnValue({
-        getDescription: () => 'Execute shell command',
-        toolLocations: () => [],
-        shouldConfirmExecute: vi.fn().mockResolvedValue(null),
-        execute: vi.fn().mockImplementation(async (abortSignal, onOutput) => {
-          if (onOutput) {
-            onOutput([[{ text: 'chunk 1' }]]);
-            onOutput([[{ text: 'chunk 2' }]]);
-          }
-          return {
-            llmContent: 'Command finished',
-            data: { exitCode: 0 },
-          };
-        }),
-      }),
-    };
     mockToolRegistry = {
-      getTool: vi.fn().mockImplementation((name) => {
-        if (name === SHELL_TOOL_NAME || name === 'shell') {
-          return mockShellTool;
-        }
-        return mockTool;
-      }),
+      getTool: vi.fn().mockReturnValue(mockTool),
     };
     mockMessageBus = {
       publish: vi.fn(),
@@ -996,101 +971,6 @@ describe('Session', () => {
     expect(result).toMatchObject({ stopReason: 'end_turn' });
   });
 
-  it('should emit terminal lifecycle events for ShellTool', async () => {
-    const stream1 = createMockStream([
-      {
-        type: StreamEventType.CHUNK,
-        value: {
-          functionCalls: [{ name: SHELL_TOOL_NAME, args: { command: 'ls' } }],
-        },
-      },
-    ]);
-    const stream2 = createMockStream([
-      {
-        type: StreamEventType.CHUNK,
-        value: {
-          candidates: [{ content: { parts: [{ text: 'Result' }] } }],
-        },
-      },
-    ]);
-
-    mockChat.sendMessageStream
-      .mockResolvedValueOnce(stream1)
-      .mockResolvedValueOnce(stream2);
-
-    const result = await session.prompt({
-      sessionId: 'session-1',
-      prompt: [{ type: 'text', text: 'Run ls' }],
-    });
-
-    expect(mockToolRegistry.getTool).toHaveBeenCalledWith(SHELL_TOOL_NAME);
-
-    // Verify terminal_info
-    expect(mockConnection.sessionUpdate).toHaveBeenCalledWith(
-      expect.objectContaining({
-        update: expect.objectContaining({
-          sessionUpdate: 'tool_call',
-          status: 'in_progress',
-          _meta: expect.objectContaining({
-            terminal_info: expect.objectContaining({
-              cwd: '/tmp',
-              terminal_id: expect.any(String),
-            }),
-          }),
-        }),
-      }),
-    );
-
-    // Verify terminal_output (2 chunks)
-    expect(mockConnection.sessionUpdate).toHaveBeenCalledWith(
-      expect.objectContaining({
-        update: expect.objectContaining({
-          sessionUpdate: 'tool_call_update',
-          status: 'in_progress',
-          _meta: expect.objectContaining({
-            terminal_output: expect.objectContaining({
-              data: 'chunk 1',
-              terminal_id: expect.any(String),
-            }),
-          }),
-        }),
-      }),
-    );
-    expect(mockConnection.sessionUpdate).toHaveBeenCalledWith(
-      expect.objectContaining({
-        update: expect.objectContaining({
-          sessionUpdate: 'tool_call_update',
-          status: 'in_progress',
-          _meta: expect.objectContaining({
-            terminal_output: expect.objectContaining({
-              data: 'chunk 2',
-              terminal_id: expect.any(String),
-            }),
-          }),
-        }),
-      }),
-    );
-
-    // Verify terminal_exit
-    expect(mockConnection.sessionUpdate).toHaveBeenCalledWith(
-      expect.objectContaining({
-        update: expect.objectContaining({
-          sessionUpdate: 'tool_call_update',
-          status: 'completed',
-          _meta: expect.objectContaining({
-            terminal_exit: expect.objectContaining({
-              exit_code: 0,
-              signal: null,
-              terminal_id: expect.any(String),
-            }),
-          }),
-        }),
-      }),
-    );
-
-    expect(result).toMatchObject({ stopReason: 'end_turn' });
-  });
-
   it('should handle tool call permission request', async () => {
     const confirmationDetails = {
       type: 'info',

packages/cli/src/acp/acpClient.ts

@@ -51,7 +51,6 @@ import {
   InvalidStreamError,
   type AgentLoopContext,
   updatePolicy,
-  SHELL_TOOL_NAME,
 } from '@google/gemini-cli-core';
 import * as acp from '@agentclientprotocol/sdk';
 import { AcpFileSystemService } from './fileSystemService.js';
@@ -1107,34 +1106,8 @@ export class Session {
             throw new Error(`Unexpected: ${resultOutcome}`);
           }
         }
-
-        if (tool.name === SHELL_TOOL_NAME) {
-          await this.sendUpdate({
-            sessionUpdate: 'tool_call_update',
-            toolCallId: callId,
-            status: 'in_progress',
-            title: displayTitle,
-            content: [],
-            _meta: {
-              terminal_info: {
-                cwd: this.context.config.getTargetDir(),
-                terminal_id: callId,
-              },
-            },
-          });
-        }
       } else {
         const content: acp.ToolCallContent[] = [];
-        let meta = undefined;
-
-        if (tool.name === SHELL_TOOL_NAME) {
-          meta = {
-            terminal_info: {
-              cwd: this.context.config.getTargetDir(),
-              terminal_id: callId,
-            },
-          };
-        }
 
         await this.sendUpdate({
           sessionUpdate: 'tool_call',
@@ -1144,92 +1117,22 @@ export class Session {
           content,
           locations: invocation.toolLocations(),
           kind: toAcpToolKind(tool.kind),
-          _meta: meta ?? undefined,
         });
       }
 
-      const updateOutput = async (output: unknown) => {
-        if (tool.name === SHELL_TOOL_NAME) {
-          let data = '';
-          if (typeof output === 'string') {
-            data = output;
-          } else if (Array.isArray(output)) {
-            data = output
-              .map((line) => {
-                if (Array.isArray(line)) {
-                  return line
-                    .map((token) => {
-                      if (
-                        typeof token === 'object' &&
-                        token !== null &&
-                        'text' in token
-                      ) {
-                        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-                        return (token as { text?: string }).text || '';
-                      }
-                      return '';
-                    })
-                    .join('');
-                }
-                return '';
-              })
-              .join('\n');
-          }
-          await this.sendUpdate({
-            sessionUpdate: 'tool_call_update',
-            toolCallId: callId,
-            status: 'in_progress',
-            content: [],
-            _meta: {
-              terminal_output: {
-                data,
-                terminal_id: callId,
-              },
-            },
-          });
-        }
-      };
-
-      const toolResult: ToolResult = await invocation.execute(
-        abortSignal,
-        updateOutput,
-      );
+      const toolResult: ToolResult = await invocation.execute(abortSignal);
       const content = toToolCallContent(toolResult);
 
       const updateContent: acp.ToolCallContent[] = content ? [content] : [];
 
-      let meta: Record<string, unknown> | undefined = undefined;
-      const isShellTool = tool.name === SHELL_TOOL_NAME;
-      const isShellError = !!(isShellTool && toolResult.data?.['isError']);
-
-      if (isShellTool) {
-        const rawExitCode = toolResult.data?.['exitCode'];
-        const exitCode: number | undefined =
-          typeof rawExitCode === 'number' ? rawExitCode : undefined;
-
-        const rawSignal = toolResult.data?.['signal'];
-        const signal: string | null =
-          typeof rawSignal === 'string' ? rawSignal : null;
-
-        meta = {
-          terminal_exit: {
-            exit_code:
-              typeof exitCode === 'number' ? exitCode : isShellError ? 1 : 0,
-            signal,
-            terminal_id: callId,
-          },
-        };
-      }
-
       await this.sendUpdate({
         sessionUpdate: 'tool_call_update',
         toolCallId: callId,
-        status: toolResult.error || isShellError ? 'failed' : 'completed',
+        status: 'completed',
         title: displayTitle,
         content: updateContent,
         locations: invocation.toolLocations(),
         kind: toAcpToolKind(tool.kind),
-        _meta: meta ?? undefined,
       });
 
       const durationMs = Date.now() - startTime;

packages/cli/src/config/config.test.ts

@@ -989,6 +989,7 @@ describe('Hierarchical Memory Loading (config.ts) - Placeholder Suite', () => {
         respectGeminiIgnore: true,
       }),
       200, // maxDirs
+      ['.git'], // boundaryMarkers
     );
   });
 
@@ -1018,6 +1019,7 @@ describe('Hierarchical Memory Loading (config.ts) - Placeholder Suite', () => {
         respectGeminiIgnore: true,
       }),
       200,
+      ['.git'], // boundaryMarkers
     );
   });
 
@@ -1046,6 +1048,7 @@ describe('Hierarchical Memory Loading (config.ts) - Placeholder Suite', () => {
         respectGeminiIgnore: true,
       }),
       200,
+      ['.git'], // boundaryMarkers
     );
   });
 });
@@ -1122,12 +1125,7 @@ describe('mergeExcludeTools', () => {
     ]);
     process.argv = ['node', 'script.js'];
     const argv = await parseArguments(createTestMergedSettings());
-    const config = await loadCliConfig(
-      settings,
-
-      'test-session',
-      argv,
-    );
+    const config = await loadCliConfig(settings, 'test-session', argv);
     expect(config.getExcludeTools()).toEqual(
       new Set(['tool1', 'tool2', 'tool3', 'tool4', 'tool5']),
     );

packages/cli/src/config/config.ts

@@ -642,6 +642,7 @@ export async function loadCliConfig(
       memoryImportFormat,
       memoryFileFiltering,
       settings.context?.discoveryMaxDirs,
+      settings.context?.memoryBoundaryMarkers,
     );
     memoryContent = result.memoryContent;
     fileCount = result.fileCount;
@@ -896,6 +897,7 @@ export async function loadCliConfig(
     loadMemoryFromIncludeDirectories:
       settings.context?.loadMemoryFromIncludeDirectories || false,
     discoveryMaxDirs: settings.context?.discoveryMaxDirs,
+    memoryBoundaryMarkers: settings.context?.memoryBoundaryMarkers,
     importFormat: settings.context?.importFormat,
     debugMode,
     question,
@@ -998,6 +1000,8 @@ export async function loadCliConfig(
     useAlternateBuffer: settings.ui?.useAlternateBuffer,
     useRipgrep: settings.tools?.useRipgrep,
     enableInteractiveShell: settings.tools?.shell?.enableInteractiveShell,
+    shellBackgroundCompletionBehavior: settings.tools?.shell
+      ?.backgroundCompletionBehavior as string | undefined,
     shellToolInactivityTimeout: settings.tools?.shell?.inactivityTimeout,
     enableShellOutputEfficiency:
       settings.tools?.shell?.enableShellOutputEfficiency ?? true,

packages/cli/src/config/extension-manager-themes.spec.ts

@@ -199,6 +199,7 @@ describe('ExtensionManager theme loading', () => {
         respectGeminiIgnore: true,
       }),
       getDiscoveryMaxDirs: () => 200,
+      getMemoryBoundaryMarkers: () => ['.git'],
       getMcpClientManager: () => ({
         getMcpInstructions: () => '',
         startExtension: vi.fn().mockResolvedValue(undefined),

packages/cli/src/config/settingsSchema.ts

@@ -1291,6 +1291,19 @@ const SETTINGS_SCHEMA = {
         description: 'Maximum number of directories to search for memory.',
         showInDialog: true,
       },
+      memoryBoundaryMarkers: {
+        type: 'array',
+        label: 'Memory Boundary Markers',
+        category: 'Context',
+        requiresRestart: true,
+        default: ['.git'] as string[],
+        description:
+          'File or directory names that mark the boundary for GEMINI.md discovery. ' +
+          'The upward traversal stops at the first directory containing any of these markers. ' +
+          'An empty array disables parent traversal.',
+        showInDialog: false,
+        items: { type: 'string' },
+      },
       includeDirectories: {
         type: 'array',
         label: 'Include Directories',
@@ -1445,6 +1458,21 @@ const SETTINGS_SCHEMA = {
             `,
             showInDialog: true,
           },
+          backgroundCompletionBehavior: {
+            type: 'enum',
+            label: 'Background Completion Behavior',
+            category: 'Tools',
+            requiresRestart: false,
+            default: 'silent',
+            description:
+              "Controls what happens when a background shell command finishes. 'silent' (default): quietly exits in background. 'inject': automatically returns output to agent. 'notify': shows brief message in chat.",
+            showInDialog: false,
+            options: [
+              { label: 'Silent', value: 'silent' },
+              { label: 'Inject', value: 'inject' },
+              { label: 'Notify', value: 'notify' },
+            ],
+          },
           pager: {
             type: 'string',
             label: 'Pager',

packages/cli/src/gemini.tsx

@@ -671,11 +671,6 @@ export async function main() {
       }
     }
 
-    // Register SessionEnd hook for graceful exit
-    registerCleanup(async () => {
-      await config.getHookSystem()?.fireSessionEndEvent(SessionEndReason.Exit);
-    });
-
     if (!input) {
       debugLogger.error(
         `No input provided via stdin. Input can be provided by piping data into gemini or using the --prompt option.`,

packages/cli/src/gemini_cleanup.test.tsx

@@ -6,7 +6,12 @@
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { main } from './gemini.js';
-import { debugLogger, type Config } from '@google/gemini-cli-core';
+import {
+  debugLogger,
+  SessionEndReason,
+  type Config,
+  type HookSystem,
+} from '@google/gemini-cli-core';
 
 vi.mock('@google/gemini-cli-core', async (importOriginal) => {
   const actual =
@@ -197,11 +202,11 @@ describe('gemini.tsx main function cleanup', () => {
       setValue: vi.fn(),
       forScope: () => ({ settings: {}, originalSettings: {}, path: '' }),
       errors: [],
-    } as any); // eslint-disable-line @typescript-eslint/no-explicit-any
+    } as unknown as ReturnType<typeof loadSettings>);
 
     vi.mocked(parseArguments).mockResolvedValue({
       promptInteractive: false,
-    } as any); // eslint-disable-line @typescript-eslint/no-explicit-any
+    } as unknown as Awaited<ReturnType<typeof parseArguments>>);
     vi.mocked(loadCliConfig).mockResolvedValue({
       isInteractive: vi.fn(() => false),
       getQuestion: vi.fn(() => 'test'),
@@ -238,7 +243,8 @@ describe('gemini.tsx main function cleanup', () => {
       setTerminalBackground: vi.fn(),
       refreshAuth: vi.fn(),
       getRemoteAdminSettings: vi.fn(() => undefined),
-    } as any); // eslint-disable-line @typescript-eslint/no-explicit-any
+      getUseAlternateBuffer: vi.fn(() => false),
+    } as unknown as Config);
 
     await main();
 
@@ -248,4 +254,80 @@ describe('gemini.tsx main function cleanup', () => {
       expect.objectContaining({ message: 'Cleanup failed' }),
     );
   });
+
+  it('should register SessionEnd hook exactly once in non-interactive mode', async () => {
+    const { loadCliConfig, parseArguments } = await import(
+      './config/config.js'
+    );
+    const { registerCleanup } = await import('./utils/cleanup.js');
+
+    const mockHookSystem = {
+      fireSessionEndEvent: vi.fn().mockResolvedValue(undefined),
+      fireSessionStartEvent: vi.fn().mockResolvedValue(undefined),
+    } as unknown as HookSystem;
+
+    vi.mocked(parseArguments).mockResolvedValue({
+      promptInteractive: false,
+    } as unknown as Awaited<ReturnType<typeof parseArguments>>);
+
+    vi.mocked(loadCliConfig).mockResolvedValue(
+      buildMockConfig({
+        getHookSystem: vi.fn(() => mockHookSystem),
+      }),
+    );
+
+    vi.spyOn(process, 'exit').mockImplementation(() => undefined as never);
+
+    await main();
+
+    const registeredCallbacks = vi
+      .mocked(registerCleanup)
+      .mock.calls.map(([fn]) => fn);
+    for (const fn of registeredCallbacks) await fn();
+    expect(mockHookSystem.fireSessionEndEvent).toHaveBeenCalledTimes(1);
+    expect(mockHookSystem.fireSessionEndEvent).toHaveBeenCalledWith(
+      SessionEndReason.Exit,
+    );
+  });
+
+  function buildMockConfig(overrides: Partial<Config> = {}): Config {
+    return {
+      isInteractive: vi.fn(() => false),
+      getQuestion: vi.fn(() => 'test'),
+      getSandbox: vi.fn(() => false),
+      getDebugMode: vi.fn(() => false),
+      getPolicyEngine: vi.fn(),
+      getMessageBus: () => ({ subscribe: vi.fn() }),
+      getEnableHooks: vi.fn(() => true),
+      getHookSystem: vi.fn(() => undefined),
+      initialize: vi.fn(),
+      storage: { initialize: vi.fn().mockResolvedValue(undefined) },
+      getContentGeneratorConfig: vi.fn(),
+      getMcpClientManager: vi.fn(),
+      getIdeMode: vi.fn(() => false),
+      getAcpMode: vi.fn(() => false),
+      getScreenReader: vi.fn(() => false),
+      getGeminiMdFileCount: vi.fn(() => 0),
+      getProjectRoot: vi.fn(() => '/'),
+      getListExtensions: vi.fn(() => false),
+      getListSessions: vi.fn(() => false),
+      getDeleteSession: vi.fn(() => undefined),
+      getToolRegistry: vi.fn(),
+      getExtensions: vi.fn(() => []),
+      getModel: vi.fn(() => 'gemini-pro'),
+      getEmbeddingModel: vi.fn(() => 'embedding-001'),
+      getApprovalMode: vi.fn(() => 'default'),
+      getCoreTools: vi.fn(() => []),
+      getTelemetryEnabled: vi.fn(() => false),
+      getTelemetryLogPromptsEnabled: vi.fn(() => false),
+      getFileFilteringRespectGitIgnore: vi.fn(() => true),
+      getOutputFormat: vi.fn(() => 'text'),
+      getUsageStatisticsEnabled: vi.fn(() => false),
+      setTerminalBackground: vi.fn(),
+      refreshAuth: vi.fn(),
+      getRemoteAdminSettings: vi.fn(() => undefined),
+      getUseAlternateBuffer: vi.fn(() => false),
+      ...overrides,
+    } as unknown as Config;
+  }
 });

packages/cli/src/services/BuiltinCommandLoader.ts

@@ -56,7 +56,7 @@ import { themeCommand } from '../ui/commands/themeCommand.js';
 import { toolsCommand } from '../ui/commands/toolsCommand.js';
 import { skillsCommand } from '../ui/commands/skillsCommand.js';
 import { settingsCommand } from '../ui/commands/settingsCommand.js';
-import { shellsCommand } from '../ui/commands/shellsCommand.js';
+import { tasksCommand } from '../ui/commands/tasksCommand.js';
 import { vimCommand } from '../ui/commands/vimCommand.js';
 import { setupGithubCommand } from '../ui/commands/setupGithubCommand.js';
 import { terminalSetupCommand } from '../ui/commands/terminalSetupCommand.js';
@@ -221,7 +221,7 @@ export class BuiltinCommandLoader implements ICommandLoader {
           : [skillsCommand]
         : []),
       settingsCommand,
-      shellsCommand,
+      tasksCommand,
       vimCommand,
       setupGithubCommand,
       terminalSetupCommand,

packages/cli/src/test-utils/mockConfig.ts

@@ -163,6 +163,7 @@ export const createMockConfig = (overrides: Partial<Config> = {}): Config =>
     getAdminSkillsEnabled: vi.fn().mockReturnValue(false),
     getDisabledSkills: vi.fn().mockReturnValue([]),
     getExperimentalJitContext: vi.fn().mockReturnValue(false),
+    getMemoryBoundaryMarkers: vi.fn().mockReturnValue(['.git']),
     getTerminalBackground: vi.fn().mockReturnValue(undefined),
     getEmbeddingModel: vi.fn().mockReturnValue('embedding-model'),
     getQuotaErrorOccurred: vi.fn().mockReturnValue(false),

packages/cli/src/test-utils/render.tsx

@@ -506,8 +506,8 @@ const baseMockUiState = {
   cleanUiDetailsVisible: false,
   allowPlanMode: true,
   activePtyId: undefined,
-  backgroundShells: new Map(),
-  backgroundShellHeight: 0,
+  backgroundTasks: new Map(),
+  backgroundTaskHeight: 0,
   quota: {
     userTier: undefined,
     stats: undefined,
@@ -534,6 +534,7 @@ export const mockAppState: AppState = {
 };
 
 const mockUIActions: UIActions = {
+  toggleAlternateBuffer: vi.fn(),
   handleThemeSelect: vi.fn(),
   closeThemeDialog: vi.fn(),
   handleThemeHighlight: vi.fn(),
@@ -568,6 +569,7 @@ const mockUIActions: UIActions = {
   handleOverageMenuChoice: vi.fn(),
   handleEmptyWalletChoice: vi.fn(),
   setQueueErrorMessage: vi.fn(),
+  addMessage: vi.fn(),
   popAllMessages: vi.fn(),
   handleApiKeySubmit: vi.fn(),
   handleApiKeyCancel: vi.fn(),
@@ -578,9 +580,9 @@ const mockUIActions: UIActions = {
   revealCleanUiDetailsTemporarily: vi.fn(),
   handleWarning: vi.fn(),
   setEmbeddedShellFocused: vi.fn(),
-  dismissBackgroundShell: vi.fn(),
-  setActiveBackgroundShellPid: vi.fn(),
-  setIsBackgroundShellListOpen: vi.fn(),
+  dismissBackgroundTask: vi.fn(),
+  setActiveBackgroundTaskPid: vi.fn(),
+  setIsBackgroundTaskListOpen: vi.fn(),
   setAuthContext: vi.fn(),
   onHintInput: vi.fn(),
   onHintBackspace: vi.fn(),

packages/cli/src/ui/App.test.tsx

@@ -88,7 +88,7 @@ describe('App', () => {
       defaultText: 'Mock Banner Text',
       warningText: '',
     },
-    backgroundShells: new Map(),
+    backgroundTasks: new Map(),
   };
 
   it('should render main content and composer when not quitting', async () => {

packages/cli/src/ui/AppContainer.test.tsx

@@ -328,13 +328,13 @@ describe('AppContainer State Management', () => {
     handleApprovalModeChange: vi.fn(),
     activePtyId: null,
     loopDetectionConfirmationRequest: null,
-    backgroundShellCount: 0,
-    isBackgroundShellVisible: false,
-    toggleBackgroundShell: vi.fn(),
-    backgroundCurrentShell: vi.fn(),
-    backgroundShells: new Map(),
-    registerBackgroundShell: vi.fn(),
-    dismissBackgroundShell: vi.fn(),
+    backgroundTaskCount: 0,
+    isBackgroundTaskVisible: false,
+    toggleBackgroundTasks: vi.fn(),
+    backgroundCurrentExecution: vi.fn(),
+    backgroundTasks: new Map(),
+    registerBackgroundTask: vi.fn(),
+    dismissBackgroundTask: vi.fn(),
   };
 
   beforeEach(() => {
@@ -2257,13 +2257,13 @@ describe('AppContainer State Management', () => {
       });
 
       it('should focus background shell on Tab when already visible (not toggle it off)', async () => {
-        const mockToggleBackgroundShell = vi.fn();
+        const mockToggleBackgroundTask = vi.fn();
         mockedUseGeminiStream.mockReturnValue({
           ...DEFAULT_GEMINI_STREAM_MOCK,
           activePtyId: null,
-          isBackgroundShellVisible: true,
-          backgroundShells: new Map([[123, { pid: 123, status: 'running' }]]),
-          toggleBackgroundShell: mockToggleBackgroundShell,
+          isBackgroundTaskVisible: true,
+          backgroundTasks: new Map([[123, { pid: 123, status: 'running' }]]),
+          toggleBackgroundTasks: mockToggleBackgroundTask,
         });
 
         await setupKeypressTest();
@@ -2277,7 +2277,7 @@ describe('AppContainer State Management', () => {
         // Should be focused
         expect(capturedUIState.embeddedShellFocused).toBe(true);
         // Should NOT have toggled (closed) the shell
-        expect(mockToggleBackgroundShell).not.toHaveBeenCalled();
+        expect(mockToggleBackgroundTask).not.toHaveBeenCalled();
 
         unmount();
       });
@@ -2285,13 +2285,13 @@ describe('AppContainer State Management', () => {
 
     describe('Background Shell Toggling (CTRL+B)', () => {
       it('should toggle background shell on Ctrl+B even if visible but not focused', async () => {
-        const mockToggleBackgroundShell = vi.fn();
+        const mockToggleBackgroundTask = vi.fn();
         mockedUseGeminiStream.mockReturnValue({
           ...DEFAULT_GEMINI_STREAM_MOCK,
           activePtyId: null,
-          isBackgroundShellVisible: true,
-          backgroundShells: new Map([[123, { pid: 123, status: 'running' }]]),
-          toggleBackgroundShell: mockToggleBackgroundShell,
+          isBackgroundTaskVisible: true,
+          backgroundTasks: new Map([[123, { pid: 123, status: 'running' }]]),
+          toggleBackgroundTasks: mockToggleBackgroundTask,
         });
 
         await setupKeypressTest();
@@ -2303,7 +2303,7 @@ describe('AppContainer State Management', () => {
         pressKey('\x02');
 
         // Should have toggled (closed) the shell
-        expect(mockToggleBackgroundShell).toHaveBeenCalled();
+        expect(mockToggleBackgroundTask).toHaveBeenCalled();
         // Should be unfocused
         expect(capturedUIState.embeddedShellFocused).toBe(false);
 
@@ -2311,28 +2311,28 @@ describe('AppContainer State Management', () => {
       });
 
       it('should show and focus background shell on Ctrl+B if hidden', async () => {
-        const mockToggleBackgroundShell = vi.fn();
+        const mockToggleBackgroundTask = vi.fn();
         const geminiStreamMock = {
           ...DEFAULT_GEMINI_STREAM_MOCK,
           activePtyId: null,
-          isBackgroundShellVisible: false,
-          backgroundShells: new Map([[123, { pid: 123, status: 'running' }]]),
-          toggleBackgroundShell: mockToggleBackgroundShell,
+          isBackgroundTaskVisible: false,
+          backgroundTasks: new Map([[123, { pid: 123, status: 'running' }]]),
+          toggleBackgroundTasks: mockToggleBackgroundTask,
         };
         mockedUseGeminiStream.mockReturnValue(geminiStreamMock);
 
         await setupKeypressTest();
 
         // Update the mock state when toggled to simulate real behavior
-        mockToggleBackgroundShell.mockImplementation(() => {
-          geminiStreamMock.isBackgroundShellVisible = true;
+        mockToggleBackgroundTask.mockImplementation(() => {
+          geminiStreamMock.isBackgroundTaskVisible = true;
         });
 
         // Press Ctrl+B
         pressKey('\x02');
 
         // Should have toggled (shown) the shell
-        expect(mockToggleBackgroundShell).toHaveBeenCalled();
+        expect(mockToggleBackgroundTask).toHaveBeenCalled();
         // Should be focused
         expect(capturedUIState.embeddedShellFocused).toBe(true);
 

packages/cli/src/ui/AppContainer.tsx

@@ -68,8 +68,10 @@ import {
   writeToStdout,
   disableMouseEvents,
   enterAlternateScreen,
+  exitAlternateScreen,
   enableMouseEvents,
   disableLineWrapping,
+  enableLineWrapping,
   shouldEnterAlternateScreen,
   startupProfiler,
   SessionStartSource,
@@ -110,7 +112,7 @@ import { computeTerminalTitle } from '../utils/windowTitle.js';
 import { useTextBuffer } from './components/shared/text-buffer.js';
 import { useLogger } from './hooks/useLogger.js';
 import { useGeminiStream } from './hooks/useGeminiStream.js';
-import { type BackgroundShell } from './hooks/shellCommandProcessor.js';
+import { type BackgroundTask } from './hooks/useExecutionLifecycle.js';
 import { useVim } from './hooks/vim.js';
 import { type LoadableSettingScope, SettingScope } from '../config/settings.js';
 import { type InitializationResult } from '../core/initializer.js';
@@ -151,7 +153,7 @@ import { useInputHistoryStore } from './hooks/useInputHistoryStore.js';
 import { useBanner } from './hooks/useBanner.js';
 import { useTerminalSetupPrompt } from './utils/terminalSetup.js';
 import { useHookDisplayState } from './hooks/useHookDisplayState.js';
-import { useBackgroundShellManager } from './hooks/useBackgroundShellManager.js';
+import { useBackgroundTaskManager } from './hooks/useBackgroundTaskManager.js';
 import {
   WARNING_PROMPT_DURATION_MS,
   QUEUE_ERROR_DISPLAY_DURATION_MS,
@@ -213,7 +215,7 @@ export const AppContainer = (props: AppContainerProps) => {
   });
 
   useMemoryMonitor(historyManager);
-  const isAlternateBuffer = config.getUseAlternateBuffer();
+  const [isAlternateBuffer, setIsAlternateBuffer] = useState(config.getUseAlternateBuffer());
   const [corgiMode, setCorgiMode] = useState(false);
   const [forceRerenderKey, setForceRerenderKey] = useState(0);
   const [debugMessage, setDebugMessage] = useState<string>('');
@@ -232,9 +234,9 @@ export const AppContainer = (props: AppContainerProps) => {
   );
   const [copyModeEnabled, setCopyModeEnabled] = useState(false);
   const [pendingRestorePrompt, setPendingRestorePrompt] = useState(false);
-  const toggleBackgroundShellRef = useRef<() => void>(() => {});
-  const isBackgroundShellVisibleRef = useRef<boolean>(false);
-  const backgroundShellsRef = useRef<Map<number, BackgroundShell>>(new Map());
+  const toggleBackgroundTasksRef = useRef<() => void>(() => {});
+  const isBackgroundTaskVisibleRef = useRef<boolean>(false);
+  const backgroundTasksRef = useRef<Map<number, BackgroundTask>>(new Map());
 
   const [adminSettingsChanged, setAdminSettingsChanged] = useState(false);
 
@@ -454,7 +456,7 @@ export const AppContainer = (props: AppContainerProps) => {
 
       // Kill all background shells
       await Promise.all(
-        Array.from(backgroundShellsRef.current.keys()).map((pid) =>
+        Array.from(backgroundTasksRef.current.keys()).map((pid) =>
           ShellExecutionService.kill(pid),
         ),
       );
@@ -865,7 +867,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
 
   const { toggleVimEnabled } = useVimMode();
 
-  const setIsBackgroundShellListOpenRef = useRef<(open: boolean) => void>(
+  const setIsBackgroundTaskListOpenRef = useRef<(open: boolean) => void>(
     () => {},
   );
   const [shortcutsHelpVisible, setShortcutsHelpVisible] = useState(false);
@@ -900,14 +902,14 @@ Logging in with Google... Restarting Gemini CLI to continue.
       toggleDebugProfiler,
       dispatchExtensionStateUpdate,
       addConfirmUpdateExtensionRequest,
-      toggleBackgroundShell: () => {
-        toggleBackgroundShellRef.current();
-        if (!isBackgroundShellVisibleRef.current) {
+      toggleBackgroundTasks: () => {
+        toggleBackgroundTasksRef.current();
+        if (!isBackgroundTaskVisibleRef.current) {
           setEmbeddedShellFocused(true);
-          if (backgroundShellsRef.current.size > 1) {
-            setIsBackgroundShellListOpenRef.current(true);
+          if (backgroundTasksRef.current.size > 1) {
+            setIsBackgroundTaskListOpenRef.current(true);
           } else {
-            setIsBackgroundShellListOpenRef.current(false);
+            setIsBackgroundTaskListOpenRef.current(false);
           }
         }
       },
@@ -1079,7 +1081,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
 
   useEffect(() => {
     const hintListener = (text: string, source: InjectionSource) => {
-      if (source !== 'user_steering') {
+      if (source !== 'user_steering' && source !== 'background_completion') {
         return;
       }
       pendingHintsRef.current.push(text);
@@ -1103,12 +1105,12 @@ Logging in with Google... Restarting Gemini CLI to continue.
     activePtyId,
     loopDetectionConfirmationRequest,
     lastOutputTime,
-    backgroundShellCount,
-    isBackgroundShellVisible,
-    toggleBackgroundShell,
-    backgroundCurrentShell,
-    backgroundShells,
-    dismissBackgroundShell,
+    backgroundTaskCount,
+    isBackgroundTaskVisible,
+    toggleBackgroundTasks,
+    backgroundCurrentExecution,
+    backgroundTasks,
+    dismissBackgroundTask,
     retryStatus,
   } = useGeminiStream(
     config.getGeminiClient(),
@@ -1142,27 +1144,27 @@ Logging in with Google... Restarting Gemini CLI to continue.
     [pendingHistoryItems],
   );
 
-  toggleBackgroundShellRef.current = toggleBackgroundShell;
-  isBackgroundShellVisibleRef.current = isBackgroundShellVisible;
-  backgroundShellsRef.current = backgroundShells;
+  toggleBackgroundTasksRef.current = toggleBackgroundTasks;
+  isBackgroundTaskVisibleRef.current = isBackgroundTaskVisible;
+  backgroundTasksRef.current = backgroundTasks;
 
   const {
-    activeBackgroundShellPid,
-    setIsBackgroundShellListOpen,
-    isBackgroundShellListOpen,
-    setActiveBackgroundShellPid,
-    backgroundShellHeight,
-  } = useBackgroundShellManager({
-    backgroundShells,
-    backgroundShellCount,
-    isBackgroundShellVisible,
+    activeBackgroundTaskPid,
+    setIsBackgroundTaskListOpen,
+    isBackgroundTaskListOpen,
+    setActiveBackgroundTaskPid,
+    backgroundTaskHeight,
+  } = useBackgroundTaskManager({
+    backgroundTasks,
+    backgroundTaskCount,
+    isBackgroundTaskVisible,
     activePtyId,
     embeddedShellFocused,
     setEmbeddedShellFocused,
     terminalHeight,
   });
 
-  setIsBackgroundShellListOpenRef.current = setIsBackgroundShellListOpen;
+  setIsBackgroundTaskListOpenRef.current = setIsBackgroundTaskListOpen;
 
   const lastOutputTimeRef = useRef(0);
 
@@ -1434,7 +1436,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
   // Compute available terminal height based on stable controls measurement
   const availableTerminalHeight = Math.max(
     0,
-    terminalHeight - stableControlsHeight - backgroundShellHeight - 1,
+    terminalHeight - stableControlsHeight - backgroundTaskHeight - 1,
   );
 
   config.setShellExecutionConfig({
@@ -1550,6 +1552,23 @@ Logging in with Google... Restarting Gemini CLI to continue.
     type: TransientMessageType;
   }>(WARNING_PROMPT_DURATION_MS);
 
+  const [shownBufferToggleHint, setShownBufferToggleHint] = useState(false);
+
+  useEffect(() => {
+    if (isAlternateBuffer) return;
+
+    const isLongHistory = historyManager.history.length > 15;
+    const isComplexPrompt = buffer.text.length > 200 || buffer.text.includes('\n');
+
+    if ((isLongHistory || isComplexPrompt) && !shownBufferToggleHint) {
+      showTransientMessage({ 
+        text: 'Tip: Press Alt+T to toggle full-screen mode for better scrolling/editing', 
+        type: TransientMessageType.Hint 
+      });
+      setShownBufferToggleHint(true);
+    }
+  }, [historyManager.history.length, buffer.text, isAlternateBuffer, shownBufferToggleHint, showTransientMessage]);
+
   const {
     isFolderTrustDialogOpen,
     discoveryResults: folderDiscoveryResults,
@@ -1700,6 +1719,11 @@ Logging in with Google... Restarting Gemini CLI to continue.
         return true;
       }
 
+      if (keyMatchers[Command.TOGGLE_BUFFER_MODE](key)) {
+        toggleAlternateBuffer();
+        return true;
+      }
+
       if (keyMatchers[Command.QUIT](key)) {
         // If the user presses Ctrl+C, we want to cancel any ongoing requests.
         // This should happen regardless of the count.
@@ -1790,7 +1814,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       } else if (
         (keyMatchers[Command.FOCUS_SHELL_INPUT](key) ||
           keyMatchers[Command.UNFOCUS_BACKGROUND_SHELL_LIST](key)) &&
-        (activePtyId || (isBackgroundShellVisible && backgroundShells.size > 0))
+        (activePtyId || (isBackgroundTaskVisible && backgroundTasks.size > 0))
       ) {
         if (embeddedShellFocused) {
           const capturedTime = lastOutputTimeRef.current;
@@ -1811,12 +1835,12 @@ Logging in with Google... Restarting Gemini CLI to continue.
 
         const isIdle = Date.now() - lastOutputTimeRef.current >= 100;
 
-        if (isIdle && !activePtyId && !isBackgroundShellVisible) {
+        if (isIdle && !activePtyId && !isBackgroundTaskVisible) {
           if (tabFocusTimeoutRef.current)
             clearTimeout(tabFocusTimeoutRef.current);
-          toggleBackgroundShell();
+          toggleBackgroundTasks();
           setEmbeddedShellFocused(true);
-          if (backgroundShells.size > 1) setIsBackgroundShellListOpen(true);
+          if (backgroundTasks.size > 1) setIsBackgroundTaskListOpen(true);
           return true;
         }
 
@@ -1833,15 +1857,15 @@ Logging in with Google... Restarting Gemini CLI to continue.
         return false;
       } else if (keyMatchers[Command.TOGGLE_BACKGROUND_SHELL](key)) {
         if (activePtyId) {
-          backgroundCurrentShell();
+          backgroundCurrentExecution();
           // After backgrounding, we explicitly do NOT show or focus the background UI.
         } else {
-          toggleBackgroundShell();
+          toggleBackgroundTasks();
           // Toggle focus based on intent: if we were hiding, unfocus; if showing, focus.
-          if (!isBackgroundShellVisible && backgroundShells.size > 0) {
+          if (!isBackgroundTaskVisible && backgroundTasks.size > 0) {
             setEmbeddedShellFocused(true);
-            if (backgroundShells.size > 1) {
-              setIsBackgroundShellListOpen(true);
+            if (backgroundTasks.size > 1) {
+              setIsBackgroundTaskListOpen(true);
             }
           } else {
             setEmbeddedShellFocused(false);
@@ -1849,11 +1873,11 @@ Logging in with Google... Restarting Gemini CLI to continue.
         }
         return true;
       } else if (keyMatchers[Command.TOGGLE_BACKGROUND_SHELL_LIST](key)) {
-        if (backgroundShells.size > 0 && isBackgroundShellVisible) {
+        if (backgroundTasks.size > 0 && isBackgroundTaskVisible) {
           if (!embeddedShellFocused) {
             setEmbeddedShellFocused(true);
           }
-          setIsBackgroundShellListOpen(true);
+          setIsBackgroundTaskListOpen(true);
         }
         return true;
       }
@@ -1878,11 +1902,11 @@ Logging in with Google... Restarting Gemini CLI to continue.
       tabFocusTimeoutRef,
       isAlternateBuffer,
       shortcutsHelpVisible,
-      backgroundCurrentShell,
-      toggleBackgroundShell,
-      backgroundShells,
-      isBackgroundShellVisible,
-      setIsBackgroundShellListOpen,
+      backgroundCurrentExecution,
+      toggleBackgroundTasks,
+      backgroundTasks,
+      isBackgroundTaskVisible,
+      setIsBackgroundTaskListOpen,
       lastOutputTimeRef,
       showTransientMessage,
       settings.merged.general.devtools,
@@ -2055,7 +2079,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
   const showStatusWit = loadingPhrases === 'witty' || loadingPhrases === 'all';
 
   const showLoadingIndicator =
-    (!embeddedShellFocused || isBackgroundShellVisible) &&
+    (!embeddedShellFocused || isBackgroundTaskVisible) &&
     streamingState === StreamingState.Responding &&
     !hasPendingActionRequired;
 
@@ -2204,8 +2228,11 @@ Logging in with Google... Restarting Gemini CLI to continue.
     };
   }, [config, refreshStatic]);
 
+  const showIsAlternateBufferHint = (historyManager.history.length > 15 || buffer.text.length > 200 || buffer.text.includes('\n')) && !isAlternateBuffer;
+
   const uiState: UIState = useMemo(
     () => ({
+      isAlternateBuffer,
       history: historyManager.history,
       historyManager,
       isThemeDialogOpen,
@@ -2313,8 +2340,8 @@ Logging in with Google... Restarting Gemini CLI to continue.
       isRestarting,
       extensionsUpdateState,
       activePtyId,
-      backgroundShellCount,
-      isBackgroundShellVisible,
+      backgroundTaskCount,
+      isBackgroundTaskVisible,
       embeddedShellFocused,
       showDebugProfiler,
       customDialog,
@@ -2324,13 +2351,14 @@ Logging in with Google... Restarting Gemini CLI to continue.
       bannerVisible,
       terminalBackgroundColor: config.getTerminalBackground(),
       settingsNonce,
-      backgroundShells,
-      activeBackgroundShellPid,
-      backgroundShellHeight,
-      isBackgroundShellListOpen,
+      backgroundTasks,
+      activeBackgroundTaskPid,
+      backgroundTaskHeight,
+      isBackgroundTaskListOpen,
       adminSettingsChanged,
       newAgents,
       showIsExpandableHint,
+      showIsAlternateBufferHint,
       hintMode:
         config.isModelSteeringEnabled() && isToolExecuting(pendingHistoryItems),
       hintBuffer: '',
@@ -2436,8 +2464,8 @@ Logging in with Google... Restarting Gemini CLI to continue.
       currentModel,
       extensionsUpdateState,
       activePtyId,
-      backgroundShellCount,
-      isBackgroundShellVisible,
+      backgroundTaskCount,
+      isBackgroundTaskVisible,
       historyManager,
       embeddedShellFocused,
       showDebugProfiler,
@@ -2450,13 +2478,15 @@ Logging in with Google... Restarting Gemini CLI to continue.
       bannerVisible,
       config,
       settingsNonce,
-      backgroundShellHeight,
-      isBackgroundShellListOpen,
-      activeBackgroundShellPid,
-      backgroundShells,
+      backgroundTaskHeight,
+      isBackgroundTaskListOpen,
+      activeBackgroundTaskPid,
+      backgroundTasks,
       adminSettingsChanged,
       newAgents,
       showIsExpandableHint,
+      showIsAlternateBufferHint,
+      isAlternateBuffer,
     ],
   );
 
@@ -2465,6 +2495,31 @@ Logging in with Google... Restarting Gemini CLI to continue.
     [setShowPrivacyNotice],
   );
 
+  const toggleAlternateBuffer = useCallback(() => {
+    setIsAlternateBuffer(prev => {
+      const next = !prev;
+      if (next) {
+        enterAlternateScreen();
+        enableMouseEvents();
+        disableLineWrapping();
+      } else {
+        exitAlternateScreen();
+        disableMouseEvents();
+        enableLineWrapping();
+        writeToStdout('\x1b[2J\x1b[H');
+      }
+      process.stdout.emit('resize');
+
+      // Give a tick for resize to process, then trigger remount to force full redraw
+      setImmediate(() => {
+        refreshStatic();
+        setForceRerenderKey((prev) => prev + 1);
+      });
+
+      return next;
+    });
+  }, [setIsAlternateBuffer, refreshStatic, setForceRerenderKey]);
+
   const uiActions: UIActions = useMemo(
     () => ({
       handleThemeSelect,
@@ -2476,6 +2531,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       handleEditorSelect,
       exitEditorDialog,
       exitPrivacyNotice,
+      toggleAlternateBuffer,
       closeSettingsDialog,
       closeModelDialog,
       openAgentConfigDialog,
@@ -2502,6 +2558,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       handleResumeSession,
       handleDeleteSession,
       setQueueErrorMessage,
+      addMessage,
       popAllMessages,
       handleApiKeySubmit,
       handleApiKeyCancel,
@@ -2512,9 +2569,9 @@ Logging in with Google... Restarting Gemini CLI to continue.
       revealCleanUiDetailsTemporarily,
       handleWarning,
       setEmbeddedShellFocused,
-      dismissBackgroundShell,
-      setActiveBackgroundShellPid,
-      setIsBackgroundShellListOpen,
+      dismissBackgroundTask,
+      setActiveBackgroundTaskPid,
+      setIsBackgroundTaskListOpen,
       setAuthContext,
       onHintInput: () => {},
       onHintBackspace: () => {},
@@ -2593,6 +2650,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
       handleResumeSession,
       handleDeleteSession,
       setQueueErrorMessage,
+      addMessage,
       popAllMessages,
       handleApiKeySubmit,
       handleApiKeyCancel,
@@ -2603,15 +2661,16 @@ Logging in with Google... Restarting Gemini CLI to continue.
       revealCleanUiDetailsTemporarily,
       handleWarning,
       setEmbeddedShellFocused,
-      dismissBackgroundShell,
-      setActiveBackgroundShellPid,
-      setIsBackgroundShellListOpen,
+      dismissBackgroundTask,
+      setActiveBackgroundTaskPid,
+      setIsBackgroundTaskListOpen,
       setAuthContext,
       setAccountSuspensionInfo,
       newAgents,
       config,
       historyManager,
       getPreferredEditor,
+      toggleAlternateBuffer,
     ],
   );
 

packages/cli/src/ui/commands/chatCommand.ts

@@ -75,6 +75,7 @@ const listCommand: SlashCommand = {
   description: 'List saved manual conversation checkpoints',
   kind: CommandKind.BUILT_IN,
   autoExecute: true,
+  takesArgs: false,
   action: async (context): Promise<void> => {
     const chatDetails = await getSavedChatTags(context, false);
 
@@ -406,14 +407,24 @@ export const chatResumeSubCommands: SlashCommand[] = [
   checkpointCompatibilityCommand,
 ];
 
+import { parseSlashCommand } from '../../utils/commands.js';
+
 export const chatCommand: SlashCommand = {
   name: 'chat',
   description: 'Browse auto-saved conversations and manage chat checkpoints',
   kind: CommandKind.BUILT_IN,
   autoExecute: true,
-  action: async () => ({
-    type: 'dialog',
-    dialog: 'sessionBrowser',
-  }),
+  action: async (context, args) => {
+    if (args) {
+      const parsed = parseSlashCommand(`/${args}`, chatResumeSubCommands);
+      if (parsed.commandToExecute?.action) {
+        return parsed.commandToExecute.action(context, parsed.args);
+      }
+    }
+    return {
+      type: 'dialog',
+      dialog: 'sessionBrowser',
+    };
+  },
   subCommands: chatResumeSubCommands,
 };

packages/cli/src/ui/commands/extensionsCommand.ts

@@ -789,6 +789,7 @@ const listExtensionsCommand: SlashCommand = {
   description: 'List active extensions',
   kind: CommandKind.BUILT_IN,
   autoExecute: true,
+  takesArgs: false,
   action: listAction,
 };
 
@@ -849,6 +850,7 @@ const exploreExtensionsCommand: SlashCommand = {
   description: 'Open extensions page in your browser',
   kind: CommandKind.BUILT_IN,
   autoExecute: true,
+  takesArgs: false,
   action: exploreAction,
 };
 
@@ -870,6 +872,8 @@ const configCommand: SlashCommand = {
   action: configAction,
 };
 
+import { parseSlashCommand } from '../../utils/commands.js';
+
 export function extensionsCommand(
   enableExtensionReloading?: boolean,
 ): SlashCommand {
@@ -883,20 +887,29 @@ export function extensionsCommand(
         configCommand,
       ]
     : [];
+  const subCommands = [
+    listExtensionsCommand,
+    updateExtensionsCommand,
+    exploreExtensionsCommand,
+    reloadCommand,
+    ...conditionalCommands,
+  ];
+
   return {
     name: 'extensions',
     description: 'Manage extensions',
     kind: CommandKind.BUILT_IN,
     autoExecute: false,
-    subCommands: [
-      listExtensionsCommand,
-      updateExtensionsCommand,
-      exploreExtensionsCommand,
-      reloadCommand,
-      ...conditionalCommands,
-    ],
-    action: (context, args) =>
+    subCommands,
+    action: async (context, args) => {
+      if (args) {
+        const parsed = parseSlashCommand(`/${args}`, subCommands);
+        if (parsed.commandToExecute?.action) {
+          return parsed.commandToExecute.action(context, parsed.args);
+        }
+      }
       // Default to list if no subcommand is provided
-      listExtensionsCommand.action!(context, args),
+      return listExtensionsCommand.action!(context, args);
+    },
   };
 }

packages/cli/src/ui/commands/mcpCommand.test.ts

@@ -17,7 +17,7 @@ import {
 } from '@google/gemini-cli-core';
 
 import type { CallableTool } from '@google/genai';
-import { MessageType } from '../types.js';
+import { MessageType, type HistoryItemMcpStatus } from '../types.js';
 
 vi.mock('@google/gemini-cli-core', async (importOriginal) => {
   const actual =
@@ -280,5 +280,41 @@ describe('mcpCommand', () => {
         }),
       );
     });
+
+    it('should filter servers by name when an argument is provided to list', async () => {
+      await mcpCommand.action!(mockContext, 'list server1');
+
+      expect(mockContext.ui.addItem).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageType.MCP_STATUS,
+          servers: expect.objectContaining({
+            server1: expect.any(Object),
+          }),
+        }),
+      );
+
+      // Should NOT contain server2 or server3
+      const call = vi.mocked(mockContext.ui.addItem).mock
+        .calls[0][0] as HistoryItemMcpStatus;
+      expect(Object.keys(call.servers)).toEqual(['server1']);
+    });
+
+    it('should filter servers by name and show descriptions when an argument is provided to desc', async () => {
+      await mcpCommand.action!(mockContext, 'desc server2');
+
+      expect(mockContext.ui.addItem).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: MessageType.MCP_STATUS,
+          showDescriptions: true,
+          servers: expect.objectContaining({
+            server2: expect.any(Object),
+          }),
+        }),
+      );
+
+      const call = vi.mocked(mockContext.ui.addItem).mock
+        .calls[0][0] as HistoryItemMcpStatus;
+      expect(Object.keys(call.servers)).toEqual(['server2']);
+    });
   });
 });

packages/cli/src/ui/commands/mcpCommand.ts

@@ -31,6 +31,7 @@ import {
   canLoadServer,
 } from '../../config/mcp/mcpServerEnablement.js';
 import { loadSettings } from '../../config/settings.js';
+import { parseSlashCommand } from '../../utils/commands.js';
 
 const authCommand: SlashCommand = {
   name: 'auth',
@@ -177,6 +178,7 @@ const listAction = async (
   context: CommandContext,
   showDescriptions = false,
   showSchema = false,
+  serverNameFilter?: string,
 ): Promise<void | MessageActionReturn> => {
   const agentContext = context.services.agentContext;
   const config = agentContext?.config;
@@ -199,11 +201,25 @@ const listAction = async (
     };
   }
 
-  const mcpServers = config.getMcpClientManager()?.getMcpServers() || {};
-  const serverNames = Object.keys(mcpServers);
+  let mcpServers = config.getMcpClientManager()?.getMcpServers() || {};
   const blockedMcpServers =
     config.getMcpClientManager()?.getBlockedMcpServers() || [];
 
+  if (serverNameFilter) {
+    const filter = serverNameFilter.trim().toLowerCase();
+    if (filter) {
+      mcpServers = Object.fromEntries(
+        Object.entries(mcpServers).filter(
+          ([name]) =>
+            name.toLowerCase().includes(filter) ||
+            normalizeServerId(name).includes(filter),
+        ),
+      );
+    }
+  }
+
+  const serverNames = Object.keys(mcpServers);
+
   const connectingServers = serverNames.filter(
     (name) => getMCPServerStatus(name) === MCPServerStatus.CONNECTING,
   );
@@ -306,7 +322,7 @@ const listCommand: SlashCommand = {
   description: 'List configured MCP servers and tools',
   kind: CommandKind.BUILT_IN,
   autoExecute: true,
-  action: (context) => listAction(context),
+  action: (context, args) => listAction(context, false, false, args),
 };
 
 const descCommand: SlashCommand = {
@@ -315,7 +331,7 @@ const descCommand: SlashCommand = {
   description: 'List configured MCP servers and tools with descriptions',
   kind: CommandKind.BUILT_IN,
   autoExecute: true,
-  action: (context) => listAction(context, true),
+  action: (context, args) => listAction(context, true, false, args),
 };
 
 const schemaCommand: SlashCommand = {
@@ -324,7 +340,7 @@ const schemaCommand: SlashCommand = {
     'List configured MCP servers and tools with descriptions and schemas',
   kind: CommandKind.BUILT_IN,
   autoExecute: true,
-  action: (context) => listAction(context, true, true),
+  action: (context, args) => listAction(context, true, true, args),
 };
 
 const reloadCommand: SlashCommand = {
@@ -333,6 +349,7 @@ const reloadCommand: SlashCommand = {
   description: 'Reloads MCP servers',
   kind: CommandKind.BUILT_IN,
   autoExecute: true,
+  takesArgs: false,
   action: async (
     context: CommandContext,
   ): Promise<void | SlashCommandActionReturn> => {
@@ -530,5 +547,18 @@ export const mcpCommand: SlashCommand = {
     enableCommand,
     disableCommand,
   ],
-  action: async (context: CommandContext) => listAction(context),
+  action: async (
+    context: CommandContext,
+    args: string,
+  ): Promise<void | SlashCommandActionReturn> => {
+    if (args) {
+      const parsed = parseSlashCommand(`/${args}`, mcpCommand.subCommands!);
+      if (parsed.commandToExecute?.action) {
+        return parsed.commandToExecute.action(context, parsed.args);
+      }
+      // If no subcommand matches, treat the whole args as a filter for list
+      return listAction(context, false, false, args);
+    }
+    return listAction(context);
+  },
 };

packages/cli/src/ui/commands/planCommand.test.ts

@@ -104,6 +104,47 @@ describe('planCommand', () => {
     );
   });
 
+  it('should not return a submit_prompt action if arguments are empty', async () => {
+    vi.mocked(
+      mockContext.services.agentContext!.config.isPlanEnabled,
+    ).mockReturnValue(true);
+    mockContext.invocation = {
+      raw: '/plan',
+      name: 'plan',
+      args: '',
+    };
+
+    if (!planCommand.action) throw new Error('Action missing');
+    const result = await planCommand.action(mockContext, '');
+
+    expect(result).toBeUndefined();
+    expect(
+      mockContext.services.agentContext!.config.setApprovalMode,
+    ).toHaveBeenCalledWith(ApprovalMode.PLAN);
+  });
+
+  it('should return a submit_prompt action if arguments are provided', async () => {
+    vi.mocked(
+      mockContext.services.agentContext!.config.isPlanEnabled,
+    ).mockReturnValue(true);
+    mockContext.invocation = {
+      raw: '/plan implement auth',
+      name: 'plan',
+      args: 'implement auth',
+    };
+
+    if (!planCommand.action) throw new Error('Action missing');
+    const result = await planCommand.action(mockContext, 'implement auth');
+
+    expect(result).toEqual({
+      type: 'submit_prompt',
+      content: 'implement auth',
+    });
+    expect(
+      mockContext.services.agentContext!.config.setApprovalMode,
+    ).toHaveBeenCalledWith(ApprovalMode.PLAN);
+  });
+
   it('should display the approved plan from config', async () => {
     const mockPlanPath = '/mock/plans/dir/approved-plan.md';
     vi.mocked(

packages/cli/src/ui/commands/planCommand.ts

@@ -66,6 +66,13 @@ export const planCommand: SlashCommand = {
       coreEvents.emitFeedback('info', 'Switched to Plan Mode.');
     }
 
+    if (context.invocation?.args) {
+      return {
+        type: 'submit_prompt',
+        content: context.invocation.args,
+      };
+    }
+
     const approvedPlanPath = config.getApprovedPlanPath();
 
     if (!approvedPlanPath) {
@@ -86,12 +93,14 @@ export const planCommand: SlashCommand = {
         type: MessageType.GEMINI,
         text: partToString(content.llmContent),
       });
+      return;
     } catch (error) {
       coreEvents.emitFeedback(
         'error',
         `Failed to read approved plan at ${approvedPlanPath}: ${error}`,
         error,
       );
+      return;
     }
   },
   subCommands: [
@@ -100,6 +109,7 @@ export const planCommand: SlashCommand = {
       description: 'Copy the currently approved plan to your clipboard',
       kind: CommandKind.BUILT_IN,
       autoExecute: true,
+      takesArgs: false,
       action: copyAction,
     },
   ],

packages/cli/src/ui/commands/shellsCommand.test.ts

@@ -1,35 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { describe, it, expect, vi } from 'vitest';
-import { shellsCommand } from './shellsCommand.js';
-import type { CommandContext } from './types.js';
-
-describe('shellsCommand', () => {
-  it('should call toggleBackgroundShell', async () => {
-    const toggleBackgroundShell = vi.fn();
-    const context = {
-      ui: {
-        toggleBackgroundShell,
-      },
-    } as unknown as CommandContext;
-
-    if (shellsCommand.action) {
-      await shellsCommand.action(context, '');
-    }
-
-    expect(toggleBackgroundShell).toHaveBeenCalled();
-  });
-
-  it('should have correct name and altNames', () => {
-    expect(shellsCommand.name).toBe('shells');
-    expect(shellsCommand.altNames).toContain('bashes');
-  });
-
-  it('should auto-execute', () => {
-    expect(shellsCommand.autoExecute).toBe(true);
-  });
-});

packages/cli/src/ui/commands/skillsCommand.ts

@@ -357,6 +357,8 @@ function enableCompletion(
     .map((s) => s.name);
 }
 
+import { parseSlashCommand } from '../../utils/commands.js';
+
 export const skillsCommand: SlashCommand = {
   name: 'skills',
   description:
@@ -402,5 +404,13 @@ export const skillsCommand: SlashCommand = {
       action: reloadAction,
     },
   ],
-  action: listAction,
+  action: async (context, args) => {
+    if (args) {
+      const parsed = parseSlashCommand(`/${args}`, skillsCommand.subCommands!);
+      if (parsed.commandToExecute?.action) {
+        return parsed.commandToExecute.action(context, parsed.args);
+      }
+    }
+    return listAction(context, args);
+  },
 };

packages/cli/src/ui/commands/tasksCommand.test.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { tasksCommand } from './tasksCommand.js';
+import type { CommandContext } from './types.js';
+
+describe('tasksCommand', () => {
+  it('should call toggleBackgroundTasks', async () => {
+    const toggleBackgroundTasks = vi.fn();
+    const context = {
+      ui: {
+        toggleBackgroundTasks,
+      },
+    } as unknown as CommandContext;
+
+    if (tasksCommand.action) {
+      await tasksCommand.action(context, '');
+    }
+
+    expect(toggleBackgroundTasks).toHaveBeenCalled();
+  });
+
+  it('should have correct name and altNames', () => {
+    expect(tasksCommand.name).toBe('tasks');
+    expect(tasksCommand.altNames).toContain('bg');
+    expect(tasksCommand.altNames).toContain('background');
+  });
+
+  it('should auto-execute', () => {
+    expect(tasksCommand.autoExecute).toBe(true);
+  });
+});

packages/cli/src/ui/commands/tasksCommand.ts

@@ -6,13 +6,13 @@
 
 import { CommandKind, type SlashCommand } from './types.js';
 
-export const shellsCommand: SlashCommand = {
-  name: 'shells',
-  altNames: ['bashes'],
+export const tasksCommand: SlashCommand = {
+  name: 'tasks',
+  altNames: ['bg', 'background'],
   kind: CommandKind.BUILT_IN,
-  description: 'Toggle background shells view',
+  description: 'Toggle background tasks view',
   autoExecute: true,
   action: async (context) => {
-    context.ui.toggleBackgroundShell();
+    context.ui.toggleBackgroundTasks();
   },
 };

packages/cli/src/ui/commands/types.ts

@@ -90,7 +90,7 @@ export interface CommandContext {
      */
     setConfirmationRequest: (value: ConfirmationRequest) => void;
     removeComponent: () => void;
-    toggleBackgroundShell: () => void;
+    toggleBackgroundTasks: () => void;
     toggleShortcutsHelp: () => void;
   };
   // Session-specific data
@@ -240,5 +240,14 @@ export interface SlashCommand {
    */
   showCompletionLoading?: boolean;
 
+  /**
+   * Whether the command expects arguments.
+   * If false, and the command is a subcommand, the command parser may treat
+   * any following text as arguments for the parent command instead of this subcommand,
+   * provided the parent command has an action.
+   * Defaults to true.
+   */
+  takesArgs?: boolean;
+
   subCommands?: SlashCommand[];
 }

packages/cli/src/ui/components/BackgroundTaskDisplay.test.tsx

@@ -6,8 +6,8 @@
 
 import { render } from '../../test-utils/render.js';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { BackgroundShellDisplay } from './BackgroundShellDisplay.js';
-import { type BackgroundShell } from '../hooks/shellCommandProcessor.js';
+import { BackgroundTaskDisplay } from './BackgroundTaskDisplay.js';
+import { type BackgroundTask } from '../hooks/useExecutionLifecycle.js';
 import { ShellExecutionService } from '@google/gemini-cli-core';
 import { act } from 'react';
 import { type Key, type KeypressHandler } from '../contexts/KeypressContext.js';
@@ -15,15 +15,15 @@ import { ScrollProvider } from '../contexts/ScrollProvider.js';
 import { Box } from 'ink';
 
 // Mock dependencies
-const mockDismissBackgroundShell = vi.fn();
-const mockSetActiveBackgroundShellPid = vi.fn();
-const mockSetIsBackgroundShellListOpen = vi.fn();
+const mockDismissBackgroundTask = vi.fn();
+const mockSetActiveBackgroundTaskPid = vi.fn();
+const mockSetIsBackgroundTaskListOpen = vi.fn();
 
 vi.mock('../contexts/UIActionsContext.js', () => ({
   useUIActions: () => ({
-    dismissBackgroundShell: mockDismissBackgroundShell,
-    setActiveBackgroundShellPid: mockSetActiveBackgroundShellPid,
-    setIsBackgroundShellListOpen: mockSetIsBackgroundShellListOpen,
+    dismissBackgroundTask: mockDismissBackgroundTask,
+    setActiveBackgroundTaskPid: mockSetActiveBackgroundTaskPid,
+    setIsBackgroundTaskListOpen: mockSetIsBackgroundTaskListOpen,
   }),
 }));
 
@@ -86,14 +86,14 @@ vi.mock('./shared/ScrollableList.js', () => ({
       data,
       renderItem,
     }: {
-      data: BackgroundShell[];
+      data: BackgroundTask[];
       renderItem: (props: {
-        item: BackgroundShell;
+        item: BackgroundTask;
         index: number;
       }) => React.ReactNode;
     }) => (
       <Box flexDirection="column">
-        {data.map((item: BackgroundShell, index: number) => (
+        {data.map((item: BackgroundTask, index: number) => (
           <Box key={index}>{renderItem({ item, index })}</Box>
         ))}
       </Box>
@@ -116,9 +116,9 @@ const createMockKey = (overrides: Partial<Key>): Key => ({
   ...overrides,
 });
 
-describe('<BackgroundShellDisplay />', () => {
-  const mockShells = new Map<number, BackgroundShell>();
-  const shell1: BackgroundShell = {
+describe('<BackgroundTaskDisplay />', () => {
+  const mockShells = new Map<number, BackgroundTask>();
+  const shell1: BackgroundTask = {
     pid: 1001,
     command: 'npm start',
     output: 'Starting server...',
@@ -126,7 +126,7 @@ describe('<BackgroundShellDisplay />', () => {
     binaryBytesReceived: 0,
     status: 'running',
   };
-  const shell2: BackgroundShell = {
+  const shell2: BackgroundTask = {
     pid: 1002,
     command: 'tail -f log.txt',
     output: 'Log entry 1',
@@ -147,7 +147,7 @@ describe('<BackgroundShellDisplay />', () => {
     const width = 80;
     const { lastFrame, unmount } = await render(
       <ScrollProvider>
-        <BackgroundShellDisplay
+        <BackgroundTaskDisplay
           shells={mockShells}
           activePid={shell1.pid}
           width={width}
@@ -167,7 +167,7 @@ describe('<BackgroundShellDisplay />', () => {
     const width = 100;
     const { lastFrame, unmount } = await render(
       <ScrollProvider>
-        <BackgroundShellDisplay
+        <BackgroundTaskDisplay
           shells={mockShells}
           activePid={shell1.pid}
           width={width}
@@ -187,7 +187,7 @@ describe('<BackgroundShellDisplay />', () => {
     const width = 80;
     const { lastFrame, unmount } = await render(
       <ScrollProvider>
-        <BackgroundShellDisplay
+        <BackgroundTaskDisplay
           shells={mockShells}
           activePid={shell1.pid}
           width={width}
@@ -207,7 +207,7 @@ describe('<BackgroundShellDisplay />', () => {
     const width = 80;
     const { rerender, unmount } = await render(
       <ScrollProvider>
-        <BackgroundShellDisplay
+        <BackgroundTaskDisplay
           shells={mockShells}
           activePid={shell1.pid}
           width={width}
@@ -227,7 +227,7 @@ describe('<BackgroundShellDisplay />', () => {
 
     rerender(
       <ScrollProvider>
-        <BackgroundShellDisplay
+        <BackgroundTaskDisplay
           shells={mockShells}
           activePid={shell1.pid}
           width={100}
@@ -250,7 +250,7 @@ describe('<BackgroundShellDisplay />', () => {
     const width = 80;
     const { lastFrame, unmount } = await render(
       <ScrollProvider>
-        <BackgroundShellDisplay
+        <BackgroundTaskDisplay
           shells={mockShells}
           activePid={shell1.pid}
           width={width}
@@ -270,7 +270,7 @@ describe('<BackgroundShellDisplay />', () => {
     const width = 80;
     const { unmount } = await render(
       <ScrollProvider>
-        <BackgroundShellDisplay
+        <BackgroundTaskDisplay
           shells={mockShells}
           activePid={shell1.pid}
           width={width}
@@ -287,13 +287,13 @@ describe('<BackgroundShellDisplay />', () => {
       simulateKey({ name: 'down' });
     });
 
-    // Simulate Ctrl+L (handled by BackgroundShellDisplay)
+    // Simulate Ctrl+L (handled by BackgroundTaskDisplay)
     await act(async () => {
       simulateKey({ name: 'l', ctrl: true });
     });
 
-    expect(mockSetActiveBackgroundShellPid).toHaveBeenCalledWith(shell2.pid);
-    expect(mockSetIsBackgroundShellListOpen).toHaveBeenCalledWith(false);
+    expect(mockSetActiveBackgroundTaskPid).toHaveBeenCalledWith(shell2.pid);
+    expect(mockSetIsBackgroundTaskListOpen).toHaveBeenCalledWith(false);
     unmount();
   });
 
@@ -301,7 +301,7 @@ describe('<BackgroundShellDisplay />', () => {
     const width = 80;
     const { unmount } = await render(
       <ScrollProvider>
-        <BackgroundShellDisplay
+        <BackgroundTaskDisplay
           shells={mockShells}
           activePid={shell1.pid}
           width={width}
@@ -325,7 +325,7 @@ describe('<BackgroundShellDisplay />', () => {
       simulateKey({ name: 'k', ctrl: true });
     });
 
-    expect(mockDismissBackgroundShell).toHaveBeenCalledWith(shell2.pid);
+    expect(mockDismissBackgroundTask).toHaveBeenCalledWith(shell2.pid);
     unmount();
   });
 
@@ -333,7 +333,7 @@ describe('<BackgroundShellDisplay />', () => {
     const width = 80;
     const { unmount } = await render(
       <ScrollProvider>
-        <BackgroundShellDisplay
+        <BackgroundTaskDisplay
           shells={mockShells}
           activePid={shell1.pid}
           width={width}
@@ -349,7 +349,7 @@ describe('<BackgroundShellDisplay />', () => {
       simulateKey({ name: 'k', ctrl: true });
     });
 
-    expect(mockDismissBackgroundShell).toHaveBeenCalledWith(shell1.pid);
+    expect(mockDismissBackgroundTask).toHaveBeenCalledWith(shell1.pid);
     unmount();
   });
 
@@ -358,7 +358,7 @@ describe('<BackgroundShellDisplay />', () => {
     const width = 80;
     const { lastFrame, unmount } = await render(
       <ScrollProvider>
-        <BackgroundShellDisplay
+        <BackgroundTaskDisplay
           shells={mockShells}
           activePid={shell2.pid}
           width={width}
@@ -375,7 +375,7 @@ describe('<BackgroundShellDisplay />', () => {
   });
 
   it('keeps exit code status color even when selected', async () => {
-    const exitedShell: BackgroundShell = {
+    const exitedShell: BackgroundTask = {
       pid: 1003,
       command: 'exit 0',
       output: '',
@@ -389,7 +389,7 @@ describe('<BackgroundShellDisplay />', () => {
     const width = 80;
     const { lastFrame, unmount } = await render(
       <ScrollProvider>
-        <BackgroundShellDisplay
+        <BackgroundTaskDisplay
           shells={mockShells}
           activePid={exitedShell.pid}
           width={width}

packages/cli/src/ui/components/BackgroundTaskDisplay.tsx

@@ -17,7 +17,7 @@ import {
   type AnsiToken,
 } from '@google/gemini-cli-core';
 import { cpLen, cpSlice, getCachedStringWidth } from '../utils/textUtils.js';
-import { type BackgroundShell } from '../hooks/shellCommandProcessor.js';
+import { type BackgroundTask } from '../hooks/useExecutionLifecycle.js';
 import { Command } from '../key/keyMatchers.js';
 import { useKeypress } from '../hooks/useKeypress.js';
 import { formatCommand } from '../key/keybindingUtils.js';
@@ -34,8 +34,8 @@ import {
 } from './shared/RadioButtonSelect.js';
 import { useKeyMatchers } from '../hooks/useKeyMatchers.js';
 
-interface BackgroundShellDisplayProps {
-  shells: Map<number, BackgroundShell>;
+interface BackgroundTaskDisplayProps {
+  shells: Map<number, BackgroundTask>;
   activePid: number;
   width: number;
   height: number;
@@ -61,19 +61,19 @@ const formatShellCommandForDisplay = (command: string, maxWidth: number) => {
     : commandFirstLine;
 };
 
-export const BackgroundShellDisplay = ({
+export const BackgroundTaskDisplay = ({
   shells,
   activePid,
   width,
   height,
   isFocused,
   isListOpenProp,
-}: BackgroundShellDisplayProps) => {
+}: BackgroundTaskDisplayProps) => {
   const keyMatchers = useKeyMatchers();
   const {
-    dismissBackgroundShell,
-    setActiveBackgroundShellPid,
-    setIsBackgroundShellListOpen,
+    dismissBackgroundTask,
+    setActiveBackgroundTaskPid,
+    setIsBackgroundTaskListOpen,
   } = useUIActions();
   const activeShell = shells.get(activePid);
   const [output, setOutput] = useState<string | AnsiOutput>(
@@ -152,13 +152,13 @@ export const BackgroundShellDisplay = ({
         // RadioButtonSelect handles Enter -> onSelect
 
         if (keyMatchers[Command.BACKGROUND_SHELL_ESCAPE](key)) {
-          setIsBackgroundShellListOpen(false);
+          setIsBackgroundTaskListOpen(false);
           return true;
         }
 
         if (keyMatchers[Command.KILL_BACKGROUND_SHELL](key)) {
           if (highlightedPid) {
-            void dismissBackgroundShell(highlightedPid);
+            void dismissBackgroundTask(highlightedPid);
             // If we killed the active one, the list might update via props
           }
           return true;
@@ -166,9 +166,9 @@ export const BackgroundShellDisplay = ({
 
         if (keyMatchers[Command.TOGGLE_BACKGROUND_SHELL_LIST](key)) {
           if (highlightedPid) {
-            setActiveBackgroundShellPid(highlightedPid);
+            setActiveBackgroundTaskPid(highlightedPid);
           }
-          setIsBackgroundShellListOpen(false);
+          setIsBackgroundTaskListOpen(false);
           return true;
         }
         return false;
@@ -179,12 +179,12 @@ export const BackgroundShellDisplay = ({
       }
 
       if (keyMatchers[Command.KILL_BACKGROUND_SHELL](key)) {
-        void dismissBackgroundShell(activeShell.pid);
+        void dismissBackgroundTask(activeShell.pid);
         return true;
       }
 
       if (keyMatchers[Command.TOGGLE_BACKGROUND_SHELL_LIST](key)) {
-        setIsBackgroundShellListOpen(true);
+        setIsBackgroundTaskListOpen(true);
         return true;
       }
 
@@ -339,8 +339,8 @@ export const BackgroundShellDisplay = ({
             items={items}
             initialIndex={initialIndex >= 0 ? initialIndex : 0}
             onSelect={(pid) => {
-              setActiveBackgroundShellPid(pid);
-              setIsBackgroundShellListOpen(false);
+              setActiveBackgroundTaskPid(pid);
+              setIsBackgroundTaskListOpen(false);
             }}
             onHighlight={(pid) => setHighlightedPid(pid)}
             isFocused={isFocused}

packages/cli/src/ui/components/Composer.test.tsx

@@ -198,7 +198,7 @@ const createMockUIState = (overrides: Partial<UIState> = {}): UIState =>
     nightly: false,
     isTrustedFolder: true,
     activeHooks: [],
-    isBackgroundShellVisible: false,
+    isBackgroundTaskVisible: false,
     embeddedShellFocused: false,
     showIsExpandableHint: false,
     quota: {
@@ -464,7 +464,7 @@ describe('Composer', () => {
       const uiState = createMockUIState({
         streamingState: StreamingState.Responding,
         embeddedShellFocused: true,
-        isBackgroundShellVisible: true,
+        isBackgroundTaskVisible: true,
       });
 
       const { lastFrame } = await renderComposer(uiState);
@@ -494,7 +494,7 @@ describe('Composer', () => {
       const uiState = createMockUIState({
         streamingState: StreamingState.Responding,
         embeddedShellFocused: true,
-        isBackgroundShellVisible: false,
+        isBackgroundTaskVisible: false,
       });
 
       const { lastFrame } = await renderComposer(uiState);

packages/cli/src/ui/components/Composer.tsx

@@ -152,6 +152,7 @@ export const Composer = ({ isFocused = true }: { isFocused?: boolean }) => {
           vimHandleInput={uiActions.vimHandleInput}
           isEmbeddedShellFocused={uiState.embeddedShellFocused}
           popAllMessages={uiActions.popAllMessages}
+          onQueueMessage={uiActions.addMessage}
           placeholder={
             vimEnabled
               ? vimMode === 'INSERT'

packages/cli/src/ui/components/HistoryItemDisplay.tsx

@@ -48,6 +48,7 @@ interface HistoryItemDisplayProps {
   isExpandable?: boolean;
   isFirstThinking?: boolean;
   isFirstAfterThinking?: boolean;
+  suppressNarration?: boolean;
 }
 
 export const HistoryItemDisplay: React.FC<HistoryItemDisplayProps> = ({
@@ -60,6 +61,7 @@ export const HistoryItemDisplay: React.FC<HistoryItemDisplayProps> = ({
   isExpandable,
   isFirstThinking = false,
   isFirstAfterThinking = false,
+  suppressNarration = false,
 }) => {
   const settings = useSettings();
   const inlineThinkingMode = getInlineThinkingMode(settings);
@@ -68,6 +70,17 @@ export const HistoryItemDisplay: React.FC<HistoryItemDisplayProps> = ({
   const needsTopMarginAfterThinking =
     isFirstAfterThinking && inlineThinkingMode !== 'off';
 
+  // If there's a topic update in this turn, we suppress the regular narration
+  // and thoughts as they are being "replaced" by the update_topic tool.
+  if (
+    suppressNarration &&
+    (itemForDisplay.type === 'thinking' ||
+      itemForDisplay.type === 'gemini' ||
+      itemForDisplay.type === 'gemini_content')
+  ) {
+    return null;
+  }
+
   return (
     <Box
       flexDirection="column"

packages/cli/src/ui/components/InputPrompt.test.tsx

@@ -191,6 +191,7 @@ describe('InputPrompt', () => {
     setCleanUiDetailsVisible: mockSetCleanUiDetailsVisible,
     toggleCleanUiDetailsVisible: mockToggleCleanUiDetailsVisible,
     revealCleanUiDetailsTemporarily: mockRevealCleanUiDetailsTemporarily,
+    addMessage: vi.fn(),
   };
 
   beforeEach(() => {
@@ -352,6 +353,8 @@ describe('InputPrompt', () => {
     vi.mocked(clipboardy.read).mockResolvedValue('');
 
     props = {
+      onQueueMessage: vi.fn(),
+
       buffer: mockBuffer,
       onSubmit: vi.fn(),
       userMessages: [],
@@ -1099,6 +1102,76 @@ describe('InputPrompt', () => {
     unmount();
   });
 
+  it('queues a message when Tab is pressed during generation', async () => {
+    props.buffer.setText('A new prompt');
+    props.streamingState = StreamingState.Responding;
+
+    const { stdin, unmount } = await renderWithProviders(
+      <InputPrompt {...props} />,
+      {
+        uiActions,
+      },
+    );
+
+    await act(async () => {
+      stdin.write('\t');
+    });
+
+    await waitFor(() => {
+      expect(props.onQueueMessage).toHaveBeenCalledWith('A new prompt');
+      expect(props.buffer.text).toBe('');
+    });
+    unmount();
+  });
+
+  it('shows an error when attempting to queue a slash command', async () => {
+    props.buffer.setText('/clear');
+    props.streamingState = StreamingState.Responding;
+
+    const { stdin, unmount } = await renderWithProviders(
+      <InputPrompt {...props} />,
+      {
+        uiActions,
+      },
+    );
+
+    await act(async () => {
+      stdin.write('\t');
+    });
+
+    await waitFor(() => {
+      expect(props.setQueueErrorMessage).toHaveBeenCalledWith(
+        'Slash commands cannot be queued',
+      );
+      expect(props.onQueueMessage).not.toHaveBeenCalled();
+    });
+    unmount();
+  });
+
+  it('shows an error when attempting to queue a shell command', async () => {
+    props.shellModeActive = true;
+    props.buffer.setText('ls');
+    props.streamingState = StreamingState.Responding;
+
+    const { stdin, unmount } = await renderWithProviders(
+      <InputPrompt {...props} />,
+      {
+        uiActions,
+      },
+    );
+
+    await act(async () => {
+      stdin.write('\t');
+    });
+
+    await waitFor(() => {
+      expect(props.setQueueErrorMessage).toHaveBeenCalledWith(
+        'Shell commands cannot be queued',
+      );
+      expect(props.onQueueMessage).not.toHaveBeenCalled();
+    });
+    unmount();
+  });
   it('should not submit on Enter when the buffer is empty or only contains whitespace', async () => {
     props.buffer.setText('   '); // Set buffer to whitespace
 

packages/cli/src/ui/components/InputPrompt.tsx

@@ -117,6 +117,7 @@ export interface InputPromptProps {
   setQueueErrorMessage: (message: string | null) => void;
   streamingState: StreamingState;
   popAllMessages?: () => string | undefined;
+  onQueueMessage?: (message: string) => void;
   suggestionsPosition?: 'above' | 'below';
   setBannerVisible: (visible: boolean) => void;
   copyModeEnabled?: boolean;
@@ -211,6 +212,7 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
   setQueueErrorMessage,
   streamingState,
   popAllMessages,
+  onQueueMessage,
   suggestionsPosition = 'below',
   setBannerVisible,
   copyModeEnabled = false,
@@ -230,8 +232,8 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
     terminalWidth,
     activePtyId,
     history,
-    backgroundShells,
-    backgroundShellHeight,
+    backgroundTasks,
+    backgroundTaskHeight,
     shortcutsHelpVisible,
   } = useUIState();
   const [suppressCompletion, setSuppressCompletion] = useState(false);
@@ -690,6 +692,7 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
         streamingState === StreamingState.Responding ||
         streamingState === StreamingState.WaitingForConfirmation;
 
+      const isQueueMessageKey = keyMatchers[Command.QUEUE_MESSAGE](key);
       const isPlainTab =
         key.name === 'tab' && !key.shift && !key.alt && !key.ctrl && !key.cmd;
       const hasTabCompletionInteraction =
@@ -698,6 +701,29 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
         reverseSearchActive ||
         commandSearchActive;
 
+      if (
+        isGenerating &&
+        isQueueMessageKey &&
+        !hasTabCompletionInteraction &&
+        buffer.text.trim().length > 0
+      ) {
+        const trimmedMessage = buffer.text.trim();
+        const isSlash = isSlashCommand(trimmedMessage);
+
+        if (isSlash || shellModeActive) {
+          setQueueErrorMessage(
+            `${shellModeActive ? 'Shell' : 'Slash'} commands cannot be queued`,
+          );
+        } else if (onQueueMessage) {
+          onQueueMessage(buffer.text);
+          buffer.setText('');
+          resetCompletionState();
+          resetReverseSearchCompletionState();
+        }
+        resetPlainTabPress();
+        return true;
+      }
+
       if (isPlainTab && shellModeActive) {
         resetPlainTabPress();
         if (!shouldShowSuggestions) {
@@ -1236,7 +1262,7 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
       if (keyMatchers[Command.FOCUS_SHELL_INPUT](key)) {
         if (
           activePtyId ||
-          (backgroundShells.size > 0 && backgroundShellHeight > 0)
+          (backgroundTasks.size > 0 && backgroundTaskHeight > 0)
         ) {
           setEmbeddedShellFocused(true);
           return true;
@@ -1293,11 +1319,14 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
       shortcutsHelpVisible,
       setShortcutsHelpVisible,
       tryLoadQueuedMessages,
+      onQueueMessage,
+      setQueueErrorMessage,
+      resetReverseSearchCompletionState,
       setBannerVisible,
       activePtyId,
       setEmbeddedShellFocused,
-      backgroundShells.size,
-      backgroundShellHeight,
+      backgroundTasks.size,
+      backgroundTaskHeight,
       streamingState,
       handleEscPress,
       registerPlainTabPress,

packages/cli/src/ui/components/MainContent.test.tsx

@@ -86,10 +86,10 @@ vi.mock('./shared/ScrollableList.js', () => ({
 }));
 
 import { theme } from '../semantic-colors.js';
-import { type BackgroundShell } from '../hooks/shellReducer.js';
+import { type BackgroundTask } from '../hooks/shellReducer.js';
 
 describe('getToolGroupBorderAppearance', () => {
-  const mockBackgroundShells = new Map<number, BackgroundShell>();
+  const mockBackgroundTasks = new Map<number, BackgroundTask>();
   const activeShellPtyId = 123;
 
   it('returns default empty values for non-tool_group items', () => {
@@ -99,7 +99,7 @@ describe('getToolGroupBorderAppearance', () => {
       null,
       false,
       [],
-      mockBackgroundShells,
+      mockBackgroundTasks,
     );
     expect(result).toEqual({ borderColor: '', borderDimColor: false });
   });
@@ -144,7 +144,7 @@ describe('getToolGroupBorderAppearance', () => {
       null,
       false,
       pendingItems,
-      mockBackgroundShells,
+      mockBackgroundTasks,
     );
     expect(result).toEqual({
       borderColor: theme.border.default,
@@ -173,7 +173,7 @@ describe('getToolGroupBorderAppearance', () => {
       null,
       false,
       [],
-      mockBackgroundShells,
+      mockBackgroundTasks,
     );
     expect(result).toEqual({
       borderColor: theme.border.default,
@@ -202,7 +202,7 @@ describe('getToolGroupBorderAppearance', () => {
       null,
       false,
       [],
-      mockBackgroundShells,
+      mockBackgroundTasks,
     );
     expect(result).toEqual({
       borderColor: theme.status.warning,
@@ -232,7 +232,7 @@ describe('getToolGroupBorderAppearance', () => {
       activeShellPtyId,
       false,
       [],
-      mockBackgroundShells,
+      mockBackgroundTasks,
     );
     expect(result).toEqual({
       borderColor: theme.ui.active,
@@ -262,7 +262,7 @@ describe('getToolGroupBorderAppearance', () => {
       activeShellPtyId,
       true,
       [],
-      mockBackgroundShells,
+      mockBackgroundTasks,
     );
     expect(result).toEqual({
       borderColor: theme.ui.focus,
@@ -291,7 +291,7 @@ describe('getToolGroupBorderAppearance', () => {
       activeShellPtyId,
       false,
       [],
-      mockBackgroundShells,
+      mockBackgroundTasks,
     );
     expect(result).toEqual({
       borderColor: theme.ui.active,
@@ -308,7 +308,7 @@ describe('getToolGroupBorderAppearance', () => {
       activeShellPtyId,
       true,
       [],
-      mockBackgroundShells,
+      mockBackgroundTasks,
     );
     // Since there are no tools to inspect, it falls back to empty pending, but isCurrentlyInShellTurn=true
     // so it counts as pending shell.

packages/cli/src/ui/components/MainContent.tsx

@@ -7,8 +7,10 @@
 import { Box, Static } from 'ink';
 import { HistoryItemDisplay } from './HistoryItemDisplay.js';
 import { useUIState } from '../contexts/UIStateContext.js';
+import { useSettings } from '../contexts/SettingsContext.js';
 import { useAppContext } from '../contexts/AppContext.js';
 import { AppHeader } from './AppHeader.js';
+
 import { useAlternateBuffer } from '../hooks/useAlternateBuffer.js';
 import {
   SCROLL_TO_ITEM_END,
@@ -19,6 +21,7 @@ import { useMemo, memo, useCallback, useEffect, useRef } from 'react';
 import { MAX_GEMINI_MESSAGE_LINES } from '../constants.js';
 import { useConfirmingTool } from '../hooks/useConfirmingTool.js';
 import { ToolConfirmationQueue } from './ToolConfirmationQueue.js';
+import { isTopicTool } from './messages/TopicMessage.js';
 
 const MemoizedHistoryItemDisplay = memo(HistoryItemDisplay);
 const MemoizedAppHeader = memo(AppHeader);
@@ -63,12 +66,39 @@ export const MainContent = () => {
     return -1;
   }, [uiState.history]);
 
+  const settings = useSettings();
+  const topicUpdateNarrationEnabled =
+    settings.merged.experimental?.topicUpdateNarration === true;
+
+  const suppressNarrationFlags = useMemo(() => {
+    const combinedHistory = [...uiState.history, ...pendingHistoryItems];
+    const flags = new Array<boolean>(combinedHistory.length).fill(false);
+
+    if (topicUpdateNarrationEnabled) {
+      let toolGroupInTurn = false;
+      for (let i = combinedHistory.length - 1; i >= 0; i--) {
+        const item = combinedHistory[i];
+        if (item.type === 'user' || item.type === 'user_shell') {
+          toolGroupInTurn = false;
+        } else if (item.type === 'tool_group') {
+          toolGroupInTurn = item.tools.some((t) => isTopicTool(t.name));
+        } else if (
+          (item.type === 'thinking' ||
+            item.type === 'gemini' ||
+            item.type === 'gemini_content') &&
+          toolGroupInTurn
+        ) {
+          flags[i] = true;
+        }
+      }
+    }
+    return flags;
+  }, [uiState.history, pendingHistoryItems, topicUpdateNarrationEnabled]);
+
   const augmentedHistory = useMemo(
     () =>
-      uiState.history.map((item, index) => {
-        const isExpandable = index > lastUserPromptIndex;
-        const prevType =
-          index > 0 ? uiState.history[index - 1]?.type : undefined;
+      uiState.history.map((item, i) => {
+        const prevType = i > 0 ? uiState.history[i - 1]?.type : undefined;
         const isFirstThinking =
           item.type === 'thinking' && prevType !== 'thinking';
         const isFirstAfterThinking =
@@ -76,18 +106,25 @@ export const MainContent = () => {
 
         return {
           item,
-          isExpandable,
+          isExpandable: i > lastUserPromptIndex,
           isFirstThinking,
           isFirstAfterThinking,
+          suppressNarration: suppressNarrationFlags[i] ?? false,
         };
       }),
-    [uiState.history, lastUserPromptIndex],
+    [uiState.history, lastUserPromptIndex, suppressNarrationFlags],
   );
 
   const historyItems = useMemo(
     () =>
       augmentedHistory.map(
-        ({ item, isExpandable, isFirstThinking, isFirstAfterThinking }) => (
+        ({
+          item,
+          isExpandable,
+          isFirstThinking,
+          isFirstAfterThinking,
+          suppressNarration,
+        }) => (
           <MemoizedHistoryItemDisplay
             terminalWidth={mainAreaWidth}
             availableTerminalHeight={
@@ -103,6 +140,7 @@ export const MainContent = () => {
             isExpandable={isExpandable}
             isFirstThinking={isFirstThinking}
             isFirstAfterThinking={isFirstAfterThinking}
+            suppressNarration={suppressNarration}
           />
         ),
       ),
@@ -138,6 +176,9 @@ export const MainContent = () => {
           const isFirstAfterThinking =
             item.type !== 'thinking' && prevType === 'thinking';
 
+          const suppressNarration =
+            suppressNarrationFlags[uiState.history.length + i] ?? false;
+
           return (
             <HistoryItemDisplay
               key={`pending-${i}`}
@@ -150,6 +191,7 @@ export const MainContent = () => {
               isExpandable={true}
               isFirstThinking={isFirstThinking}
               isFirstAfterThinking={isFirstAfterThinking}
+              suppressNarration={suppressNarration}
             />
           );
         })}
@@ -169,6 +211,7 @@ export const MainContent = () => {
       showConfirmationQueue,
       confirmingTool,
       uiState.history,
+      suppressNarrationFlags,
     ],
   );
 
@@ -176,12 +219,19 @@ export const MainContent = () => {
     () => [
       { type: 'header' as const },
       ...augmentedHistory.map(
-        ({ item, isExpandable, isFirstThinking, isFirstAfterThinking }) => ({
+        ({
+          item,
+          isExpandable,
+          isFirstThinking,
+          isFirstAfterThinking,
+          suppressNarration,
+        }) => ({
           type: 'history' as const,
           item,
           isExpandable,
           isFirstThinking,
           isFirstAfterThinking,
+          suppressNarration,
         }),
       ),
       { type: 'pending' as const },
@@ -216,6 +266,7 @@ export const MainContent = () => {
             isExpandable={item.isExpandable}
             isFirstThinking={item.isFirstThinking}
             isFirstAfterThinking={item.isFirstAfterThinking}
+            suppressNarration={item.suppressNarration}
           />
         );
       } else {

packages/cli/src/ui/components/StatusDisplay.test.tsx

@@ -51,7 +51,7 @@ const createMockUIState = (overrides: UIStateOverrides = {}): UIState =>
     ideContextState: null,
     geminiMdFileCount: 0,
     contextFileNames: [],
-    backgroundShellCount: 0,
+    backgroundTaskCount: 0,
     buffer: { text: '' },
     history: [{ id: 1, type: 'user', text: 'test' }],
     ...overrides,
@@ -159,9 +159,9 @@ describe('StatusDisplay', () => {
     unmount();
   });
 
-  it('passes backgroundShellCount to ContextSummaryDisplay', async () => {
+  it('passes backgroundTaskCount to ContextSummaryDisplay', async () => {
     const uiState = createMockUIState({
-      backgroundShellCount: 3,
+      backgroundTaskCount: 3,
     });
     const { lastFrame, unmount } = await renderStatusDisplay(
       { hideContextSummary: false },

packages/cli/src/ui/components/StatusDisplay.tsx

@@ -38,7 +38,7 @@ export const StatusDisplay: React.FC<StatusDisplayProps> = ({
           config.getMcpClientManager()?.getBlockedMcpServers() ?? []
         }
         skillCount={config.getSkillManager().getDisplayableSkills().length}
-        backgroundProcessCount={uiState.backgroundShellCount}
+        backgroundProcessCount={uiState.backgroundTaskCount}
       />
     );
   }

packages/cli/src/ui/components/StatusRow.test.tsx

@@ -0,0 +1,179 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { renderWithProviders } from '../../test-utils/render.js';
+import { StatusRow } from './StatusRow.js';
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import { useComposerStatus } from '../hooks/useComposerStatus.js';
+import { type UIState } from '../contexts/UIStateContext.js';
+import { type TextBuffer } from '../components/shared/text-buffer.js';
+import { type SessionStatsState } from '../contexts/SessionContext.js';
+import { type ThoughtSummary } from '../types.js';
+import { ApprovalMode } from '@google/gemini-cli-core';
+
+vi.mock('../hooks/useComposerStatus.js', () => ({
+  useComposerStatus: vi.fn(),
+}));
+
+describe('<StatusRow />', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const defaultUiState: Partial<UIState> = {
+    currentTip: undefined,
+    thought: null,
+    elapsedTime: 0,
+    currentWittyPhrase: undefined,
+    activeHooks: [],
+    buffer: { text: '' } as unknown as TextBuffer,
+    sessionStats: { lastPromptTokenCount: 0 } as unknown as SessionStatsState,
+    shortcutsHelpVisible: false,
+    contextFileNames: [],
+    showApprovalModeIndicator: ApprovalMode.DEFAULT,
+    allowPlanMode: false,
+    shellModeActive: false,
+    renderMarkdown: true,
+    currentModel: 'gemini-3',
+  };
+
+  it('renders status and tip correctly when they both fit', async () => {
+    (useComposerStatus as Mock).mockReturnValue({
+      isInteractiveShellWaiting: false,
+      showLoadingIndicator: true,
+      showTips: true,
+      showWit: true,
+      modeContentObj: null,
+      showMinimalContext: false,
+    });
+
+    const uiState: Partial<UIState> = {
+      ...defaultUiState,
+      currentTip: 'Test Tip',
+      thought: { subject: 'Thinking...' } as unknown as ThoughtSummary,
+      elapsedTime: 5,
+      currentWittyPhrase: 'I am witty',
+    };
+
+    const { lastFrame, waitUntilReady } = await renderWithProviders(
+      <StatusRow
+        showUiDetails={false}
+        isNarrow={false}
+        terminalWidth={100}
+        hideContextSummary={false}
+        hideUiDetailsForSuggestions={false}
+        hasPendingActionRequired={false}
+      />,
+      {
+        width: 100,
+        uiState,
+      },
+    );
+
+    await waitUntilReady();
+    const output = lastFrame();
+    expect(output).toContain('Thinking...');
+    expect(output).toContain('I am witty');
+    expect(output).toContain('Tip: Test Tip');
+  });
+
+  it('renders correctly when interactive shell is waiting', async () => {
+    (useComposerStatus as Mock).mockReturnValue({
+      isInteractiveShellWaiting: true,
+      showLoadingIndicator: false,
+      showTips: false,
+      showWit: false,
+      modeContentObj: null,
+      showMinimalContext: false,
+    });
+
+    const { lastFrame, waitUntilReady } = await renderWithProviders(
+      <StatusRow
+        showUiDetails={true}
+        isNarrow={false}
+        terminalWidth={100}
+        hideContextSummary={false}
+        hideUiDetailsForSuggestions={false}
+        hasPendingActionRequired={false}
+      />,
+      {
+        width: 100,
+        uiState: defaultUiState,
+      },
+    );
+
+    await waitUntilReady();
+    expect(lastFrame()).toContain('! Shell awaiting input (Tab to focus)');
+  });
+
+  it('renders tip with absolute positioning when it fits but might collide (verification of container logic)', async () => {
+    (useComposerStatus as Mock).mockReturnValue({
+      isInteractiveShellWaiting: false,
+      showLoadingIndicator: true,
+      showTips: true,
+      showWit: true,
+      modeContentObj: null,
+      showMinimalContext: false,
+    });
+
+    const uiState: Partial<UIState> = {
+      ...defaultUiState,
+      currentTip: 'Test Tip',
+    };
+
+    const { lastFrame, waitUntilReady } = await renderWithProviders(
+      <StatusRow
+        showUiDetails={false}
+        isNarrow={false}
+        terminalWidth={100}
+        hideContextSummary={false}
+        hideUiDetailsForSuggestions={false}
+        hasPendingActionRequired={false}
+      />,
+      {
+        width: 100,
+        uiState,
+      },
+    );
+
+    await waitUntilReady();
+    expect(lastFrame()).toContain('Tip: Test Tip');
+  });
+
+  it('renders buffer toggle hint when showIsAlternateBufferHint is true', async () => {
+    (useComposerStatus as Mock).mockReturnValue({
+      isInteractiveShellWaiting: false,
+      showLoadingIndicator: false,
+      showTips: false,
+      showWit: false,
+      modeContentObj: null,
+      showMinimalContext: false,
+    });
+
+    const uiState: Partial<UIState> = {
+      ...defaultUiState,
+      showIsAlternateBufferHint: true,
+    };
+
+    const { lastFrame, waitUntilReady } = await renderWithProviders(
+      <StatusRow
+        showUiDetails={false}
+        isNarrow={false}
+        terminalWidth={100}
+        hideContextSummary={false}
+        hideUiDetailsForSuggestions={false}
+        hasPendingActionRequired={false}
+      />,
+      {
+        width: 100,
+        uiState,
+      },
+    );
+
+    await waitUntilReady();
+    expect(lastFrame()).toContain('[Alt+T] Switch to Full Screen');
+  });
+});

packages/cli/src/ui/components/StatusRow.tsx

@@ -179,7 +179,13 @@ export const StatusRow: React.FC<StatusRowProps> = ({
       const observer = new ResizeObserver((entries) => {
         const entry = entries[0];
         if (entry) {
-          setTipWidth(Math.round(entry.contentRect.width));
+          const width = Math.round(entry.contentRect.width);
+          // Only update if width > 0 to prevent layout feedback loops
+          // when the tip is hidden. This ensures we always use the
+          // intrinsic width for collision detection.
+          if (width > 0) {
+            setTipWidth(width);
+          }
         }
       });
       observer.observe(node);
@@ -200,7 +206,12 @@ export const StatusRow: React.FC<StatusRowProps> = ({
       return uiState.currentTip;
     }
 
-    // 2. Shortcut Hint (Fallback)
+    // 2. Buffer Toggle Hint
+    if (uiState.showIsAlternateBufferHint) {
+      return '[Alt+T] Switch to Full Screen';
+    }
+
+    // 3. Shortcut Hint (Fallback)
     if (
       settings.merged.ui.showShortcutsHint &&
       !hideUiDetailsForSuggestions &&
@@ -230,6 +241,10 @@ export const StatusRow: React.FC<StatusRowProps> = ({
   const showRow1 = showUiDetails || showRow1Minimal;
   const showRow2 = showUiDetails || showRow2Minimal;
 
+  const onStatusResize = useCallback((width: number) => {
+    if (width > 0) setStatusWidth(width);
+  }, []);
+
   const statusNode = (
     <StatusNode
       showTips={showTips}
@@ -242,7 +257,7 @@ export const StatusRow: React.FC<StatusRowProps> = ({
       errorVerbosity={
         settings.merged.ui.errorVerbosity as 'low' | 'full' | undefined
       }
-      onResize={setStatusWidth}
+      onResize={onStatusResize}
     />
   );
 
@@ -322,20 +337,23 @@ export const StatusRow: React.FC<StatusRowProps> = ({
 
           <Box
             flexShrink={0}
-            marginLeft={LAYOUT.TIP_LEFT_MARGIN}
+            marginLeft={showTipLine ? LAYOUT.TIP_LEFT_MARGIN : 0}
             marginRight={
-              isNarrow
-                ? LAYOUT.TIP_RIGHT_MARGIN_NARROW
-                : LAYOUT.TIP_RIGHT_MARGIN_WIDE
+              showTipLine
+                ? isNarrow
+                  ? LAYOUT.TIP_RIGHT_MARGIN_NARROW
+                  : LAYOUT.TIP_RIGHT_MARGIN_WIDE
+                : 0
             }
+            position={showTipLine ? 'relative' : 'absolute'}
+            {...(showTipLine ? {} : { top: -100, left: -100 })}
           >
             {/* 
-                We always render the tip node so it can be measured by ResizeObserver,
-                but we control its visibility based on the collision detection.
+                We always render the tip node so it can be measured by ResizeObserver.
+                When hidden, we use absolute positioning so it can still be measured 
+                but doesn't affect the layout of Row 1. This prevents layout loops.
             */}
-            <Box display={showTipLine ? 'flex' : 'none'}>
-              {!isNarrow && tipContentStr && renderTipNode()}
-            </Box>
+            {!isNarrow && tipContentStr && renderTipNode()}
           </Box>
         </Box>
       )}

packages/cli/src/ui/components/__snapshots__/BackgroundTaskDisplay.test.tsx.snap

@@ -1,6 +1,6 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`<BackgroundShellDisplay /> > highlights the focused state 1`] = `
+exports[`<BackgroundTaskDisplay /> > highlights the focused state 1`] = `
 "┌──────────────────────────────────────────────────────────────────────────────┐
 │  1: npm sta.. (PID: 1001)        Close (Ctrl+B) | Kill (Ctrl+K) | List       │
 │              (Focused)           (Ctrl+L)                                    │
@@ -10,7 +10,7 @@ exports[`<BackgroundShellDisplay /> > highlights the focused state 1`] = `
 "
 `;
 
-exports[`<BackgroundShellDisplay /> > keeps exit code status color even when selected 1`] = `
+exports[`<BackgroundTaskDisplay /> > keeps exit code status color even when selected 1`] = `
 "┌──────────────────────────────────────────────────────────────────────────────┐
 │  1: npm sta.. (PID: 1003)        Close (Ctrl+B) | Kill (Ctrl+K) | List       │
 │              (Focused)           (Ctrl+L)                                    │
@@ -25,7 +25,7 @@ exports[`<BackgroundShellDisplay /> > keeps exit code status color even when sel
 "
 `;
 
-exports[`<BackgroundShellDisplay /> > renders tabs for multiple shells 1`] = `
+exports[`<BackgroundTaskDisplay /> > renders tabs for multiple shells 1`] = `
 "┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
 │  1: npm start  2: tail -f lo...  (PID: 1001)      Close (Ctrl+B) | Kill (Ctrl+K) | List (Ctrl+L) │
 │ Starting server...                                                                               │
@@ -34,7 +34,7 @@ exports[`<BackgroundShellDisplay /> > renders tabs for multiple shells 1`] = `
 "
 `;
 
-exports[`<BackgroundShellDisplay /> > renders the output of the active shell 1`] = `
+exports[`<BackgroundTaskDisplay /> > renders the output of the active shell 1`] = `
 "┌──────────────────────────────────────────────────────────────────────────────┐
 │  1: ...  2: ...  (PID: 1001)  Close (Ctrl+B) | Kill (Ctrl+K) | List (Ctrl+L) │
 │ Starting server...                                                           │
@@ -43,7 +43,7 @@ exports[`<BackgroundShellDisplay /> > renders the output of the active shell 1`]
 "
 `;
 
-exports[`<BackgroundShellDisplay /> > renders the process list when isListOpenProp is true 1`] = `
+exports[`<BackgroundTaskDisplay /> > renders the process list when isListOpenProp is true 1`] = `
 "┌──────────────────────────────────────────────────────────────────────────────┐
 │  1: npm sta.. (PID: 1001)        Close (Ctrl+B) | Kill (Ctrl+K) | List       │
 │              (Focused)           (Ctrl+L)                                    │
@@ -57,7 +57,7 @@ exports[`<BackgroundShellDisplay /> > renders the process list when isListOpenPr
 "
 `;
 
-exports[`<BackgroundShellDisplay /> > scrolls to active shell when list opens 1`] = `
+exports[`<BackgroundTaskDisplay /> > scrolls to active shell when list opens 1`] = `
 "┌──────────────────────────────────────────────────────────────────────────────┐
 │  1: npm sta.. (PID: 1002)        Close (Ctrl+B) | Kill (Ctrl+K) | List       │
 │              (Focused)           (Ctrl+L)                                    │

packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx

@@ -7,13 +7,10 @@
 import { renderWithProviders } from '../../../test-utils/render.js';
 import { describe, it, expect, vi, afterEach } from 'vitest';
 import { ToolGroupMessage } from './ToolGroupMessage.js';
-import type {
-  HistoryItem,
-  HistoryItemWithoutId,
-  IndividualToolCallDisplay,
-} from '../../types.js';
-import { Scrollable } from '../shared/Scrollable.js';
 import {
+  UPDATE_TOPIC_TOOL_NAME,
+  TOPIC_PARAM_TITLE,
+  TOPIC_PARAM_STRATEGIC_INTENT,
   makeFakeConfig,
   CoreToolCallStatus,
   ApprovalMode,
@@ -23,6 +20,12 @@ import {
   READ_FILE_DISPLAY_NAME,
   GLOB_DISPLAY_NAME,
 } from '@google/gemini-cli-core';
+import type {
+  HistoryItem,
+  HistoryItemWithoutId,
+  IndividualToolCallDisplay,
+} from '../../types.js';
+import { Scrollable } from '../shared/Scrollable.js';
 import os from 'node:os';
 import { createMockSettings } from '../../../test-utils/settings.js';
 
@@ -36,6 +39,7 @@ describe('<ToolGroupMessage />', () => {
   ): IndividualToolCallDisplay => ({
     callId: 'tool-123',
     name: 'test-tool',
+    args: {},
     description: 'A tool for testing',
     resultDisplay: 'Test result',
     status: CoreToolCallStatus.Success,
@@ -253,8 +257,71 @@ describe('<ToolGroupMessage />', () => {
       unmount();
     });
 
-    it('renders mixed tool calls including shell command', async () => {
+    it('renders update_topic tool call using TopicMessage', async () => {
       const toolCalls = [
+        createToolCall({
+          callId: 'topic-tool',
+          name: UPDATE_TOPIC_TOOL_NAME,
+          args: {
+            [TOPIC_PARAM_TITLE]: 'Testing Topic',
+            [TOPIC_PARAM_STRATEGIC_INTENT]: 'This is the description',
+          },
+        }),
+      ];
+      const item = createItem(toolCalls);
+
+      const { lastFrame, unmount } = await renderWithProviders(
+        <ToolGroupMessage {...baseProps} item={item} toolCalls={toolCalls} />,
+        {
+          config: baseMockConfig,
+          settings: fullVerbositySettings,
+        },
+      );
+
+      const output = lastFrame();
+      expect(output).toContain('Testing Topic');
+      expect(output).toContain('— This is the description');
+      expect(output).toMatchSnapshot('update_topic_tool');
+      unmount();
+    });
+
+    it('renders update_topic tool call with summary instead of strategic_intent', async () => {
+      const toolCalls = [
+        createToolCall({
+          callId: 'topic-tool-summary',
+          name: UPDATE_TOPIC_TOOL_NAME,
+          args: {
+            [TOPIC_PARAM_TITLE]: 'Testing Topic',
+            summary: 'This is the summary',
+          },
+        }),
+      ];
+      const item = createItem(toolCalls);
+
+      const { lastFrame, unmount } = await renderWithProviders(
+        <ToolGroupMessage {...baseProps} item={item} toolCalls={toolCalls} />,
+        {
+          config: baseMockConfig,
+          settings: fullVerbositySettings,
+        },
+      );
+
+      const output = lastFrame();
+      expect(output).toContain('Testing Topic');
+      expect(output).toContain('— This is the summary');
+      unmount();
+    });
+
+    it('renders mixed tool calls including update_topic', async () => {
+      const toolCalls = [
+        createToolCall({
+          callId: 'topic-tool-mixed',
+          name: UPDATE_TOPIC_TOOL_NAME,
+          args: {
+            [TOPIC_PARAM_TITLE]: 'Testing Topic',
+            [TOPIC_PARAM_STRATEGIC_INTENT]: 'This is the description',
+          },
+        }),
         createToolCall({
           callId: 'tool-1',
           name: 'read_file',

packages/cli/src/ui/components/messages/ToolGroupMessage.tsx

@@ -15,6 +15,7 @@ import type {
 import { ToolCallStatus, mapCoreStatusToDisplayStatus } from '../../types.js';
 import { ToolMessage } from './ToolMessage.js';
 import { ShellToolMessage } from './ShellToolMessage.js';
+import { TopicMessage, isTopicTool } from './TopicMessage.js';
 import { SubagentGroupDisplay } from './SubagentGroupDisplay.js';
 import { theme } from '../../semantic-colors.js';
 import { useConfig } from '../../contexts/ConfigContext.js';
@@ -81,7 +82,7 @@ export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
   const {
     activePtyId,
     embeddedShellFocused,
-    backgroundShells,
+    backgroundTasks,
     pendingHistoryItems,
   } = useUIState();
 
@@ -92,14 +93,14 @@ export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
         activePtyId,
         embeddedShellFocused,
         pendingHistoryItems,
-        backgroundShells,
+        backgroundTasks,
       ),
     [
       item,
       activePtyId,
       embeddedShellFocused,
       pendingHistoryItems,
-      backgroundShells,
+      backgroundTasks,
     ],
   );
 
@@ -192,7 +193,20 @@ export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
       paddingRight={TOOL_MESSAGE_HORIZONTAL_MARGIN}
     >
       {groupedTools.map((group, index) => {
-        const isFirst = index === 0;
+        let isFirst = index === 0;
+        if (!isFirst) {
+          // Check if all previous tools were topics
+          let allPreviousWereTopics = true;
+          for (let i = 0; i < index; i++) {
+            const prevGroup = groupedTools[i];
+            if (Array.isArray(prevGroup) || !isTopicTool(prevGroup.name)) {
+              allPreviousWereTopics = false;
+              break;
+            }
+          }
+          isFirst = allPreviousWereTopics;
+        }
+
         const resolvedIsFirst =
           borderTopOverride !== undefined
             ? borderTopOverride && isFirst
@@ -215,6 +229,7 @@ export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
 
         const tool = group;
         const isShellToolCall = isShellTool(tool.name);
+        const isTopicToolCall = isTopicTool(tool.name);
 
         const commonProps = {
           ...tool,
@@ -234,7 +249,9 @@ export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
             minHeight={1}
             width={contentWidth}
           >
-            {isShellToolCall ? (
+            {isTopicToolCall ? (
+              <TopicMessage {...commonProps} />
+            ) : isShellToolCall ? (
               <ShellToolMessage {...commonProps} config={config} />
             ) : (
               <ToolMessage {...commonProps} />
@@ -262,26 +279,26 @@ export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
           </Box>
         );
       })}
-      {
-        /*
-            We have to keep the bottom border separate so it doesn't get
-            drawn over by the sticky header directly inside it.
-           */
-        (visibleToolCalls.length > 0 || borderBottomOverride !== undefined) &&
-          borderBottomOverride !== false && (
-            <Box
-              height={0}
-              width={contentWidth}
-              borderLeft={true}
-              borderRight={true}
-              borderTop={false}
-              borderBottom={borderBottomOverride ?? true}
-              borderColor={borderColor}
-              borderDimColor={borderDimColor}
-              borderStyle="round"
-            />
-          )
-      }
+      {/*
+          We have to keep the bottom border separate so it doesn't get
+          drawn over by the sticky header directly inside it.
+         */}
+      {(visibleToolCalls.length > 0 || borderBottomOverride !== undefined) &&
+        borderBottomOverride !== false &&
+        (visibleToolCalls.length === 0 ||
+          !visibleToolCalls.every((tool) => isTopicTool(tool.name))) && (
+          <Box
+            height={0}
+            width={contentWidth}
+            borderLeft={true}
+            borderRight={true}
+            borderTop={false}
+            borderBottom={borderBottomOverride ?? true}
+            borderColor={borderColor}
+            borderDimColor={borderDimColor}
+            borderStyle="round"
+          />
+        )}
     </Box>
   );
 

packages/cli/src/ui/components/messages/TopicMessage.tsx

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type React from 'react';
+import { Box, Text } from 'ink';
+import {
+  UPDATE_TOPIC_TOOL_NAME,
+  UPDATE_TOPIC_DISPLAY_NAME,
+  TOPIC_PARAM_TITLE,
+  TOPIC_PARAM_SUMMARY,
+  TOPIC_PARAM_STRATEGIC_INTENT,
+} from '@google/gemini-cli-core';
+import type { IndividualToolCallDisplay } from '../../types.js';
+import { theme } from '../../semantic-colors.js';
+
+interface TopicMessageProps extends IndividualToolCallDisplay {
+  terminalWidth: number;
+}
+
+export const isTopicTool = (name: string): boolean =>
+  name === UPDATE_TOPIC_TOOL_NAME || name === UPDATE_TOPIC_DISPLAY_NAME;
+
+export const TopicMessage: React.FC<TopicMessageProps> = ({ args }) => {
+  const rawTitle = args?.[TOPIC_PARAM_TITLE];
+  const title = typeof rawTitle === 'string' ? rawTitle : undefined;
+  const rawIntent =
+    args?.[TOPIC_PARAM_STRATEGIC_INTENT] || args?.[TOPIC_PARAM_SUMMARY];
+  const intent = typeof rawIntent === 'string' ? rawIntent : undefined;
+
+  return (
+    <Box flexDirection="row" marginLeft={2}>
+      <Text color={theme.text.primary} bold>
+        {title || 'Topic'}
+      </Text>
+      {intent && <Text color={theme.text.secondary}> — {intent}</Text>}
+    </Box>
+  );
+};

packages/cli/src/ui/components/messages/__snapshots__/ToolGroupMessage.test.tsx.snap

@@ -74,8 +74,9 @@ exports[`<ToolGroupMessage /> > Golden Snapshots > renders header when scrolled
 "
 `;
 
-exports[`<ToolGroupMessage /> > Golden Snapshots > renders mixed tool calls including shell command 1`] = `
-"╭──────────────────────────────────────────────────────────────────────────╮
+exports[`<ToolGroupMessage /> > Golden Snapshots > renders mixed tool calls including update_topic 1`] = `
+"  Testing Topic — This is the description
+╭──────────────────────────────────────────────────────────────────────────╮
 │ ✓  read_file Read a file                                                 │
 │                                                                          │
 │ Test result                                                              │
@@ -137,6 +138,11 @@ exports[`<ToolGroupMessage /> > Golden Snapshots > renders two tool groups where
 "
 `;
 
+exports[`<ToolGroupMessage /> > Golden Snapshots > renders update_topic tool call using TopicMessage > update_topic_tool 1`] = `
+"  Testing Topic — This is the description
+"
+`;
+
 exports[`<ToolGroupMessage /> > Golden Snapshots > renders with limited terminal height 1`] = `
 "╭──────────────────────────────────────────────────────────────────────────╮
 │ ✓  tool-with-result Tool with output                                     │

packages/cli/src/ui/contexts/KeypressContext.tsx

@@ -205,6 +205,8 @@ const MAC_ALT_KEY_CHARACTER_MAP: Record<string, string> = {
   '\u03A9': 'z', // "Ω" Option+z
   '\u00B8': 'Z', // "¸" Option+Shift+z
   '\u2202': 'd', // "∂" delete word forward
+  '\u2020': 't', // "†" toggle full screen buffer
+  '\u00E5': 'a', // "å" Option+a for alternate buffer
 };
 
 function nonKeyboardEventFilter(

packages/cli/src/ui/contexts/UIActionsContext.tsx

@@ -70,6 +70,7 @@ export interface UIActions {
   handleResumeSession: (session: SessionInfo) => Promise<void>;
   handleDeleteSession: (session: SessionInfo) => Promise<void>;
   setQueueErrorMessage: (message: string | null) => void;
+  addMessage: (message: string) => void;
   popAllMessages: () => string | undefined;
   handleApiKeySubmit: (apiKey: string) => Promise<void>;
   handleApiKeyCancel: () => void;
@@ -77,12 +78,13 @@ export interface UIActions {
   setShortcutsHelpVisible: (visible: boolean) => void;
   setCleanUiDetailsVisible: (visible: boolean) => void;
   toggleCleanUiDetailsVisible: () => void;
+  toggleAlternateBuffer: () => void;
   revealCleanUiDetailsTemporarily: (durationMs?: number) => void;
   handleWarning: (message: string) => void;
   setEmbeddedShellFocused: (value: boolean) => void;
-  dismissBackgroundShell: (pid: number) => Promise<void>;
-  setActiveBackgroundShellPid: (pid: number) => void;
-  setIsBackgroundShellListOpen: (isOpen: boolean) => void;
+  dismissBackgroundTask: (pid: number) => Promise<void>;
+  setActiveBackgroundTaskPid: (pid: number) => void;
+  setIsBackgroundTaskListOpen: (isOpen: boolean) => void;
   setAuthContext: (context: { requiresRestart?: boolean }) => void;
   onHintInput: (char: string) => void;
   onHintBackspace: () => void;

packages/cli/src/ui/contexts/UIStateContext.tsx

@@ -84,7 +84,7 @@ export interface EmptyWalletDialogRequest {
 import { type UseHistoryManagerReturn } from '../hooks/useHistoryManager.js';
 import { type RestartReason } from '../hooks/useIdeTrustListener.js';
 import type { TerminalBackgroundColor } from '../utils/terminalCapabilityManager.js';
-import type { BackgroundShell } from '../hooks/shellCommandProcessor.js';
+import type { BackgroundTask } from '../hooks/useExecutionLifecycle.js';
 
 export interface QuotaState {
   userTier: UserTierId | undefined;
@@ -118,6 +118,8 @@ export interface UIState {
   isEditorDialogOpen: boolean;
   showPrivacyNotice: boolean;
   corgiMode: boolean;
+  isAlternateBuffer: boolean;
+  showIsAlternateBufferHint: boolean;
   debugMessage: string;
   quittingMessages: HistoryItem[] | null;
   isSettingsDialogOpen: boolean;
@@ -201,8 +203,8 @@ export interface UIState {
   isRestarting: boolean;
   extensionsUpdateState: Map<string, ExtensionUpdateState>;
   activePtyId: number | undefined;
-  backgroundShellCount: number;
-  isBackgroundShellVisible: boolean;
+  backgroundTaskCount: number;
+  isBackgroundTaskVisible: boolean;
   embeddedShellFocused: boolean;
   showDebugProfiler: boolean;
   showFullTodos: boolean;
@@ -215,10 +217,10 @@ export interface UIState {
   customDialog: React.ReactNode | null;
   terminalBackgroundColor: TerminalBackgroundColor;
   settingsNonce: number;
-  backgroundShells: Map<number, BackgroundShell>;
-  activeBackgroundShellPid: number | null;
-  backgroundShellHeight: number;
-  isBackgroundShellListOpen: boolean;
+  backgroundTasks: Map<number, BackgroundTask>;
+  activeBackgroundTaskPid: number | null;
+  backgroundTaskHeight: number;
+  isBackgroundTaskListOpen: boolean;
   adminSettingsChanged: boolean;
   newAgents: AgentDefinition[] | null;
   showIsExpandableHint: boolean;

packages/cli/src/ui/hooks/shellReducer.test.ts

@@ -36,27 +36,27 @@ describe('shellReducer', () => {
   it('should handle SET_VISIBILITY', () => {
     const action: ShellAction = { type: 'SET_VISIBILITY', visible: true };
     const state = shellReducer(initialState, action);
-    expect(state.isBackgroundShellVisible).toBe(true);
+    expect(state.isBackgroundTaskVisible).toBe(true);
   });
 
   it('should handle TOGGLE_VISIBILITY', () => {
     const action: ShellAction = { type: 'TOGGLE_VISIBILITY' };
     let state = shellReducer(initialState, action);
-    expect(state.isBackgroundShellVisible).toBe(true);
+    expect(state.isBackgroundTaskVisible).toBe(true);
     state = shellReducer(state, action);
-    expect(state.isBackgroundShellVisible).toBe(false);
+    expect(state.isBackgroundTaskVisible).toBe(false);
   });
 
-  it('should handle REGISTER_SHELL', () => {
+  it('should handle REGISTER_TASK', () => {
     const action: ShellAction = {
-      type: 'REGISTER_SHELL',
+      type: 'REGISTER_TASK',
       pid: 1001,
       command: 'ls',
       initialOutput: 'init',
     };
     const state = shellReducer(initialState, action);
-    expect(state.backgroundShells.has(1001)).toBe(true);
-    expect(state.backgroundShells.get(1001)).toEqual({
+    expect(state.backgroundTasks.has(1001)).toBe(true);
+    expect(state.backgroundTasks.get(1001)).toEqual({
       pid: 1001,
       command: 'ls',
       output: 'init',
@@ -66,9 +66,9 @@ describe('shellReducer', () => {
     });
   });
 
-  it('should not REGISTER_SHELL if PID already exists', () => {
+  it('should not REGISTER_TASK if PID already exists', () => {
     const action: ShellAction = {
-      type: 'REGISTER_SHELL',
+      type: 'REGISTER_TASK',
       pid: 1001,
       command: 'ls',
       initialOutput: 'init',
@@ -76,35 +76,35 @@ describe('shellReducer', () => {
     const state = shellReducer(initialState, action);
     const state2 = shellReducer(state, { ...action, command: 'other' });
     expect(state2).toBe(state);
-    expect(state2.backgroundShells.get(1001)?.command).toBe('ls');
+    expect(state2.backgroundTasks.get(1001)?.command).toBe('ls');
   });
 
-  it('should handle UPDATE_SHELL', () => {
+  it('should handle UPDATE_TASK', () => {
     const registeredState = shellReducer(initialState, {
-      type: 'REGISTER_SHELL',
+      type: 'REGISTER_TASK',
       pid: 1001,
       command: 'ls',
       initialOutput: 'init',
     });
 
     const action: ShellAction = {
-      type: 'UPDATE_SHELL',
+      type: 'UPDATE_TASK',
       pid: 1001,
       update: { status: 'exited', exitCode: 0 },
     };
     const state = shellReducer(registeredState, action);
-    const shell = state.backgroundShells.get(1001);
+    const shell = state.backgroundTasks.get(1001);
     expect(shell?.status).toBe('exited');
     expect(shell?.exitCode).toBe(0);
     // Map should be new
-    expect(state.backgroundShells).not.toBe(registeredState.backgroundShells);
+    expect(state.backgroundTasks).not.toBe(registeredState.backgroundTasks);
   });
 
-  it('should handle APPEND_SHELL_OUTPUT when visible (triggers re-render)', () => {
+  it('should handle APPEND_TASK_OUTPUT when visible (triggers re-render)', () => {
     const visibleState: ShellState = {
       ...initialState,
-      isBackgroundShellVisible: true,
-      backgroundShells: new Map([
+      isBackgroundTaskVisible: true,
+      backgroundTasks: new Map([
         [
           1001,
           {
@@ -120,21 +120,21 @@ describe('shellReducer', () => {
     };
 
     const action: ShellAction = {
-      type: 'APPEND_SHELL_OUTPUT',
+      type: 'APPEND_TASK_OUTPUT',
       pid: 1001,
       chunk: ' + more',
     };
     const state = shellReducer(visibleState, action);
-    expect(state.backgroundShells.get(1001)?.output).toBe('init + more');
+    expect(state.backgroundTasks.get(1001)?.output).toBe('init + more');
     // Drawer is visible, so we expect a NEW map object to trigger React re-render
-    expect(state.backgroundShells).not.toBe(visibleState.backgroundShells);
+    expect(state.backgroundTasks).not.toBe(visibleState.backgroundTasks);
   });
 
-  it('should handle APPEND_SHELL_OUTPUT when hidden (no re-render optimization)', () => {
+  it('should handle APPEND_TASK_OUTPUT when hidden (no re-render optimization)', () => {
     const hiddenState: ShellState = {
       ...initialState,
-      isBackgroundShellVisible: false,
-      backgroundShells: new Map([
+      isBackgroundTaskVisible: false,
+      backgroundTasks: new Map([
         [
           1001,
           {
@@ -150,27 +150,27 @@ describe('shellReducer', () => {
     };
 
     const action: ShellAction = {
-      type: 'APPEND_SHELL_OUTPUT',
+      type: 'APPEND_TASK_OUTPUT',
       pid: 1001,
       chunk: ' + more',
     };
     const state = shellReducer(hiddenState, action);
-    expect(state.backgroundShells.get(1001)?.output).toBe('init + more');
+    expect(state.backgroundTasks.get(1001)?.output).toBe('init + more');
     // Drawer is hidden, so we expect the SAME map object (mutation optimization)
-    expect(state.backgroundShells).toBe(hiddenState.backgroundShells);
+    expect(state.backgroundTasks).toBe(hiddenState.backgroundTasks);
   });
 
-  it('should handle SYNC_BACKGROUND_SHELLS', () => {
-    const action: ShellAction = { type: 'SYNC_BACKGROUND_SHELLS' };
+  it('should handle SYNC_BACKGROUND_TASKS', () => {
+    const action: ShellAction = { type: 'SYNC_BACKGROUND_TASKS' };
     const state = shellReducer(initialState, action);
-    expect(state.backgroundShells).not.toBe(initialState.backgroundShells);
+    expect(state.backgroundTasks).not.toBe(initialState.backgroundTasks);
   });
 
-  it('should handle DISMISS_SHELL', () => {
+  it('should handle DISMISS_TASK', () => {
     const registeredState: ShellState = {
       ...initialState,
-      isBackgroundShellVisible: true,
-      backgroundShells: new Map([
+      isBackgroundTaskVisible: true,
+      backgroundTasks: new Map([
         [
           1001,
           {
@@ -185,9 +185,9 @@ describe('shellReducer', () => {
       ]),
     };
 
-    const action: ShellAction = { type: 'DISMISS_SHELL', pid: 1001 };
+    const action: ShellAction = { type: 'DISMISS_TASK', pid: 1001 };
     const state = shellReducer(registeredState, action);
-    expect(state.backgroundShells.has(1001)).toBe(false);
-    expect(state.isBackgroundShellVisible).toBe(false); // Auto-hide if last shell
+    expect(state.backgroundTasks.has(1001)).toBe(false);
+    expect(state.isBackgroundTaskVisible).toBe(false); // Auto-hide if last shell
   });
 });

packages/cli/src/ui/hooks/shellReducer.ts

@@ -4,9 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { AnsiOutput } from '@google/gemini-cli-core';
+import type { AnsiOutput, CompletionBehavior } from '@google/gemini-cli-core';
 
-export interface BackgroundShell {
+export interface BackgroundTask {
   pid: number;
   command: string;
   output: string | AnsiOutput;
@@ -14,13 +14,14 @@ export interface BackgroundShell {
   binaryBytesReceived: number;
   status: 'running' | 'exited';
   exitCode?: number;
+  completionBehavior?: CompletionBehavior;
 }
 
 export interface ShellState {
   activeShellPtyId: number | null;
   lastShellOutputTime: number;
-  backgroundShells: Map<number, BackgroundShell>;
-  isBackgroundShellVisible: boolean;
+  backgroundTasks: Map<number, BackgroundTask>;
+  isBackgroundTaskVisible: boolean;
 }
 
 export type ShellAction =
@@ -29,21 +30,22 @@ export type ShellAction =
   | { type: 'SET_VISIBILITY'; visible: boolean }
   | { type: 'TOGGLE_VISIBILITY' }
   | {
-      type: 'REGISTER_SHELL';
+      type: 'REGISTER_TASK';
       pid: number;
       command: string;
       initialOutput: string | AnsiOutput;
+      completionBehavior?: CompletionBehavior;
     }
-  | { type: 'UPDATE_SHELL'; pid: number; update: Partial<BackgroundShell> }
-  | { type: 'APPEND_SHELL_OUTPUT'; pid: number; chunk: string | AnsiOutput }
-  | { type: 'SYNC_BACKGROUND_SHELLS' }
-  | { type: 'DISMISS_SHELL'; pid: number };
+  | { type: 'UPDATE_TASK'; pid: number; update: Partial<BackgroundTask> }
+  | { type: 'APPEND_TASK_OUTPUT'; pid: number; chunk: string | AnsiOutput }
+  | { type: 'SYNC_BACKGROUND_TASKS' }
+  | { type: 'DISMISS_TASK'; pid: number };
 
 export const initialState: ShellState = {
   activeShellPtyId: null,
   lastShellOutputTime: 0,
-  backgroundShells: new Map(),
-  isBackgroundShellVisible: false,
+  backgroundTasks: new Map(),
+  isBackgroundTaskVisible: false,
 };
 
 export function shellReducer(
@@ -56,75 +58,76 @@ export function shellReducer(
     case 'SET_OUTPUT_TIME':
       return { ...state, lastShellOutputTime: action.time };
     case 'SET_VISIBILITY':
-      return { ...state, isBackgroundShellVisible: action.visible };
+      return { ...state, isBackgroundTaskVisible: action.visible };
     case 'TOGGLE_VISIBILITY':
       return {
         ...state,
-        isBackgroundShellVisible: !state.isBackgroundShellVisible,
+        isBackgroundTaskVisible: !state.isBackgroundTaskVisible,
       };
-    case 'REGISTER_SHELL': {
-      if (state.backgroundShells.has(action.pid)) return state;
-      const nextShells = new Map(state.backgroundShells);
-      nextShells.set(action.pid, {
+    case 'REGISTER_TASK': {
+      if (state.backgroundTasks.has(action.pid)) return state;
+      const nextTasks = new Map(state.backgroundTasks);
+      nextTasks.set(action.pid, {
         pid: action.pid,
         command: action.command,
         output: action.initialOutput,
         isBinary: false,
         binaryBytesReceived: 0,
         status: 'running',
+        completionBehavior: action.completionBehavior,
       });
-      return { ...state, backgroundShells: nextShells };
+      return { ...state, backgroundTasks: nextTasks };
     }
-    case 'UPDATE_SHELL': {
-      const shell = state.backgroundShells.get(action.pid);
-      if (!shell) return state;
-      const nextShells = new Map(state.backgroundShells);
-      const updatedShell = { ...shell, ...action.update };
+    case 'UPDATE_TASK': {
+      const task = state.backgroundTasks.get(action.pid);
+      if (!task) return state;
+      const nextTasks = new Map(state.backgroundTasks);
+      const updatedTask = { ...task, ...action.update };
       // Maintain insertion order, move to end if status changed to exited
       if (action.update.status === 'exited') {
-        nextShells.delete(action.pid);
+        nextTasks.delete(action.pid);
       }
-      nextShells.set(action.pid, updatedShell);
-      return { ...state, backgroundShells: nextShells };
+      nextTasks.set(action.pid, updatedTask);
+      return { ...state, backgroundTasks: nextTasks };
     }
-    case 'APPEND_SHELL_OUTPUT': {
-      const shell = state.backgroundShells.get(action.pid);
-      if (!shell) return state;
-      // Note: we mutate the shell object in the map for background updates
+    case 'APPEND_TASK_OUTPUT': {
+      const task = state.backgroundTasks.get(action.pid);
+      if (!task) return state;
+      // Note: we mutate the task object in the map for background updates
       // to avoid re-rendering if the drawer is not visible.
       // This is an intentional performance optimization for the CLI.
-      let newOutput = shell.output;
+      let newOutput = task.output;
       if (typeof action.chunk === 'string') {
         newOutput =
-          typeof shell.output === 'string'
-            ? shell.output + action.chunk
+          typeof task.output === 'string'
+            ? task.output + action.chunk
             : action.chunk;
       } else {
         newOutput = action.chunk;
       }
-      shell.output = newOutput;
+      task.output = newOutput;
 
       const nextState = { ...state, lastShellOutputTime: Date.now() };
 
-      if (state.isBackgroundShellVisible) {
+      if (state.isBackgroundTaskVisible) {
         return {
           ...nextState,
-          backgroundShells: new Map(state.backgroundShells),
+          backgroundTasks: new Map(state.backgroundTasks),
         };
       }
       return nextState;
     }
-    case 'SYNC_BACKGROUND_SHELLS': {
-      return { ...state, backgroundShells: new Map(state.backgroundShells) };
+    case 'SYNC_BACKGROUND_TASKS': {
+      return { ...state, backgroundTasks: new Map(state.backgroundTasks) };
     }
-    case 'DISMISS_SHELL': {
-      const nextShells = new Map(state.backgroundShells);
-      nextShells.delete(action.pid);
+    case 'DISMISS_TASK': {
+      const nextTasks = new Map(state.backgroundTasks);
+      nextTasks.delete(action.pid);
       return {
         ...state,
-        backgroundShells: nextShells,
-        isBackgroundShellVisible:
-          nextShells.size === 0 ? false : state.isBackgroundShellVisible,
+        backgroundTasks: nextTasks,
+        isBackgroundTaskVisible:
+          nextTasks.size === 0 ? false : state.isBackgroundTaskVisible,
       };
     }
     default:

packages/cli/src/ui/hooks/slashCommandProcessor.test.tsx

@@ -213,7 +213,7 @@ describe('useSlashCommandProcessor', () => {
             toggleDebugProfiler: vi.fn(),
             dispatchExtensionStateUpdate: vi.fn(),
             addConfirmUpdateExtensionRequest: vi.fn(),
-            toggleBackgroundShell: vi.fn(),
+            toggleBackgroundTasks: vi.fn(),
             toggleShortcutsHelp: vi.fn(),
             setText: vi.fn(),
           },

packages/cli/src/ui/hooks/slashCommandProcessor.ts

@@ -84,7 +84,7 @@ interface SlashCommandProcessorActions {
   toggleDebugProfiler: () => void;
   dispatchExtensionStateUpdate: (action: ExtensionUpdateAction) => void;
   addConfirmUpdateExtensionRequest: (request: ConfirmationRequest) => void;
-  toggleBackgroundShell: () => void;
+  toggleBackgroundTasks: () => void;
   toggleShortcutsHelp: () => void;
   setText: (text: string) => void;
 }
@@ -242,7 +242,7 @@ export const useSlashCommandProcessor = (
           actions.addConfirmUpdateExtensionRequest,
         setConfirmationRequest,
         removeComponent: () => setCustomDialog(null),
-        toggleBackgroundShell: actions.toggleBackgroundShell,
+        toggleBackgroundTasks: actions.toggleBackgroundTasks,
         toggleShortcutsHelp: actions.toggleShortcutsHelp,
       },
       session: {

packages/cli/src/ui/hooks/toolMapping.ts

@@ -50,6 +50,7 @@ export function mapToDisplay(
       callId: call.request.callId,
       parentCallId: call.request.parentCallId,
       name: displayName,
+      args: call.request.args,
       description,
       renderOutputAsMarkdown,
     };

packages/cli/src/ui/hooks/useAlternateBuffer.test.ts

@@ -11,49 +11,47 @@ import {
   isAlternateBufferEnabled,
 } from './useAlternateBuffer.js';
 import type { Config } from '@google/gemini-cli-core';
+import { useUIState } from '../contexts/UIStateContext.js';
 
-vi.mock('../contexts/ConfigContext.js', () => ({
-  useConfig: vi.fn(),
-}));
+vi.mock('../contexts/UIStateContext.js');
 
-const mockUseConfig = vi.mocked(
-  await import('../contexts/ConfigContext.js').then((m) => m.useConfig),
-);
+const mockUseUIState = vi.mocked(useUIState);
 
 describe('useAlternateBuffer', () => {
   beforeEach(() => {
     vi.clearAllMocks();
   });
 
-  it('should return false when config.getUseAlternateBuffer returns false', async () => {
-    mockUseConfig.mockReturnValue({
-      getUseAlternateBuffer: () => false,
-    } as unknown as ReturnType<typeof mockUseConfig>);
+  it('should return false when uiState.isAlternateBuffer is false', async () => {
+    mockUseUIState.mockReturnValue({
+      isAlternateBuffer: false,
+    } as unknown as ReturnType<typeof mockUseUIState>);
 
     const { result } = await renderHook(() => useAlternateBuffer());
     expect(result.current).toBe(false);
   });
 
-  it('should return true when config.getUseAlternateBuffer returns true', async () => {
-    mockUseConfig.mockReturnValue({
-      getUseAlternateBuffer: () => true,
-    } as unknown as ReturnType<typeof mockUseConfig>);
+  it('should return true when uiState.isAlternateBuffer is true', async () => {
+    mockUseUIState.mockReturnValue({
+      isAlternateBuffer: true,
+    } as unknown as ReturnType<typeof mockUseUIState>);
 
     const { result } = await renderHook(() => useAlternateBuffer());
     expect(result.current).toBe(true);
   });
 
-  it('should return the immutable config value, not react to settings changes', async () => {
-    const mockConfig = {
-      getUseAlternateBuffer: () => true,
-    } as unknown as ReturnType<typeof mockUseConfig>;
-
-    mockUseConfig.mockReturnValue(mockConfig);
+  it('should react to state changes', async () => {
+    mockUseUIState.mockReturnValue({
+      isAlternateBuffer: false,
+    } as unknown as ReturnType<typeof mockUseUIState>);
 
     const { result, rerender } = await renderHook(() => useAlternateBuffer());
 
-    // Value should remain true even after rerender
-    expect(result.current).toBe(true);
+    expect(result.current).toBe(false);
+
+    mockUseUIState.mockReturnValue({
+      isAlternateBuffer: true,
+    } as unknown as ReturnType<typeof mockUseUIState>);
 
     rerender();
 

packages/cli/src/ui/hooks/useAlternateBuffer.ts

@@ -4,14 +4,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { useConfig } from '../contexts/ConfigContext.js';
+import { useUIState } from '../contexts/UIStateContext.js';
 import type { Config } from '@google/gemini-cli-core';
 
 export const isAlternateBufferEnabled = (config: Config): boolean =>
   config.getUseAlternateBuffer();
 
-// This is read from Config so that the UI reads the same value per application session
+// This is read from UIState so that the UI can toggle dynamically
 export const useAlternateBuffer = (): boolean => {
-  const config = useConfig();
-  return isAlternateBufferEnabled(config);
+  const uiState = useUIState();
+  return uiState.isAlternateBuffer;
 };

packages/cli/src/ui/hooks/useBackgroundShellManager.test.tsx

@@ -1,191 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { render } from '../../test-utils/render.js';
-import {
-  useBackgroundShellManager,
-  type BackgroundShellManagerProps,
-} from './useBackgroundShellManager.js';
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { act } from 'react';
-import { type BackgroundShell } from './shellReducer.js';
-
-describe('useBackgroundShellManager', () => {
-  const setEmbeddedShellFocused = vi.fn();
-  const terminalHeight = 30;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  const renderHook = async (props: BackgroundShellManagerProps) => {
-    let hookResult: ReturnType<typeof useBackgroundShellManager>;
-    function TestComponent({ p }: { p: BackgroundShellManagerProps }) {
-      hookResult = useBackgroundShellManager(p);
-      return null;
-    }
-    const { rerender } = await render(<TestComponent p={props} />);
-    return {
-      result: {
-        get current() {
-          return hookResult;
-        },
-      },
-      rerender: (newProps: BackgroundShellManagerProps) =>
-        rerender(<TestComponent p={newProps} />),
-    };
-  };
-
-  it('should initialize with correct default values', async () => {
-    const backgroundShells = new Map<number, BackgroundShell>();
-    const { result } = await renderHook({
-      backgroundShells,
-      backgroundShellCount: 0,
-      isBackgroundShellVisible: false,
-      activePtyId: null,
-      embeddedShellFocused: false,
-      setEmbeddedShellFocused,
-      terminalHeight,
-    });
-
-    expect(result.current.isBackgroundShellListOpen).toBe(false);
-    expect(result.current.activeBackgroundShellPid).toBe(null);
-    expect(result.current.backgroundShellHeight).toBe(0);
-  });
-
-  it('should auto-select the first background shell when added', async () => {
-    const backgroundShells = new Map<number, BackgroundShell>();
-    const { result, rerender } = await renderHook({
-      backgroundShells,
-      backgroundShellCount: 0,
-      isBackgroundShellVisible: false,
-      activePtyId: null,
-      embeddedShellFocused: false,
-      setEmbeddedShellFocused,
-      terminalHeight,
-    });
-
-    const newShells = new Map<number, BackgroundShell>([
-      [123, {} as BackgroundShell],
-    ]);
-    rerender({
-      backgroundShells: newShells,
-      backgroundShellCount: 1,
-      isBackgroundShellVisible: false,
-      activePtyId: null,
-      embeddedShellFocused: false,
-      setEmbeddedShellFocused,
-      terminalHeight,
-    });
-
-    expect(result.current.activeBackgroundShellPid).toBe(123);
-  });
-
-  it('should reset state when all shells are removed', async () => {
-    const backgroundShells = new Map<number, BackgroundShell>([
-      [123, {} as BackgroundShell],
-    ]);
-    const { result, rerender } = await renderHook({
-      backgroundShells,
-      backgroundShellCount: 1,
-      isBackgroundShellVisible: true,
-      activePtyId: null,
-      embeddedShellFocused: true,
-      setEmbeddedShellFocused,
-      terminalHeight,
-    });
-
-    act(() => {
-      result.current.setIsBackgroundShellListOpen(true);
-    });
-    expect(result.current.isBackgroundShellListOpen).toBe(true);
-
-    rerender({
-      backgroundShells: new Map(),
-      backgroundShellCount: 0,
-      isBackgroundShellVisible: true,
-      activePtyId: null,
-      embeddedShellFocused: true,
-      setEmbeddedShellFocused,
-      terminalHeight,
-    });
-
-    expect(result.current.activeBackgroundShellPid).toBe(null);
-    expect(result.current.isBackgroundShellListOpen).toBe(false);
-  });
-
-  it('should unfocus embedded shell when no shells are active', async () => {
-    const backgroundShells = new Map<number, BackgroundShell>([
-      [123, {} as BackgroundShell],
-    ]);
-    await renderHook({
-      backgroundShells,
-      backgroundShellCount: 1,
-      isBackgroundShellVisible: false, // Background shell not visible
-      activePtyId: null, // No foreground shell
-      embeddedShellFocused: true,
-      setEmbeddedShellFocused,
-      terminalHeight,
-    });
-
-    expect(setEmbeddedShellFocused).toHaveBeenCalledWith(false);
-  });
-
-  it('should calculate backgroundShellHeight correctly when visible', async () => {
-    const backgroundShells = new Map<number, BackgroundShell>([
-      [123, {} as BackgroundShell],
-    ]);
-    const { result } = await renderHook({
-      backgroundShells,
-      backgroundShellCount: 1,
-      isBackgroundShellVisible: true,
-      activePtyId: null,
-      embeddedShellFocused: true,
-      setEmbeddedShellFocused,
-      terminalHeight: 100,
-    });
-
-    // 100 * 0.3 = 30
-    expect(result.current.backgroundShellHeight).toBe(30);
-  });
-
-  it('should maintain current active shell if it still exists', async () => {
-    const backgroundShells = new Map<number, BackgroundShell>([
-      [123, {} as BackgroundShell],
-      [456, {} as BackgroundShell],
-    ]);
-    const { result, rerender } = await renderHook({
-      backgroundShells,
-      backgroundShellCount: 2,
-      isBackgroundShellVisible: true,
-      activePtyId: null,
-      embeddedShellFocused: true,
-      setEmbeddedShellFocused,
-      terminalHeight,
-    });
-
-    act(() => {
-      result.current.setActiveBackgroundShellPid(456);
-    });
-    expect(result.current.activeBackgroundShellPid).toBe(456);
-
-    // Remove the OTHER shell
-    const updatedShells = new Map<number, BackgroundShell>([
-      [456, {} as BackgroundShell],
-    ]);
-    rerender({
-      backgroundShells: updatedShells,
-      backgroundShellCount: 1,
-      isBackgroundShellVisible: true,
-      activePtyId: null,
-      embeddedShellFocused: true,
-      setEmbeddedShellFocused,
-      terminalHeight,
-    });
-
-    expect(result.current.activeBackgroundShellPid).toBe(456);
-  });
-});

packages/cli/src/ui/hooks/useBackgroundShellManager.ts

@@ -1,91 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { useState, useEffect, useMemo } from 'react';
-import { type BackgroundShell } from './shellCommandProcessor.js';
-
-export interface BackgroundShellManagerProps {
-  backgroundShells: Map<number, BackgroundShell>;
-  backgroundShellCount: number;
-  isBackgroundShellVisible: boolean;
-  activePtyId: number | null | undefined;
-  embeddedShellFocused: boolean;
-  setEmbeddedShellFocused: (focused: boolean) => void;
-  terminalHeight: number;
-}
-
-export function useBackgroundShellManager({
-  backgroundShells,
-  backgroundShellCount,
-  isBackgroundShellVisible,
-  activePtyId,
-  embeddedShellFocused,
-  setEmbeddedShellFocused,
-  terminalHeight,
-}: BackgroundShellManagerProps) {
-  const [isBackgroundShellListOpen, setIsBackgroundShellListOpen] =
-    useState(false);
-  const [activeBackgroundShellPid, setActiveBackgroundShellPid] = useState<
-    number | null
-  >(null);
-
-  useEffect(() => {
-    if (backgroundShells.size === 0) {
-      if (activeBackgroundShellPid !== null) {
-        setActiveBackgroundShellPid(null);
-      }
-      if (isBackgroundShellListOpen) {
-        setIsBackgroundShellListOpen(false);
-      }
-    } else if (
-      activeBackgroundShellPid === null ||
-      !backgroundShells.has(activeBackgroundShellPid)
-    ) {
-      // If active shell is closed or none selected, select the first one (last added usually, or just first in iteration)
-      setActiveBackgroundShellPid(backgroundShells.keys().next().value ?? null);
-    }
-  }, [
-    backgroundShells,
-    activeBackgroundShellPid,
-    backgroundShellCount,
-    isBackgroundShellListOpen,
-  ]);
-
-  useEffect(() => {
-    if (embeddedShellFocused) {
-      const hasActiveForegroundShell = !!activePtyId;
-      const hasVisibleBackgroundShell =
-        isBackgroundShellVisible && backgroundShells.size > 0;
-
-      if (!hasActiveForegroundShell && !hasVisibleBackgroundShell) {
-        setEmbeddedShellFocused(false);
-      }
-    }
-  }, [
-    isBackgroundShellVisible,
-    backgroundShells,
-    embeddedShellFocused,
-    backgroundShellCount,
-    activePtyId,
-    setEmbeddedShellFocused,
-  ]);
-
-  const backgroundShellHeight = useMemo(
-    () =>
-      isBackgroundShellVisible && backgroundShells.size > 0
-        ? Math.max(Math.floor(terminalHeight * 0.3), 5)
-        : 0,
-    [isBackgroundShellVisible, backgroundShells.size, terminalHeight],
-  );
-
-  return {
-    isBackgroundShellListOpen,
-    setIsBackgroundShellListOpen,
-    activeBackgroundShellPid,
-    setActiveBackgroundShellPid,
-    backgroundShellHeight,
-  };
-}

packages/cli/src/ui/hooks/useBackgroundTaskManager.test.tsx

@@ -0,0 +1,191 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { render } from '../../test-utils/render.js';
+import {
+  useBackgroundTaskManager,
+  type BackgroundTaskManagerProps,
+} from './useBackgroundTaskManager.js';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { act } from 'react';
+import { type BackgroundTask } from './shellReducer.js';
+
+describe('useBackgroundTaskManager', () => {
+  const setEmbeddedShellFocused = vi.fn();
+  const terminalHeight = 30;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const renderHook = async (props: BackgroundTaskManagerProps) => {
+    let hookResult: ReturnType<typeof useBackgroundTaskManager>;
+    function TestComponent({ p }: { p: BackgroundTaskManagerProps }) {
+      hookResult = useBackgroundTaskManager(p);
+      return null;
+    }
+    const { rerender } = await render(<TestComponent p={props} />);
+    return {
+      result: {
+        get current() {
+          return hookResult;
+        },
+      },
+      rerender: (newProps: BackgroundTaskManagerProps) =>
+        rerender(<TestComponent p={newProps} />),
+    };
+  };
+
+  it('should initialize with correct default values', async () => {
+    const backgroundTasks = new Map<number, BackgroundTask>();
+    const { result } = await renderHook({
+      backgroundTasks,
+      backgroundTaskCount: 0,
+      isBackgroundTaskVisible: false,
+      activePtyId: null,
+      embeddedShellFocused: false,
+      setEmbeddedShellFocused,
+      terminalHeight,
+    });
+
+    expect(result.current.isBackgroundTaskListOpen).toBe(false);
+    expect(result.current.activeBackgroundTaskPid).toBe(null);
+    expect(result.current.backgroundTaskHeight).toBe(0);
+  });
+
+  it('should auto-select the first background shell when added', async () => {
+    const backgroundTasks = new Map<number, BackgroundTask>();
+    const { result, rerender } = await renderHook({
+      backgroundTasks,
+      backgroundTaskCount: 0,
+      isBackgroundTaskVisible: false,
+      activePtyId: null,
+      embeddedShellFocused: false,
+      setEmbeddedShellFocused,
+      terminalHeight,
+    });
+
+    const newShells = new Map<number, BackgroundTask>([
+      [123, {} as BackgroundTask],
+    ]);
+    rerender({
+      backgroundTasks: newShells,
+      backgroundTaskCount: 1,
+      isBackgroundTaskVisible: false,
+      activePtyId: null,
+      embeddedShellFocused: false,
+      setEmbeddedShellFocused,
+      terminalHeight,
+    });
+
+    expect(result.current.activeBackgroundTaskPid).toBe(123);
+  });
+
+  it('should reset state when all shells are removed', async () => {
+    const backgroundTasks = new Map<number, BackgroundTask>([
+      [123, {} as BackgroundTask],
+    ]);
+    const { result, rerender } = await renderHook({
+      backgroundTasks,
+      backgroundTaskCount: 1,
+      isBackgroundTaskVisible: true,
+      activePtyId: null,
+      embeddedShellFocused: true,
+      setEmbeddedShellFocused,
+      terminalHeight,
+    });
+
+    act(() => {
+      result.current.setIsBackgroundTaskListOpen(true);
+    });
+    expect(result.current.isBackgroundTaskListOpen).toBe(true);
+
+    rerender({
+      backgroundTasks: new Map(),
+      backgroundTaskCount: 0,
+      isBackgroundTaskVisible: true,
+      activePtyId: null,
+      embeddedShellFocused: true,
+      setEmbeddedShellFocused,
+      terminalHeight,
+    });
+
+    expect(result.current.activeBackgroundTaskPid).toBe(null);
+    expect(result.current.isBackgroundTaskListOpen).toBe(false);
+  });
+
+  it('should unfocus embedded shell when no shells are active', async () => {
+    const backgroundTasks = new Map<number, BackgroundTask>([
+      [123, {} as BackgroundTask],
+    ]);
+    await renderHook({
+      backgroundTasks,
+      backgroundTaskCount: 1,
+      isBackgroundTaskVisible: false, // Background shell not visible
+      activePtyId: null, // No foreground shell
+      embeddedShellFocused: true,
+      setEmbeddedShellFocused,
+      terminalHeight,
+    });
+
+    expect(setEmbeddedShellFocused).toHaveBeenCalledWith(false);
+  });
+
+  it('should calculate backgroundTaskHeight correctly when visible', async () => {
+    const backgroundTasks = new Map<number, BackgroundTask>([
+      [123, {} as BackgroundTask],
+    ]);
+    const { result } = await renderHook({
+      backgroundTasks,
+      backgroundTaskCount: 1,
+      isBackgroundTaskVisible: true,
+      activePtyId: null,
+      embeddedShellFocused: true,
+      setEmbeddedShellFocused,
+      terminalHeight: 100,
+    });
+
+    // 100 * 0.3 = 30
+    expect(result.current.backgroundTaskHeight).toBe(30);
+  });
+
+  it('should maintain current active shell if it still exists', async () => {
+    const backgroundTasks = new Map<number, BackgroundTask>([
+      [123, {} as BackgroundTask],
+      [456, {} as BackgroundTask],
+    ]);
+    const { result, rerender } = await renderHook({
+      backgroundTasks,
+      backgroundTaskCount: 2,
+      isBackgroundTaskVisible: true,
+      activePtyId: null,
+      embeddedShellFocused: true,
+      setEmbeddedShellFocused,
+      terminalHeight,
+    });
+
+    act(() => {
+      result.current.setActiveBackgroundTaskPid(456);
+    });
+    expect(result.current.activeBackgroundTaskPid).toBe(456);
+
+    // Remove the OTHER shell
+    const updatedShells = new Map<number, BackgroundTask>([
+      [456, {} as BackgroundTask],
+    ]);
+    rerender({
+      backgroundTasks: updatedShells,
+      backgroundTaskCount: 1,
+      isBackgroundTaskVisible: true,
+      activePtyId: null,
+      embeddedShellFocused: true,
+      setEmbeddedShellFocused,
+      terminalHeight,
+    });
+
+    expect(result.current.activeBackgroundTaskPid).toBe(456);
+  });
+});

packages/cli/src/ui/hooks/useBackgroundTaskManager.ts

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useState, useEffect, useMemo } from 'react';
+import { type BackgroundTask } from './useExecutionLifecycle.js';
+
+export interface BackgroundTaskManagerProps {
+  backgroundTasks: Map<number, BackgroundTask>;
+  backgroundTaskCount: number;
+  isBackgroundTaskVisible: boolean;
+  activePtyId: number | null | undefined;
+  embeddedShellFocused: boolean;
+  setEmbeddedShellFocused: (focused: boolean) => void;
+  terminalHeight: number;
+}
+
+export function useBackgroundTaskManager({
+  backgroundTasks,
+  backgroundTaskCount,
+  isBackgroundTaskVisible,
+  activePtyId,
+  embeddedShellFocused,
+  setEmbeddedShellFocused,
+  terminalHeight,
+}: BackgroundTaskManagerProps) {
+  const [isBackgroundTaskListOpen, setIsBackgroundTaskListOpen] =
+    useState(false);
+  const [activeBackgroundTaskPid, setActiveBackgroundTaskPid] = useState<
+    number | null
+  >(null);
+
+  useEffect(() => {
+    if (backgroundTasks.size === 0) {
+      if (activeBackgroundTaskPid !== null) {
+        setActiveBackgroundTaskPid(null);
+      }
+      if (isBackgroundTaskListOpen) {
+        setIsBackgroundTaskListOpen(false);
+      }
+    } else if (
+      activeBackgroundTaskPid === null ||
+      !backgroundTasks.has(activeBackgroundTaskPid)
+    ) {
+      // If active shell is closed or none selected, select the first one (last added usually, or just first in iteration)
+      setActiveBackgroundTaskPid(backgroundTasks.keys().next().value ?? null);
+    }
+  }, [
+    backgroundTasks,
+    activeBackgroundTaskPid,
+    backgroundTaskCount,
+    isBackgroundTaskListOpen,
+  ]);
+
+  useEffect(() => {
+    if (embeddedShellFocused) {
+      const hasActiveForegroundShell = !!activePtyId;
+      const hasVisibleBackgroundTask =
+        isBackgroundTaskVisible && backgroundTasks.size > 0;
+
+      if (!hasActiveForegroundShell && !hasVisibleBackgroundTask) {
+        setEmbeddedShellFocused(false);
+      }
+    }
+  }, [
+    isBackgroundTaskVisible,
+    backgroundTasks,
+    embeddedShellFocused,
+    backgroundTaskCount,
+    activePtyId,
+    setEmbeddedShellFocused,
+  ]);
+
+  const backgroundTaskHeight = useMemo(
+    () =>
+      isBackgroundTaskVisible && backgroundTasks.size > 0
+        ? Math.max(Math.floor(terminalHeight * 0.3), 5)
+        : 0,
+    [isBackgroundTaskVisible, backgroundTasks.size, terminalHeight],
+  );
+
+  return {
+    isBackgroundTaskListOpen,
+    setIsBackgroundTaskListOpen,
+    activeBackgroundTaskPid,
+    setActiveBackgroundTaskPid,
+    backgroundTaskHeight,
+  };
+}

packages/cli/src/ui/hooks/useComposerStatus.ts

@@ -49,7 +49,7 @@ export const useComposerStatus = () => {
   );
 
   const showLoadingIndicator =
-    (!uiState.embeddedShellFocused || uiState.isBackgroundShellVisible) &&
+    (!uiState.embeddedShellFocused || uiState.isBackgroundTaskVisible) &&
     uiState.streamingState === StreamingState.Responding &&
     !hasPendingActionRequired;
 

packages/cli/src/ui/hooks/useExecutionLifecycle.test.tsx

@@ -35,6 +35,23 @@ const mockShellOnExit = vi.hoisted(() =>
     ) => () => void
   >(() => vi.fn()),
 );
+const mockLifecycleSubscribe = vi.hoisted(() =>
+  vi.fn<
+    (pid: number, listener: (event: ShellOutputEvent) => void) => () => void
+  >(() => vi.fn()),
+);
+const mockLifecycleOnExit = vi.hoisted(() =>
+  vi.fn<
+    (
+      pid: number,
+      callback: (exitCode: number, signal?: number) => void,
+    ) => () => void
+  >(() => vi.fn()),
+);
+const mockLifecycleKill = vi.hoisted(() => vi.fn());
+const mockLifecycleBackground = vi.hoisted(() => vi.fn());
+const mockLifecycleOnBackground = vi.hoisted(() => vi.fn());
+const mockLifecycleOffBackground = vi.hoisted(() => vi.fn());
 
 vi.mock('@google/gemini-cli-core', async (importOriginal) => {
   const actual =
@@ -48,6 +65,14 @@ vi.mock('@google/gemini-cli-core', async (importOriginal) => {
       subscribe: mockShellSubscribe,
       onExit: mockShellOnExit,
     },
+    ExecutionLifecycleService: {
+      subscribe: mockLifecycleSubscribe,
+      onExit: mockLifecycleOnExit,
+      kill: mockLifecycleKill,
+      background: mockLifecycleBackground,
+      onBackground: mockLifecycleOnBackground,
+      offBackground: mockLifecycleOffBackground,
+    },
     isBinary: mockIsBinary,
   };
 });
@@ -68,9 +93,9 @@ vi.mock('node:os', async (importOriginal) => {
 vi.mock('node:crypto');
 
 import {
-  useShellCommandProcessor,
+  useExecutionLifecycle,
   OUTPUT_UPDATE_INTERVAL_MS,
-} from './shellCommandProcessor.js';
+} from './useExecutionLifecycle.js';
 import {
   type Config,
   type GeminiClient,
@@ -83,7 +108,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 
-describe('useShellCommandProcessor', () => {
+describe('useExecutionLifecycle', () => {
   let addItemToHistoryMock: Mock;
   let setPendingHistoryItemMock: Mock;
   let onExecMock: Mock;
@@ -140,7 +165,7 @@ describe('useShellCommandProcessor', () => {
   });
 
   const renderProcessorHook = async () => {
-    let hookResult: ReturnType<typeof useShellCommandProcessor>;
+    let hookResult: ReturnType<typeof useExecutionLifecycle>;
     let renderCount = 0;
     function TestComponent({
       isWaitingForConfirmation,
@@ -148,7 +173,7 @@ describe('useShellCommandProcessor', () => {
       isWaitingForConfirmation?: boolean;
     }) {
       renderCount++;
-      hookResult = useShellCommandProcessor(
+      hookResult = useExecutionLifecycle(
         addItemToHistoryMock,
         setPendingHistoryItemMock,
         onExecMock,
@@ -772,11 +797,11 @@ describe('useShellCommandProcessor', () => {
       const { result } = await renderProcessorHook();
 
       act(() => {
-        result.current.registerBackgroundShell(1001, 'bg-cmd', 'initial');
+        result.current.registerBackgroundTask(1001, 'bg-cmd', 'initial');
       });
 
-      expect(result.current.backgroundShellCount).toBe(1);
-      const shell = result.current.backgroundShells.get(1001);
+      expect(result.current.backgroundTaskCount).toBe(1);
+      const shell = result.current.backgroundTasks.get(1001);
       expect(shell).toEqual(
         expect.objectContaining({
           pid: 1001,
@@ -784,8 +809,11 @@ describe('useShellCommandProcessor', () => {
           output: 'initial',
         }),
       );
-      expect(mockShellOnExit).toHaveBeenCalledWith(1001, expect.any(Function));
-      expect(mockShellSubscribe).toHaveBeenCalledWith(
+      expect(mockLifecycleOnExit).toHaveBeenCalledWith(
+        1001,
+        expect.any(Function),
+      );
+      expect(mockLifecycleSubscribe).toHaveBeenCalledWith(
         1001,
         expect.any(Function),
       );
@@ -795,55 +823,55 @@ describe('useShellCommandProcessor', () => {
       const { result } = await renderProcessorHook();
 
       act(() => {
-        result.current.registerBackgroundShell(1001, 'bg-cmd', 'initial');
+        result.current.registerBackgroundTask(1001, 'bg-cmd', 'initial');
       });
 
-      expect(result.current.isBackgroundShellVisible).toBe(false);
+      expect(result.current.isBackgroundTaskVisible).toBe(false);
 
       act(() => {
-        result.current.toggleBackgroundShell();
+        result.current.toggleBackgroundTasks();
       });
 
-      expect(result.current.isBackgroundShellVisible).toBe(true);
+      expect(result.current.isBackgroundTaskVisible).toBe(true);
 
       act(() => {
-        result.current.toggleBackgroundShell();
+        result.current.toggleBackgroundTasks();
       });
 
-      expect(result.current.isBackgroundShellVisible).toBe(false);
+      expect(result.current.isBackgroundTaskVisible).toBe(false);
     });
 
     it('should show info message when toggling background shells if none are active', async () => {
       const { result } = await renderProcessorHook();
 
       act(() => {
-        result.current.toggleBackgroundShell();
+        result.current.toggleBackgroundTasks();
       });
 
       expect(addItemToHistoryMock).toHaveBeenCalledWith(
         expect.objectContaining({
           type: 'info',
-          text: 'No background shells are currently active.',
+          text: 'No background tasks are currently active.',
         }),
         expect.any(Number),
       );
-      expect(result.current.isBackgroundShellVisible).toBe(false);
+      expect(result.current.isBackgroundTaskVisible).toBe(false);
     });
 
     it('should dismiss a background shell and remove it from state', async () => {
       const { result } = await renderProcessorHook();
 
       act(() => {
-        result.current.registerBackgroundShell(1001, 'bg-cmd', 'initial');
+        result.current.registerBackgroundTask(1001, 'bg-cmd', 'initial');
       });
 
       await act(async () => {
-        await result.current.dismissBackgroundShell(1001);
+        await result.current.dismissBackgroundTask(1001);
       });
 
-      expect(mockShellKill).toHaveBeenCalledWith(1001);
-      expect(result.current.backgroundShellCount).toBe(0);
-      expect(result.current.backgroundShells.has(1001)).toBe(false);
+      expect(mockLifecycleKill).toHaveBeenCalledWith(1001);
+      expect(result.current.backgroundTaskCount).toBe(0);
+      expect(result.current.backgroundTasks.has(1001)).toBe(false);
     });
 
     it('should handle backgrounding the current shell', async () => {
@@ -867,7 +895,7 @@ describe('useShellCommandProcessor', () => {
       expect(result.current.activeShellPtyId).toBe(555);
 
       act(() => {
-        result.current.backgroundCurrentShell();
+        result.current.backgroundCurrentExecution();
       });
 
       expect(mockShellBackground).toHaveBeenCalledWith(555);
@@ -887,19 +915,19 @@ describe('useShellCommandProcessor', () => {
       // Wait for promise resolution
       await act(async () => await onExecMock.mock.calls[0][0]);
 
-      expect(result.current.backgroundShellCount).toBe(1);
+      expect(result.current.backgroundTaskCount).toBe(1);
       expect(result.current.activeShellPtyId).toBeNull();
     });
 
-    it('should persist background shell on successful exit and mark as exited', async () => {
+    it('should auto-dismiss background task on successful exit', async () => {
       const { result } = await renderProcessorHook();
 
       act(() => {
-        result.current.registerBackgroundShell(888, 'auto-exit', '');
+        result.current.registerBackgroundTask(888, 'auto-exit', '');
       });
 
       // Find the exit callback registered
-      const exitCallback = mockShellOnExit.mock.calls.find(
+      const exitCallback = mockLifecycleOnExit.mock.calls.find(
         (call) => call[0] === 888,
       )?.[1];
       expect(exitCallback).toBeDefined();
@@ -910,22 +938,19 @@ describe('useShellCommandProcessor', () => {
         });
       }
 
-      // Should NOT be removed, but updated
-      expect(result.current.backgroundShellCount).toBe(0); // Badge count is 0
-      expect(result.current.backgroundShells.has(888)).toBe(true); // Map has it
-      const shell = result.current.backgroundShells.get(888);
-      expect(shell?.status).toBe('exited');
-      expect(shell?.exitCode).toBe(0);
+      // Should be auto-dismissed from the panel
+      expect(result.current.backgroundTaskCount).toBe(0);
+      expect(result.current.backgroundTasks.has(888)).toBe(false);
     });
 
-    it('should persist background shell on failed exit', async () => {
+    it('should auto-dismiss background task on failed exit', async () => {
       const { result } = await renderProcessorHook();
 
       act(() => {
-        result.current.registerBackgroundShell(999, 'fail-exit', '');
+        result.current.registerBackgroundTask(999, 'fail-exit', '');
       });
 
-      const exitCallback = mockShellOnExit.mock.calls.find(
+      const exitCallback = mockLifecycleOnExit.mock.calls.find(
         (call) => call[0] === 999,
       )?.[1];
       expect(exitCallback).toBeDefined();
@@ -936,34 +961,26 @@ describe('useShellCommandProcessor', () => {
         });
       }
 
-      // Should NOT be removed, but updated
-      expect(result.current.backgroundShellCount).toBe(0); // Badge count is 0
-      const shell = result.current.backgroundShells.get(999);
-      expect(shell?.status).toBe('exited');
-      expect(shell?.exitCode).toBe(1);
-
-      // Now dismiss it
-      await act(async () => {
-        await result.current.dismissBackgroundShell(999);
-      });
-      expect(result.current.backgroundShellCount).toBe(0);
+      // Should be auto-dismissed from the panel
+      expect(result.current.backgroundTaskCount).toBe(0);
+      expect(result.current.backgroundTasks.has(999)).toBe(false);
     });
 
     it('should NOT trigger re-render on background shell output when visible', async () => {
       const { result, getRenderCount } = await renderProcessorHook();
 
       act(() => {
-        result.current.registerBackgroundShell(1001, 'bg-cmd', 'initial');
+        result.current.registerBackgroundTask(1001, 'bg-cmd', 'initial');
       });
 
       // Show the background shells
       act(() => {
-        result.current.toggleBackgroundShell();
+        result.current.toggleBackgroundTasks();
       });
 
       const initialRenderCount = getRenderCount();
 
-      const subscribeCallback = mockShellSubscribe.mock.calls.find(
+      const subscribeCallback = mockLifecycleSubscribe.mock.calls.find(
         (call) => call[0] === 1001,
       )?.[1];
       expect(subscribeCallback).toBeDefined();
@@ -975,7 +992,7 @@ describe('useShellCommandProcessor', () => {
       }
 
       expect(getRenderCount()).toBeGreaterThan(initialRenderCount);
-      const shell = result.current.backgroundShells.get(1001);
+      const shell = result.current.backgroundTasks.get(1001);
       expect(shell?.output).toBe('initial + updated');
     });
 
@@ -983,13 +1000,13 @@ describe('useShellCommandProcessor', () => {
       const { result, getRenderCount } = await renderProcessorHook();
 
       act(() => {
-        result.current.registerBackgroundShell(1001, 'bg-cmd', 'initial');
+        result.current.registerBackgroundTask(1001, 'bg-cmd', 'initial');
       });
 
       // Ensure background shells are hidden (default)
       const initialRenderCount = getRenderCount();
 
-      const subscribeCallback = mockShellSubscribe.mock.calls.find(
+      const subscribeCallback = mockLifecycleSubscribe.mock.calls.find(
         (call) => call[0] === 1001,
       )?.[1];
       expect(subscribeCallback).toBeDefined();
@@ -1001,7 +1018,7 @@ describe('useShellCommandProcessor', () => {
       }
 
       expect(getRenderCount()).toBeGreaterThan(initialRenderCount);
-      const shell = result.current.backgroundShells.get(1001);
+      const shell = result.current.backgroundTasks.get(1001);
       expect(shell?.output).toBe('initial + updated');
     });
 
@@ -1009,17 +1026,17 @@ describe('useShellCommandProcessor', () => {
       const { result, getRenderCount } = await renderProcessorHook();
 
       act(() => {
-        result.current.registerBackgroundShell(1001, 'bg-cmd', 'initial');
+        result.current.registerBackgroundTask(1001, 'bg-cmd', 'initial');
       });
 
       // Show the background shells
       act(() => {
-        result.current.toggleBackgroundShell();
+        result.current.toggleBackgroundTasks();
       });
 
       const initialRenderCount = getRenderCount();
 
-      const subscribeCallback = mockShellSubscribe.mock.calls.find(
+      const subscribeCallback = mockLifecycleSubscribe.mock.calls.find(
         (call) => call[0] === 1001,
       )?.[1];
       expect(subscribeCallback).toBeDefined();
@@ -1031,7 +1048,7 @@ describe('useShellCommandProcessor', () => {
       }
 
       expect(getRenderCount()).toBeGreaterThan(initialRenderCount);
-      const shell = result.current.backgroundShells.get(1001);
+      const shell = result.current.backgroundTasks.get(1001);
       expect(shell?.isBinary).toBe(true);
       expect(shell?.binaryBytesReceived).toBe(1024);
     });
@@ -1041,12 +1058,12 @@ describe('useShellCommandProcessor', () => {
 
       // 1. Register and show background shell
       act(() => {
-        result.current.registerBackgroundShell(1001, 'bg-cmd', 'initial');
+        result.current.registerBackgroundTask(1001, 'bg-cmd', 'initial');
       });
       act(() => {
-        result.current.toggleBackgroundShell();
+        result.current.toggleBackgroundTasks();
       });
-      expect(result.current.isBackgroundShellVisible).toBe(true);
+      expect(result.current.isBackgroundTaskVisible).toBe(true);
 
       // 2. Simulate model responding (not waiting for confirmation)
       act(() => {
@@ -1054,7 +1071,7 @@ describe('useShellCommandProcessor', () => {
       });
 
       // Should stay visible
-      expect(result.current.isBackgroundShellVisible).toBe(true);
+      expect(result.current.isBackgroundTaskVisible).toBe(true);
     });
 
     it('should hide background shell when waiting for confirmation and restore after delay', async () => {
@@ -1062,12 +1079,12 @@ describe('useShellCommandProcessor', () => {
 
       // 1. Register and show background shell
       act(() => {
-        result.current.registerBackgroundShell(1001, 'bg-cmd', 'initial');
+        result.current.registerBackgroundTask(1001, 'bg-cmd', 'initial');
       });
       act(() => {
-        result.current.toggleBackgroundShell();
+        result.current.toggleBackgroundTasks();
       });
-      expect(result.current.isBackgroundShellVisible).toBe(true);
+      expect(result.current.isBackgroundTaskVisible).toBe(true);
 
       // 2. Simulate tool confirmation showing up
       act(() => {
@@ -1075,7 +1092,7 @@ describe('useShellCommandProcessor', () => {
       });
 
       // Should be hidden
-      expect(result.current.isBackgroundShellVisible).toBe(false);
+      expect(result.current.isBackgroundTaskVisible).toBe(false);
 
       // 3. Simulate confirmation accepted (waiting for PTY start)
       act(() => {
@@ -1083,11 +1100,11 @@ describe('useShellCommandProcessor', () => {
       });
 
       // Should STAY hidden during the 300ms gap
-      expect(result.current.isBackgroundShellVisible).toBe(false);
+      expect(result.current.isBackgroundTaskVisible).toBe(false);
 
       // 4. Wait for restore delay
       await waitFor(() =>
-        expect(result.current.isBackgroundShellVisible).toBe(true),
+        expect(result.current.isBackgroundTaskVisible).toBe(true),
       );
     });
 
@@ -1096,12 +1113,12 @@ describe('useShellCommandProcessor', () => {
 
       // 1. Register and show background shell
       act(() => {
-        result.current.registerBackgroundShell(1001, 'bg-cmd', 'initial');
+        result.current.registerBackgroundTask(1001, 'bg-cmd', 'initial');
       });
       act(() => {
-        result.current.toggleBackgroundShell();
+        result.current.toggleBackgroundTasks();
       });
-      expect(result.current.isBackgroundShellVisible).toBe(true);
+      expect(result.current.isBackgroundTaskVisible).toBe(true);
 
       // 2. Start foreground shell
       act(() => {
@@ -1112,7 +1129,7 @@ describe('useShellCommandProcessor', () => {
       await waitFor(() => expect(result.current.activeShellPtyId).toBe(12345));
 
       // Should be hidden automatically
-      expect(result.current.isBackgroundShellVisible).toBe(false);
+      expect(result.current.isBackgroundTaskVisible).toBe(false);
 
       // 3. Complete foreground shell
       act(() => {
@@ -1123,7 +1140,7 @@ describe('useShellCommandProcessor', () => {
 
       // Should be restored automatically (after delay)
       await waitFor(() =>
-        expect(result.current.isBackgroundShellVisible).toBe(true),
+        expect(result.current.isBackgroundTaskVisible).toBe(true),
       );
     });
 
@@ -1132,25 +1149,25 @@ describe('useShellCommandProcessor', () => {
 
       // 1. Register and show background shell
       act(() => {
-        result.current.registerBackgroundShell(1001, 'bg-cmd', 'initial');
+        result.current.registerBackgroundTask(1001, 'bg-cmd', 'initial');
       });
       act(() => {
-        result.current.toggleBackgroundShell();
+        result.current.toggleBackgroundTasks();
       });
-      expect(result.current.isBackgroundShellVisible).toBe(true);
+      expect(result.current.isBackgroundTaskVisible).toBe(true);
 
       // 2. Start foreground shell
       act(() => {
         result.current.handleShellCommand('ls', new AbortController().signal);
       });
       await waitFor(() => expect(result.current.activeShellPtyId).toBe(12345));
-      expect(result.current.isBackgroundShellVisible).toBe(false);
+      expect(result.current.isBackgroundTaskVisible).toBe(false);
 
       // 3. Manually toggle visibility (e.g. user wants to peek)
       act(() => {
-        result.current.toggleBackgroundShell();
+        result.current.toggleBackgroundTasks();
       });
-      expect(result.current.isBackgroundShellVisible).toBe(true);
+      expect(result.current.isBackgroundTaskVisible).toBe(true);
 
       // 4. Complete foreground shell
       act(() => {
@@ -1161,7 +1178,7 @@ describe('useShellCommandProcessor', () => {
       // It should NOT change visibility because manual toggle cleared the auto-restore flag
       // After delay it should stay true (as it was manually toggled to true)
       await waitFor(() =>
-        expect(result.current.isBackgroundShellVisible).toBe(true),
+        expect(result.current.isBackgroundTaskVisible).toBe(true),
       );
     });
   });

packages/cli/src/ui/hooks/useExecutionLifecycle.ts

@@ -9,10 +9,16 @@ import type {
   IndividualToolCallDisplay,
 } from '../types.js';
 import { useCallback, useReducer, useRef, useEffect } from 'react';
-import type { AnsiOutput, Config, GeminiClient } from '@google/gemini-cli-core';
+import type {
+  AnsiOutput,
+  Config,
+  GeminiClient,
+  CompletionBehavior,
+} from '@google/gemini-cli-core';
 import {
   isBinary,
   ShellExecutionService,
+  ExecutionLifecycleService,
   CoreToolCallStatus,
 } from '@google/gemini-cli-core';
 import { type PartListUnion } from '@google/genai';
@@ -27,9 +33,9 @@ import { themeManager } from '../../ui/themes/theme-manager.js';
 import {
   shellReducer,
   initialState,
-  type BackgroundShell,
+  type BackgroundTask,
 } from './shellReducer.js';
-export { type BackgroundShell };
+export { type BackgroundTask };
 
 export const OUTPUT_UPDATE_INTERVAL_MS = 1000;
 const RESTORE_VISIBILITY_DELAY_MS = 300;
@@ -66,7 +72,7 @@ function addShellCommandToGeminiHistory(
  * Hook to process shell commands.
  * Orchestrates command execution and updates history and agent context.
  */
-export const useShellCommandProcessor = (
+export const useExecutionLifecycle = (
   addItemToHistory: UseHistoryManagerReturn['addItem'],
   setPendingHistoryItem: React.Dispatch<
     React.SetStateAction<HistoryItemWithoutId | null>
@@ -113,7 +119,7 @@ export const useShellCommandProcessor = (
         m.restoreTimeout = null;
       }
 
-      if (state.isBackgroundShellVisible && !m.wasVisibleBeforeForeground) {
+      if (state.isBackgroundTaskVisible && !m.wasVisibleBeforeForeground) {
         m.wasVisibleBeforeForeground = true;
         dispatch({ type: 'SET_VISIBILITY', visible: false });
       }
@@ -135,14 +141,14 @@ export const useShellCommandProcessor = (
   }, [
     activePtyId,
     isWaitingForConfirmation,
-    state.isBackgroundShellVisible,
+    state.isBackgroundTaskVisible,
     m,
     dispatch,
   ]);
 
   useEffect(
     () => () => {
-      // Unsubscribe from all background shell events on unmount
+      // Unsubscribe from all background task events on unmount
       for (const unsubscribe of m.subscriptions.values()) {
         unsubscribe();
       }
@@ -151,9 +157,9 @@ export const useShellCommandProcessor = (
     [m],
   );
 
-  const toggleBackgroundShell = useCallback(() => {
-    if (state.backgroundShells.size > 0) {
-      const willBeVisible = !state.isBackgroundShellVisible;
+  const toggleBackgroundTasks = useCallback(() => {
+    if (state.backgroundTasks.size > 0) {
+      const willBeVisible = !state.isBackgroundTaskVisible;
       dispatch({ type: 'TOGGLE_VISIBILITY' });
 
       const isForegroundActive = !!activePtyId || !!isWaitingForConfirmation;
@@ -167,34 +173,44 @@ export const useShellCommandProcessor = (
       }
 
       if (willBeVisible) {
-        dispatch({ type: 'SYNC_BACKGROUND_SHELLS' });
+        dispatch({ type: 'SYNC_BACKGROUND_TASKS' });
       }
     } else {
       dispatch({ type: 'SET_VISIBILITY', visible: false });
       addItemToHistory(
         {
           type: 'info',
-          text: 'No background shells are currently active.',
+          text: 'No background tasks are currently active.',
         },
         Date.now(),
       );
     }
   }, [
     addItemToHistory,
-    state.backgroundShells.size,
-    state.isBackgroundShellVisible,
+    state.backgroundTasks.size,
+    state.isBackgroundTaskVisible,
     activePtyId,
     isWaitingForConfirmation,
     m,
     dispatch,
   ]);
 
-  const backgroundCurrentShell = useCallback(() => {
+  const backgroundCurrentExecution = useCallback(() => {
     const pidToBackground =
       state.activeShellPtyId ?? activeBackgroundExecutionId;
     if (pidToBackground) {
-      ShellExecutionService.background(pidToBackground);
+      // TRACK THE PID BEFORE TRIGGERING THE BACKGROUND ACTION
+      // This prevents the onBackground listener from double-registering.
       m.backgroundedPids.add(pidToBackground);
+
+      // Use ShellExecutionService for shell PTYs (handles log files, etc.),
+      // fall back to ExecutionLifecycleService for non-shell executions
+      // (e.g. remote agents, MCP tools, local agents).
+      if (state.activeShellPtyId) {
+        ShellExecutionService.background(pidToBackground);
+      } else {
+        ExecutionLifecycleService.background(pidToBackground);
+      }
       // Ensure backgrounding is silent and doesn't trigger restoration
       m.wasVisibleBeforeForeground = false;
       if (m.restoreTimeout) {
@@ -204,14 +220,16 @@ export const useShellCommandProcessor = (
     }
   }, [state.activeShellPtyId, activeBackgroundExecutionId, m]);
 
-  const dismissBackgroundShell = useCallback(
+  const dismissBackgroundTask = useCallback(
     async (pid: number) => {
-      const shell = state.backgroundShells.get(pid);
+      const shell = state.backgroundTasks.get(pid);
       if (shell) {
         if (shell.status === 'running') {
-          await ShellExecutionService.kill(pid);
+          // ExecutionLifecycleService.kill handles both shell and non-shell
+          // executions. For shells, ShellExecutionService.kill delegates to it.
+          ExecutionLifecycleService.kill(pid);
         }
-        dispatch({ type: 'DISMISS_SHELL', pid });
+        dispatch({ type: 'DISMISS_TASK', pid });
         m.backgroundedPids.delete(pid);
 
         // Unsubscribe from updates
@@ -222,40 +240,73 @@ export const useShellCommandProcessor = (
         }
       }
     },
-    [state.backgroundShells, dispatch, m],
+    [state.backgroundTasks, dispatch, m],
   );
 
-  const registerBackgroundShell = useCallback(
-    (pid: number, command: string, initialOutput: string | AnsiOutput) => {
-      dispatch({ type: 'REGISTER_SHELL', pid, command, initialOutput });
+  const registerBackgroundTask = useCallback(
+    (
+      pid: number,
+      command: string,
+      initialOutput: string | AnsiOutput,
+      completionBehavior?: CompletionBehavior,
+    ) => {
+      m.backgroundedPids.add(pid);
+      dispatch({
+        type: 'REGISTER_TASK',
+        pid,
+        command,
+        initialOutput,
+        completionBehavior,
+      });
 
-      // Subscribe to process exit directly
-      const exitUnsubscribe = ShellExecutionService.onExit(pid, (code) => {
+      // Subscribe to exit via ExecutionLifecycleService (works for all execution types)
+      const exitUnsubscribe = ExecutionLifecycleService.onExit(pid, (code) => {
         dispatch({
-          type: 'UPDATE_SHELL',
+          type: 'UPDATE_TASK',
           pid,
           update: { status: 'exited', exitCode: code },
         });
+        // Auto-dismiss for inject/notify (output was delivered to conversation).
+        // Silent tasks stay in the UI until manually dismissed.
+        if (completionBehavior !== 'silent') {
+          dispatch({ type: 'DISMISS_TASK', pid });
+        }
+        const unsub = m.subscriptions.get(pid);
+        if (unsub) {
+          unsub();
+          m.subscriptions.delete(pid);
+        }
         m.backgroundedPids.delete(pid);
       });
 
-      // Subscribe to future updates (data only)
-      const dataUnsubscribe = ShellExecutionService.subscribe(pid, (event) => {
-        if (event.type === 'data') {
-          dispatch({ type: 'APPEND_SHELL_OUTPUT', pid, chunk: event.chunk });
-        } else if (event.type === 'binary_detected') {
-          dispatch({ type: 'UPDATE_SHELL', pid, update: { isBinary: true } });
-        } else if (event.type === 'binary_progress') {
-          dispatch({
-            type: 'UPDATE_SHELL',
-            pid,
-            update: {
-              isBinary: true,
-              binaryBytesReceived: event.bytesReceived,
-            },
-          });
-        }
-      });
+      // Subscribe to output via ExecutionLifecycleService (works for all execution types)
+      const dataUnsubscribe = ExecutionLifecycleService.subscribe(
+        pid,
+        (event) => {
+          if (event.type === 'data') {
+            dispatch({
+              type: 'APPEND_TASK_OUTPUT',
+              pid,
+              chunk: event.chunk,
+            });
+          } else if (event.type === 'binary_detected') {
+            dispatch({
+              type: 'UPDATE_TASK',
+              pid,
+              update: { isBinary: true },
+            });
+          } else if (event.type === 'binary_progress') {
+            dispatch({
+              type: 'UPDATE_TASK',
+              pid,
+              update: {
+                isBinary: true,
+                binaryBytesReceived: event.bytesReceived,
+              },
+            });
+          }
+        },
+      );
 
       m.subscriptions.set(pid, () => {
         exitUnsubscribe();
@@ -265,6 +316,34 @@ export const useShellCommandProcessor = (
     [dispatch, m],
   );
 
+  // Auto-register any execution that gets backgrounded, regardless of type.
+  // This is the agnostic hook: any tool that calls
+  // ExecutionLifecycleService.createExecution() or attachExecution()
+  // automatically gets Ctrl+B support — no UI changes needed per tool.
+  useEffect(() => {
+    const listener = (info: {
+      executionId: number;
+      label: string;
+      output: string;
+      completionBehavior: CompletionBehavior;
+    }) => {
+      // Skip if already registered (e.g. shells register via their own flow)
+      if (m.backgroundedPids.has(info.executionId)) {
+        return;
+      }
+      registerBackgroundTask(
+        info.executionId,
+        info.label,
+        info.output,
+        info.completionBehavior,
+      );
+    };
+    ExecutionLifecycleService.onBackground(listener);
+    return () => {
+      ExecutionLifecycleService.offBackground(listener);
+    };
+  }, [registerBackgroundTask, m]);
+
   const handleShellCommand = useCallback(
     (rawQuery: PartListUnion, abortSignal: AbortSignal): boolean => {
       if (typeof rawQuery !== 'string' || rawQuery.trim() === '') {
@@ -377,7 +456,7 @@ export const useShellCommandProcessor = (
                 if (executionPid && m.backgroundedPids.has(executionPid)) {
                   // If already backgrounded, let the background shell subscription handle it.
                   dispatch({
-                    type: 'APPEND_SHELL_OUTPUT',
+                    type: 'APPEND_TASK_OUTPUT',
                     pid: executionPid,
                     chunk:
                       event.type === 'data' ? event.chunk : cumulativeStdout,
@@ -437,7 +516,12 @@ export const useShellCommandProcessor = (
           setPendingHistoryItem(null);
 
           if (result.backgrounded && result.pid) {
-            registerBackgroundShell(result.pid, rawQuery, cumulativeStdout);
+            registerBackgroundTask(
+              result.pid,
+              rawQuery,
+              cumulativeStdout,
+              'notify',
+            );
             dispatch({ type: 'SET_ACTIVE_PTY', pid: null });
           }
 
@@ -529,26 +613,26 @@ export const useShellCommandProcessor = (
       setShellInputFocused,
       terminalHeight,
       terminalWidth,
-      registerBackgroundShell,
+      registerBackgroundTask,
       m,
       dispatch,
     ],
   );
 
-  const backgroundShellCount = Array.from(
-    state.backgroundShells.values(),
-  ).filter((s: BackgroundShell) => s.status === 'running').length;
+  const backgroundTaskCount = Array.from(state.backgroundTasks.values()).filter(
+    (s: BackgroundTask) => s.status === 'running',
+  ).length;
 
   return {
     handleShellCommand,
     activeShellPtyId: state.activeShellPtyId,
     lastShellOutputTime: state.lastShellOutputTime,
-    backgroundShellCount,
-    isBackgroundShellVisible: state.isBackgroundShellVisible,
-    toggleBackgroundShell,
-    backgroundCurrentShell,
-    registerBackgroundShell,
-    dismissBackgroundShell,
-    backgroundShells: state.backgroundShells,
+    backgroundTaskCount,
+    isBackgroundTaskVisible: state.isBackgroundTaskVisible,
+    toggleBackgroundTasks,
+    backgroundCurrentExecution,
+    registerBackgroundTask,
+    dismissBackgroundTask,
+    backgroundTasks: state.backgroundTasks,
   };
 };

packages/cli/src/ui/hooks/useGeminiStream.test.tsx

@@ -179,11 +179,18 @@ vi.mock('./useKeypress.js', () => ({
   useKeypress: vi.fn(),
 }));
 
-vi.mock('./shellCommandProcessor.js', () => ({
-  useShellCommandProcessor: vi.fn().mockReturnValue({
+vi.mock('./useExecutionLifecycle.js', () => ({
+  useExecutionLifecycle: vi.fn().mockReturnValue({
     handleShellCommand: vi.fn(),
     activeShellPtyId: null,
     lastShellOutputTime: 0,
+    backgroundTaskCount: 0,
+    isBackgroundTaskVisible: false,
+    toggleBackgroundTasks: vi.fn(),
+    backgroundCurrentExecution: vi.fn(),
+    backgroundTasks: new Map(),
+    dismissBackgroundTask: vi.fn(),
+    registerBackgroundTask: vi.fn(),
   }),
 }));
 

packages/cli/src/ui/hooks/useGeminiStream.ts

@@ -40,6 +40,8 @@ import {
   Kind,
   ACTIVATE_SKILL_TOOL_NAME,
   shouldHideToolCall,
+  UPDATE_TOPIC_TOOL_NAME,
+  UPDATE_TOPIC_DISPLAY_NAME,
 } from '@google/gemini-cli-core';
 import type {
   Config,
@@ -73,7 +75,7 @@ import {
   ToolCallStatus,
 } from '../types.js';
 import { isAtCommand, isSlashCommand } from '../utils/commandUtils.js';
-import { useShellCommandProcessor } from './shellCommandProcessor.js';
+import { useExecutionLifecycle } from './useExecutionLifecycle.js';
 import { handleAtCommand } from './atCommandProcessor.js';
 import { findLastSafeSplitPoint } from '../utils/markdownUtilities.js';
 import { getInlineThinkingMode } from '../utils/inlineThinkingMode.js';
@@ -108,6 +110,9 @@ interface BackgroundedToolInfo {
   initialOutput: string;
 }
 
+const isTopicTool = (name: string): boolean =>
+  name === UPDATE_TOPIC_TOOL_NAME || name === UPDATE_TOPIC_DISPLAY_NAME;
+
 enum StreamProcessingStatus {
   Completed,
   UserCancelled,
@@ -364,14 +369,14 @@ export const useGeminiStream = (
     handleShellCommand,
     activeShellPtyId,
     lastShellOutputTime,
-    backgroundShellCount,
-    isBackgroundShellVisible,
-    toggleBackgroundShell,
-    backgroundCurrentShell,
-    registerBackgroundShell,
-    dismissBackgroundShell,
-    backgroundShells,
-  } = useShellCommandProcessor(
+    backgroundTaskCount,
+    isBackgroundTaskVisible,
+    toggleBackgroundTasks,
+    backgroundCurrentExecution,
+    registerBackgroundTask,
+    dismissBackgroundTask,
+    backgroundTasks,
+  } = useExecutionLifecycle(
     addItem,
     setPendingHistoryItem,
     onExec,
@@ -483,13 +488,23 @@ export const useGeminiStream = (
           activeShellPtyId,
           !!isShellFocused,
           [],
-          backgroundShells,
+          backgroundTasks,
         ),
       });
       addItem(historyItem);
 
       setPushedToolCallIds(newPushed);
-      setIsFirstToolInGroup(false);
+
+      // If this batch ONLY contains topics, and we were the first in the group,
+      // the NEXT batch is still effectively the first VISIBLE bordered tool in the group.
+      if (
+        isFirstToolInGroupRef.current &&
+        toolsToPush.every((tc) => isTopicTool(tc.request.name))
+      ) {
+        // Keep it true!
+      } else {
+        setIsFirstToolInGroup(false);
+      }
     }
   }, [
     toolCalls,
@@ -500,9 +515,8 @@ export const useGeminiStream = (
     addItem,
     activeShellPtyId,
     isShellFocused,
-    backgroundShells,
+    backgroundTasks,
   ]);
-
   const pendingToolGroupItems = useMemo((): HistoryItemWithoutId[] => {
     const remainingTools = toolCalls.filter(
       (tc) => !pushedToolCallIds.has(tc.request.callId),
@@ -515,19 +529,30 @@ export const useGeminiStream = (
       activeShellPtyId,
       !!isShellFocused,
       [],
-      backgroundShells,
+      backgroundTasks,
     );
 
     if (remainingTools.length > 0) {
+      // Should we draw a top border? Yes if NO previous tools were drawn,
+      // OR if ALL previously drawn tools were topics (which don't draw top borders).
+      let needsTopBorder = pushedToolCallIds.size === 0;
+      if (!needsTopBorder) {
+        const allPushedWereTopics = toolCalls
+          .filter((tc) => pushedToolCallIds.has(tc.request.callId))
+          .every((tc) => isTopicTool(tc.request.name));
+        if (allPushedWereTopics) {
+          needsTopBorder = true;
+        }
+      }
+
       items.push(
         mapTrackedToolCallsToDisplay(remainingTools, {
-          borderTop: pushedToolCallIds.size === 0,
+          borderTop: needsTopBorder,
           borderBottom: false, // Stay open to connect with the slice below
           ...appearance,
         }),
       );
     }
-
     // Always show a bottom border slice if we have ANY tools in the batch
     // and we haven't finished pushing the whole batch to history yet.
     // Once all tools are terminal and pushed, the last history item handles the closing border.
@@ -604,7 +629,7 @@ export const useGeminiStream = (
     pushedToolCallIds,
     activeShellPtyId,
     isShellFocused,
-    backgroundShells,
+    backgroundTasks,
   ]);
 
   const lastQueryRef = useRef<PartListUnion | null>(null);
@@ -1794,7 +1819,7 @@ export const useGeminiStream = (
       for (const toolCall of completedAndReadyToSubmitTools) {
         const backgroundedTool = getBackgroundedToolInfo(toolCall);
         if (backgroundedTool) {
-          registerBackgroundShell(
+          registerBackgroundTask(
             backgroundedTool.pid,
             backgroundedTool.command,
             backgroundedTool.initialOutput,
@@ -1928,7 +1953,7 @@ export const useGeminiStream = (
       performMemoryRefresh,
       modelSwitchedFromQuotaError,
       addItem,
-      registerBackgroundShell,
+      registerBackgroundTask,
       consumeUserHint,
       isLowErrorVerbosity,
       maybeAddSuppressedToolErrorNote,
@@ -2023,12 +2048,12 @@ export const useGeminiStream = (
     activePtyId,
     loopDetectionConfirmationRequest,
     lastOutputTime,
-    backgroundShellCount,
-    isBackgroundShellVisible,
-    toggleBackgroundShell,
-    backgroundCurrentShell,
-    backgroundShells,
-    dismissBackgroundShell,
+    backgroundTaskCount,
+    isBackgroundTaskVisible,
+    toggleBackgroundTasks,
+    backgroundCurrentExecution,
+    backgroundTasks,
+    dismissBackgroundTask,
     retryStatus,
   };
 };

packages/cli/src/ui/key/keyBindings.ts

@@ -74,6 +74,7 @@ export enum Command {
 
   // Text Input
   SUBMIT = 'input.submit',
+  QUEUE_MESSAGE = 'input.queueMessage',
   NEWLINE = 'input.newline',
   OPEN_EXTERNAL_EDITOR = 'input.openExternalEditor',
   PASTE_CLIPBOARD = 'input.paste',
@@ -94,6 +95,7 @@ export enum Command {
   RESTART_APP = 'app.restart',
   SUSPEND_APP = 'app.suspend',
   SHOW_SHELL_INPUT_UNFOCUS_WARNING = 'app.showShellUnfocusWarning',
+  TOGGLE_BUFFER_MODE = 'app.toggleBufferMode',
 
   // Background Shell Controls
   BACKGROUND_SHELL_ESCAPE = 'background.escape',
@@ -354,6 +356,7 @@ export const defaultKeyBindingConfig: KeyBindingConfig = new Map([
   // Text Input
   // Must also exclude shift to allow shift+enter for newline
   [Command.SUBMIT, [new KeyBinding('enter')]],
+  [Command.QUEUE_MESSAGE, [new KeyBinding('tab')]],
   [
     Command.NEWLINE,
     [
@@ -390,6 +393,7 @@ export const defaultKeyBindingConfig: KeyBindingConfig = new Map([
   [Command.RESTART_APP, [new KeyBinding('r'), new KeyBinding('shift+r')]],
   [Command.SUSPEND_APP, [new KeyBinding('ctrl+z')]],
   [Command.SHOW_SHELL_INPUT_UNFOCUS_WARNING, [new KeyBinding('tab')]],
+  [Command.TOGGLE_BUFFER_MODE, [new KeyBinding('alt+a')]],
 
   // Background Shell Controls
   [Command.BACKGROUND_SHELL_ESCAPE, [new KeyBinding('escape')]],
@@ -488,6 +492,7 @@ export const commandCategories: readonly CommandCategory[] = [
     title: 'Text Input',
     commands: [
       Command.SUBMIT,
+      Command.QUEUE_MESSAGE,
       Command.NEWLINE,
       Command.OPEN_EXTERNAL_EDITOR,
       Command.PASTE_CLIPBOARD,
@@ -593,6 +598,8 @@ export const commandDescriptions: Readonly<Record<Command, string>> = {
 
   // Text Input
   [Command.SUBMIT]: 'Submit the current prompt.',
+  [Command.QUEUE_MESSAGE]:
+    'Queue the current prompt to be processed after the current task finishes.',
   [Command.NEWLINE]: 'Insert a newline without submitting.',
   [Command.OPEN_EXTERNAL_EDITOR]:
     'Open the current prompt or the plan in an external editor.',
@@ -604,6 +611,7 @@ export const commandDescriptions: Readonly<Record<Command, string>> = {
   [Command.SHOW_IDE_CONTEXT_DETAIL]: 'Show IDE context details.',
   [Command.TOGGLE_MARKDOWN]: 'Toggle Markdown rendering.',
   [Command.TOGGLE_COPY_MODE]: 'Toggle copy mode when in alternate buffer mode.',
+  [Command.TOGGLE_BUFFER_MODE]: 'Toggle between regular and full screen (alternate buffer) mode.',
   [Command.TOGGLE_YOLO]: 'Toggle YOLO (auto-approval) mode for tool calls.',
   [Command.CYCLE_APPROVAL_MODE]:
     'Cycle through approval modes: default (prompt), auto_edit (auto-approve edits), and plan (read-only). Plan mode is skipped when the agent is busy.',

packages/cli/src/ui/layouts/DefaultAppLayout.test.tsx

@@ -10,7 +10,7 @@ import { DefaultAppLayout } from './DefaultAppLayout.js';
 import { StreamingState } from '../types.js';
 import { Text } from 'ink';
 import type { UIState } from '../contexts/UIStateContext.js';
-import type { BackgroundShell } from '../hooks/shellCommandProcessor.js';
+import type { BackgroundTask } from '../hooks/useExecutionLifecycle.js';
 
 // Mock dependencies
 const mockUIState = {
@@ -18,13 +18,13 @@ const mockUIState = {
   terminalHeight: 24,
   terminalWidth: 80,
   mainAreaWidth: 80,
-  backgroundShells: new Map<number, BackgroundShell>(),
-  activeBackgroundShellPid: null as number | null,
-  backgroundShellHeight: 10,
+  backgroundTasks: new Map<number, BackgroundTask>(),
+  activeBackgroundTaskPid: null as number | null,
+  backgroundTaskHeight: 10,
   embeddedShellFocused: false,
   dialogsVisible: false,
   streamingState: StreamingState.Idle,
-  isBackgroundShellListOpen: false,
+  isBackgroundTaskListOpen: false,
   mainControlsRef: vi.fn(),
   customDialog: null,
   historyManager: { addItem: vi.fn() },
@@ -34,7 +34,7 @@ const mockUIState = {
   constrainHeight: false,
   availableTerminalHeight: 20,
   activePtyId: null,
-  isBackgroundShellVisible: true,
+  isBackgroundTaskVisible: true,
 } as unknown as UIState;
 
 vi.mock('../contexts/UIStateContext.js', () => ({
@@ -79,11 +79,11 @@ vi.mock('../components/ExitWarning.js', () => ({
 vi.mock('../components/CopyModeWarning.js', () => ({
   CopyModeWarning: () => <Text>CopyModeWarning</Text>,
 }));
-vi.mock('../components/BackgroundShellDisplay.js', () => ({
-  BackgroundShellDisplay: () => <Text>BackgroundShellDisplay</Text>,
+vi.mock('../components/BackgroundTaskDisplay.js', () => ({
+  BackgroundTaskDisplay: () => <Text>BackgroundTaskDisplay</Text>,
 }));
 
-const createMockShell = (pid: number): BackgroundShell => ({
+const createMockShell = (pid: number): BackgroundTask => ({
   pid,
   command: 'test command',
   output: 'test output',
@@ -96,25 +96,25 @@ describe('<DefaultAppLayout />', () => {
   beforeEach(() => {
     vi.clearAllMocks();
     // Reset mock state defaults
-    mockUIState.backgroundShells = new Map();
-    mockUIState.activeBackgroundShellPid = null;
+    mockUIState.backgroundTasks = new Map();
+    mockUIState.activeBackgroundTaskPid = null;
     mockUIState.streamingState = StreamingState.Idle;
   });
 
-  it('renders BackgroundShellDisplay when shells exist and active', async () => {
-    mockUIState.backgroundShells.set(123, createMockShell(123));
-    mockUIState.activeBackgroundShellPid = 123;
-    mockUIState.backgroundShellHeight = 5;
+  it('renders BackgroundTaskDisplay when shells exist and active', async () => {
+    mockUIState.backgroundTasks.set(123, createMockShell(123));
+    mockUIState.activeBackgroundTaskPid = 123;
+    mockUIState.backgroundTaskHeight = 5;
 
     const { lastFrame, unmount } = await render(<DefaultAppLayout />);
     expect(lastFrame()).toMatchSnapshot();
     unmount();
   });
 
-  it('hides BackgroundShellDisplay when StreamingState is WaitingForConfirmation', async () => {
-    mockUIState.backgroundShells.set(123, createMockShell(123));
-    mockUIState.activeBackgroundShellPid = 123;
-    mockUIState.backgroundShellHeight = 5;
+  it('hides BackgroundTaskDisplay when StreamingState is WaitingForConfirmation', async () => {
+    mockUIState.backgroundTasks.set(123, createMockShell(123));
+    mockUIState.activeBackgroundTaskPid = 123;
+    mockUIState.backgroundTaskHeight = 5;
     mockUIState.streamingState = StreamingState.WaitingForConfirmation;
 
     const { lastFrame, unmount } = await render(<DefaultAppLayout />);
@@ -122,10 +122,10 @@ describe('<DefaultAppLayout />', () => {
     unmount();
   });
 
-  it('shows BackgroundShellDisplay when StreamingState is NOT WaitingForConfirmation', async () => {
-    mockUIState.backgroundShells.set(123, createMockShell(123));
-    mockUIState.activeBackgroundShellPid = 123;
-    mockUIState.backgroundShellHeight = 5;
+  it('shows BackgroundTaskDisplay when StreamingState is NOT WaitingForConfirmation', async () => {
+    mockUIState.backgroundTasks.set(123, createMockShell(123));
+    mockUIState.activeBackgroundTaskPid = 123;
+    mockUIState.backgroundTaskHeight = 5;
     mockUIState.streamingState = StreamingState.Responding;
 
     const { lastFrame, unmount } = await render(<DefaultAppLayout />);

packages/cli/src/ui/layouts/DefaultAppLayout.tsx

@@ -15,7 +15,7 @@ import { useUIState } from '../contexts/UIStateContext.js';
 import { useFlickerDetector } from '../hooks/useFlickerDetector.js';
 import { useAlternateBuffer } from '../hooks/useAlternateBuffer.js';
 import { CopyModeWarning } from '../components/CopyModeWarning.js';
-import { BackgroundShellDisplay } from '../components/BackgroundShellDisplay.js';
+import { BackgroundTaskDisplay } from '../components/BackgroundTaskDisplay.js';
 import { StreamingState } from '../types.js';
 
 export const DefaultAppLayout: React.FC = () => {
@@ -39,21 +39,21 @@ export const DefaultAppLayout: React.FC = () => {
     >
       <MainContent />
 
-      {uiState.isBackgroundShellVisible &&
-        uiState.backgroundShells.size > 0 &&
-        uiState.activeBackgroundShellPid &&
-        uiState.backgroundShellHeight > 0 &&
+      {uiState.isBackgroundTaskVisible &&
+        uiState.backgroundTasks.size > 0 &&
+        uiState.activeBackgroundTaskPid &&
+        uiState.backgroundTaskHeight > 0 &&
         uiState.streamingState !== StreamingState.WaitingForConfirmation && (
-          <Box height={uiState.backgroundShellHeight} flexShrink={0}>
-            <BackgroundShellDisplay
-              shells={uiState.backgroundShells}
-              activePid={uiState.activeBackgroundShellPid}
+          <Box height={uiState.backgroundTaskHeight} flexShrink={0}>
+            <BackgroundTaskDisplay
+              shells={uiState.backgroundTasks}
+              activePid={uiState.activeBackgroundTaskPid}
               width={uiState.terminalWidth}
-              height={uiState.backgroundShellHeight}
+              height={uiState.backgroundTaskHeight}
               isFocused={
                 uiState.embeddedShellFocused && !uiState.dialogsVisible
               }
-              isListOpenProp={uiState.isBackgroundShellListOpen}
+              isListOpenProp={uiState.isBackgroundTaskListOpen}
             />
           </Box>
         )}

packages/cli/src/ui/layouts/__snapshots__/DefaultAppLayout.test.tsx.snap

@@ -1,6 +1,6 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`<DefaultAppLayout /> > hides BackgroundShellDisplay when StreamingState is WaitingForConfirmation 1`] = `
+exports[`<DefaultAppLayout /> > hides BackgroundTaskDisplay when StreamingState is WaitingForConfirmation 1`] = `
 "MainContent
 Notifications
 CopyModeWarning
@@ -9,9 +9,9 @@ ExitWarning
 "
 `;
 
-exports[`<DefaultAppLayout /> > renders BackgroundShellDisplay when shells exist and active 1`] = `
+exports[`<DefaultAppLayout /> > renders BackgroundTaskDisplay when shells exist and active 1`] = `
 "MainContent
-BackgroundShellDisplay
+BackgroundTaskDisplay
 
 
 
@@ -23,9 +23,9 @@ ExitWarning
 "
 `;
 
-exports[`<DefaultAppLayout /> > shows BackgroundShellDisplay when StreamingState is NOT WaitingForConfirmation 1`] = `
+exports[`<DefaultAppLayout /> > shows BackgroundTaskDisplay when StreamingState is NOT WaitingForConfirmation 1`] = `
 "MainContent
-BackgroundShellDisplay
+BackgroundTaskDisplay
 
 
 

packages/cli/src/ui/noninteractive/nonInteractiveUi.ts

@@ -41,7 +41,7 @@ export function createNonInteractiveUI(): CommandContext['ui'] {
     addConfirmUpdateExtensionRequest: (_request) => {},
     setConfirmationRequest: (_request) => {},
     removeComponent: () => {},
-    toggleBackgroundShell: () => {},
+    toggleBackgroundTasks: () => {},
     toggleShortcutsHelp: () => {},
   };
 }

packages/cli/src/ui/types.ts

@@ -118,6 +118,7 @@ export interface IndividualToolCallDisplay {
   callId: string;
   parentCallId?: string;
   name: string;
+  args?: Record<string, unknown>;
   description: string;
   resultDisplay: ToolResultDisplay | undefined;
   status: CoreToolCallStatus;

packages/cli/src/ui/utils/borderStyles.ts

@@ -13,7 +13,7 @@ import type {
   HistoryItemToolGroup,
   IndividualToolCallDisplay,
 } from '../types.js';
-import type { BackgroundShell } from '../hooks/shellReducer.js';
+import type { BackgroundTask } from '../hooks/shellReducer.js';
 import type { TrackedToolCall } from '../hooks/useToolScheduler.js';
 
 function isTrackedToolCall(
@@ -33,7 +33,7 @@ export function getToolGroupBorderAppearance(
   activeShellPtyId: number | null | undefined,
   embeddedShellFocused: boolean | undefined,
   allPendingItems: HistoryItemWithoutId[] = [],
-  backgroundShells: Map<number, BackgroundShell> = new Map(),
+  backgroundTasks: Map<number, BackgroundTask> = new Map(),
 ): { borderColor: string; borderDimColor: boolean } {
   if (item.type !== 'tool_group') {
     return { borderColor: '', borderDimColor: false };
@@ -100,7 +100,7 @@ export function getToolGroupBorderAppearance(
   // If we have an active PTY that isn't a background shell, then the current
   // pending batch is definitely a shell batch.
   const isCurrentlyInShellTurn =
-    !!activeShellPtyId && !backgroundShells.has(activeShellPtyId);
+    !!activeShellPtyId && !backgroundTasks.has(activeShellPtyId);
 
   const isShell =
     isShellCommand || (item.tools.length === 0 && isCurrentlyInShellTurn);

packages/cli/src/utils/commands.test.ts

@@ -137,4 +137,105 @@ describe('parseSlashCommand', () => {
     expect(result.args).toBe('');
     expect(result.canonicalPath).toEqual([]);
   });
+
+  describe('backtracking', () => {
+    const backtrackingCommands: readonly SlashCommand[] = [
+      {
+        name: 'parent',
+        description: 'Parent command',
+        kind: CommandKind.BUILT_IN,
+        action: async () => {},
+        subCommands: [
+          {
+            name: 'notakes',
+            description: 'Subcommand that does not take arguments',
+            kind: CommandKind.BUILT_IN,
+            takesArgs: false,
+            action: async () => {},
+          },
+          {
+            name: 'takes',
+            description: 'Subcommand that takes arguments',
+            kind: CommandKind.BUILT_IN,
+            takesArgs: true,
+            action: async () => {},
+          },
+        ],
+      },
+    ];
+
+    it('should backtrack to parent if subcommand has takesArgs: false and args are provided', () => {
+      const result = parseSlashCommand(
+        '/parent notakes some prompt',
+        backtrackingCommands,
+      );
+      expect(result.commandToExecute?.name).toBe('parent');
+      expect(result.args).toBe('notakes some prompt');
+      expect(result.canonicalPath).toEqual(['parent']);
+    });
+
+    it('should NOT backtrack if subcommand has takesArgs: false but NO args are provided', () => {
+      const result = parseSlashCommand('/parent notakes', backtrackingCommands);
+      expect(result.commandToExecute?.name).toBe('notakes');
+      expect(result.args).toBe('');
+      expect(result.canonicalPath).toEqual(['parent', 'notakes']);
+    });
+
+    it('should NOT backtrack if subcommand has takesArgs: true and args are provided', () => {
+      const result = parseSlashCommand(
+        '/parent takes some args',
+        backtrackingCommands,
+      );
+      expect(result.commandToExecute?.name).toBe('takes');
+      expect(result.args).toBe('some args');
+      expect(result.canonicalPath).toEqual(['parent', 'takes']);
+    });
+
+    it('should NOT backtrack if parent has NO action', () => {
+      const noActionCommands: readonly SlashCommand[] = [
+        {
+          name: 'parent',
+          description: 'Parent without action',
+          kind: CommandKind.BUILT_IN,
+          subCommands: [
+            {
+              name: 'notakes',
+              description: 'Subcommand without args',
+              kind: CommandKind.BUILT_IN,
+              takesArgs: false,
+              action: async () => {},
+            },
+          ],
+        },
+      ];
+      const result = parseSlashCommand(
+        '/parent notakes some args',
+        noActionCommands,
+      );
+      // It stays with the subcommand because parent can't handle it
+      expect(result.commandToExecute?.name).toBe('notakes');
+      expect(result.args).toBe('some args');
+      expect(result.canonicalPath).toEqual(['parent', 'notakes']);
+    });
+
+    it('should NOT backtrack if subcommand is NOT marked with takesArgs: false', () => {
+      const result = parseSlashCommand(
+        '/parent takes some args',
+        backtrackingCommands,
+      );
+      expect(result.commandToExecute?.name).toBe('takes');
+      expect(result.args).toBe('some args');
+      expect(result.canonicalPath).toEqual(['parent', 'takes']);
+    });
+
+    it('should backtrack if subcommand has takesArgs: false and args are provided (like /plan copy foo)', () => {
+      const result = parseSlashCommand(
+        '/parent notakes some prompt',
+        backtrackingCommands,
+      );
+      expect(result.commandToExecute?.name).toBe('parent');
+      expect(result.args).toBe('notakes some prompt');
+      expect(result.canonicalPath).toEqual(['parent']);
+    });
+  });
 });

packages/cli/src/utils/commands.ts

@@ -33,6 +33,7 @@ export const parseSlashCommand = (
   let commandToExecute: SlashCommand | undefined;
   let pathIndex = 0;
   const canonicalPath: string[] = [];
+  let parentCommand: SlashCommand | undefined;
 
   for (const part of commandPath) {
     // TODO: For better performance and architectural clarity, this two-pass
@@ -52,6 +53,7 @@ export const parseSlashCommand = (
     }
 
     if (foundCommand) {
+      parentCommand = commandToExecute;
       commandToExecute = foundCommand;
       canonicalPath.push(foundCommand.name);
       pathIndex++;
@@ -67,5 +69,21 @@ export const parseSlashCommand = (
 
   const args = parts.slice(pathIndex).join(' ');
 
+  // Backtrack if the matched (sub)command doesn't take arguments but some were provided,
+  // AND the parent command is capable of handling them.
+  if (
+    commandToExecute &&
+    commandToExecute.takesArgs === false &&
+    args.length > 0 &&
+    parentCommand &&
+    parentCommand.action
+  ) {
+    return {
+      commandToExecute: parentCommand,
+      args: parts.slice(pathIndex - 1).join(' '),
+      canonicalPath: canonicalPath.slice(0, -1),
+    };
+  }
+
   return { commandToExecute, args, canonicalPath };
 };

packages/core/src/code_assist/oauth2.ts

@@ -119,7 +119,8 @@ async function initOauthClient(
     credentials &&
     typeof credentials === 'object' &&
     'type' in credentials &&
-    credentials.type === 'external_account_authorized_user'
+    (credentials.type === 'external_account_authorized_user' ||
+      credentials.type === 'service_account')
   ) {
     const auth = new GoogleAuth({
       scopes: OAUTH_SCOPE,
@@ -130,7 +131,7 @@ async function initOauthClient(
     });
     const token = await byoidClient.getAccessToken();
     if (token) {
-      debugLogger.debug('Created BYOID auth client.');
+      debugLogger.debug(`Created ${credentials.type} auth client.`);
       return byoidClient;
     }
   }

packages/core/src/config/config.test.ts

@@ -92,6 +92,7 @@ vi.mock('../tools/tool-registry', () => {
   ToolRegistryMock.prototype.sortTools = vi.fn();
   ToolRegistryMock.prototype.getAllTools = vi.fn(() => []); // Mock methods if needed
   ToolRegistryMock.prototype.getTool = vi.fn();
+  ToolRegistryMock.prototype.getAllToolNames = vi.fn(() => []);
   ToolRegistryMock.prototype.getFunctionDeclarations = vi.fn(() => []);
   return { ToolRegistry: ToolRegistryMock };
 });
@@ -1563,6 +1564,17 @@ describe('Server Config (config.ts)', () => {
       expect(config.getSandboxNetworkAccess()).toBe(false);
     });
   });
+
+  it('should have independent TopicState across instances', () => {
+    const config1 = new Config(baseParams);
+    const config2 = new Config(baseParams);
+
+    config1.topicState.setTopic('Topic 1');
+    config2.topicState.setTopic('Topic 2');
+
+    expect(config1.topicState.getTopic()).toBe('Topic 1');
+    expect(config2.topicState.getTopic()).toBe('Topic 2');
+  });
 });
 
 describe('GemmaModelRouterSettings', () => {

packages/core/src/config/config.ts

@@ -36,6 +36,8 @@ import { WebFetchTool } from '../tools/web-fetch.js';
 import { MemoryTool, setGeminiMdFilename } from '../tools/memoryTool.js';
 import { WebSearchTool } from '../tools/web-search.js';
 import { AskUserTool } from '../tools/ask-user.js';
+import { UpdateTopicTool } from '../tools/topicTool.js';
+import { TopicState } from './topicState.js';
 import { ExitPlanModeTool } from '../tools/exit-plan-mode.js';
 import { EnterPlanModeTool } from '../tools/enter-plan-mode.js';
 import { GeminiClient } from '../core/client.js';
@@ -640,6 +642,7 @@ export interface ConfigParameters {
   useAlternateBuffer?: boolean;
   useRipgrep?: boolean;
   enableInteractiveShell?: boolean;
+  shellBackgroundCompletionBehavior?: string;
   skipNextSpeakerCheck?: boolean;
   shellExecutionConfig?: ShellExecutionConfig;
   extensionManagement?: boolean;
@@ -685,6 +688,7 @@ export interface ConfigParameters {
   experimentalAgentHistoryTruncationThreshold?: number;
   experimentalAgentHistoryRetainedMessages?: number;
   experimentalAgentHistorySummarization?: boolean;
+  memoryBoundaryMarkers?: string[];
   topicUpdateNarration?: boolean;
   toolOutputMasking?: Partial<ToolOutputMaskingConfig>;
   disableLLMCorrection?: boolean;
@@ -727,6 +731,7 @@ export class Config implements McpContext, AgentLoopContext {
   private clientVersion: string;
   private fileSystemService: FileSystemService;
   private trackerService?: TrackerService;
+  readonly topicState = new TopicState();
   private contentGeneratorConfig!: ContentGeneratorConfig;
   private contentGenerator!: ContentGenerator;
   readonly modelConfigService: ModelConfigService;
@@ -842,6 +847,10 @@ export class Config implements McpContext, AgentLoopContext {
   private readonly directWebFetch: boolean;
   private readonly useRipgrep: boolean;
   private readonly enableInteractiveShell: boolean;
+  private readonly shellBackgroundCompletionBehavior:
+    | 'inject'
+    | 'notify'
+    | 'silent';
   private readonly skipNextSpeakerCheck: boolean;
   private readonly useBackgroundColor: boolean;
   private readonly useAlternateBuffer: boolean;
@@ -917,6 +926,7 @@ export class Config implements McpContext, AgentLoopContext {
   private readonly experimentalAgentHistoryTruncationThreshold: number;
   private readonly experimentalAgentHistoryRetainedMessages: number;
   private readonly experimentalAgentHistorySummarization: boolean;
+  private readonly memoryBoundaryMarkers: readonly string[];
   private readonly topicUpdateNarration: boolean;
   private readonly disableLLMCorrection: boolean;
   private readonly planEnabled: boolean;
@@ -1134,6 +1144,7 @@ export class Config implements McpContext, AgentLoopContext {
       params.experimentalAgentHistoryRetainedMessages ?? 15;
     this.experimentalAgentHistorySummarization =
       params.experimentalAgentHistorySummarization ?? false;
+    this.memoryBoundaryMarkers = params.memoryBoundaryMarkers ?? ['.git'];
     this.topicUpdateNarration = params.topicUpdateNarration ?? false;
     this.modelSteering = params.modelSteering ?? false;
     this.injectionService = new InjectionService(() =>
@@ -1178,6 +1189,14 @@ export class Config implements McpContext, AgentLoopContext {
     this.useBackgroundColor = params.useBackgroundColor ?? true;
     this.useAlternateBuffer = params.useAlternateBuffer ?? false;
     this.enableInteractiveShell = params.enableInteractiveShell ?? false;
+
+    const requestedBehavior = params.shellBackgroundCompletionBehavior;
+    if (requestedBehavior === 'inject' || requestedBehavior === 'notify') {
+      this.shellBackgroundCompletionBehavior = requestedBehavior;
+    } else {
+      this.shellBackgroundCompletionBehavior = 'silent';
+    }
+
     this.skipNextSpeakerCheck = params.skipNextSpeakerCheck ?? true;
     this.shellExecutionConfig = {
       terminalWidth: params.shellExecutionConfig?.terminalWidth ?? 80,
@@ -1187,6 +1206,7 @@ export class Config implements McpContext, AgentLoopContext {
       sanitizationConfig: this.sanitizationConfig,
       sandboxManager: this._sandboxManager,
       sandboxConfig: this.sandbox,
+      backgroundCompletionBehavior: this.shellBackgroundCompletionBehavior,
     };
     this.truncateToolOutputThreshold =
       params.truncateToolOutputThreshold ??
@@ -2310,6 +2330,10 @@ export class Config implements McpContext, AgentLoopContext {
     return this.experimentalJitContext;
   }
 
+  getMemoryBoundaryMarkers(): readonly string[] {
+    return this.memoryBoundaryMarkers;
+  }
+
   isMemoryManagerEnabled(): boolean {
     return this.experimentalMemoryManager;
   }
@@ -3157,6 +3181,10 @@ export class Config implements McpContext, AgentLoopContext {
     return this.enableInteractiveShell;
   }
 
+  getShellBackgroundCompletionBehavior(): 'inject' | 'notify' | 'silent' {
+    return this.shellBackgroundCompletionBehavior;
+  }
+
   getSkipNextSpeakerCheck(): boolean {
     return this.skipNextSpeakerCheck;
   }
@@ -3347,6 +3375,10 @@ export class Config implements McpContext, AgentLoopContext {
       }
     };
 
+    maybeRegister(UpdateTopicTool, () =>
+      registry.registerTool(new UpdateTopicTool(this, this.messageBus)),
+    );
+
     maybeRegister(LSTool, () =>
       registry.registerTool(new LSTool(this, this.messageBus)),
     );

packages/core/src/config/topicState.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Manages the current active topic title and tactical intent for a session.
+ * Hosted within the Config instance for session-scoping.
+ */
+export class TopicState {
+  private activeTopicTitle?: string;
+  private activeIntent?: string;
+
+  /**
+   * Sanitizes and sets the topic title and/or intent.
+   * @returns true if the input was valid and set, false otherwise.
+   */
+  setTopic(title?: string, intent?: string): boolean {
+    const sanitizedTitle = title?.trim().replace(/[\r\n]+/g, ' ');
+    const sanitizedIntent = intent?.trim().replace(/[\r\n]+/g, ' ');
+
+    if (!sanitizedTitle && !sanitizedIntent) return false;
+
+    if (sanitizedTitle) {
+      this.activeTopicTitle = sanitizedTitle;
+    }
+
+    if (sanitizedIntent) {
+      this.activeIntent = sanitizedIntent;
+    }
+
+    return true;
+  }
+
+  getTopic(): string | undefined {
+    return this.activeTopicTitle;
+  }
+
+  getIntent(): string | undefined {
+    return this.activeIntent;
+  }
+
+  reset(): void {
+    this.activeTopicTitle = undefined;
+    this.activeIntent = undefined;
+  }
+}

packages/core/src/core/prompts-substitution.test.ts

@@ -59,6 +59,11 @@ describe('Core System Prompt Substitution', () => {
         getSkills: vi.fn().mockReturnValue([]),
       }),
       getApprovedPlanPath: vi.fn().mockReturnValue(undefined),
+      isTopicUpdateNarrationEnabled: vi.fn().mockReturnValue(false),
+      isTrackerEnabled: vi.fn().mockReturnValue(false),
+      isModelSteeringEnabled: vi.fn().mockReturnValue(false),
+      getHasAccessToPreviewModel: vi.fn().mockReturnValue(true),
+      getGemini31LaunchedSync: vi.fn().mockReturnValue(true),
     } as unknown as Config;
   });
 

packages/core/src/index.ts

@@ -164,12 +164,6 @@ export * from './services/executionLifecycleService.js';
 // Export Injection Service
 export * from './config/injectionService.js';
 
-// Export Execution Lifecycle Service
-export * from './services/executionLifecycleService.js';
-
-// Export Injection Service
-export * from './config/injectionService.js';
-
 // Export base tool definitions
 export * from './tools/tools.js';
 export * from './tools/tool-error.js';

packages/core/src/policy/policies/plan.toml

@@ -113,6 +113,13 @@ decision = "allow"
 priority = 70
 modes = ["plan"]
 
+# Topic grouping tool is innocuous and used for UI organization.
+[[rule]]
+toolName = "update_topic"
+decision = "allow"
+priority = 70
+modes = ["plan"]
+
 [[rule]]
 toolName = ["ask_user", "save_memory"]
 decision = "ask_user"

packages/core/src/policy/policies/read-only.toml

@@ -55,4 +55,10 @@ priority = 50
 [[rule]]
 toolName = ["codebase_investigator", "cli_help", "get_internal_docs"]
 decision = "allow"
+priority = 50
+
+# Topic grouping tool is innocuous and used for UI organization.
+[[rule]]
+toolName = "update_topic"
+decision = "allow"
 priority = 50

packages/core/src/policy/policies/sandbox-default.toml

@@ -7,13 +7,14 @@ allowOverrides = false
 [modes.default]
 network = false
 readonly = true
-approvedTools = []
+approvedTools = ['cat', 'ls', 'grep', 'head', 'tail', 'less', 'Get-Content', 'dir', 'type', 'findstr', 'Get-ChildItem', 'echo']
 allowOverrides = true
 
 [modes.accepting_edits]
 network = false
 readonly = false
-approvedTools = ['sed', 'grep', 'awk', 'perl', 'cat', 'echo']
+approvedTools = ['sed', 'grep', 'awk', 'perl', 'cat', 'echo', 'Add-Content', 'Set-Content']
 allowOverrides = true
 
 [commands]
+

packages/core/src/policy/topic-policy.test.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import * as path from 'node:path';
+import { loadPoliciesFromToml } from './toml-loader.js';
+import { PolicyEngine } from './policy-engine.js';
+import { ApprovalMode, PolicyDecision } from './types.js';
+import { UPDATE_TOPIC_TOOL_NAME } from '../tools/tool-names.js';
+
+describe('Topic Tool Policy', () => {
+  async function loadDefaultPolicies() {
+    // Path relative to packages/core root
+    const policiesDir = path.resolve(process.cwd(), 'src/policy/policies');
+    const getPolicyTier = () => 1; // Default tier
+    const result = await loadPoliciesFromToml([policiesDir], getPolicyTier);
+    return result.rules;
+  }
+
+  it('should allow update_topic in DEFAULT mode', async () => {
+    const rules = await loadDefaultPolicies();
+    const engine = new PolicyEngine({
+      rules,
+      approvalMode: ApprovalMode.DEFAULT,
+    });
+
+    const result = await engine.check(
+      { name: UPDATE_TOPIC_TOOL_NAME },
+      undefined,
+    );
+    expect(result.decision).toBe(PolicyDecision.ALLOW);
+  });
+
+  it('should allow update_topic in PLAN mode', async () => {
+    const rules = await loadDefaultPolicies();
+    const engine = new PolicyEngine({
+      rules,
+      approvalMode: ApprovalMode.PLAN,
+    });
+
+    const result = await engine.check(
+      { name: UPDATE_TOPIC_TOOL_NAME },
+      undefined,
+    );
+    expect(result.decision).toBe(PolicyDecision.ALLOW);
+  });
+
+  it('should allow update_topic in YOLO mode', async () => {
+    const rules = await loadDefaultPolicies();
+    const engine = new PolicyEngine({
+      rules,
+      approvalMode: ApprovalMode.YOLO,
+    });
+
+    const result = await engine.check(
+      { name: UPDATE_TOPIC_TOOL_NAME },
+      undefined,
+    );
+    expect(result.decision).toBe(PolicyDecision.ALLOW);
+  });
+});

packages/core/src/prompts/promptProvider.test.ts

@@ -15,6 +15,8 @@ import { PREVIEW_GEMINI_MODEL } from '../config/models.js';
 import { ApprovalMode } from '../policy/types.js';
 import { DiscoveredMCPTool } from '../tools/mcp-tool.js';
 import { MockTool } from '../test-utils/mock-tool.js';
+import { UPDATE_TOPIC_TOOL_NAME } from '../tools/tool-names.js';
+import { TopicState } from '../config/topicState.js';
 import type { CallableTool } from '@google/genai';
 import type { MessageBus } from '../confirmation-bus/message-bus.js';
 import type { ToolRegistry } from '../tools/tool-registry.js';
@@ -53,6 +55,7 @@ describe('PromptProvider', () => {
         ).getToolRegistry?.() as unknown as ToolRegistry;
       },
       getToolRegistry: vi.fn().mockReturnValue(mockToolRegistry),
+      topicState: new TopicState(),
       getEnableShellOutputEfficiency: vi.fn().mockReturnValue(true),
       getSandboxEnabled: vi.fn().mockReturnValue(false),
       storage: {
@@ -73,6 +76,8 @@ describe('PromptProvider', () => {
       getApprovedPlanPath: vi.fn().mockReturnValue(undefined),
       getApprovalMode: vi.fn(),
       isTrackerEnabled: vi.fn().mockReturnValue(false),
+      getHasAccessToPreviewModel: vi.fn().mockReturnValue(true),
+      getGemini31LaunchedSync: vi.fn().mockReturnValue(true),
     } as unknown as Config;
   });
 
@@ -234,4 +239,67 @@ describe('PromptProvider', () => {
       expect(prompt).not.toContain('### APPROVED PLAN PRESERVATION');
     });
   });
+
+  describe('Topic & Update Narration', () => {
+    beforeEach(() => {
+      mockConfig.topicState.reset();
+      vi.mocked(mockConfig.isTopicUpdateNarrationEnabled).mockReturnValue(true);
+      (mockConfig.getToolRegistry as ReturnType<typeof vi.fn>).mockReturnValue({
+        getAllToolNames: vi.fn().mockReturnValue([UPDATE_TOPIC_TOOL_NAME]),
+        getAllTools: vi.fn().mockReturnValue([
+          new MockTool({
+            name: UPDATE_TOPIC_TOOL_NAME,
+            displayName: 'Topic',
+          }),
+        ]),
+      });
+      vi.mocked(mockConfig.getHasAccessToPreviewModel).mockReturnValue(true);
+      vi.mocked(mockConfig.getGemini31LaunchedSync).mockReturnValue(true);
+    });
+
+    it('should include active topic context when narration is enabled', () => {
+      mockConfig.topicState.setTopic('Active Chapter');
+      const provider = new PromptProvider();
+      const prompt = provider.getCoreSystemPrompt(mockConfig);
+
+      expect(prompt).toContain('[Active Topic: Active Chapter]');
+    });
+
+    it('should NOT include active topic context when narration is disabled', () => {
+      vi.mocked(mockConfig.isTopicUpdateNarrationEnabled).mockReturnValue(
+        false,
+      );
+      mockConfig.topicState.setTopic('Active Chapter');
+      const provider = new PromptProvider();
+      const prompt = provider.getCoreSystemPrompt(mockConfig);
+
+      expect(prompt).not.toContain('[Active Topic: Active Chapter]');
+    });
+
+    it('should filter out update_topic tool when narration is disabled', () => {
+      vi.mocked(mockConfig.getApprovalMode).mockReturnValue(ApprovalMode.PLAN);
+      vi.mocked(mockConfig.isTopicUpdateNarrationEnabled).mockReturnValue(
+        false,
+      );
+      // Simulate registry behavior where it filters out update_topic
+      vi.mocked(mockConfig.getToolRegistry().getAllToolNames).mockReturnValue(
+        [],
+      );
+      vi.mocked(mockConfig.getToolRegistry().getAllTools).mockReturnValue([]);
+
+      const provider = new PromptProvider();
+
+      const prompt = provider.getCoreSystemPrompt(mockConfig);
+      expect(prompt).not.toContain(UPDATE_TOPIC_TOOL_NAME);
+    });
+
+    it('should NOT filter out update_topic tool when narration is enabled', () => {
+      vi.mocked(mockConfig.getApprovalMode).mockReturnValue(ApprovalMode.PLAN);
+      vi.mocked(mockConfig.isTopicUpdateNarrationEnabled).mockReturnValue(true);
+      const provider = new PromptProvider();
+      const prompt = provider.getCoreSystemPrompt(mockConfig);
+
+      expect(prompt).toContain(`<tool>\`${UPDATE_TOPIC_TOOL_NAME}\`</tool>`);
+    });
+  });
 });

packages/core/src/prompts/promptProvider.ts

@@ -57,6 +57,7 @@ export class PromptProvider {
     const skills = context.config.getSkillManager().getSkills();
     const toolNames = context.toolRegistry.getAllToolNames();
     const enabledToolNames = new Set(toolNames);
+
     const approvedPlanPath = context.config.getApprovedPlanPath();
 
     const desiredModel = resolveModel(
@@ -71,7 +72,6 @@ export class PromptProvider {
     const activeSnippets = isModernModel ? snippets : legacySnippets;
     const contextFilenames = getAllGeminiMdFilenames();
 
-    // --- Context Gathering ---
     let planModeToolsList = '';
     if (isPlanMode) {
       const allTools = context.toolRegistry.getAllTools();
@@ -232,7 +232,18 @@ export class PromptProvider {
     );
 
     // Sanitize erratic newlines from composition
-    const sanitizedPrompt = finalPrompt.replace(/\n{3,}/g, '\n\n');
+    let sanitizedPrompt = finalPrompt.replace(/\n{3,}/g, '\n\n');
+
+    // Context Reinjection (Active Topic)
+    if (context.config.isTopicUpdateNarrationEnabled()) {
+      const activeTopic = context.config.topicState.getTopic();
+      if (activeTopic) {
+        const sanitizedTopic = activeTopic
+          .replace(/\n/g, ' ')
+          .replace(/\]/g, '');
+        sanitizedPrompt += `\n\n[Active Topic: ${sanitizedTopic}]`;
+      }
+    }
 
     // Write back to file if requested
     this.maybeWriteSystemMd(

packages/core/src/prompts/snippets.ts

@@ -10,6 +10,9 @@ import {
   EDIT_TOOL_NAME,
   ENTER_PLAN_MODE_TOOL_NAME,
   EXIT_PLAN_MODE_TOOL_NAME,
+  UPDATE_TOPIC_TOOL_NAME,
+  TOPIC_PARAM_TITLE,
+  TOPIC_PARAM_SUMMARY,
   GLOB_TOOL_NAME,
   GREP_TOOL_NAME,
   MEMORY_TOOL_NAME,
@@ -239,7 +242,9 @@ Use the following guidelines to optimize your search and read patterns.
       ? mandateTopicUpdateModel()
       : mandateExplainBeforeActing()
   }
-- **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.${mandateSkillGuidance(options.hasSkills)}${mandateContinueWork(options.interactive)}
+- **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.${mandateSkillGuidance(
+    options.hasSkills,
+  )}${mandateContinueWork(options.interactive)}
 `.trim();
 }
 
@@ -361,7 +366,7 @@ export function renderOperationalGuidelines(
 - **Role:** A senior software engineer and collaborative peer programmer.
 - **High-Signal Output:** Focus exclusively on **intent** and **technical rationale**. Avoid conversational filler, apologies, and ${
     options.topicUpdateNarration
-      ? 'per-tool explanations.'
+      ? 'unnecessary per-tool explanations.'
       : 'mechanical tool-use narration (e.g., "I will now call...").'
   }
 - **Concise & Direct:** Adopt a professional, direct, and concise tone suitable for a CLI environment.
@@ -614,46 +619,19 @@ function mandateConfirm(interactive: boolean): string {
 
 function mandateTopicUpdateModel(): string {
   return `
-- **Protocol: Topic Model**
-  You are an agentic system. You must maintain a visible state log that tracks broad logical phases using a specific header format.
+## Topic Updates
+As you work, the user follows along by reading topic updates that you publish with ${UPDATE_TOPIC_TOOL_NAME}. Keep them informed by doing the following:
 
-- **1. Topic Initialization & Persistence:**
-  - **The Trigger:** You MUST issue a \`Topic: <Phase> : <Brief Summary>\` header ONLY when beginning a task or when the broad logical nature of the task changes (e.g., transitioning from research to implementation).
-  - **The Format:** Use exactly \`Topic: <Phase> : <Brief Summary>\` (e.g., \`Topic: <Research> : Researching Agent Skills in the repo\`).
-  - **Persistence:** Once a Topic is declared, do NOT repeat it for subsequent tool calls or in subsequent messages within that same phase. 
-  - **Start of Task:** Your very first tool execution must be preceded by a Topic header.
+- Always call ${UPDATE_TOPIC_TOOL_NAME} in your first and last turn. The final turn should always recap what was done.
+- Each topic update should give a concise description of what you are doing for the next few turns in the \`${TOPIC_PARAM_SUMMARY}\` parameter.
+- Provide topic updates whenever you change "topics". A topic is typically a discrete subgoal and will be every 3 to 10 turns. Do not use ${UPDATE_TOPIC_TOOL_NAME} on every turn.
+- The typical user message should call ${UPDATE_TOPIC_TOOL_NAME} 3 or more times. Each corresponds to a distinct phase of the task, such as "Researching X", "Researching Y", "Implementing Z with X", and "Testing Z".
+- Remember to call ${UPDATE_TOPIC_TOOL_NAME} when you experience an unexpected event (e.g., a test failure, compilation error, environment issue, or unexpected learning) that requires a strategic detour.
+- **Examples:**
+  - \`update_topic(${TOPIC_PARAM_TITLE}="Researching Parser", ${TOPIC_PARAM_SUMMARY}="I am starting an investigation into the parser timeout bug. My goal is to first understand the current test coverage and then attempt to reproduce the failure. This phase will focus on identifying the bottleneck in the main loop before we move to implementation.")\`
+  - \`update_topic(${TOPIC_PARAM_TITLE}="Implementing Buffer Fix", ${TOPIC_PARAM_SUMMARY}="I have completed the research phase and identified a race condition in the tokenizer's buffer management. I am now transitioning to implementation. This new chapter will focus on refactoring the buffer logic to handle async chunks safely, followed by unit testing the fix.")\`
 
-- **2. Tool Execution Protocol (Zero-Noise):**
-  - **No Per-Tool Headers:** It is a violation of protocol to print "Topic:" before every tool call. 
-  - **Silent Mode:** No conversational filler, no "I will now...", and no summaries between tools. 
-  - Only the Topic header at the start of a broad phase is permitted to break the silence. Everything in between must be silent.
-
-- **3. Thinking Protocol:**
-  - Use internal thought blocks to keep track of what tools you have called, plan your next steps, and reason about the task.
-  - Without reasoning and tracking in thought blocks, you may lose context.
-  - Always use the required syntax for thought blocks to ensure they remain hidden from the user interface.
-
-- **4. Completion:**
-  - Only when the entire task is finalized do you provide a **Final Summary**.
-
-**IMPORTANT: Topic Headers vs. Thoughts**
-The \`Topic: <Phase> : <Brief Summary>\` header must **NOT** be placed inside a thought block. It must be standard text output so that it is properly rendered and displayed in the UI.
-
-**Correct State Log Example:**
-\`\`\`
-Topic: <Research> : Researching Agent Skills in the repo
-<tool_call 1>
-<tool_call 2>
-<tool_call 3>
-
-Topic: <Implementation> : Implementing the skill-creator logic
-<tool_call 1>
-<tool_call 2>
-
-The task is complete. [Final Summary]
-\`\`\`
-
-- **Constraint Enforcement:** If you repeat a "Topic:" line without a fundamental shift in work, or if you provide a Topic for every tool call, you have failed the system integrity protocol.`;
+`;
 }
 
 function mandateExplainBeforeActing(): string {

packages/core/src/sandbox/linux/LinuxSandboxManager.ts

@@ -187,7 +187,7 @@ export class LinuxSandboxManager implements SandboxManager {
       : false;
     const workspaceWrite = !isReadonlyMode || isApproved;
     const networkAccess =
-      this.options.modeConfig?.network ?? req.policy?.networkAccess ?? false;
+      this.options.modeConfig?.network || req.policy?.networkAccess || false;
 
     const persistentPermissions = allowOverrides
       ? this.options.policyManager?.getCommandPermissions(commandName)

packages/core/src/sandbox/macos/MacOsSandboxManager.ts

@@ -78,7 +78,7 @@ export class MacOsSandboxManager implements SandboxManager {
 
     const workspaceWrite = !isReadonlyMode || isApproved;
     const defaultNetwork =
-      this.options.modeConfig?.network ?? req.policy?.networkAccess ?? false;
+      this.options.modeConfig?.network || req.policy?.networkAccess || false;
 
     // Fetch persistent approvals for this command
     const commandName = await getCommandName(req.command, req.args);

packages/core/src/sandbox/windows/GeminiSandbox.cs

@@ -58,6 +58,13 @@ public class GeminiSandbox {
         public ulong OtherTransferCount;
     }
 
+    [StructLayout(LayoutKind.Sequential)]
+    struct JOBOBJECT_NET_RATE_CONTROL_INFORMATION {
+        public ulong MaxBandwidth;
+        public uint ControlFlags;
+        public byte DscpTag;
+    }
+
     [DllImport("kernel32.dll", SetLastError = true)]
     static extern IntPtr CreateJobObject(IntPtr lpJobAttributes, string lpName);
 
@@ -70,6 +77,9 @@ public class GeminiSandbox {
     [DllImport("advapi32.dll", SetLastError = true)]
     static extern bool OpenProcessToken(IntPtr ProcessHandle, uint DesiredAccess, out IntPtr TokenHandle);
 
+    [DllImport("advapi32.dll", SetLastError = true)]
+    static extern bool DuplicateTokenEx(IntPtr hExistingToken, uint dwDesiredAccess, IntPtr lpTokenAttributes, uint ImpersonationLevel, uint TokenType, out IntPtr phNewToken);
+
     [DllImport("advapi32.dll", SetLastError = true)]
     static extern bool CreateRestrictedToken(IntPtr ExistingTokenHandle, uint Flags, uint DisableSidCount, IntPtr SidsToDisable, uint DeletePrivilegeCount, IntPtr PrivilegesToDelete, uint RestrictedSidCount, IntPtr SidsToRestrict, out IntPtr NewTokenHandle);
 
@@ -143,6 +153,8 @@ public class GeminiSandbox {
 
     private const int TokenIntegrityLevel = 25;
     private const uint SE_GROUP_INTEGRITY = 0x00000020;
+    private const uint TOKEN_ALL_ACCESS = 0xF01FF;
+    private const uint DISABLE_MAX_PRIVILEGE = 0x1;
 
     static int Main(string[] args) {
         if (args.Length < 3) {
@@ -182,14 +194,14 @@ public class GeminiSandbox {
         IntPtr lowIntegritySid = IntPtr.Zero;
 
         try {
-            // 1. Create Restricted Token
-            if (!OpenProcessToken(GetCurrentProcess(), 0x0002 /* TOKEN_DUPLICATE */ | 0x0008 /* TOKEN_QUERY */ | 0x0080 /* TOKEN_ADJUST_DEFAULT */, out hToken)) {
+            // 1. Duplicate Primary Token
+            if (!OpenProcessToken(GetCurrentProcess(), TOKEN_ALL_ACCESS, out hToken)) {
                 Console.WriteLine("Error: OpenProcessToken failed (" + Marshal.GetLastWin32Error() + ")");
                 return 1;
             }
 
-            // Flags: 0x1 (DISABLE_MAX_PRIVILEGE)
-            if (!CreateRestrictedToken(hToken, 1, 0, IntPtr.Zero, 0, IntPtr.Zero, 0, IntPtr.Zero, out hRestrictedToken)) {
+            // Create a restricted token to strip administrative privileges
+            if (!CreateRestrictedToken(hToken, DISABLE_MAX_PRIVILEGE, 0, IntPtr.Zero, 0, IntPtr.Zero, 0, IntPtr.Zero, out hRestrictedToken)) {
                 Console.WriteLine("Error: CreateRestrictedToken failed (" + Marshal.GetLastWin32Error() + ")");
                 return 1;
             }
@@ -223,6 +235,18 @@ public class GeminiSandbox {
             SetInformationJobObject(hJob, 9 /* JobObjectExtendedLimitInformation */, lpJobLimits, (uint)Marshal.SizeOf(jobLimits));
             Marshal.FreeHGlobal(lpJobLimits);
 
+            if (!networkAccess) {
+                JOBOBJECT_NET_RATE_CONTROL_INFORMATION netLimits = new JOBOBJECT_NET_RATE_CONTROL_INFORMATION();
+                netLimits.MaxBandwidth = 1;
+                netLimits.ControlFlags = 0x1 | 0x2; // ENABLE | MAX_BANDWIDTH
+                netLimits.DscpTag = 0;
+                
+                IntPtr lpNetLimits = Marshal.AllocHGlobal(Marshal.SizeOf(netLimits));
+                Marshal.StructureToPtr(netLimits, lpNetLimits, false);
+                SetInformationJobObject(hJob, 32 /* JobObjectNetRateControlInformation */, lpNetLimits, (uint)Marshal.SizeOf(netLimits));
+                Marshal.FreeHGlobal(lpNetLimits);
+            }
+
             // 4. Handle Internal Commands or External Process
             if (command == "__read") {
                 if (argIndex + 1 >= args.Length) {

packages/core/src/sandbox/windows/WindowsSandboxManager.test.ts

@@ -158,7 +158,7 @@ describe('WindowsSandboxManager', () => {
     expect(icaclsArgs).toContainEqual([
       persistentPath,
       '/setintegritylevel',
-      'Low',
+      '(OI)(CI)Low',
     ]);
   });
 
@@ -227,13 +227,13 @@ describe('WindowsSandboxManager', () => {
       expect(icaclsArgs).toContainEqual([
         path.resolve(testCwd),
         '/setintegritylevel',
-        'Low',
+        '(OI)(CI)Low',
       ]);
 
       expect(icaclsArgs).toContainEqual([
         path.resolve(allowedPath),
         '/setintegritylevel',
-        'Low',
+        '(OI)(CI)Low',
       ]);
     } finally {
       fs.rmSync(allowedPath, { recursive: true, force: true });
@@ -273,7 +273,7 @@ describe('WindowsSandboxManager', () => {
       expect(icaclsArgs).toContainEqual([
         path.resolve(extraWritePath),
         '/setintegritylevel',
-        'Low',
+        '(OI)(CI)Low',
       ]);
     } finally {
       fs.rmSync(extraWritePath, { recursive: true, force: true });
@@ -308,7 +308,7 @@ describe('WindowsSandboxManager', () => {
       expect(icaclsArgs).not.toContainEqual([
         uncPath,
         '/setintegritylevel',
-        'Low',
+        '(OI)(CI)Low',
       ]);
     },
   );
@@ -343,12 +343,12 @@ describe('WindowsSandboxManager', () => {
       expect(icaclsArgs).toContainEqual([
         longPath,
         '/setintegritylevel',
-        'Low',
+        '(OI)(CI)Low',
       ]);
       expect(icaclsArgs).toContainEqual([
         devicePath,
         '/setintegritylevel',
-        'Low',
+        '(OI)(CI)Low',
       ]);
     },
   );

packages/core/src/sandbox/windows/WindowsSandboxManager.ts

@@ -34,6 +34,7 @@ import {
   isStrictlyApproved,
 } from './commandSafety.js';
 import { verifySandboxOverrides } from '../utils/commandUtils.js';
+import { parseWindowsSandboxDenials } from './windowsSandboxDenialUtils.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -66,8 +67,8 @@ export class WindowsSandboxManager implements SandboxManager {
     return isDangerousCommand(args);
   }
 
-  parseDenials(_result: ShellExecutionResult): ParsedSandboxDenial | undefined {
-    return undefined; // TODO: Implement Windows-specific denial parsing
+  parseDenials(result: ShellExecutionResult): ParsedSandboxDenial | undefined {
+    return parseWindowsSandboxDenials(result);
   }
 
   /**
@@ -235,6 +236,10 @@ export class WindowsSandboxManager implements SandboxManager {
         false,
     };
 
+    const defaultNetwork =
+      this.options.modeConfig?.network || req.policy?.networkAccess || false;
+    const networkAccess = defaultNetwork || mergedAdditional.network;
+
     // 1. Handle filesystem permissions for Low Integrity
     // Grant "Low Mandatory Level" write access to the workspace.
     // If not in readonly mode OR it's a strictly approved pipeline, allow workspace writes
@@ -250,7 +255,7 @@ export class WindowsSandboxManager implements SandboxManager {
       await this.grantLowIntegrityAccess(this.options.workspace);
     }
 
-    // Grant "Low Mandatory Level" read access to allowedPaths.
+    // Grant "Low Mandatory Level" read/write access to allowedPaths.
     const allowedPaths = sanitizePaths(req.policy?.allowedPaths) || [];
     for (const allowedPath of allowedPaths) {
       await this.grantLowIntegrityAccess(allowedPath);
@@ -341,10 +346,6 @@ export class WindowsSandboxManager implements SandboxManager {
     // GeminiSandbox.exe <network:0|1> <cwd> --forbidden-manifest <path> <command> [args...]
     const program = this.helperPath;
 
-    const defaultNetwork =
-      this.options.modeConfig?.network ?? req.policy?.networkAccess ?? false;
-    const networkAccess = defaultNetwork || mergedAdditional.network;
-
     const args = [
       networkAccess ? '1' : '0',
       req.cwd,
@@ -394,7 +395,11 @@ export class WindowsSandboxManager implements SandboxManager {
     }
 
     try {
-      await spawnAsync('icacls', [resolvedPath, '/setintegritylevel', 'Low']);
+      await spawnAsync('icacls', [
+        resolvedPath,
+        '/setintegritylevel',
+        '(OI)(CI)Low',
+      ]);
       this.allowedCache.add(resolvedPath);
     } catch (e) {
       debugLogger.log(

packages/core/src/sandbox/windows/windowsSandboxDenialUtils.test.ts

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseWindowsSandboxDenials } from './windowsSandboxDenialUtils.js';
+import type { ShellExecutionResult } from '../../services/shellExecutionService.js';
+
+describe('parseWindowsSandboxDenials', () => {
+  it('should detect CMD "Access is denied" and extract paths', () => {
+    const parsed = parseWindowsSandboxDenials({
+      output: 'Access is denied.\r\n',
+      error: new Error('Command failed: dir C:\\Windows\\System32\\config'),
+    } as unknown as ShellExecutionResult);
+
+    expect(parsed).toBeDefined();
+    expect(parsed?.filePaths).toContain('C:\\Windows\\System32\\config');
+  });
+
+  it('should detect PowerShell "Access to the path is denied"', () => {
+    const parsed = parseWindowsSandboxDenials({
+      output:
+        "Set-Content : Access to the path 'C:\\test.txt' is denied.\r\nAt line:1 char:1\r\n",
+    } as unknown as ShellExecutionResult);
+
+    expect(parsed).toBeDefined();
+    expect(parsed?.filePaths).toContain('C:\\test.txt');
+  });
+
+  it('should detect Node.js EPERM on Windows', () => {
+    const parsed = parseWindowsSandboxDenials({
+      error: {
+        message:
+          "Error: EPERM: operation not permitted, open 'D:\\project\\file.ts'",
+      },
+    } as unknown as ShellExecutionResult);
+
+    expect(parsed).toBeDefined();
+    expect(parsed?.filePaths).toContain('D:\\project\\file.ts');
+  });
+
+  it('should detect network denial (EACCES)', () => {
+    const parsed = parseWindowsSandboxDenials({
+      output: 'Error: listen EACCES: permission denied 0.0.0.0:3000',
+    } as unknown as ShellExecutionResult);
+
+    expect(parsed).toBeDefined();
+    expect(parsed?.network).toBe(true);
+  });
+
+  it('should detect native Windows error code 0x80070005', () => {
+    const parsed = parseWindowsSandboxDenials({
+      output: 'HRESULT: 0x80070005',
+    } as unknown as ShellExecutionResult);
+
+    expect(parsed).toBeDefined();
+    // No path in output, but recognized as denial
+  });
+
+  it('should handle extended-length paths', () => {
+    const parsed = parseWindowsSandboxDenials({
+      output: 'Access is denied to \\\\?\\C:\\Very\\Long\\Path\\file.txt',
+    } as unknown as ShellExecutionResult);
+
+    expect(parsed).toBeDefined();
+    expect(parsed?.filePaths).toContain(
+      '\\\\?\\C:\\Very\\Long\\Path\\file.txt',
+    );
+  });
+
+  it('should detect Windows paths with forward slashes', () => {
+    const parsed = parseWindowsSandboxDenials({
+      output:
+        "Error: EPERM: operation not permitted, open 'C:/project/file.ts'",
+    } as unknown as ShellExecutionResult);
+
+    expect(parsed).toBeDefined();
+    expect(parsed?.filePaths).toContain('C:/project/file.ts');
+  });
+
+  it('should return undefined if no denial detected', () => {
+    const parsed = parseWindowsSandboxDenials({
+      output:
+        'Directory of C:\\Users\r\n03/26/2026  11:40 AM    <DIR>          .',
+    } as unknown as ShellExecutionResult);
+
+    expect(parsed).toBeUndefined();
+  });
+});