fix(mcp): lead preview coaching with no-iframe fallback (#648)

The preview→apply coaching appended to every preview-mode write tool's
description led with the iframe-happy path ("returns a Prefab card with
Confirm/Cancel buttons. End your turn after the preview response.") and
relegated the no-iframe fallback to a final paragraph. Agents in hosts
that don't render MCP Apps iframes (Claude Code, plain CLI clients)
followed the lead sentence, ended their turn, and waited for clicks the
user could never make.

Restructure both PREVIEW_APPLY_COACHING and PREVIEW_APPLY_DIRECT_COACHING
so the no-iframe scenario is explicit and ordered first, and point the
agent at the ``content`` channel JSON as the data source for the
in-chat summary. Sync the parallel guidance in the help resource.

Pin the new ordering with TestPreviewCoachingLeadsWithNoIframeFallback
in test_prefab_ui.py: both coaching strings must (1) mention "does NOT
render" before "DOES render", (2) reference the ``content`` channel,
and (3) include the ``preview=False`` re-issue mechanic. Together with
the existing test_tool_descriptions_and_annotations.py coverage of
"Do NOT re-narrate" / "Apply: call" / "ui/update-model-context", every
registered preview-button tool now has both the happy-path button
contract and the no-iframe fallback contract enforced.

Bundles the uv.lock sync to mcp v0.69.0 that landed on main but didn't
update the workspace lockfile.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dougborg

katana_mcp_server/src/katana_mcp/resources/help.py

@@ -102,22 +102,46 @@
 
 ### Agent guidance for preview→apply
 
-After returning a preview, **do not re-narrate the card or ask for
-confirmation in chat** — the buttons handle that. End your turn and wait
-for the user.
-
-When the user clicks Confirm on a preview card, the iframe sends a chat
-message of the form:
+The same preview card serves two host families, and the agent's
+end-of-turn behavior is different for each. The `content` channel of
+every preview response carries the response JSON, so the data is always
+available even if the card itself doesn't render.
+
+**1. Hosts that do NOT render MCP Apps iframes** (Claude Code, plain CLI
+clients). The Prefab card is invisible — the user can't click anything.
+Summarize the planned change in chat from the `content` JSON (what's
+changing, key field values), ask the user to confirm, and on yes
+re-issue the call with `preview=False` yourself. Do **not** end your
+turn waiting for a button click; there is none. Common signals that
+this is the case: the user says they can't see the card, or you have no
+prior evidence iframes have rendered in this session.
+
+**2. Hosts that DO render iframes** (Claude Desktop, Claude.ai, Cowork).
+The card has Confirm and Cancel buttons the user clicks. **Do not
+re-narrate the card or ask for confirmation in chat** — the buttons
+handle that. End your turn after the preview response. The Confirm-click
+behavior depends on which rail the tool is on:
+
+*SendMessage rail (ADR-0015) — default for tools that don't opt into
+direct-apply.* The iframe sends a chat message of the form:
 
     Apply: call <tool_name>(<arg>=<value>, ..., preview=False)
 
 Recognize the `Apply:` prefix and re-issue the tool call **exactly as
-written**, with all inlined arguments preserved. The agent's tool-calling
-loop is the only path that lets the agent see the structured apply
-response — the iframe-initiated call (which the spec routes back to the
-iframe, not to the agent) was the wrong rail; see ADR-0015.
-
-When the user clicks Cancel, the iframe sends:
+written**, with all inlined arguments preserved. Re-issuing through the
+agent's tool-calling loop is what lets the agent see the structured
+apply response on this rail; the iframe-initiated call alone routes its
+result back to the iframe, not to the agent.
+
+*Direct-apply rail (ADR-0016) — used by `create_purchase_order`,
+`create_sales_order`, `create_manufacturing_order`, the unified
+`modify_<entity>` / `delete_<entity>` family, the `correct_*` family,
+and the stock-adjustment write tools.* The Confirm click fires the
+apply `tools/call` directly and the iframe pushes the structured result
+back to the agent's model context via `ui/update-model-context`. The
+agent sees the apply response on its next turn without re-issuing.
+
+Cancel behavior is the same on both rails: the iframe sends
 
     Cancel: do not apply <description>.
 

katana_mcp_server/src/katana_mcp/tools/prefab_ui.py

@@ -76,20 +76,35 @@ def _split_warnings(
     return blocks, regulars
 
 
-# Coaching text appended to every preview-mode write tool's description so
-# the agent (1) does not re-narrate or ask for chat-confirmation after a
-# preview returns (closes #544), and (2) knows to re-issue the call when it
-# sees an ``Apply: call ...`` SendMessage from a Confirm-button click. The
-# rationale lives in ADR-0015.
+# Coaching text appended to every preview-mode write tool's description.
+# The agent's host may or may not render MCP Apps iframes — lead with the
+# no-iframe path because it's the footgun: in iframe hosts the buttons
+# handle the UX with no agent help, but in non-iframe hosts an agent that
+# follows the iframe-happy-path coaching ends its turn waiting for clicks
+# that never come (see #648). Mention the iframe path second.
+#
+# The rationale for the chat-message rail lives in ADR-0015; the
+# Confirm-then-iframe-handles-everything UX in ADR-0016.
 PREVIEW_APPLY_COACHING = (
-    "Preview→apply: when ``preview=True`` (default), returns a Prefab card "
-    "with Confirm/Cancel buttons. Do NOT re-narrate the card or ask for "
-    "confirmation in chat — the buttons handle that. End your turn after "
-    "the preview response.\n\n"
-    "If you receive a chat message starting with ``Apply: call <tool>(...)`` "
-    "or ``Cancel: do not apply ...``, that is a button click from a previous "
-    "preview. For Apply, re-issue the tool call exactly as written. For "
-    "Cancel, acknowledge briefly without re-issuing."
+    "Preview→apply pattern: when ``preview=True`` (default) the tool returns "
+    "a Prefab card describing the planned change. The ``content`` channel of "
+    "the tool result carries the response JSON, so you always have the data "
+    "even if the card itself doesn't render. Handle both host scenarios:\n\n"
+    "1. If the host does NOT render MCP Apps iframes (Claude Code, plain CLI "
+    "clients, etc.) — common signal: the user says they can't see the card, "
+    "or you have no other evidence the card was rendered — the Prefab card "
+    "is invisible. Summarize the planned change in chat from the ``content`` "
+    "JSON (what's changing, key field values), ask the user to confirm, then "
+    "re-issue the call with ``preview=False`` yourself. Do NOT end your turn "
+    "waiting for a button click — there is none.\n\n"
+    "2. If the host DOES render iframes (Claude Desktop, Claude.ai, Cowork, "
+    "etc.), the card has Confirm/Cancel buttons the user clicks. Do NOT "
+    "re-narrate the card or ask for confirmation in chat — the buttons "
+    "handle that. End your turn after the preview response. If you later "
+    "receive a chat message starting with ``Apply: call <tool>(...)`` or "
+    "``Cancel: do not apply ...``, that is a button click from a previous "
+    "preview: for Apply re-issue the tool call exactly as written; for "
+    "Cancel acknowledge briefly without re-issuing."
 )
 
 
@@ -98,24 +113,32 @@ def _split_warnings(
 # ``ui/update-model-context``). The agent does not re-issue the call — it
 # receives the apply result automatically on its next turn. See
 # ``docs/adr/0016-direct-apply-confirm-button-rail.md`` (forthcoming).
+#
+# Same no-iframe-first lead as PREVIEW_APPLY_COACHING (see #648).
 PREVIEW_APPLY_DIRECT_COACHING = (
-    "Preview→apply: when ``preview=True`` (default) AND the host renders "
-    "MCP Apps iframes (Claude Desktop, Claude.ai, Cowork, etc.), returns a "
-    "Prefab card with Confirm/Cancel buttons. Do NOT re-narrate the card or "
-    "ask for confirmation in chat — the buttons handle that. End your turn "
-    "after the preview response.\n\n"
-    "When the user clicks Confirm in the iframe, the iframe fires the apply "
-    "call directly and morphs in place to a result card. The structured "
-    "apply response (id, status, etc.) arrives in your context on your next "
-    "turn via ``ui/update-model-context``. Treat it as you would any "
-    "tool-call result — acknowledge completion, suggest next steps. Do NOT "
-    "re-issue the call after the iframe already applied.\n\n"
-    "Non-iframe-host fallback: if the host does not render Prefab cards "
-    "(no iframe was shown to the user), there are no buttons. Ask the user "
-    "for confirmation in chat, then re-issue with ``preview=False`` "
-    "yourself.\n\n"
-    "If you receive a chat message starting with ``Cancel: do not apply ...``, "
-    "the user opted out — acknowledge briefly without re-issuing."
+    "Preview→apply pattern: when ``preview=True`` (default) the tool returns "
+    "a Prefab card describing the planned change. The ``content`` channel of "
+    "the tool result carries the response JSON, so you always have the data "
+    "even if the card itself doesn't render. Handle both host scenarios:\n\n"
+    "1. If the host does NOT render MCP Apps iframes (Claude Code, plain CLI "
+    "clients, etc.) — common signal: the user says they can't see the card, "
+    "or you have no other evidence the card was rendered — the Prefab card "
+    "is invisible. Summarize the planned change in chat from the ``content`` "
+    "JSON (what's changing, key field values), ask the user to confirm, then "
+    "re-issue the call with ``preview=False`` yourself. Do NOT end your turn "
+    "waiting for a button click — there is none.\n\n"
+    "2. If the host DOES render iframes (Claude Desktop, Claude.ai, Cowork, "
+    "etc.), the card has Confirm/Cancel buttons the user clicks. When the "
+    "user clicks Confirm in the iframe, the iframe fires the apply call "
+    "directly and morphs in place to a result card. The structured apply "
+    "response (id, status, etc.) arrives in your context on your next turn "
+    "via ``ui/update-model-context``. Treat it as you would any tool-call "
+    "result — acknowledge completion, suggest next steps. Do NOT re-narrate "
+    "the preview card, do NOT ask for confirmation in chat (the buttons "
+    "handle that), and Do NOT re-issue the call after the iframe already "
+    "applied. End your turn after the preview response. If you receive a "
+    "chat message starting with ``Cancel: do not apply ...``, the user "
+    "opted out — acknowledge briefly without re-issuing."
 )
 
 

katana_mcp_server/tests/test_prefab_ui.py

@@ -13,6 +13,8 @@
 
 import pytest
 from katana_mcp.tools.prefab_ui import (
+    PREVIEW_APPLY_COACHING,
+    PREVIEW_APPLY_DIRECT_COACHING,
     build_batch_recipe_update_ui,
     build_fulfill_preview_ui,
     build_fulfill_success_ui,
@@ -28,6 +30,7 @@
     build_search_results_ui,
     build_variant_details_ui,
     build_verification_ui,
+    with_preview_coaching,
 )
 from prefab_ui.app import PrefabApp
 from pydantic import BaseModel
@@ -2256,3 +2259,84 @@ def collect_titles(o: Any) -> None:
         assert any(t.endswith("Delete") for t in titles), (
             f"delete_* result title must end with 'Delete'; got {titles!r}"
         )
+
+
+class TestPreviewCoachingLeadsWithNoIframeFallback:
+    """Regression tests for #648 — the docstring coaching templates must
+    surface the non-iframe-host fallback prominently, not as a footnote.
+    Agents in Claude Code / plain CLI hosts can't click iframe buttons; the
+    previous coaching led with the iframe-happy path and agents silently
+    ended their turns waiting for clicks the user could not make.
+    """
+
+    @pytest.mark.parametrize(
+        "coaching",
+        [PREVIEW_APPLY_COACHING, PREVIEW_APPLY_DIRECT_COACHING],
+        ids=["sendmessage-rail", "direct-apply-rail"],
+    )
+    def test_no_iframe_scenario_appears_before_iframe_scenario(
+        self, coaching: str
+    ) -> None:
+        """The no-iframe path must be discussed BEFORE the iframe path so
+        agents whose host doesn't render Prefab cards don't miss the
+        fallback instructions."""
+        # Numbered scenarios — `1.` introduces no-iframe, `2.` iframe.
+        no_iframe_idx = coaching.find("does NOT render")
+        iframe_idx = coaching.find("DOES render")
+        assert no_iframe_idx != -1, (
+            "coaching must explicitly call out the no-iframe path "
+            f"(searched for 'does NOT render'); got:\n{coaching}"
+        )
+        assert iframe_idx != -1, (
+            "coaching must also explain the iframe path "
+            f"(searched for 'DOES render'); got:\n{coaching}"
+        )
+        assert no_iframe_idx < iframe_idx, (
+            "no-iframe scenario must appear FIRST so agents read it before "
+            "the iframe-happy path; reversing the order is exactly the "
+            "footgun #648 fixed."
+        )
+
+    @pytest.mark.parametrize(
+        "coaching",
+        [PREVIEW_APPLY_COACHING, PREVIEW_APPLY_DIRECT_COACHING],
+        ids=["sendmessage-rail", "direct-apply-rail"],
+    )
+    def test_mentions_content_channel_as_data_source(self, coaching: str) -> None:
+        """The no-iframe fallback path tells the agent to summarize from the
+        ``content`` channel — make sure the coaching points there explicitly
+        so agents don't claim "I don't have enough data" instead of reading
+        the JSON they were just handed."""
+        assert "``content``" in coaching, (
+            "coaching must direct the agent to the ``content`` channel for "
+            "the no-iframe summarize-then-confirm path; otherwise agents "
+            "may not realize the response data is already in context."
+        )
+
+    @pytest.mark.parametrize(
+        "coaching",
+        [PREVIEW_APPLY_COACHING, PREVIEW_APPLY_DIRECT_COACHING],
+        ids=["sendmessage-rail", "direct-apply-rail"],
+    )
+    def test_no_iframe_path_says_re_issue_with_preview_false(
+        self, coaching: str
+    ) -> None:
+        """The no-iframe fallback must spell out the apply mechanic
+        (``preview=False``) so the agent isn't left guessing how to apply."""
+        assert "preview=False" in coaching, (
+            "the no-iframe fallback must tell the agent to re-issue with "
+            "``preview=False``"
+        )
+
+    def test_with_preview_coaching_appends_to_existing_docstring(self) -> None:
+        """``with_preview_coaching`` should preserve the function's own
+        docstring AND append the new lead-with-no-iframe block — verifies
+        the rewrite didn't break the existing concatenation contract.
+        """
+
+        def fn() -> None:
+            """My tool's own purpose."""
+
+        result = with_preview_coaching(fn)
+        assert result.startswith("My tool's own purpose.")
+        assert "does NOT render" in result