OpenHuman Approval Gate Mechanism: Enabling Human Oversight of AI Agent Actions

The OpenHuman approval gate mechanism intercepts medium-to-high-risk tool calls before execution, pausing them in a SQLite-backed pending state until a human reviewer explicitly approves, denies, or permanently authorizes the action through RPC endpoints.

OpenHuman provides a robust approval gate mechanism that enforces human-in-the-loop oversight for AI agent operations. This gating layer sits between the agent's decision-making process and the external world, ensuring that consequential actions receive appropriate scrutiny before taking effect. By implementing configurable autonomy policies and persistent audit trails, the system balances operational efficiency with strict safety requirements.

Architecture of the Approval Gate Mechanism

The approval gate operates as a gating layer within the tool-dispatch pipeline, evaluating every tool call against configurable risk thresholds before allowing external execution.

Tool Call Classification and Risk Assessment

When an agent invokes a tool, the core system classifies the operation by category—such as read, write, network, or destructive actions. Calls that exceed a configurable risk threshold are marked as gating, triggering the oversight workflow. This classification happens immediately upon tool invocation, before any external effects occur.

The Gate Decision Logic

The ApprovalGate struct in src/openhuman/security/approval/gate.rs evaluates each classified call against the current autonomy tier. Based on policy configuration, the gate either permits automatic execution or pauses the call to create a pending-approval record. This decision point ensures that only pre-authorized low-risk operations proceed without human intervention.

Persistent Storage for Pending Approvals

Paused requests are persisted in a lightweight SQLite database implemented in src/openhuman/security/approval/store.rs. Each pending record contains the tool payload, originating thread ID, and an expiration deadline. The store also maintains a recent-decisions table for complete audit trails, accessible via the list_recent_decisions implementation in the same file.

Human Interaction and the Approval Workflow

Desktop UI and RPC Endpoints

The React and Tauri-based desktop interface communicates with the core through specific RPC endpoints defined in src/openhuman/security/approval/schemas.rs. The frontend polls openhuman.approval_list_pending to retrieve active requests and openhuman.approval_list_recent_decisions for historical context. Pending items render as Approval Request Cards offering three distinct options: Approve Once, Approve Always, or Deny.

Decision Handling and Execution Resumption

When a user submits a decision via the openhuman.approval_decide RPC method, the handler records the choice, updates the SQLite store, and unparks the originally paused tool call. The ApprovalGate then returns an ExecutionOutcome to the agent—either Allowed or Denied—completing the intervention loop and allowing the agent to proceed or handle the rejection.

Configuring Autonomy Policies

Risk Thresholds and Policy Flags

Administrators configure the approval gate through the autonomy policy defined in src/openhuman/config/schema/autonomy.rs. Toggling boolean flags such as require_approval_for_medium_risk shifts the system between fully automatic operation and strict human supervision, allowing deployment-specific calibration of oversight intensity.

Implementation Examples

Enabling the Approval Gate in Configuration

Configure the autonomy policy via TOML to require human approval for medium-risk operations:

[autonomy]

# Require explicit human approval for any tool classified as “medium” risk

require_approval_for_medium_risk = true

Making a Tool Call That Triggers the Gate

In Rust, a tool call classified as medium risk will be intercepted:

use openhuman_core::openhuman::tools::registry::ToolCall;

let tool_call = ToolCall {
    name: "send_email".into(),
    args: serde_json::json!({
        "to": "alice@example.com",
        "subject": "Report",
        "body": "The analysis is attached."
    }),
    // The tool is classified as a network‑write operation → medium risk
    classification: CommandClass::Network,
};

let result = harness.run_tool(tool_call).await?;

If the autonomy policy requires approval, the call pauses and stores a pending approval record.

Listing Pending Approvals via RPC

Query pending requests from the frontend using TypeScript:

// Using the core RPC client from the frontend
const pending = await coreRpcClient.call("openhuman.approval_list_pending");
console.log("Pending approvals:", pending);

Submitting an Approval Decision

Resolve a pending request by calling the decision endpoint:

await coreRpcClient.call("openhuman.approval_decide", {
  request_id: "abc123",          // ID returned by the pending list
  decision: "ApproveOnce",       // "ApproveOnce", "ApproveAlways", or "Deny"
});

The decision instantly unblocks the original tool call, returning ExecutionOutcome::Allowed or Denied to the agent.

Inspecting the Audit Trail

Review recent human decisions for compliance monitoring:

const recent = await coreRpcClient.call("openhuman.approval_list_recent_decisions");
console.table(recent);

Summary

• The approval gate mechanism in OpenHuman acts as a mandatory checkpoint between AI agents and external tool execution.
• Risk-based classification in the tool-dispatch pipeline identifies operations requiring oversight before they execute.
• The ApprovalGate implementation in gate.rs pauses high-risk calls and persists them in SQLite via store.rs.
• Human reviewers interact through RPC endpoints defined in schemas.rs, with decisions stored in an auditable recent-decisions table.
• Configurable autonomy policies in autonomy.rs allow administrators to set risk thresholds and toggle automatic versus supervised operation modes.

Frequently Asked Questions

What triggers the OpenHuman approval gate mechanism?

The gate triggers when a tool call classification—such as network, write, or destructive operations—exceeds the configured risk threshold defined in the autonomy policy. Operations marked as gating automatically pause before execution, creating a pending record in the SQLite store until human review occurs.

How does the approval gate store pending requests?

Pending requests are persisted in a lightweight SQLite database managed by src/openhuman/security/approval/store.rs. Each record contains the complete tool payload, originating thread ID for context, and a deadline timestamp after which the request expires if not reviewed.

Can the approval gate be bypassed for low-risk operations?

Yes. The autonomy tier configuration in src/openhuman/config/schema/autonomy.rs allows administrators to define which risk levels require approval. By setting require_approval_for_medium_risk to false or configuring specific tool allowlists, low-risk read operations and trusted tool calls can execute automatically without human interruption.

Where is the audit trail for approval decisions stored?

All decisions are logged in the recent-decisions table within the same SQLite database that handles pending approvals. The list_recent_decisions implementation in src/openhuman/security/approval/store.rs provides queryable access to this history, enabling compliance review and forensic analysis of human-in-the-loop interventions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}