# Questionnaire

PiCraft 的主动意图澄清工具。主 Agent 在已经检查代码、配置、文档和现有约定后，如果仍有会实质影响范围、行为、兼容性或不可逆决策的歧义，可以调用 `questionnaire` 批量询问用户。

## 行为

- 每题支持单选或多选，并始终提供自由输入；自由输入不需要模型传递额外开关。
- 选项描述会按终端宽度自动换行，并保留输入中的显式换行。
- 最多批量询问 4 个相关问题；TUI 使用问题标签页和最终 Review 页。
- 用户可以保留未回答项；结果会明确返回 `Unanswered`，不会伪装成用户选择。
- 结构化结果将预定义选择写入 `selectedOptions`，自由输入单独写入 `customInput`。
- 不设置超时或自动选择，避免错误归因用户意图。
- Escape 或 Abort 会结束当前询问；同一轮不会立即重复弹出问题。
- 仅 Pi TUI 启用该工具。RPC、JSON、Print 和独立 Subagent 会停用；Subagent 应把关键歧义返回父 Agent。

## 调用原则

`questionnaire` 只处理无法从仓库事实推导、且确实需要用户权衡的选择。可逆细节或多个方案都可接受时，Agent 应采用保守、常规的默认值继续执行。

每题最多 5 个预定义选项。UI 会自动增加自由输入入口，模型不应自行添加 `Other`；纯开放题使用空选项数组，并且不能设置推荐索引。