llm-cli-gateway 2.11.1 → 2.12.0

package/dist/index.js

@@ -23,11 +23,10 @@ import { runAcpRequest } from "./acp/runtime.js";
 import { isAcpError } from "./acp/errors.js";
 import { createApiProvider, runApiRequest, apiProviderBreakerState, } from "./api-provider.js";
 import { prepareApiRequest, apiProviderCatalogEntry, ApiModelNotAllowedError, } from "./api-request.js";
-import { createXaiResponse, XaiApiError, } from "./xai-api-provider.js";
 import { checkHealth } from "./health.js";
 import { clearModelRegistryCache, getAvailableCliInfo, getCliInfo, resolveModelAlias, } from "./model-registry.js";
 import { getProviderToolCapabilities } from "./provider-tool-capabilities.js";
-import { AsyncJobManager, } from "./async-job-manager.js";
+import { AsyncJobManager, extractApiHttpStatus, extractApiErrorBody, } from "./async-job-manager.js";
 import { createJobStore } from "./job-store.js";
 import { ApprovalManager, bypassAllowedByOperator, } from "./approval-manager.js";
 import { checkReviewIntegrity } from "./review-integrity.js";
@@ -43,6 +42,7 @@ import { printDoctorJson } from "./doctor.js";
 import { createWorkspace, describeWorkspace, getWorkspace, loadWorkspaceRegistry, registerExistingWorkspace, resolveWorkspaceForProvider, validatePathInsideWorkspace, } from "./workspace-registry.js";
 import { generateSecret, hashSecret } from "./oauth.js";
 import { registerValidationTools } from "./validation-tools.js";
+import { currentCaller, resolveValidationReceipt } from "./validation-receipt.js";
 import { assertUpstreamCliArgs, assertUpstreamCliEnv, buildProviderSubcommandsCompactCatalog, buildUpstreamContractReport, getCliSubcommandContract, probeInstalledCliContract, serializeCliSubcommandContract, UPSTREAM_CLI_CONTRACTS, } from "./upstream-contracts.js";
 import { buildArgvFromGeneration, deriveZodShapeFromGeneration, GROK_FLAG_GENERATION, GROK_GEN_OUTPUT_FORMAT, GROK_GEN_MAIN, GROK_GEN_PROMPT_FILE, GROK_GEN_SINGLE, GROK_GEN_TAIL, } from "./provider-codegen.js";
 import { entrypointFileURL } from "./entrypoint-url.js";
