Skip to main content

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​

ToolEnforcementNotes
Claude CodePreventive — can block or askFull allow / ask / deny.
Codex CLI and the ChatGPT desktop app's coding modePreventive — can blockCodex has no "ask": a warn-level rule is allowed and logged.
Cursor (1.7+)Preventive — can block or ask
GitHub Copilot CLIPreventive — can block or ask
Gemini CLIPreventive — can blockNo "ask": warnings are shown to the user and the action continues.
Cline (CLI and VS Code extension)Preventive — can block tool callsPrompts typed into the Cline CLI are observed, not blocked.
Windsurf / DevinPreventive — can blockNo "ask".
opencode, AntigravityPreventive — on/off
Claude Desktop sessions (Cowork and Chat) on the MacPreventiveVia a Waxell plugin Claude Desktop loads for the organisation.
Claude sessions running in Anthropic's cloudPreventive, decided by Waxell's serversA cloud plugin forwards each event to Waxell for a verdict.
ChatGPT desktop app chatDetective — observed, never blockedSee 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:

StateMeaning
managedRegistered in the tool's managed configuration.
guardRegistered at user level.
n/9Some events missing.
no PreToolUseThe blocking event is missing — the device is marked degraded.
noneNo 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.

AreaWhat it doesDefaults
Blocked commandsRefuses 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 firstAsks the user before running.rm -rf, kill -9, Docker prune, DROP / TRUNCATE, unbounded DELETE.
Protected filesRefuses reads and writes..env*, credentials, *.pem, *.key, SSH keys, .aws, gcloud config, .netrc, .npmrc, .pypirc.
Files that ask before a writeAsks before changing.Lock files, .gitignore, .dockerignore.
Path boundaryKeeps the agent inside its working directory.Off.
GitProtects branches and history.Protected branches main, master, develop, release/*, production; force-push, hard reset and git-config edits blocked.
Infrastructure filesExtra confirmation before writing.Dockerfiles, CI configs, Terraform, Kubernetes and Helm, Makefiles, deploy configs.
Agent networkBlocks fetches to listed domains and internal addresses.Internal and cloud-metadata addresses blocked.
Agent DLPWarns or blocks prompts and tool output containing secrets.Off.
Session limitsCaps 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.