llm-cli-gateway 2.3.0 → 2.5.0

package/dist/index.js

@@ -2,7 +2,8 @@
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { randomUUID } from "crypto";
-import { existsSync, readFileSync, readdirSync, renameSync, unlinkSync } from "fs";
+import { createRequire } from "module";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, chmodSync, } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { z } from "zod/v3";
@@ -12,12 +13,13 @@ import { parseCodexJsonStream } from "./codex-json-parser.js";
 import { parseGeminiJson, parseGeminiStreamJson } from "./gemini-json-parser.js";
 import { parseVibeMetaJson } from "./mistral-meta-json-parser.js";
 import { homedir } from "os";
-import { createSessionManager } from "./session-manager.js";
+import { CLI_TYPES, PROVIDER_TYPES, createSessionManager, } from "./session-manager.js";
 import { createWorktree, createWorktreeSessionCleanupHook, } from "./worktree-manager.js";
 import { ResourceProvider } from "./resources.js";
 import { PerformanceMetrics } from "./metrics.js";
 import { estimateTokens, optimizePrompt as optimizePromptText, optimizeResponse as optimizeResponseText, } from "./optimizer.js";
-import { loadConfig, loadPersistenceConfig, loadCacheAwarenessConfig, minStableTokensForModel, } from "./config.js";
+import { loadConfig, loadPersistenceConfig, loadCacheAwarenessConfig, loadProvidersConfig, defaultGatewayConfigPath, isXaiProviderEnabled, minStableTokensForModel, } from "./config.js";
+import { createXaiResponse, XaiApiError, } from "./xai-api-provider.js";
 import { checkHealth } from "./health.js";
 import { clearModelRegistryCache, getAvailableCliInfo, getCliInfo, resolveModelAlias, } from "./model-registry.js";
 import { AsyncJobManager, } from "./async-job-manager.js";
@@ -31,9 +33,12 @@ import { resolvePromptInput, PromptPartsSchema, assembleClaudeCacheBlocks, } fro
 import { computeSessionCacheStats, computeTtlRemaining, readPersistedRequest, PERSISTED_REQUEST_DEFAULT_MAX_CHARS, } from "./cache-stats.js";
 import { getCliVersions, runCliUpgrade } from "./cli-updater.js";
 import { startHttpGateway } from "./http-transport.js";
+import { getRequestContext } from "./request-context.js";
 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 { assertUpstreamCliArgs, assertUpstreamCliEnv, buildUpstreamContractReport, } from "./upstream-contracts.js";
