@theia/ai-ide 1.76.0-next.7 → 1.76.0

package/src/browser/commit-message-runner.ts

@@ -0,0 +1,163 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { Emitter, Event, ILogger, MessageService, nls } from '@theia/core';
+import { ConfirmDialog, Dialog } from '@theia/core/lib/browser/dialogs';
+import { CancellationTokenSource } from '@theia/core/lib/common/cancellation';
+import { inject, injectable, named } from '@theia/core/shared/inversify';
+import { ScmRepository } from '@theia/scm/lib/browser/scm-repository';
+import { ScmService } from '@theia/scm/lib/browser/scm-service';
+import { CommitMessageAgent } from './commit-message-agent';
+import { GetGitChangesTool } from './git-changes-tool';
+
+/**
+ * Drives the {@link CommitMessageAgent}: reads the staged git diff of the selected repository,
+ * asks the agent to turn it into a commit message and writes the result into that repository's
+ * SCM commit-message input.
+ *
+ * The diff is read by calling {@link GetGitChangesTool.getStagedChanges} directly rather than by
+ * letting the model call the tool: the agent is a plain (non-chat) agent with a single, fixed
+ * input, so there is no chat session, no tool-confirmation prompt and no chat-model bookkeeping.
+ * `git diff --cached` also renders staged additions of new files as complete addition diffs, so
+ * untracked files need no separate handling.
+ */
+@injectable()
+export class CommitMessageRunner {
+
+    @inject(CommitMessageAgent)
+    protected readonly commitMessageAgent: CommitMessageAgent;
+
+    @inject(GetGitChangesTool)
+    protected readonly gitChangesTool: GetGitChangesTool;
+
+    @inject(ScmService)
+    protected readonly scmService: ScmService;
+
+    @inject(MessageService)
+    protected readonly messageService: MessageService;
+
+    @inject(ILogger) @named('ai-ide:CommitMessageRunner')
+    protected readonly logger: ILogger;
+
+    /**
+     * Cancellation source of the in-flight generation, or `undefined` when idle. It is fired by
+     * {@link cancel} so a click on the spinning button cancels the run even while we are still in
+     * the pre-request phase (resolving the repository, fetching the diff, awaiting the overwrite
+     * confirmation). Once the LLM request is under way, the same token cancels it via
+     * {@link CommitMessageAgent.generateCommitMessage}.
+     */
+    protected current: CancellationTokenSource | undefined;
+
+    protected readonly onDidChangeEmitter = new Emitter<void>();
+    readonly onDidChange: Event<void> = this.onDidChangeEmitter.event;
+
+    isRunning(): boolean {
+        return !!this.current;
+    }
+
+    cancel(): void {
+        this.current?.cancel();
+    }
+
+    async run(): Promise<void> {
+        if (this.current) {
+            return;
+        }
+        const cts = new CancellationTokenSource();
+        this.current = cts;
+        this.onDidChangeEmitter.fire();
+
+        try {
+            const repository = this.scmService.selectedRepository;
+            if (!repository) {
+                // Deliberately not awaited: a dismissed toast never resolves, which would leave
+                // the button spinning forever.
+                this.messageService.warn(
+                    nls.localize('theia/ai-ide/commit-message/no-repository', 'No source-control repository is selected.')
+                );
+                return;
+            }
+
+            const changes = await this.gitChangesTool.getStagedChanges(repository, cts.token);
+            if (cts.token.isCancellationRequested) {
+                return;
+            }
+            if (!changes.trim()) {
+                this.messageService.warn(
+                    nls.localize('theia/ai-ide/commit-message/no-changes', 'There are no staged changes to generate a commit message from.')
+                );
+                return;
+            }
+
+            if (!(await this.confirmOverwrite(repository))) {
+                return;
+            }
+            if (cts.token.isCancellationRequested) {
+                return;
+            }
+
+            const message = await this.commitMessageAgent.generateCommitMessage(changes, cts.token);
+            if (cts.token.isCancellationRequested) {
+                return;
+            }
+            if (!message) {
+                this.messageService.warn(
+                    nls.localize('theia/ai-ide/commit-message/empty', 'The model returned an empty commit message.')
+                );
+                return;
+            }
+
+            repository.input.value = message;
+            repository.input.focus();
+        } catch (error) {
+            if (cts.token.isCancellationRequested) {
+                return;
+            }
+            this.logger.error('Failed to run commit-message agent', error);
+            this.notifyFailure(error instanceof Error ? error.message : String(error));
+        } finally {
+            this.current = undefined;
+            this.onDidChangeEmitter.fire();
+            cts.dispose();
+        }
+    }
+
+    protected notifyFailure(reason: string): void {
+        this.messageService.error(
+            nls.localize(
+                'theia/ai-ide/commit-message/failed',
+                'Failed to generate commit message: {0}',
+                reason
+            )
+        );
+    }
+
+    /** Returns `true` if the operation should proceed. */
+    protected async confirmOverwrite(repository: ScmRepository): Promise<boolean> {
+        if (!repository.input.value.trim()) {
+            return true;
+        }
+        return !!await new ConfirmDialog({
+            title: nls.localize('theia/ai-ide/commit-message/replace-title', 'Replace Commit Message'),
+            msg: nls.localize(
+                'theia/ai-ide/commit-message/replace-prompt',
+                'The commit message field is not empty. Replace its content with the generated message?'
+            ),
+            ok: nls.localizeByDefault('Replace'),
+            cancel: Dialog.CANCEL
+        }).open();
+    }
+}

