Does Agent Approve use OpenHands hooks or OpenHands plugins?

Hooks. OpenHands' `plugins` field is for adding skills and MCP servers to the agent; it does not host lifecycle callbacks the way OpenClaw's plugin API does. The six `.openhands/hooks.json` events are the right surface for governance, and they support synchronous blocking via `exit 2` or stdout `{"decision":"deny","reason":"..."}`, which is exactly what Agent Approve needs.

How does the follow-up command from my phone get into OpenHands?

OpenHands' `stop` hook is blocking. When the agent finishes a turn, our `openhands-hook.sh` POSTs to Agent Approve and waits (up to five minutes) for an iPhone or Apple Watch follow-up. If you submit one, the hook returns `{"decision":"deny","reason":" "}` and OpenHands keeps the agent running with your text as the next user instruction.

Where does the hook config file live?

OpenHands looks for hooks at ` /.openhands/hooks.json` per project. The installer writes a user-global default at `~/.openhands/hooks.json` so a single `npx agentapprove` run covers your default setup. If OpenHands does not auto-resolve the global file in a specific workspace, `cp ~/.openhands/hooks.json ./.openhands/hooks.json` from inside that project.

What happens if Agent Approve is unreachable?

Your `failBehavior` setting decides. `ask` (default) and `allow` let the action through; `deny` fails closed and blocks it. The dispatcher logs the fallback to `~/.agentapprove/hook-debug.log` so you can see exactly when and why.

Why does the OpenHands CLI print "UNKNOWN Event: HookExecutionEvent"?

That message comes from the OpenHands CLI itself, not from Agent Approve. The CLI renders every hook execution as a generic "UNKNOWN Event" label because the OpenHands SDK does not yet have a friendly display name for `HookExecutionEvent`. The hook itself is running correctly — events and approvals continue to flow to your iPhone. We have raised this upstream; in the meantime the noise is cosmetic and can be safely ignored.

Why does `/exit` print a "RuntimeError: App is not running" traceback?

This is an upstream OpenHands SDK lifecycle ordering bug, not caused by Agent Approve. When you type `/exit`, the CLI tears down its TUI first, then `LocalConversation.close()` runs and fires the `session_end` hook. The OpenHands SDK synthesizes a `HookExecutionEvent` for that run and dispatches it to listeners, one of which is the (already-shut-down) TUI visualizer — Textual then raises `App is not running`. The session_end hook itself completed successfully and your final session_end event reaches Agent Approve. The traceback is noisy but harmless; we have raised it upstream.

All agents

Agent Approve for OpenHands

Centralized approvals, guardrails, and activity monitoring for OpenHands from your phone

Autonomous agentCLIHook integration

Agent Approve adds a supervision layer to your OpenHands setup using OpenHands' native .openhands/hooks.json lifecycle hooks. Approve or deny shell commands, MCP tool calls, file writes, and reads from your iPhone or Apple Watch, with push notifications so you know the moment OpenHands needs a decision.

When the agent finishes a turn, the blocking stop hook holds the run open while Agent Approve waits for an iPhone-supplied follow-up command — type or dictate the next instruction, and OpenHands continues with it as the next user message. The same shared allow and deny rules cover OpenHands and every other agent you supervise: Cursor, Claude Code, Gemini CLI, Codex, Pi, OpenCode, OpenClaw, Hermes, Windsurf, and Copilot.

Install OpenHands

Quick start

Download Agent Approve from the App Store and complete onboarding.

Run npx agentapprove on your machine and select OpenHands.

The installer writes ~/.openhands/hooks.json with the six lifecycle events wired to the Agent Approve dispatcher.

Scan the QR code to pair, then start using OpenHands — approval requests and stop-input prompts arrive on your phone.

Install command

npx agentapprove

Agent Approve config: ~/.agentapprove/

OpenHands hook config: ~/.openhands/hooks.json

agentapprovev0.1.24

Recommended configuration

•OpenHands resolves hooks per workspace from <project>/.openhands/hooks.json. The installer writes a user-global default at ~/.openhands/hooks.json; if OpenHands does not auto-resolve it in a specific workspace, copy or symlink the file into that project.
•Pre-tool and stop events block synchronously (exit 2 / decision:deny). Session and post-tool events run async: true so they never delay the agent loop.

Capabilities

Approval requests

Follow-up commands

Voice input

Activity monitoring

Push notifications

MCP tool tracking

Good to know

Six lifecycle events – pre_tool_use, post_tool_use, user_prompt_submit, stop, session_start, session_end all route through a single bundled dispatcher (openhands-hook.sh).

Blocking pre-tool approval – Shell commands, file writes, file reads, and MCP tool calls all flow through pre_tool_use. A deny on your phone returns {"decision":"deny","reason":"..."} so OpenHands cancels the tool call and surfaces your reason to the agent.

Follow-up commands on stop – OpenHands' stop hook is blocking, so Agent Approve holds the run open while you type or dictate the next instruction on your phone. The reply comes back as decision:deny with the follow-up text as reason, and OpenHands acts on it as the next user message — same UX as Cursor and Claude Code.

Voice input – Especially useful when OpenHands runs headless on a server or in a sandbox. Dictate the follow-up from your watch or phone instead of switching back to the terminal.

MCP tracking – Tools with the mcp__server__tool naming convention are grouped by server in your activity history so you can see which MCP servers OpenHands actually used.

User prompts are logged, never blocked – user_prompt_submit emits a telemetry event so prompts appear in activity history, but Agent Approve never blocks the prompt itself; this product is self-governance for indie developers, not corporate prompt surveillance.

Bulk command parsing – Policy evaluation splits shell commands chained with && into individual sub-commands evaluated independently. A dangerous command like rm -rf hidden as the third step in a chain is caught even when the batch starts with safe commands.

Stay up to date – Run npx agentapprove again to refresh hooks. The installer is idempotent and preserves any non-Agent-Approve entries already in your hooks.json.

Use cases

Block destructive shell commands and risky MCP tool calls from iPhone or Apple Watch before OpenHands runs them.

Send voice or text follow-ups from your phone the moment OpenHands finishes a turn — useful when the agent runs headless on a server.

Track OpenHands prompts, tool calls, MCP usage, and stop events in the same unified activity history as your other agents.

Apply the same deny rules to OpenHands that you use for Cursor, Claude Code, Gemini CLI, Codex, Pi, OpenCode, OpenClaw, Hermes, and Copilot.

See what OpenHands is doing in a sandbox or remote workspace when you are away from the terminal — push notifications surface the moments that need a decision.

Questions about OpenHands

A few common questions about how Agent Approve fits alongside OpenHands.

More guides

View all supported agents Frequently asked questions Get help