@gamaraan/ask-tool

A pi extension that ports the ask tool from Oh My Pi (OMP): interactive multiple-choice questions the agent asks the user mid-turn, with a rich TUI dialog, recommended options, live timeouts with auto-select, free-text answers, and multi-question paging.

It is the full replacement for the obsolete interactive-question extension.

What it does

Gives the model a tool named ask that takes one or more questions:

{
  "questions": [
    {
      "id": "storage",
      "question": "Which storage backend should the API use?",
      "header": "Storage",
      "options": [
        { "label": "SQLite", "description": "File-based, zero config." },
        { "label": "PostgreSQL", "description": "Server-based, feature-rich." },
        { "label": "MongoDB" }
      ],
      "recommended": 0
    },
    {
      "id": "auth",
      "question": "Which auth method?",
      "multi": true,
      "options": [
        { "label": "JWT", "description": "Bearer tokens." },
        { "label": "OAuth2" }
      ]
    }
  ]
}

• recommended: <index> marks the default option; " (Recommended)" is appended automatically and the cursor starts there.
• multi: true turns the question into a multi-select (checkboxes).
• header shows as a short chip in the dialog tab bar.
• description is displayed under each option; preview renders rich (markdown + code fences) content in the TUI dialog.
• Reserved runtime options are always offered and can never collide with model-provided labels (schema validation rejects them):
  • Other (type your own) — free-text answer (inline editor in TUI, ctx.ui.editor in RPC)
  • Chat about this — TUI-only redirect: the agent switches to conversation instead of answering
  • Next → — internal paging affordance
• Timeout with auto-select: when a configured timeout elapses without input, the recommended option (or the first) is auto-selected and the result is marked timedOut — the model receives a real answer, not a hang.
• Multi-question dialogs page with Next →/back navigation; multi-select questions confirm on a "Review answers" submit tab.

Runtime behaviors

| Feature | TUI | RPC | print/headless | | --- | --- | --- | --- | | Rich multi-question dialog (tabs, previews, notes, submit tab) | ✅ | — | — | | Chat about this redirect | ✅ | — | — | | Option descriptions & markers | ✅ | — | — | | Per-question select loop with Other free text | ✅ | ✅ | — | | Multi-question back/forward via confirm gate | ✅ | ✅ | — | | Timeout countdown + auto-select | ✅ | ✅ | — | | Esc cancels the ask and aborts the turn | ✅ | ✅ | — | | Error result instead of a dialog | — | — | ✅ |

ctx.mode === "tui" shows the rich dialog as a widget panel in the extension widget slot — directly under the transcript, above the prompt editor — via ctx.ui.setWidget (the dialog grabs keyboard focus while open and restores it to the prompt afterwards, and is cleared when the answers are submitted). Every other mode with UI (RPC) uses the simple per-question loop; headless modes return an Error: Ask tool requires interactive mode result without throwing.

When ask-notify is on, the existing in-UI waiting notice is retained. For TUI asks in terminals advertising OSC 9/99 notifications (Kitty, Ghostty, WezTerm, iTerm2, or Warp), ask-tool also emits a best-effort desktop-notify:request EventBus event whose title is the first ask question (and whose body remains Waiting for input). The terminal owns focus handling, so a waiting notification is intended to appear only while its window is inactive. Unknown/base terminals do not receive the EventBus request because native notify-send fallbacks cannot reliably determine terminal focus.

@gamaraan/desktop-notify is optional: when it is loaded it may handle the request, and when it is unavailable no action is required.

Configuration

Ask-tool stores persistent defaults in the global ask-tool.json file under Pi's agent directory (normally ~/.pi/agent/ask-tool.json). Configure it interactively with /ask-configure; the file is written and extensions are reloaded immediately when the wizard finishes.

The effective precedence is flag > environment > static JSON > built-in default:

| Setting | Static JSON | Flag | Env | Default | | --- | --- | --- | --- | --- | | Timeout in seconds (0 = disabled) | timeoutSeconds | --ask-timeout <seconds> | PI_ASK_TIMEOUT_SECONDS | 0 (disabled) | | Best-effort waiting notification | notify | --ask-notify <off\|on> | PI_ASK_NOTIFY | false |

Example static configuration:

{
  "notify": true,
  "timeoutSeconds": 30
}

Example: pi --ask-timeout 30 overrides the saved timeout for that session; the countdown resets on key presses.

Install & enable

The extension is a plain pi extension package. Enable it either by:

1. npm package + pi.extensions discovery — install @gamaraan/ask-tool wherever your pi packages live (e.g. add it to your pi config packages), or
2. direct copy — copy this repository (or the published package) into ~/.pi/agent/extensions/ so pi's extension discovery picks up src/index.ts (the "pi": { "extensions": ["./src/index.ts"] } manifest also works).

After a /reload (or restart), the model is offered the ask tool. Ask the model to "list your tools" to confirm.

Development

The source lives in src/; AGENTS.md documents the architecture, invariants, and development commands.

Tests run through the pi-mono test runner (they reuse its vitest alias graph for @earendil-works/pi-*):

cd ../pi-mono/packages/coding-agent
npx vitest run test/ask-user-question

Typecheck the package against the pi-mono sources:

cd ../pi-mono && ./node_modules/.bin/tsgo --noEmit -p ../ask-tool/tsconfig.json

See AGENTS.md for the architecture invariants and the roadmap.

License

MIT — this package is a port of OMP's ask tool (itself a fork of pi); see LICENSE for the original copyright notices (Mario Zechner, Can Bölük) and the port notice.