@raidiant/notifai 0.1.8 → 0.2.0

package/src/hooks.test.ts

@@ -127,7 +127,8 @@ function reply(overrides: Partial<ReplyView> = {}): ReplyView {
     device_id: 'dev_test',
     device_name: 'Furankuphone',
     text: 'Allow',
-    choice_id: 'allow',
+    answers: [{ question_id: 'q1', choice_ids: ['allow'], text: null }],
+    source: null,
     created_at: new Date().toISOString(),
     ...overrides,
   }
@@ -915,11 +916,11 @@ describe('ask registration', () => {
     const h = harness()
     // Inside a hook, a rejection is only a stderr note the agent never reads —
     // so it would look registered and then silently never ask.
-    expect(askCommand(h.deps, 'Ship it?', { choice: 'Yes|No', session: 'a1' })).toBe(EXIT.usage)
+    expect(askCommand(h.deps, 'Ship it?', { choice: ['Only one'], session: 'a1' })).toBe(EXIT.usage)
     expect(readSessionState('a1', h.env).pending).toBeUndefined()
   })
 
-  it('stores validated labels verbatim, commas and all', () => {
+  it('stores the validated question set, comma-bearing labels verbatim', () => {
     const h = harness()
     expect(
       askCommand(h.deps, 'Ship it?', {
@@ -927,7 +928,104 @@ describe('ask registration', () => {
         session: 'a2',
       }),
     ).toBe(EXIT.ok)
-    expect(readSessionState('a2', h.env).pending?.choices).toEqual(['Yes, ship it', 'No, hold'])
+    expect(readSessionState('a2', h.env).pending?.questions).toEqual([
+      {
+        id: 'ship-it',
+        text: 'Ship it?',
+        choices: [
+          { id: 'yes-ship-it', label: 'Yes, ship it' },
+          { id: 'no-hold', label: 'No, hold' },
+        ],
+      },
+    ])
+  })
+
+  it('registers a multi-question form and pushes it as one set', async () => {
+    const h = harness([reply({ text: 'Yes' })], 900)
+    writeSessionState('form1', h.env, { last_prompt_at: AWAY })
+    expect(
+      askCommand(h.deps, undefined, {
+        session: 'form1',
+        form: JSON.stringify({
+          questions: [
+            { text: 'Deploy where?', choices: ['Staging', 'Production'], multi: true },
+            { text: 'Anything to watch?' },
+          ],
+          detail: '## Context\nThe long story.',
+        }),
+      }),
+    ).toBe(EXIT.ok)
+    const pending = readSessionState('form1', h.env).pending
+    expect(pending?.questions).toHaveLength(2)
+    expect(pending?.detail).toContain('long story')
+
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'form1' }))
+    const draft = h.recorder.submitted[0]?.draft
+    // The banner leads with the first question and admits the rest exists;
+    // the full set rides the payload for the answering card.
+    expect(draft?.presentation.body).toBe('Deploy where? (+1 more)')
+    expect(draft?.presentation.detail).toContain('long story')
+    expect(draft?.reply?.questions).toEqual([
+      {
+        id: 'deploy-where',
+        text: 'Deploy where?',
+        choices: [
+          { id: 'staging', label: 'Staging' },
+          { id: 'production', label: 'Production' },
+        ],
+        multi: true,
+      },
+      { id: 'anything-to-watch', text: 'Anything to watch?' },
+    ])
+  })
+
+  it('acts on the latest reply when answers conflict, because it is a correction', async () => {
+    const h = harness(
+      [
+        reply({ seq: 1, text: 'Yes', answers: [{ question_id: 'ship-it', choice_ids: ['yes'], text: null }] }),
+        reply({
+          seq: 2,
+          reply_id: 'rpl_2',
+          text: 'No',
+          answers: [{ question_id: 'ship-it', choice_ids: ['no'], text: null }],
+        }),
+      ],
+      900,
+    )
+    writeSessionState('latest1', h.env, { last_prompt_at: AWAY })
+    expect(
+      askCommand(h.deps, 'Ship it?', { session: 'latest1', choice: ['Yes', 'No'] }),
+    ).toBe(EXIT.ok)
+
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'latest1' }))
+
+    const decision = JSON.parse(h.io.outLines.at(-1)!) as { decision: string; reason: string }
+    expect(decision.decision).toBe('block')
+    expect(decision.reason).toContain('"No"')
+    expect(decision.reason).not.toContain('"Yes"')
+  })
+
+  it('hands a free-text answer written in parts to the agent in order', async () => {
+    const h = harness(
+      [
+        reply({ seq: 1, text: 'Use blue', answers: [{ question_id: 'which-color', choice_ids: [], text: 'Use blue' }] }),
+        reply({
+          seq: 2,
+          reply_id: 'rpl_2',
+          text: 'actually teal',
+          answers: [{ question_id: 'which-color', choice_ids: [], text: 'actually teal' }],
+        }),
+      ],
+      900,
+    )
+    writeSessionState('parts1', h.env, { last_prompt_at: AWAY })
+    expect(askCommand(h.deps, 'Which color?', { session: 'parts1' })).toBe(EXIT.ok)
+
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'parts1' }))
+
+    const decision = JSON.parse(h.io.outLines.at(-1)!) as { reason: string }
+    expect(decision.reason).toContain('in the order written')
+    expect(decision.reason).toContain('"Use blue", then "actually teal"')
   })
 
   it('resolves the session as flag, then hook pointer, then NOTIFAI_SESSION', async () => {

package/src/hooks.ts

@@ -11,7 +11,7 @@ import {
   writeFileSync,
 } from 'node:fs'
 import path from 'node:path'
-import type { LifecycleEndState, ReplyView } from '@raidiant/notifai-protocol'
+import type { LifecycleEndState, QuestionT, ReplyView } from '@raidiant/notifai-protocol'
 import type { ApiClient } from './client.js'
 import {
   loadConfig,
@@ -120,6 +120,7 @@ const ORPHAN_TTL_MS = 24 * 3600 * 1000
 const ORPHAN_QUEUE_CAP = 50
 
 export interface PendingQuestion {
+  /** One-line summary: the single question's text, or the set's first. */
   question: string
   /**
    * Epoch ms when `notifai ask` registered this. The grace window runs from
@@ -128,11 +129,12 @@ export interface PendingQuestion {
    */
   asked_at?: number
   /**
-   * Canonical answer labels, already split and validated by `notifai ask`.
-   * Stored as a list rather than a comma-joined string so a label containing a
-   * comma survives the round trip.
+   * The full question set as `notifai ask` validated it: generated ids,
+   * texts, choices, multi flags. What actually rides the push.
    */
-  choices?: string[]
+  questions?: QuestionT[]
+  /** Long-form markdown context, shown in the companion's detail view. */
+  detail?: string
   /** Set once the question has actually been pushed, so it can be retired. */
   request_id?: string
   collapse_key?: string
@@ -641,7 +643,10 @@ export type HookHarness = 'claude-code' | 'codex' | 'cursor' | 'opencode'
 interface AskResult {
   requestId: string
   collapseKey: string
+  /** The answer to act on: the latest reply, because a later one corrects. */
   reply: ReplyView | null
+  /** Every reply in arrival order, for free-text answers given in parts. */
+  replies: ReplyView[]
   /** The devices the question went to; retirement must not reach any other. */
   devices: string[]
   /** The wait ended amid network failures, so "no answer" is unproven. */
@@ -658,8 +663,11 @@ const REPLY_PRESENCE_POLL_SECONDS = 5
 /**
  * Push a question and block for the answer.
  *
- * An answered question is closed immediately: the first answer wins, and the
- * other devices must stop offering to change it. An unanswered one stays open,
+ * An answered question is closed the moment this wait sees the answer: the
+ * first device to answer claims the question and the others are told. Until
+ * that close, a later reply is a correction — so what this returns as "the"
+ * answer is always the latest reply, with the full stream alongside for
+ * free-text answers given in parts. An unanswered question stays open,
  * because nobody has acted on the silence yet and the next turn can still
  * collect the answer with `notifai replies`.
  */
@@ -668,7 +676,8 @@ async function askAndWait(
   options: {
     title: string
     body: string
-    choices?: string[]
+    questions: QuestionT[]
+    detail?: string | undefined
     event: string
     /** Which agent is asking; two of them must not look alike. */
     session?: string | undefined
@@ -695,7 +704,8 @@ async function askAndWait(
     device: answerable,
     reply: true,
     replyWindow: Math.max(60, options.windowSeconds),
-    ...(options.choices !== undefined ? { replyChoice: options.choices } : {}),
+    questions: options.questions,
+    ...(options.detail !== undefined ? { detail: options.detail } : {}),
     collapseKey,
   })
   if (!build.ok) return { error: build.error }
@@ -718,6 +728,7 @@ async function askAndWait(
       requestId: receipt.request_id,
       collapseKey,
       reply: null,
+      replies: [],
       devices: answerable,
       degraded: false,
       waited: false,
@@ -730,7 +741,11 @@ async function askAndWait(
   return {
     requestId: receipt.request_id,
     collapseKey,
-    reply: result.replies[0] ?? null,
+    // The latest reply, not the first: an earlier conflicting answer was
+    // corrected by the one that followed it. The cross-device race is still
+    // first-answer-claims — that is what the close above enforces.
+    reply: result.replies.at(-1) ?? null,
+    replies: result.replies,
     devices: answerable,
     degraded: result.degraded,
     waited: true,
@@ -1088,7 +1103,10 @@ const LATE_PROMPT_POLL_SECONDS = 3
 const MAX_CONTINUATION_COUNT = 3
 
 interface PendingPoll {
+  /** The answer to act on: the latest reply, because a later one corrects. */
   reply: ReplyView | null
+  /** Every reply in arrival order, for free-text answers given in parts. */
+  replies: ReplyView[]
   degraded: boolean
   failed: boolean
 }
@@ -1099,34 +1117,64 @@ async function pollPendingReply(
   pending: PendingQuestion,
   timeoutSeconds: number,
 ): Promise<PendingPoll> {
-  if (pending.request_id === undefined) return { reply: null, degraded: false, failed: false }
+  if (pending.request_id === undefined) {
+    return { reply: null, replies: [], degraded: false, failed: false }
+  }
   try {
     const result = await ctx.waitForFirstReply(pending.request_id, timeoutSeconds)
     return {
-      reply: result.replies[0] ?? null,
+      reply: result.replies.at(-1) ?? null,
+      replies: result.replies,
       degraded: result.degraded === true,
       failed: false,
     }
   } catch {
-    return { reply: null, degraded: true, failed: true }
+    return { reply: null, replies: [], degraded: true, failed: true }
   }
 }
 
-function answerContext(reply: ReplyView): string {
-  return `Notifai — the user answered from ${reply.device_name}: "${reply.text}". Continue with that answer.`
+/** The question set this pending record pushes, however it was registered. */
+function pendingQuestions(pending: PendingQuestion): QuestionT[] {
+  return pending.questions ?? [{ id: 'q1', text: pending.question }]
+}
+
+/** Did any question in the set offer choices? Decides how replies combine. */
+function pendingHasChoices(pending: PendingQuestion): boolean {
+  return pendingQuestions(pending).some((question) => question.choices !== undefined)
+}
+
+/**
+ * The answer as the agent should read it. For a question with choices the
+ * latest reply IS the answer — an earlier conflicting one was corrected by
+ * it. Free-text answers can arrive in parts, and every part reaches the
+ * agent in the order it was written, so it can tell expansion from
+ * correction itself.
+ */
+function answerContext(replies: ReplyView[], hadChoices: boolean): string {
+  const latest = replies.at(-1)
+  if (latest === undefined) return 'Notifai — no answer was recorded.'
+  if (replies.length === 1 || hadChoices) {
+    return `Notifai — the user answered from ${latest.device_name}: "${latest.text}". Continue with that answer.`
+  }
+  const parts = replies.map((reply) => `"${reply.text}"`).join(', then ')
+  return (
+    `Notifai — the user answered from ${latest.device_name} in ${replies.length} parts, ` +
+    `in the order written: ${parts}. Later parts extend or correct earlier ones. ` +
+    'Continue with that answer.'
+  )
 }
 
-function userPromptAnswerOutput(reply: ReplyView): string {
+function userPromptAnswerOutput(replies: ReplyView[], hadChoices: boolean): string {
   return JSON.stringify({
     hookSpecificOutput: {
       hookEventName: 'UserPromptSubmit',
-      additionalContext: answerContext(reply),
+      additionalContext: answerContext(replies, hadChoices),
     },
   })
 }
 
-function stopAnswerOutput(reply: ReplyView): string {
-  return JSON.stringify({ decision: 'block', reason: answerContext(reply) })
+function stopAnswerOutput(replies: ReplyView[], hadChoices: boolean): string {
+  return JSON.stringify({ decision: 'block', reason: answerContext(replies, hadChoices) })
 }
 
 /**
@@ -1199,7 +1247,7 @@ export async function handleUserPromptSubmit(
       }
       await drainOrphanRetirements(ctx, ctx.env, ctx.now())
       notes.push(`late answer from ${late.reply.device_name}: ${late.reply.text}`)
-      return { stdout: userPromptAnswerOutput(late.reply), notes }
+      return { stdout: userPromptAnswerOutput(late.replies, pendingHasChoices(pending)), notes }
     }
     if (late.failed || late.degraded) {
       notes.push('could not check the pending question for a late answer before the prompt')
@@ -1279,7 +1327,7 @@ export async function handleStop(ctx: HookContext, envelope: HookEnvelope): Prom
     if (late.reply !== null) {
       await finishPendingAnswer(ctx, envelope, sessionId, pending, late.reply, true)
       notes.push(`late answer from ${late.reply.device_name}: ${late.reply.text}`)
-      return { stdout: stopAnswerOutput(late.reply), notes }
+      return { stdout: stopAnswerOutput(late.replies, pendingHasChoices(pending)), notes }
     }
     // Already live on the user's devices from an earlier Stop; asking twice for
     // one question is the nagging failure this feature exists to avoid.
@@ -1352,13 +1400,20 @@ async function escalate(
     notes.push('no idle signal on this machine; asking now rather than holding the terminal')
   }
 
+  const questions = pendingQuestions(pending)
   const asked = await askAndWait(ctx, {
     title:
       ctx.config.project.value === null
         ? 'Question'
         : `Question · ${ctx.config.project.value}`,
-    body: pending.question,
-    ...(pending.choices !== undefined ? { choices: pending.choices } : {}),
+    // A set is answered on the expanded card; the banner leads with the first
+    // question and says how much more is waiting behind it.
+    body:
+      questions.length > 1
+        ? `${questions[0]!.text} (+${questions.length - 1} more)`
+        : pending.question,
+    questions,
+    ...(pending.detail !== undefined ? { detail: pending.detail } : {}),
     event: 'agent_question',
     session: sessionLabel(ctx, envelope),
     // Outlives the block, and stays open on purpose: the answer is still
@@ -1426,7 +1481,7 @@ async function escalate(
   }, asked.reply, true)
   notes.push(`answer from ${asked.reply.device_name}: ${asked.reply.text}`)
   return {
-    stdout: stopAnswerOutput(asked.reply),
+    stdout: stopAnswerOutput(asked.replies, pendingHasChoices(pending)),
     notes,
   }
 }

package/src/install-hooks.test.ts

@@ -44,28 +44,21 @@ function ours(): HookConfig {
 }
 
 describe('choice labels', () => {
-  it('splits a single value on commas for the one-liner case', () => {
-    expect(parseChoices('Staging,Production')).toEqual([
-      { id: 'staging', label: 'Staging' },
-      { id: 'production', label: 'Production' },
-    ])
-  })
-
-  it('keeps commas inside a label when the flag is repeated', () => {
-    // Observed live 2026-08-02: "Yes, it worked,No, something broke" passed as
-    // one value silently became four choices, and 2-6 validation let it
-    // through because four is in range. Repeating the flag is the escape.
+  it('treats a comma as an ordinary character, never a delimiter', () => {
+    // Observed live 2026-08-02 under the old comma-split grammar:
+    // "Yes, it worked,No, something broke" passed as one value silently
+    // became four choices. The delimiter form is gone; one flag, one answer.
     expect(parseChoices(['Yes, it worked', 'No, something broke'])).toEqual([
       { id: 'yes-it-worked', label: 'Yes, it worked' },
       { id: 'no-something-broke', label: 'No, something broke' },
     ])
-    expect(parseChoices('Yes, it worked,No, something broke')).toHaveLength(4)
+    expect(parseChoices(['Staging,Production', 'Neither'])).toEqual([
+      { id: 'staging-production', label: 'Staging,Production' },
+      { id: 'neither', label: 'Neither' },
+    ])
   })
 
   it('rejects a set that cannot become a valid closed question', () => {
-    // A pipe-separated string is one label, not two — the shape that reached
-    // the hook and failed there instead of at registration.
-    expect(parseChoices('Yes|No')).toBe('invalid')
     expect(parseChoices(['Only one'])).toBe('invalid')
     expect(parseChoices(['A', 'a'])).toBe('invalid')
     expect(parseChoices(['1', '2', '3', '4', '5', '6', '7'])).toBe('invalid')

package/src/main.ts

@@ -195,9 +195,10 @@ const send = program
   .option('--reply-window <seconds>', 'how long the server accepts a reply (default: 3600)', (v: string) => Number(v))
   .option(
     '--reply-choice <label>',
-    'with --reply, ask a closed question (2-6 answers); one value splits on commas, or repeat the flag',
+    'with --reply, ask a closed question; repeat the flag once per answer (2-6)',
     (v: string, all: string[]) => [...all, v], [],
   )
+  .option('--reply-multi', 'with --reply-choice, several answers may be selected')
   // Kept registered, and always a usage error with --reply, so the caller gets
   // a message pointing at `ask` instead of "unknown option".
   .option('--no-block', 'rejected with --reply; use `notifai ask` to ask and end the turn')
@@ -264,19 +265,55 @@ program
   })
 
 program
-  .command('ask <question>')
+  .command('ask [question]')
   .description('Register a question for the turn-end hook to route under your presence settings')
   .option(
     '--choice <label>',
-    'answers to offer instead of free text (2-6); one value splits on commas, or repeat the flag',
+    'answers to offer instead of free text; repeat the flag once per answer (2-6)',
     (v: string, all: string[]) => [...all, v], [],
   )
+  .option('--multi', 'with --choice, several answers may be selected')
+  .option('--detail <markdown>', 'long-form context shown only in the app, never on the banner')
+  .option('--detail-file <path>', 'read --detail from a file (use - for stdin)')
+  .option('--form <path>', 'ask several questions as one form; JSON file (use - for stdin)')
   .option('--session <id>', 'session id (default: the session working in this directory, else $NOTIFAI_SESSION)')
-  .action((question: string, opts: { choice?: string[]; session?: string }) => {
+  .action((question: string | undefined, opts: {
+    choice?: string[]
+    multi?: boolean
+    detail?: string
+    detailFile?: string
+    form?: string
+    session?: string
+  }) => {
+    let detail = opts.detail
+    if (typeof opts.detailFile === 'string') {
+      if (detail !== undefined) {
+        deps.io.err('Pass either --detail or --detail-file, not both.')
+        process.exit(2)
+      }
+      try {
+        detail = readFileSync(opts.detailFile === '-' ? 0 : opts.detailFile, 'utf8')
+      } catch (err) {
+        deps.io.err(`Could not read ${opts.detailFile}: ${String(err)}`)
+        process.exit(2)
+      }
+    }
+    let form: string | undefined
+    if (typeof opts.form === 'string') {
+      try {
+        form = readFileSync(opts.form === '-' ? 0 : opts.form, 'utf8')
+      } catch (err) {
+        deps.io.err(`Could not read ${opts.form}: ${String(err)}`)
+        process.exit(2)
+      }
+    }
     // commander's collector defaults to []; an empty list means "not asked".
     const flags: Parameters<typeof askCommand>[2] = {
       ...(opts.session !== undefined ? { session: opts.session } : {}),
       ...(opts.choice?.length ? { choice: opts.choice } : {}),
+      ...(opts.multi ? { multi: true } : {}),
+      ...(detail !== undefined ? { detail } : {}),
+      ...(form !== undefined ? { form } : {}),
     }
     process.exit(askCommand(deps, question, flags))
   })

package/src/send.ts

@@ -3,6 +3,7 @@ import {
   COLLAPSE_KEY_MAX_BYTES,
   INTERRUPTION_LEVELS,
   NOTIFICATION_SCHEMA_VERSION,
+  QUESTION_TEXT_MAX_LENGTH,
   type IosOptionsT,
   type LifecycleT,
   type MacosOptionsT,
@@ -10,6 +11,7 @@ import {
   NOTIFICATION_KINDS,
   PLATFORMS,
   type Platform,
+  type QuestionT,
   type SubmissionReceipt,
 } from '@raidiant/notifai-protocol'
 import type { CliConfig } from './config.js'
@@ -41,10 +43,17 @@ export interface SendFlags {
   /** How long the server accepts a reply after submission. */
   replyWindow?: number
   /**
-   * Answer labels; turns the reply into a closed question. One value splits on
-   * commas; repeating the flag passes each label through verbatim.
+   * Answer labels; turns the reply into a closed question. One flag occurrence
+   * per label, always — a label is a label, whatever characters it contains.
    */
-  replyChoice?: string | string[]
+  replyChoice?: string[]
+  /** The user may select several of the offered answers. */
+  replyMulti?: boolean
+  /**
+   * A full question set, overriding the single question the flags describe.
+   * Not a user-facing flag: `ask --form` and the hooks build it.
+   */
+  questions?: QuestionT[]
   /** Platform whose optional notification fields these flags configure. */
   platform?: string
   /**
@@ -149,6 +158,24 @@ export function buildDraft(config: CliConfig, flags: SendFlags): DraftBuild {
       error: CHOICE_USAGE,
     }
   }
+  if (flags.replyMulti && choices === null && flags.questions === undefined) {
+    return { ok: false, error: '--reply-multi needs answers to select between; add --reply-choice.' }
+  }
+  // The banner body doubles as the question text on a single-question send, so
+  // it inherits the question's readable-in-full bound; context beyond that
+  // belongs in --detail, which never rides the banner.
+  if (
+    flags.reply &&
+    flags.questions === undefined &&
+    flags.body.length > QUESTION_TEXT_MAX_LENGTH
+  ) {
+    return {
+      ok: false,
+      error:
+        `A question must be readable where it is answered: keep it within ${QUESTION_TEXT_MAX_LENGTH} ` +
+        'characters and put the longer context in --detail.',
+    }
+  }
 
   const draft: NotificationDraftT = {
     schema_version: NOTIFICATION_SCHEMA_VERSION,
@@ -174,7 +201,14 @@ export function buildDraft(config: CliConfig, flags: SendFlags): DraftBuild {
       ? {
           reply: {
             expires_in_seconds: flags.replyWindow ?? 3600,
-            ...(choices !== null ? { kind: 'choice' as const, choices } : {}),
+            questions: flags.questions ?? [
+              {
+                id: 'q1',
+                text: flags.body,
+                ...(choices !== null ? { choices } : {}),
+                ...(flags.replyMulti ? { multi: true } : {}),
+              },
+            ],
           },
         }
       : {}),
@@ -229,23 +263,19 @@ export function receiptExitCode(receipt: SubmissionReceipt): number {
 }
 
 /**
- * `"Staging,Production"` -> `[{id:'staging',label:'Staging'}, ...]`.
+ * One flag occurrence, one answer: `--choice Staging --choice Production` ->
+ * `[{id:'staging',label:'Staging'}, ...]`.
  *
- * A single occurrence splits on commas, which keeps the common one-liner
- * short. Repeating the flag is the escape hatch, and the only way to write a
- * label that itself contains a comma: passing `"Yes, ship it,No"` as one value
- * silently yields three choices, and nothing downstream can detect that the
- * agent meant two.
+ * Commas are ordinary characters. The old single-value comma split produced
+ * buttons the agent never intended ("Nothing, I'll review" became two answers)
+ * and nothing downstream could detect it, so the delimiter form is gone
+ * rather than guarded: a label is a label.
  */
 export function parseChoices(
-  value: string | string[] | undefined,
+  value: string[] | undefined,
 ): { id: string; label: string }[] | null | 'invalid' {
-  if (value === undefined) return null
-  const raw = Array.isArray(value) ? value : [value]
-  if (raw.length === 0) return null
-  const labels = (raw.length === 1 ? (raw[0] ?? '').split(',') : raw)
-    .map((part) => part.trim())
-    .filter((part) => part.length > 0)
+  if (value === undefined || value.length === 0) return null
+  const labels = value.map((part) => part.trim()).filter((part) => part.length > 0)
   if (labels.length < 2 || labels.length > 6) return 'invalid'
   const choices = labels.map((label) => ({ id: slugify(label), label }))
   if (choices.some((choice) => choice.id === '')) return 'invalid'
@@ -255,38 +285,10 @@ export function parseChoices(
 
 /** Message shared by every surface that accepts choice labels. */
 export const CHOICE_USAGE =
-  'Choices must be 2-6 non-empty labels, unique once slugified. One value splits on ' +
-  'commas ("Staging,Production"); repeat the flag when a label contains a comma.'
-
-/**
- * Catches the split that looked like it worked.
- *
- * `--choice "macOS parity,Long-form detail,Nothing, I'll review"` produced four
- * buttons rather than three, because the third label contained a comma. Nothing
- * downstream can detect it — the labels are all well-formed — and the CLI
- * cheerfully echoed the wrong list back, so the user saw buttons the agent
- * never intended.
- *
- * The tell is a comma followed by a space. A delimiter list is written
- * "Yes,No"; prose is written "Nothing, I'll review". That is a heuristic and it
- * will occasionally be wrong, which is exactly why this warns and names the
- * escape hatch rather than rejecting: the split may well have been intended.
- */
-export function ambiguousChoiceSplit(value: string | string[] | undefined): string | null {
-  if (value === undefined || Array.isArray(value)) return null
-  if (!/,\s/.test(value)) return null
-  const parts = value
-    .split(',')
-    .map((part) => part.trim())
-    .filter((part) => part.length > 0)
-  return (
-    `Heads up: "${value}" was split on commas into ${parts.length} answers ` +
-    `(${parts.join(' / ')}). If one of those labels was meant to contain a comma, ` +
-    'pass --choice once per answer instead.'
-  )
-}
+  'Offer 2-6 answers, one --choice flag per answer, unique once slugified — ' +
+  'e.g. --choice "Yes, ship it" --choice "Not yet".'
 
-function slugify(label: string): string {
+export function slugify(label: string): string {
   return label
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')