Documentation
Shield docsIntegrate Shield

Embedded enforcement handoff

Use shield::enforcement::handoff to embed Shield in a trusted Rust host. It revalidates policy evidence and invokes your callback only for an allowed operation. Your host classifies requests and performs the operation.

For Claude or Codex setup, use native project setup. For restricted SDK reads, use Claude SDK integration. The embedded API installs neither integration.

Integration contract

Load the project’s active snapshot, evaluate the request, and classify it with enforcement::AgentAccess:

Access Gate behavior
Ordinary Revalidate current state; invoke the callback only for allow
Operator Block approval, grants, activation, enrollment and protection disabling
AuthorizationStateWrite Block direct mutation of retained policy/approval/active state or its storage parents
Unclassified Block unsupported or ambiguous requests

Allow rules cannot override protected or unclassified access. Ask returns ApprovalRequired, Deny returns Denied, and state or locking failures return Runtime with the cause. This API cannot issue or consume approval grants.

Classification is the host’s responsibility; AgentAccess cannot be deserialized from agent JSON. Intercept every applicable tool path, including indirect writes to state files, directories, and ancestors. The API does not inspect paths, resolve aliases, parse vendor tools, or verify executable identity and future shell effects. Incorrect classification defeats its protection.

Handoff and failures

The callback receives the original request/evaluation while the writer lock is held. Keep it short; do not wait for process completion or acquire another review writer lock. Same-policy reactivation, foreign enrollment or corrupt state prevents ordinary handoff. Snapshot checks do not prove executable or filesystem stability.

The outer Result reports protection failures; the inner value is the callback’s result. Panic unwinding releases the lock. A lock-release error can occur after the callback ran, so check its effects before retrying.

Handoff consumes its evidence through Rust ownership. Callers can evaluate a new request; consuming evidence is not a one-time approval grant. Unrestricted processes can still invoke the operator CLI or write state.

Verified scope

Local macOS tests cover decisions, protected access, stale and corrupt state, callback errors, and panic cleanup. Doctests check ownership and reject JSON access claims. Host interception and request classification need their own verification.

The embedded gate writes no audit history. The SDK adapter and native runner use separate approval gates and record their own observations. None provides OS isolation from unrestricted same-user processes.