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

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.

1. 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.

1. Omit model unless the caller explicitly asked for a specific variant; the

gateway resolves the configured Grok default.

1. 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.

1. 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.

1. mcpServers is approval tracking only; Grok owns its MCP configuration.
2. 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.

1. The full subcommand surface (including agent/*, update, worktree, dashboard, login, etc.) is exposed via provider_subcommands_list, provider_subcommand_contract, and provider_subcommand_drift for inspection and drift monitoring. dashboard (grok 0.2.60 (474c2bbfc)+) is catalogued as read-only/inspect.
2. 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

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 (e.g. dashboard).

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.

1. Add a conformance fixture proving the new accept/reject behaviour

(mirror the existing grok-* fixtures).

1. If a source URL or watch category changed, update upstreamMetadata and

mirror it into docs/upstream/provider-sources.dag.toml.

1. Verify: npm run build && npm run upstream:contracts and npm test.

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

• Tested against grok 0.2.60 (474c2bbfc) (ACP targetVersion).
• --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.
• dashboard subcommand is tracked (read_only risk, inspect tier, tracked_only exposure) in the subcommand catalog and --probe-installed drift detection. It opens the central Agent Dashboard view (grok 0.2.60 (474c2bbfc)+). Example:

  provider_subcommand_contract({provider:"grok", commandPath:["dashboard"]})

Use provider_subcommands_list / provider_subcommand_drift for discovery and drift checks.