grok-runner

Grok Runner

Use shared/references/model-preview.md to choose the branch first. Deterministic checks need no model selection. Actual dispatch uses one concrete approved snapshot; nested calls consume it without re-resolution or extra workers.

Execute the caller's scoped prompt through the local CLI. Shared roles, envelope keys, and result handling live in shared/references/runner-common.md. Preserve seat fidelity: name the provider that actually answered, and report unavailable or unverified seats honestly.

Native routing

Read shared/references/host-model-execution.md before choosing an external route. If the current host can dispatch the exact selected Grok model with the required effort, isolation, and receipt policy in a native subagent or task thread, use that route. agents/openai.yaml is host UI metadata; it does not dispatch a native model.

Invocation

Set SKILL_DIR to this loaded skill directory in the same shell call:

SKILL_DIR="<absolute path of this skill directory>";
python3 "$SKILL_DIR/scripts/run_grok.py" "<scoped prompt>" \
  --model <approved-model-id> --effort <approved-effort> --disable-fallback --json

Copy the exact model and effort from the selected snapshot. Add its role, tool mode, receipt policy, and limits. Omit an effort flag only for a selected runtime controlled route. Nested calls use these saved options without resolving defaults again. The example does not grant source sharing or tool authority.

Runtime boundaries

• Use the local authenticated grok CLI in print mode. Analysis roles default to enforced read-only plan mode.
• --restrict-tools forces plan mode; --allow-write opts out within the caller's authority. Prompt and file context may be sent to the configured provider.
• Sessions persist under ~/.grok; the native CLI has no persistence opt-out.
• The native modelUsage receipt identifies the serving model. Effort values unsupported by a direct call are clamped and reported; approved routes must satisfy their exact plan.
• No fallback is allowed. A missing CLI is an unavailable seat, never another model's answer.
• Structured output is checked locally after the native schema constraint. A zero exit code does not make malformed output successful.

Load by need

• references/command-reference.md: flags, examples, native mappings, and return codes when composing a non-basic invocation.
• references/runtime-reference.md: authentication, fallback conditions, configuration, and extended envelope fields when configuring a route or interpreting its result.
• references/continuation.md: only when resuming a session or managing a background job.

Result

Read agent_message and the wrapper envelope. Check success, serving-model receipt, effective runner/provider, and any fallback or malformed-output status. A completed process alone does not prove the requested task or model was used. Report touched files when the caller authorized edits.