---
name: provider-grok
description: Track and maintain the upstream xAI Grok CLI contract. Use when xAI ships a Grok CLI release, when a `grok` flag/permission-mode/sandbox/output-format/resume behaviour changes, or when an upstream scan flags drift. Process guidance only — `src/upstream-contracts.ts` is the mechanical source of truth.
metadata:
  author: verivus-oss
  version: "1.0"
---

# Provider: xAI Grok CLI

Process guidance for keeping the gateway's Grok (`grok`) integration aligned
with the upstream CLI. This skill does **not** define argv/env behaviour — the
single mechanical source of truth is `UPSTREAM_CLI_CONTRACTS.grok` in
`src/upstream-contracts.ts`, enforced by `validateUpstreamCliArgs` /
`validateUpstreamCliEnv`. Never re-encode flags, permission modes, sandbox, or
resume rules here or in TOML.

## Identity

| Field | Value |
|-------|-------|
| CliType | `grok` |
| Executable | `grok` |
| Distribution | vendor (no pinned npm/PyPI package recorded) |
| Changelog | https://docs.x.ai/developers/release-notes.md |
| Install docs | https://docs.x.ai/build/overview |
| Watch categories | `flags`, `permission-modes`, `session-resume`, `sandbox`, `output-formats` |

These values mirror `UPSTREAM_CLI_CONTRACTS.grok.upstreamMetadata` and
`docs/upstream/provider-sources.dag.toml` (`[providers.grok]`). The TypeScript
metadata is authoritative; the TOML is scanner input only.

## When to use

- An xAI Grok CLI release lands and you need to check for contract drift.
- A `grok` request fails the upstream contract check before spawn.
- `npm run upstream:scan -- --live` reports a change on the x.ai changelog.

## How LLM agents should use Grok through the gateway

1. Discover the live gateway/provider surface before relying on Grok-specific
   controls or local skill tools:
   ```
   provider_tool_capabilities({cli:"grok"})
   ```
   For a cached read-only resource, use `provider-tools://grok`.
2. Use `grok_request` for normal turns and `grok_request_async` for long-running
   review, analysis, or diversity checks. Sync calls may auto-defer; poll
   `llm_job_status` and fetch with `llm_job_result` when that happens.
3. Omit `model` unless the caller explicitly asked for a specific variant; the
   gateway resolves the configured Grok default.
4. Do not copy Claude tool names such as `Read`, `Grep`, `Glob`, or `Bash` into
   Grok `allowedTools`; Grok has its own provider-native tool names. This was
   the root cause of prior Grok reviewer startup failures.
5. Grok supports gateway `allowedTools` / `disallowedTools`, `allow` / `deny`,
   `alwaysApprove`, `permissionMode`, `approvalStrategy`, `approvalPolicy`,
   agent/subagent controls, web-search toggles, memory/planning toggles, prompt
   controls, output format, workspace/worktree/native-worktree controls,
   session controls, and compaction/effort controls as reported by
   `provider_tool_capabilities`.
6. `mcpServers` is approval tracking only; Grok owns its MCP configuration.
7. Local Grok skills are discoverable from `~/.grok/skills` and bundled skill
   directories. `provider_tool_capabilities` reports discovered provider-native
   tools such as Imagine `image_gen`, `image_edit`, `image_to_video`, and
   `reference_to_video` when those skills are present. The gateway still
   executes Grok through `grok_request`; it does not directly call those native
   tools.
8. Grok continuity is real via `sessionId`, `resumeLatest`, `createNewSession`,
   `--resume`, and `--continue`. Auth must already be set up with `grok login`
   or `GROK_CODE_XAI_API_KEY`.

## Scan for upstream change

```bash
npm run upstream:scan -- --provider grok
npm run upstream:scan -- --live --provider grok --fail-on-critical
npm run upstream:scan -- --live --provider grok --write-snapshot --write-report
```

**Strongly recommended for Grok (vendor binary):** include `--probe-installed`.
The tracked web page is high-level product notes and rarely contains detailed
CLI flag/subcommand drift. The installed `--help` probe + help-surface
snapshot diff is the reliable detector for new flags (`--worktree`,
`--todo-gate`, `--agent`, etc.), arity changes, and new subcommands.

A failed fetch is advisory (exit 0) unless `--fail-on-critical` is passed.

## Update procedure when the upstream CLI changes

1. **Edit the contract** in `src/upstream-contracts.ts` (`UPSTREAM_CLI_CONTRACTS.grok`):
   flag arities, the `--permission-mode` / `--effort` / `--output-format` enums,
   and freeform passthrough flags (e.g. `--sandbox`) live here.
2. **Add a conformance fixture** proving the new accept/reject behaviour
   (mirror the existing `grok-*` fixtures).
3. **If a source URL or watch category changed**, update `upstreamMetadata` and
   mirror it into `docs/upstream/provider-sources.dag.toml`.
4. **Verify**: `npm run build && npm run upstream:contracts` and `npm test`.

## Grok-specific notes (see the contract for exact rules)

- `--sandbox` is freeform passthrough (no `values` enum) per `grok --help`; `--permission-mode` / `--effort` / `--output-format` are closed enums.
- `--allow` / `--deny` / `--rules` repeat once per rule.
- Continuity is real via `--resume` / `--continue`; auth must be set up first (`grok login` OAuth or `GROK_CODE_XAI_API_KEY`).
- No cache statistics are surfaced by the Grok CLI.
