Code

How to run (transparent)

1. Take the absolute Base directory for this skill from the Skill tool

(the folder that contains this skill's SKILL.md and run.mjs).

1. Set SKILL_BASE to that path. Do not invent versioned cache paths.
2. Always invoke the companion only through this skill's runner:

SKILL_BASE=''
# Required for completion notifications (plugin/references/execution-context.md):
export GROK_COMPANION_EXECUTION_CONTEXT=foreground   # or background
node "$SKILL_BASE/run.mjs"  [args...]

run.mjs finds the plugin install from its own location and runs scripts/grok-companion.mjs. No CLAUDE_PLUGIN_ROOT / PLUGIN_ROOT required.

If the host already exported CLAUDE_PLUGIN_ROOT or PLUGIN_ROOT, you may call node "$CLAUDE_PLUGIN_ROOT/scripts/grok-companion.mjs" instead; prefer "$SKILL_BASE/run.mjs" whenever the Skill tool loaded this skill.

Return companion stdout verbatim. Never put free-text in --task "..."; use --task-file - with a single-quoted heredoc.

Run a Grok code implementation through the hardened wrapper and relay its result envelope. The wrapper creates and verifies its own external git worktree (never the current checkout), runs the workspace build gate, and keeps the worktree for inspection. Nothing is ever committed, merged, pushed, or deleted automatically.

Raw slash-command arguments: $ARGUMENTS

Required wrapper flags (copy exactly, substitute only placeholder values):

• --target is required.
• --base is required (the wrapper builds the worktree

from a committed revision; if the task depends on uncommitted changes, the run fails closed - the user must commit what the task needs first).

• Exactly one of --task or --task-file is required. Prefer

--task-file for a multi-paragraph spec.

• Preserve the user's arguments exactly. Do not strip, add, or reorder flags.

Do not invent a flag that is not in the argument-hint.

• Shell-injection safety for --task : the task is free text you must NEVER

place in a shell-evaluated position. $(...)/backticks inside a double-quoted --task "..." run locally BEFORE the wrapper validates them. When the arguments carry a --task , deliver that text on STDIN with --task-file - and a SINGLE-QUOTED heredoc so the shell passes it byte-for-byte; the companion stages it into a temp file for the wrapper.

• Shell-injection safety for flag VALUES (--target, --base, a `--task-file

, --model, --timeout, --max-turns, and EVERY other value you substitute from $ARGUMENTS): wrap each substituted value in SINGLE quotes, for example --target '' --base ''. Single quotes stop the shell from evaluating $(...)/backticks, so a hostile value reaches the companion as one literal argv token and the wrapper validates it (target/worktree path resolution + escape guards). An unquoted OR double-quoted value would be command-substituted locally BEFORE the wrapper ever sees it -- the same injection class as an unsafe --task "...". The bare --web` flag carries no value to quote.

--web passthrough:

• Web tools are OFF by default. Pass --web only when the implementation

genuinely depends on current external practices, current library or software versions, or living external documentation the repo cannot answer. Do not add --web otherwise.

Execution mode (foreground vs background):

• If the raw arguments include --wait, run in the foreground (do not ask).
• If the raw arguments include --background, run in a Claude background task

(do not ask).

• --wait and --background are Claude Code execution flags. Do NOT forward

them to the companion or wrapper; strip them from the wrapper argv.

• Otherwise, estimate the size first:
• Run git status --short --untracked-files=all and git diff --shortstat.
• A code run is an implementation (default wrapper timeout 3600s), so it is

almost always long. Recommend background unless the change is clearly tiny.

• Then use AskUserQuestion exactly once, recommended option first with its

label suffixed (Recommended). The two options are:

• Wait for results
• Run in background

Foreground flow (one Bash call, then relay verbatim). When the arguments carry a --task , route that text through STDIN so it is never shell-evaluated:

export GROK_COMPANION_EXECUTION_CONTEXT=foreground
node "$SKILL_BASE/run.mjs" code --target '' --base '' [other non-task flags from $ARGUMENTS, each substituted value single-quoted] --task-file - 
GROK_TASK

When the arguments already use --task-file , drop the heredoc and pass every flag as single-quoted argv tokens:

export GROK_COMPANION_EXECUTION_CONTEXT=foreground
node "$SKILL_BASE/run.mjs" code --target '' --base '' --task-file '' [other non-task flags from $ARGUMENTS, each substituted value single-quoted]

• Return the command stdout envelope VERBATIM. Do not paraphrase, summarize, or

add commentary before or after it. Preserve the exit status.

Background flow:

• Set export GROK_COMPANION_EXECUTION_CONTEXT=background (see

plugin/references/execution-context.md).

• Launch the same command with Bash(run_in_background: true).
• Do not wait for completion or read its output this turn.
• Tell the user: "Grok code run started in the background. Run `/grok:status

--run-id ` to read the result envelope."

If the companion prints an actionable "could not locate the Grok wrapper" message instead of an envelope, tell the user to run /grok:setup.

Implementation contract + handoff (1.6.0+)

Optional --contract-file points at operator-trusted JSON (writeScopes + requiredValidation argv arrays). Bad contracts fail closed before Grok with implementation-contract-invalid. Trust model: operator-contract-trusted-no-os-sandbox (no OS filesystem sandbox claim for validation commands).

Direct run-mode refuses --contract-file (companion fail-closed). Verified handoff artifacts (implementation.patch + implementation-handoff.json) are written only on the hardened path under the C2 run dir.

On success or classified failure after hardened Grok, the wrapper writes:

• runs//artifacts/implementation.patch (immutable git binary full-index)
• runs//implementation-handoff.json

Notify is not integrate. After a code run, parents (Claude Code / Codex) must call /grok:handoff --run-id and require dual-condition ready before any apply. See skills/handoff/SKILL.md and references/implementation-handoff.md. Never auto-apply.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sfourdrinier
• Source: sfourdrinier/grok-skills
• License: MIT

Install and usage instructions live in the source repository linked above.