+import { assertUpstreamCliArgs, assertUpstreamCliEnv, buildProviderSubcommandsCompactCatalog, buildUpstreamContractReport, getCliSubcommandContract, probeInstalledCliContract, serializeCliSubcommandContract, } from "./upstream-contracts.js";
 import { entrypointFileURL } from "./entrypoint-url.js";
 const logger = {
     info: (message, ...args) => {
@@ -141,31 +146,32 @@ function loadSkills() {
     return skills;
 }
 const loadedSkills = loadSkills();
-export function buildServerInstructions(asyncJobsEnabled) {
+export function buildServerInstructions(asyncJobsEnabled, grokApiToolsEnabled = false) {
     const asyncToolsNote = asyncJobsEnabled ? " | *_request_async (async)" : "";
+    const apiToolsNote = grokApiToolsEnabled ? ", grok_api_request" : "";
     const jobsLine = asyncJobsEnabled ? "Jobs: llm_job_status, llm_job_result, llm_job_cancel\n" : "";
     const deferralLine = asyncJobsEnabled
         ? `- Sync auto-defers at ${SYNC_DEADLINE_MS}ms. Poll deferred jobs via llm_job_status/llm_job_result.`
         : '- 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 (sync)${asyncToolsNote} | codex_fork_session (fork a Codex session into a new branch)
+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)
 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 (use --probe-installed after CLI upgrades to detect drift), cli_upgrade, approval_list, llm_process_health, llm_request_result (read back any persisted request — sync or async — by correlationId)
+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)
 
 Key behaviors:
 ${deferralLine}
 - Sessions: Claude --continue, Gemini --resume, 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.
 - Approval gates: opt-in via approvalStrategy:"mcp_managed".
-- Upstream drift detection: After upgrading any provider CLI (especially grok), use the upstream_contracts tool with probeInstalled: true (or the CLI command "llm-cli-gateway contracts --json --probe-installed"). This is the primary reliable way to detect when an installed binary has gained or lost flags compared to the gateway's declared contract. The probe is safe and read-only.
+- 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).
 
 Skills (full docs via MCP resources):
 ${loadedSkills.map(s => `- skills://${s.name} — ${s.description}`).join("\n")}`;
 }
-function newGatewayMcpServer(asyncJobsEnabled = true) {
-    return new McpServer({ name: "llm-cli-gateway", version: packageVersion() }, { instructions: buildServerInstructions(asyncJobsEnabled) });
+function newGatewayMcpServer(asyncJobsEnabled = true, grokApiToolsEnabled = false) {
+    return new McpServer({ name: "llm-cli-gateway", version: packageVersion() }, { instructions: buildServerInstructions(asyncJobsEnabled, grokApiToolsEnabled) });
 }
 let sessionManager;
 let db = null;
@@ -174,6 +180,7 @@ let resourceProvider;
 let flightRecorder = null;
 let persistenceConfig = null;
 let cacheAwarenessConfig = null;
+let providersConfig = null;
 let jobStore = null;
 let jobStoreInitialized = false;
 let asyncJobManager = null;
@@ -190,6 +197,10 @@ function getCacheAwarenessConfig(runtimeLogger = logger) {
     cacheAwarenessConfig ??= loadCacheAwarenessConfig(runtimeLogger);
     return cacheAwarenessConfig;
 }
+function getProvidersConfig(runtimeLogger = logger) {
+    providersConfig ??= loadProvidersConfig(runtimeLogger);
+    return providersConfig;
+}
 function getJobStore(runtimeLogger = logger) {
     if (jobStoreInitialized)
         return jobStore;
@@ -217,6 +228,7 @@ function getApprovalManager(runtimeLogger = logger) {
     return approvalManager;
 }
 const MCP_SERVER_ENUM = z.enum(CLAUDE_MCP_SERVER_NAMES);
+const CLI_TYPE_ENUM = z.enum(CLI_TYPES);
 export const MAX_TURNS_SCHEMA = z.number().int().positive().safe().max(10_000);
 export const MAX_TOKENS_SCHEMA = z.number().int().positive().safe().max(100_000_000);
 export const MAX_PRICE_SCHEMA = z.number().positive().finite().min(1e-6).max(10_000);
@@ -244,7 +256,13 @@ export const WORKTREE_SCHEMA = z
     "path. NOTE: callers should `.gitignore` the `.worktrees/` " +
     "directory in their repo (the gateway does NOT auto-gitignore — " +
     "see slice λ spec Q4).");
-export const SESSION_PROVIDER_VALUES = ["claude", "codex", "gemini", "grok", "mistral"];
+export const WORKSPACE_ALIAS_SCHEMA = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[A-Za-z][A-Za-z0-9._-]{0,63}$/)
+    .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);
 let activeServer = null;
 let activeHttpGateway = null;
@@ -277,8 +295,13 @@ export function resolveGatewayServerRuntime(deps = {}, options = {}) {
         logger: runtimeLogger,
         persistence: deps.persistence ?? getPersistenceConfig(runtimeLogger),
         cacheAwareness: deps.cacheAwareness ?? getCacheAwarenessConfig(runtimeLogger),
+        providers: deps.providers ?? getProvidersConfig(runtimeLogger),
+        workspaces: deps.workspaces ?? loadWorkspaceRegistry(runtimeLogger),
     };
 }
+export function shouldRegisterGrokApiTools(providers) {
+    return isXaiProviderEnabled(providers);
+}
 const CLI_IDLE_TIMEOUTS = {
     claude: 600_000,
     codex: 600_000,
@@ -403,7 +426,7 @@ function buildDeferredToolResponse(deferred, sessionId) {
         ],
     };
 }
-export async function resolveWorktreeForRequest(worktreeOpt, sessionId, runtime) {
+export async function resolveWorktreeForRequest(worktreeOpt, sessionId, runtime, options = {}) {
     if (!worktreeOpt)
         return {};
     const sessionManager = runtime.sessionManager;
@@ -411,12 +434,21 @@ export async function resolveWorktreeForRequest(worktreeOpt, sessionId, runtime)
         const session = await Promise.resolve(sessionManager.getSession(sessionId));
         const existingPath = session?.metadata?.worktreePath;
         if (typeof existingPath === "string" && existingPath.length > 0) {
-            return { cwd: existingPath, worktreePath: existingPath };
+            return {
+                cwd: existingPath,
+                worktreePath: existingPath,
+                workspaceAlias: typeof session?.metadata?.workspaceAlias === "string"
+                    ? session.metadata.workspaceAlias
+                    : options.workspaceAlias,
+                workspaceRoot: typeof session?.metadata?.workspaceRoot === "string"
+                    ? session.metadata.workspaceRoot
+                    : options.workspaceRoot,
+            };
         }
     }
     const name = worktreeOpt === true ? undefined : worktreeOpt.name;
     const ref = worktreeOpt === true ? undefined : worktreeOpt.ref;
-    const repoRoot = process.cwd();
+    const repoRoot = options.repoRoot ?? process.cwd();
     const handle = await createWorktree({
         repoRoot,
         name,
@@ -427,13 +459,204 @@ export async function resolveWorktreeForRequest(worktreeOpt, sessionId, runtime)
         await Promise.resolve(sessionManager.updateSessionMetadata(sessionId, {
             worktreePath: handle.path,
             worktreeName: handle.name,
+            ...(options.workspaceAlias ? { workspaceAlias: options.workspaceAlias } : {}),
+            ...(options.workspaceRoot ? { workspaceRoot: options.workspaceRoot } : {}),
         }));
     }
-    return { cwd: handle.path, worktreePath: handle.path };
+    return {
+        cwd: handle.path,
+        worktreePath: handle.path,
+        workspaceAlias: options.workspaceAlias,
+        workspaceRoot: options.workspaceRoot,
+    };
+}
+function isGatewayAppDirCwd() {
+    return process.cwd() === join(homedir(), ".llm-cli-gateway");
+}
+async function resolveWorkspaceAndWorktreeForRequest(args) {
+    const session = args.sessionId
+        ? await Promise.resolve(args.runtime.sessionManager.getSession(args.sessionId))
+        : null;
+    let workspace;
+    if (args.workspace ||
+        args.runtime.workspaces.defaultAlias ||
+        typeof session?.metadata?.workspaceAlias === "string") {
+        workspace = resolveWorkspaceForProvider(args.runtime.workspaces, args.provider, args.workspace, session?.metadata);
+    }
+    else if (isGatewayAppDirCwd()) {
+        throw new Error("No workspace selected. Configure [workspaces].default or pass a registered workspace alias.");
+    }
+    if (!workspace && getRequestContext()?.authKind === "oauth") {
+        throw new Error("Remote OAuth provider requests require a registered workspace alias or [workspaces].default.");
+    }
+    if (!workspace &&
+        (args.workingDir || (args.addDir?.length ?? 0) > 0) &&
+        !args.runtime.workspaces.allowUnregisteredWorkingDir) {
+        throw new Error("workingDir/addDir require a registered workspace alias unless [workspaces].allow_unregistered_working_dir is explicitly enabled.");
+    }
+    if (workspace) {
+        if (args.workingDir) {
+            validatePathInsideWorkspace(workspace, args.workingDir, "workingDir");
+        }
+        for (const dir of args.addDir ?? []) {
+            validatePathInsideWorkspace(workspace, dir, "addDir");
+        }
+    }
+    if (args.worktree) {
+        if (workspace && !workspace.repo.allowWorktree) {
+            throw new Error(`Workspace "${workspace.alias}" does not allow worktree requests`);
+        }
+        const resolved = await resolveWorktreeForRequest(args.worktree, args.sessionId, args.runtime, {
+            repoRoot: workspace?.root,
+            workspaceAlias: workspace?.alias,
+            workspaceRoot: workspace?.root,
+        });
+        return { cwd: resolved.cwd, worktreePath: resolved.worktreePath, workspace };
+    }
+    if (workspace && args.sessionId) {
+        await Promise.resolve(args.runtime.sessionManager.updateSessionMetadata(args.sessionId, {
+            workspaceAlias: workspace.alias,
+            workspaceRoot: workspace.root,
+        }));
+    }
+    return { cwd: workspace?.cwd, workspace };
 }
 export function formatWorktreePrefix(worktreePath) {
     return worktreePath ? `[gateway] worktree=${worktreePath}\n` : "";
 }
+function workspaceAdminEnabled() {
+    const scopes = getRequestContext()?.authScopes ?? [];
+    return process.env.LLM_GATEWAY_WORKSPACE_ADMIN === "1" && scopes.includes("workspace:admin");
+}
+function registerWorkspaceTools(server, runtime) {
+    server.tool("workspace_list", "List registered workspace aliases and summary metadata. Does not browse files.", {}, {
+        title: "List workspaces",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async () => {
+        const registry = loadWorkspaceRegistry(runtime.logger);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        enabled: registry.enabled,
+                        default: registry.defaultAlias,
+                        workspaces: registry.repos.map(describeWorkspace),
+                        allowed_roots: registry.allowedRoots.map(root => ({
+                            alias: root.alias,
+                            path: root.path,
+                            allow_register_existing_git_repos: root.allowRegisterExistingGitRepos,
+                            allow_create_directories: root.allowCreateDirectories,
+                            allow_init_git_repos: root.allowInitGitRepos,
+                            max_create_depth: root.maxCreateDepth,
+                        })),
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("workspace_get", "Inspect a registered workspace alias. Does not list files.", { alias: WORKSPACE_ALIAS_SCHEMA }, {
+        title: "Get workspace",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ alias }) => {
+        try {
+            const registry = loadWorkspaceRegistry(runtime.logger);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ success: true, workspace: describeWorkspace(getWorkspace(registry, alias)) }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse("workspace_get", 1, "", undefined, error);
+        }
+    });
+    server.tool("workspace_create", "Create a new local folder or git repo under a configured allowed root. Requires LLM_GATEWAY_WORKSPACE_ADMIN=1 and OAuth scope workspace:admin.", {
+        alias: WORKSPACE_ALIAS_SCHEMA,
+        root: WORKSPACE_ALIAS_SCHEMA.describe("Allowed-root alias from workspace_list."),
+        slug: z.string().min(1).max(255).describe("Safe relative path under the allowed root."),
+        kind: z.enum(["folder", "git"]).default("git"),
+        setDefault: z.boolean().default(false),
+    }, {
+        title: "Create workspace",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false,
+    }, async ({ alias, root, slug, kind, setDefault }) => {
+        try {
+            if (!workspaceAdminEnabled()) {
+                throw new Error("workspace_create requires LLM_GATEWAY_WORKSPACE_ADMIN=1 and OAuth scope workspace:admin");
+            }
+            const repo = createWorkspace({
+                alias,
+                rootAlias: root,
+                slug,
+                kind,
+                setDefault,
+                logger: runtime.logger,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ success: true, workspace: describeWorkspace(repo) }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse("workspace_create", 1, "", undefined, error);
+        }
+    });
+    server.tool("workspace_register_existing_repo", "Register an existing local Git repo under an allowed root. Requires LLM_GATEWAY_WORKSPACE_ADMIN=1 and OAuth scope workspace:admin.", {
+        alias: WORKSPACE_ALIAS_SCHEMA,
+        path: z
+            .string()
+            .min(1)
+            .describe("Absolute path to an existing Git repo under an allowed root."),
+        setDefault: z.boolean().default(false),
+    }, {
+        title: "Register workspace",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    }, async ({ alias, path, setDefault }) => {
+        try {
+            if (!workspaceAdminEnabled()) {
+                throw new Error("workspace_register_existing_repo requires LLM_GATEWAY_WORKSPACE_ADMIN=1 and OAuth scope workspace:admin");
+            }
+            const repo = registerExistingWorkspace({
+                alias,
+                repoPath: path,
+                setDefault,
+                logger: runtime.logger,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ success: true, workspace: describeWorkspace(repo) }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse("workspace_register_existing_repo", 1, "", undefined, error);
+        }
+    });
+}
 function createErrorResponse(cli, code, stderr, correlationId, error) {
     let errorMessage = `Error executing ${cli} CLI`;
     const isLaunchExit = code === 127 || code === -4058;
@@ -741,12 +964,12 @@ function registerBaseResources(server, runtime) {
         const contents = await runtime.resourceProvider.readResource(uri.href);
         return { contents: contents ? [contents] : [] };
     });
-    server.registerResource("cache-state-global", "cache_state://global", {
+    server.registerResource("cache-state-global", "cache-state://global", {
         title: "💾 Cache State (Global)",
         description: "Aggregate cache hit/miss/savings across all CLIs in the flight recorder. Tokens/hashes only — no prompt text.",
         mimeType: "application/json",
     }, async (uri) => {
-        runtime.logger.debug("Reading cache_state://global resource");
+        runtime.logger.debug("Reading cache-state://global resource");
         const stats = runtime.resourceProvider.readCacheStateGlobal({
             lastNHours: 24,
         });
@@ -760,7 +983,7 @@ function registerBaseResources(server, runtime) {
             ],
         };
     });
-    server.registerResource("cache-state-session", new ResourceTemplate("cache_state://session/{sessionId}", { list: undefined }), {
+    server.registerResource("cache-state-session", new ResourceTemplate("cache-state://session/{sessionId}", { list: undefined }), {
         title: "💾 Cache State (Session)",
         description: "Per-session cache hit/miss/savings. Tokens/hashes only — no prompt text.",
         mimeType: "application/json",
@@ -768,7 +991,7 @@ function registerBaseResources(server, runtime) {
         const sessionId = Array.isArray(variables.sessionId)
             ? variables.sessionId[0]
             : variables.sessionId;
-        runtime.logger.debug(`Reading cache_state://session/${sessionId}`);
+        runtime.logger.debug(`Reading cache-state://session/${sessionId}`);
         const stats = runtime.resourceProvider.readCacheStateSession(String(sessionId));
         return {
             contents: [
@@ -780,13 +1003,13 @@ function registerBaseResources(server, runtime) {
             ],
         };
     });
