fix(interactions): accept intuitive ask_user_questions payload shape

[sagiw]

Thinking Path

• Paperclip is the open source app people use to manage AI agents for work
• Agents ask the human questions through the ask_user_questions interaction, sent to POST /api/issues/:id/interactions and validated by askUserQuestionsPayloadSchema in packages/shared (shared by both the HTTP route and the MCP tool)
• The schema required option objects { id, label } and a mandatory selectionMode, but agents (including the built-in CTO/orchestrator) naturally send options as plain strings and omit selectionMode — the shape of Claude's own AskUserQuestion tool
• Every such request was rejected with 400, so the questions silently never reached the user; observed in the wild as an orchestrator looping on 400 while asking for staging deploy sign-off
• This pull request normalizes the intuitive shape instead of rejecting it, and makes selectionMode optional with a "single" default
• The benefit is that agents reliably reach the human for approval instead of failing silently, with no change for callers already sending the canonical shape

Linked Issues or Issue Description

No public GitHub issue exists; the underlying bug is described inline below.

What happened?
Agents send ask_user_questions payloads with options as plain strings and no selectionMode (Claude's own AskUserQuestion tool shape). askUserQuestionsPayloadSchema required option objects { id, label } and a mandatory selectionMode, so POST /api/issues/:id/interactions returned 400 and the questions never reached the user. An orchestrator was observed repeatedly hitting this 400 while asking a human for staging deploy authorization.

Expected behavior
The intuitive payload shape is accepted and normalized to the canonical form, so the questions reach the user. Canonical object-shaped payloads keep validating exactly as before.

Steps to reproduce

1. Send POST /api/issues/:id/interactions with an ask_user_questions payload whose options are strings (e.g. ["Yes", "No"]) and with selectionMode omitted.
2. Before this fix: the request is rejected 400 and no prompt is shown to the user.
3. After this fix: the payload parses, options become { id, label } with a slugified id, and selectionMode defaults to "single".

What Changed

• packages/shared/src/validators/issue.ts: askUserQuestionsQuestionOptionSchema now preprocesses string options into { id, label }, slugifying id from the label; object options missing an id also get a slugified id.
• packages/shared/src/validators/issue.ts: selectionMode is now optional() and defaults to "single".
• Duplicate-option-id and duplicate-question-id protection is preserved (duplicate slugified ids are still rejected).
• packages/shared/src/validators/issue.test.ts: added tests for string-shape normalization, canonical-shape pass-through, and duplicate-id rejection after normalization.

Verification

• cd packages/shared && npx vitest run src/validators/issue.test.ts → 35/35 pass, including the 3 new askUserQuestionsPayloadSchema cases.
• The exact previously-400 string-shape payload now parses; options normalize to { id: "yes-ship-it", label: "Yes, ship it" }; selectionMode defaults to "single".

Risks

Low risk. The change is purely additive and backward-compatible: canonical object-shaped payloads validate identically, and duplicate-id protection is unchanged. There is no database migration and no change to stored data.

Model Used

Claude Opus 4.8 (claude-opus-4-8), via Claude Code, with tool use and code execution.

Checklist

• I have included a thinking path that traces from project context to this change
• I have specified the model used (with version and capability details)
• I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
• I have searched GitHub for duplicate or related PRs and linked them above
• I have either (a) linked existing issues with Fixes: # / Closes # / Refs # OR (b) described the issue in-PR following the relevant issue template
• I have not referenced internal/instance-local Paperclip issues or links (only public GitHub #NNN / github.com/paperclipai/paperclip URLs)

[commitperclip]

✅ All checks passing — ready for Greptile review and maintainer approval.

— commitperclip