Stop a force-push and ask before risky commands in Grok Build
See, control, and price every tool call Grok Build makes (shell, file edits, search, subagents) from one dashboard. Grok Build runs PreToolUse hooks in every mode, including always-approve. This hook puts your policy on that path.
Install
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
irm https://agenticcontrolplane.com/install.ps1 | iex
The installer detects Grok Build and drops the hook at ~/.acp/hooks/grok-build/hook.mjs. It registers the hook in ~/.grok/hooks/acp.json, which applies to your user, so there is no per-project prompt. It then opens your browser once to create a workspace and writes the key to ~/.acp/credentials. Your next Grok Build session is checked.
MIT-licensed, zero dependencies, one readable file. Read it before you run it.
Why a separate hook
Grok Build reads hooks from your ~/.claude/settings.json by default. If our Claude Code hook is installed, Grok Build already runs it on every call, then ignores what it says. The output formats differ. Grok reads a top-level decision field and does not read Claude’s hookSpecificOutput.permissionDecision. So a Claude-style deny looks like no decision, which Grok treats as allow.
A hook that looks installed and blocks nothing is the worst case for a policy tool. This integration is its own hook that answers in Grok’s format, with Claude’s format alongside in case xAI starts reading it.
The hook makes two other translations:
- Tool names. Grok’s native names (
run_terminal_command,read_file,search_replace) are mapped to the names ACP’s rules use before the check. In live testing,rm -rf /got past the hardline floor under the native name and was denied under the mapped one. The native name is kept in the audit record asclient_tool_name. - The missing ask. Grok has no
askdecision. An ACP ask becomes a block that carries a console link. Open the link in the block message to approve it on the console, or approve it from the approval email, then ask Grok Build to retry. This is the same in every permission mode. ACP denies always hold.
What’s on the wire
| Grok event | ACP call | Effect |
|---|---|---|
PreToolUse |
POST /govern/tool-use |
allow or deny before anything runs, in every permission mode |
PostToolUse / PostToolUseFailure |
POST /govern/tool-output |
audit and PII scan. Findings after the fact are flagged loudly, because only PreToolUse can block in Grok |
Stop |
none | session receipt in the scrollback: calls checked, denies, holds, and a console review link |
If the gateway is down
Grok Build’s hooks are fail-open by design: a hook that times out or crashes lets the call through. This hook doesn’t rely on that. Its registered timeout (30s) is far above its own 4-second decision budget, so it always answers first.
If the gateway is unreachable:
- Attended sessions fail open, loudly. You get
[ACP] ⚠ UNGOVERNEDin the scrollback and a line in~/.acp/lapse.log. An ACP outage should not brick your session. - Unattended tiers fail closed. Nobody is watching, so the block is the safety net.
The hook retries once on a network failure. An HTTP error status means the server answered, so it is not retried.
Manual install
mkdir -p ~/.acp/hooks/grok-build ~/.grok/hooks
curl -fsSL https://raw.githubusercontent.com/agentic-control-plane/grok-build-acp-plugin/main/hook.mjs \
-o ~/.acp/hooks/grok-build/hook.mjs
curl -fsSL https://raw.githubusercontent.com/agentic-control-plane/grok-build-acp-plugin/main/hooks/acp.json \
-o ~/.grok/hooks/acp.json
Then put a workspace key in ~/.acp/credentials (create one at cloud.agenticcontrolplane.com). Node 20 or newer must be on your PATH.
Add the cost X-ray
The hook checks and logs tool calls. It never sees the model call, so it can’t price it. To see cost, the installer appends a [model.acp] block to ~/.grok/config.toml (a base URL and env_key = "ACP_KEY", never a literal key) and leaves your [models] default alone. It also installs grok-acp next to claude-acp and codex-acp:
grok-acp
grok-acp reads your workspace key from ~/.acp/credentials, exports it as ACP_KEY, passes -m acp for that launch only, and starts plain grok with a one-line note if the gateway is unreachable. The block routes gemini-3.5-flash by default. Change model = under [model.acp] to any gpt-*, claude-* or gemini-* id the proxy routes. Full walkthrough: Turn on Cost X-Ray.
Verify it
echo '{"hookEventName":"pre_tool_use","toolName":"run_terminal_command","permissionMode":"default","toolInput":{"command":"rm -rf /"}}' \
| node ~/.acp/hooks/grok-build/hook.mjs
Expected: a decision:"deny" with the hardline-floor reason and exit code 2. The denied call shows up in your activity log a few seconds later. The plugin’s test suite runs this same check.
Which ACP?
Grok Build can also run as an Agent Client Protocol host (grok agent stdio). That is Zed’s editor protocol, and it shares the acronym. This page is about the Agentic Control Plane. Disambiguation.
Protected in 3 steps
Out of the box, ACP records every tool call your agents make. A short safety floor applies in every mode: catastrophic commands (rm -rf on your home or system folders, disk wipes) are always blocked, and force-push, destructive SQL, piping a download into a shell, and deleting outside your project are held for your approval. Your own rules (ask first / never) start applying when you turn on enforce. No rule can loosen the floor; a workspace owner or admin can switch it off on the Policies page (you were asked at install). With --local the always-blocked list is narrower: rm -rf on your home or root, disk wipes, fork bombs.
-
1
Install. One command, then approve this machine in the browser.
curl -fsSL https://agenticcontrolplane.com/install.sh | bash -
2
Turn on your rules. Run
/acp-enforcein your agent. The starter rules start applying:rmand keychain reads are held for your approval (you approve on the console Approvals page or from the approval email); everything else keeps running and is recorded. Add your own with/acp-ask Bash.curl,/acp-deny Bash.git.push,/acp-allow Bash.npm, or on the Policies page. With--localthere is no mode switch: the rules in~/.acp/policy.jsonapply from the first call, and the starter file asks beforerm,curl,git push,chmodandchown. -
3
See it work. Ask your agent to do something risky, for example
git push --forceon a scratch repo. ACP holds the call for your approval; the call and your answer land in the audit log (/acp-whyfor the last hold, the console Activity page, or~/.acp/audit.jsonlwith--local). In Grok Build, a held call shows as a block in the agent; approve it on the console Approvals page or from the approval email, then ask the agent to retry.
Copy-paste rules for the things people are most afraid of (force-push, prod database, rm -rf, a secret in a curl, overnight runs, a cost cap): Rules that stop the scary things.