llm-cli-gateway 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to the llm-cli-gateway project.
 
 ## Unreleased
 
+## [2.1.0] - 2026-06-07: Grok Build 0.2.32, probe drift acknowledgement, docs currency
+
+### Added
+
+- Grok Build 0.2.32 support: new `leaderSocket` parameter on `grok_request` /
+  `grok_request_async` maps to the new `--leader-socket <PATH>` flag (isolated
+  leader process for local/branch Grok builds; default `~/.grok/leader.sock`).
+  Contract declares the flag with arity-one validation plus conformance
+  fixtures. The release's other changes (plugin slash commands in all
+  conversations, ordered rapid prompt submissions, faster grep on large
+  repos) are CLI-internal and inherited automatically. Probe at 0.2.32:
+  missingFlags/warnings clean.
+
+### Fixed
+
+- Upstream-contract probe drift after the 2026-06 provider CLI upgrades
+  (gemini 0.45.2, grok 0.2.22, vibe 2.14.0): `CliFlagContract.hiddenFromHelp`
+  marks real flags hidden from a binary's `--help` (Claude `--max-turns`), and
+  `CliContract.acknowledgedUpstreamFlags` acknowledges upstream-only flags the
+  gateway never emits (29 Claude, 18 Gemini). Both are probe-only — the argv
+  allowlist is unchanged — with stale-marker warnings in both directions and a
+  new `acknowledgedExtraFlags` probe field. New pure `computeFlagDrift` plus
+  7 unit tests.
+- MCP server version now reports the real package version (was hardcoded
+  `1.0.0`).
+
+### Documentation
+
+- Cross-LLM documentation currency review (Codex + Gemini + Grok + Mistral):
+  README tool reference gains `codex_fork_session`, `llm_request_result`,
+  `llm_process_health`, `upstream_contracts`, and `list_available_models`;
+  `claude_request` parameter list completed (`outputFormat` default is
+  `stream-json`); Codex `fullAuto` documented as deprecated in favour of
+  `sandboxMode`; Gemini approval modes include `plan`; grok/mistral upgrade
+  strategies documented; stale test counts, provider lists, and
+  `BEST_PRACTICES.md` path pointers corrected across README, AGENTS.md,
+  .cursorrules, CLAUDE.md, docs/guides, docs/personal-mcp (Mistral/Vibe row
+  added to the provider support matrix), and docs/upstream.
+
 ## [2.0.0] - 2026-06-04: node:sqlite migration — native module out of the prod graph
 
 Major release. Persistence moves from the native `better-sqlite3` binding to

package/README.md

@@ -205,7 +205,7 @@ Opt-in flags (all default off) live under `[cache_awareness]` in `~/.llm-cli-gat
 
 ### Security & Quality
 
-- **Comprehensive Testing**: 900+ tests covering unit, integration, and regression scenarios with real CLI execution
+- **Comprehensive Testing**: 1,000+ tests covering unit, integration, and regression scenarios with real CLI execution
 - **Input Validation**: Zod schemas prevent injection attacks
 - **No Secret Leakage**: Generic session descriptions only (file permissions 0o600)
 - **No ReDoS**: Bounded regex patterns prevent catastrophic backtracking
@@ -344,6 +344,7 @@ The personal-appliance surface exposes simplified validation tools for non-devel
 - `consensus_check`: check whether providers agree with a claim.
 - `ask_model`: ask one provider through the simplified surface.
 - `synthesize_validation`: run an explicit judge model after provider results have been collected.
+- `list_available_models`: list the models each provider CLI exposes through the simplified surface.
 - `job_status` and `job_result`: poll and collect validation job outputs.
 
 The validation report preserves per-provider disagreement. Optional judge synthesis is explicit about which provider produced the judge job.
@@ -356,15 +357,29 @@ Execute a Claude Code request with optional session management.
 
 **Parameters:**
 
-- `prompt` (string, required): The prompt to send (1-100,000 chars)
+- `prompt` (string, optional*): The prompt to send (1-100,000 chars). *Exactly one of `prompt` or `promptParts` is required (mutually exclusive)
 - `model` (string, optional): Model name or alias (use `list_models` for available values; supports `latest`)
-- `outputFormat` (string, optional): Output format ("text" or "json"), default: "text"
+- `outputFormat` (string, optional): Output format (`text|json|stream-json`), default: `stream-json` — the gateway parses NDJSON usage events for token/cost observability; override to `text` only when you want unparsed stdout
 - `sessionId` (string, optional): Specific session ID to use
 - `continueSession` (boolean, optional): Continue the active session
 - `createNewSession` (boolean, optional): Always create a new session
+- `forkSession` (boolean, optional): Fork the resumed session instead of appending to it
 - `allowedTools` (string[], optional): Restrict Claude tools to this allow-list
 - `disallowedTools` (string[], optional): Explicitly deny listed Claude tools
-- `dangerouslySkipPermissions` (boolean, optional): Request CLI-side permission bypass (legacy mode only)
+- `permissionMode` (string, optional): Claude permission mode (`default|acceptEdits|plan|auto|dontAsk|bypassPermissions`); preferred over `dangerouslySkipPermissions`
+- `dangerouslySkipPermissions` (boolean, optional): Deprecated — maps to `permissionMode: "bypassPermissions"`; `permissionMode` wins when both are set
+- `agent` (string, optional): Named sub-agent to run as
+- `agents` (string, optional): Inline agent definitions JSON
+- `systemPrompt` / `appendSystemPrompt` (string, optional): Replace or extend the system prompt
+- `maxBudgetUsd` (number, optional): Budget cap in USD for the request
+- `maxTurns` (integer, optional): Agent-loop turn cap
+- `effort` (string, optional): Reasoning effort (`low|medium|high|xhigh|max`)
+- `fallbackModel` (string, optional): Auto-fallback model when the default is overloaded
+- `jsonSchema` (string, optional): JSON Schema literal constraining structured output
+- `addDir` (string[], optional): Additional workspace directories
+- `noSessionPersistence` (boolean, optional): Ephemeral session (not persisted to disk)
+- `settingSources` / `settings` / `tools` (optional): Setting sources to load, settings JSON path/literal, built-in tool restriction
+- `excludeDynamicSystemPromptSections` (boolean, optional): Trim dynamic system prompt sections
 - `approvalStrategy` (string, optional): `"legacy"` (default) or `"mcp_managed"`
 - `approvalPolicy` (string, optional): `"strict"`, `"balanced"`, or `"permissive"`
 - `mcpServers` (string[], optional): Claude MCP servers to expose (default: `["sqry","exa","ref_tools"]`; `"trstr"` available as opt-in)
@@ -372,6 +387,10 @@ Execute a Claude Code request with optional session management.
 - `optimizePrompt` (boolean, optional): Optimize prompt for token efficiency (44% reduction), default: false
 - `optimizeResponse` (boolean, optional): Optimize response for token efficiency (37% reduction), default: false
 - `correlationId` (string, optional): Request trace ID (auto-generated if omitted)
+- `idleTimeoutMs` (integer, optional): Kill a stuck process after output inactivity; 30,000 to 3,600,000 ms
+- `worktree` (boolean|object, optional): Run inside a gateway-owned git worktree (slice λ)
+- `promptParts` (object, optional): Cache-aware structured prompt `{ system?, tools?, context?, task }`; mutually exclusive with `prompt`
+- `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
 
 **Response extras:**
 
