Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / agent-tools-and-guardrails

Agent tools and guardrails

Agent tools turn a model decision into a bounded action and a result that can safely return to the next model step. The tool system discovers only usable capabilities, checks calls before execution, asks for consent when needed, limits access to terminals and browsers, and stops repeated or unsafe work. This page is a child of Agent runtime and relates to Agent turn execution, Model provider integration, and Context, memory, and compression.

Tool capability model

Tool registry and availability

The tool registry is the common capability directory for built-in tools, MCP tools, and plugin tools. Each tool exposes a model-facing schema, an execution handler, a toolset, and an optional availability check. Toolsets let each session receive only the capabilities that fit its platform, configuration, credentials, and safety needs. A failed availability check removes the tool from the model's view rather than advertising a capability that cannot work.

The registry also protects tool identity. Cross-toolset name collisions are rejected unless an explicit, operator-approved override is in use. Handler results are normalized to supported JSON or multimodal forms, and errors are bounded before they enter model context.

References: tools/registry.py• L181-197 tools/registry.py• L666-743 tools/registry.py• L843-921

Progressive tool discovery

Tool Search keeps large or optional capability sets out of the fixed model prompt while keeping them discoverable. The model searches a session-scoped catalog, loads the schema for a selected tool, and then calls it through a bridge. Direct core tools remain available unless an explicit deferral rule names them.

The bridge does not weaken normal controls. A deferred call is checked against the current session's tool grant and concrete schema before it is unwrapped to the real tool name. Local calls run one at a time through the normal agent path; connector calls can use the supported remote batch path.

flowchart LR
    A[Session tool grants] --> B[Visible tool schemas]
    A --> C[Deferred tool catalog]
    C --> D[tool_search]
    D --> E[tool_describe]
    E --> F[tool_call]
    F --> G[Scope and schema checks]
    G --> H[Real tool dispatch]

References: tools/tool_search.py• L1-7 tools/tool_search.py• L149-178 tools/tool_search.py• L350-385 tools/tool_search.py• L557-586 tools/tool_search_validation.py• L74-137

Tool dispatch and result boundary

Call validation and dispatch

Tool dispatch converts a model tool call into one controlled execution while preserving the call's session, task, turn, and provider identity. The path canonicalizes legacy names, parses arguments, applies request middleware, runs pre-call hooks, enforces session scope, and then invokes the registered or agent-level handler. Agent-level tools such as memory, planning, session search, and delegation are handled where the agent owns their state.

Invalid names and malformed arguments do not become arbitrary execution. The turn loop repairs known name mistakes, returns tool-role errors for invalid calls, retries bounded argument errors, and ends with a partial result when the model continues to emit invalid calls. This keeps provider message order valid while giving the model a useful recovery signal.

References: model_tools.py• L605-641 model_tools.py• L703-749 model_tools.py• L872-965 agent/turn_tool_validation.py• L72-229

Result validation and context budget

Every completed call produces a result that the agent can classify, persist, and send back to the model. The system records tool progress before publishing it, marks errors and blocked calls separately, and prevents unsupported handler return types from crossing the registry boundary.

Large results are stored outside the active conversation with a bounded preview and a path for later reading. If the combined tool results still exceed the turn budget, the largest text results are spilled first. Repeated byte-identical results can become references to an earlier result, but the original call still runs when polling or other repeated work is valid.

References: tools/registry.py• L875-921 tools/tool_result_storage.py• L264-334 tools/tool_result_storage.py• L359-390 agent/tool_guardrails.py• L438-489 agent/tool_executor.py• L1061-1092

Dangerous action approval

Approval is the consent gate for commands and other actions that may cause destructive or irreversible effects. The gate checks hard blocks and operator deny rules before any bypass, then uses session approvals, an interactive prompt, a gateway approval queue, or an unattended-session policy. Silence, timeout, withdrawal, delivery failure, and explicit denial fail closed; the model receives instructions not to retry the same action through another form.

Approvals can apply once, for the session, or permanently for recognized command patterns. Permanent approvals belong to the active profile. Smart approval may review a flagged command, but an automatic denial can escalate to a circuit breaker and a human override remains one-operation consent.

References: tools/approval.py• L44-66 tools/approval.py• L139-190 tools/approval.py• L351-392 tools/approval.py• L654-736 tools/approval.py• L927-997

Protected writes

