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

# Claude and OpenAI enterprise hooks

> Require the account holder's approval before a governed AI tool call runs, switched on by your admin, with no change to the tools themselves.

Most BotShield integrations live inside the company that owns the tool: the MCP server or API checks for a BotShield proof before it acts. That gives the deepest control, but the tool vendor has to write the code.

Enterprise AI platforms now offer a second place to put the check: a **policy hook** that the platform calls before a prompt runs or before a tool call executes. The customer's admin turns it on, and every tool the organization's AI can reach is covered, including tools whose vendors have never heard of BotShield.

BotShield can act as the policy service behind those hooks. When a governed tool call needs a person, BotShield answers **deny** with a short reason, sends a request to the person's phone, and answers **allow** once they confirm with their passkey.

> [!NOTE]
>
> This is an enterprise engagement, not a self-serve setting. BotShield's professional services team sets up and runs the policy service with your security and IT teams. To start, email **[hello@botshield.ai](mailto:hello@botshield.ai)**.

## Where the hooks are

| Platform | Hook | Who turns it on | What it can check |
| - | - | - | - |
| Claude Enterprise | [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks) | Organization Owner or Primary Owner | Every governed prompt, and every tool call before it runs (with **Validate tool calls** on), across claude.ai, Claude Code, Cowork and other Claude Enterprise apps |
| Claude Code | [Hooks](https://code.claude.com/docs/en/hooks) in managed settings | IT, through managed settings or MDM | `PreToolUse` on any tool, including MCP tools (`mcp__.*`) |
| OpenAI Codex and ChatGPT Business or Enterprise | [Codex hooks](https://developers.openai.com/codex/hooks), managed through `requirements.toml` or the workspace's Agent Security settings | Workspace or IT admin | `PreToolUse` and `PermissionRequest` on shell, file edits and MCP tools |
| OpenAI Agents SDK | [Tool guardrails](https://openai.github.io/openai-agents-python/guardrails/) | The team building the agent | Each guarded tool call, including local MCP tools |

The Claude Enterprise inference hook is the broadest of these: it runs on Anthropic's servers, so it covers every Claude product in the organization with nothing installed on employee devices. The others run where the agent runs, so they're a good fit for developer tools and for agents your own teams build.

## How it works with Claude Enterprise inference hooks

Your admin points the organization's inference hook at a BotShield policy endpoint and turns on **Validate tool calls**. You agree with us which tools need a person: for example, any tool that moves money, sends email to customers, or changes production data.

```mermaid theme={null}
sequenceDiagram
    participant U as Employee
    participant C as Claude (Anthropic)
    participant B as BotShield policy endpoint
    participant P as Employee's phone (BotShield app)
    participant T as The tool

    U->>C: "Refund order 4417"
    C->>B: tool_call frame (issue_refund)
    Note over B: Tool needs a person. No approval on file.
    B->>P: Request: Approve refund for order 4417?
    B-->>C: deny + "Approve this in the BotShield app, then ask again."
    C-->>U: Blocked, with that reason
    P->>B: Approved with passkey
    U->>C: "Approved, go ahead"
    C->>B: tool_call frame (issue_refund)
    Note over B: Matching approval on file, unused, not expired
    B-->>C: allow
    C->>T: issue_refund runs
```

Step by step:

1. **The tool call arrives.** Anthropic sends BotShield the tool call frame before any tool in that response runs. One verdict covers all the tool calls in the response.
2. **BotShield checks the policy.** Tools that don't need a person get an immediate **allow**, so normal work isn't slowed down.
3. **No approval yet: deny and ask.** The hook has to answer within the timeout your admin sets (5 seconds by default, 10 seconds at most), which isn't long enough for someone to find their phone. So BotShield answers **deny**, with a `deny_reason` telling the person to approve in the BotShield app, and sends the request to their phone at the same moment.
4. **The person confirms.** They see what the AI is about to do and confirm with their passkey, or decline.
5. **The retry goes through.** When the person asks Claude to continue, the same tool call comes back. BotShield finds the matching approval and answers **allow**. Each approval covers one action, once, for a short time.

The person connects their BotShield app to your organization once, when you roll this out. After that, no names or emails are needed to send them a request.

### What BotShield receives and keeps

The inference hook sends the conversation transcript and an `actor` with an account ID and an email address. BotShield uses the account ID to find the phone bound to that account, keeping only a keyed hash of it, and doesn't store the email address or the transcript. What BotShield keeps is the same as everywhere else: an approval record tied to an opaque ID, the action that was confirmed, and when. See [Privacy boundary](https://docs.botshield.ai/concepts/privacy-boundary.md).

### Limits to plan around

* **Claude Enterprise only.** Inference hooks aren't available to Claude Platform (API) organizations, or on Amazon Bedrock or Google Cloud.
* **Deny, then retry.** The hook can only answer allow or deny, so the person sees one blocked attempt before the approved one.
* **Failure handling is your admin's choice.** If the policy endpoint can't be reached, Anthropic applies your organization's failure setting: block, or allow without inspection. For tools that need a person, we recommend **block**.
* **Roll out in shadow mode first.** Inference hooks support shadow mode, a rollout percentage and role exclusions, so you can watch verdicts on live traffic before anything is blocked.

## How it works with Claude Code and Codex hooks

Claude Code and Codex both run a `PreToolUse` hook before a tool executes, and both let IT lock hooks in place so engineers can't turn them off: managed settings for Claude Code, and `requirements.toml` or the workspace's Agent Security settings for Codex.

The flow matches the one above. The hook matches the tools that need a person (for example `mcp__payments__.*`), calls the BotShield policy endpoint, and either lets the call run or blocks it with a reason while the request goes to the person's phone.

> [!WARNING]
>
> OpenAI documents that a Codex `PreToolUse` error, timeout or malformed response can let the tool run, and that tool hooks are "a useful guardrail, not a complete enforcement boundary." Treat Claude Code and Codex hooks the same way: they're a strong control for developer tools, not a replacement for a check inside the tool when one is possible.

## How this fits with other BotShield integrations

| Approach | Who changes something | Best for |
| - | - | - |
| Enterprise hooks (this page) | Your AI platform admin | Covering every tool your organization's AI can reach, including third-party tools |
| [agentgateway](https://docs.botshield.ai/integrations/agentgateway.md) | Whoever runs the gateway | MCP traffic that's already routed through a gateway |
| [Agents Ask](https://docs.botshield.ai/agents-ask/overview.md) and the [Server SDK](https://docs.botshield.ai/sdk/typescript.md) | The company that owns the tool | Per-action confirmation built into the product, with a signed Proof of Resolution |

These work together. A tool that checks BotShield itself keeps doing so, and the hook adds coverage for the tools that don't.

## Talk to us

Implementation is handled by BotShield's sales and professional services team. We'll help you:

* choose which tools and teams need the account holder's approval;
* set up the policy endpoint, signing secret and failure handling with your security team;
* link employees' BotShield apps to your organization;
* roll out in shadow mode, then turn on enforcement.

Email **[hello@botshield.ai](mailto:hello@botshield.ai)** to start an enterprise engagement.


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