@@ -396,19 +415,33 @@ Execute a Codex request with optional session tracking.
 
 **Parameters:**
 
-- `prompt` (string, required): The prompt to send (1-100,000 chars)
-- `model` (string, optional): Model name or alias (use `list_models` for available values; supports `latest`, recommended: `gpt-5.4`)
-- `fullAuto` (boolean, optional): Enable full-auto mode, default: false
+- `prompt` (string, optional*): The prompt to send (1-100,000 chars). *Exactly one of `prompt` or `promptParts` is required (mutually exclusive)
+- `model` (string, optional): Model name or alias (use `list_models` for available values; supports `latest`, recommended: `gpt-5.5`)
+- `fullAuto` (boolean, optional): Deprecated — expands to `--sandbox workspace-write` only (current Codex no longer accepts approval-policy flags); prefer `sandboxMode`
+- `sandboxMode` (string, optional): Codex sandbox (`read-only|workspace-write|danger-full-access`)
 - `dangerouslyBypassApprovalsAndSandbox` (boolean, optional): Request Codex bypass flags
 - `approvalStrategy` (string, optional): `"legacy"` (default) or `"mcp_managed"`
 - `approvalPolicy` (string, optional): `"strict"`, `"balanced"`, or `"permissive"`
 - `mcpServers` (string[], optional): MCP servers expected for Codex execution context
 - `sessionId` (string, optional): Session identifier for tracking
+- `resumeLatest` (boolean, optional): Resume the most recent Codex session in the current cwd (`codex exec resume --last`); ignored if `sessionId` is set
 - `createNewSession` (boolean, optional): Always create a new session
