askuser

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 14, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const Description = `Asks the user multiple choice questions to gather information, clarify ambiguity, understand preferences, make decisions or offer them choices.

Use this tool when progress is blocked by missing user input.

This tool is for real clarification, preference gathering, or decision points during execution. It is not for narration, status updates, or asking for approval that another tool already handles.

## Good reasons to use it

- The request is ambiguous and multiple valid implementations exist
- A product or UX preference must be chosen by the user
- You need a concrete decision before continuing
- You need structured answers for recommendations, research direction, or implementation scope
- You need the user to choose between tradeoffs that you cannot resolve from evidence alone

## Do NOT use it when

- you already have enough information to proceed safely
- you are only giving a status update
- you are asking "should I continue?"
- you are in plan mode and simply need plan approval; use ` + "`exit_plan_mode`" + ` for that
- you could instead verify the answer from the repository or a reliable source

## Question design rules

- Ask the minimum number of questions needed to unblock progress
- Prefer one focused question over a large survey unless batching is clearly useful
- Keep each question concise and concrete
- Make sure each option represents a real decision the user can understand
- Use 2 to 10 options
- Use ` + "`multiSelect: true`" + ` only when multiple answers are genuinely useful
- Put the recommended option first and suffix the label with ` + "\"(Recommended)\"" + `
- Do NOT include an explicit ` + "\"Other\"" + ` option; the UI/runtime adds a free-text path automatically
- If a free-text answer is likely, keep the structured choices broad and complementary rather than overly exhaustive

## Examples

Good:
- "Which deployment target should I optimize for first?"
- "Which of these auth approaches matches your preference?"
- "What kind of project should I research for you?"
- "Which of these rollout strategies do you prefer for this change?"

Bad:
- "Should I proceed?"
- "Is my plan good?"
- "Anything else?"
- "Can you confirm this fact?" when the fact could be verified from tools

## Plan mode note

In plan mode, use this tool only to resolve requirement gaps before finalizing the plan. Do not ask the user to approve the plan through this tool.`

Description is the tool description.

View Source 
const PreviewFeatureDescriptionHTML = `
Preview feature:
Use the optional ` + "`preview`" + ` field on options when presenting concrete artifacts that users need to visually compare:
- HTML mockups of UI layouts or components
- Formatted code snippets showing different implementations
- Visual comparisons or diagrams

Preview content must be a self-contained HTML fragment (no <html>/<body> wrapper, no <script> or <style> tags — use inline style attributes instead). Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).
`

PreviewFeatureDescriptionHTML is the preview feature guidance for HTML format.

View Source 
const PreviewFeatureDescriptionMarkdown = `
Preview feature:
Use the optional ` + "`preview`" + ` field on options when presenting concrete artifacts that users need to visually compare:
- ASCII mockups of UI layouts or components
- Code snippets showing different implementations
- Diagram variations
- Configuration examples

Preview content is rendered as markdown in a monospace box. Multi-line text with newlines is supported. When any option has a preview, the UI switches to a side-by-side layout with a vertical option list on the left and preview on the right. Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).
`

PreviewFeatureDescriptionMarkdown is the preview feature guidance for markdown format.

View Source 
const SearchHint = "prompt the user with a multiple choice question"

SearchHint is a hint for tool search functionality.

View Source 
const ToolName = "ask_user_question"

ToolName is the tool name.

Variables

This section is empty.

Functions

func GetDescription 

func GetDescription(includePreviewMarkdown bool, includePreviewHTML bool) string

GetDescription returns the full description, optionally including preview feature guidance.

func ValidateHTMLPreview 

func ValidateHTMLPreview(preview string) string

ValidateHTMLPreview validates HTML preview content. Returns an error message if invalid, nil if valid.

Types

type Annotation 

type Annotation struct {
	Preview string `json:"preview,omitempty"`
	Notes   string `json:"notes,omitempty"`
}

Annotation contains additional info about a user's answer.

type Config 

type Config struct {
	InputReader *bufio.Reader
	Timeout     time.Duration
	PromptFn    types.PromptFn
}

