grok

Grok Capability Layer

Operate the installed grok_* tools according to their current schemas. Codex owns scope, workspace state, verification, git, and final judgment.

Required contract

• Use grok_check when CLI discovery, compatibility, login, or model listing is uncertain. Treat cliDiscovered, authenticated, entitled, modelsListed, and callable as separate facts. authenticated and entitled are true, false, or the string "unknown" — never null — so never read an undetermined fact as a negative one; entitled: false means the account listed models but has no quota. modelInvocationTested/callable stay false/null unless you pass probeInvocation: true, which spends real quota on one bounded call; do not enable it routinely.
• Configure a custom executable through trusted MCP environment variable GROK_BIN; never accept a binary path from a task prompt or tool argument.
• Pass an explicit absolute cwd for workspace, session, and export operations. That value grants only this tool call access to the exact canonical directory; it need not already be an advertised MCP root and is not remembered. This does not grant operation approval: alwaysApprove stays opt-in, while review and adversarial-review calls remain read-only plan mode without subagents. They also require an explicit non-empty target. Spell it target or, equivalently, prompt — grok_rescue takes problem or prompt the same way — and pass exactly one of the pair (a string or an array of strings, joined into bullets). Only cwd is required by the schema; a missing, empty, or doubled target is the non-retryable target_required, and one over the limit is target_too_large with details.chars/details.maxChars.
• background defaults to true for grok_run, grok_review, grok_adversarial_review, and grok_rescue, and to false for grok_continue; a background start returns data.background === true and data.job.id. Call status, result, or cancel with that jobId only; job state is private and independent of workspace cwd. background: false blocks the MCP call for up to timeoutMs plus a 10 s grace and then returns foreground_wait_timeout carrying the same job id. An omitted timeoutMs defaults per kind (run/continue 180000, review/rescue 240000, adversarial_review 300000); an explicit value is never clamped, and every envelope echoes effectiveTimeoutMs / effectiveMaxTurns.
• Accept an answer only when data.resultComplete === true; it already accounts for truncation. outputSummary.outputTruncated alone does not disqualify an answer — it usually means tool-call echo overflowed the capture window — while outputSummary.textTruncated means answer text was dropped. The plugin normalises stopReason case- and separator-insensitively (end_turn, EndTurn, cancelled, Cancelled are all understood); never string-match the raw value yourself. Treat cancelled_output and max_turns_reached as partial. Use data.finalText, not previews or raw log tails; grok_result returns the raw stdoutTail/stderrTail only when you pass includeRawTail: true.
• grok_adversarial_review accepts threatModel: the operating scope the review must judge against. Findings outside it are labelled out-of-model and are advisory — they must never block, force NO_GO, or interrupt work in progress.
• grok_finalize({ cwd, jobId }) is the one-call form of the recovery: one turn, no tools, complete answer, anything unverified marked UNVERIFIED. Use it for timeout, max_turns_reached, cancelled_output, and permission_denied_headless instead of rerunning the task. It inherits the read-only mode of the session it resumes.
• Every non-complete result carries a recovery handle: error.details.recovery on a failed foreground call and data.recovery on grok_result, shaped { jobId, grokSessionId, partialTextChars, suggested: { tool: "grok_finalize", args }, fallback: { tool: "grok_continue", args } }. Run that suggestion as given — one turn, no tools, complete answer — or the fallback if you only call grok_continue; neither asks for a shortened answer. Do not rerun the task or raise the budget. The partial answer is never destroyed: error.details.finalTextRef is the job id and grok_result returns the complete captured finalText whatever resultComplete says.
• When outputSummary.stopReasonRecognised === false the plugin accepted an unfamiliar stop reason and said so in warnings. The answer is still returned; reject it only if your task needs strict vocabulary matching.
• Continue only a known sessionId or explicitly request the latest session. Continuing a session that this plugin created for a review, adversarial review, or rescue inherits enforced read-only plan mode, and alwaysApprove on such a session is refused with the non-retryable readonly_session_escalation; when a named sessionId is unknown to the plugin the call proceeds with a warning saying the original mode could not be verified.
• continueLatest: true names no session, so the plugin infers the target from the newest session it started in this cwd, and that inference may only restrict, never certify. If the inferred session was read-only, alwaysApprove is refused with readonly_session_escalation and error.details.inferredFromLatestJob === true (non-retryable — do not retry it), and a plain continuation inherits plan mode. Every continueLatest call also warns that the resumed session could not be verified, because the CLI may resume a session this plugin never created. The remedy in both cases is one parameter: pass the explicit sessionId of the session you mean, or start a new one with grok_run. Export returns Markdown; the plugin does not write a caller-selected output file.