+- `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
+- `outputFormat` (string, optional): `text` (default) or `json` (`--json` JSONL events for token usage extraction)
+- `outputSchema` (string|object, optional): Codex `--output-schema` — path or inline JSON Schema
+- `workingDir` (string, optional): Working root for this session (`-C`/`--cd`; new sessions only)
+- `addDir` (string[], optional): Additional writable workspace directories (one `--add-dir` per entry; new sessions only)
+- `ephemeral` (boolean, optional): Codex `--ephemeral` (no session persistence)
+- `images` (string[], optional): Image attachments (one `-i <path>` per entry)
+- `profile` (string, optional): Codex `--profile <name>` (new sessions only; ignored with a logged warning on resume)
+- `configOverrides` (object, optional): Codex `-c key=value` overrides
+- `ignoreRules` / `ignoreUserConfig` (boolean, optional): Codex `--ignore-rules` / `--ignore-user-config`
+- `worktree` (boolean|object, optional): Run inside a gateway-owned git worktree (slice λ)
+- `promptParts` (object, optional): Cache-aware structured prompt `{ system?, tools?, context?, task }`; mutually exclusive with `prompt`
 - `optimizePrompt` (boolean, optional): Optimize prompt for token efficiency, default: false
 - `optimizeResponse` (boolean, optional): Optimize response for token efficiency, default: false
 - `correlationId` (string, optional): Request trace ID (auto-generated if omitted)
-- `idleTimeoutMs` (number, optional): Kill a stuck Codex process after output inactivity; 30,000 to 3,600,000 ms
+- `idleTimeoutMs` (integer, optional): Kill a stuck Codex process after output inactivity; 30,000 to 3,600,000 ms
 
 **Response extras:**
 
@@ -420,32 +453,56 @@ Execute a Codex request with optional session tracking.
 ```json
 {
   "prompt": "Create a REST API endpoint",
-  "model": "gpt-5.4",
-  "fullAuto": true,
+  "model": "gpt-5.5",
+  "sandboxMode": "workspace-write",
   "optimizePrompt": true
 }
 ```
 
+##### `codex_fork_session`
+
+Fork an existing Codex session into a new branch (`codex fork <SESSION_ID|--last> <prompt>`), preserving the original session's history while the fork diverges.
+
+**Parameters:**
+
+- `prompt` (string, required): Prompt text for the forked session (1-100,000 chars)
+- `sessionId` (string, optional): Codex session UUID to fork from (mutually exclusive with `forkLast`)
+- `forkLast` (boolean, optional): Fork the most recent Codex session instead of naming one
+- `model` (string, optional): Model name or alias (e.g. `gpt-5.5`, `latest`)
+- `sandboxMode` (string, optional): Codex sandbox (`read-only|workspace-write|danger-full-access`)
+- `correlationId` (string, optional): Request trace ID (auto-generated if omitted)
+- `idleTimeoutMs` (number, optional): Idle timeout in ms (30s-1h, omit for CLI default)
+
 ##### `gemini_request`
 
 Execute a Gemini CLI request with session support.
 
 **Parameters:**
 
-- `prompt` (string, required): The prompt to send (1-100,000 chars)
+- `prompt` (string, optional*): The prompt to send (1-100,000 chars). *Exactly one of `prompt` or `promptParts` is required (mutually exclusive)
 - `model` (string, optional): Model name or alias (use `list_models` for available values; supports `latest`, `pro`, `flash`)
 - `sessionId` (string, optional): Session ID to resume
 - `resumeLatest` (boolean, optional): Resume the latest session automatically
 - `createNewSession` (boolean, optional): Always create a new session
-- `approvalMode` (string, optional): Gemini approval mode (`default|auto_edit|yolo`) in legacy mode
+- `approvalMode` (string, optional): Gemini approval mode (`default|auto_edit|yolo|plan`) in legacy mode
 - `approvalStrategy` (string, optional): `"legacy"` (default) or `"mcp_managed"`
 - `approvalPolicy` (string, optional): `"strict"`, `"balanced"`, or `"permissive"`
 - `mcpServers` (string[], optional): Allowed Gemini MCP server names
 - `allowedTools` (string[], optional): Restrict Gemini tools to this allow-list
 - `includeDirs` (string[], optional): Additional workspace directories for Gemini
+- `outputFormat` (string, optional): `text` (default), `json` (`-o json`), or `stream-json` (`-o stream-json`, NDJSON with usage extraction)
+- `sandbox` (boolean, optional): Run Gemini in sandbox mode (`-s`)
+- `policyFiles` / `adminPolicyFiles` (string[], optional): Policy / admin-policy file paths (one `--policy`/`--admin-policy` per file; paths must exist)
+- `attachments` (string[], optional): Absolute file paths prepended as `@<path>` tokens to the prompt
+- `skipTrust` (boolean, optional): Emit `--skip-trust` to trust the workspace for this session (required for headless runs in fresh workspaces)
+- `yolo` (boolean, optional): Auto-approve all; equivalent to `approvalMode: "yolo"`. Emits `--yolo` only when `--approval-mode yolo` is not already being emitted (never both)
+- `worktree` (boolean|object, optional): Run inside a gateway-owned git worktree (slice λ)
+- `promptParts` (object, optional): Cache-aware structured prompt `{ system?, tools?, context?, task }`; mutually exclusive with `prompt`
 - `optimizePrompt` (boolean, optional): Optimize prompt for token efficiency, default: false
 - `optimizeResponse` (boolean, optional): Optimize response for token efficiency, default: false
 - `correlationId` (string, optional): Request trace ID (auto-generated if omitted)
+- `idleTimeoutMs` (integer, optional): Kill a stuck process after output inactivity; 30,000 to 3,600,000 ms
+- `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
 
 **Response extras:**
 
@@ -469,7 +526,7 @@ Execute a Grok CLI (xAI) request with session support.
 
 **Parameters:**
 
