feat: add interactive ask-user extension

pi-ask-user/README.md

@@ -0,0 +1,60 @@
+# pi-ask-user
+
+A locally maintained Pi extension that consolidates the upstream `question.ts` and `questionnaire.ts` examples into one model-initiated tool. It intentionally does not include the `/qna` command.
+
+## Tool
+
+The extension registers `ask_user_question`. The model can present one to eight questions in one sequential TUI interaction:
+
+- `select`: one to eight stable `{ value, label, description? }` choices, with an optional free-form choice;
+- `text`: a free-form Editor answer;
+- `required: false`: lets the user explicitly skip the question;
+- multiple questions: progress tabs plus a final review page.
+
+The model should call the tool only when a missing decision, preference, or clarification is needed to continue. It should not repeat questions already answered in the user's direct messages.
+
+## Controls
+
+- `↑` / `↓`: move through choices;
+- `Enter`: select, edit, or submit;
+- `Tab`, `Shift+Tab`, `←`, `→`: move between questions and review;
+- `Esc`: leave text entry, or cancel from a question/review page.
+
+The outer component propagates focus to the embedded Editor for IME cursor positioning.
+
+## Result contract
+
+Successful results include readable text and structured `details`:
+
+```json
+{
+  "version": 1,
+  "cancelled": false,
+  "questions": [],
+  "answers": [
+    {
+      "id": "language",
+      "question": "Which language should be used?",
+      "type": "select",
+      "answer": "TypeScript",
+      "value": "typescript",
+      "label": "TypeScript",
+      "custom": false,
+      "skipped": false
+    }
+  ]
+}
+```
+
+The tool name and the `question` / `answer` fields intentionally match `pi-permission-auto-review`'s trusted structured user-interaction envelope. Cancelled results are never treated as authorization evidence.
+
+The tool requires Pi's interactive TUI mode. RPC, JSON, and print modes receive a tool error rather than an invented answer.
+
+## Development
+
+```sh
+npm test
+npm run check
+```
+
+See `UPSTREAM.md` for the imported reference snapshot and local differences.