Studio Code: don't expose share_screenshot outside the remote-session runtime

[epeicher]

Related issues

• Fixes STU-1695

How AI was used in this PR

Claude Code traced the bug to the gating in apps/cli/ai/tools/index.ts, threaded the existing remoteSession runtime flag through buildAgentTools, and updated the unit tests to drive the new option directly. It also rewrote the eager wording in the tool description and the matching REMOTE_SESSION_GUIDANCE block. I reviewed each diff and verified the behavior locally.

Proposed Changes

Gate share_screenshot on the active runtime, not the feature flag

• share_screenshot was registered whenever STUDIO_ENABLE_REMOTE_SESSION=true, so direct studio code sessions also got the tool and the agent kept trying to share screenshots into a void. The flag is meant to opt users into the remote-session command, not to advertise a Telegram-only tool to every interactive run.
• Replaced the isRemoteSessionEnabled() check in resolveStudioToolDefinitions with a new remoteSession option on CreateStudioToolsOptions, mirroring the existing enablePreviewSteering pattern.
• Threaded the already-computed remoteSession value (from config.env.STUDIO_REMOTE_SESSION === '1' in apps/cli/ai/runtimes/pi/index.ts) through buildAgentTools into the tool resolver. The system prompt's REMOTE_SESSION_GUIDANCE was already gated on that same runtime signal — only the tool registration was on the wrong flag.
• The MCP server (apps/cli/ai/mcp-server.ts) calls resolveStudioToolDefinitions() with no options, so share_screenshot is correctly excluded there too — it would have nowhere to deliver an image from external assistants like Claude Desktop.
• Updated the stale comment in share-screenshot.ts and rewrote the gating tests to drive the new option instead of mutating process.env.

Tone down share_screenshot eagerness inside remote sessions

• The tool description previously said "Call after ANY visible change" and the system prompt's REMOTE_SESSION_GUIDANCE echoed it. That phrasing was the proximate reason the agent fired the tool aggressively whenever it was registered.
• Reworded both to "when the user explicitly asks to see the site, or when you finish a logical milestone with a clear visible result" and added an explicit "one screenshot per milestone, not per edit" rule so the agent doesn't pepper the Telegram chat with intermediate snapshots while iterating.

Testing Instructions

• Run STUDIO_ENABLE_REMOTE_SESSION=true npm run cli:build && STUDIO_ENABLE_REMOTE_SESSION=true node apps/cli/dist/cli/main.mjs code and confirm the agent no longer tries to call share_screenshot after visible site changes.
• Start a remote session (studio code remote-session start) and confirm the Telegram bridge still receives screenshots — STUDIO_REMOTE_SESSION=1 is set by turn-runner.ts for the spawned child, so the tool is registered there. Verify the agent now sends one screenshot per milestone instead of one per edit.
• npm test -- apps/cli/ai/tests/tools.test.ts apps/cli/lib/tests/feature-flags.test.ts passes.
• npm run typecheck passes.

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[wpmobilebot]

📊 Performance Test Results

Comparing 28fe1b4 vs trunk

app-size

Metric	trunk	28fe1b4	Diff	Change
App Size (Mac)	1409.57 MB	1409.57 MB	+0.00 MB	⚪ 0.0%

site-editor

Metric	trunk	28fe1b4	Diff	Change
load	1499 ms	1479 ms	20 ms	⚪ 0.0%

site-startup

Metric	trunk	28fe1b4	Diff	Change
siteCreation	8089 ms	8079 ms	10 ms	⚪ 0.0%
siteStartup	4939 ms	4922 ms	17 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[gcsecsey]

Great catch, thanks for the fix and for adding tests @epeicher! 🙌 The changes make sense to me, and this works well.

telegram	logs

[gcsecsey]

Thanks for improving the prompt and the description, it makes sense to only take a screenshot witht these conditions. 👍