-    server.registerResource("cache-state-prefix", new ResourceTemplate("cache_state://prefix/{hash}", { list: undefined }), {
+    server.registerResource("cache-state-prefix", new ResourceTemplate("cache-state://prefix/{hash}", { list: undefined }), {
         title: "💾 Cache State (Prefix)",
         description: "Per-stable-prefix-hash cache hit/miss/savings, with CLI breakdown. Tokens/hashes only — no prompt text.",
         mimeType: "application/json",
     }, async (uri, variables) => {
         const hash = Array.isArray(variables.hash) ? variables.hash[0] : variables.hash;
-        runtime.logger.debug(`Reading cache_state://prefix/${hash}`);
+        runtime.logger.debug(`Reading cache-state://prefix/${hash}`);
         const stats = runtime.resourceProvider.readCacheStateForPrefix(String(hash));
         return {
             contents: [
@@ -798,6 +1021,30 @@ function registerBaseResources(server, runtime) {
             ],
         };
     });
+    server.registerResource("provider-subcommands-catalog", "provider-subcommands://catalog", {
+        title: "Provider Subcommands Catalog",
+        description: "Compact read-only catalog of declared provider CLI subcommands",
+        mimeType: "application/json",
+    }, async (uri) => {
+        runtime.logger.debug("Reading provider-subcommands://catalog resource");
+        const contents = await runtime.resourceProvider.readResource(uri.href);
+        return { contents: contents ? [contents] : [] };
+    });
+    server.registerResource("provider-subcommand-contract", new ResourceTemplate("provider-subcommands://{provider}/{+commandPath}", { list: undefined }), {
+        title: "Provider Subcommand Contract",
+        description: "Detailed read-only contract for one declared provider CLI subcommand",
+        mimeType: "application/json",
+    }, async (uri, variables) => {
+        const provider = Array.isArray(variables.provider)
+            ? variables.provider[0]
+            : variables.provider;
+        const commandPath = Array.isArray(variables.commandPath)
+            ? variables.commandPath[0]
+            : variables.commandPath;
+        runtime.logger.debug(`Reading provider-subcommands://${provider}/${commandPath}`);
+        const contents = await runtime.resourceProvider.readResource(uri.href);
+        return { contents: contents ? [contents] : [] };
+    });
 }
 function resolvePromptOrPartsForPrep(args) {
     const hasPrompt = typeof args.prompt === "string" && args.prompt.length > 0;
@@ -1676,6 +1923,271 @@ function buildCliResponse(cli, stdout, optimizeResponse, corrId, sessionId, prep
     }
     return response;
 }
+function buildXaiPromptPartsUserContent(promptParts) {
+    const userSections = [];
+    if (promptParts.tools && promptParts.tools.length > 0) {
+        userSections.push(`<tools>\n${promptParts.tools}\n</tools>`);
+    }
+    if (promptParts.context && promptParts.context.length > 0) {
+        userSections.push(`<context>\n${promptParts.context}\n</context>`);
+    }
+    if (promptParts.task && promptParts.task.length > 0) {
+        userSections.push(promptParts.task);
+    }
+    return userSections.join("\n\n");
+}
+function buildXaiPromptPartsEffectivePrompt(instructions, userContent) {
+    return instructions && instructions.length > 0
+        ? `${instructions}\n\n${userContent}`
+        : userContent;
+}
+function prepareGrokApiRequest(params, providers) {
+    const corrId = params.correlationId || randomUUID();
+    if (!providers.xai) {
+        return createErrorResponse("grok_api_request", 1, "", corrId, new Error("[providers.xai] is not configured"));
+    }
+    const inputResolution = resolvePromptOrPartsForPrep({
+        prompt: params.prompt,
+        promptParts: params.promptParts,
+        operation: "grok_api_request",
+        correlationId: corrId,
+    });
+    if (!inputResolution.ok)
+        return inputResolution.error;
+    const instructions = params.promptParts?.system && params.promptParts.system.length > 0
+        ? params.promptParts.system
+        : undefined;
+    let effectivePrompt = inputResolution.assembledPrompt;
+    let input;
+    if (params.promptParts) {
+        let userContent = buildXaiPromptPartsUserContent(params.promptParts);
+        if (params.optimizePrompt) {
+            const optimized = optimizePromptText(userContent);
+            logOptimizationTokens("prompt", corrId, userContent, optimized);
+            userContent = optimized;
+        }
+        effectivePrompt = buildXaiPromptPartsEffectivePrompt(instructions, userContent);
+        input = [{ role: "user", content: userContent }];
+    }
+    else {
+        if (params.optimizePrompt) {
+            const optimized = optimizePromptText(effectivePrompt);
+            logOptimizationTokens("prompt", corrId, effectivePrompt, optimized);
+            effectivePrompt = optimized;
+        }
+        input = effectivePrompt;
+    }
+    const resolvedModel = params.model ?? providers.xai.defaultModel;
+    if (params.reasoningEffort && !/^grok-4\.3(?:$|[-.])/.test(resolvedModel)) {
+        return createErrorResponse("grok_api_request", 1, "", corrId, new Error("reasoningEffort is currently supported only for xAI model grok-4.3"));
+    }
+    return {
+        corrId,
+        effectivePrompt,
+        resolvedModel,
+        instructions,
+        input,
+        stablePrefixHash: inputResolution.stablePrefixHash,
+        stablePrefixTokens: inputResolution.stablePrefixTokens,
+    };
+}
+function usageFromXaiResult(result) {
+    return {
+        inputTokens: result.usage.inputTokens,
+        outputTokens: result.usage.outputTokens,
+        cacheReadTokens: result.usage.cacheReadTokens,
+        costUsd: result.usage.costUsd,
+    };
+}
+async function getExistingSessionForProvider(sessionManager, sessionId, provider) {
+    if (!sessionId)
+        return null;
+    const existing = await sessionManager.getSession(sessionId);
+    if (existing && existing.cli !== provider) {
+        throw new Error(`Session ${sessionId} belongs to provider '${existing.cli}', not '${provider}'`);
+    }
+    return existing;
+}
+function asXaiApiError(error) {
+    if (error instanceof XaiApiError)
+        return error;
+    const cause = error?.cause;
+    return cause instanceof XaiApiError ? cause : null;
+}
+function buildGrokApiToolResponse(args) {
+    let text = args.result.text;
+    if (args.optimizeResponse) {
+        const optimized = optimizeResponseText(text);
+        logOptimizationTokens("response", args.corrId, text, optimized);
+        text = optimized;
+    }
+    const response = {
+        content: [{ type: "text", text }],
+        structuredContent: {
+            provider: "grok-api",
+            cli: "grok-api",
+            model: args.result.model || args.prep.resolvedModel,
+            correlationId: args.corrId,
+            sessionId: args.sessionId || null,
+            responseId: args.result.responseId,
+            previousResponseId: args.previousResponseId || null,
+            stalePreviousResponseCleared: args.stalePreviousResponseCleared,
+            status: args.result.status,
+            httpStatus: args.result.httpStatus,
+            durationMs: args.durationMs,
+            ...usageFromXaiResult(args.result),
+            exitCode: 0,
+            retryCount: 0,
+        },
+    };
+    if (args.sessionId)
+        response.sessionId = args.sessionId;
+    return response;
+}
+async function resolveGrokApiSession(params, runtime) {
+    if (params.sessionId) {
+        const existing = await getExistingSessionForProvider(runtime.sessionManager, params.sessionId, "grok-api");
+        const session = existing ??
+            (await runtime.sessionManager.createSession("grok-api", "Grok API Session", params.sessionId));
+        const previous = !params.createNewSession && typeof session.metadata?.xaiPreviousResponseId === "string"
+            ? session.metadata.xaiPreviousResponseId
+            : undefined;
+        return { sessionId: session.id, previousResponseId: previous };
+    }
+    if (!params.createNewSession) {
+        const active = await runtime.sessionManager.getActiveSession("grok-api");
+        if (active) {
+            const previous = typeof active.metadata?.xaiPreviousResponseId === "string"
+                ? active.metadata.xaiPreviousResponseId
+                : undefined;
+            return { sessionId: active.id, previousResponseId: previous };
+        }
+    }
+    const session = await runtime.sessionManager.createSession("grok-api", "Grok API Session", `${GATEWAY_SESSION_PREFIX}${randomUUID()}`);
+    return { sessionId: session.id };
+}
+export async function handleGrokApiRequest(deps, params) {
+    const runtime = resolveHandlerRuntime(deps);
+    const startTime = Date.now();
+    const prep = prepareGrokApiRequest(params, runtime.providers);
+    if ("content" in prep)
+        return prep;
+    const { corrId } = prep;
+    const xaiConfig = runtime.providers.xai;
+    let durationMs = 0;
+    let wasSuccessful = false;
+    try {
+        await getExistingSessionForProvider(runtime.sessionManager, params.sessionId, "grok-api");
+    }
+    catch (err) {
+        return createErrorResponse("grok_api_request", 1, "", corrId, err);
+    }
+    if (!xaiConfig) {
+        return createErrorResponse("grok_api_request", 1, "", corrId, new Error("[providers.xai] is not configured"));
+    }
+    const apiKey = process.env[xaiConfig.apiKeyEnv]?.trim();
+    if (!apiKey) {
+        return createErrorResponse("grok_api_request", 1, "", corrId, new Error(`xAI API key env var ${xaiConfig.apiKeyEnv} is not set`));
+    }
+    safeFlightStart({
+        correlationId: corrId,
+        cli: "grok-api",
+        model: prep.resolvedModel,
+        prompt: prep.effectivePrompt,
+        sessionId: params.sessionId,
+        stablePrefixHash: prep.stablePrefixHash ?? undefined,
+        stablePrefixTokens: prep.stablePrefixTokens ?? undefined,
+    }, runtime);
+    let sessionId;
+    let previousResponseId;
+    let stalePreviousResponseCleared = false;
+    try {
+        const session = await resolveGrokApiSession(params, runtime);
+        sessionId = session.sessionId;
+        previousResponseId = session.previousResponseId;
+        const call = (prev) => createXaiResponse({
+            baseUrl: xaiConfig.baseUrl,
+            apiKey,
+            model: prep.resolvedModel,
+            input: prep.input,
+            instructions: prep.instructions,
+            previousResponseId: prev,
+            maxOutputTokens: params.maxOutputTokens,
+            temperature: params.temperature,
+            topP: params.topP,
+            reasoningEffort: params.reasoningEffort,
+            timeoutMs: params.timeoutMs,
+        }, runtime.logger);
+        let result;
+        try {
+            result = await call(previousResponseId);
+        }
+        catch (error) {
+            const xaiError = asXaiApiError(error);
+            if (xaiError?.status === 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,
+                    xaiResponseCreatedAt: null,
+                });
+                stalePreviousResponseCleared = true;
+                previousResponseId = undefined;
+                result = await call(undefined);
+            }
+            else {
+                throw error;
+            }
+        }
+        durationMs = Math.max(0, Date.now() - startTime);
+        wasSuccessful = true;
+        await runtime.sessionManager.updateSessionMetadata(sessionId, {
+            xaiPreviousResponseId: result.responseId,
+            xaiResponseCreatedAt: new Date().toISOString(),
+            xaiModel: result.model || prep.resolvedModel,
+        });
+        await runtime.sessionManager.updateSessionUsage(sessionId);
+        safeFlightComplete(corrId, {
+            response: result.text,
+            durationMs,
+            retryCount: 0,
+            circuitBreakerState: "closed",
+            optimizationApplied: params.optimizePrompt || (params.optimizeResponse ?? false),
+            exitCode: 0,
+            status: "completed",
+            ...usageFromXaiResult(result),
+        }, runtime);
+        return buildGrokApiToolResponse({
+            result,
+            prep,
+            corrId,
+            durationMs,
+            sessionId,
+            previousResponseId,
+            stalePreviousResponseCleared,
+            optimizeResponse: params.optimizeResponse ?? false,
+        });
+    }
+    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 ?? "",
+            durationMs,
+            retryCount: 0,
+            circuitBreakerState: "closed",
+            optimizationApplied: false,
+            exitCode: 1,
+            errorMessage: err.message,
+            status: "failed",
+        }, runtime);
+        return createErrorResponse("grok_api_request", 1, "", corrId, err);
+    }
+    finally {
+        runtime.performanceMetrics.recordRequest("grok-api", durationMs || Math.max(0, Date.now() - startTime), wasSuccessful);
+    }
+}
 function maybeBuildCacheTtlWarning(args) {
     if (args.cli !== "claude")
         return null;
@@ -1715,6 +2227,7 @@ function resolveHandlerRuntime(deps) {
         sessionManager: deps.sessionManager,
         logger: normalizedLogger,
         asyncJobManager: asyncDeps.asyncJobManager,
+        workspaces: deps.workspaces,
     });
 }
 export async function handleGeminiRequest(deps, params) {
@@ -1762,18 +2275,28 @@ export async function handleGeminiRequest(deps, params) {
             resumeLatest: params.resumeLatest,
             createNewSession: params.createNewSession,
         });
