zerto-ai-rewind/hooks/README.md

PreToolUse guard hook

Makes the rewind guard enforceable instead of advisory.

The MCP server cannot see another server's tool calls, so zerto_check_tool and zerto_guard_before_mutate only work if the model chooses to call them. A model that skips the step is not stopped by anything. A PreToolUse hook runs in the host, where the tool call genuinely pauses, so a failed checkpoint stops the change.

Decisions

situation	decision	effect
tool in read_only_tools	none	runs, no checkpoint
mutating, checkpoint confirmed	none, plus additionalContext	runs, and the model is told which checkpoint to recover from
mutating, checkpoint failed	deny	the call never happens
mutating, VM unknown to Zerto	prompt	human decides; nothing to rewind to
mutating, no VM in the arguments	prompt	catalog's vm_arg did not match
unlisted tool	prompt	nobody said it was read-only

ZERTO_HOOK_UNKNOWN switches the unlisted case to allow or deny.

Install

cp hooks/settings.example.json /tmp/x        # then merge the hooks block into
                                             # .claude/settings.json
export ZERTO_REWIND_CONFIG=/abs/path/config.json

Both paths in the command must be absolute, and the interpreter must be the venv that has this package installed.

Timeouts, which matter here

The hook is synchronous: the host waits. That is the point, because the checkpoint has to exist before the change does.

Budget for the slow path, not the fast one. A successful tag took about 4s against a healthy vSphere-protected VPG, but a refusal took 63s, because wait_for_tag spends 45s before giving up.

So:

• timeout in settings.json: 180 (seconds)
• ZERTO_HOOK_GUARD_TIMEOUT: 150 (seconds), kept under it

If the host's timeout fires first it cancels the hook and discards its output, and the tool call carries on through the normal permission flow. A timeout is therefore a silent failure of the guard, which is why the hook's own budget is the smaller of the two: it would rather deny than be cancelled.

Verified behaviour

Against a live ZVM 10.9.10, all six rows of the table above. Two worth naming:

• jp-ubuntu (healthy, local VPG) tagged checkpoint 7180 and allowed the call, passing the tag back through additionalContext.
• win2019-1 (VPG CMH-AWS-1, protected site AWS) was denied. The deny path works, but see the known issue below: that particular denial was wrong.

Both decisions held with permission_mode: bypassPermissions. A hook still blocks when the user has turned permissions off, which is when an agent is most likely to be running unattended.

Log

~/.zerto-guard-hook.log, or ZERTO_HOOK_LOG. One line per decision.

Known issue: false denials on cloud-protected VPGs

The win2019-1 denial above was a false negative, and it is worth understanding before relying on this hook in an estate with cloud-protected workloads.

wait_for_tag gives up after a hardcoded 45s. That is generous for a vSphere-protected VPG, which checkpoints every 5s and surfaces a tag in about 4s. It is far too short elsewhere: a tag takes ~34s to appear on an Azure-protected VPG and ~128s on an AWS-protected one, because journal cadence is set by the protected site (5s vSphere, 60s Azure, 630s AWS).

So the hook denied the change, and the checkpoint landed anyway. It is in the journal as cp 56, timestamped a minute after the hook reported failure. The guard told the agent there was no rewind point while Zerto was in the middle of creating one.

That failure mode is worse than the one the hook guards against, because it is silent and looks correct: legitimate work is refused on every cloud-protected VM while the log reads like the guard is doing its job.

Until wait_for_tag becomes cadence-aware, scope this hook's matcher to vSphere-protected workloads.