@@ -161,14 +161,15 @@ export function buildServerInstructions(asyncJobsEnabled, grokApiToolsEnabled =
         : '- Async jobs are DISABLED (persistence.backend = "none"): *_request_async and llm_job_* tools are not registered, and sync requests run to completion (no auto-deferral).';
     return `llm-cli-gateway: Multi-LLM orchestration via MCP.
 
-Tools: claude_request, codex_request, gemini_request, grok_request, mistral_request${apiToolsNote} (sync)${asyncToolsNote} | codex_fork_session (fork a Codex session into a new branch)
+Tools: claude_request, codex_request, gemini_request, grok_request, mistral_request, devin_request${apiToolsNote} (sync)${asyncToolsNote} | 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)
 ${jobsLine}Sessions: session_create, session_list, session_set_active, session_get, session_delete, session_clear_all
-Other: list_models, cli_versions, upstream_contracts, provider_subcommands_* (read-only subcommand contract/drift introspection), cli_upgrade, approval_list, llm_process_health, llm_request_result (read back any persisted request — sync or async — by correlationId)
+Other: list_models, provider_tool_capabilities, cli_versions, upstream_contracts, provider_subcommands_* (read-only subcommand contract/drift introspection), cli_upgrade, approval_list, llm_process_health, llm_request_result (read back any persisted request, sync or async, by correlationId)
+Workspaces: workspace_create, workspace_list, workspace_get, workspace_register_existing_repo
 
 Key behaviors:
 ${deferralLine}
-- Sessions: Claude --continue, Gemini (Antigravity) --conversation <id>/--continue, Grok --resume/--continue, Mistral --resume/--continue (current Vibe defaults session logging on; doctor flags explicit session_logging.enabled=false), Codex \`exec resume <ID>\` / \`exec resume --last\` (all real CLI continuity). For Codex, sessionId must be a real Codex UUID (from ~/.codex/sessions/); gateway-generated gw-* IDs are rejected.
+- Sessions: Claude --continue, Gemini (Antigravity) --conversation <id>/--continue, Grok --resume/--continue, Mistral --resume/--continue (current Vibe defaults session logging on; doctor flags explicit session_logging.enabled=false), Codex \`exec resume <ID>\` / \`exec resume --last\`, Devin --resume <id>/--continue (all real CLI continuity). For Codex, sessionId must be a real Codex UUID (from ~/.codex/sessions/); gateway-generated gw-* IDs are rejected.
 - Approval gates: opt-in via approvalStrategy:"mcp_managed".
 - Upstream drift detection: After upgrading any provider CLI (especially grok), use upstream_contracts with probeInstalled:true and provider_subcommand_drift for declared subcommand help surfaces. Probes are safe, read-only --help checks.
 - Idle timeout kills stuck processes (default 10min, configurable via idleTimeoutMs).
@@ -280,6 +281,11 @@ export const WORKSPACE_ALIAS_SCHEMA = z
     .describe("Registered workspace alias. Remote clients use aliases, not absolute paths.");
 export const SESSION_PROVIDER_VALUES = PROVIDER_TYPES;
 export const SESSION_PROVIDER_ENUM = z.enum(SESSION_PROVIDER_VALUES);
+export function sessionProviderValuesFor(providers) {
+    return [
+        ...new Set([...SESSION_PROVIDER_VALUES, ...enabledApiProviders(providers).map(p => p.name)]),
+    ];
+}
 let activeServer = null;
 let activeHttpGateway = null;
 export function resolveGatewayServerRuntime(deps = {}, options = {}) {
@@ -458,7 +464,7 @@ async function awaitJobOrDefer(cli, args, corrId, idleTimeoutMs, outputFormat, f
         message: `Execution exceeded sync deadline (${SYNC_DEADLINE_MS}ms). Poll with llm_job_status, collect with llm_job_result.`,
     };
 }
-async function awaitApiJobOrDefer(provider, apiRequest, corrId, runtime = resolveGatewayServerRuntime(), onComplete, flightRecorderEntry, extractUsage) {
+async function awaitApiJobOrDefer(provider, apiRequest, corrId, runtime = resolveGatewayServerRuntime(), onComplete, flightRecorderEntry, extractUsage, forceRefresh, forceInline) {
     let onCompleteOwnedByCaller = onComplete !== undefined;
     const consumeOnComplete = () => {
         if (!onCompleteOwnedByCaller || !onComplete)
@@ -474,13 +480,28 @@ async function awaitApiJobOrDefer(provider, apiRequest, corrId, runtime = resolv
     const deferralAvailable = runtime.persistence.backend !== "none" &&
         runtime.persistence.asyncJobsEnabled &&
         runtime.asyncJobManager.hasStore();
-    if (SYNC_DEADLINE_MS === 0 || !deferralAvailable) {
+    if (SYNC_DEADLINE_MS === 0 || !deferralAvailable || forceInline) {
         try {
             const result = await runApiRequest(provider, apiRequest, runtime.logger);
-            return { stdout: result.text, stderr: "", code: 0 };
+            return {
+                stdout: result.text,
+                stderr: "",
+                code: 0,
+                usage: result.usage,
+                httpStatus: result.httpStatus,
+                responseId: result.responseId ?? null,
+                model: result.model,
+                status: result.status ?? null,
+            };
         }
         catch (err) {
-            return { stdout: "", stderr: err.message, code: 1 };
+            return {
+                stdout: "",
+                stderr: err.message,
+                code: 1,
+                httpStatus: extractApiHttpStatus(err) ?? undefined,
+                errorBody: extractApiErrorBody(err),
+            };
         }
         finally {
             consumeOnComplete();
@@ -495,6 +516,7 @@ async function awaitApiJobOrDefer(provider, apiRequest, corrId, runtime = resolv
             onComplete,
             flightRecorderEntry,
             extractUsage,
+            forceRefresh,
         });
         onCompleteOwnedByCaller = false;
     }
@@ -517,6 +539,11 @@ async function awaitApiJobOrDefer(provider, apiRequest, corrId, runtime = resolv
                 stdout: result.stdout,
                 stderr: result.stderr || result.error || "",
                 code: result.exitCode ?? 1,
+                usage: result.apiUsage,
+                httpStatus: result.httpStatus,
+                responseId: result.responseId,
+                model: result.model,
+                errorBody: result.errorBody,
             };
         }
         await new Promise(resolve => setTimeout(resolve, SYNC_POLL_INTERVAL_MS));
@@ -780,22 +807,41 @@ function registerWorkspaceTools(server, runtime) {
         }
     });
 }
-function createErrorResponse(cli, code, stderr, correlationId, error) {
+export function createErrorResponse(cli, code, stderr, correlationId, error, apiError) {
     let errorMessage = `Error executing ${cli} CLI`;
     const isLaunchExit = code === 127 || code === -4058;
+    const isOutputOverflow = Boolean(error) && /Output exceeded maximum size/i.test(error.message);
+    const authProbe = `${error?.message ?? ""}\n${stderr ?? ""}`;
+    const isAuthError = /not logged in|please run .*login|unauthorized|\b401\b|authentication failed|invalid api key|no api key|expired token|re-?authenticate/i.test(authProbe);
+    const authRemediation = {
+        claude: "Run `claude login` (or set ANTHROPIC_API_KEY) and retry.",
+        codex: "Run `codex login` and retry.",
+        gemini: "Re-authenticate the Antigravity `agy` CLI and retry.",
+        grok: "Run `grok login` (or re-authenticate) and retry.",
+        mistral: "Run `vibe --setup` (or re-authenticate) and retry.",
+        devin: "Run `devin auth login` (or set WINDSURF_API_KEY) and retry.",
+    };
     if (error) {
         errorMessage += `:\n${error.message}`;
         if (error.message.includes("ENOENT")) {
             errorMessage += `\n\nThe '${cli}' command was not found. Please ensure ${cli} CLI is installed and in your PATH.`;
         }
+        else if (/EACCES|EPERM/.test(error.message)) {
+            errorMessage += `\n\nThe '${cli}' binary is not executable or permission was denied (EACCES/EPERM). Check its file permissions and PATH.`;
+        }
+        else if (isOutputOverflow) {
+            errorMessage += `\n\nThe ${cli} output exceeded the 50MB cap. Narrow the request, ask for structured/JSON output, or split the work into smaller calls.`;
+        }
         logger.error(`[${correlationId || "unknown"}] ${cli} CLI execution failed:`, error.message);
     }
     else if (code === 124) {
         errorMessage += `: Command timed out\n${stderr}`;
+        errorMessage += `\n\nIncrease timeoutMs, or use the *_request_async variant and poll with llm_job_status / llm_job_result.`;
         logger.error(`[${correlationId || "unknown"}] ${cli} CLI timed out`);
     }
     else if (code === 125) {
         errorMessage += `: Process killed due to inactivity\n${stderr}`;
+        errorMessage += `\n\nThe CLI may have been awaiting interactive approval. Pass a non-interactive permission/approval option, or raise idleTimeoutMs.`;
         logger.error(`[${correlationId || "unknown"}] ${cli} CLI killed due to inactivity`);
     }
     else if (isLaunchExit) {
@@ -804,8 +850,14 @@ function createErrorResponse(cli, code, stderr, correlationId, error) {
     }
     else if (code !== 0) {
         errorMessage += ` (exit code ${code}):\n${stderr}`;
+        if (!stderr || stderr.trim().length === 0) {
+            errorMessage += `\n\nNo error output was captured. The CLI may not be authenticated, may be awaiting interactive input, or may have rejected an unsupported flag. Re-run with DEBUG=1 for more detail.`;
+        }
         logger.error(`[${correlationId || "unknown"}] ${cli} CLI failed with exit code ${code}`);
     }
+    if (isAuthError) {
+        errorMessage += `\n\n${authRemediation[cli] ?? `Re-authenticate the ${cli} CLI and retry.`}`;
+    }
     return {
         content: [{ type: "text", text: errorMessage }],
         isError: true,
@@ -814,20 +866,30 @@ function createErrorResponse(cli, code, stderr, correlationId, error) {
             correlationId: correlationId || null,
             cli,
             exitCode: code,
-            errorCategory: code === 124
-                ? "timeout"
-                : code === 125
-                    ? "idle_timeout"
-                    : error
-                        ? "spawn_error"
-                        : isLaunchExit
-                            ? "spawn_error"
-                            : "cli_error",
+            errorCategory: isAuthError
+                ? "auth_error"
+                : code === 124
+                    ? "timeout"
+                    : code === 125
+                        ? "idle_timeout"
+                        : isOutputOverflow
+                            ? "output_overflow"
+                            : error
+                                ? "spawn_error"
+                                : isLaunchExit
+                                    ? "spawn_error"
+                                    : "cli_error",
+            ...(apiError
+                ? {
+                    httpStatus: apiError.httpStatus ?? undefined,
+                    responseBody: apiError.responseBody,
+                }
+                : {}),
         },
     };
 }
 export function extractUsageAndCost(cli, output, outputFormat, ctx) {
-    if (cli === "claude" && outputFormat === "stream-json") {
+    if (cli === "claude" && (outputFormat === "stream-json" || outputFormat === "json")) {
         const parsed = parseStreamJson(output);
         if (!parsed.usage) {
             return { costUsd: parsed.costUsd ?? undefined };
@@ -1191,9 +1253,30 @@ function registerBaseResources(server, runtime) {
         const contents = await runtime.resourceProvider.readResource(uri.href);
         return { contents: contents ? [contents] : [] };
     });
+    const validationReceiptStore = runtime.persistence.backend === "sqlite"
+        ? runtime.asyncJobManager.getValidationRunStore()
+        : null;
+    if (validationReceiptStore) {
+        server.registerResource("validation-receipt", new ResourceTemplate("validation-receipt://{validationId}", { list: undefined }), {
+            title: "Validation Receipt",
+            description: "Immutable receipt of a terminal cross-LLM validation run (own-or-not-found).",
+            mimeType: "application/json",
+        }, async (uri, variables) => {
+            const validationId = Array.isArray(variables.validationId)
+                ? variables.validationId[0]
+                : variables.validationId;
+            runtime.logger.debug(`Reading validation-receipt://${validationId}`);
+            const result = resolveValidationReceipt({ asyncJobManager: runtime.asyncJobManager, validationRunStore: validationReceiptStore }, String(validationId), { caller: currentCaller() });
+            return {
+                contents: [
+                    { uri: uri.href, mimeType: "application/json", text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        });
+    }
 }
 function resolvePromptOrPartsForPrep(args) {
-    const hasPrompt = typeof args.prompt === "string" && args.prompt.length > 0;
+    const hasPrompt = typeof args.prompt === "string" && args.prompt.trim().length > 0;
     const hasParts = args.promptParts !== undefined;
     if (hasPrompt && hasParts) {
         return {
@@ -1705,6 +1788,15 @@ export function prepareGeminiRequest(params, runtime = resolveGatewayServerRunti
     if (params.yolo || effectiveApprovalMode === "yolo") {
         args.push("--dangerously-skip-permissions");
     }
+    if (params.project !== undefined && params.newProject) {
+        return createErrorResponse(params.operation, 1, "", corrId, new Error("project and newProject are mutually exclusive"));
+    }
+    if (params.project !== undefined && params.project !== "") {
+        args.push("--project", params.project);
+    }
+    if (params.newProject) {
+        args.push("--new-project");
+    }
     return {
         corrId,
         effectivePrompt,
@@ -1818,12 +1910,30 @@ export function prepareGrokRequest(params, runtime = resolveGatewayServerRuntime
     }
     args.push(...buildArgvFromGeneration(grokContract, GROK_GEN_SINGLE, genParams));
     args.push(...buildArgvFromGeneration(grokContract, GROK_GEN_TAIL, genParams));
+    const hasNativeWorktree = params.nativeWorktree === true ||
+        (typeof params.nativeWorktree === "string" && params.nativeWorktree.length > 0);
     if (params.nativeWorktree === true) {
         args.push("--worktree");
     }
     else if (typeof params.nativeWorktree === "string" && params.nativeWorktree.length > 0) {
         args.push("--worktree", params.nativeWorktree);
     }
+    if (params.worktreeRef !== undefined && params.worktreeRef !== "") {
+        if (!hasNativeWorktree) {
+            return createErrorResponse(params.operation, 1, "", corrId, new Error("worktreeRef: requires nativeWorktree (grok --worktree-ref needs --worktree)"));
+        }
+        args.push("--worktree-ref", params.worktreeRef);
+    }
+    if (params.forkSession) {
+        args.push("--fork-session");
+    }
+    if (params.jsonSchema !== undefined) {
+        const schemaArg = typeof params.jsonSchema === "string" ? params.jsonSchema : JSON.stringify(params.jsonSchema);
+        if (!schemaArg.trim()) {
+            return createErrorResponse(params.operation, 1, "", corrId, new Error("jsonSchema: must be a non-empty JSON Schema string or object"));
+        }
+        args.push("--json-schema", schemaArg);
+    }
     return {
         corrId,
         effectivePrompt,
@@ -1960,7 +2070,7 @@ export function buildMistralRetryPrep(params, recoveryModel) {
         addDir: params.addDir,
     });
 }
-function buildCliResponse(cli, stdout, optimizeResponse, corrId, sessionId, prep, durationMs, resumable, outputFormat, warnings) {
+export function buildCliResponse(cli, stdout, optimizeResponse, corrId, sessionId, prep, durationMs, resumable, outputFormat, warnings) {
     let finalStdout = stdout;
     if (cli === "codex" && outputFormat !== "json") {
         finalStdout = codexDisplayText(stdout);
@@ -1978,9 +2088,37 @@ function buildCliResponse(cli, stdout, optimizeResponse, corrId, sessionId, prep
             .join("\n");
         finalStdout += `\n\n⚠️ Review Integrity Warnings (score: ${prep.reviewIntegrity.totalScore}):\n${warnings}`;
     }
+    const derivedWarnings = [];
+    const extraStructured = {};
+    let claudeResultError = false;
+    if (cli === "claude") {
+        const parsedResult = parseStreamJson(stdout);
+        if (parsedResult.isError) {
+            claudeResultError = true;
+            extraStructured.resultIsError = true;
+            derivedWarnings.push({
+                code: "claude_result_error",
+                message: "Claude exited 0 but the result event reported is_error:true (e.g. max-turns or mid-run error). The returned text may be partial.",
+            });
+        }
+    }
+    if (cli === "codex") {
+        const parsedCodex = parseCodexJsonStream(stdout);
+        if (parsedCodex.threadId) {
+            extraStructured.codexSessionId = parsedCodex.threadId;
+        }
+    }
+    if (!claudeResultError && finalStdout.trim().length === 0) {
+        extraStructured.emptyOutput = true;
+        derivedWarnings.push({
+            code: "empty_output",
+            message: `${cli} exited 0 but produced no assistant output. The request may have been a no-op, hit a guardrail, or awaited input.`,
+        });
+    }
     const response = {
         content: [{ type: "text", text: finalStdout }],
         structuredContent: {
+            ...extraStructured,
             response: finalStdout,
             model: prep.resolvedModel || "default",
             cli,
@@ -2011,8 +2149,9 @@ function buildCliResponse(cli, stdout, optimizeResponse, corrId, sessionId, prep
     if (prep.reviewIntegrity && prep.reviewIntegrity.violations.length > 0) {
         response.reviewIntegrity = prep.reviewIntegrity;
     }
-    if (warnings && warnings.length > 0) {
-        response.warnings = warnings;
+    const allWarnings = [...(warnings ?? []), ...derivedWarnings];
+    if (allWarnings.length > 0) {
+        response.warnings = allWarnings;
     }
     return response;
 }
@@ -2123,11 +2262,18 @@ async function getExistingSessionForProvider(sessionManager, sessionId, provider
     }
     return existing;
 }
-function asXaiApiError(error) {
-    if (error instanceof XaiApiError)
-        return error;
-    const cause = error?.cause;
-    return cause instanceof XaiApiError ? cause : null;
+function grokInputToMessages(input, instructions) {
+    const messages = [];
+    if (instructions && instructions.length > 0) {
+        messages.push({ role: "system", content: instructions });
+    }
+    if (typeof input === "string") {
+        messages.push({ role: "user", content: input });
+    }
+    else {
+        messages.push(...input);
+    }
+    return messages;
 }
 function buildGrokApiToolResponse(args) {
     let text = args.result.text;
@@ -2221,12 +2367,12 @@ export async function handleGrokApiRequest(deps, params) {
         const session = await resolveGrokApiSession(params, runtime);
         sessionId = session.sessionId;
         previousResponseId = session.previousResponseId;
-        const call = (prev) => createXaiResponse({
+        const grokProvider = createApiProvider("grok-api", "xai-responses");
+        const call = (prev) => runApiRequest(grokProvider, {
             baseUrl: xaiConfig.baseUrl,
             apiKey,
             model: prep.resolvedModel,
-            input: prep.input,
-            instructions: prep.instructions,
+            messages: grokInputToMessages(prep.input, prep.instructions),
             previousResponseId: prev,
             maxOutputTokens: params.maxOutputTokens,
             temperature: params.temperature,
@@ -2239,8 +2385,7 @@ export async function handleGrokApiRequest(deps, params) {
             result = await call(previousResponseId);
         }
         catch (error) {
-            const xaiError = asXaiApiError(error);
-            if (xaiError?.status === 404 && previousResponseId) {
+            if (extractApiHttpStatus(error) === 404 && previousResponseId) {
                 runtime.logger.warn(`[${corrId}] xAI previous_response_id was rejected; clearing stale session metadata and retrying fresh`);
                 await runtime.sessionManager.updateSessionMetadata(sessionId, {
                     xaiPreviousResponseId: null,
@@ -2286,10 +2431,9 @@ export async function handleGrokApiRequest(deps, params) {
     catch (error) {
         durationMs = Math.max(0, Date.now() - startTime);
         const err = error;
-        const xaiError = asXaiApiError(error);
         runtime.logger.error(`[${corrId}] grok_api_request failed`, err.message);
         safeFlightComplete(corrId, {
-            response: xaiError?.responseText ?? "",
+            response: extractApiErrorBody(error) ?? "",
             durationMs,
             retryCount: 0,
             circuitBreakerState: "closed",
@@ -2304,10 +2448,63 @@ export async function handleGrokApiRequest(deps, params) {
         runtime.performanceMetrics.recordRequest("grok-api", durationMs || Math.max(0, Date.now() - startTime), wasSuccessful);
     }
 }
-function buildApiProviderCall(providerRuntime, params) {
+function resolveApiProviderInput(params, toolName, corrId) {
+    const inputResolution = resolvePromptOrPartsForPrep({
+        prompt: params.prompt,
+        promptParts: params.promptParts,
+        operation: toolName,
+        correlationId: corrId,
+    });
+    if (!inputResolution.ok)
+        return { ok: false, error: inputResolution.error };
+    const system = params.promptParts?.system && params.promptParts.system.length > 0
+        ? params.promptParts.system
+        : params.system;
+    let userContent = params.promptParts
+        ? buildXaiPromptPartsUserContent(params.promptParts)
+        : (params.prompt ?? "");
+    let optimizationApplied = false;
+    if (params.optimizePrompt) {
+        const optimized = optimizePromptText(userContent);
+        logOptimizationTokens("prompt", corrId, userContent, optimized);
+        userContent = optimized;
+        optimizationApplied = true;
+    }
+    return {
+        ok: true,
+        userContent,
+        system,
+        effectivePrompt: buildXaiPromptPartsEffectivePrompt(system, userContent),
+        optimizationApplied,
+        stablePrefixHash: inputResolution.stablePrefixHash,
+        stablePrefixTokens: inputResolution.stablePrefixTokens,
+    };
+}
+async function resolveApiSession(providerName, continuity, params, runtime) {
+    const label = `${providerName} API Session`;
+    const readPrev = (s) => continuity === "server-side-id" &&
+        !params.createNewSession &&
+        typeof s.metadata?.apiPreviousResponseId === "string"
+        ? s.metadata.apiPreviousResponseId
+        : undefined;
+    if (params.sessionId) {
+        const existing = await getExistingSessionForProvider(runtime.sessionManager, params.sessionId, providerName);
+        const session = existing ??
+            (await runtime.sessionManager.createSession(providerName, label, params.sessionId));
+        return { sessionId: session.id, previousResponseId: readPrev(session) };
+    }
+    if (continuity === "server-side-id" && !params.createNewSession) {
+        const active = await getCallerOwnedActiveSession(runtime.sessionManager, providerName);
+        if (active)
+            return { sessionId: active.id, previousResponseId: readPrev(active) };
+    }
+    const session = await runtime.sessionManager.createSession(providerName, label, `${GATEWAY_SESSION_PREFIX}${randomUUID()}`);
+    return { sessionId: session.id };
+}
+function buildApiProviderCall(providerRuntime, params, userContent, system) {
     const apiRequest = prepareApiRequest(providerRuntime, {
-        prompt: params.prompt ?? "",
-        system: params.system,
+        prompt: userContent,
+        system,
         model: params.model,
         maxOutputTokens: params.maxOutputTokens,
         temperature: params.temperature,
@@ -2318,16 +2515,32 @@ function buildApiProviderCall(providerRuntime, params) {
     const provider = createApiProvider(providerRuntime.name, providerRuntime.kind);
     return { provider, apiRequest };
 }
-function buildApiSuccessResponse(text, corrId, providerName) {
-    return {
+function buildApiSuccessResponse(text, corrId, providerName, telemetry) {
+    const usage = telemetry?.usage;
+    const response = {
         content: [{ type: "text", text }],
         structuredContent: {
             response: text,
-            correlationId: corrId,
+            provider: providerName,
             cli: providerName,
+            model: telemetry?.model,
+            correlationId: corrId,
+            sessionId: telemetry?.sessionId ?? null,
+            responseId: telemetry?.responseId ?? null,
+            previousResponseId: telemetry?.previousResponseId ?? null,
+            stalePreviousResponseCleared: telemetry?.stalePreviousResponseCleared ?? false,
+            status: telemetry?.status ?? undefined,
+            httpStatus: telemetry?.httpStatus ?? undefined,
+            inputTokens: usage?.inputTokens,
+            outputTokens: usage?.outputTokens,
+            cacheReadTokens: usage?.cacheReadTokens,
+            costUsd: usage?.costUsd,
             exitCode: 0,
         },
     };
+    if (telemetry?.sessionId)
+        response.sessionId = telemetry.sessionId;
+    return response;
 }
 export async function handleApiProviderRequest(runtimeArg, providerRuntime, params) {
     const toolName = `api_${providerRuntime.name}_request`;
@@ -2335,18 +2548,115 @@ export async function handleApiProviderRequest(runtimeArg, providerRuntime, para
     const startTime = Date.now();
     let wasSuccessful = false;
     try {
-        if (!params.prompt || params.prompt.trim().length === 0) {
-            return createErrorResponse(toolName, 1, "prompt is required and cannot be empty", corrId);
+        const resolved = resolveApiProviderInput(params, toolName, corrId);
+        if (!resolved.ok)
+            return resolved.error;
+        const { provider, apiRequest } = buildApiProviderCall(providerRuntime, params, resolved.userContent, resolved.system);
+        const serverSide = provider.continuity === "server-side-id";
+        const wantsSession = serverSide || params.sessionId !== undefined || params.createNewSession === true;
+        let sessionId;
+        let previousResponseId;
+        if (wantsSession) {
+            const session = await resolveApiSession(providerRuntime.name, provider.continuity, params, runtimeArg);
+            sessionId = session.sessionId;
+            previousResponseId = session.previousResponseId;
+            await runtimeArg.sessionManager.updateSessionUsage(sessionId);
+            if (previousResponseId)
+                apiRequest.previousResponseId = previousResponseId;
+        }
+        const flightRecorderEntry = {
+            model: apiRequest.model,
+            prompt: resolved.effectivePrompt,
+            sessionId,
+            stablePrefixHash: resolved.stablePrefixHash ?? undefined,
+            stablePrefixTokens: resolved.stablePrefixTokens ?? undefined,
+        };
+        safeFlightStart({
+            correlationId: corrId,
+            cli: providerRuntime.name,
+            model: apiRequest.model,
+            prompt: resolved.effectivePrompt,
+            system: resolved.system,
+            sessionId,
+            stablePrefixHash: resolved.stablePrefixHash ?? undefined,
+            stablePrefixTokens: resolved.stablePrefixTokens ?? undefined,
+        }, runtimeArg);
+        let result = await awaitApiJobOrDefer(provider, apiRequest, corrId, runtimeArg, undefined, flightRecorderEntry, undefined, params.forceRefresh, serverSide);
+        let stalePreviousResponseCleared = false;
+        if (serverSide &&
+            !isDeferredResponse(result) &&
+            result.code !== 0 &&
+            result.httpStatus === 404 &&
+            sessionId &&
+            previousResponseId) {
+            await runtimeArg.sessionManager.updateSessionMetadata(sessionId, {
+                apiPreviousResponseId: null,
+                apiResponseCreatedAt: null,
+            });
+            apiRequest.previousResponseId = undefined;
+            previousResponseId = undefined;
+            stalePreviousResponseCleared = true;
+            const retry = await awaitApiJobOrDefer(provider, apiRequest, corrId, runtimeArg, undefined, flightRecorderEntry, undefined, true, serverSide);
+            if (!isDeferredResponse(retry))
+                result = retry;
         }
-        const { provider, apiRequest } = buildApiProviderCall(providerRuntime, params);
-        const result = await awaitApiJobOrDefer(provider, apiRequest, corrId, runtimeArg);
         if (isDeferredResponse(result))
-            return buildDeferredToolResponse(result);
+            return buildDeferredToolResponse(result, sessionId);
+        const durationMs = Math.max(0, Date.now() - startTime);
         if (result.code !== 0) {
-            return createErrorResponse(toolName, result.code, result.stderr, corrId);
+            safeFlightComplete(corrId, {
+                response: result.errorBody ?? "",
+                durationMs,
+                retryCount: 0,
+                circuitBreakerState: "closed",
+                optimizationApplied: resolved.optimizationApplied,
+                exitCode: result.code,
+                httpStatus: result.httpStatus ?? undefined,
+                errorMessage: result.stderr,
+                status: "failed",
+            }, runtimeArg);
+            return createErrorResponse(toolName, result.code, result.stderr, corrId, undefined, {
+                httpStatus: result.httpStatus,
+                responseBody: result.errorBody,
+            });
         }
         wasSuccessful = true;
-        return buildApiSuccessResponse(result.stdout, corrId, providerRuntime.name);
+        if (serverSide && sessionId && result.responseId) {
+            await runtimeArg.sessionManager.updateSessionMetadata(sessionId, {
+                apiPreviousResponseId: result.responseId,
+                apiResponseCreatedAt: new Date().toISOString(),
+            });
+        }
+        let text = result.stdout;
+        if (params.optimizeResponse) {
+            const optimized = optimizeResponseText(text);
+            logOptimizationTokens("response", corrId, text, optimized);
+            text = optimized;
+        }
+        safeFlightComplete(corrId, {
+            response: text,
+            durationMs,
+            retryCount: 0,
+            circuitBreakerState: "closed",
+            optimizationApplied: resolved.optimizationApplied || (params.optimizeResponse ?? false),
+            exitCode: 0,
+            httpStatus: result.httpStatus ?? undefined,
+            status: "completed",
+            inputTokens: result.usage?.inputTokens,
+            outputTokens: result.usage?.outputTokens,
+            cacheReadTokens: result.usage?.cacheReadTokens,
+            costUsd: result.usage?.costUsd,
+        }, runtimeArg);
+        return buildApiSuccessResponse(text, corrId, providerRuntime.name, {
+            model: result.model,
+            httpStatus: result.httpStatus,
+            responseId: result.responseId,
+            usage: result.usage,
+            sessionId,
+            previousResponseId,
+            stalePreviousResponseCleared,
+            status: result.status,
+        });
     }
     catch (err) {
         if (err instanceof ApiModelNotAllowedError) {
@@ -2362,15 +2672,22 @@ export function handleApiProviderRequestAsync(runtimeArg, providerRuntime, param
     const toolName = `api_${providerRuntime.name}_request_async`;
     const corrId = params.correlationId ?? randomUUID();
     try {
-        if (!params.prompt || params.prompt.trim().length === 0) {
-            return createErrorResponse(toolName, 1, "prompt is required and cannot be empty", corrId);
-        }
-        const { provider, apiRequest } = buildApiProviderCall(providerRuntime, params);
+        const resolved = resolveApiProviderInput(params, toolName, corrId);
+        if (!resolved.ok)
+            return resolved.error;
+        const { provider, apiRequest } = buildApiProviderCall(providerRuntime, params, resolved.userContent, resolved.system);
         const outcome = runtimeArg.asyncJobManager.startHttpJob({
             provider,
             apiRequest,
             correlationId: corrId,
             writeFlightStart: true,
+            forceRefresh: params.forceRefresh,
+            flightRecorderEntry: {
+                model: apiRequest.model,
+                prompt: resolved.effectivePrompt,
+                stablePrefixHash: resolved.stablePrefixHash ?? undefined,
+                stablePrefixTokens: resolved.stablePrefixTokens ?? undefined,
+            },
         });
         return buildDeferredToolResponse({
             deferred: true,
@@ -2393,7 +2710,13 @@ const ApiReasoningEffortSchema = z.enum(["none", "low", "medium", "high"]);
 export function registerApiProviderTools(server, runtime, providers, asyncJobsEnabled) {
     const registered = [];
     const inputSchema = {
-        prompt: z.string().min(1).max(100000).optional().describe("Prompt text for the API provider"),
+        prompt: z
+            .string()
+            .min(1)
+            .max(100000)
+            .optional()
+            .describe("Prompt text (mutually exclusive with promptParts)"),
+        promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt { system?, tools?, context?, task }; mutually exclusive with prompt"),
         system: z.string().max(100000).optional().describe("Optional system instruction"),
         model: z
             .string()
@@ -2401,18 +2724,56 @@ export function registerApiProviderTools(server, runtime, providers, asyncJobsEn
             .optional()
             .describe("Model id; defaults to the provider default_model"),
         correlationId: z.string().optional().describe("Request trace ID (auto if omitted)"),
-        maxOutputTokens: z.number().int().positive().max(100000000).optional(),
-        temperature: z.number().finite().min(0).max(2).optional(),
-        topP: z.number().finite().min(0).max(1).optional(),
-        reasoningEffort: ApiReasoningEffortSchema.optional(),
-        timeoutMs: z.number().int().min(30_000).max(3_600_000).optional(),
+        maxOutputTokens: z
+            .number()
+            .int()
+            .positive()
+            .max(100000000)
+            .optional()
+            .describe("Max output tokens. Bounded to safe integers <= 100000000. Anthropic-kind api providers default max output to 4096 tokens unless maxOutputTokens is set."),
+        temperature: z
+            .number()
+            .finite()
+            .min(0)
+            .max(2)
+            .optional()
+            .describe("Sampling temperature passed to the provider API"),
+        topP: z
+            .number()
+            .finite()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("Nucleus sampling top_p passed to the provider API"),
+        reasoningEffort: ApiReasoningEffortSchema.optional().describe("Reasoning effort (none|low|medium|high). Only forwarded by the xai adapter; ignored by other provider kinds."),
+        timeoutMs: z
+            .number()
+            .int()
+            .min(30_000)
+            .max(3_600_000)
+            .optional()
+            .describe("HTTP request timeout in ms (min 30s, max 1h, default 10m)"),
+        optimizePrompt: z.boolean().optional().describe("Optimize the prompt before sending"),
+        optimizeResponse: z
+            .boolean()
+            .optional()
+            .describe("Optimize the response text (sync path only)"),
+        forceRefresh: z.boolean().optional().describe("Bypass dedup and force a fresh request"),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Gateway session to resolve/track (sync tool; reuse keeps it alive). On the async api handler sessionId and createNewSession are currently inert."),
+        createNewSession: z
+            .boolean()
+            .optional()
+            .describe("Force a fresh session instead of reusing the active one. On the async api handler sessionId and createNewSession are currently inert."),
     };
     for (const providerRuntime of enabledApiProviders(providers)) {
         const name = providerRuntime.name;
-        server.tool(`api_${name}_request`, `Run a request against the "${name}" API provider (kind: ${providerRuntime.kind}) synchronously. Registered only when [providers.${name}] is configured and enabled.`, inputSchema, { title: `${name} API request`, readOnlyHint: false, openWorldHint: true }, async (params) => handleApiProviderRequest(runtime, providerRuntime, params));
+        server.tool(`api_${name}_request`, `Run a request against the "${name}" API provider (kind: ${providerRuntime.kind}) synchronously. Registered only when [providers.${name}] is configured and enabled. OpenRouter-kind providers require usage_include=true in their provider config for cost reporting.`, inputSchema, { title: `${name} API request`, readOnlyHint: false, openWorldHint: true }, async (params) => handleApiProviderRequest(runtime, providerRuntime, params));
         registered.push(`api_${name}_request`);
         if (asyncJobsEnabled) {
-            server.tool(`api_${name}_request_async`, `Start an async request against the "${name}" API provider; returns a jobId to poll with llm_job_status.`, inputSchema, { title: `${name} API request (async)`, readOnlyHint: false, openWorldHint: true }, async (params) => handleApiProviderRequestAsync(runtime, providerRuntime, params));
+            server.tool(`api_${name}_request_async`, `Start an async request against the "${name}" API provider; returns a jobId to poll with llm_job_status. OpenRouter-kind providers require usage_include=true in their provider config for cost reporting.`, inputSchema, { title: `${name} API request (async)`, readOnlyHint: false, openWorldHint: true }, async (params) => handleApiProviderRequestAsync(runtime, providerRuntime, params));
             registered.push(`api_${name}_request_async`);
         }
     }
@@ -2483,6 +2844,8 @@ export async function handleGeminiRequest(deps, params) {
         attachments: params.attachments,
         skipTrust: params.skipTrust,
         yolo: params.yolo,
+        project: params.project,
+        newProject: params.newProject,
     }, runtime);
     if (!("args" in prep))
         return prep;
@@ -2630,6 +2993,8 @@ export async function handleGeminiRequestAsync(deps, params) {
         attachments: params.attachments,
         skipTrust: params.skipTrust,
         yolo: params.yolo,
+        project: params.project,
+        newProject: params.newProject,
     }, runtime);
     if (!("args" in prep))
         return prep;
@@ -2759,6 +3124,9 @@ export async function handleGrokRequest(deps, params) {
         restoreCode: params.restoreCode,
         leaderSocket: params.leaderSocket,
         nativeWorktree: params.nativeWorktree,
+        worktreeRef: params.worktreeRef,
+        forkSession: params.forkSession,
+        jsonSchema: params.jsonSchema,
     }, runtime);
     if (!("args" in prep))
         return prep;
@@ -2927,6 +3295,9 @@ export async function handleGrokRequestAsync(deps, params) {
         restoreCode: params.restoreCode,
         leaderSocket: params.leaderSocket,
         nativeWorktree: params.nativeWorktree,
+        worktreeRef: params.worktreeRef,
+        forkSession: params.forkSession,
+        jsonSchema: params.jsonSchema,
     }, runtime);
     if (!("args" in prep))
         return prep;
@@ -3620,6 +3991,7 @@ export function createGatewayServer(deps = {}) {
     registerValidationTools(server, {
         asyncJobManager,
         apiProviders: enabledApiProviders(providers),
+        validationRunStore: persistence.backend === "sqlite" ? asyncJobManager.getValidationRunStore() : null,
     });
     registerWorkspaceTools(server, runtime);
     const apiProviderTools = registerApiProviderTools(server, runtime, providers, asyncJobsEnabled);
@@ -3720,7 +4092,7 @@ export function createGatewayServer(deps = {}) {
         sessionId: z
             .string()
             .optional()
-            .describe("Gateway session record to associate (uses the active session if omitted). Claude continuity itself is via continueSession (--continue); this ID is gateway bookkeeping, not a Claude-native session."),
+            .describe("On a fresh request this id is emitted as Claude --session-id <uuid> (must be a valid UUID that does not already exist). Resume the latest cwd conversation with continueSession:true. gw-* ids are not valid Claude --session-id values."),
         continueSession: z
             .boolean()
             .default(false)
@@ -3754,11 +4126,11 @@ export function createGatewayServer(deps = {}) {
         systemPrompt: z
             .string()
             .optional()
-            .describe("Claude --system-prompt: replace the system prompt entirely."),
+            .describe("Claude --system-prompt: replace the system prompt entirely. Mutually exclusive with appendSystemPrompt."),
         appendSystemPrompt: z
             .string()
             .optional()
-            .describe("Claude --append-system-prompt: append to the existing system prompt."),
+            .describe("Claude --append-system-prompt: append to the existing system prompt. Mutually exclusive with systemPrompt."),
         maxBudgetUsd: z
             .number()
             .positive()
@@ -3786,7 +4158,7 @@ export function createGatewayServer(deps = {}) {
         jsonSchema: z
             .union([z.string(), z.record(z.string(), z.unknown())])
             .optional()
-            .describe("Claude --json-schema: JSON Schema literal (NOT a path) constraining structured output. Object values are JSON.stringify-d; string values are passed verbatim. Use with outputFormat='json'."),
+            .describe("Claude --json-schema: JSON Schema literal (NOT a path) constraining structured output. Object values are JSON.stringify-d; string values are passed verbatim. Use with outputFormat='json'. 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."),
         addDir: z
             .array(z.string())
             .optional()
@@ -3814,11 +4186,11 @@ export function createGatewayServer(deps = {}) {
         approvalStrategy: z
             .enum(["legacy", "mcp_managed"])
             .default("legacy")
-            .describe("Approval strategy"),
+            .describe("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."),
         approvalPolicy: z
             .enum(["strict", "balanced", "permissive"])
             .optional()
-            .describe("Approval policy override"),
+            .describe("Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy."),
         mcpServers: z.array(mcpServerEnum()).default([]).describe("MCP servers exposed to Claude"),
         strictMcpConfig: z
             .boolean()
@@ -3833,7 +4205,7 @@ export function createGatewayServer(deps = {}) {
             .min(30_000)
             .max(3_600_000)
             .optional()
-            .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
+            .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default). Idle enforcement applies only when outputFormat is stream-json; it is ignored for text/json."),
         forceRefresh: z
             .boolean()
             .default(false)
@@ -4060,7 +4432,7 @@ export function createGatewayServer(deps = {}) {
             .optional()
             .describe("Prompt text for Codex (mutually exclusive with promptParts)"),
         promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking."),
-        model: z.string().optional().describe("Model name or alias (e.g. gpt-5.4, latest)"),
+        model: z.string().optional().describe("Model name or alias (e.g. gpt-5.5, gpt-5.4, latest)"),
         fullAuto: z
             .boolean()
             .default(false)
@@ -4068,7 +4440,7 @@ export function createGatewayServer(deps = {}) {
         sandboxMode: z
             .enum(CODEX_SANDBOX_MODES)
             .optional()
-            .describe("Codex --sandbox: read-only|workspace-write|danger-full-access."),
+            .describe("Codex --sandbox. Omit = Codex exec built-in default (read-only; cannot write files). Pass workspace-write to let Codex edit files in the working dir, or danger-full-access for unrestricted access."),
         askForApproval: z
             .enum(CODEX_ASK_FOR_APPROVAL_MODES)
             .optional()
@@ -4084,11 +4456,11 @@ export function createGatewayServer(deps = {}) {
         approvalStrategy: z
             .enum(["legacy", "mcp_managed"])
             .default("legacy")
-            .describe("Approval strategy"),
+            .describe("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."),
         approvalPolicy: z
             .enum(["strict", "balanced", "permissive"])
             .optional()
-            .describe("Approval policy override"),
+            .describe("Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy."),
         mcpServers: z
             .array(mcpServerEnum())
             .default([])
@@ -4096,11 +4468,11 @@ export function createGatewayServer(deps = {}) {
         sessionId: z
             .string()
             .optional()
-            .describe("Codex session UUID to resume via `codex exec resume <ID>`. Must be a real Codex session ID (from `~/.codex/sessions/` or the `codex resume` picker). Gateway-generated `gw-*` IDs are rejected."),
+            .describe("Codex session UUID to resume via `codex exec resume <ID>`. Must be a real Codex session ID (from `~/.codex/sessions/` or the `codex resume` picker). Gateway-generated `gw-*` IDs are rejected. For a brand-new session no resumable sessionId is returned; continue with resumeLatest:true or a real Codex UUID."),
         resumeLatest: z
             .boolean()
             .default(false)
-            .describe("Resume the most recent Codex session in the current cwd via `codex exec resume --last`. Ignored if sessionId is set."),
+            .describe("Resume the most recent Codex session via `codex exec resume --last`. Ignored if sessionId is set. A brand-new session returns no resumable sessionId; continue with resumeLatest:true or a real Codex UUID."),
         createNewSession: z.boolean().default(false).describe("Force a fresh session (no resume)"),
         correlationId: z.string().optional().describe("Request trace ID (auto if omitted)"),
         optimizePrompt: z.boolean().default(false).describe("Optimize prompt before execution"),
@@ -4255,7 +4627,12 @@ export function createGatewayServer(deps = {}) {
                     errorMessage: stderr || `Exit code ${code}`,
                     status: "failed",
                 }, runtime);
-                return createErrorResponse("codex", code, stderr, corrId);
+                const codexErrorDetail = stderr && stderr.trim().length > 0 ? stderr : codexDisplayText(stdout);
+                const codexResumeHint = sessionId &&
+                    /not found|no such|unknown session|does not exist|invalid session/i.test(codexErrorDetail)
+                    ? `\n\nSession ${sessionId} could not be resumed. Codex session IDs are UUIDs under ~/.codex/sessions/; verify the id, omit sessionId, or set createNewSession:true.`
+                    : "";
+                return createErrorResponse("codex", code, `${codexErrorDetail}${codexResumeHint}`, corrId);
             }
             wasSuccessful = true;
             let effectiveSessionId = sessionId;
@@ -4339,7 +4716,7 @@ export function createGatewayServer(deps = {}) {
         sandboxMode: z
             .enum(CODEX_SANDBOX_MODES)
             .optional()
-            .describe("Codex --sandbox: read-only|workspace-write|danger-full-access."),
+            .describe("Codex --sandbox. Omit = Codex exec built-in default (read-only; cannot write files). Pass workspace-write to let Codex edit files in the working dir, or danger-full-access for unrestricted access."),
         askForApproval: z
             .enum(CODEX_ASK_FOR_APPROVAL_MODES)
             .optional()
@@ -4412,7 +4789,12 @@ export function createGatewayServer(deps = {}) {
             const { stdout, stderr, code } = result;
             durationMs = Math.max(0, Date.now() - startTime);
             if (code !== 0) {
-                return createErrorResponse("codex", code, stderr, corrId);
+                const codexErrorDetail = stderr && stderr.trim().length > 0 ? stderr : codexDisplayText(stdout);
+                const codexResumeHint = sessionId &&
+                    /not found|no such|unknown session|does not exist|invalid session/i.test(codexErrorDetail)
+                    ? `\n\nSession ${sessionId} could not be resumed. Codex session IDs are UUIDs under ~/.codex/sessions/; verify the id, omit sessionId, or set createNewSession:true.`
+                    : "";
+                return createErrorResponse("codex", code, `${codexErrorDetail}${codexResumeHint}`, corrId);
             }
             wasSuccessful = true;
             return {
@@ -4442,21 +4824,24 @@ export function createGatewayServer(deps = {}) {
         sessionId: z
             .string()
             .optional()
-            .describe("Antigravity conversation ID to resume (emits --conversation <id>)"),
-        resumeLatest: z.boolean().default(false).describe("Continue the most recent conversation"),
+            .describe("Antigravity conversation ID to resume (emits --conversation <id>). agy owns conversation ids; a fresh request returns no resumable sessionId, continue via resumeLatest:true."),
+        resumeLatest: z
+            .boolean()
+            .default(false)
+            .describe("Continue the most recent conversation. agy owns conversation ids; a fresh request returns no resumable sessionId, continue via resumeLatest:true."),
         createNewSession: z.boolean().default(false).describe("Force new session"),
         approvalMode: z
             .enum(GEMINI_APPROVAL_MODES)
             .optional()
-            .describe("Approval: default|auto_edit|yolo|plan"),
+            .describe("Approval mode. Only default (prompted) and yolo (auto-approve all, emits --dangerously-skip-permissions) work with the Antigravity agy headless path; auto_edit and plan are rejected at request time (agy has no headless accept-edits/plan mode)."),
         approvalStrategy: z
             .enum(["legacy", "mcp_managed"])
             .default("legacy")
-            .describe("Approval strategy"),
+            .describe("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."),
         approvalPolicy: z
             .enum(["strict", "balanced", "permissive"])
             .optional()
-            .describe("Approval policy override"),
+            .describe("Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy."),
         mcpServers: z
             .array(mcpServerEnum())
             .default([])
@@ -4486,7 +4871,7 @@ export function createGatewayServer(deps = {}) {
         outputFormat: z
             .enum(["text", "json", "stream-json"])
             .default("text")
-            .describe("Antigravity CLI currently supports text output only through the gateway; json and stream-json are rejected."),
+            .describe("Output format. The Antigravity agy headless path emits text only; json and stream-json are rejected at request time. Per-request token usage and cost are therefore not available for gemini."),
         sandbox: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.sandbox.describe("Run Antigravity in sandbox mode (--sandbox)"),
         policyFiles: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.policyFiles.describe("Unsupported for Antigravity CLI; non-empty values are rejected."),
         adminPolicyFiles: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.adminPolicyFiles.describe("Unsupported for Antigravity CLI; non-empty values are rejected."),
@@ -4499,6 +4884,15 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .optional()
             .describe("Emit `--dangerously-skip-permissions` to auto-approve all actions. Routed through the same approval gate. Under mcp_managed the gate still decides."),
+        project: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Antigravity 1.0.13 --project <ID>: select the project for this session. Mutually exclusive with newProject."),
+        newProject: z
+            .boolean()
+            .optional()
+            .describe("Antigravity 1.0.13 --new-project: create a new project for this session. Mutually exclusive with project."),
         workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
         worktree: WORKTREE_SCHEMA.optional(),
     }, {
@@ -4507,7 +4901,7 @@ export function createGatewayServer(deps = {}) {
         destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true,
-    }, async ({ prompt, promptParts, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, outputFormat, sandbox, policyFiles, adminPolicyFiles, attachments, skipTrust, yolo, workspace, worktree, }) => {
+    }, async ({ prompt, promptParts, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, outputFormat, sandbox, policyFiles, adminPolicyFiles, attachments, skipTrust, yolo, project, newProject, workspace, worktree, }) => {
         return handleGeminiRequest({ sessionManager, logger, runtime }, {
             prompt,
             promptParts,
@@ -4533,6 +4927,8 @@ export function createGatewayServer(deps = {}) {
             attachments,
             skipTrust,
             yolo,
+            project,
+            newProject,
             workspace,
             worktree,
         });
@@ -4554,11 +4950,11 @@ export function createGatewayServer(deps = {}) {
         sessionId: z
             .string()
             .optional()
-            .describe("Provider-native session ID to resume (emits --resume <id>; use resumeLatest for --continue)"),
+            .describe("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."),
         resumeLatest: z
             .boolean()
             .default(false)
-            .describe("Resume most recent Grok session in cwd (--continue)"),
+            .describe("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."),
         createNewSession: z.boolean().default(false).describe("Force new session"),
         alwaysApprove: z
             .boolean()
@@ -4567,15 +4963,15 @@ export function createGatewayServer(deps = {}) {
         permissionMode: z
             .enum(["default", "acceptEdits", "auto", "dontAsk", "bypassPermissions", "plan"])
             .optional()
-            .describe("Grok permission mode"),
+            .describe("Grok permission mode: default|acceptEdits|auto|dontAsk|bypassPermissions|plan."),
         approvalStrategy: z
             .enum(["legacy", "mcp_managed"])
             .default("legacy")
-            .describe("Approval strategy"),
+            .describe("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."),
         approvalPolicy: z
             .enum(["strict", "balanced", "permissive"])
             .optional()
-            .describe("Approval policy override"),
+            .describe("Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy."),
         mcpServers: z
             .array(mcpServerEnum())
             .default([])
@@ -4589,7 +4985,7 @@ export function createGatewayServer(deps = {}) {
             .min(30_000)
             .max(3_600_000)
             .optional()
-            .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
+            .describe("Idle timeout in ms (min 30s, max 1h). Omit = gateway default of 600000ms (10 min) with no output before the process is killed."),
         forceRefresh: z
             .boolean()
             .default(false)
@@ -4606,6 +5002,19 @@ export function createGatewayServer(deps = {}) {
             .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`."),
+        worktreeRef: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Grok 0.2.73 --worktree-ref <REF>: git ref (branch/tag/commit) to base the native worktree on. Requires nativeWorktree."),
+        forkSession: z
+            .boolean()
+            .optional()
+            .describe("Grok 0.2.73 --fork-session: when resuming (--resume/--continue), fork into a new session ID instead of reusing the original."),
+        jsonSchema: z
+            .union([z.string().min(1), z.record(z.string(), z.unknown())])
+            .optional()
+            .describe("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."),
         workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
         worktree: WORKTREE_SCHEMA.optional(),
     }, {
@@ -4614,7 +5023,7 @@ export function createGatewayServer(deps = {}) {
         destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true,
-    }, async ({ prompt, promptParts, model, transport, 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, workspace, worktree, }) => {
+    }, async ({ prompt, promptParts, model, transport, 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, worktreeRef, forkSession, jsonSchema, workspace, worktree, }) => {
         return handleGrokRequest({ sessionManager, logger, runtime }, {
             prompt,
             promptParts,
@@ -4666,6 +5075,9 @@ export function createGatewayServer(deps = {}) {
             restoreCode,
             leaderSocket,
             nativeWorktree,
+            worktreeRef,
+            forkSession,
+            jsonSchema,
             workspace,
             worktree,
         });
@@ -4676,7 +5088,7 @@ export function createGatewayServer(deps = {}) {
             .min(1, "Prompt cannot be empty")
             .max(100000, "Prompt too long (max 100k chars)")
             .optional()
-            .describe("Prompt text for Devin CLI"),
+            .describe("Prompt text for Devin CLI. Required in practice; promptFile is additive (loads an initial prompt from a file)."),
         model: z.string().optional().describe("Model name or alias (e.g. opus, latest)"),
         transport: z
             .enum(["cli", "acp"])
@@ -4685,7 +5097,7 @@ export function createGatewayServer(deps = {}) {
         permissionMode: z
             .enum(["auto", "smart", "dangerous"])
             .optional()
-            .describe("Devin CLI permission mode (--permission-mode). auto auto-approves read-only tools; smart additionally auto-runs actions a fast model judges safe; dangerous auto-approves all."),
+            .describe("Devin CLI permission mode (--permission-mode). auto auto-approves read-only tools; smart additionally auto-runs actions a fast model judges safe; dangerous auto-approves all. When omitted, Devin uses its own headless default; pass auto or smart for unattended runs."),
         promptFile: z
             .string()
             .optional()
@@ -4693,11 +5105,11 @@ export function createGatewayServer(deps = {}) {
         sessionId: z
             .string()
             .optional()
-            .describe("Devin session ID to resume (emits --resume <id>; use resumeLatest for --continue)"),
+            .describe("Devin 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."),
         resumeLatest: z
             .boolean()
             .default(false)
-            .describe("Resume the most recent Devin session in cwd (--continue)"),
+            .describe("Resume the most recent Devin session in cwd (--continue). Note: the gw-* id minted for a brand-new session is not resumable via sessionId; continue with resumeLatest:true."),
         createNewSession: z.boolean().default(false).describe("Force a new session"),
         correlationId: z.string().optional().describe("Request trace ID (auto if omitted)"),
         optimizePrompt: z.boolean().default(false).describe("Optimize prompt before execution"),
@@ -4736,7 +5148,7 @@ export function createGatewayServer(deps = {}) {
             forceRefresh,
         });
     });
-    server.tool("mistral_request", "Run a Mistral Vibe 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.", {
+    server.tool("mistral_request", "Run a Mistral Vibe 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. Defaults to --agent auto-approve (unattended tool execution); pass permissionMode plan or accept-edits for safer runs.", {
         prompt: z
             .string()
             .min(1, "Prompt cannot be empty")
@@ -4759,11 +5171,11 @@ export function createGatewayServer(deps = {}) {
         sessionId: z
             .string()
             .optional()
-            .describe("Session ID (user-provided CLI handle for --resume). Current Vibe defaults session logging on; doctor flags explicit [session_logging] enabled = false."),
+            .describe("Session ID (user-provided CLI handle for --resume). Current Vibe defaults session logging on; doctor flags explicit [session_logging] enabled = false. Note: the gw-* id minted for a brand-new session is not resumable via sessionId; continue with resumeLatest:true."),
         resumeLatest: z
             .boolean()
             .default(false)
-            .describe("Resume most recent Vibe session in cwd (--continue)"),
+            .describe("Resume most recent Vibe session in cwd (--continue). Note: the gw-* id minted for a brand-new session is not resumable via sessionId; continue with resumeLatest:true."),
         createNewSession: z.boolean().default(false).describe("Force new session"),
         permissionMode: z
             .string()
@@ -4772,11 +5184,11 @@ export function createGatewayServer(deps = {}) {
         approvalStrategy: z
             .enum(["legacy", "mcp_managed"])
             .default("legacy")
-            .describe("Approval strategy"),
+            .describe("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."),
         approvalPolicy: z
             .enum(["strict", "balanced", "permissive"])
             .optional()
-            .describe("Approval policy override"),
+            .describe("Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy."),
         mcpServers: z
             .array(mcpServerEnum())
             .default([])
@@ -4878,7 +5290,7 @@ export function createGatewayServer(deps = {}) {
             sessionId: z
                 .string()
                 .optional()
-                .describe("Gateway session record to associate (uses the active session if omitted). Claude continuity itself is via continueSession (--continue); this ID is gateway bookkeeping, not a Claude-native session."),
+                .describe("On a fresh request this id is emitted as Claude --session-id <uuid> (must be a valid UUID that does not already exist). Resume the latest cwd conversation with continueSession:true. gw-* ids are not valid Claude --session-id values."),
             continueSession: z
                 .boolean()
                 .default(false)
@@ -4912,11 +5324,11 @@ export function createGatewayServer(deps = {}) {
             systemPrompt: z
                 .string()
                 .optional()
-                .describe("Claude --system-prompt: replace the system prompt entirely."),
+                .describe("Claude --system-prompt: replace the system prompt entirely. Mutually exclusive with appendSystemPrompt."),
             appendSystemPrompt: z
                 .string()
                 .optional()
-                .describe("Claude --append-system-prompt: append to the existing system prompt."),
+                .describe("Claude --append-system-prompt: append to the existing system prompt. Mutually exclusive with systemPrompt."),
             maxBudgetUsd: z
                 .number()
                 .positive()
@@ -4944,7 +5356,7 @@ export function createGatewayServer(deps = {}) {
             jsonSchema: z
                 .union([z.string(), z.record(z.string(), z.unknown())])
                 .optional()
-                .describe("Claude --json-schema: JSON Schema literal (NOT a path) constraining structured output. Object values are JSON.stringify-d; string values are passed verbatim. Use with outputFormat='json'."),
+                .describe("Claude --json-schema: JSON Schema literal (NOT a path) constraining structured output. Object values are JSON.stringify-d; string values are passed verbatim. Use with outputFormat='json'. 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."),
             addDir: z
                 .array(z.string())
                 .optional()
@@ -4972,11 +5384,11 @@ export function createGatewayServer(deps = {}) {
             approvalStrategy: z
                 .enum(["legacy", "mcp_managed"])
                 .default("legacy")
-                .describe("Approval strategy"),
+                .describe("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."),
             approvalPolicy: z
                 .enum(["strict", "balanced", "permissive"])
                 .optional()
-                .describe("Approval policy override"),
+                .describe("Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy."),
             mcpServers: z.array(mcpServerEnum()).default([]).describe("MCP servers exposed to Claude"),
             strictMcpConfig: z
                 .boolean()
@@ -4990,7 +5402,7 @@ export function createGatewayServer(deps = {}) {
                 .min(30_000)
                 .max(3_600_000)
                 .optional()
-                .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
+                .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default). Idle enforcement applies only when outputFormat is stream-json; it is ignored for text/json."),
             forceRefresh: z
                 .boolean()
                 .default(false)
@@ -5137,7 +5549,10 @@ export function createGatewayServer(deps = {}) {
                 .optional()
                 .describe("Prompt text for Codex (mutually exclusive with promptParts)"),
             promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking."),
-            model: z.string().optional().describe("Model name or alias (e.g. gpt-5.4, latest)"),
+            model: z
+                .string()
+                .optional()
+                .describe("Model name or alias (e.g. gpt-5.5, gpt-5.4, latest)"),
             fullAuto: z
                 .boolean()
                 .default(false)
@@ -5145,7 +5560,7 @@ export function createGatewayServer(deps = {}) {
             sandboxMode: z
                 .enum(CODEX_SANDBOX_MODES)
                 .optional()
-                .describe("Codex --sandbox: read-only|workspace-write|danger-full-access."),
+                .describe("Codex --sandbox. Omit = Codex exec built-in default (read-only; cannot write files). Pass workspace-write to let Codex edit files in the working dir, or danger-full-access for unrestricted access."),
             askForApproval: z
                 .enum(CODEX_ASK_FOR_APPROVAL_MODES)
                 .optional()
@@ -5161,11 +5576,11 @@ export function createGatewayServer(deps = {}) {
             approvalStrategy: z
                 .enum(["legacy", "mcp_managed"])
                 .default("legacy")
-                .describe("Approval strategy"),
+                .describe("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."),
             approvalPolicy: z
                 .enum(["strict", "balanced", "permissive"])
                 .optional()
-                .describe("Approval policy override"),
+                .describe("Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy."),
             mcpServers: z
                 .array(mcpServerEnum())
                 .default([])
@@ -5173,11 +5588,11 @@ export function createGatewayServer(deps = {}) {
             sessionId: z
                 .string()
                 .optional()
-                .describe("Codex session UUID to resume via `codex exec resume <ID>`. Must be a real Codex session ID (from `~/.codex/sessions/` or the `codex resume` picker). Gateway-generated `gw-*` IDs are rejected."),
+                .describe("Codex session UUID to resume via `codex exec resume <ID>`. Must be a real Codex session ID (from `~/.codex/sessions/` or the `codex resume` picker). Gateway-generated `gw-*` IDs are rejected. For a brand-new session no resumable sessionId is returned; continue with resumeLatest:true or a real Codex UUID."),
             resumeLatest: z
                 .boolean()
                 .default(false)
-                .describe("Resume the most recent Codex session in the current cwd via `codex exec resume --last`. Ignored if sessionId is set."),
+                .describe("Resume the most recent Codex session via `codex exec resume --last`. Ignored if sessionId is set. A brand-new session returns no resumable sessionId; continue with resumeLatest:true or a real Codex UUID."),
             createNewSession: z.boolean().default(false).describe("Force a fresh session (no resume)"),
             correlationId: z.string().optional().describe("Request trace ID (auto if omitted)"),
             optimizePrompt: z.boolean().default(false).describe("Optimize prompt before execution"),
@@ -5277,21 +5692,24 @@ export function createGatewayServer(deps = {}) {
             sessionId: z
                 .string()
                 .optional()
-                .describe("Antigravity conversation ID to resume (emits --conversation <id>)"),
-            resumeLatest: z.boolean().default(false).describe("Continue the most recent conversation"),
+                .describe("Antigravity conversation ID to resume (emits --conversation <id>). agy owns conversation ids; a fresh request returns no resumable sessionId, continue via resumeLatest:true."),
+            resumeLatest: z
+                .boolean()
+                .default(false)
+                .describe("Continue the most recent conversation. agy owns conversation ids; a fresh request returns no resumable sessionId, continue via resumeLatest:true."),
             createNewSession: z.boolean().default(false).describe("Force new session"),
             approvalMode: z
                 .enum(GEMINI_APPROVAL_MODES)
                 .optional()
-                .describe("Approval: default|auto_edit|yolo|plan"),
+                .describe("Approval mode. Only default (prompted) and yolo (auto-approve all, emits --dangerously-skip-permissions) work with the Antigravity agy headless path; auto_edit and plan are rejected at request time (agy has no headless accept-edits/plan mode)."),
             approvalStrategy: z
                 .enum(["legacy", "mcp_managed"])
                 .default("legacy")
-                .describe("Approval strategy"),
+                .describe("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."),
             approvalPolicy: z
                 .enum(["strict", "balanced", "permissive"])
                 .optional()
-                .describe("Approval policy override"),
+                .describe("Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy."),
             mcpServers: z
                 .array(mcpServerEnum())
                 .default([])
@@ -5320,7 +5738,7 @@ export function createGatewayServer(deps = {}) {
             outputFormat: z
                 .enum(["text", "json", "stream-json"])
                 .default("text")
-                .describe("Antigravity CLI currently supports text output only through the gateway; json and stream-json are rejected."),
+                .describe("Output format. The Antigravity agy headless path emits text only; json and stream-json are rejected at request time. Per-request token usage and cost are therefore not available for gemini."),
             sandbox: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.sandbox.describe("Run Antigravity in sandbox mode (--sandbox)"),
             policyFiles: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.policyFiles.describe("Unsupported for Antigravity CLI; non-empty values are rejected."),
             adminPolicyFiles: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.adminPolicyFiles.describe("Unsupported for Antigravity CLI; non-empty values are rejected."),
@@ -5333,6 +5751,15 @@ export function createGatewayServer(deps = {}) {
                 .boolean()
                 .optional()
                 .describe("Emit `--dangerously-skip-permissions` to auto-approve all actions. Routed through the same approval gate. Under mcp_managed the gate still decides."),
+            project: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Antigravity 1.0.13 --project <ID>: select the project for this session. Mutually exclusive with newProject."),
+            newProject: z
+                .boolean()
+                .optional()
+                .describe("Antigravity 1.0.13 --new-project: create a new project for this session. Mutually exclusive with project."),
             workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
             worktree: WORKTREE_SCHEMA.optional(),
         }, {
@@ -5341,7 +5768,7 @@ export function createGatewayServer(deps = {}) {
             destructiveHint: true,
             idempotentHint: false,
             openWorldHint: true,
-        }, async ({ prompt, promptParts, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, outputFormat, sandbox, policyFiles, adminPolicyFiles, attachments, skipTrust, yolo, workspace, worktree, }) => {
+        }, async ({ prompt, promptParts, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, outputFormat, sandbox, policyFiles, adminPolicyFiles, attachments, skipTrust, yolo, project, newProject, workspace, worktree, }) => {
             return handleGeminiRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
                 promptParts,
@@ -5366,6 +5793,8 @@ export function createGatewayServer(deps = {}) {
                 attachments,
                 skipTrust,
                 yolo,
+                project,
+                newProject,
                 workspace,
                 worktree,
             });
@@ -5386,11 +5815,11 @@ export function createGatewayServer(deps = {}) {
             sessionId: z
                 .string()
                 .optional()
-                .describe("Provider-native session ID to resume (emits --resume <id>; use resumeLatest for --continue)"),
+                .describe("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."),
             resumeLatest: z
                 .boolean()
                 .default(false)
-                .describe("Resume most recent Grok session in cwd (--continue)"),
+                .describe("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."),
             createNewSession: z.boolean().default(false).describe("Force new session"),
             alwaysApprove: z
                 .boolean()
@@ -5399,7 +5828,7 @@ export function createGatewayServer(deps = {}) {
             permissionMode: z
                 .enum(["default", "acceptEdits", "auto", "dontAsk", "bypassPermissions", "plan"])
                 .optional()
-                .describe("Grok permission mode"),
+                .describe("Grok permission mode: default|acceptEdits|auto|dontAsk|bypassPermissions|plan."),
             effort: z
                 .enum(["low", "medium", "high", "xhigh", "max"])
                 .optional()
@@ -5408,11 +5837,11 @@ export function createGatewayServer(deps = {}) {
             approvalStrategy: z
                 .enum(["legacy", "mcp_managed"])
                 .default("legacy")
-                .describe("Approval strategy"),
+                .describe("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."),
             approvalPolicy: z
                 .enum(["strict", "balanced", "permissive"])
                 .optional()
-                .describe("Approval policy override"),
+                .describe("Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy."),
             mcpServers: z
                 .array(mcpServerEnum())
                 .default([])
@@ -5433,7 +5862,7 @@ export function createGatewayServer(deps = {}) {
                 .min(30_000)
                 .max(3_600_000)
                 .optional()
-                .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
+                .describe("Idle timeout in ms (min 30s, max 1h). Omit = gateway default of 600000ms (10 min) with no output before the process is killed."),
             forceRefresh: z
                 .boolean()
                 .default(false)
@@ -5546,6 +5975,19 @@ export function createGatewayServer(deps = {}) {
                 .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`."),
+            worktreeRef: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Grok 0.2.73 --worktree-ref <REF>: git ref (branch/tag/commit) to base the native worktree on. Requires nativeWorktree."),
+            forkSession: z
+                .boolean()
+                .optional()
+                .describe("Grok 0.2.73 --fork-session: when resuming (--resume/--continue), fork into a new session ID instead of reusing the original."),
+            jsonSchema: z
+                .union([z.string().min(1), z.record(z.string(), z.unknown())])
+                .optional()
+                .describe("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."),
             workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
             worktree: WORKTREE_SCHEMA.optional(),
         }, {
@@ -5554,7 +5996,7 @@ export function createGatewayServer(deps = {}) {
             destructiveHint: true,
             idempotentHint: false,
             openWorldHint: true,
-        }, 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, workspace, 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, worktreeRef, forkSession, jsonSchema, workspace, worktree, }) => {
             return handleGrokRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
                 promptParts,
@@ -5604,6 +6046,9 @@ export function createGatewayServer(deps = {}) {
                 restoreCode,
                 leaderSocket,
                 nativeWorktree,
+                worktreeRef,
+                forkSession,
+                jsonSchema,
                 workspace,
                 worktree,
             });
@@ -5614,12 +6059,12 @@ export function createGatewayServer(deps = {}) {
                 .min(1, "Prompt cannot be empty")
                 .max(100000, "Prompt too long (max 100k chars)")
                 .optional()
-                .describe("Prompt text for Devin CLI"),
+                .describe("Prompt text for Devin CLI. Required in practice; promptFile is additive (loads an initial prompt from a file)."),
             model: z.string().optional().describe("Model name or alias (e.g. opus, latest)"),
             permissionMode: z
                 .enum(["auto", "smart", "dangerous"])
                 .optional()
-                .describe("Devin CLI permission mode (--permission-mode). auto, smart, or dangerous."),
+                .describe("Devin CLI permission mode (--permission-mode). auto, smart, or dangerous. When omitted, Devin uses its own headless default; pass auto or smart for unattended runs."),
             promptFile: z
                 .string()
                 .optional()
@@ -5627,11 +6072,11 @@ export function createGatewayServer(deps = {}) {
             sessionId: z
                 .string()
                 .optional()
-                .describe("Devin session ID to resume (--resume <id>; use resumeLatest for --continue)"),
+                .describe("Devin session ID to resume (--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."),
             resumeLatest: z
                 .boolean()
                 .default(false)
-                .describe("Resume the most recent Devin session in cwd (--continue)"),
+                .describe("Resume the most recent Devin session in cwd (--continue). Note: the gw-* id minted for a brand-new session is not resumable via sessionId; continue with resumeLatest:true."),
             createNewSession: z.boolean().default(false).describe("Force a new session"),
             correlationId: z.string().optional().describe("Request trace ID (auto if omitted)"),
             optimizePrompt: z.boolean().default(false).describe("Optimize prompt before execution"),
@@ -5686,11 +6131,11 @@ export function createGatewayServer(deps = {}) {
             sessionId: z
                 .string()
                 .optional()
-                .describe("Session ID (user-provided CLI handle for --resume). Current Vibe defaults session logging on; doctor flags explicit [session_logging] enabled = false."),
+                .describe("Session ID (user-provided CLI handle for --resume). Current Vibe defaults session logging on; doctor flags explicit [session_logging] enabled = false. Note: the gw-* id minted for a brand-new session is not resumable via sessionId; continue with resumeLatest:true."),
             resumeLatest: z
                 .boolean()
                 .default(false)
-                .describe("Resume most recent Vibe session in cwd (--continue)"),
+                .describe("Resume most recent Vibe session in cwd (--continue). Note: the gw-* id minted for a brand-new session is not resumable via sessionId; continue with resumeLatest:true."),
             createNewSession: z.boolean().default(false).describe("Force new session"),
             permissionMode: z
                 .string()
@@ -5699,11 +6144,11 @@ export function createGatewayServer(deps = {}) {
             approvalStrategy: z
                 .enum(["legacy", "mcp_managed"])
                 .default("legacy")
-                .describe("Approval strategy"),
+                .describe("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."),
             approvalPolicy: z
                 .enum(["strict", "balanced", "permissive"])
                 .optional()
-                .describe("Approval policy override"),
+                .describe("Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy."),
             mcpServers: z
                 .array(mcpServerEnum())
                 .default([])
@@ -6084,10 +6529,10 @@ export function createGatewayServer(deps = {}) {
             ],
         };
     });
-    server.tool("list_models", "List models, aliases, and defaults for one provider CLI (claude|codex|gemini|grok|mistral).", {
+    server.tool("list_models", "List models, aliases, and defaults for one provider CLI (claude|codex|gemini|grok|mistral|devin), or omit cli to list all providers.", {
         cli: z
-            .preprocess(value => (value === "" || value === null ? undefined : value), z.enum(["claude", "codex", "gemini", "grok", "mistral"]).optional())
-            .describe("CLI filter (claude|codex|gemini|grok|mistral)"),
+            .preprocess(value => (value === "" || value === null ? undefined : value), CLI_TYPE_ENUM.optional())
+            .describe("CLI filter (claude|codex|gemini|grok|mistral|devin)"),
     }, {
         title: "Provider models",
         readOnlyHint: true,
@@ -6099,10 +6544,10 @@ export function createGatewayServer(deps = {}) {
         const result = cli ? { [cli]: cliInfo[cli] } : cliInfo;
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("provider_tool_capabilities", "Report provider tool/feature capabilities and discovered local skill/tool integrations for claude|codex|gemini|grok|grok_api|mistral.", {
+    server.tool("provider_tool_capabilities", "Report provider tool/feature capabilities and discovered local skill/tool integrations for claude|codex|gemini|grok|mistral|devin|grok_api.", {
         cli: z
-            .preprocess(value => (value === "" || value === null ? undefined : value), z.enum(["claude", "codex", "gemini", "grok", "grok_api", "mistral"]).optional())
-            .describe("Provider filter (claude|codex|gemini|grok|grok_api|mistral)"),
+            .preprocess(value => (value === "" || value === null ? undefined : value), z.enum(["claude", "codex", "gemini", "grok", "mistral", "devin", "grok_api"]).optional())
+            .describe("Provider filter (claude|codex|gemini|grok|mistral|devin|grok_api)"),
         includeSkills: z
             .boolean()
             .default(true)
@@ -6137,10 +6582,10 @@ export function createGatewayServer(deps = {}) {
         });
         return { content: [{ type: "text", text: JSON.stringify(capabilities, null, 2) }] };
     });
-    server.tool("cli_versions", "Report installed provider CLI versions, availability, and login status for all five providers or one.", {
+    server.tool("cli_versions", "Report installed provider CLI versions, availability, and login status for all six providers (claude|codex|gemini|grok|mistral|devin) or one.", {
         cli: z
-            .preprocess(value => (value === "" || value === null ? undefined : value), z.enum(["claude", "codex", "gemini", "grok", "mistral"]).optional())
-            .describe("CLI filter (claude|codex|gemini|grok|mistral)"),
+            .preprocess(value => (value === "" || value === null ? undefined : value), CLI_TYPE_ENUM.optional())
+            .describe("CLI filter (claude|codex|gemini|grok|mistral|devin)"),
     }, {
         title: "Provider CLI versions",
         readOnlyHint: true,
@@ -6154,7 +6599,7 @@ export function createGatewayServer(deps = {}) {
     server.tool("upstream_contracts", "Return the gateway's declared provider CLI contracts; with probeInstalled true, diff against installed --help surfaces to detect flag drift.", {
         cli: z
             .preprocess(value => (value === "" || value === null ? undefined : value), CLI_TYPE_ENUM.optional())
-            .describe("CLI filter (claude|codex|gemini|grok|mistral)"),
+            .describe("CLI filter (claude|codex|gemini|grok|mistral|devin)"),
         probeInstalled: z
             .boolean()
             .default(false)
@@ -6172,7 +6617,7 @@ export function createGatewayServer(deps = {}) {
     server.tool("provider_subcommands_list", "Return a compact, filterable read-only catalog of declared provider CLI subcommands without flags or raw help.", {
         provider: z
             .preprocess(value => (value === "" || value === null ? undefined : value), CLI_TYPE_ENUM.optional())
-            .describe("Optional provider filter (claude|codex|gemini|grok|mistral)"),
+            .describe("Optional provider filter (claude|codex|gemini|grok|mistral|devin)"),
         tier: z
             .enum(["catalog", "inspect", "execute_candidate", "diagnostic"])
             .optional()
@@ -6222,7 +6667,7 @@ export function createGatewayServer(deps = {}) {
         };
     });
     server.tool("provider_subcommand_contract", "Return the detailed read-only contract for exactly one declared provider CLI subcommand.", {
-        provider: CLI_TYPE_ENUM.describe("Provider (claude|codex|gemini|grok|mistral)"),
+        provider: CLI_TYPE_ENUM.describe("Provider (claude|codex|gemini|grok|mistral|devin)"),
         commandPath: z.array(z.string().min(1)).min(1).describe("Command path segments"),
     }, {
         title: "Provider subcommand contract",
@@ -6246,7 +6691,7 @@ export function createGatewayServer(deps = {}) {
     server.tool("provider_subcommand_drift", "Probe declared provider subcommand --help surfaces and return compact drift rows without raw help output.", {
         provider: z
             .preprocess(value => (value === "" || value === null ? undefined : value), CLI_TYPE_ENUM.optional())
-            .describe("Optional provider filter (claude|codex|gemini|grok|mistral)"),
+            .describe("Optional provider filter (claude|codex|gemini|grok|mistral|devin)"),
         includeClean: z
             .boolean()
             .default(false)
@@ -6297,7 +6742,7 @@ export function createGatewayServer(deps = {}) {
         };
     });
     server.tool("cli_upgrade", "Plan (dryRun, default true) or execute an upgrade for one provider CLI using its native update mechanism.", {
-        cli: z.enum(["claude", "codex", "gemini", "grok", "mistral"]).describe("CLI to upgrade"),
+        cli: CLI_TYPE_ENUM.describe("CLI to upgrade (claude|codex|gemini|grok|mistral|devin)"),
         target: z
             .string()
             .min(1)
@@ -6351,8 +6796,12 @@ export function createGatewayServer(deps = {}) {
             };
         }
     });
-    server.tool("session_create", "Create a gateway session record for a provider. NOTE: this is gateway bookkeeping (gw-* ID), not a provider-native session — Codex resume needs a real Codex UUID.", {
-        cli: SESSION_PROVIDER_ENUM.describe("Provider type (claude|codex|gemini|grok|mistral|grok-api)"),
+    const sessionProviderValues = sessionProviderValuesFor(providers);
+    const sessionProviderEnum = sessionProviderValues.length > SESSION_PROVIDER_VALUES.length
+        ? z.enum(sessionProviderValues)
+        : SESSION_PROVIDER_ENUM;
+    server.tool("session_create", "Create a gateway session record for a provider. NOTE: this is gateway bookkeeping (a plain UUID), not a provider-native session; Codex resume needs a real Codex UUID.", {
+        cli: sessionProviderEnum.describe("Provider type (claude|codex|gemini|grok|mistral|grok-api)"),
         description: z.string().optional().describe("Session description"),
         setAsActive: z.boolean().default(true).describe("Set as active session"),
     }, {
@@ -6391,7 +6840,9 @@ export function createGatewayServer(deps = {}) {
         }
     });
     server.tool("session_list", "List gateway session records and the active session per provider, optionally filtered by provider.", {
-        cli: SESSION_PROVIDER_ENUM.optional().describe("Provider filter (claude|codex|gemini|grok|mistral|grok-api)"),
+        cli: sessionProviderEnum
+            .optional()
+            .describe("Provider filter (claude|codex|gemini|grok|mistral|grok-api)"),
     }, {
         title: "List sessions",
         readOnlyHint: true,
@@ -6402,7 +6853,7 @@ export function createGatewayServer(deps = {}) {
         try {
             const caller = resolveOwnerPrincipal(getRequestContext());
             const sessions = (await sessionManager.listSessions(cli)).filter(s => principalCanAccess(s.ownerPrincipal, caller));
-            const activeSessions = Object.fromEntries(await Promise.all(SESSION_PROVIDER_VALUES.map(async (provider) => {
+            const activeSessions = Object.fromEntries(await Promise.all(sessionProviderValues.map(async (provider) => {
                 const active = await sessionManager.getActiveSession(provider);
                 return [
                     provider,
@@ -6424,7 +6875,7 @@ export function createGatewayServer(deps = {}) {
                         text: JSON.stringify({
                             total: sessionList.length,
                             sessions: sessionList,
-                            activeSessions: Object.fromEntries(SESSION_PROVIDER_VALUES.map(provider => [
+                            activeSessions: Object.fromEntries(sessionProviderValues.map(provider => [
                                 provider,
                                 activeSessions[provider]?.id || null,
                             ])),
@@ -6438,7 +6889,7 @@ export function createGatewayServer(deps = {}) {
         }
     });
     server.tool("session_set_active", "Set or clear the active session for a provider; the active session is used when a request omits sessionId.", {
-        cli: SESSION_PROVIDER_ENUM.describe("Provider type (claude|codex|gemini|grok|mistral|grok-api)"),
+        cli: sessionProviderEnum.describe("Provider type (claude|codex|gemini|grok|mistral|grok-api)"),
         sessionId: z.string().nullable().describe("Session ID (null to clear)"),
     }, {
         title: "Set active session",
@@ -6618,7 +7069,9 @@ export function createGatewayServer(deps = {}) {
         }
     });
     server.tool("session_clear_all", "Delete all gateway session records, optionally scoped to one provider.", {
-        cli: SESSION_PROVIDER_ENUM.optional().describe("Provider filter (claude|codex|gemini|grok|mistral|grok-api)"),
+        cli: sessionProviderEnum
+            .optional()
+            .describe("Provider filter (claude|codex|gemini|grok|mistral|grok-api)"),
     }, {
         title: "Clear sessions",
         readOnlyHint: false,