pi-clarify

Prompt clarification extension for pi coding agent.

Features

• clarify_prompt tool - Prompts the LLM to ask clarifying questions when user input is vague
• Vague input detection - Flags structurally empty input (blank, single-character, or pure punctuation) and lets the LLM judge ambiguity for everything else via an injected system-prompt section
• /clarify toggle - Enable or disable clarification with /clarify on|off
• ~ bypass prefix - Prefix prompts with ~ to skip clarification for one turn
• Network/proxy issue handling - When a tool call fails with a network, proxy, connectivity, or rate-limit error, the model stops and asks the user how to proceed instead of silently retrying or switching approaches

Requirements

pi 1.2.0 or newer. pi 1.2.0 split before_agent_start into a union on messageType, and the extension reads that field to tell a user prompt from an extension message.

On an older host the extension reports pi-clarify requires pi 1.2.0 or newer: this host sends no messageType on before_agent_start, so clarification cannot tell a user prompt from an extension message. Upgrade pi to continue using this extension. once per turn instead of failing silently, so a stale host is obvious rather than leaving clarification quietly disabled.

Installation

From npm:

pi install npm:@dkmnx/pi-clarify

From a local path (the path is added to settings without copying, so edits take effect on the next pi start — useful when developing the extension):

pi install /path/to/pi-clarify

Or add directly to your settings.json:

{
  "packages": ["npm:@dkmnx/pi-clarify"]
}

Usage

Automatic Clarification

When enabled, the LLM automatically detects vague prompts and asks for clarification:

• "fix it" → "What specifically needs to be fixed?"
• "make it better" → "What does 'better' mean in this context?"
• "optimize this" → "Which files or functions should be optimized?"

Manual Tool Call

The LLM can explicitly call the clarify_prompt tool:

clarify_prompt({
  question: "What specific behavior needs to be fixed?",
  options: [
    "Fix the login redirect issue",
    "Fix the form validation error",
    "Fix the memory leak in the dashboard"
  ]
})

Commands

Bypass

Prefix your prompt with ~ to skip clarification for one turn:

~ fix it - just update the error message text

~ is used instead of ! because pi reserves !/!! as the built-in shell-command prefix.

A tilde that does not start a path is the marker, so ~ fix it and ~fix it both bypass. A prompt starting ~/… or ~user/… is a home-relative path, not a marker, so it passes through untouched.

Network / proxy issue handling

When a tool call fails with a network, proxy, connectivity, or rate-limit error (timeout, ECONNREFUSED, ENOTFOUND, ETIMEDOUT, ECONNRESET, fetch failed, socket hang up, proxy error, 429, 502/503/504, TLS or certificate failures, …), the extension:

1. Injects a NETWORK_ISSUE_PROMPT guideline into the system prompt telling the model to not silently retry more than once and to not silently switch approaches.
2. Detects network/proxy error signatures in failed tool results (tool_result with isError: true) and appends a reminder that nudges the model to call clarify_prompt with options like:
   • "Retry the same request"
   • "Switch to a different proxy / network"
   • "Wait and try again later"
   • "Use a fallback approach / different tool"
   • "Skip this step and continue"

Both parts are governed by the same /clarify toggle. The system-prompt guideline is injected in every mode. The per-result reminder needs a dialog-capable UI, so it stays inactive in print and JSON mode.

How vague input is detected

Clarification is driven by the LLM, not by keyword matching. When enabled, the extension writes a clarify section into pi's system-prompt options instructing the model to call clarify_prompt whenever a request is ambiguous, has unclear outcomes/scope, admits multiple valid interpretations, or is missing constraints. It is a structured section rather than a whole-prompt replacement, so pi records it as a transcript delta and its own prompt sections stay intact.

The only client-side heuristic is a minimal structural guard: completely blank, single-character, or pure-punctuation input is flagged as vague so the model receives an extra reminder. Short but actionable commands like git push or npm test are not auto-flagged — the model decides based on the full conversation context.

Example patterns the LLM is told to clarify

These are examples the injected section tells the model to watch for (the model does the actual judgment, not the extension):

• Ambiguous referents: "fix it", "this is broken", "the bug"
• Unclear outcomes: "make it better", "improve the code"
• Undefined scope: "refactor everything", "fix the tests"
• Missing constraints: no mention of backwards compatibility, performance priorities, or approach preferences
• Multiple valid interpretations: the request could reasonably mean 2+ different things

License

MIT