Pause Verdict & Approval Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The Pause Verdict & Approval Workflow is a critical security feature in Honmoon that enables human-in-the-loop intervention for sensitive AI agent actions. When the policy engine evaluates a request and returns a Pause verdict, the system "holds" the network connection in a pending state. This allows an administrator to review the request's metadata (facts) and manually approve or reject the connection before any data is transmitted to the upstream destination.
This workflow bridges the gap between strictly automated allow/deny rules and the need for oversight in high-risk scenarios, such as destructive database queries or sensitive cloud resource modifications. It is primarily implemented across the honmoon-proxy (handling the connection hold) and honmoon-mgmt (providing the interface for human resolution) modules.
Architecture & Components
The approval workflow relies on a shared state architecture where the data plane (proxy) and the management plane (API) communicate via a centralized registry.
Approval Registry
The ApprovalRegistry is the core data structure that manages the lifecycle of paused requests. It maintains an internal map of pending approvals and uses asynchronous primitives to signal when a decision has been made.
- Storage: Uses a
DashMapfor concurrent access toPendingApprovalrecords. - Signaling: Employs
tokio::sync::oneshotchannels to block the proxy task while waiting for a decision. - Capacity: Includes a
max_pendinglimit (defaulting to 100) to prevent resource exhaustion from too many concurrent pauses.
Sources: [crates/honmoon-proxy/src/approval.rs:34-59](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/crates/honmoon-proxy/src/approval.rs#L34-L59), [wiki/deep-dive/control-plane.md:25-35](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/wiki/deep-dive/control-plane.md#L25-L35)
Data Structures
| Type | Description | Key Fields |
|---|---|---|
Verdict | The engine's output. | Allow, Deny, Pause |
PendingApproval | Metadata about the held request. | id, created_at, facts, rule_name |
Decision | The result of human intervention. | Approved, Rejected, TimedOut |
Sources: [crates/honmoon-core/src/lib.rs:15-25](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/crates/honmoon-core/src/lib.rs#L15-L25), [crates/honmoon-proxy/src/approval.rs:18-32](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/crates/honmoon-proxy/src/approval.rs#L18-L32)
The Approval Lifecycle
The workflow follows a strict sequence from detection to resolution, ensuring that no connection is established until a valid approval is received.
1. Interception and Holding
When the proxy receives a Verdict::Pause from the decision engine, it generates a unique ID for the request and registers it with the ApprovalRegistry. The proxy task then enters an await state on a receiver channel.
2. Management Interaction
The honmoon-mgmt API surfaces these pending approvals to the Dashboard. An administrator reviews the request and sends a POST request to either the /approve or /reject endpoint.
3. Resolution
Upon receiving the decision, the registry sends the result through the oneshot channel back to the waiting proxy task. The proxy then either continues the connection (tunneling) or returns a 403 Forbidden error to the agent.
4. Timeouts
To prevent infinite hangs, paused requests have a mandatory timeout (defaulting to 300 seconds). If no decision is made within this window, the registry automatically resolves the request as TimedOut, which the proxy treats as a Deny (Fail Closed).
Sources: [crates/honmoon-proxy/src/approval.rs:148-160](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/crates/honmoon-proxy/src/approval.rs#L148-L160), [wiki/getting-started/quick-start.md:120-145](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/wiki/getting-started/quick-start.md#L120-L145), [wiki/deep-dive/control-plane.md:105-125](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/wiki/deep-dive/control-plane.md#L105-L125)
Workflow Sequence Diagram
The following diagram illustrates the interaction between the AI Agent, Proxy, Registry, and Administrator.
The diagram shows the synchronous hold on the proxy task and the asynchronous resolution via the management plane.
Sources: [wiki/deep-dive/architecture.md:55-75](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/wiki/deep-dive/architecture.md#L55-L75), [wiki/deep-dive/control-plane.md:95-120](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/wiki/deep-dive/control-plane.md#L95-L120)
Management API Endpoints
The honmoon-mgmt module exposes several endpoints to facilitate the approval workflow. These endpoints interact directly with the ApprovalRegistry stored in the shared GatewayState.
| Endpoint | Method | Description |
|---|---|---|
/api/approvals | GET | Returns a list of all currently PendingApproval requests. |
/api/approvals/{id}/approve | POST | Approves the request; triggers the proxy to allow the connection. |
/api/approvals/{id}/reject | POST | Rejects the request; triggers the proxy to block the connection. |
Sources: [crates/honmoon-mgmt/src/lib.rs:86-110](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/crates/honmoon-mgmt/src/lib.rs#L86-L110), [wiki/deep-dive/control-plane.md:70-85](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/wiki/deep-dive/control-plane.md#L70-L85)
Technical Implementation Details
Fail-Closed Invariant
A core architectural invariant of Honmoon is "Fail Closed." If the ApprovalRegistry is full (at max_pending), any new Pause verdict is automatically treated as a Deny. Similarly, any error during the signaling process or a timeout results in a rejection.
// crates/honmoon-proxy/src/approval.rs
pub async fn register(&self, facts: Facts, rule_name: Option<String>) -> Result<oneshot::Receiver<Decision>, ApprovalError> {
if self.pending.len() >= self.max_pending {
return Err(ApprovalError::QueueFull);
}
// ... registration logic ...
}
Sources: [crates/honmoon-proxy/src/approval.rs:115-130](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/crates/honmoon-proxy/src/approval.rs#L115-L130), [wiki/getting-started/quick-start.md:148-155](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/wiki/getting-started/quick-start.md#L148-L155)
Shared State (Arc)
The ApprovalRegistry is wrapped in an Arc (Atomic Reference Count) and shared between the proxy's accept loop and the management API's router. This allows the API to resolve connections that are physically managed by separate Tokio tasks within the proxy.
Sources: [crates/honmoon-mgmt/src/lib.rs:45-60](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/crates/honmoon-mgmt/src/lib.rs#L45-L60), [wiki/deep-dive/architecture.md:30-45](https://github.com/pleaseai/honmoon/blob/9cb18b45e7685e1ee787d4f27829b0d7c383aa5d/wiki/deep-dive/architecture.md#L30-L45)
Summary
The Pause Verdict & Approval Workflow provides a secure, auditable mechanism for human oversight of AI agents. By utilizing an asynchronous registry with oneshot signaling and a strict fail-closed posture, Honmoon ensures that sensitive requests are held safely until explicitly resolved by an administrator. This system integrates seamlessly with the embedded dashboard, providing a complete end-to-end solution for managed agent egress.