"""ask_clarification 工具参数的共享解析（Harness + Gateway）。

圆桌 Step 1（``intent.py``）与 Step 2 总控（``multi_agent.py``）在 SSE 终态帧里
都会带上 ``allow_multiple``，供前端 ``resolveAllowMultiple`` 决定选项卡片是
「点击即发送（单选）」还是「多选 + 发送按钮」。

约定（与前端 ``roundtable-planning/lib/clarification.ts`` 一致）：
- 模型**未传** ``allow_multiple`` 或传 ``null`` → **False**（单选）；
- 仅当模型显式传 ``true`` 时才多选；
- 不再根据 ``clarification_type`` 推断多选（旧逻辑已移除）。
"""

from __future__ import annotations


def coerce_bool(value: object | None, *, default: bool) -> bool:
    """把 LLM tool args 里可能出现的 bool/数字/字符串统一成 bool。"""
    if value is None:
        return default
    if isinstance(value, bool):
        return value
    if isinstance(value, (int, float)):
        return bool(value)
    if isinstance(value, str):
        lowered = value.strip().lower()
        if lowered in ("true", "1", "yes", "y", "on"):
            return True
        if lowered in ("false", "0", "no", "n", "off"):
            return False
    return bool(value)


def resolve_allow_multiple(args: dict) -> bool:
    """是否允许多选。仅 ``args["allow_multiple"]`` 显式为真时返回 True。"""
    if "allow_multiple" in args and args["allow_multiple"] is not None:
        return coerce_bool(args["allow_multiple"], default=False)
    return False