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

# Tool Call Governance

> See the tool calls that AI coding agents make on your organization's computers, and write rules that flag, hold or stop them.

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

A tool call is one action an AI agent takes, such as running a shell command, editing a file, or calling an MCP server. An MCP server is a service that gives an agent extra tools, for example GitHub or Notion.

Tool call governance shows you the tool calls that agents make on your organization's computers. Each call appears in Opal with the tool, its arguments, who it was for, and what Opal decided. You can also write rules that flag a call, ask the developer to confirm it, or stop it before it runs.

## Requirements

Before you begin, you must:

* Be an Opal Admin to change rules and settings, and to open **Setup**. Read-only admins can view Activity and rules.
* Have tool call governance enabled for your organization. Contact Opal support.

## How it works

A hook is something an agent runs at set moments, such as just before it runs a tool. Opal's hooks tell Opal what the agent is doing, and Opal answers. Depending on the agent, a hook is a small program that you install on each computer, or a setting that the agent reads, such as Claude Code's HTTP hook.

| When the hook runs | What it does |
| - | - |
| Before a tool call | Sends the call to Opal at once and waits for the answer. Opal records the call, checks it against your rules, and answers. This is the only check that can stop a tool call. |
| Any other time, such as when a call finishes | Sends the event to Opal. Opal records it and doesn't check it against your rules. |

When Opal stops a call, the hook passes the answer to the agent, and the agent doesn't run the call.

If Opal is slow or can't be reached, the call runs anyway. The hook fails open: when it can't reach Opal, or Opal doesn't answer within a few seconds, the agent runs the call as if there were no hook. The hook isn't a security boundary. It reaches only the computers that run it, and it relies on the agent to follow Opal's answer.

Cowork doesn't run a hook. You point Cowork's telemetry at Opal in Claude's admin console, and Opal reads it after each call. Opal records Cowork's calls, and it can't stop one through its telemetry. See the [Cowork page](https://docs.opal.dev/docs/tool-call-governance-cowork.md).

