Module grok_cli 

Grok Build CLI subprocess model provider.

Every inference request uses the documented grok agent stdio ACP transport. The assembled prompt is sent as JSON-RPC on child stdin; it is never placed in argv or a temporary file. Authentication uses the Grok CLI login cache by default. API-key auth is an explicit per-alias opt-in: export XAI_API_KEY into the ZeroClaw process and list that name in env_passthrough. Typed alias api_key is rejected; this provider does not store the key in config. At each spawn the child allowlist resolves process env by name (including XAI_API_KEY when opted in) so the CLI login cache remains the default owner and the key is never snapshotted into the long-lived provider handle. A future typed Config bridge may map the same name at load time; until then the documented process-env + env_passthrough surface is the single operator credential path.

Usage

[providers.models.grok_cli.default]
model = "grok-4.5"
working_directory = "/path/to/agents/default/workspace"
# binary_path = "/home/you/.grok/bin/grok"

[agents.default]
model_provider = "grok_cli.default"
classifier_provider = "xai.default"

Host-side trust boundary

The child is a tool-capable agent outside ZeroClaw’s native tool approval path. The provider therefore:

• requires an explicit absolute working directory;
• clears the inherited environment and forwards only process-runtime entries plus explicit per-alias env_passthrough names;
• defaults to --no-plan, --sandbox strict, --permission-mode dontAsk, and an empty built-in tool set;
• rejects ACP permission requests unless the alias explicitly enables a bypass mode, in which case it selects the request’s allow-once option;
• bounds ACP frames, configurable aggregate stdout, assistant output, and stderr;
• on success, failure, timeout, or cancellation, terminates the child process group (Unix) or Job Object (Windows) and reaps the direct child. Descendants that create a new session/process group can escape group kill on Unix; the public guarantee is process-group / Job Object scope, not every possible detached process on the host;
• never includes child stderr or raw ACP frames (or child-controlled protocol free-text such as stopReason / protocolVersion / string error codes) in public errors or logs.

Operators can deliberately relax the CLI policy through extra_args (for example, --tools=Read,Grep, --permission-mode=acceptEdits, or --sandbox=workspace). Such overrides are explicit per-provider-alias opt-ins. Bypass flags also authorize the headless ACP client to approve interactive permission requests for that alias.

Limitations

• Only the system prompt (if present) and final user message are forwarded.
• The provider is one-shot; ACP sessions are not resumed.
• Native ZeroClaw tool calls are not emitted; ChatRequest.tools is ignored.
• Token usage is not reported (ChatResponse.usage is None).
• Only temperatures 0.7 and 1.0 are accepted because Grok Build has no corresponding sampling flag.
• timeout_secs is clamped to one hour maximum.

Structs

GrokCliBuilder

Typed builder for GrokCliModelProvider.

GrokCliModelProvider

Model provider that invokes Grok Build through ACP.