File writes have separate protection because a write can change future agent behavior or security settings. The system refuses sensitive system paths and the active Hermes configuration. It always asks before changing project instruction files such as AGENTS.md, CLAUDE.md, SOUL.md, .cursorrules, or matching protected paths, and it does not allow this protection to be bypassed by unattended execution or a broad approval mode.

The write path also rejects plain-text replacement of binary documents, SQLite sidecars, and uncertain remote targets. Before a whole-file overwrite, it checks that the task saw a current full baseline or uses a targeted patch instead.

References: tools/file_tools_write_guards.py• L146-173 tools/file_tools_write_guards.py• L176-252 tools/file_tools_write_guards.py• L259-355 tools/file_tools_write_guards.py• L480-544 tools/file_tools_write_guards.py• L554-609

Terminal execution controls

Terminal environments

The terminal tool gives the agent a shell in a selected execution environment. Local, remote, container, and cloud backends provide different isolation and persistence choices, while the agent-facing contract stays the same: a command has a task-scoped working directory, timeout, output, and process identity.

The environment choice affects which safety checks can be skipped. Isolated backends can reduce host risk, but host-mounted Docker paths keep dangerous-command checks active. Task and profile scoping prevent one session from inheriting another session's working directory, credentials, or sandbox.

References: tools/terminal_tool.py• L1-18 tools/terminal_tool.py• L376-531 tools/terminal_tool.py• L583-612 tools/approval.py• L1000-1014

Command and process controls

Before a command runs, the terminal path validates the working directory, rejects attempts to manage the supervised gateway from inside itself, and detects shell patterns that should be managed as background work. Dangerous commands go through the approval gate before the environment executes them. Foreground time limits and managed process handles stop a long or detached command from becoming an untracked child.

Terminal environments are created on demand, kept alive only as long as their task needs them, and cleaned by explicit teardown or an idle reaper. Background results are retained as bounded, redacted receipts so a completed process can be recovered without re-running it. A failed environment is evicted so later calls do not reuse a dead connection.

References: tools/terminal_tool_guards.py• L38-47 tools/terminal_tool_guards.py• L135-141 tools/terminal_tool_guards.py• L178-263 tools/terminal_tool.py• L1018-1051 tools/terminal_tool_lifecycle.py• L143-181 tools/terminal_tool_lifecycle.py• L250-330

Browser controls

Browser sessions and navigation safety

Browser tools provide a task-scoped session for navigation, page inspection, and input. The browser can use local or remote execution, and private URLs may use a local sidecar when the configured routing allows it. Successful navigation establishes the session used by later clicks, typing, snapshots, and evaluation.

Navigation applies several safety floors before and after a request. URLs that contain likely Hermes secrets are rejected. Cloud metadata endpoints are always blocked. Private or internal addresses are blocked for remote browser paths unless an explicit local route or policy allows them. The final redirected URL is checked again, and a blocked page is cleared before later tools can read it.

References: tools/browser_tool.py• L47-77 tools/browser_tool.py• L317-366 tools/browser_tool.py• L630-681 tools/browser_tool.py• L691-710 tools/browser_tool.py• L742-794

Browser input and evaluation

Browser actions use references from the current accessibility snapshot so the model acts on visible page state. Input actions and content reads verify that the current page still belongs to the allowed address class. Browser output and typed text are redacted before they appear in progress or conversation data.

JavaScript evaluation has two distinct controls. The private-network check blocks expressions that target unsafe URLs, while an optional sensitive-primitive policy can reject access to cookies, storage, credentials, form values, or network APIs. A page that navigates to a private address during evaluation is treated as unsafe before its content is returned.

References: tools/browser_tool.py• L817-848 tools/browser_tool.py• L875-914 tools/browser_tool.py• L956-1014 tools/browser_tool_eval_policy.py• L15-69 tools/browser_tool_eval_policy.py• L92-151

Execution recovery and stopping

Repeated-call guardrails

The per-turn tool guardrail controller detects work that repeats without progress. It tracks exact failed calls, repeated failures on one tool, unchanged results from read-only tools, identical call-and-result streaks, repeating multi-call cycles, and per-turn caps on web searches and subagent spawns. A successful mutation resets the relevant failure history because it creates a new state to test.

Warnings add recovery guidance to the tool result. Configured hard stops return a synthetic tool result or halt the turn, with unattended platforms using a stricter default. Polling tools remain exempt from the duplicate-call notice when unchanged polling is a valid wait operation.

References: agent/tool_guardrails.py• L20-85 agent/tool_guardrails.py• L100-152 agent/tool_guardrails.py• L307-373 agent/tool_guardrails.py• L375-433 agent/tool_guardrails.py• L438-561