-        args.push(...sessionPlan.args);
         const userProvidedSession = sessionPlan.resumed;
         const effectiveSessionIdHint = sessionPlan.resumed ? params.sessionId : undefined;
+        if (effectiveSessionIdHint) {
+            await getExistingSessionForProvider(deps.sessionManager, effectiveSessionIdHint, "gemini");
+        }
+        args.push(...sessionPlan.args);
         let worktreeResolution = {};
         try {
-            worktreeResolution = await resolveWorktreeForRequest(params.worktree, effectiveSessionIdHint, runtime);
+            worktreeResolution = await resolveWorkspaceAndWorktreeForRequest({
+                provider: "gemini",
+                workspace: params.workspace,
+                worktree: params.worktree,
+                sessionId: effectiveSessionIdHint,
+                runtime,
+                addDir: params.includeDirs,
+            });
         }
         catch (err) {
             return createErrorResponse("gemini_request", 1, "", corrId, err);
         }
         const geminiFrHandoff = buildAsyncFlightRecorderHandoff("gemini", prep, params.sessionId, params.outputFormat);
-        const result = await awaitJobOrDefer("gemini", args, corrId, resolveIdleTimeout("gemini", params.idleTimeoutMs), params.outputFormat, params.forceRefresh, runtime, undefined, undefined, geminiFrHandoff.flightRecorderEntry, geminiFrHandoff.extractUsage, worktreeResolution.cwd);
+        const result = await awaitJobOrDefer("gemini", args, corrId, resolveIdleTimeout("gemini", params.idleTimeoutMs), params.outputFormat, params.forceRefresh, runtime, undefined, undefined, geminiFrHandoff.flightRecorderEntry, geminiFrHandoff.extractUsage, undefined, worktreeResolution.cwd);
         if (isDeferredResponse(result)) {
             return buildDeferredToolResponse(result, effectiveSessionIdHint);
         }
@@ -1887,11 +2410,11 @@ export async function handleGeminiRequestAsync(deps, params) {
             resumeLatest: params.resumeLatest,
             createNewSession: params.createNewSession,
         });
-        args.push(...sessionPlan.args);
         let effectiveSessionId = sessionPlan.resumed ? params.sessionId : undefined;