-- `prompt` (string, required): The prompt to send (1-100,000 chars)
+- `prompt` (string, optional*): The prompt to send (1-100,000 chars). *Exactly one of `prompt` or `promptParts` is required (mutually exclusive)
 - `model` (string, optional): Model name or alias (e.g. `grok-build`, `latest`)
 - `outputFormat` (string, optional): `"plain"` (default), `"json"`, or `"streaming-json"`
 - `sessionId` (string, optional): Session ID to resume (`--resume <id>`)
@@ -484,9 +541,35 @@ Execute a Grok CLI (xAI) request with session support.
 - `mcpServers` (string[], optional): MCP server names tracked for approvals (Grok manages its own MCP config via `grok mcp`)
 - `allowedTools` (string[], optional): Allowed built-in tools (passed as `--tools` comma list)
 - `disallowedTools` (string[], optional): Disallowed built-in tools (passed as `--disallowed-tools` comma list)
+- `maxTurns` (integer, optional): Agent-loop iteration cap (`--max-turns`)
+- `workingDir` (string, optional): Working directory for this invocation (`--cwd`)
+- `sandbox` (string, optional): Sandbox profile for filesystem/network access (`--sandbox`, freeform; also via `GROK_SANDBOX`)
+- `rules` (string, optional): Extra rules appended to the system prompt (`--rules`; supports `@file` prefix)
+- `systemPromptOverride` (string, optional): Replace the agent's system prompt entirely
+- `allow` / `deny` (string[], optional): Permission allow/deny rules (one `--allow`/`--deny` per entry)
+- `compactionMode` (string, optional): `summary` (default) `|transcript|segments`
+- `compactionDetail` (string, optional): `none|minimal|balanced|verbose` (segments mode only)
+- `agent` (string, optional): Agent name or definition file path
+- `agents` (string|object, optional): Inline subagent definitions JSON
+- `bestOfN` (integer, optional): Run the task N ways in parallel and pick the best (headless only)
+- `check` (boolean, optional): Append a self-verification loop (headless only)
+- `disableWebSearch` (boolean, optional): Disable web search and remote retrieval tools
+- `todoGate` (boolean, optional): Enable runtime turn-end TodoGate (session-scoped)
+- `verbatim` (boolean, optional): Send the prompt exactly as given (also skips gateway prompt optimisation)
+- `promptFile` / `promptJson` / `single` (optional): Single-turn prompt from a file / JSON blocks / literal
+- `experimentalMemory` / `noMemory` (boolean, optional): Enable/disable cross-session memory
+- `noAltScreen` / `noPlan` / `noSubagents` (boolean, optional): Disable alt screen / plan mode / subagent spawning
+- `oauth` (boolean, optional): Use OAuth during authentication
+- `restoreCode` (boolean, optional): Check out the original session commit when resuming
+- `leaderSocket` (string, optional): Custom leader socket path (`--leader-socket`, Grok 0.2.32+; default `~/.grok/leader.sock`) — targets an isolated leader process, e.g. a local/branch Grok build
+- `nativeWorktree` (boolean|string, optional): Grok's own `--worktree` flag (`true` → bare, string → named); distinct from the gateway `worktree` option
+- `worktree` (boolean|object, optional): Run inside a gateway-owned git worktree (slice λ)
+- `promptParts` (object, optional): Cache-aware structured prompt `{ system?, tools?, context?, task }`; mutually exclusive with `prompt`
 - `optimizePrompt` (boolean, optional): Optimize prompt for token efficiency, default: false
 - `optimizeResponse` (boolean, optional): Optimize response for token efficiency, default: false
 - `correlationId` (string, optional): Request trace ID (auto-generated if omitted)
+- `idleTimeoutMs` (integer, optional): Kill a stuck process after output inactivity; 30,000 to 3,600,000 ms
+- `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
 
 **Example:**
 
@@ -740,6 +823,21 @@ Run a Mistral Vibe agentic coding request. Like `grok_request` in shape, but wit
 - `disallowedTools` (string[], optional): Accepted for parity with the other providers; ignored at the CLI boundary with a logged warning.
 - `outputFormat` (string, optional): Vibe 2.x values are `"text"`, `"json"`, or `"streaming"`; legacy aliases `"plain"` and `"stream-json"` are accepted and normalized before spawn.
 - `sessionId` / `resumeLatest` / `createNewSession`: standard session controls. Current Vibe defaults session logging to enabled; if an older config has `[session_logging] enabled = false`, `doctor --json` surfaces an actionable next-action.
+- `trust` (boolean, optional): Emit `--trust` so Vibe trusts the cwd for this invocation only (not persisted; skips the interactive trust prompt)
+- `maxTurns` (integer, optional): Agent-loop iteration cap (`--max-turns`, programmatic mode only)
+- `maxPrice` (number, optional): Interrupt when cumulative cost crosses this USD cap (`--max-price`, programmatic mode only)
+- `maxTokens` (integer, optional): Cap cumulative prompt + completion tokens (`--max-tokens`, programmatic mode only)
+- `workingDir` (string, optional): Change to this directory before running (`--workdir`)
+- `addDir` (string[], optional): Additional writable workspace directories (one `--add-dir` per entry)
+- `approvalStrategy` (string, optional): `"legacy"` (default) or `"mcp_managed"`
+- `approvalPolicy` (string, optional): `"strict"`, `"balanced"`, or `"permissive"`
+- `mcpServers` (string[], optional): MCP server names tracked for approvals (Vibe manages its own MCP config via `vibe mcp`)
+- `worktree` (boolean|object, optional): Run inside a gateway-owned git worktree (slice λ)
+- `promptParts` (object, optional): Cache-aware structured prompt `{ system?, tools?, context?, task }`; mutually exclusive with `prompt`
+- `optimizePrompt` / `optimizeResponse` (boolean, optional): Token-efficiency optimisation, default: false
+- `correlationId` (string, optional): Request trace ID (auto-generated if omitted)
+- `idleTimeoutMs` (integer, optional): Kill a stuck process after output inactivity; 30,000 to 3,600,000 ms
+- `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
 
 ##### `claude_request_async` / `codex_request_async` / `gemini_request_async` / `grok_request_async` / `mistral_request_async`
 
