AiHummer docs
v1.0.x ▾
v1.0.x stable
RU EN
Security /Approval gates

Approval gates

v1.0.x · updated 2026-06-26

Some tool calls should not happen without a human saying yes — sending mail, posting to a channel, making changes with real-world consequences. AiHummer’s approval gates put a person in the loop before such tools run, and pair with idempotent side-effects so that approving a recovered turn never fires the same action twice.

How the gate works

You declare which tools require approval with the AIHUMMER_APPROVAL_TOOLS setting — a list of tool names. When the agent decides to call one of those tools, execution pauses and an approval request is raised for a human to review.

# /home/.aihummer/etc/gateway.env
# Comma-separated list of tools that require approval before execution
AIHUMMER_APPROVAL_TOOLS=mail,http_request

The pending request surfaces in the admin UI and admin API (/v1/admin/approvals), where a reviewer sees the tool, its arguments and the context, and then approves or rejects it.

Approve means run, reject means do not run

The gate is unambiguous:

  • Approve — the tool executes with exactly the arguments that were reviewed.
  • Reject — the tool is not executed. There is no partial or deferred execution; a rejected call simply does not happen, and the turn continues without that side-effect.

[!NOTE] A reject is a hard stop for that specific call. The agent does not silently retry the rejected action behind the reviewer’s back.

Why this is safe under recovery

Approval gates pair with AiHummer’s idempotent side-effects. A turn can be interrupted (a restart, a crash) and then recovered. Without protection, a recovered turn could re-issue an action that already happened — sending the same email twice, posting the same message again.

AiHummer prevents this with a resume-stable ledger key and a side-effect barrier: each side-effect is recorded under a stable key, and the barrier refuses to re-run an effect that the ledger shows as already performed.

[!TIP] The practical payoff: approving a recovered turn does not double-fire mail or channel-send. The barrier ensures the effect happens exactly once, whether or not the turn was recovered.

See Multitenancy & idempotency for the full mechanics of the ledger and the side-effect barrier.

Choosing which tools to gate

Gate tools whose effects are externally visible or hard to undo. Good candidates:

  • mail — outbound email.
  • Channel-send / outbound delivery to customers or staff.
  • http_request and other tools that can mutate external systems.
  • code_exec on shared hosts (also off by default there).

Read-only tools (search, knowledge lookup, time) generally do not need a gate. Combine approval gates with the air-gapped mode and egress controls for tools that reach the public internet.

Where to next