Merge branch 'pr4-cli' into mb/agent-interactive

Merge branch 'main' into pr4-cli
refactor(cli): remove config dependency from useAgentStream
2026-07-24 00:30:59 -07:00 · 2026-03-30 12:59:33 -07:00 · 2026-03-30 12:39:30 -07:00 · 2026-03-30 12:35:31 -07:00 · 2026-03-30 09:48:31 -07:00 · 2026-03-30 14:31:20 +00:00
102 changed files with 4092 additions and 1781 deletions
@@ -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}"
@@ -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
@@ -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
@@ -1366,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`.
@@ -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,
+        );
+      }
+    },
+  });
 });
@@ -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. */
@@ -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',
        );
      });
    });
@@ -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']}`,
    );
@@ -988,6 +988,7 @@ export async function loadCliConfig(
    modelSteering: settings.experimental?.modelSteering,
    topicUpdateNarration: settings.experimental?.topicUpdateNarration,
    toolOutputMasking: settings.experimental?.toolOutputMasking,
+    useAgentProtocol: settings.experimental?.useAgentProtocol,
    noBrowser: !!process.env['NO_BROWSER'],
    summarizeToolOutput: settings.model?.summarizeToolOutput,
    ideMode,
@@ -1000,6 +1001,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,
@@ -1458,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',
@@ -2093,6 +2108,16 @@ const SETTINGS_SCHEMA = {
          'Enable dynamic model configuration (definitions, resolutions, and chains) via settings.',
        showInDialog: false,
      },
+      useAgentProtocol: {
+        type: 'boolean',
+        label: 'Use Agent Protocol',
+        category: 'Experimental',
+        requiresRestart: true,
+        default: false,
+        description:
+          'Enable the experimental unified agent for interactive mode.',
+        showInDialog: false,
+      },
      gemmaModelRouter: {
        type: 'object',
        label: 'Gemma Model Router',
@@ -77,6 +77,8 @@ vi.mock('@google/gemini-cli-core', async (importOriginal) => {
    uiTelemetryService: {
      getMetrics: vi.fn(),
    },
+    LegacyAgentSession: original.LegacyAgentSession,
+    geminiPartsToContentParts: original.geminiPartsToContentParts,
    coreEvents: mockCoreEvents,
    createWorkingStdio: vi.fn(() => ({
      stdout: process.stdout,
@@ -108,6 +110,8 @@ describe('runNonInteractive', () => {
    sendMessageStream: Mock;
    resumeChat: Mock;
    getChatRecordingService: Mock;
+    getChat: Mock;
+    getCurrentSequenceModel: Mock;
  };
  const MOCK_SESSION_METRICS: SessionMetrics = {
    models: {},
@@ -163,6 +167,8 @@ describe('runNonInteractive', () => {
        recordMessageTokens: vi.fn(),
        recordToolCalls: vi.fn(),
      })),
+      getChat: vi.fn(() => ({ recordCompletedToolCalls: vi.fn() })),
+      getCurrentSequenceModel: vi.fn().mockReturnValue(null),
    };

    mockConfig = {
@@ -268,6 +274,54 @@ describe('runNonInteractive', () => {
    // so we no longer expect shutdownTelemetry to be called directly here
  });

+  it('should stream the specific stream started by send', async () => {
+    const { LegacyAgentSession } = await import('@google/gemini-cli-core');
+    const streamSpy = vi.spyOn(LegacyAgentSession.prototype, 'stream');
+    const events: ServerGeminiStreamEvent[] = [
+      { type: GeminiEventType.Content, value: 'Hello again' },
+      {
+        type: GeminiEventType.Finished,
+        value: { reason: undefined, usageMetadata: { totalTokenCount: 10 } },
+      },
+    ];
+    mockGeminiClient.sendMessageStream.mockReturnValue(
+      createStreamFromEvents(events),
+    );
+
+    await runNonInteractive({
+      config: mockConfig,
+      settings: mockSettings,
+      input: 'Test input',
+      prompt_id: 'prompt-id-stream',
+    });
+
+    expect(streamSpy).toHaveBeenCalledWith({ streamId: expect.any(String) });
+  });
+
+  it('fails fast if the session acknowledges a message send without a stream', async () => {
+    const { LegacyAgentSession } = await import('@google/gemini-cli-core');
+    const sendSpy = vi
+      .spyOn(LegacyAgentSession.prototype, 'send')
+      .mockResolvedValue({ streamId: null });
+    const streamSpy = vi.spyOn(LegacyAgentSession.prototype, 'stream');
+
+    await expect(
+      runNonInteractive({
+        config: mockConfig,
+        settings: mockSettings,
+        input: 'Test input',
+        prompt_id: 'prompt-id-null-stream',
+      }),
+    ).rejects.toThrow(
+      'LegacyAgentSession.send() unexpectedly returned no stream for a message send.',
+    );
+
+    expect(streamSpy).not.toHaveBeenCalled();
+
+    sendSpy.mockRestore();
+    streamSpy.mockRestore();
+  });
+
  it('should register activity logger when GEMINI_CLI_ACTIVITY_LOG_TARGET is set', async () => {
    vi.stubEnv('GEMINI_CLI_ACTIVITY_LOG_TARGET', '/tmp/test.jsonl');
    const events: ServerGeminiStreamEvent[] = [
@@ -558,7 +612,7 @@ describe('runNonInteractive', () => {
        input: 'Initial fail',
        prompt_id: 'prompt-id-4',
      }),
-    ).rejects.toThrow(apiError);
+    ).rejects.toThrow('API connection failed');
  });

  it('should not exit if a tool is not found, and should send error back to model', async () => {
@@ -822,6 +876,79 @@ describe('runNonInteractive', () => {
    );
  });

+  it('should keep only the final post-tool assistant text in JSON output', async () => {
+    const toolCallEvent: ServerGeminiStreamEvent = {
+      type: GeminiEventType.ToolCallRequest,
+      value: {
+        callId: 'tool-1',
+        name: 'testTool',
+        args: { arg1: 'value1' },
+        isClientInitiated: false,
+        prompt_id: 'prompt-id-json-tool-text',
+      },
+    };
+    mockSchedulerSchedule.mockResolvedValue([
+      {
+        status: CoreToolCallStatus.Success,
+        request: toolCallEvent.value,
+        tool: {} as AnyDeclarativeTool,
+        invocation: {} as AnyToolInvocation,
+        response: {
+          responseParts: [{ text: 'Tool executed successfully' }],
+          callId: 'tool-1',
+          error: undefined,
+          errorType: undefined,
+          contentLength: undefined,
+        },
+      },
+    ]);
+
+    mockGeminiClient.sendMessageStream
+      .mockReturnValueOnce(
+        createStreamFromEvents([
+          { type: GeminiEventType.Content, value: 'Let me check that...' },
+          toolCallEvent,
+          {
+            type: GeminiEventType.Finished,
+            value: { reason: undefined, usageMetadata: { totalTokenCount: 5 } },
+          },
+        ]),
+      )
+      .mockReturnValueOnce(
+        createStreamFromEvents([
+          { type: GeminiEventType.Content, value: 'Final answer' },
+          {
+            type: GeminiEventType.Finished,
+            value: { reason: undefined, usageMetadata: { totalTokenCount: 3 } },
+          },
+        ]),
+      );
+
+    vi.mocked(mockConfig.getOutputFormat).mockReturnValue(OutputFormat.JSON);
+    vi.mocked(uiTelemetryService.getMetrics).mockReturnValue(
+      MOCK_SESSION_METRICS,
+    );
+
+    await runNonInteractive({
+      config: mockConfig,
+      settings: mockSettings,
+      input: 'Use a tool',
+      prompt_id: 'prompt-id-json-tool-text',
+    });
+
+    expect(processStdoutSpy).toHaveBeenCalledWith(
+      JSON.stringify(
+        {
+          session_id: 'test-session-id',
+          response: 'Final answer',
+          stats: MOCK_SESSION_METRICS,
+        },
+        null,
+        2,
+      ),
+    );
+  });
+
  it('should write JSON output with stats for empty response commands', async () => {
    // Test the scenario where a command completes but produces no content at all
    const events: ServerGeminiStreamEvent[] = [
@@ -1068,10 +1195,11 @@ describe('runNonInteractive', () => {

    // Spy on handleCancellationError to verify it's called
    const errors = await import('./utils/errors.js');
+    const cancellationSentinel = new Error('Cancelled');
    const handleCancellationErrorSpy = vi
      .spyOn(errors, 'handleCancellationError')
      .mockImplementation(() => {
-        throw new Error('Cancelled');
+        throw cancellationSentinel;
      });

    const events: ServerGeminiStreamEvent[] = [
@@ -1087,7 +1215,7 @@ describe('runNonInteractive', () => {
            signal.addEventListener('abort', () => {
              clearTimeout(timeout);
              setTimeout(() => {
-                reject(new Error('Aborted')); // This will be caught by nonInteractiveCli and passed to handleError
+                reject(new Error('Aborted'));
              }, 300);
            });
          });
@@ -1120,20 +1248,10 @@ describe('runNonInteractive', () => {
      keypressHandler('\u0003', { ctrl: true, name: 'c' });
    }

-    // The promise should reject with 'Aborted' because our mock stream throws it,
-    // and nonInteractiveCli catches it and calls handleError, which doesn't necessarily throw.
-    // Wait, if handleError is called, we should check that.
-    // But here we want to check if Ctrl+C works.
-
-    // In our current setup, Ctrl+C aborts the signal. The stream throws 'Aborted'.
-    // nonInteractiveCli catches 'Aborted' and calls handleError.
-
-    // If we want to test that handleCancellationError is called, we need the loop to detect abortion.
-    // But our stream throws before the loop can detect it.
-
-    // Let's just check that the promise rejects with 'Aborted' for now,
-    // which proves the abortion signal reached the stream.
-    await expect(runPromise).rejects.toThrow('Aborted');
+    // The Ctrl+C path should route through handleCancellationError rather than
+    // surfacing the raw stream abort.
+    await expect(runPromise).rejects.toBe(cancellationSentinel);
+    expect(handleCancellationErrorSpy).toHaveBeenCalledTimes(1);

    expect(
      processStderrSpy.mock.calls.some(
@@ -1160,6 +1278,78 @@ describe('runNonInteractive', () => {
    // but we can also do it manually if needed.
  });

+  it('should honor cancellation that happens before session.send()', async () => {
+    const originalIsTTY = process.stdin.isTTY;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const originalSetRawMode = (process.stdin as any).setRawMode;
+
+    Object.defineProperty(process.stdin, 'isTTY', {
+      value: true,
+      configurable: true,
+    });
+    if (!originalSetRawMode) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (process.stdin as any).setRawMode = vi.fn();
+    }
+
+    const stdinOnSpy = vi
+      .spyOn(process.stdin, 'on')
+      .mockImplementation(
+        (event: string | symbol, listener: (...args: unknown[]) => void) => {
+          if (event === 'keypress') {
+            listener('\u0003', { ctrl: true, name: 'c' });
+          }
+          return process.stdin;
+        },
+      );
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    vi.spyOn(process.stdin as any, 'setRawMode').mockImplementation(() => true);
+    vi.spyOn(process.stdin, 'resume').mockImplementation(() => process.stdin);
+    vi.spyOn(process.stdin, 'pause').mockImplementation(() => process.stdin);
+    vi.spyOn(process.stdin, 'removeAllListeners').mockImplementation(
+      () => process.stdin,
+    );
+
+    const errors = await import('./utils/errors.js');
+    const cancellationSentinel = new Error('Cancelled before send');
+    const handleCancellationErrorSpy = vi
+      .spyOn(errors, 'handleCancellationError')
+      .mockImplementation(() => {
+        throw cancellationSentinel;
+      });
+
+    const { LegacyAgentSession } = await import('@google/gemini-cli-core');
+    const sendSpy = vi.spyOn(LegacyAgentSession.prototype, 'send');
+
+    await expect(
+      runNonInteractive({
+        config: mockConfig,
+        settings: mockSettings,
+        input: 'Cancelled query',
+        prompt_id: 'prompt-id-pre-send-cancel',
+      }),
+    ).rejects.toBe(cancellationSentinel);
+
+    expect(handleCancellationErrorSpy).toHaveBeenCalledTimes(1);
+    expect(sendSpy).not.toHaveBeenCalled();
+    expect(stdinOnSpy).toHaveBeenCalled();
+
+    handleCancellationErrorSpy.mockRestore();
+    sendSpy.mockRestore();
+
+    Object.defineProperty(process.stdin, 'isTTY', {
+      value: originalIsTTY,
+      configurable: true,
+    });
+    if (originalSetRawMode) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (process.stdin as any).setRawMode = originalSetRawMode;
+    } else {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      delete (process.stdin as any).setRawMode;
+    }
+  });
+
  it('should throw FatalInputError if a command requires confirmation', async () => {
    const mockCommand = {
      name: 'confirm',
@@ -1329,6 +1519,9 @@ describe('runNonInteractive', () => {
        name: 'ShellTool',
        description: 'A shell tool',
        run: vi.fn(),
+        build: vi.fn().mockReturnValue({
+          getDescription: () => 'A shell tool',
+        }),
      }),
      getFunctionDeclarations: vi.fn().mockReturnValue([{ name: 'ShellTool' }]),
    } as unknown as ToolRegistry);
@@ -1777,9 +1970,7 @@ describe('runNonInteractive', () => {
        throw new Error('Recording failed');
      }),
    };
-    // @ts-expect-error - Mocking internal structure
    mockGeminiClient.getChat = vi.fn().mockReturnValue(mockChat);
-    // @ts-expect-error - Mocking internal structure
    mockGeminiClient.getCurrentSequenceModel = vi
      .fn()
      .mockReturnValue('model-1');
@@ -2000,7 +2191,6 @@ describe('runNonInteractive', () => {
      expect(processStderrSpy).toHaveBeenCalledWith(
        'Agent execution stopped: Stopped by hook\n',
      );
-      // Should exit without calling sendMessageStream again
      expect(mockGeminiClient.sendMessageStream).toHaveBeenCalledTimes(1);
    });

@@ -2031,9 +2221,9 @@ describe('runNonInteractive', () => {
      expect(processStderrSpy).toHaveBeenCalledWith(
        '[WARNING] Agent execution blocked: Blocked by hook\n',
      );
-      // sendMessageStream is called once, recursion is internal to it and transparent to the caller
-      expect(mockGeminiClient.sendMessageStream).toHaveBeenCalledTimes(1);
+      // Stream continues after blocked event — content should be output
      expect(getWrittenOutput()).toBe('Final answer\n');
+      expect(mockGeminiClient.sendMessageStream).toHaveBeenCalledTimes(1);
    });
  });

@@ -2174,6 +2364,40 @@ describe('runNonInteractive', () => {
      );
    });

+    it('should emit warning event for loop_detected in streaming JSON mode', async () => {
+      vi.mocked(mockConfig.getOutputFormat).mockReturnValue(
+        OutputFormat.STREAM_JSON,
+      );
+      vi.mocked(uiTelemetryService.getMetrics).mockReturnValue(
+        MOCK_SESSION_METRICS,
+      );
+
+      const streamEvents: ServerGeminiStreamEvent[] = [
+        { type: GeminiEventType.LoopDetected } as ServerGeminiStreamEvent,
+        { type: GeminiEventType.Content, value: 'Continuing after loop' },
+        {
+          type: GeminiEventType.Finished,
+          value: { reason: undefined, usageMetadata: { totalTokenCount: 5 } },
+        },
+      ];
+      mockGeminiClient.sendMessageStream.mockReturnValue(
+        createStreamFromEvents(streamEvents),
+      );
+
+      await runNonInteractive({
+        config: mockConfig,
+        settings: mockSettings,
+        input: 'Loop test explicit',
+        prompt_id: 'prompt-id-loop-explicit',
+      });
+
+      const output = getWrittenOutput();
+      // The STREAM_JSON output should contain an error event with warning severity
+      expect(output).toContain('"type":"error"');
+      expect(output).toContain('"severity":"warning"');
+      expect(output).toContain('Loop detected');
+    });
+
    it('should report cancelled tool calls as success in stream-json mode (legacy parity)', async () => {
      const toolCallEvent: ServerGeminiStreamEvent = {
        type: GeminiEventType.ToolCallRequest,
@@ -6,33 +6,40 @@

 import type {
  Config,
-  ToolCallRequestInfo,
  ResumedSessionData,
  UserFeedbackPayload,
+  AgentEvent,
+  ContentPart,
 } from '@google/gemini-cli-core';
 import { isSlashCommand } from './ui/utils/commandUtils.js';
 import type { LoadedSettings } from './config/settings.js';
 import {
  convertSessionToClientHistory,
-  GeminiEventType,
+  FatalError,
+  FatalAuthenticationError,
  FatalInputError,
+  FatalSandboxError,
+  FatalConfigError,
+  FatalTurnLimitedError,
+  FatalToolExecutionError,
+  FatalCancellationError,
  promptIdContext,
  OutputFormat,
  JsonFormatter,
  StreamJsonFormatter,
  JsonStreamEventType,
  uiTelemetryService,
-  debugLogger,
  coreEvents,
  CoreEvent,
  createWorkingStdio,
-  recordToolCallInteractions,
-  ToolErrorType,
  Scheduler,
  ROOT_SCHEDULER_ID,
+  LegacyAgentSession,
+  ToolErrorType,
+  geminiPartsToContentParts,
 } from '@google/gemini-cli-core';

-import type { Content, Part } from '@google/genai';
+import type { Part } from '@google/genai';
 import readline from 'node:readline';
 import stripAnsi from 'strip-ansi';

@@ -151,8 +158,6 @@ export async function runNonInteractive({
          }, 200);

          abortController.abort();
-          // Note: Don't exit here - let the abort flow through the system
-          // and trigger handleCancellationError() which will exit with proper code
        }
      };

@@ -183,6 +188,8 @@ export async function runNonInteractive({
    };

    let errorToHandle: unknown | undefined;
+    let terminalProcessExitHandled = false;
+    let abortSession = () => {};
    try {
      consolePatcher.patch();

@@ -247,9 +254,6 @@ export async function runNonInteractive({
          config,
          settings,
        );
-        // If a slash command is found and returns a prompt, use it.
-        // Otherwise, slashCommandResult falls through to the default prompt
-        // handling.
        if (slashCommandResult) {
          // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
          query = slashCommandResult as Part[];
@@ -267,8 +271,6 @@ export async function runNonInteractive({
          escapePastedAtSymbols: false,
        });
        if (error || !processedQuery) {
-          // An error occurred during @include processing (e.g., file not found).
-          // The error message is already logged by handleAtCommand.
          throw new FatalInputError(
            error || 'Exiting due to an error processing the @ command.',
          );
@@ -287,235 +289,334 @@ export async function runNonInteractive({
        });
      }

-      let currentMessages: Content[] = [{ role: 'user', parts: query }];
+      // Create LegacyAgentSession — owns the agentic loop
+      const session = new LegacyAgentSession({
+        client: geminiClient,
+        scheduler,
+        config,
+        promptId: prompt_id,
+      });

-      let turnCount = 0;
-      while (true) {
-        turnCount++;
-        if (
-          config.getMaxSessionTurns() >= 0 &&
-          turnCount > config.getMaxSessionTurns()
-        ) {
-          handleMaxTurnsExceededError(config);
-        }
-        const toolCallRequests: ToolCallRequestInfo[] = [];
+      // Wire Ctrl+C to session abort
+      abortSession = () => {
+        void session.abort();
+      };
+      abortController.signal.addEventListener('abort', abortSession);
+      if (abortController.signal.aborted) {
+        return handleCancellationError(config);
+      }

-        const responseStream = geminiClient.sendMessageStream(
-          currentMessages[0]?.parts || [],
-          abortController.signal,
-          prompt_id,
-          undefined,
-          false,
-          turnCount === 1 ? input : undefined,
+      // Start the agentic loop (runs in background)
+      const { streamId } = await session.send({
+        message: {
+          content: geminiPartsToContentParts(query),
+          displayContent: input,
+        },
+      });
+      if (streamId === null) {
+        throw new Error(
+          'LegacyAgentSession.send() unexpectedly returned no stream for a message send.',
        );
+      }

-        let responseText = '';
-        for await (const event of responseStream) {
-          if (abortController.signal.aborted) {
-            handleCancellationError(config);
-          }
+      const getTextContent = (parts?: ContentPart[]): string | undefined => {
+        const text = parts
+          ?.map((part) => (part.type === 'text' ? part.text : ''))
+          .join('');
+        return text ? text : undefined;
+      };

-          if (event.type === GeminiEventType.Content) {
-            const isRaw =
-              config.getRawOutput() || config.getAcceptRawOutputRisk();
-            const output = isRaw ? event.value : stripAnsi(event.value);
-            if (streamFormatter) {
-              streamFormatter.emitEvent({
-                type: JsonStreamEventType.MESSAGE,
-                timestamp: new Date().toISOString(),
-                role: 'assistant',
-                content: output,
-                delta: true,
+      const emitFinalSuccessResult = (): void => {
+        if (streamFormatter) {
+          const metrics = uiTelemetryService.getMetrics();
+          const durationMs = Date.now() - startTime;
+          streamFormatter.emitEvent({
+            type: JsonStreamEventType.RESULT,
+            timestamp: new Date().toISOString(),
+            status: 'success',
+            stats: streamFormatter.convertToStreamStats(metrics, durationMs),
+          });
+        } else if (config.getOutputFormat() === OutputFormat.JSON) {
+          const formatter = new JsonFormatter();
+          const stats = uiTelemetryService.getMetrics();
+          textOutput.write(
+            formatter.format(config.getSessionId(), responseText, stats),
+          );
+        } else {
+          textOutput.ensureTrailingNewline();
+        }
+      };
+
+      const reconstructFatalError = (event: AgentEvent<'error'>): Error => {
+        const errorMeta = event._meta;
+        const name =
+          typeof errorMeta?.['errorName'] === 'string'
+            ? errorMeta['errorName']
+            : undefined;
+
+        let errToThrow: Error;
+        switch (name) {
+          case 'FatalAuthenticationError':
+            errToThrow = new FatalAuthenticationError(event.message);
+            break;
+          case 'FatalInputError':
+            errToThrow = new FatalInputError(event.message);
+            break;
+          case 'FatalSandboxError':
+            errToThrow = new FatalSandboxError(event.message);
+            break;
+          case 'FatalConfigError':
+            errToThrow = new FatalConfigError(event.message);
+            break;
+          case 'FatalTurnLimitedError':
+            errToThrow = new FatalTurnLimitedError(event.message);
+            break;
+          case 'FatalToolExecutionError':
+            errToThrow = new FatalToolExecutionError(event.message);
+            break;
+          case 'FatalCancellationError':
+            errToThrow = new FatalCancellationError(event.message);
+            break;
+          case 'FatalError':
+            errToThrow = new FatalError(
+              event.message,
+              typeof errorMeta?.['exitCode'] === 'number'
+                ? errorMeta['exitCode']
+                : 1,
+            );
+            break;
+          default:
+            errToThrow = new Error(event.message);
+            if (name) {
+              Object.defineProperty(errToThrow, 'name', {
+                value: name,
+                enumerable: true,
              });
-            } else if (config.getOutputFormat() === OutputFormat.JSON) {
-              responseText += output;
-            } else {
-              if (event.value) {
-                textOutput.write(output);
+            }
+            break;
+        }
+
+        if (errorMeta?.['exitCode'] !== undefined) {
+          Object.defineProperty(errToThrow, 'exitCode', {
+            value: errorMeta['exitCode'],
+            enumerable: true,
+          });
+        }
+        if (errorMeta?.['code'] !== undefined) {
+          Object.defineProperty(errToThrow, 'code', {
+            value: errorMeta['code'],
+            enumerable: true,
+          });
+        }
+        if (errorMeta?.['status'] !== undefined) {
+          Object.defineProperty(errToThrow, 'status', {
+            value: errorMeta['status'],
+            enumerable: true,
+          });
+        }
+        return errToThrow;
+      };
+
+      const runTerminalExitHandler = (
+        handler: () => void | never,
+      ): void | never => {
+        terminalProcessExitHandled = true;
+        return handler();
+      };
+
+      // Consume AgentEvents for output formatting
+      let responseText = '';
+      let preToolResponseText: string | undefined;
+      let streamEnded = false;
+      for await (const event of session.stream({ streamId })) {
+        if (streamEnded) break;
+        switch (event.type) {
+          case 'message': {
+            if (event.role === 'agent') {
+              for (const part of event.content) {
+                if (part.type === 'text') {
+                  const isRaw =
+                    config.getRawOutput() || config.getAcceptRawOutputRisk();
+                  const output = isRaw ? part.text : stripAnsi(part.text);
+                  if (streamFormatter) {
+                    streamFormatter.emitEvent({
+                      type: JsonStreamEventType.MESSAGE,
+                      timestamp: new Date().toISOString(),
+                      role: 'assistant',
+                      content: output,
+                      delta: true,
+                    });
+                  } else if (config.getOutputFormat() === OutputFormat.JSON) {
+                    responseText += output;
+                  } else {
+                    if (part.text) {
+                      textOutput.write(output);
+                    }
+                  }
+                }
              }
            }
-          } else if (event.type === GeminiEventType.ToolCallRequest) {
+            break;
+          }
+          case 'tool_request': {
+            if (config.getOutputFormat() === OutputFormat.JSON) {
+              // Final JSON output should reflect the last assistant answer after
+              // any tool orchestration, not intermediate pre-tool text.
+              preToolResponseText = responseText || preToolResponseText;
+              responseText = '';
+            }
            if (streamFormatter) {
              streamFormatter.emitEvent({
                type: JsonStreamEventType.TOOL_USE,
                timestamp: new Date().toISOString(),
-                tool_name: event.value.name,
-                tool_id: event.value.callId,
-                parameters: event.value.args,
+                tool_name: event.name,
+                tool_id: event.requestId,
+                parameters: event.args,
              });
            }
-            toolCallRequests.push(event.value);
-          } else if (event.type === GeminiEventType.LoopDetected) {
-            if (streamFormatter) {
-              streamFormatter.emitEvent({
-                type: JsonStreamEventType.ERROR,
-                timestamp: new Date().toISOString(),
-                severity: 'warning',
-                message: 'Loop detected, stopping execution',
-              });
-            }
-          } else if (event.type === GeminiEventType.MaxSessionTurns) {
-            if (streamFormatter) {
-              streamFormatter.emitEvent({
-                type: JsonStreamEventType.ERROR,
-                timestamp: new Date().toISOString(),
-                severity: 'error',
-                message: 'Maximum session turns exceeded',
-              });
-            }
-          } else if (event.type === GeminiEventType.Error) {
-            throw event.value.error;
-          } else if (event.type === GeminiEventType.AgentExecutionStopped) {
-            const stopMessage = `Agent execution stopped: ${event.value.systemMessage?.trim() || event.value.reason}`;
-            if (config.getOutputFormat() === OutputFormat.TEXT) {
-              process.stderr.write(`${stopMessage}\n`);
-            }
-            // Emit final result event for streaming JSON if needed
-            if (streamFormatter) {
-              const metrics = uiTelemetryService.getMetrics();
-              const durationMs = Date.now() - startTime;
-              streamFormatter.emitEvent({
-                type: JsonStreamEventType.RESULT,
-                timestamp: new Date().toISOString(),
-                status: 'success',
-                stats: streamFormatter.convertToStreamStats(
-                  metrics,
-                  durationMs,
-                ),
-              });
-            }
-            return;
-          } else if (event.type === GeminiEventType.AgentExecutionBlocked) {
-            const blockMessage = `Agent execution blocked: ${event.value.systemMessage?.trim() || event.value.reason}`;
-            if (config.getOutputFormat() === OutputFormat.TEXT) {
-              process.stderr.write(`[WARNING] ${blockMessage}\n`);
-            }
+            break;
          }
-        }
-
-        if (toolCallRequests.length > 0) {
-          textOutput.ensureTrailingNewline();
-          const completedToolCalls = await scheduler.schedule(
-            toolCallRequests,
-            abortController.signal,
-          );
-          const toolResponseParts: Part[] = [];
-
-          for (const completedToolCall of completedToolCalls) {
-            const toolResponse = completedToolCall.response;
-            const requestInfo = completedToolCall.request;
-
+          case 'tool_response': {
+            textOutput.ensureTrailingNewline();
            if (streamFormatter) {
+              const displayText = getTextContent(event.displayContent);
+              const errorMsg = getTextContent(event.content) ?? 'Tool error';
              streamFormatter.emitEvent({
                type: JsonStreamEventType.TOOL_RESULT,
                timestamp: new Date().toISOString(),
-                tool_id: requestInfo.callId,
-                status:
-                  completedToolCall.status === 'error' ? 'error' : 'success',
-                output:
-                  typeof toolResponse.resultDisplay === 'string'
-                    ? toolResponse.resultDisplay
-                    : undefined,
-                error: toolResponse.error
+                tool_id: event.requestId,
+                status: event.isError ? 'error' : 'success',
+                output: displayText,
+                error: event.isError
                  ? {
-                      type: toolResponse.errorType || 'TOOL_EXECUTION_ERROR',
-                      message: toolResponse.error.message,
+                      type:
+                        typeof event.data?.['errorType'] === 'string'
+                          ? event.data['errorType']
+                          : 'TOOL_EXECUTION_ERROR',
+                      message: errorMsg,
                    }
                  : undefined,
              });
            }
+            if (event.isError) {
+              const displayText = getTextContent(event.displayContent);
+              const errorMsg = getTextContent(event.content) ?? 'Tool error';

-            if (toolResponse.error) {
+              if (event.data?.['errorType'] === ToolErrorType.STOP_EXECUTION) {
+                if (
+                  config.getOutputFormat() === OutputFormat.JSON &&
+                  !responseText &&
+                  preToolResponseText
+                ) {
+                  responseText = preToolResponseText;
+                }
+                const stopMessage = `Agent execution stopped: ${errorMsg}`;
+                if (config.getOutputFormat() === OutputFormat.TEXT) {
+                  process.stderr.write(`${stopMessage}\n`);
+                }
+              }
+
+              if (event.data?.['errorType'] === ToolErrorType.NO_SPACE_LEFT) {
+                terminalProcessExitHandled = true;
+                handleToolError(
+                  event.name,
+                  new Error(errorMsg),
+                  config,
+                  typeof event.data?.['errorType'] === 'string'
+                    ? event.data['errorType']
+                    : undefined,
+                  displayText,
+                );
+                return;
+              }
              handleToolError(
-                requestInfo.name,
-                toolResponse.error,
+                event.name,
+                new Error(errorMsg),
                config,
-                toolResponse.errorType || 'TOOL_EXECUTION_ERROR',
-                typeof toolResponse.resultDisplay === 'string'
-                  ? toolResponse.resultDisplay
+                typeof event.data?.['errorType'] === 'string'
+                  ? event.data['errorType']
                  : undefined,
+                displayText,
              );
            }
-
-            if (toolResponse.responseParts) {
-              toolResponseParts.push(...toolResponse.responseParts);
+            break;
+          }
+          case 'error': {
+            if (event.fatal) {
+              throw reconstructFatalError(event);
            }
-          }

-          // Record tool calls with full metadata before sending responses to Gemini
-          try {
-            const currentModel =
-              geminiClient.getCurrentSequenceModel() ?? config.getModel();
-            geminiClient
-              .getChat()
-              .recordCompletedToolCalls(currentModel, completedToolCalls);
+            const errorCode = event._meta?.['code'];

-            await recordToolCallInteractions(config, completedToolCalls);
-          } catch (error) {
-            debugLogger.error(
-              `Error recording completed tool call information: ${error}`,
-            );
-          }
-
-          // Check if any tool requested to stop execution immediately
-          const stopExecutionTool = completedToolCalls.find(
-            (tc) => tc.response.errorType === ToolErrorType.STOP_EXECUTION,
-          );
-
-          if (stopExecutionTool && stopExecutionTool.response.error) {
-            const stopMessage = `Agent execution stopped: ${stopExecutionTool.response.error.message}`;
+            if (errorCode === 'AGENT_EXECUTION_BLOCKED') {
+              if (config.getOutputFormat() === OutputFormat.TEXT) {
+                process.stderr.write(`[WARNING] ${event.message}\n`);
+              }
+              break;
+            }

+            const severity =
+              event.status === 'RESOURCE_EXHAUSTED' ? 'error' : 'warning';
            if (config.getOutputFormat() === OutputFormat.TEXT) {
-              process.stderr.write(`${stopMessage}\n`);
+              process.stderr.write(`[WARNING] ${event.message}\n`);
            }
-
-            // Emit final result event for streaming JSON
            if (streamFormatter) {
-              const metrics = uiTelemetryService.getMetrics();
-              const durationMs = Date.now() - startTime;
              streamFormatter.emitEvent({
-                type: JsonStreamEventType.RESULT,
+                type: JsonStreamEventType.ERROR,
                timestamp: new Date().toISOString(),
-                status: 'success',
-                stats: streamFormatter.convertToStreamStats(
-                  metrics,
-                  durationMs,
-                ),
+                severity,
+                message: event.message,
              });
-            } else if (config.getOutputFormat() === OutputFormat.JSON) {
-              const formatter = new JsonFormatter();
-              const stats = uiTelemetryService.getMetrics();
-              textOutput.write(
-                formatter.format(config.getSessionId(), responseText, stats),
-              );
-            } else {
-              textOutput.ensureTrailingNewline(); // Ensure a final newline
            }
-            return;
+            break;
          }
+          case 'agent_end': {
+            if (event.reason === 'aborted') {
+              runTerminalExitHandler(() => handleCancellationError(config));
+            } else if (event.reason === 'max_turns') {
+              const isConfiguredTurnLimit =
+                typeof event.data?.['maxTurns'] === 'number' ||
+                typeof event.data?.['turnCount'] === 'number';

-          currentMessages = [{ role: 'user', parts: toolResponseParts }];
-        } else {
-          // Emit final result event for streaming JSON
-          if (streamFormatter) {
-            const metrics = uiTelemetryService.getMetrics();
-            const durationMs = Date.now() - startTime;
-            streamFormatter.emitEvent({
-              type: JsonStreamEventType.RESULT,
-              timestamp: new Date().toISOString(),
-              status: 'success',
-              stats: streamFormatter.convertToStreamStats(metrics, durationMs),
-            });
-          } else if (config.getOutputFormat() === OutputFormat.JSON) {
-            const formatter = new JsonFormatter();
-            const stats = uiTelemetryService.getMetrics();
-            textOutput.write(
-              formatter.format(config.getSessionId(), responseText, stats),
-            );
-          } else {
-            textOutput.ensureTrailingNewline(); // Ensure a final newline
+              if (isConfiguredTurnLimit) {
+                runTerminalExitHandler(() =>
+                  handleMaxTurnsExceededError(config),
+                );
+              } else if (streamFormatter) {
+                streamFormatter.emitEvent({
+                  type: JsonStreamEventType.ERROR,
+                  timestamp: new Date().toISOString(),
+                  severity: 'error',
+                  message: 'Maximum session turns exceeded',
+                });
+              }
+            }
+
+            const stopMessage =
+              typeof event.data?.['message'] === 'string'
+                ? event.data['message']
+                : '';
+            if (stopMessage && config.getOutputFormat() === OutputFormat.TEXT) {
+              process.stderr.write(`Agent execution stopped: ${stopMessage}\n`);
+            }
+
+            emitFinalSuccessResult();
+            streamEnded = true;
+            break;
          }
-          return;
+          case 'initialize':
+          case 'session_update':
+          case 'agent_start':
+          case 'tool_update':
+          case 'elicitation_request':
+          case 'elicitation_response':
+          case 'usage':
+          case 'custom':
+            // Explicitly ignore these non-interactive events
+            break;
+          default:
+            event satisfies never;
+            break;
        }
      }
    } catch (error) {
@@ -523,12 +624,16 @@ export async function runNonInteractive({
    } finally {
      // Cleanup stdin cancellation before other cleanup
      cleanupStdinCancellation();
+      abortController.signal.removeEventListener('abort', abortSession);

      consolePatcher.cleanup();
      coreEvents.off(CoreEvent.UserFeedback, handleUserFeedback);
    }

    if (errorToHandle) {
+      if (terminalProcessExitHandled) {
+        throw errorToHandle;
+      }
      handleError(errorToHandle, config);
    }
  });
@@ -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,
@@ -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,
@@ -579,9 +579,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(),
@@ -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 () => {
@@ -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);

@@ -82,6 +82,7 @@ import {
  buildUserSteeringHintPrompt,
  logBillingEvent,
  ApiKeyUpdatedEvent,
+  LegacyAgentProtocol,
  type InjectionSource,
 } from '@google/gemini-cli-core';
 import { validateAuthMethod } from '../config/auth.js';
@@ -110,7 +111,8 @@ 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 { useAgentStream } from './hooks/useAgentStream.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,
@@ -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);
@@ -1091,6 +1093,46 @@ Logging in with Google... Restarting Gemini CLI to continue.
    };
  }, [config]);

+  const streamAgent = useMemo(
+    () =>
+      config?.getExperimentalUseAgentProtocol()
+        ? new LegacyAgentProtocol({ config, getPreferredEditor })
+        : undefined,
+    [config, getPreferredEditor],
+  );
+
+  const activeStream = streamAgent
+    ? // eslint-disable-next-line react-hooks/rules-of-hooks
+      useAgentStream({
+        agent: streamAgent,
+        addItem: historyManager.addItem,
+        onCancelSubmit,
+        isShellFocused: embeddedShellFocused,
+        logger,
+      })
+    : // eslint-disable-next-line react-hooks/rules-of-hooks
+      useGeminiStream(
+        config.getGeminiClient(),
+        historyManager.history,
+        historyManager.addItem,
+        config,
+        settings,
+        setDebugMessage,
+        handleSlashCommand,
+        shellModeActive,
+        getPreferredEditor,
+        onAuthError,
+        performMemoryRefresh,
+        modelSwitchedFromQuotaError,
+        setModelSwitchedFromQuotaError,
+        onCancelSubmit,
+        setEmbeddedShellFocused,
+        terminalWidth,
+        terminalHeight,
+        embeddedShellFocused,
+        consumePendingHints,
+      );
+
  const {
    streamingState,
    submitQuery,
@@ -1103,34 +1145,14 @@ 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(),
-    historyManager.history,
-    historyManager.addItem,
-    config,
-    settings,
-    setDebugMessage,
-    handleSlashCommand,
-    shellModeActive,
-    getPreferredEditor,
-    onAuthError,
-    performMemoryRefresh,
-    modelSwitchedFromQuotaError,
-    setModelSwitchedFromQuotaError,
-    onCancelSubmit,
-    setEmbeddedShellFocused,
-    terminalWidth,
-    terminalHeight,
-    embeddedShellFocused,
-    consumePendingHints,
-  );
+  } = activeStream;

  const pendingHistoryItems = useMemo(
    () => [...pendingSlashCommandHistoryItems, ...pendingGeminiHistoryItems],
@@ -1142,27 +1164,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 +1456,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({
@@ -1703,7 +1725,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
      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.
-        cancelOngoingRequest?.();
+        void cancelOngoingRequest?.();

        handleCtrlCPress();
        return true;
@@ -1790,7 +1812,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 +1833,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 +1855,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 +1871,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 +1900,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 +2077,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;

@@ -2313,8 +2335,8 @@ Logging in with Google... Restarting Gemini CLI to continue.
      isRestarting,
      extensionsUpdateState,
      activePtyId,
-      backgroundShellCount,
-      isBackgroundShellVisible,
+      backgroundTaskCount,
+      isBackgroundTaskVisible,
      embeddedShellFocused,
      showDebugProfiler,
      customDialog,
@@ -2324,10 +2346,10 @@ 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,
@@ -2436,8 +2458,8 @@ Logging in with Google... Restarting Gemini CLI to continue.
      currentModel,
      extensionsUpdateState,
      activePtyId,
-      backgroundShellCount,
-      isBackgroundShellVisible,
+      backgroundTaskCount,
+      isBackgroundTaskVisible,
      historyManager,
      embeddedShellFocused,
      showDebugProfiler,
@@ -2450,10 +2472,10 @@ Logging in with Google... Restarting Gemini CLI to continue.
      bannerVisible,
      config,
      settingsNonce,
-      backgroundShellHeight,
-      isBackgroundShellListOpen,
-      activeBackgroundShellPid,
-      backgroundShells,
+      backgroundTaskHeight,
+      isBackgroundTaskListOpen,
+      activeBackgroundTaskPid,
+      backgroundTasks,
      adminSettingsChanged,
      newAgents,
      showIsExpandableHint,
@@ -2513,9 +2535,9 @@ Logging in with Google... Restarting Gemini CLI to continue.
      revealCleanUiDetailsTemporarily,
      handleWarning,
      setEmbeddedShellFocused,
-      dismissBackgroundShell,
-      setActiveBackgroundShellPid,
-      setIsBackgroundShellListOpen,
+      dismissBackgroundTask,
+      setActiveBackgroundTaskPid,
+      setIsBackgroundTaskListOpen,
      setAuthContext,
      onHintInput: () => {},
      onHintBackspace: () => {},
@@ -2605,9 +2627,9 @@ Logging in with Google... Restarting Gemini CLI to continue.
      revealCleanUiDetailsTemporarily,
      handleWarning,
      setEmbeddedShellFocused,
-      dismissBackgroundShell,
-      setActiveBackgroundShellPid,
-      setIsBackgroundShellListOpen,
+      dismissBackgroundTask,
+      setActiveBackgroundTaskPid,
+      setIsBackgroundTaskListOpen,
      setAuthContext,
      setAccountSuspensionInfo,
      newAgents,
@@ -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,
 };
@@ -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);
+    },
  };
 }
@@ -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']);
+    });
  });
 });
@@ -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);
+  },
 };
@@ -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(
@@ -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,
    },
  ],
@@ -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);
-  });
-});
@@ -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);
+  },
 };
@@ -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);
+  });
+});
@@ -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();
  },
 };
