Struct PolicyEngine 

pub struct PolicyEngine { /* private fields */ }

Evaluates actions against registered policies.

Implementations

impl PolicyEngine

pub fn new() -> PolicyEngine

pub fn register( &mut self, name: &str, check: Box<dyn Fn(&Action, &StateStore) -> Option<String> + Sync + Send>, description: &str, )

pub fn register_tool_deny( &mut self, name: &str, tool: &str, check: Box<dyn Fn(&Action, &StateStore) -> Option<String> + Sync + Send>, description: &str, )

Self::register, plus the standing fact that check forbids tool outright — whatever the arguments.

Use this for a rule that denies a whole tool, so it can be read back by Self::blanket_denied_tools. The check itself is still the caller’s, deliberately: a file-loaded rule and a host-registered one word their refusal differently, and centralizing the closure here would make one of those messages wrong.

Registering a conditional check through this door mislabels it and will hide a tool that is only sometimes denied. There is no way to check that from here — the check is an opaque closure — so the contract is on the caller.

pub fn check(&self, action: &Action, state: &StateStore) -> Vec<PolicyViolation>

Check an action against all policies.

If a policy check panics, the panic is caught and treated as a violation.

pub fn unregister(&mut self, name: &str) -> usize

Remove every policy registered under name. Returns how many were dropped — 0 when nothing matched, so the caller can distinguish “removed” from “there was nothing by that name”.

Self::register appends without de-duplicating, so the same name can legitimately appear more than once; this removes all of them rather than leaving a shadowed copy still enforcing (Parslee-ai/car#623).

pub fn clear(&mut self) -> usize

Drop every registered policy. Returns how many were removed.

pub fn blanket_denied_tools(&self) -> BTreeSet<String>

The tools this engine forbids outright, whatever the arguments — the deny_tool rule kind, and only that kind.

For callers that assemble the tool list a model is shown. A tool no call can ever satisfy is worth removing from that list rather than advertising and then refusing: the refusal is correct but costs a turn and a schema’s worth of context on every request.

Why only deny_tool

Not because the other kinds are “argument-dependent” — several of them can forbid a tool outright too:

• allow_tool_param with an empty allow permits nothing.
• rate_limit_tool with max_calls = 0 denies every call.
• deny_tool_param_matching whose pattern fails to compile denies the whole tool, fail-closed.
• deny_tool_param with neither equals nor contains denies on the parameter’s mere presence, which is total for a required parameter.

The property that actually separates them is whether totality is decidable from the rule kind alone, without reading the rule’s contents. deny_tool is the only kind where it is. The others are total only by inspection, and a caller assembling a tool list has no business inspecting them — so this deliberately under-reports rather than guess. Under-reporting is the safe direction: the tool is advertised and then refused, which is exactly the old behavior.

A narrow-but-not-total allow_tool_param is the case this leaves on the table. Hiding is the wrong remedy there (the tool is callable, just not that way); narrowing the advertised parameter schema to the permitted values is, and that is a separate change.

Populated by Self::register_tool_deny and emptied in step with Self::unregister and Self::clear, so it cannot name a tool the engine no longer blocks. A stale entry here would hide a tool that is actually allowed, which is the one failure mode worth engineering against.

pub fn policy_names(&self) -> Vec<String>

Registered policy names, in registration order. May contain duplicates — see Self::unregister.

pub fn policy_details(&self) -> Vec<(String, String)>

Registered policies as (name, description) pairs, in registration order. The description is what register was given.

pub fn is_empty(&self) -> bool

Trait Implementations

impl Default for PolicyEngine

fn default() -> PolicyEngine

Returns the “default value” for a type.