Use the Claude Code hook
Verify automatically when Claude Code says it is done, and send a blocked agent back with what failed.
Claude Code is the one agent with a built-in integration in 0.1.1. It has been tested end to end, including a headless run that a hook verdict reached.
Install#
The repository needs a contract first:
ohx init --lock-tests # or ohx contract new ... --accept
ohx hook installohx hook install adds a Stop hook to .claude/settings.local.json in the repository, keeping your other settings and hooks. Keep that file out of git: it holds paths on your machine.
What happens when the agent stops#
When Claude Code says it is done, the hook runs ohx verify (sandboxed with srt when it is installed) and answers:
| Verdict | What happens |
|---|---|
| READY | The agent stops. You get a one-line message with the report's path |
| NO REGRESSIONS | The agent stops. The message says the task is not shown to be done and how many locked tests still fail as before |
| Anything else | The result goes back to the agent with the agreed tests that failed, the error lines and where the full output is. You get a message such as OpenHarnX: BLOCKED (attempt 1 of 3); sent back to the agent with what failed. |
After three blocked attempts in a row the agent may stop, and you get still BLOCKED after 3 attempts. An agent that cannot fix the problem is not trapped.
Without a contract, the hook verifies nothing and says so: OpenHarnX: nothing verified, this repository has no contract yet.
From Claude Code 2.1.163 the result reaches the agent as hook feedback. With older versions it is sent as a plain block, which Claude Code shows as a hook error.
Headless runs#
With claude -p, the hook's message appears only with --output-format stream-json. Plain --output-format json carries no hook output. ohx report always has the result.
Timing#
The hook allows 900 seconds for verification, above Claude Code's 600-second default for command hooks. A slow suite can run in parallel with pytest_args = ["-n", "auto"] in ohx.toml (pytest-xdist must be installed in the checker's environment).