Module question 

ask_question (#1660): parse/validate the model’s clarifying-question batch, and the pure types the turn loop’s question-pause phase builds and consumes.

This is a sibling pause path to the tool-approval gate, not a reuse of it — see issue #1660 and its parent PRD #1659. This module owns only the parse/validate half (invariant I5: a malformed call is rejected back to the model as a tool-call error and never reaches a pause or an event-log write); the pause/resume machinery that consumes QuestionItem (a pending-question record, the turn result’s own pending-questions list) lands in a later slice of this same issue.

Why the tool name is duplicated here rather than imported

polyc_tools already depends on polyc_agent (for crate::ToolExecutor), so this crate cannot depend back on polyc_tools without a cycle. ASK_QUESTION_TOOL_NAME is therefore the same literal as polyc_tools::ask_question::TOOL_NAME, duplicated deliberately — the same reasoning polyc_proto’s INVITE_TOOL_NAME duplication already documents. A cross-crate test in polyc-tools pins the two literals equal.

Structs

PendingQuestion

One question from an ask_question call, paused and awaiting an answer.

QuestionArgsError

A validation failure from parse_ask_question_args (invariant I5).

QuestionItem

One clarifying question: a short header, a one-sentence prompt, and 2-4 mutually exclusive QuestionOptions.

QuestionOption

One option a question offers: a short label and its one-sentence consequence. At most one option per QuestionItem is recommended.

UnrecognizedAnswerState

s did not match any of polyc_crypto::question’s three signed state strings.

VerifiedAnswer

A verified, signature-checked answer to one pending question.

Enums

AnswerState

A resolved answer’s state (invariant I4: three states, pairwise distinguishable in the tool result).

Constants

ASK_QUESTION_TOOL_NAME

The ask_question tool name the turn loop recognizes to trigger the question-pause phase.

MAX_HEADER_CHARS

Maximum length (in characters) of a question’s header. Kept in sync with polyc_tools::ask_question::MAX_HEADER_CHARS.

MAX_OPTIONS

Maximum number of options a question may offer. Kept in sync with polyc_tools::ask_question::MAX_OPTIONS.

MAX_OPTION_LABEL_CHARS

Maximum length (in characters) of an option’s label. Kept in sync with polyc_tools::ask_question::MAX_OPTION_LABEL_CHARS.

MAX_QUESTIONS_PER_CALL

Maximum number of questions in a single ask_question call. Kept in sync with polyc_tools::ask_question::MAX_QUESTIONS_PER_CALL.

MAX_SENTENCE_CHARS

Maximum length (in characters) of a one-sentence field (question or an option’s description). Kept in sync with polyc_tools::ask_question::MAX_SENTENCE_CHARS.

MIN_OPTIONS

Minimum number of options a question may offer. Kept in sync with polyc_tools::ask_question::MIN_OPTIONS.

Functions

parse_ask_question_args

Parses and validates one ask_question call’s arguments (invariant I5).

question_call_result_json

Build the combined tool-call result JSON for one ask_question call.

question_still_pending_json

Builds a transcript-only interim result for a call whose question(s) are still unanswered when new turn input arrives (invariant I8).