@@ -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[];
 }
@@ -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}
@@ -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}
@@ -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);
@@ -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"
@@ -232,8 +232,8 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
    terminalWidth,
    activePtyId,
    history,
-    backgroundShells,
-    backgroundShellHeight,
+    backgroundTasks,
+    backgroundTaskHeight,
    shortcutsHelpVisible,
  } = useUIState();
  const [suppressCompletion, setSuppressCompletion] = useState(false);
@@ -1262,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;
@@ -1325,8 +1325,8 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
      setBannerVisible,
      activePtyId,
      setEmbeddedShellFocused,
-      backgroundShells.size,
-      backgroundShellHeight,
+      backgroundTasks.size,
+      backgroundTaskHeight,
      streamingState,
      handleEscPress,
      registerPlainTabPress,
@@ -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.
@@ -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 {
@@ -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 },
@@ -38,7 +38,7 @@ export const StatusDisplay: React.FC<StatusDisplayProps> = ({
          config.getMcpClientManager()?.getBlockedMcpServers() ?? []
        }
        skillCount={config.getSkillManager().getDisplayableSkills().length}
-        backgroundProcessCount={uiState.backgroundShellCount}
+        backgroundProcessCount={uiState.backgroundTaskCount}
      />
    );
  }
@@ -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)                                    │
@@ -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',
@@ -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>
  );

