{"_id":"@agenticcontrolplane/grok-build","name":"@agenticcontrolplane/grok-build","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agenticcontrolplane/grok-build","version":"0.1.0","description":"Agentic Control Plane governance hook for Grok Build (xAI) — identity, audit, and policy enforcement on every tool call, firing even in always-approve mode","type":"module","main":"hook.mjs","scripts":{"test":"node --test test/*.test.mjs"},"engines":{"node":">=20"},"keywords":["grok-build","xai","agent-governance","hooks","policy","audit","agentic-control-plane"],"homepage":"https://agenticcontrolplane.com/controls/grok-build","repository":{"type":"git","url":"git+https://github.com/agentic-control-plane/grok-build-acp-plugin.git"},"license":"MIT","_id":"@agenticcontrolplane/grok-build@0.1.0","gitHead":"8f83d542d1056b6544705608c1ff3e7736f8d843","bugs":{"url":"https://github.com/agentic-control-plane/grok-build-acp-plugin/issues"},"_nodeVersion":"22.23.2","_npmVersion":"10.9.8","dist":{"integrity":"sha512-dtfu3V6cUjlFC7iKv7jylTiyUqIy3Y8H/bg1L0L9K8lONqXHU0eBQgQGs9MQqcg/J6RqvT5v3mVPrhTE0DbgVw==","shasum":"c995a847d0094d731ef80092bff868260ad5ebbe","tarball":"https://registry.npmjs.org/@agenticcontrolplane/grok-build/-/grok-build-0.1.0.tgz","fileCount":5,"unpackedSize":24903,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDKqWmHSi5cgQvKvrJnAl3K99gJGOQxu0AG2XlyC+EV6AiEA84Oqm8BGjmGLjU7zPKIzwImQuv5goItr6Z0HbZGaxk8="}]},"_npmUser":{"name":"davidcrowe","email":"reducibl@gmail.com"},"directories":{},"maintainers":[{"name":"davidcrowe","email":"reducibl@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/grok-build_0.1.0_1787167143292_0.2926914515959693"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-19T19:19:03.101Z","0.1.0":"2026-08-19T19:19:03.454Z","modified":"2026-08-19T19:19:03.727Z"},"maintainers":[{"name":"davidcrowe","email":"reducibl@gmail.com"}],"description":"Agentic Control Plane governance hook for Grok Build (xAI) — identity, audit, and policy enforcement on every tool call, firing even in always-approve mode","homepage":"https://agenticcontrolplane.com/controls/grok-build","keywords":["grok-build","xai","agent-governance","hooks","policy","audit","agentic-control-plane"],"repository":{"type":"git","url":"git+https://github.com/agentic-control-plane/grok-build-acp-plugin.git"},"bugs":{"url":"https://github.com/agentic-control-plane/grok-build-acp-plugin/issues"},"license":"MIT","readme":"# @agenticcontrolplane/grok-build\n\n![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen) ![license](https://img.shields.io/badge/license-MIT-blue)\n\n[Agentic Control Plane](https://agenticcontrolplane.com) governance hook for **Grok Build** (xAI's coding agent). Every tool call is checked against your workspace policy before it runs — and because Grok Build fires `PreToolUse` hooks in **every** permission mode, the policy holds even in `--always-approve`.\n\nBefore any tool runs, ACP is consulted via `/govern/tool-use`; after it runs, the output goes to `/govern/tool-output` for audit and PII scan. Session end emits a receipt with a review link.\n\n## Install\n\n```bash\ncurl -fsSL https://agenticcontrolplane.com/install.sh | bash\n```\n\nThe installer detects Grok Build, places the hook at `~/.acp/hooks/grok-build/hook.mjs`, and registers it in `~/.grok/hooks/acp.json` (user-global — no per-project trust prompt). Manual install:\n\n```bash\nmkdir -p ~/.acp/hooks/grok-build ~/.grok/hooks\ncurl -fsSL https://raw.githubusercontent.com/agentic-control-plane/grok-build-acp-plugin/main/hook.mjs \\\n  -o ~/.acp/hooks/grok-build/hook.mjs\ncurl -fsSL https://raw.githubusercontent.com/agentic-control-plane/grok-build-acp-plugin/main/hooks/acp.json \\\n  -o ~/.grok/hooks/acp.json\n```\n\nCredentials live at `~/.acp/credentials` (the installer provisions them; or paste a workspace key from [cloud.agenticcontrolplane.com](https://cloud.agenticcontrolplane.com)).\n\n## What it does\n\n| Grok event | ACP call | Effect |\n|---|---|---|\n| `PreToolUse` | `POST /govern/tool-use` | `deny` blocks the call (top-level `decision:\"deny\"` + exit 2, both channels); `ask` resolves by mode (below); `allow` proceeds |\n| `PostToolUse` / `PostToolUseFailure` | `POST /govern/tool-output` | Audit + PII scan; a post-hoc block degrades to a loud audit line (Grok's only blocking tool event is `PreToolUse`) |\n| `Stop` | — | Session receipt in the scrollback with a console review link |\n\n**Tool-name mapping.** Grok's native names (`run_terminal_command`, `read_file`, `search_replace`, …) are mapped to the canonical vocabulary before the policy check so content floors fire — verified live: `rm -rf /` hits the hardline floor under the native name. The native name is preserved as `client_tool_name` in the audit record. Unknown and MCP (`server__tool`) names pass through.\n\n## The ask decision\n\nGrok Build's hook contract has no `ask` — a gate hook can only allow or deny. An ACP `ask` verdict resolves by permission mode:\n\n- **`default` / `plan`** — a human answers prompts and Grok's own permission gate still stands after this hook, so the ask lands on the native prompt. Caveat: an explicit local allow rule outranks an ACP ask in these modes. ACP denies always hold.\n- **`auto` / `bypassPermissions` / headless** — nobody is at the prompt: the ask becomes a deny whose reason carries the console link.\n\n## Failure posture\n\nGrok Build hooks are **fail-open by design** — a timed-out, crashed, or malformed hook logs and allows. This hook therefore makes its posture explicit rather than inheriting Grok's:\n\n- **Interactive sessions** (`default`/`plan`/`auto`): gateway unreachable → fail **open**, loudly — `[ACP] ⚠ UNGOVERNED` on stderr and a durable line in `~/.acp/lapse.log`. An ACP outage must never brick your session.\n- **Unattended tiers** (`bypassPermissions`, headless, CI): fail **closed** — nobody is watching, so the block is the safety net.\n- One retry on transport failure before the posture applies (cold starts answer on the second try). HTTP error statuses are the server answering — never retried.\n- The registered hook timeout (30s) sits far above the internal 4s decision budget, so our posture decides the outcome, not Grok's fail-open timer.\n\nFor yolo users: `--always-approve` bypasses Grok's own prompts but **not** this hook — Grok fires deny rules and PreToolUse hooks in every mode. That is the point.\n\n## Configuration\n\nEnvironment (or `~/.acp/config.json` — snake_case keys — for setups where env doesn't reach hooks):\n\n| Env | Config key | Default |\n|---|---|---|\n| `ACP_BEARER_TOKEN` | — | `~/.acp/credentials` |\n| `ACP_GOVERN_BASE` | `govern_base` | `https://govern.agenticcontrolplane.com` |\n| `ACP_CONSOLE_BASE` | `console_base` | `https://cloud.agenticcontrolplane.com` |\n| `ACP_AGENT_TIER` | `agent_tier` | resolved from `permissionMode` / CI |\n| `ACP_CHECK_TIMEOUT_MS` | `check_timeout_ms` | `4000` |\n| `ACP_SHADOW` | `shadow` | shadow-mode notices on |\n\n## Tests\n\n```bash\nnode --test test/*.test.mjs\n```\n\n17 offline tests against a mock gateway (payload parsing both vocabularies, deny/ask/allow, both fail postures, retry discipline, tool-name mapping, receipts). Deny/allow/receipt additionally verified live against the production gateway on Grok's documented payload shape.\n\n## Which ACP?\n\nThis is the **Agentic Control Plane**. Grok Build also speaks Zed's **Agent Client Protocol** (`grok agent stdio`) — an editor-integration protocol that shares the acronym. [Disambiguation.](https://agenticcontrolplane.com/acp-vs-acp)\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-1308cc49c5a2935c26d027dd54c34674"}