@tduyng/pi-ask 0.0.2 → 0.0.4

package/README.md

@@ -1,42 +1,33 @@
 # @tduyng/pi-ask
 
-Ask the user a question in the terminal and wait for the answer. One `ask_user` tool.
+`ask_user` puts a decision in front of a person: up to four questions, each with options and an optional stated guess, answered in a dialog and returned as a tool result in the same turn.
 
-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.
+A model that hits a decision only a person can settle does one of two things. It guesses and writes the guess in prose, where it reads like a decision. Or it stops and asks in prose, which costs a request and usually gets "go ahead" because the question arrived without the options.
 
-## The tool
+## The guess field
 
-`ask_user` takes `questions`, an array of at most four. Each question carries:
+`guess` takes one line of reasoning, so the model has to commit before it asks. That field does two jobs:
 
-| 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  |
+- The dialog highlights that answer, which makes the common case one keystroke.
+- With no UI attached, such as in a subagent, a script or `pi -p`, the tool returns a plain message: proceed on each guess and record it as an assumption. The turn never waits for a person who is not there.
 
-```
-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.
+## Asking
 
-## Result
+One tool, up to four questions, each with `question`, optional `options` and optional `guess`.
 
-One `Q:` and `A:` block per question:
-
-```
-Q: Which Windows surface first?
-A: WSL first
+```text
+ask_user({questions: [
+  {question: "Which auth path?", options: ["session cookie", "bearer token"], guess: "session cookie, since the rest of the app uses it"}
+]})
 ```
 
-A cancelled dialog records `(skipped)`, so the transcript shows a question that was asked and not answered rather than nothing at all.
+A question with `options` opens a select dialog with an extra "Other: type my answer" row. A question without options opens a text field.
 
-## Without a UI
+The transcript keeps two ways of not answering apart: `(cancelled)` for a dialog closed unanswered, `(skipped)` for a typed answer left blank.
 
-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.
+## When to use it
+
+When the answer changes the design and the model would need correcting anyway, or when a guess belongs on the record before code is written. Not for confirmation, and not for something the request already settled.
 
 ## Install
 
@@ -44,10 +35,12 @@ Headless, RPC, print, and subagent runs have nobody to answer. The tool says so
 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
+The schema costs 202 tokens a request. There are no hooks, no prompt text and no session entries.
 
-```bash
-bun test extensions/pi-ask
-```
+## Limits
+
+- Four questions per call. A fifth means the model should ask a narrower one.
+- Options are single select. Two questions model a multiple choice.
+- The dialog blocks the turn until it is answered or cancelled.

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.4",
+  "description": "Ask the user up to 4 questions and wait for the answer. One tool, 202 tokens a request.",
   "keywords": [
     "pi",
     "pi-package",