What does this PR do?

Fixes the Discord clarify() prompt so that:

1. Choice lists longer than 2 entries render as a Discord Select menu (drop-up) with proper label + description support, replacing the old text-fallback that capped labels at 80 chars and dropped multi-line descriptions on the floor.
2. Models that ignore the schema's items: {type: string} and pass dict/int choices (e.g. {"key": "cc", "value": "Claude Code CLI"}) get normalized to clean labels instead of str(dict) Python-repr garbage in the button row.
3. The Discord adapter explicitly calls mark_awaiting_text() after sending a choice-based prompt, so the gateway's get_pending_for_session() interceptor picks up the user's text reply on Discord (where the platform has no native button).

Net effect: clarify() actually resolves on Discord instead of hanging at ⏳ Still working… until the 10-minute timeout.

Related Issue

Fixes #26009

Refs #12573

Complements #26008 (open — gateway-side awaiting_text filter removal; this PR calls mark_awaiting_text from the adapter, which works with or without #26008)

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• tools/clarify_tool.py (+168/-50) — added _normalize_clarify_choice, _extract_clarify_description, _normalize_clarify_choices_rich. Widens accepted choice type from List[str] to Sequence[ClarifyChoice]. Callback contract preserved: clarify_callback still receives List[str].
• plugins/platforms/discord/adapter.py (+224) — rewrote ClarifyChoiceView with branching:
  • ≤2 choices → buttons (yes/no speed)

  • 2 choices → Discord Select menu (drop-up) with 100-char label + 100-char description per option, plus a trailing ✏️ Other (type your answer) row as the 25th option.

  • New _on_select interaction handler dispatches picks via resolve_gateway_clarify; "Other" flips the entry into text-capture.
  • send_clarify passes the question to the view so the Select placeholder can include it.
  • Calls mark_awaiting_text() after a Select-menu prompt so the gateway interceptor picks up the user's text reply.
• tests/tools/test_clarify_tool.py (+80) — 5 new tests for dict/int normalization, label fallback, mixed types, and unrenderable graceful-degradation.
• tests/gateway/test_discord_clarify_buttons.py (+320) — 8 new tests for the Select-menu path, description truncation, the 25-cap, and end-to-end interaction resolution; 2 updated tests for the new button/select branching.

How to Test

1. pytest tests/tools/test_clarify_tool.py tests/gateway/test_discord_clarify_buttons.py -q — 75/75 pass.
2. Run the gateway with a Discord platform adapter, trigger an agent that calls clarify with 3+ choices. Verify:
   • The user sees a Discord Select menu (not truncated buttons).
   • Picking an option (or "Other" + typing text) resolves the clarify immediately.
   • The ⏳ Still working… hang no longer happens.
3. (Optional) Cross-platform regression: pytest tests/gateway/test_telegram_clarify_*.py tests/gateway/test_clarify_*.py -q — should be unaffected.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)

Why this is the right shape

Discord component limits drove the heuristic:

• Button labels: 80-char cap → fine for "Yes"/"No", useless for descriptions.
• Select menu: 25 options, 100-char label, 100-char description → fits a 4-choice question with a 1-line description per option, plus an "Other" row.

So the public surface stays a normal clarify() call. The change is purely render-path. No other adapters (CLI, TUI, Telegram, gateway) are affected.

Risk

• Low. Single source of truth for normalization lives in tools/clarify_tool.py; the adapter re-normalizes defensively but cannot diverge meaningfully.
• Backward compatible. Sequence[ClarifyChoice] widens List[str]; old string-only callers and the existing callback signature are unchanged.
• No new dependencies. discord.py 2.7.1's existing Select / StringSelect components are used directly.

Demo

A live demo of the rendered Select menu (4 options with descriptions + "Other" row) was sent to the reporter over Discord. The PR description does not link to that DM by design — public PRs should not reference private channel/message IDs (per the project's public-PR-privacy convention).