Choose a capture path
This page is for an agent helping a person decide how Zaun sees their AI traffic. It says what each capture path can and cannot do, who sets it up, how long it adds to a request, and what happens when Zaun cannot be reached. If you are the person, pick a path per agent or gateway; you can combine them.
The short version#
- Observe with telemetry. Agents export what they do. Zaun records and alerts, but cannot block, because events arrive after the fact.
- Block with hooks, inference hooks, a gateway or the API. Each of these asks Zaun before the prompt is sent or the tool runs, so it can stop it.
- Review history with batch import. Upload past conversations to see what Hex v1.3 would have flagged and to tune controls before going live.
Every path is billed as scans: telemetry, hook and batch scans spend the same credit as API scans.
What each path can and cannot do#
| Path | Can | Cannot | Set up by |
|---|---|---|---|
| Telemetry export (OpenTelemetry from Claude Code, Claude Cowork, Codex, gateways and custom agents) | Record every prompt, tool call and reply the agent exports; show sessions on Violations; alert | Block anything: events arrive after the prompt was sent and the tool ran | An admin, through managed settings, device management or gateway configuration |
| Client hooks (Claude Code, Codex, Cursor) | Stop a prompt before it is sent or a tool before it runs; record the prompts and tool calls they check | Redact (a Redact control alerts in a hook); cover agents that have no hooks; block when the hook times out, unless configured to fail closed | An admin, through managed settings, Codex requirements.toml or Cursor hooks.json |
| Claude Enterprise inference hooks | Allow or deny prompts and tool calls across claude.ai, Claude Cowork, Claude Code and Claude Tag from one Owner setting | Redact; see the final assistant reply; run on Team plans | A Claude Enterprise Owner |
| Gateway inline (LiteLLM, Kong, Azure API Management, AWS AgentCore Gateway) | Block at the gateway for every client behind it | Redact (a Redact control blocks at the gateway); block streamed replies in most gateways | A platform team |
| Gateway export (the same gateways' logs) | Record every request and reply that passes the gateway | Block anything | A platform team |
API scan (POST /v1/scan/prompt, POST /v1/responses) | Everything: block, redact and alert, in your own code | Nothing in scope | Developers, in application code |
| Batch import | Review history on Violations; tune controls before going live | Act on anything in time | A security engineer |
The same verdict rules apply wherever a scan comes from. Only a threat blocks, and only where the matching control is set to Block; other findings alert even then. A threat Hex v1.3 finds in the person's own messages can block. A threat it finds only in model replies, tool calls or tool results normally raises an alert instead. The test string always blocks, wherever it appears, including tool-call arguments; other input checks follow the project's setting for them.
Latency and failure#
| Path | Added to each request | When Zaun cannot be reached |
|---|---|---|
| Telemetry export | Nothing; export runs beside the agent | The agent keeps working; those events may not arrive |
| Client hooks | The scan, before the prompt is sent or the tool runs; Zaun answers within 8 seconds, inside the generated 10-second hook timeout | Fails open by default: the prompt or tool goes ahead. Claude Code can fail closed with onFailure: "block", except that a timed-out tool check still does not block. Cursor fails closed per hook with failClosed. Codex hooks fail open. |
| Claude Enterprise inference hooks | The scan, within Anthropic's 5-second default timeout | The Owner chooses fail open (the default) or fail closed. Shadow mode observes without blocking. |
| Gateway inline | The scan, inside the gateway request | Set per gateway. LiteLLM fails closed by default; Zaun's LiteLLM configuration sets unreachable_fallback: fail_open. The Azure API Management policy fragment fails open (ignore-error="true"). Kong follows the plugin's stop_on_error setting. |
| API scan | The scan; your call waits for the verdict | Your code decides what an HTTP error, such as 503 capacity, does. When Hex v1.3 could not complete the assessment, POST /v1/scan/prompt still returns a result, and that result alerts and never blocks. POST /v1/responses fails closed instead, with 503 assessment_unavailable. A document scan that could not be read returns status: failed. |
| Batch import | Nothing; history is processed after upload | The upload can be retried |
Failing closed covers Zaun being unreachable, not a slow scan. To stay inside the agent's own timeout, a client hook whose scan runs past 8 seconds is answered with allow and a message saying Zaun did not answer in time. Gateways follow their own timeout settings.
How to choose#
- Your own application or agent calls a model: use the API scan. The quickstart has every call. Responses generates for you, with the input assessed and generated tool calls assessed before release; plain output text is not scanned.
- People use Claude Code, Codex or Cursor: start with telemetry to see what happens, then add hooks where you want risky actions stopped in the client.
- Your organization is on Claude Enterprise: inference hooks block across Claude products without configuring laptops. On a Team plan, Claude Code hooks delivered through claude.ai managed settings are the blocking path.
- Traffic already passes a gateway: use gateway inline for blocking and gateway export for the record.
- Before turning on Block: run batch import over recent history and tune project controls.
The recommendation is ours; the action is yours. Every scan response carries a fixed-vocabulary
containment field, one of none, stop_turn, end_session, quarantine_session,
disable_tool or review, so your automation can map it to your own controls.
Pages per agent#
- Claude Code: managed settings on Team and Enterprise plans, telemetry and hooks.
- Claude Cowork: telemetry, and inference hooks on Claude Enterprise.
- Codex: telemetry as a central default, and enforced hooks on every platform.
- Cursor: system hooks.
- OpenTelemetry for custom agents: the endpoint, header and attributes.
The proof to show#
For the API path, run the test string from Try it and show the blocked result. Each other path's page ends with its own proof, such as the test string denied in Claude Code by a hook.
Maintained with the API contract · Defaults may vary by deployment.