> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Rules for Tool Calls

> Write rules that allow, flag, hold or stop the tool calls AI coding agents make, and test them before you rely on them.

> [!NOTE]
>
> Tool call governance is currently in limited beta. Contact Opal support to enable it for your organization.

A rule says what Opal does with the calls that match it. You manage rules under **Agent Center** > **Policies**. The tab is called **Policies** and the button is **New policy**, but the form says **Rule name** and **Create rule**. They mean the same thing.

Agent Consul can draft a rule from a plain-English description. You check and edit the draft before you save it.

## Requirements

Before you begin, you must:

* Be an Opal Admin to create or change rules. Read-only admins can view them.
* Have [tool call governance](https://docs.opal.dev/docs/tool-call-governance.md) enabled for your organization, and at least one agent set up.

> [!NOTE]
>
> Opal turns on enforcement for each organization. Until it is on for yours, a rule records what it would have done and stops nothing. Once it is on, a rule stops calls from the agents whose **Enforce** switch is on, and calls through Anthropic's inference hook. See [Log, Enforce and conversation content](https://docs.opal.dev/docs/tool-call-governance.md#log-enforce-and-conversation-content).

## Choose a result

| Result | What happens | What **Activity** shows |
| - | - | - |
| **Allow** | The call runs. | Allowed |
| **Allow and flag** | The call runs, and Opal marks it as flagged. | Flagged |
| **Ask the developer to confirm** | Claude Code asks the person to confirm the call. Cursor and Codex can't ask, so they refuse it. Calls through Anthropic's inference hook are refused too. | Held for approval in Claude Code, and Blocked in Cursor and Codex |
| **Block** | The call doesn't run. | Blocked |

Opal has no approval queue for tool calls. A call that needs confirmation is confirmed by the person using Claude Code, or it's refused.

## Choose what a rule matches

Each rule needs at least one condition. A call matches the rule only when it meets every condition. A call meets a condition when it matches any of the values you list in it. The exception is **Session**, where a call must match both the permission mode and the folder, if you set both.

| Condition | What it matches |
| - | - |
| **Tool** | The tool's name without its MCP server prefix, such as `Bash` or `delete_*`. |
| **Kind of action** | What the call does: Read, Write, Delete, Execute, Network or Admin. |
| **Arguments** | What the call sent, such as a command, a file path, a URL or a tool's input. |
| **Secrets** | Credentials in what the call sent. **Any secret** matches keys and tokens that Opal recognizes by their shape. Kinds that Opal recognizes only by a nearby name, such as **Credential field**, match only when you pick them. |
| **MCP server** | The server a tool came from, by name or from the list of servers, or servers nobody registered or approved. |
| **Agent** | The agent app, such as `claude-code`, `codex` or `cursor`, a specific agent, or an agent Opal has no record of. |
| **Session** | The permission mode and the working folder. Claude Code and Codex report both, and Cursor reports only the folder. A call that doesn't report a field never matches a rule that uses it. |
| **People** | Calls made for specific people or groups, calls with no person behind them, or people Opal can't identify. |

In a pattern, `*` matches any run of characters and `?` matches exactly one. Patterns ignore case and must match the whole value. They aren't regular expressions. In **Tool** and **Arguments** patterns, separate alternatives with a vertical bar, as in `Bash|Shell`. **Server name**, **Agent app** and **Folder** take one pattern. For example, a **Tool** of `Bash|Shell` and an **Arguments** pattern of `*terraform destroy*` match a shell command that runs `terraform destroy`.

An **Arguments** pattern is tried against the command or path, against every value the call sent, and against the raw input. To match text anywhere in a value, wrap it in `*`, as in `*DROP TABLE*`. To apply the rule to every call except the ones that match, turn on **Apply to every call except these**. Exceptions work for file paths (Read, Edit, Write and NotebookEdit) and for the domain of a web fetch, such as `docs.example.com`. The pattern is matched against the domain, not the whole address, and file path exceptions are case-sensitive. Shell commands and MCP calls always match.

To name specific people, groups or agents, describe them to Agent Consul, or open a call in **Activity** and select **Make a rule from this call**. The rule form can't pick them by hand. Once a rule is saved, neither the policy list nor the editor shows who it names, only how many.

## Decide what wins when rules conflict

More than one rule can match a call. Opal decides in this order.

1. A pause wins over everything else.
2. A server you blocked on the **Tools** tab is blocked, whatever the rules say.
3. Otherwise, the switch at the top of **Policies** decides: **Strictest wins** or **In order**. Only admins can change it, and it applies from the next call.
   * **Strictest wins** is the default. The most severe result wins: Block, then Ask the developer to confirm, then Allow and flag, then Allow. An Allow rule never overrides a Block rule.
   * **In order** lets the first matching rule in the list decide, whatever its result. An Allow rule above a Block rule lets the call through. Drag the rules into the order you want, then select **Save order**.
4. If no rule matches, Tool defaults decide.

## Set Tool defaults

Calls that no rule matches follow **Tool defaults**. Select **Tool defaults** next to **Rules** on the **Policies** tab.

| Setting | What it does |
| - | - |
| **Org default** | What happens to a call with no matching rule: **Allow**, **Ask** or **Block**. It starts as Allow. |
| **New tools start as** | For 7 days after a tool's first call: **Inherit the org default**, **Ask** or **Block**. This needs your organization to keep at least 7 days of activity. If it keeps less, Opal ignores the setting and doesn't save it. |
| A tool's own default | **Allow**, **Ask** or **Block** for one tool. It wins over the other two. |

A default of **Ask** or **Block** stops calls the same way a rule does. For agents that run a hook, it follows the same **Enforce** settings. Through Anthropic's inference hook, a default of **Ask** refuses the call.

## Calls that Opal flags without a rule

Opal also flags a call on its own when its arguments contain a credential that it recognizes by its shape, a US social security number, or a payment card number. It does this when no rule matches, and when an Allow rule matches. A stronger result, such as Block, still wins. **Activity** shows the reason, for example `Arguments contained: GitHub token.` Calls through Anthropic's inference hook are also flagged for an email address or a phone number.

## Start from the recommended rules

Every organization starts with a set of recommended rules. They all use **Allow and flag**, so none of them stops a call. You can edit any of them, turn it off, or change its result.

| Rule | What it flags |
| - | - |
| Credentials in tool arguments | A key or token that Opal recognizes in a call's arguments, such as a private key, a cloud access key or an API token. |
| Destructive shell commands | In a Bash or Shell call: force pushes, history rewrites, infrastructure teardown, database drops, and deleting `/` or the home folder. |
| MCP tools that delete | A call to an MCP tool with `delete` in its name. |
| MCP tools that destroy | A call to an MCP tool with `destroy` in its name. |
| MCP servers nobody approved | A call to an MCP server that no admin approved. Claude's built-in tools, servers Opal recognizes and claude.ai connectors count as approved. |
| Permission checks turned off | Every call from a session in `bypassPermissions` mode. Claude Code and Codex report the mode, and Cursor doesn't. |
| No person behind the call | A call that names no person. This rule starts turned off. |
| Code published outside the company | In a Bash or Shell call: a `gh` command that creates a public GitHub repository, makes one public, or creates a gist. |

If you delete a recommended rule, select **Restore recommended rules** to add it back. Restoring leaves the rules you edited or turned off as they are.

## Create a rule

1. Go to **Agent Center** > **Policies**.
2. Select **New policy**.
3. If you see **Describe the rule**, type what you want in plain English and select **Draft rule**. Agent Consul fills in the form for you to check and edit. Nothing applies until you save the rule. To skip it, select **Create manually**.
4. Enter a **Rule name**. You can add a **Description**, which admins see in the policy list and on each call the rule decides.
5. Choose a **Result**.
6. Select **Add condition**, and add at least one.
7. Check **Would have matched** to see which recent calls the rule matches.
8. Select **Create rule**. The rule applies from the next tool call.

To change a rule, select it in the list. Use the switch at the start of its row to turn it off or on, and the delete icon to delete it. An edit saves a new version. Calls that the rule already decided keep showing the rule as it was.

## Test a rule

Test a rule before you rely on it.

1. In the rule form, **Would have matched** shows how many calls from the last 24 hours the rule matches, then the count for the last 7 days. It lists example calls, and shows how many of the checked calls would get a different outcome. When nothing matches, it suggests similar tool names.
2. For an **Arguments** pattern, use **Try the pattern**. Type sample commands, paths or URLs, one per line, to see which ones match. Opal doesn't save the samples.
3. To try a rule on live calls without stopping anything, set the agent to **Log** on and **Enforce** off under **Setup** > **Clients**. Rules run, and **Activity** shows **Would have blocked** or **Would have asked** for the calls a rule would have stopped.
4. Ask the agent to run a harmless command that the rule matches, such as `echo opal-test`, and check **Activity**.

**Would have matched** checks the newest calls, up to a limit, and reads them as Opal stored them. Text that Opal masked, and arguments over the size limit, can't match. The count can be lower than it would be on live calls.

## What developers see when a call is stopped

* **A rule, a default or a blocked server stops a call.** The agent doesn't run the call. Opal sends the agent the reason.
* **A rule or default asks the developer to confirm.** Claude Code asks the person to confirm the call. Cursor and Codex can't ask, so they refuse the call, and Opal's reason says why. Calls through Anthropic's inference hook are refused too.
* **A pause is in force.** The agent doesn't run the call. See [Pause agents](https://docs.opal.dev/docs/tool-call-governance.md#pause-agents) for what Opal sends.
* **A call is allowed or flagged.** Nothing changes for the developer.

Each agent decides how it shows Opal's reason, and its setup page says what the person sees. The messages for a rule read like this.

```text theme={null}
This tool call was blocked by Opal policy "Block terraform destroy".
```

```text theme={null}
Opal policy "Review production deploys" needs a person to confirm this tool call.
```

```text theme={null}
Opal policy "Review production deploys" needs a person to confirm this tool call. This agent cannot ask you to confirm a tool call, so Opal denied it. If the call should run, ask an Opal admin to change the policy.
```

## Next steps

* See what each outcome means: [Read the outcome in Activity](https://docs.opal.dev/docs/tool-call-governance.md#read-the-outcome-in-activity).
* Choose what each agent logs and enforces: [Log, Enforce and conversation content](https://docs.opal.dev/docs/tool-call-governance.md#log-enforce-and-conversation-content).
* Stop agents for a while: [Pause agents](https://docs.opal.dev/docs/tool-call-governance.md#pause-agents).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.