package/src/browser/frontend-module.ts

@@ -95,7 +95,11 @@ import { ContextFilesVariableContribution } from '../common/context-files-variab
 import { TabBarToolbarContribution } from '@theia/core/lib/browser/shell/tab-bar-toolbar';
 import { TemplatePreferenceContribution } from './template-preference-contribution';
 import { ChatWelcomeMessageProvider } from '@theia/ai-chat-ui/lib/browser/chat-tree-view';
+import { WalkthroughProvider } from '@theia/getting-started/lib/common/walkthrough-provider';
 import { IdeChatWelcomeMessageProvider } from './ide-chat-welcome-message-provider';
+import { AiGettingStartedWalkthroughProvider } from './ai-getting-started-walkthrough';
+import { AiGettingStartedContribution } from './ai-getting-started-contribution';
+import { AiWalkthroughContextKeys } from './ai-walkthrough-context-keys';
 import { ChatSessionsWelcomeMessageProvider } from './chat-sessions-welcome-message-provider';
 import { ChatSessionItemActionContribution, DefaultChatSessionItemActionContribution } from './chat-session-item-action-contribution';
 import { AiAllowAllModeChatBanner } from './ai-allow-all-mode-chat-banner';
@@ -148,6 +152,12 @@ import { AIFirstPerspectiveContribution } from './ai-first-perspective-contribut
 import { ChatSessionListService } from './chat-session-list-service';
 import { AISessionsWidget } from './ai-sessions-widget';
 import { AISessionsViewContribution } from './ai-sessions-view-contribution';
