kandev/docs/specs/ui/clarification-context.md

status, created, owner

status	created	owner
shipped	2026-08-13	cfl

Clarification Shared Context

Why

Agents can provide shared background with ask_user_question_kandev.context, but operators currently see only the individual question fields. Questions that depend on that background can therefore appear incomplete or confusing.

What

• A pending clarification bundle with non-empty shared context displays that context once above the active question card.
• Shared context uses normal text presentation with spacing above it. It has no bordered, padded, or filled container.
• Shared context remains visible while the operator moves between questions in a multi-question bundle.
• Task chat, Quick Chat, and other surfaces that use the shared clarification overlay display the same context behavior on desktop and mobile.
• Omitted or whitespace-only context does not create an empty context region.
• The UI preserves line breaks in the agent-authored context and allows long text to wrap within the clarification surface.
• Agents can provide multiline shared background as explicit context paragraphs. The backend joins those paragraphs with blank lines while preserving the legacy single context string verbatim.

Scenarios

• GIVEN an agent submits a multi-question clarification with non-empty shared context, WHEN the pending clarification appears, THEN the operator sees the context exactly once above the active question card.
• GIVEN a visible multi-question clarification with shared context, WHEN the operator navigates to another question, THEN the same single context region remains visible.
• GIVEN an agent omits context or sends only whitespace, WHEN the pending clarification appears, THEN the UI renders no context region and preserves the existing question layout.
• GIVEN a pending clarification with shared context on a phone viewport, WHEN the operator views the question, THEN the context is visible, wraps inside the overlay, and does not introduce horizontal page overflow.
• GIVEN an agent submits multiple explicit context paragraphs, WHEN the clarification is stored and displayed, THEN the operator sees those paragraphs separated by blank lines.
• GIVEN an agent submits a legacy context string containing literal escape syntax, WHEN the clarification is stored and displayed, THEN the literal text remains unchanged.

Out of scope

• Changing the ask_user_question_kandev schema or backend message metadata.
• Repeating shared context inside every question card.
• Adding shared context to resolved clarification messages in chat history.
• Changing clarification answer, skip, timeout, or carousel behavior.