You usually find out a guard hook isn't running after something slips through that it should have stopped.
There is an issue in the Antigravity CLI repository describing exactly that. On macOS arm64 with CLI 1.2.1 and 1.2.2, the log says it loaded five named hooks from hooks.json, and /hooks lists each matcher and command. But no hook process is ever spawned, and nothing is reported as an error. With the same config, account and machine, going back to 1.1.28 made the hooks run again.
The cause isn't confirmed. The reporter suspects the hook executor rather than the config, and I couldn't find a fix version stated anywhere I checked. So this isn't a repair guide. It's a way to find out in about ten minutes whether your own setup has a config mistake or an executor problem.
Loaded and executed are two different facts
A hook appearing in /hooks only proves the file parsed. It says nothing about whether anything was called.
Mixing those up sends you into rewriting the config again and again. If the list looks right but nothing happens, collect separate evidence that a hook fired at all before you blame the wording of the config.
Show evidence for "displayed" and for "executed" separately. That's the line I'm drawing here.
Put three throwaway hooks in place
The check is simple: three hooks that do nothing except append one line to a file when called. The reporter used the same canary idea to isolate the problem.
The report places the file at ~/.gemini/config/hooks.json. If your version differs, trust the official docs.
{
"canary-invocation": {
"PreInvocation": [
{ "type": "command", "command": "echo \"$(date +%T) PreInvocation\" >> /tmp/agy-hook-canary.log", "timeout": 5 }
]
},
"canary-tool": {
"PreToolUse": [
{
"matcher": "*",
"hooks": [
{ "type": "command", "command": "echo \"$(date +%T) PreToolUse\" >> /tmp/agy-hook-canary.log", "timeout": 5 }
]
}
]
},
"canary-stop": {
"Stop": [
{ "type": "command", "command": "echo \"$(date +%T) Stop\" >> /tmp/agy-hook-canary.log", "timeout": 5 }
]
}
}The point is to strip out everything real (checks, approvals) and keep only the fact that the hook was called. If the hook body is complex, you can't tell whether a failure comes from the config or from your script.
Note the two entry shapes. According to the report, PreToolUse takes a matcher with a nested hooks array, while PreInvocation and Stop take a flat shape. That difference is discussed in another issue too, and flattening everything can load fine but not behave as expected. I also can't say how timeout is interpreted in every version, so I start with a short value.
Run one turn and read the log
Empty the log, then run one short turn that triggers one LLM call and one tool call. The reporter ran a single turn with agy -i.
rm -f /tmp/agy-hook-canary.log
agy -i
# Ask it to "read the first 5 lines of README.md" and wait for the reply to finish
cat /tmp/agy-hook-canary.logYou'll land in one of three cases.
If all three lines appear, the executor is fine. Look at your real script or at the matcher conditions.
If only one or two lines appear, note which event is missing. The routes may differ per event, and mixing up the nested and flat shapes is worth suspecting here.
If the file is never created while /hooks lists everything, a config mistake alone is hard to blame. That matches the report, so check your version.
Change only the version, compare
In the third case, run the same turn again changing nothing but the CLI version. The report says 1.1.28 produced three lines, while 1.2.1 and 1.2.2 left nothing.
agy --version
# How to pin or roll back depends on how you installed the CLIOne more detail from the report stuck with me: processes started before the 1.2.2 binary was installed kept firing hooks, while processes started afterward didn't. If you keep the CLI running as a long-lived process, the problem may only show up after the first restart following an update. Running the canary for one turn after every update is a cheap habit.
Decide where the guard lives while hooks are silent
If it turns out to be an executor problem, I'd stop relying on hooks alone. As an indie developer working solo, I have no second reviewer to catch what a silent guard misses.
Whatever you wanted a hook to block, put a second copy outside the agent, such as a git pre-push check. If the hook goes quiet, the push is still stopped. I wrote about how to combine them in a two-layer gate with hooks and git pre-push.
I haven't been able to confirm whether a later release fixed this, so please check the current state of the issue yourself.
As a first step, add the three-line canary to your hooks.json today and run one turn. If all three lines appear, you can go back to the real hook body with a little more confidence.