+        const existingSession = await getExistingSessionForProvider(deps.sessionManager, effectiveSessionId, "gemini");
+        args.push(...sessionPlan.args);
         if (effectiveSessionId) {
-            const existing = await deps.sessionManager.getSession(effectiveSessionId);
-            if (!existing) {
+            if (!existingSession) {
                 try {
                     await deps.sessionManager.createSession("gemini", "Gemini Session", effectiveSessionId);
                 }
@@ -1905,7 +2428,14 @@ export async function handleGeminiRequestAsync(deps, params) {
         }
         let worktreeResolution = {};
         try {
-            worktreeResolution = await resolveWorktreeForRequest(params.worktree, effectiveSessionId, runtime);
+            worktreeResolution = await resolveWorkspaceAndWorktreeForRequest({
+                provider: "gemini",
+                workspace: params.workspace,
+                worktree: params.worktree,
+                sessionId: effectiveSessionId,
+                runtime,
+                addDir: params.includeDirs,
+            });
         }
         catch (err) {
             return createErrorResponse("gemini_request_async", 1, "", corrId, err);
@@ -2012,10 +2542,20 @@ export async function handleGrokRequest(deps, params) {
             resumeLatest: params.resumeLatest,
             createNewSession: params.createNewSession,
         });
+        if (sessionResult.userProvidedSession) {
+            await getExistingSessionForProvider(deps.sessionManager, sessionResult.effectiveSessionId, "grok");
+        }
         args.push(...sessionResult.resumeArgs);
         let worktreeResolution = {};
         try {
-            worktreeResolution = await resolveWorktreeForRequest(params.worktree, sessionResult.effectiveSessionId, runtime);
+            worktreeResolution = await resolveWorkspaceAndWorktreeForRequest({
+                provider: "grok",
+                workspace: params.workspace,
+                worktree: params.worktree,
+                sessionId: sessionResult.effectiveSessionId,
+                runtime,
+                workingDir: params.workingDir,
+            });
         }
         catch (err) {
             return createErrorResponse("grok_request", 1, "", corrId, err);
@@ -2158,6 +2698,9 @@ export async function handleGrokRequestAsync(deps, params) {
             resumeLatest: params.resumeLatest,
             createNewSession: params.createNewSession,
         });
+        if (sessionResult.userProvidedSession) {
+            await getExistingSessionForProvider(deps.sessionManager, sessionResult.effectiveSessionId, "grok");
+        }
         args.push(...sessionResult.resumeArgs);
         let effectiveSessionId = sessionResult.effectiveSessionId;
         if (sessionResult.userProvidedSession && effectiveSessionId) {
@@ -2180,7 +2723,14 @@ export async function handleGrokRequestAsync(deps, params) {
         }
         let worktreeResolution = {};
         try {
-            worktreeResolution = await resolveWorktreeForRequest(params.worktree, effectiveSessionId, runtime);
+            worktreeResolution = await resolveWorkspaceAndWorktreeForRequest({
+                provider: "grok",
+                workspace: params.workspace,
+                worktree: params.worktree,
+                sessionId: effectiveSessionId,
+                runtime,
+                workingDir: params.workingDir,
+            });
         }
         catch (err) {
             return createErrorResponse("grok_request_async", 1, "", corrId, err);
@@ -2262,10 +2812,21 @@ export async function handleMistralRequest(deps, params) {
             resumeLatest: params.resumeLatest,
             createNewSession: params.createNewSession,
         });
+        if (sessionResult.userProvidedSession) {
+            await getExistingSessionForProvider(deps.sessionManager, sessionResult.effectiveSessionId, "mistral");
+        }
         args.push(...sessionResult.resumeArgs);
         let worktreeResolution = {};
         try {
-            worktreeResolution = await resolveWorktreeForRequest(params.worktree, sessionResult.effectiveSessionId, runtime);
+            worktreeResolution = await resolveWorkspaceAndWorktreeForRequest({
+                provider: "mistral",
+                workspace: params.workspace,
+                worktree: params.worktree,
+                sessionId: sessionResult.effectiveSessionId,
+                runtime,
+                workingDir: params.workingDir,
+                addDir: params.addDir,
+            });
         }
         catch (err) {
             return createErrorResponse("mistral_request", 1, "", corrId, err);
@@ -2397,11 +2958,11 @@ export async function handleMistralRequestAsync(deps, params) {
             resumeLatest: params.resumeLatest,
             createNewSession: params.createNewSession,
         });
-        args.push(...sessionResult.resumeArgs);
         let effectiveSessionId = sessionResult.effectiveSessionId;
+        const existingSession = await getExistingSessionForProvider(deps.sessionManager, sessionResult.userProvidedSession ? effectiveSessionId : undefined, "mistral");
+        args.push(...sessionResult.resumeArgs);
         if (sessionResult.userProvidedSession && effectiveSessionId) {
-            const existing = await deps.sessionManager.getSession(effectiveSessionId);
-            if (!existing) {
+            if (!existingSession) {
                 try {
                     await deps.sessionManager.createSession("mistral", "Mistral Session", effectiveSessionId);
                 }
@@ -2419,7 +2980,15 @@ export async function handleMistralRequestAsync(deps, params) {
         }
         let worktreeResolution = {};
         try {
-            worktreeResolution = await resolveWorktreeForRequest(params.worktree, effectiveSessionId, runtime);
+            worktreeResolution = await resolveWorkspaceAndWorktreeForRequest({
+                provider: "mistral",
+                workspace: params.workspace,
+                worktree: params.worktree,
+                sessionId: effectiveSessionId,
+                runtime,
+                workingDir: params.workingDir,
+                addDir: params.addDir,
+            });
         }
         catch (err) {
             return createErrorResponse("mistral_request_async", 1, "", corrId, err);
@@ -2458,6 +3027,12 @@ export async function handleMistralRequestAsync(deps, params) {
 }
 export async function handleCodexRequestAsync(deps, params) {
     const runtime = resolveHandlerRuntime(deps);
+    try {
+        await getExistingSessionForProvider(deps.sessionManager, params.sessionId, "codex");
+    }
+    catch (err) {
+        return createErrorResponse("codex_request_async", 1, "", params.correlationId, err);
+    }
     const prep = prepareCodexRequest({
         prompt: params.prompt,
         promptParts: params.promptParts,
@@ -2525,7 +3100,15 @@ export async function handleCodexRequestAsync(deps, params) {
         }
         let worktreeResolution = {};
         try {
-            worktreeResolution = await resolveWorktreeForRequest(params.worktree, effectiveSessionId, runtime);
+            worktreeResolution = await resolveWorkspaceAndWorktreeForRequest({
+                provider: "codex",
+                workspace: params.workspace,
+                worktree: params.worktree,
+                sessionId: effectiveSessionId,
+                runtime,
+                workingDir: params.workingDir,
+                addDir: params.addDir,
+            });
         }
         catch (err) {
             runPrepCleanupLocally();
@@ -2572,13 +3155,90 @@ export async function handleCodexRequestAsync(deps, params) {
 }
 export function createGatewayServer(deps = {}) {
     const runtime = resolveGatewayServerRuntime(deps, { isolateState: true });
-    const { sessionManager, asyncJobManager, approvalManager, performanceMetrics, logger, persistence, flightRecorder, cacheAwareness, } = runtime;
+    const { sessionManager, asyncJobManager, approvalManager, performanceMetrics, logger, persistence, flightRecorder, cacheAwareness, providers, } = runtime;
     void flightRecorder;
     void cacheAwareness;
+    const grokApiToolsEnabled = shouldRegisterGrokApiTools(providers);
     const asyncJobsEnabled = persistence.backend !== "none" && persistence.asyncJobsEnabled && asyncJobManager.hasStore();
-    const server = newGatewayMcpServer(asyncJobsEnabled);
+    const server = newGatewayMcpServer(asyncJobsEnabled, grokApiToolsEnabled);
     registerBaseResources(server, runtime);
     registerValidationTools(server, { asyncJobManager });
+    registerWorkspaceTools(server, runtime);
+    if (grokApiToolsEnabled) {
+        server.tool("grok_api_request", "Run an xAI Grok API request synchronously through the Responses API. Requires exactly one of prompt or promptParts. Registered only when [providers.xai] is configured and its API-key env var is present.", {
+            prompt: z
+                .string()
+                .min(1, "Prompt cannot be empty")
+                .max(100000, "Prompt too long (max 100k chars)")
+                .optional()
+                .describe("Prompt text for xAI Grok API (mutually exclusive with promptParts)"),
+            promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. The stable prefix hash is logged for cache_state aggregates; xAI does not receive cache_control hints."),
+            model: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("xAI model id; defaults to [providers.xai].default_model"),
+            sessionId: z
+                .string()
+                .optional()
+                .describe("Gateway grok-api session to continue. The gateway stores xAI previous_response_id in session metadata."),
+            createNewSession: z
+                .boolean()
+                .default(false)
+                .describe("Start a fresh xAI response chain. With sessionId, ignores any stored previous_response_id for this request."),
+            correlationId: z.string().optional().describe("Request trace ID (auto if omitted)"),
+            optimizePrompt: z.boolean().default(false).describe("Optimize prompt before execution"),
+            optimizeResponse: z.boolean().default(false).describe("Optimize response output"),
+            maxOutputTokens: MAX_TOKENS_SCHEMA.optional().describe("xAI Responses API max_output_tokens. Bounded to safe integers <= 100000000."),
+            temperature: z
+                .number()
+                .finite()
+                .min(0)
+                .max(2)
+                .optional()
+                .describe("Sampling temperature passed to xAI Responses API"),
+            topP: z
+                .number()
+                .finite()
+                .min(0)
+                .max(1)
+                .optional()
+                .describe("Nucleus sampling top_p passed to xAI Responses API"),
+            reasoningEffort: z
+                .enum(["none", "low", "medium", "high"])
+                .optional()
+                .describe("xAI Responses API reasoning.effort"),
+            timeoutMs: z
+                .number()
+                .int()
+                .min(30_000)
+                .max(3_600_000)
+                .optional()
+                .describe("HTTP request timeout in ms (min 30s, max 1h, default 10m)"),
+        }, {
+            title: "Grok API request",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        }, async ({ prompt, promptParts, model, sessionId, createNewSession, correlationId, optimizePrompt, optimizeResponse, maxOutputTokens, temperature, topP, reasoningEffort, timeoutMs, }) => {
+            return handleGrokApiRequest({ sessionManager, logger, runtime }, {
+                prompt,
+                promptParts,
+                model,
+                sessionId,
+                createNewSession,
+                correlationId,
+                optimizePrompt,
+                optimizeResponse,
+                maxOutputTokens,
+                temperature,
+                topP,
+                reasoningEffort,
+                timeoutMs,
+            });
+        });
+    }
     server.tool("claude_request", "Run a Claude Code 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.", {
         prompt: z
             .string()
@@ -2687,6 +3347,7 @@ export function createGatewayServer(deps = {}) {
             .array(z.string())
             .optional()
             .describe('Claude --tools: restrict the available built-in tool set (distinct from allowedTools permission gating). Pass [""] to disable all tools.'),
+        workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
         worktree: WORKTREE_SCHEMA.optional(),
         approvalStrategy: z
             .enum(["legacy", "mcp_managed"])
@@ -2724,7 +3385,7 @@ export function createGatewayServer(deps = {}) {
         destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true,
-    }, async ({ prompt, promptParts, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, permissionMode, agent, agents, forkSession, systemPrompt, appendSystemPrompt, maxBudgetUsd, maxTurns, effort, excludeDynamicSystemPromptSections, fallbackModel, jsonSchema, addDir, noSessionPersistence, settingSources, settings, tools, worktree, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, }) => {
+    }, async ({ prompt, promptParts, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, permissionMode, agent, agents, forkSession, systemPrompt, appendSystemPrompt, maxBudgetUsd, maxTurns, effort, excludeDynamicSystemPromptSections, fallbackModel, jsonSchema, addDir, noSessionPersistence, settingSources, settings, tools, workspace, worktree, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, }) => {
         const startTime = Date.now();
         if (systemPrompt !== undefined && appendSystemPrompt !== undefined) {
             return createErrorResponse("claude", 1, "", correlationId, new Error("systemPrompt and appendSystemPrompt are mutually exclusive; use one or the other (not both)."));
@@ -2783,6 +3444,12 @@ export function createGatewayServer(deps = {}) {
         if (!useContinue && effectiveSessionId && activeSession?.id === effectiveSessionId) {
             useContinue = true;
         }
+        try {
+            await getExistingSessionForProvider(sessionManager, effectiveSessionId, "claude");
+        }
+        catch (err) {
+            return createErrorResponse("claude_request", 1, "", corrId, err);
+        }
         const ttlWarning = maybeBuildCacheTtlWarning({
             runtime,
             sessionId: effectiveSessionId,
@@ -2813,7 +3480,14 @@ export function createGatewayServer(deps = {}) {
             }
             let worktreeResolution = {};
             try {
-                worktreeResolution = await resolveWorktreeForRequest(worktree, effectiveSessionId, runtime);
+                worktreeResolution = await resolveWorkspaceAndWorktreeForRequest({
+                    provider: "claude",
+                    workspace,
+                    worktree,
+                    sessionId: effectiveSessionId,
+                    runtime,
+                    addDir,
+                });
             }
             catch (err) {
                 return createErrorResponse("claude_request", 1, "", corrId, err);
@@ -3024,6 +3698,7 @@ export function createGatewayServer(deps = {}) {
             .array(z.string())
             .optional()
             .describe("Codex --add-dir <DIR>: additional writable workspace directories. Emitted once per entry on new sessions only; resume inherits the original session's writable-dir policy."),
+        workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
         worktree: WORKTREE_SCHEMA.optional(),
     }, {
         title: "Codex request",
@@ -3031,7 +3706,7 @@ export function createGatewayServer(deps = {}) {
         destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true,
-    }, async ({ prompt, promptParts, model, fullAuto, sandboxMode, askForApproval, useLegacyFullAutoFlag, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, resumeLatest, createNewSession, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, outputFormat, outputSchema, search, profile, configOverrides, ephemeral, images, ignoreUserConfig, ignoreRules, workingDir, addDir, worktree, }) => {
+    }, async ({ prompt, promptParts, model, fullAuto, sandboxMode, askForApproval, useLegacyFullAutoFlag, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, resumeLatest, createNewSession, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, outputFormat, outputSchema, search, profile, configOverrides, ephemeral, images, ignoreUserConfig, ignoreRules, workingDir, addDir, workspace, worktree, }) => {
         const startTime = Date.now();
         const prep = prepareCodexRequest({
             prompt,
@@ -3068,6 +3743,12 @@ export function createGatewayServer(deps = {}) {
         const { corrId, args } = prep;
         let durationMs = 0;
         let wasSuccessful = false;
+        try {
+            await getExistingSessionForProvider(sessionManager, sessionId, "codex");
+        }
+        catch (err) {
+            return createErrorResponse("codex_request", 1, "", corrId, err);
+        }
         safeFlightStart({
             correlationId: corrId,
             cli: "codex",
@@ -3081,7 +3762,15 @@ export function createGatewayServer(deps = {}) {
         const prepCleanup = "cleanup" in prep && typeof prep.cleanup === "function" ? prep.cleanup : undefined;
         let worktreeResolution = {};
         try {
-            worktreeResolution = await resolveWorktreeForRequest(worktree, sessionId, runtime);
+            worktreeResolution = await resolveWorkspaceAndWorktreeForRequest({
+                provider: "codex",
+                workspace,
+                worktree,
+                sessionId,
+                runtime,
+                workingDir,
+                addDir,
+            });
         }
         catch (err) {
             return createErrorResponse("codex_request", 1, "", corrId, err);
@@ -3203,13 +3892,14 @@ export function createGatewayServer(deps = {}) {
             .max(3_600_000)
             .optional()
             .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
+        workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
     }, {
         title: "Fork Codex session",
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true,
-    }, async ({ prompt, sessionId, forkLast, model, sandboxMode, askForApproval, correlationId, idleTimeoutMs, }) => {
+    }, async ({ prompt, sessionId, forkLast, model, sandboxMode, askForApproval, correlationId, idleTimeoutMs, workspace, }) => {
         const corrId = correlationId || randomUUID();
         const startTime = Date.now();
         let durationMs = 0;
@@ -3220,6 +3910,12 @@ export function createGatewayServer(deps = {}) {
         if (!sessionId && !forkLast) {
             return createErrorResponse("codex_fork_session", 1, "", corrId, new Error("one of sessionId or forkLast is required"));
         }
+        try {
+            await getExistingSessionForProvider(sessionManager, sessionId, "codex");
+        }
+        catch (err) {
+            return createErrorResponse("codex_fork_session", 1, "", corrId, err);
+        }
         let forkArgs;
         try {
             forkArgs = prepareCodexForkRequest({ prompt, sessionId, forkLast }).args;
@@ -3243,7 +3939,13 @@ export function createGatewayServer(deps = {}) {
         const finalArgs = [forkArgs[0], ...flagSegment, ...forkArgs.slice(1)];
         logger.info(`[${corrId}] codex_fork_session invoked (forkLast=${Boolean(forkLast)}, sessionId=${sessionId ? "set" : "unset"})`);
         try {
-            const result = await awaitJobOrDefer("codex", finalArgs, corrId, resolveIdleTimeout("codex", idleTimeoutMs), undefined, false, runtime);
+            const worktreeResolution = await resolveWorkspaceAndWorktreeForRequest({
+                provider: "codex",
+                workspace,
+                sessionId,
+                runtime,
+            });
+            const result = await awaitJobOrDefer("codex", finalArgs, corrId, resolveIdleTimeout("codex", idleTimeoutMs), undefined, false, runtime, undefined, undefined, undefined, undefined, undefined, worktreeResolution.cwd);
             if (isDeferredResponse(result)) {
                 return buildDeferredToolResponse(result, sessionId);
             }
@@ -3334,6 +4036,7 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .optional()
             .describe("Emit `--yolo` to auto-approve all actions. Equivalent to approvalMode 'yolo'; routed through the same approval gate. Under mcp_managed the gate still decides."),
+        workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
         worktree: WORKTREE_SCHEMA.optional(),
     }, {
         title: "Gemini request",
@@ -3341,7 +4044,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, 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, workspace, worktree, }) => {
         return handleGeminiRequest({ sessionManager, logger, runtime }, {
             prompt,
             promptParts,
@@ -3367,6 +4070,7 @@ export function createGatewayServer(deps = {}) {
             attachments,
             skipTrust,
             yolo,
+            workspace,
             worktree,
         });
     });
@@ -3544,6 +4248,7 @@ 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`."),
+        workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
         worktree: WORKTREE_SCHEMA.optional(),
     }, {
         title: "Grok request",
@@ -3551,7 +4256,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, optimizeResponse, idleTimeoutMs, forceRefresh, maxTurns, workingDir, sandbox, rules, systemPromptOverride, allow, deny, compactionMode, compactionDetail, agent, bestOfN, check, disableWebSearch, todoGate, verbatim, agents, promptFile, promptJson, single, experimentalMemory, noAltScreen, noMemory, noPlan, noSubagents, oauth, restoreCode, leaderSocket, nativeWorktree, worktree, }) => {
+    }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, maxTurns, workingDir, sandbox, rules, systemPromptOverride, allow, deny, compactionMode, compactionDetail, agent, bestOfN, check, disableWebSearch, todoGate, verbatim, agents, promptFile, promptJson, single, experimentalMemory, noAltScreen, noMemory, noPlan, noSubagents, oauth, restoreCode, leaderSocket, nativeWorktree, workspace, worktree, }) => {
         return handleGrokRequest({ sessionManager, logger, runtime }, {
             prompt,
             promptParts,
@@ -3602,6 +4307,7 @@ export function createGatewayServer(deps = {}) {
             restoreCode,
             leaderSocket,
             nativeWorktree,
+            workspace,
             worktree,
         });
     });
@@ -3684,6 +4390,7 @@ export function createGatewayServer(deps = {}) {
             .array(z.string())
             .optional()
             .describe("Vibe --add-dir <DIR>: additional writable workspace directories. Each entry is emitted as its own --add-dir instance (Vibe states this flag may be specified multiple times)."),
+        workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
         worktree: WORKTREE_SCHEMA.optional(),
     }, {
         title: "Mistral Vibe request",
@@ -3691,7 +4398,7 @@ export function createGatewayServer(deps = {}) {
         destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true,
-    }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, permissionMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, trust, maxTurns, maxPrice, maxTokens, workingDir, addDir, worktree, }) => {
+    }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, permissionMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, trust, maxTurns, maxPrice, maxTokens, workingDir, addDir, workspace, worktree, }) => {
         return handleMistralRequest({ sessionManager, logger, runtime }, {
             prompt,
             promptParts,
@@ -3717,6 +4424,7 @@ export function createGatewayServer(deps = {}) {
             maxTokens,
             workingDir,
             addDir,
+            workspace,
             worktree,
         });
     });
@@ -3829,6 +4537,7 @@ export function createGatewayServer(deps = {}) {
                 .array(z.string())
                 .optional()
                 .describe('Claude --tools: restrict the available built-in tool set (distinct from allowedTools permission gating). Pass [""] to disable all tools.'),
+            workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
             worktree: WORKTREE_SCHEMA.optional(),
             approvalStrategy: z
                 .enum(["legacy", "mcp_managed"])
@@ -3865,7 +4574,7 @@ export function createGatewayServer(deps = {}) {
             destructiveHint: true,
             idempotentHint: false,
             openWorldHint: true,
-        }, async ({ prompt, promptParts, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, permissionMode, agent, agents, forkSession, systemPrompt, appendSystemPrompt, maxBudgetUsd, maxTurns, effort, excludeDynamicSystemPromptSections, fallbackModel, jsonSchema, addDir, noSessionPersistence, settingSources, settings, tools, worktree, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, }) => {
+        }, async ({ prompt, promptParts, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, permissionMode, agent, agents, forkSession, systemPrompt, appendSystemPrompt, maxBudgetUsd, maxTurns, effort, excludeDynamicSystemPromptSections, fallbackModel, jsonSchema, addDir, noSessionPersistence, settingSources, settings, tools, workspace, worktree, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, }) => {
             if (systemPrompt !== undefined && appendSystemPrompt !== undefined) {
                 return createErrorResponse("claude", 1, "", correlationId, new Error("systemPrompt and appendSystemPrompt are mutually exclusive; use one or the other (not both)."));
             }
@@ -3916,6 +4625,7 @@ export function createGatewayServer(deps = {}) {
                 if (!useContinue && effectiveSessionId && activeSession?.id === effectiveSessionId) {
                     useContinue = true;
                 }
+                const existingSession = await getExistingSessionForProvider(sessionManager, effectiveSessionId, "claude");
                 if (useContinue) {
                     args.push("--continue");
                 }
@@ -3924,7 +4634,6 @@ export function createGatewayServer(deps = {}) {
                     await sessionManager.updateSessionUsage(effectiveSessionId);
                 }
                 if (effectiveSessionId) {
-                    const existingSession = await sessionManager.getSession(effectiveSessionId);
                     if (!existingSession) {
                         await sessionManager.createSession("claude", "Claude Session", effectiveSessionId);
                     }
@@ -3936,7 +4645,14 @@ export function createGatewayServer(deps = {}) {
                 });
                 let worktreeResolution = {};
                 try {
-                    worktreeResolution = await resolveWorktreeForRequest(worktree, effectiveSessionId, runtime);
+                    worktreeResolution = await resolveWorkspaceAndWorktreeForRequest({
+                        provider: "claude",
+                        workspace,
+                        worktree,
+                        sessionId: effectiveSessionId,
+                        runtime,
+                        addDir,
+                    });
                 }
                 catch (err) {
                     return createErrorResponse("claude_request_async", 1, "", corrId, err);
@@ -4076,6 +4792,7 @@ export function createGatewayServer(deps = {}) {
                 .array(z.string())
                 .optional()
                 .describe("Codex --add-dir <DIR>: additional writable workspace directories (repeat per entry). New sessions only."),
+            workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
             worktree: WORKTREE_SCHEMA.optional(),
         }, {
             title: "Codex request (async job)",
@@ -4083,7 +4800,7 @@ export function createGatewayServer(deps = {}) {
             destructiveHint: true,
             idempotentHint: false,
             openWorldHint: true,
-        }, async ({ prompt, promptParts, model, fullAuto, sandboxMode, askForApproval, useLegacyFullAutoFlag, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, resumeLatest, createNewSession, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, outputFormat, outputSchema, search, profile, configOverrides, ephemeral, images, ignoreUserConfig, ignoreRules, workingDir, addDir, worktree, }) => {
+        }, async ({ prompt, promptParts, model, fullAuto, sandboxMode, askForApproval, useLegacyFullAutoFlag, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, resumeLatest, createNewSession, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, outputFormat, outputSchema, search, profile, configOverrides, ephemeral, images, ignoreUserConfig, ignoreRules, workingDir, addDir, workspace, worktree, }) => {
             return handleCodexRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
                 promptParts,
@@ -4114,6 +4831,7 @@ export function createGatewayServer(deps = {}) {
                 ignoreRules,
                 workingDir,
                 addDir,
+                workspace,
                 worktree,
             });
         });
@@ -4185,6 +4903,7 @@ export function createGatewayServer(deps = {}) {
                 .boolean()
                 .optional()
                 .describe("Emit `--yolo` to auto-approve all actions. Equivalent to approvalMode 'yolo'; routed through the same approval gate. Under mcp_managed the gate still decides."),
+            workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
             worktree: WORKTREE_SCHEMA.optional(),
         }, {
             title: "Gemini request (async job)",
@@ -4192,7 +4911,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, 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, workspace, worktree, }) => {
             return handleGeminiRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
                 promptParts,
@@ -4217,6 +4936,7 @@ export function createGatewayServer(deps = {}) {
                 attachments,
                 skipTrust,
                 yolo,
+                workspace,
                 worktree,
             });
         });
@@ -4396,6 +5116,7 @@ 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`."),
+            workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
             worktree: WORKTREE_SCHEMA.optional(),
         }, {
             title: "Grok request (async job)",
@@ -4403,7 +5124,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, 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, workspace, worktree, }) => {
             return handleGrokRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
                 promptParts,
@@ -4453,6 +5174,7 @@ export function createGatewayServer(deps = {}) {
                 restoreCode,
                 leaderSocket,
                 nativeWorktree,
+                workspace,
                 worktree,
             });
         });
@@ -4534,6 +5256,7 @@ export function createGatewayServer(deps = {}) {
                 .array(z.string())
                 .optional()
                 .describe("Vibe --add-dir <DIR>: additional writable workspace directories. Each entry is emitted as its own --add-dir instance."),
+            workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
             worktree: WORKTREE_SCHEMA.optional(),
         }, {
             title: "Mistral Vibe request (async job)",
@@ -4541,7 +5264,7 @@ export function createGatewayServer(deps = {}) {
             destructiveHint: true,
             idempotentHint: false,
             openWorldHint: true,
-        }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, permissionMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, trust, maxTurns, maxPrice, maxTokens, workingDir, addDir, worktree, }) => {
+        }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, permissionMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, trust, maxTurns, maxPrice, maxTokens, workingDir, addDir, workspace, worktree, }) => {
             return handleMistralRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
                 promptParts,
@@ -4566,6 +5289,7 @@ export function createGatewayServer(deps = {}) {
                 maxTokens,
                 workingDir,
                 addDir,
+                workspace,
                 worktree,
             });
         });
@@ -4777,11 +5501,33 @@ export function createGatewayServer(deps = {}) {
                 ? null
                 : "Async job persistence is disabled (backend = 'none'). *_request_async tools are NOT registered on this gateway. Set [persistence].backend = 'sqlite' (or 'memory' + acknowledgeEphemeral = true) to enable them.",
         };
+        const outboundProviders = {
+            xai: providers.xai
+                ? {
+                    configured: true,
+                    enabled: isXaiProviderEnabled(providers),
+                    apiKeyEnv: providers.xai.apiKeyEnv,
+                    apiKeyPresent: isXaiProviderEnabled(providers),
+                    baseUrl: providers.xai.baseUrl,
+                    defaultModel: providers.xai.defaultModel,
+                    mode: isXaiProviderEnabled(providers) ? "sync" : "configured-missing-key",
+                }
+                : {
+                    configured: false,
+                    enabled: false,
+                    apiKeyEnv: null,
+                    apiKeyPresent: false,
+                    baseUrl: null,
+                    defaultModel: null,
+                    mode: "disabled",
+                },
+            sources: providers.sources,
+        };
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify({ success: true, ...health, persistence: persistenceBlock }, null, 2),
+                    text: JSON.stringify({ success: true, ...health, persistence: persistenceBlock, outboundProviders }, null, 2),
                 },
             ],
         };
@@ -4850,7 +5596,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), SESSION_PROVIDER_ENUM.optional())
+            .preprocess(value => (value === "" || value === null ? undefined : value), CLI_TYPE_ENUM.optional())
             .describe("CLI filter (claude|codex|gemini|grok|mistral)"),
         probeInstalled: z
             .boolean()
@@ -4866,6 +5612,133 @@ export function createGatewayServer(deps = {}) {
         const report = buildUpstreamContractReport({ cli, probeInstalled });
         return { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
     });
+    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)"),
+        tier: z
+            .enum(["catalog", "inspect", "execute_candidate", "diagnostic"])
+            .optional()
+            .describe("Optional subcommand tier filter"),
+        risk: z
+            .enum([
+            "read_only",
+            "writes_local_config",
+            "auth",
+            "network",
+            "starts_server",
+            "updates_binary",
+            "destructive",
+            "executes_agent",
+        ])
+            .optional()
+            .describe("Optional risk classification filter"),
+        exposure: z
+            .enum(["tracked_only", "mcp_readonly", "mcp_requires_approval", "not_exposed"])
+            .optional()
+            .describe("Optional MCP exposure filter"),
+        commandPathPrefix: z
+            .array(z.string().min(1))
+            .optional()
+            .describe("Optional command path prefix filter, e.g. ['agent']"),
+    }, {
+        title: "Provider subcommands catalog",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ provider, tier, risk, exposure, commandPathPrefix }) => {
+        const catalog = buildProviderSubcommandsCompactCatalog({
+            provider,
+            tier,
+            risk,
+            exposure,
+            commandPathPrefix,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ ...catalog, total: catalog.rows.length }),
+                },
+            ],
+        };
+    });
+    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)"),
+        commandPath: z.array(z.string().min(1)).min(1).describe("Command path segments"),
+    }, {
+        title: "Provider subcommand contract",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ provider, commandPath }) => {
+        const contract = getCliSubcommandContract(provider, commandPath);
+        const payload = contract
+            ? {
+                schemaVersion: "provider-subcommand-contract.v1",
+                contract: serializeCliSubcommandContract(provider, contract),
+            }
+            : {
+                schemaVersion: "provider-subcommand-contract.v1",
+                error: `No declared ${provider} subcommand contract for ${commandPath.join(" ")}`,
+            };
+        return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    });
+    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)"),
+        includeClean: z
+            .boolean()
+            .default(false)
+            .describe("When false, return only unavailable or drifted command paths"),
+    }, {
+        title: "Provider subcommand drift",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ provider, includeClean }) => {
+        const providers = provider ? [provider] : CLI_TYPES;
+        const rows = providers.flatMap(cli => {
+            const probe = probeInstalledCliContract(cli);
+            return Object.values(probe.subcommands).flatMap(sub => {
+                const drifted = !sub.available || sub.extraFlags.length > 0 || sub.missingFlags.length > 0;
+                if (!includeClean && !drifted)
+                    return [];
+                return [
+                    {
+                        provider: cli,
+                        commandPath: sub.commandPath,
+                        driftStatus: drifted ? "drift" : "clean",
+                        available: sub.available,
+                        extraVsContract: sub.extraFlags,
+                        missingFromBinary: sub.missingFlags,
+                        helpHash: sub.helpHash ?? null,
+                        risk: sub.risk,
+                        exposure: sub.exposure,
+                        tier: sub.tier,
+                        summary: sub.summary,
+                        warnings: sub.warnings,
+                    },
+                ];
+            });
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        schemaVersion: "provider-subcommand-drift.v1",
+                        total: rows.length,
+                        rows,
+                    }),
+                },
+            ],
+        };
+    });
     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"),
         target: z
@@ -4921,8 +5794,8 @@ export function createGatewayServer(deps = {}) {
             };
         }
     });
