First version

docs/features/questions.md

@@ -0,0 +1,47 @@
+# Questions
+
+**Status:** Implemented · **Code:** `Scripts/permissions.js` (`_askQuestions`,
+`_askOne`, `_askMultiple`)
+
+When Claude needs a decision it calls `AskUserQuestion`, which arrives as a
+`can_use_tool` request with `requires_user_interaction: true`.
+
+## Input
+
+```jsonc
+{"questions":[{
+  "question":"Do you prefer tabs or spaces?",
+  "header":"Indentation",
+  "multiSelect":false,
+  "options":[{"label":"Tabs","description":"…"},{"label":"Spaces","description":"…"}]
+}]}
+```
+
+## Answering
+
+The host **rewrites the tool input**; there is no separate answer channel:
+
+```jsonc
+{"behavior":"allow",
+ "updatedInput":{…input, "answers":{"<question text>":"<chosen label>"}}}
+```
+
+Keyed by the question's exact text. The CLI feeds it to the tool, which reports
+back *"Your questions have been answered: …"*. Verified end to end: answering
+`"Tabs"` produced a model reply of "You chose **Tabs**."
+
+Multi-select answers are joined with `, `.
+
+## Presentation
+
+Each question becomes a `showChoicePalette` with `label — description` rows,
+asked in sequence.
+
+- **Single select** appends `Other…`, which opens an input panel for free text.
+- **Multi select** toggles rows with a `✓` marker and appends
+  `Done — N selected`; with nothing selected that row is `Other…` instead.
+- Dismissing a palette resolves `deny` with "The user dismissed the question
+  without answering" — matching Claude Code's own Escape behaviour.
+
+Unit-covered: multi-select, free text, dismissal, and several questions in
+sequence.