SafeClaw Policy Engine FAQ

How does the policy engine work?

SafeClaw's policy engine intercepts every action an AI agent attempts and evaluates it against an ordered list of policy rules. Evaluation uses a first-match-wins model: the engine iterates through rules from top to bottom, and the first rule whose conditions match the action determines the outcome (allow, deny, or audit). If no rule matches, the deny-by-default fallback blocks the action. The entire evaluation runs locally in sub-millisecond time. See also: What Is SafeClaw? FAQ.

What is a policy rule?

A policy rule is a single entry in a SafeClaw policy that defines: (1) conditions to match against an action (action type, target path/URL/command, optional metadata), and (2) an effect to apply if the conditions match (allow, deny, or audit). Rules are evaluated in order. A policy is a list of rules plus the deny-by-default fallback. See also: Action-Level Gating FAQ.

What conditions can I use?

Rules can match on action type (file_write, shell_exec, network), target (file path, command string, URL/domain), and optional metadata fields. Conditions support exact matches, glob patterns, and prefix matching. For example, a rule can allow file_write to /project/output/* while another denies file_write to /project/.env. Multiple conditions in a single rule are evaluated with AND logic — all must match.

What are the effect types?

There are three effect types: allow permits the action to execute, deny blocks the action entirely, and audit permits the action but flags it in the audit trail for human review. Every rule must specify exactly one effect. The deny-by-default fallback applies when no rule matches, ensuring unrecognized actions are always blocked. See also: Audit Trail FAQ.

What is deny-by-default?

Deny-by-default is SafeClaw's core security posture. Every action an AI agent attempts is blocked unless an explicit policy rule allows it. This is the inverse of most permissive systems, where everything is allowed unless specifically denied. Deny-by-default ensures that new, unexpected, or malicious actions are automatically blocked without requiring the user to anticipate every possible threat. See also: AI Agent Security Risks FAQ.

How does first-match-wins work?

First-match-wins means the policy engine stops evaluation as soon as it finds a rule whose conditions match the incoming action. The effect of that rule (allow, deny, or audit) is applied immediately. Rules are evaluated in the order they appear in the policy. This means rule ordering is critical — a broad allow rule placed above a specific deny rule will override the deny. Users should place more specific rules before more general ones.

Can I version control policies?

Yes. SafeClaw policies are stored as standard configuration files that can be committed to Git or any version control system. This enables change tracking, code review for policy changes, rollback to previous policies, and team collaboration on policy definitions. Version-controlled policies are a best practice for any team using AI agents in production. See also: Enterprise and Compliance FAQ.

What is simulation mode?

Simulation mode allows you to test a policy without enforcing it. In simulation mode, SafeClaw evaluates every action against the policy and logs the result (what would have been allowed, denied, or audited) but does not actually block any actions. This lets you validate that a new policy works correctly before switching to enforcement mode. Simulation mode is especially useful when onboarding a new agent or changing existing rules.

How fast is policy evaluation?

SafeClaw evaluates policies in sub-millisecond time. The policy engine runs entirely locally — no network round-trip is required for action decisions. SafeClaw is written in TypeScript strict mode with zero third-party dependencies, which contributes to its minimal overhead. In practice, the evaluation latency is negligible compared to the time AI agents spend on LLM inference or API calls.

Can I have per-agent policies?

Yes. SafeClaw supports defining separate policies for different agents or agent instances. Each agent can be assigned a distinct policy with different rules for file_write, shell_exec, and network actions. This enables the principle of least privilege at the individual agent level — a coding agent gets different permissions than a data analysis agent. See also: AI Frameworks FAQ.