Interrupts, timeouts, and durable turns

The execution layer treats interruption, timeout, and persistence failure as distinct outcomes. It can abandon a non-cooperative worker, synthesize a cancelled or timed-out result, and interrupt tracked worker threads without treating a late result as a second completion. Approval waits extend the tool deadline within a bounded policy so a real user response is not cut off, while a wedged approval or plugin path cannot hold the batch forever.

The agent persists the assistant tool-call block before side effects and persists each result before the next model call. If either durable write fails, the turn stops instead of sending process-only state back to the model. This prevents a restart or resume from losing the record of an action that already ran.

sequenceDiagram
    participant M as Model
    participant V as Turn validation
    participant P as Durable session state
    participant G as Guardrails and approval
    participant T as Tool
    M->>V: Tool calls
    V-->>M: Repair or tool-role error when invalid
    V->>P: Store assistant tool-call block
    P-->>G: Durable execution record
    G->>G: Scope, safety, and consent checks
    alt Allowed
        G->>T: Execute once
        T-->>P: Store bounded result
        P-->>M: Tool result for next round
    else Blocked or timed out
        G-->>P: Store refusal or cancellation
        P-->>M: Recovery result or controlled halt
    end

References: agent/tool_executor.py• L486-556 agent/tool_executor.py• L655-752 agent/tool_executor.py• L835-988 agent/turn_tool_round.py• L127-174 agent/turn_tool_round.py• L176-230

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the model-visible tool set, Tool Search catalog, deferred-call scope check, and execute_code allowed-tool list aligned.
  • Preserve the one-call approval contract when adding a new effect-capable tool or a new approval transport.
  • Update both pre-action guards and post-result failure classification when a tool gains a new side effect or result shape.
  • Keep terminal task/profile identity consistent across environment creation, current working directory tracking, process ownership, and cleanup.
  • Recheck both initial and post-redirect browser URL checks when changing navigation or browser evaluation paths.
  • Preserve the durable ordering: persist the assistant tool-call block before execution and persist the result before the next model request.

Important failure modes

TriggerConsequenceGuard
Deferred tool call names a tool outside the session grantThe call is refused instead of escaping the session's toolsetSession-scoped catalog check and concrete schema validation
Dangerous command is denied, withdrawn, or times outThe command does not run and the model receives a no-retry refusalApproval gate treats silence and delivery failure as non-consent
Agent writes a protected instruction fileFuture behavior could be changed without consentAlways-ask protected-file gate with no unattended bypass
Browser navigation redirects to metadata or private contentThe page could expose host or cloud credentialsPre-navigation and post-redirect URL floors; blocked pages are cleared
Model repeats failed or unchanged tool workThe turn can consume its budget without progressPer-turn warnings, loop caps, synthetic blocks, and controlled halts
Tool result exceeds the context budgetThe next model request can overflow or lose useful contextSpillover storage, bounded previews, and aggregate budget enforcement
Session persistence fails before or after a toolResume state could disagree with an action that already ranPersist-before-execute and stop-on-flush-failure rules

Key files

FileWhy to read it
tools/registry.pyCentral tool identity, availability, schema filtering, result normalization, and dispatch boundary
model_tools.pySession tool selection, Tool Search bridge handling, hooks, middleware, and public dispatch path
tools/tool_search.pyProgressive discovery, catalog scope, bridge calls, and connector access
tools/approval.pyConsent state, approval transports, unattended behavior, allowlists, and denial recovery
tools/file_tools_write_guards.pyWrite-side protection for system paths, instruction files, binary documents, and stale overwrites
tools/terminal_tool.pyTerminal contract, backend selection, task scope, approval handoff, and execution planning
tools/terminal_tool_guards.pyWorkdir, gateway lifecycle, and managed-background command blocks
tools/terminal_tool_lifecycle.pyEnvironment creation, idle cleanup, failure eviction, and teardown
tools/browser_tool.pyBrowser session ownership, navigation, page actions, URL safety, and output handling
tools/browser_tool_eval_policy.pyJavaScript evaluation restrictions and private-page checks
agent/tool_executor.pyPer-call policy order, concurrency, interruption, timeouts, and result commit flow
agent/tool_guardrails.pyRepetition detection, loop caps, result deduplication, and controlled decisions
agent/turn_tool_validation.pyUnknown-tool repair, argument validation, bounded retries, and partial exits
agent/turn_tool_round.pyDurable ordering for tool-call rounds and turn continuation or halt decisions