Summary

Add a standalone api.approval.request() method to the Plugin SDK that allows plugins to request user approval at any point in agent
execution, not just before tool calls.

Problem to solve

Currently, OpenClaw’s approval infrastructure (plugin.approval.* flow) is only accessible through the before_tool_call hook’s requireApproval result. This means:

• Only works before tool calls — cannot request approval for agent decisions or workflow stages
• No async pause/resume — the hook must return immediately, approval is handled by Gateway
• Tight coupling — approval is tied to tool execution, not general agent flow

Real-World Use Cases Blocked

• Pre-execution plan review — Agent creates a multi-step plan, requests approval before executing
• Mid-execution checkpoints — Agent is about to proceed with next step, requests confirmation
• Human-in-the-loop decisions — Agent needs user input before continuing workflow

Proposed solution

Add a new API method to OpenClawPluginApi:
interface ApprovalRequestOptions {
title: string;
description: string;
severity?: "info" | "warning" | "critical";
timeoutMs?: number; // default: 30000 (30 seconds)
timeoutBehavior?: "allow" | "deny"; // default: "deny"
allowedDecisions?: Array<"allow-once" | "allow-always" | "deny">;
}

interface ApprovalResult {
decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled";
}

// New API method
api.approval.request(options: ApprovalRequestOptions): Promise;

Alternatives considered

1. Use before_tool_call.requireApproval — Only works for tool calls, not general agent flow
2. Create synthetic tools just for approval — Clunky, breaks separation of concerns
3. Implement custom approval UI in plugin — Duplication of existing infrastructure
4. Requiring approval on every tool call.... Tiresome.
5. Thinking mode in model pause to allow user a chance to abort.... obviously weaker.

Impact

Affected users: Plugin authors who need to implement workflow checkpoints or human-in-the-loop decisions
Severity: Medium — blocks common agent patterns (plan review, multi-step workflows)
Frequency: Always — anyone building non-trivial plugins would benefit
Consequence: - Workarounds exist but are clunky (synthetic tools, complex hooks) - No way to enforce the “pre-action protocol” pattern cleanly -
Plugin approval infrastructure exists but is underutilized

Evidence/examples

Current approval flow: Gateway’s plugin.approval.* flow
Hook-based approval: before_tool_call.requireApproval in plugin hooks
Use case: Pre-Action Protocol — enforcing Ground Truth hierarchy with approval-based waits

Additional information

Migration path: This is additive — doesn’t break existing functionality
Dependencies: Reuses existing approval infrastructure (Gateway plugin.approval.* flow)
Implementation scope:

1. Gateway: Add plugin.approval.request handler
2. Plugin SDK: Add api.approval.request() to OpenClawPluginApi
3. Docs: Update plugin docs, add examples