feat(chat): Add explanation for tool invocation for fsWrite and executeBash (aws#7037)

## Problem
- Multiple invocations of ExecuteBash and FsWrite can be confusing to
the user

## Solution
- Add explanation for tool invocation for fsWrite and executeBash

[
<img width="374" alt="Screenshot 2025-04-14 at 1 57 11 PM"
src="https://github.com/user-attachments/assets/fb0c2873-f2fe-4554-b448-be2c41f2ddea"
/>
](url)

---

- Treat all work as PUBLIC. Private `feature/x` branches will not be
squash-merged at release time.
- Your code changes must meet the guidelines in
[CONTRIBUTING.md](https://github.com/aws/aws-toolkit-vscode/blob/master/CONTRIBUTING.md#guidelines).
- License: I confirm that my contribution is made under the terms of the
Apache 2.0 license.

Author: jguoamz

packages/core/src/codewhispererChat/controllers/chat/messenger/messenger.ts

@@ -61,7 +61,7 @@ import { TabType } from '../../../../amazonq/webview/ui/storages/tabsStorage'
 import { ToolType, ToolUtils } from '../../../tools/toolUtils'
 import { ChatStream } from '../../../tools/chatStream'
 import path from 'path'
-import { CommandValidation } from '../../../tools/executeBash'
+import { CommandValidation, ExecuteBashParams } from '../../../tools/executeBash'
 import { extractErrorInfo } from '../../../../shared/utilities/messageUtil'
 import { noWriteTools, tools } from '../../../constants'
 import { Change } from 'diff'
@@ -306,12 +306,32 @@ export class Messenger {
                             }
                             const tool = ToolUtils.tryFromToolUse(toolUse)
                             if ('type' in tool) {
+                                let explanation: string | undefined = undefined
                                 let changeList: Change[] | undefined = undefined
                                 let messageIdToUpdate: string | undefined = undefined
                                 const isReadOrList: boolean = [ToolType.FsRead, ToolType.ListDirectory].includes(
                                     tool.type
                                 )
-                                if (tool.type === ToolType.FsWrite) {
+                                if (tool.type === ToolType.ExecuteBash) {
+                                    const input = toolUse.input as unknown as ExecuteBashParams
+                                    if (input.explanation) {
+                                        getLogger().debug(
+                                            'Tool explanation: %s for executeBash toolUseId: %s',
+                                            input.explanation,
+                                            toolUse.toolUseId
+                                        )
+                                        explanation = input.explanation
+                                    }
+                                } else if (tool.type === ToolType.FsWrite) {
+                                    const input = toolUse.input as unknown as FsWriteParams
+                                    if (input.explanation) {
+                                        getLogger().debug(
+                                            'Tool explanation: %s for fsWrite toolUseId: %s',
+                                            input.explanation,
+                                            toolUse.toolUseId
+                                        )
+                                        explanation = input.explanation
+                                    }
                                     session.setShowDiffOnFileWrite(true)
                                     changeList = await tool.tool.getDiffChanges()
                                 }
@@ -353,7 +373,8 @@ export class Messenger {
                                     true,
                                     validation,
                                     isReadOrList,
-                                    changeList
+                                    changeList,
+                                    explanation
                                 )
                                 await ToolUtils.queueDescription(tool, chatStream)
                                 if (session.messageIdToUpdate === undefined && tool.type === ToolType.FsRead) {

packages/core/src/codewhispererChat/tools/chatStream.ts

@@ -32,6 +32,7 @@ export class ChatStream extends Writable {
         private readonly validation: CommandValidation,
         private readonly isReadorList: boolean,
         private readonly changeList?: Change[],
+        private readonly explanation?: string,
         private readonly logger = getLogger('chatStream')
     ) {
         super()
@@ -41,7 +42,10 @@ export class ChatStream extends Writable {
         if (!emitEvent) {
             return
         }
-        if (validation.requiresAcceptance) {
+        if (this.explanation) {
+            this.messenger.sendDirectiveMessage(tabID, triggerID, this.explanation)
+        }
+        if (validation.requiresAcceptance && this.toolUse?.name === 'executeBash') {
             this.messenger.sendDirectiveMessage(
                 tabID,
                 triggerID,

packages/core/src/codewhispererChat/tools/executeBash.ts

@@ -113,6 +113,7 @@ export const mutateCommandWarningMessage = 'Mutation command:\n\n'
 export interface ExecuteBashParams {
     command: string
     cwd?: string
+    explanation?: string
 }
 
 export interface CommandValidation {

packages/core/src/codewhispererChat/tools/fsWrite.ts

@@ -12,6 +12,7 @@ import { Change, diffLines } from 'diff'
 
 interface BaseParams {
     path: string
+    explanation?: string
 }
 
 export interface CreateParams extends BaseParams {

packages/core/src/codewhispererChat/tools/tool_index.json

@@ -65,6 +65,10 @@
         "inputSchema": {
             "type": "object",
             "properties": {
+                "explanation": {
+                    "description": "One sentence explanation as to why this tool is being used, and how it contributes to the goal.",
+                    "type": "string"
+                },
                 "command": {
                     "type": "string",
                     "description": "Bash command to execute"
@@ -83,10 +87,6 @@
         "inputSchema": {
             "type": "object",
             "properties": {
-                "explanation": {
-                    "description": "One sentence explanation as to why this tool is being used, and how it contributes to the goal.",
-                    "type": "string"
-                },
                 "path": {
                     "type": "string",
                     "description": "Absolute path to a directory, e.g., `/repo`."