Grok Subagent
Use Grok as an implementation worker. The parent agent owns scope, review,
verification, commits, and external publication.
Workflow
1. Confirm the local CLI contract
Run:
bash
grok --version
grok --help
jq --version
Prefer the flags reported by the installed binary. Grok Build 1.0.5 uses:
- for one headless turn
- for a prompt file
- for the working directory
- for non-interactive implementation
- to expose the real stop reason
- to prevent nested delegation
Other projects named Grok CLI use incompatible flags such as
and
. Never translate examples across CLI variants without checking
.
2. Establish the boundary
Before delegation:
- Inspect repository status and current branch.
- Preserve and describe any pre-existing changes.
- Give Grok one focused task with explicit completion criteria.
- Name files or local reference implementations worth inspecting.
- Specify the exact verification commands.
- Reserve commit, tag, push, package publication, and destructive Git actions
for the parent agent unless the user explicitly delegates them to Grok.
For parallel or risky work, create isolation outside Grok before invocation.
Headless
does not create a worktree from
.
3. Invoke Grok headlessly
When the host supports shell subagents, delegate this invocation to one so the
parent remains available to orchestrate other work. The shell subagent must
actually run Grok rather than implement the task in its place.
Use an absolute repository path and quote the prompt with a heredoc. Capture
JSON because Grok Build 1.0.5 can exit with status 0 even when a tool call is
cancelled:
bash
grok_result=$(grok -p "$(cat <<'EOF'
Work in /absolute/path/to/repository.
Task:
- <one focused implementation goal>
Requirements:
- <behavior and compatibility constraints>
- Preserve existing public APIs unless explicitly changed.
- Preserve pre-existing uncommitted changes.
Verification:
- Run <exact test/build commands>.
- Run git diff --check.
Do not commit, tag, push, publish, reset, or discard unrelated changes.
Return changed files, design decisions, test results, and unresolved risks.
EOF
)" \
--cwd "/absolute/path/to/repository" \
--permission-mode auto \
--no-subagents \
--output-format json)
printf '%s\n' "$grok_result"
printf '%s\n' "$grok_result" | jq -e '.stopReason == "end_turn"' >/dev/null
Use
when the executable path is unknown. Use
for very long generated prompts. Keep credentials, tokens, and
private data out of prompts. Do not replace
with
;
keep the delegated working directory and task boundary narrow instead.
Treat
,
, missing output, invalid JSON, or any other stop
reason as a failed invocation even when the process exits with status 0. For a
mutation task, also require the expected repository delta;
without
the requested files or behavior is not success.
4. Review centrally
Treat Grok's report as a claim to verify:
- Inspect , , , and the full
relevant diff.
- Read every new public interface and security-sensitive path.
- Confirm deletions and dependency changes are intentional.
- Run the required tests and builds independently.
- Search for obsolete references when the task replaces an old API or
package.
- Check that only intended files changed.
The step is complete only when the parent can explain the resulting design and
has direct evidence that verification passed.
5. Use focused correction passes
If review finds a defect, send Grok a narrow correction containing:
- the concrete defect and why it matters
- the required behavior
- tests that must change or be added
- the same Git and scope guardrails
Resume the same host shell subagent when practical so it retains implementation
context. Run Grok again inside that subagent, then repeat central review.
If Grok stalls or exits without edits, inspect
, its output, and
repository state.
after a proposed tool call usually indicates a
permission-mode mismatch. Retry once only after changing the evidenced cause,
or with a smaller task and sharper completion criteria. Do not repeat the same
invocation without new evidence.
Prompt checklist
- Absolute repository path
- One focused goal
- Existing changes to preserve
- Exact behavior and non-goals
- Language and architecture constraints
- Relevant source and reference paths
- Error and compatibility expectations
- Required tests and build commands
- No-commit/no-push guardrail
- Expected final report
Completion report
Report:
- Grok command shape, CLI version, and JSON stop reason
- implementation summary
- files changed or deleted
- independent test/build results
- commits or publications performed by the parent
- remaining blockers or physical-device/runtime verification