@@ -778,10 +876,33 @@ List recent MCP-managed approval decisions recorded by the gateway.
 **Parameters:**
 
 - `limit` (number, optional): Max records (1-500), default: 50
-- `cli` (string, optional): Filter by `"claude"`, `"codex"`, or `"gemini"`
+- `cli` (string, optional): Filter by `"claude"`, `"codex"`, `"gemini"`, `"grok"`, or `"mistral"`
 
 Approval records are persisted to `~/.llm-cli-gateway/approvals.jsonl`.
 
+##### `llm_request_result`
+
+Read back any persisted request — sync or async — by its correlation ID. Every response echoes its ID in `structuredContent.correlationId`; pass it here to recover the persisted prompt/response after the inline result is gone. Reads the flight recorder, so it works independently of async-job persistence (returns "not found" when flight recording is disabled).
+
+**Parameters:**
+
+- `correlationId` (string, required): Correlation ID from a prior request
+- `maxChars` (number, optional): Max chars of the persisted response to return (1,000-2,000,000)
+- `includePrompt` (boolean, optional): Include the full persisted prompt text, default: false
+
+##### `llm_process_health`
+
+Report gateway process health: async-job manager state plus the resolved persistence block (`backend`, `dbPath`, config sources). Use it to confirm which config file and SQLite paths the gateway is actually running under.
+
+##### `upstream_contracts`
+
+Return the gateway's declared provider CLI contracts, optionally probing the installed binaries for drift.
+
+**Parameters:**
+
+- `cli` (string, optional): Filter (`claude|codex|gemini|grok|mistral`)
+- `probeInstalled` (boolean, optional, default `false`): Run local `--help` probes and compare advertised flags against the declared contract — strongly recommended after any provider CLI upgrade. The probe reports `missingFlags`, `extraFlags`, `acknowledgedExtraFlags` (known upstream-only flags filtered from `extraFlags`), `discoveredFlags`, and stale-marker `warnings`.
+
 #### Session Management Tools
 
 ##### `session_create`
@@ -924,6 +1045,9 @@ Plan or run an upgrade for one CLI.
 - Codex latest: `codex update`
 - Codex explicit target: `npm install -g @openai/codex@<target>`
 - Gemini: `npm install -g @google/gemini-cli@<target>`
+- Grok latest: `grok update`
+- Grok explicit target: `grok update --version <target>`
+- Mistral (Vibe): dispatches to the detected installer (`pip`/`uv`/`brew`); errors with guidance when none is detected (Vibe ships no self-update command)
 
 **Example dry run:**
 

package/dist/index.d.ts

