Governing Coding Agents with Hooks
AI coding agents run commands, read and write files and call tools on the developer's machine. Waxell governs them through each tool's own hook system: the Waxell agent registers a hook that the tool calls before it acts, and the hook answers allow, ask or deny from your Guard policy.
Which tools are covered
| Tool | Enforcement | Notes |
|---|---|---|
| Claude Code | Preventive — can block or ask | Full allow / ask / deny. |
| Codex CLI and the ChatGPT desktop app's coding mode | Preventive — can block | Codex has no "ask": a warn-level rule is allowed and logged. |
| Cursor (1.7+) | Preventive — can block or ask | |
| GitHub Copilot CLI | Preventive — can block or ask | |
| Gemini CLI | Preventive — can block | No "ask": warnings are shown to the user and the action continues. |
| Cline (CLI and VS Code extension) | Preventive — can block tool calls | Prompts typed into the Cline CLI are observed, not blocked. |
| Windsurf / Devin | Preventive — can block | No "ask". |
| opencode, Antigravity | Preventive — on/off | |
| Claude Desktop sessions (Cowork and Chat) on the Mac | Preventive | Via a Waxell plugin Claude Desktop loads for the organisation. |
| Claude sessions running in Anthropic's cloud | Preventive, decided by Waxell's servers | A cloud plugin forwards each event to Waxell for a verdict. |
| ChatGPT desktop app chat | Detective — observed, never blocked | See ChatGPT desktop. |
"Preventive" means the action is stopped before it happens. "Detective" means it is recorded after the fact.
How hooks are installed
The Waxell agent writes each tool's managed (administrator-owned) hook
configuration, which the tool loads ahead of the user's own settings. For
example, Claude Code reads
/Library/Application Support/ClaudeCode/managed-settings.d/50-waxell-hooks.json
on macOS and %ProgramFiles%\ClaudeCode\managed-settings.d\ on Windows; Codex
reads /etc/codex/requirements.toml and %ProgramData%\OpenAI\Codex\requirements.toml.
Managed hooks matter for Codex in particular: it ignores user-level hooks until
someone approves them interactively, which never happens in a headless run.
The agent checks the registration continuously. If a tool update or a user edit removes an event Waxell needs, it puts it back. The Hooks column on the Health page reports each device:
| State | Meaning |
|---|---|
| managed | Registered in the tool's managed configuration. |
| guard | Registered at user level. |
| n/9 | Some events missing. |
| no PreToolUse | The blocking event is missing — the device is marked degraded. |
| none | No hooks registered. |
What a hook checks
Before a tool call runs (the PreToolUse event), the hook evaluates the command
or file against your Guard. When the user submits a prompt (UserPromptSubmit),
it runs DLP over the prompt text.
| Area | What it does | Defaults |
|---|---|---|
| Blocked commands | Refuses matching commands outright. | Destructive deletes of / or home, disk formatting, fork bombs, shutdown, download-and-run, wiping shadow copies or event logs, disabling Defender, and more — macOS/Linux and Windows lists. |
| Commands that ask first | Asks the user before running. | rm -rf, kill -9, Docker prune, DROP / TRUNCATE, unbounded DELETE. |
| Protected files | Refuses reads and writes. | .env*, credentials, *.pem, *.key, SSH keys, .aws, gcloud config, .netrc, .npmrc, .pypirc. |
| Files that ask before a write | Asks before changing. | Lock files, .gitignore, .dockerignore. |
| Path boundary | Keeps the agent inside its working directory. | Off. |
| Git | Protects branches and history. | Protected branches main, master, develop, release/*, production; force-push, hard reset and git-config edits blocked. |
| Infrastructure files | Extra confirmation before writing. | Dockerfiles, CI configs, Terraform, Kubernetes and Helm, Makefiles, deploy configs. |
| Agent network | Blocks fetches to listed domains and internal addresses. | Internal and cloud-metadata addresses blocked. |
| Agent DLP | Warns or blocks prompts and tool output containing secrets. | Off. |
| Session limits | Caps how many files one session changes. | Warn at 20, stop at 50. |
You build these lists from a catalog of named rules in the Guard editor — search by what a rule does ("Download-and-run", "Cloud credentials"), filter by platform, and tick the ones you want. You can still add your own patterns. Windows-only rules are only sent to Windows devices.
Ask in unattended runs
A rule that asks needs someone to answer. When an agent runs unattended (Claude
Code's bypassPermissions mode), Ask fallback (non-interactive) decides what
an ask becomes: deny (the default) or allow. Tools that have no "ask" at all
(Codex, Gemini CLI, Windsurf, Cline) let warn-level actions continue with a
message.
When Waxell is unreachable
Hooks decide on the device from the last policy the agent received, before contacting Waxell, so an offline laptop, a captive portal or a Waxell outage does not switch enforcement off. Recording the decision happens afterwards.
One limit belongs to the tools themselves: each event has a time budget
(PreToolUse 5 seconds by default, adjustable from 1 to 120 per tool and event
on the Hooks tab). A hook that runs past it is ignored by the tool, and the
action proceeds.
Where decisions appear
- Decisions — every allow, ask and deny, filterable by source (coding-agent guard, browser extension, Cowork), action, agent and time.
- Device Activity — each session turn by turn, with the commands, files and decisions in line.
- Alerts — conditions and anomalies that need attention.
ChatGPT desktop
The ChatGPT desktop app's chat is not visible to hooks or the network. Waxell can capture it after the fact by reading the rendered conversation over the app's local debug port. It is off by default; turn it on per layer on the Guard's ChatGPT Desktop tab. The app does not open that port by itself: turn on Relaunch to let Waxell restart an already-open ChatGPT with the port (at most once every ten minutes, never launching it on its own), or open the port through your MDM's launch arguments. The app's coding mode is governed preventively by the Codex hooks above.