Grok over ACP
Run Grok Build on this machine as a worker in the SDLC sense: a
separate agent with its own transcript that you mint clean, resume by id,
and never trust without verification. Transport is ACP, JSON-RPC over
grok agent stdio, driven by the grok-acp command from
packages/grok-acp in this repo. Stdlib Python,
Linux only. If grok-acp is not on PATH, run packages/grok-acp/grok_acp.py
from the checkout that holds this skill directory's real path, or install it
as the package README says. This skill directory is usually a symlink.
Iron law
The operator picks Grok; you do not. Offloading is opt-in per ask.
Exception: the credit-failure fallback in cursor-cloud-agents-when is pre-approved.
Grok's summary is a claim, not evidence. Verify before you report.
Permissions (operator order, 2026-09-21)
Grok runs with maximum permissions, on purpose: --always-approve,
_meta.yoloMode, sandbox off, and any permission request that still
arrives is auto-approved. It runs as the same user, so it can read, write,
run, push, and reach the network exactly as the operator can.
What still binds it: deny rules and hooks in ~/.grok/config.toml and
~/.claude/settings.json (Grok reads it). Project-level rules, hooks, and
auto-loaded instructions apply only in a folder Grok already trusts; a
fresh item worktree usually is not, so do not count on them. Nothing else.
Scope is set by your prompt, so write the scope down.
Run it
GROK=grok-acp
# mint a clean worker for a work item
$GROK run --cwd <item worktree> --label <item-id>:builder --prompt-file <handoff.md>
# resume the same worker later: delta only
$GROK run --cwd <item worktree> --resume <item-id>:builder --prompt-file <delta.md>
One invocation is one prompt turn. Stdout is one JSON object; progress lines
go to stderr. Start run in the background and read the result when
notified; builds outlast a foreground shell call. --timeout defaults to
3600 seconds. On timeout or SIGTERM the client sends ACP session/cancel,
waits up to 20 seconds, and exits 5; the session stays resumable. A SIGTERM
before the prompt is sent stops the run with no turn spent. A label and a
session each take one turn at a time: a second run gets busy (exit 2).
| Flag |
Use |
--cwd |
Item branch worktree. Required. A resumed label must use the cwd it was minted in |
--label |
Registry name, <item-id>:<role>. This is the builder_id you store on the item |
--resume |
A label, or a raw Grok session id. grok sessions list finds ids started elsewhere. To adopt one, add an unused --label |
--replace |
With --label only: mint a new session under a label that already exists. For fallback or overflow |
--prompt / --prompt-file / stdin |
The handoff. Prefer a file |
--model, --effort |
low medium high xhigh. Omit for Grok's defaults |
--rules-file |
Extra system-prompt rules. New sessions only; refused with --resume |
--out |
Run directory. Default ~/.local/state/grok-acp/runs/<stamp>-<pid> |
$GROK sessions prints the label registry, ~/.local/state/grok-acp/sessions.json.
If GROK_ACP_STATE is set, the state directory is that path. The state
directory and the run directories it creates are 0700.
$GROK forget <label> drops a label; Grok keeps the session.
Result
| Field |
Meaning |
ok, error, stopReason |
ok only when the turn ended with end_turn. Usage failures carry error + detail only |
sessionId, label, resumed |
Store these on the item |
text |
Grok's final message only. Full text: response.md in runDir |
filesEdited, toolCalls, failedToolCalls |
From ACP tool-call updates. A hint, not a diff |
leftoverProcessesKilled |
Grok's child processes still alive at exit and sent SIGTERM. Its shell commands outlive it otherwise |
permissionRequestsAutoApproved, plan, durationSec |
Permission prompts answered for Grok; its last plan, if any; wall time |
usage |
Model, tokens, calls for this turn |
runDir |
prompt.md, response.md, result.json, events.ndjson (every ACP message), grok.stderr |
| Exit |
Meaning |
Do |
| 0 |
end_turn |
Verify |
| 2 |
Usage: bad_cwd, empty_prompt, unreadable_file, bad_args, label_exists, unknown_label, cwd_mismatch, busy, bad_out |
Fix the call. unknown_label is a typo, not a reason to --replace |
| 3 |
Resume failed |
Mint --replace with a short handoff, per SDLC Fallback |
| 4 |
Agent or protocol error |
Read grok.stderr. Auth: operator runs grok login |
| 5 |
Timeout, signal, or cancelled |
Resume with what is left, or raise --timeout. If sessionId is null, it stopped before a session existed: mint again |
| 6 |
Stopped for another reason (max_tokens, refusal, …) |
Read stopReason; usually overflow → --replace |
SDLC fit
- Role. Grok is a builder unless the operator says otherwise. The
verifier and the reviewer of that item are different agents and never
see Grok's transcript. Do not read
response.md or events.ndjson into
their prompts. Give the verifier the ticket and the proving commands;
give the reviewer the inputs pr-review names.
- One label per role per item.
DER-12:builder is never reused on
another item and never resumed to verify or review its own work.
- Mint = pack. The first prompt is the whole handoff: ticket, LLD
slice, acceptance, paths, standards, the proving commands, and the repo
rules that bind it. Tell it to read the repo
AGENTS.md first. Grok
cannot see this skills home, so pack the text or give the path.
- Resume = delta. What changed, what failed, what to do next. Do not
re-send the spec.
- Branching is yours. Create the item branch and worktree yourself from
the source Branches names;
pass it as
--cwd. Tell Grok to commit on that branch, never to push,
and never to merge the item branch into anything. De-conflicting is still
the builder's job: when project-main moves, resume the label with a delta
that tells it to merge or rebase project-main into the item branch.
Lands stay serialized and stay with the manager (Land path).
- Blockers and gates. Check the item's blockers before minting.
Offloading the build skips no gate: Review and security still run.
- Fallback and overflow. Exit 3, or a session too long to be useful:
--replace with a short handoff, per SDLC Fallback.
Handoff shape
You are the builder for <item-id> in <repo>. Read AGENTS.md first.
Goal: <what done looks like>
Acceptance: <from the ticket>
Design: <LLD slice or path>
Scope: <paths>. Do not touch <paths>.
Standards: <language / test rules, packed or by path>
Prove it: <exact commands that must pass>
Git: commit on <branch>. Never push. Never merge <branch> into another
branch or switch branches. Merge <base> into <branch> only when asked.
Finish with: files changed, commands run and their results, open risks.
After it returns
Load verify-before-done. You are the manager, not the verifier.
- Smoke-check the worktree yourself:
git status, git diff <base>...,
and that the branch and git rule were kept. filesEdited misses
shell-made changes. This smoke check is not the gate.
- First pass: mint the item's verifier clean with the ticket and the
proving commands. Later passes: resume that
verifier_id with the
delta. Never give it Grok's output.
- verifier runs the proving commands.
- Send verifier failures to the same Grok label as a delta.
- At every step, take "tests pass" from the verifier, never from
text.
Always
- State scope, do-not-touch paths, and the git rule in every mint.
- Keep secrets out of prompts;
prompt.md is written to disk.
- Report to the operator what was offloaded, the label, and the evidence.
Ask first
- Offloading when the operator did not ask for Grok on this work.
- Pointing
--cwd at a live host's config tree, $HOME, or /.
- Work that needs credentials the prompt would have to carry.
Never
- Treat
ok: true as landed+verified. Run After it returns.
- Let one Grok session build and verify the same item. Mint a separate verifier.
- Feed Grok's transcript to a verifier or reviewer. Give each its Role inputs.
- Run two turns against the same session at once. Wait, then resume.
- Tighten or loosen the permission posture here without a new operator
order; it is recorded above with its date. Ask the operator for one.
Red flags
- "Grok said the tests pass"
- "I'll resume the builder to double-check its own work"
- "New session each loop, it is simpler"
- "Let Grok merge it, it has the perms"
1---2name: grok-acp3description: use this when the operator chooses to offload work to Grok Build — "offload to grok", "have grok build it", "delegate to grok", "resume the grok session" — to run the local Grok CLI as an SDLC worker (builder by default) over ACP, with session resume. do not use on your own initiative, and do not use for a quick read, search, or one-line fix you can do inline.4metadata:5 source: https://skillmd.com/skills/alexderz/grok-acp6---78# Grok over ACP910Run Grok Build on this machine as a **worker** in the SDLC sense: a11separate agent with its own transcript that you mint clean, resume by id,12and never trust without verification. Transport is ACP, JSON-RPC over13`grok agent stdio`, driven by the `grok-acp` command from14[packages/grok-acp](../../packages/grok-acp/) in this repo. Stdlib Python,15Linux only. If `grok-acp` is not on `PATH`, run `packages/grok-acp/grok_acp.py`16from the checkout that holds this skill directory's real path, or install it17as the package README says. This skill directory is usually a symlink.1819## Iron law2021**The operator picks Grok; you do not.** Offloading is opt-in per ask.22Exception: the credit-failure fallback in [cursor-cloud-agents-when](../cursor-cloud-agents-when/SKILL.md#credit-degrade) is pre-approved.23**Grok's summary is a claim, not evidence.** Verify before you report.2425## Permissions (operator order, 2026-09-21)2627Grok runs with maximum permissions, on purpose: `--always-approve`,28`_meta.yoloMode`, sandbox `off`, and any permission request that still29arrives is auto-approved. It runs as the same user, so it can read, write,30run, push, and reach the network exactly as the operator can.3132What still binds it: `deny` rules and hooks in `~/.grok/config.toml` and33`~/.claude/settings.json` (Grok reads it). Project-level rules, hooks, and34auto-loaded instructions apply only in a folder Grok already trusts; a35fresh item worktree usually is not, so do not count on them. Nothing else.36Scope is set by your prompt, so write the scope down.3738## Run it3940```bash41GROK=grok-acp4243# mint a clean worker for a work item44$GROK run --cwd <item worktree> --label <item-id>:builder --prompt-file <handoff.md>4546# resume the same worker later: delta only47$GROK run --cwd <item worktree> --resume <item-id>:builder --prompt-file <delta.md>48```4950One invocation is one prompt turn. Stdout is one JSON object; progress lines51go to stderr. Start `run` **in the background** and read the result when52notified; builds outlast a foreground shell call. `--timeout` defaults to533600 seconds. On timeout or SIGTERM the client sends ACP `session/cancel`,54waits up to 20 seconds, and exits 5; the session stays resumable. A SIGTERM55before the prompt is sent stops the run with no turn spent. A label and a56session each take one turn at a time: a second run gets `busy` (exit 2).5758| Flag | Use |59| --- | --- |60| `--cwd` | Item branch worktree. Required. A resumed label must use the cwd it was minted in |61| `--label` | Registry name, `<item-id>:<role>`. This is the `builder_id` you store on the item |62| `--resume` | A label, or a raw Grok session id. `grok sessions list` finds ids started elsewhere. To adopt one, add an unused `--label` |63| `--replace` | With `--label` only: mint a new session under a label that already exists. For fallback or overflow |64| `--prompt` / `--prompt-file` / stdin | The handoff. Prefer a file |65| `--model`, `--effort` | `low` `medium` `high` `xhigh`. Omit for Grok's defaults |66| `--rules-file` | Extra system-prompt rules. New sessions only; refused with `--resume` |67| `--out` | Run directory. Default `~/.local/state/grok-acp/runs/<stamp>-<pid>` |6869`$GROK sessions` prints the label registry, `~/.local/state/grok-acp/sessions.json`.70If `GROK_ACP_STATE` is set, the state directory is that path. The state71directory and the run directories it creates are `0700`.72`$GROK forget <label>` drops a label; Grok keeps the session.7374### Result7576| Field | Meaning |77| --- | --- |78| `ok`, `error`, `stopReason` | `ok` only when the turn ended with `end_turn`. Usage failures carry `error` + `detail` only |79| `sessionId`, `label`, `resumed` | Store these on the item |80| `text` | Grok's **final** message only. Full text: `response.md` in `runDir` |81| `filesEdited`, `toolCalls`, `failedToolCalls` | From ACP tool-call updates. A hint, not a diff |82| `leftoverProcessesKilled` | Grok's child processes still alive at exit and sent SIGTERM. Its shell commands outlive it otherwise |83| `permissionRequestsAutoApproved`, `plan`, `durationSec` | Permission prompts answered for Grok; its last plan, if any; wall time |84| `usage` | Model, tokens, calls for this turn |85| `runDir` | `prompt.md`, `response.md`, `result.json`, `events.ndjson` (every ACP message), `grok.stderr` |8687| Exit | Meaning | Do |88| --- | --- | --- |89| 0 | `end_turn` | Verify |90| 2 | Usage: `bad_cwd`, `empty_prompt`, `unreadable_file`, `bad_args`, `label_exists`, `unknown_label`, `cwd_mismatch`, `busy`, `bad_out` | Fix the call. `unknown_label` is a typo, not a reason to `--replace` |91| 3 | Resume failed | Mint `--replace` with a short handoff, per SDLC [Fallback](../sdlc/references/subagents.md#fallback) |92| 4 | Agent or protocol error | Read `grok.stderr`. Auth: operator runs `grok login` |93| 5 | Timeout, signal, or cancelled | Resume with what is left, or raise `--timeout`. If `sessionId` is `null`, it stopped before a session existed: mint again |94| 6 | Stopped for another reason (`max_tokens`, `refusal`, …) | Read `stopReason`; usually overflow → `--replace` |9596## SDLC fit9798- **Role.** Grok is a **builder** unless the operator says otherwise. The99 verifier and the reviewer of that item are different agents and never100 see Grok's transcript. Do not read `response.md` or `events.ndjson` into101 their prompts. Give the verifier the ticket and the proving commands;102 give the reviewer the inputs [pr-review](../pr-review/SKILL.md) names.103- **One label per role per item.** `DER-12:builder` is never reused on104 another item and never resumed to verify or review its own work.105- **Mint = pack.** The first prompt is the whole handoff: ticket, LLD106 slice, acceptance, paths, standards, the proving commands, and the repo107 rules that bind it. Tell it to read the repo `AGENTS.md` first. Grok108 cannot see this skills home, so pack the text or give the path.109- **Resume = delta.** What changed, what failed, what to do next. Do not110 re-send the spec.111- **Branching is yours.** Create the item branch and worktree yourself from112 the source [Branches](../sdlc/references/branches-and-lands.md#branches) names;113 pass it as `--cwd`. Tell Grok to commit on that branch, **never** to push,114 and never to merge the item branch into anything. De-conflicting is still115 the builder's job: when project-main moves, resume the label with a delta116 that tells it to merge or rebase project-main **into** the item branch.117 Lands stay serialized and stay with the manager ([Land path](../sdlc/references/branches-and-lands.md#land-path)).118- **Blockers and gates.** Check the item's blockers before minting.119 Offloading the build skips no gate: Review and security still run.120- **Fallback and overflow.** Exit 3, or a session too long to be useful:121 `--replace` with a short handoff, per SDLC [Fallback](../sdlc/references/subagents.md#fallback).122123### Handoff shape124125```text126You are the builder for <item-id> in <repo>. Read AGENTS.md first.127128Goal: <what done looks like>129Acceptance: <from the ticket>130Design: <LLD slice or path>131Scope: <paths>. Do not touch <paths>.132Standards: <language / test rules, packed or by path>133Prove it: <exact commands that must pass>134Git: commit on <branch>. Never push. Never merge <branch> into another135 branch or switch branches. Merge <base> into <branch> only when asked.136137Finish with: files changed, commands run and their results, open risks.138```139140## After it returns141142Load `verify-before-done`. You are the manager, not the verifier.1431441. Smoke-check the worktree yourself: `git status`, `git diff <base>...`,145 and that the branch and git rule were kept. `filesEdited` misses146 shell-made changes. This smoke check is not the gate.1472. First pass: mint the item's verifier clean with the ticket and the148 proving commands. Later passes: resume that `verifier_id` with the149 delta. Never give it Grok's output.1503. **verifier** runs the proving commands.1514. Send verifier failures to the **same** Grok label as a delta.1525. At every step, take "tests pass" from the verifier, never from `text`.153154## Always155156- State scope, do-not-touch paths, and the git rule in every mint.157- Keep secrets out of prompts; `prompt.md` is written to disk.158- Report to the operator what was offloaded, the label, and the evidence.159160## Ask first161162- Offloading when the operator did not ask for Grok on this work.163- Pointing `--cwd` at a live host's config tree, `$HOME`, or `/`.164- Work that needs credentials the prompt would have to carry.165166## Never167168- Treat `ok: true` as landed+verified. Run [After it returns](#after-it-returns).169- Let one Grok session build and verify the same item. Mint a separate verifier.170- Feed Grok's transcript to a verifier or reviewer. Give each its Role inputs.171- Run two turns against the same session at once. Wait, then resume.172- Tighten or loosen the permission posture here without a new operator173 order; it is recorded above with its date. Ask the operator for one.174175## Red flags176177- "Grok said the tests pass"178- "I'll resume the builder to double-check its own work"179- "New session each loop, it is simpler"180- "Let Grok merge it, it has the perms"