feat: add runtime reasoning_effort tool for on-the-fly agent reasoning control

[ian-pascoe]

Summary

Add a first-class reasoning_effort tool so Hermes agents can adjust their own reasoning effort on the fly during a session instead of relying on user-only slash commands like /reasoning.

Problem

Hermes already supports reasoning effort through config and chat commands:

• agent.reasoning_effort in config
• /reasoning ... in CLI and gateway chats

But agents cannot reliably use those as structured state transitions.

Today, if an agent realizes a task just became much harder or much simpler, it cannot cleanly say:

• lower reasoning for rote follow-through
• raise reasoning for debugging / cross-file synthesis / hard planning
• persist the new default only when the user explicitly wants that

Trying to fake /reasoning low in chat is brittle and not a real tool interaction.

Proposed change

Add a tool with this shape:

{
  "name": "reasoning_effort",
  "parameters": {
    "level": "none|minimal|low|medium|high|xhigh",
    "persist": false
  }
}

Behavior

• updates the active AIAgent.reasoning_config for subsequent model calls
• optionally persists through the platform layer when persist=true
• returns structured JSON describing the new state

Important implementation detail

This should not be treated as a plain registry-only tool.

Like clarify and delegate_task, it needs access to live AIAgent state and optional platform callbacks. In practice that means:

• normal registry-backed schema in tools/reasoning_effort_tool.py
• discovery import in model_tools.py
• exposure via toolsets.py
• agent-loop interception in run_agent.py so it can mutate self.reasoning_config
• optional persistence callback injected from CLI / gateway instead of importing platform config logic directly into run_agent.py

Why this is useful

This lets agents adapt reasoning cost and depth to the actual work:

• low / minimal for simple lookups, formatting, rote edits, narrow reads
• medium for default non-trivial work
• high / xhigh for ambiguous debugging, hard planning, cross-file reasoning, tradeoff analysis

That makes Hermes more efficient and more agentic.

Docs / prompting follow-up

If added, Hermes should also include tool-aware prompt guidance telling agents when to use the tool effectively and when not to thrash it.

Testing

Suggested coverage:

• tool registration + discovery
• agent-loop interception
• updates to AIAgent.reasoning_config
• none disables reasoning
• invalid level returns JSON error
• persistence callback path
• CLI/gateway regressions

Extra note

The current docs imply adding a tool is a 3-file change, but stateful tools like this end up needing a 4th integration point in run_agent.py. It may be worth clarifying that in the developer docs too.

[trusktr]

For a n00b to AI agents, it is daunting to have to figure out what options to pick. I imagine the most ideal would be the user starts typing, everything else is automatically determined based on the prompts: which model to use (if the chosen provider exposes multiple models), which reasoning effort to use, etc; and only a more experienced user would want to specifically set certain effort levels or models if they know exactly what they are doing.

[israellot]

We implemented this in a downstream fork (YallaPlay) and can confirm the design in this issue is sound — the clarify/delegate_task-style agent-loop interception is exactly right. A few findings that may help whoever picks this up:

1. It's a 5-integration-point change, not 4. The issue notes stateful tools need a 4th point beyond the "3-file" docs. In practice we found a 5th: there are two dispatch paths and both need the explicit branch:

• agent/agent_runtime_helpers.py::invoke_tool (interactive path)
• agent/tool_executor.py::execute_tool_calls_sequential (the quiet / -q one-shot path)

Wiring only the first gives a working interactive session but the inert "<tool> must be handled by the agent loop" stub under -q/gateway, because that path routes unknown _AGENT_LOOP_TOOLS names through handle_function_call, which early-returns the stub. Plus toolsets.py (a TOOLSETS entry and adding the tool to _HERMES_CORE_TOOLS) or you get Warning: Unknown toolsets.

2. Same-turn escalation works — no re-init needed. AIAgent.reasoning_config is re-read on every API call inside the turn loop (agent/chat_completion_helpers.py), not cached per turn. So mutating it mid-turn takes effect on the model's next API call, including the same turn — unlike /reasoning, which sets self.agent = None only because it runs between turns. This makes "call the tool first, then think hard on the same request" actually work.

3. persist — we chose session-only. The proposed shape has persist: true writing through the platform layer. We deliberately made ours session-scoped and never persist (no save_config_value) — a task-local escalation silently rewriting the profile's agent.reasoning_effort for all future sessions felt like a footgun. If persist is kept, it's probably worth defaulting to false and gating the write behind the platform callback as the issue suggests, rather than the tool touching config directly.

