grok_request_async
Destructive
Initiates an xAI Grok CLI request as a durable background job. Poll with llm_job_status, collect results with llm_job_result.
Instructions
Start an xAI Grok CLI request as a durable background job. Poll with llm_job_status, collect with llm_job_result.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| deny | No | Grok --deny <RULE>: permission deny rules. Each entry → its own --deny instance. | |
| agent | No | Grok --agent <NAME>: agent name or definition file path. | |
| allow | No | Grok --allow <RULE>: permission allow rules. Each entry → its own --allow instance. | |
| check | No | Grok --check: append a self-verification loop to the prompt (headless only). | |
| model | No | Model name or alias (e.g. grok-build, 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; gateway passes the value verbatim. | |
| agents | No | Grok --agents <JSON>: inline subagent definitions (JSON string or name → { description, prompt, … } map). | |
| effort | No | Grok effort level | |
| noPlan | No | Grok --no-plan: disable plan mode. | |
| prompt | No | Prompt text for Grok (mutually exclusive with promptParts) | |
| single | No | Grok --single <PROMPT>: single-turn prompt (in addition to gateway -p). | |
| bestOfN | No | Grok --best-of-n <N>: run the task N ways in parallel and pick the best (headless only). | |
| sandbox | No | Grok --sandbox <PROFILE>: sandbox profile for filesystem and network access. Freeform per `grok --help` (no enum constraint); also settable via GROK_SANDBOX env var. | |
| 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, that worktree is reused. The gateway spawns the child CLI with `cwd: <worktree-path>` — no `-w`/`--worktree` flag is ever emitted to the underlying CLI. On session_delete or TTL eviction the gateway runs `git worktree remove --force`. Successful responses are prefixed with `[gateway] worktree=<absolute-path>\n` so callers can use the path. NOTE: callers should `.gitignore` the `.worktrees/` directory in their repo (the gateway does NOT auto-gitignore — see slice λ spec Q4). | |
| sessionId | No | Provider-native session ID to resume (emits --resume <id>; use resumeLatest for --continue). Note: the gw-* id minted for a brand-new session is not resumable via sessionId; continue with resumeLatest:true. | |
| 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 | MCP server names for approval tracking (Grok manages its own MCP config via `grok mcp`) | |
| 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. Stdio/local callers may pass local paths directly. Remote HTTP/OAuth callers must use relative paths inside a selected registered workspace. Do not call workspace_* tools to fix stdio/local provider path access. | |
| 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 (plain|json|streaming-json). Grok default is plain. | |
| resumeLatest | No | Resume most recent Grok session in cwd (--continue). Note: the gw-* id minted for a brand-new session is not resumable via sessionId; continue with resumeLatest:true. | |
| 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. | |
| approvalPolicy | No | Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy. | |
| compactionMode | No | Grok --compaction-mode: summary (default) | transcript | segments. 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 | |
| approvalStrategy | No | Approval strategy: legacy (default) lets the provider CLI's own flags decide; mcp_managed routes the run through the gateway approval gate (required for approvalPolicy and approval_list). Under mcp_managed the caller's permissionMode/alwaysApprove may be overridden by the gate. | legacy |
| compactionDetail | No | Grok --compaction-detail: segment verbatim detail (none|minimal|balanced|verbose, default verbose). Only affects segments mode. Sets GROK_COMPACTION_DETAIL. | |
| compressResponse | No | Compress the response display text when collected via llm_job_result (native compressor; default: [compression].enabled). | |
| createNewSession | No | Force new session | |
| disableWebSearch | No | Grok --disable-web-search: disable web search and remote retrieval tools. | |
| experimentalMemory | No | Grok --experimental-memory: enable cross-session memory. | |
| systemPromptOverride | No | Grok --system-prompt-override <PROMPT>: replace the agent's system prompt entirely. |