Config represents tool configuration.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns default configuration.

type Input 

type Input struct {
	Questions   []Question            `json:"questions"`
	Answers     map[string]string     `json:"answers,omitempty"`
	Annotations map[string]Annotation `json:"annotations,omitempty"`
}

Input represents the tool input.

func NewInput 

func NewInput(question, header string, options ...string) *Input

NewInput creates a new Input from a question.

func (*Input) FormatForDisplay 

func (i *Input) FormatForDisplay() string

FormatForDisplay formats the questions for display to user.

func (*Input) Validate 

func (i *Input) Validate() error

Validate validates the input.

type Output 

type Output struct {
	Questions   []Question            `json:"questions"`
	Answers     map[string]string     `json:"answers"`
	Annotations map[string]Annotation `json:"annotations,omitempty"`
}

Output represents the tool output.

type Question 

type Question struct {
	Question    string           `json:"question"`
	Header      string           `json:"header"`
	Options     []QuestionOption `json:"options"`
	MultiSelect bool             `json:"multiSelect,omitempty"`
}

Question represents a question to ask the user.

func (*Question) GetOptionByIndex 

func (q *Question) GetOptionByIndex(index int) *QuestionOption

GetOptionByIndex returns the option for a given question and index.

func (*Question) GetOptionByLabel 

func (q *Question) GetOptionByLabel(label string) *QuestionOption

GetOptionByLabel returns the option for a given question and label.

type QuestionOption 

type QuestionOption struct {
	Label       string `json:"label"`
	Description string `json:"description"`
	Preview     string `json:"preview,omitempty"`
}

QuestionOption represents an option for a question.

type Tool 

type Tool struct {
	// contains filtered or unexported fields
}

Tool represents the AskUserQuestion tool.

func NewTool 

func NewTool(config *Config) *Tool

NewTool creates a new AskUserQuestion tool.

func (*Tool) BackfillInput 

func (t *Tool) BackfillInput(ctx context.Context, input map[string]any) map[string]any

BackfillInput enriches a shallow clone of the parsed input with derived fields.

func (*Tool) Call 

func (t *Tool) Call(
	ctx context.Context,
	input tool.CallInput,
	permissionCheck types.CanUseToolFn,
) (tool.CallResult, error)

Call executes the tool.

func (*Tool) CheckPermissions 

func (t *Tool) CheckPermissions(ctx context.Context, input map[string]any, toolCtx tool.ToolUseContext) types.PermissionResult

CheckPermissions marks AskUserQuestion as locally allowed.

func (*Tool) Definition 

func (t *Tool) Definition() tool.Definition

Definition returns the tool definition.

func (*Tool) Description 

func (t *Tool) Description(ctx context.Context) (string, error)

Description returns human-readable description.

func (*Tool) FormatResult 

func (t *Tool) FormatResult(data any) string

FormatResult serialises the tool output into the tool_result content string.

func (*Tool) IsConcurrencySafe 

func (t *Tool) IsConcurrencySafe(input map[string]any) bool

IsConcurrencySafe reports that AskUserQuestion can run concurrently.

func (*Tool) IsEnabled 

func (t *Tool) IsEnabled() bool

IsEnabled returns whether this tool is currently active.

func (*Tool) IsReadOnly 

func (t *Tool) IsReadOnly(input map[string]any) bool

IsReadOnly reports that AskUserQuestion does not modify state.

func (*Tool) SetPromptFn 

func (t *Tool) SetPromptFn(promptFn types.PromptFn)

SetPromptFn sets a prompt function for structured prompting.

func (*Tool) SetReader 

func (t *Tool) SetReader(reader *bufio.Reader)

SetReader sets a custom input reader (for testing).

func (*Tool) SetTimeout 

func (t *Tool) SetTimeout(timeout time.Duration)

SetTimeout sets the input timeout.

func (*Tool) ValidateInput 

func (t *Tool) ValidateInput(ctx context.Context, input map[string]any) (map[string]any, error)

ValidateInput validates AskUserQuestion input.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.