Let take_screenshot skip chat display for internal verification captures

apps/cli/ai/tests/tools.test.ts

@@ -1,6 +1,7 @@
 import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'fs/promises';
 import os from 'os';
 import path from 'path';
+import { fileURLToPath } from 'url';
 import { getConnectedWpcomSitesForLocalSite } from '@studio/common/lib/connected-sites';
 import { SITE_RUNTIME_PLAYGROUND } from '@studio/common/lib/site-runtime';
 import { vi } from 'vitest';
@@ -403,6 +404,39 @@ describe( 'Studio AI MCP tools', () => {
 		await cleanUpScreenshotArtifacts( artifacts );
 	} );
 
+	it( 'returns no artifacts when take_screenshot is called with display: false', async () => {
+		const screenshotBuffer = Buffer.from( 'internal-jpeg' );
+		mockScreenshotBrowser( createMockPage( { buffer: screenshotBuffer, documentHeight: 900 } ) );
+		const progressMessages: string[] = [];
+		setProgressCallback( ( message ) => {
+			progressMessages.push( message );
+		} );
+
+		const result = await getTool( 'take_screenshot' ).rawHandler( {
+			url: 'http://localhost:8903/story-time',
+			display: false,
+		} as never );
+
+		// Nothing to emit into the chat, but the model still gets the image
+		// for its own verification.
+		expect( result.studioArtifacts ).toBeUndefined();
+		expect( result.content[ 1 ] ).toEqual( {
+			type: 'image',
+			data: screenshotBuffer.toString( 'base64' ),
+			mimeType: 'image/jpeg',
+		} );
+
+		const savedLine = progressMessages.find( ( message ) => message.startsWith( 'Saved ' ) );
+		expect( savedLine ).toBeDefined();
+		await rm(
+			path.dirname( fileURLToPath( savedLine!.slice( savedLine!.indexOf( 'file://' ) ) ) ),
+			{
+				recursive: true,
+				force: true,
+			}
+		);
+	} );
+
 	it( 'can capture desktop and mobile screenshots in one take_screenshot call', async () => {
 		const desktopBuffer = Buffer.from( 'desktop-jpeg' );
 		const mobileBuffer = Buffer.from( 'mobile-jpeg' );

apps/cli/ai/tools/take-screenshot.ts

@@ -60,11 +60,18 @@ export const takeScreenshotTool = defineTool(
 		'Pass `colorScheme: "light"`, `colorScheme: "dark"`, or `colorScheme: "all"` to verify pages that respond to prefers-color-scheme. ' +
 		'Long pages are clipped at 8000 vertical pixels (a vision-model limit); the response reports the document height and whether more remains, and you can call again with `offset` to fetch the next slice. ' +
 		'Use this to verify the site looks correct after building it. ' +
+		'Captures are shown to the user in the chat by default; pass `display: false` for internal verification captures while iterating so the user only sees deliberate milestones. ' +
 		'Use `share_screenshot` instead only in remote sessions where you need to deliver the rendered page outside the Studio UI.',
 	{
 		url: Type.String( { description: 'The URL to screenshot' } ),
 		viewport: Type.Optional( screenshotViewportSchema ),
 		colorScheme: Type.Optional( screenshotColorSchemeSchema ),
+		display: Type.Optional(
+			Type.Boolean( {
+				description:
+					'Whether to show the capture to the user in the chat. Defaults to true; set false for internal verification captures the user does not need to see.',
+			} )
+		),
 		offset: Type.Optional(
 			Type.Number( {
 				minimum: 0,
@@ -162,7 +169,9 @@ export const takeScreenshotTool = defineTool(
 						mimeType: capture.mimeType,
 					} ) ),
 				],
-				studioArtifacts: captures.map( ( capture ) => capture.mediaWidgetPayload ),
+				...( args.display === false
+					? {}
+					: { studioArtifacts: captures.map( ( capture ) => capture.mediaWidgetPayload ) } ),
 			};
 		} catch ( error ) {
 			throw new Error(

packages/common/ai/studio-widgets.ts

@@ -63,7 +63,7 @@ export const STUDIO_PRESENTATION_RULES: StudioPresentationRule[] = [
 	{
 		id: 'screenshot-auto-artifact',
 		description:
-			'take_screenshot captures are already shown to the user as inline media in the conversation. Never call studio_present for a screenshot, and do not substitute a site-preview widget for one; site-preview is for live previews, not captured screenshots.',
+			'take_screenshot captures are shown to the user as inline media in the conversation by default. Do not show every internal verification screenshot: while iterating (design polish loops, intermediate checks), pass `display: false` and let only deliberate milestone captures display. Never call studio_present for a screenshot, and do not substitute a site-preview widget for one; site-preview is for live previews, not captured screenshots.',
 	},
 ];