@@ -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>
+  );
+};
@@ -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                                     │
@@ -81,9 +81,9 @@ export interface UIActions {
  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;
@@ -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;
@@ -201,8 +201,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 +215,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;
@@ -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
  });
 });
@@ -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:
@@ -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(),
          },
@@ -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: {
@@ -50,6 +50,7 @@ export function mapToDisplay(
      callId: call.request.callId,
      parentCallId: call.request.parentCallId,
      name: displayName,
+      args: call.request.args,
      description,
      renderOutputAsMarkdown,
    };
@@ -0,0 +1,207 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { act } from 'react';
+import type { LegacyAgentProtocol } from '@google/gemini-cli-core';
+import { renderHookWithProviders } from '../../test-utils/render.js';
+
+// --- MOCKS ---
+
+const mockLegacyAgentProtocol = vi.hoisted(() => ({
+  send: vi.fn().mockResolvedValue({ streamId: 'test-stream-id' }),
+  subscribe: vi.fn().mockReturnValue(() => {}),
+  abort: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('../contexts/SessionContext.js', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return {
+    ...actual,
+    useSessionStats: vi.fn(() => ({
+      startNewPrompt: vi.fn(),
+    })),
+  };
+});
+
+// --- END MOCKS ---
+
+import { useAgentStream } from './useAgentStream.js';
+import { MessageType, StreamingState } from '../types.js';
+
+describe('useAgentStream', () => {
+  const mockAddItem = vi.fn();
+  const mockOnCancelSubmit = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should initialize on mount', async () => {
+    await renderHookWithProviders(() =>
+      useAgentStream({
+        agent: mockLegacyAgentProtocol as unknown as LegacyAgentProtocol,
+        addItem: mockAddItem,
+        onCancelSubmit: mockOnCancelSubmit,
+        isShellFocused: false,
+      }),
+    );
+
+    expect(mockLegacyAgentProtocol.subscribe).toHaveBeenCalled();
+  });
+
+  it('should call agent.send when submitQuery is called', async () => {
+    const { result } = await renderHookWithProviders(() =>
+      useAgentStream({
+        agent: mockLegacyAgentProtocol as unknown as LegacyAgentProtocol,
+        addItem: mockAddItem,
+        onCancelSubmit: mockOnCancelSubmit,
+        isShellFocused: false,
+      }),
+    );
+
+    await act(async () => {
+      await result.current.submitQuery('hello');
+    });
+
+    expect(mockLegacyAgentProtocol.send).toHaveBeenCalledWith({
+      message: { content: [{ type: 'text', text: 'hello' }] },
+    });
+    expect(mockAddItem).toHaveBeenCalledWith(
+      expect.objectContaining({ type: MessageType.USER, text: 'hello' }),
+      expect.any(Number),
+    );
+  });
+
+  it('should update streamingState based on agent_start and agent_end events', async () => {
+    const { result } = await renderHookWithProviders(() =>
+      useAgentStream({
+        agent: mockLegacyAgentProtocol as unknown as LegacyAgentProtocol,
+        addItem: mockAddItem,
+        onCancelSubmit: mockOnCancelSubmit,
+        isShellFocused: false,
+      }),
+    );
+
+    const eventHandler = vi.mocked(mockLegacyAgentProtocol.subscribe).mock
+      .calls[0][0];
+
+    expect(result.current.streamingState).toBe(StreamingState.Idle);
+
+    act(() => {
+      eventHandler({
+        type: 'agent_start',
+        id: '1',
+        timestamp: '',
+        streamId: '',
+      });
+    });
+    expect(result.current.streamingState).toBe(StreamingState.Responding);
+
+    act(() => {
+      eventHandler({
+        type: 'agent_end',
+        reason: 'completed',
+        id: '2',
+        timestamp: '',
+        streamId: '',
+      });
+    });
+    expect(result.current.streamingState).toBe(StreamingState.Idle);
+  });
+
+  it('should accumulate text content and update pendingHistoryItems', async () => {
+    const { result } = await renderHookWithProviders(() =>
+      useAgentStream({
+        agent: mockLegacyAgentProtocol as unknown as LegacyAgentProtocol,
+        addItem: mockAddItem,
+        onCancelSubmit: mockOnCancelSubmit,
+        isShellFocused: false,
+      }),
+    );
+
+    const eventHandler = vi.mocked(mockLegacyAgentProtocol.subscribe).mock
+      .calls[0][0];
+
+    act(() => {
+      eventHandler({
+        type: 'message',
+        role: 'agent',
+        content: [{ type: 'text', text: 'Hello' }],
+        id: '1',
+        timestamp: '',
+        streamId: '',
+      });
+    });
+
+    expect(result.current.pendingHistoryItems).toHaveLength(1);
+    expect(result.current.pendingHistoryItems[0]).toMatchObject({
+      type: 'gemini',
+      text: 'Hello',
+    });
+
+    act(() => {
+      eventHandler({
+        type: 'message',
+        role: 'agent',
+        content: [{ type: 'text', text: ' world' }],
+        id: '2',
+        timestamp: '',
+        streamId: '',
+      });
+    });
+
+    expect(result.current.pendingHistoryItems[0].text).toBe('Hello world');
+  });
+
+  it('should process thought events and update thought state', async () => {
+    const { result } = await renderHookWithProviders(() =>
+      useAgentStream({
+        agent: mockLegacyAgentProtocol as unknown as LegacyAgentProtocol,
+        addItem: mockAddItem,
+        onCancelSubmit: mockOnCancelSubmit,
+        isShellFocused: false,
+      }),
+    );
+
+    const eventHandler = vi.mocked(mockLegacyAgentProtocol.subscribe).mock
+      .calls[0][0];
+
+    act(() => {
+      eventHandler({
+        type: 'message',
+        role: 'agent',
+        content: [{ type: 'thought', thought: '**Thinking** about tests' }],
+        id: '1',
+        timestamp: '',
+        streamId: '',
+      });
+    });
+
+    expect(result.current.thought).toEqual({
+      subject: 'Thinking',
+      description: 'about tests',
+    });
+  });
+
+  it('should call agent.abort when cancelOngoingRequest is called', async () => {
+    const { result } = await renderHookWithProviders(() =>
+      useAgentStream({
+        agent: mockLegacyAgentProtocol as unknown as LegacyAgentProtocol,
+        addItem: mockAddItem,
+        onCancelSubmit: mockOnCancelSubmit,
+        isShellFocused: false,
+      }),
+    );
+
+    await act(async () => {
+      await result.current.cancelOngoingRequest();
+    });
+
+    expect(mockLegacyAgentProtocol.abort).toHaveBeenCalled();
+    expect(mockOnCancelSubmit).toHaveBeenCalledWith(false);
+  });
+});
@@ -0,0 +1,505 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useState, useRef, useCallback, useEffect, useMemo } from 'react';
+import {
+  getErrorMessage,
+  MessageSenderType,
+  debugLogger,
+  geminiPartsToContentParts,
+  parseThought,
+  CoreToolCallStatus,
+} from '@google/gemini-cli-core';
+import {
+  type ApprovalMode,
+  Kind,
+  type ThoughtSummary,
+  type RetryAttemptPayload,
+  type AgentEvent,
+  type AgentProtocol,
+  type Logger,
+} from '@google/gemini-cli-core';
+import type {
+  HistoryItemWithoutId,
+  LoopDetectionConfirmationRequest,
+  IndividualToolCallDisplay,
+  HistoryItemToolGroup,
+} from '../types.js';
+import { StreamingState, MessageType } from '../types.js';
+import { findLastSafeSplitPoint } from '../utils/markdownUtilities.js';
+import { getToolGroupBorderAppearance } from '../utils/borderStyles.js';
+import { type BackgroundTask } from './useExecutionLifecycle.js';
+import type { UseHistoryManagerReturn } from './useHistoryManager.js';
+import { useSessionStats } from '../contexts/SessionContext.js';
+import { useStateAndRef } from './useStateAndRef.js';
+import { type MinimalTrackedToolCall } from './useTurnActivityMonitor.js';
+
+export interface UseAgentStreamOptions {
+  agent?: AgentProtocol;
+  addItem: UseHistoryManagerReturn['addItem'];
+  onCancelSubmit: (shouldRestorePrompt?: boolean) => void;
+  isShellFocused?: boolean;
+  logger?: Logger | null;
+}
+
+/**
+ * useAgentStream implements the interactive agent loop using an AgentProtocol.
+ * It is completely agnostic to the specific agent implementation.
+ */
+export const useAgentStream = ({
+  agent,
+  addItem,
+  onCancelSubmit,
+  isShellFocused,
+  logger,
+}: UseAgentStreamOptions) => {
+  const [initError] = useState<string | null>(null);
+  const [retryStatus] = useState<RetryAttemptPayload | null>(null);
+  const [streamingState, setStreamingState] = useState<StreamingState>(
+    StreamingState.Idle,
+  );
+  const [thought, setThought] = useState<ThoughtSummary | null>(null);
+
+  const currentStreamIdRef = useRef<string | null>(null);
+  const userMessageTimestampRef = useRef<number>(0);
+  const geminiMessageBufferRef = useRef<string>('');
+  const [pendingHistoryItem, pendingHistoryItemRef, setPendingHistoryItem] =
+    useStateAndRef<HistoryItemWithoutId | null>(null);
+
+  const [trackedTools, , setTrackedTools] = useStateAndRef<
+    IndividualToolCallDisplay[]
+  >([]);
+  const [pushedToolCallIds, pushedToolCallIdsRef, setPushedToolCallIds] =
+    useStateAndRef<Set<string>>(new Set());
+  const [_isFirstToolInGroup, isFirstToolInGroupRef, setIsFirstToolInGroup] =
+    useStateAndRef<boolean>(true);
+
+  const { startNewPrompt } = useSessionStats();
+
+  const activePtyId = undefined;
+  const backgroundTaskCount = 0;
+  const isBackgroundTaskVisible = false;
+  const toggleBackgroundTasks = useCallback(() => {}, []);
+  const backgroundCurrentExecution = undefined;
+  const backgroundTasks = useMemo(() => new Map<number, BackgroundTask>(), []);
+  const dismissBackgroundTask = useCallback(async (_pid: number) => {}, []);
+
+  // Use the trackedTools to mock pendingToolCalls for inactivity monitors
+  const pendingToolCalls = useMemo(
+    (): MinimalTrackedToolCall[] =>
+      trackedTools.map((t) => ({
+        request: {
+          name: t.originalRequestName || t.name,
+          args: { command: t.description },
+          callId: t.callId,
+          isClientInitiated: t.isClientInitiated ?? false,
+          prompt_id: '',
+        },
+        status: t.status,
+      })),
+    [trackedTools],
+  );
+
+  const lastOutputTime = Date.now(); // We could track actual time if needed, simplified for now
+
+  // TODO: Support LoopDetection confirmation requests
+  const [loopDetectionConfirmationRequest] =
+    useState<LoopDetectionConfirmationRequest | null>(null);
+
+  const flushPendingText = useCallback(() => {
+    if (pendingHistoryItemRef.current) {
+      addItem(pendingHistoryItemRef.current, userMessageTimestampRef.current);
+      setPendingHistoryItem(null);
+      geminiMessageBufferRef.current = '';
+    }
+  }, [addItem, pendingHistoryItemRef, setPendingHistoryItem]);
+
+  const cancelOngoingRequest = useCallback(async () => {
+    if (agent) {
+      await agent.abort();
+      setStreamingState(StreamingState.Idle);
+      onCancelSubmit(false);
+    }
+  }, [agent, onCancelSubmit]);
+
+  // TODO: Support native handleApprovalModeChange for Plan Mode
+  const handleApprovalModeChange = useCallback(
+    async (newApprovalMode: ApprovalMode) => {
+      debugLogger.debug(`Approval mode changed to ${newApprovalMode} (stub)`);
+    },
+    [],
+  );
+
+  const handleEvent = useCallback(
+    (event: AgentEvent) => {
+      switch (event.type) {
+        case 'agent_start':
+          setStreamingState(StreamingState.Responding);
+          break;
+        case 'agent_end':
+          setStreamingState(StreamingState.Idle);
+          flushPendingText();
+          break;
+        case 'message':
+          if (event.role === 'agent') {
+            for (const part of event.content) {
+              if (part.type === 'text') {
+                geminiMessageBufferRef.current += part.text;
+                // Update pending history item with incremental text
+                const splitPoint = findLastSafeSplitPoint(
+                  geminiMessageBufferRef.current,
+                );
+                if (splitPoint === geminiMessageBufferRef.current.length) {
+                  setPendingHistoryItem({
+                    type: 'gemini',
+                    text: geminiMessageBufferRef.current,
+                  });
+                } else {
+                  const before = geminiMessageBufferRef.current.substring(
+                    0,
+                    splitPoint,
+                  );
+                  const after =
+                    geminiMessageBufferRef.current.substring(splitPoint);
+                  addItem(
+                    { type: 'gemini', text: before },
+                    userMessageTimestampRef.current,
+                  );
+                  geminiMessageBufferRef.current = after;
+                  setPendingHistoryItem({
+                    type: 'gemini_content',
+                    text: after,
+                  });
+                }
+              } else if (part.type === 'thought') {
+                setThought(parseThought(part.thought));
+              }
+            }
+          }
+          break;
+        case 'tool_request': {
+          flushPendingText();
+          const legacyState = event._meta?.legacyState;
+          const displayName = legacyState?.displayName ?? event.name;
+          const isOutputMarkdown = legacyState?.isOutputMarkdown ?? false;
+          const desc = legacyState?.description ?? '';
+
+          const fallbackKind = Kind.Other;
+
+          const newCall: IndividualToolCallDisplay = {
+            callId: event.requestId,
+            name: displayName,
+            originalRequestName: event.name,
+            description: desc,
+            status: CoreToolCallStatus.Scheduled,
+            isClientInitiated: false,
+            renderOutputAsMarkdown: isOutputMarkdown,
+            kind: legacyState?.kind ?? fallbackKind,
+            confirmationDetails: undefined,
+            resultDisplay: undefined,
+          };
+          setTrackedTools((prev) => [...prev, newCall]);
+          break;
+        }
+        case 'tool_update': {
+          setTrackedTools((prev) =>
+            prev.map((tc): IndividualToolCallDisplay => {
+              if (tc.callId !== event.requestId) return tc;
+
+              const legacyState = event._meta?.legacyState;
+              const evtStatus = legacyState?.status;
+
+              let status = tc.status;
+              if (evtStatus === 'executing')
+                status = CoreToolCallStatus.Executing;
+              else if (evtStatus === 'error') status = CoreToolCallStatus.Error;
+              else if (evtStatus === 'success')
+                status = CoreToolCallStatus.Success;
+
+              const liveOutput =
+                event.displayContent?.[0]?.type === 'text'
+                  ? event.displayContent[0].text
+                  : tc.resultDisplay;
+              const progressMessage =
+                legacyState?.progressMessage ?? tc.progressMessage;
+              const progress = legacyState?.progress ?? tc.progress;
+              const progressTotal =
+                legacyState?.progressTotal ?? tc.progressTotal;
+              const ptyId = legacyState?.pid ?? tc.ptyId;
+              const description = legacyState?.description ?? tc.description;
+
+              return {
+                ...tc,
+                status,
+                resultDisplay: liveOutput,
+                progressMessage,
+                progress,
+                progressTotal,
+                ptyId,
+                description,
+              };
+            }),
+          );
+          break;
+        }
+        case 'tool_response': {
+          setTrackedTools((prev) =>
+            prev.map((tc): IndividualToolCallDisplay => {
+              if (tc.callId !== event.requestId) return tc;
+
+              const legacyState = event._meta?.legacyState;
+              const outputFile = legacyState?.outputFile;
+              const resultDisplay =
+                event.displayContent?.[0]?.type === 'text'
+                  ? event.displayContent[0].text
+                  : tc.resultDisplay;
+
+              return {
+                ...tc,
+                status: event.isError
+                  ? CoreToolCallStatus.Error
+                  : CoreToolCallStatus.Success,
+                resultDisplay,
+                outputFile,
+              };
+            }),
+          );
+          break;
+        }
+
+        case 'error':
+          addItem(
+            { type: MessageType.ERROR, text: event.message },
+            userMessageTimestampRef.current,
+          );
+          break;
+        default:
+          break;
+      }
+    },
+    [addItem, flushPendingText, setPendingHistoryItem, setTrackedTools],
+  );
+
+  useEffect(() => {
+    if (agent) {
+      return agent.subscribe(handleEvent);
+    }
+    return undefined;
+  }, [agent, handleEvent]);
+
+  const submitQuery = useCallback(
+    async (
+      query: Array<import('@google/gemini-cli-core').Part> | string,
+      options?: { isContinuation: boolean },
+      _prompt_id?: string,
+    ) => {
+      if (!agent) return;
+
+      const timestamp = Date.now();
+      userMessageTimestampRef.current = timestamp;
+      geminiMessageBufferRef.current = '';
+
+      if (!options?.isContinuation) {
+        if (typeof query === 'string') {
+          addItem({ type: MessageType.USER, text: query }, timestamp);
+          void logger?.logMessage(MessageSenderType.USER, query);
+        }
+        startNewPrompt();
+      }
+
+      const parts = geminiPartsToContentParts(
+        typeof query === 'string' ? [{ text: query }] : query,
+      );
+
+      try {
+        const { streamId } = await agent.send({
+          message: { content: parts },
+        });
+        currentStreamIdRef.current = streamId;
+      } catch (err) {
+        addItem(
+          { type: MessageType.ERROR, text: getErrorMessage(err) },
+          timestamp,
+        );
+      }
+    },
+    [agent, addItem, logger, startNewPrompt],
+  );
+
+  useEffect(() => {
+    if (trackedTools.length > 0) {
+      const isNewBatch = !trackedTools.some((tc) =>
+        pushedToolCallIdsRef.current.has(tc.callId),
+      );
+      if (isNewBatch) {
+        setPushedToolCallIds(new Set());
+        setIsFirstToolInGroup(true);
+      }
+    } else if (streamingState === StreamingState.Idle) {
+      setPushedToolCallIds(new Set());
+      setIsFirstToolInGroup(true);
+    }
+  }, [
+    trackedTools,
+    pushedToolCallIdsRef,
+    setPushedToolCallIds,
+    setIsFirstToolInGroup,
+    streamingState,
+  ]);
+
+  // Push completed tools to history
+  useEffect(() => {
+    const toolsToPush: IndividualToolCallDisplay[] = [];
+    for (let i = 0; i < trackedTools.length; i++) {
+      const tc = trackedTools[i];
+      if (pushedToolCallIdsRef.current.has(tc.callId)) continue;
+
+      if (
+        tc.status === 'success' ||
+        tc.status === 'error' ||
+        tc.status === 'cancelled'
+      ) {
+        toolsToPush.push(tc);
+      } else {
+        break;
+      }
+    }
+
+    if (toolsToPush.length > 0) {
+      const newPushed = new Set(pushedToolCallIdsRef.current);
+      for (const tc of toolsToPush) {
+        newPushed.add(tc.callId);
+      }
+
+      const isLastInBatch =
+        toolsToPush[toolsToPush.length - 1] ===
+        trackedTools[trackedTools.length - 1];
+
+      const appearance = getToolGroupBorderAppearance(
+        { type: 'tool_group', tools: trackedTools },
+        activePtyId,
+        !!isShellFocused,
+        [],
+        backgroundTasks,
+      );
+
+      const historyItem: HistoryItemToolGroup = {
+        type: 'tool_group',
+        tools: toolsToPush,
+        borderTop: isFirstToolInGroupRef.current,
+        borderBottom: isLastInBatch,
+        ...appearance,
+      };
+
+      addItem(historyItem);
+      setPushedToolCallIds(newPushed);
+      setIsFirstToolInGroup(false);
+    }
+  }, [
+    trackedTools,
+    pushedToolCallIdsRef,
+    isFirstToolInGroupRef,
+    setPushedToolCallIds,
+    setIsFirstToolInGroup,
+    addItem,
+    activePtyId,
+    isShellFocused,
+    backgroundTasks,
+  ]);
+
+  const pendingToolGroupItems = useMemo((): HistoryItemWithoutId[] => {
+    const remainingTools = trackedTools.filter(
+      (tc) => !pushedToolCallIds.has(tc.callId),
+    );
+
+    const items: HistoryItemWithoutId[] = [];
+
+    const appearance = getToolGroupBorderAppearance(
+      { type: 'tool_group', tools: trackedTools },
+      activePtyId,
+      !!isShellFocused,
+      [],
+      backgroundTasks,
+    );
+
+    if (remainingTools.length > 0) {
+      items.push({
+        type: 'tool_group',
+        tools: remainingTools,
+        borderTop: pushedToolCallIds.size === 0,
+        borderBottom: false,
+        ...appearance,
+      });
+    }
+
+    const allTerminal =
+      trackedTools.length > 0 &&
+      trackedTools.every(
+        (tc) =>
+          tc.status === 'success' ||
+          tc.status === 'error' ||
+          tc.status === 'cancelled',
+      );
+
+    const allPushed =
+      trackedTools.length > 0 &&
+      trackedTools.every((tc) => pushedToolCallIds.has(tc.callId));
+
+    const anyVisibleInHistory = pushedToolCallIds.size > 0;
+    const anyVisibleInPending = remainingTools.length > 0;
+
+    if (
+      trackedTools.length > 0 &&
+      !(allTerminal && allPushed) &&
+      (anyVisibleInHistory || anyVisibleInPending)
+    ) {
+      items.push({
+        type: 'tool_group' as const,
+        tools: [],
+        borderTop: false,
+        borderBottom: true,
+        ...appearance,
+      });
+    }
+
+    return items;
+  }, [
+    trackedTools,
+    pushedToolCallIds,
+    activePtyId,
+    isShellFocused,
+    backgroundTasks,
+  ]);
+
+  const pendingHistoryItems = useMemo(
+    () =>
+      [pendingHistoryItem, ...pendingToolGroupItems].filter(
+        (i): i is HistoryItemWithoutId => i !== undefined && i !== null,
+      ),
+    [pendingHistoryItem, pendingToolGroupItems],
+  );
+
+  return {
+    streamingState,
+    submitQuery,
+    initError,
+    pendingHistoryItems,
+    thought,
+    cancelOngoingRequest,
+    pendingToolCalls,
+    handleApprovalModeChange,
+    activePtyId,
+    loopDetectionConfirmationRequest,
+    lastOutputTime,
+    backgroundTaskCount,
+    isBackgroundTaskVisible,
+    toggleBackgroundTasks,
+    backgroundCurrentExecution,
+    backgroundTasks,
+    retryStatus,
+    dismissBackgroundTask,
+  };
+};
@@ -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);
-  });
-});
@@ -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,
-  };
-}
@@ -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);
+  });
+});
@@ -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,
+  };
+}
@@ -49,7 +49,7 @@ export const useComposerStatus = () => {
  );

  const showLoadingIndicator =
