# OpenHands

OpenHands and chock: install methods and steps, what it can enforce, and the evidence behind it.

Install methods: plugin, sync. Agentseam tier block, grade best-effort before a tool runs.

> Ask the user before running any command on this page: each one changes how their agent or repository behaves.

## Install methods

- Plugin: `chock install --client openhands` (ask the user before running it)
- Repo hooks: `chock sync --repo . --agents openhands` writes `.openhands/hooks.json` (ask the user before running it)

## Note

Chock's Claude Code plugin does not protect OpenHands, even though OpenHands reads .claude-plugin/: its matchers never match OpenHands' terminal or file_editor tools. Use the OpenHands plugin. (Source: `docs/enforcement-surfaces.md` in chock)

## Install steps

### OpenHands (openhands)

State: untested.

Evidence wanted for OpenHands. Chock has not seen OpenHands run the plugin yet. The command still builds the plugin. If you use OpenHands, you can help: run it and share what happens in [agentseam issue #181](https://github.com/open-coder-ai/agentseam/issues/181).

The command (ask the user before running it: it builds a plugin of hooks that change how their agent behaves):

    chock install --selection <code> --client openhands

Then, in OpenHands:

OpenHands loads a local plugin when it starts: run `openhands --plugin ~/.chock/marketplace/openhands/chock-guardrails`, or add "~/.chock/marketplace/openhands/chock-guardrails" to sources under [plugins] in ~/.openhands/config.toml (chock does not edit it). Its hooks name ~/.chock/marketplace/openhands/chock-guardrails by absolute path (OpenHands documents no plugin-root variable), so keep that folder where it is; a rebuild applies from the next start.

## What it can enforce

- Tier: block
- Grade before a tool runs: best-effort
- Fail mode before a tool runs: open
- Basis: vendor-docs
- Recorded: 2026-10-11

## Events

| Event | Can block | Can rewrite | Fail mode |
| --- | --- | --- | --- |
| pre_tool | yes | no | open |
| post_tool | no | no | open |
| prompt_submit | yes | no | open |
| session_start | no | no | open |
| session_end | no | no | open |
| stop | yes | no | open |

## Ask support

Answers an ask with: deny. Honours ask: no. Evidence: tested (tests/test_guard_fail_to_ask.py::test_a_crashed_guard_asks_rather_than_allowing).

## Hook timeout

Default 60 seconds, set by the timeout field in s.

Vendor source: https://docs.openhands.dev/openhands/usage/customization/hooks

## Test status

- Plugin (openhands): untested.
- Repo hooks: untested. A test of the plugin says nothing about repo hooks.
- No row in the engine's list of live tests for this agent.

## Known limits

PreToolUse, UserPromptSubmit and Stop can block; a block at Stop keeps the conversation going. The verdict is the flat {decision: deny, reason} body, and a bare allow is silence (exit 0). No rewrite and no ask: a transform or escalate degrades to a block, never to a silent pass. Fail-open: the docs say any exit code other than 0 and 2 is an error and the operation proceeds. The event name rides under event_type, not hook_event_name, which is what separates OpenHands payloads from every other adapter's. The cwd is working_dir. Known limit: file_editor's own sub-command (view, create, str_replace, insert, undo_edit) arrives in tool_input.command, the same key as terminal's shell command, so Event.command carries it for file_editor calls; a shell policy should check event.tool. The docs document only the project file; a user-level ~/.openhands/hooks.json exists in the SDK source, and a project file shadows it rather than merging. The standalone OpenHands-CLI repository says it is no longer actively maintained; the hooks docs still list the CLI. Instruction files reach it through AGENTS.md (https://docs.openhands.dev/overview/skills). Evidence wanted (to test or overturn this row): https://github.com/open-coder-ai/agentseam/issues/181


---

Built from engine [5a4b6287a46e](https://github.com/open-coder-ai/chock/commit/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021) and catalog [1e60d211c1bb](https://github.com/open-coder-ai/chock-catalog/commit/1e60d211c1bb767152c6ab0167932da06ab3a10f).