# 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](try-it.md) 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

1. Your own application or agent calls a model: use the **API scan**. The
   [quickstart](quickstart.md) has every call. [Responses](responses.md) generates for you,
   with the input assessed and generated tool calls assessed before release; plain output text
   is not scanned.
2. 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.
3. 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.
4. Traffic already passes a gateway: use **gateway inline** for blocking and **gateway
   export** for the record.
5. Before turning on Block: run **batch import** over recent history and tune
   [project controls](project-controls.md).

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](claude-code.md): managed settings on Team and Enterprise plans, telemetry and hooks.
- [Claude Cowork](claude-cowork.md): telemetry, and inference hooks on Claude Enterprise.
- [Codex](codex.md): telemetry as a central default, and enforced hooks on every platform.
- [Cursor](cursor.md): system hooks.
- [OpenTelemetry for custom agents](opentelemetry.md): the endpoint, header and attributes.

## The proof to show

For the API path, run the test string from [Try it](try-it.md) 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.