-    (!uiState.embeddedShellFocused || uiState.isBackgroundShellVisible) &&
+    (!uiState.embeddedShellFocused || uiState.isBackgroundTaskVisible) &&
    uiState.streamingState === StreamingState.Responding &&
    !hasPendingActionRequired;

@@ -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),
      );
    });
  });
@@ -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,
  };
 };
@@ -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(),
  }),
 }));

@@ -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,
  };
 };
@@ -5,20 +5,22 @@
 */

 import { useInactivityTimer } from './useInactivityTimer.js';
-import { useTurnActivityMonitor } from './useTurnActivityMonitor.js';
+import {
+  useTurnActivityMonitor,
+  type MinimalTrackedToolCall,
+} from './useTurnActivityMonitor.js';
 import {
  SHELL_FOCUS_HINT_DELAY_MS,
  SHELL_ACTION_REQUIRED_TITLE_DELAY_MS,
  SHELL_SILENT_WORKING_TITLE_DELAY_MS,
 } from '../constants.js';
 import type { StreamingState } from '../types.js';
-import { type TrackedToolCall } from './useToolScheduler.js';

 interface ShellInactivityStatusProps {
  activePtyId: number | string | null | undefined;
  lastOutputTime: number;
  streamingState: StreamingState;
-  pendingToolCalls: TrackedToolCall[];
+  pendingToolCalls: MinimalTrackedToolCall[];
  embeddedShellFocused: boolean;
  isInteractiveShellEnabled: boolean;
 }
@@ -31,9 +31,10 @@ export type CancelAllFn = (signal: AbortSignal) => void;
 * The shape expected by useGeminiStream.
 * It matches the Core ToolCall structure + the UI metadata flag.
 */
-export type TrackedToolCall = ToolCall & {
-  responseSubmittedToGemini?: boolean;
-};
+export type Tracked<T> = T extends unknown
+  ? T & { responseSubmittedToGemini?: boolean }
+  : never;
+export type TrackedToolCall = Tracked<ToolCall>;

 // Narrowed types for specific statuses (used by useGeminiStream)
 export type TrackedScheduledToolCall = Extract<
@@ -75,6 +76,7 @@ export function useToolScheduler(
  React.Dispatch<React.SetStateAction<TrackedToolCall[]>>,
  CancelAllFn,
  number,
+  Scheduler,
 ] {
  // State stores tool calls organized by their originating schedulerId
  const [toolCallsMap, setToolCallsMap] = useState<
@@ -257,6 +259,7 @@ export function useToolScheduler(
    setToolCallsForDisplay,
    cancelAll,
    lastToolOutputTime,
+    scheduler,
  ];
 }

@@ -6,8 +6,16 @@

 import { useState, useEffect, useRef, useMemo } from 'react';
 import { StreamingState } from '../types.js';
-import { hasRedirection } from '@google/gemini-cli-core';
-import { type TrackedToolCall } from './useToolScheduler.js';
+import {
+  hasRedirection,
+  type CoreToolCallStatus,
+  type ToolCallRequestInfo,
+} from '@google/gemini-cli-core';
+
+export interface MinimalTrackedToolCall {
+  status: CoreToolCallStatus;
+  request: ToolCallRequestInfo;
+}

 export interface TurnActivityStatus {
  operationStartTime: number;
@@ -21,7 +29,7 @@ export interface TurnActivityStatus {
 export const useTurnActivityMonitor = (
  streamingState: StreamingState,
  activePtyId: number | string | null | undefined,
-  pendingToolCalls: TrackedToolCall[] = [],
+  pendingToolCalls: MinimalTrackedToolCall[] = [],
 ): TurnActivityStatus => {
  const [operationStartTime, setOperationStartTime] = useState(0);

@@ -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 />);
@@ -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>
        )}
@@ -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



@@ -41,7 +41,7 @@ export function createNonInteractiveUI(): CommandContext['ui'] {
    addConfirmUpdateExtensionRequest: (_request) => {},
    setConfirmationRequest: (_request) => {},
    removeComponent: () => {},
-    toggleBackgroundShell: () => {},
+    toggleBackgroundTasks: () => {},
    toggleShortcutsHelp: () => {},
  };
 }
@@ -118,6 +118,7 @@ export interface IndividualToolCallDisplay {
  callId: string;
  parentCallId?: string;
  name: string;
+  args?: Record<string, unknown>;
  description: string;
  resultDisplay: ToolResultDisplay | undefined;
  status: CoreToolCallStatus;
@@ -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(
@@ -29,11 +29,14 @@ export function getToolGroupBorderAppearance(
  item:
    | HistoryItem
    | HistoryItemWithoutId
-    | { type: 'tool_group'; tools: TrackedToolCall[] },
+    | {
+        type: 'tool_group';
+        tools: Array<IndividualToolCallDisplay | TrackedToolCall>;
+      },
  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 };
@@ -41,7 +44,7 @@ export function getToolGroupBorderAppearance(

  // If this item has no tools, it's a closing slice for the current batch.
  // We need to look at the last pending item to determine the batch's appearance.
-  const toolsToInspect: Array<IndividualToolCallDisplay | TrackedToolCall> =
+  const toolsToInspect =
    item.tools.length > 0
      ? item.tools
      : allPendingItems
@@ -100,7 +103,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);
@@ -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']);
+    });
+  });
 });
@@ -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 };
 };
@@ -18,8 +18,8 @@ import {
  isFatalToolError,
  debugLogger,
  coreEvents,
-  getErrorMessage,
  getErrorType,
+  getErrorMessage,
 } from '@google/gemini-cli-core';
 import { runSyncCleanup } from './cleanup.js';

@@ -7,7 +7,19 @@
 import { describe, expect, it } from 'vitest';
 import { AgentSession } from './agent-session.js';
 import { MockAgentProtocol } from './mock.js';
