feat(guard): read the Zerto task, and ask before guarding unknown tools

Two changes that both come from the same mistake: assuming an answer
instead of reading one.

1. Read the task after inserting a checkpoint.

   POST /v1/vpgs/{id}/checkpoints returns a TASK ID, not a result. A 200
   only means queued. The outcome lives in GET /v1/tasks/{id} under
   Status.State: 1 InProgress, 4 Failed, 5 Stopped, 6 Completed, with
   4/5/6 terminal.

   tag_vpgs now waits for that task and refuses unless it Completed, and
   reports task_id and task_state. Measured: two inserts fired back to
   back at one VPG give Completed for the first and Failed for the
   second. That is exactly the case an earlier comment in this file
   called "silently dropped" -- it was never silent, we just never read
   the task. Comment corrected.

   Previously a failed insert surfaced only as wait_for_tag timing out
   45s later with a misleading hint about Azure/AWS. Now it says the
   task failed and the operation did not happen.

2. Unknown tools ask the human instead of passing through.

   The catalog is opt-in, so an unlisted tool ran unguarded. But the set
   of mutating tools is unbounded and grows with every MCP installed,
   while the set of read-only ones is small, so a mutating-only list is
   permanently behind and being behind fails open.

   Adds read_only_tools and zerto_check_tool(server, tool, vm) returning
   read_only / mutating / unknown. unknown does not mean safe: it means
   nobody classified it, so the tool hands the agent a question to put
   to the human, and the human decides whether to checkpoint. On yes the
   agent guards; on no it runs and says plainly that Zerto cannot rewind
   it; if they want it remembered, zerto_add_mutating_tool.

   This stays advisory. An MCP server cannot see or block another
   server's tool calls, so real enforcement belongs in a host PreToolUse
   hook. The skill carries the flow.

Known issue, not addressed here: two concurrent tool calls race on
Keycloak token acquisition in the shared client and one gets HTTP 401.

pytest 41 passed (12 new).

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_016yVfC5nvZowoLFnEGWhLGn

skills/zerto-rewind/SKILL.md

@@ -11,16 +11,33 @@ You talk to **one** MCP: `zerto_rewind_mcp`. Do not also require official ZVM MC
 
 ## Loop (mandatory)
 
-Before **every** guest-mutating tool call:
+Before **every** tool call that might touch a guest:
 
 1. Take the hostname / VM name / Zerto `vmIdentifier` from the tool args.
-2. Call `zerto_guard_before_mutate` with `change_id` and `action` (or `zerto_find_protection` then `zerto_create_tagged_checkpoint`).
-3. If `ok` is not true: **stop**. Do not mutate.
-4. Then run the mutating call.
+2. Call `zerto_check_tool(server, tool, vm)`. Act on the verdict:
 
-Reads skip the guard.
+| verdict | what you do |
+|---|---|
+| `read_only` | Run the tool. No checkpoint. |
+| `mutating` | Guard first. Do not ask — it is already known to change the guest. |
+| `unknown` | **Ask the human.** Do not assume it is safe, and do not silently guard. |
 
-Unlisted MCP tools pass through. If you are about to change a protected VM with a tool that is not in the catalog, call `zerto_add_mutating_tool` (server, tool, `vm_arg`) and then guard.
+3. For `mutating`, or for `unknown` where the human said yes: call
+   `zerto_guard_before_mutate` with `change_id` and `action`.
+4. If `ok` is not true: **stop**. Do not mutate.
+5. Then run the call.
+
+`unknown` is the normal case, not an edge case. The catalogs are short and the
+world of tools is not, so most tools are unclassified. Unknown means *nobody has
+said this is read-only* — it does not mean safe. Put the decision to the human:
+
+> `winrm/run_ps` is not a known read-only command. It may change `web01`.
+> Insert a Zerto tagged checkpoint first so this is reversible?
+
+If they say yes, guard, then run. If they say no, run it and tell them plainly
+that it is not reversible through Zerto. If they want it remembered, call
+`zerto_add_mutating_tool` (server, tool, `vm_arg`) so it is guarded
+automatically next time instead of asking again.
 
 ## find_protection outcomes