feat(hitl): generic ask_user_via_form capability for selected reasoners

[AbirAbbas]

Summary

Generalizes the existing Phase 1.5 plan-approval gate into a reusable
ask_user_via_form substrate. Three reasoners (run_product_manager,
run_issue_advisor, run_replanner) can now emit an ask_user_form
field in their structured output; when populated, the workflow pauses
on the control plane (real app.pause, hours/days if needed) until the
user submits, then re-invokes the reasoner with the answers in
prior_user_responses.

Why

The existing HITL surface is exactly one moment — Phase 1.5 plan approval.
Everywhere else the agent silently picks a default when the right
answer hinges on user judgment (which failing acceptance criteria are
acceptable as debt? abort or reduce scope? which of multiple plausible
goal interpretations?). This adds an opt-in way for the LLM itself to
escalate those cases.

What's in this PR

New substrate — swe_af/hitl/:

• AskUserForm / AskUserFormField — Pydantic spec the LLM emits. Covers
  all FormBuilder field types (input, textarea, number, slider, select,
  radio, checkbox, checkbox_group, switch, date).
• build_form_builder(spec) — translates the spec into hax.FormBuilder.
• request_user_input_and_pause(...) — sends form via create_request(type="form-builder")
  (wrapped with the same 120s hard timeout the plan-approval gate uses),
  then await app.pause(...), then parses the response into AskUserResponse.
• run_with_ask_user(...) — generic reasoner wrapper that loops on
  ask_user_form output, threading prior_user_responses back into each
  subsequent invocation. Budget-capped (AskUserBudget) and max-iteration-capped.
• format_prior_user_responses(prior) — renders accumulated answers as
  a markdown block so the LLM doesn't re-ask questions already answered.
• build_hax_client_from_env() / approval_webhook_url(app) — env-driven
  plumbing so each reasoner self-configures.

Initial allowlist (each reasoner gets ask_user_form schema field + prompt guidance):

• run_product_manager — for fundamentally ambiguous goals where two
  interpretations would yield very different PRDs.
• run_issue_advisor — for RETRY_MODIFIED vs ACCEPT_WITH_DEBT trade-offs
  and which failing acceptance criteria are acceptable as debt.
• run_replanner — for ABORT (project-level judgment) and REDUCE_SCOPE
  vs MODIFY_DAG (user's appetite for partial delivery).

Each reasoner caps itself at 2 ask iterations per invocation. Across a
build, total asks are bounded by call-site count (each reasoner
invocation has its own budget — cross-reasoner sharing wasn't feasible
because run_issue_advisor / run_replanner are invoked across
reasoner boundaries via app.call()).

Dependency bump: hax-sdk>=0.2.0 → >=0.2.4 in
requirements.txt, requirements-docker.txt, and pyproject.toml.
Docker pip cache keys on the constraint string; without the floor bump,
cached layers keep installing whatever was first resolved. FormBuilder
and create_form_request were already in 0.2.0; this is purely cache
invalidation.

What this PR does NOT change

• The existing Phase 1.5 plan-approval gate (type="plan-review-v2").
  Stays as-is; runs alongside the new substrate.
• Default behavior when HAX_API_KEY is unset. build_hax_client_from_env
  returns None; the wrapper short-circuits. Pipeline behavior is
  identical to main.
• Tool calls to the Claude Code harness. We kept the schema-output path
  (LLM emits ask_user_form in its structured response) rather than
  migrating to mid-turn tool calls, because the workflow pause is
  durable (hours/days) and a mid-turn tool would have to hold the LLM
  conversation open across that interval.

Test plan

• python -m pytest tests/test_ask_user.py — 17/17 pass locally
• python -m pytest tests/test_hax_create_request_timeout.py — 52/52 still pass
• ruff check swe_af/hitl/ tests/test_ask_user.py <touched reasoner/prompt/schema files> — clean
• No regressions across 162 planner/advisor/replanner/dag tests
• Verified ruff error count vs origin/main — net zero new findings
• CI green on this PR
• Manual smoke test with HAX_API_KEY set: LLM emits ask_user_form, form renders in Hub, submit, reasoner resumes with answers in prior_user_responses (deferred to follow-up — requires a live Hax + control plane)

Files touched

• requirements.txt, requirements-docker.txt, pyproject.toml — pin bump
• swe_af/hitl/{__init__,ask_user,wrapper}.py — new
• tests/test_ask_user.py — new
• swe_af/reasoners/schemas.py — PRD.ask_user_form field
• swe_af/execution/schemas.py — IssueAdvisorDecision.ask_user_form, ReplanDecision.ask_user_form
• swe_af/reasoners/pipeline.py — run_product_manager runs through run_with_ask_user
• swe_af/reasoners/execution_agents.py — run_issue_advisor and run_replanner likewise
• swe_af/prompts/{product_manager,issue_advisor,replanner}.py — when-to-ask guidance + prior_user_responses threading

🤖 Generated with Claude Code

[AbirAbbas]

Manual validation (local, Tier 3 — live LLM)

Exercised the real LLM path on a local control plane + Hax:

• ✅ PM emitted ask_user_form on a deliberately ambiguous goal.
• ✅ run_with_ask_user built the Hax form and called app.pause; the workflow suspended and the pause cascaded to the parent plan/build executions (all waiting).
• ✅ Form rendered in the Hax Hub and was submitted.
• ⏸️ Resume-after-submit was not closed in this setup: the hosted Hax couldn't deliver its webhook to the local (non-public) control plane. The agent-side pause + form-creation path is confirmed here; the webhook→resume hop is exercised in feat(hitl): environment scout — negotiate scoped credentials before architecture #78's validation (same shared substrate), where a signed webhook was relayed to the CP and the reasoner resumed cleanly.

Budget cap (2 asks/reasoner) + max-iteration behavior remain covered by the 17 unit tests. CI green.