> For the complete documentation index, see [llms.txt](https://help.nightfall.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.nightfall.ai/data-exfiltration-prevention/ai-agent-security/ai-governance/auditability-and-control/hooks-vs.-open-telemetry.md). # Hooks vs. Open Telemetry ## Hooks vs. OTel Telemetry Nightfall uses two complementary mechanisms to monitor AI agent activity. This page explains the differences, when to use each, and the recommended deployment strategy. *** ### Capability Comparison | Capability | Hooks (Real-Time) | OTel Telemetry (Async) | | ---------------------------- | -------------------------- | ------------------------------------------------------------------------------------ | | Timing | Before the action executes | After the action completes | | Can block actions | Yes | No - monitor only | | Prompt text scanning | Yes | Yes (requires OTEL\_LOG\_USER\_PROMPTS=1) | | Tool I/O scanning | Yes | Yes (requires OTEL\_LOG\_TOOL\_DETAILS=1) | | Cost and token tracking | No | Yes (costUSD, inputTokens, outputTokens) | | Model name | No | Yes (e.g., claude-sonnet-4-6) | | Complete session audit trail | Partial (hook points only) | As supported via OTEL | | API error tracking | No | Yes (failed requests, retries) | | Detect hook bypass | No | Yes, Hooks status is available via device list page (detects if hooks were disabled) | *** ### Agent Support Matrix Not every agent supports both mechanisms. Use this matrix to understand what is available for each agent: | Agent | Hooks | OTel | Enforcement Options | | ------------- | --------------------- | ---- | ------------------- | | Claude Code | Yes | No | Block or Monitor | | Cursor | Yes (via Claude Code) | No | Block or Monitor | | VS Code | Yes (via Claude Code) | No | Block or Monitor | | Claude Cowork | No | Yes | Monitor only | *** ### When to Use Each #### Use hooks when you need to: * Block sensitive data from being sent to AI models or external tools * Prevent shell commands that could leak credentials * Enforce MCP server allowlists in real time * Stop tool calls to unauthorized services before they execute #### Use OTel when you need to: * Track costs - token usage and dollar cost per prompt * Audit complete session activity including tool decisions and API calls * Monitor Claude Cowork - the only mechanism available * Detect hook bypass - identify when developers disable or circumvent hooks Compliance logging - capture every prompt for regulatory requirements ### What Hooks Intercept The Nightfall agent registers handlers for four hook points. Each hook fires at a specific moment in the AI agent's workflow: | Hook Point | When It Fires | What It Scans | Can Block? | | --------------- | ----------------------------------------- | ------------------------------ | -------------------------------------- | | User Prompts | Before the prompt is sent to the AI model | Full prompt text | Yes | | Tool Calls | Before a tool executes | Tool name and input parameters | Yes | | Tool Responses | After a tool finishes executing | Tool name and output content | Yes (Not supported in VS Code Copilot) | | Model Responses | After a model finishes evaluating task | Model response | No | | Shell Commands | Before a shell command executes | Full shell command string | Yes | #### Why Tool Responses are monitor-only Tool Responses capture content after the tool has already executed - the action has completed and cannot be reversed. Nightfall still scans the output for policy violations and creates incidents, but blocking is not possible at this point. *** ### How Enforcement Works When a hook fires, the following happens: 1. The AI agent (Claude Code, Cursor, or VS Code) pauses the action and sends the content to the Nightfall agent running on the endpoint. 2. The Nightfall agent evaluates the content against your active AI agent policies and enforces remediation actions such as block user prompts, tool calls or shell commands. 3. The agent returns a verdict: * Allow - the action proceeds normally. * Block - the action is denied. The end-user sees a message explaining why. 4. If a violation is detected, the incident is recorded in your Nightfall console regardless of whether the action was blocked or monitored. #### Fail-open design If the Nightfall agent is temporarily unavailable or takes longer than 15 seconds to respond, the hook fails open - the AI agent action proceeds normally. This ensures that developer workflows are never blocked by infrastructure issues. When the agent recovers, hooks resume normal enforcement automatically. *** ### Claude Cowork Monitoring Claude Cowork is monitored through OpenTelemetry (OTel) rather than hooks. You need to configure OpenTelemetry for Claude Cowork. You can follow the steps available here to setup OTel --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.nightfall.ai/data-exfiltration-prevention/ai-agent-security/ai-governance/auditability-and-control/hooks-vs.-open-telemetry.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.