From e5c21767cf01e64d311844399631f403e3ed8274 Mon Sep 17 00:00:00 2001
From: JJ Lee <jeonghun.jj.lee@gmail.com>
Date: Sun, 2 Aug 2026 18:08:43 -0400
Subject: [PATCH 1/9] feat(schema): question kind field (amicode#245)

---
 packages/schema/src/question.ts       |  6 +++
 packages/schema/src/v1/question.ts    |  5 +++
 packages/schema/test/question.test.ts | 54 +++++++++++++++++++++++++++
 3 files changed, 65 insertions(+)
 create mode 100644 packages/schema/test/question.test.ts

diff --git a/packages/schema/src/question.ts b/packages/schema/src/question.ts
index aba5ebfbaf..0f44af7685 100644
--- a/packages/schema/src/question.ts
+++ b/packages/schema/src/question.ts
@@ -25,11 +25,17 @@ export const Option = Schema.Struct({
 }).annotate({ identifier: "QuestionV2.Option" })
 export interface Option extends Schema.Schema.Type<typeof Option> {}
 
+export const Kind = Schema.Literals(["choice", "text"]).annotate({
+  description: 'Question shape: "choice" (default, an option list) or "text" (a free-form text card, no options)',
+})
+export type Kind = typeof Kind.Type
+
 const base = {
   question: Schema.String.annotate({ description: "Complete question" }),
   header: Schema.String.annotate({ description: "Very short label (max 30 chars)" }),
   options: Schema.Array(Option).annotate({ description: "Available choices" }),
   multiple: Schema.Boolean.pipe(optional).annotate({ description: "Allow selecting multiple choices" }),
+  kind: Kind.pipe(optional),
 }
 
 export const Info = Schema.Struct({
diff --git a/packages/schema/src/v1/question.ts b/packages/schema/src/v1/question.ts
index e566996472..b90503a594 100644
--- a/packages/schema/src/v1/question.ts
+++ b/packages/schema/src/v1/question.ts
@@ -17,11 +17,16 @@ export const Option = Schema.Struct({
   description: Schema.String.annotate({ description: "Explanation of choice" }),
 }).annotate({ identifier: "QuestionOption" })
 
+export const Kind = Schema.Literals(["choice", "text"]).annotate({
+  description: 'Question shape: "choice" (default, an option list) or "text" (a free-form text card, no options)',
+})
+
 const base = {
   question: Schema.String.annotate({ description: "Complete question" }),
   header: Schema.String.annotate({ description: "Very short label (max 30 chars)" }),
   options: Schema.Array(Option).annotate({ description: "Available choices" }),
   multiple: Schema.optional(Schema.Boolean).annotate({ description: "Allow selecting multiple choices" }),
+  kind: Schema.optional(Kind),
 }
 
 export const Info = Schema.Struct({
diff --git a/packages/schema/test/question.test.ts b/packages/schema/test/question.test.ts
new file mode 100644
index 0000000000..099bc0319f
--- /dev/null
+++ b/packages/schema/test/question.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test"
+import { Schema } from "effect"
+import { Question } from "../src/question"
+import { QuestionV1 } from "../src/question-v1"
+
+// Coverage for the question `kind` field (amicode#245): a Free-form Question
+// carries kind: "text" and renders as a text card; a Choice Question omits it
+// or carries kind: "choice". Back-compat: a payload WITHOUT kind decodes as a
+// choice question; an UNKNOWN kind fails decoding loudly rather than silently
+// degrading to choice.
+
+const choicePayload = {
+  question: "Which environment?",
+  header: "Env",
+  options: [
+    { label: "Dev", description: "Development" },
+    { label: "Prod", description: "Production" },
+  ],
+}
+
+const textPayload = {
+  question: "What should we call you?",
+  header: "Name",
+  options: [],
+  kind: "text",
+}
+
+const shapes: { name: string; schema: Schema.Decoder<unknown> }[] = [
+  { name: "v1 Info (server)", schema: QuestionV1.Info },
+  { name: "v1 Prompt (agent-facing)", schema: QuestionV1.Prompt },
+  { name: "v2 Info (server)", schema: Question.Info },
+  { name: "v2 Prompt (agent-facing)", schema: Question.Prompt },
+]
+
+describe.each(shapes)("question kind — $name", ({ schema }) => {
+  const decode = Schema.decodeUnknownSync(schema)
+  const kindOf = (input: unknown) => (decode(input) as { kind?: string }).kind
+
+  test("a payload without kind decodes (back-compat: a choice question)", () => {
+    expect(kindOf(choicePayload)).toBeUndefined()
+  })
+
+  test("an explicit choice kind decodes", () => {
+    expect(kindOf({ ...choicePayload, kind: "choice" })).toBe("choice")
+  })
+
+  test("a text kind decodes", () => {
+    expect(kindOf(textPayload)).toBe("text")
+  })
+
+  test("an unknown kind fails decoding loudly", () => {
+    expect(() => decode({ ...choicePayload, kind: "essay" })).toThrow()
+  })
+})

From a73af42e95fc7be8f95da8fd8b03642ecbbe5d7f Mon Sep 17 00:00:00 2001
From: JJ Lee <jeonghun.jj.lee@gmail.com>
Date: Sun, 2 Aug 2026 18:09:54 -0400
Subject: [PATCH 2/9] chore(sdk): regenerate question types with kind
 (amicode#245)

---
 packages/client/src/generated/types.ts  | 2 ++
 packages/sdk/js/src/v2/gen/types.gen.ts | 8 ++++++++
 2 files changed, 10 insertions(+)

diff --git a/packages/client/src/generated/types.ts b/packages/client/src/generated/types.ts
index 3b3188c874..8370f14b09 100644
--- a/packages/client/src/generated/types.ts
+++ b/packages/client/src/generated/types.ts
@@ -2707,6 +2707,7 @@ export type QuestionsListRequestsOutput = {
       readonly header: string
       readonly options: ReadonlyArray<{ readonly label: string; readonly description: string }>
       readonly multiple?: boolean
+      readonly kind?: "choice" | "text"
       readonly custom?: boolean
     }>
     readonly tool?: { readonly messageID: string; readonly callID: string }
@@ -2724,6 +2725,7 @@ export type QuestionsListOutput = {
       readonly header: string
       readonly options: ReadonlyArray<{ readonly label: string; readonly description: string }>
       readonly multiple?: boolean
+      readonly kind?: "choice" | "text"
       readonly custom?: boolean
     }>
     readonly tool?: { readonly messageID: string; readonly callID: string }
diff --git a/packages/sdk/js/src/v2/gen/types.gen.ts b/packages/sdk/js/src/v2/gen/types.gen.ts
index 90c91e9158..31cb4069cf 100644
--- a/packages/sdk/js/src/v2/gen/types.gen.ts
+++ b/packages/sdk/js/src/v2/gen/types.gen.ts
@@ -717,6 +717,10 @@ export type QuestionInfo = {
    */
   options: Array<QuestionOption>
   multiple?: boolean
+  /**
+   * Question shape: "choice" (default, an option list) or "text" (a free-form text card, no options)
+   */
+  kind?: "choice" | "text"
   custom?: boolean
 }
 
@@ -3152,6 +3156,10 @@ export type QuestionV2Info = {
    */
   options: Array<QuestionV2Option>
   multiple?: boolean
+  /**
+   * Question shape: "choice" (default, an option list) or "text" (a free-form text card, no options)
+   */
+  kind?: "choice" | "text"
   custom?: boolean
 }
 

From d5ac54d697bf3726f17ea977e50658920ccc14d7 Mon Sep 17 00:00:00 2001
From: JJ Lee <jeonghun.jj.lee@gmail.com>
Date: Sun, 2 Aug 2026 18:14:14 -0400
Subject: [PATCH 3/9] feat(cli): text-card question rendering in the run footer
 (amicode#245)

---
 .../src/cli/cmd/run/footer.question.tsx       | 78 ++++++++++++++--
 .../src/cli/cmd/run/question.shared.ts        | 22 ++++-
 .../test/cli/run/question.shared.test.ts      | 91 +++++++++++++++++++
 3 files changed, 179 insertions(+), 12 deletions(-)

diff --git a/packages/opencode/src/cli/cmd/run/footer.question.tsx b/packages/opencode/src/cli/cmd/run/footer.question.tsx
index 6b0b40bbd0..4039c6aef6 100644
--- a/packages/opencode/src/cli/cmd/run/footer.question.tsx
+++ b/packages/opencode/src/cli/cmd/run/footer.question.tsx
@@ -38,6 +38,7 @@ import {
   questionSubmit,
   questionSync,
   questionTabs,
+  questionText,
   questionTotal,
 } from "./question.shared"
 import { footerWidthPolicy } from "./footer.width"
@@ -55,6 +56,11 @@ export function RunQuestionBody(props: {
   const single = createMemo(() => questionSingle(props.request))
   const confirm = createMemo(() => questionConfirm(props.request, state()))
   const info = createMemo(() => questionInfo(props.request, state()))
+  // A Free-form Question (amicode#245) renders as a text card: the header plus
+  // a bare text input with submit — no option rows, no pseudo-option. The card
+  // is always in editing mode; its answer rides the typed-custom-answer path.
+  const text = createMemo(() => !confirm() && questionText(props.request, state()))
+  const editing = createMemo(() => state().editing || text())
   const input = createMemo(() => questionInput(state()))
   const other = createMemo(() => questionOther(props.request, state()))
   const picked = createMemo(() => questionPicked(state()))
@@ -171,9 +177,15 @@ export function RunQuestionBody(props: {
       return
     }
 
-    if (cur.editing) {
+    if (editing()) {
       if (event.name === "escape") {
-        setState((prev) => questionSetEditing(prev, false))
+        // A text card has no non-editing mode: esc dismisses the card, the
+        // same rejection a choice card's esc performs outside editing.
+        if (text()) {
+          reject()
+        } else {
+          setState((prev) => questionSetEditing(prev, false))
+        }
         event.preventDefault()
         return
       }
@@ -248,7 +260,7 @@ export function RunQuestionBody(props: {
   })
 
   createEffect(() => {
-    if (!state().editing || !area || area.isDestroyed) {
+    if (!editing() || !area || area.isDestroyed) {
       return
     }
 
@@ -258,7 +270,7 @@ export function RunQuestionBody(props: {
     }
 
     queueMicrotask(() => {
-      if (!area || area.isDestroyed || !state().editing) {
+      if (!area || area.isDestroyed || !editing()) {
         return
       }
 
@@ -361,8 +373,41 @@ export function RunQuestionBody(props: {
               </text>
             </box>
 
-            <box flexGrow={1} flexShrink={1}>
-              <scrollbox
+            <Show
+              when={!text()}
+              fallback={
+                <box flexGrow={1} flexShrink={1}>
+                  <textarea
+                    width="100%"
+                    minHeight={1}
+                    maxHeight={4}
+                    wrapMode="word"
+                    placeholder="Type your answer"
+                    placeholderColor={props.theme.muted}
+                    textColor={props.theme.text}
+                    focusedTextColor={props.theme.text}
+                    backgroundColor={props.theme.surface}
+                    focusedBackgroundColor={props.theme.surface}
+                    cursorColor={props.theme.text}
+                    focused={!disabled()}
+                    onSubmit={saveCustom}
+                    onContentChange={() => {
+                      if (!area || area.isDestroyed || disabled()) {
+                        return
+                      }
+
+                      const value = area.plainText
+                      setState((prev) => questionStoreCustom(prev, prev.tab, value))
+                    }}
+                    ref={(item) => {
+                      area = item
+                    }}
+                  />
+                </box>
+              }
+            >
+              <box flexGrow={1} flexShrink={1}>
+                <scrollbox
                 width="100%"
                 height="100%"
                 verticalScrollbarOptions={{
@@ -506,7 +551,8 @@ export function RunQuestionBody(props: {
                   </Show>
                 </box>
               </scrollbox>
-            </box>
+              </box>
+            </Show>
           </box>
         </Show>
       </box>
@@ -536,16 +582,28 @@ export function RunQuestionBody(props: {
             width={narrow() ? "100%" : undefined}
           >
             <Show
-              when={!state().editing}
+              when={!editing()}
               fallback={
-                <>
+                <Show
+                  when={!text()}
+                  fallback={
+                    <>
+                      <text fg={props.theme.text}>
+                        enter <span style={{ fg: props.theme.muted }}>submit</span>
+                      </text>
+                      <text fg={props.theme.text}>
+                        esc <span style={{ fg: props.theme.muted }}>dismiss</span>
+                      </text>
+                    </>
+                  }
+                >
                   <text fg={props.theme.text}>
                     enter <span style={{ fg: props.theme.muted }}>save</span>
                   </text>
                   <text fg={props.theme.text}>
                     esc <span style={{ fg: props.theme.muted }}>cancel</span>
                   </text>
-                </>
+                </Show>
               }
             >
               <Show when={!single()}>
diff --git a/packages/opencode/src/cli/cmd/run/question.shared.ts b/packages/opencode/src/cli/cmd/run/question.shared.ts
index 2821240d58..186db36c37 100644
--- a/packages/opencode/src/cli/cmd/run/question.shared.ts
+++ b/packages/opencode/src/cli/cmd/run/question.shared.ts
@@ -67,7 +67,14 @@ export function questionInfo(request: QuestionRequest, state: QuestionBodyState)
   return request.questions[state.tab]
 }
 
+// A Free-form Question (amicode#245): renders as a text card — a bare text
+// input with submit, no option rows and no "Type your own answer" pseudo-option.
+export function questionText(request: QuestionRequest, state: QuestionBodyState): boolean {
+  return questionInfo(request, state)?.kind === "text"
+}
+
 export function questionCustom(request: QuestionRequest, state: QuestionBodyState): boolean {
+  if (questionText(request, state)) return false
   return questionInfo(request, state)?.custom !== false
 }
 
@@ -86,7 +93,7 @@ export function questionPicked(state: QuestionBodyState): boolean {
 
 export function questionOther(request: QuestionRequest, state: QuestionBodyState): boolean {
   const info = questionInfo(request, state)
-  if (!info || info.custom === false) {
+  if (!info || info.custom === false || info.kind === "text") {
     return false
   }
 
@@ -95,7 +102,7 @@ export function questionOther(request: QuestionRequest, state: QuestionBodyState
 
 export function questionTotal(request: QuestionRequest, state: QuestionBodyState): number {
   const info = questionInfo(request, state)
-  if (!info) {
+  if (!info || info.kind === "text") {
     return 0
   }
 
@@ -264,6 +271,13 @@ export function questionSave(state: QuestionBodyState, request: QuestionRequest)
   const value = questionInput(state).trim()
   const prev = state.custom[state.tab]
   if (!value) {
+    // A text card has no other way to answer: stay editing, never submit
+    // empty text (submit is enabled only once the trimmed text is non-empty).
+    if (info.kind === "text") {
+      return {
+        state: questionSetEditing(state, true),
+      }
+    }
     if (!prev) {
       return {
         state: questionSetEditing(state, false),
@@ -327,6 +341,10 @@ export function questionHint(request: QuestionRequest, state: QuestionBodyState)
     return "enter submit   esc dismiss"
   }
 
+  if (questionText(request, state)) {
+    return "enter submit   esc dismiss"
+  }
+
   if (state.editing) {
     return "enter save   esc cancel"
   }
diff --git a/packages/opencode/test/cli/run/question.shared.test.ts b/packages/opencode/test/cli/run/question.shared.test.ts
index 27c8cecdb3..90e7242e29 100644
--- a/packages/opencode/test/cli/run/question.shared.test.ts
+++ b/packages/opencode/test/cli/run/question.shared.test.ts
@@ -3,6 +3,9 @@ import type { QuestionRequest } from "@opencode-ai/sdk/v2"
 import {
   createQuestionBodyState,
   questionConfirm,
+  questionCustom,
+  questionHint,
+  questionOther,
   questionReject,
   questionSave,
   questionSelect,
@@ -10,6 +13,8 @@ import {
   questionStoreCustom,
   questionSubmit,
   questionSync,
+  questionText,
+  questionTotal,
 } from "@/cli/cmd/run/question.shared"
 
 function req(input: Partial<QuestionRequest> = {}): QuestionRequest {
@@ -103,6 +108,92 @@ describe("run question shared", () => {
     })
   })
 
+  test("a text-kind question renders no options and no pseudo-option", () => {
+    const ask = req({
+      questions: [
+        {
+          question: "What should we call you?",
+          header: "Name",
+          options: [],
+          kind: "text",
+        },
+      ],
+    })
+    const state = createQuestionBodyState("question-1")
+
+    expect(questionText(ask, state)).toBe(true)
+    expect(questionTotal(ask, state)).toBe(0)
+    expect(questionOther(ask, state)).toBe(false)
+    expect(questionCustom(ask, state)).toBe(false)
+    expect(questionSelect(state, ask).state).toBe(state)
+  })
+
+  test("a text-kind question submits typed text through the custom-answer path", () => {
+    const ask = req({
+      questions: [
+        {
+          question: "What should we call you?",
+          header: "Name",
+          options: [],
+          kind: "text",
+        },
+      ],
+    })
+
+    const state = questionStoreCustom(createQuestionBodyState("question-1"), 0, "  JJ  ")
+    const next = questionSave(state, ask)
+    expect(next.reply).toEqual({
+      requestID: "question-1",
+      answers: [["JJ"]],
+    })
+  })
+
+  test("a text-kind question does not submit empty text", () => {
+    const ask = req({
+      questions: [
+        {
+          question: "What should we call you?",
+          header: "Name",
+          options: [],
+          kind: "text",
+        },
+      ],
+    })
+
+    const next = questionSave(createQuestionBodyState("question-1"), ask)
+    expect(next.reply).toBeUndefined()
+    expect(next.state.editing).toBe(true)
+    expect(next.state.answers[0] ?? []).toEqual([])
+    expect(questionHint(ask, next.state)).toBe("enter submit   esc dismiss")
+  })
+
+  test("a choice question without kind keeps its options and pseudo-option", () => {
+    const state = createQuestionBodyState("question-1")
+    const ask = req()
+
+    expect(questionText(ask, state)).toBe(false)
+    expect(questionTotal(ask, state)).toBe(2)
+    expect(questionCustom(ask, state)).toBe(true)
+  })
+
+  test("a choice question with custom disabled shows no pseudo-option", () => {
+    const state = createQuestionBodyState("question-1")
+    const ask = req({
+      questions: [
+        {
+          question: "Mode?",
+          header: "Mode",
+          options: [{ label: "chunked", description: "Incremental output" }],
+          multiple: false,
+          custom: false,
+        },
+      ],
+    })
+
+    expect(questionTotal(ask, state)).toBe(1)
+    expect(questionOther(ask, state)).toBe(false)
+  })
+
   test("resets state when the request id changes and builds reject payloads", () => {
     const state = questionSetSelected(createQuestionBodyState("question-1"), 1)
 

From 5a4abc7c3ab11643bbcd97c4d403cb404becf19c Mon Sep 17 00:00:00 2001
From: JJ Lee <jeonghun.jj.lee@gmail.com>
Date: Sun, 2 Aug 2026 18:23:32 -0400
Subject: [PATCH 4/9] feat(tui): text-card question rendering (amicode#245)

---
 packages/tui/src/routes/session/question.tsx  |  61 ++++-
 .../tui/test/routes/session/question.test.tsx | 214 ++++++++++++++++++
 2 files changed, 266 insertions(+), 9 deletions(-)
 create mode 100644 packages/tui/test/routes/session/question.test.tsx

diff --git a/packages/tui/src/routes/session/question.tsx b/packages/tui/src/routes/session/question.tsx
index 191d0a936a..7921b3a1e6 100644
--- a/packages/tui/src/routes/session/question.tsx
+++ b/packages/tui/src/routes/session/question.tsx
@@ -35,6 +35,11 @@ export function QuestionPrompt(props: { request: QuestionRequest; directory?: st
   const question = createMemo(() => questions()[store.tab])
   const confirm = createMemo(() => !single() && store.tab === questions().length)
   const options = createMemo(() => question()?.options ?? [])
+  // A Free-form Question (amicode#245) renders as a text card: the header plus
+  // a bare text input with submit — no option rows, no pseudo-option. The card
+  // is always in editing mode; its answer rides the typed-custom-answer path.
+  const text = createMemo(() => !confirm() && question()?.kind === "text")
+  const editing = createMemo(() => store.editing || text())
   const custom = createMemo(() => question()?.custom !== false)
   const other = createMemo(() => custom() && store.selected === options().length)
   const input = createMemo(() => store.custom[store.tab] ?? "")
@@ -132,15 +137,15 @@ export function QuestionPrompt(props: { request: QuestionRequest; directory?: st
 
   useBindings(() => ({
     mode: QUESTION_MODE,
-    enabled: store.editing && !confirm(),
+    enabled: editing() && !confirm(),
     commands: [
       {
         name: "prompt.clear",
         title: "Clear answer edit",
         category: "Question",
         run() {
-          const text = textarea?.plainText ?? ""
-          if (!text) {
+          const value = textarea?.plainText ?? ""
+          if (!value) {
             setStore("editing", false)
             return
           }
@@ -154,6 +159,12 @@ export function QuestionPrompt(props: { request: QuestionRequest; directory?: st
         desc: "Cancel answer edit",
         group: "Question",
         cmd: () => {
+          // A text card has no non-editing mode: esc dismisses the card, the
+          // same rejection a choice card's esc performs outside editing.
+          if (text()) {
+            reject()
+            return
+          }
           setStore("editing", false)
         },
       },
@@ -166,6 +177,12 @@ export function QuestionPrompt(props: { request: QuestionRequest; directory?: st
           const text = textarea?.plainText?.trim() ?? ""
           const prev = store.custom[store.tab]
 
+          // A text card's submit is enabled only once the trimmed text is
+          // non-empty: stay editing instead of clearing the (empty) answer.
+          if (!text && question()?.kind === "text") {
+            return
+          }
+
           if (!text) {
             if (prev) {
               const inputs = [...store.custom]
@@ -213,7 +230,7 @@ export function QuestionPrompt(props: { request: QuestionRequest; directory?: st
 
     return {
       mode: QUESTION_MODE,
-      enabled: !store.editing,
+      enabled: !editing(),
       commands: [
         {
           name: "app.exit",
@@ -360,8 +377,33 @@ export function QuestionPrompt(props: { request: QuestionRequest; directory?: st
                 {multi() ? " (select all that apply)" : ""}
               </text>
             </box>
-            <box>
-              <For each={options()}>
+            <Show
+              when={!text()}
+              fallback={
+                <box>
+                  <textarea
+                    ref={(val: TextareaRenderable) => {
+                      textarea = val
+                      val.traits = { status: "ANSWER" }
+                      queueMicrotask(() => {
+                        val.focus()
+                        val.gotoLineEnd()
+                      })
+                    }}
+                    initialValue={input()}
+                    placeholder="Type your answer"
+                    placeholderColor={theme.textMuted}
+                    minHeight={1}
+                    maxHeight={6}
+                    textColor={theme.text}
+                    focusedTextColor={theme.text}
+                    cursorColor={theme.primary}
+                  />
+                </box>
+              }
+            >
+              <box>
+                <For each={options()}>
                 {(opt, i) => {
                   const active = () => i() === store.selected
                   const picked = () => store.answers[store.tab]?.includes(opt.label) ?? false
@@ -451,7 +493,8 @@ export function QuestionPrompt(props: { request: QuestionRequest; directory?: st
                   </Show>
                 </box>
               </Show>
-            </box>
+              </box>
+            </Show>
           </box>
         </Show>
 
@@ -492,7 +535,7 @@ export function QuestionPrompt(props: { request: QuestionRequest; directory?: st
               {"⇆"} <span style={{ fg: theme.textMuted }}>tab</span>
             </text>
           </Show>
-          <Show when={!confirm()}>
+          <Show when={!confirm() && !text()}>
             <text fg={theme.text}>
               {"↑↓"} <span style={{ fg: theme.textMuted }}>select</span>
             </text>
@@ -500,7 +543,7 @@ export function QuestionPrompt(props: { request: QuestionRequest; directory?: st
           <text fg={theme.text}>
             enter{" "}
             <span style={{ fg: theme.textMuted }}>
-              {confirm() ? "submit" : multi() ? "toggle" : single() ? "submit" : "confirm"}
+              {confirm() || text() ? "submit" : multi() ? "toggle" : single() ? "submit" : "confirm"}
             </span>
           </text>
 
diff --git a/packages/tui/test/routes/session/question.test.tsx b/packages/tui/test/routes/session/question.test.tsx
new file mode 100644
index 0000000000..214e2a948c
--- /dev/null
+++ b/packages/tui/test/routes/session/question.test.tsx
@@ -0,0 +1,214 @@
+/** @jsxImportSource @opentui/solid */
+import { TextareaRenderable } from "@opentui/core"
+import { createDefaultOpenTuiKeymap } from "@opentui/keymap/opentui"
+import { testRender, useRenderer } from "@opentui/solid"
+import { expect, test } from "bun:test"
+import { mkdir } from "node:fs/promises"
+import path from "node:path"
+import { onCleanup } from "solid-js"
+import type { QuestionRequest } from "@opencode-ai/sdk/v2"
+import { tmpdir } from "../../fixture/fixture"
+import { TestTuiContexts } from "../../fixture/tui-environment"
+import { createTuiResolvedConfig } from "../../fixture/tui-runtime"
+
+// Render coverage for the question card shapes (amicode#245): a Free-form
+// Question (kind: "text") renders a text card — the header plus a bare text
+// input with submit, no option rows and no "Type your own answer"
+// pseudo-option — and its answer resolves through the typed-custom-answer
+// path. A Choice Question renders its options, with the pseudo-option only
+// when the question allows a custom answer.
+
+async function wait(fn: () => boolean, timeout = 2000) {
+  const start = Date.now()
+  while (!fn()) {
+    if (Date.now() - start > timeout) throw new Error("timed out waiting for condition")
+    await Bun.sleep(10)
+  }
+}
+
+type Captured = { pathname: string; body: unknown }
+
+async function mountQuestion(input: { root: string; request: QuestionRequest; captured: Captured[] }) {
+  const state = path.join(input.root, "state")
+  await mkdir(state, { recursive: true })
+  await Bun.write(path.join(state, "kv.json"), "{}")
+
+  const server = Bun.serve({
+    port: 0,
+    async fetch(req) {
+      const url = new URL(req.url)
+      if (req.method === "POST") {
+        input.captured.push({ pathname: url.pathname, body: await req.json().catch(() => null) })
+        return Response.json(true)
+      }
+      return new Response("not found", { status: 404 })
+    },
+  })
+
+  const [
+    { ThemeProvider },
+    { TuiConfigProvider },
+    { KVProvider },
+    { SDKProvider },
+    { OpencodeKeymapProvider, registerOpencodeKeymap },
+    { QuestionPrompt },
+  ] = await Promise.all([
+    import("../../../src/context/theme"),
+    import("../../../src/config"),
+    import("../../../src/context/kv"),
+    import("../../../src/context/sdk"),
+    import("../../../src/keymap"),
+    import("../../../src/routes/session/question"),
+  ])
+
+  function Harness() {
+    const renderer = useRenderer()
+    const keymap = createDefaultOpenTuiKeymap(renderer)
+    const resolvedConfig = createTuiResolvedConfig({ leader_timeout: 1000 })
+    const off = registerOpencodeKeymap(keymap, renderer, resolvedConfig)
+    onCleanup(off)
+
+    return (
+      <TestTuiContexts
+        directory={input.root}
+        paths={{
+          home: input.root,
+          state,
+          worktree: input.root,
+        }}
+      >
+        <OpencodeKeymapProvider keymap={keymap}>
+          <TuiConfigProvider config={resolvedConfig}>
+            <KVProvider>
+              <ThemeProvider mode="dark">
+                <SDKProvider url={`http://127.0.0.1:${server.port}`} events={{ subscribe: async () => () => {} }}>
+                  <QuestionPrompt request={input.request} directory={input.root} />
+                </SDKProvider>
+              </ThemeProvider>
+            </KVProvider>
+          </TuiConfigProvider>
+        </OpencodeKeymapProvider>
+      </TestTuiContexts>
+    )
+  }
+
+  const app = await testRender(() => <Harness />, { kittyKeyboard: true })
+  return {
+    app,
+    async cleanup() {
+      app.renderer.destroy()
+      server.stop(true)
+    },
+  }
+}
+
+const textRequest: QuestionRequest = {
+  id: "que_text",
+  sessionID: "ses_test",
+  questions: [
+    {
+      question: "What should we call you?",
+      header: "Name",
+      options: [],
+      kind: "text",
+    },
+  ],
+}
+
+const choiceRequest: QuestionRequest = {
+  id: "que_choice",
+  sessionID: "ses_test",
+  questions: [
+    {
+      question: "Which environment?",
+      header: "Env",
+      options: [
+        { label: "local-sim", description: "Local simulation" },
+        { label: "qick-lab", description: "The QICK lab" },
+      ],
+    },
+  ],
+}
+
+test("a free-form question renders a text card — no option rows, no pseudo-option", async () => {
+  await using tmp = await tmpdir()
+  const prompt = await mountQuestion({ root: tmp.path, request: textRequest, captured: [] })
+
+  try {
+    await wait(() => prompt.app.captureCharFrame().includes("What should we call you?"))
+    const frame = prompt.app.captureCharFrame()
+    expect(frame).not.toContain("Type your own answer")
+    expect(frame).not.toContain("local-sim")
+    await wait(() => prompt.app.renderer.currentFocusedEditor instanceof TextareaRenderable)
+  } finally {
+    await prompt.cleanup()
+  }
+})
+
+test("a text card submits the typed answer through the custom-answer path", async () => {
+  await using tmp = await tmpdir()
+  const captured: Captured[] = []
+  const prompt = await mountQuestion({ root: tmp.path, request: textRequest, captured })
+
+  try {
+    await wait(() => prompt.app.renderer.currentFocusedEditor instanceof TextareaRenderable)
+
+    await prompt.app.mockInput.typeText("JJ Lee")
+    prompt.app.mockInput.pressEnter()
+
+    await wait(() => captured.some((item) => item.pathname === "/question/que_text/reply"))
+    const reply = captured.find((item) => item.pathname === "/question/que_text/reply")
+    expect(reply?.body).toEqual({ answers: [["JJ Lee"]] })
+  } finally {
+    await prompt.cleanup()
+  }
+})
+
+test("a text card does not submit empty text", async () => {
+  await using tmp = await tmpdir()
+  const captured: Captured[] = []
+  const prompt = await mountQuestion({ root: tmp.path, request: textRequest, captured })
+
+  try {
+    await wait(() => prompt.app.renderer.currentFocusedEditor instanceof TextareaRenderable)
+
+    prompt.app.mockInput.pressEnter()
+    await Bun.sleep(300)
+    expect(captured.filter((item) => item.pathname === "/question/que_text/reply")).toEqual([])
+  } finally {
+    await prompt.cleanup()
+  }
+})
+
+test("a choice question renders its options and the typed-custom-answer row", async () => {
+  await using tmp = await tmpdir()
+  const prompt = await mountQuestion({ root: tmp.path, request: choiceRequest, captured: [] })
+
+  try {
+    await wait(() => prompt.app.captureCharFrame().includes("Which environment?"))
+    const frame = prompt.app.captureCharFrame()
+    expect(frame).toContain("local-sim")
+    expect(frame).toContain("qick-lab")
+    expect(frame).toContain("Type your own answer")
+  } finally {
+    await prompt.cleanup()
+  }
+})
+
+test("a choice question with custom disabled renders no pseudo-option", async () => {
+  await using tmp = await tmpdir()
+  const request: QuestionRequest = {
+    ...choiceRequest,
+    questions: [{ ...choiceRequest.questions[0], custom: false }],
+  }
+  const prompt = await mountQuestion({ root: tmp.path, request, captured: [] })
+
+  try {
+    await wait(() => prompt.app.captureCharFrame().includes("Which environment?"))
+    const frame = prompt.app.captureCharFrame()
+    expect(frame).toContain("local-sim")
+    expect(frame).not.toContain("Type your own answer")
+  } finally {
+    await prompt.cleanup()
+  }
+})

From be967a45de0f20e677cb57a8972edc94c9bf133d Mon Sep 17 00:00:00 2001
From: JJ Lee <jeonghun.jj.lee@gmail.com>
Date: Sun, 2 Aug 2026 18:27:39 -0400
Subject: [PATCH 5/9] feat(app): text-card questions + honor the custom-answer
 flag in the dock (amicode#245)

---
 .../session-question-dock.helpers.test.ts     | 45 ++++++++++
 .../composer/session-question-dock.helpers.ts | 25 ++++++
 .../composer/session-question-dock.tsx        | 83 ++++++++++++++-----
 3 files changed, 132 insertions(+), 21 deletions(-)
 create mode 100644 packages/app/src/pages/session/composer/session-question-dock.helpers.test.ts
 create mode 100644 packages/app/src/pages/session/composer/session-question-dock.helpers.ts

diff --git a/packages/app/src/pages/session/composer/session-question-dock.helpers.test.ts b/packages/app/src/pages/session/composer/session-question-dock.helpers.test.ts
new file mode 100644
index 0000000000..ab57e5752d
--- /dev/null
+++ b/packages/app/src/pages/session/composer/session-question-dock.helpers.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test"
+import { questionCustomRow, questionText, questionTextReady } from "./session-question-dock.helpers"
+
+// The dock rendering contract (amicode#245): text cards carry no option rows
+// and no pseudo-option; choice cards show the typed-custom-answer row only
+// when the question allows it; a text card's submit waits for non-empty text.
+
+describe("questionText", () => {
+  test("a text-kind question renders as a text card", () => {
+    expect(questionText({ kind: "text" })).toBe(true)
+  })
+
+  test("an absent or explicit choice kind renders as a choice card", () => {
+    expect(questionText({})).toBe(false)
+    expect(questionText({ kind: "choice" })).toBe(false)
+    expect(questionText(undefined)).toBe(false)
+  })
+})
+
+describe("questionCustomRow", () => {
+  test("a text card never shows the pseudo-option", () => {
+    expect(questionCustomRow({ kind: "text" })).toBe(false)
+    expect(questionCustomRow({ kind: "text", custom: true })).toBe(false)
+  })
+
+  test("a choice question shows the pseudo-option by default", () => {
+    expect(questionCustomRow({})).toBe(true)
+    expect(questionCustomRow({ kind: "choice" })).toBe(true)
+    expect(questionCustomRow({ custom: true })).toBe(true)
+  })
+
+  test("a choice question with custom disabled shows no pseudo-option", () => {
+    expect(questionCustomRow({ custom: false })).toBe(false)
+    expect(questionCustomRow({ kind: "choice", custom: false })).toBe(false)
+  })
+})
+
+describe("questionTextReady", () => {
+  test("submit is enabled only once the trimmed text is non-empty", () => {
+    expect(questionTextReady("")).toBe(false)
+    expect(questionTextReady("   \n  ")).toBe(false)
+    expect(questionTextReady("JJ")).toBe(true)
+    expect(questionTextReady("  JJ  ")).toBe(true)
+  })
+})
diff --git a/packages/app/src/pages/session/composer/session-question-dock.helpers.ts b/packages/app/src/pages/session/composer/session-question-dock.helpers.ts
new file mode 100644
index 0000000000..00787da07f
--- /dev/null
+++ b/packages/app/src/pages/session/composer/session-question-dock.helpers.ts
@@ -0,0 +1,25 @@
+import type { QuestionInfo } from "@opencode-ai/sdk/v2"
+
+// Question-shape rules for the session question dock (amicode#245). Extracted
+// from the component so the rendering contract is unit-testable: a Free-form
+// Question (kind: "text") renders a text card — the header plus a bare text
+// input with submit, no option rows and no typed-custom-answer pseudo-option —
+// while a Choice Question renders its options and shows the pseudo-option row
+// only when the question allows a custom answer.
+
+/** True when the question renders as a text card (no option list). */
+export function questionText(info: Pick<QuestionInfo, "kind"> | undefined): boolean {
+  return info?.kind === "text"
+}
+
+/** True when the typed-custom-answer row renders: choice questions that allow
+ *  a custom answer (the TUI flag check the dock previously ignored). */
+export function questionCustomRow(info: Pick<QuestionInfo, "kind" | "custom"> | undefined): boolean {
+  if (questionText(info)) return false
+  return info?.custom !== false
+}
+
+/** A text card's submit is enabled only once the trimmed text is non-empty. */
+export function questionTextReady(input: string): boolean {
+  return input.trim().length > 0
+}
diff --git a/packages/app/src/pages/session/composer/session-question-dock.tsx b/packages/app/src/pages/session/composer/session-question-dock.tsx
index 077f1e218e..50653ece84 100644
--- a/packages/app/src/pages/session/composer/session-question-dock.tsx
+++ b/packages/app/src/pages/session/composer/session-question-dock.tsx
@@ -13,6 +13,7 @@ import { makeEventListener } from "@solid-primitives/event-listener"
 import { createResizeObserver } from "@solid-primitives/resize-observer"
 import { useServerSDK } from "@/context/server-sdk"
 import { ScopedKey } from "@/utils/server-scope"
+import { questionCustomRow, questionText, questionTextReady } from "./session-question-dock.helpers"
 
 const cache = new Map<string, { tab: number; answers: QuestionAnswer[]; custom: string[]; customOn: boolean[] }>()
 
@@ -94,7 +95,12 @@ export const SessionQuestionDock: Component<{ request: QuestionRequest; onSubmit
   const input = createMemo(() => store.custom[store.tab] ?? "")
   const on = createMemo(() => store.customOn[store.tab] === true)
   const multi = createMemo(() => question()?.multiple === true)
-  const count = createMemo(() => options().length + 1)
+  // A Free-form Question (amicode#245) renders as a text card: the header plus
+  // a bare text input with submit — no option rows, no pseudo-option. Its
+  // answer rides the typed-custom-answer path; submit waits for non-empty text.
+  const text = createMemo(() => questionText(question()))
+  const customRow = createMemo(() => questionCustomRow(question()))
+  const count = createMemo(() => (text() ? 0 : options().length + 1))
 
   const summary = createMemo(() => {
     const n = Math.min(store.tab + 1, total())
@@ -339,7 +345,7 @@ export const SessionQuestionDock: Component<{ request: QuestionRequest; onSubmit
 
     const target =
       event.target instanceof HTMLElement ? event.target.closest('[data-slot="question-options"]') : undefined
-    if (store.editing) return
+    if (store.editing || text()) return
     if (!(target instanceof HTMLElement)) return
     if (event.altKey || event.ctrlKey || event.metaKey) return
 
@@ -416,6 +422,7 @@ export const SessionQuestionDock: Component<{ request: QuestionRequest; onSubmit
   const next = () => {
     if (sending()) return
     if (store.editing) commitCustom()
+    if (text() && !questionTextReady(input())) return
 
     if (store.tab >= total() - 1) {
       submit()
@@ -534,7 +541,7 @@ export const SessionQuestionDock: Component<{ request: QuestionRequest; onSubmit
               <Button
                 variant={last() ? "primary" : "secondary"}
                 size="large"
-                disabled={sending()}
+                disabled={sending() || (text() && !questionTextReady(input()))}
                 onClick={next}
                 aria-keyshortcuts="Meta+Enter Control+Enter"
               >
@@ -555,7 +562,7 @@ export const SessionQuestionDock: Component<{ request: QuestionRequest; onSubmit
         >
           {question()?.question}
         </div>
-        <Show when={!store.minimized}>
+        <Show when={!store.minimized && !text()}>
           <Show when={multi()} fallback={<div data-slot="question-hint">{language.t("ui.question.singleHint")}</div>}>
             <div data-slot="question-hint">{language.t("ui.question.multiHint")}</div>
           </Show>
@@ -571,23 +578,55 @@ export const SessionQuestionDock: Component<{ request: QuestionRequest; onSubmit
             visibility: optionsOff() ? "hidden" : "visible",
           }}
         >
-          <For each={options()}>
-            {(opt, i) => (
-              <Option
-                multi={multi()}
-                picked={picked(opt.label)}
-                label={opt.label}
-                description={opt.description}
-                disabled={sending()}
-                ref={(el) => (optsRef[i()] = el)}
-                onFocus={() => setStore("focus", i())}
-                onClick={() => selectOption(i())}
-              />
-            )}
-          </For>
-
           <Show
-            when={store.editing}
+            when={!text()}
+            fallback={
+              <form
+                data-slot="question-text-form"
+                onSubmit={(e) => {
+                  e.preventDefault()
+                  next()
+                }}
+              >
+                <textarea
+                  ref={focusCustom}
+                  data-slot="question-custom-input"
+                  placeholder={customPlaceholder()}
+                  value={input()}
+                  rows={1}
+                  disabled={sending()}
+                  onKeyDown={(e) => {
+                    if ((e.metaKey || e.ctrlKey) && !e.altKey) return
+                    if (e.key !== "Enter" || e.shiftKey) return
+                    e.preventDefault()
+                    next()
+                  }}
+                  onInput={(e) => {
+                    customUpdate(e.currentTarget.value, true)
+                    resizeInput(e.currentTarget)
+                  }}
+                />
+              </form>
+            }
+          >
+            <For each={options()}>
+              {(opt, i) => (
+                <Option
+                  multi={multi()}
+                  picked={picked(opt.label)}
+                  label={opt.label}
+                  description={opt.description}
+                  disabled={sending()}
+                  ref={(el) => (optsRef[i()] = el)}
+                  onFocus={() => setStore("focus", i())}
+                  onClick={() => selectOption(i())}
+                />
+              )}
+            </For>
+
+            <Show when={customRow()}>
+              <Show
+                when={store.editing}
             fallback={
               <button
                 type="button"
@@ -655,9 +694,11 @@ export const SessionQuestionDock: Component<{ request: QuestionRequest; onSubmit
                     customUpdate(e.currentTarget.value)
                     resizeInput(e.currentTarget)
                   }}
-                />
+                 />
               </span>
             </form>
+              </Show>
+            </Show>
           </Show>
         </div>
       </DockPrompt>

From f6892690eed01bb7c52d79beff4947f4fa086fd5 Mon Sep 17 00:00:00 2001
From: JJ Lee <jeonghun.jj.lee@gmail.com>
Date: Sun, 2 Aug 2026 18:29:55 -0400
Subject: [PATCH 6/9] feat(session): bilingual prose-guard nudge for text-card
 questions (amicode#245)

---
 packages/opencode/src/session/prompt.ts       | 33 ++++------
 packages/opencode/src/session/prose-guard.ts  | 57 +++++++++++++++++
 .../opencode/test/session/prose-guard.test.ts | 62 +++++++++++++++++++
 3 files changed, 131 insertions(+), 21 deletions(-)
 create mode 100644 packages/opencode/src/session/prose-guard.ts
 create mode 100644 packages/opencode/test/session/prose-guard.test.ts

diff --git a/packages/opencode/src/session/prompt.ts b/packages/opencode/src/session/prompt.ts
index 5692fbf000..67e791ce0b 100644
--- a/packages/opencode/src/session/prompt.ts
+++ b/packages/opencode/src/session/prompt.ts
@@ -3,6 +3,7 @@ import { PermissionV1 } from "@opencode-ai/core/v1/permission"
 import path from "path"
 import { SessionV1 } from "@opencode-ai/core/v1/session"
 import { producedUserVisibleOutput } from "./turn-output"
+import { askedQuestionInProse, PROSE_QUESTION_NUDGE } from "./prose-guard"
 import os from "os"
 import { SessionID, MessageID, PartID } from "./schema"
 import { MessageV2 } from "./message-v2"
@@ -1216,26 +1217,19 @@ const layer = Layer.effect(
             // stubborn turn can't loop forever.
             const askedInProse = (() => {
               if (!lastAssistantMsg || !lastAssistant) return false
-              // already nudged this exact assistant message? let it exit.
-              if (amicoNudged.has(lastAssistant.id)) return false
-              const askedQuestionTool = lastAssistantMsg.parts.some(
-                (p) => p.type === "tool" && p.tool === "question",
-              )
-              if (askedQuestionTool) return false
-              const text = lastAssistantMsg.parts
-                .filter((p): p is SessionV1.TextPart => p.type === "text")
-                .map((p) => p.text)
-                .join("\n")
-                .trimEnd()
-              // Heuristic: final non-empty line ends with "?" (a question to the user).
-              const endsWithQuestion = /\?["')\]]*\s*$/.test(text)
-              if (!endsWithQuestion) return false
               // Only within an active Amico interview: the session has recorded
               // at least one entity via an amicode_* tool this session.
               const interviewActive = msgs.some((m) =>
                 m.parts.some((p) => p.type === "tool" && typeof p.tool === "string" && p.tool.startsWith("amicode_")),
               )
-              return interviewActive
+              // The guard rule itself lives in prose-guard.ts so it is
+              // unit-testable (the turn-output.ts pattern).
+              return askedQuestionInProse({
+                // already nudged this exact assistant message? let it exit.
+                alreadyNudged: amicoNudged.has(lastAssistant.id),
+                parts: lastAssistantMsg.parts,
+                interviewActive,
+              })
             })()
 
             if (askedInProse && lastAssistant) {
@@ -1259,12 +1253,9 @@ const layer = Layer.effect(
                 messageID: nudgeMsg.id,
                 sessionID,
                 type: "text",
-                text:
-                  "[system] You just asked the user a question in plain text. The interview " +
-                  "requires the `question` tool for every question so the user gets a clickable " +
-                  "card — plain prose renders nothing to answer. Re-ask that exact question by " +
-                  "calling the `question` tool now (one question, default option first with " +
-                  "\"(Recommended)\"), and do not repeat the question in prose.",
+                // Bilingual nudge (amicode#245): options-with-recommended-first
+                // for choice questions, kind: "text" for free-form questions.
+                text: PROSE_QUESTION_NUDGE,
                 synthetic: true,
               } satisfies SessionV1.TextPart)
               step++
diff --git a/packages/opencode/src/session/prose-guard.ts b/packages/opencode/src/session/prose-guard.ts
new file mode 100644
index 0000000000..5458b2fcd6
--- /dev/null
+++ b/packages/opencode/src/session/prose-guard.ts
@@ -0,0 +1,57 @@
+// Amico interview prose-question guard — the prompt loop's rules, extracted so
+// they are unit-testable (same pattern as turn-output.ts for the silent-turn
+// guard).
+//
+// The pulse-designer interview must ask every question via the `question` tool
+// (it renders the clickable card). Models intermittently drift and ask in PROSE
+// instead, which leaves the user with no card and stalls the interview. When a
+// turn ends by asking a question in prose — no question tool call, final text
+// ends in "?" — while an interview is active, the loop injects a synthetic
+// nudge so the model re-asks via the tool. The guard fires at most once per
+// assistant message so a genuinely stubborn turn can't loop forever.
+//
+// The nudge is bilingual (amicode#245): the model picks the card shape from
+// the question it is re-asking — a choice question lists options (recommended
+// first), a free-form question uses kind: "text". The loop deliberately does
+// no classification of prose intent.
+
+/** The part shapes this rule cares about. Structural on purpose — it accepts
+ *  any superset, so callers can pass the full SessionV1 part union unchanged. */
+export interface ProseGuardPartLike {
+  type: string
+  text?: string
+  tool?: string
+}
+
+/** True when an assistant turn asked the user a question in prose and should
+ *  be nudged to re-ask via the `question` tool. */
+export function askedQuestionInProse(input: {
+  /** This exact assistant message was already nudged (at most once per message). */
+  alreadyNudged: boolean
+  parts: readonly ProseGuardPartLike[] | undefined
+  /** The session has recorded at least one entity via an amicode_* tool. */
+  interviewActive: boolean
+}): boolean {
+  if (input.alreadyNudged) return false
+  const parts = input.parts ?? []
+  if (parts.some((p) => p.type === "tool" && p.tool === "question")) return false
+  const text = parts
+    .filter((p) => p.type === "text")
+    .map((p) => p.text ?? "")
+    .join("\n")
+    .trimEnd()
+  // Heuristic: final non-empty line ends with "?" (a question to the user).
+  if (!/\?["')\]]*\s*$/.test(text)) return false
+  return input.interviewActive
+}
+
+/** The synthetic user-turn text injected when the guard fires. */
+export const PROSE_QUESTION_NUDGE =
+  "[system] You just asked the user a question in plain text. The interview " +
+  "requires the `question` tool for every question so the user gets a clickable " +
+  "card — plain prose renders nothing to answer. Re-ask that exact question by " +
+  "calling the `question` tool now, and do not repeat the question in prose. " +
+  "Pick the card shape from the question you are re-asking: a choice question " +
+  "lists its options (default option first with \"(Recommended)\"); a free-form " +
+  "question — one expecting an open-ended typed answer, like a name or a number " +
+  "— uses kind: \"text\" and no options."
diff --git a/packages/opencode/test/session/prose-guard.test.ts b/packages/opencode/test/session/prose-guard.test.ts
new file mode 100644
index 0000000000..4cb2d7b9a3
--- /dev/null
+++ b/packages/opencode/test/session/prose-guard.test.ts
@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test"
+import { askedQuestionInProse, PROSE_QUESTION_NUDGE } from "../../src/session/prose-guard"
+
+// Coverage for the Amico interview prose guard (amicode#245). Behavior is
+// unchanged — a prose question in an active interview is still forced into a
+// card, at most once per assistant message — but the nudge text is bilingual:
+// it instructs options-with-recommended-first for choice questions and the
+// text kind for free-form questions. A turn that called the question tool
+// (either kind) never triggers the nudge.
+
+describe("askedQuestionInProse", () => {
+  const prose = [{ type: "text", text: "Reasoning done. What is your name?" }]
+
+  test("a prose question in an active interview triggers the nudge", () => {
+    expect(askedQuestionInProse({ alreadyNudged: false, parts: prose, interviewActive: true })).toBe(true)
+  })
+
+  test("a turn that called the question tool never triggers it", () => {
+    const parts = [
+      { type: "tool", tool: "question" },
+      { type: "text", text: "What is your name?" },
+    ]
+    expect(askedQuestionInProse({ alreadyNudged: false, parts, interviewActive: true })).toBe(false)
+  })
+
+  test("an already-nudged message is let through (at most once per message)", () => {
+    expect(askedQuestionInProse({ alreadyNudged: true, parts: prose, interviewActive: true })).toBe(false)
+  })
+
+  test("text that does not end in a question mark is not a prose question", () => {
+    const parts = [{ type: "text", text: "Recording the system now." }]
+    expect(askedQuestionInProse({ alreadyNudged: false, parts, interviewActive: true })).toBe(false)
+  })
+
+  test("a trailing quote or bracket after the question mark still counts", () => {
+    const parts = [{ type: "text", text: 'And your affiliation — "where do you work?"' }]
+    expect(askedQuestionInProse({ alreadyNudged: false, parts, interviewActive: true })).toBe(true)
+  })
+
+  test("outside an active interview a prose question is left alone", () => {
+    expect(askedQuestionInProse({ alreadyNudged: false, parts: prose, interviewActive: false })).toBe(false)
+  })
+
+  test("missing parts never throw and never nudge", () => {
+    expect(askedQuestionInProse({ alreadyNudged: false, parts: undefined, interviewActive: true })).toBe(false)
+  })
+})
+
+describe("PROSE_QUESTION_NUDGE", () => {
+  test("still forces every question through the question tool", () => {
+    expect(PROSE_QUESTION_NUDGE).toContain("`question` tool")
+    expect(PROSE_QUESTION_NUDGE).toContain("plain prose renders nothing to answer")
+  })
+
+  test("instructs options with the recommended option first for choice questions", () => {
+    expect(PROSE_QUESTION_NUDGE).toContain("(Recommended)")
+  })
+
+  test("instructs the text kind for free-form questions", () => {
+    expect(PROSE_QUESTION_NUDGE).toContain('kind: "text"')
+  })
+})

From 22cb9e9f37976f8ca3c24ddd1378a4f932743adc Mon Sep 17 00:00:00 2001
From: JJ Lee <jeonghun.jj.lee@gmail.com>
Date: Sun, 2 Aug 2026 18:32:08 -0400
Subject: [PATCH 7/9] feat(tool): teach the question text kind for free-form
 questions (amicode#245)

---
 packages/core/src/tool/question.ts           |  1 +
 packages/core/test/tool-question.test.ts     |  6 ++++
 packages/opencode/src/tool/question.txt      |  1 +
 packages/opencode/test/tool/question.test.ts | 32 ++++++++++++++++++++
 4 files changed, 40 insertions(+)

diff --git a/packages/core/src/tool/question.ts b/packages/core/src/tool/question.ts
index e5ae0d7426..3fa5b3b215 100644
--- a/packages/core/src/tool/question.ts
+++ b/packages/core/src/tool/question.ts
@@ -18,6 +18,7 @@ export const description = `Use this tool when you need to ask the user question
 4. Offer choices to the user about what direction to take.
 
 Usage notes:
+- Every question is a card: a choice question (default) lists options; a free-form question — one expecting an open-ended typed answer, like a name or a number — uses kind: "text" and renders a bare text input with submit, so give it no options
 - When \`custom\` is enabled (default), a "Type your own answer" option is added automatically; don't include "Other" or catch-all options
 - Answers are returned as arrays of labels; set \`multiple: true\` to allow selecting more than one
 - If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label`
diff --git a/packages/core/test/tool-question.test.ts b/packages/core/test/tool-question.test.ts
index d76e153882..540bae03b5 100644
--- a/packages/core/test/tool-question.test.ts
+++ b/packages/core/test/tool-question.test.ts
@@ -52,6 +52,12 @@ const it = testEffect(
 )
 
 describe("QuestionTool", () => {
+  it.effect("teaches the text kind for free-form questions in its description", () =>
+    Effect.gen(function* () {
+      expect(QuestionTool.description).toContain('kind: "text"')
+    }),
+  )
+
   it.effect("omits a denied built-in question and terminally settles a stale call", () =>
     Effect.gen(function* () {
       captured = undefined
diff --git a/packages/opencode/src/tool/question.txt b/packages/opencode/src/tool/question.txt
index 03cd496d60..f7f76bc2d3 100644
--- a/packages/opencode/src/tool/question.txt
+++ b/packages/opencode/src/tool/question.txt
@@ -5,6 +5,7 @@ Use this tool when you need to ask the user questions during execution. This all
 4. Offer choices to the user about what direction to take.
 
 Usage notes:
+- Every question is a card: a choice question (default) lists options; a free-form question — one expecting an open-ended typed answer, like a name or a number — uses kind: "text" and renders a bare text input with submit, so give it no options
 - When `custom` is enabled (default), a "Type your own answer" option is added automatically; don't include "Other" or catch-all options
 - Answers are returned as arrays of labels; set `multiple: true` to allow selecting more than one
 - If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
diff --git a/packages/opencode/test/tool/question.test.ts b/packages/opencode/test/tool/question.test.ts
index d8c6df77e8..bcbf2d07ad 100644
--- a/packages/opencode/test/tool/question.test.ts
+++ b/packages/opencode/test/tool/question.test.ts
@@ -68,6 +68,38 @@ describe("tool.question", () => {
     }),
   )
 
+  it.instance("teaches the text kind for free-form questions in its description", () =>
+    Effect.gen(function* () {
+      const toolInfo = yield* QuestionTool
+      const tool = yield* toolInfo.init()
+      expect(tool.description).toContain('kind: "text"')
+    }),
+  )
+
+  it.instance("passes a text-kind question through to the pending request", () =>
+    Effect.gen(function* () {
+      const question = yield* Question.Service
+      const toolInfo = yield* QuestionTool
+      const tool = yield* toolInfo.init()
+      const questions = [
+        {
+          question: "What should we call you?",
+          header: "Name",
+          options: [],
+          kind: "text" as const,
+        },
+      ]
+
+      const fiber = yield* tool.execute({ questions }, ctx).pipe(Effect.forkScoped)
+      const item = yield* pending(question)
+      expect(item.questions[0]?.kind).toBe("text")
+      yield* question.reply({ requestID: item.id, answers: [["JJ"]] })
+
+      const result = yield* Fiber.join(fiber)
+      expect(result.output).toContain(`"What should we call you?"="JJ"`)
+    }),
+  )
+
   it.instance("should now pass with a header longer than 12 but less than 30 chars", () =>
     Effect.gen(function* () {
       const question = yield* Question.Service

From 3a6d7f273818f05d67b2d5a457d16f7c46e287d0 Mon Sep 17 00:00:00 2001
From: JJ Lee <jeonghun.jj.lee@gmail.com>
Date: Sun, 2 Aug 2026 18:33:42 -0400
Subject: [PATCH 8/9] =?UTF-8?q?docs(amicode):=20patch=2026=20=E2=80=94=20t?=
 =?UTF-8?q?ext-card=20questions=20(amicode#245)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AMICODE-PATCHES.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/AMICODE-PATCHES.md b/AMICODE-PATCHES.md
index 7de875daa3..5cc739cd1c 100644
--- a/AMICODE-PATCHES.md
+++ b/AMICODE-PATCHES.md
@@ -404,6 +404,8 @@ Rebuilt with the exact T3 recipe (`OPENCODE_VERSION=1.17.3 bun run script/build.
     - `text-shimmer.tsx` untouched — it has many other live callers (`basic-tool.tsx`, `message-part.tsx` ×7, `session-turn.tsx`, `v2/components/basic-tool-v2.tsx` via `text-shimmer-v2.tsx`, plus stories), confirmed via `rg -n 'TextShimmer' packages/`. Not a candidate for deletion.
     - The dropped `offset` prop existed only so the shimmer's gradient phase stayed continuous across the prefix/tail split; with no shimmer there's nothing to phase-align, so it has no replacement. Verified live (Storybook, `UI/AnimatedCountList` stories) that the prefix and tail still read as one unbroken word with no seam: in the swap-mode `Playground` story, driving an active→done transition showed the mid-animation frame rendering both the active and done spans simultaneously under the animating width (`data-ready="true"`, container `style="width: 0px"` mid-transition, then settling) — the word-morph is intact. The suffix/prefix-tail mode (`data-mode="suffix"`) is currently unreachable from any real call site — both app usages (`message-part.tsx` context-tool-group and shell-group titles) and the only story pass `split={false}` — so it was verified by transiently flipping one story's `split` prop off (`Done` export, "Exploring"/"Explored"), confirming `data-mode="suffix"` renders `"Explor"` + `"ed"` as an unbroken "Explored" with no visible gap, then reverting that story edit before commit (`git status` shows only the two files below).
     - Tests: ui `bun test src` → 402 pass / 0 fail (unchanged). typecheck (tsgo) clean in `packages/ui`. `oxlint packages/ui/src` → 498 warnings / 0 errors both before and after (no new warnings once `prefixLen` was dropped).
+26. (text-card questions — free-form asks get a first-class card, 2026-08-02) — amicode#245 + ADR `docs/adr/0002-free-form-questions-render-as-text-cards.md`: the question schema grows an optional `kind` (`"choice"` default | `"text"`) on the agent-facing AND server shapes (v1 `packages/schema/src/v1/question.ts` + v2 `packages/schema/src/question.ts`, both in `base` so `Prompt` and `Info` carry it; absent → choice, unknown kind fails decoding loudly). Three renderers branch a text card (header + bare text input + submit; NO option rows, NO "Type your own answer" pseudo-option; submit gated on non-empty trimmed text; answers ride the EXISTING typed-custom-answer path; dismissal unchanged): app dock (`session-question-dock.tsx` + new `session-question-dock.helpers.ts` — ALSO honors the `custom` flag for CHOICE cards, the TUI pattern it previously ignored), TUI (`question.tsx`), CLI (`question.shared.ts` + `footer.question.tsx`). Prose guard (`session/prompt.ts`) behavior UNCHANGED (still fires on prose questions in active interviews, once per assistant message, never after a question-tool call); predicate + nudge extracted to `session/prose-guard.ts` (turn-output.ts pattern); nudge text now bilingual (options-with-recommended-first for choice, `kind: "text"` for free-form). Tool descriptions teach the text kind (`tool/question.txt` + core `tool/question.ts`). Legacy SDK + client codegen regenerated (QuestionInfo/QuestionV2Info gain `kind?: "choice" | "text"`). Upstream-sync watch: the dock's question component is already a high-conflict file — keep the text-card branch and the `customRow()` gate honest on syncs.
+    - Tests: schema `test/question.test.ts` (decode ×4 shapes: absent/choice/text/unknown), opencode `test/cli/run/question.shared.test.ts` (+5: text card shape/submit/empty-blocked, choice regression, custom:false), tui `test/routes/session/question.test.tsx` (+5: render coverage incl. typed-answer submit through a stub server), app `session-question-dock.helpers.test.ts` (+6), opencode `test/session/prose-guard.test.ts` (+10: predicate truth table + bilingual nudge), tool tests (+2 description, +1 kind passthrough).
 
 ## Feature-branch recovery 2026-08-01 (after the upstream sync)
 

From f5f51b9a4c6adc2926311854e8a476708c1c4bff Mon Sep 17 00:00:00 2001
From: JJ Lee <jeonghun.jj.lee@gmail.com>
Date: Sun, 2 Aug 2026 18:48:58 -0400
Subject: [PATCH 9/9] test(opencode): question wire-shape snapshot gains the
 kind field (amicode#245)

---
 .../test/tool/__snapshots__/parameters.test.ts.snap       | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/packages/opencode/test/tool/__snapshots__/parameters.test.ts.snap b/packages/opencode/test/tool/__snapshots__/parameters.test.ts.snap
index 51ff867ea4..1dec8f36f5 100644
--- a/packages/opencode/test/tool/__snapshots__/parameters.test.ts.snap
+++ b/packages/opencode/test/tool/__snapshots__/parameters.test.ts.snap
@@ -206,6 +206,14 @@ exports[`tool parameters JSON Schema (wire shape) question 1`] = `
             "description": "Very short label (max 30 chars)",
             "type": "string",
           },
+          "kind": {
+            "description": "Question shape: "choice" (default, an option list) or "text" (a free-form text card, no options)",
+            "enum": [
+              "choice",
+              "text",
+            ],
+            "type": "string",
+          },
           "multiple": {
             "description": "Allow selecting multiple choices",
             "type": "boolean",