4. Cost-model caveat for the prompt guidance. On adaptive-thinking models (current Claude), effort maps to output_config.effort (adaptive) — it's a ceiling, not a floor. Raising it is a quality lever (lets the model think harder when a step warrants it); it does not force spend on easy steps. The real savings direction is lowering the ceiling for rote work, i.e. a low default + escalation. Worth noting in the "when not to thrash it" guidance so users don't expect raising effort to save money. (On non-adaptive/tiered providers it behaves more like a real dial in both directions.)

Design guarantees we kept that seem worth baking in: idempotent no-op when already at the requested level, and provider-honest reporting (some providers ignore/remap — Codex clamps minimal -> low).

Happy to open a PR if there's maintainer appetite. Before that it'd need generalizing our Bedrock/Anthropic effort->wire tests across the other providers, and a decision on whether it should be config-flag-gated / default-off given the self-spend implications.

(Sharing as a downstream fork contributor, not affiliated with Nous.)

[konsisumer]

These issues look like facets of one underlying problem: #7273.

They were grouped by a semantic pass as different symptoms of one underlying problem in comp/agent. A single coordinated fix may resolve them together — flagging for visibility; no action has been taken on the individual issues.

Related, already covered by an earlier root-cause note: #50240 (see the root-cause note on #50240).

Automated root-cause grouping. Reply to correct if these are unrelated.

[GottZ]

This was generated by AI during triage.

Summary

Two PRs address #7273 by adding a structured runtime reasoning_effort tool with live agent-state mutation and optional persistence. #7282 implements the core concept but leaves prompt-stability, gateway session-scope, dispatch-path, test, and scope problems, while #63316 cleanly reimplements the feature across both dispatch paths and all platform persistence surfaces.

Related pull requests

• feat: add runtime reasoning_effort tool for on-the-fly agent reasoning control #7282 partial — (+1921/-1295) — partial fix, superseded by feat: runtime reasoning_effort tool (clean reimplementation of #7282) #63316: it adds the tool schema, registration, live reasoning_config mutation, persistence callbacks, prompting, and tests, but invalidates the lifetime-stable system prompt, loses non-persistent gateway changes on the next message, omits the split runtime dispatch architecture, includes failing guidance assertions, and bundles extensive unrelated browser, SearXNG, updater, and lockfile changes. Despite the keep_open review on feat: add runtime reasoning_effort tool for on-the-fly agent reasoning control #7282, its documented blockers remain visible in the diff and are addressed by the focused replacement feat: runtime reasoning_effort tool (clean reimplementation of #7282) #63316, so it should not be merged as-is.
• feat: runtime reasoning_effort tool (clean reimplementation of #7282) #63316 best fix — (+978/-4) — fixes: it provides the focused runtime tool, intercepts both agent/agent_runtime_helpers.py and agent/tool_executor.py dispatch paths, keeps the system prompt byte-stable, applies the new reasoning_config on the next API request, and preserves session or persisted state across CLI, gateway, and TUI/desktop. The keep_open review on feat: runtime reasoning_effort tool (clean reimplementation of #7282) #63316 identified missing TUI persistence and permanent core-schema footprint; the later diff explicitly addresses both with a tested TUI callback and an opt-in, default-off reasoning toolset.

Duplicates

#7282 and #63316 implement substantially the same runtime reasoning_effort feature; #63316 is the focused, corrected reimplementation that supersedes #7282.

Suggested consolidation

Merge #63316 — it is the verified best fix and addresses the reported root cause while incorporating the contributor review requirements for stable prompts, session-scoped gateway behavior, TUI/desktop persistence, both dispatch paths, and zero default schema footprint. Close #7282 as superseded by duplicate #63316 rather than merging or reopening it over its unresolved contributor-review blockers.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I7273(["issue #7273 (open)"])
    subgraph Dup7282 ["PRs duplicating each other"]
        P7282["PR #7282 (open)"]
        P63316["PR #63316 (open)"]
    end
    P7282 -.->|partial| I7273
    P63316 -->|best fix| I7273
    class I7273 open
    class I7273 target
    class P7282 open
    class P63316 open
    class P63316 best
    click I7273 "https://github.com/NousResearch/hermes-agent/issues/7273"
    click P7282 "https://github.com/NousResearch/hermes-agent/pull/7282"
    click P63316 "https://github.com/NousResearch/hermes-agent/pull/63316"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed or no verify verdict yet (state tag in the node label).

Cross-PR triage: Reviewed 2 pull requests and 1 issue in this complex. Each diff was read against this issue; Assessment working set: 266 kB of PR diffs, 8 kB of issue/PR text, 9 kB of discussion (10 comments), 4 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.