Approvals

How it works

1. A policy rule matches an agent tool call and returns require_approval.
2. The Guard hook keeps the tool call waiting and sends an approval request to Guard Cloud from the enrolled device.
3. An administrator approves or denies it in the Console.
4. The hook consumes the approval once and lets that one action run.

The hook waits at most 10 seconds in total. Anything other than a valid, live, one-time approval of the exact action denies it: a timeout, a network error, a denial, an expired request, a changed input or a repeated use.

The request carries only digests of the harness session and the exact action (tool name, working directory and tool input). Raw tool input, prompts, commands, paths and secrets are never sent.

Policy decisions

Response rules use a versioned decision object:

{"version": 2, "verb": "require_approval"}

The older warn, ask and block strings still work unchanged. An older Guard build rejects version 2 objects rather than treating them as warnings.

Harness support

Copilot hooks have no stable session identity, so approval and quarantine deny.

Warning: These hook paths are tested with real Guard processes, not yet in live sessions of every vendor release. Check what your installed version supports with guard approval capabilities HARNESS.

Deciding in the Console

The approval queue lists requests newest first. Filter by state, device, harness and time.

Any Console role can view the queue. Only an administrator can decide. A decision needs:

• approve or deny;
• the reviewed action digest;
• a reason of 1 to 200 bytes;
• optionally, a shorter approval window of 1 to 300 seconds.

Rules for decisions:

• Each approval covers one exact action, used once. A changed input needs a new request.
• Decisions can't be changed. An identical retry returns the recorded decision.
• With SSO and a device bound to a directory identity, that person can't approve their own device's requests. Another administrator must.
• There is no two-person rule for action approvals.
• Each decision is written to the audit log as approval.approve or approval.deny.

Automation can decide with an organization machine-administrator key through POST /v1/admin/approvals/decide. Never put that key on an endpoint.

Audit on the device

Guard records every response decision before it allows or modifies an action. If it can't record it, it denies the action. The record holds metadata only and reaches Guard Cloud through the signed device channel. It records the decision, not proof that the vendor ran the tool.

Managed Linux hooks

By default, the device user controls Guard's enrollment, policy and state, so they could point the hook at their own server. On Linux, administrators can pin the authority instead:

guard --managed-endpoint claude-tool-hook

The global flag must come first. The same applies to the Codex, Copilot, Cursor, Gemini, Windsurf and Cline tool-hook commands.

• The root-owned /etc/runeward/collector.json pins the user's enrollment and server.
• An optional managed_catalog entry pins the policy (path, sha256, public_key).
• Managed approvals require HTTPS, even on loopback. A self-hosted private CA can be pinned with approval_ca: {path, sha256}.
• Any missing or changed pin denies. Managed mode is Linux only; elsewhere it denies.

Limits

• A harness that kills, skips or removes the hook can ignore its result. Missing hooks and already-running tools are outside enforcement.
• Some harnesses fail open. Gemini CLI and Copilot CLI run the action when a hook times out or returns malformed output. Hook deadlines installed by older versions were five seconds: run guard hooks repair to update them.
• Cline ignores failed or timed-out hooks. Set Cline's hook timeout above Guard's 10-second budget plus start-up time, and test it.
• Where tool output already reached the model, Guard can only block or warn; it can't undo the exposure.
• Quarantine does not kill processes or end the session in the vendor's tool.
• The local guard approval approve and deny commands are user-owned and never authorize a hook. Only a Cloud approval does.

See limits.md and hooks.md.