What this project is about
Tool Policy Playground demonstrates application-side permission checks for AI agents that use tools. A model may request an action, but ordinary application code decides whether it is allowed on the named resource, such as a file or calendar. Default-deny means nothing is allowed without a matching permission; an explicit prohibition overrides a permission. Proposing an action is not the same as being authorized to perform it.
This is a compact learning tool, not a production authorization library. It compares action and resource names with policy rules and explains the decision. It does not verify a user's identity or consent, execute the tool, establish who owns a resource or determine whether the detailed parameters of an otherwise permitted action are safe.
How it works
- Proposed tool action
- Explicit permission policy
- Allow / deny decision
Check rules and requests
A policy must declare default deny and contain a list of rules. Each rule needs text fields for its ID, action and resource, plus an allow or deny effect. Requests must also supply text action and resource names. Invalid input is rejected rather than interpreted as permission.
Match action and resource
Rules use case-sensitive glob matching: patterns with wildcards that match text names. Both the action pattern and resource pattern must match. Permission to read a project document therefore does not automatically permit deleting that document or reading a resource outside the specified pattern.
Explain conflicting rules
The evaluator gathers all matches, chooses the first explicit deny if one exists, otherwise the first allow, and otherwise denies by default. Its JSON decision records the request ID, selected rule ID and reason. Rule order matters when several rules with the same allow or deny effect match.
The important design choices
Deny unknown actions
Require a matching permission rather than assuming unfamiliar actions are allowed.
The trade-offNew tools require deliberate rule changes; inventing a new action name does not automatically expand what the caller may do.
Keep patterns simple
Use visible wildcard rules instead of a large policy framework.
The trade-offThe decision is easy to inspect, but broad patterns can permit unintended resources. Text matching alone does not understand ownership, customer boundaries or different paths that refer to the same resource.
Keep a sensitive file blocked
A policy allows reading project documents but explicitly denies reading one sensitive resource.
- Submit a read request that matches both rules.
- Collect all matches instead of stopping at the earlier permission.
- Return the explicit denial and its rule identifier for inspection.
What this showsThe broad permission does not override the specific restriction, and the decision record explains why the request was denied.
Illustrative example, not an additional measured result.
How it was tested—and what it shows
The checks
The public security notes document rejection of unknown tools, conflicting allow/deny rules and requests for invented resources. The code makes the decision order inspectable and identifies the line containing invalid request data. These behaviours demonstrate repeatable rule evaluation; they do not prove complete agent safety or verify who is making the request.
What to take from the results
The deliverable is an explainable default-deny evaluator. Model output remains an untrusted request, not proof of permission. A production tool gateway would still need verified identity, checks on each parameter's type and value, time-limited approvals where appropriate, ownership checks, protected policies and retained audit records. Correct rule evaluation cannot compensate for unsafe rules.
What to keep in mind
- Correct policy decisions still depend on correctly implemented tools.
- This is an educational component, not a complete agent security system.
Technical notes & source
Built with
Python · policy evaluation · agent tools
Terms used in this project
- Default deny
- Reject an action unless a rule explicitly permits it.