@quantum-ai/gemini-cli 0.45.8 → 0.45.10

package/dist/acp/acpSession.js

@@ -0,0 +1,1167 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CoreToolCallStatus, coreEvents, CoreEvent, logToolCall, convertToFunctionResponse, ToolConfirmationOutcome, getErrorStatus, DiscoveredMCPTool, ToolCallEvent, debugLogger, ReadManyFilesTool, partListUnionToString, updatePolicy, getErrorMessage, isTextPart, GeminiEventType, isWithinRoot, processSingleFileContent, isNodeError, REFERENCE_CONTENT_START, InvalidStreamError, MessageBusType, PolicyDecision, resolveAtCommandPath, } from '@google/gemini-cli-core';
+import * as acp from '@agentclientprotocol/sdk';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { CommandHandler } from './acpCommandHandler.js';
+import { toToolCallContent, toPermissionOptions, toAcpToolKind, buildAvailableModes, RequestPermissionResponseSchema, } from './acpUtils.js';
+import { z } from 'zod';
+import { getAcpErrorMessage } from './acpErrors.js';
+const StructuredErrorSchema = z.object({
+    status: z.number().optional(),
+    message: z.string().optional(),
+});
+export class Session {
+    id;
+    chat;
+    context;
+    connection;
+    settings;
+    pendingPrompt = null;
+    commandHandler = new CommandHandler();
+    callIdCounter = 0;
+    disposeController = new AbortController();
+    generateCallId(name) {
+        return `${name}-${Date.now()}-${++this.callIdCounter}`;
+    }
+    constructor(id, chat, context, connection, settings) {
+        this.id = id;
+        this.chat = chat;
+        this.context = context;
+        this.connection = connection;
+        this.settings = settings;
+        coreEvents.on(CoreEvent.ApprovalModeChanged, this.handleApprovalModeChanged);
+        // Subscribe to tool confirmation requests to handle policy checks (e.g. auto-allowing safe shell commands)
+        this.context.config
+            .getMessageBus()
+            ?.subscribe(MessageBusType.TOOL_CONFIRMATION_REQUEST, this.handleToolConfirmationRequest, { signal: this.disposeController.signal });
+    }
+    handleToolConfirmationRequest = async (request) => {
+        try {
+            const policyEngine = this.context.config.getPolicyEngine?.();
+            const messageBus = this.context.config.getMessageBus();
+            if (!messageBus) {
+                return;
+            }
+            if (!policyEngine) {
+                debugLogger.warn('Policy engine missing. Denying tool confirmation request.');
+                await messageBus.publish({
+                    type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+                    correlationId: request.correlationId,
+                    confirmed: false,
+                    requiresUserConfirmation: false,
+                });
+                return;
+            }
+            const toolName = request.toolCall.name?.trim();
+            if (!toolName) {
+                debugLogger.warn('Tool confirmation request missing tool name. Denying.');
+                await messageBus.publish({
+                    type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+                    correlationId: request.correlationId,
+                    confirmed: false,
+                    requiresUserConfirmation: false,
+                });
+                return;
+            }
+            const tool = this.context.toolRegistry.getTool(toolName);
+            if (!tool) {
+                debugLogger.warn(`Tool confirmation request for unknown tool: ${toolName}. Denying.`);
+                await messageBus.publish({
+                    type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+                    correlationId: request.correlationId,
+                    confirmed: false,
+                    requiresUserConfirmation: false,
+                });
+                return;
+            }
+            const serverName = tool instanceof DiscoveredMCPTool ? tool.serverName : undefined;
+            const toolAnnotations = tool.toolAnnotations;
+            const result = await policyEngine.check(request.toolCall, serverName, toolAnnotations, request.subagent);
+            await messageBus.publish({
+                type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+                correlationId: request.correlationId,
+                confirmed: result.decision === PolicyDecision.ALLOW,
+                requiresUserConfirmation: result.decision === PolicyDecision.ASK_USER,
+            });
+        }
+        catch (error) {
+            debugLogger.error('Error handling tool confirmation request:', error);
+            // Fail closed on exception
+            await this.context.config.getMessageBus()?.publish({
+                type: MessageBusType.TOOL_CONFIRMATION_RESPONSE,
+                correlationId: request.correlationId,
+                confirmed: false,
+                requiresUserConfirmation: false,
+            });
+        }
+    };
+    handleApprovalModeChanged = (payload) => {
+        if (payload.sessionId === this.id) {
+            void this.sendUpdate({
+                sessionUpdate: 'agent_message_chunk',
+                content: {
+                    type: 'text',
+                    text: `[MODE_UPDATE] ${payload.mode}`,
+                },
+            });
+        }
+    };
+    dispose() {
+        coreEvents.off(CoreEvent.ApprovalModeChanged, this.handleApprovalModeChanged);
+        this.disposeController.abort();
+    }
+    async cancelPendingPrompt() {
+        if (!this.pendingPrompt) {
+            throw new Error('Not currently generating');
+        }
+        this.pendingPrompt.abort();
+        this.pendingPrompt = null;
+    }
+    setMode(modeId) {
+        const availableModes = buildAvailableModes(this.context.config.isPlanEnabled());
+        const mode = availableModes.find((m) => m.id === modeId);
+        if (!mode) {
+            throw new Error(`Invalid or unavailable mode: ${modeId}`);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        this.context.config.setApprovalMode(mode.id);
+        return {};
+    }
+    getAvailableCommands() {
+        return this.commandHandler.getAvailableCommands();
+    }
+    async sendAvailableCommands() {
+        const availableCommands = this.getAvailableCommands().map((command) => ({
+            name: command.name,
+            description: command.description,
+        }));
+        await this.sendUpdate({
+            sessionUpdate: 'available_commands_update',
+            availableCommands,
+        });
+    }
+    setModel(modelId) {
+        this.context.config.setModel(modelId);
+        return {};
+    }
+    async streamHistory(messages) {
+        for (const msg of messages) {
+            const contentString = partListUnionToString(msg.content);
+            if (msg.type === 'user') {
+                if (contentString.trim()) {
+                    await this.sendUpdate({
+                        sessionUpdate: 'user_message_chunk',
+                        content: { type: 'text', text: contentString },
+                    });
+                }
+            }
+            else if (msg.type === 'gemini') {
+                // Thoughts
+                if (msg.thoughts) {
+                    for (const thought of msg.thoughts) {
+                        const thoughtText = `**${thought.subject}**\n${thought.description}`;
+                        await this.sendUpdate({
+                            sessionUpdate: 'agent_thought_chunk',
+                            content: { type: 'text', text: thoughtText },
+                        });
+                    }
+                }
+                // Message text
+                if (contentString.trim()) {
+                    await this.sendUpdate({
+                        sessionUpdate: 'agent_message_chunk',
+                        content: { type: 'text', text: contentString },
+                    });
+                }
+                // Tool calls
+                if (msg.toolCalls) {
+                    for (const toolCall of msg.toolCalls) {
+                        const toolCallContent = [];
+                        if (toolCall.resultDisplay) {
+                            if (typeof toolCall.resultDisplay === 'string') {
+                                toolCallContent.push({
+                                    type: 'content',
+                                    content: { type: 'text', text: toolCall.resultDisplay },
+                                });
+                            }
+                            else if ('fileName' in toolCall.resultDisplay) {
+                                toolCallContent.push({
+                                    type: 'diff',
+                                    path: toolCall.resultDisplay.fileName,
+                                    oldText: toolCall.resultDisplay.originalContent,
+                                    newText: toolCall.resultDisplay.newContent,
+                                });
+                            }
+                        }
+                        const tool = this.context.toolRegistry.getTool(toolCall.name);
+                        await this.sendUpdate({
+                            sessionUpdate: 'tool_call',
+                            toolCallId: toolCall.id,
+                            status: toolCall.status === CoreToolCallStatus.Success
+                                ? 'completed'
+                                : 'failed',
+                            title: toolCall.displayName || toolCall.name,
+                            content: toolCallContent,
+                            kind: tool ? toAcpToolKind(tool.kind) : 'other',
+                        });
+                    }
+                }
+            }
+        }
+    }
+    async prompt(params) {
+        this.pendingPrompt?.abort();
+        const pendingSend = new AbortController();
+        this.pendingPrompt = pendingSend;
+        await this.context.config.waitForMcpInit();
+        const promptId = Math.random().toString(16).slice(2);
+        const parts = await this.#resolvePrompt(params.prompt, pendingSend.signal);
+        // Command interception
+        let commandText = '';
+        for (const part of parts) {
+            if (typeof part === 'object' && part !== null) {
+                if (isTextPart(part)) {
+                    // It is a text part
+                    const text = part.text;
+                    commandText += text;
+                }
+                else {
+                    // Non-text part (image, embedded resource)
+                    // Stop looking for command
+                    break;
+                }
+            }
+        }
+        commandText = commandText.trim();
+        if (commandText &&
+            (commandText.startsWith('/') || commandText.startsWith('$'))) {
+            // If we found a command, pass it to handleCommand
+            // Note: handleCommand currently expects `commandText` to be the command string
+            // It uses `parts` argument but effectively ignores it in current implementation
+            const handled = await this.handleCommand(commandText, parts);
+            if (handled) {
+                return {
+                    stopReason: 'end_turn',
+                    _meta: {
+                        quota: {
+                            token_count: { input_tokens: 0, output_tokens: 0 },
+                            model_usage: [],
+                        },
+                    },
+                };
+            }
+        }
+        let totalInputTokens = 0;
+        let totalOutputTokens = 0;
+        const modelUsageMap = new Map();
+        let currentParts = parts;
+        let turnCount = 0;
+        const maxTurns = this.context.config.getMaxSessionTurns();
+        while (true) {
+            turnCount++;
+            if (maxTurns >= 0 && turnCount > maxTurns) {
+                return {
+                    stopReason: 'max_turn_requests',
+                    _meta: {
+                        quota: {
+                            token_count: {
+                                input_tokens: totalInputTokens,
+                                output_tokens: totalOutputTokens,
+                            },
+                            model_usage: Array.from(modelUsageMap.entries()).map(([modelName, counts]) => ({
+                                model: modelName,
+                                token_count: {
+                                    input_tokens: counts.input,
+                                    output_tokens: counts.output,
+                                },
+                            })),
+                        },
+                    },
+                };
+            }
+            if (pendingSend.signal.aborted) {
+                return { stopReason: 'cancelled' };
+            }
+            const toolCallRequests = [];
+            let stopReason = 'end_turn';
+            let turnModelId = this.context.config.getModel();
+            let turnInputTokens = 0;
+            let turnOutputTokens = 0;
+            try {
+                const responseStream = this.context.geminiClient.sendMessageStream(currentParts, pendingSend.signal, promptId);
+                for await (const event of responseStream) {
+                    if (pendingSend.signal.aborted) {
+                        return { stopReason: 'cancelled' };
+                    }
+                    switch (event.type) {
+                        case GeminiEventType.Content: {
+                            const content = {
+                                type: 'text',
+                                text: event.value,
+                            };
+                            await this.sendUpdate({
+                                sessionUpdate: 'agent_message_chunk',
+                                content,
+                            });
+                            break;
+                        }
+                        case GeminiEventType.Thought: {
+                            const thoughtText = `**${event.value.subject}**\n${event.value.description}`;
+                            await this.sendUpdate({
+                                sessionUpdate: 'agent_thought_chunk',
+                                content: { type: 'text', text: thoughtText },
+                            });
+                            break;
+                        }
+                        case GeminiEventType.ToolCallRequest:
+                            toolCallRequests.push(event.value);
+                            break;
+                        case GeminiEventType.Finished: {
+                            const usage = event.value.usageMetadata;
+                            if (usage) {
+                                turnInputTokens = usage.promptTokenCount ?? turnInputTokens;
+                                turnOutputTokens =
+                                    usage.candidatesTokenCount ?? turnOutputTokens;
+                            }
+                            break;
+                        }
+                        case GeminiEventType.ModelInfo:
+                            turnModelId = event.value;
+                            break;
+                        case GeminiEventType.MaxSessionTurns:
+                            stopReason = 'max_turn_requests';
+                            break;
+                        case GeminiEventType.LoopDetected:
+                            stopReason = 'max_turn_requests';
+                            break;
+                        case GeminiEventType.ContextWindowWillOverflow:
+                            stopReason = 'max_tokens';
+                            break;
+                        case GeminiEventType.Error: {
+                            const parseResult = StructuredErrorSchema.safeParse(event.value.error);
+                            const errData = parseResult.success ? parseResult.data : {};
+                            throw new acp.RequestError(errData.status ?? 500, errData.message ?? 'Unknown stream execution error.');
+                        }
+                        default:
+                            break;
+                    }
+                }
+            }
+            catch (error) {
+                if (getErrorStatus(error) === 429) {
+                    throw new acp.RequestError(429, 'Rate limit exceeded. Try again later.');
+                }
+                if (pendingSend.signal.aborted ||
+                    (error instanceof Error && error.name === 'AbortError')) {
+                    return { stopReason: 'cancelled' };
+                }
+                if (error instanceof acp.RequestError) {
+                    throw error;
+                }
+                if (error instanceof InvalidStreamError ||
+                    (error &&
+                        typeof error === 'object' &&
+                        'type' in error &&
+                        (error.type === 'NO_RESPONSE_TEXT' ||
+                            error.type === 'NO_FINISH_REASON' ||
+                            error.type === 'MALFORMED_FUNCTION_CALL' ||
+                            error.type === 'UNEXPECTED_TOOL_CALL'))) {
+                    // The stream ended with an empty response or malformed tool call.
+                    // Treat this as a graceful end to the model's turn rather than a crash.
+                    return {
+                        stopReason: 'end_turn',
+                        _meta: {
+                            quota: {
+                                token_count: {
+                                    input_tokens: totalInputTokens,
+                                    output_tokens: totalOutputTokens,
+                                },
+                                model_usage: Array.from(modelUsageMap.entries()).map(([modelName, counts]) => ({
+                                    model: modelName,
+                                    token_count: {
+                                        input_tokens: counts.input,
+                                        output_tokens: counts.output,
+                                    },
+                                })),
+                            },
+                        },
+                    };
+                }
+                throw new acp.RequestError(getErrorStatus(error) || 500, getAcpErrorMessage(error));
+            }
+            totalInputTokens += turnInputTokens;
+            totalOutputTokens += turnOutputTokens;
+            if (turnInputTokens > 0 || turnOutputTokens > 0) {
+                const existing = modelUsageMap.get(turnModelId) ?? {
+                    input: 0,
+                    output: 0,
+                };
+                existing.input += turnInputTokens;
+                existing.output += turnOutputTokens;
+                modelUsageMap.set(turnModelId, existing);
+            }
+            if (stopReason !== 'end_turn') {
+                return {
+                    stopReason,
+                    _meta: {
+                        quota: {
+                            token_count: {
+                                input_tokens: totalInputTokens,
+                                output_tokens: totalOutputTokens,
+                            },
+                            model_usage: Array.from(modelUsageMap.entries()).map(([modelName, counts]) => ({
+                                model: modelName,
+                                token_count: {
+                                    input_tokens: counts.input,
+                                    output_tokens: counts.output,
+                                },
+                            })),
+                        },
+                    },
+                };
+            }
+            if (toolCallRequests.length === 0) {
+                break;
+            }
+            const toolResponseParts = [];
+            for (const tReq of toolCallRequests) {
+                const fc = {
+                    id: tReq.callId,
+                    name: tReq.name,
+                    args: tReq.args,
+                };
+                const response = await this.runTool(pendingSend.signal, promptId, fc);
+                toolResponseParts.push(...response);
+            }
+            currentParts = toolResponseParts;
+        }
+        const modelUsageArray = Array.from(modelUsageMap.entries()).map(([modelName, counts]) => ({
+            model: modelName,
+            token_count: {
+                input_tokens: counts.input,
+                output_tokens: counts.output,
+            },
+        }));
+        return {
+            stopReason: 'end_turn',
+            _meta: {
+                quota: {
+                    token_count: {
+                        input_tokens: totalInputTokens,
+                        output_tokens: totalOutputTokens,
+                    },
+                    model_usage: modelUsageArray,
+                },
+            },
+        };
+    }
+    async handleCommand(commandText, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    parts) {
+        const gitService = await this.context.config.getGitService();
+        const commandContext = {
+            agentContext: this.context,
+            settings: this.settings,
+            git: gitService,
+            sendMessage: async (text) => {
+                await this.sendUpdate({
+                    sessionUpdate: 'agent_message_chunk',
+                    content: { type: 'text', text },
+                });
+            },
+        };
+        return this.commandHandler.handleCommand(commandText, commandContext);
+    }
+    async sendUpdate(update) {
+        const params = {
+            sessionId: this.id,
+            update,
+        };
+        await this.connection.sessionUpdate(params);
+    }
+    async runTool(abortSignal, promptId, fc) {
+        const callId = fc.id ?? this.generateCallId(fc.name || 'unknown');
+        const args = fc.args ?? {};
+        const startTime = Date.now();
+        const errorResponse = (error) => {
+            const durationMs = Date.now() - startTime;
+            logToolCall(this.context.config, new ToolCallEvent(undefined, fc.name ?? '', args, durationMs, false, promptId, typeof tool !== 'undefined' && tool instanceof DiscoveredMCPTool
+                ? 'mcp'
+                : 'native', error.message));
+            return [
+                {
+                    functionResponse: {
+                        id: callId,
+                        name: fc.name ?? '',
+                        response: { error: error.message },
+                    },
+                },
+            ];
+        };
+        if (!fc.name) {
+            return errorResponse(new Error('Missing function name'));
+        }
+        const toolRegistry = this.context.toolRegistry;
+        const tool = toolRegistry.getTool(fc.name);
+        if (!tool) {
+            return errorResponse(new Error(`Tool "${fc.name}" not found in registry.`));
+        }
+        try {
+            const invocation = tool.build(args);
+            const displayTitle = typeof invocation.getDisplayTitle === 'function'
+                ? invocation.getDisplayTitle()
+                : invocation.getDescription();
+            const explanation = typeof invocation.getExplanation === 'function'
+                ? invocation.getExplanation()
+                : '';
+            const confirmationDetails = await invocation.shouldConfirmExecute(abortSignal);
+            if (confirmationDetails) {
+                const content = [];
+                if (confirmationDetails.type === 'edit') {
+                    content.push({
+                        type: 'diff',
+                        path: confirmationDetails.filePath,
+                        oldText: confirmationDetails.originalContent,
+                        newText: confirmationDetails.newContent,
+                        _meta: {
+                            kind: !confirmationDetails.originalContent
+                                ? 'add'
+                                : confirmationDetails.newContent === ''
+                                    ? 'delete'
+                                    : 'modify',
+                        },
+                    });
+                }
+                if (content.length === 0 && explanation) {
+                    content.push({
+                        type: 'content',
+                        content: { type: 'text', text: explanation },
+                    });
+                }
+                const params = {
+                    sessionId: this.id,
+                    options: toPermissionOptions(confirmationDetails, this.context.config, this.settings.merged.security.enablePermanentToolApproval),
+                    toolCall: {
+                        toolCallId: callId,
+                        status: 'pending',
+                        title: displayTitle,
+                        content,
+                        locations: invocation.toolLocations(),
+                        kind: toAcpToolKind(tool.kind),
+                    },
+                };
+                const output = RequestPermissionResponseSchema.parse(await this.connection.requestPermission(params));
+                const outcome = output.outcome.outcome === 'cancelled'
+                    ? ToolConfirmationOutcome.Cancel
+                    : z
+                        .nativeEnum(ToolConfirmationOutcome)
+                        .parse(output.outcome.optionId);
+                await confirmationDetails.onConfirm(outcome);
+                // Update policy to enable Always Allow persistence
+                await updatePolicy(tool, outcome, confirmationDetails, this.context, this.context.messageBus, invocation);
+                switch (outcome) {
+                    case ToolConfirmationOutcome.Cancel:
+                        return errorResponse(new Error(`Tool "${fc.name}" was canceled by the user.`));
+                    case ToolConfirmationOutcome.ProceedOnce:
+                    case ToolConfirmationOutcome.ProceedAlways:
+                    case ToolConfirmationOutcome.ProceedAlwaysAndSave:
+                    case ToolConfirmationOutcome.ProceedAlwaysServer:
+                    case ToolConfirmationOutcome.ProceedAlwaysTool:
+                    case ToolConfirmationOutcome.ModifyWithEditor:
+                        break;
+                    default: {
+                        const resultOutcome = outcome;
+                        throw new Error(`Unexpected: ${resultOutcome}`);
+                    }
+                }
+            }
+            else {
+                const content = [];
+                if (explanation) {
+                    content.push({
+                        type: 'content',
+                        content: { type: 'text', text: explanation },
+                    });
+                }
+                await this.sendUpdate({
+                    sessionUpdate: 'tool_call',
+                    toolCallId: callId,
+                    status: 'in_progress',
+                    title: displayTitle,
+                    content,
+                    locations: invocation.toolLocations(),
+                    kind: toAcpToolKind(tool.kind),
+                });
+            }
+            const toolResult = await invocation.execute({
+                abortSignal,
+            });
+            const content = toToolCallContent(toolResult);
+            const updateContent = content ? [content] : [];
+            await this.sendUpdate({
+                sessionUpdate: 'tool_call_update',
+                toolCallId: callId,
+                status: 'completed',
+                title: displayTitle,
+                content: updateContent,
+                locations: invocation.toolLocations(),
+                kind: toAcpToolKind(tool.kind),
+            });
+            const durationMs = Date.now() - startTime;
+            logToolCall(this.context.config, new ToolCallEvent(undefined, fc.name ?? '', args, durationMs, true, promptId, typeof tool !== 'undefined' && tool instanceof DiscoveredMCPTool
+                ? 'mcp'
+                : 'native'));
+            this.chat.recordCompletedToolCalls(this.context.config.getActiveModel(), [
+                {
+                    status: CoreToolCallStatus.Success,
+                    request: {
+                        callId,
+                        name: fc.name,
+                        args,
+                        isClientInitiated: false,
+                        prompt_id: promptId,
+                    },
+                    tool,
+                    invocation,
+                    response: {
+                        callId,
+                        responseParts: convertToFunctionResponse(fc.name, callId, toolResult.llmContent, this.context.config.getActiveModel(), this.context.config),
+                        resultDisplay: toolResult.returnDisplay,
+                        error: undefined,
+                        errorType: undefined,
+                    },
+                },
+            ]);
+            return convertToFunctionResponse(fc.name, callId, toolResult.llmContent, this.context.config.getActiveModel(), this.context.config);
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            await this.sendUpdate({
+                sessionUpdate: 'tool_call_update',
+                toolCallId: callId,
+                status: 'failed',
+                content: [
+                    { type: 'content', content: { type: 'text', text: error.message } },
+                ],
+                kind: toAcpToolKind(tool.kind),
+            });
+            this.chat.recordCompletedToolCalls(this.context.config.getActiveModel(), [
+                {
+                    status: CoreToolCallStatus.Error,
+                    request: {
+                        callId,
+                        name: fc.name,
+                        args,
+                        isClientInitiated: false,
+                        prompt_id: promptId,
+                    },
+                    tool,
+                    response: {
+                        callId,
+                        responseParts: [
+                            {
+                                functionResponse: {
+                                    id: callId,
+                                    name: fc.name ?? '',
+                                    response: { error: error.message },
+                                },
+                            },
+                        ],
+                        resultDisplay: error.message,
+                        error,
+                        errorType: undefined,
+                    },
+                },
+            ]);
+            return errorResponse(error);
+        }
+    }
+    async #resolvePrompt(message, abortSignal) {
+        const FILE_URI_SCHEME = 'file://';
+        const embeddedContext = [];
+        const parts = message.map((part) => {
+            switch (part.type) {
+                case 'text':
+                    return { text: part.text };
+                case 'image':
+                case 'audio':
+                    return {
+                        inlineData: {
+                            mimeType: part.mimeType,
+                            data: part.data,
+                        },
+                    };
+                case 'resource_link': {
+                    if (part.uri.startsWith(FILE_URI_SCHEME)) {
+                        return {
+                            fileData: {
+                                mimeData: part.mimeType,
+                                name: part.name,
+                                fileUri: part.uri.slice(FILE_URI_SCHEME.length),
+                            },
+                        };
+                    }
+                    else {
+                        return { text: `@${part.uri}` };
+                    }
+                }
+                case 'resource': {
+                    embeddedContext.push(part.resource);
+                    return { text: `@${part.resource.uri}` };
+                }
+                default: {
+                    const unreachable = part;
+                    throw new Error(`Unexpected chunk type: '${unreachable}'`);
+                }
+            }
+        });
+        const atPathCommandParts = parts.filter((part) => 'fileData' in part);
+        if (atPathCommandParts.length === 0 && embeddedContext.length === 0) {
+            return parts;
+        }
+        const atPathToResolvedSpecMap = new Map();
+        // Get centralized file discovery service
+        const fileDiscovery = this.context.config.getFileService();
+        const fileFilteringOptions = this.context.config.getFileFilteringOptions();
+        const pathSpecsToRead = [];
+        const contentLabelsForDisplay = [];
+        const ignoredPaths = [];
+        const directContents = [];
+        const toolRegistry = this.context.toolRegistry;
+        const readManyFilesTool = new ReadManyFilesTool(this.context.config, this.context.messageBus);
+        const globTool = toolRegistry.getTool('glob');
+        if (!readManyFilesTool) {
+            throw new Error('Error: read_many_files tool not found.');
+        }
+        for (const atPathPart of atPathCommandParts) {
+            const pathName = atPathPart.fileData.fileUri;
+            // Check if path should be ignored
+            if (fileDiscovery.shouldIgnoreFile(pathName, fileFilteringOptions)) {
+                ignoredPaths.push(pathName);
+                debugLogger.warn(`Path ${pathName} is ignored and will be skipped.`);
+                continue;
+            }
+            let currentPathSpec = pathName;
+            let resolvedSuccessfully = false;
+            let readDirectly = false;
+            const result = await resolveAtCommandPath(pathName, this.context.config, (msg) => this.debug(msg));
+            let validationError = null;
+            let absolutePath;
+            let resolved;
+            if (result.status === 'resolved') {
+                resolved = result.resolved;
+                absolutePath = resolved.absolutePath;
+            }
+            else if (result.status === 'unauthorized') {
+                absolutePath = result.absolutePath;
+                validationError = result.error;
+            }
+            else if (result.status === 'invalid') {
+                // Already logged in resolveAtCommandPath
+                continue;
+            }
+            else {
+                // Result is not_found.
+                // We still check if it's an unauthorized absolute path that we can ask permission for,
+                // specifically for paths that are completely outside the root and not even in any workspace directory.
+                // For relative paths not found anywhere, we resolve relative to targetDir for permission check.
+                absolutePath = path.resolve(this.context.config.getTargetDir(), pathName);
+            }
+            if (!resolved &&
+                validationError &&
+                !isWithinRoot(absolutePath, this.context.config.getTargetDir())) {
+                try {
+                    const stats = await fs.stat(absolutePath);
+                    if (stats.isFile()) {
+                        const syntheticCallId = `resolve-prompt-${pathName}-${randomUUID()}`;
+                        const params = {
+                            sessionId: this.id,
+                            options: [
+                                {
+                                    optionId: ToolConfirmationOutcome.ProceedOnce,
+                                    name: 'Allow once',
+                                    kind: 'allow_once',
+                                },
+                                {
+                                    optionId: ToolConfirmationOutcome.Cancel,
+                                    name: 'Deny',
+                                    kind: 'reject_once',
+                                },
+                            ],
+                            toolCall: {
+                                toolCallId: syntheticCallId,
+                                status: 'pending',
+                                title: `Allow access to absolute path: ${pathName}`,
+                                content: [
+                                    {
+                                        type: 'content',
+                                        content: {
+                                            type: 'text',
+                                            text: `The Agent needs access to read an attached file outside your workspace: ${pathName}`,
+                                        },
+                                    },
+                                ],
+                                locations: [],
+                                kind: 'read',
+                            },
+                        };
+                        const output = RequestPermissionResponseSchema.parse(await this.connection.requestPermission(params));
+                        const outcome = output.outcome.outcome === 'cancelled'
+                            ? ToolConfirmationOutcome.Cancel
+                            : z
+                                .nativeEnum(ToolConfirmationOutcome)
+                                .parse(output.outcome.optionId);
+                        if (outcome === ToolConfirmationOutcome.ProceedOnce) {
+                            this.context.config
+                                .getWorkspaceContext()
+                                .addReadOnlyPath(absolutePath);
+                            validationError = null;
+                        }
+                        else {
+                            this.debug(`Direct read authorization denied for absolute path ${pathName}`);
+                            directContents.push({
+                                spec: pathName,
+                                content: `[Warning: Access to absolute path \`${pathName}\` denied by user.]`,
+                            });
+                            continue;
+                        }
+                    }
+                }
+                catch (error) {
+                    this.debug(`Failed to request permission for absolute attachment ${pathName}: ${getErrorMessage(error)}`);
+                    await this.sendUpdate({
+                        sessionUpdate: 'agent_thought_chunk',
+                        content: {
+                            type: 'text',
+                            text: `Warning: Failed to display permission dialog for \`${absolutePath}\`. Error: ${getErrorMessage(error)}`,
+                        },
+                    });
+                }
+            }
+            try {
+                if (!validationError) {
+                    // If it's an absolute path that is authorized (e.g. added via readOnlyPaths),
+                    // read it directly to avoid ReadManyFilesTool absolute path resolution issues.
+                    if ((path.isAbsolute(pathName) ||
+                        !isWithinRoot(absolutePath, this.context.config.getTargetDir())) &&
+                        !readDirectly) {
+                        try {
+                            const stats = resolved
+                                ? resolved.stats
+                                : await fs.stat(absolutePath);
+                            if (stats.isFile()) {
+                                const fileReadResult = await processSingleFileContent(absolutePath, this.context.config.getTargetDir(), this.context.config.getFileSystemService());
+                                if (!fileReadResult.error) {
+                                    if (typeof fileReadResult.llmContent === 'object' &&
+                                        'inlineData' in fileReadResult.llmContent) {
+                                        directContents.push({
+                                            spec: pathName,
+                                            part: fileReadResult.llmContent,
+                                        });
+                                    }
+                                    else if (typeof fileReadResult.llmContent === 'string') {
+                                        let contentToPush = fileReadResult.llmContent;
+                                        if (fileReadResult.isTruncated) {
+                                            contentToPush = `[WARNING: This file was truncated]\n\n${contentToPush}`;
+                                        }
+                                        directContents.push({
+                                            spec: pathName,
+                                            content: contentToPush,
+                                        });
+                                    }
+                                    readDirectly = true;
+                                    resolvedSuccessfully = true;
+                                }
+                                else {
+                                    this.debug(`Direct read failed for absolute path ${pathName}: ${fileReadResult.error}`);
+                                    await this.sendUpdate({
+                                        sessionUpdate: 'agent_thought_chunk',
+                                        content: {
+                                            type: 'text',
+                                            text: `Warning: file read failed for \`${pathName}\`. Reason: ${fileReadResult.error}`,
+                                        },
+                                    });
+                                    continue;
+                                }
+                            }
+                        }
+                        catch (error) {
+                            this.debug(`File stat/access error for absolute path ${pathName}: ${getErrorMessage(error)}`);
+                            await this.sendUpdate({
+                                sessionUpdate: 'agent_thought_chunk',
+                                content: {
+                                    type: 'text',
+                                    text: `Warning: file access failed for \`${pathName}\`. Reason: ${getErrorMessage(error)}`,
+                                },
+                            });
+                            continue;
+                        }
+                    }
+                    if (!readDirectly) {
+                        const stats = resolved
+                            ? resolved.stats
+                            : await fs.stat(absolutePath);
+                        if (stats.isDirectory()) {
+                            currentPathSpec = pathName.endsWith('/')
+                                ? `${pathName}**`
+                                : `${pathName}/**`;
+                            this.debug(`Path ${pathName} resolved to directory, using glob: ${currentPathSpec}`);
+                        }
+                        else {
+                            this.debug(`Path ${pathName} resolved to file: ${currentPathSpec}`);
+                        }
+                        resolvedSuccessfully = true;
+                    }
+                }
+                else {
+                    this.debug(`Path ${pathName} access disallowed: ${validationError}. Skipping.`);
+                    await this.sendUpdate({
+                        sessionUpdate: 'agent_thought_chunk',
+                        content: {
+                            type: 'text',
+                            text: `Warning: skipping access to \`${pathName}\`. Reason: ${validationError}`,
+                        },
+                    });
+                }
+            }
+            catch (error) {
+                if (isNodeError(error) && error.code === 'ENOENT') {
+                    if (this.context.config.getEnableRecursiveFileSearch() && globTool) {
+                        this.debug(`Path ${pathName} not found directly, attempting glob search.`);
+                        try {
+                            const globResult = await globTool.buildAndExecute({
+                                pattern: `**/*${pathName}*`,
+                                path: this.context.config.getTargetDir(),
+                            }, abortSignal);
+                            if (globResult.llmContent &&
+                                typeof globResult.llmContent === 'string' &&
+                                !globResult.llmContent.startsWith('No files found') &&
+                                !globResult.llmContent.startsWith('Error:')) {
+                                const lines = globResult.llmContent.split('\n');
+                                if (lines.length > 1 && lines[1]) {
+                                    const firstMatchAbsolute = lines[1].trim();
+                                    currentPathSpec = path.relative(this.context.config.getTargetDir(), firstMatchAbsolute);
+                                    this.debug(`Glob search for ${pathName} found ${firstMatchAbsolute}, using relative path: ${currentPathSpec}`);
+                                    resolvedSuccessfully = true;
+                                }
+                                else {
+                                    this.debug(`Glob search for '**/*${pathName}*' did not return a usable path. Path ${pathName} will be skipped.`);
+                                }
+                            }
+                            else {
+                                this.debug(`Glob search for '**/*${pathName}*' found no files or an error. Path ${pathName} will be skipped.`);
+                            }
+                        }
+                        catch (globError) {
+                            debugLogger.error(`Error during glob search for ${pathName}: ${getErrorMessage(globError)}`);
+                        }
+                    }
+                    else {
+                        this.debug(`Glob tool not found. Path ${pathName} will be skipped.`);
+                    }
+                }
+                else {
+                    debugLogger.error(`Error stating path ${pathName}. Path ${pathName} will be skipped.`);
+                }
+            }
+            if (resolvedSuccessfully) {
+                if (!readDirectly) {
+                    pathSpecsToRead.push(currentPathSpec);
+                }
+                atPathToResolvedSpecMap.set(pathName, currentPathSpec);
+                contentLabelsForDisplay.push(pathName);
+            }
+        }
+        // Construct the initial part of the query for the LLM
+        let initialQueryText = '';
+        for (let i = 0; i < parts.length; i++) {
+            const chunk = parts[i];
+            if ('text' in chunk) {
+                initialQueryText += chunk.text;
+            }
+            else {
+                // type === 'atPath'
+                const resolvedSpec = chunk.fileData && atPathToResolvedSpecMap.get(chunk.fileData.fileUri);
+                if (i > 0 &&
+                    initialQueryText.length > 0 &&
+                    !initialQueryText.endsWith(' ') &&
+                    resolvedSpec) {
+                    // Add space if previous part was text and didn't end with space, or if previous was @path
+                    const prevPart = parts[i - 1];
+                    if ('text' in prevPart ||
+                        ('fileData' in prevPart &&
+                            atPathToResolvedSpecMap.has(prevPart.fileData.fileUri))) {
+                        initialQueryText += ' ';
+                    }
+                }
+                if (resolvedSpec) {
+                    initialQueryText += `@${resolvedSpec}`;
+                }
+                else {
+                    // If not resolved for reading (e.g. lone @ or invalid path that was skipped),
+                    // add the original @-string back, ensuring spacing if it's not the first element.
+                    if (i > 0 &&
+                        initialQueryText.length > 0 &&
+                        !initialQueryText.endsWith(' ') &&
+                        !chunk.fileData?.fileUri.startsWith(' ')) {
+                        initialQueryText += ' ';
+                    }
+                    if (chunk.fileData?.fileUri) {
+                        initialQueryText += `@${chunk.fileData.fileUri}`;
+                    }
+                }
+            }
+        }
+        initialQueryText = initialQueryText.trim();
+        // Inform user about ignored paths
+        if (ignoredPaths.length > 0) {
+            this.debug(`Ignored ${ignoredPaths.length} files: ${ignoredPaths.join(', ')}`);
+        }
+        const processedQueryParts = [{ text: initialQueryText }];
+        if (pathSpecsToRead.length === 0 &&
+            embeddedContext.length === 0 &&
+            directContents.length === 0) {
+            // Fallback for lone "@" or completely invalid @-commands resulting in empty initialQueryText
+            debugLogger.warn('No valid file paths found in @ commands to read.');
+            return [{ text: initialQueryText }];
+        }
+        if (pathSpecsToRead.length > 0) {
+            const toolArgs = {
+                include: pathSpecsToRead,
+            };
+            const callId = this.generateCallId(readManyFilesTool.name);
+            try {
+                const invocation = readManyFilesTool.build(toolArgs);
+                await this.sendUpdate({
+                    sessionUpdate: 'tool_call',
+                    toolCallId: callId,
+                    status: 'in_progress',
+                    title: invocation.getDescription(),
+                    content: [],
+                    locations: invocation.toolLocations(),
+                    kind: toAcpToolKind(readManyFilesTool.kind),
+                });
+                const result = await invocation.execute({ abortSignal });
+                const content = toToolCallContent(result) || {
+                    type: 'content',
+                    content: {
+                        type: 'text',
+                        text: `Successfully read: ${contentLabelsForDisplay.join(', ')}`,
+                    },
+                };
+                await this.sendUpdate({
+                    sessionUpdate: 'tool_call_update',
+                    toolCallId: callId,
+                    status: 'completed',
+                    title: invocation.getDescription(),
+                    content: content ? [content] : [],
+                    locations: invocation.toolLocations(),
+                    kind: toAcpToolKind(readManyFilesTool.kind),
+                });
+                if (Array.isArray(result.llmContent)) {
+                    const fileContentRegex = /^--- (.*?) ---\n\n([\s\S]*?)\n\n$/;
+                    processedQueryParts.push({
+                        text: `\n${REFERENCE_CONTENT_START}`,
+                    });
+                    for (const part of result.llmContent) {
+                        if (typeof part === 'string') {
+                            const match = fileContentRegex.exec(part);
+                            if (match) {
+                                const filePathSpecInContent = match[1]; // This is a resolved pathSpec
+                                const fileActualContent = match[2].trim();
+                                processedQueryParts.push({
+                                    text: `\nContent from @${filePathSpecInContent}:\n`,
+                                });
+                                processedQueryParts.push({ text: fileActualContent });
+                            }
+                            else {
+                                processedQueryParts.push({ text: part });
+                            }
+                        }
+                        else {
+                            // part is a Part object.
+                            processedQueryParts.push(part);
+                        }
+                    }
+                }
+                else {
+                    debugLogger.warn('read_many_files tool returned no content or empty content.');
+                }
+            }
+            catch (error) {
+                await this.sendUpdate({
+                    sessionUpdate: 'tool_call_update',
+                    toolCallId: callId,
+                    status: 'failed',
+                    content: [
+                        {
+                            type: 'content',
+                            content: {
+                                type: 'text',
+                                text: `Error reading files (${contentLabelsForDisplay.join(', ')}): ${getErrorMessage(error)}`,
+                            },
+                        },
+                    ],
+                    kind: toAcpToolKind(readManyFilesTool.kind),
+                });
+                throw error;
+            }
+        }
+        if (directContents.length > 0) {
+            const hasReferenceStart = processedQueryParts.some((p) => 'text' in p &&
+                typeof p.text === 'string' &&
+                p.text.includes(REFERENCE_CONTENT_START));
+            if (!hasReferenceStart) {
+                processedQueryParts.push({
+                    text: `\n${REFERENCE_CONTENT_START}`,
+                });
+            }
+            for (const item of directContents) {
+                processedQueryParts.push({
+                    text: `\nContent from @${item.spec}:\n`,
+                });
+                if (item.content) {
+                    processedQueryParts.push({ text: item.content });
+                }
+                else if (item.part) {
+                    processedQueryParts.push(item.part);
+                }
+            }
+        }
+        if (embeddedContext.length > 0) {
+            processedQueryParts.push({
+                text: '\n--- Content from referenced context ---',
+            });
+            for (const contextPart of embeddedContext) {
+                processedQueryParts.push({
+                    text: `\nContent from @${contextPart.uri}:\n`,
+                });
+                if ('text' in contextPart) {
+                    processedQueryParts.push({
+                        text: contextPart.text,
+                    });
+                }
+                else {
+                    processedQueryParts.push({
+                        inlineData: {
+                            mimeType: contextPart.mimeType ?? 'application/octet-stream',
+                            data: contextPart.blob,
+                        },
+                    });
+                }
+            }
+        }
+        return processedQueryParts;
+    }
+    debug(msg) {
+        if (this.context.config.getDebugMode()) {
+            debugLogger.warn(msg);
+        }
+    }
+}