@tduyng/pi-ask 0.0.2 → 0.0.3

package/README.md

@@ -1,33 +1,37 @@
 # @tduyng/pi-ask
 
-Ask the user a question in the terminal and wait for the answer. One `ask_user` tool.
+One tool that stops and waits. The model asks up to four questions, you answer with a keystroke, and the turn carries on instead of guessing.
 
-pi core ships no question tool. Claude Code has `AskUserQuestion`, opencode ships its own, pi has none, so a model facing a fork it cannot resolve falls back to asking in prose: a turn spent, a block that renders badly, and a question that reads as a guess.
+## What it costs
+
+`ask_user` is 202 tokens a request, and it is the only thing this package adds. No system prompt block, no statusline, no background work.
+
+The saving is the turns it removes. A model facing a fork it cannot resolve writes a paragraph of options, waits for you to answer, then re-reads that paragraph every turn after. One question in a dialog costs one exchange and leaves one short `Q:` and `A:` block in the transcript.
 
 ## The tool
 
 `ask_user` takes `questions`, an array of at most four. Each question carries:
 
-| Field      | Meaning                                                     |
-| ---------- | ----------------------------------------------------------- |
-| `question` | The question to ask                                         |
-| `guess`    | Your best guess, one line of reasoning, shown in the dialog |
-| `options`  | Predefined choices, single select, plus a free-text escape  |
+| Field | Meaning |
+| --- | --- |
+| `question` | The question to ask |
+| `guess` | Your best guess, one line of reasoning, shown in the dialog |
+| `options` | Predefined choices, single select, plus a free-text escape |
 
-```
+```text
 ask_user(questions: [
   { question: "Which Windows surface first?", guess: "WSL gwt plus Windows Terminal",
     options: ["WSL first", "native gwt.exe first", "both"] }
 ])
 ```
 
-The dialog shows the guess under the question, so a wrong guess is corrected in one keystroke. The call blocks until every question is answered or cancelled.
+The guess sits under the question, so a wrong guess is corrected in one keystroke. The call blocks until every question is answered or cancelled.
 
-## Result
+## What lands in the transcript
 
 One `Q:` and `A:` block per question:
 
-```
+```text
 Q: Which Windows surface first?
 A: WSL first
 ```
@@ -38,13 +42,19 @@ A cancelled dialog records `(skipped)`, so the transcript shows a question that
 
 Headless, RPC, print, and subagent runs have nobody to answer. The tool says so once and tells the model to proceed on each question's stated guess and record it as an assumption.
 
+That is why `guess` is worth writing even when you are at the keyboard: it is the fallback the model acts on when the dialog cannot open.
+
+## Why not just ask in prose
+
+pi core ships no question tool. Claude Code has `AskUserQuestion`, opencode ships its own, pi has none, so a model facing a fork falls back to a paragraph: a turn spent, a block that renders badly, and a question that reads as a guess rather than a choice.
+
 ## Install
 
 ```bash
 pi install npm:@tduyng/pi-ask
 ```
 
-Local checkout: `pi install /path/to/extensions/pi-ask`
+Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-ask`
 
 ## Tests
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tduyng/pi-ask",
-  "version": "0.0.2",
-  "description": "One tool that stops and waits: ask the user up to 4 questions with options and a stated guess, answered in the terminal.",
+  "version": "0.0.3",
+  "description": "Ask the user up to 4 questions and wait for the answer. One tool, 202 tokens a request.",
   "keywords": [
     "pi",
     "pi-package",