open-question

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { AskedQuestion, OpenQuestion } from '../types'
5
6const PANE = 'open-question'
7const PIN_TOOL = 'mcp__open-question__pin_question'
8const UNPIN_TOOL = 'mcp__open-question__unpin_question'
9const MAX_QUESTION_LENGTH = 100
10const MAX_OPEN_QUESTIONS = 1
11const MAX_HISTORY = 100
12const ELLIPSIS = '…'
13const PREFIX = '❓ '
14const PREFIX_CELLS = 3
15const GAP = '   '
16const FRAME_CELLS = 4
17const FRAME_TITLE = 'En attente de ta réponse'
18const DETAILS_LABEL = 'détails'
19const REMOVE_LABEL = 'x'
20const ANSWER_LABEL = 'répondre'
21const MIN_OPTIONS = 2
22const MAX_OPTIONS = 4
23const MAX_OPTION_LENGTH = 30
24
25const RULE_SECTION = {
26  id: 'open-question:rule',
27  text: "While the open-question mod is loaded, a question still awaiting the user's answer when a subagent report comes in is pinned with `pin_question` instead of being asked again. Ask questions in your message first; never pin a question as you ask it. One pinned at a time: if two questions await when the report comes in, pin the first and ask the second again in full. An answer through the bar arrives as `Réponse à « … » :` and unpins by itself; call `unpin_question` only when an answer typed directly settles the question.",
28  scope: 'session',
29} as const
30
31const questions = atom({ plugin: 'open-question', key: 'questions' } as const, [])
32const nextId = atom({ plugin: 'open-question', key: 'nextId' } as const, 1)
33const shownId = atom({ plugin: 'open-question', key: 'shownId' } as const, null)
34const asked = atom({ plugin: 'open-question', key: 'asked' } as const, [])
35
36/**
37 * Cells the terminal takes to draw a Button labelled `label`: `[ label ]`.
38 *
39 * @param label the Button's label
40 * @returns its width in cells
41 */
42const buttonCells = (label: string): number => label.length + 4
43
44/**
45 * Cuts `text` to at most `cells` characters, ending it with an ellipsis when cut.
46 *
47 * @param text the question to fit
48 * @param cells the room left on the line, in cells; below 1, the ellipsis alone
49 * @returns `text` whole when it fits, else its head and `…`
50 */
51const fitToCells = (text: string, cells: number): string => {
52  if (text.length <= cells) {
53    return text
54  }
55
56  return text.slice(0, Math.max(0, cells - 1)).trimEnd() + ELLIPSIS
57}
58
59/**
60 * Checks a `pin_question` input against the rules the model is held to.
61 *
62 * @param question the question as the model sent it
63 * @param openCount how many questions are pinned already
64 * @returns the refusal the model reads, or undefined when the input is accepted
65 */
66const refusePin = (question: unknown, openCount: number): string | undefined => {
67  if (typeof question !== 'string' || question.trim() === '') {
68    return 'pin_question: `question` must be a non-empty string.'
69  }
70  if (/[\r\n]/.test(question)) {
71    return 'pin_question: `question` must fit on one line. Rephrase it as one short line and put the detail in `context`.'
72  }
73  if (question.length > MAX_QUESTION_LENGTH) {
74    return `pin_question: \`question\` is ${question.length} characters, the limit is ${MAX_QUESTION_LENGTH}. Rephrase it shorter and put the detail in \`context\`.`
75  }
76  if (openCount >= MAX_OPEN_QUESTIONS) {
77    return 'pin_question: A question is already pinned: ask this one in your message, or unpin the open one first.'
78  }
79
80  return undefined
81}
82
83/**
84 * Checks the `options` of a `pin_question` input.
85 *
86 * @param options the options as the model sent them; undefined for an open question
87 * @returns the refusal the model reads, or undefined when they are accepted
88 */
89const refuseOptions = (options: unknown): string | undefined => {
90  if (options === undefined) {
91    return undefined
92  }
93  if (!Array.isArray(options) || options.length < MIN_OPTIONS || options.length > MAX_OPTIONS) {
94    return `pin_question: \`options\` takes ${MIN_OPTIONS} to ${MAX_OPTIONS} choices. Rephrase the question, or put the detail in \`context\`.`
95  }
96  for (const option of options) {
97    if (typeof option !== 'string' || option.trim() === '') {
98      return 'pin_question: each option must be a non-empty string.'
99    }
100    if (/[\r\n]/.test(option) || option.length > MAX_OPTION_LENGTH) {
101      return `pin_question: each option fits on one line, at most ${MAX_OPTION_LENGTH} characters; ${JSON.stringify(option)} does not. Rephrase it shorter, or put the detail in \`context\`.`
102    }
103  }
104
105  return undefined
106}
107
108/**
109 * The words that open the user's answer to a question, up to the colon.
110 *
111 * @param question the question as pinned
112 * @returns `Réponse à « <question> » :`
113 */
114const answerTag = (question: string): string => `Réponse à « ${question} » :`
115
116/**
117 * Removes from a draft the answer opening of any question pinned this session,
118 * and the option it carried, so a press relabels the draft instead of stacking.
119 *
120 * The longest matching tag wins, then the longest matching option.
121 *
122 * @param draft the prompt box's text
123 * @param history every question pinned this session
124 * @returns what the person typed beside the answer opening
125 */
126const stripAnswer = (draft: string, history: readonly AskedQuestion[]): string => {
127  const matching = history.filter(one => draft.startsWith(answerTag(one.question)))
128  if (matching.length === 0) {
129    return draft
130  }
131
132  const question = matching.reduce((longest, one) => (one.question.length > longest.length ? one.question : longest), '')
133  const rest = draft.slice(answerTag(question).length).trimStart()
134  const option = matching
135    .filter(one => one.question === question)
136    .flatMap(one => one.options ?? [])
137    .filter(choice => rest === choice || rest.startsWith(`${choice} `))
138    .reduce((longest, choice) => (choice.length > longest.length ? choice : longest), '')
139
140  return rest.slice(option.length).trimStart()
141}
142
143/**
144 * Puts the answer to `one` in the prompt box, the draft already typed kept after it.
145 *
146 * @param $ the engine interface of the pressing hook
147 * @param one the question answered
148 * @param option the option pressed; undefined for a free answer
149 */
150const fillAnswer = async ($: EngineInterface, one: OpenQuestion, option?: string): Promise<void> => {
151  const draft = stripAnswer((await $.prompt.read()).text, await read($, asked))
152  const head = option === undefined ? `${answerTag(one.question)} ` : `${answerTag(one.question)} ${option}`
153  const separator = option === undefined || draft === '' ? '' : ' '
154  await $.prompt.fill({ text: head + separator + draft, mode: 'replace' })
155}
156
157/**
158 * Removes a pinned question, and closes the details pane when it shows that one.
159 *
160 * @param $ the engine interface of the calling hook
161 * @param id the question's id
162 * @returns true when a question was removed, false when no pinned question has that id
163 */
164const removeQuestion = async ($: EngineInterface, id: string): Promise<boolean> => {
165  let isFound = false
166  await update($, questions, list => {
167    isFound = list.some(one => one.id === id)
168
169    return list.filter(one => one.id !== id)
170  })
171  if (isFound && (await read($, shownId)) === id) {
172    await update($, shownId, () => null)
173    await $.ui.close({ id: PANE })
174  }
175
176  return isFound
177}
178
179export const register: Register = on => {
180  on('session.start', async ($, e, next) => {
181    await $.tool.register({
182      name: 'pin_question',
183      description:
184        'Pins a question that awaits the user\'s answer above the prompt, so it stays visible while you keep working. Ask the question in your message first; pin it only when a subagent report has come in while it still awaits the answer, since that is what pushes it off screen. Pinning never blocks your work. `question`: one line, at most 100 characters. `context`: optional Markdown the user can open for details. `options`: 2 to 4 choices, one line and at most 30 characters each, for a multiple-choice question; leave it out for an open question. An answer given through the bar arrives as `Réponse à « <question> » : …` and unpins the question by itself. At most one pinned at once. Returns the question\'s id.',
185      inputSchema: {
186        type: 'object',
187        properties: {
188          question: { type: 'string', description: 'The question, one line, at most 100 characters.' },
189          context: { type: 'string', description: 'Optional Markdown context shown in a details pane.' },
190          options: {
191            type: 'array',
192            items: { type: 'string' },
193            minItems: MIN_OPTIONS,
194            maxItems: MAX_OPTIONS,
195            description: 'Optional choices for a multiple-choice question, one line and at most 30 characters each.',
196          },
197        },
198        required: ['question'],
199      },
200      isDeferred: false,
201    })
202    await $.tool.register({
203      name: 'unpin_question',
204      description:
205        'Removes a pinned question by its id. Call it when an answer typed directly (not through the bar) settles the question; an answer through the bar has already unpinned it; an answer that misses the question leaves it pinned.',
206      inputSchema: {
207        type: 'object',
208        properties: {
209          id: { type: 'string', description: 'The id pin_question returned.' },
210        },
211        required: ['id'],
212      },
213      isDeferred: false,
214    })
215
216    return next(e)
217  })
218
219  on('prompt.compose', async ($, e, next) => {
220    const composed = await next(e)
221    if (!e.tools.includes(PIN_TOOL)) {
222      return composed
223    }
224
225    return { sections: [...composed.sections, RULE_SECTION] }
226  })
227
228  on('session.end', async ($, e, next) => {
229    await update($, questions, () => [])
230    await update($, shownId, () => null)
231    await update($, asked, () => [])
232    await $.ui.close({ id: PANE })
233
234    return next(e)
235  })
236
237  on('tool.call', { tool: PIN_TOOL }, async ($, e) => {
238    const raw = e as unknown as { question?: unknown; context?: unknown; options?: unknown }
239    const trim = (value: unknown): unknown => (typeof value === 'string' ? value.trim() : value)
240    const input = {
241      question: trim(raw.question),
242      context: raw.context,
243      options: Array.isArray(raw.options) ? raw.options.map(trim) : raw.options,
244    }
245    const refusal = refusePin(input.question, (await read($, questions)).length) ?? refuseOptions(input.options)
246    if (refusal !== undefined) {
247      return { deny: refusal }
248    }
249    if (input.context !== undefined && typeof input.context !== 'string') {
250      return { deny: 'pin_question: `context` must be a string of Markdown.' }
251    }
252
253    let id = ''
254    await update($, nextId, n => {
255      id = `q${n}`
256
257      return n + 1
258    })
259    const pinned: OpenQuestion = { id, question: String(input.question) }
260    if (typeof input.context === 'string' && input.context.trim() !== '') {
261      pinned.context = input.context
262    }
263    if (Array.isArray(input.options)) {
264      pinned.options = input.options.map(String)
265    }
266    let isFull = false
267    await update($, questions, list => {
268      isFull = list.length >= MAX_OPEN_QUESTIONS
269
270      return isFull ? list : [...list, pinned]
271    })
272    if (isFull) {
273      return { deny: refusePin(pinned.question, MAX_OPEN_QUESTIONS) ?? 'pin_question: refused.' }
274    }
275    const record: AskedQuestion = pinned.options ? { question: pinned.question, options: pinned.options } : { question: pinned.question }
276    await update($, asked, history => [...history, record].slice(-MAX_HISTORY))
277
278    return { result: id }
279  }).catch(() => ({ deny: 'pin_question: the question could not be pinned.' }))
280
281  on('tool.call', { tool: UNPIN_TOOL }, async ($, e) => {
282    const { id } = e as unknown as { id?: unknown }
283    if (typeof id !== 'string' || !(await removeQuestion($, id))) {
284      return { deny: `unpin_question: no pinned question has the id ${JSON.stringify(id)}.` }
285    }
286
287    return { result: `Unpinned ${id}.` }
288  }).catch(() => ({ deny: 'unpin_question: the question could not be unpinned.' }))
289
290  on('prompt.submit', async ($, e, next) => {
291    const sent = await next(e)
292    if (sent.drop !== undefined) {
293      return sent
294    }
295    const answered = (await read($, questions)).find(one => e.text.startsWith(answerTag(one.question)))
296    if (answered !== undefined) {
297      await removeQuestion($, answered.id)
298    }
299
300    return sent
301  }).catch(($, e, next) => next(e))
302
303  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
304    const list = await read($, questions)
305    if (e.props.hasSurvey || list.length === 0) {
306      return next(e)
307    }
308
309    const { Box, Button, Text } = $.ui.resolve(e)
310    const columns = e.props.bodyColumns - FRAME_CELLS
311
312    return (
313      <Box key="frame" flexDirection="column" borderStyle="round" borderColor="claude" paddingX={1}>
314        <Text bold color="claude">
315          {FRAME_TITLE}
316        </Text>
317        {list.map(one => {
318          const buttons = (one.context ? buttonCells(DETAILS_LABEL) + 1 : 0) + buttonCells(REMOVE_LABEL)
319          const room = columns - PREFIX_CELLS - GAP.length - buttons
320
321          return (
322            <Box key={`question:${one.id}`} flexDirection="column">
323              <Box key={`row:${one.id}`} flexDirection="row">
324                <Text wrap="truncate-end">
325                  {PREFIX}
326                  {fitToCells(one.question, room)}
327                  {GAP}
328                </Text>
329                {one.context && (
330                  <Button
331                    key={`details:${one.id}`}
332                    label={DETAILS_LABEL}
333                    onPress={async () => {
334                      await update($, shownId, () => one.id)
335                      await $.ui.open({ id: PANE, title: one.question })
336                    }}
337                  />
338                )}
339                {one.context && <Text> </Text>}
340                <Button
341                  key={`remove:${one.id}`}
342                  label={REMOVE_LABEL}
343                  onPress={async () => {
344                    await removeQuestion($, one.id)
345                  }}
346                />
347              </Box>
348              <Box
349                key={`answers:${one.id}`}
350                flexDirection="row"
351                flexWrap="wrap"
352                columnGap={1}
353                marginLeft={PREFIX_CELLS}
354              >
355                {(one.options ?? []).map((option, index) => (
356                  <Button key={`option:${one.id}:${index}`} label={option} onPress={() => fillAnswer($, one, option)} />
357                ))}
358                <Button key={`answer:${one.id}`} label={ANSWER_LABEL} onPress={() => fillAnswer($, one)} />
359              </Box>
360            </Box>
361          )
362        })}
363      </Box>
364    )
365  })
366
367  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
368    const { Markdown, Text } = $.ui.resolve(e)
369    const id = await read($, shownId)
370    const shown = (await read($, questions)).find(one => one.id === id)
371
372    if (shown?.context === undefined) {
373      return <Text dimColor>No question to show.</Text>
374    }
375
376    return <Markdown key="context" text={shown.context} />
377  })
378}
379

1/** One question pinned above the prompt, awaiting the user's answer. */
2export type OpenQuestion = {
3  /** Stable handle the model passes to `unpin_question`. */
4  id: string
5  /** One line, at most 100 characters. */
6  question: string
7  /** Markdown shown in the details pane; absent when none was given. */
8  context?: string
9  /** 2 to 4 one-line choices, at most 30 characters each; absent for an open question. */
10  options?: string[]
11}
12
13/** A question pinned earlier in the session, kept to recognise its answer tag in a draft. */
14export type AskedQuestion = Pick<OpenQuestion, 'question' | 'options'>
15
16declare module 'claude-code' {
17  interface PluginState {
18    'open-question': {
19      questions: OpenQuestion[]
20      nextId: number
21      shownId: string | null
22      asked: AskedQuestion[]
23    }
24  }
25}
26