@@ -251,6 +251,7 @@ export declare function prepareGrokRequest(params: {
     noSubagents?: boolean;
     oauth?: boolean;
     restoreCode?: boolean;
+    leaderSocket?: string;
     nativeWorktree?: boolean | string;
 }, runtime?: GatewayServerRuntime): CliRequestPrep | ExtendedToolResponse;
 export declare function prepareMistralRequest(params: {
@@ -376,6 +377,7 @@ export interface GrokRequestParams {
     noSubagents?: boolean;
     oauth?: boolean;
     restoreCode?: boolean;
+    leaderSocket?: string;
     nativeWorktree?: boolean | string;
     worktree?: boolean | {
         name?: string;

package/dist/index.js

@@ -143,8 +143,8 @@ function loadSkills() {
 const loadedSkills = loadSkills();
 const SERVER_INSTRUCTIONS = `llm-cli-gateway: Multi-LLM orchestration via MCP.
 
-Tools: claude_request, codex_request, gemini_request, grok_request, mistral_request (sync) | *_request_async (async)
-Validation: validate_with_models, second_opinion, compare_answers, red_team_review, consensus_check, ask_model, synthesize_validation
+Tools: claude_request, codex_request, gemini_request, grok_request, mistral_request (sync) | *_request_async (async) | codex_fork_session (fork a Codex session into a new branch)
+Validation: validate_with_models, second_opinion, compare_answers, red_team_review, consensus_check, ask_model, synthesize_validation, list_available_models | job_status/job_result (validation jobs)
 Jobs: llm_job_status, llm_job_result, llm_job_cancel
 Sessions: session_create, session_list, session_set_active, session_get, session_delete, session_clear_all
 Other: list_models, cli_versions, upstream_contracts (use --probe-installed after CLI upgrades to detect drift), cli_upgrade, approval_list, llm_process_health, llm_request_result (read back any persisted request — sync or async — by correlationId)
@@ -159,7 +159,7 @@ Key behaviors:
 Skills (full docs via MCP resources):
 ${loadedSkills.map(s => `- skills://${s.name} — ${s.description}`).join("\n")}`;
 function newGatewayMcpServer() {
-    return new McpServer({ name: "llm-cli-gateway", version: "1.0.0" }, { instructions: SERVER_INSTRUCTIONS });
+    return new McpServer({ name: "llm-cli-gateway", version: packageVersion() }, { instructions: SERVER_INSTRUCTIONS });
 }
 let sessionManager;
 let db = null;
@@ -1474,6 +1474,9 @@ export function prepareGrokRequest(params, runtime = resolveGatewayServerRuntime
     if (params.restoreCode) {
         args.push("--restore-code");
     }
+    if (params.leaderSocket) {
+        args.push("--leader-socket", params.leaderSocket);
+    }
     if (params.nativeWorktree === true) {
         args.push("--worktree");
     }
@@ -1976,6 +1979,7 @@ export async function handleGrokRequest(deps, params) {
         noSubagents: params.noSubagents,
         oauth: params.oauth,
         restoreCode: params.restoreCode,
+        leaderSocket: params.leaderSocket,
         nativeWorktree: params.nativeWorktree,
     }, runtime);
     if (!("args" in prep))
@@ -2133,6 +2137,7 @@ export async function handleGrokRequestAsync(deps, params) {
         noSubagents: params.noSubagents,
         oauth: params.oauth,
         restoreCode: params.restoreCode,
+        leaderSocket: params.leaderSocket,
         nativeWorktree: params.nativeWorktree,
     }, runtime);
     if (!("args" in prep))
@@ -3488,12 +3493,17 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .optional()
             .describe("Grok --restore-code: check out the original session commit when resuming."),
+        leaderSocket: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("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."),
         nativeWorktree: z
             .union([z.boolean(), z.string().min(1)])
             .optional()
             .describe("Grok -w/--worktree: native CLI worktree flag (`true` → bare `--worktree`, string → named). NOT gateway slice λ `worktree`."),
         worktree: WORKTREE_SCHEMA.optional(),
-    }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, maxTurns, workingDir, sandbox, rules, systemPromptOverride, allow, deny, compactionMode, compactionDetail, agent, bestOfN, check, disableWebSearch, todoGate, verbatim, agents, promptFile, promptJson, single, experimentalMemory, noAltScreen, noMemory, noPlan, noSubagents, oauth, restoreCode, nativeWorktree, worktree, }) => {
+    }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, maxTurns, workingDir, sandbox, rules, systemPromptOverride, allow, deny, compactionMode, compactionDetail, agent, bestOfN, check, disableWebSearch, todoGate, verbatim, agents, promptFile, promptJson, single, experimentalMemory, noAltScreen, noMemory, noPlan, noSubagents, oauth, restoreCode, leaderSocket, nativeWorktree, worktree, }) => {
         return handleGrokRequest({ sessionManager, logger, runtime }, {
             prompt,
             promptParts,
@@ -3542,6 +3552,7 @@ export function createGatewayServer(deps = {}) {
             noSubagents,
             oauth,
             restoreCode,
+            leaderSocket,
             nativeWorktree,
             worktree,
         });
@@ -4298,12 +4309,17 @@ export function createGatewayServer(deps = {}) {
                 .boolean()
                 .optional()
                 .describe("Grok --restore-code: check out the original session commit when resuming."),
+            leaderSocket: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("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."),
             nativeWorktree: z
                 .union([z.boolean(), z.string().min(1)])
                 .optional()
                 .describe("Grok -w/--worktree: native CLI worktree flag (`true` → bare `--worktree`, string → named). NOT gateway slice λ `worktree`."),
             worktree: WORKTREE_SCHEMA.optional(),
-        }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, maxTurns, workingDir, sandbox, rules, systemPromptOverride, allow, deny, compactionMode, compactionDetail, agent, bestOfN, check, disableWebSearch, todoGate, verbatim, agents, promptFile, promptJson, single, experimentalMemory, noAltScreen, noMemory, noPlan, noSubagents, oauth, restoreCode, nativeWorktree, worktree, }) => {
+        }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, maxTurns, workingDir, sandbox, rules, systemPromptOverride, allow, deny, compactionMode, compactionDetail, agent, bestOfN, check, disableWebSearch, todoGate, verbatim, agents, promptFile, promptJson, single, experimentalMemory, noAltScreen, noMemory, noPlan, noSubagents, oauth, restoreCode, leaderSocket, nativeWorktree, worktree, }) => {
             return handleGrokRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
                 promptParts,
@@ -4351,6 +4367,7 @@ export function createGatewayServer(deps = {}) {
                 noSubagents,
                 oauth,
                 restoreCode,
+                leaderSocket,
                 nativeWorktree,
                 worktree,
             });

