{"_id":"@datspike/pi-ask-user","_rev":"2-508fb85a9be41ff1553162f7d04cffea","name":"@datspike/pi-ask-user","dist-tags":{"latest":"0.15.0"},"versions":{"0.7.0":{"name":"@datspike/pi-ask-user","version":"0.7.0","keywords":["pi-package","pi","pi-coding-agent","extension","ask","ask_user","interactive"],"author":{"name":"Enzo Lucchesi","email":"enzo@edl.sh"},"license":"MIT","_id":"@datspike/pi-ask-user@0.7.0","maintainers":[{"name":"datspike","email":"elesin38@gmail.com"}],"homepage":"https://github.com/datspike/pi-ask-user#readme","bugs":{"url":"https://github.com/datspike/pi-ask-user/issues"},"pi":{"skills":["./skills"],"extensions":["./index.ts"]},"dist":{"shasum":"3b3ca65469e03976da12d2682dda5210bff3a4a9","tarball":"https://registry.npmjs.org/@datspike/pi-ask-user/-/pi-ask-user-0.7.0.tgz","fileCount":12,"integrity":"sha512-Qj7ICbRb5hr8TBOo8ZMpqpXhK58BkkZoIo1qfQyMQjS39DbZpCwKA4IFosQLHmI7SEXBOjpmU4h01lfrWtu7Rg==","signatures":[{"sig":"MEQCIBp8OIyP4gTtsgOONVZl4mqVzuhC7IHCU4zDbERrXGpEAiAmL+oHTdeXVADiXs/sxSRPHGDJq4o+Wx40MsoTNN1C6A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":114996},"type":"module","gitHead":"d492e80b9f38b22ead4eea7ed02788e76476c228","scripts":{"check":"npm pack --dry-run"},"_npmUser":{"name":"datspike","email":"elesin38@gmail.com"},"repository":{"url":"git+https://github.com/datspike/pi-ask-user.git","type":"git"},"_npmVersion":"11.12.1","description":"Interactive ask_user tool for pi-coding-agent with wrapped selection UI, batch clarifications, and freeform input","directories":{},"_nodeVersion":"25.9.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"@sinclair/typebox":"*","@mariozechner/pi-tui":"*","@mariozechner/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-ask-user_0.7.0_1776609743357_0.3840919429969929","host":"s3://npm-registry-packages-npm-production"}},"0.15.0":{"pi":{"skills":["./skills"],"extensions":["./index.ts"]},"_id":"@datspike/pi-ask-user@0.15.0","bugs":{"url":"https://github.com/datspike/pi-ask-user/issues"},"dist":{"shasum":"5ab0aa4245fd9eb79b1ad49242228e0ca9a8de9f","tarball":"https://registry.npmjs.org/@datspike/pi-ask-user/-/pi-ask-user-0.15.0.tgz","fileCount":14,"integrity":"sha512-dBbHuhUWShtXaICwd0npqB+2JbgJWtsfMZx9ug58aWuU7X5m2HxzuAm6Z0QomugK4XhpGOPYEuFEKGaWRUBpNA==","signatures":[{"sig":"MEQCIDyuJfxWEGHj/ufB+4lazfSOmWO6QSZyYzSQBAM6cNSuAiAXqpfgAbQf8eER+EYxoevBr3R8bjq9aBciUak4w2BHBQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC+My7orgLQ5SPxupExYQiJ65cDacXDJNMLMfDXobJ5zgIgTxoWXR9fvvjyRGtZ144K0nKkVNyU0hVE3nEVTuPRdmE="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@datspike%2fpi-ask-user@0.15.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":153104},"name":"@datspike/pi-ask-user","type":"module","author":{"name":"Enzo Lucchesi","email":"enzo@edl.sh"},"gitHead":"526e71edac06b03fc7fa87af19480c1286cf1473","license":"MIT","scripts":{"test":"bun test","check":"bun test && npm pack --dry-run","pack:dry-run":"npm pack --dry-run"},"version":"0.15.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:223e953e-89cb-4dca-9007-03f9f960767a"}},"homepage":"https://github.com/datspike/pi-ask-user#readme","keywords":["pi-package","pi","pi-coding-agent","extension","ask","ask_user","interactive"],"repository":{"url":"git+https://github.com/datspike/pi-ask-user.git","type":"git"},"_npmVersion":"11.5.1","description":"Interactive ask_user tool for pi-coding-agent with wrapped selection UI, batch clarifications, and freeform input","directories":{},"maintainers":[{"name":"datspike","email":"elesin38@gmail.com"}],"_nodeVersion":"24.21.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"@sinclair/typebox":"*","@earendil-works/pi-tui":">=0.85.1","@earendil-works/pi-coding-agent":">=0.85.1"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-ask-user_0.15.0_1790438750039_0.9162351599235599"}}},"time":{"created":"2026-04-19T14:42:23.295Z","modified":"2026-09-26T16:05:50.516Z","0.7.0":"2026-04-19T14:42:23.552Z","0.15.0":"2026-09-26T16:05:50.130Z"},"bugs":{"url":"https://github.com/datspike/pi-ask-user/issues"},"author":{"name":"Enzo Lucchesi","email":"enzo@edl.sh"},"license":"MIT","homepage":"https://github.com/datspike/pi-ask-user#readme","keywords":["pi-package","pi","pi-coding-agent","extension","ask","ask_user","interactive"],"repository":{"url":"git+https://github.com/datspike/pi-ask-user.git","type":"git"},"description":"Interactive ask_user tool for pi-coding-agent with wrapped selection UI, batch clarifications, and freeform input","maintainers":[{"name":"datspike","email":"elesin38@gmail.com"}],"readme":"# pi-ask-user\n\nA Pi package that adds an interactive `ask_user` tool for collecting explicit user decisions during an agent run.\n\n> This repository is a heavily reworked fork of the original [`edlsh/pi-ask-user`](https://github.com/edlsh/pi-ask-user). It keeps the same tool name and core intent, but the `main` branch in this fork contains additional changes beyond upstream `v0.6.1`.\n\n## Preview\n\n![ask_user preview](./media/ask-user-demo.gif)\n\nHigh-quality video: [ask-user-demo.mp4](./media/ask-user-demo.mp4)\n\n## What changed in this fork after upstream `v0.6.1`\n\n- Batch clarification mode for collecting 2-7 related answers in a single `ask_user` call\n- Plain-text answer summaries in tool `content`, so agents can continue even in integrations that only surface tool text\n- Stronger freeform UX: direct typing in selectable prompts, safer backspace handling, and preserved batch drafts while moving between questions\n- Updated tool guidance and bundled skill guidance around one focused question per call or one related clarification batch\n- Internal refactor that split the runtime into core, overlay controller, overlay UI, and batch components for easier maintenance\n\n## Features\n\n- One focused decision gate in single-question mode\n- One related clarification packet in `mode: \"batch\"`\n- Single-select and multi-select option lists\n- Optional freeform responses\n- Optional comment capture for structured single-question answers\n- Wrapped option rows with titles and descriptions\n- Responsive split-pane details preview on wide terminals with single-column fallback on narrow terminals\n- Context display support\n- Overlay and inline display modes, selected per call or with `PI_ASK_USER_DISPLAY_MODE`\n- Hide and restore an active overlay with `f7` (configurable with `PI_ASK_USER_OVERLAY_TOGGLE_KEY`) without recreating its component state\n- Pi-TUI-aligned keybinding and editor behavior\n- Custom TUI rendering for tool calls and results\n- Graceful fallback when interactive custom UI is unavailable\n- Optional timeout for auto-dismiss in both overlay and fallback input modes\n- Structured `details` on all results for session state reconstruction\n- Bundled `ask-user` skill for mandatory decision-gating in high-stakes or ambiguous tasks\n\n## Bundled skill: `ask-user`\n\nThis package ships a skill at `skills/ask-user/SKILL.md` that nudges or mandates the agent to use `ask_user` when:\n\n- architectural trade-offs are high impact\n- requirements are ambiguous or conflicting\n- assumptions would materially change implementation\n\nThe skill follows a decision handshake flow:\n\n1. Gather evidence and summarize context\n2. Use single-question `ask_user` for one decision gate, or batch mode to ask several related clarification questions in one sweep when they are already known up front and can be answered in one pass\n3. Wait for explicit user choice\n4. Confirm the decision, then proceed\n\nThe bundled skill is self-contained in `skills/ask-user/SKILL.md`.\n\n## Install\n\n### This fork from npm\n\n```bash\npi install npm:@datspike/pi-ask-user@0.15.0\n```\n\n### This fork from git\n\n```bash\npi install git:github.com/datspike/pi-ask-user\n# or\npi install https://github.com/datspike/pi-ask-user\n```\n\n### Local checkout during development\n\n```bash\npi install /absolute/path/to/pi-ask-user\n```\n\n### Original upstream npm package\n\n```bash\npi install npm:pi-ask-user\n```\n\nUse the scoped package or the git/local install forms if you want the fork-only behavior documented in this repository. The unscoped `pi-ask-user` package remains the upstream release line.\n\n## Tool name\n\nThe registered tool name is:\n\n- `ask_user`\n\n## Parameters\n\n### Single-question mode\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `mode` | `\"single\"?` | omitted | Optional explicit single-question mode |\n| `question` | `string` | *required* | The question to ask the user |\n| `context` | `string?` | - | Relevant context summary shown before the question |\n| `options` | `{title: string, description?: string}[]?` | `[]` | Multiple-choice options exposed to the model |\n| `allowMultiple` | `boolean?` | `false` | Enable multi-select mode |\n| `allowComment` | `boolean?` | env / `false` | Expose a user-toggleable extra-context option and collect an optional comment; overrides `PI_ASK_USER_ALLOW_COMMENT` |\n| `displayMode` | `\"overlay\" \\| \"inline\"?` | env / `\"overlay\"` | UI presentation; overrides `PI_ASK_USER_DISPLAY_MODE` |\n| `singleSelectLayout` | `\"auto\" \\| \"list\"?` | env / `\"auto\"` | Use responsive preview panes or force a list; overrides `PI_ASK_USER_SINGLE_SELECT_LAYOUT` |\n| `contextExpanded` | `boolean?` | env / `false` | Initial state for oversized context; overrides `PI_ASK_USER_CONTEXT_EXPANDED` |\n| `overlayToggleKey` | `string?` | env / `\"f7\"` | Hide/restore shortcut; overrides `PI_ASK_USER_OVERLAY_TOGGLE_KEY`; use `off` to disable |\n| `commentToggleKey` | `string?` | env / `\"ctrl+g\"` | Comment toggle shortcut; overrides `PI_ASK_USER_COMMENT_TOGGLE_KEY` |\n| `timeout` | `number?` | - | Auto-dismiss after N ms; returns `cancelled: true` with `outcome: \"timeout\"` |\n\n### Batch clarification mode\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `mode` | `\"batch\"` | *required* | Enables a one-call clarification batch |\n| `title` | `string?` | - | Short title shown above the batch UI |\n| `context` | `string?` | - | Relevant context summary shown before the batch |\n| `questions` | `BatchQuestion[]` | *required* | Related clarification questions; must contain 2-7 questions |\n| `displayMode` | `\"overlay\" \\| \"inline\"?` | env / `\"overlay\"` | UI presentation; parameter overrides environment |\n| `overlayToggleKey` | `string?` | env / `\"f7\"` | Hide/restore shortcut in overlay mode |\n| `timeout` | `number?` | - | Auto-dismiss after N ms; returns `cancelled: true` with `outcome: \"timeout\"` |\n\n### Environment and keyboard behavior\n\nConfiguration precedence is per-call parameter, matching environment variable, then built-in default. Supported variables are `PI_ASK_USER_DISPLAY_MODE`, `PI_ASK_USER_SINGLE_SELECT_LAYOUT`, `PI_ASK_USER_CONTEXT_EXPANDED`, `PI_ASK_USER_ALLOW_COMMENT`, `PI_ASK_USER_OVERLAY_TOGGLE_KEY`, `PI_ASK_USER_COMMENT_TOGGLE_KEY`, and `PI_ASK_USER_EMIT_FULL_EVENTS`. Boolean values accept `1/true/yes/on` and `0/false/no/off`. Shortcut values accept `off`, `none`, `disabled`, `false`, or an empty string to disable the shortcut.\n\nUse `ctrl+j` / `ctrl+k` as down/up aliases. Searchable single-select uses printable input as a fuzzy filter; Backspace removes filter characters and Escape clears the filter. Oversized context starts from `contextExpanded`, then can be expanded and collapsed with the first free key among `ctrl+e`, `ctrl+x`, and `ctrl+y`. This avoids configured overlay/comment shortcuts. If overlay and comment shortcuts are identical, overlay hide/restore takes priority and comment remains available through its selectable row. In overlay mode the help includes the hide shortcut; hiding also emits a notification with the restore key.\n\n`herdr:blocked` emits `{ active: true, label: \"Waiting for user response\" }` while interactive input is pending and `{ active: false }` on every exit path. `ask:answered` and `ask:cancelled` are privacy-minimal by default: they omit context, option lists, question packets, and answer text. Set `PI_ASK_USER_EMIT_FULL_EVENTS=true` only when trusted consumers require full payloads.\n\n`BatchQuestion` reuses the current ask vocabulary where possible:\n\n```ts\ninterface BatchQuestion {\n  id: string;\n  question: string;\n  options?: { title: string; description?: string }[];\n  allowMultiple?: boolean;\n  required?: boolean;\n}\n```\n\nFor runtime compatibility, legacy string options and defensive object aliases (`label`, `text`, `value`, `name`, `option`) are normalized before schema validation. New model-generated calls should use the flat `{ \"title\": \"...\", \"description\": \"...\" }` shape shown above.\n\nBatch-mode notes:\n- Use it only for one related clarification pass, not unrelated questions, branching interviews, or a single go/no-go decision.\n- If you already know you need several related clarifications, prefer one batch instead of repeated single-question pauses.\n- Keep batch questions independent enough to answer in one pass.\n- `questions` must contain between 2 and 7 entries.\n- Batch questions do not support `allowComment`; add a final optional text question instead.\n- In the interactive overlay, use `left` / `right` or `ctrl+n` / `ctrl+p` to switch questions.\n- For selectable questions, start typing to filter options or enter a custom response.\n\n## Example usage shapes\n\n### Single-question mode\n\n```json\n{\n  \"question\": \"Which option should we use?\",\n  \"context\": \"We are choosing a deploy target.\",\n  \"options\": [\n    { \"title\": \"staging\" },\n    { \"title\": \"production\", \"description\": \"Customer-facing\" }\n  ],\n  \"allowMultiple\": false,\n  \"allowComment\": true\n}\n```\n\n### Batch clarification mode\n\n```json\n{\n  \"mode\": \"batch\",\n  \"title\": \"Clarify implementation scope\",\n  \"context\": \"I need a few details before proceeding.\",\n  \"questions\": [\n    {\n      \"id\": \"surface\",\n      \"question\": \"Which surface is in scope?\",\n      \"options\": [{ \"title\": \"Overlay\" }, { \"title\": \"RPC/headless fallback\" }, { \"title\": \"Both\" }],\n      \"required\": true\n    },\n    {\n      \"id\": \"compat\",\n      \"question\": \"Must the current single-question behavior remain exact?\",\n      \"options\": [{ \"title\": \"Yes\" }, { \"title\": \"No\" }, { \"title\": \"Mostly yes\" }],\n      \"required\": true\n    },\n    {\n      \"id\": \"notes\",\n      \"question\": \"Anything else I should optimize for?\",\n      \"required\": false\n    }\n  ]\n}\n```\n\n## Result details\n\nSuccessful tool results include the user's actual answer text in plain-text `content` so agents can continue even in integrations that surface only tool text. Results also include a structured `details` object for rendering and session state reconstruction:\n\n```typescript\ntype AskResponse =\n  | { kind: \"selection\"; selections: string[]; comment?: string }\n  | { kind: \"freeform\"; text: string }\n  | {\n      kind: \"batch\";\n      answers: Array<\n        | { id: string; kind: \"selection\"; selections: string[] }\n        | { id: string; kind: \"freeform\"; text: string }\n        | { id: string; kind: \"skipped\" }\n      >;\n    };\n\ninterface AskToolDetails {\n  mode: \"single\" | \"batch\";\n  question?: string;\n  title?: string;\n  context?: string;\n  options?: QuestionOption[];\n  questions?: BatchQuestion[];\n  response: AskResponse | null;\n  cancelled: boolean; // compatibility flag: true for cancel, timeout, and abort\n  outcome: \"answered\" | \"cancelled\" | \"timeout\" | \"aborted\";\n}\n```\n\nSingle-question payloads and response variants remain unchanged. The batch result branch is returned only when `mode: \"batch\"` is used. Configuration precedence is always per-call parameter, then the corresponding environment variable, then the documented default. Manual cancellation, timeout, and `AbortSignal` remain backward-compatible through `cancelled: true` and are distinguished by `outcome`.\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md).\n","readmeFilename":"README.md"}