feat: add Clarification tool and UI

[Bl3f]

Summary

Adds a new clarification agent tool + UI, mirroring the SOTA behaviour in Claude Code and Codex. When the user's request is genuinely ambiguous (multiple plausible tables, unclear metric, missing time range, etc.), the agent can call this tool to ask one focused question and optionally surface 2–5 clickable answer chips. The agent then stops and waits for the user's reply.

UX

• Clicking an option chip sends the answer directly — no extra Enter press required.
• Free-form answers are still supported via the normal chat input.
• Multi-turn clarification works naturally: every new user message ends the current clarification turn. The agent can call clarification again on the next turn; previous cards automatically switch to an "Answered" state (muted, checkmark on the selected chip) so the user keeps the full decision trail visible.
• Intermediate answers don't need dedicated storage: they live as ordinary user messages in the chat history, and the model reads them back on every subsequent step. The tool call itself is preserved too (not pruned like suggest_follow_ups), so the assistant remembers what it asked.

Walkthrough

Direct-send + multi-turn answered state:

clarification_v2_direct_send_and_answered_state.mp4

Initial clarification card with chips:

Clarification card with Quick question header and option chips

Clicking a chip sends it instantly (input stays empty, message appears as a user bubble):

Chip click sends directly

When a follow-up clarification fires, the previous card turns into an "Answered" card with a checkmark on the selected option:

Multi-turn state: previous card marked answered

What changed

• Shared schema (apps/shared/src/tools/clarification.ts) — zod input { question, options?: string[2..5] }.
• Backend tool (apps/backend/src/agents/tools/clarification.ts) — registered in tools/index.ts; the ToolLoopAgent's stopWhen now also fires on clarification so the run halts and waits for the user.
• System prompt + tool description — describe when to use it (only when guessing would be costly, never alongside other tools or suggest_follow_ups), and now explicitly cover the multi-turn flow: one question per call, ask the next on a later turn, never re-ask something already answered.
• Frontend — new ClarificationToolCall component (apps/frontend/src/components/tool-calls/clarification.tsx):
  • renders a "Quick question" card with the question and pill-shaped option chips;
  • chip click dispatches queueOrSendMessage({ text: option }) from the agent context for immediate submission;
  • detects whether a user message has been sent after this tool call and, if so, renders the card in an "Answered" muted style with a checkmark on the matching option (so stale cards remain informative but non-interactive);
  • added to NON_COLLAPSIBLE_TOOLS so it never gets folded into a tool group.
• Messaging providers — tool-clarification added to EXCLUDED_TOOLS so Slack/Telegram/etc. summaries don't render raw tool entries for it.

Testing

• ✅ npm run lint
• ✅ Manual end-to-end in the live app (see walkthrough): agent calls the tool, chip click sends instantly, follow-up clarification renders, previous card marked answered with checkmark.
• ⚠️ npm run -w @nao/backend test — 11 pre-existing failures on main (system-prompt date tests, sqlite tests, compaction LLM); none related to this change.

_{To show artifacts inline, enable in settings.}

  

[github-actions]

🚀 Preview Deployment

URL	https://pr-701-5fcaa26.preview.getnao.io
Commit	5fcaa26

⚠️ No LLM API keys configured - you'll see the API key setup flow when trying to chat.

---

_{Preview will be automatically removed when this PR is closed.}

[cubic-dev-ai]

No issues found across 10 files