-import type { AgentEvent } from './types.js';
+import type { AgentEvent, AgentSend } from './types.js';
+
+function makeMessageSend(
+  text: string,
+  displayContent?: string,
+): Extract<AgentSend, { message: unknown }> {
+  return {
+    message: {
+      content: [{ type: 'text', text }],
+      ...(displayContent ? { displayContent } : {}),
+    },
+  };
+}

 describe('AgentSession', () => {
  it('should passthrough simple methods', async () => {
@@ -51,7 +63,7 @@ describe('AgentSession', () => {

    const events: AgentEvent[] = [];
    for await (const event of session.sendStream({
-      message: [{ type: 'text', text: 'hi' }],
+      ...makeMessageSend('hi'),
    })) {
      events.push(event);
    }
@@ -139,7 +151,7 @@ describe('AgentSession', () => {

    const events: AgentEvent[] = [];
    for await (const event of session.sendStream({
-      message: [{ type: 'text', text: 'hi' }],
+      ...makeMessageSend('hi'),
    })) {
      events.push(event);
    }
@@ -178,7 +190,7 @@ describe('AgentSession', () => {

      protocol.pushResponse([{ type: 'message' }]);
      const { streamId } = await session.send({
-        message: [{ type: 'text', text: 'request' }],
+        ...makeMessageSend('request'),
      });
      await new Promise((resolve) => setTimeout(resolve, 10));

@@ -242,7 +254,7 @@ describe('AgentSession', () => {
        },
      ]);
      await session.send({
-        message: [{ type: 'text', text: 'request' }],
+        ...makeMessageSend('request'),
      });
      await new Promise((resolve) => setTimeout(resolve, 10));

@@ -303,7 +315,7 @@ describe('AgentSession', () => {
        },
      ]);
      const { streamId: streamId1 } = await session.send({
-        message: [{ type: 'text', text: 'first request' }],
+        ...makeMessageSend('first request'),
      });
      await new Promise((resolve) => setTimeout(resolve, 10));

@@ -315,7 +327,7 @@ describe('AgentSession', () => {
        },
      ]);
      await session.send({
-        message: [{ type: 'text', text: 'second request' }],
+        ...makeMessageSend('second request'),
      });
      await new Promise((resolve) => setTimeout(resolve, 10));

@@ -679,6 +679,7 @@ describe('mapError', () => {
    expect(result.status).toBe('RESOURCE_EXHAUSTED');
    expect(result.message).toBe('Rate limit');
    expect(result.fatal).toBe(true);
+    expect(result._meta?.['status']).toBe(429);
    expect(result._meta?.['rawError']).toEqual({
      message: 'Rate limit',
      status: 429,
@@ -403,7 +403,7 @@ export function mapError(
  }

  if (isStructuredError(error)) {
-    const structuredMeta = { ...meta, rawError: error };
+    const structuredMeta = { ...meta, rawError: error, status: error.status };
    return {
      status: mapHttpToGrpcStatus(error.status),
      message: error.message,
@@ -10,13 +10,16 @@ import { LegacyAgentSession } from './legacy-agent-session.js';
 import type { LegacyAgentSessionDeps } from './legacy-agent-session.js';
 import { GeminiEventType } from '../core/turn.js';
 import type { ServerGeminiStreamEvent } from '../core/turn.js';
-import type { AgentEvent } from './types.js';
+import type { AgentEvent, AgentSend } from './types.js';
 import { ToolErrorType } from '../tools/tool-error.js';
 import type {
  CompletedToolCall,
  ToolCallRequestInfo,
 } from '../scheduler/types.js';
 import { CoreToolCallStatus } from '../scheduler/types.js';
+import type { GeminiClient } from '../core/client.js';
+import type { Scheduler } from '../scheduler/scheduler.js';
+import type { Config } from '../config/config.js';

 // ---------------------------------------------------------------------------
 // Mock helpers
@@ -24,7 +27,7 @@ import { CoreToolCallStatus } from '../scheduler/types.js';

 function createMockDeps(
  overrides?: Partial<LegacyAgentSessionDeps>,
-): LegacyAgentSessionDeps {
+): Required<LegacyAgentSessionDeps> {
  const mockClient = {
    sendMessageStream: vi.fn(),
    getChat: vi.fn().mockReturnValue({
@@ -40,18 +43,22 @@ function createMockDeps(
  const mockConfig = {
    getMaxSessionTurns: vi.fn().mockReturnValue(-1),
    getModel: vi.fn().mockReturnValue('gemini-2.5-pro'),
+    getGeminiClient: vi.fn().mockReturnValue(mockClient),
+    getMessageBus: vi.fn().mockImplementation(() => ({
+      subscribe: vi.fn(),
+      unsubscribe: vi.fn(),
+    })),
  };

  return {
-    client: mockClient as unknown as LegacyAgentSessionDeps['client'],
-
-    scheduler: mockScheduler as unknown as LegacyAgentSessionDeps['scheduler'],
-
-    config: mockConfig as unknown as LegacyAgentSessionDeps['config'],
+    client: mockClient as unknown as GeminiClient,
+    scheduler: mockScheduler as unknown as Scheduler,
+    config: mockConfig as unknown as Config,
    promptId: 'test-prompt',
    streamId: 'test-stream',
+    getPreferredEditor: vi.fn().mockReturnValue(undefined),
    ...overrides,
-  };
+  } as Required<LegacyAgentSessionDeps>;
 }

 async function* makeStream(
@@ -72,6 +79,18 @@ function makeToolRequest(callId: string, name: string): ToolCallRequestInfo {
  };
 }

+function makeMessageSend(
+  text: string,
+  displayContent?: string,
+): Extract<AgentSend, { message: unknown }> {
+  return {
+    message: {
+      content: [{ type: 'text', text }],
+      ...(displayContent ? { displayContent } : {}),
+    },
+  };
+}
+
 function makeCompletedToolCall(
  callId: string,
  name: string,
@@ -117,7 +136,7 @@ async function collectEvents(
 // ---------------------------------------------------------------------------

 describe('LegacyAgentSession', () => {
-  let deps: LegacyAgentSessionDeps;
+  let deps: Required<LegacyAgentSessionDeps>;

  beforeEach(() => {
    deps = createMockDeps();
@@ -140,9 +159,7 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      const result = await session.send({
-        message: [{ type: 'text', text: 'hi' }],
-      });
+      const result = await session.send(makeMessageSend('hi'));

      expect(result.streamId).toBe('test-stream');
    });
@@ -162,7 +179,10 @@ describe('LegacyAgentSession', () => {

      const session = new LegacyAgentSession(deps);
      const { streamId } = await session.send({
-        message: [{ type: 'text', text: 'hi' }],
+        message: {
+          content: [{ type: 'text', text: 'hi' }],
+          displayContent: 'raw input',
+        },
        _meta: { source: 'user-test' },
      });

@@ -170,8 +190,19 @@ describe('LegacyAgentSession', () => {
        (e): e is AgentEvent<'message'> =>
          e.type === 'message' && e.role === 'user' && e.streamId === streamId,
      );
-      expect(userMessage?.content).toEqual([{ type: 'text', text: 'hi' }]);
+      expect(userMessage?.content).toEqual([
+        { type: 'text', text: 'raw input' },
+      ]);
      expect(userMessage?._meta).toEqual({ source: 'user-test' });
+      await vi.advanceTimersByTimeAsync(0);
+      expect(sendMock).toHaveBeenCalledWith(
+        [{ text: 'hi' }],
+        expect.any(AbortSignal),
+        'test-prompt',
+        undefined,
+        false,
+        'raw input',
+      );

      await collectEvents(session, { streamId: streamId ?? undefined });
    });
@@ -195,9 +226,7 @@ describe('LegacyAgentSession', () => {
        liveEvents.push(event);
      });

-      const { streamId } = await session.send({
-        message: [{ type: 'text', text: 'hi' }],
-      });
+      const { streamId } = await session.send(makeMessageSend('hi'));

      expect(streamId).toBe('test-stream');
      expect(liveEvents.some((event) => event.type === 'agent_start')).toBe(
@@ -235,14 +264,12 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      const { streamId } = await session.send({
-        message: [{ type: 'text', text: 'first' }],
-      });
+      const { streamId } = await session.send(makeMessageSend('first'));
      await vi.advanceTimersByTimeAsync(0);

-      await expect(
-        session.send({ message: [{ type: 'text', text: 'second' }] }),
-      ).rejects.toThrow('cannot be called while a stream is active');
+      await expect(session.send(makeMessageSend('second'))).rejects.toThrow(
+        'cannot be called while a stream is active',
+      );

      resolveHang?.();
      await collectEvents(session, { streamId: streamId ?? undefined });
@@ -273,16 +300,12 @@ describe('LegacyAgentSession', () => {
        );

      const session = new LegacyAgentSession(deps);
-      const first = await session.send({
-        message: [{ type: 'text', text: 'first' }],
-      });
+      const first = await session.send(makeMessageSend('first'));
      const firstEvents = await collectEvents(session, {
        streamId: first.streamId ?? undefined,
      });

-      const second = await session.send({
-        message: [{ type: 'text', text: 'second' }],
-      });
+      const second = await session.send(makeMessageSend('second'));
      const secondEvents = await collectEvents(session, {
        streamId: second.streamId ?? undefined,
      });
@@ -330,7 +353,7 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      const events = await collectEvents(session);

      const types = events.map((e) => e.type);
@@ -387,7 +410,7 @@ describe('LegacyAgentSession', () => {
      ]);

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'read a file' }] });
+      await session.send(makeMessageSend('read a file'));
      const events = await collectEvents(session);

      const types = events.map((e) => e.type);
@@ -455,9 +478,7 @@ describe('LegacyAgentSession', () => {
      scheduleMock.mockResolvedValueOnce([errorToolCall]);

      const session = new LegacyAgentSession(deps);
-      await session.send({
-        message: [{ type: 'text', text: 'write file' }],
-      });
+      await session.send(makeMessageSend('write file'));
      const events = await collectEvents(session);

      const toolResp = events.find(
@@ -506,9 +527,7 @@ describe('LegacyAgentSession', () => {
      scheduleMock.mockResolvedValueOnce([stopToolCall]);

      const session = new LegacyAgentSession(deps);
-      await session.send({
-        message: [{ type: 'text', text: 'do something' }],
-      });
+      await session.send(makeMessageSend('do something'));
      const events = await collectEvents(session);

      const streamEnd = events.find(
@@ -552,9 +571,7 @@ describe('LegacyAgentSession', () => {
      scheduleMock.mockResolvedValueOnce([fatalToolCall]);

      const session = new LegacyAgentSession(deps);
-      await session.send({
-        message: [{ type: 'text', text: 'write file' }],
-      });
+      await session.send(makeMessageSend('write file'));
      const events = await collectEvents(session);

      const toolResp = events.find(
@@ -592,7 +609,7 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      const events = await collectEvents(session);

      const streamEnd = events.find(
@@ -621,7 +638,7 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      const events = await collectEvents(session);

      const blocked = events.find(
@@ -663,7 +680,7 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      const events = await collectEvents(session);

      const err = events.find(
@@ -690,7 +707,7 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      const events = await collectEvents(session);

      const warning = events.find(
@@ -738,7 +755,7 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      const events = await collectEvents(session);

      const streamEnd = events.find(
@@ -762,7 +779,7 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      const events = await collectEvents(session);

      const errorEvents = events.filter(
@@ -799,9 +816,7 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      const { streamId } = await session.send({
-        message: [{ type: 'text', text: 'hi' }],
-      });
+      const { streamId } = await session.send(makeMessageSend('hi'));
      await vi.advanceTimersByTimeAsync(0);

      await session.abort();
@@ -847,7 +862,7 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));

      // Give the loop time to start processing
      await new Promise((r) => setTimeout(r, 50));
@@ -891,9 +906,7 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      const { streamId } = await session.send({
-        message: [{ type: 'text', text: 'hi' }],
-      });
+      const { streamId } = await session.send(makeMessageSend('hi'));

      await new Promise((resolve) => setTimeout(resolve, 25));
      await session.abort();
@@ -935,7 +948,7 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      await collectEvents(session);

      expect(session.events.length).toBeGreaterThan(0);
@@ -964,9 +977,7 @@ describe('LegacyAgentSession', () => {
        liveEvents.push(event);
      });

-      const { streamId } = await session.send({
-        message: [{ type: 'text', text: 'hi' }],
-      });
+      const { streamId } = await session.send(makeMessageSend('hi'));
      await collectEvents(session, { streamId: streamId ?? undefined });
      unsubscribe();

@@ -1002,9 +1013,7 @@ describe('LegacyAgentSession', () => {
        );

      const session = new LegacyAgentSession(deps);
-      const first = await session.send({
-        message: [{ type: 'text', text: 'first request' }],
-      });
+      const first = await session.send(makeMessageSend('first request'));
      await collectEvents(session, { streamId: first.streamId ?? undefined });

      const liveEvents: AgentEvent[] = [];
@@ -1012,9 +1021,7 @@ describe('LegacyAgentSession', () => {
        liveEvents.push(event);
      });

-      const second = await session.send({
-        message: [{ type: 'text', text: 'second request' }],
-      });
+      const second = await session.send(makeMessageSend('second request'));
      await collectEvents(session, { streamId: second.streamId ?? undefined });
      unsubscribe();

@@ -1058,14 +1065,10 @@ describe('LegacyAgentSession', () => {
        );

      const session = new LegacyAgentSession(deps);
-      const first = await session.send({
-        message: [{ type: 'text', text: 'first request' }],
-      });
+      const first = await session.send(makeMessageSend('first request'));
      await collectEvents(session, { streamId: first.streamId ?? undefined });

-      const second = await session.send({
-        message: [{ type: 'text', text: 'second request' }],
-      });
+      const second = await session.send(makeMessageSend('second request'));
      await collectEvents(session, { streamId: second.streamId ?? undefined });

      const firstStreamEvents = await collectEvents(session, {
@@ -1120,14 +1123,10 @@ describe('LegacyAgentSession', () => {
        );

      const session = new LegacyAgentSession(deps);
-      const first = await session.send({
-        message: [{ type: 'text', text: 'first request' }],
-      });
+      const first = await session.send(makeMessageSend('first request'));
      await collectEvents(session, { streamId: first.streamId ?? undefined });

-      await session.send({
-        message: [{ type: 'text', text: 'second request' }],
-      });
+      await session.send(makeMessageSend('second request'));
      await collectEvents(session);

      const firstAgentMessage = session.events.find(
@@ -1175,7 +1174,7 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      const events = await collectEvents(session);

      expect(events.length).toBeGreaterThan(0);
@@ -1196,7 +1195,7 @@ describe('LegacyAgentSession', () => {
      );

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      const events = await collectEvents(session);

      expect(events[events.length - 1]?.type).toBe('agent_end');
@@ -1244,7 +1243,7 @@ describe('LegacyAgentSession', () => {
      ]);

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'do it' }] });
+      await session.send(makeMessageSend('do it'));
      const events = await collectEvents(session);

      // Only one agent_end at the very end
@@ -1291,7 +1290,7 @@ describe('LegacyAgentSession', () => {
      ]);

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'go' }] });
+      await session.send(makeMessageSend('go'));
      const events = await collectEvents(session);

      // Should have at least one usage event from the intermediate Finished
@@ -1314,7 +1313,7 @@ describe('LegacyAgentSession', () => {
      });

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      const events = await collectEvents(session);

      const err = events.find(
@@ -1342,7 +1341,7 @@ describe('LegacyAgentSession', () => {
      });

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      const events = await collectEvents(session);

      const err = events.find(
@@ -1365,7 +1364,7 @@ describe('LegacyAgentSession', () => {
      });

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      const events = await collectEvents(session);

      const err = events.find(
@@ -1385,7 +1384,7 @@ describe('LegacyAgentSession', () => {
      });

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      const events = await collectEvents(session);

      const err = events.find(
@@ -1405,7 +1404,7 @@ describe('LegacyAgentSession', () => {
      });

      const session = new LegacyAgentSession(deps);
-      await session.send({ message: [{ type: 'text', text: 'hi' }] });
+      await session.send(makeMessageSend('hi'));
      const events = await collectEvents(session);

      const err = events.find(
@@ -14,10 +14,11 @@ import type { Part } from '@google/genai';
 import type { GeminiClient } from '../core/client.js';
 import type { Config } from '../config/config.js';
 import type { ToolCallRequestInfo } from '../scheduler/types.js';
-import type { Scheduler } from '../scheduler/scheduler.js';
+import { Scheduler } from '../scheduler/scheduler.js';
 import { recordToolCallInteractions } from '../code_assist/telemetry.js';
 import { ToolErrorType, isFatalToolError } from '../tools/tool-error.js';
 import { debugLogger } from '../utils/debugLogger.js';
+import type { EditorType } from '../utils/editor.js';
 import {
  buildToolResponseData,
  contentPartsToGeminiParts,
@@ -45,14 +46,15 @@ function isAbortLikeError(err: unknown): boolean {
 }

 export interface LegacyAgentSessionDeps {
-  client: GeminiClient;
-  scheduler: Scheduler;
  config: Config;
-  promptId: string;
+  client?: GeminiClient;
+  scheduler?: Scheduler;
+  promptId?: string;
  streamId?: string;
+  getPreferredEditor?: () => EditorType | undefined;
 }

-class LegacyAgentProtocol implements AgentProtocol {
+export class LegacyAgentProtocol implements AgentProtocol {
  private _events: AgentEvent[] = [];
  private _subscribers = new Set<(event: AgentEvent) => void>();
  private _translationState: TranslationState;
@@ -69,10 +71,16 @@ class LegacyAgentProtocol implements AgentProtocol {
  constructor(deps: LegacyAgentSessionDeps) {
    this._translationState = createTranslationState(deps.streamId);
    this._nextStreamIdOverride = deps.streamId;
-    this._client = deps.client;
-    this._scheduler = deps.scheduler;
    this._config = deps.config;
-    this._promptId = deps.promptId;
+    this._client = deps.client ?? deps.config.getGeminiClient();
+    this._promptId = deps.promptId ?? deps.config.promptId ?? '';
+    this._scheduler =
+      deps.scheduler ??
+      new Scheduler({
+        context: deps.config,
+        schedulerId: 'legacy-agent-scheduler',
+        getPreferredEditor: deps.getPreferredEditor ?? (() => undefined),
+      });
  }

  get events(): readonly AgentEvent[] {
@@ -105,12 +113,16 @@ class LegacyAgentProtocol implements AgentProtocol {

    this._beginNewStream();
    const streamId = this._translationState.streamId;
-    const parts = contentPartsToGeminiParts(message);
-    const userMessage = this._makeUserMessageEvent(message, payload._meta);
+    const parts = contentPartsToGeminiParts(message.content);
+    const userMessage = this._makeUserMessageEvent(
+      message.content,
+      message.displayContent,
+      payload._meta,
+    );

    this._emit([userMessage]);

-    this._scheduleRunLoop(parts);
+    this._scheduleRunLoop(parts, message.displayContent);

    return { streamId };
  }
@@ -119,18 +131,24 @@ class LegacyAgentProtocol implements AgentProtocol {
    this._abortController.abort();
  }

-  private _scheduleRunLoop(initialParts: Part[]): void {
+  private _scheduleRunLoop(
+    initialParts: Part[],
+    displayContent?: string,
+  ): void {
    // Use a macrotask so send() resolves with the streamId before agent_start
    // is emitted and consumers can attach to the stream without racing startup.
    setTimeout(() => {
-      void this._runLoopInBackground(initialParts);
+      void this._runLoopInBackground(initialParts, displayContent);
    }, 0);
  }

-  private async _runLoopInBackground(initialParts: Part[]): Promise<void> {
+  private async _runLoopInBackground(
+    initialParts: Part[],
+    displayContent?: string,
+  ): Promise<void> {
    this._ensureAgentStart();
    try {
-      await this._runLoop(initialParts);
+      await this._runLoop(initialParts, displayContent);
    } catch (err: unknown) {
      if (this._abortController.signal.aborted || isAbortLikeError(err)) {
        this._ensureAgentEnd('aborted');
@@ -141,8 +159,12 @@ class LegacyAgentProtocol implements AgentProtocol {
    }
  }

-  private async _runLoop(initialParts: Part[]): Promise<void> {
+  private async _runLoop(
+    initialParts: Part[],
+    initialDisplayContent?: string,
+  ): Promise<void> {
    let currentParts: Part[] = initialParts;
+    let currentDisplayContent = initialDisplayContent;
    let turnCount = 0;
    const maxTurns = this._config.getMaxSessionTurns();

@@ -162,7 +184,11 @@ class LegacyAgentProtocol implements AgentProtocol {
        currentParts,
        this._abortController.signal,
        this._promptId,
+        undefined,
+        false,
+        currentDisplayContent,
      );
+      currentDisplayContent = undefined;

      for await (const event of responseStream) {
        if (this._abortController.signal.aborted) {
@@ -383,13 +409,17 @@ class LegacyAgentProtocol implements AgentProtocol {

  private _makeUserMessageEvent(
    content: ContentPart[],
+    displayContent?: string,
    meta?: Record<string, unknown>,
  ): AgentEvent<'message'> {
+    const eventContent: ContentPart[] = displayContent
+      ? [{ type: 'text', text: displayContent }]
+      : content;
    const event = {
      ...this._nextEventFields(),
      type: 'message',
      role: 'user',
-      content,
+      content: eventContent,
      ...(meta ? { _meta: meta } : {}),
    } satisfies AgentEvent<'message'>;
    return event;
@@ -34,7 +34,7 @@ describe('MockAgentProtocol', () => {
    const streamPromise = waitForStreamEnd(session);

    const { streamId } = await session.send({
-      message: [{ type: 'text', text: 'hi' }],
+      message: { content: [{ type: 'text', text: 'hi' }] },
    });
    expect(streamId).toBeDefined();

@@ -10,6 +10,7 @@ import type {
  AgentEventData,
  AgentProtocol,
  AgentSend,
+  ContentPart,
  Unsubscribe,
 } from './types.js';

@@ -133,11 +134,17 @@ export class MockAgentProtocol implements AgentProtocol {

    // 1. User/Update event (BEFORE agent_start)
    if ('message' in payload && payload.message) {
+      const message = Array.isArray(payload.message)
+        ? { content: payload.message, displayContent: undefined }
+        : payload.message;
+      const userContent: ContentPart[] = message.displayContent
+        ? [{ type: 'text', text: message.displayContent }]
+        : message.content;
      eventsToEmit.push(
        normalize({
          type: 'message',
          role: 'user',
-          content: payload.message,
+          content: userContent,
          _meta: payload._meta,
        }),
      );
@@ -4,6 +4,8 @@
 * SPDX-License-Identifier: Apache-2.0
 */

+import type { Kind } from '../tools/tools.js';
+
 export type WithMeta = { _meta?: Record<string, unknown> };

 export type Unsubscribe = () => void;
@@ -46,7 +48,10 @@ type RequireExactlyOne<T> = {
 }[keyof T];

 interface AgentSendPayloads {
-  message: ContentPart[];
+  message: {
+    content: ContentPart[];
+    displayContent?: string;
+  };
  elicitations: ElicitationResponse[];
  update: { title?: string; model?: string; config?: Record<string, unknown> };
  action: { type: string; data: unknown };
@@ -177,6 +182,16 @@ export interface ToolRequest {
  name: string;
  /** The arguments for the tool. */
  args: Record<string, unknown>;
+  /** UI specific metadata */
+  _meta?: {
+    legacyState?: {
+      displayName?: string;
+      isOutputMarkdown?: boolean;
+      description?: string;
+      kind?: Kind;
+    };
+    [key: string]: unknown;
+  };
 }

 /**
@@ -189,6 +204,18 @@ export interface ToolUpdate {
  displayContent?: ContentPart[];
  content?: ContentPart[];
  data?: Record<string, unknown>;
+  /** UI specific metadata */
+  _meta?: {
+    legacyState?: {
+      status?: string;
+      progressMessage?: string;
+      progress?: number;
+      progressTotal?: number;
+      pid?: number;
+      description?: string;
+    };
+    [key: string]: unknown;
+  };
 }

 export interface ToolResponse {
@@ -202,6 +229,13 @@ export interface ToolResponse {
  data?: Record<string, unknown>;
  /** When true, the tool call encountered an error that will be sent to the model. */
  isError?: boolean;
+  /** UI specific metadata */
+  _meta?: {
+    legacyState?: {
+      outputFile?: string;
+    };
+    [key: string]: unknown;
+  };
 }

 export type ElicitationRequest = {
@@ -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;
    }
  }
@@ -36,7 +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, TopicState } from '../tools/topicTool.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';
@@ -641,6 +642,7 @@ export interface ConfigParameters {
  useAlternateBuffer?: boolean;
  useRipgrep?: boolean;
  enableInteractiveShell?: boolean;
+  shellBackgroundCompletionBehavior?: string;
  skipNextSpeakerCheck?: boolean;
  shellExecutionConfig?: ShellExecutionConfig;
  extensionManagement?: boolean;
@@ -682,6 +684,7 @@ export interface ConfigParameters {
  adminSkillsEnabled?: boolean;
  experimentalJitContext?: boolean;
  experimentalMemoryManager?: boolean;
+  useAgentProtocol?: boolean;
  experimentalAgentHistoryTruncation?: boolean;
  experimentalAgentHistoryTruncationThreshold?: number;
  experimentalAgentHistoryRetainedMessages?: number;
@@ -845,6 +848,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;
@@ -916,6 +923,7 @@ export class Config implements McpContext, AgentLoopContext {

  private readonly experimentalJitContext: boolean;
  private readonly experimentalMemoryManager: boolean;
+  private readonly useAgentProtocol: boolean;
  private readonly experimentalAgentHistoryTruncation: boolean;
  private readonly experimentalAgentHistoryTruncationThreshold: number;
  private readonly experimentalAgentHistoryRetainedMessages: number;
@@ -1130,6 +1138,7 @@ export class Config implements McpContext, AgentLoopContext {

    this.experimentalJitContext = params.experimentalJitContext ?? true;
    this.experimentalMemoryManager = params.experimentalMemoryManager ?? false;
+    this.useAgentProtocol = params.useAgentProtocol ?? false;
    this.experimentalAgentHistoryTruncation =
      params.experimentalAgentHistoryTruncation ?? false;
    this.experimentalAgentHistoryTruncationThreshold =
@@ -1183,6 +1192,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,
@@ -1192,6 +1209,7 @@ export class Config implements McpContext, AgentLoopContext {
      sanitizationConfig: this.sanitizationConfig,
      sandboxManager: this._sandboxManager,
      sandboxConfig: this.sandbox,
+      backgroundCompletionBehavior: this.shellBackgroundCompletionBehavior,
    };
    this.truncateToolOutputThreshold =
      params.truncateToolOutputThreshold ??
@@ -2323,6 +2341,12 @@ export class Config implements McpContext, AgentLoopContext {
    return this.experimentalMemoryManager;
  }

+  getExperimentalUseAgentProtocol(): boolean {
+    return (
+      this.useAgentProtocol ||
+      process.env['GEMINI_CLI_USE_AGENT_PROTOCOL'] === 'true'
+    );
+  }
  isExperimentalAgentHistoryTruncationEnabled(): boolean {
    return this.experimentalAgentHistoryTruncation;
  }
@@ -3166,6 +3190,10 @@ export class Config implements McpContext, AgentLoopContext {
    return this.enableInteractiveShell;
  }

+  getShellBackgroundCompletionBehavior(): 'inject' | 'notify' | 'silent' {
+    return this.shellBackgroundCompletionBehavior;
+  }
+
  getSkipNextSpeakerCheck(): boolean {
    return this.skipNextSpeakerCheck;
  }
@@ -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;
+  }
+}
@@ -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';
@@ -6,6 +6,7 @@

 import stripAnsi from 'strip-ansi';
 import type { SessionMetrics } from '../telemetry/uiTelemetry.js';
+import { getErrorType } from '../utils/errors.js';
 import type { JsonError, JsonOutput } from './types.js';

 export class JsonFormatter {
@@ -42,7 +43,7 @@ export class JsonFormatter {
    sessionId?: string,
  ): string {
    const jsonError: JsonError = {
-      type: error.constructor.name,
+      type: getErrorType(error),
      message: stripAnsi(error.message),
      ...(code && { code }),
    };
@@ -16,7 +16,7 @@ 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 '../tools/topicTool.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';
@@ -233,7 +233,6 @@ Use the following guidelines to optimize your search and read patterns.
 - **Types, warnings and linters:** NEVER use hacks like disabling or suppressing warnings or bypassing the type system (i.e.: casts in TypeScript) unless explicitly instructed to by the user. Instead, use idiomatic language features (e.g.: type guard functions).
 - **Libraries/Frameworks:** NEVER assume a library/framework is available. Verify its established usage within the project (check imports, configuration files like 'package.json', 'Cargo.toml', 'requirements.txt', etc.) before employing it.
 - **Technical Integrity:** You are responsible for the entire lifecycle: implementation, testing, and validation. Within the scope of your changes, prioritize readability and long-term maintainability by consolidating logic into clean abstractions rather than threading state across unrelated layers. Align strictly with the requested architectural direction, ensuring the final implementation is focused and free of redundant "just-in-case" alternatives. Validation is not merely running tests; it is the exhaustive process of ensuring that every aspect of your change—behavioral, structural, and stylistic—is correct and fully compatible with the broader project. For bug fixes, you must empirically reproduce the failure with a new test case or reproduction script before applying the fix.
- **Multi-line File Creation:** ALWAYS use the ${formatToolName(WRITE_FILE_TOOL_NAME)} tool for creating or overwriting files with multiple lines of content. DO NOT use ${formatToolName(SHELL_TOOL_NAME)} with \`cat << 'EOF'\` or similar heredoc patterns, as they are prone to shell parsing errors and internal buffer limits.
 - **Expertise & Intent Alignment:** Provide proactive technical opinions grounded in research while strictly adhering to the user's intended workflow. Distinguish between **Directives** (unambiguous requests for action or implementation) and **Inquiries** (requests for analysis, advice, or observations). Assume all requests are Inquiries unless they contain an explicit instruction to perform a task. For Inquiries, your scope is strictly limited to research and analysis; you may propose a solution or strategy, but you MUST NOT modify files until a corresponding Directive is issued. Do not initiate implementation based on observations of bugs or statements of fact. Once an Inquiry is resolved, or while waiting for a Directive, stop and wait for the next user instruction. ${options.interactive ? 'For Directives, only clarify if critically underspecified; otherwise, work autonomously.' : 'For Directives, you must work autonomously as no further user input is available.'} You should only seek user intervention if you have exhausted all possible routes or if a proposed solution would take the workspace in a significantly different architectural direction.
 - **Proactiveness:** When executing a Directive, persist through errors and obstacles by diagnosing failures in the execution phase and, if necessary, backtracking to the research or strategy phases to adjust your approach until a successful, verified outcome is achieved. Fulfill the user's request thoroughly, including adding tests when adding features or fixing bugs. Take reasonable liberties to fulfill broad goals while staying within the requested scope; however, prioritize simplicity and the removal of redundant logic over providing "just-in-case" alternatives that diverge from the established path.
 - **Testing:** ALWAYS search for and update related tests after making a code change. You must add a new test case to the existing test file (if one exists) or create a new test file to verify your changes.${mandateConflictResolution(options.hasHierarchicalMemory)}
@@ -10,6 +10,7 @@ import {
  type ExecutionHandle,
  type ExecutionResult,
 } from './executionLifecycleService.js';
+import { InjectionService } from '../config/injectionService.js';

 function createResult(
  overrides: Partial<ExecutionResult> = {},
@@ -296,6 +297,81 @@ describe('ExecutionLifecycleService', () => {
    }).toThrow('Execution 4324 is already attached.');
  });

+  describe('Background Start Listeners', () => {
+    it('fires onBackground when an execution is backgrounded', async () => {
+      const listener = vi.fn();
+      ExecutionLifecycleService.onBackground(listener);
+
+      const handle = ExecutionLifecycleService.createExecution(
+        '',
+        undefined,
+        'remote_agent',
+        undefined,
+        'My Remote Agent',
+      );
+      const executionId = handle.pid!;
+
+      ExecutionLifecycleService.appendOutput(executionId, 'some output');
+      ExecutionLifecycleService.background(executionId);
+      await handle.result;
+
+      expect(listener).toHaveBeenCalledTimes(1);
+      const info = listener.mock.calls[0][0];
+      expect(info.executionId).toBe(executionId);
+      expect(info.executionMethod).toBe('remote_agent');
+      expect(info.label).toBe('My Remote Agent');
+      expect(info.output).toBe('some output');
+
+      ExecutionLifecycleService.offBackground(listener);
+    });
+
+    it('uses fallback label when none is provided', async () => {
+      const listener = vi.fn();
+      ExecutionLifecycleService.onBackground(listener);
+
+      const handle = ExecutionLifecycleService.createExecution(
+        '',
+        undefined,
+        'none',
+      );
+      const executionId = handle.pid!;
+
+      ExecutionLifecycleService.background(executionId);
+      await handle.result;
+
+      const info = listener.mock.calls[0][0];
+      expect(info.label).toContain('none');
+      expect(info.label).toContain(String(executionId));
+
+      ExecutionLifecycleService.offBackground(listener);
+    });
+
+    it('does not fire onBackground for non-backgrounded completions', async () => {
+      const listener = vi.fn();
+      ExecutionLifecycleService.onBackground(listener);
+
+      const handle = ExecutionLifecycleService.createExecution();
+      ExecutionLifecycleService.completeExecution(handle.pid!);
+      await handle.result;
+
+      expect(listener).not.toHaveBeenCalled();
+
+      ExecutionLifecycleService.offBackground(listener);
+    });
+
+    it('offBackground removes the listener', async () => {
+      const listener = vi.fn();
+      ExecutionLifecycleService.onBackground(listener);
+      ExecutionLifecycleService.offBackground(listener);
+
+      const handle = ExecutionLifecycleService.createExecution();
+      ExecutionLifecycleService.background(handle.pid!);
+      await handle.result;
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
  describe('Background Completion Listeners', () => {
    it('fires onBackgroundComplete with formatInjection text when backgrounded execution settles', async () => {
      const listener = vi.fn();
@@ -326,7 +402,10 @@ describe('ExecutionLifecycleService', () => {
      expect(info.executionMethod).toBe('remote_agent');
      expect(info.output).toBe('agent output');
      expect(info.error).toBeNull();
-      expect(info.injectionText).toBe('[Agent completed]\nagent output');
+      expect(info.injectionText).toBe(
+        '<output>\n[Agent completed]\nagent output\n</output>',
+      );
+      expect(info.completionBehavior).toBe('inject');

      ExecutionLifecycleService.offBackgroundComplete(listener);
    });
@@ -353,12 +432,14 @@ describe('ExecutionLifecycleService', () => {
      expect(listener).toHaveBeenCalledTimes(1);
      const info = listener.mock.calls[0][0];
      expect(info.error?.message).toBe('something broke');
-      expect(info.injectionText).toBe('Error: something broke');
+      expect(info.injectionText).toBe(
+        '<output>\nError: something broke\n</output>',
+      );

      ExecutionLifecycleService.offBackgroundComplete(listener);
    });

-    it('sets injectionText to null when no formatInjection callback is provided', async () => {
+    it('sets injectionText to null and completionBehavior to silent when no formatInjection is provided', async () => {
      const listener = vi.fn();
      ExecutionLifecycleService.onBackgroundComplete(listener);

@@ -377,6 +458,7 @@ describe('ExecutionLifecycleService', () => {

      expect(listener).toHaveBeenCalledTimes(1);
      expect(listener.mock.calls[0][0].injectionText).toBeNull();
+      expect(listener.mock.calls[0][0].completionBehavior).toBe('silent');

      ExecutionLifecycleService.offBackgroundComplete(listener);
    });
@@ -443,5 +525,214 @@ describe('ExecutionLifecycleService', () => {

      expect(listener).not.toHaveBeenCalled();
    });
+
+    it('explicit notify behavior includes injectionText and auto-dismiss signal', async () => {
+      const listener = vi.fn();
+      ExecutionLifecycleService.onBackgroundComplete(listener);
+
+      const handle = ExecutionLifecycleService.createExecution(
+        '',
+        undefined,
+        'child_process',
+        () => '[Command completed. Output saved to /tmp/bg.log]',
+        undefined,
+        'notify',
+      );
+      const executionId = handle.pid!;
+
+      ExecutionLifecycleService.background(executionId);
+      await handle.result;
+
+      ExecutionLifecycleService.completeExecution(executionId);
+
+      expect(listener).toHaveBeenCalledTimes(1);
+      const info = listener.mock.calls[0][0];
+      expect(info.completionBehavior).toBe('notify');
+      expect(info.injectionText).toBe(
+        '<output>\n[Command completed. Output saved to /tmp/bg.log]\n</output>',
+      );
+
+      ExecutionLifecycleService.offBackgroundComplete(listener);
+    });
+
+    it('explicit silent behavior skips injection even when formatInjection is provided', async () => {
+      const formatFn = vi.fn().mockReturnValue('should not appear');
+      const listener = vi.fn();
+      ExecutionLifecycleService.onBackgroundComplete(listener);
+
+      const handle = ExecutionLifecycleService.createExecution(
+        '',
+        undefined,
+        'none',
+        formatFn,
+        undefined,
+        'silent',
+      );
+      const executionId = handle.pid!;
+
+      ExecutionLifecycleService.background(executionId);
+      await handle.result;
+
+      ExecutionLifecycleService.completeExecution(executionId);
+
+      expect(listener).toHaveBeenCalledTimes(1);
+      const info = listener.mock.calls[0][0];
+      expect(info.completionBehavior).toBe('silent');
+      expect(info.injectionText).toBeNull();
+      expect(formatFn).not.toHaveBeenCalled();
+
+      ExecutionLifecycleService.offBackgroundComplete(listener);
+    });
+
+    it('includes completionBehavior in BackgroundStartInfo', async () => {
+      const bgStartListener = vi.fn();
+      ExecutionLifecycleService.onBackground(bgStartListener);
+
+      const handle = ExecutionLifecycleService.createExecution(
+        '',
+        undefined,
+        'remote_agent',
+        () => 'text',
+        'test-label',
+        'inject',
+      );
+
+      ExecutionLifecycleService.background(handle.pid!);
+      await handle.result;
+
+      expect(bgStartListener).toHaveBeenCalledTimes(1);
+      expect(bgStartListener.mock.calls[0][0].completionBehavior).toBe(
+        'inject',
+      );
+
+      ExecutionLifecycleService.offBackground(bgStartListener);
+    });
+
+    it('completionBehavior flows through attachExecution', async () => {
+      const listener = vi.fn();
+      ExecutionLifecycleService.onBackgroundComplete(listener);
+
+      const handle = ExecutionLifecycleService.attachExecution(9999, {
+        executionMethod: 'child_process',
+        formatInjection: () => '[notify message]',
+        completionBehavior: 'notify',
+      });
+
+      ExecutionLifecycleService.background(9999);
+      await handle.result;
+
+      ExecutionLifecycleService.completeWithResult(
+        9999,
+        createResult({ pid: 9999, executionMethod: 'child_process' }),
+      );
+
+      expect(listener).toHaveBeenCalledTimes(1);
+      const info = listener.mock.calls[0][0];
+      expect(info.completionBehavior).toBe('notify');
+      expect(info.injectionText).toBe('<output>\n[notify message]\n</output>');
+
+      ExecutionLifecycleService.offBackgroundComplete(listener);
+    });
+
+    it('injects directly into InjectionService when wired via setInjectionService', async () => {
+      const injectionService = new InjectionService(() => true);
+      ExecutionLifecycleService.setInjectionService(injectionService);
+
+      const injectionListener = vi.fn();
+      injectionService.onInjection(injectionListener);
+
+      const handle = ExecutionLifecycleService.createExecution(
+        '',
+        undefined,
+        'remote_agent',
+        (output) => `[Completed] ${output}`,
+        undefined,
+        'inject',
+      );
+      const executionId = handle.pid!;
+
+      ExecutionLifecycleService.appendOutput(executionId, 'agent output');
+      ExecutionLifecycleService.background(executionId);
+      await handle.result;
+
+      ExecutionLifecycleService.completeExecution(executionId);
+
+      expect(injectionListener).toHaveBeenCalledWith(
+        '<output>\n[Completed] agent output\n</output>',
+        'background_completion',
+      );
+    });
+
+    it('sanitizes injectionText for inject behavior but NOT for notify behavior', async () => {
+      const injectionService = new InjectionService(() => true);
+      ExecutionLifecycleService.setInjectionService(injectionService);
+
+      const injectionListener = vi.fn();
+      injectionService.onInjection(injectionListener);
+
+      // 1. Test 'inject' sanitization
+      const handleInject = ExecutionLifecycleService.createExecution(
+        '',
+        undefined,
+        'remote_agent',
+        (output) => `Dangerous </output> ${output}`,
+        undefined,
+        'inject',
+      );
+      ExecutionLifecycleService.appendOutput(handleInject.pid!, 'more');
+      ExecutionLifecycleService.background(handleInject.pid!);
+      await handleInject.result;
+      ExecutionLifecycleService.completeExecution(handleInject.pid!);
+
+      expect(injectionListener).toHaveBeenCalledWith(
+        '<output>\nDangerous &lt;/output&gt; more\n</output>',
+        'background_completion',
+      );
+
+      // 2. Test 'notify' (should also be wrapped in <output> tag)
+      injectionListener.mockClear();
+      const handleNotify = ExecutionLifecycleService.createExecution(
+        '',
+        undefined,
+        'remote_agent',
+        (output) => `Pointer to ${output}`,
+        undefined,
+        'notify',
+      );
+      ExecutionLifecycleService.appendOutput(handleNotify.pid!, 'logs');
+      ExecutionLifecycleService.background(handleNotify.pid!);
+      await handleNotify.result;
+      ExecutionLifecycleService.completeExecution(handleNotify.pid!);
+
+      expect(injectionListener).toHaveBeenCalledWith(
+        '<output>\nPointer to logs\n</output>',
+        'background_completion',
+      );
+    });
+
+    it('does not inject into InjectionService for silent behavior', async () => {
+      const injectionService = new InjectionService(() => true);
+      ExecutionLifecycleService.setInjectionService(injectionService);
+
+      const injectionListener = vi.fn();
+      injectionService.onInjection(injectionListener);
+
+      const handle = ExecutionLifecycleService.createExecution(
+        '',
+        undefined,
+        'none',
+        () => 'should not inject',
+        undefined,
+        'silent',
+      );
+      const executionId = handle.pid!;
+
+      ExecutionLifecycleService.background(executionId);
+      await handle.result;
+
+      ExecutionLifecycleService.completeExecution(executionId);
+
+      expect(injectionListener).not.toHaveBeenCalled();
+    });
  });
 });
@@ -7,6 +7,7 @@
 import type { InjectionService } from '../config/injectionService.js';
 import type { AnsiOutput } from '../utils/terminalSerializer.js';
 import { debugLogger } from '../utils/debugLogger.js';
+import { sanitizeOutput } from '../utils/textUtils.js';

 export type ExecutionMethod =
  | 'lydell-node-pty'
@@ -59,12 +60,16 @@ export interface ExecutionCompletionOptions {

 export interface ExternalExecutionRegistration {
  executionMethod: ExecutionMethod;
+  /** Human-readable label for the background task UI (e.g. the command string). */
+  label?: string;
  initialOutput?: string;
  getBackgroundOutput?: () => string;
  getSubscriptionSnapshot?: () => string | AnsiOutput | undefined;
  writeInput?: (input: string) => void;
  kill?: () => void;
  isActive?: () => boolean;
+  formatInjection?: FormatInjectionFn;
+  completionBehavior?: CompletionBehavior;
 }

 /**
@@ -77,15 +82,41 @@ export type FormatInjectionFn = (
  error: Error | null,
 ) => string | null;

+/**
+ * Controls what happens when a backgrounded execution completes:
+ * - `'inject'`  — full formatted output is injected into the conversation; task auto-dismisses from UI.
+ * - `'notify'`  — a short pointer (e.g. "output saved to /tmp/...") is injected; task auto-dismisses from UI.
+ * - `'silent'`  — nothing is injected; task stays in the UI until manually dismissed.
+ *
+ * The distinction between `inject` and `notify` is semantic for now (both inject + dismiss),
+ * but enables the system to treat them differently in the future (e.g. LLM-decided injection).
+ */
+export type CompletionBehavior = 'inject' | 'notify' | 'silent';
+
 interface ManagedExecutionBase {
  executionMethod: ExecutionMethod;
+  label?: string;
  output: string;
  backgrounded?: boolean;
  formatInjection?: FormatInjectionFn;
+  completionBehavior?: CompletionBehavior;
  getBackgroundOutput?: () => string;
  getSubscriptionSnapshot?: () => string | AnsiOutput | undefined;
 }

+/**
+ * Payload emitted when an execution is moved to the background.
+ */
+export interface BackgroundStartInfo {
+  executionId: number;
+  executionMethod: ExecutionMethod;
+  label: string;
+  output: string;
+  completionBehavior: CompletionBehavior;
+}
+
+export type BackgroundStartListener = (info: BackgroundStartInfo) => void;
+
 /**
 * Payload emitted when a previously-backgrounded execution settles.
 */
@@ -96,6 +127,7 @@ export interface BackgroundCompletionInfo {
  error: Error | null;
  /** Pre-formatted injection text from the execution creator, or `null` if skipped. */
  injectionText: string | null;
+  completionBehavior: CompletionBehavior;
 }

 export type BackgroundCompletionListener = (
@@ -124,6 +156,16 @@ const NON_PROCESS_EXECUTION_ID_START = 2_000_000_000;
 export class ExecutionLifecycleService {
  private static readonly EXIT_INFO_TTL_MS = 5 * 60 * 1000;
  private static nextExecutionId = NON_PROCESS_EXECUTION_ID_START;
+  private static injectionService: InjectionService | null = null;
+
+  /**
+   * Connects the lifecycle service to the injection service so that
+   * backgrounded executions are reinjected into the model conversation
+   * directly from the backend — no UI hop needed.
+   */
+  static setInjectionService(service: InjectionService): void {
+    this.injectionService = service;
+  }

  private static activeExecutions = new Map<number, ManagedExecutionState>();
  private static activeResolvers = new Map<
@@ -140,14 +182,22 @@ export class ExecutionLifecycleService {
  >();
  private static backgroundCompletionListeners =
    new Set<BackgroundCompletionListener>();
-  private static injectionService: InjectionService | null = null;
+
+  private static backgroundStartListeners = new Set<BackgroundStartListener>();

  /**
-   * Wires a singleton InjectionService so that backgrounded executions
-   * can inject their output directly without routing through the UI layer.
+   * Registers a listener that fires when any execution is moved to the background.
+   * This is the hook for the UI to automatically discover backgrounded executions.
   */
-  static setInjectionService(service: InjectionService): void {
-    this.injectionService = service;
+  static onBackground(listener: BackgroundStartListener): void {
+    this.backgroundStartListeners.add(listener);
+  }
+
+  /**
+   * Unregisters a background start listener.
+   */
+  static offBackground(listener: BackgroundStartListener): void {
+    this.backgroundStartListeners.delete(listener);
  }

  /**
@@ -222,6 +272,7 @@ export class ExecutionLifecycleService {
    this.exitedExecutionInfo.clear();
    this.backgroundCompletionListeners.clear();
    this.injectionService = null;
+    this.backgroundStartListeners.clear();
    this.nextExecutionId = NON_PROCESS_EXECUTION_ID_START;
  }

@@ -239,6 +290,7 @@ export class ExecutionLifecycleService {

    this.activeExecutions.set(executionId, {
      executionMethod: registration.executionMethod,
+      label: registration.label,
      output: registration.initialOutput ?? '',
      kind: 'external',
      getBackgroundOutput: registration.getBackgroundOutput,
@@ -246,6 +298,8 @@ export class ExecutionLifecycleService {
      writeInput: registration.writeInput,
      kill: registration.kill,
      isActive: registration.isActive,
+      formatInjection: registration.formatInjection,
+      completionBehavior: registration.completionBehavior,
    });

    return {
@@ -259,15 +313,19 @@ export class ExecutionLifecycleService {
    onKill?: () => void,
    executionMethod: ExecutionMethod = 'none',
    formatInjection?: FormatInjectionFn,
+    label?: string,
+    completionBehavior?: CompletionBehavior,
  ): ExecutionHandle {
    const executionId = this.allocateExecutionId();

    this.activeExecutions.set(executionId, {
      executionMethod,
+      label,
      output: initialOutput,
      kind: 'virtual',
      onKill,
      formatInjection,
+      completionBehavior,
      getBackgroundOutput: () => {
        const state = this.activeExecutions.get(executionId);
        return state?.output ?? initialOutput;
@@ -325,19 +383,17 @@ export class ExecutionLifecycleService {

    // Fire background completion listeners if this was a backgrounded execution.
    if (execution.backgrounded && !result.aborted) {
-      const injectionText = execution.formatInjection
-        ? execution.formatInjection(result.output, result.error)
-        : null;
-      const info: BackgroundCompletionInfo = {
-        executionId,
-        executionMethod: execution.executionMethod,
-        output: result.output,
-        error: result.error,
-        injectionText,
-      };
+      const behavior =
+        execution.completionBehavior ??
+        (execution.formatInjection ? 'inject' : 'silent');
+      const rawInjection =
+        behavior !== 'silent' && execution.formatInjection
+          ? execution.formatInjection(result.output, result.error)
+          : null;

-      // Inject directly into the model conversation if injection text is
-      // available and the injection service has been wired up.
+      const injectionText = rawInjection ? sanitizeOutput(rawInjection) : null;
+
+      // Inject directly into the model conversation from the backend.
      if (injectionText && this.injectionService) {
        this.injectionService.addInjection(
          injectionText,
@@ -345,6 +401,15 @@ export class ExecutionLifecycleService {
        );
      }

+      const info: BackgroundCompletionInfo = {
+        executionId,
+        executionMethod: execution.executionMethod,
+        output: result.output,
+        error: result.error,
+        injectionText,
+        completionBehavior: behavior,
+      };
+
      for (const listener of this.backgroundCompletionListeners) {
        try {
          listener(info);
@@ -434,6 +499,21 @@ export class ExecutionLifecycleService {

    this.activeResolvers.delete(executionId);
    execution.backgrounded = true;
+
+    // Notify listeners that an execution was moved to the background.
+    const info: BackgroundStartInfo = {
+      executionId,
+      executionMethod: execution.executionMethod,
+      label:
+        execution.label ?? `${execution.executionMethod} (ID: ${executionId})`,
+      output,
+      completionBehavior:
+        execution.completionBehavior ??
+        (execution.formatInjection ? 'inject' : 'silent'),
+    };
+    for (const listener of this.backgroundStartListeners) {
+      listener(info);
+    }
  }

  static subscribe(
@@ -19,7 +19,7 @@ import {
  resolveExecutable,
  type ShellType,
 } from '../utils/shell-utils.js';
-import { isBinary } from '../utils/textUtils.js';
+import { isBinary, truncateString } from '../utils/textUtils.js';
 import pkg from '@xterm/headless';
 import { debugLogger } from '../utils/debugLogger.js';
 import { Storage } from '../config/storage.js';
@@ -102,6 +102,7 @@ export interface ShellExecutionConfig {
  scrollback?: number;
  maxSerializedLines?: number;
  sandboxConfig?: SandboxConfig;
+  backgroundCompletionBehavior?: 'inject' | 'notify' | 'silent';
 }

 /**
@@ -239,6 +240,23 @@ export class ShellExecutionService {
    return path.join(Storage.getGlobalTempDir(), 'background-processes');
  }

+  private static formatShellBackgroundCompletion(
+    pid: number,
+    behavior: string,
+    output: string,
+    error?: Error,
+  ): string {
+    const logPath = ShellExecutionService.getLogFilePath(pid);
+    const status = error ? `with error: ${error.message}` : 'successfully';
+
+    if (behavior === 'inject') {
+      const truncated = truncateString(output, 5000);
+      return `[Background command completed ${status}. Output saved to ${logPath}]\n\n${truncated}`;
+    }
+
+    return `[Background command completed ${status}. Output saved to ${logPath}]`;
+  }
+
  static getLogFilePath(pid: number): string {
    return path.join(this.getLogDir(), `background-${pid}.log`);
  }
@@ -532,6 +550,15 @@ export class ShellExecutionService {
                return false;
              }
            },
+            formatInjection: (output, error) =>
+              ShellExecutionService.formatShellBackgroundCompletion(
+                child.pid!,
+                shellExecutionConfig.backgroundCompletionBehavior || 'silent',
+                output,
+                error ?? undefined,
+              ),
+            completionBehavior:
+              shellExecutionConfig.backgroundCompletionBehavior || 'silent',
          })
        : undefined;

@@ -862,6 +889,15 @@ export class ShellExecutionService {
          );
          return bufferData.length > 0 ? bufferData : undefined;
        },
+        formatInjection: (output, error) =>
+          ShellExecutionService.formatShellBackgroundCompletion(
+            ptyPid,
+            shellExecutionConfig.backgroundCompletionBehavior || 'silent',
+            output,
+            error ?? undefined,
+          ),
+        completionBehavior:
+          shellExecutionConfig.backgroundCompletionBehavior || 'silent',
      }).result;

      let processingChain = Promise.resolve();
@@ -128,6 +128,7 @@ export const PARAM_ADDITIONAL_PERMISSIONS = 'additional_permissions';

 // -- update_topic --
 export const UPDATE_TOPIC_TOOL_NAME = 'update_topic';
+export const UPDATE_TOPIC_DISPLAY_NAME = 'Update Topic Context';
 export const TOPIC_PARAM_TITLE = 'title';
 export const TOPIC_PARAM_SUMMARY = 'summary';
 export const TOPIC_PARAM_STRATEGIC_INTENT = 'strategic_intent';
@@ -40,6 +40,7 @@ export {
  EXIT_PLAN_MODE_TOOL_NAME,
  ENTER_PLAN_MODE_TOOL_NAME,
  UPDATE_TOPIC_TOOL_NAME,
+  UPDATE_TOPIC_DISPLAY_NAME,
  // Shared parameter names
  PARAM_FILE_PATH,
  PARAM_DIR_PATH,
@@ -136,6 +136,7 @@ describe('ShellTool', () => {
      getGeminiClient: vi.fn().mockReturnValue({}),
      getShellToolInactivityTimeout: vi.fn().mockReturnValue(1000),
      getEnableInteractiveShell: vi.fn().mockReturnValue(false),
+      getShellBackgroundCompletionBehavior: vi.fn().mockReturnValue('silent'),
      getEnableShellOutputEfficiency: vi.fn().mockReturnValue(true),
      getSandboxEnabled: vi.fn().mockReturnValue(false),
      sanitizationConfig: {},
@@ -470,38 +471,6 @@ describe('ShellTool', () => {
      expect(result.error?.message).toBe('command failed');
    });

-    it('should include write_file suggestion when a command with a heredoc fails', async () => {
-      const invocation = shellTool.build({
-        command: "cat << 'EOF'\nhello\nEOF",
-      });
-      const promise = invocation.execute(mockAbortSignal);
-      resolveShellExecution({
-        exitCode: 1,
-        output: 'bash: syntax error',
-      });
-
-      const result = await promise;
-      expect(result.llmContent).toContain(
-        "Suggestion: Large heredoc detected. Please use the 'write_file' tool for better reliability.",
-      );
-    });
-
-    it('should NOT include write_file suggestion when a command with a heredoc succeeds', async () => {
-      const invocation = shellTool.build({
-        command: "cat << 'EOF'\nhello\nEOF",
-      });
-      const promise = invocation.execute(mockAbortSignal);
-      resolveShellExecution({
-        exitCode: 0,
-        output: 'hello',
-      });
-
-      const result = await promise;
-      expect(result.llmContent).not.toContain(
-        "Suggestion: Large heredoc detected. Please use the 'write_file' tool for better reliability.",
-      );
-    });
-
    it('should throw an error for invalid parameters', () => {
      expect(() => shellTool.build({ command: '' })).toThrow(
        'Command cannot be empty.',
@@ -51,8 +51,6 @@ import type { AgentLoopContext } from '../config/agent-loop-context.js';

 export const OUTPUT_UPDATE_INTERVAL_MS = 1000;

-const HEREDOC_REGEX = /<<[-]?\s*['"\\\]?EOF['"]?/;
-
 // Delay so user does not see the output of the process before the process is moved to the background.
 const BACKGROUND_DELAY_MS = 200;

@@ -359,6 +357,8 @@ export class ShellToolInvocation extends BaseToolInvocation<
              this.context.config.sanitizationConfig,
            sandboxManager: this.context.config.sandboxManager,
            additionalPermissions: this.params[PARAM_ADDITIONAL_PERMISSIONS],
+            backgroundCompletionBehavior:
+              this.context.config.getShellBackgroundCompletionBehavior(),
          },
        );

@@ -432,11 +432,6 @@ export class ShellToolInvocation extends BaseToolInvocation<
        } else {
          llmContent += ' There was no output before it was cancelled.';
        }
-
-        if (HEREDOC_REGEX.test(this.params.command)) {
-          llmContent +=
-            "\nSuggestion: Large heredoc detected. Please use the 'write_file' tool for better reliability.";
-        }
      } else if (this.params.is_background || result.backgrounded) {
        llmContent = `Command moved to background (PID: ${result.pid}). Output hidden. Press Ctrl+B to view.`;
        data = {
@@ -475,17 +470,6 @@ export class ShellToolInvocation extends BaseToolInvocation<
          llmContentParts.push(`Process Group PGID: ${result.pid}`);
        }

-        const failed =
-          !!result.error ||
-          !!result.signal ||
-          (result.exitCode !== null && result.exitCode !== 0);
-
-        if (failed && HEREDOC_REGEX.test(this.params.command)) {
-          llmContentParts.push(
-            "Suggestion: Large heredoc detected. Please use the 'write_file' tool for better reliability.",
-          );
-        }
-
        llmContent = llmContentParts.join('\n');
      }

@@ -76,6 +76,7 @@ import {
  EXIT_PLAN_PARAM_PLAN_FILENAME,
  SKILL_PARAM_NAME,
  UPDATE_TOPIC_TOOL_NAME,
+  UPDATE_TOPIC_DISPLAY_NAME,
  TOPIC_PARAM_TITLE,
  TOPIC_PARAM_SUMMARY,
  TOPIC_PARAM_STRATEGIC_INTENT,
@@ -100,6 +101,7 @@ export {
  EXIT_PLAN_MODE_TOOL_NAME,
  ENTER_PLAN_MODE_TOOL_NAME,
  UPDATE_TOPIC_TOOL_NAME,
+  UPDATE_TOPIC_DISPLAY_NAME,
  // Shared parameter names
  PARAM_FILE_PATH,
  PARAM_DIR_PATH,
@@ -5,7 +5,8 @@
 */

 import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { TopicState, UpdateTopicTool } from './topicTool.js';
+import { UpdateTopicTool } from './topicTool.js';
+import { TopicState } from '../config/topicState.js';
 import { MessageBus } from '../confirmation-bus/message-bus.js';
 import type { PolicyEngine } from '../policy/policy-engine.js';
 import {
@@ -6,6 +6,7 @@

 import {
  UPDATE_TOPIC_TOOL_NAME,
+  UPDATE_TOPIC_DISPLAY_NAME,
  TOPIC_PARAM_TITLE,
  TOPIC_PARAM_SUMMARY,
  TOPIC_PARAM_STRATEGIC_INTENT,
@@ -21,49 +22,6 @@ import { debugLogger } from '../utils/debugLogger.js';
 import { getUpdateTopicDeclaration } from './definitions/dynamic-declaration-helpers.js';
 import type { Config } from '../config/config.js';

-/**
- * 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;
-  }
-}
-
 interface UpdateTopicParams {
  [TOPIC_PARAM_TITLE]?: string;
  [TOPIC_PARAM_SUMMARY]?: string;
@@ -153,7 +111,7 @@ export class UpdateTopicTool extends BaseDeclarativeTool<
    const declaration = getUpdateTopicDeclaration();
    super(
      UPDATE_TOPIC_TOOL_NAME,
-      'Update Topic Context',
+      UPDATE_TOPIC_DISPLAY_NAME,
      declaration.description ?? '',
      Kind.Think,
      declaration.parametersJsonSchema,
@@ -133,3 +133,21 @@ export function safeTemplateReplace(
      : match,
  );
 }
+
+/**
+ * Sanitizes output for injection into the model conversation.
+ * Wraps output in a secure <output> tag and handles potential injection vectors
+ * (like closing tags or template patterns) within the data.
+ * @param output The raw output to sanitize.
+ * @returns The sanitized string ready for injection.
+ */
+export function sanitizeOutput(output: string): string {
+  const trimmed = output.trim();
+  if (trimmed.length === 0) {
+    return '';
+  }
+
+  // Prevent direct closing tag injection.
+  const escaped = trimmed.replaceAll('</output>', '&lt;/output&gt;');
+  return `<output>\n${escaped}\n</output>`;
+}
@@ -69,4 +69,84 @@ export const TEST_AGENTS = {
    tools: ['read_file', 'write_file'],
    body: 'You are the test agent. Add or update tests.',
  }),
+  /**
+   * An agent with expertise in database schemas, SQL, and creating database migrations.
+   */
+  DATABASE_AGENT: createAgent({
+    name: 'database-agent',
+    description:
+      'An expert in database schemas, SQL, and creating database migrations.',
+    tools: ['read_file', 'write_file'],
+    body: 'You are the database agent. Create and update SQL migrations.',
+  }),
+
+  /**
+   * An agent with expertise in CSS, styling, and UI design.
+   */
+  CSS_AGENT: createAgent({
+    name: 'css-agent',
+    description: 'An expert in CSS, styling, and UI design.',
+    tools: ['read_file', 'write_file'],
+    body: 'You are the CSS agent.',
+  }),
+
+  /**
+   * An agent with expertise in internationalization and translations.
+   */
+  I18N_AGENT: createAgent({
+    name: 'i18n-agent',
+    description: 'An expert in internationalization and translations.',
+    tools: ['read_file', 'write_file'],
+    body: 'You are the i18n agent.',
+  }),
+
+  /**
+   * An agent with expertise in security audits and vulnerability patches.
+   */
+  SECURITY_AGENT: createAgent({
+    name: 'security-agent',
+    description: 'An expert in security audits and vulnerability patches.',
+    tools: ['read_file', 'write_file'],
+    body: 'You are the security agent.',
+  }),
+
+  /**
+   * An agent with expertise in CI/CD, Docker, and deployment scripts.
+   */
+  DEVOPS_AGENT: createAgent({
+    name: 'devops-agent',
+    description: 'An expert in CI/CD, Docker, and deployment scripts.',
+    tools: ['read_file', 'write_file'],
+    body: 'You are the devops agent.',
+  }),
+
+  /**
+   * An agent with expertise in tracking, analytics, and metrics.
+   */
+  ANALYTICS_AGENT: createAgent({
+    name: 'analytics-agent',
+    description: 'An expert in tracking, analytics, and metrics.',
+    tools: ['read_file', 'write_file'],
+    body: 'You are the analytics agent.',
+  }),
+
+  /**
+   * An agent with expertise in web accessibility and ARIA roles.
+   */
+  ACCESSIBILITY_AGENT: createAgent({
+    name: 'accessibility-agent',
+    description: 'An expert in web accessibility and ARIA roles.',
+    tools: ['read_file', 'write_file'],
+    body: 'You are the accessibility agent.',
+  }),
+
+  /**
+   * An agent with expertise in React Native and mobile app development.
+   */
+  MOBILE_AGENT: createAgent({
+    name: 'mobile-agent',
+    description: 'An expert in React Native and mobile app development.',
+    tools: ['read_file', 'write_file'],
+    body: 'You are the mobile agent.',
+  }),
 } as const;
@@ -2394,6 +2394,14 @@
              "default": true,
              "type": "boolean"
            },
+            "backgroundCompletionBehavior": {
+              "title": "Background Completion Behavior",
+              "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.",
+              "markdownDescription": "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.\n\n- Category: `Tools`\n- Requires restart: `no`\n- Default: `silent`",
+              "default": "silent",
+              "type": "string",
+              "enum": ["silent", "inject", "notify"]
+            },
            "pager": {
              "title": "Pager",
              "description": "The pager command to use for shell output. Defaults to `cat`.",
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Michael Bleigh	d9e2c87131	Merge branch 'pr4-cli' into mb/agent-interactive	2026-03-30 12:59:33 -07:00
Michael Bleigh	3b0906f319	Merge branch 'main' into pr4-cli	2026-03-30 12:39:30 -07:00
Michael Bleigh	cd7d91f35e	refactor(cli): remove config dependency from useAgentStream	2026-03-30 12:35:31 -07:00
Michael Bleigh	6020551d1f	Merge branch 'pr4-cli' of github.com:google-gemini/gemini-cli into mb/agent-interactive	2026-03-30 09:48:31 -07:00
Alex Stephen	9cf410478c	Text can be added after /plan command (#22833 )	2026-03-30 14:31:20 +00:00
Spencer	a255529c6b	fix(a2a-server): prioritize ADC before evaluating headless constraints for auth initialization (#23614 )	2026-03-30 12:26:15 +00:00
Abhi	d9d2ce36f2	test(evals): add comprehensive subagent delegation evaluations (#24132 )	2026-03-29 23:13:50 +00:00
Adam Weidman	8e9961a791	fixes	2026-03-29 17:43:07 -04:00
Tommaso Sciortino	da8c841ef4	fix: shellcheck warnings in scripts (#24035 )	2026-03-29 02:47:05 +00:00
Christian Gunderman	b7c86b5497	UX for topic narration tool (#24079 )	2026-03-28 21:33:38 +00:00
Adam Weidman	3eebb75b7a	feat(core): agnostic background task UI with CompletionBehavior (#22740 ) Co-authored-by: mkorwel <matt.korwel@gmail.com>	2026-03-28 21:27:51 +00:00
Michael Bleigh	e046cbd8e0	fix: resolve rebase compilation and test failures	2026-03-27 16:05:06 -07:00
Michael Bleigh	b810e57ef1	feat: add experimental useAgentProtocol flag	2026-03-27 15:42:12 -07:00
Michael Bleigh	ecc9e50a1f	fix: resolve typescript lint errors and test failures - Remove unnecessary `any` casts and unsafe type assertions in `useAgentStream.ts`. - Introduce `MinimalTrackedToolCall` to safely type mock tool calls for inactivity monitors. - Fix arrow-body-style lint errors in `AppContainer.tsx` and `useAgentStream.ts`. - Update `nonInteractiveCli.test.ts` to include a required `build` method in mock tools to prevent TypeErrors during stream initialization. - Remove redundant non-null assertion in `legacy-agent-session.ts`.	2026-03-27 15:41:39 -07:00
joshualitt	fd321abd3d	feat(core): Land `AgentHistoryProvider`. (#23978 )	2026-03-27 15:41:39 -07:00
Sri Pasumarthi	2bb161b36f	fix(acp): prevent crash on empty response in ACP mode (#23952 )	2026-03-27 15:35:58 -07:00
Jacob Richman	565851f2d5	Increase memory limited for eslint. (#24022 )	2026-03-27 15:35:58 -07:00
Michael Bleigh	593c33f927	refactor(cli): simplify useAgentStream state to use IndividualToolCallDisplay This commit refactors the `useAgentStream` hook to track its internal state using the lightweight `IndividualToolCallDisplay` interface instead of the heavyweight `TrackedToolCall`. By mapping `AgentEvent` payloads directly to `IndividualToolCallDisplay`, we completely bypass the need for `DummyTool` re-hydration and the `mapToDisplay` adapter. This removes a redundant data bridging layer and properly aligns the UI state with the flattened data provided by the `AgentProtocol` in `legacyState`.	2026-03-27 15:35:58 -07:00
Michael Bleigh	f85299717a	refactor: allow GEMINI_CLI_USE_AGENT_PROTOCOL env to trigger agent use	2026-03-27 15:35:58 -07:00
Michael Bleigh	0afe5117a4	fix(cli,core): resolve lint and type errors in agent stream and core types	2026-03-27 15:35:54 -07:00
Michael Bleigh	f853d2f9da	fix: explicitly fail pending tool calls when approval is required This commit ensures that when a tool call enters the 'awaiting_approval' state (which is not yet supported in the new protocol), we not only emit a fatal error but also emit a 'tool_response' event with 'isError: true'. This allows the UI to correctly transition the tool call from a pending (scheduled/executing) state to an error state, providing clear visual feedback to the user and preventing the UI from appearing to hang.	2026-03-27 15:02:25 -07:00
Michael Bleigh	0f37dd1d78	fix: error out on tool approvals instead of hanging This commit ensures that the interactive agent loop does not hang when a tool requires manual approval (since confirmation dialogs are not yet implemented for the new protocol). Instead of waiting indefinitely, 'LegacyAgentSession' now detects the 'awaiting_approval' status, emits a descriptive error event, and aborts the session. Key changes: - 'LegacyAgentSession' now emits status updates in 'tool_update' events. - 'LegacyAgentSession' aborts and errors on 'awaiting_approval' status. - 'useAgentStream' now correctly tracks and displays tool status transitions and intermediate progress via the 'AgentEvent' stream.	2026-03-27 15:02:25 -07:00
Michael Bleigh	87e9491e78	fix: ensure correct message ordering in agent stream This commit fixes a bug where model text preceding a tool call would be displayed after the tool call in the conversation history. We now explicitly flush any pending agent text to the conversation history (via 'addItem') immediately before a tool request is tracked. This ensures the model's intent is rendered above the execution result.	2026-03-27 15:02:25 -07:00
Michael Bleigh	2a8918c72f	feat: achieve rich tool call display parity for agent stream This change ensures that tool execution in the Agent Protocol experiment reaches visual parity with the legacy implementation by passing rich metadata and objects (like FileDiff) through the AgentEvent stream. Key changes: - Core 'LegacyAgentSession' now builds temporary invocations for tool requests to capture rich, argument-aware descriptions (e.g. 'Writing to poem.md'). - Core 'LegacyAgentSession' now attaches the raw 'resultDisplay' object and 'outputFile' path to the 'tool_response' event metadata. - Core 'LegacyAgentSession' now passes the rich description through 'tool_update' events to ensure dynamic descriptions are updated during execution. - UI 'useAgentStream' hook now extracts these rich values from event metadata to populate the local 'trackedTools' state, allowing 'mapToDisplay' to correctly trigger bespoke rendering components (like the diff viewer).	2026-03-27 15:02:25 -07:00
Michael Bleigh	6975224e45	feat: implement tool display parity for agent stream This commit achieves visual parity for tool execution in the interactive stream when using the experimental 'useAgentProtocol' flag. It removes direct UI dependency on the tool scheduler's internal state. Key changes: - Core 'LegacyAgentSession' now attaches display metadata (displayName, description, etc.) to 'tool_request' AgentEvents. - Core 'LegacyAgentSession' listens to the MessageBus to emit 'tool_update' AgentEvents for live output (e.g., shell commands). - UI 'useAgentStream' now maintains its own 'trackedTools' local state, constructed entirely from incoming 'tool_request', 'tool_update', and 'tool_response' events. - The local 'trackedTools' state is mapped to 'pendingToolGroupItems' using the existing 'mapToDisplay' function for seamless visual parity.	2026-03-27 15:02:18 -07:00
Michael Bleigh	d3a7fc39e3	feat: implement experimental useAgentStream with unified agent protocol This change introduces an experimental 'useAgentProtocol' flag to interactive mode. When enabled, the UI uses the new 'useAgentStream' hook which leverages the core 'LegacyAgentSession' (AgentProtocol) instead of the custom 'useGeminiStream' logic. Key changes: - Added 'useAgentProtocol' experimental setting to CLI and Core config. - Implemented 'useAgentStream' hook with basic interaction and thought support. - Modified 'useToolScheduler' to expose its internal Scheduler instance to ensure implementation parity. - Updated 'AppContainer' to conditionally branch between implementations via ternary operator. - Added comprehensive unit tests for the new hook.	2026-03-27 14:55:11 -07:00
Michael Bleigh	3b317f9198	feat: add experimental useAgentProtocol flag	2026-03-27 14:55:11 -07:00
Michael Bleigh	6a80311a37	Merge branch 'main' into pr4-cli	2026-03-27 11:08:15 -07:00
Adam Weidman	6fb7bcf868	fix(core): preserve first-turn display content	2026-03-26 11:51:15 -04:00
Adam Weidman	56656dfbc9	fix(cli): preserve max-turns non-interactive parity	2026-03-23 18:47:11 -04:00
Adam Weidman	93322430a0	fix(cli): align non-interactive loop warning handling	2026-03-23 18:38:56 -04:00
Adam Weidman	25c5d44678	!feat(cli): harden non-interactive agent session handling	2026-03-23 18:38:56 -04:00
Adam Weidman	2dfe237738	!feat(cli): address non-interactive review follow-ups	2026-03-23 18:38:56 -04:00
Adam Weidman	f77e4716fa	!feat(cli): adopt protocol-backed agent session streaming	2026-03-23 18:38:56 -04:00
Adam Weidman	3e0b8aa958	fix(cli): consume the stream returned by send	2026-03-23 18:38:56 -04:00
Adam Weidman	b268e93a1d	refactor(cli): handle max turns from stream end	2026-03-23 18:38:56 -04:00
Adam Weidman	218adcd6c3	feat(cli): migrate nonInteractiveCli to LegacyAgentSession	2026-03-23 18:38:56 -04:00