Agent tools
The agent gets two tools. No skill or instruction file is required, because the tool descriptions carry their own guidance.
| Tool | Arguments | Returns |
|---|---|---|
coach_ask | question (required, ≤ 4000 chars), intent (advice, plan, review), context (≤ 4000 chars) | Advice text, or {ok: false, error} |
coach_decide | question (required), options (2–6 strings), state (object) | {decision, confidence, probabilities, gate, rationale} |
turn_id and session_id are optional host hints used for per-turn caps and the child-session refusal. The agent does not need to send them, and the dispatcher overrides them if it does.
A consult is one model call. The ledger is capped at 3500 tokens and replies at 400 by default.
Decide backends
| Backend | Model | Billing |
|---|---|---|
jev-openrouter (default) | typesafe/jev-1.14 through OpenRouter | OPENROUTER_API_KEY |
jev-direct | TypeSafe’s API | TYPESAFE_API_KEY in ~/.hermes/.env |
chat-model | Any chat model that returns JSON | Self-reported confidence, and less reliable |
gate is act at or above the configured confidence threshold and escalate below it. An answer that cannot be parsed also escalates, rather than guessing.
The /coach command
| Command | Effect |
|---|---|
/coach status | Model, modes, spend and pending notes |
/coach last [n] | The last advice, or the last n, for this session |
/coach log [n] [full] | Recent reviews and decisions: turn, time, body, evidence, fix, question and options |
/coach active on|off|pre|post|both | Per-turn review; a timing word also switches the mode on |
/coach review on|off | Completion review |
/coach decide on|off | The decide tool |
/coach model [mode] | Show or set a model |
/coach set <key> <value> | Any setting, by name |
/coach guidance | Both guidance paths and whether they exist |
/coach pending | List held advice |
/coach send | Release held advice now |
/coach pause | Pause background reviews for this session |
/coach grant / revoke | Write or clear the model-override permission |
/coach forget | Delete this session’s coach state |
Unknown input prints the full help. A handler exception becomes a one-line error rather than a broken session.
Cards, notes and logs
Each review finding and decision is posted as a card in the conversation and written as one line in $HERMES_HOME/coach/logs/<session>.jsonl: timestamp, kind, severity, title, body, evidence and fix. Decisions also carry the question, options and rationale.
A card is a host notification and cannot carry buttons. The one-click path lives on the Desktop page: under Status → Recent reviews, every finding has a Send to chat button that puts it in the composer. From the CLI, /coach send does the same.
Where the model reads it: review and Active findings become <coach-note> blocks at the start of its next turn, and a blocked completion is a message inside the current turn. Consult advice is the tool result itself, which the agent is asked to relay.