Human Approval Gate plugin thumbnail

Human Approval Gate

Pauses Agent Zero before high-risk actions (destructive commands, file deletion, git push, external HTTP writes) and waits for an explicit Approve or Reject in the UI. Every decision is logged to a local audit file. Safe defaults, no external services.

Author glatinone 0 stars Version 0.1.0 Updated
SecurityAutomationAgentsTools
GitHub Repository Discussion How to install

README

Human Approval Gate

Pause Agent Zero before high-risk actions and require explicit human approval.

When the agent is about to run a gated action, the plugin holds the tool call, shows an approval card in the Agent Zero UI, and only lets the action run after you press Approve. Press Reject (or let the timeout expire) and the agent receives a clear error telling it the action was not executed.

Gated action categories

Category Examples
Destructive shell or host commands mkfs, dd to a device, shutdown/reboot, fdisk, git reset --hard, git clean -f, chmod 777 /
File deletion rm, rmdir, unlink, shred, find -delete, shutil.rmtree, os.remove, Path.unlink, fs.rm*
Git push any git push
External HTTP writes POST / PUT / DELETE / PATCH via curl, wget, requests, httpx, axios, fetch to non-private hosts

All categories are editable toggles in plugin settings, and every one defaults to ON. Internal targets (localhost, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, *.local, host.docker.internal) do not trigger the HTTP write gate, so local development and testing keep working.

How it works

  1. A tool_execute_before extension inspects every tool call before execution using a small pattern-based detector (no AI risk scoring, no network calls).
  2. If a rule matches an enabled category, the tool call is parked in a pending approval record and the extension waits.
  3. The WebUI overlay polls POST /api/plugins/human_approval_gate/approvals and renders a card showing tool, category, and a snippet of the action.
  4. Approve: the extension returns and the tool executes normally.
  5. Reject or timeout: the extension raises a repairable error so the tool never runs and the agent knows to ask you instead of retrying blindly.
  6. Every decision is appended to a local JSONL audit file with tool, category, decision, and timestamps.

Settings

  • Per-category on/off toggles
  • Decision timeout in seconds (0 = wait forever, default 300)
  • Audit history size cap

Open Settings > Agents > Human Approval Gate to configure.

Install

  1. Copy this folder into usr/plugins/human_approval_gate in your Agent Zero installation (or install via the Plugin Hub if published).
  2. Restart Agent Zero (or reload the WebUI) so the plugin is discovered.
  3. Enable the plugin. No API keys, no external services.

Files

plugin.yaml                                  manifest
default_config.yaml                          safe defaults
helpers/detector.py                          detection rules (pure stdlib)
helpers/store.py                             pending state + audit log
extensions/python/tool_execute_before/       the gate itself
extensions/webui/initFw_end/approvals.js     approval overlay in the UI
api/approvals.py                             list / decide / history endpoints
webui/config.html                            settings form

Manual test

  1. Ask your agent: "Run this exact command: rm /tmp/a0-gate-test.txt".
  2. An approval card appears in the bottom right corner.
  3. Approve: the command runs. Repeat with Reject: the agent receives a blocked error and the command never runs.
  4. Check usr/plugins/human_approval_gate/data/audit.jsonl for the record.

Limitations (MVP)

  • Detection is pattern based: exotic obfuscation can evade it, and unusual but harmless wording can trigger a prompt. The gate fails toward safety.
  • Pending approvals live in memory; restarting Agent Zero drops undecided approvals (audit history survives on disk).
  • Single-user, single-UI assumption. No multi-user voting or external approval services by design.
  • Only built-in execution tools are gated (code_execution_tool, browser evaluate). MCP tools are out of scope for the MVP.

License

MIT