Anthropic's inference hook is a second route, for Claude.ai, Cowork and the API. Anthropic sends each tool call to Opal before it runs, and Opal's rules, Tool defaults, blocked servers and pauses decide it. Opal's answer applies at once. The **Log** and **Enforce** switches don't apply to these calls. They also don't wait for Opal to turn on enforcement. A rule or Tool default that asks the developer to confirm refuses the call instead, because the hook can't ask the person. If Opal can't answer, Anthropic applies your organization's failure handling for Inference hooks. To set it up, go to **Agent Center** > **Setup** > **Anthropic**, and find **Inference hooks**. The [Cowork page](https://docs.opal.dev/docs/tool-call-governance-cowork.md) has the details.

## Set up an agent

Each agent has its own setup page.

| Agent | Setup page |
| - | - |
| Claude Code | [Claude Code](https://docs.opal.dev/docs/tool-call-governance-claude-code.md) |
| Cowork | [Cowork](https://docs.opal.dev/docs/tool-call-governance-cowork.md) |
| Cursor | [Cursor](https://docs.opal.dev/docs/tool-call-governance-cursor.md) |
| Codex | [Codex](https://docs.opal.dev/docs/tool-call-governance-codex.md) |

To see the agents themselves, go to [Agent Inventory](https://docs.opal.dev/docs/agent-inventory.md).

## Where you work in Opal

Everything is under **Agent Center** in the left sidebar.

| Tab | What you do there |
| - | - |
| **Activity** | See each call and what Opal decided. |
| **Policies** | Write [rules](https://docs.opal.dev/docs/tool-call-governance-rules.md), set Tool defaults, and see the pauses in force. |
| **Tools** | Approve or block the MCP servers your agents call. |
| **Setup** | Get the settings and commands for Claude Code, Cowork and Cursor. Under **Clients**, choose **Log**, **Enforce** and **Store conversation content** for each agent. |

Admins and read-only admins can open Agent Center. Only admins can change rules and settings, and only admins see **Setup**.

## Log, Enforce and conversation content

Go to **Agent Center** > **Setup** > **Clients**. Each agent has these settings.

| Setting | What it does |
| - | - |
| **Log** | Records every call the agent makes, and the conversation if your content setting allows. |
| **Enforce** | Applies your rules to the agent's calls, so a rule can block or hold one. |
| **Store conversation content** | Decides whether Opal stores the prompts, replies and tool output that computers send. |

The settings apply to your whole organization. Computers pick up a change within a few minutes, with no reinstall.

### What the two switches do together

| Log | Enforce | What Opal does |
| - | - | - |
| On | On | Records every call and applies your rules. This is the default. |
| On | Off | Records every call and checks your rules, but no rule stops a call. Opal records what each rule would have done. |
| Off | On | Applies your rules. Records only the calls that Opal flagged, held or stopped. Stores no conversation content. |
| Off | Off | The hook sends no calls, and Opal drops any it still receives. Calls run without Opal's check. |

To switch an agent off, turn off both **Log** and **Enforce** for it. Turn either one back on to start again. Each agent's setup page says what a switched-off agent can still send.

Opal's Claude Code hook can also block a prompt that contains a key or token. **Enforce** must be on for Claude Code. Opal must also have turned on enforcement for your organization. The [Claude Code page](https://docs.opal.dev/docs/tool-call-governance-claude-code.md) explains it.

Cowork has **Log** and no **Enforce** switch, because Opal can't stop its calls through its telemetry. **Log** is on unless you turn it off.

> [!NOTE]
>
> Opal turns on enforcement for each organization. Until it is on for yours, **Enforce** behaves like **Log** only. Opal checks every call and records what a rule, a Tool default or a blocked server would have done, but none of them stops a call. **Activity** shows these calls as **Would have blocked** or **Would have asked**. Contact Opal support to turn on enforcement. A pause stops calls whether or not enforcement is on.

### Store conversation content

Conversation content is the prompts people send, the model's replies, and what each tool returned. Opal masks credentials and personal data that it recognizes, such as email addresses and phone numbers, and cuts long text.

Two settings decide whether Opal stores it. First, Opal turns on conversation content storage for each organization. Until it is on for yours, Opal stores none, whatever you choose below. Contact Opal support to turn it on. Second, **Store conversation content** under **Setup** > **Clients** sets the choice for each agent:

| Choice | What happens |
| - | - |
| **Always** | Every computer sends conversation content. This is the default. |
| **Each person decides** | A computer sends it only if its person installed the hook with the `--content` option (`-Content` on Windows). |
| **Never** | Opal stores none, even if the person used `--content`. |

The second setting matters only when the first is on. With **Log** off, Opal stores none. Each agent's setup page says what its computers send, and where a choice doesn't apply. For example, Claude Code's HTTP hook always sends conversation content, so **Each person decides** acts like **Always** for it. Cowork has no content choice, because each Cowork device decides what it sends. Opal stores what Cowork sends only when the first setting is on.

## Rules

A rule says what Opal does with the calls that match it. Each rule has a result: **Allow**, **Allow and flag**, **Ask the developer to confirm** or **Block**. You write rules under **Agent Center** > **Policies**, or describe one in plain English and let Agent Consul draft it. Every organization starts with recommended rules that flag risky calls and stop none.

A rule or Tool default that asks the developer to confirm works in Claude Code only. Cursor, Codex and Anthropic's inference hook can't ask the person, so they refuse the call. Opal has no approval queue for tool calls.

[Rules for tool calls](https://docs.opal.dev/docs/tool-call-governance-rules.md) covers the results, the conditions, what wins when rules conflict, Tool defaults, the recommended rules, and how to create and test a rule.

## Pause agents

A pause stops agent tool calls for a set time. It is the quickest way to stop calls while you check a policy.

* **Pause every agent.** Select **Pause agents** at the top of **Agent Center**. Choose 15 minutes, 1 hour, 4 hours or 24 hours, and, if you want, enter a reason. Opal sends the reason and the end time to the agent. While agents are paused, a banner shows when the pause ends, with **Extend** and **Resume now**.
* **Pause one agent or one person.** Open a call in **Activity** and use **Pause** in its details. Active pauses appear under **Paused now** on **Policies**, where you can end them with **Resume**.

A pause stops the calls that start while it is in force. It doesn't stop a call that was already running. A pause on one agent or one person applies only to calls that Opal can match to that agent or person. For agents that run a hook, a pause applies as long as **Log** or **Enforce** is on for the agent. It applies even before Opal turns on enforcement for your organization. Calls through Anthropic's inference hook are paused whatever the switches say. A computer that can't reach Opal, or has no hook, keeps running. If you don't see **Pause agents**, contact Opal support.

While a pause is in force, the agent doesn't run the call. Each agent decides how it shows Opal's message, and its setup page says what the person sees. When you pause every agent, the message reads like this.

```text theme={null}
Opal has paused agent tool calls for your organization until 15:00 UTC on Mar 3, 2027. Reason given: Checking a new policy. Contact an Opal administrator if you need this lifted.
```

When you pause one agent or one person, it reads like this.

```text theme={null}
This tool call was blocked by Opal policy "Pause Build bot". Paused by an Opal administrator until 15:00 UTC on Mar 3, 2027. Reason given: Checking a new policy. Contact an Opal administrator if you need this lifted.
```

## Read the outcome in Activity

| Outcome | What it means |
| - | - |
| Allowed | No rule stopped the call. |
| Flagged | A rule with **Allow and flag** matched, or Opal flagged the call on its own because its arguments carried a credential, a social security number or a card number. |
| Held for approval | A rule or default asked the developer to confirm the call. |
| Blocked | A rule, a default, a blocked server, or a pause on one agent or person stopped the call. |
| Denied | The pause on every agent stopped the call, or Claude Code or Cowork reported that the call was denied. |
| Would have blocked, Would have asked | A rule would have stopped or held the call, but the call ran. Either the agent has **Enforce** off, or Opal hasn't turned on enforcement for your organization. |
| Blocked, but it ran, or Denied, but it ran | Opal stopped the call, but the call ran. Either the agent ignored Opal's answer, or the hook didn't get the answer in time. Hover over the outcome to see which. A shell startup file that prints to the hook's output is a common reason an agent ignores the answer. |
| Held, but it ran | The hook didn't get Opal's answer in time, so the call ran. |

## What Opal records

For each call, Opal records:

* The tool's name and arguments, such as a shell command, a file path, a URL, or an MCP tool's input.
* Who the call was for and which agent it came from, when Opal can match them.
* The labels that the computer reports for the person, such as email addresses and the computer's name, where the hook reports them.
* The time, the working folder, and the permission mode where the agent reports it.
* What Opal decided: the outcome, the rule or default that decided it, and the reason.
* Whether the call ran or failed.

The hook sends arguments to Opal as they are, so rules can match them. Before Opal stores arguments, it masks credentials and personal data that it recognizes, such as email addresses and phone numbers. Opal doesn't store arguments over a size limit. **Activity** shows those as **Too large to store**.

With **Log** on and conversation content allowed, Opal also records prompts, replies and tool output.

Opal stores activity only after it turns on collection for your organization. After the number of days set for your organization, Opal deletes the activity that agents' hooks and telemetry reported. That period doesn't apply to calls through Anthropic's inference hook. Contact Opal support to change the period. Admins and read-only admins can see all of it.

## What isn't covered

* **Computers without the hook.** A computer that doesn't run the hook, or whose agent has **Log** and **Enforce** both off, runs calls without Opal's check.
* **Calls Opal can't check in time.** If Opal doesn't answer within a few seconds, the call runs. The hook may send the check again afterward, so Opal still records the call, without a decision.
* **Agents in a vendor's cloud.** The hook runs on your organization's computers. Each agent's setup page says what it covers.

## Next steps

* Set up an agent: [Claude Code](https://docs.opal.dev/docs/tool-call-governance-claude-code.md), [Cowork](https://docs.opal.dev/docs/tool-call-governance-cowork.md), [Cursor](https://docs.opal.dev/docs/tool-call-governance-cursor.md), or [Codex](https://docs.opal.dev/docs/tool-call-governance-codex.md).
* Write your first rule: see [Rules for tool calls](https://docs.opal.dev/docs/tool-call-governance-rules.md).


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