@pi-in-go/pigpen-ask-user-question 0.0.0-stage → 0.1.0

package/CREDITS.md

@@ -0,0 +1,17 @@
+# Credits
+
+`extensions/rpiv-ask-user-question` is a Go port of **@juicesharp/rpiv-ask-user-question** 2.11.0 from **rpiv-mono**,
+https://github.com/juicesharp/rpiv-mono, by **juicesharp** (MIT, Copyright (c) 2026 juicesharp).
+
+- Original: `packages/rpiv-ask-user-question`
+- Commit: `61904e69e1a50e12585bdf15f0310e633a62ba36` (release v2.11.0)
+- The unmodified original (its tests included, images omitted) is kept at
+  [`port/oracle/`](port/oracle) as the equivalence oracle, with the license at
+  [`port/oracle/LICENSE`](port/oracle/LICENSE). `@juicesharp/rpiv-config` 2.12.0 (MIT, juicesharp), the
+  original's configuration library, is installed from npm into `port/oracle/node_modules` and is not
+  copied; the port's `config.go` is the todo port's, which was written against its `config.ts` at the pinned commit.
+
+The Go code, the scenarios and the tests were written for this Package by Michael Kinsy. Wording, tool schema,
+prompt guidance and behavior follow the original. Modified paths: none of the original is modified; the port is a
+separate implementation. Not ported: the locales (E1, English only: approved by the owner), the interactive questionnaire component and the overlay
+collapse key (see [port/PORT.md](port/PORT.md)).

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 juicesharp (the original, @juicesharp/rpiv-ask-user-question)
+Copyright (c) 2026 Michael Kinsy (the Go port)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# rpiv-ask-user-question (Go port, partial)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Go extension for PiG: the `ask_user_question` tool, which lets the model put up to four structured questions
+(2-4 options each, single or multiple choice, an optional preview per option) to you when it would otherwise guess.
+Every question gets a "Type something." row for a free-text answer; dismissing a dialog declines the questionnaire.
+
+It is a port of `@juicesharp/rpiv-ask-user-question` 2.11.0 (see [CREDITS.md](CREDITS.md)), made with the
+[extension porting Skill](../extension-port/README.md). It needs no Node runtime.
+
+## What is ported
+
+This is **slice A**: the tool and everything the model sees and the equivalence checks can reach.
+
+- The tool, its JSON Schema (limits enforced by the host), its description and prompt guidance, and the config
+  overrides (`~/.config/rpiv-ask-user-question/config.json`: `guidance.description`, `guidance.promptSnippet`,
+  `guidance.promptGuidelines`).
+- Line-terminator normalisation, the validation (reserved and duplicate labels, option counts), the answer envelope
+  and decline text, the `rpiv:ask-user:prompt` and `rpiv:ask-user:blocked` events.
+- The sequential dialog walker (one select or input dialog per question), which is what the original runs on RPC hosts.
+  **In a terminal this port runs the same dialogs**, where the original shows its tabbed questionnaire.
+- Removing the tool from the active set on hosts without a UI (`before_agent_start`).
+
+**Not ported yet (slice B):** the interactive questionnaire (tabs, per-option notes, submit tab, side-by-side preview
+pane, external editor, collapse key), the locales, and the terminal bell. See [port/PORT.md](port/PORT.md).
+
+```sh
+pig install ./components/ask-user-question
+```

package/extensions/rpiv-ask-user-question/config.go

