feat: ask_user_question — structured clarifying questions via mid-turn interrupt (PR-1)

[philmerrell]

Backend for a Claude-style follow-up questions UI: the agent pauses a turn to ask the user 1–4 structured multiple-choice questions, then continues in place with their answer as the tool's result.

PR 1 of 4 — backend only. No SPA renderer yet, so the catalog seed ships enabledByDefault: False. A paused turn with no picker is a worse failure than a guessed assumption.

Spec: docs/specs/ask-user-question.md

Why this shape

The mechanism already existed. Per-tool approval (MCPExternalApprovalHook) is this same thing with one question and two fixed options — a Strands interrupt pauses the turn, an SSE event drives an inline prompt, and the decision POSTs back as an interrupt_responses entry. Generalizing the payload was cheaper than a second pause mechanism, and it inherits the paused-turn snapshot, the resume guard and the reload breadcrumbs for free.

An MCP App (ui_resource) was considered and rejected: App frames render alongside a running turn, they don't pause it.

The one real risk, and how it was closed

Every interrupt shipped so far is raised from a BeforeToolCallEvent hook. This one is raised by the tool itself via ToolContext (which implements _Interruptible), because here the pause is the tool. The resume path — PausedTurnSnapshot → rebuilt agent → restored _interrupt_state → pending_tool_execution replayed — was built and proven against the hook flavor only.

test_user_question_interrupt_integration.py drives the real Strands event loop (real Agent, real @tool, scripted model only) and pins the tool-scoped flavor: the turn pauses, pending_tool_execution is captured, the id is v1:tool_call:{toolUseId}:…, resuming feeds the answer back into the same tool call, and the tool is not re-invoked.

Two asymmetric contracts, deliberately

• Questions come from the model → validated strictly, at the tool boundary, while it still has a turn left to fix them. Emitting an unrenderable prompt would pause the turn with nothing on screen.
• Answers come from the client → parsed leniently (keyed, positional, bare string, junk). That payload is the user's only route out of a paused turn, so a shape mismatch must never strand them.

Cost

• The tool spec is a constant in the cacheable toolConfig prefix — registered once at startup, never injected per-turn. Do not make its presence conditional on conversation state.
• It is a static registry tool, not an extra_tools injection, so it captures no identity and doesn't touch the injected-tool agent-cache bypass.
• Questions ride the SSE channel; only the one-line formatted answer block re-enters the conversation.

Validation

Unit: 82 new tests; full backend suite green (8,540), ruff clean.

Live against real Bedrock on dev-ai (Haiku 4.5 + Sonnet 4.6), 42/42: asks on an ambiguous request, does not over-trigger on unambiguous ones, emits one well-formed user_question_required frame with a tool-scoped id, resumes into the same tool call, and the skip path lets the model proceed rather than stall.

Two defects the unit tests could not have found, fixed in c60b91c:

• Haiku supplied its own "Other" option on ~half of sampled turns despite the description. Worse than a duplicate — the picker's Other carries a free-text field, a model-supplied one records the bare string. Now stripped server-side.
• Haiku sometimes opened a second round of questions after the first answers. Legal (fresh interrupt id, resumes fine) but reads as an interrogation; the docstring now says ask once.

Regression: a normal chat turn through the local stack streams and completes unchanged (POST /chat/stream → 200), with the new extractor in the done path.

Follow-ups

PR	Scope
2	UserQuestionService + stream-parser wiring + single-question single-select prompt; generalize resumeFromToolApproval to carry an object. Ships usable.
3	Multi-select, multi-question carousel, "Other", "Skip", reload rehydration.
4	Flip enabledByDefault, description tuning, RBAC grants.

🤖 Generated with Claude Code