Action approvals and degrade
Scope: current hosted production uses organization workspaces. Personal workspaces and owner self-review require a later control-plane upgrade; self-hosted installations depend on their actual version and identity configuration.
Policy format v2 adds two rule effects for calls that shouldn't simply be allowed or denied:
require_approval: the call waits until a named reviewer approves it, and then it can run once, with exactly the arguments that were approved.degrade: the original tool doesn't run. A narrower fallback tool you registered runs instead.
Both apply only in Enforce mode. In Observe and Suggest mode they are recorded as "allow with warning". Neither ever runs the original tool without a decision.
Scope
Action approvals cover tool calls made through the SDK and the MCP proxy. Shell commands, files and network access outside those paths are allowed or blocked by your isolation layer, and a ticket can't open them.
Before you start
- The policy is format v2 (
schema_version: guard.policy.v2) and in Enforce mode. - Every active executor supports format v2. The SDKs the wizard installs do.
- Every call an approval rule can match carries a trusted subject, the end user it is for:
guard_run(subject_id=...)or an adapter'sresolve. A call without one is refused (APPROVAL_SUBJECT_REQUIRED), never queued. - Reviewers have been named. The owner gives the reviewer role, and each reviewer's trusted subject, on "Members".
How an approval goes
- The agent proposes a call that an approval rule matches. The SDK files a ticket with the control plane and does not run the tool. The ticket is bound to the project, agent, trusted subject, tool, a SHA-256 digest of the exact action, the rule and the policy version. It carries a short redacted preview, never the raw arguments. It is valid for one hour.
- Your code gets the ticket ID. With a framework adapter, the model sees it too.
- A reviewer opens "Approvals" in the console, checks the preview and the binding, and clicks "Approve once" or "Reject".
- Your application resumes the call. The SDK consumes the ticket, which works once, and runs the tool on the approved arguments.
Rules the control plane enforces:
- A reviewer can't approve an action whose trusted subject is themselves.
- The owner can't approve actions in place of a reviewer. Reviewers and admins can.
- A later personal-workspace release permits the owner to review their agents' actions, while still refusing self-subject approvals. This exception is not enabled in current hosted production.
- Changed arguments, a changed policy, a replay of a used ticket or an expired ticket are all refused (
APPROVAL_NOT_CONSUMABLE). If the policy changed while the ticket was being filed, the reason isPOLICY_CHANGEDand the SDK refreshes the policy. - The same action proposed again before a decision gets the same ticket, not a new one.
Resuming in Python
For a function you wrap yourself, pending=True keeps a private snapshot of the arguments so that you can resume later, even after a restart:
from preworld_guard import GuardApprovalRequired, guard_run
@guard.tool('finance.submit', pending=True)
def submit(payload):
return trusted_business_api.submit(payload)
with guard_run(subject_id=trusted_employee_id):
try:
submit({'amount': 4200})
except GuardApprovalRequired as pending:
ticket_id = pending.ticket_id
# Resume from the application after a reviewer approves. Never let the model change the arguments.
if guard.pending.status(ticket_id)['status'] == 'approved':
result = guard.pending.resume(ticket_id)The snapshots live in pending.sqlite3 next to the policy cache, readable only by the process owner, and only for tools marked pending=True. Keep that folder on protected or encrypted storage.
Other ways to resume:
| Way | Use it when |
|---|---|
with guard_approval(ticket_id): | You call the guarded entry point again yourself. The first matching call consumes the ticket; any later use fails |
with guard_resume(ticket_id): | A framework agent should run again. When the model proposes the same call, the adapter consumes the ticket once; other calls in the scope are decided as usual |
auto_resume_approved=True | OpenAI Agents, Claude Agent SDK, Microsoft Agent Framework, LlamaIndex, Agno, DSPy and CrewAI adapters: an approved ticket is consumed without guard_resume |
| Pydantic AI's own deferral | The default for Pydantic AI; see Framework adapters |
guard.approval_status(ticket_id) returns pending, approved, rejected, consumed, canceled, expired or policy_changed. guard.cancel_approval(ticket_id) withdraws a ticket.
When something fails mid-way
The SDK marks its intent to run before it consumes the ticket. If the process crashes, the connection drops or the task is cancelled after that, the snapshot stays as executing or uncertain and is never replayed automatically. Check the business result yourself and file a new approval if needed. Guard can't promise exactly-once for an outside system: give your write tools an idempotency key and reconcile.
Approvals through the MCP proxy
The proxy returns a pending approval as an error result (isError: true) whose text has status: approval_required, the ticket, its expiry and the policy version. The same ticket is in the result's _meta["com.preworld.guard/approval-id"]. After approval, the client retries the same tool with the same arguments and the ticket in the request's _meta:
result = await session.call_tool("finance__transfer", {"account_id": "demo-42", "amount": 1})
ticket = result.meta["com.preworld.guard/approval-id"]
# After an independent reviewer approves, retry with the same tool name and arguments:
result = await session.call_tool("finance__transfer", {"account_id": "demo-42", "amount": 1},
meta={"com.preworld.guard/approval-id": ticket})Start the proxy with --subject-id agent-service-1 (or PREWORLD_GUARD_SUBJECT_ID) to bind its requests to a trusted service subject. That is a process-wide service identity, not an end user. A proxy shared through one downstream token can't tell people apart. Without a subject, approval calls are refused. MCP clients that can't send _meta on a retry only ever see the pending error.
Degrade
A degrade rule names a fallback:
schema_version: guard.policy.v2
policy_id: support-v2
mode: enforce
default_effect: deny
rules:
- rule_id: crm-read
effect: allow
risk: normal
match: {resource: crm.read}
- rule_id: crm-delete
effect: deny
match: {resource: crm.delete}
- rule_id: transfer-approval
effect: require_approval
match: {resource: payments.transfer}
- rule_id: export-degrade
effect: degrade
fallback_resource: report.export_summary
match: {resource: report.export_full}
- rule_id: export-summary
effect: allow
risk: normal
match: {resource: report.export_summary}- Register the fallback in the agent's process:
guard.register_fallback(resource, function, map_arguments=...).map_argumentsturns the original arguments into the fallback's. - The fallback is checked on its own, and it must be plainly allowed by the policy (the
export-summaryrule above). Otherwise it is denied (FALLBACK_NOT_ALLOWED). - If no fallback is registered, or it can't run on this path (an async fallback for a sync tool), the call is denied (
FALLBACK_UNAVAILABLE). - The Claude Agent SDK can't swap a tool's output, so there a degrade denies the call and names the fallback in
fallback_resourcefor the model to call instead. - Through the MCP proxy, degrade works only with a registry configuration that maps the original tool to a reviewed fallback tool. A single-upstream proxy denies instead.
Register only fallbacks that your team has reviewed as safe, ideally without side effects.