package/dist/upstream-contracts.d.ts

@@ -5,6 +5,7 @@ export interface CliFlagContract {
     values?: readonly string[];
     pattern?: RegExp;
     description: string;
+    hiddenFromHelp?: boolean;
 }
 export interface CliUpstreamMetadata {
     sourceUrls: readonly string[];
@@ -32,6 +33,7 @@ export interface CliContract {
     resumeMaxPositionals?: number;
     resumeOnlyFlags?: readonly string[];
     resumeForbiddenFlags?: readonly string[];
+    acknowledgedUpstreamFlags?: readonly string[];
     upstreamMetadata?: CliUpstreamMetadata;
 }
 export interface CliContractFixture {
@@ -57,6 +59,13 @@ export declare function assertUpstreamCliArgs(cli: CliType, args: readonly strin
 export declare function validateUpstreamCliEnv(cli: CliType, env: Record<string, string> | undefined): ContractValidationResult;
 export declare function assertUpstreamCliEnv(cli: CliType, env: Record<string, string> | undefined): void;
 export declare function extractDiscoveredFlags(helpText: string): readonly string[];
+export interface FlagDriftResult {
+    missingFlags: string[];
+    extraFlags: readonly string[];
+    acknowledgedExtraFlags: readonly string[];
+    warnings: string[];
+}
+export declare function computeFlagDrift(contract: CliContract, helpText: string, discoveredFlags: readonly string[]): FlagDriftResult;
 export interface InstalledCliContractProbe {
     cli: CliType;
     executable: string;
@@ -66,6 +75,7 @@ export interface InstalledCliContractProbe {
     checkedHelpCommands: string[][];
     missingFlags: string[];
     extraFlags: readonly string[];
+    acknowledgedExtraFlags: readonly string[];
     discoveredFlags: readonly string[];
     helpHash?: string;
     versionHint?: string;

package/dist/upstream-contracts.js

@@ -99,7 +99,12 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 pattern: /^[0-9]+(?:\.[0-9]+)?$/,
                 description: "Budget cap in USD",
             },
-            "--max-turns": { arity: "one", pattern: /^[1-9][0-9]*$/, description: "Turn cap" },
+            "--max-turns": {
+                arity: "one",
+                pattern: /^[1-9][0-9]*$/,
+                description: "Turn cap",
+                hiddenFromHelp: true,
+            },
             "--effort": { arity: "one", values: EFFORT_LEVELS, description: "Reasoning effort" },
             "--exclude-dynamic-system-prompt-sections": {
                 arity: "none",
@@ -136,6 +141,37 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 description: 'Restrict the available built-in tool set ("" disables all)',
             },
         },
+        acknowledgedUpstreamFlags: [
+            "--allow-dangerously-skip-permissions",
+            "--allowed",
+            "--bare",
+            "--betas",
+            "--brief",
+            "--chrome",
+            "--dangerously-skip-permissions",
+            "--debug",
+            "--debug-file",
+            "--disable-slash-commands",
+            "--disallowed",
+            "--file",
+            "--from-pr",
+            "--ide",
+            "--include-hook-events",
+            "--mcp-debug",
+            "--name",
+            "--no-chrome",
+            "--plugin-dir",
+            "--plugin-url",
+            "--print",
+            "--prompt-suggestions",
+            "--remote-control",
+            "--remote-control-session-name-prefix",
+            "--replay-user-messages",
+            "--resume",
+            "--tmux",
+            "--version",
+            "--worktree",
+        ],
         env: {},
         conformanceFixtures: [
             {
@@ -518,6 +554,26 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 description: "Auto-approve all actions (gemini -y/--yolo). Functionally equivalent to --approval-mode yolo; the gateway emits at most one of the two.",
             },
         },
+        acknowledgedUpstreamFlags: [
+            "--accept-raw-output-risk",
+            "--acp",
+            "--debug",
+            "--delete-session",
+            "--experimental-acp",
+            "--extensions",
+            "--list-extensions",
+            "--list-sessions",
+            "--output-format",
+            "--prompt",
+            "--prompt-interactive",
+            "--raw-output",
+            "--sandbox",
+            "--screen-reader",
+            "--session-file",
+            "--session-id",
+            "--version",
+            "--worktree",
+        ],
         env: {},
         conformanceFixtures: [
             {
@@ -612,6 +668,7 @@ export const UPSTREAM_CLI_CONTRACTS = {
             "noSubagents",
             "oauth",
             "restoreCode",
+            "leaderSocket",
             "nativeWorktree",
         ],
         flags: {
@@ -693,6 +750,10 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 arity: "none",
                 description: "Check out the original session commit when resuming",
             },
+            "--leader-socket": {
+                arity: "one",
+                description: "Custom leader socket path (isolated leader, Grok 0.2.32+)",
+            },
             "--single": { arity: "one", description: "Single-turn prompt" },
             "--todo-gate": { arity: "none", description: "Enable runtime turn-end TodoGate" },
             "--verbatim": { arity: "none", description: "Send prompt exactly as given" },
@@ -843,6 +904,18 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 ],
                 expect: "pass",
             },
+            {
+                id: "grok-leader-socket",
+                description: "Grok 0.2.32: --leader-socket <PATH> is accepted",
+                args: ["-p", "hello", "--leader-socket", "/home/user/.grok/leader-branch.sock"],
+                expect: "pass",
+            },
+            {
+                id: "grok-leader-socket-missing-value",
+                description: "Grok 0.2.32: --leader-socket without a path is rejected (arity one)",
+                args: ["-p", "hello", "--leader-socket"],
+                expect: "fail",
+            },
         ],
     },
     mistral: {
@@ -1220,6 +1293,42 @@ export function extractDiscoveredFlags(helpText) {
     }
     return Array.from(discovered).sort();
 }
+export function computeFlagDrift(contract, helpText, discoveredFlags) {
+    const warnings = [];
+    const missingFlags = [];
+    for (const [flag, spec] of Object.entries(contract.flags)) {
+        const inHelp = helpText.includes(flag);
+        if (spec.hiddenFromHelp) {
+            if (inHelp) {
+                warnings.push(`${flag} is marked hiddenFromHelp but now appears in ${contract.executable} help output; remove the hiddenFromHelp marker from the contract`);
+            }
+            continue;
+        }
+        if (!inHelp)
+            missingFlags.push(flag);
+    }
+    const contractFlagSet = new Set(Object.keys(contract.flags));
+    const acknowledged = new Set(contract.acknowledgedUpstreamFlags ?? []);
+    const extraFlags = [];
+    const acknowledgedExtraFlags = [];
+    for (const flag of discoveredFlags) {
+        if (contractFlagSet.has(flag))
+            continue;
+        if (acknowledged.has(flag)) {
+            acknowledgedExtraFlags.push(flag);
+        }
+        else {
+            extraFlags.push(flag);
+        }
+    }
+    const discoveredSet = new Set(discoveredFlags);
+    for (const flag of acknowledged) {
+        if (!discoveredSet.has(flag)) {
+            warnings.push(`acknowledged upstream flag ${flag} no longer appears in ${contract.executable} help output; remove it from acknowledgedUpstreamFlags`);
+        }
+    }
+    return { missingFlags, extraFlags, acknowledgedExtraFlags, warnings };
+}
 export function probeInstalledCliContract(cli, timeoutMs = 5_000) {
     const contract = UPSTREAM_CLI_CONTRACTS[cli];
     const outputs = [];
@@ -1252,6 +1361,7 @@ export function probeInstalledCliContract(cli, timeoutMs = 5_000) {
                 checkedHelpCommands: contract.helpArgs,
                 missingFlags: [],
                 extraFlags: [],
+                acknowledgedExtraFlags: [],
                 discoveredFlags: [],
                 helpHash: undefined,
                 versionHint: undefined,
@@ -1265,10 +1375,9 @@ export function probeInstalledCliContract(cli, timeoutMs = 5_000) {
         }
     }
     const helpText = outputs.join("\n");
-    const missingFlags = Object.keys(contract.flags).filter(flag => !helpText.includes(flag));
     const discoveredFlags = extractDiscoveredFlags(helpText);
-    const contractFlagSet = new Set(Object.keys(contract.flags));
-    const extraFlags = discoveredFlags.filter(f => !contractFlagSet.has(f));
+    const drift = computeFlagDrift(contract, helpText, discoveredFlags);
+    warnings.push(...drift.warnings);
     const versionMatch = helpText.match(/^\s*(?:[A-Za-z][\w .-]+)?v?\d+\.\d+\S*/m);
     const versionHint = versionMatch ? versionMatch[0].trim().slice(0, 80) : undefined;
     const helpHash = createHash("sha256").update(helpText).digest("hex");
@@ -1279,8 +1388,9 @@ export function probeInstalledCliContract(cli, timeoutMs = 5_000) {
         resolvedArgs,
         available: true,
         checkedHelpCommands: contract.helpArgs,
-        missingFlags,
-        extraFlags,
+        missingFlags: drift.missingFlags,
+        extraFlags: drift.extraFlags,
+        acknowledgedExtraFlags: drift.acknowledgedExtraFlags,
         discoveredFlags,
         helpHash,
         versionHint,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "mcpName": "io.github.verivus-oss/llm-cli-gateway",
   "description": "MCP server providing unified access to Claude Code, Codex, Gemini, Grok, and Mistral Vibe CLIs with session management, retry logic, async job orchestration, durable job results, and cross-LLM validation.",
   "license": "MIT",