Guard Hooks
Guard Hooks connect AI coding agents to your runtime guards using each agent's native lifecycle hooks. Every user prompt and file tool call is evaluated against your guards before the agent acts on it, and — on Claude Code — tool output can be masked for PII and secrets before the model reads it.
The hooks are packaged as a first-class, editable plugin (Willow Guard Hooks) so you configure them once and roll them out to your whole fleet. The org token they need is delivered through the same MDM profile as the Willow Scan Agent.
Supported agents
| Agent | Coverage | Status |
|---|---|---|
| Claude Code | Prompts, file tool calls, and PII/secret masking on tool output | Available |
| Cursor | User prompts and file tool calls | Available |
| Codex | Session evaluation | Coming soon |
| Antigravity | Agent workflow coverage | Coming soon |
Prerequisites
- The Guard Hooks beta feature must be enabled in Beta Features. Once enabled, the Guard Hooks option appears under Setup on the Security → Guards page.
- At least one runtime guard should be active so the hooks have something to enforce.
How it works
The Willow Guard Hooks plugin is the single source of truth. It defines which guards run (prompts, file tools, tool-output masking) and the tool matchers they use. Everything downstream — the managed configuration, the MDM token profile, and the marketplace bundle — is generated from it.
The rollout has four parts: activate the plugin, choose which hooks run, deliver the token via MDM, and enforce org-wide.
Step 1 — Activate the guard hooks plugin
On the Security → Guards page, open the Setup menu and choose Guard Hooks.
- If the plugin has not been created yet, a dialog explains that guard hooks aren't active. Click Activate hooks to create the Willow Guard Hooks plugin for your organization and open its plugin page.
- If the plugin already exists, you go straight to its plugin page.
Activating is idempotent — re-running it re-syncs the plugin's adapter URLs and regenerates the underlying hooks. The plugin is created as a draft, so it is never published to your marketplace until you choose to.
Step 2 — Choose which hooks run
On the plugin page you control exactly which guards ship and how they match:
- Toggle each hook Included / Excluded.
- Tune the tool matcher for tool-use hooks (a pipe-separated list of tool names the hook runs on, e.g.
Read|Write|Edit). Prompt hooks run on every prompt and have no matcher. - Edit the plugin name and description, then Save.
- Download a ready-to-install bundle for Claude Code or Cursor (the org token is baked into the bundle).
Your changes flow automatically into the managed configuration (Step 4) and the plugin bundle.
Step 3 — Deliver the org token via MDM
The hooks authenticate to Willow with your organization token. Rather than putting it on each machine by hand, deliver it fleet-wide with the same MDM profile as the Willow Scan Agent (Shadow AI).
If a machine already has the Willow Scan Agent profile, the token is already present and the guard hook reads it directly — you can skip this step for those machines.
macOS — configuration profile (.mobileconfig)
Download the profile from the Scan Agent setup flow (pre-filled for your organization) and push it through your MDM (Jamf, Kandji, Mosyle, or Intune). It writes the token to the com.mcp-s-scan.agent managed-preferences payload. See Deploy the Scan Agent with MDM.
Windows — registry policy (.reg)
Import the registry policy via GPO or deploy it with Intune. It writes the token to HKLM\SOFTWARE\Policies\MCP-S-Scan, which the PowerShell hook reads.
These files contain your organization auth token. Treat them as secrets and distribute them only through your MDM.
Token resolution order
At runtime the hook resolves the token from the first source that has it — any one is enough. Each source corresponds to a rollout channel, so you only ever need the one that matches how you deploy:
- Willow Scan Agent profile (
com.mcp-s-scan.agent) — the token is delivered by the Scan Agent's MDM profile: the macOS.mobileconfig(com.mcp-s-scan.agentmanaged-preferences payload) or the Windows.reg(HKLM\SOFTWARE\Policies\MCP-S-Scan). This is the same profile used for the Willow Scan Agent (Shadow AI), so any machine that already runs it needs nothing extra (Step 3). - Plugin bundle token file — baked into the downloaded plugin, used when you roll out via the marketplace or install the plugin locally (Step 4, Plugin marketplace).
WILLOW_GUARD_TOKENenvironment variable — fallback for dev shells and env-based deploys (e.g. Linux).
Device identity is detected automatically at runtime (the same identity source as the Scan Agent). Optionally set WILLOW_USER_EMAIL to attribute audit decisions to a user; Cursor also forwards the authenticated user's email in the hook payload when available.
Step 4 — Enforce org-wide
With the plugin configured and the token in place, turn the hooks on for everyone. Pick the channel your organization already uses.
Managed configuration
- Claude Code: push the plugin's hooks through Claude Code's
managed-settings.jsonusing the policy builder, which validates the full schema and exports an MDM-ready profile. The token comes from Step 3. - Cursor: deploy the hooks to Cursor's enterprise
hooks.jsonsystem path via MDM so they apply to every user on the machine.
Plugin marketplace
Publish the Willow Guard Hooks plugin to your marketplace and mark it enforced — agents auto-install it on launch, with the token already delivered from Step 3.
Both agents fail open — on a hook timeout or if Willow is unreachable, the agent proceeds. Blocks apply only when Willow responds with a guard block.
Hooks reference
Claude Code — merge the copied fragment into your Claude Code settings (user, project, or managed), keeping any existing hook groups:
| Event | Tools | Purpose |
|---|---|---|
UserPromptSubmit | — | Evaluate every prompt |
PreToolUse | Read, Write, Edit, MultiEdit, NotebookEdit | Evaluate file tool calls |
PostToolUse | Bash, Read | Mask PII/secrets in tool output |
Cursor — save the hooks.json as project .cursor/hooks.json, user ~/.cursor/hooks.json, or the enterprise system path, keeping any existing hooks:
| Event | Tools | Purpose |
|---|---|---|
beforeSubmitPrompt | — | Evaluate every prompt |
preToolUse | Read, Write | Evaluate file tool calls |
Both agents authenticate with Authorization: Bearer $WILLOW_GUARD_TOKEN. Hooks load at startup, so restart or reload the agent after changing settings.