Finish Agent Questions (ACP Elicitations) — OpenAPI, Tests, E2E and Live Verification

[lukemarsden]

Finish the feature described below. Most of it is already committed on the branch you are starting on — read it before writing anything.

Finish the agent-questions (ACP elicitation) feature — it is ~70% built already

This continues task 002731, whose sandbox lost its agent connection permanently before the
work could be finished. All of the code that exists is already committed and pushed to
the project git server on the branch feature/002731-end-to-end-agent in both the helix
and zed repos. You are starting on that branch. Do not re-implement any of it; read it
first, then finish the remaining items.

Run this before anything else, in both repos, and read what is there:

git log --oneline -3
git show --stat HEAD

• helix: 0cc5290ce (design doc) on top of 9ddbd5d74 "feat(api): record and answer
  agent questions from ACP elicitations" — 2492 insertions across 23 files.
• zed: 8fbf40ad92 "feat(external_websocket_sync): mirror ACP elicitations to Helix and
  accept answers" — 629 insertions across 4 files.

The full design lives in design/2026-08-11-agent-questions-elicitation.md (committed) and
in design/tasks/002731_*/{requirements,design,tasks}.md in the helix-specs repo. Those
were reviewed and approved; follow them.

What the feature is

Claude Code asks the user a question mid-turn via its built-in AskUserQuestion tool. The
claude-agent-acp adapter turns that into an ACP form elicitation and blocks the turn
until the client answers. Helix could not see or answer those questions at all —
crates/external_websocket_sync/ dropped AgentThreadEntry::Elicitation on the floor, and
grep -rn elicitation api/ returned nothing. The committed work adds: the Zed→Helix sync
events, a respond_elicitation command back to Zed, an agent_elicitations store, a REST
endpoint, and a React card that renders the question's options and submits an answer.

The Zed agent panel's own elicitation UI is known-broken and deliberately staying broken
(it draws the card with no option controls and no text field). Helix must work without it.
Do not fix it, do not depend on it, and do not rebase Zed onto upstream.

What is left — this is your whole job

1. ./stack update_openapi has never been run, and the frontend cannot build without it.
   frontend/src/services/elicitationService.ts imports TypesElicitationRespondResponse
   and calls client.v1SessionsElicitationsRespondCreate / v1SessionsElicitationsDetail,
   but grep -c "v1SessionsElicitationsRespondCreate" frontend/src/api/api.ts returns 0.
   Regenerate and commit the generated files, then confirm cd frontend && yarn build is
   clean.

2. Go tests. None exist yet. Write them in the suite.Suite + gomock style of
   api/pkg/server/websocket_external_agent_sync_test.go, covering: the
   elicitation_requested / elicitation_resolved / elicitation_resync /
   elicitation_response_ack handlers; the REST endpoint's auth and 404/403/409 paths; two
   clients answering at once; an answer arriving after cancel; the empty-request_id
   fallback; reconnect-does-not-cancel and resync-absence-does-cancel-after-grace; and
   TestAutoWake_SkipsInteractionBlockedOnUserQuestion. Run them.

3. E2E phase. Add Phase 17 to
   zed/crates/external_websocket_sync/e2e-test/helix-ws-test-server/main.go:
   elicitation_requested (assert a non-empty schema) → respond_elicitation →
   elicitation_resolved(accepted) → message_completed for the same turn. Drive it
   through the synthetic seam — do not make a CI phase depend on the model choosing to
   call a tool; say so in the phase comment. Then run the full dockerized suite
   (./run_docker_e2e.sh) and see it green. CLAUDE.md is absolute on this: if you touch
   the e2e tests you must run them. "It compiles" and "it follows the pattern" are not
   evidence.

4. sandbox-versions.txt — bump ZED_COMMIT to your final zed commit.

5. Live end-to-end verification in this inner Helix, with screenshots. This is the part
   that actually proves the feature and it has never been done:

   • get an agent to call AskUserQuestion;
   • the question renders in the Helix UI with every option — screenshot;
   • answer it in Helix, the turn resumes reflecting that answer — screenshot;
   • then the next operation: a normal follow-up message is delivered and answered, and a
     second question in the same session works;
   • the decline path settles cleanly;
   • a question left unanswered and then interrupted from Helix settles and stops being
     answerable.

   If any of these fail, fix them or say plainly which ones do not work. Do not report the
   feature as done on the strength of unit tests.

Then ship it

Merge order from CLAUDE.md, exactly: commit in zed (do not push yet) → git rev-parse HEAD
→ bump ZED_COMMIT in sandbox-versions.txt → open the Helix PR first → push the zed
branch and open its PR with gh pr create --repo helixml/zed → CI green on both → merge zed
first, then helix. Rebase if ZED_COMMIT has moved.

Environment warnings, learned the hard way on the last attempt

• The previous sandbox's agent connection died and never came back, taking a six-hour turn
  with it. Commit and push early and often — every meaningful chunk of work, pushed to
  the project git server. Do not accumulate hours of uncommitted work.
• Do not use long blind sleeps (the last attempt sat in sleep 540 waiting on a build).
  Poll in a loop with a short interval so you notice a build that finished or died.
• Builds here are heavy and the box is shared. Prefer targeted go build ./pkg/... and
  package-scoped tests over full-workspace builds where you can.

---

🔗 Open in Helix

📋 Spec:

• Requirements
• Design
• Tasks

🚀 Built with Helix

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[nessie993]

Superseded by the merged transport in #95 and the merged Helix implementation in helixml/helix#3220. Closing to keep one maintained implementation path.