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

> Discover the OpenHuman approval gate, a mechanism for human oversight of AI agent actions. It intercepts high-risk tool calls for explicit human review before execution.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: deep-dive
- Published: 2026-09-01

---

**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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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:

```toml
[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:

```rust
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:

```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:

```typescript
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:

```typescript
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`](https://github.com/tinyhumansai/openhuman/blob/main/gate.rs) pauses high-risk calls and persists them in SQLite via [`store.rs`](https://github.com/tinyhumansai/openhuman/blob/main/store.rs).
- Human reviewers interact through RPC endpoints defined in [`schemas.rs`](https://github.com/tinyhumansai/openhuman/blob/main/schemas.rs), with decisions stored in an auditable recent-decisions table.
- Configurable autonomy policies in [`autonomy.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/security/approval/store.rs) provides queryable access to this history, enabling compliance review and forensic analysis of human-in-the-loop interventions.