---
title: Tool permissions
description: Which tools an agent may run, where it may run them, and what was approved or blocked — the pre-tool permission axis, kept separate from Guard policies.
keywords: agent tool permissions, agent sandbox policy, tool risk governance, agent allowlist
eyebrow: 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](/docs/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](/docs/guard/approvals/)

## 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](/docs/guard/approvals/).

## 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.