Part 4 — Build the Harness Chapter 21
Hooks, Validation & Agent Automation
In this chapter
CI gives the reviewer a result on a clean checkout. You can shorten your own feedback loop by running a check before creating a commit. You can also record that an assistant called a tool. Those are different events, and the distinction matters when you investigate a failure.
Put the check where it will run
From a clean checkout, start a branch at lab-coverage. Record the existing value of git config --local --get core.hooksPath before changing it. Create .githooks/pre-commit in the repository root.
#!/bin/sh
set -eu
git diff --cached --check
npm run verify
chmod +x .githooks/pre-commit
git config --local core.hooksPath .githooks
Add a line with trailing whitespace to README.md, stage the file, and try to commit. git diff --cached --check should stop the commit and identify the line. Remove the trailing whitespace, stage the fix, and try again. This time the hook should reach npm run verify. Watch for its result before Git reports the commit.
The diff check reads the index. The tests and coverage run on the working tree. Inspect git status --short while reproducing the check and use CI to verify the committed revision. Return core.hooksPath to its previous value when you finish, or use git config --local --unset core.hooksPath if it was absent.
Where an OpenCode hook fits
A server plugin observes events inside OpenCode. This exercise attaches a marker to a completed shell call. The plugin runs in the server process, so review its code before loading it. Put this file in the repository at .opencode/plugins/lab-check-marker.js.
export default {
id: "lab-check-marker",
async setup(ctx) {
await ctx.tool.hook("execute.after", event => {
if (event.tool === "shell" && event.status === "completed") {
event.result = {
...event.result,
metadata: { ...event.result.metadata, labCheckObserved: true },
};
}
});
},
};
Use a fresh OpenCode invocation. If the CLI has no selected model, add --model provider/model with the ID from setup. The exact npm test command matches the lab’s permission rule.
opencode run --standalone --agent plan --format json \
"Execute only npm test using the shell tool. Report the observed result." \
> ../hook-enabled.jsonl
Find the completed shell event. In the OpenCode 2.3.2 JSON stream, look for the metadata object under part.state.metadata.metadata. It should contain labCheckObserved: true and the command exit status. A completed tool call can carry a failing command result. Check both values.
Move the plugin file outside .opencode/plugins/ and repeat in another fresh process with the same model and prompt. Look for the completed shell event again. The marker should disappear while the command result remains. If the agent skips the shell tool, repeat the request before drawing a conclusion about the plugin. Save only the reviewed evidence you need from the two runs. The merge requirement still comes from the CI check.
References
- Git maintainers. githooks. Git reference manual.
- OpenCode maintainers. Server, server hooks, Plugins, and CLI commands. Official OpenCode 2 documentation.