@tduyng/pi-ask 0.0.3 → 0.0.4

package/README.md

@@ -1,52 +1,33 @@
 # @tduyng/pi-ask
 
-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.
+`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.
 
-## What it costs
+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.
 
-`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 guess field
 
-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.
+`guess` takes one line of reasoning, so the model has to commit before it asks. That field does two jobs:
 
-## The tool
+- 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` takes `questions`, an array of at most four. Each question carries:
+## Asking
 
-| 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 |
+One tool, up to four questions, each with `question`, optional `options` and optional `guess`.
 
 ```text
-ask_user(questions: [
-  { question: "Which Windows surface first?", guess: "WSL gwt plus Windows Terminal",
-    options: ["WSL first", "native gwt.exe first", "both"] }
-])
+ask_user({questions: [
+  {question: "Which auth path?", options: ["session cookie", "bearer token"], guess: "session cookie, since the rest of the app uses it"}
+]})
 ```
 
-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.
+A question with `options` opens a select dialog with an extra "Other: type my answer" row. A question without options opens a text field.
 
-## What lands in the transcript
+The transcript keeps two ways of not answering apart: `(cancelled)` for a dialog closed unanswered, `(skipped)` for a typed answer left blank.
 
-One `Q:` and `A:` block per question:
+## When to use it
 
-```text
-Q: Which Windows surface first?
-A: WSL first
-```
-
-A cancelled dialog records `(skipped)`, so the transcript shows a question that was asked and not answered rather than nothing at all.
-
-## Without a UI
-
-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.
+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
 
@@ -56,8 +37,10 @@ pi install npm:@tduyng/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,6 +1,6 @@
 {
   "name": "@tduyng/pi-ask",
-  "version": "0.0.3",
+  "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",