How Guard works
The parts
| Part | Where it runs | What it does |
|---|---|---|
| Executor | Your environment, inside the agent's process (the SDK) or next to it (the MCP proxy, the HTTP broker) | Loads the policy, decides each action before it runs, records the decision, sends heartbeats |
| Control plane | Hosted by us, or in your network | Keeps projects, members, policies and their versions, reviews, approval tickets, events and the audit log |
| Console | In the browser, served by the control plane | Connections, policy editing and review, approvals, events, members |
The executor talks to the control plane over HTTPS with its own executor credential. The control plane never calls into your agent.
What an action is
Before a side effect, the executor builds an action: who is acting, what it wants to do and to what.
| Field | Meaning |
|---|---|
action_type | The kind of action: tool.call, mcp.call, network.http and so on |
resource | The tool, MCP tool or logical resource name, such as search_customer or mcp:finance__transfer |
arguments | The arguments the tool will receive. Used for the decision, never uploaded |
destination | Where an outbound call goes, for HTTP |
data_labels | Labels your code attaches, such as finance |
agent_id | The agent the executor credential belongs to |
subject_id | The trusted subject: the end user the agent acts for. It comes from your application (guard_run(subject_id=...) or an adapter's resolve), never from the model |
The action types Guard's own enforcement points use:
| Action type | Raised by |
|---|---|
tool.call | @guard.tool and every framework adapter |
mcp.admit | The MCP proxy, when it decides whether a tool or resource is listed at all |
mcp.call | The MCP proxy, for each tools/call |
mcp.read | The MCP proxy, for each resource read |
mcp.sampling, mcp.elicitation.form, mcp.elicitation.url | The MCP proxy, for questions an upstream server sends back |
network.http | The guarded HTTP client and the HTTP broker |
guard.authorize(...) and @guard.tool(...) also take your own action_type.
One call, step by step
- The agent proposes a call. The executor builds the action and evaluates the policy locally. The policy is already in memory, so no network round trip is needed.
- It records a
proposedevent with the decision. - If the decision lets the call run, it records
started, runs the tool with the arguments that were decided, then recordscompletedwith the outcome. - If not, the tool does not run. Your code or the model gets the reason (see what the model sees).
If started can't be recorded, for example because the local event queue is full, the tool does not run (GUARD_AUDIT_UNAVAILABLE).
The five decisions
| Decision | Console | What happens |
|---|---|---|
allow | Allow | The tool runs |
deny | Deny | The tool doesn't run |
allow_with_warning | Allow with warning | The tool runs; the event records what an enforcing policy would have decided (would_effect). Happens in Observe and Suggest mode |
require_approval | Require approval | The tool doesn't run. A one-use approval ticket is filed; after a reviewer approves, the same call can run once. Policy format v2, Enforce mode. See Approvals and degrade |
degrade | Degrade | The original tool doesn't run. A narrower fallback tool you registered runs instead, after its own check. Policy format v2, Enforce mode |
Each decision carries the rule that decided it, a reason code such as RULE_DENIED or DEFAULT_DENY, the policy version and the policy hash. Policies explains which rule wins.
When Guard can't decide
Guard fails closed. In each of these cases there is no decision, and the tool does not run:
- The control plane can't be reached and there is no valid cached policy.
- The cached policy is older than the allowed offline time.
- The executor credential was revoked or has expired (
GUARD_CREDENTIALS_INVALID). A 401 or 403 never falls back to the cache. - The
startedrecord can't be written (GUARD_AUDIT_UNAVAILABLE). - The trusted subject from an adapter's
resolveand the one inguard_rundiffer (GUARD_SUBJECT_MISMATCH), orresolvefails (GUARD_IDENTITY_UNAVAILABLE). - An internal error in the SDK.
A policy past its expires_at denies every action (POLICY_EXPIRED), whatever its mode.
How the failure reaches the agent depends on the framework: some stop the run, some hand the model an error result. See Framework adapters.
Offline and the cached policy
- The executor keeps the last verified policy in
.preworld-guard/policy.json(PREWORLD_GUARD_CACHEmoves it). The cache is bound to the project and the control-plane address, and its SHA-256 is checked when it is read. - With
guard.start(), the executor sends a heartbeat every 15 seconds and loads a new policy version as soon as it sees one. Without it, the client refreshes the policy when it is used and at least 60 seconds have passed. - If the control plane can't be reached, the executor keeps deciding with the cached policy. After 5 minutes without a successful refresh (the default
max_stale_age=300), it blocks every protected action until it reaches the control plane again. - Events wait in a bounded local queue (SQLite, next to the policy cache) and are sent when the control plane is back. A full queue blocks new actions rather than letting them run unrecorded.
- New approvals can't be filed or used while the control plane is down.
What leaves your environment
With the SDK, only redacted events are sent:
- IDs: event, run, trace, action, project, agent and trusted subject.
- What was attempted: action type, resource, destination, data labels, enforcement point, and the argument names.
- The decision: effect,
would_effect, rule, reason code, message, policy version and hash. - The outcome: status, the type of result or error, and SHA-256 digests of the arguments, result and error text.
Argument values, tool results, model prompts and output, source code and your business credentials stay in your process. Resource names, destinations and subject IDs can still be sensitive, so treat exported events like any other log. See Security.
What Guard can't see
Guard decides only what passes through it. Tools you didn't wrap, provider-hosted tools (for example an LLM vendor's built-in search), shell commands and raw sockets bypass it. Use the MCP proxy in its own process, the HTTP egress broker, network rules and a sandbox to close those paths, and test them with a call that should fail.