+import { CommitMessageAgent } from './commit-message-agent';
+import { CommitMessageRunner } from './commit-message-runner';
+import { CommitMessageCommandContribution } from './commit-message-command-contribution';
+import { GetGitChangesTool } from './git-changes-tool';
+import { AiAwareScmCommitWidget } from './ai-aware-scm-commit-widget';
+import { ScmCommitWidget } from '@theia/scm/lib/browser/scm-commit-widget';
 
 export default new ContainerModule((bind, _unbind, _isBound, rebind) => {
     bind(PreferenceContribution).toConstantValue({ schema: aiIdePreferenceSchema });
@@ -217,6 +227,11 @@ export default new ContainerModule((bind, _unbind, _isBound, rebind) => {
 
     bind(ChatSessionListService).toSelf().inSingletonScope();
 
+    bind(WalkthroughProvider).to(AiGettingStartedWalkthroughProvider).inSingletonScope();
+    bind(CommandContribution).to(AiGettingStartedContribution).inSingletonScope();
+    bind(AiWalkthroughContextKeys).toSelf().inSingletonScope();
+    bind(FrontendApplicationContribution).toService(AiWalkthroughContextKeys);
+
     bind(ChatWelcomeMessageProvider).to(IdeChatWelcomeMessageProvider).inSingletonScope();
     bind(ChatWelcomeMessageProvider).to(ChatSessionsWelcomeMessageProvider).inSingletonScope();
     bind(ChatBannerProvider).to(AiAllowAllModeChatBanner).inSingletonScope();
@@ -386,4 +401,16 @@ export default new ContainerModule((bind, _unbind, _isBound, rebind) => {
         .inSingletonScope();
     bindViewContribution(bind, AISessionsViewContribution);
     bind(TabBarToolbarContribution).toService(AISessionsViewContribution);
+
+    // CommitMessageAgent is a plain (non-chat) `Agent`: it is driven exclusively from the SCM
+    // commit widget via `CommitMessageRunner`, so it does not appear in chat `@`-mention
+    // completion or the chat agent list. The `Agent` binding registers its prompt fragments
+    // with the prompt service.
+    bind(CommitMessageAgent).toSelf().inSingletonScope();
+    bind(Agent).toService(CommitMessageAgent);
+    bindToolProvider(GetGitChangesTool, bind);
+    bind(CommitMessageRunner).toSelf().inSingletonScope();
+    bind(CommitMessageCommandContribution).toSelf().inSingletonScope();
+    bind(CommandContribution).toService(CommitMessageCommandContribution);
+    rebind(ScmCommitWidget).to(AiAwareScmCommitWidget);
 });

package/src/browser/git-changes-tool.spec.ts

@@ -0,0 +1,200 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { enableJSDOM } from '@theia/core/lib/browser/test/jsdom';
+let disableJSDOM = enableJSDOM();
+import { FrontendApplicationConfigProvider } from '@theia/core/lib/browser/frontend-application-config-provider';
+FrontendApplicationConfigProvider.set({});
+
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+import { Container } from '@theia/core/shared/inversify';
+import URI from '@theia/core/lib/common/uri';
+import { WorkspaceService } from '@theia/workspace/lib/browser/workspace-service';
+import { ScmRepository } from '@theia/scm/lib/browser/scm-repository';
+import { ScmService } from '@theia/scm/lib/browser/scm-service';
+import { ShellExecutionRequest, ShellExecutionResult, ShellExecutionServer } from '@theia/ai-terminal/lib/common/shell-execution-server';
+import { GET_GIT_CHANGES_FUNCTION_ID, GetGitChangesTool, GitChangesRepositoryError } from './git-changes-tool';
+
+disableJSDOM();
+
+function shellResult(overrides: Partial<ShellExecutionResult> = {}): ShellExecutionResult {
+    return { success: true, exitCode: 0, stdout: 'staged diff', stderr: '', duration: 1, ...overrides };
+}
+
+function makeRepo(rootUri: string): ScmRepository {
+    return { provider: { rootUri } } as unknown as ScmRepository;
+}
+
+describe('GetGitChangesTool', () => {
+
+    let container: Container;
+    let shellServer: { execute: sinon.SinonStub; cancel: sinon.SinonStub };
+    let scmService: { repositories: ScmRepository[]; selectedRepository: ScmRepository | undefined };
+    let workspaceRoots: URI[];
+    let tool: GetGitChangesTool;
+
+    const backend = makeRepo('file:///work/backend');
+    const frontend = makeRepo('file:///work/frontend');
+    const nested = makeRepo('file:///work/backend/vendor/lib');
+
+    function cwdOfCall(index = 0): string | undefined {
+        return (shellServer.execute.getCall(index).args[0] as ShellExecutionRequest).cwd?.replace(/\\/g, '/');
+    }
+
+    before(() => {
+        disableJSDOM = enableJSDOM();
+    });
+
+    after(() => {
+        disableJSDOM();
+    });
+
+    beforeEach(() => {
+        container = new Container();
+        shellServer = { execute: sinon.stub().resolves(shellResult()), cancel: sinon.stub().resolves(true) };
+        workspaceRoots = [new URI('file:///work/backend'), new URI('file:///work/frontend')];
+        scmService = { repositories: [backend, frontend, nested], selectedRepository: frontend };
+        const workspaceService: Partial<WorkspaceService> = {
+            tryGetRoots: () => workspaceRoots.map(resource => ({ resource } as never))
+        };
+        container.bind(ShellExecutionServer).toConstantValue(shellServer as unknown as ShellExecutionServer);
+        container.bind(ScmService).toConstantValue(scmService as unknown as ScmService);
+        container.bind(WorkspaceService).toConstantValue(workspaceService as WorkspaceService);
+        container.bind(GetGitChangesTool).toSelf();
+        tool = container.get(GetGitChangesTool);
+    });
+
+    afterEach(() => sinon.restore());
+
+    it('exposes the well-known tool id getGitChanges with a repository parameter', () => {
+        const request = tool.getTool();
+        expect(request.id).to.equal(GET_GIT_CHANGES_FUNCTION_ID);
+        expect((request.parameters.properties.repository as { type: string }).type).to.equal('string');
+        expect(request.parameters.required ?? []).to.not.contain('repository');
+    });
+
+    it('runs a cross-platform "git diff --cached" with no POSIX-only shell operators', async () => {
+        await tool.getTool().handler('{}');
+        const command = (shellServer.execute.firstCall.args[0] as ShellExecutionRequest).command;
+        expect(command).to.equal('git diff --cached --no-color');
+        expect(command).to.not.match(/;|\||xargs|sh -c|\/dev\/null/);
+    });
+
+    it('falls back to the selected repository when no repository argument is given', async () => {
+        await tool.getTool().handler('{}');
+        expect(cwdOfCall()).to.equal('/work/frontend');
+    });
+
+    it('runs in the named repository rather than the selected one', async () => {
+        const result = await tool.getTool().handler(JSON.stringify({ repository: 'backend' })) as { output: string };
+        expect(result.output).to.equal('staged diff');
+        expect(cwdOfCall()).to.equal('/work/backend');
+    });
+
+    it('identifies a repository nested inside a workspace root by its relative path', async () => {
+        await tool.getTool().handler(JSON.stringify({ repository: 'backend/vendor/lib' }));
+        expect(cwdOfCall()).to.equal('/work/backend/vendor/lib');
+    });
+
+    it('labels the argument with the repository for the tool-call summary', () => {
+        const label = tool.getTool().getArgumentsShortLabel!(JSON.stringify({ repository: 'backend' }));
+        expect(label).to.deep.equal({ label: 'backend', hasMore: false });
+    });
+
+    it('accepts an absolute path and ignores separator and case differences', async () => {
+        await tool.getTool().handler(JSON.stringify({ repository: '/work/backend' }));
+        expect(cwdOfCall()).to.equal('/work/backend');
+
+        await tool.getTool().handler(JSON.stringify({ repository: 'BackEnd/' }));
+        expect(cwdOfCall(1)).to.equal('/work/backend');
+    });
+
+    it('reports the known repositories instead of running an unknown one', async () => {
+        const result = await tool.getTool().handler(JSON.stringify({ repository: '../../etc' })) as GitChangesRepositoryError;
+        expect(result.error).to.contain('../../etc');
+        expect(result.availableRepositories).to.deep.equal(['backend', 'frontend', 'backend/vendor/lib']);
+        expect(shellServer.execute.called).to.be.false;
+    });
+
+    it('reports an ambiguous folder name instead of picking the first matching repository', async () => {
+        const otherLib = makeRepo('file:///work/frontend/vendor/lib');
+        scmService.repositories = [backend, frontend, nested, otherLib];
+
+        const result = await tool.getTool().handler(JSON.stringify({ repository: 'lib' })) as GitChangesRepositoryError;
+        expect(result.error).to.contain('ambiguous');
+        expect(shellServer.execute.called).to.be.false;
+
+        await tool.getTool().handler(JSON.stringify({ repository: 'frontend/vendor/lib' }));
+        expect(cwdOfCall()).to.equal('/work/frontend/vendor/lib');
+    });
+
+    it('prefers an exact label match over a folder name shared with a nested repository', async () => {
+        const nestedBackend = makeRepo('file:///work/frontend/backend');
+        scmService.repositories = [backend, frontend, nestedBackend];
+
+        await tool.getTool().handler(JSON.stringify({ repository: 'backend' }));
+        expect(cwdOfCall()).to.equal('/work/backend');
+    });
+
+    it('never derives the working directory from the argument, only from the matched repository', async () => {
+        await tool.getTool().handler(JSON.stringify({ repository: 'backend; rm -rf /' }));
+        expect(shellServer.execute.called).to.be.false;
+    });
+
+    it('asks for a repository when none is named and none is selected', async () => {
+        scmService.selectedRepository = undefined;
+        const result = await tool.getTool().handler('{}') as GitChangesRepositoryError;
+        expect(result.error).to.contain('repository argument');
+        expect(shellServer.execute.called).to.be.false;
+    });
+
+    it('throws instead of returning the error output when the git command fails', async () => {
+        shellServer.execute.resolves(shellResult({
+            success: false,
+            exitCode: 128,
+            stdout: '',
+            stderr: 'fatal: not a git repository'
+        }));
+
+        let caught: Error | undefined;
+        try {
+            await tool.getStagedChanges(backend);
+        } catch (error) {
+            caught = error as Error;
+        }
+        expect(caught?.message).to.match(/fatal: not a git repository/);
+    });
+
+    it('returns an empty diff when the execution was canceled', async () => {
+        shellServer.execute.resolves(shellResult({ canceled: true, stdout: 'partial' }));
+        expect(await tool.getStagedChanges(backend)).to.equal('');
+    });
+
+    it('keeps far more diff lines than the default shellExecute budget', async () => {
+        const stdout = Array.from({ length: 600 }, (_unused, index) => `+line ${index}`).join('\n');
+        shellServer.execute.resolves(shellResult({ stdout }));
+
+        const diff = await tool.getStagedChanges(backend);
+
+        expect(diff).to.contain('+line 300');
+        expect(diff).to.not.contain('lines omitted');
+    });
+
+    it('does not declare checkAutoAction so confirmation flows through the normal ToolConfirmationManager', () => {
+        expect(tool.getTool().checkAutoAction).to.be.undefined;
+    });
+});

package/src/browser/git-changes-tool.ts

@@ -0,0 +1,239 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { CancellationToken } from '@theia/core';
+import URI from '@theia/core/lib/common/uri';
+import { inject, injectable } from '@theia/core/shared/inversify';
+import { ToolInvocationContext, ToolRequest, ToolRequestParameters } from '@theia/ai-core';
+import { ScmRepository } from '@theia/scm/lib/browser/scm-repository';
+import { ScmService } from '@theia/scm/lib/browser/scm-service';
+import { PredefinedShellTool } from '@theia/ai-terminal/lib/browser/predefined-shell-tool';
+import {
+    OutputTruncationOptions,
+    ShellExecutionCanceledResult,
+    ShellExecutionToolResult
+} from '@theia/ai-terminal/lib/common/shell-execution-server';
+
+export const GET_GIT_CHANGES_FUNCTION_ID = 'getGitChanges';
+
+/** Returned instead of a diff when the arguments do not identify a known repository. */
+export interface GitChangesRepositoryError {
+    error: string;
+    availableRepositories: string[];
+}
+
+export namespace GitChangesRepositoryError {
+    export function is(result: unknown): result is GitChangesRepositoryError {
+        return !!result && typeof result === 'object' && 'availableRepositories' in result;
+    }
+}
+
+/**
+ * Returns `git diff --cached` for one of the workspace's git repositories.
+ *
+ * `git diff --cached` is a plain, operator-free command that behaves the same on POSIX shells and
+ * Windows `cmd.exe`, and it renders staged additions of new files as complete addition diffs, so
+ * untracked files need no separate handling.
+ *
+ * The `repository` argument is matched against the repositories the SCM service actually knows
+ * about, and the command then runs in *that* repository's root. The argument never reaches the
+ * shell, so a repository name cannot inject a command. An unknown or ambiguous name is answered
+ * with the list of valid ones rather than a silent fallback, so the model cannot mistake one
+ * repository's diff for another's.
+ */
+@injectable()
+export class GetGitChangesTool extends PredefinedShellTool {
+
+    @inject(ScmService)
+    protected readonly scmService: ScmService;
+
+    readonly id = GET_GIT_CHANGES_FUNCTION_ID;
+
+    readonly description =
+        'Returns the staged changes (`git diff --cached`) of a git repository in the workspace, ' +
+        'including the full content of newly added files. Unstaged and untracked files are not ' +
+        'included. Returns an empty diff when nothing is staged, and an error listing the known ' +
+        'repositories when the requested one does not exist.';
+
+    protected override readonly parameters: ToolRequestParameters = {
+        type: 'object',
+        properties: {
+            repository: {
+                type: 'string',
+                description:
+                    'Which repository to read. Use the path of the repository root relative to the ' +
+                    'workspace (e.g. "backend" or "backend/tools"), or its absolute path. Omit it to ' +
+                    'use the repository currently selected in the Source Control view; in a ' +
+                    'single-repository workspace that is always the right one, but in a workspace ' +
+                    'with several repositories pass the name explicitly so the diff is not taken ' +
+                    'from whichever repository the user happens to have selected.'
+            }
+        }
+    };
+
+    /**
+     * A diff is only useful as a whole, so the `shellExecute` budget of 50 head plus 50 tail
+     * lines is far too tight. The head is favoured over the tail because the leading hunks
+     * describe the change; the backend caps stdout at 1MB regardless.
+     */
+    protected override readonly truncation: OutputTruncationOptions = {
+        headLines: 2000,
+        tailLines: 500,
+        maxLineLength: 2000
+    };
+
+    override getTool(): ToolRequest {
+        return {
+            ...super.getTool(),
+            // The base class runs the command unconditionally; an unknown repository has to be
+            // answered before that, so the handler is wrapped rather than `execute` overridden.
+            handler: (argString: string, ctx?: ToolInvocationContext) => this.handle(argString, ctx),
+            getArgumentsShortLabel: (args: string) => {
+                try {
+                    const repository = JSON.parse(args)?.repository;
+                    return typeof repository === 'string' && repository ? { label: repository, hasMore: false } : undefined;
+                } catch {
+                    return undefined;
+                }
+            }
+        };
+    }
+
+    /**
+     * Runs the diff for the given repository and returns it. Used directly by the commit-message
+     * generator, which already knows its repository and must not go through tool confirmation.
+     *
+     * Returns an empty string when the execution was canceled.
+     *
+     * @throws if the git command fails, so a `fatal: ...` message is never mistaken for a diff.
+     */
+    async getStagedChanges(repository: ScmRepository, cancellationToken?: CancellationToken): Promise<string> {
+        const result = await this.runShellCommand({
+            command: this.buildCommand(),
+            cwd: new URI(repository.provider.rootUri).path.fsPath(),
+            timeout: this.timeout,
+            ctx: { cancellationToken },
+            truncation: this.truncation
+        });
+        if (ShellExecutionCanceledResult.is(result)) {
+            return '';
+        }
+        if (!result.success) {
+            const detail = result.error || result.output || `exit code ${result.exitCode}`;
+            throw new Error(`Failed to read the staged changes: ${detail}`);
+        }
+        return result.output;
+    }
+
+    protected buildCommand(): string {
+        return 'git diff --cached --no-color';
+    }
+
+    protected async handle(
+        argString: string,
+        ctx?: ToolInvocationContext
+    ): Promise<ShellExecutionToolResult | ShellExecutionCanceledResult | GitChangesRepositoryError> {
+        const args: Record<string, unknown> = argString ? JSON.parse(argString) : {};
+        const requested = this.requestedRepository(args);
+        const candidates = this.findRepositories(args);
+        if (candidates.length > 1) {
+            return {
+                error: `Repository '${requested}' is ambiguous. Pass the relative path shown in availableRepositories or the absolute path of the repository root.`,
+                availableRepositories: this.availableRepositories()
+            };
+        }
+        if (candidates.length === 0) {
+            return {
+                error: requested
+                    ? `Unknown repository '${requested}'.`
+                    : 'No repository is selected in the Source Control view. Pass the repository argument.',
+                availableRepositories: this.availableRepositories()
+            };
+        }
+        return this.execute(argString, ctx);
+    }
+
+    protected resolveWorkspaceRoot(args: Record<string, unknown>): string {
+        const repository = this.findRepository(args);
+        if (!repository) {
+            // Guarded by `handle`; failing loudly here keeps an unresolved repository from
+            // silently running the diff in the backend process' own working directory.
+            throw new Error(`Unknown repository '${this.requestedRepository(args) ?? ''}'.`);
+        }
+        return new URI(repository.provider.rootUri).path.fsPath();
+    }
+
+    protected requestedRepository(args: Record<string, unknown>): string | undefined {
+        return typeof args.repository === 'string' && args.repository.trim() ? args.repository.trim() : undefined;
+    }
+
+    /** The repository identified by the `repository` argument, or `undefined` if it is unknown or ambiguous. */
+    protected findRepository(args: Record<string, unknown>): ScmRepository | undefined {
+        const candidates = this.findRepositories(args);
+        return candidates.length === 1 ? candidates[0] : undefined;
+    }
+
+    /**
+     * Matches the `repository` argument against the known repositories by label or path. The
+     * folder name alone is only used when nothing matches by label or path. Falls back to the
+     * selected repository when the argument is absent. More than one result means the argument
+     * is ambiguous.
+     */
+    protected findRepositories(args: Record<string, unknown>): ScmRepository[] {
+        const requested = this.requestedRepository(args);
+        if (!requested) {
+            return this.scmService.selectedRepository ? [this.scmService.selectedRepository] : [];
+        }
+        const normalized = this.normalize(requested);
+        const repositories = this.scmService.repositories;
+        const byLabelOrPath = repositories.filter(repository => {
+            const root = new URI(repository.provider.rootUri);
+            return this.normalize(this.repositoryLabel(repository)) === normalized
+                || this.normalize(root.path.fsPath()) === normalized
+                || this.normalize(root.toString()) === normalized;
+        });
+        if (byLabelOrPath.length > 0) {
+            return byLabelOrPath;
+        }
+        return repositories.filter(repository => this.normalize(new URI(repository.provider.rootUri).path.base) === normalized);
+    }
+
+    protected availableRepositories(): string[] {
+        return this.scmService.repositories.map(repository => this.repositoryLabel(repository));
+    }
+
+    /**
+     * Identifies a repository by the path of its root relative to the workspace, so that the label
+     * is usable as the `repository` argument of a follow-up call. Workspace roots sharing a folder
+     * name produce identical labels, which {@link findRepositories} reports as ambiguous.
+     */
+    protected repositoryLabel(repository: ScmRepository): string {
+        const root = new URI(repository.provider.rootUri);
+        for (const workspaceRoot of this.workspaceService.tryGetRoots()) {
+            if (!workspaceRoot.resource.isEqualOrParent(root)) {
+                continue;
+            }
+            const relative = workspaceRoot.resource.relative(root)?.toString();
+            return relative ? `${workspaceRoot.resource.path.base}/${relative}` : workspaceRoot.resource.path.base;
+        }
+        return root.path.base;
+    }
+
+    /** Path separators and case differ across platforms and between user phrasings. */
+    protected normalize(value: string): string {
+        return value.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+    }
+}