Nightfall Hooks for Claude Code

Step-by-step instructions for deploying Nightfall's Claude Code hooks to corporate-managed employee devices via your MDM.

---

1. What gets deployed

Nightfall ships a managed-settings drop-in (payloads/nightfall-hooks.json) that registers the nightfall-hook-relay binary against four Claude Code events:

Event	When it fires	Purpose
PreToolUse	Before Claude Code runs a tool (file write, bash, etc.)	Inspect/intercept the action before it happens
PostToolUse	After a tool runs	Capture the result
UserPromptSubmit	When the developer submits a prompt	Inspect prompt content
Stop	When the agent finishes responding	Capture the completed turn

Every event runs the same command — nightfall-hook-relay --source claude_code - with a 15-second timeout. The payload also sets "allowManagedHooksOnly": true, which prevents users from registering their own hooks alongside the managed ones.

{
  "hooks": {
    "PreToolUse":       [ { "hooks": [ { "type": "command", "command": "nightfall-hook-relay --source claude_code", "timeout": 15 } ] } ],
    "PostToolUse":      [ { "hooks": [ { "type": "command", "command": "nightfall-hook-relay --source claude_code", "timeout": 15 } ] } ],
    "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "nightfall-hook-relay --source claude_code", "timeout": 15 } ] } ],
    "Stop":             [ { "hooks": [ { "type": "command", "command": "nightfall-hook-relay --source claude_code", "timeout": 15 } ] } ]
  },
  "allowManagedHooksOnly": true
}

---

2. How the deployment works

Each device needs two things to happen, in order:

1. Payload staged - the JSON file lands at a fixed staging path, delivered by your MDM's file-distribution / app-deployment feature.

2. Install script runs - copies the staged payload into Claude Code's managed-settings.d/ drop-in directory and locks the file permissions.

The install scripts are idempotent: re-running just re-copies the file, so it's safe to wire them to a recurring trigger.

Staging and target paths

Platform	Staging path (step 1)	Target path (step 2)
macOS	/opt/nightfall/hooks/claude-code/nightfall-hooks.json	/Library/Application Support/ClaudeCode/managed-settings.d/nightfall-hooks.json
Windows	`C:\Nightfall\Hooks\claude-code ightfall-hooks.json`	`C:\Program Files\ClaudeCode\managed-settings.d ightfall-hooks.json`

The drop-in directory managed-settings.d/ accepts multiple vendor files, so Nightfall's nightfall-hooks.json coexists with anything else already there. The install just adds one file.

---

3. macOS setup

Step 1 - Stage the payload

Deliver payloads/nightfall-hooks.json to /opt/nightfall/hooks/claude-code/nightfall-hooks.json using your MDM's file-distribution or app-deployment feature (e.g. wrap the JSON in a .pkg, or use Workspace ONE's Files feature).

Step 2 - Run the install script

Wire scripts/macos/install.sh into your MDM as a System-context script. It:

1. Verifies it's running as root (exits early if not — deploy at System scope).

2. Confirms the staged payload exists.

3. Creates …/ClaudeCode/managed-settings.d/ if needed.

4. Copies the payload in, then sets chmod 644 and chown root:wheel.

sudo ./scripts/macos/install.sh

Drift checking (optional, recommended for Kandji-style audit/remediation MDMs)

scripts/macos/audit.sh compares the deployed file against the staged payload byte-for-byte (cmp -s):

• Exit 0 > in sync, no action.

• Exit 1 > drift detected, run install.sh to remediate.

(If the staging file is missing, audit exits 0 to avoid a remediation loop it can't fix.)

---

4. Windows setup

Step 1 - Stage the payload

Deliver payloads/nightfall-hooks.json to C:\Nightfall\Hooks\claude-code\nightfall-hooks.json using your MDM's file-distribution feature (e.g. an .msi or .intunewin).

Step 2 - Run the install script

Wire scripts/windows/install.ps1 into your MDM as a SYSTEM-context script. It:

1. Verifies it's running as administrator (exits early if not).

2. Confirms the staged payload exists.

3. Creates C:\Program Files\ClaudeCode\managed-settings.d if needed.

4. Copies the payload in, then locks the ACL with icacls — full control for

Administrators and SYSTEM, read-only for Users.

powershell -ExecutionPolicy Bypass -File .\scripts\windows\install.ps1

Drift checking (Intune Win32 Remediation pattern)

scripts/windows/detect.ps1 compares the deployed file against the staged payload by SHA256:

• Prints present, exit 0 → in sync.

• Prints staging-missing, exit 0 → staging not deployed yet (no remediation loop).

• Exit 1 → drift, run install.ps1 as the remediation.

---

5. Wiring into your MDM

The scripts are MDM-agnostic - the same install script works regardless of vendor. Wire each into the matching MDM feature:

MDM	Platform	Wire into	Script
Rippling	macOS	Custom Script (on enrollment + daily)	scripts/macos/install.sh
Rippling	Windows	PowerShell Script	scripts/windows/install.ps1
Jamf Pro	macOS	Script + Policy (Recurring Check-in + Enrollment)	scripts/macos/install.sh
Kandji	macOS	Custom Script — Audit	scripts/macos/audit.sh
Kandji	macOS	Custom Script — Remediation	scripts/macos/install.sh
Microsoft Intune	Windows	Win32 Remediation - Detection	scripts/windows/detect.ps1
Microsoft Intune	Windows	Win32 Remediation - Remediation	scripts/windows/install.ps1
Workspace ONE	macOS	Script (System context, Periodic + Enrollment)	scripts/macos/install.sh
Workspace ONE	Windows	Script (SYSTEM context, Periodic + Enrollment)	scripts/windows/install.ps1

Two drift strategies:

• Re-run on a schedule (Rippling / Jamf / Workspace ONE) - the install script is idempotent, so a periodic trigger simply re-copies and re-locks. Simplest.

• Audit/detect → remediate (Kandji / Intune) - pair the audit/detect script with the install script so a re-install only fires when drift is detected.

---

6. Validation

After deployment, open the Devices page in the Nightfall console. Each device shows a per-client hook status indicator. A healthy status for Claude Code means the hooks are registered and the relay is responding - the deployment is working.

On a single device you can also confirm the file landed at the target path and that nightfall-hook-relay resolves on PATH (the endpoint agent provides it).

---

7. Rollback

Delete the deployed file; the relay binary stays installed (the Nightfall agent owns its lifecycle):

• macOS: /Library/Application Support/ClaudeCode/managed-settings.d/nightfall-hooks.json

• Windows: C:\Program Files\ClaudeCode\managed-settings.d\nightfall-hooks.json

If you wired the install to a recurring trigger, remove that MDM assignment first - otherwise the next check-in will re-deploy the file.

---

8. Notes & known issues

• User-consent dialog. Any managed Claude Code setting that contains hooks triggers a one-time security dialog the user must accept. Plan internal comms before rollout so employees aren't surprised.

• Anthropic Windows path migration (March 2026). Claude Code on Windows moved managed-settings to C:\Program Files\ClaudeCode. The shipped scripts target this new path — pin managed devices to a recent Claude Code version so the path matches.

• Multi-vendor coexistence. The managed-settings.d/ drop-in directory accepts multiple vendor files. Nightfall's nightfall-hooks.json coexists with anything else there - the install adds a single file and never overwrites others.

• allowManagedHooksOnly: true. This locks out user-defined hooks. If a team has a legitimate need for their own Claude Code hooks, that's a policy decision to revisit before rollout.