feat: move shell efficiency guidelines to tool description (#18614)

packages/core/src/tools/__snapshots__/shell.test.ts.snap

@@ -3,6 +3,10 @@
 exports[`ShellTool > getDescription > should return the non-windows description when not on windows 1`] = `
 "This tool executes a given shell command as \`bash -c <command>\`. Command can start background processes using \`&\`. Command is executed as a subprocess that leads its own process group. Command process group can be terminated as \`kill -- -PGID\` or signaled as \`kill -s SIGNAL -- -PGID\`.
 
+      Efficiency Guidelines:
+      - Quiet Flags: Always prefer silent or quiet flags (e.g., \`npm install --silent\`, \`git --no-pager\`) to reduce output volume while still capturing necessary information.
+      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\`).
+
       The following information is returned:
 
       Output: Combined stdout/stderr. Can be \`(empty)\` or partial on error and for any unwaited background processes.
@@ -16,6 +20,10 @@ exports[`ShellTool > getDescription > should return the non-windows description
 exports[`ShellTool > getDescription > should return the windows description when on windows 1`] = `
 "This tool executes a given shell command as \`powershell.exe -NoProfile -Command <command>\`. Command can start background processes using PowerShell constructs such as \`Start-Process -NoNewWindow\` or \`Start-Job\`.
 
+      Efficiency Guidelines:
+      - Quiet Flags: Always prefer silent or quiet flags (e.g., \`npm install --silent\`, \`git --no-pager\`) to reduce output volume while still capturing necessary information.
+      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\`).
+
       The following information is returned:
 
       Output: Combined stdout/stderr. Can be \`(empty)\` or partial on error and for any unwaited background processes.

packages/core/src/tools/shell.test.ts

@@ -130,6 +130,7 @@ describe('ShellTool', () => {
       getGeminiClient: vi.fn().mockReturnValue({}),
       getShellToolInactivityTimeout: vi.fn().mockReturnValue(1000),
       getEnableInteractiveShell: vi.fn().mockReturnValue(false),
+      getEnableShellOutputEfficiency: vi.fn().mockReturnValue(true),
       sanitizationConfig: {},
     } as unknown as Config;
 
@@ -633,6 +634,15 @@ describe('ShellTool', () => {
       const shellTool = new ShellTool(mockConfig, createMockMessageBus());
       expect(shellTool.description).toMatchSnapshot();
     });
+
+    it('should not include efficiency guidelines when disabled', () => {
+      mockPlatform.mockReturnValue('linux');
+      vi.mocked(mockConfig.getEnableShellOutputEfficiency).mockReturnValue(
+        false,
+      );
+      const shellTool = new ShellTool(mockConfig, createMockMessageBus());
+      expect(shellTool.description).not.toContain('Efficiency Guidelines:');
+    });
   });
 
   describe('llmContent output format', () => {

packages/core/src/tools/shell.ts

@@ -451,7 +451,18 @@ export class ShellToolInvocation extends BaseToolInvocation<
   }
 }
 
-function getShellToolDescription(enableInteractiveShell: boolean): string {
+function getShellToolDescription(
+  enableInteractiveShell: boolean,
+  enableEfficiency: boolean,
+): string {
+  const efficiencyGuidelines = enableEfficiency
+    ? `
+
+      Efficiency Guidelines:
+      - Quiet Flags: Always prefer silent or quiet flags (e.g., \`npm install --silent\`, \`git --no-pager\`) to reduce output volume while still capturing necessary information.
+      - Pagination: Always disable terminal pagination to ensure commands terminate (e.g., use \`git --no-pager\`, \`systemctl --no-pager\`, or set \`PAGER=cat\`).`
+    : '';
+
   const returnedInfo = `
 
       The following information is returned:
@@ -467,12 +478,12 @@ function getShellToolDescription(enableInteractiveShell: boolean): string {
     const backgroundInstructions = enableInteractiveShell
       ? 'To run a command in the background, set the `is_background` parameter to true. Do NOT use PowerShell background constructs.'
       : 'Command can start background processes using PowerShell constructs such as `Start-Process -NoNewWindow` or `Start-Job`.';
-    return `This tool executes a given shell command as \`powershell.exe -NoProfile -Command <command>\`. ${backgroundInstructions}${returnedInfo}`;
+    return `This tool executes a given shell command as \`powershell.exe -NoProfile -Command <command>\`. ${backgroundInstructions}${efficiencyGuidelines}${returnedInfo}`;
   } else {
     const backgroundInstructions = enableInteractiveShell
       ? 'To run a command in the background, set the `is_background` parameter to true. Do NOT use `&` to background commands.'
       : 'Command can start background processes using `&`.';
-    return `This tool executes a given shell command as \`bash -c <command>\`. ${backgroundInstructions} Command is executed as a subprocess that leads its own process group. Command process group can be terminated as \`kill -- -PGID\` or signaled as \`kill -s SIGNAL -- -PGID\`.${returnedInfo}`;
+    return `This tool executes a given shell command as \`bash -c <command>\`. ${backgroundInstructions} Command is executed as a subprocess that leads its own process group. Command process group can be terminated as \`kill -- -PGID\` or signaled as \`kill -s SIGNAL -- -PGID\`.${efficiencyGuidelines}${returnedInfo}`;
   }
 }
 
@@ -500,7 +511,10 @@ export class ShellTool extends BaseDeclarativeTool<
     super(
       ShellTool.Name,
       'Shell',
-      getShellToolDescription(config.getEnableInteractiveShell()),
+      getShellToolDescription(
+        config.getEnableInteractiveShell(),
+        config.getEnableShellOutputEfficiency(),
+      ),
       Kind.Execute,
       {
         type: 'object',