From 88ce92652544e641940b0b6bc8d5e7710439b34a Mon Sep 17 00:00:00 2001
From: zLeoAlex <z.alex.leo@outlook.com>
Date: Wed, 10 Jun 2026 01:48:48 +0800
Subject: [PATCH] fix(prompts): explain visibility="internal" attribute in
 Runtime Policy Reference

The <runtime_prompt> tag includes a visibility="internal" attribute that
was listed in the tag format but never explained.  Models sometimes
interpreted this as an instruction to announce or restate the current
mode to the user, leading to repetitive YOLO-mode confirmations before
every tool call (#2922).

Add a one-sentence explanation: the attribute marks this tag as a
runtime instruction for the model (not user input), and the model should
apply the referenced rules silently without announcing the mode.

Closes #2922
---
 crates/tui/src/prompts.rs | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/crates/tui/src/prompts.rs b/crates/tui/src/prompts.rs
index dab8bb30..2f89347f 100644
--- a/crates/tui/src/prompts.rs
+++ b/crates/tui/src/prompts.rs
@@ -721,7 +721,11 @@ pub(crate) fn render_runtime_policy_reference() -> String {
          approval policy. When you see this tag, look up the corresponding \
          rules below and apply them for the current turn.\n\n\
          The tag format is:\n\
-         `<runtime_prompt visibility=\"internal\" mode=\"<mode>\" approval=\"<approval>\"/>`\n\n",
+         `<runtime_prompt visibility=\"internal\" mode=\"<mode>\" approval=\"<approval>\"/>`\n\n\
+         The `visibility=\"internal\"` attribute means this tag is a runtime \
+         instruction for the model, not user input. Do not announce the \
+         current mode or restate the tag content to the user — just apply \
+         the referenced rules silently.\n\n",
     );
 
     // ── Mode reference ─────────────────────────────────────────────────