Pi Ask Tool Extension

An extension for the Pi coding agent that adds a structured ask tool with interactive, tab-based questioning and inline note editing.

ask({
  questions: [
    {
      id: "auth",
      question: "Which authentication model should we use?",
      options: [{ label: "JWT" }, { label: "Session" }],
      recommended: 1
    }
  ]
})

Why

When an agent needs a decision from you, free-form prompts are slow and inconsistent. This extension provides:

• Structured options with clear IDs and deterministic outputs
• Single + multi-select in one tool
• Tab-based multi-question flow with a final submit review tab
• Inline note editing (no large UI pane shifts)
• Question text auto-wrap (avoids one-line ... truncation)
• Optional Markdown context for longer explanations/structure diagrams
• Automatic Other (type your own) handling

Install

From npm

pi install npm:pi-ask-tool-extension

From git

pi install git:github.com/devkade/pi-ask-tool@main
# or pin a tag
pi install git:github.com/devkade/[email protected]

Local development run

pi -e ./src/index.ts

Quick Start

Single question (single-select)

ask({
  questions: [
    {
      id: "auth",
      question: "Which auth approach?",
      options: [{ label: "JWT" }, { label: "Session" }],
      recommended: 1
    }
  ]
})

Result example:

User answers:
auth: Session

Answer context:
Question 1 (auth)
Prompt: Which auth approach?
Options:
  1. JWT
  2. Session
Response:
  Selected: Session

Single question (multi-select)

ask({
  questions: [
    {
      id: "features",
      question: "Which features should be enabled?",
      options: [{ label: "Logging" }, { label: "Metrics" }, { label: "Tracing" }],
      multi: true
    }
  ]
})

Result example:

User answers:
features: [Logging, Metrics]

Answer context:
Question 1 (features)
Prompt: Which features should be enabled?
Options:
  1. Logging
  2. Metrics
  3. Tracing
Response:
  Selected: [Logging, Metrics]

Multi-question (tab flow)

ask({
  questions: [
    {
      id: "auth",
      question: "Which auth approach?",
      options: [{ label: "JWT" }, { label: "Session" }]
    },
    {
      id: "cache",
      question: "Which cache strategy?",
      options: [{ label: "Redis" }, { label: "None" }]
    }
  ]
})

Result example:

User answers:
auth: Session
cache: Redis

Answer context:
Question 1 (auth)
Prompt: Which auth approach?
Options:
  1. JWT
  2. Session
Response:
  Selected: Session

Question 2 (cache)
Prompt: Which cache strategy?
Options:
  1. Redis
  2. None
Response:
  Selected: Redis

Question with Markdown context (long guidance / structure)

ask({
  questions: [
    {
      id: "architecture",
      question: "Which execution path should we prioritize?",
      description: `# Background\n\n- Current bottleneck: network I/O\n- Goal: reduce response latency\n\n\`\`\`text\n[Client] -> [API] -> [Cache] -> [DB]\n\`\`\``,
      options: [{ label: "Cache-first" }, { label: "DB-first" }],
      recommended: 0
    }
  ]
})

description accepts both Markdown and plain text, and is wrapped above options.

Interaction Model

| Flow | UI style | Submit behavior | |---|---|---| | Single + multi: false | one-question picker | Enter submits immediately | | Single + multi: true | tab UI (Question + Submit) | Submit tab confirms | | Multiple questions (mixed allowed) | tab UI (Q1..Qn + Submit) | Submit tab confirms all |

Inline Notes (Minimal UI Transitions)

Press Tab on any option to edit a note inline on that same row.

• Display format: Option — note: ...
• Editing cursor: inverse block on the character under caret (or space at end)
• Notes are sanitized for inline display (line breaks/control chars)
• Narrow-width rendering keeps the edit cursor visible

For Other, a note is required to become valid.

Keyboard Shortcuts

• ↑ / ↓: move between options
• ← / →: switch question tabs
• Enter: select/toggle or submit (on Submit tab)
• Tab: start/stop inline note editing
• Esc: cancel flow

Tool Schema

{
  questions: [
    {
      id: string,
      question: string,
      description?: string, // optional Markdown/plain context shown above options
      options: [{ label: string }],
      multi?: boolean,
      recommended?: number // 0-indexed
    }
  ]
}

Do not include an Other option in options. The UI injects it automatically.

Development

npm install
npm run check

npm run check runs:

• TypeScript checks (npm run typecheck)
• Test suite with coverage (npm run test:coverage)
• Coverage gate (npm run coverage:check)

Coverage gate defaults (override via env vars in CI if needed):

• Overall: lines >= 38%, functions >= 80%
• src/index.ts: lines >= 95%, functions >= 100%
• src/ask-logic.ts: lines >= 95%, functions >= 100%
• src/ask-inline-note.ts: lines >= 80%, functions >= 70%

Project Structure

• src/index.ts - extension entrypoint, tool registration, and orchestration
• src/ask-logic.ts - selection/result mapping helpers
• src/ask-inline-ui.ts - single-question UI
• src/ask-tabs-ui.ts - tabbed multi-question UI
• src/ask-inline-note.ts - inline note rendering helper
• src/ask-text-wrap.ts - shared line-wrapping helper for long prompts
• test/*.test.ts - logic + UI mapping + integration coverage