Guard & governance

Tool permissions#

Which tools each agent can run, where they run, and what got approved or blocked.

This is the pre-tool axis. It is deliberately a different table, a different timing and no shared state with Guard policies, which are mid-run enforcement. Two endpoints with similar names, two genuinely different features:

	`/api/tool-policy`	`/api/guard/policies`
Timing	Before a tool runs	During a run
Trigger	The tool being called	A detector incident
Effect	Allow, block, require approval	Pause, stop, kill

The tab#

Tool permissions shows, per agent:

Which tools it is permitted to call
Where — the working directories and sandboxes those calls are allowed in
What has actually been approved or blocked, with the decision trail

The last part is the useful one day to day. A policy you wrote six months ago that is silently blocking something is only visible if the blocks are recorded, and they are.

bash

curl -s localhost:8900/api/tool-policy -X POST -d '{}' -H 'content-type: application/json' | jq
curl -s localhost:8900/api/security/policy-events | jq

Risk classes#

Tools are grouped by what they can do, because writing a rule per tool name does not survive a runtime adding tools:

Class	Examples
Read	file reads, searches, listing
Write	file edits, patches, writes
Execute	shell, exec, terminal, run_command
Network	fetch, browser, API calls
Privileged	anything requiring elevation

A rule on a class covers tools that did not exist when you wrote it, which is the difference between a policy that holds and one that quietly stops covering new surface.

The sandbox axis#

Where a tool runs is as important as whether it runs. A shell command inside a project directory and the same command in your home directory are not the same risk, and the permission surface treats the location as part of the rule.

bash

curl -s localhost:8900/api/sandbox-status | jq

Approvals#

A rule can require a human decision rather than allowing or blocking outright. That routes into the approval queue. → Approvals and pre-tool gates

What the runtime already enforces#

Most runtimes have their own permission model, and ClawMetry's job here is mostly to make it visible and consistent rather than to replace it. An agent that is already restricted by its own sandbox is restricted; what ClawMetry adds is one place to see all of them at once, and a record of what was decided.

Where a runtime's hook is fail-open, ClawMetry's layer is advisory. See the fail-closed discussion in Approvals and pre-tool gates.

Auditing#

bash

curl -s localhost:8900/api/audit-log | jq
curl -s localhost:8900/api/agents/audit -X POST -d '{}' -H 'content-type: application/json' | jq
curl -s localhost:8900/api/authority-violations | jq

authority-violations is the interesting one: actions an agent took that its declared permissions did not cover. On a well-configured node this should be empty, and a non-empty result is either a misconfiguration or something worth reading carefully.

Tier#

tool_policy is a Pro feature. audit_logs and siem_export are Enterprise.

Edit this page View as Markdown Report an issue