Fix Gemini Code's (GC) smarts.

- The tl;dr; is that GC couldn't see what the user was saying when tool call events happened in response. The rason why this was happening was because we were instantly invoking tools that the model told us to invoke and then instantly re-requesting. This resulted in the bug because the genai APIs can't update the chat history before a full response has been completed (doesn't know how to update if it's incomplete).
- To address the above issue I had to do quite the large refactor. The gist is that now turns truly drive everything on the server (vs. a server client split). This ensured that when we got tool invocations we could control when/how re-requesting would happen and then also ensure that history was updated. This change also meant that the server would act as an event publisher to enable the client to react to events rather than try and weave in complex logic between the events.
- A BIG change that this changeset incudes is the removal of all of the CLI tools in favor of the server tools.
- Removed some dead code as part of this
- **NOTE: Confirmations are still broken (they were broken prior to this); however, I've set them up to be able to work in the future, I'll dot hat in a follow up to be less breaking to others.**

Fixes https://b.corp.google.com/issues/412320087

packages/server/src/core/gemini-client.ts

@@ -18,15 +18,7 @@ import {
 import { CoreSystemPrompt } from './prompts.js';
 import process from 'node:process';
 import { getFolderStructure } from '../utils/getFolderStructure.js';
-import { Turn, ServerTool, GeminiEventType } from './turn.js';
-
-// Import the ServerGeminiStreamEvent type
-type ServerGeminiStreamEvent =
-  | { type: GeminiEventType.Content; value: string }
-  | {
-      type: GeminiEventType.ToolCallRequest;
-      value: { callId: string; name: string; args: Record<string, unknown> };
-    };
+import { Turn, ServerTool, ServerGeminiStreamEvent } from './turn.js';
 
 export class GeminiClient {
   private ai: GoogleGenAI;
@@ -112,6 +104,14 @@ export class GeminiClient {
         for await (const event of resultStream) {
           yield event;
         }
+
+        const confirmations = turn.getConfirmationDetails();
+        if (confirmations.length > 0) {
+          break;
+        }
+
+        // What do we do when we have both function responses and confirmations?
+
         const fnResponses = turn.getFunctionResponses();
         if (fnResponses.length > 0) {
           request = fnResponses;

packages/server/src/core/turn.ts

@@ -13,7 +13,11 @@ import {
   FunctionDeclaration,
 } from '@google/genai';
 // Removed UI type imports
-import { ToolResult } from '../tools/tools.js'; // Keep ToolResult for now
+import {
+  ToolCallConfirmationDetails,
+  ToolResult,
+  ToolResultDisplay,
+} from '../tools/tools.js'; // Keep ToolResult for now
 // Removed gemini-stream import (types defined locally)
 
 // --- Types for Server Logic ---
@@ -25,7 +29,7 @@ interface ServerToolExecutionOutcome {
   args: Record<string, unknown>; // Use unknown for broader compatibility
   result?: ToolResult;
   error?: Error;
-  // Confirmation details are handled by CLI, not server logic
+  confirmationDetails: ToolCallConfirmationDetails | undefined;
 }
 
 // Define a structure for tools passed to the server
@@ -34,6 +38,9 @@ export interface ServerTool {
   schema: FunctionDeclaration; // Schema is needed
   // The execute method signature might differ slightly or be wrapped
   execute(params: Record<string, unknown>): Promise<ToolResult>;
+  shouldConfirmExecute(
+    params: Record<string, unknown>,
+  ): Promise<ToolCallConfirmationDetails | false>;
   // validation and description might be handled differently or passed
 }
 
@@ -41,17 +48,36 @@ export interface ServerTool {
 export enum GeminiEventType {
   Content = 'content',
   ToolCallRequest = 'tool_call_request',
+  ToolCallResponse = 'tool_call_response',
+  ToolCallConfirmation = 'tool_call_confirmation',
 }
 
-interface ToolCallRequestInfo {
+export interface ToolCallRequestInfo {
   callId: string;
   name: string;
   args: Record<string, unknown>;
 }
 
-type ServerGeminiStreamEvent =
+export interface ToolCallResponseInfo {
+  callId: string;
+  responsePart: Part;
+  resultDisplay: ToolResultDisplay | undefined;
+  error: Error | undefined;
+}
+
+export interface ServerToolCallConfirmationDetails {
+  request: ToolCallRequestInfo;
+  details: ToolCallConfirmationDetails;
+}
+
+export type ServerGeminiStreamEvent =
   | { type: GeminiEventType.Content; value: string }
-  | { type: GeminiEventType.ToolCallRequest; value: ToolCallRequestInfo };
+  | { type: GeminiEventType.ToolCallRequest; value: ToolCallRequestInfo }
+  | { type: GeminiEventType.ToolCallResponse; value: ToolCallResponseInfo }
+  | {
+      type: GeminiEventType.ToolCallConfirmation;
+      value: ServerToolCallConfirmationDetails;
+    };
 
 // --- Turn Class (Refactored for Server) ---
 
@@ -65,6 +91,7 @@ export class Turn {
     args: Record<string, unknown>; // Use unknown
   }>;
   private fnResponses: Part[];
+  private confirmationDetails: ToolCallConfirmationDetails[];
   private debugResponses: GenerateContentResponse[];
 
   constructor(chat: Chat, availableTools: ServerTool[]) {
@@ -72,6 +99,7 @@ export class Turn {
     this.availableTools = new Map(availableTools.map((t) => [t.name, t]));
     this.pendingToolCalls = [];
     this.fnResponses = [];
+    this.confirmationDetails = [];
     this.debugResponses = [];
   }
 
@@ -113,19 +141,31 @@ export class Turn {
               error: new Error(
                 `Tool "${pendingToolCall.name}" not found or not provided to Turn.`,
               ),
+              confirmationDetails: undefined,
             };
           }
-          // No confirmation logic in the server Turn
+
           try {
-            // TODO: Add validation step if needed (tool.validateParams?)
-            const result = await tool.execute(pendingToolCall.args);
-            return { ...pendingToolCall, result };
+            const confirmationDetails = await tool.shouldConfirmExecute(
+              pendingToolCall.args,
+            );
+            if (confirmationDetails) {
+              return { ...pendingToolCall, confirmationDetails };
+            } else {
+              const result = await tool.execute(pendingToolCall.args);
+              return {
+                ...pendingToolCall,
+                result,
+                confirmationDetails: undefined,
+              };
+            }
           } catch (execError: unknown) {
             return {
               ...pendingToolCall,
               error: new Error(
                 `Tool execution failed: ${execError instanceof Error ? execError.message : String(execError)}`,
               ),
+              confirmationDetails: undefined,
             };
           }
         },
@@ -133,9 +173,37 @@ export class Turn {
       const outcomes = await Promise.all(toolPromises);
 
       // Process outcomes and prepare function responses
-      this.fnResponses = this.buildFunctionResponses(outcomes);
       this.pendingToolCalls = []; // Clear pending calls for this turn
 
+      for (let i = 0; i < outcomes.length; i++) {
+        const outcome = outcomes[i];
+        if (outcome.confirmationDetails) {
+          this.confirmationDetails.push(outcome.confirmationDetails);
+          const serverConfirmationetails: ServerToolCallConfirmationDetails = {
+            request: {
+              callId: outcome.callId,
+              name: outcome.name,
+              args: outcome.args,
+            },
+            details: outcome.confirmationDetails,
+          };
+          yield {
+            type: GeminiEventType.ToolCallConfirmation,
+            value: serverConfirmationetails,
+          };
+        } else {
+          const responsePart = this.buildFunctionResponse(outcome);
+          this.fnResponses.push(responsePart);
+          const responseInfo: ToolCallResponseInfo = {
+            callId: outcome.callId,
+            responsePart,
+            resultDisplay: outcome.result?.returnDisplay,
+            error: outcome.error,
+          };
+          yield { type: GeminiEventType.ToolCallResponse, value: responseInfo };
+        }
+      }
+
       // If there were function responses, the caller (GeminiService) will loop
       // and call run() again with these responses.
       // If no function responses, the turn ends here.
@@ -160,31 +228,27 @@ export class Turn {
   }
 
   // Builds the Part array expected by the Google GenAI API
-  private buildFunctionResponses(
-    outcomes: ServerToolExecutionOutcome[],
-  ): Part[] {
-    return outcomes.map((outcome): Part => {
-      const { name, result, error } = outcome;
-      let fnResponsePayload: Record<string, unknown>;
+  private buildFunctionResponse(outcome: ServerToolExecutionOutcome): Part {
+    const { name, result, error } = outcome;
+    let fnResponsePayload: Record<string, unknown>;
 
-      if (error) {
-        // Format error for the LLM
-        const errorMessage = error?.message || String(error);
-        fnResponsePayload = { error: `Tool execution failed: ${errorMessage}` };
-        console.error(`[Server Turn] Error executing tool ${name}:`, error);
-      } else {
-        // Pass successful tool result (content meant for LLM)
-        fnResponsePayload = { output: result?.llmContent ?? '' }; // Default to empty string if no content
-      }
+    if (error) {
+      // Format error for the LLM
+      const errorMessage = error?.message || String(error);
+      fnResponsePayload = { error: `Tool execution failed: ${errorMessage}` };
+      console.error(`[Server Turn] Error executing tool ${name}:`, error);
+    } else {
+      // Pass successful tool result (content meant for LLM)
+      fnResponsePayload = { output: result?.llmContent ?? '' }; // Default to empty string if no content
+    }
 
-      return {
-        functionResponse: {
-          name,
-          id: outcome.callId,
-          response: fnResponsePayload,
-        },
-      };
-    });
+    return {
+      functionResponse: {
+        name,
+        id: outcome.callId,
+        response: fnResponsePayload,
+      },
+    };
   }
 
   private abortError(): Error {
@@ -193,6 +257,10 @@ export class Turn {
     return error; // Return instead of throw, let caller handle
   }
 
+  getConfirmationDetails(): ToolCallConfirmationDetails[] {
+    return this.confirmationDetails;
+  }
+
   // Allows the service layer to get the responses needed for the next API call
   getFunctionResponses(): Part[] {
     return this.fnResponses;

packages/server/src/tools/edit.ts

@@ -7,7 +7,14 @@
 import fs from 'fs';
 import path from 'path';
 import * as Diff from 'diff';
-import { BaseTool, ToolResult, ToolResultDisplay } from './tools.js';
+import {
+  BaseTool,
+  ToolCallConfirmationDetails,
+  ToolConfirmationOutcome,
+  ToolEditConfirmationDetails,
+  ToolResult,
+  ToolResultDisplay,
+} from './tools.js';
 import { SchemaValidator } from '../utils/schemaValidator.js';
 import { makeRelative, shortenPath } from '../utils/paths.js';
 import { isNodeError } from '../utils/errors.js';
@@ -48,8 +55,9 @@ interface CalculatedEdit {
 /**
  * Implementation of the Edit tool logic (moved from CLI)
  */
-export class EditLogic extends BaseTool<EditToolParams, ToolResult> {
+export class EditTool extends BaseTool<EditToolParams, ToolResult> {
   static readonly Name = 'replace'; // Keep static name
+  private shouldAlwaysEdit = false;
 
   private readonly rootDirectory: string;
 
@@ -61,9 +69,9 @@ export class EditLogic extends BaseTool<EditToolParams, ToolResult> {
     // Note: The description here mentions other tools like ReadFileTool/WriteFileTool
     // by name. This might need updating if those tool names change.
     super(
-      EditLogic.Name,
-      '', // Display name handled by CLI wrapper
-      '', // Description handled by CLI wrapper
+      EditTool.Name,
+      'Edit',
+      'Replaces a SINGLE, UNIQUE occurrence of text within a file. Requires providing significant context around the change to ensure uniqueness. For moving/renaming files, use the Bash tool with `mv`. For replacing entire file contents or creating new files use the WriteFile tool. Always use the ReadFile tool to examine the file before using this tool.',
       {
         properties: {
           file_path: {
@@ -225,7 +233,82 @@ export class EditLogic extends BaseTool<EditToolParams, ToolResult> {
     };
   }
 
-  // Removed shouldConfirmExecute - Confirmation is handled by the CLI wrapper
+  /**
+   * Handles the confirmation prompt for the Edit tool in the CLI.
+   * It needs to calculate the diff to show the user.
+   */
+  async shouldConfirmExecute(
+    params: EditToolParams,
+  ): Promise<ToolCallConfirmationDetails | false> {
+    if (this.shouldAlwaysEdit) {
+      return false;
+    }
+    const validationError = this.validateToolParams(params);
+    if (validationError) {
+      console.error(
+        `[EditTool Wrapper] Attempted confirmation with invalid parameters: ${validationError}`,
+      );
+      return false;
+    }
+    let currentContent: string | null = null;
+    let fileExists = false;
+    let newContent = '';
+    try {
+      currentContent = fs.readFileSync(params.file_path, 'utf8');
+      fileExists = true;
+    } catch (err: unknown) {
+      if (isNodeError(err) && err.code === 'ENOENT') {
+        fileExists = false;
+      } else {
+        console.error(`Error reading file for confirmation diff: ${err}`);
+        return false;
+      }
+    }
+    if (params.old_string === '' && !fileExists) {
+      newContent = params.new_string;
+    } else if (!fileExists) {
+      return false;
+    } else if (currentContent !== null) {
+      const occurrences = this.countOccurrences(
+        currentContent,
+        params.old_string,
+      );
+      const expectedReplacements =
+        params.expected_replacements === undefined
+          ? 1
+          : params.expected_replacements;
+      if (occurrences === 0 || occurrences !== expectedReplacements) {
+        return false;
+      }
+      newContent = this.replaceAll(
+        currentContent,
+        params.old_string,
+        params.new_string,
+      );
+    } else {
+      return false;
+    }
+    const fileName = path.basename(params.file_path);
+    const fileDiff = Diff.createPatch(
+      fileName,
+      currentContent ?? '',
+      newContent,
+      'Current',
+      'Proposed',
+      { context: 3 },
+    );
+    const confirmationDetails: ToolEditConfirmationDetails = {
+      title: `Confirm Edit: ${shortenPath(makeRelative(params.file_path, this.rootDirectory))}`,
+      fileName,
+      fileDiff,
+      onConfirm: async (outcome: ToolConfirmationOutcome) => {
+        if (outcome === ToolConfirmationOutcome.ProceedAlways) {
+          this.shouldAlwaysEdit = true;
+        }
+      },
+    };
+    return confirmationDetails;
+  }
 
   getDescription(params: EditToolParams): string {
     const relativePath = makeRelative(params.file_path, this.rootDirectory);

packages/server/src/tools/glob.ts

@@ -29,7 +29,7 @@ export interface GlobToolParams {
 /**
  * Implementation of the Glob tool logic (moved from CLI)
  */
-export class GlobLogic extends BaseTool<GlobToolParams, ToolResult> {
+export class GlobTool extends BaseTool<GlobToolParams, ToolResult> {
   static readonly Name = 'glob'; // Keep static name
 
   /**
@@ -43,9 +43,9 @@ export class GlobLogic extends BaseTool<GlobToolParams, ToolResult> {
    */
   constructor(rootDirectory: string) {
     super(
-      GlobLogic.Name,
-      '', // Display name handled by CLI wrapper
-      '', // Description handled by CLI wrapper
+      GlobTool.Name,
+      'FindFiles', // Display name handled by CLI wrapper
+      'Efficiently finds files matching specific glob patterns (e.g., `src/**/*.ts`, `**/*.md`), returning absolute paths sorted by modification time (newest first). Ideal for quickly locating files based on their name or path structure, especially in large codebases.', // Description handled by CLI wrapper
       {
         properties: {
           pattern: {

packages/server/src/tools/grep.ts

@@ -51,7 +51,7 @@ interface GrepMatch {
 /**
  * Implementation of the Grep tool logic (moved from CLI)
  */
-export class GrepLogic extends BaseTool<GrepToolParams, ToolResult> {
+export class GrepTool extends BaseTool<GrepToolParams, ToolResult> {
   static readonly Name = 'search_file_content'; // Keep static name
 
   private rootDirectory: string;
@@ -62,9 +62,9 @@ export class GrepLogic extends BaseTool<GrepToolParams, ToolResult> {
    */
   constructor(rootDirectory: string) {
     super(
-      GrepLogic.Name,
-      '', // Display name handled by CLI wrapper
-      '', // Description handled by CLI wrapper
+      GrepTool.Name,
+      'SearchText',
+      'Searches for a regular expression pattern within the content of files in a specified directory (or current working directory). Can filter files by a glob pattern. Returns the lines containing matches, along with their file paths and line numbers.',
       {
         properties: {
           pattern: {

packages/server/src/tools/ls.ts

@@ -58,7 +58,7 @@ export interface FileEntry {
 /**
  * Implementation of the LS tool logic
  */
-export class LSLogic extends BaseTool<LSToolParams, ToolResult> {
+export class LSTool extends BaseTool<LSToolParams, ToolResult> {
   static readonly Name = 'list_directory';
 
   /**
@@ -73,9 +73,9 @@ export class LSLogic extends BaseTool<LSToolParams, ToolResult> {
    */
   constructor(rootDirectory: string) {
     super(
-      LSLogic.Name,
-      '', // Display name handled by CLI wrapper
-      '', // Description handled by CLI wrapper
+      LSTool.Name,
+      'ReadFolder',
+      'Lists the names of files and subdirectories directly within a specified directory path. Can optionally ignore entries matching provided glob patterns.',
       {
         properties: {
           path: {

packages/server/src/tools/read-file.ts

@@ -33,7 +33,7 @@ export interface ReadFileToolParams {
 /**
  * Implementation of the ReadFile tool logic
  */
-export class ReadFileLogic extends BaseTool<ReadFileToolParams, ToolResult> {
+export class ReadFileTool extends BaseTool<ReadFileToolParams, ToolResult> {
   static readonly Name: string = 'read_file';
   private static readonly DEFAULT_MAX_LINES = 2000;
   private static readonly MAX_LINE_LENGTH = 2000;
@@ -41,9 +41,9 @@ export class ReadFileLogic extends BaseTool<ReadFileToolParams, ToolResult> {
 
   constructor(rootDirectory: string) {
     super(
-      ReadFileLogic.Name,
-      '', // Display name handled by CLI wrapper
-      '', // Description handled by CLI wrapper
+      ReadFileTool.Name,
+      'ReadFile',
+      'Reads and returns the content of a specified file from the local filesystem. Handles large files by allowing reading specific line ranges.',
       {
         properties: {
           path: {
@@ -236,16 +236,15 @@ export class ReadFileLogic extends BaseTool<ReadFileToolParams, ToolResult> {
       const startLine = params.offset || 0;
       const endLine = params.limit
         ? startLine + params.limit
-        : Math.min(startLine + ReadFileLogic.DEFAULT_MAX_LINES, lines.length);
+        : Math.min(startLine + ReadFileTool.DEFAULT_MAX_LINES, lines.length);
       const selectedLines = lines.slice(startLine, endLine);
 
       let truncated = false;
       const formattedLines = selectedLines.map((line) => {
         let processedLine = line;
-        if (line.length > ReadFileLogic.MAX_LINE_LENGTH) {
+        if (line.length > ReadFileTool.MAX_LINE_LENGTH) {
           processedLine =
-            line.substring(0, ReadFileLogic.MAX_LINE_LENGTH) +
-            '... [truncated]';
+            line.substring(0, ReadFileTool.MAX_LINE_LENGTH) + '... [truncated]';
           truncated = true;
         }
 

packages/server/src/tools/tools.ts

@@ -49,7 +49,14 @@ export interface Tool<
    */
   getDescription(params: TParams): string;
 
-  // Removed shouldConfirmExecute as it's UI-specific
+  /**
+   * Determines if the tool should prompt for confirmation before execution
+   * @param params Parameters for the tool execution
+   * @returns Whether execute should be confirmed.
+   */
+  shouldConfirmExecute(
+    params: TParams,
+  ): Promise<ToolCallConfirmationDetails | false>;
 
   /**
    * Executes the tool with the given parameters
@@ -115,7 +122,17 @@ export abstract class BaseTool<
     return JSON.stringify(params);
   }
 
-  // Removed shouldConfirmExecute as it's UI-specific
+  /**
+   * Determines if the tool should prompt for confirmation before execution
+   * @param params Parameters for the tool execution
+   * @returns Whether or not execute should be confirmed by the user.
+   */
+  shouldConfirmExecute(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    params: TParams,
+  ): Promise<ToolCallConfirmationDetails | false> {
+    return Promise.resolve(false);
+  }
 
   /**
    * Abstract method to execute the tool with the given parameters
@@ -148,3 +165,27 @@ export type ToolResultDisplay = string | FileDiff;
 export interface FileDiff {
   fileDiff: string;
 }
+
+export interface ToolCallConfirmationDetails {
+  title: string;
+  onConfirm: (outcome: ToolConfirmationOutcome) => Promise<void>;
+}
+
+export interface ToolEditConfirmationDetails
+  extends ToolCallConfirmationDetails {
+  fileName: string;
+  fileDiff: string;
+}
+
+export interface ToolExecuteConfirmationDetails
+  extends ToolCallConfirmationDetails {
+  command: string;
+  rootCommand: string;
+  description: string;
+}
+
+export enum ToolConfirmationOutcome {
+  ProceedOnce,
+  ProceedAlways,
+  Cancel,
+}

packages/server/src/tools/web-fetch.ts

@@ -21,14 +21,14 @@ export interface WebFetchToolParams {
 /**
  * Implementation of the WebFetch tool logic (moved from CLI)
  */
-export class WebFetchLogic extends BaseTool<WebFetchToolParams, ToolResult> {
+export class WebFetchTool extends BaseTool<WebFetchToolParams, ToolResult> {
   static readonly Name: string = 'web_fetch';
 
   constructor() {
     super(
-      WebFetchLogic.Name,
-      '', // Display name handled by CLI wrapper
-      '', // Description handled by CLI wrapper
+      WebFetchTool.Name,
+      'WebFetch',
+      'Fetches text content from a given URL. Handles potential network errors and non-success HTTP status codes.',
       {
         properties: {
           url: {

packages/server/src/tools/write-file.ts

@@ -7,7 +7,14 @@
 import fs from 'fs';
 import path from 'path';
 import * as Diff from 'diff'; // Keep for result generation
-import { BaseTool, ToolResult, FileDiff } from './tools.js'; // Updated import (Removed ToolResultDisplay)
+import {
+  BaseTool,
+  ToolResult,
+  FileDiff,
+  ToolEditConfirmationDetails,
+  ToolConfirmationOutcome,
+  ToolCallConfirmationDetails,
+} from './tools.js'; // Updated import (Removed ToolResultDisplay)
 import { SchemaValidator } from '../utils/schemaValidator.js'; // Updated import
 import { makeRelative, shortenPath } from '../utils/paths.js'; // Updated import
 import { isNodeError } from '../utils/errors.js'; // Import isNodeError
@@ -30,16 +37,17 @@ export interface WriteFileToolParams {
 /**
  * Implementation of the WriteFile tool logic (moved from CLI)
  */
-export class WriteFileLogic extends BaseTool<WriteFileToolParams, ToolResult> {
+export class WriteFileTool extends BaseTool<WriteFileToolParams, ToolResult> {
   static readonly Name: string = 'write_file';
+  private shouldAlwaysWrite = false;
 
   private readonly rootDirectory: string;
 
   constructor(rootDirectory: string) {
     super(
-      WriteFileLogic.Name,
-      '', // Display name handled by CLI wrapper
-      '', // Description handled by CLI wrapper
+      WriteFileTool.Name,
+      'WriteFile',
+      'Writes content to a specified file in the local filesystem.',
       {
         properties: {
           file_path: {
@@ -98,6 +106,56 @@ export class WriteFileLogic extends BaseTool<WriteFileToolParams, ToolResult> {
     return `Writing to ${shortenPath(relativePath)}`;
   }
 
+  /**
+   * Handles the confirmation prompt for the WriteFile tool in the CLI.
+   */
+  async shouldConfirmExecute(
+    params: WriteFileToolParams,
+  ): Promise<ToolCallConfirmationDetails | false> {
+    if (this.shouldAlwaysWrite) {
+      return false;
+    }
+
+    const validationError = this.validateToolParams(params);
+    if (validationError) {
+      console.error(
+        `[WriteFile Wrapper] Attempted confirmation with invalid parameters: ${validationError}`,
+      );
+      return false;
+    }
+
+    const relativePath = makeRelative(params.file_path, this.rootDirectory);
+    const fileName = path.basename(params.file_path);
+
+    let currentContent = '';
+    try {
+      currentContent = fs.readFileSync(params.file_path, 'utf8');
+    } catch {
+      // File might not exist, that's okay for write/create
+    }
+
+    const fileDiff = Diff.createPatch(
+      fileName,
+      currentContent,
+      params.content,
+      'Current',
+      'Proposed',
+      { context: 3 },
+    );
+
+    const confirmationDetails: ToolEditConfirmationDetails = {
+      title: `Confirm Write: ${shortenPath(relativePath)}`,
+      fileName,
+      fileDiff,
+      onConfirm: async (outcome: ToolConfirmationOutcome) => {
+        if (outcome === ToolConfirmationOutcome.ProceedAlways) {
+          this.shouldAlwaysWrite = true;
+        }
+      },
+    };
+    return confirmationDetails;
+  }
+
   async execute(params: WriteFileToolParams): Promise<ToolResult> {
     const validationError = this.validateParams(params);
     if (validationError) {

packages/server/src/utils/BackgroundTerminalAnalyzer.ts

@@ -0,0 +1,473 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Content, SchemaUnion, Type } from '@google/genai';
+import {
+  Config,
+  getErrorMessage,
+  isNodeError,
+  GeminiClient,
+} from '@gemini-code/server';
+import { promises as fs } from 'fs';
+import { exec as _exec } from 'child_process';
+import { promisify } from 'util';
+
+// Define the AnalysisStatus type alias
+type AnalysisStatus =
+  | 'Running'
+  | 'SuccessReported'
+  | 'ErrorReported'
+  | 'Unknown'
+  | 'AnalysisFailed';
+
+// Promisify child_process.exec for easier async/await usage
+const execAsync = promisify(_exec);
+
+// Define the expected interface for the AI client dependency
+export interface AiClient {
+  generateJson(
+    prompt: Content[], // Keep flexible or define a stricter prompt structure type
+    schema: SchemaUnion,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ): Promise<any>; // Ideally, specify the expected JSON structure TAnalysisResult | TAnalysisFailure
+}
+
+// Identifier for the background process (e.g., PID)
+// Using `unknown` allows more flexibility than `object` while still being type-safe
+export type ProcessHandle = number | string | unknown;
+
+// Represents the structure expected from a successful LLM analysis call
+export interface AnalysisResult {
+  summary: string;
+  inferredStatus: 'Running' | 'SuccessReported' | 'ErrorReported' | 'Unknown';
+}
+
+// Represents the structure returned when the LLM analysis itself fails
+export interface AnalysisFailure {
+  error: string;
+  inferredStatus: 'AnalysisFailed';
+}
+
+// Type guard to check if the result is a failure object
+function isAnalysisFailure(
+  result: AnalysisResult | AnalysisFailure,
+): result is AnalysisFailure {
+  return (result as AnalysisFailure).inferredStatus === 'AnalysisFailed';
+}
+
+// Represents the final outcome after polling is complete (or failed/timed out)
+export interface FinalAnalysisOutcome {
+  status: string; // e.g., 'Completed_SuccessReported', 'TimedOut_Running', 'AnalysisFailed'
+  summary: string; // Final summary or error message
+}
+
+export class BackgroundTerminalAnalyzer {
+  private geminiClient: GeminiClient | null = null;
+  private readonly maxOutputAnalysisLength = 20000;
+  private pollIntervalMs: number;
+  private maxAttempts: number;
+  private initialDelayMs: number;
+
+  constructor(
+    config: Config, // Accept Config object
+    options: {
+      pollIntervalMs?: number;
+      maxAttempts?: number;
+      initialDelayMs?: number;
+    } = {},
+  ) {
+    try {
+      // Initialize Gemini client using config
+      this.geminiClient = new GeminiClient(
+        config.getApiKey(),
+        config.getModel(),
+      );
+    } catch (error) {
+      console.error(
+        'Failed to initialize GeminiClient in BackgroundTerminalAnalyzer:',
+        error,
+      );
+      // Set client to null so analyzeOutput handles it
+      this.geminiClient = null;
+    }
+    this.pollIntervalMs = options.pollIntervalMs ?? 5000; // Default 5 seconds
+    this.maxAttempts = options.maxAttempts ?? 6; // Default 6 attempts (approx 30s total)
+    this.initialDelayMs = options.initialDelayMs ?? 500; // Default 0.5s initial delay
+  }
+
+  /**
+   * Polls the output of a background process using an LLM
+   * until a conclusive status is determined or timeout occurs.
+   * @param pid The handle/identifier of the background process (typically PID number).
+   * @param tempStdoutFilePath Path to the temporary file capturing stdout.
+   * @param tempStderrFilePath Path to the temporary file capturing stderr.
+   * @param command The command string that was executed (for context in prompts).
+   * @returns A promise resolving to the final analysis outcome.
+   */
+  async analyze(
+    pid: ProcessHandle,
+    tempStdoutFilePath: string,
+    tempStderrFilePath: string,
+    command: string,
+  ): Promise<FinalAnalysisOutcome> {
+    // --- Validate PID ---
+    if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) {
+      console.error(
+        `BackgroundTerminalAnalyzer: Invalid or non-numeric PID provided (${pid}). Analysis cannot proceed.`,
+      );
+      return {
+        status: 'AnalysisFailed',
+        summary: 'Invalid PID provided for analysis.',
+      };
+    }
+
+    // --- Initial Delay ---
+    // Wait briefly before the first check to allow the process to initialize
+    // and potentially write initial output.
+    await new Promise((resolve) => setTimeout(resolve, this.initialDelayMs));
+
+    let attempts = 0;
+    let lastAnalysisResult: AnalysisResult | AnalysisFailure | null = null;
+
+    while (attempts < this.maxAttempts) {
+      attempts++;
+      let currentStdout = '';
+      let currentStderr = '';
+
+      // --- Robust File Reading ---
+      try {
+        currentStdout = await fs.readFile(tempStdoutFilePath, 'utf-8');
+      } catch (error: unknown) {
+        // If file doesn't exist yet or isn't readable, treat as empty, but log warning
+        if (!isNodeError(error) || error.code !== 'ENOENT') {
+          console.warn(
+            `Attempt ${attempts}: Failed to read stdout file ${tempStdoutFilePath}: ${getErrorMessage(error)}`,
+          );
+        }
+      }
+      try {
+        currentStderr = await fs.readFile(tempStderrFilePath, 'utf-8');
+      } catch (error: unknown) {
+        if (!isNodeError(error) || error.code !== 'ENOENT') {
+          console.warn(
+            `Attempt ${attempts}: Failed to read stderr file ${tempStderrFilePath}: ${getErrorMessage(error)}`,
+          );
+        }
+      }
+
+      // --- Process Status Check ---
+      let isRunning = false;
+      try {
+        // Check if process is running *before* the final analysis if it seems to have ended
+        isRunning = await this.isProcessRunning(pid);
+        if (!isRunning) {
+          // Reread files one last time in case output was written just before exit
+          try {
+            currentStdout = await fs.readFile(tempStdoutFilePath, 'utf-8');
+          } catch {
+            /* ignore */
+          }
+          try {
+            currentStderr = await fs.readFile(tempStderrFilePath, 'utf-8');
+          } catch {
+            /* ignore */
+          }
+
+          lastAnalysisResult = await this.performLlmAnalysis(
+            currentStdout,
+            currentStderr,
+            command,
+            pid,
+          );
+
+          if (isAnalysisFailure(lastAnalysisResult)) {
+            return {
+              status: 'Completed_AnalysisFailed',
+              summary: `Process ended. Final analysis failed: ${lastAnalysisResult.error}`,
+            };
+          }
+          // Append ProcessEnded to the status determined by the final analysis
+          return {
+            status: 'Completed_' + lastAnalysisResult.inferredStatus,
+            summary: `Process ended. Final analysis summary: ${lastAnalysisResult.summary}`,
+          };
+        }
+      } catch (procCheckError: unknown) {
+        // Log the error but allow polling to continue, as log analysis might still be useful
+        console.warn(
+          `Could not check process status for PID ${pid} on attempt ${attempts}: ${getErrorMessage(procCheckError)}`,
+        );
+        // Decide if you want to bail out here or continue analysis based on logs only
+        // For now, we continue.
+      }
+
+      // --- LLM Analysis ---
+      lastAnalysisResult = await this.performLlmAnalysis(
+        currentStdout,
+        currentStderr,
+        command,
+        pid,
+      );
+
+      if (isAnalysisFailure(lastAnalysisResult)) {
+        console.error(
+          `LLM Analysis failed for PID ${pid} on attempt ${attempts}:`,
+          lastAnalysisResult.error,
+        );
+        // Stop polling on analysis failure, returning the specific failure status
+        return {
+          status: lastAnalysisResult.inferredStatus,
+          summary: lastAnalysisResult.error,
+        };
+      }
+
+      // --- Exit Conditions ---
+      if (
+        lastAnalysisResult.inferredStatus === 'SuccessReported' ||
+        lastAnalysisResult.inferredStatus === 'ErrorReported'
+      ) {
+        return {
+          status: lastAnalysisResult.inferredStatus,
+          summary: lastAnalysisResult.summary,
+        };
+      }
+
+      // Heuristic: If the process seems stable and 'Running' after several checks,
+      // return that status without waiting for the full timeout. Adjust threshold as needed.
+      const runningExitThreshold = Math.floor(this.maxAttempts / 3) + 1; // e.g., exit after attempt 4 if maxAttempts is 6
+      if (
+        attempts >= runningExitThreshold &&
+        lastAnalysisResult.inferredStatus === 'Running'
+      ) {
+        return {
+          status: lastAnalysisResult.inferredStatus,
+          summary: lastAnalysisResult.summary,
+        };
+      }
+
+      // --- Wait before next poll ---
+      if (attempts < this.maxAttempts) {
+        await new Promise((resolve) =>
+          setTimeout(resolve, this.pollIntervalMs),
+        );
+      }
+    } // End while loop
+
+    // --- Timeout Condition ---
+    console.warn(
+      `Polling timed out for PID ${pid} after ${this.maxAttempts} attempts.`,
+    );
+
+    // Determine final status based on the last successful analysis (if any)
+    const finalStatus =
+      lastAnalysisResult && !isAnalysisFailure(lastAnalysisResult)
+        ? `TimedOut_${lastAnalysisResult.inferredStatus}` // e.g., TimedOut_Running
+        : 'TimedOut_AnalysisFailed'; // If last attempt failed or no analysis succeeded
+
+    const finalSummary =
+      lastAnalysisResult && !isAnalysisFailure(lastAnalysisResult)
+        ? `Polling timed out after ${this.maxAttempts} attempts. Last known summary: ${lastAnalysisResult.summary}`
+        : lastAnalysisResult && isAnalysisFailure(lastAnalysisResult)
+          ? `Polling timed out; last analysis attempt failed: ${lastAnalysisResult}`
+          : `Polling timed out after ${this.maxAttempts} attempts without any successful analysis.`;
+
+    return { status: finalStatus, summary: finalSummary };
+  }
+
+  // --- Actual Implementation of isProcessRunning ---
+  /**
+   * Checks if the background process is still running using OS-specific methods.
+   * @param pid Process handle/identifier (expects a number for standard checks).
+   * @returns True if running, false otherwise.
+   * @throws Error if the check itself fails critically (e.g., command not found, permissions).
+   */
+  private async isProcessRunning(pid: ProcessHandle): Promise<boolean> {
+    if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) {
+      console.warn(
+        `isProcessRunning: Invalid PID provided (${pid}). Assuming not running.`,
+      );
+      return false;
+    }
+
+    try {
+      if (process.platform === 'win32') {
+        // Windows: Use tasklist command
+        const command = `tasklist /FI "PID eq ${pid}" /NH`; // /NH for no header
+        const { stdout } = await execAsync(command);
+        // Check if the output contains the process information (it will have the image name if found)
+        return stdout.toLowerCase().includes('.exe'); // A simple check, adjust if needed
+      } else {
+        // Linux/macOS/Unix-like: Use kill -0 signal
+        // process.kill sends signal 0 to check existence without killing
+        process.kill(pid, 0);
+        return true; // If no error is thrown, process exists
+      }
+    } catch (error: unknown) {
+      if (isNodeError(error) && error.code === 'ESRCH') {
+        // ESRCH: Standard error code for "No such process" on Unix-like systems
+        return false;
+      } else if (
+        process.platform === 'win32' &&
+        getErrorMessage(error).includes('No tasks are running')
+      ) {
+        // tasklist specific error when PID doesn't exist
+        return false;
+      } else {
+        // Other errors (e.g., EPERM - permission denied) mean we couldn't determine status.
+        // Re-throwing might be appropriate depending on desired behavior.
+        // Here, we log it and cautiously return true, assuming it *might* still be running.
+        console.warn(
+          `isProcessRunning(${pid}) encountered error: ${getErrorMessage(error)}. Assuming process might still exist.`,
+        );
+        // Or you could throw the error: throw new Error(`Failed to check process status for PID ${pid}: ${error.message}`);
+        return true; // Cautious assumption
+      }
+    }
+  }
+
+  // --- LLM Analysis Method (largely unchanged but added validation robustness) ---
+  private async performLlmAnalysis(
+    stdoutContent: string,
+    stderrContent: string,
+    command: string,
+    pid: number,
+  ): Promise<AnalysisResult | AnalysisFailure> {
+    if (!this.geminiClient) {
+      return {
+        error: '[Analysis unavailable: Gemini client not initialized]',
+        inferredStatus: 'AnalysisFailed',
+      };
+    }
+
+    const truncatedStdout =
+      stdoutContent.substring(0, this.maxOutputAnalysisLength) +
+      (stdoutContent.length > this.maxOutputAnalysisLength
+        ? '... [truncated]'
+        : '');
+    const truncatedStderr =
+      stderrContent.substring(0, this.maxOutputAnalysisLength) +
+      (stderrContent.length > this.maxOutputAnalysisLength
+        ? '... [truncated]'
+        : '');
+
+    const analysisPrompt = `**Analyze Background Process Logs**
+
+**Context:** A command (\`${command}\`) was executed in the background. You are analyzing the standard output (stdout) and standard error (stderr) collected so far to understand its progress and outcome. This analysis will be used to inform a user about what the command did.
+
+**Input:**
+* **Command:** \`${command}\`
+* **Stdout:**
+    \`\`\`
+    ${truncatedStdout}
+    \`\`\`
+* **Stderr:**
+    \`\`\`
+    ${truncatedStderr}
+    \`\`\`
+
+**Task:**
+
+Based *only* on the provided stdout and stderr:
+
+1.  **Interpret and Summarize:** Do *not* simply repeat the logs. Analyze the content and provide a concise summary describing the significant actions, results, progress, or errors reported by the command. If logs are empty, state that no output was captured. Summaries should be formatted as markdown. Focus on the most recent or conclusive information if logs are long.
+2.  **Infer Current Status:** Based *only* on the log content, infer the likely status of the command's execution as reflected *in the logs*. Choose the most appropriate status from the options defined in the schema (\`Running\`, \`SuccessReported\`, \`ErrorReported\`, \`Unknown\`). For example:
+    * If logs show ongoing activity or progress messages without clear completion or error signals, use \`Running\`.
+    * If logs contain explicit messages indicating successful completion or the final expected output of a successful run, use \`SuccessReported\`.
+    * If logs contain error messages, stack traces, or failure indications, use \`ErrorReported\`.
+    * If the logs provide insufficient information to determine a clear status (e.g., empty logs, vague messages), use \`Unknown\`.
+    * If dealing with a node server, the second the port has been shown the server is considered booted, use \`SuccessReported\`.
+    * *Note: This status reflects the log content, not necessarily the absolute real-time state of the OS process.*
+3.  **Format Output:** Return the results as a JSON object adhering strictly to the following schema:
+
+    \`\`\`json
+    ${JSON.stringify(
+      {
+        // Generate the schema JSON string for the prompt context
+        type: 'object',
+        properties: {
+          summary: {
+            type: 'string',
+            description:
+              'Concise markdown summary (1-3 sentences) of log interpretation.',
+          },
+          inferredStatus: {
+            type: 'string',
+            enum: ['Running', 'SuccessReported', 'ErrorReported', 'Unknown'],
+            description:
+              'Status inferred from logs: Running, SuccessReported, ErrorReported, Unknown',
+          },
+        },
+        required: ['summary', 'inferredStatus'],
+      },
+      null,
+      2,
+    )}
+    \`\`\`
+
+**Instructions:**
+* The \`summary\` must be an interpretation of the logs, focusing on key outcomes or activities. Prioritize recent events if logs are extensive.
+* The \`inferredStatus\` should reflect the most likely state *deduced purely from the log text provided*. Ensure it is one of the specified enum values.`;
+
+    const schema: SchemaUnion = {
+      type: Type.OBJECT,
+      properties: {
+        summary: {
+          type: Type.STRING,
+          description:
+            'Concise markdown summary (1-3 sentences) of log interpretation.',
+        },
+        inferredStatus: {
+          type: Type.STRING,
+          description:
+            'Status inferred from logs: Running, SuccessReported, ErrorReported, Unknown',
+          enum: ['Running', 'SuccessReported', 'ErrorReported', 'Unknown'],
+        },
+      },
+      required: ['summary', 'inferredStatus'],
+    };
+
+    try {
+      const resultJson = await this.geminiClient.generateJson(
+        [{ role: 'user', parts: [{ text: analysisPrompt }] }],
+        schema,
+      );
+
+      // Validate and construct the AnalysisResult object
+      const summary =
+        typeof resultJson?.summary === 'string'
+          ? resultJson.summary
+          : '[Summary unavailable]';
+
+      // Define valid statuses using the AnalysisStatus type (ensure it's defined above)
+      const validStatuses: Array<Exclude<AnalysisStatus, 'AnalysisFailed'>> = [
+        'Running',
+        'SuccessReported',
+        'ErrorReported',
+        'Unknown',
+      ];
+
+      // Cast the unknown value to string before checking with includes
+      const statusString = resultJson?.inferredStatus as string;
+      const inferredStatus = validStatuses.includes(
+        statusString as Exclude<AnalysisStatus, 'AnalysisFailed'>,
+      )
+        ? (statusString as Exclude<AnalysisStatus, 'AnalysisFailed'>)
+        : 'Unknown';
+
+      // Explicitly construct the object matching AnalysisResult type
+      const analysisResult: AnalysisResult = { summary, inferredStatus };
+      return analysisResult;
+    } catch (error: unknown) {
+      console.error(`LLM Analysis Request Failed for PID ${pid}:`, error);
+      // Return the AnalysisFailure type
+      const analysisFailure: AnalysisFailure = {
+        error: `[Analysis failed: ${getErrorMessage(error)}]`,
+        inferredStatus: 'AnalysisFailed', // This matches the AnalysisStatus type
+      };
+      return analysisFailure;
+    }
+  }
+}