Back to Details

grok-subagent

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Grok Subagent

Grok Subagent

Use Grok as an implementation worker. The parent agent owns scope, review, verification, commits, and external publication.
将Grok用作实现工作代理。父代理负责范围界定、审核、验证、提交以及外部发布。

Workflow

工作流程

1. Confirm the local CLI contract

1. 确认本地CLI约定

Run:
bash
grok --version
grok --help
jq --version
Prefer the flags reported by the installed binary. Grok Build 1.0.5 uses:
  • -p, --single <PROMPT>
    for one headless turn
  • --prompt-file <PATH>
    for a prompt file
  • --cwd <PATH>
    for the working directory
  • --permission-mode auto
    for non-interactive implementation
  • --output-format json
    to expose the real stop reason
  • --no-subagents
    to prevent nested delegation
Other projects named Grok CLI use incompatible flags such as 
--prompt
and 
--directory
. Never translate examples across CLI variants without checking 
--help
.
运行：
bash
grok --version
grok --help
jq --version
优先使用已安装二进制文件所报告的参数。Grok Build 1.0.5使用以下参数：
  • -p, --single <PROMPT>
    用于单次无头交互
  • --prompt-file <PATH>
    用于指定提示文件
  • --cwd <PATH>
    用于指定工作目录
  • --permission-mode auto
    用于非交互式实现
  • --output-format json
    用于显示真实停止原因
  • --no-subagents
    用于防止嵌套委托
其他名为Grok CLI的项目使用不兼容的参数，例如
--prompt
和
--directory
。在未查看
--help
的情况下，切勿在不同CLI变体间转换示例。

2. Establish the boundary

2. 确立边界

Before delegation:
  1. Inspect repository status and current branch.
  2. Preserve and describe any pre-existing changes.
  3. Give Grok one focused task with explicit completion criteria.
  4. Name files or local reference implementations worth inspecting.
  5. Specify the exact verification commands.
  6. 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 
-p
does not create a worktree from 
--worktree
.
委托前：
  1. 检查仓库状态和当前分支。
  2. 保留并描述所有已存在的变更。
  3. 为Grok分配一个明确的专注任务，并给出清晰的完成标准。
  4. 指定值得检查的文件或本地参考实现。
  5. 明确具体的验证命令。
  6. 除非用户明确将提交、打标签、推送、包发布以及破坏性Git操作委托给Grok，否则这些操作由父代理负责。
对于并行或高风险工作，在调用Grok前先在外部创建隔离环境。无头模式的
-p
参数不会从
--worktree
创建工作树。

3. Invoke Grok headlessly

3. 无头模式调用Grok

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 
command -v grok
when the executable path is unknown. Use 
--prompt-file
for very long generated prompts. Keep credentials, tokens, and private data out of prompts. Do not replace 
auto
with 
bypassPermissions
; keep the delegated working directory and task boundary narrow instead.
Treat 
cancelled
, 
max_turns
, 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; 
end_turn
without the requested files or behavior is not success.
当主机支持shell子代理时，将此调用委托给shell子代理，以便父代理可继续协调其他工作。shell子代理必须实际运行Grok，而非自行完成任务。
使用绝对仓库路径，并通过here-doc引用提示内容。捕获JSON输出，因为即使工具调用被取消，Grok Build 1.0.5仍可能以状态码0退出：
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
当可执行文件路径未知时，使用
command -v grok
。对于极长的生成提示，使用
--prompt-file
。请勿在提示中包含凭据、令牌和私有数据。不要将
auto
替换为
bypassPermissions
；相反，应缩小委托的工作目录和任务范围。
即使进程以状态码0退出，若停止原因为
cancelled
、
max_turns
、输出缺失、JSON无效或其他任何异常，均视为调用失败。对于变更任务，还需确认仓库有预期的变更；仅
end_turn
但未生成请求的文件或行为不算成功。

4. Review centrally

4. 集中审核

Treat Grok's report as a claim to verify:
  1. Inspect 
    git status
    , 
    git diff --stat
    , 
    git diff --check
    , and the full relevant diff.
  2. Read every new public interface and security-sensitive path.
  3. Confirm deletions and dependency changes are intentional.
  4. Run the required tests and builds independently.
  5. Search for obsolete references when the task replaces an old API or package.
  6. 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.
将Grok的报告视为需要验证的声明：
  1. 检查
    git status
    、
    git diff --stat
    、
    git diff --check
    以及完整的相关差异。
  2. 阅读所有新的公共接口和安全敏感路径。
  3. 确认删除操作和依赖变更是有意为之。
  4. 独立运行所需的测试和构建。
  5. 当任务替换旧API或包时，搜索过时的引用。
  6. 检查是否只有目标文件被修改。
只有当父代理能够解释最终设计，并且有直接证据证明验证通过时，此步骤才算完成。

5. Use focused correction passes

5. 使用聚焦修正环节

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 
.stopReason
, its output, and repository state. 
cancelled
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.
如果审核发现缺陷，向Grok发送一份明确的修正指令，包含：
  • 具体缺陷及其影响
  • 所需行为
  • 必须修改或添加的测试
  • 相同的Git和范围限制
若可行，继续使用同一主机shell子代理，以便其保留实现上下文。在该子代理中再次运行Grok，然后重复集中审核。
如果Grok停滞或未做任何编辑就退出，检查
.stopReason
、其输出以及仓库状态。若在提议工具调用后出现
cancelled
，通常表示权限模式不匹配。仅在更改已确认的原因后，或使用更小的任务和更明确的完成标准时，重试一次。若无新证据，请勿重复相同的调用。

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
报告内容：
  • Grok命令格式、CLI版本以及JSON停止原因
  • 实现摘要
  • 已修改或删除的文件
  • 独立测试/构建结果
  • 父代理执行的提交或发布操作
  • 剩余障碍或物理设备/运行时验证需求