@@ -0,0 +1,189 @@
+package ask_user_question
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// Configuration: <config home>/rpiv-ask-user-question/config.json, read fresh on every call (no caching, no /reload).
+// upstream: config.ts, and rpiv-config config.ts (loadJsonConfigWithLegacyFallback) at the same commit.
+const (
+	// defaultCollapseKey is the collapse and expand shortcut when collapseKey is missing or invalid.
+	defaultCollapseKey = "ctrl+]"
+	// collapseKeyOff disables the collapse shortcut entirely.
+	collapseKeyOff = "off"
+	configName     = "rpiv-ask-user-question"
+)
+
+type guidanceFields struct {
+	PromptSnippet    string
+	PromptGuidelines []string
+	Description      string
+}
+
+// askConfig is the file's content. The loader does not validate: each resolver decides.
+type askConfig struct {
+	Guidance    any
+	CollapseKey any
+}
+
+func homeDir() string {
+	home, _ := os.UserHomeDir()
+	return home
+}
+
+func defaultConfigDir() string { return filepath.Join(homeDir(), ".config") }
+
+// resolveConfigDir is $XDG_CONFIG_HOME when it is set and absolute (a leading ~ is expanded), else ~/.config.
+func resolveConfigDir() string {
+	xdg := jsTrim(os.Getenv("XDG_CONFIG_HOME"))
+	if xdg == "" {
+		return defaultConfigDir()
+	}
+	switch {
+	case xdg == "~":
+		xdg = homeDir()
+	case strings.HasPrefix(xdg, "~/"):
+		xdg = filepath.Join(homeDir(), xdg[2:])
+	}
+	if filepath.IsAbs(xdg) {
+		return xdg
+	}
+	return defaultConfigDir()
+}
+
+// loadJSONConfig reads a JSON object; a missing, unreadable, invalid or non-object file reads as empty.
+func loadJSONConfig(path string) map[string]any {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return map[string]any{}
+	}
+	var parsed any
+	if err := json.Unmarshal(data, &parsed); err != nil {
+		return map[string]any{}
+	}
+	m, ok := parsed.(map[string]any)
+	if !ok {
+		return map[string]any{}
+	}
+	return m
+}
+
+func fileExists(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
+
+func loadConfig() askConfig {
+	xdgPath := filepath.Join(resolveConfigDir(), configName, "config.json")
+	m := loadJSONConfig(filepath.Join(defaultConfigDir(), configName, "config.json"))
+	if fileExists(xdgPath) {
+		m = loadJSONConfig(xdgPath)
+	}
+	return askConfig{Guidance: m["guidance"], CollapseKey: m["collapseKey"]}
+}
+
+var (
+	specialKeys = map[string]bool{
+		"escape": true, "esc": true, "enter": true, "return": true, "tab": true, "space": true, "backspace": true,
+		"delete": true, "insert": true, "clear": true, "home": true, "end": true, "pageup": true, "pagedown": true,
+		"up": true, "down": true, "left": true, "right": true,
+		"f1": true, "f2": true, "f3": true, "f4": true, "f5": true, "f6": true, "f7": true, "f8": true,
+		"f9": true, "f10": true, "f11": true, "f12": true,
+	}
+	modifierKeys = map[string]bool{"ctrl": true, "shift": true, "alt": true, "super": true}
+)
+
+const baseKeyChars = "abcdefghijklmnopqrstuvwxyz0123456789_-!@#$%^&*()|~`'\":;,./<>?[]{}=\\"
+
+// isValidCollapseKeySpec validates a spec against pi-tui's KeyId grammar: zero or more distinct modifiers,
+// then a base key that is one printable character or a named special key. A loose check is not enough: pi-tui
+// takes the last `+` part as the key and ignores unknown parts, so a typo like `ctr+]` would match every bare
+// `]` keypress. upstream: config.ts:78-93.
+func isValidCollapseKeySpec(spec string) bool {
+	if spec == "" || strings.HasPrefix(spec, "+") || strings.HasSuffix(spec, "+") || strings.Contains(spec, "++") {
+		return false
+	}
+	parts := strings.Split(spec, "+")
+	base := parts[len(parts)-1]
+	modifiers := parts[:len(parts)-1]
+	seen := map[string]bool{}
+	for _, m := range modifiers {
+		if seen[m] || !modifierKeys[m] {
+			return false
+		}
+		seen[m] = true
+	}
+	if r := []rune(base); len(r) == 1 && r[0] < 0x10000 {
+		return strings.ContainsRune(baseKeyChars, r[0])
+	}
+	return specialKeys[base]
+}
+
+// resolveCollapseKey is the collapse key: the default when the field is missing, not a string, blank or
+// invalid; the sentinel "off"; or the lowercased validated spec.
+func resolveCollapseKey() string {
+	raw, ok := loadConfig().CollapseKey.(string)
+	if !ok {
+		return defaultCollapseKey
+	}
+	raw = strings.ToLower(jsTrim(raw))
+	switch {
+	case raw == "":
+		return defaultCollapseKey
+	case raw == collapseKeyOff:
+		return collapseKeyOff
+	case isValidCollapseKeySpec(raw):
+		return raw
+	}
+	return defaultCollapseKey
+}
+
+// validateGuidanceFields keeps the guidance fields that have the right type and are not empty.
+// upstream: rpiv-config config.ts validateGuidanceFields.
+func validateGuidanceFields(fields any) guidanceFields {
+	g, ok := fields.(map[string]any)
+	if !ok {
+		return guidanceFields{}
+	}
+	var out guidanceFields
+	if s, ok := g["promptSnippet"].(string); ok && s != "" {
+		out.PromptSnippet = s
+	}
+	if list, ok := g["promptGuidelines"].([]any); ok && len(list) > 0 {
+		lines := make([]string, 0, len(list))
+		for _, e := range list {
+			s, ok := e.(string)
+			if !ok || s == "" {
+				lines = nil
+				break
+			}
+			lines = append(lines, s)
+		}
+		out.PromptGuidelines = lines
+	}
+	if s, ok := g["description"].(string); ok && s != "" {
+		out.Description = s
+	}
+	return out
+}
+
+// formatKeySpecForDisplay renders a key spec for a hint: `ctrl+]` as `Ctrl+]`, `pageup` as `PageUp`.
+// upstream: config.ts:formatKeySpecForDisplay.
+func formatKeySpecForDisplay(spec string) string {
+	compound := map[string]string{"pageup": "PageUp", "pagedown": "PageDown"}
+	parts := strings.Split(spec, "+")
+	for i, p := range parts {
+		switch {
+		case compound[p] != "":
+			parts[i] = compound[p]
+		case len([]rune(p)) <= 1:
+			parts[i] = strings.ToUpper(p)
+		default:
+			parts[i] = strings.ToUpper(p[:1]) + p[1:]
+		}
+	}
+	return strings.Join(parts, "+")
+}

package/extensions/rpiv-ask-user-question/config_test.go

@@ -0,0 +1,142 @@
+package ask_user_question
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+const fConfig = "config"
+
+// configHome points HOME at a temp dir (and clears XDG_CONFIG_HOME) and returns a writer for
+// ~/.config/rpiv-ask-user-question/config.json (upstream: config.test.ts).
+func configHome(t *testing.T) (write func(contents string)) {
+	t.Helper()
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+	t.Setenv("XDG_CONFIG_HOME", "")
+	path := filepath.Join(home, ".config", "rpiv-ask-user-question", "config.json")
+	return func(contents string) {
+		t.Helper()
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(path, []byte(contents), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func TestFormatKeySpecForDisplay(t *testing.T) {
+	tw(t, fConfig, "capitalizes each +-part of a resolved spec", func(t *testing.T) {
+		eq(t, formatKeySpecForDisplay("ctrl+shift+t"), "Ctrl+Shift+T", "spec")
+		eq(t, formatKeySpecForDisplay("alt+o"), "Alt+O", "alt")
+	})
+	tw(t, fConfig, "handles named special keys and bare keys", func(t *testing.T) {
+		eq(t, formatKeySpecForDisplay("escape"), "Escape", "escape")
+		eq(t, formatKeySpecForDisplay("f5"), "F5", "f5")
+		eq(t, formatKeySpecForDisplay("]"), "]", "bare")
+	})
+	tw(t, fConfig, "cases compound-word named keys conventionally", func(t *testing.T) {
+		eq(t, formatKeySpecForDisplay("pageup"), "PageUp", "pageup")
+		eq(t, formatKeySpecForDisplay("ctrl+pagedown"), "Ctrl+PageDown", "pagedown")
+	})
+	tw(t, fConfig, "round-trips the default key to the historical hint casing", func(t *testing.T) {
+		eq(t, formatKeySpecForDisplay(defaultCollapseKey), "Ctrl+]", "default")
+	})
+}
+
+func TestResolveCollapseKey(t *testing.T) {
+	tw(t, fConfig, "returns the default when config has no collapseKey", func(t *testing.T) {
+		w := configHome(t)
+		eq(t, resolveCollapseKey(), "ctrl+]", "no file")
+		w(`{}`)
+		eq(t, resolveCollapseKey(), "ctrl+]", "empty config")
+	})
+	tw(t, fConfig, "returns the default when collapseKey is empty or whitespace", func(t *testing.T) {
+		w := configHome(t)
+		w(`{"collapseKey":""}`)
+		eq(t, resolveCollapseKey(), defaultCollapseKey, "empty")
+		w(`{"collapseKey":"   "}`)
+		eq(t, resolveCollapseKey(), defaultCollapseKey, "blank")
+	})
+	tw(t, fConfig, "normalizes the spec (trim + lowercase)", func(t *testing.T) {
+		w := configHome(t)
+		w(`{"collapseKey":"  Alt+O  "}`)
+		eq(t, resolveCollapseKey(), "alt+o", "key")
+	})
+	tw(t, fConfig, "returns the off sentinel unchanged (case-insensitive)", func(t *testing.T) {
+		w := configHome(t)
+		for _, v := range []string{"off", "OFF", " Off "} {
+			w(`{"collapseKey":"` + v + `"}`)
+			eq(t, resolveCollapseKey(), collapseKeyOff, v)
+		}
+	})
+	tw(t, fConfig, "falls back to the default for malformed specs", func(t *testing.T) {
+		w := configHome(t)
+		for _, v := range []string{"+", "ctrl+", "+t", "ctrl++t", "ctrl+ctrl+t", ""} {
+			w(`{"collapseKey":"` + v + `"}`)
+			eq(t, resolveCollapseKey(), defaultCollapseKey, "spec "+v)
+		}
+	})
+	tw(t, fConfig, "falls back to the default for typo'd modifiers and unknown key names", func(t *testing.T) {
+		w := configHome(t)
+		for _, v := range []string{"ctr+]", "control+t", "ctrl+foo", "ctrl+f13", "meta+t"} {
+			w(`{"collapseKey":"` + v + `"}`)
+			eq(t, resolveCollapseKey(), defaultCollapseKey, "spec "+v)
+		}
+	})
+	tw(t, fConfig, "accepts named special keys and bare base keys", func(t *testing.T) {
+		w := configHome(t)
+		for _, v := range []string{"escape", "ctrl+pageup", "f12", "alt+o", "ctrl+]", "shift+tab", "super+k"} {
+			w(`{"collapseKey":"` + v + `"}`)
+			eq(t, resolveCollapseKey(), v, "spec "+v)
+		}
+	})
+}
+
+func TestLoadConfig(t *testing.T) {
+	tw(t, fConfig, "returns an empty config when no file is present", func(t *testing.T) {
+		configHome(t)
+		eq(t, loadConfig(), askConfig{}, "config")
+	})
+	tw(t, fConfig, "reads a valid JSON config", func(t *testing.T) {
+		w := configHome(t)
+		w(`{"collapseKey":"alt+o","guidance":{"promptSnippet":"s"}}`)
+		got := loadConfig()
+		eq(t, got.CollapseKey, "alt+o", "collapseKey")
+		eq(t, got.Guidance, map[string]any{"promptSnippet": "s"}, "guidance")
+	})
+}
+
+func TestConfigRobustness(t *testing.T) {
+	w := configHome(t)
+	for _, bad := range []string{`not json`, `[]`, `"x"`, `null`, ``} {
+		w(bad)
+		eq(t, loadConfig(), askConfig{}, "content "+bad)
+	}
+	// The default location is the legacy one; an XDG location wins when its file exists.
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	w(`{"collapseKey":"alt+o"}`)
+	eq(t, resolveCollapseKey(), "alt+o", "legacy location when XDG has no file")
+	xdg := os.Getenv("XDG_CONFIG_HOME")
+	if err := os.MkdirAll(filepath.Join(xdg, "rpiv-ask-user-question"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(xdg, "rpiv-ask-user-question", "config.json"), []byte(`{"collapseKey":"off"}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	eq(t, resolveCollapseKey(), "off", "XDG file wins")
+	t.Setenv("XDG_CONFIG_HOME", "relative/dir")
+	eq(t, resolveCollapseKey(), "alt+o", "a relative XDG_CONFIG_HOME is ignored")
+}
+
+func TestValidateGuidanceFields(t *testing.T) {
+	eq(t, validateGuidanceFields(nil), guidanceFields{}, "nil")
+	eq(t, validateGuidanceFields("x"), guidanceFields{}, "string")
+	eq(t, validateGuidanceFields(map[string]any{"promptSnippet": "s", "promptGuidelines": []any{"a", "b"}, "description": "d"}),
+		guidanceFields{PromptSnippet: "s", PromptGuidelines: []string{"a", "b"}, Description: "d"}, "valid")
+	eq(t, validateGuidanceFields(map[string]any{"promptSnippet": "", "promptGuidelines": []any{"a", ""}, "description": 5.0}), guidanceFields{}, "invalid")
+	eq(t, validateGuidanceFields(map[string]any{"promptGuidelines": []any{}}), guidanceFields{}, "empty list")
+}

package/extensions/rpiv-ask-user-question/copy.go

@@ -0,0 +1,34 @@
+package ask_user_question
+
+// The tool's built-in model-facing copy. upstream: ask-user-question.ts DEFAULT_PROMPT_SNIPPET,
+// DEFAULT_PROMPT_GUIDELINES and DEFAULT_TOOL_DESCRIPTION, with the limits (4 questions, 2-4 options) filled in.
+var (
+	defaultPromptSnippet = "Ask the user up to 4 structured questions (2-4 options each) when requirements are ambiguous"
+
+	defaultPromptGuidelines = []string{
+		"Use ask_user_question whenever the user's request is underspecified and you cannot proceed without concrete decisions — you can ask up to 4 questions per invocation.",
+		"Each question MUST have 2-4 options. Every option requires a concise label (1-5 words) and a description explaining what the choice means or its trade-offs. The user can additionally type a custom answer via the automatically appended \"Type something.\" row on every question, or press Esc to abandon the questionnaire. Do NOT author \"Other\" or \"Type something.\" labels yourself — reserved labels are rejected at runtime.",
+		"Set multiSelect: true when multiple answers are valid. Provide an options[].preview markdown string when an option benefits from richer side-by-side context (mockups, code snippets, diagrams, configs) — single-select only. The \"Type something.\" row is appended to every question; in preview mode it expands to the full pane width while typing so the custom answer is not cramped into the narrow options column. If you recommend a specific option, make that the first option and append \"(Recommended)\" to its label.",
+		"Do not stack multiple ask_user_question calls back-to-back — group all clarifying questions into one invocation.",
+	}
+
+	defaultToolDescription = "Ask the user one or more structured questions during execution. Use when you need to:\n" +
+		"1. Gather user preferences or requirements\n" +
+		"2. Clarify ambiguous instructions\n" +
+		"3. Get decisions on implementation choices as you work\n" +
+		"4. Offer choices to the user about what direction to take\n" +
+		"\n" +
+		"Usage notes:\n" +
+		"- Users can type a custom answer via the automatically appended \"Type something.\" row on every question or press Esc to abandon the questionnaire. Do NOT author \"Other\" or \"Type something.\" labels yourself — reserved labels are rejected at runtime.\n" +
+		"- Use multiSelect: true when multiple answers are valid. The \"Type something.\" row is available on every question, including when options carry a `preview`; in preview mode it expands to the full pane width while typing so the custom answer is not cramped into the narrow options column.\n" +
+		"- If you recommend a specific option, make that the first option in the list and add \"(Recommended)\" at the end of the label.\n" +
+		"\n" +
+		"Preview feature:\n" +
+		"Use the optional `preview` field on options when presenting concrete artifacts that users need to visually compare:\n" +
+		"- ASCII mockups of UI layouts or components\n" +
+		"- Code snippets showing different implementations\n" +
+		"- Diagram variations\n" +
+		"- Configuration examples\n" +
+		"\n" +
+		"Preview content is rendered as markdown in a monospace box. Multi-line text with newlines is supported. When any option has a preview, the UI switches to a side-by-side layout with a vertical option list on the left and preview on the right. Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect)."
+)

package/extensions/rpiv-ask-user-question/envelope_test.go

@@ -0,0 +1,177 @@
+package ask_user_question
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+const fMain = "ask-user-question"
+
+func twoQ() questionParams {
+	return params(qn("Q1?", "A", opt("x", "d"), opt("y", "d")), qn("Q2?", "B", opt("p", "d"), opt("q", "d")))
+}
+
+func TestEnvelope(t *testing.T) {
+	const prefix, suffix = "User has answered your questions:", "You can now continue with the user's answers in mind."
+	tw(t, fMain, "null result → decline envelope + empty answers + cancelled true", func(t *testing.T) {
+		out := buildQuestionnaireResponse(nil, single())
+		eq(t, out.Text, "User declined to answer questions", "text")
+		eq(t, out.Details, questionnaireResult{Cancelled: true}, "details")
+	})
+	tw(t, fMain, "cancelled result preserves partial answers in details (not in content)", func(t *testing.T) {
+		r := &questionnaireResult{Cancelled: true, Answers: []questionAnswer{answerOpt(0, "Which?", "A")}}
+		out := buildQuestionnaireResponse(r, single())
+		eq(t, out.Text, "User declined to answer questions", "text")
+		eq(t, out.Details.Answers, r.Answers, "answers")
+	})
+	tw(t, fMain, "single answered question → CC envelope wrapper with question text and answer", func(t *testing.T) {
+		r := &questionnaireResult{Answers: []questionAnswer{answerOpt(0, "Which?", "A")}}
+		eq(t, buildQuestionnaireResponse(r, single()).Text, prefix+` "Which?"="A". `+suffix, "text")
+	})
+	tw(t, fMain, "envelope uses question text not header (no Q1 prefix)", func(t *testing.T) {
+		r := &questionnaireResult{Answers: []questionAnswer{answerOpt(0, "Which?", "A")}}
+		text := buildQuestionnaireResponse(r, single()).Text
+		if contains(text, "Pick") || contains(text, "Q1") {
+			t.Fatalf("header or Q1 leaked into %q", text)
+		}
+	})
+	tw(t, fMain, "two answered questions render as separate sentences inside one envelope", func(t *testing.T) {
+		r := &questionnaireResult{Answers: []questionAnswer{answerOpt(0, "Q1?", "x"), answerOpt(1, "Q2?", "q")}}
+		eq(t, buildQuestionnaireResponse(r, twoQ()).Text, prefix+` "Q1?"="x". "Q2?"="q". `+suffix, "text")
+	})
+	tw(t, fMain, "multiSelect answer renders as comma-joined labels in <A> position", func(t *testing.T) {
+		p := params(multi(qn("Q?", "H", opt("red", "r"), opt("blue", "b"))))
+		r := &questionnaireResult{Answers: []questionAnswer{answerMulti(0, "Q?", "red", "blue")}}
+		eq(t, buildQuestionnaireResponse(r, p).Text, prefix+` "Q?"="red, blue". `+suffix, "text")
+	})
+	tw(t, fMain, "custom typed answer renders raw text (no 'User answered:' prefix)", func(t *testing.T) {
+		r := &questionnaireResult{Answers: []questionAnswer{answerCustom(0, "Which?", "my own")}}
+		eq(t, buildQuestionnaireResponse(r, single()).Text, prefix+` "Which?"="my own". `+suffix, "text")
+	})
+	tw(t, fMain, "empty custom answer renders as (no input) in <A> position", func(t *testing.T) {
+		a := questionAnswer{QuestionIndex: 0, Question: "Which?", Kind: "custom"}
+		eq(t, buildQuestionnaireResponse(&questionnaireResult{Answers: []questionAnswer{a}}, single()).Text, prefix+` "Which?"="(no input)". `+suffix, "text")
+		a.Answer = sp("")
+		eq(t, buildQuestionnaireResponse(&questionnaireResult{Answers: []questionAnswer{a}}, single()).Text, prefix+` "Which?"="(no input)". `+suffix, "empty string")
+	})
+	tw(t, fMain, "notes are echoed as 'user notes: <text>' AND preserved in details", func(t *testing.T) {
+		a := answerOpt(0, "Which?", "A")
+		a.Notes = "because"
+		out := buildQuestionnaireResponse(&questionnaireResult{Answers: []questionAnswer{a}}, single())
+		eq(t, out.Text, prefix+` "Which?"="A". user notes: because. `+suffix, "text")
+		eq(t, at(out.Details.Answers, 0).Notes, "because", "details")
+	})
+	tw(t, fMain, "multiSelect answer with notes renders 'user notes:' suffix and NO 'selected preview:' suffix (FR-7)", func(t *testing.T) {
+		a := answerMulti(0, "Q?", "red")
+		a.Notes = "n"
+		p := params(multi(qn("Q?", "H", opt("red", "r"), opt("blue", "b"))))
+		eq(t, buildQuestionnaireResponse(&questionnaireResult{Answers: []questionAnswer{a}}, p).Text, prefix+` "Q?"="red". user notes: n. `+suffix, "text")
+	})
+	tw(t, fMain, "cancelled: false with no matching answers still returns DECLINE_MESSAGE text", func(t *testing.T) {
+		out := buildQuestionnaireResponse(&questionnaireResult{}, single())
+		eq(t, out.Text, "User declined to answer questions", "text")
+		eq(t, out.Details, questionnaireResult{Cancelled: true}, "details")
+	})
+	tw(t, fMain, "success + note: exact envelope bytes with the trailing 'global note: <note>.' segment (raw multiline echo)", func(t *testing.T) {
+		r := &questionnaireResult{Answers: []questionAnswer{answerOpt(0, "Which?", "A")}, GlobalNote: "line one\nline two"}
+		eq(t, buildQuestionnaireResponse(r, single()).Text, prefix+` "Which?"="A". global note: line one`+"\n"+`line two. `+suffix, "text")
+	})
+	tw(t, fMain, "the global-note segment is anchored by the envelope suffix", func(t *testing.T) {
+		r := &questionnaireResult{Answers: []questionAnswer{answerOpt(0, "Which?", "A")}, GlobalNote: "n"}
+		text := buildQuestionnaireResponse(r, single()).Text
+		eq(t, tail(text, len(" global note: n. "+suffix)), " global note: n. "+suffix, "tail")
+	})
+	tw(t, fMain, "zero answers + note is NOT a decline — answered envelope with details by reference", func(t *testing.T) {
+		r := &questionnaireResult{GlobalNote: "just this"}
+		out := buildQuestionnaireResponse(r, single())
+		eq(t, out.Text, prefix+` global note: just this. `+suffix, "text")
+		eq(t, out.Details, *r, "details")
+	})
+	tw(t, fMain, "cancelled + note: DECLINE_MESSAGE text, answers forwarded AND globalNote preserved in details", func(t *testing.T) {
+		r := &questionnaireResult{Cancelled: true, GlobalNote: "kept", Answers: []questionAnswer{answerOpt(0, "Which?", "A")}}
+		out := buildQuestionnaireResponse(r, single())
+		eq(t, out.Text, "User declined to answer questions", "text")
+		eq(t, out.Details, questionnaireResult{Cancelled: true, GlobalNote: "kept", Answers: r.Answers}, "details")
+	})
+	tw(t, fMain, "zero answers + no note still declines (fresh details literal carries no globalNote key)", func(t *testing.T) {
+		out := buildQuestionnaireResponse(&questionnaireResult{}, single())
+		b, _ := json.Marshal(out.Details)
+		eq(t, string(b), `{"answers":[],"cancelled":true}`, "wire")
+	})
+	tw(t, fMain, "formats 2 answered questions as comma-period-separated segments inside one envelope", func(t *testing.T) {
+		r := &questionnaireResult{Answers: []questionAnswer{answerOpt(0, "Q1?", "x"), answerCustom(1, "Q2?", "free")}}
+		eq(t, buildQuestionnaireResponse(r, twoQ()).Text, prefix+` "Q1?"="x". "Q2?"="free". `+suffix, "text")
+	})
+	tw(t, fMain, "formats 3 questions with mixed answer types in single-line envelope", func(t *testing.T) {
+		p := params(qn("Q1?", "A", two()...), multi(qn("Q2?", "B", opt("p", "d"), opt("q", "d"))), qn("Q3?", "C", two()...))
+		r := &questionnaireResult{Answers: []questionAnswer{answerOpt(0, "Q1?", "A"), answerMulti(1, "Q2?", "p", "q"), answerCustom(2, "Q3?", "z")}}
+		text := buildQuestionnaireResponse(r, p).Text
+		eq(t, text, prefix+` "Q1?"="A". "Q2?"="p, q". "Q3?"="z". `+suffix, "text")
+		if contains(text, "\n") {
+			t.Fatalf("envelope spans lines: %q", text)
+		}
+	})
+	tw(t, fMain, "skips unanswered questions (omits their segment from envelope)", func(t *testing.T) {
+		r := &questionnaireResult{Answers: []questionAnswer{answerOpt(1, "Q2?", "p")}}
+		eq(t, buildQuestionnaireResponse(r, twoQ()).Text, prefix+` "Q2?"="p". `+suffix, "text")
+	})
+	tw(t, fMain, "preserves notes in details AND echoes them across multiple questions", func(t *testing.T) {
+		a, b := answerOpt(0, "Q1?", "x"), answerOpt(1, "Q2?", "p")
+		a.Notes, b.Notes = "n1", "n2"
+		out := buildQuestionnaireResponse(&questionnaireResult{Answers: []questionAnswer{a, b}}, twoQ())
+		eq(t, out.Text, prefix+` "Q1?"="x". user notes: n1. "Q2?"="p". user notes: n2. `+suffix, "text")
+		eq(t, at(out.Details.Answers, 1).Notes, "n2", "details")
+	})
+	tw(t, fMain, "echoes preview text in envelope when single-select answer matches a preview-bearing option", func(t *testing.T) {
+		a := answerOpt(0, "Which?", "A")
+		a.Preview = "+--+"
+		eq(t, buildQuestionnaireResponse(&questionnaireResult{Answers: []questionAnswer{a}}, single()).Text, prefix+` "Which?"="A". selected preview: +--+. `+suffix, "text")
+	})
+	tw(t, fMain, "omits 'selected preview:' fragment when answer has no preview", func(t *testing.T) {
+		text := buildQuestionnaireResponse(&questionnaireResult{Answers: []questionAnswer{answerOpt(0, "Which?", "A")}}, single()).Text
+		if contains(text, "selected preview") {
+			t.Fatalf("preview fragment in %q", text)
+		}
+	})
+	tw(t, fMain, "omits 'user notes:' fragment when answer has no notes", func(t *testing.T) {
+		text := buildQuestionnaireResponse(&questionnaireResult{Answers: []questionAnswer{answerOpt(0, "Which?", "A")}}, single()).Text
+		if contains(text, "user notes") {
+			t.Fatalf("notes fragment in %q", text)
+		}
+	})
+	tw(t, fMain, "envelope wraps with CC prefix and suffix sentences", func(t *testing.T) {
+		text := buildQuestionnaireResponse(&questionnaireResult{Answers: []questionAnswer{answerOpt(0, "Which?", "A")}}, single()).Text
+		eq(t, head(text, len(prefix)), prefix, "prefix")
+		eq(t, tail(text, len(suffix)), suffix, "suffix")
+	})
+	tw(t, fMain, "locks the envelope shape", func(t *testing.T) {
+		out := buildQuestionnaireResponse(&questionnaireResult{Answers: []questionAnswer{answerOpt(0, "Which?", "A")}}, single())
+		b, _ := json.Marshal(out.Details)
+		eq(t, string(b), `{"answers":[{"answer":"A","kind":"option","question":"Which?","questionIndex":0}],"cancelled":false}`, "details wire")
+	})
+	tskip(t, fMain, "passes details by reference (no clone)", "Go passes the result by value into the output; there is no reference identity to assert (the details equal the input: TestEnvelopeDetailsEqualTheInput)")
+	tw(t, fMain, "accepts error field in envelope", func(t *testing.T) {
+		out := buildToolResult("Error: x", questionnaireResult{Cancelled: true, Error: errNoUI})
+		b, _ := json.Marshal(out.Details)
+		eq(t, string(b), `{"answers":[],"cancelled":true,"error":"no_ui"}`, "wire")
+		eq(t, out.Text, "Error: x", "text")
+	})
+}
+
+func TestEnvelopeDetailsEqualTheInput(t *testing.T) {
+	r := &questionnaireResult{Answers: []questionAnswer{answerOpt(0, "Which?", "A")}}
+	eq(t, buildQuestionnaireResponse(r, single()).Details, *r, "details")
+}
+
+func TestAnswerSegmentOrdersPreviewBeforeNotes(t *testing.T) {
+	a := answerOpt(0, "Q?", "A")
+	a.Preview, a.Notes = "P", "N"
+	eq(t, buildAnswerSegment(a), `"Q?"="A". selected preview: P. user notes: N.`, "segment")
+}
+
+func TestFormatAnswerScalar(t *testing.T) {
+	eq(t, formatAnswerScalar(answerMulti(0, "Q", "a", "b")), "a, b", "multi")
+	eq(t, formatAnswerScalar(answerMulti(0, "Q")), "(no input)", "multi empty")
+	eq(t, formatAnswerScalar(questionAnswer{Kind: "option"}), "(no input)", "option without answer")
+	eq(t, formatAnswerScalar(answerOpt(0, "Q", "")), "", "option with an empty answer keeps it (?? only replaces null)")
+}