Hermes host skills should use clarify instead of AskUserQuestion
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## Problem
Generated Hermes-host GStack skills still tell agents to use `AskUserQuestion`, but Hermes Agent's native interactive-question tool is `clarify`.
That means a Hermes user running generated GStack skills gets one of two bad paths:
1. the agent tries to call a tool that does not exist in Hermes, then falls back to prose, or
2. the agent treats `AskUserQuestion` as a concept instead of using Hermes' actual question card surface.
The current prose fallback is useful for hosts with no question tool, but Hermes does have one. We should route the host-specific question instruction to `clarify` instead of degrading to markdown prompts.
## Max / Hermes use case
Max runs GStack inside Hermes as a real daily workflow, including `/autoplan`, `/review`, `/ship`, and issue-discovery lanes. These skills rely heavily on decision gates. In Hermes CLI/gateway sessions, those gates should use the native `clarify` tool so options render as proper interactive choices instead of plain prose asking the user to reply with a letter.
This matters most in long-running GStack workflows where questions are safety gates: telemetry consent, routing injection, vendoring migration, premise gates, destructive confirmations, and taste decisions.
## Evidence inspected
Upstream `main` at `c7ae6320` (`2026-06-14T18:40:57Z`) via GitHub API:
- `hosts/hermes.ts` rewrites Claude tool names for Bash/Read/Write/Edit/Agent/Grep/Glob, but has no rewrite for `AskUserQuestion` → `clarify`.
- `scripts/resolvers/preamble/generate-ask-user-format.ts` emits a full `AskUserQuestion` contract, including: prefer `mcp__*__AskUserQuestion`, call AskUserQuestion as tool_use, and use prose fallback when unavailable.
- README documents Hermes as a supported generated host: `| Hermes | --host hermes | ~/.hermes/skills/gstack-*/ |`.
- CONTRIBUTING says each host config controls host-appropriate tool names and paths.
- Official Hermes docs, `https://hermes-agent.nousresearch.com/docs/reference/tools-reference`, list `clarify` as a built-in Hermes tool. The same page contains no `AskUserQuestion` mention.
Local reproduction on the GStack checkout also showed `bun run gen:skill-docs --host hermes --dry-run` producing `.hermes/skills/*/SKILL.md` files with many `AskUserQuestion` references.
## Expected behavior
For `--host hermes` output, generated skill docs should instruct Hermes agents to use `clarify` for interactive user decisions.
A Hermes-specific rendering could be something like:
- `Use AskUserQuestion:` → `Use the clarify tool:`
- `AskUserQuestion options:` → `clarify choices:`
- adjust the generic fallback text so Hermes does not prefer prose fallback when `clarify` is present
- preserve the existing prose fallback for genuinely headless/no-question-tool hosts
## Suggested implementation shape
I would probably do this in the host/resolver layer, not by manually editing generated files:
1. Add a Hermes-specific tool rewrite or resolver branch for the AskUserQuestion contract.
2. Map up to 4 AUQ options onto `clarify` `choices`.
3. For open-ended AUQ prompts, call `clarify` without `choices`.
4. Add a regression test that generated Hermes output contains `clarify` guidance and does not require `AskUserQuestion` as the primary tool path.
5. Keep existing tests around Codex/Conductor AUQ fallback intact.
## Duplicate search performed
I searched at least 200 open and 200 closed issues/PRs before filing:
- `gh issue list --repo garrytan/gstack --state open --limit 200`
- `gh issue list --repo garrytan/gstack --state closed --limit 200`
- `gh pr list --repo garrytan/gstack --state open --limit 200`
- `gh pr list --repo garrytan/gstack --state closed --limit 200`
- targeted searches for: `AskUserQuestion Hermes`, `Hermes clarify`, `Hermes AskUserQuestion clarify`, `generated Hermes skills AskUserQuestion`, `missing AskUserQuestion`, `tool rewrites AskUserQuestion`, `question fallback Hermes`, `host hermes generated skills`
Closest related items, but not covering this exact Hermes-native-tool mismatch:
- #1201 / #1267 / PR #1494 cover whether `./setup --host hermes` is a banner vs installer.
- #1077 covers Hermes generated path/prefix mismatches.
- PR #1556 and PR #1908 add no-tool / runtime-failure prose fallback for `AskUserQuestion`.
- PR #1818 is Codex-specific missing-AUQ handling.
- PR #1935 fixes Agent-tool phrasing rewrites across runtime hosts.
- #2006 / PR #1924 cover `permissionDecision: "defer"` interrupting AUQ cards.
None appear to cover: Hermes has a native question tool named `clarify`, but generated Hermes GStack skills still point at `AskUserQuestion` first.
## Willingness to contribute
Happy to contribute the host-specific rewrite/test once maintainers confirm the desired mapping from GStack's AUQ decision brief format onto Hermes `clarify` choices.
Contributor guide
Assessment
This issue has not been assessed yet.