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

# Coding agents

> Check what Claude Code, Codex and Cursor do on your developers' machines, before it runs.

See and stop what coding agents do for your developers. Their hooks send each prompt and tool call to Xenovia before it runs, and Xenovia answers with a decision.

For example, a developer's agent runs `curl https://example.sh | sh`. Xenovia refuses it before it runs, the agent is told to take another approach, and the session shows the rule that fired.

Xenovia checks each call with built-in rules, the agent's [policies](https://docs.xenovia.io/control/policies.md) and [Neon](https://docs.xenovia.io/control/neon.md). The prompts and actions show up in **Sessions**. The hooks don't change where the coding agent sends its model requests.

## Set it up

> [tab] Claude Code
>
> ### Before you start
>
> * You need to be an admin of your Xenovia organization.
> * For everyone in a Claude organization: a Claude Team or Enterprise plan. Pasting the settings needs an Owner of that organization.
> * For one person: a Claude Pro or Max plan, and Node.js on each computer.
> * **Block actions when Xenovia can't be reached** needs Claude Code 2.1.295 or later.
>
> **1. Open Claude Code in Xenovia**
>
> In first-run setup, choose **Protect your agent**, then **Claude Code**. Or, on **Agents**, click **Create agent** and pick **Claude Code** under **Coding agents**. Or, in **Settings**, open **Integrations**, then **Claude Code**.
>
> **2. Set up**
>
> * **Name**: the agent's name in Xenovia.
> * **What developers use it for**: optional. It is saved as the agent's purpose.
> * **When Neon finds a problem**: **Monitor** records it in Sessions and lets the action run. **Enforce** stops the action and tells Claude Code why. Monitor is the default.
>
> Click **Connect**. Xenovia creates the agent, activates it, and makes a hooks key for it.
>
> **3. Add it to Claude**
>
> Under **Your Claude account**, pick where the settings go.
>
> **Enterprise account** (Team or Enterprise plan). An admin pastes the settings once in Claude for everyone.
>
> 1. Choose the options. **Lock it down** (on by default): only these hooks run, developers' own hooks are turned off, and Claude Code won't start until it has your organization's settings. **Block actions when Xenovia can't be reached** (off by default): otherwise actions go ahead unchecked.
> 2. Click **Copy settings and open Claude**. This opens Claude Code's admin settings in claude.ai.
> 3. In **Managed settings**, paste them and click **Save**. Every developer signed in to your organization gets them.
>
> **Individual account** (Pro or Max plan). Click **Copy command** and run it on each computer that uses Claude Code (it needs Node.js), then restart Claude Code. The command adds Xenovia's hooks to `~/.claude/settings.json`, keeps your other settings, and saves the old file as `~/.claude/settings.json.bak`. Running it again replaces Xenovia's hooks rather than adding them twice. The two Enterprise options don't apply here.
>
> Click **See what we paste** to read the settings first. The key is in the settings and isn't shown again.
>
> **4. Verify**
>
> Click **Check it's working**. Start Claude Code and send a prompt; it picks up new settings when it starts. When the first event arrives, the page says **Claude Code is connected**. Click **Open agent** to see it.
>
> ![Connect Claude Code dialog on the Add it to Claude step, with Enterprise account selected and Lock it down on](https://mintcdn.com/xenovia/RO5UF1Tk8L9B7yPt/images/screens/coding-agents-claude-code.png?fit=max\&auto=format\&n=RO5UF1Tk8L9B7yPt\&q=85\&s=360b416d84bfc4c03a8394beb4dda1c3)
>
> Connecting Claude Code: Add it to Claude
>
> > [accordion] The settings Xenovia generates
> >
> > With **Lock it down** on, the managed settings look like this. Xenovia fills in the runtime address, and the key in place of `xe_REPLACE_WITH_HOOKS_KEY`. The `PreToolUse`, `PostToolUse` and `Stop` entries repeat the same hook; `PreToolUse` and `PostToolUse` add `"matcher": "*"`.
> >
> > ```json managed-settings.json theme={null}
> > {
> >   "hooks": {
> >     "UserPromptSubmit": [
> >       {
> >         "hooks": [
> >           {
> >             "type": "http",
> >             "url": "https://runtime.xenovia.io/v1/hooks/claude-code",
> >             "headers": {
> >               "Authorization": "Bearer xe_REPLACE_WITH_HOOKS_KEY",
> >               "X-Xenovia-User": "$USER"
> >             },
> >             "allowedEnvVars": ["USER"],
> >             "timeout": 10
> >           }
> >         ]
> >       }
> >     ],
> >     "PreToolUse": [{ "matcher": "*", "hooks": [ /* same hook */ ] }],
> >     "PostToolUse": [{ "matcher": "*", "hooks": [ /* same hook */ ] }],
> >     "Stop": [{ "hooks": [ /* same hook */ ] }]
> >   },
> >   "allowManagedHooksOnly": true,
> >   "forceRemoteSettingsRefresh": true
> > }
> > ```
> >
> > * **Lock it down** adds `allowManagedHooksOnly` and `forceRemoteSettingsRefresh`.
> > * **Block actions when Xenovia can't be reached** adds `"onFailure": "block"` to each hook.
> > * `X-Xenovia-User` sends the developer's computer user name with each event; it is recorded as the session's user.
>
> ### Hook events
>
> | Hook event | What Xenovia does | Stage |
> | - | - | - |
> | `UserPromptSubmit` | Starts a new turn. Stops a prompt that contains a credential | — |
> | `PreToolUse` | Answers read-only calls at once, applies the built-in rules, and judges the rest | `tool_call` |
> | `PostToolUse` | Records the tool's input and output. Judges output that came from outside | `tool_result` |
> | `Stop` | Records Claude's final reply and closes the turn | — |
>
> | Call | Answered at once | Built-in rule | Judged at `tool_call` |
> | - | - | - | - |
> | `Bash` | Every part of the command only reads or runs tests: `ls`, `cat`, `rg`, `git status`, `git diff`, `go test`, `npm test`, … | See [Built-in rules](#built-in-rules) | Everything else |
> | `Edit`, `Write`, `MultiEdit`, `NotebookEdit` | Files inside the working directory | Claude Code's settings, `.mcp.json`, git hooks or git config; content that looks like a credential | Files outside the working directory, and `.github/workflows/` |
> | `Read` | Yes | A credentials file | — |
> | `WebFetch`, `WebSearch` | Yes. The output is judged after the tool runs | — | — |
> | Sub-agents, tasks, plans, `Grep`, `Glob` | Yes | — | — |
> | MCP tools (`mcp__<server>__<tool>`) and any other tool | — | — | Yes |
>
> A sub-agent's own tool calls come back through the same hooks. Outside output judged at `tool_result`: `WebFetch`, `WebSearch`, MCP tools, and `Bash` commands that print what they read from the network.
>
> **Built-in rules that ask.** Claude Code can ask the developer, so `rm-outside`, `force-push`, `sudo`, `secret-file`, `sandbox-off` (a command that asks to run outside Claude Code's sandbox), `agent-config` (an edit to Claude Code's settings, `.mcp.json`, git hooks or git config) and `secret-in-file` show its permission prompt with the rule's reason. The developer decides.
>
> **When Xenovia finds nothing**, it gives no opinion: Claude Code's own permission rules and mode decide. Xenovia never answers "allow", so it never skips the developer's permission prompt.
>
> **Hosted tools types**: Web search (`WebSearch`), Web fetch (`WebFetch`), Shell (`Bash`, `PowerShell`), Remote MCP (`mcp__<server>__<tool>`, matched by **Server name**, the part between `mcp__` and the next `__`, such as `github`).
>
> **Policy input**: `name` is the tool's name, such as `Bash` or `mcp__github__create_issue`; `input.messages` holds the session's prompts and Claude's replies.
>
> **Sessions**: each Claude Code session is one session, named after its first prompt. A turn shows the prompt, Claude's final reply, the working directory and Claude Code's permission mode. A step run by a Claude Code sub-agent records the sub-agent's type.
>
> **If Xenovia can't be reached**: with the Enterprise default or an Individual account, Claude Code lets the action through. With **Block actions when Xenovia can't be reached**, it blocks the action (Claude Code 2.1.295 or later).
>
> > [!WARNING]
> >
> > Blocking when Xenovia can't be reached means an outage stops your developers' Claude Code. Turn it on only where that is acceptable.

> [tab] Codex
>
> The hooks call a tool on Xenovia's MCP server. With the Enterprise settings, nothing is installed on developers' computers, and Codex cloud runs the same hooks.
>
> ### Before you start
>
> * You need to be an admin of your Xenovia organization.
> * For everyone in a ChatGPT workspace: a ChatGPT Business or Enterprise plan. Pasting the settings needs an admin of that workspace.
> * For one person: a ChatGPT Plus or Pro plan, and Node.js on each computer.
>
> **1. Open Codex in Xenovia**
>
> In first-run setup, choose **Protect your agent**, then **Codex**. Or, on **Agents**, click **Create agent** and pick **Codex** under **Coding agents**. Or, in **Settings**, open **Integrations**, then **Codex**.
>
> **2. Set up**
>
> Fill in **Name**, **What developers use it for** (optional, saved as the agent's purpose) and **When Neon finds a problem** (**Monitor**, the default, or **Enforce**). Click **Connect**. Xenovia creates the agent, activates it, and makes a hooks key for it.
>
> **3. Add it to ChatGPT**
>
> Under **Your ChatGPT account**, pick where the settings go.
>
> **Enterprise account** (Business or Enterprise plan). Click **Copy settings and open ChatGPT**, which opens the ChatGPT admin console. In **Agent security**, choose **Edit as TOML**. Paste the Requirements part into **Requirements** and the Defaults part into **Defaults**, then save.
>
> **Individual account** (Plus or Pro plan). Click **Copy command**, run it on each computer that uses Codex (it needs Node.js), then restart Codex. The command adds Xenovia's part to `~/.codex/config.toml`, between `# >>> Xenovia` and `# <<< Xenovia`, and turns on `hooks = true` under `[features]`. It keeps your other settings and saves the old file as `~/.codex/config.toml.bak`. Running it again replaces Xenovia's part rather than adding it twice.
>
> Click **See what we paste** to read the settings first. The key is in the settings and isn't shown again.
>
> **4. Verify**
>
> Click **Check it's working**. Start Codex and send a prompt. When the first event arrives, the page says **Codex is connected**. Click **Open agent** to see it.
>
> TODO: screenshot of the Codex connect dialog, Your ChatGPT account step
>
> > [accordion] The settings Xenovia generates
> >
> > Xenovia fills in the runtime address, and the key in place of `xe_REPLACE_WITH_HOOKS_KEY`.
> >
> > ```toml requirements.toml theme={null}
> > # Xenovia: check what Codex does. Generated for the Codex integration.
> > # In the ChatGPT admin console, open Agent security and Edit as TOML.
> >
> > # --- Requirements ---
> > [features]
> > hooks = true
> >
> > [[hooks.UserPromptSubmit]]
> > [[hooks.UserPromptSubmit.hooks]]
> > type = "mcp_tool"
> > server = "xenovia"
> > tool = "check_event"
> > input = { hook_event_name = "UserPromptSubmit", session_id = "${session_id}", cwd = "${cwd}", prompt = "${prompt}" }
> > timeout = 10
> >
> > [[hooks.PreToolUse]]
> > matcher = ".*"
> > [[hooks.PreToolUse.hooks]]
> > type = "mcp_tool"
> > server = "xenovia"
> > tool = "check_event"
> > input = { hook_event_name = "PreToolUse", session_id = "${session_id}", cwd = "${cwd}", tool_name = "${tool_name}", tool_use_id = "${tool_use_id}", tool_input = "${tool_input}" }
> > timeout = 10
> >
> > [[hooks.PostToolUse]]
> > matcher = ".*"
> > [[hooks.PostToolUse.hooks]]
> > type = "mcp_tool"
> > server = "xenovia"
> > tool = "check_event"
> > input = { hook_event_name = "PostToolUse", session_id = "${session_id}", cwd = "${cwd}", tool_name = "${tool_name}", tool_use_id = "${tool_use_id}", tool_input = "${tool_input}", tool_response = "${tool_response}" }
> > timeout = 10
> >
> > [[hooks.Stop]]
> > [[hooks.Stop.hooks]]
> > type = "mcp_tool"
> > server = "xenovia"
> > tool = "check_event"
> > input = { hook_event_name = "Stop", session_id = "${session_id}", cwd = "${cwd}", last_assistant_message = "${last_assistant_message}" }
> > timeout = 10
> >
> > # --- Defaults ---
> > [mcp_servers.xenovia]
> > url = "https://runtime.xenovia.io/v1/hooks/codex/mcp"
> > http_headers = { Authorization = "Bearer xe_REPLACE_WITH_HOOKS_KEY" }
> > ```
> >
> > * **Requirements** turn on hooks and add one hook per event. Each calls `check_event` on the `xenovia` MCP server with the event's fields.
> > * **Defaults** add the `xenovia` MCP server, with the key, for every member.
> >
> > Codex has no options here.
>
> ### Hook events
>
> `UserPromptSubmit`, `PreToolUse`, `PostToolUse` and `Stop` work as for Claude Code: a prompt starts a turn, `PreToolUse` is judged at `tool_call`, outside output at `tool_result`, and `Stop` records Codex's final reply.
>
> | Call | Answered at once | Built-in rule | Judged at `tool_call` |
> | - | - | - | - |
> | Shell (`Bash`, `shell`) | Every part of the command only reads or runs tests | See [Built-in rules](#built-in-rules) | Everything else |
> | `apply_patch` | Every file it changes is inside the working directory | Codex's own configuration; added lines that look like a credential | A file outside the working directory, or in `.github/workflows/` |
> | `update_plan`, `view_image` | Yes | — | — |
> | MCP tools (`mcp__<server>__<tool>`) and any other tool | — | — | Yes |
>
> A shell command sent as an argument list, such as `["bash", "-lc", "…"]`, is read as the script it runs. For `apply_patch`, every file the patch adds, updates, moves or deletes is judged as an edit of the lines it adds. Outside output judged at `tool_result`: MCP tools, and shell commands that print what they read from the network.
>
> **Built-in rules that would ask.** Codex can't ask the developer from a hook, so a rule that would ask refuses the call, and says the developer can run it themselves. `agent-config` covers Codex's configuration (`.codex/`, `/etc/codex/`), git hooks and git config.
>
> **When Xenovia finds nothing**, it gives no opinion and Codex goes on as it would without the hook.
>
> **Hosted tools types**: Shell (`Bash`, `shell`) and Remote MCP (`mcp__<server>__<tool>`, matched by **Server name**). Codex's other tools, such as `apply_patch`, aren't covered by the list.
>
> **Policy input**: `name` is Codex's name for the tool, such as `Bash`, `apply_patch` or `mcp__browser__fetch`. A shell call's `command` is the script as one string. `input.messages` holds the session's prompts and Codex's replies.
>
> **Sessions**: each Codex session is one session, named after its first prompt. A turn shows the prompt, Codex's final reply and the working directory.
>
> **If Xenovia can't be reached**, Codex goes ahead. An MCP hook's error never blocks, so this holds for an outage and for an error answer, such as a revoked key.

> [tab] Cursor
>
> Each hook is a command that pipes the event to Xenovia with `curl` and prints Xenovia's answer back to Cursor. The hooks check Cursor's agent.
>
> ### Before you start
>
> * You need to be an admin of your Xenovia organization.
> * For everyone on a Cursor team: a Cursor Teams or Enterprise plan. Adding the hooks needs an admin of that team.
> * For one person: a Cursor Pro plan, and Node.js on each computer.
> * The hooks run `curl` on each developer's computer.
>
> **1. Open Cursor in Xenovia**
>
> In first-run setup, choose **Protect your agent**, then **Cursor**. Or, on **Agents**, click **Create agent** and pick **Cursor** under **Coding agents**. Or, in **Settings**, open **Integrations**, then **Cursor**.
>
> **2. Set up**
>
> Fill in **Name**, **What developers use it for** (optional, saved as the agent's purpose) and **When Neon finds a problem** (**Monitor**, the default, or **Enforce**). Click **Connect**. Xenovia creates the agent, activates it, and makes a hooks key for it.
>
> **3. Add it to Cursor**
>
> Under **Your Cursor account**, pick where the settings go.
>
> **Enterprise account** (Teams or Enterprise plan). Click **Copy settings and open Cursor**, which opens the Cursor dashboard. In **Team hooks**, add them and save. Cursor sends them to every developer on your team.
>
> **Individual account** (Pro plan). Click **Copy command**, run it on each computer that uses Cursor (it needs Node.js), then restart Cursor. The command adds Xenovia's hooks to `~/.cursor/hooks.json`, keeps your other hooks, and saves the old file as `~/.cursor/hooks.json.bak`. Running it again replaces Xenovia's hooks rather than adding them twice.
>
> Click **See what we paste** to read the settings first. The key is in the settings and isn't shown again.
>
> **4. Verify**
>
> Click **Check it's working**. Start Cursor and send a prompt to the agent. When the first event arrives, the page says **Cursor is connected**. Click **Open agent** to see it.
>
> TODO: screenshot of the Cursor connect dialog, Your Cursor account step
>
> > [accordion] The settings Xenovia generates
> >
> > Xenovia fills in the runtime address, and the key in place of `xe_REPLACE_WITH_HOOKS_KEY`. `preToolUse`, `postToolUse` and `stop` run the same command.
> >
> > ```json hooks.json theme={null}
> > {
> >   "version": 1,
> >   "hooks": {
> >     "beforeSubmitPrompt": [
> >       {
> >         "command": "curl -fsS --max-time 10 -H \"Authorization: Bearer xe_REPLACE_WITH_HOOKS_KEY\" -H \"X-Xenovia-User: ${CURSOR_USER_EMAIL}\" --data-binary @- https://runtime.xenovia.io/v1/hooks/cursor",
> >         "timeout": 10
> >       }
> >     ],
> >     "preToolUse": [{ "command": "…same command…", "timeout": 10 }],
> >     "postToolUse": [{ "command": "…same command…", "timeout": 10 }],
> >     "stop": [{ "command": "…same command…", "timeout": 10 }]
> >   }
> > }
> > ```
> >
> > * Every event goes to the same address. Xenovia reads the event's `hook_event_name`.
> > * `X-Xenovia-User` names the developer by their Cursor email.
> > * `-f` makes an error answer, such as a revoked key, a failed hook with no output.
> >
> > Cursor has no options here.
>
> ### Hook events
>
> | Hook event | What Xenovia does | Stage |
> | - | - | - |
> | `beforeSubmitPrompt` | Starts a new turn. Stops a prompt that contains a credential | — |
> | `preToolUse` | Answers read-only calls at once, applies the built-in rules, and judges the rest | `tool_call` |
> | `postToolUse` | Records the tool's input and output. Judges output that came from outside | `tool_result` |
> | `stop` | Closes the turn | — |
>
> | Call | Answered at once | Built-in rule | Judged at `tool_call` |
> | - | - | - | - |
> | `Shell` | Every part of the command only reads or runs tests | See [Built-in rules](#built-in-rules) | Everything else |
> | `Write`, `Edit`, `Delete` | Files inside the workspace | Cursor's hooks or MCP settings, git hooks or git config; content that looks like a credential | Files outside the workspace, and `.github/workflows/` |
> | `Read` | Yes | A credentials file | — |
> | `Grep`, `Glob`, `LS` | Yes | — | — |
> | MCP tools (`MCP:<tool>`) and any other tool | — | — | Yes |
>
> The working directory is the event's `cwd`, the first workspace root, or the command's `working_directory`.
>
> **Built-in rules that would ask.** Cursor doesn't enforce "ask" from this hook, so a rule that would ask refuses the call, and says the developer can run it themselves. `agent-config` covers `.cursor/hooks.json`, `.cursor/mcp.json`, Cursor's enterprise `hooks.json`, git hooks and git config.
>
> **When Xenovia finds nothing**, it answers `{"continue": true}` to a prompt and `{"permission": "allow"}` to a tool call. Cursor needs a permission in every `preToolUse` answer, so `allow` only means Xenovia doesn't object. When Xenovia blocks, the developer and the agent both see the reason.
>
> **Hosted tools types**: Shell (`Shell`) and Remote MCP (`MCP:<tool>`). Cursor's MCP calls don't name their server, so they match a server with the **Server name** `cursor`: add a server named `cursor` to allow them, and list tool names on it to allow only those.
>
> **Policy input**: `name` is Cursor's name for the tool, such as `Shell`, `Write` or `MCP:send_email`. For `Shell`, `arguments` has `command` and `working_directory`; for `Read`, `Write`, `Edit` and `Delete` it has `file_path`, plus `content` for a write. `input.messages` holds the session's prompts.
>
> **Sessions**: each Cursor conversation is one session, named after its first prompt. A turn shows the prompt and the working directory, and each step uses Cursor's own tool name. The developer's Cursor email is the session's user, from `X-Xenovia-User` or the event's `user_email` when the header is empty.
>
> **If Xenovia can't be reached**, Cursor goes ahead: when the `curl` call fails, times out, or gets an error answer, the hook fails and Cursor lets the action through.

Setup creates a **hooks key** for the agent. It works only on Xenovia's hook endpoints, and Xenovia refuses it for model requests, so it can go in settings developers can read. The **API keys** tab marks it **Hooks only**.

## What Xenovia checks

Policies and Neon don't judge the prompt itself. The prompt is what later checks in the turn read as the developer's request, together with the session's earlier prompts and replies. So a prompt like "yes, go ahead" is read with the turn it answers.

Xenovia parses each shell command and judges every part of it, including pipelines, `$(…)`, and `bash -c '…'`. After a tool runs, Xenovia judges its output at `tool_result` when it came from outside, such as MCP tools and commands that print what they read from the network (`curl`, `wget`, `gh issue view`, `gh pr view`, `gh api`, …).

### Built-in rules

Built-in rules run before policies and Neon, in both Monitor and Enforce. A rule's reason is shown in full.

| Rule | What it catches | Claude Code | Codex and Cursor |
| - | - | - | - |
| `remote-script` | A download piped into a shell, such as `curl … \| sh` | **Denied** | **Refused** |
| `rm-root` | A recursive delete of `/` or the home directory | **Denied** | **Refused** |
| `rm-outside` | A recursive delete outside the working directory | Asks the developer | Refused; the developer can run it |
| `force-push` | A force push | Asks the developer | Refused; the developer can run it |
| `sudo` | A command run with `sudo` | Asks the developer | Refused; the developer can run it |
| `secret-file` | Reading a credentials file (`~/.ssh`, `~/.aws`, `.env`, `*.pem`, …) | Asks the developer | Refused; the developer can run it |
| `sandbox-off` | A command that asks to run outside Claude Code's sandbox | Asks the developer | — |
| `agent-config` | An edit to the coding agent's own settings, git hooks or git config | Asks the developer | Refused; the developer can run it |
| `secret-in-file` | Writing what looks like a credential into a file | Asks the developer | Refused; the developer can run it |
| `secret-in-prompt` | A prompt that contains what looks like a credential | **Prompt not sent** | **Prompt not sent** |

The credential formats are private key blocks, AWS access keys, GitHub tokens, Slack tokens, Anthropic, OpenAI and Google API keys, and Xenovia `xe_` keys.

### Policies

A tool call judged at `tool_call` runs the agent's [policies](https://docs.xenovia.io/control/policies.md) at the response stage. In the policy input, `input.enforcement_stage` is `"tool_call"`, and `input.output.tool_calls` holds the call: `name` is the tool's name and `arguments` is the tool's input as a JSON string.

```rego theme={null}
package xenovia

import future.keywords.if
import future.keywords.in

default decision = {"action": "allow"}

decision = {"action": "block_response", "rule": "no-terraform-apply"} if {
    input.enforcement_stage == "tool_call"
    some call in input.output.tool_calls
    call.name in {"Bash", "shell", "Shell"}
    contains(json.unmarshal(call.arguments).command, "terraform apply")
}
```

Attach the policy to the coding agent's Xenovia agent. Policies don't run on tool output: `tool_result` is judged by Neon only.

### Neon

[Neon](https://docs.xenovia.io/control/neon.md) judges tool calls at `tool_call` and outside output at `tool_result`. It reads each call with the developer's prompt and the session's earlier turns.

### Hosted tools

The agent's **Hosted tools** tab limits which kinds of tool the coding agent may use. It applies before the built-in rules. Each tab above lists the tool types that apply. Other tools, such as reading and editing files, aren't covered by the list. In **Monitor**, a call outside the list is recorded and goes on to the other checks. In **Enforce**, it is refused.

## When Xenovia blocks

Each hook call gets HTTP `200` with the decision in the body, in the shape the coding agent reads. This differs from the model routes, where a block is a `200` refusal.

| Situation | What the coding agent does |
| - | - |
| A policy or Neon blocks a tool call | Refuses the call. The agent gets the reason and can take another approach |
| A built-in rule denies | Refuses the call, with the rule's reason |
| A built-in rule asks | Claude Code shows its permission prompt; Codex and Cursor refuse and say the developer can run it |
| **Hosted tools** doesn't allow the tool | Refuses the call |
| An enforced check can't run | Refuses the call |
| A prompt contains a credential | Doesn't send the prompt, and says why |
| Neon flags a tool's output | Keeps the output, and tells the agent not to follow instructions in it |

The reasons name the tool, never the policy or check that fired. That stays in Sessions. For example: "Xenovia: this Bash call was blocked by your organization's policy. Do not retry it; take another approach or tell the developer."

A policy that escalates refuses the call, like a block. When Neon escalates, the call runs, Sessions marks it **Escalated**, and the escalation is queued for review. A policy redaction can't rewrite a tool call: the call runs as sent, and Sessions records the redaction.

### Monitor and Enforce

* **Monitor**: Neon records what it finds and the action runs. When nothing on the agent can stop a call, Xenovia answers at once and judges the call afterwards, so the coding agent doesn't wait.
* **Enforce**: Neon stops the action. Xenovia judges the call before it answers, within 8 seconds.

The built-in rules, the credential check on prompts, enforced policies, and **Hosted tools** in Enforce apply either way. Change the mode later on the agent's **Neon** tab.

### If Xenovia can't be reached

Each tab above says what its coding agent does when Xenovia can't be reached. When Xenovia is reachable but an enforced check can't run, Xenovia refuses the call (fail closed). A check that doesn't finish within 8 seconds counts as one that couldn't run. For tool output, the agent is told to treat it as untrusted.

## Sessions

Each coding-agent session or conversation is one session in **Sessions**, for its agent, named after its first prompt. Each prompt starts a turn, and each tool run is a step with its input and output. Each decision shows on its step: **Allowed**, **Blocked**, **Asked developer** (Claude Code), **Escalated**, **Would block** (monitored), or **Unchecked**. A turn in which anything was refused is marked blocked. A call answered at once is recorded when the tool has run.

## Roll out to your organization

Each agent has its own key. If you have more than one Claude organization, ChatGPT workspace or Cursor team, add an agent for each: on **Agents**, click **Create agent** and pick the coding agent again. Xenovia shows how many of those agents you already have. Click **Create and continue** to make a new agent and key, then add its settings there.

To replace a key, open the agent's **API keys** tab and click **Create API key**, then **Create another Claude Code key** (or Codex, or Cursor). The new key comes with its settings and its command. Revoke the old key once the new settings are in place.

## Troubleshooting

> [accordion] Send one test event
>
> ```bash Claude Code theme={null}
> curl -sS https://runtime.xenovia.io/v1/hooks/claude-code \
>   -H "Authorization: Bearer xe_..." \
>   --data-binary '{"session_id":"xenovia-test","hook_event_name":"UserPromptSubmit","prompt":"hello","cwd":"/tmp"}'
> ```
>
> ```bash Codex theme={null}
> curl -sS https://runtime.xenovia.io/v1/hooks/codex/mcp \
>   -H "Authorization: Bearer xe_..." \
>   --data-binary '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_event","arguments":{"hook_event_name":"UserPromptSubmit","session_id":"xenovia-test","cwd":"/tmp","prompt":"hello"}}}'
> ```
>
> ```bash Cursor theme={null}
> curl -sS https://runtime.xenovia.io/v1/hooks/cursor \
>   -H "Authorization: Bearer xe_..." \
>   --data-binary '{"conversation_id":"xenovia-test","hook_event_name":"beforeSubmitPrompt","workspace_roots":["/tmp"],"prompt":"hello"}'
> ```
>
> It works when Claude Code's answer is `{}`, Cursor's is `{"continue":true}`, and Codex's result has `"isError": false` and the text `{}`. The test shows up in Sessions as a session named "hello". An error comes back as `{"error": "..."}` (for Codex, a result with `"isError": true`; with no key at all, HTTP `401`). With `-f`, Cursor's hook doesn't print these bodies, so run the test to see them.

> [accordion] Error messages
>
> | Error | Cause | Fix |
> | - | - | - |
> | `missing Authorization: Bearer xe_* token` | The hook sends no key | Check the `Authorization` header in the settings (for Codex, `http_headers` under `[mcp_servers.xenovia]`) |
> | `unknown api key` | The key was revoked, mistyped, or is still `xe_REPLACE_WITH_HOOKS_KEY` | Make a new key on the agent's **API keys** tab |
> | `agent is not active: activate it in the Xenovia dashboard before sending requests` | The agent was deactivated | Activate the agent |
> | `invalid api key for this agent` | The key's agent no longer exists | Set up the coding agent again |
> | `request body must be a Claude Code hook event` (or `a Cursor hook event`) | The body isn't a hook event's JSON | Use the settings Xenovia generated |
> | `session_id is required`, `tool_name is required` | The event is missing a field | Use the settings Xenovia generated |
> | `hook event exceeds 4 MiB` | A tool's output was larger than 4 MiB | Xenovia can't check an event this large |
> | `auth unavailable`, `agent config unavailable`, `session store unavailable` | Xenovia is briefly unavailable (`503`, with `Retry-After`) | Retry. Meanwhile actions follow what the coding agent does when Xenovia can't be reached |

> [accordion] Messages in the console
>
> * **Waiting for the first Claude Code event** (or Codex, or Cursor) doesn't clear: restart the coding agent, and make sure the developer is signed in to the organization, workspace or team that has the settings.
> * **Neon couldn't be set to enforce, so this agent monitors for now.**: change the mode on the agent's **Neon** tab.
> * **Couldn't make the command from these settings.**: use **Enterprise account**, or try again.

## What next?

> [card] [Write a policy](https://docs.xenovia.io/control/policies.md)
>
> Block a command your developers' agents should never run.

> [card] [Tune Neon](https://docs.xenovia.io/control/neon.md)
>
> Move risks from Monitor to Enforce.

> [card] [Find more agents](https://docs.xenovia.io/discovery/overview.md)
>
> See which coding agents your developers use.


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