Hermes Agent's Clarify Tool Asks Up to Five Questions in One Call
Hermes Agent's clarify tool now accepts an optional questions array, letting the agent ask two to five independent questions in a single call instead of one question per call. The change landed in PR #89467 by ethernet, merged August 19, 2026. It touches 35 files with 3,073 additions and 48 deletions.
The round-trip problem
Before this change, the agent asked one question per call. Each additional question cost a full round-trip between the agent and the user. When the agent needed two or three independent answers, the only workaround was to concatenate them into a single composite question with composite choices, where each choice encoded answers to every sub-question at once. The feature request in issue #18450 quantifies the failure mode:
This does not scale: 2 questions x 4 choices each = 16 composite options; 3 questions x 3 choices each = 27.
The composite approach forced unnatural combined choices like "Feeling good, likes blue" and "Feeling tired, likes red," where a single option had to encode answers across unrelated dimensions. The issue's example is an agent asking about approach preference (A vs B) and availability timeline at the same time, two independent axes that the composite format could not represent cleanly.
What the batching changes
The clarify tool keeps its existing single-question parameter and adds a questions array alongside it. Each question object carries its own question text and an optional choices list of up to four options. When questions is present, it takes precedence and the single-question parameter is ignored.
The round-trip math is the headline number. Asking N questions previously required N calls. Now it requires one:
| Questions asked | Calls before | Calls after |
|---|---|---|
| 2 | 2 | 1 |
| 3 | 3 | 1 |
| 5 (max) | 5 | 1 |
At the maximum of five questions, the tool reduces agent-human round-trips from five to one, an 80% reduction.
Answer flow across surfaces
The three interactive surfaces handle the batch differently:
- Desktop renders one card with every question. Answers stage locally, and a single "Confirm and continue" button submits the whole batch once every question has an answer.
- TUI and CLI render a compact status list with a checkmark for answered, an arrow for active, and a dot for pending. Enter locks the active answer and advances; Tab and Shift-Tab cycle in both directions.
- Messaging platforms fall back to the existing single-question prompt, one question at a time. If the user stops responding, the remaining questions are not sent.
Partial answers survive timeouts
The PR handles the timeout case explicitly. If the prompt times out part-way on the TUI or CLI, answers the user already locked are kept. The tool result carries them with a timed_out flag, and unanswered entries stay blank. This lets the agent tell a deliberate skip from an absent user.
The wire protocol uses one clarify.request carrying the question list with server-generated per-question ids. clarify.respond gains an optional question_id that locks or overwrites a single answer, while a respond without question_id keeps its existing cancel meaning. The reconnect replay snapshot carries locked answers, so a reattached client restores its state. The PR notes this update-in-place shape leaves room for a follow-up that persists interim answers in the session database.
Backward compatibility and a hydration fix
The single-question path is byte-identical to the previous behavior on every surface, so existing callers are unaffected.
The PR also fixes a duplicate-card bug found during testing. The desktop hydration-race merge correlated the tool.start row and the clarify.request row through the top-level question text, which a batch payload does not have, so the batch card mounted twice. The correlation key for a batch now comes from the joined per-question texts.
[^1]: ethernet. "feat(clarify): ask multiple independent questions in one call." GitHub. 2026-08-19. [^2]: ethernet. "Feature: Support multiple independent questions in clarify tool." GitHub.