@superblocksteam/gateway 2.0.177 → 2.0.178-next.0

package/dist/transports/mcp/mount.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { getUiCapability, registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY, } from "@modelcontextprotocol/ext-apps/server";
 import { McpServer, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { trace } from "@opentelemetry/api";
 import { z } from "zod";
 import { assertEnterprisePlan, EntitlementError, } from "@superblocksteam/mcp-server";
 import { getIntegrationMetadata } from "../../capabilities/integration-metadata.js";
@@ -8,16 +9,15 @@ import { askUser, checkAppProgress, checkPublishProgress, editApp, getApp, getPr
 import { LiveStateAttaches } from "../../capabilities/live-state-attaches.js";
 import { ToolPermissionReply } from "../../capabilities/tool-permission-reply.js";
 import { IMPORT_ZIP_BASE64_MAX_CHARS } from "../../capabilities/types.js";
-import { HOST_BROWSER_TOOLS_COWORK, HOST_BROWSER_TOOLS_UNKNOWN, } from "../../capture/browser-contract.js";
 import { BROWSER_DRIVER_INSTRUCTIONS } from "../../capture/browser-instructions.js";
 import { captureLibraryScreenshotWithPlaywright } from "../../capture/capture-library.js";
-import { withCoworkEditorHost } from "../../capture/cowork-editor-url.js";
 import { gatewayDebug, gatewayDebugStack } from "../../debug.js";
 import { capturePreviewScreenshotWithPlaywright } from "../../preview/capture-screenshot.js";
 import { createStores } from "../../stores/memory.js";
+import { McpUsage } from "../../telemetry/mcp-usage.js";
 import { registerAdminTools } from "./admin-tools.js";
 import { APP_STATUS_HTML, APP_STATUS_RESOURCE_URI } from "./app-status-html.js";
-import { clientPresentationCapabilities, collectsUserApproval, } from "./client-presentation.js";
+import { collectsUserApproval, } from "./client-presentation.js";
 import { APP_DECISION_HTML, APP_DECISION_RESOURCE_URI, CONFIRM_PLAN_APPROVAL_TOOL, PLAN_APPROVAL_TOKEN_META_KEY, PLAN_MARKUP_META_KEY, } from "./decision-card-html.js";
 import { clientSupportsFormElicitation, elicitDecision, pendingDecision, resolveDecisionByElicitation, resultApplicationId, resultBranch, } from "./decision-elicitation.js";
 import { createEditorDocumentProbe, } from "./editor-document-probe.js";
@@ -25,10 +25,10 @@ import { EDITOR_SETUP_RECENT_APP_WINDOW_MS, editorIntegrationSetupUrl, } from ".
 import { formatMcpToolContent, withDisplayedMentions, } from "./format-tool-content.js";
 import { attachAgentInstructions, instructionFor, } from "./instructions/index.js";
 import { isRecord, readResult } from "./instructions/result.js";
-import { APP_LOAD_CHECK, COWORK_BROWSER_TOOLSEARCH, PLAIN_HOST_TOOL_PERMISSION, } from "./instructions/tools/copy.js";
-import { NativeBrowserPresence, nativeBrowserPresenceDirectory, } from "./native-browser-presence.js";
+import { APP_LOAD_CHECK, PLAIN_HOST_TOOL_PERMISSION, } from "./instructions/tools/copy.js";
 import { planApprovalDirectory, PlanApprovalChallenges, } from "./plan-approval.js";
 import { createProgressNotifier } from "./progress-notifier.js";
+import { permissionMeta } from "./tool-permissions.js";
 const DESTRUCTIVE_TOOL_ANNOTATIONS = {
     destructiveHint: true,
     idempotentHint: false,
@@ -68,16 +68,15 @@ class ResultAcknowledgingMcpServer extends McpServer {
     connect(transport) {
         const send = transport.send.bind(transport);
         transport.send = async (message, options) => {
-            const outgoing = withClientInstructions(message, this.server.getClientVersion());
             try {
-                await send(outgoing, options);
-                if (isRecord(outgoing) && "result" in outgoing && "id" in outgoing) {
-                    this.onResultDelivered?.(outgoing.result, outgoing.id);
+                await send(message, options);
+                if (isRecord(message) && "result" in message && "id" in message) {
+                    this.onResultDelivered?.(message.result, message.id);
                 }
             }
             catch (error) {
-                if (isRecord(outgoing) && "result" in outgoing && "id" in outgoing) {
-                    this.onResultDeliveryFailed?.(outgoing.result, outgoing.id);
+                if (isRecord(message) && "result" in message && "id" in message) {
+                    this.onResultDeliveryFailed?.(message.result, message.id);
                 }
                 throw error;
             }
@@ -183,7 +182,14 @@ async function principalFrom(deps) {
         ...(deps.cliIdentity ?? {}),
     };
 }
-const SOURCE_ARTIFACT_INSTRUCTIONS = "When the source is a readable tree on this machine, archive the source and assets with their original relative paths, excluding .git, node_modules, build output, secrets, and production data. Inspect the archive, upload it with upload_artifact filePath, then pass the returned artifact unchanged in start_app or edit_app artifacts. Local paths and prose descriptions are not a substitute for the source artifact: Superblocks cannot read the host's workspace. Ask Superblocks to read the attached source and preserve its UI and behavior. Reuse the artifact on retries. Follow the superblocks-import skill when available; Superblocks writes the application, not the host.";
+const SOURCE_ARTIFACT_RULES = "Local paths and prose descriptions are not a substitute for the source artifact: Superblocks cannot read the host's workspace. Ask Superblocks to read the attached source and preserve its UI and behavior. Reuse the artifact on retries. Follow the superblocks-import skill when available; Superblocks writes the application, not the host.";
+const SOURCE_ARTIFACT_INSTRUCTIONS = `When the source is a readable tree on this machine, archive the source and assets with their original relative paths, excluding .git, node_modules, build output, secrets, and production data. Inspect the archive, upload it with upload_artifact filePath, then pass the returned artifact unchanged in start_app or edit_app artifacts. ${SOURCE_ARTIFACT_RULES}`;
+// Hosted, the gateway cannot read the user's disk, so source arrives as text.
+const HOSTED_SOURCE_ARTIFACT_INSTRUCTIONS = `To migrate source, send its text files with their original relative paths through upload_artifact files, excluding .git, node_modules, build output, secrets, and production data, then pass the returned artifact unchanged in start_app or edit_app artifacts. ${SOURCE_ARTIFACT_RULES}`;
+const UPLOAD_ARTIFACT_INPUTS = "Pass filePath with the full host path when you have it. A bare file name falls back to the gateway's search folders. If the file exists only in your own sandbox or scratchpad, where the gateway cannot read it, send text source through files: [{ path, content }] instead of filePath. The gateway reads filePath bytes itself. Only source you are writing out yourself goes in files, which is archived as text: never put an image, PDF, or other binary in there, and never base64 a file into it. Doing that spends minutes emitting the encoding and uploads those characters under the file's name instead of the file. zipBase64 is only for test fixtures.";
+// shortcut: zipBase64 keeps its small cap, so hosted takes only tiny binaries until it gets an upload path for real files.
+const HOSTED_BINARY_UPLOAD = `For an image, PDF, or other binary file, put it in a ZIP and pass that as zipBase64. zipBase64 takes at most ${IMPORT_ZIP_BASE64_MAX_CHARS} base64 characters, so a larger binary cannot be uploaded on this connection yet: tell the user that instead of retrying.`;
+const HOSTED_UPLOAD_ARTIFACT_INPUTS = `This server cannot read files on the user's machine or in this chat's sandbox. Only source you are writing out yourself goes in files, which is archived as text: never put an image, PDF, or other binary in there, and never base64 a file into it. ${HOSTED_BINARY_UPLOAD}`;
 function compactRecord(value) {
     if (!value) {
         return undefined;
@@ -196,6 +202,10 @@ function compactRecord(value) {
     }
     return Object.keys(compacted).length > 0 ? compacted : undefined;
 }
+const UPLOAD_FILE_INSTRUCTIONS = "When the user attached a file in this chat (a log, CSV, screenshot, image, zip, or anything else), or when migrating source visible in this conversation, call upload_artifact. Pass upload_artifact filePath with the full host path when you have it; a bare file name falls back to the gateway's search folders. If the file exists only in your own sandbox or scratchpad, where the gateway cannot read it, send text source through files: [{ path, content }] instead of filePath. The gateway reads filePath bytes itself, so an image or PDF costs nothing to send. Only source you are writing out yourself goes in files, which is archived as text - never base64 a file into it. Then pass the returned artifact in start_app or edit_app artifacts. Do not create an artifact in the host or use the host's own file-upload UI.";
+const HOSTED_UPLOAD_FILE_INSTRUCTIONS = `When the user attached a file in this chat (a log, CSV, screenshot, image, zip, or anything else), or when migrating source visible in this conversation, call upload_artifact. This server cannot read files on the user's machine or in this chat's sandbox. Send text through files: [{ path, content }], which is archived as text. ${HOSTED_BINARY_UPLOAD} Then pass the returned artifact in start_app or edit_app artifacts. Do not create an artifact in the host or use the host's own file-upload UI.`;
+// Hosted has no login or set_server; the relay already signed the user in.
+const SIGN_IN_INSTRUCTIONS = 'This connection may be established before browser sign-in. Call the tool that does the user\'s job. If it reports "MCP browser login required" or "Saved Superblocks login changed outside this task", explicitly call login when available, then retry the requested tool in this current task. Account-dependent tools never start browser sign-in themselves. Do not ask the user to restart the app they are chatting in. Do not call whoami as a preflight. If the user asks which Superblocks account is in use, call whoami. If the user asks to sign in or switch accounts, call login when available. If the user asks to change the Superblocks server, use a native question form when available to confirm https://app.superblocks.com or collect another server URL, then call set_server; continue in the current task after sign-in succeeds. Report the sign-in status from set_server\'s result; a successful whoami does not show whether browser sign-in occurred.';
 /**
  * Told to the model on connect, so it can match what a user actually says
  * against these tools.
@@ -207,7 +217,8 @@ function compactRecord(value) {
  * is input-only, because a client that reads "Clark" here repeats it back and
  * reintroduces the retired name to the user.
  */
-export const SERVER_INSTRUCTIONS = `Superblocks builds, edits, and publishes internal web applications. Prompts sent through these tools are handed to Superblocks, which writes the application code in a live-edit session.
+function serverInstructions(hosted) {
+    return `Superblocks builds, edits, and publishes internal web applications. Prompts sent through these tools are handed to Superblocks, which writes the application code in a live-edit session.
 
 Name the builder "Superblocks" in every word you write. Users sometimes call it "Clark", an older name for this same system: understand them, and answer about Superblocks. Never write "Clark" yourself — not as a name, not as an aside, not even when the user just used it, and never as a separate agent or persona. If Superblocks' own words come back naming Clark, relay the substance and say Superblocks.
 
@@ -229,75 +240,66 @@ Building or editing an app follows one loop: start_app hands a new application t
 
 ${APP_LOAD_CHECK}
 
-When the user attached a file in this chat (a log, CSV, screenshot, image, zip, or anything else), or when migrating source visible in this conversation, call upload_artifact. Pass upload_artifact filePath with the full host path when you have it; a bare file name falls back to the gateway's search folders. If the file exists only in this chat's scratchpad path (for example /tmp/claude-.../scratchpad), send text source through files: [{ path, content }] instead of filePath. The gateway reads filePath bytes itself, so an image or PDF costs nothing to send. Only source you are writing out yourself goes in files, which is archived as text - never base64 a file into it. Then pass the returned artifact in start_app or edit_app artifacts. Do not create a Claude artifact or use the host's own file-upload UI.
+${hosted ? HOSTED_UPLOAD_FILE_INSTRUCTIONS : UPLOAD_FILE_INSTRUCTIONS}
 
-${SOURCE_ARTIFACT_INSTRUCTIONS}
+${hosted ? HOSTED_SOURCE_ARTIFACT_INSTRUCTIONS : SOURCE_ARTIFACT_INSTRUCTIONS}
 
 For a migrated app with missing integrations, call list_integrations first. Reuse only the same plugin and the same connection: the same REST base URL, or the same host, port, and database. A similar name is not a match. list_integrations and get_integration_metadata do not expose connection URLs or hosts, so do not use them to guess a match. When there is no exact match, follow the result's agentInstructions to create and wire every declared integration.
 
-This connector is the single Superblocks MCP: Builder tools (upload_artifact, start_app, edit_app, check_app_progress, ask_user, get_app, build_app, publish_app, check_publish_progress) and Admin tools (integrations, apps, users, folders, deploy_application, and the rest of the customer Admin surface) share this endpoint. Prefer create_integration / list_integrations here over sending the user to a second MCP. create_integration takes name, plugin_id, and configuration, never the raw integrations API envelope. create_integration is Admin CRUD for org datasources; start_app creates an application and hands it a prompt. deploy_application is Admin deploy of an existing commit; publish_app is the Builder path that commits current work and waits for it to go live. Omit base_url on Admin tools unless targeting a different control plane. checkout_application is not exposed on this network surface (host filesystem writes); use the CLI/workspace checkout path instead.
+This connector is the single Superblocks MCP: Builder tools (upload_artifact, start_app, edit_app, check_app_progress, ask_user, get_app, build_app, publish_app, check_publish_progress) and Admin tools (integrations, apps, users, folders, deploy_application, and the rest of the customer Admin surface) share this endpoint. Prefer create_integration / list_integrations here over sending the user to a second MCP. create_integration takes name, plugin_id, and configuration, never the raw integrations API envelope; for a REST API integration backed by an OpenAPI spec, also pass openapi_spec (the spec file contents as JSON or YAML text) and file_name so the spec is stored and linked in the same call. create_integration is Admin CRUD for org datasources; start_app creates an application and hands it a prompt. deploy_application is Admin deploy of an existing commit; publish_app is the Builder path that commits current work and waits for it to go live. checkout_application is not exposed on this network surface (host filesystem writes); use the CLI/workspace checkout path instead.
 
-This connection may be established before browser sign-in. Call the tool that does the user's job. If it reports "MCP browser login required" or "Saved Superblocks login changed outside this task", explicitly call login when available, then retry the requested tool in this current task. Account-dependent tools never start browser sign-in themselves. Do not ask the user to restart Claude. Do not call whoami as a preflight. If the user asks which Superblocks account is in use, call whoami. If the user asks to sign in or switch accounts, call login when available. If the user asks to change the Superblocks server, use a native question form when available to confirm https://app.superblocks.com or collect another server URL, then call set_server; continue in the current Cowork task after sign-in succeeds. Report the sign-in status from set_server's result; a successful whoami does not show whether browser sign-in occurred.
-
-Never tell the user to restart the MCP server; keep the MCP server running.
+${hosted ? "" : `${SIGN_IN_INSTRUCTIONS}\n\n`}Never tell the user to restart the MCP server; keep the MCP server running.
 
 A cancelled tool call does not undo work Superblocks already did. The application still exists; read applicationId on the error and follow agentInstructions (or pendingAction) instead of starting over.
 
-get_app's previewUrl opens the current development app with existing app permissions; it is not a published end-user URL. Live-editor previews, including fullscreen links, require app edit/build permission (apps:update); End-User or READ access alone is insufficient. For a requested live-preview link, return that exact URL; do not open Share, change permissions, invite anyone, or publish. Call build_app only when the user explicitly requests an unpublished build or a shareable versioned preview, never automatically after an ordinary app creation, edit, or get_app. It creates a commit preview without publishing; retain its previewUrl and use get_preview_status for subsequent checks. If a sharing request is ambiguous (including "Can I share this app?"), ask before calling any tools whether they mean live preview, an unpublished commit preview, or publishing. Access permissions and deployment history cannot resolve this intent; an empty deployment history does not mean publishing is required to share a preview. Call publish_app or deploy_application only when the user explicitly asks to publish or deploy. Publishing does not extend the hosting environment's lifetime; URLs in ephemeral environments remain temporary. Otherwise prefer MCP Apps Open editor / Open preview buttons over dumping editUrl / previewUrl / publishUrl into chat, especially preview JWTs. Claude Desktop can only openLink https URLs; when a URL is http, say so and rely on any screenshot instead.
+get_app's previewUrl opens the current development app with existing app permissions; it is not a published end-user URL. Live-editor previews, including fullscreen links, require app edit/build permission (apps:update); End-User or READ access alone is insufficient. For a requested live-preview link, return that exact URL; do not open Share, change permissions, invite anyone, or publish. Call build_app only when the user explicitly requests an unpublished build or a shareable versioned preview, never automatically after an ordinary app creation, edit, or get_app. It creates a commit preview without publishing; retain its previewUrl and use get_preview_status for subsequent checks. If a sharing request is ambiguous (including "Can I share this app?"), ask before calling any tools whether they mean live preview, an unpublished commit preview, or publishing. Access permissions and deployment history cannot resolve this intent; an empty deployment history does not mean publishing is required to share a preview. Call publish_app or deploy_application only when the user explicitly asks to publish or deploy. Publishing does not extend the hosting environment's lifetime; URLs in ephemeral environments remain temporary. Otherwise prefer MCP Apps Open editor / Open preview buttons over dumping editUrl / previewUrl / publishUrl into chat, especially preview JWTs. Some hosts can only open https links; when a URL is http and you cannot open it, say so and rely on any screenshot instead.
 
 ${BROWSER_DRIVER_INSTRUCTIONS}`;
-const COWORK_EMBEDDED_BROWSER_TOOLS = `Load your browser pane tools, you will need them. Call ToolSearch with query ${COWORK_BROWSER_TOOLSEARCH}. When a check_app_progress or get_app result includes browserNavigation, ensure its exact URL is open in Cowork's embedded Page browser before any other action. If that app is already open, do not reload it; otherwise, focus the Page URL field, enter that exact URL, and press Enter. Verify the app loaded; normal authentication or canonical URL redirects are allowed. A blank tab is insufficient. Keep the Page open so the user can watch the live canvas update.`;
-function serverInstructionsFor(client) {
-    if (!clientPresentationCapabilities(client).hasNativeBrowser) {
-        return SERVER_INSTRUCTIONS;
-    }
-    return `${SERVER_INSTRUCTIONS}
-
-${COWORK_EMBEDDED_BROWSER_TOOLS}`;
 }
-const PUBLISH_APP_DESCRIPTION_PREFIX = 'Publish/deploy the recent or specified Superblocks application. Pass exactly one of commitMessage or commitId. commitMessage snapshots current work as a new commit: you write it yourself, as a short summary of what changed in the app since the last publish, like a git commit message ("Add a login page"). It is the message on that commit and it is shown in the app\'s history. commitId publishes an earlier commit and then omit commitMessage. Returns status "deployed" once the app is live, or status "publishing" when the deploy was accepted and is still rolling out - that is a success, not a failure: the commit is made and the policy gates passed. On "publishing", tell the user the publish went through and is rolling out, then follow it with check_publish_progress until it reports "deployed"; carry the returned commitId back on every check_publish_progress poll. ';
-function publishAppDescription(hasNativeBrowser) {
-    return (PUBLISH_APP_DESCRIPTION_PREFIX +
-        (hasNativeBrowser
-            ? "On either successful status, open publishDetailsUrl automatically in the browser pane before the first check_publish_progress poll."
-            : "On either successful status, include publishDetailsUrl immediately in your next user-facing response before the first check_publish_progress poll."));
-}
-function withClientInstructions(message, client) {
-    if (!isRecord(message) || !("result" in message)) {
-        return message;
-    }
-    const result = message.result;
-    if (!isRecord(result) ||
-        typeof result.protocolVersion !== "string" ||
-        !isRecord(result.serverInfo)) {
-        return message;
-    }
-    return {
-        ...message,
-        result: {
-            ...result,
-            instructions: serverInstructionsFor(client),
-        },
-    };
+// The stdio text, kept for tests. Live servers pick stdio or hosted text from config.
+export const SERVER_INSTRUCTIONS = serverInstructions(false);
+// Every client reads the tool descriptions, and check_app_progress returns
+// browserNavigation as soon as the canvas is ready, while the build still runs.
+// Opening the editor in an ordinary browser then can take over the live-edit
+// turn, so mid-build opening needs agentInstructions, the host or the plugin
+// to allow it.
+const BROWSER_NAVIGATION_IS_DATA = 'A result may include "browserNavigation": the editor URL, added once the editor answers. While status is "building", do not open it unless "agentInstructions" or instructions from your host or the Superblocks plugin say you may open or show it then. Once status is no longer "building", you may open it in your browser or show it to the user.';
+const PUBLISH_APP_DESCRIPTION = 'Publish/deploy the recent or specified Superblocks application. Pass exactly one of commitMessage or commitId. commitMessage snapshots current work as a new commit: you write it yourself, as a short summary of what changed in the app since the last publish, like a git commit message ("Add a login page"). It is the message on that commit and it is shown in the app\'s history. commitId publishes an earlier commit and then omit commitMessage. Returns status "deployed" once the app is live, or status "publishing" when the deploy was accepted and is still rolling out - that is a success, not a failure: the commit is made and the policy gates passed. On "publishing", tell the user the publish went through and is rolling out, then follow it with check_publish_progress until it reports "deployed"; carry the returned commitId back on every check_publish_progress poll. On either successful status, include publishDetailsUrl immediately in your next user-facing response before the first check_publish_progress poll.';
+/**
+ * ask_user's description. Only a host that renders the decision card is told
+ * about the card; any other host is told how the decision reaches its user.
+ */
+function askUserDescription(decisionCard) {
+    return [
+        'Render a form to put the plan or question Superblocks stopped on to the user — call this the moment any tool reports status "needs_decision", except pendingAction "decide_in_editor" (nothing to show; point the user at the edit URL instead). Do not call this if check_app_progress agentInstructions says not too because you already have a native ask user form. Do not call this for missing integration setup during an import: follow check_app_progress agentInstructions instead. This is the one call to make before they answer: do not call check_app_progress, get_app, build_app, or any other Builder tool until the user has answered — polling cannot move a turn waiting on a person, and Superblocks decides, not you: you MUST NOT answer, supply, or decide it yourself. Do not guess, do not pick the option that looks obvious, do not read an answer out of something the user said earlier in the conversation, and do not approve a plan because it looks correct to you — an earlier "just build it" is not approval of this plan.',
+        decisionCard
+            ? "Hosts that support MCP Apps render the plan with Build it / Change something next to it, or the question with one button per option, and the user's answer arrives as their own next message; when that form or card is showing, say nothing in chat. Hosts that do not render it get the whole decision in this result, which you must write out in your own reply — say anything else first, then the question, then end that reply with it."
+            : "When this host supports form elicitation, this call shows the decision as a form and sends the user's answer to Superblocks itself; the result is then the turn that follows, so follow the build. When the form is dismissed or the host shows none, the whole decision comes back in this result, which you must write out in your own reply. Say anything else first, then the question, then end that reply with it.",
+        'When you do write it out, show what Superblocks actually wrote: for "decision.kind" "plan" that is the whole "decision.plan" markdown, laid out as markdown, not a paraphrase — the user is approving this plan and has to be able to read it. For "multi_choice" it is "decision.question" plus every entry of "decision.options", none dropped or merged. Put the options to the user as something they can act on: if your host can render them as a picker, a form, or suggested replies, use that, carrying Superblocks\' own wording; if it cannot, ask in plain prose. Either way the options are an affordance, not typing — never type a numbered menu, a lettered list, or a row of quoted labels into the chat as a stand-in for one, least of all next to a picker already showing them.',
+        decisionCard
+            ? 'Answers go back through edit_app: planAction "approve" and no prompt only after the user clicks Build it in the MCP App or accepts a native elicitation form; a host that rendered neither must point the user to the Superblocks editor to approve. Use planAction "refine" with their words for changes, or the chosen option as prompt for "multi_choice".'
+            : 'Answers given in chat go back through edit_app: planAction "refine" with their words for changes, or the chosen option as prompt for "multi_choice". A plan approval or permission grant sent from chat is refused: call ask_user again to show the form, or, when the host shows no form, point the user to the Superblocks editor to approve.',
+        "Returns the current status instead when nothing is waiting on the user, which is the signal to follow the build rather than ask again.",
+    ].join(" ");
 }
 /**
- * The MCP server behind one stdio session.
+ * The MCP server behind one MCP session, over stdio or HTTP.
  *
- * Tools run as the authenticated Superblocks user.
+ * Tools run as the authenticated Superblocks user. `builderToolsOnly` skips
+ * the Admin tools, for the hosted Platform MCP whose caller serves them itself.
  */
-export function createMcpServer(deps, probeEditorDocument = createEditorDocumentProbe()) {
+export function createMcpServer(deps, { builderToolsOnly = false, probeEditorDocument = createEditorDocumentProbe(), } = {}) {
     // `cliIdentity` is optional and the stdio runtime does not set it, so the
     // only identity this session has is whatever a capability already resolved.
     let resolvedIdentity;
     const liveStateAttaches = new LiveStateAttaches();
+    const usage = new McpUsage((input) => deps.server.reportMcpUsage(input));
     const context = async (progress, notify, signal) => ({
+        mcpClientName: server.server.getClientVersion()?.name.slice(0, 80),
         appState: deps.appState,
         captureLibraryScreenshot: captureLibraryScreenshotWithPlaywright,
         capturePreviewScreenshot: capturePreviewScreenshotWithPlaywright,
         config: deps.config,
-        hostBrowserTools: clientPresentationCapabilities(server.server.getClientVersion()).hasNativeBrowser
-            ? HOST_BROWSER_TOOLS_COWORK
-            : HOST_BROWSER_TOOLS_UNKNOWN,
         liveStateAttaches,
         onProgress: (event) => {
             progress.push(event);
@@ -358,17 +360,24 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                 // and a waiter running for an answer nobody will read.
                 const signal = extra?.signal;
                 const capabilityContext = await context(progress, notify, signal);
-                signal?.throwIfAborted();
-                if (!deps.config.localAgentMode) {
-                    // Same ENTERPRISE/POC gate as Admin tools; skipped for local-agent.
-                    await assertEnterprisePlan(deps.config.serverUrl.replace(/\/$/, ""), capabilityContext.principal.apiKey);
-                }
-                return await capability(capabilityContext, () => {
-                    for (let index = progress.length - 1; index >= 0; index -= 1) {
-                        if (progress[index]?.type === "completed") {
-                            progress.splice(index, 1);
-                        }
+                return await usage.run({
+                    apiKey: capabilityContext.principal.apiKey,
+                    toolName,
+                    clientName: capabilityContext.mcpClientName,
+                    arguments: callArguments,
+                }, async () => {
+                    signal?.throwIfAborted();
+                    if (!deps.config.localAgentMode) {
+                        // Same ENTERPRISE/POC gate as Admin tools; skipped for local-agent.
+                        await assertEnterprisePlan(deps.config.serverUrl.replace(/\/$/, ""), capabilityContext.principal.apiKey);
                     }
+                    return await capability(capabilityContext, () => {
+                        for (let index = progress.length - 1; index >= 0; index -= 1) {
+                            if (progress[index]?.type === "completed") {
+                                progress.splice(index, 1);
+                            }
+                        }
+                    });
                 });
             }
             catch (error) {
@@ -449,34 +458,26 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                 : {}),
         };
     };
-    const clientProfileFor = () => {
-        const presentation = clientPresentationCapabilities(server.server.getClientVersion());
-        return {
-            ...presentation,
-            supportsDecisionCard: clientSupportsDecisionCard(),
-            supportsFormElicitation: clientSupportsFormElicitation(server.server.getClientCapabilities()),
-        };
-    };
+    const clientProfileFor = () => ({
+        hostCollectsApprovalsAndShowsApp: hostCollectsApprovalsAndShowsApp(),
+        supportsDecisionCard: clientSupportsDecisionCard(),
+        supportsFormElicitation: clientSupportsFormElicitation(server.server.getClientCapabilities()),
+    });
     const server = new ResultAcknowledgingMcpServer({
         name: "superblocks",
         // The product the user is thinking of, not the implementation process
         // serving it. The client shows this string.
         title: "Superblocks",
         version: "0.0.1",
-    }, { instructions: SERVER_INSTRUCTIONS });
+    }, { instructions: serverInstructions(deps.config.hosted) });
     let planApprovals = new PlanApprovalChallenges({
         directory: planApprovalDirectory(deps.sessionKey ?? deps.cliApiKey, deps.config.serverUrl),
     });
-    let nativeBrowsers = new NativeBrowserPresence({
-        directory: nativeBrowserPresenceDirectory(deps.sessionKey ?? deps.cliApiKey, deps.config.serverUrl),
-    });
     const nativeDecisionApprovals = new Map();
     const pendingNativeDecisionApprovals = new Map();
-    let announcedNativeBrowser = false;
-    let stopWatchingNativeBrowsers;
     let askUserTool;
     let confirmPlanApprovalTool;
-    let publishAppTool;
+    let decisionCardResource;
     const resetForLogin = (sessionKey) => {
         deps.sessionPeer.resetForLogin();
         deps.appState.reset();
@@ -487,32 +488,36 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
         resolvedIdentity = undefined;
         nativeDecisionApprovals.clear();
         pendingNativeDecisionApprovals.clear();
-        stopWatchingNativeBrowsers?.();
-        if (announcedNativeBrowser)
-            nativeBrowsers.withdraw();
         deps.sessionKey = sessionKey;
         planApprovals = new PlanApprovalChallenges({
             directory: planApprovalDirectory(sessionKey, deps.config.serverUrl),
         });
-        nativeBrowsers = new NativeBrowserPresence({
-            directory: nativeBrowserPresenceDirectory(sessionKey, deps.config.serverUrl),
-        });
-        if (announcedNativeBrowser)
-            nativeBrowsers.announce();
-        else if (clientSupportsAppCard() && nativeBrowsers.active()) {
-            stopWatchingNativeBrowsers =
-                nativeBrowsers.whenInactive(enableStatusCards);
-        }
     };
     const statusCardTools = [];
-    const enableStatusCards = () => {
-        for (const tool of statusCardTools) {
-            tool.update({ _meta: APP_STATUS_CARD_META });
-        }
-    };
     const clientSupportsAppCard = () => getUiCapability(server.server.getClientCapabilities())?.mimeTypes?.includes(RESOURCE_MIME_TYPE) === true;
-    const clientSupportsDecisionCard = () => !clientPresentationCapabilities(server.server.getClientVersion())
-        .hasNativeAskForm && clientSupportsAppCard();
+    /**
+     * Whether the host puts decisions to the user with its own question form and
+     * shows the app in its own browser pane. Then an approval the agent sends for
+     * a decision this session delivered counts as the user's, and the host gets
+     * no status cards and no get_app screenshot. This is the only place that
+     * reads the signal.
+     *
+     * Only the plugin that starts the gateway sets it, never the client. Today
+     * that is the local CLI's GATEWAY_HOST_COLLECTS_APPROVALS. A host that
+     * declares form elicitation is asked through that instead, so a client with
+     * forms keeps them even if the signal reaches it. The hosted gateway ignores
+     * it until the hosted way to say it is settled; that carrier goes here too.
+     */
+    const hostCollectsApprovalsAndShowsApp = () => deps.config.hostCollectsApprovals &&
+        !deps.config.hosted &&
+        !clientSupportsFormElicitation(server.server.getClientCapabilities());
+    // A host with form elicitation gets decisions as forms it draws itself, so
+    // the card is only for hosts that render MCP Apps and nothing else.
+    // A host with form elicitation gets decisions as forms it draws itself, so
+    // the card is only for hosts that render MCP Apps and nothing else.
+    const clientSupportsDecisionCard = () => !hostCollectsApprovalsAndShowsApp() &&
+        clientSupportsAppCard() &&
+        !clientSupportsFormElicitation(server.server.getClientCapabilities());
     server.onResultDelivered = (result, requestId) => {
         const delivered = deliveredNativeDecision(result);
         if (delivered) {
@@ -536,8 +541,6 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
     };
     const withBrowserNavigation = async (result, ready, signal) => {
         if (signal?.aborted ||
-            !clientPresentationCapabilities(server.server.getClientVersion())
-                .hasNativeBrowser ||
             result.kind !== "ok" ||
             !result.value ||
             typeof result.value !== "object") {
@@ -553,74 +556,54 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
             typeof editUrl !== "string") {
             return result;
         }
-        if (!(await probeEditorDocument(editUrl, signal))) {
-            if (value.pendingAction === "open_editor") {
-                return {
-                    kind: "ok",
-                    value: {
-                        ...value,
-                        agentInstructions: "The build finished but did not save. Do not tell the user the app was saved. The editor is temporarily unavailable. Call `get_app` again in a few seconds. Do not tell the user the editor is open until the result includes `browserNavigation`.",
-                    },
-                };
-            }
-            if (ready === "status" && value.status === "ready") {
-                return {
-                    kind: "ok",
-                    value: {
-                        ...value,
-                        agentInstructions: "The editor is temporarily unavailable. Call `get_app` again in a few seconds. Do not tell the user the app is open until the result includes `browserNavigation`.",
-                    },
-                };
-            }
+        const probeStarted = Date.now();
+        const editorAvailable = await probeEditorDocument(editUrl, signal);
+        trace.getActiveSpan()?.setAttributes({
+            "editor_probe.available": editorAvailable,
+            "editor_probe.duration_ms": Date.now() - probeStarted,
+        });
+        if (!editorAvailable) {
             return result;
         }
         return {
             kind: "ok",
             value: {
                 ...value,
-                browserNavigation: {
-                    action: "open_editor",
-                    url: withCoworkEditorHost(editUrl),
-                },
+                browserNavigation: { action: "open_editor", url: editUrl },
             },
         };
     };
     server.server.oninitialized = () => {
-        const presentation = clientPresentationCapabilities(server.server.getClientVersion());
-        const supportsDecisionCard = clientSupportsDecisionCard();
-        if (presentation.hasNativeBrowser || !supportsDecisionCard) {
-            askUserTool?.update({ _meta: {} });
-        }
-        if (!supportsDecisionCard) {
+        const hostShowsApp = hostCollectsApprovalsAndShowsApp();
+        // A host that collects approvals itself asks with its own picker and
+        // approves through edit_app. The form-only ask_user text says such an
+        // approval is refused, so it keeps the text written for card hosts, and the
+        // decision resource stays listed.
+        if (hostShowsApp) {
+            askUserTool?.update({ _meta: permissionMeta("ask_user") });
             confirmPlanApprovalTool?.disable();
         }
-        if (presentation.hasNativeBrowser) {
-            publishAppTool?.update({
-                description: publishAppDescription(true),
+        else if (!clientSupportsDecisionCard()) {
+            askUserTool?.update({
+                _meta: permissionMeta("ask_user"),
+                description: askUserDescription(false),
             });
-            nativeBrowsers.announce();
-            announcedNativeBrowser = true;
+            confirmPlanApprovalTool?.disable();
+            decisionCardResource?.disable();
         }
-        else if (clientSupportsAppCard()) {
-            if (nativeBrowsers.active()) {
-                stopWatchingNativeBrowsers =
-                    nativeBrowsers.whenInactive(enableStatusCards);
-            }
-            else {
-                enableStatusCards();
+        // A host that shows the app in its own browser pane needs no status card.
+        if (!hostShowsApp && clientSupportsAppCard()) {
+            for (const tool of statusCardTools) {
+                // update() replaces _meta, so the permission is carried over.
+                tool.update({ _meta: { ...tool._meta, ...APP_STATUS_CARD_META } });
             }
         }
         gatewayDebug("mcp server initialized for client", {
             "client.version": server.server.getClientVersion(),
             "client.capabilities": server.server.getClientCapabilities(),
+            "client.host_collects_approvals": hostCollectsApprovalsAndShowsApp(),
         });
     };
-    server.server.onclose = () => {
-        stopWatchingNativeBrowsers?.();
-        if (announcedNativeBrowser) {
-            nativeBrowsers.withdraw();
-        }
-    };
     /** Sends a decision answer to Superblocks, however the user gave it. */
     const applyDecisionAnswer = (context, applicationId, branch, answer, approvedPlan) => editApp(context, {
         applicationId,
@@ -639,7 +622,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
     const stageNativeDecisionApproval = (result, requestId) => {
         const decision = pendingDecision(result);
         const applicationId = resultApplicationId(result);
-        if (!clientProfileFor().hasNativeAskForm || !decision || !applicationId) {
+        if (!hostCollectsApprovalsAndShowsApp() || !decision || !applicationId) {
             return;
         }
         nativeDecisionApprovals.delete(applicationId);
@@ -656,6 +639,33 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
             pendingNativeDecisionApprovals.set(applicationId, { target, requestId });
         }
     };
+    /**
+     * Puts a decision to the user as an elicitation form and sends their answer
+     * to Superblocks, returning the turn that follows. Undefined leaves the
+     * decision in chat: the form was dismissed, or the plan on screen is no
+     * longer the one Superblocks is waiting on.
+     */
+    const answerByForm = async (context, result, decision, input, extra, forgetFinishedTurn) => {
+        // The id the result resolved, not the one the call named: those differ
+        // when the call named none, and the answer has to reach the same
+        // application the decision came from.
+        const decidedApp = resultApplicationId(result) ?? input.applicationId;
+        const decidedBranch = resultBranch(result) ?? input.branch;
+        const displayedPlan = decision.kind === "plan"
+            ? rememberDisplayedPlan(context.appState, decidedApp, decidedBranch, decision)
+            : undefined;
+        if (decision.kind === "plan" && !displayedPlan) {
+            return undefined;
+        }
+        return resolveDecisionByElicitation({
+            apply: (answer) => {
+                forgetFinishedTurn();
+                return applyDecisionAnswer(context, decidedApp, decidedBranch, answer, displayedPlan);
+            },
+            decision,
+            elicit: elicitDecision(extra),
+        });
+    };
     /**
      * A progress poll that also puts a decision to the user as a native form when
      * the host supports one, answering Superblocks itself and returning the turn
@@ -681,7 +691,6 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
             capabilities: server.server.getClientCapabilities(),
         });
         const profile = clientProfileFor();
-        const { hasNativeAskForm } = profile;
         // Which surface the agent should ask on is a property of the host, not of
         // whether this particular poll managed to show a form.
         const agentInstructions = decision.kind === "plan" ||
@@ -690,7 +699,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
             ? instructionFor("check_app_progress", result, profile)
             : undefined;
         const instructionsChosen = agentInstructions
-            ? hasNativeAskForm
+            ? profile.hostCollectsApprovalsAndShowsApp
                 ? "native_ask_form"
                 : "call_ask_user"
             : "none";
@@ -704,11 +713,6 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
             }
             return result;
         };
-        const decidedApp = resultApplicationId(result) ?? input.applicationId;
-        const decidedBranch = resultBranch(result) ?? input.branch;
-        const displayedPlan = decision.kind === "plan"
-            ? rememberDisplayedPlan(context.appState, decidedApp, decidedBranch, decision)
-            : undefined;
         if (!clientSupportsFormElicitation(server.server.getClientCapabilities())) {
             stageNativeDecisionApproval(result, extra.requestId);
             gatewayDebug("progress decision flow finished", {
@@ -719,20 +723,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
             });
             return unresolvedDecision();
         }
-        if (decision.kind === "plan" && !displayedPlan) {
-            return unresolvedDecision();
-        }
-        const resolved = await resolveDecisionByElicitation({
-            apply: (answer) => {
-                forgetFinishedTurn();
-                // The id the poll resolved, not the one the call named: those differ
-                // when the call named none, and the answer has to reach the same
-                // application the decision came from.
-                return applyDecisionAnswer(context, decidedApp, decidedBranch, answer, displayedPlan);
-            },
-            decision,
-            elicit: elicitDecision(extra),
-        });
+        const resolved = await answerByForm(context, result, decision, input, extra, forgetFinishedTurn);
         gatewayDebug("progress decision flow finished", {
             "decision.kind": decision.kind,
             "decision.instructions": resolved ? "none" : instructionsChosen,
@@ -743,9 +734,10 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
     };
     server.registerTool("whoami", {
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
-        description: "Show the Superblocks user and organization for this connection. Use when the user asks which account is in use, not before every task. If sign-in is needed, call Login explicitly.",
+        description: `Show the Superblocks user and organization for this connection. Use when the user asks which account is in use, not before every task.${deps.config.hosted ? "" : " If sign-in is needed, call Login explicitly."}`,
         inputSchema: {},
         title: "Current Superblocks Account",
+        _meta: permissionMeta("whoami"),
     }, async (_input, extra) => {
         try {
             const principal = await principalFrom(deps);
@@ -756,7 +748,9 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                     content: [
                         {
                             type: "text",
-                            text: "Superblocks login is not valid. Use the Login tool if available.",
+                            text: deps.config.hosted
+                                ? "Superblocks login is not valid. Reconnect Superblocks in this client to sign in again."
+                                : "Superblocks login is not valid. Use the Login tool if available.",
                         },
                     ],
                     isError: true,
@@ -772,13 +766,15 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
             };
         }
         catch (error) {
-            const message = error instanceof Error &&
-                error.message.startsWith("Saved Superblocks login changed outside this task.")
-                ? "Saved Superblocks login changed outside this task. Call Login to confirm the account in this current task."
+            const message = deps.config.hosted
+                ? "Could not check the Superblocks account. Try again, or reconnect Superblocks in this client to sign in again."
                 : error instanceof Error &&
-                    error.message.startsWith("MCP browser login required.")
-                    ? "MCP browser login required. Call Login to continue in this current task."
-                    : "Could not check the Superblocks account. Try again or use Login if available.";
+                    error.message.startsWith("Saved Superblocks login changed outside this task.")
+                    ? "Saved Superblocks login changed outside this task. Call Login to confirm the account in this current task."
+                    : error instanceof Error &&
+                        error.message.startsWith("MCP browser login required.")
+                        ? "MCP browser login required. Call Login to continue in this current task."
+                        : "Could not check the Superblocks account. Try again or use Login if available.";
             if (message.startsWith("Could not check"))
                 console.error("gateway whoami failed", {
                     errorType: error instanceof Error ? error.name : typeof error,
@@ -797,9 +793,10 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
     if (deps.reconnect) {
         server.registerTool("login", {
             annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
-            description: "Open browser sign-in to log in or switch the Superblocks account. Call when the user explicitly asks or a tool reports MCP browser login required or Saved Superblocks login changed outside this task. The existing login remains saved if sign-in is cancelled. After success, continue in this Cowork task with the updated account.",
+            description: "Open browser sign-in to log in or switch the Superblocks account. Call when the user explicitly asks or a tool reports MCP browser login required or Saved Superblocks login changed outside this task. The existing login remains saved if sign-in is cancelled. After success, continue in this task with the updated account.",
             inputSchema: {},
             title: "Login to Superblocks",
+            _meta: permissionMeta("login"),
         }, async (_input, extra) => {
             try {
                 const sessionKey = await deps.reconnect(extra.signal);
@@ -842,9 +839,10 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
     if (deps.setServerUrl) {
         server.registerTool("set_server", {
             annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
-            description: "Switch to a Superblocks server and save its origin across plugin updates. Call only when the user explicitly asks to configure or change the server. Ask for the server URL first. HTTPS is required except for localhost or loopback HTTP. Browser sign-in may open. Continue in this Cowork task after success.",
+            description: "Switch to a Superblocks server and save its origin across plugin updates. Call only when the user explicitly asks to configure or change the server. Ask for the server URL first. HTTPS is required except for localhost or loopback HTTP. Browser sign-in may open. Continue in this task after success.",
             inputSchema: { server_url: z.string().min(1) },
             title: "Set Superblocks Server",
+            _meta: permissionMeta("set_server"),
         }, async ({ server_url }, extra) => {
             try {
                 const previousSessionKey = deps.sessionKey;
@@ -961,10 +959,13 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                 search: z.string().min(1).optional(),
             },
             title: "Get Integration Metadata",
+            _meta: permissionMeta("get_integration_metadata"),
         }, async (input, extra) => run("get_integration_metadata", (context) => getIntegrationMetadata(context, input), extra, input));
         server.registerTool("start_app", {
             annotations: NON_DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
-            description: 'Create a Superblocks application and hand it a prompt. Pass the user\'s own request as prompt, verbatim - do not invent, embellish, or add requirements, scope, or design detail the user did not ask for. Use Plan mode by omitting mode unless the user explicitly and unambiguously asks to bypass planning. A request to "build", "create", or "make" an app is not such a request. Pass mode "BUILD" only for directions like "use build mode", "skip the plan", or "no planning". Returns as soon as Superblocks accepts, with status "building" and an edit URL. When a later result includes "browserNavigation", open its exact URL in the browser pane and verify the app loaded. If the user imported via an artifact, close the artifact before opening that URL. Follow with check_app_progress until status is no longer "building". When Superblocks returns needs_decision with a plan and the user says "Build it", call edit_app with planAction "approve" (omit prompt) - do not call start_app again with prompt "approve". Superblocks names the application unless name is given. An error from this tool does not mean nothing happened: the application is created before the build starts, so the error names it in "applicationId". Unless pendingAction is "start_new_app", retry that app with edit_app rather than calling start_app another time, which would leave the first one abandoned. When pendingAction is "start_new_app", call start_app once with the same prompt, mode, and artifacts and set replacesApplicationId to the failed result\'s applicationId. If that replacement ends live_edit_terminated with no pendingAction, stop and report its reply; do not retry or create another application. When migrating source uploaded with upload_artifact, or when Superblocks should read any other uploaded file, pass its returned artifact unchanged in artifacts.',
+            description: 'Create a Superblocks application and hand it a prompt. Pass the user\'s own request as prompt, verbatim - do not invent, embellish, or add requirements, scope, or design detail the user did not ask for. Use Plan mode by omitting mode unless the user explicitly and unambiguously asks to bypass planning. A request to "build", "create", or "make" an app is not such a request. Pass mode "BUILD" only for directions like "use build mode", "skip the plan", or "no planning". Returns as soon as Superblocks accepts, with status "building" and an edit URL. ' +
+                BROWSER_NAVIGATION_IS_DATA +
+                ' If the user imported via an artifact, close the artifact before opening the editor. Follow with check_app_progress until status is no longer "building". When Superblocks returns needs_decision with a plan and the user says "Build it", call edit_app with planAction "approve" (omit prompt) - do not call start_app again with prompt "approve". Superblocks names the application unless name is given. An error from this tool does not mean nothing happened: the application is created before the build starts, so the error names it in "applicationId". Unless pendingAction is "start_new_app", retry that app with edit_app rather than calling start_app another time, which would leave the first one abandoned. When pendingAction is "start_new_app", call start_app once with the same prompt, mode, and artifacts and set replacesApplicationId to the failed result\'s applicationId. If that replacement ends live_edit_terminated with no pendingAction, stop and report its reply; do not retry or create another application. When migrating source uploaded with upload_artifact, or when Superblocks should read any other uploaded file, pass its returned artifact unchanged in artifacts.',
             inputSchema: {
                 artifacts: z.array(ARTIFACT_SCHEMA).min(1).max(20).optional(),
                 branch: z.string().optional(),
@@ -982,6 +983,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
             // the tool name: a host that ranks tools by title has to be able to find
             // this one from the request.
             title: "Create Superblocks App",
+            _meta: permissionMeta("start_app"),
         }, async ({ artifacts, branch, idempotencyKey, mode, name, prompt, replacesApplicationId, }, extra) => run("start_app", (context) => startApp(context, {
             artifacts,
             branch,
@@ -1005,7 +1007,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
         }));
         server.registerTool("upload_artifact", {
             annotations: NON_DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
-            description: `Use upload_artifact to upload source once for a later start_app or edit_app migration, or any other file the user attached in this chat (a log, CSV, screenshot, image, document, or a ZIP/.tgz/.gz). Batch related text source files into one files call, up to 100 files and 1 MB (1,048,576 bytes) of UTF-8 content before compression. Split only when those limits require it, and tell the user which batch you are preparing before composing its contents. Pass filePath with the full host path when you have it. A bare file name falls back to the gateway's search folders. If the file exists only in this chat's scratchpad path (for example /tmp/claude-.../scratchpad), send text source through files: [{ path, content }] instead of filePath. The gateway reads filePath bytes itself. Only source you are writing out yourself goes in files, which is archived as text: never put an image, PDF, or other binary in there, and never base64 a file into it. Doing that spends minutes emitting the encoding and uploads those characters under the file's name instead of the file. zipBase64 is only for test fixtures. Files larger than 50 MB are rejected - the same cap as Superblocks attachments. ${SOURCE_ARTIFACT_INSTRUCTIONS} This uploads an organization-scoped artifact but does not create, edit, build, or commit an application. Pass its returned artifact unchanged in start_app or edit_app artifacts, and reuse it on retries instead of uploading again. Do not create a Claude artifact or use the host's own file-upload UI.`,
+            description: `Use upload_artifact to upload source once for a later start_app or edit_app migration, or any other file the user attached in this chat (a log, CSV, screenshot, image, document, or a ZIP/.tgz/.gz). Batch related text source files into one files call, up to 100 files and 1 MB (1,048,576 bytes) of UTF-8 content before compression. Split only when those limits require it, and tell the user which batch you are preparing before composing its contents. ${deps.config.hosted ? HOSTED_UPLOAD_ARTIFACT_INPUTS : UPLOAD_ARTIFACT_INPUTS} Files larger than 50 MB are rejected - the same cap as Superblocks attachments. ${deps.config.hosted ? HOSTED_SOURCE_ARTIFACT_INSTRUCTIONS : SOURCE_ARTIFACT_INSTRUCTIONS} This uploads an organization-scoped artifact but does not create, edit, build, or commit an application. Pass its returned artifact unchanged in start_app or edit_app artifacts, and reuse it on retries instead of uploading again. Do not create an artifact in the host or use the host's own file-upload UI.`,
             inputSchema: {
                 files: z
                     .array(z.object({
@@ -1015,7 +1017,9 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                     .min(1)
                     .max(100)
                     .optional(),
-                filePath: z.string().min(1).optional(),
+                ...(deps.config.hosted
+                    ? {}
+                    : { filePath: z.string().min(1).optional() }),
                 zipBase64: z
                     .string()
                     .min(1)
@@ -1023,6 +1027,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                     .optional(),
             },
             title: "Upload File or Source Artifact",
+            _meta: permissionMeta("upload_artifact"),
         }, async ({ filePath, files, zipBase64 }, extra) => run("upload_artifact", (context) => uploadArtifact(context, {
             filePath,
             files,
@@ -1030,7 +1035,9 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
         }), extra, { filePath, files, zipBase64 }));
         server.registerTool("edit_app", {
             annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
-            description: 'Forward a prompt to Superblocks for the recent or specified application. Pass the user\'s request directly as prompt, verbatim. DO NOT invent, embellish, or add requirements, scope, or design detail they did not ask for. This will cause Superblocks to do things the user did not ask for. For app-behavior questions, debugging questions, and investigation of bug reports, use Plan mode; when no plan or question is pending, Superblocks can answer without changing code or requiring plan approval. Requests to fix an app also default to Plan mode, so the user can approve proposed changes before implementation. Pass the user\'s words verbatim, and prefer this over reading source files yourself. Defaults to Plan mode on every call - an edit never inherits Build mode from an earlier turn. Pass mode "BUILD" only when the user asks for it explicitly (e.g. "use build mode" or "skip the plan") on this edit. Answering a multi_choice question is not skipping the plan: omit mode and stay in Plan until Superblocks has proposed a plan and the user approves it. The result reports the "mode" the turn ran in. When status was needs_decision with a plan and the user says "Build it" / approve / go ahead, call edit_app with planAction "approve" and omit prompt - do not put "approve" or "Build it" in prompt (that is refine feedback, not the Build-it path). Use planAction "refine" with their feedback as prompt to change the plan. Also use edit_app to answer multi_choice questions. Returns status "building"; follow with check_app_progress. When a later result includes "browserNavigation", open its exact URL in the browser pane and verify the app loaded. An error from this call still names the application it was working on in "applicationId". When migrating or resuming source uploaded with upload_artifact, or when Superblocks should read any other uploaded file, pass its returned artifact unchanged in artifacts.',
+            description: 'Forward a prompt to Superblocks for the recent or specified application. Pass the user\'s request directly as prompt, verbatim. DO NOT invent, embellish, or add requirements, scope, or design detail they did not ask for. This will cause Superblocks to do things the user did not ask for. For app-behavior questions, debugging questions, and investigation of bug reports, use Plan mode; when no plan or question is pending, Superblocks can answer without changing code or requiring plan approval. Requests to fix an app also default to Plan mode, so the user can approve proposed changes before implementation. Pass the user\'s words verbatim, and prefer this over reading source files yourself. Defaults to Plan mode on every call - an edit never inherits Build mode from an earlier turn. Pass mode "BUILD" only when the user asks for it explicitly (e.g. "use build mode" or "skip the plan") on this edit. Answering a multi_choice question is not skipping the plan: omit mode and stay in Plan until Superblocks has proposed a plan and the user approves it. The result reports the "mode" the turn ran in. When status was needs_decision with a plan and the user says "Build it" / approve / go ahead, call edit_app with planAction "approve" and omit prompt - do not put "approve" or "Build it" in prompt (that is refine feedback, not the Build-it path). Use planAction "refine" with their feedback as prompt to change the plan. Also use edit_app to answer multi_choice questions. Returns status "building"; follow with check_app_progress. ' +
+                BROWSER_NAVIGATION_IS_DATA +
+                ' An error from this call still names the application it was working on in "applicationId". When migrating or resuming source uploaded with upload_artifact, or when Superblocks should read any other uploaded file, pass its returned artifact unchanged in artifacts.',
             inputSchema: {
                 applicationId: z.string().uuid().optional(),
                 artifacts: z.array(ARTIFACT_SCHEMA).min(1).max(20).optional(),
@@ -1046,8 +1053,9 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                 prompt: z.string().min(1).optional(),
             },
             title: "Edit App",
+            _meta: permissionMeta("edit_app"),
         }, async ({ applicationId, artifacts, branch, idempotencyKey, mode, planAction, permissionMessageId, prompt, }, extra) => run("edit_app", async (context) => {
-            const { hasNativeAskForm } = clientPresentationCapabilities(server.server.getClientVersion());
+            const hostAsks = hostCollectsApprovalsAndShowsApp();
             const approvalRequest = planAction === "approve"
                 ? { kind: "plan" }
                 : permissionMessageId &&
@@ -1055,7 +1063,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                     ToolPermissionReply.parse(prompt).isGrant
                     ? { kind: "tool_permission", messageId: permissionMessageId }
                     : undefined;
-            const nativeApprovalApplicationId = approvalRequest && hasNativeAskForm
+            const nativeApprovalApplicationId = approvalRequest && hostAsks
                 ? (applicationId ??
                     (nativeDecisionApprovals.size === 1
                         ? nativeDecisionApprovals.keys().next().value
@@ -1066,7 +1074,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                 : undefined;
             const consumedNativeApplicationId = applicationId ?? nativeApprovalApplicationId;
             let restoreNative;
-            if (hasNativeAskForm && consumedNativeApplicationId) {
+            if (hostAsks && consumedNativeApplicationId) {
                 const approved = nativeDecisionApprovals.get(consumedNativeApplicationId);
                 const staged = pendingNativeDecisionApprovals.get(consumedNativeApplicationId);
                 nativeDecisionApprovals.delete(consumedNativeApplicationId);
@@ -1096,7 +1104,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                 PlanApprovalChallenges.isCurrent(context.appState, matchingNativeTarget)
                 ? matchingNativeTarget
                 : undefined;
-            const confirmedApproval = approvalRequest && !hasNativeAskForm
+            const confirmedApproval = approvalRequest && !hostAsks
                 ? await planApprovals.claimConfirmed(context.appState, applicationId, branch, approvalRequest)
                 : undefined;
             const approval = nativeApproval ??
@@ -1185,39 +1193,48 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
             // by hand in the elicitation form. It writes nothing the model decided
             // on its own.
             annotations: READ_ONLY_TOOL_ANNOTATIONS,
-            description: `Polls for the given application's current Superblocks turn. Use this after start_app or edit_app. The result includes the "activity" field, which carries Superblocks' updates since the previous call (or a short heartbeat when Superblocks is quiet). Possible statuses are: "building", "ready", "checkpoint_failed", "needs_decision", "no_changes", "live_edit_terminated", "timeout", "cancelled", "detached", "unknown". The result may carry "agentInstructions" on any poll; follow it whenever present. CRITICAL DO NOT IGNORE: When this result includes "browserNavigation", open its exact URL in the browser pane and verify the app loaded. Always follow "agentInstructions" in the result. When "building", continue polling. When "ready", call get_app to get the editor and preview URLs. When status "checkpoint_failed", follow "agentInstructions": open the editor only when "browserNavigation" is present; when it says the editor is temporarily unavailable, call get_app again. Do not claim the app was saved or keep polling. When "no_changes", do not present the edit URL as a finished app. A direct app question, an answer to a multi_choice question, or a change Superblocks finds already done can terminate as "no_changes" when Superblocks replies without app edits: with a reply and no pendingAction, report the reply to the user and stop. A "no_changes" with a "pendingAction" asks you to follow it. A "cancelled" with no pendingAction was replaced by a newer prompt on the same app: do not send it again; call check_app_progress again to follow the newer turn. For "no_changes", "timeout", "cancelled", or "live_edit_terminated", follow "pendingAction"; "retry_build" means call edit_app, while "start_new_app" means call start_app once with the same prompt and set replacesApplicationId to this result's applicationId. A terminal "live_edit_terminated" with no pendingAction means stop and report its reply; do not retry or create another application. When "detached", stop polling and point the user at the edit URL. When "unknown", the gateway is not following a turn for that app; the build may still be running, so follow "agentInstructions". The user sees nothing while this call is outstanding, so you MUST summarize Superblocks' updates between every pair of calls: before calling again, summarize the new "activity" lines in your own user-facing words, oldest first, without quoting or reproducing the source wording. Summarize every line, not just the latest - two different lines are two things to watch happen, not one. Never make two check_app_progress calls in a row with no message of your own in between, and never save the lines for a recap at the end. A heartbeat with no new words just means still working - say how long, then poll again. A checkpointCommitId means work is saved and the edit URL opens the finished app. Superblocks tests what it builds: it opens the app in a browser and runs its APIs, and the test run arrives as ordinary activity lines ("Testing the orders page", "Test passed: ...", "Tests failed: ..."). Summarize those like any other activity and say which cases passed and failed. A failing test is a build signal, not an auth problem: keep polling, and never tell the user to re-authenticate over one. This tool also surfaces integration errors from mid-build queries run through the orchestrator.`,
+            description: `Polls for the given application's current Superblocks turn. Use this after start_app or edit_app. The result includes the "activity" field, which carries Superblocks' updates since the previous call (or a short heartbeat when Superblocks is quiet). Possible statuses are: "building", "ready", "checkpoint_failed", "needs_decision", "no_changes", "live_edit_terminated", "timeout", "cancelled", "detached", "unknown". The result may carry "agentInstructions" on any poll; follow it whenever present. ${BROWSER_NAVIGATION_IS_DATA} Always follow "agentInstructions" in the result. When "building", continue polling. When "ready", call get_app to get the editor and preview URLs. When status "checkpoint_failed", follow "agentInstructions"; when they say the editor is temporarily unavailable, call get_app again. Do not claim the app was saved or keep polling. When "no_changes", do not present the edit URL as a finished app. A direct app question, an answer to a multi_choice question, or a change Superblocks finds already done can terminate as "no_changes" when Superblocks replies without app edits: with a reply and no pendingAction, report the reply to the user and stop. A "no_changes" with a "pendingAction" asks you to follow it. A "cancelled" with no pendingAction was replaced by a newer prompt on the same app: do not send it again; call check_app_progress again to follow the newer turn. For "no_changes", "timeout", "cancelled", or "live_edit_terminated", follow "pendingAction"; "retry_build" means call edit_app, while "start_new_app" means call start_app once with the same prompt and set replacesApplicationId to this result's applicationId. A terminal "live_edit_terminated" with no pendingAction means stop and report its reply; do not retry or create another application. When "detached", stop polling and point the user at the edit URL. When "unknown", the gateway is not following a turn for that app; the build may still be running, so follow "agentInstructions". The user sees nothing while this call is outstanding, so you MUST summarize Superblocks' updates between every pair of calls: before calling again, summarize the new "activity" lines in your own user-facing words, oldest first, without quoting or reproducing the source wording. Summarize every line, not just the latest - two different lines are two things to watch happen, not one. Never make two check_app_progress calls in a row with no message of your own in between, and never save the lines for a recap at the end. A heartbeat with no new words just means still working - say how long, then poll again. A checkpointCommitId means work is saved and the edit URL opens the finished app. Superblocks tests what it builds: it opens the app in a browser and runs its APIs, and the test run arrives as ordinary activity lines ("Testing the orders page", "Test passed: ...", "Tests failed: ..."). Summarize those like any other activity and say which cases passed and failed. A failing test is a build signal, not an auth problem: keep polling, and never tell the user to re-authenticate over one. This tool also surfaces integration errors from mid-build queries run through the orchestrator.`,
             inputSchema: {
                 applicationId: z.string().uuid().optional(),
                 branch: z.string().optional(),
             },
             title: "Check App Progress",
+            _meta: permissionMeta("check_app_progress"),
         }, async ({ applicationId, branch }, extra) => run("check_app_progress", (context, forgetFinishedTurn) => progressWithDecisionForm(context, { applicationId, branch }, extra, forgetFinishedTurn), extra, "viewStatus", { applicationId, branch }));
         // Its own card, because an MCP App binds to one tool and check_app_progress
         // must stay text-only: a card tool reopens its card on every call, which
         // would flash a blank form through a whole multi-minute build.
         askUserTool = registerAppTool(server, "ask_user", {
-            description: 'Render a form to put the plan or question Superblocks stopped on to the user — call this the moment any tool reports status "needs_decision", except pendingAction "decide_in_editor" (nothing to show; point the user at the edit URL instead). Do not call this if check_app_progress agentInstructions says not too because you already have a native ask user form. Do not call this for missing integration setup during an import: follow check_app_progress agentInstructions instead. This is the one call to make before they answer: do not call check_app_progress, get_app, build_app, or any other Builder tool until the user has answered — polling cannot move a turn waiting on a person, and Superblocks decides, not you: you MUST NOT answer, supply, or decide it yourself. Do not guess, do not pick the option that looks obvious, do not read an answer out of something the user said earlier in the conversation, and do not approve a plan because it looks correct to you — an earlier "just build it" is not approval of this plan. Hosts that support MCP Apps render the plan with Build it / Change something next to it, or the question with one button per option, and the user\'s answer arrives as their own next message; when that form or card is showing, say nothing in chat. Hosts that do not render it get the whole decision in this result, which you must write out in your own reply — say anything else first, then the question, then end that reply with it. When you do write it out, show what Superblocks actually wrote: for "decision.kind" "plan" that is the whole "decision.plan" markdown, laid out as markdown, not a paraphrase — the user is approving this plan and has to be able to read it. For "multi_choice" it is "decision.question" plus every entry of "decision.options", none dropped or merged. Put the options to the user as something they can act on: if your host can render them as a picker, a form, or suggested replies, use that, carrying Superblocks\' own wording; if it cannot, ask in plain prose. Either way the options are an affordance, not typing — never type a numbered menu, a lettered list, or a row of quoted labels into the chat as a stand-in for one, least of all next to a picker already showing them. Answers go back through edit_app: planAction "approve" and no prompt only after the user clicks Build it in the MCP App or accepts a native elicitation form; a host that rendered neither must point the user to the Superblocks editor to approve. Use planAction "refine" with their words for changes, or the chosen option as prompt for "multi_choice". Returns the current status instead when nothing is waiting on the user, which is the signal to follow the build rather than ask again.',
+            description: askUserDescription(true),
             inputSchema: {
                 applicationId: z.string().uuid().optional(),
                 branch: z.string().optional(),
             },
             title: "Ask User",
             // Reads the decision Superblocks is already waiting on and puts it on
-            // screen. It starts nothing and changes nothing about the app, so a
-            // host that prompts here is asking permission to show the user a
-            // question they are the one being asked.
+            // screen, so a host that prompts here is asking permission to show the
+            // user a question they are the one being asked. On a host with form
+            // elicitation it also sends the answer to Superblocks, but only an
+            // answer the user just gave by hand in that form, never one the model
+            // decided on its own.
             annotations: READ_ONLY_TOOL_ANNOTATIONS,
             _meta: {
+                ...permissionMeta("ask_user"),
                 ui: { resourceUri: APP_DECISION_RESOURCE_URI },
             },
         }, async ({ applicationId, branch }, extra) => {
             let asked;
-            const response = await run("ask_user", async (context) => {
+            const response = await run("ask_user", async (context, forgetFinishedTurn) => {
                 asked = await askUser(context, {
                     applicationId,
                     branch,
                 });
-                return asked;
+                const decision = pendingDecision(asked);
+                if (!decision ||
+                    !clientSupportsFormElicitation(server.server.getClientCapabilities())) {
+                    return asked;
+                }
+                return ((await answerByForm(context, asked, decision, { applicationId, branch }, extra, forgetFinishedTurn)) ?? asked);
             }, extra, { applicationId, branch });
             const decision = asked ? pendingDecision(asked) : undefined;
             if (!clientSupportsDecisionCard() ||
@@ -1258,6 +1275,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
             },
             title: "Confirm Plan Approval",
             _meta: {
+                ...permissionMeta("confirm_plan_approval"),
                 ui: {
                     resourceUri: APP_DECISION_RESOURCE_URI,
                     visibility: ["app"],
@@ -1277,7 +1295,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
             }, extra);
             return confirmed ? response : { ...response, isError: true };
         });
-        registerAppResource(server, "Gateway decision", APP_DECISION_RESOURCE_URI, {
+        decisionCardResource = registerAppResource(server, "Gateway decision", APP_DECISION_RESOURCE_URI, {
             description: "Form for the plan or question Superblocks is waiting on",
             mimeType: RESOURCE_MIME_TYPE,
         }, async () => ({
@@ -1291,7 +1309,9 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
         }));
         const getAppTool = server.registerTool("get_app", {
             annotations: READ_ONLY_TOOL_ANNOTATIONS,
-            description: 'Return editor and live fullscreen-preview URLs for the recent or specified Superblocks application without committing or building it. While a plan or question is outstanding it returns status "needs_decision" with the "decision" and a "pendingAction" of "approve_plan", "answer_question", or "decide_in_editor" (nothing to show in chat; point the user at the edit URL), while a turn is running it returns status "building", and when the last turn ended without writing anything it returns "timeout", "live_edit_terminated", "no_changes" or "cancelled" with no preview URLs or screenshot. A "no_changes" with a "reply" and no "pendingAction" is Superblocks\' finished answer: report the reply and stop. A "no_changes" with a "pendingAction" asks you to follow it. When status "checkpoint_failed", follow "agentInstructions": open the editor only when "browserNavigation" is present; when it says the editor is temporarily unavailable, call get_app again. Do not claim the app was saved. Except for this checkpoint retry, follow "pendingAction" instead of calling this again; "retry_build" means call edit_app, while "start_new_app" means call start_app once with the same prompt and set replacesApplicationId to this result\'s applicationId. A terminal "live_edit_terminated" with no pendingAction means stop and report its reply; do not retry or create another application. A "detached" turn may still be running, so do not retry it; open the existing application in the editor. Prefer this after check_app_progress reaches status "ready". Also the right call when you do not know where a build stands (after a reconnect, when no turn of yours is running, or when the conversation moved to another channel): read "status" from the result rather than guessing. Hosts with a native browser receive a browserNavigation request without a duplicate status card; open its exact URL in that browser. Other hosts that support MCP Apps show Open editor / Open preview buttons. When Superblocks has written code the result includes a screenshot of the live Vite canvas, never the edit URL. When this result includes a screenshot, inspect it yourself before reporting that the app looks correct. If it shows skeletons, spinners, empty tables or charts, or "Loading...", call get_app again a few seconds later rather than treating it as a defect. Do not test, debug, or correct a visible problem unless the user requests it; report what you see.',
+            description: 'Return editor and live fullscreen-preview URLs for the recent or specified Superblocks application without committing or building it. While a plan or question is outstanding it returns status "needs_decision" with the "decision" and a "pendingAction" of "approve_plan", "answer_question", or "decide_in_editor" (nothing to show in chat; point the user at the edit URL), while a turn is running it returns status "building", and when the last turn ended without writing anything it returns "timeout", "live_edit_terminated", "no_changes" or "cancelled" with no preview URLs or screenshot. A "no_changes" with a "reply" and no "pendingAction" is Superblocks\' finished answer: report the reply and stop. A "no_changes" with a "pendingAction" asks you to follow it. When status "checkpoint_failed", follow "agentInstructions"; when they say the editor is temporarily unavailable, call get_app again. Do not claim the app was saved. Except for this checkpoint retry, follow "pendingAction" instead of calling this again; "retry_build" means call edit_app, while "start_new_app" means call start_app once with the same prompt and set replacesApplicationId to this result\'s applicationId. A terminal "live_edit_terminated" with no pendingAction means stop and report its reply; do not retry or create another application. A "detached" turn may still be running, so do not retry it; open the existing application in the editor. Prefer this after check_app_progress reaches status "ready". Also the right call when you do not know where a build stands (after a reconnect, when no turn of yours is running, or when the conversation moved to another channel): read "status" from the result rather than guessing. ' +
+                BROWSER_NAVIGATION_IS_DATA +
+                ' Hosts that support MCP Apps show Open editor / Open preview buttons. When Superblocks has written code the result includes a screenshot of the live Vite canvas, never the edit URL. When this result includes a screenshot, inspect it yourself before reporting that the app looks correct. If it shows skeletons, spinners, empty tables or charts, or "Loading...", call get_app again a few seconds later rather than treating it as a defect. Do not test, debug, or correct a visible problem unless the user requests it; report what you see.',
             inputSchema: {
                 applicationId: z.uuid().optional(),
                 branch: z.string().optional(),
@@ -1301,13 +1321,14 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                     .describe("Whether to capture a screenshot. Defaults to true."),
             },
             title: "Get App",
+            _meta: permissionMeta("get_app"),
         }, async ({ applicationId, branch, includeScreenshot }, extra) => run("get_app", async (context) => {
             const result = await getApp(context, {
                 applicationId,
                 branch,
-                includeScreenshot: clientPresentationCapabilities(server.server.getClientVersion()).hasNativeBrowser
-                    ? false
-                    : includeScreenshot,
+                // A host that collects approvals itself shows the app in its own
+                // browser pane, so skip the capture.
+                includeScreenshot: !hostCollectsApprovalsAndShowsApp() && includeScreenshot,
             });
             stageNativeDecisionApproval(result, extra.requestId);
             return result;
@@ -1322,6 +1343,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
             },
             title: "Get App Status",
             _meta: {
+                ...permissionMeta("get_app_status"),
                 ui: {
                     resourceUri: APP_STATUS_RESOURCE_URI,
                     visibility: ["app"],
@@ -1346,6 +1368,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                     .describe("Wait until the build finishes or the tool deadline; false returns one status check for the app card."),
             },
             title: "Get Preview Status",
+            _meta: permissionMeta("get_preview_status"),
         }, async (input, extra) => run("get_preview_status", (context) => getPreviewStatus(context, input), extra, input));
         // The card is what puts a screenshot on screen: hosts that render an MCP
         // App render it instead of the tool's content blocks, so without it this
@@ -1358,6 +1381,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                 branch: z.string().optional(),
             },
             title: "Build App",
+            _meta: permissionMeta("build_app"),
         }, async ({ applicationId, branch }, extra) => run("build_app", (context) => previewApp(context, { applicationId, branch, wait: false }), extra, { applicationId, branch }));
         statusCardTools.push(buildAppTool);
         registerAppResource(server, "Gateway app status", APP_STATUS_RESOURCE_URI, {
@@ -1372,9 +1396,9 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                 },
             ],
         }));
-        publishAppTool = server.registerTool("publish_app", {
+        server.registerTool("publish_app", {
             annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
-            description: publishAppDescription(false),
+            description: PUBLISH_APP_DESCRIPTION,
             inputSchema: {
                 applicationId: z.string().uuid().optional(),
                 branch: z.string().optional(),
@@ -1393,6 +1417,7 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                 idempotencyKey: z.string().optional(),
             },
             title: "Publish App",
+            _meta: permissionMeta("publish_app"),
         }, async ({ applicationId, branch, commitId, commitMessage, idempotencyKey }, extra) => run("publish_app", (context) => {
             const parsed = publishAppInput({
                 applicationId,
@@ -1413,11 +1438,14 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                 commitId: z.string().optional(),
             },
             title: "Check Publish Progress",
+            _meta: permissionMeta("check_publish_progress"),
             // The same poll loop as check_app_progress, on the deploy instead of
             // the build: it reports where the publish got to and does nothing else.
             annotations: READ_ONLY_TOOL_ANNOTATIONS,
         }, async ({ applicationId, commitId }, extra) => run("check_publish_progress", (context) => checkPublishProgress(context, { applicationId, commitId }), extra, { applicationId, commitId }));
     }
+    if (builderToolsOnly)
+        return server;
     const getActiveAccessToken = deps.getAccessToken
         ? () => deps.getAccessToken()
         : undefined;
@@ -1448,7 +1476,6 @@ export function createMcpServer(deps, probeEditorDocument = createEditorDocument
                 // Branch only, and only for the application the caller named, so a
                 // stale entry cannot redirect the app itself.
                 branch: deps.sessionPeer.heldContext(applicationId)?.branch ?? recent?.branch,
-                cowork: clientProfileFor().hasNativeBrowser,
                 integrationId,
                 uiBaseUrl: deps.config.uiBaseUrl,
             });