Skip to content
Agentic Control Plane

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

macOS · Linux · WSL
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
Windows · PowerShell
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 as client_tool_name.
  • The missing ask. Grok has no ask decision. 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] ⚠ UNGOVERNED in 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. 1
    Install. One command, then approve this machine in the browser. curl -fsSL https://agenticcontrolplane.com/install.sh | bash
  2. 2
    Turn on your rules. Run /acp-enforce in your agent. The starter rules start applying: rm and 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 --local there is no mode switch: the rules in ~/.acp/policy.json apply from the first call, and the starter file asks before rm, curl, git push, chmod and chown.
  3. 3
    See it work. Ask your agent to do something risky, for example git push --force on a scratch repo. ACP holds the call for your approval; the call and your answer land in the audit log (/acp-why for the last hold, the console Activity page, or ~/.acp/audit.jsonl with --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.