-    server.tool("session_create", "Create a gateway session record for a provider CLI. NOTE: this is gateway bookkeeping (gw-* ID), not a provider-native session — Codex resume needs a real Codex UUID.", {
-        cli: SESSION_PROVIDER_ENUM.describe("CLI type (claude|codex|gemini|grok|mistral)"),
+    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)"),
         description: z.string().optional().describe("Session description"),
         setAsActive: z.boolean().default(true).describe("Set as active session"),
     }, {
@@ -4960,8 +5833,8 @@ export function createGatewayServer(deps = {}) {
             return createErrorResponse("session_create", 1, "", undefined, error);
         }
     });
-    server.tool("session_list", "List gateway session records and the active session per CLI, optionally filtered by CLI.", {
-        cli: SESSION_PROVIDER_ENUM.optional().describe("CLI filter (claude|codex|gemini|grok|mistral)"),
+    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)"),
     }, {
         title: "List sessions",
         readOnlyHint: true,
@@ -4971,13 +5844,10 @@ export function createGatewayServer(deps = {}) {
     }, async ({ cli }) => {
         try {
             const sessions = await sessionManager.listSessions(cli);
-            const activeSessions = {
-                claude: await sessionManager.getActiveSession("claude"),
-                codex: await sessionManager.getActiveSession("codex"),
-                gemini: await sessionManager.getActiveSession("gemini"),
-                grok: await sessionManager.getActiveSession("grok"),
-                mistral: await sessionManager.getActiveSession("mistral"),
-            };
+            const activeSessions = Object.fromEntries(await Promise.all(SESSION_PROVIDER_VALUES.map(async (provider) => [
+                provider,
+                await sessionManager.getActiveSession(provider),
+            ])));
             const sessionList = sessions.map(s => ({
                 id: s.id,
                 cli: s.cli,
@@ -4993,13 +5863,10 @@ export function createGatewayServer(deps = {}) {
                         text: JSON.stringify({
                             total: sessionList.length,
                             sessions: sessionList,
-                            activeSessions: {
-                                claude: activeSessions.claude?.id || null,
-                                codex: activeSessions.codex?.id || null,
-                                gemini: activeSessions.gemini?.id || null,
-                                grok: activeSessions.grok?.id || null,
-                                mistral: activeSessions.mistral?.id || null,
-                            },
+                            activeSessions: Object.fromEntries(SESSION_PROVIDER_VALUES.map(provider => [
+                                provider,
+                                activeSessions[provider]?.id || null,
+                            ])),
                         }, null, 2),
                     },
                 ],
@@ -5009,8 +5876,8 @@ export function createGatewayServer(deps = {}) {
             return createErrorResponse("session_list", 1, "", undefined, error);
         }
     });
-    server.tool("session_set_active", "Set or clear the active session for a CLI; the active session is used when a request omits sessionId.", {
-        cli: SESSION_PROVIDER_ENUM.describe("CLI type (claude|codex|gemini|grok|mistral)"),
+    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)"),
         sessionId: z.string().nullable().describe("Session ID (null to clear)"),
     }, {
         title: "Set active session",
@@ -5028,7 +5895,7 @@ export function createGatewayServer(deps = {}) {
                             type: "text",
                             text: JSON.stringify({
                                 success: false,
-                                error: "Session not found or does not belong to the specified CLI",
+                                error: "Session not found or does not belong to the specified provider",
                             }, null, 2),
                         },
                     ],
@@ -5169,8 +6036,8 @@ export function createGatewayServer(deps = {}) {
             return createErrorResponse("session_get", 1, "", undefined, error);
         }
     });
-    server.tool("session_clear_all", "Delete all gateway session records, optionally scoped to one CLI.", {
-        cli: SESSION_PROVIDER_ENUM.optional().describe("CLI filter (claude|codex|gemini|grok|mistral)"),
+    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)"),
     }, {
         title: "Clear sessions",
         readOnlyHint: false,
@@ -5289,6 +6156,210 @@ async function shutdown(signal) {
 }
 process.on("SIGTERM", () => shutdown("SIGTERM"));
 process.on("SIGINT", () => shutdown("SIGINT"));
+function readMutableGatewayConfig(configPath = defaultGatewayConfigPath()) {
+    if (!existsSync(configPath))
+        return {};
+    const require = createRequire(import.meta.url);
+    const TOML = require("smol-toml");
+    return TOML.parse(readFileSync(configPath, "utf8"));
+}
+function writeMutableGatewayConfig(data, configPath = defaultGatewayConfigPath()) {
+    const require = createRequire(import.meta.url);
+    const TOML = require("smol-toml");
+    mkdirSync(dirname(configPath), { recursive: true, mode: 0o700 });
+    writeFileSync(configPath, TOML.stringify(data), { mode: 0o600 });
+    chmodSync(configPath, 0o600);
+}
+function ensureOAuthTable(config) {
+    config.http ??= {};
+    config.http.oauth ??= {};
+    const oauth = config.http.oauth;
+    oauth.enabled ??= true;
+    oauth.issuer ??= "auto";
+    oauth.require_pkce ??= true;
+    oauth.registration_policy ??= "static_clients";
+    oauth.allow_public_clients ??= false;
+    oauth.token_ttl_seconds ??= 3600;
+    oauth.clients ??= [];
+    return oauth;
+}
+function argValue(args, name) {
+    const idx = args.indexOf(name);
+    return idx >= 0 ? args[idx + 1] : undefined;
+}
+function requireArg(args, name) {
+    const value = argValue(args, name);
+    if (!value)
+        throw new Error(`Missing ${name}`);
+    return value;
+}
+function localBaseUrlForPrint() {
+    const publicUrl = process.env.LLM_GATEWAY_PUBLIC_URL;
+    if (publicUrl) {
+        try {
+            return new URL(publicUrl).origin;
+        }
+        catch {
+        }
+    }
+    return `http://${process.env.LLM_GATEWAY_HTTP_HOST ?? "127.0.0.1"}:${process.env.LLM_GATEWAY_HTTP_PORT ?? "3333"}`;
+}
+function printJsonLine(value) {
+    process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+function runOAuthCommand(args) {
+    const [scope, action] = args;
+    const config = readMutableGatewayConfig();
+    const oauth = ensureOAuthTable(config);
+    if (scope === "client") {
+        const clients = (Array.isArray(oauth.clients) ? oauth.clients : []);
+        oauth.clients = clients;
+        if (action === "add") {
+            const clientId = args[2];
+            if (!clientId)
+                throw new Error("Usage: llm-cli-gateway oauth client add <client-id> --redirect-uri <uri> [--print-once]");
+            const redirectUri = requireArg(args, "--redirect-uri");
+            const secret = generateSecret();
+            clients.push({
+                client_id: clientId,
+                client_secret_hash: hashSecret(secret),
+                allowed_redirect_uris: [redirectUri],
+                scopes: ["mcp"],
+            });
+            writeMutableGatewayConfig(config);
+            printJsonLine({
+                ok: true,
+                client_id: clientId,
+                ...(args.includes("--print-once") ? { client_secret: secret } : {}),
+                oauth: {
+                    issuer: localBaseUrlForPrint(),
+                    authorization_url: `${localBaseUrlForPrint()}/oauth/authorize`,
+                    token_url: `${localBaseUrlForPrint()}/oauth/token`,
+                },
+                note: args.includes("--print-once")
+                    ? "client_secret is shown once; it is stored only as a hash."
+                    : "client secret generated and stored only as a hash; rerun rotate --print-once if needed.",
+            });
+            return;
+        }
+        if (action === "list") {
+            printJsonLine({
+                ok: true,
+                clients: clients.map(client => ({
+                    client_id: client.client_id,
+                    redirect_uris: client.allowed_redirect_uris ?? [],
+                    secret_configured: Boolean(client.client_secret_hash),
+                })),
+            });
+            return;
+        }
+        if (action === "rotate") {
+            const clientId = args[2];
+            const client = clients.find(candidate => candidate.client_id === clientId);
+            if (!client)
+                throw new Error(`Unknown OAuth client ${clientId}`);
+            const secret = generateSecret();
+            client.client_secret_hash = hashSecret(secret);
+            writeMutableGatewayConfig(config);
+            printJsonLine({
+                ok: true,
+                client_id: clientId,
+                ...(args.includes("--print-once") ? { client_secret: secret } : {}),
+                note: "Future OAuth exchanges use the rotated secret; already-issued opaque access tokens expire by token TTL or server restart.",
+            });
+            return;
+        }
+        if (action === "revoke") {
+            const clientId = args[2];
+            oauth.clients = clients.filter(client => client.client_id !== clientId);
+            writeMutableGatewayConfig(config);
+            printJsonLine({
+                ok: true,
+                client_id: clientId,
+                note: "Future OAuth exchanges are revoked; already-issued opaque access tokens expire by token TTL or server restart.",
+            });
+            return;
+        }
+    }
+    if (scope === "shared-secret") {
+        if (action === "set" || action === "rotate") {
+            const secret = generateSecret();
+            oauth.registration_policy = "shared_secret";
+            oauth.shared_secret = {
+                enabled: true,
+                secret_hash: hashSecret(secret),
+                prompt_label: "Gateway access code",
+            };
+            writeMutableGatewayConfig(config);
+            printJsonLine({
+                ok: true,
+                shared_secret_enabled: true,
+                ...(args.includes("--print-once") ? { shared_secret: secret } : {}),
+                note: args.includes("--print-once")
+                    ? "shared_secret is shown once; it is stored only as a hash."
+                    : "shared secret generated and stored only as a hash.",
+            });
+            return;
+        }
+        if (action === "disable") {
+            oauth.shared_secret = { enabled: false, prompt_label: "Gateway access code" };
+            if (oauth.registration_policy === "shared_secret")
+                oauth.registration_policy = "static_clients";
+            writeMutableGatewayConfig(config);
+            printJsonLine({ ok: true, shared_secret_enabled: false });
+            return;
+        }
+    }
+    throw new Error("Usage: llm-cli-gateway oauth client|shared-secret ...");
+}
+function runWorkspaceCommand(args) {
+    const [action] = args;
+    if (action === "list") {
+        const registry = loadWorkspaceRegistry(logger);
+        printJsonLine({
+            ok: true,
+            default: registry.defaultAlias,
+            workspaces: registry.repos.map(describeWorkspace),
+            allowed_roots: registry.allowedRoots.map(root => ({
+                alias: root.alias,
+                path: root.path,
+                allow_create_directories: root.allowCreateDirectories,
+                allow_init_git_repos: root.allowInitGitRepos,
+            })),
+        });
+        return;
+    }
+    if (action === "create") {
+        const alias = args[1];
+        if (!alias)
+            throw new Error("Usage: llm-cli-gateway workspace create <alias> --root <root> --slug <slug> --kind folder|git [--default]");
+        const repo = createWorkspace({
+            alias,
+            rootAlias: requireArg(args, "--root"),
+            slug: requireArg(args, "--slug"),
+            kind: (argValue(args, "--kind") ?? "git"),
+            setDefault: args.includes("--default"),
+            logger,
+        });
+        printJsonLine({ ok: true, workspace: describeWorkspace(repo) });
+        return;
+    }
+    if (action === "add") {
+        const alias = args[1];
+        const repoPath = args[2];
+        if (!alias || !repoPath)
+            throw new Error("Usage: llm-cli-gateway workspace add <alias> <path> [--default]");
+        const repo = registerExistingWorkspace({
+            alias,
+            repoPath,
+            setDefault: args.includes("--default"),
+            logger,
+        });
+        printJsonLine({ ok: true, workspace: describeWorkspace(repo) });
+        return;
+    }
+    throw new Error("Usage: llm-cli-gateway workspace list|add|create ...");
+}
 async function main() {
     startWindowsBootstrapperSelfHeal();
     const args = process.argv.slice(2);
@@ -5302,6 +6373,8 @@ async function main() {
             "",
             "Usage:",
             "  llm-cli-gateway [doctor --json|contracts --json|--transport=http|--version]",
+            "  llm-cli-gateway oauth client add <id> --redirect-uri <uri> [--print-once]",
+            "  llm-cli-gateway workspace list|add|create",
             "",
             "Doctor:",
             "  doctor --json                     # environment, providers, declared contracts",
@@ -5323,12 +6396,18 @@ async function main() {
         process.stderr.write("Only doctor --json is supported in this layer.\n");
         process.exit(2);
     }
+    if (args[0] === "oauth") {
+        runOAuthCommand(args.slice(1));
+        return;
+    }
+    if (args[0] === "workspace") {
+        runWorkspaceCommand(args.slice(1));
+        return;
+    }
     if (args[0] === "contracts") {
         if (args.includes("--json")) {
             const cliArg = args.find(arg => arg.startsWith("--cli="))?.split("=")[1];
-            const cli = SESSION_PROVIDER_VALUES.includes(cliArg)
-                ? cliArg
-                : undefined;
+            const cli = CLI_TYPES.includes(cliArg) ? cliArg : undefined;
             if (cliArg && !cli) {
                 process.stderr.write(`Unsupported --cli value: ${cliArg}\n`);
                 process.exit(2);