grok_request
Destructive
Run xAI Grok CLI requests synchronously, deferring to pollable async jobs past the deadline. Accepts plain or structured prompts and CLI options for model, rules, permissions, sandbox, and sessions.
Instructions
Run an xAI Grok CLI request synchronously (when async jobs are enabled, auto-defers to a pollable job past the sync deadline; otherwise runs to completion). Requires exactly one of prompt or promptParts.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| deny | No | Grok --deny <RULE>: permission deny rules. Each entry is emitted as its own --deny instance (per `grok --help`: "Repeat to add multiple rules"). | |
| agent | No | Grok --agent <NAME>: agent name or definition file path. | |
| allow | No | Grok --allow <RULE>: permission allow rules. Each entry is emitted as its own --allow instance (per `grok --help`: "Repeat to add multiple rules"). | |
| check | No | Grok --check: append a self-verification loop to the prompt (headless only). Not advertised by grok 1.0.4+; passed through for older installs. | |
| model | No | Model name or alias (e.g. grok-4.5, latest) | |
| oauth | No | Grok --oauth: use OAuth during authentication. | |
| rules | No | Grok --rules <RULES>: extra rules to append to the system prompt. Supports `@file` prefix per `grok --help` to load from a file; gateway passes the value verbatim and lets Grok parse the prefix. | |
| agents | No | Grok --agents <JSON>: inline subagent definitions (JSON string or name → { description, prompt, … } map). | |
| effort | No | Grok effort level. Known values: low, medium, high, xhigh, max. Your installed grok decides what it accepts; these are not enforced. | |
| noPlan | No | Grok --no-plan: disable plan mode. | |
| prompt | No | Prompt text for Grok (mutually exclusive with promptParts) | |
| bestOfN | No | Grok --best-of-n <N>: run the task N ways in parallel and pick the best (headless only). Not advertised by grok 1.0.4+; passed through for older installs. | |
| sandbox | No | Grok --sandbox <PROFILE>: sandbox profile for filesystem and network access. Freeform per `grok --help` (no enum constraint on Grok 0.1.210); also settable via GROK_SANDBOX env var. Caller responsibility to pass a valid profile name. | |
| maxTurns | No | Grok `--max-turns N`: cap on agent-loop iterations for cost / latency control (Phase 4 slice δ). Bounded to safe integers ≤ 10000. | |
| noMemory | No | Grok --no-memory: disable cross-session memory. | |
| todoGate | No | Grok --todo-gate: enable runtime turn-end TodoGate for this session (session-scoped, not persisted). | |
| verbatim | No | Grok --verbatim: send the prompt exactly as given. Also skips gateway optimizePrompt when true. | |
| worktree | No | Slice λ: run this request inside a dedicated git worktree owned by the gateway. `true` creates a fresh worktree at `<repoRoot>/.worktrees/<uuid>` branched from HEAD. `{ name?, ref? }` lets the caller supply a sanitized name and/or a git ref (default: HEAD). When the request carries a sessionId and the session already has a worktree, reuse requires same-host ownership metadata and a matching live Git registration. Named path collisions never reuse manager state. Gateway-managed worktrees work with file-backed and PostgreSQL session managers. Shared PostgreSQL rows do not transfer filesystem ownership; reuse and cleanup remain limited to the owning host. The Grok, Devin, and Mistral adapters require an explicit provider-native sessionId; fresh, createNewSession, and resumeLatest-only worktree requests fail closed because they cannot durably reselect the worktree. The request must select a registered workspace explicitly, through caller-owned session metadata, or through the configured default. Worktrees never fall back to the gateway process cwd and cannot be combined with local workingDir, addDir, or includeDirs paths. The gateway spawns the child CLI with `cwd: <worktree-path>`; no `-w`/`--worktree` flag is ever emitted to the underlying CLI. On worktree materialization, the gateway suppresses repository, system, and global Git hooks and configured clean, smudge, and process checkout filters, sparse checkout, and lazy object fetching. Filter-dependent content such as Git LFS remains in its repository representation instead of executing host commands. On session_delete, session_clear_all or file-backed TTL eviction, both managers hide a durably owned worktree session while cleanup runs. Failed Git removal retains a cleanup-pending tombstone, blocks reuse, and is retried when a manager is registered on the owning host; the record is finalized only once Git no longer registers the worktree, which is read back rather than inferred from the recorded path being absent. A worktree that moved, or whose owner marker cannot be read, is not a removal. Deletion processed by another host removes no worktree and leaves the owning host's record intact. The database-side cleanup_expired_sessions function stages the same tombstone instead of deleting a worktree-bearing session; it invokes no gateway observer and so attempts no removal itself. A tombstone is not bounded by retention. Successful responses are prefixed with `[gateway] worktree=<absolute-path>\n` so callers can use the path. For Claude approvalStrategy:mcp_managed, requesting or reusing a worktree requires approval and LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1. Other adapters reject mcp_managed before launch. NOTE: callers should `.gitignore` the `.worktrees/` directory in their repo (the gateway does NOT auto-gitignore; see slice λ spec Q4). | |
| sessionId | No | On transport=cli, provider-native session ID to resume (emits --resume <id>; use resumeLatest for --continue); gateway gw-* tracking ids are not CLI session ids. On transport=acp, gateway-owned ACP session ID returned by an earlier ACP call; provider-native and CLI session ids are rejected. | |
| transport | No | Transport: 'cli' (default) runs the Grok CLI. 'acp' routes through `grok agent stdio` only when [acp].enabled plus [acp.providers.grok].enabled and runtime_enabled are true (fails closed otherwise). ACP accepts prompt, model, a gateway ACP sessionId, and a registered workspace alias; Grok CLI-only controls are rejected. | cli |
| workspace | No | Registered workspace alias for remote HTTP/OAuth provider calls. Do not use this field, workspace_list, or workspace_register_existing_repo as a fallback for stdio/local provider path access; pass workingDir/addDir/includeDirs directly instead. | |
| jsonSchema | No | Grok 0.2.73 --json-schema: constrain output to a JSON Schema (string literal or object; implies json output). Set outputFormat:json so the gateway treats the reply as structured output (skips response optimization and warning injection); the default output format is not json, so pass it explicitly. | |
| mcpServers | No | This provider does not receive gateway-managed MCP configuration. mcpServers has no effect with legacy, and mcp_managed is rejected before launch because ambient MCP configuration cannot be isolated. | |
| promptFile | No | Grok --prompt-file <PATH>: single-turn prompt loaded from a file. | |
| promptJson | No | Grok --prompt-json <JSON>: single-turn prompt JSON blocks (string or serializable value). | |
| workingDir | No | Grok --cwd <DIR>: working directory for this invocation. Lets headless callers run Grok against a directory other than the gateway process's cwd. | |
| forkSession | No | Grok 0.2.73 --fork-session: when resuming (--resume/--continue), fork into a new session ID instead of reusing the original. | |
| noAltScreen | No | Grok --no-alt-screen: run inline without alt screen. | |
| noSubagents | No | Grok --no-subagents: disable subagent spawning. | |
| promptParts | No | Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking. | |
| restoreCode | No | Grok --restore-code: check out the original session commit when resuming. | |
| worktreeRef | No | Grok 0.2.73 --worktree-ref <REF>: git ref (branch/tag/commit) to base the native worktree on. Requires nativeWorktree. | |
| allowedTools | No | Allowed built-in tools (passed as --tools comma list) | |
| forceRefresh | No | Bypass dedup and force a fresh CLI run even if a recent identical request exists | |
| leaderSocket | No | Grok 0.2.32+ --leader-socket <PATH>: custom leader socket path (default ~/.grok/leader.sock). Targets an isolated leader process, e.g. a local/branch Grok build; name it ~/.grok/leader-*.sock to keep `grok leader list/kill` discovery working. | |
| outputFormat | No | Output format for headless mode. Grok default is plain. The gateway parses json and streaming-json; other formats are passed through as raw output. | |
| resumeLatest | No | Resume the most recent Grok session in cwd (--continue) on transport=cli. true is rejected on transport=acp. | |
| alwaysApprove | No | Auto-approve all tool executions (--always-approve). | |
| correlationId | No | Request trace ID (auto if omitted) | |
| idleTimeoutMs | No | Idle timeout in ms (min 30s, max 1h). Omit = gateway default of 600000ms (10 min) with no output before the process is killed. | |
| providerFlags | No | Flags passed to the provider binary verbatim, keyed exactly as the binary spells them (e.g. {"--best-of-n": "3", "--verbatim": true, "--rules": ["a", "b"]}). Use this for any flag your installed CLI accepts that this schema does not name: the binary decides what it supports, not the gateway. true emits the flag alone; a list REPEATS the flag once per item (pass a joined string if your CLI wants a comma-separated value). Values may not start with '-', and a flag the gateway is already emitting for this request is refused rather than duplicated. LOCAL stdio callers only: remote HTTP/OAuth callers are refused every flag here and should use this tool's declared parameters, which carry their own host-path and approval gates. | |
| approvalPolicy | No | On transport=cli, approvalPolicy has no effect because mcp_managed is unavailable. On transport=acp, supplying approvalPolicy is rejected because ACP has its own permission bridge. | |
| compactionMode | No | Grok --compaction-mode: summary (default; no pointer) | transcript (points at the raw transcript) | segments (persists per-segment markdown to grep). Sets GROK_COMPACTION_MODE. | |
| nativeWorktree | No | Grok -w/--worktree: native CLI worktree flag (`true` → bare `--worktree`, string → named). NOT gateway slice λ `worktree`. | |
| optimizePrompt | No | Optimize prompt before execution | |
| permissionMode | No | Grok permission mode: default|acceptEdits|auto|dontAsk|bypassPermissions|plan. | |
| disallowedTools | No | Disallowed built-in tools (passed as --disallowed-tools comma list) | |
| reasoningEffort | No | Reasoning effort for reasoning models. Known values: low, medium, high, xhigh, max. Not enforced; the installed binary decides. | |
| approvalStrategy | No | Approval strategy. legacy is supported. mcp_managed is rejected before Grok launches because the CLI adapter cannot isolate ambient MCP configuration; transport=acp has its own permission bridge and also rejects mcp_managed. | legacy |
| compactionDetail | No | Grok --compaction-detail: verbatim segment detail (none|minimal|balanced|verbose, default verbose). Only affects `--compaction-mode segments`. Sets GROK_COMPACTION_DETAIL. | |
| compressResponse | No | Compress the response display text via the native compressor (default: [compression].enabled in config.toml, off unless opted in). Skipped for structured output. | |
| createNewSession | No | Force a new session on transport=cli. true is rejected on transport=acp. | |
| disableWebSearch | No | Grok --disable-web-search: disable web search and remote retrieval tools. | |
| optimizeResponse | No | Optimize response output | |
| experimentalMemory | No | Grok --experimental-memory: enable cross-session memory. | |
| systemPromptOverride | No | Grok --system-prompt-override <PROMPT>: replace the agent's system prompt entirely. Distinct from Claude's --system-prompt / --append-system-prompt (Grok has only one override flag, not a pair). |