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.

1. 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 https://claude.com/docs/cowork/monitoring#events