llm-cli-gateway 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -2,6 +2,181 @@
 
 All notable changes to the llm-cli-gateway project.
 
+## [1.12.0] - 2026-05-27 — Phase 4 slice ζ (working-dir + add-dir cross-provider)
+
+Ships the seventh Phase 4 slice: working-directory and additional-directory
+flags are now reachable across four CLIs in a single bundled PR. Three
+commits land together (feature wiring, contract registration, test-veracity
+regressions) plus this release commit.
+
+### Added — working-dir + add-dir parity for four CLIs
+
+- **Claude** — `claude_request` and `claude_request_async` accept a new
+  `addDir: string[]` field. Threaded through `prepareClaudeRequest` →
+  `prepareClaudeHighImpactFlags` (`src/request-helpers.ts:687`). Each
+  entry emits its own `--add-dir` instance per `claude --help` ("Additional
+  directories to allow tool access to"). Claude has no working-dir flag
+  (uses the process cwd).
+- **Codex** — `codex_request` and `codex_request_async` accept new
+  `workingDir: string` (min 1) and `addDir: string[]` fields. Both flags
+  are already in `CODEX_RESUME_FILTERED_FLAGS` (the original session's cwd
+  and writable-dir policy are inherited on resume), so `prepareCodexRequest`
+  gates emission on `sessionPlan.mode === "new"` — resume argv stays clean
+  rather than emitting then stripping. Emits `-C <DIR>` (one) and
+  `--add-dir <DIR>` (one instance per entry).
+- **Grok** — `grok_request` and `grok_request_async` accept a new
+  `workingDir: string` (min 1) field. `prepareGrokRequest` emits
+  `--cwd <DIR>`. Grok has no `--add-dir` analogue.
+- **Vibe (Mistral)** — `mistral_request` and `mistral_request_async`
+  accept new `workingDir: string` (min 1) and `addDir: string[]` fields.
+  `prepareMistralRequest` (the `request-helpers.ts` helper) emits
+  `--workdir <DIR>` (one) and `--add-dir <DIR>` (one per entry; Vibe's
+  `--help` states the flag "Can be specified multiple times").
+  `buildMistralRetryPrep` threads both fields through to the stale-model
+  recovery argv per the slice-δ retry-path invariant.
+- **Gemini** is not re-wired: `--include-directories` was wired in master
+  before this slice. A regression-guard test in REGRESSIONS Zε asserts
+  the existing wiring stays intact while adjacent contract entries
+  changed.
+
+### Out of scope — worktree flags
+
+Worktree flags (`-w/--worktree` on Claude, Gemini, Grok) create new git
+worktree directories on disk with lifecycle implications and are
+explicitly deferred to a later slice with explicit cleanup semantics.
+
+### Contract surface
+
+`UPSTREAM_CLI_CONTRACTS` updates:
+
+- `claude.flags["--add-dir"]` (arity:"one"; repeated instances accepted)
+- `codex.flags["-C"]` (the gateway only emits the short form; codex
+  0.134.0 accepts `--cd` as an alias but the contract registers exactly
+  what we emit — a future code path that emitted `--cd` would correctly
+  fail the contract check).
+- `codex.flags["--add-dir"]`
+- `grok.flags["--cwd"]`
+- `mistral.flags["--workdir"]`
+- `mistral.flags["--add-dir"]`
+- `mcpParameters` arrays updated for all four CLIs.
+- Six new passing conformance fixtures (`claude-add-dir`,
+  `codex-working-dir`, `codex-add-dir`, `grok-working-dir`,
+  `mistral-working-dir`, `mistral-add-dir`); each is mechanically
+  validated against `validateUpstreamCliArgs` in the REGRESSIONS Zε
+  suite, closing the gap class identified in slice ε round 1.
+
+### Test-veracity audit
+
+Per the standing protocol (`feedback_test_veracity_audit_protocol`),
+this slice's tests were audited by all five LLM reviewers (Codex,
+Gemini, Grok, Mistral, Claude) in async parallel with mandatory
+mutation-probe execution against `docs/plans/test-veracity-audit-slice-zeta.spec.md`.
+
+**Round 1 outcomes:**
+
+- Codex: UNCONDITIONAL APPROVE — all 13 probes [as predicted], all 37
+  tests VERIFIED. Baseline (`npx vitest run` on the slice file: 37/37;
+  `npm test`: 54 files / 853 tests; build + format:check clean).
+- Grok: UNCONDITIONAL APPROVE — all 13 probes [as predicted].
+- Mistral: UNCONDITIONAL APPROVE — all 13 probes [as predicted].
+- Claude: UNCONDITIONAL APPROVE — all 13 probes red as predicted; ran
+  in an isolated `/tmp/zeta-audit-claude` worktree because the four
+  parallel reviewers were concurrently mutating the live tree.
+- Gemini: UNCONDITIONAL APPROVE — all 13 probes [as predicted].
+
+First unanimous round-1 pass on a multi-CLI slice. The 37 new tests
+(816 → 853 total) cover every new field/flag/fixture across REGRESSIONS
+Zα/β/ε:
+
+- **Zα** — Registered tool inputSchema for every new field on every
+  tool (sync + async), including `.min(1)` empty-string rejection on
+  `workingDir`.
+- **Zβ** — `prepare*Request` end-to-end argv emission per CLI. The
+  Codex resume branch asserts NEITHER `-C` NOR `--add-dir` appears
+  in resume argv. `buildMistralRetryPrep` regression catches the
+  slice-δ retry-path bug class. Prepare → contract end-to-end
+  consistency covers all four CLIs.
+- **Zε** — `UPSTREAM_CLI_CONTRACTS` introspection + mechanical
+  fixture validation in the same `it()` block (slice-ε round-1 gap
+  class). Includes a regression guard for the pre-existing Gemini
+  `--include-directories` wiring.
+
+### Mechanical anchors (verify with `rg` before relying)
+
+- `src/request-helpers.ts` — `ClaudeHighImpactFlagsInput.addDir`
+  (`:610`), `prepareClaudeHighImpactFlags` emission (`:686-690`).
+  `PrepareMistralRequestInput.workingDir`/`.addDir` (`:248-264`),
+  `prepareMistralRequest` emission (`:300-307`).
+- `src/index.ts` — `prepareClaudeRequest` (`:1338`),
+  `prepareCodexRequest` new-session gate (`:1687-1700`),
+  `prepareGrokRequest` `--cwd` emission (`:2065-2067`),
+  `prepareMistralRequest` wrapper (`:2153-2168`),
+  `buildMistralRetryPrep` (`:2249-2289`).
+- `src/upstream-contracts.ts` — flag registrations and conformance
+  fixtures for the four CLIs (`:146-149`, `:281-292`, `:438-441`,
+  `:524-533`, plus `mcpParameters` entries).
+
+## [1.11.0] - 2026-05-27 — Phase 4 slice η (Claude `--fallback-model` + `--json-schema`)
+
+Ships the sixth Phase 4 slice: Claude's reliability fallback and
+structured-output JSON-Schema constraint flags are now reachable from
+`claude_request` and `claude_request_async`. Three commits land together
+(feature wiring, contract registration, test-veracity regressions) plus
+this release commit.
+
+### Added — `--fallback-model` and `--json-schema` for Claude
+
+- `claude_request` and `claude_request_async` accept a new `fallbackModel`
+  field (non-empty string, validated via `z.string().min(1)`). Threaded
+  through `prepareClaudeRequest` → `prepareClaudeHighImpactFlags`
+  (`src/request-helpers.ts:651`) → `--fallback-model <model>` argv pair.
+  Effective only with Claude `--print`; the gateway always passes `-p`,
+  so no extra gating required.
+- Both tools accept a new `jsonSchema` field
+  (`string | Record<string, unknown>`). Per `claude --help`, the CLI
+  argument is the JSON Schema *literal* (not a path; contrast with Codex
+  `--output-schema`). Object values are `JSON.stringify`-d; string values
+  pass verbatim. Use with `outputFormat: "json"` for structured output
+  validation. Achieves Codex parity for structured-output validation
+  in a single slice.
+- `UPSTREAM_CLI_CONTRACTS.claude.flags` registers `--fallback-model` and
+  `--json-schema` with `arity: "one"`. `mcpParameters` includes both new
+  field names. Two new passing conformance fixtures
+  (`claude-fallback-model`, `claude-json-schema`) pin the contract; both
+  are mechanically validated against `validateUpstreamCliArgs` in the
+  REGRESSIONS Hε suite.
+
+### Test-veracity audit
+
+Per the standing protocol (`feedback_test_veracity_audit_protocol`),
+this slice's tests were audited by Codex + Gemini + Grok + Mistral in
+async parallel with mandatory mutation-probe execution. Spec at
+`docs/plans/test-veracity-audit-slice-eta.spec.md`. Round 1 outcomes:
+Grok + Mistral unanimous UNCONDITIONAL APPROVE; Gemini stalled at 682B
+stderr for 15+ minutes (cancelled, documented quota/stall-class
+blocker); Codex initially REJECTED on P-Hβ-4 with an invalid claim
+("removing sync `jsonSchema` left the test green") — pre-verification
+on a clean tree confirmed the mutation does turn `Hα-4` + `Hα-6` RED as
+the spec predicts. Round-2 pushback with the verbatim vitest output:
+Codex self-corrected, reproduced the mutation in a worktree, observed
+the predicted red, restored, and issued UNCONDITIONAL APPROVE.
+
+Three substantive reviewer approves (Grok, Mistral, Codex) from
+independent vendor families satisfy the multi-LLM gate; Gemini stall
+documented.
+
+Test count: 816 → 837 (21 new across one file:
+`src/__tests__/test-veracity-regressions-slice-eta.test.ts`).
+
+### Known caveats
+
+- `npm run check` still excludes `format:check` (gap first flagged in
+  v1.8.0). Run both locally before pushing.
+- Claude `--fallback-model` and `--json-schema` are CLI-side gated to
+  `--print` mode by Claude itself; both gateway tools always pass `-p`,
+  so this is invisible to callers but worth noting if the upstream CLI
+  flag semantics change.
+
 ## [1.10.0] - 2026-05-27 — Phase 4 slice ε (Gemini `-o stream-json` enum widening)
 
 Ships the fifth Phase 4 slice: Gemini's NDJSON event-stream output format

package/dist/index.d.ts

@@ -155,6 +155,9 @@ export declare function prepareClaudeRequest(params: {
     maxTurns?: number;
     effort?: ClaudeEffortLevel;
     excludeDynamicSystemPromptSections?: boolean;
+    fallbackModel?: string;
+    jsonSchema?: string | Record<string, unknown>;
+    addDir?: string[];
 }, runtime?: GatewayServerRuntime): CliRequestPrep | ExtendedToolResponse;
 export interface CodexRequestPrep extends CliRequestPrep {
     /**
@@ -197,6 +200,8 @@ export declare function prepareCodexRequest(params: {
     images?: string[];
     ignoreUserConfig?: boolean;
     ignoreRules?: boolean;
+    workingDir?: string;
+    addDir?: string[];
 }, runtime?: GatewayServerRuntime): CodexRequestPrep | ExtendedToolResponse;
 export declare function prepareGeminiRequest(params: {
     prompt?: string;
@@ -252,6 +257,11 @@ export declare function prepareGrokRequest(params: {
      * iterations for cost / latency control. Mirrors Claude's wiring.
      */
     maxTurns?: number;
+    /**
+     * Phase 4 slice ζ: emit `--cwd <DIR>` so headless callers can set Grok's
+     * working directory without depending on the gateway process's cwd.
+     */
+    workingDir?: string;
 }, runtime?: GatewayServerRuntime): CliRequestPrep | ExtendedToolResponse;
 export declare function prepareMistralRequest(params: {
     prompt?: string;
@@ -278,6 +288,10 @@ export declare function prepareMistralRequest(params: {
     maxTurns?: number;
     /** Phase 4 slice δ: Vibe `--max-price DOLLARS` cumulative-cost cap. */
     maxPrice?: number;
+    /** Phase 4 slice ζ: Vibe `--workdir <DIR>` working-directory parity. */
+    workingDir?: string;
+    /** Phase 4 slice ζ: Vibe `--add-dir <DIR>` repeatable add-dir parity. */
+    addDir?: string[];
 }, runtime?: GatewayServerRuntime): (CliRequestPrep & {
     mistralEnv: Record<string, string>;
 }) | ExtendedToolResponse;
@@ -290,7 +304,7 @@ export declare function prepareMistralRequest(params: {
  * through here, or a fresh-workspace / budgeted run can degrade on
  * the second attempt.
  */
-export declare function buildMistralRetryPrep(params: Pick<MistralRequestParams, "outputFormat" | "permissionMode" | "effort" | "reasoningEffort" | "allowedTools" | "disallowedTools" | "approvalStrategy" | "trust" | "maxTurns" | "maxPrice"> & {
+export declare function buildMistralRetryPrep(params: Pick<MistralRequestParams, "outputFormat" | "permissionMode" | "effort" | "reasoningEffort" | "allowedTools" | "disallowedTools" | "approvalStrategy" | "trust" | "maxTurns" | "maxPrice" | "workingDir" | "addDir"> & {
     effectivePrompt: string;
 }, recoveryModel: string): {
     args: string[];
@@ -366,6 +380,8 @@ export interface GrokRequestParams {
     forceRefresh?: boolean;
     /** Phase 4 slice δ: cap agent-loop iterations via `--max-turns N`. */
     maxTurns?: number;
+    /** Phase 4 slice ζ: emit `--cwd <DIR>` so the CLI uses the specified working directory. */
+    workingDir?: string;
 }
 export declare function handleGrokRequest(deps: HandlerDeps, params: GrokRequestParams): Promise<ExtendedToolResponse>;
 export declare function handleGrokRequestAsync(deps: AsyncHandlerDeps, params: Omit<GrokRequestParams, "optimizeResponse">): Promise<ExtendedToolResponse>;
@@ -396,6 +412,10 @@ export interface MistralRequestParams {
     maxTurns?: number;
     /** Phase 4 slice δ: Vibe `--max-price DOLLARS` cumulative-cost cap. */
     maxPrice?: number;
+    /** Phase 4 slice ζ: Vibe `--workdir <DIR>` working-directory parity. */
+    workingDir?: string;
+    /** Phase 4 slice ζ: Vibe `--add-dir <DIR>` repeatable add-dir parity. */
+    addDir?: string[];
 }
 export declare function handleMistralRequest(deps: HandlerDeps, params: MistralRequestParams): Promise<ExtendedToolResponse>;
 export declare function handleMistralRequestAsync(deps: AsyncHandlerDeps, params: Omit<MistralRequestParams, "optimizeResponse">): Promise<ExtendedToolResponse>;
@@ -428,6 +448,8 @@ export declare function handleCodexRequestAsync(deps: AsyncHandlerDeps, params:
     images?: string[];
     ignoreUserConfig?: boolean;
     ignoreRules?: boolean;
+    workingDir?: string;
+    addDir?: string[];
 }): Promise<ExtendedToolResponse>;
 export declare function createGatewayServer(deps?: GatewayServerDeps): McpServer;
 export {};

package/dist/index.js

@@ -1005,6 +1005,9 @@ export function prepareClaudeRequest(params, runtime = resolveGatewayServerRunti
         maxTurns: params.maxTurns,
         effort: params.effort,
         excludeDynamicSystemPromptSections: params.excludeDynamicSystemPromptSections,
+        fallbackModel: params.fallbackModel,
+        jsonSchema: params.jsonSchema,
+        addDir: params.addDir,
     }));
     return {
         corrId,
@@ -1124,6 +1127,19 @@ export function prepareCodexRequest(params, runtime = resolveGatewayServerRuntim
     // and are emitted in both branches.
     let highImpactCleanup;
     if (sessionPlan.mode === "new") {
+        // Phase 4 slice ζ: emit working-dir and add-dir on new sessions only.
+        // Both flags are listed in CODEX_RESUME_FILTERED_FLAGS — resume inherits
+        // the original session's cwd and writable-dir policy, so emitting them
+        // on resume would be silently stripped (wasteful + misleading on argv
+        // logs). Gating here mirrors `--search` / `--sandbox` / `--full-auto`.
+        if (params.workingDir) {
+            args.push("-C", params.workingDir);
+        }
+        if (params.addDir && params.addDir.length > 0) {
+            for (const dir of params.addDir) {
+                args.push("--add-dir", dir);
+            }
+        }
         const high = prepareCodexHighImpactFlags({
             outputSchema: params.outputSchema,
             search: params.search,
@@ -1379,6 +1395,9 @@ export function prepareGrokRequest(params, runtime = resolveGatewayServerRuntime
     if (params.maxTurns !== undefined) {
         args.push("--max-turns", String(params.maxTurns));
     }
+    if (params.workingDir) {
+        args.push("--cwd", params.workingDir);
+    }
     return {
         corrId,
         effectivePrompt,
@@ -1465,6 +1484,8 @@ export function prepareMistralRequest(params, runtime = resolveGatewayServerRunt
         trust: params.trust,
         maxTurns: params.maxTurns,
         maxPrice: params.maxPrice,
+        workingDir: params.workingDir,
+        addDir: params.addDir,
     });
     if (prep.ignoredDisallowedTools) {
         runtime.logger.info(`[${corrId}] Mistral does not support disallowedTools; ignoring (caller passed ${params.disallowedTools?.length ?? 0} entries)`);
@@ -1519,6 +1540,8 @@ export function buildMistralRetryPrep(params, recoveryModel) {
         trust: params.trust,
         maxTurns: params.maxTurns,
         maxPrice: params.maxPrice,
+        workingDir: params.workingDir,
+        addDir: params.addDir,
     });
 }
 function buildCliResponse(cli, stdout, optimizeResponse, corrId, sessionId, prep, durationMs, resumable, outputFormat, warnings) {
@@ -1860,6 +1883,7 @@ export async function handleGrokRequest(deps, params) {
         optimizePrompt: params.optimizePrompt,
         operation: "grok_request",
         maxTurns: params.maxTurns,
+        workingDir: params.workingDir,
     }, runtime);
     if (!("args" in prep))
         return prep;
@@ -1981,6 +2005,7 @@ export async function handleGrokRequestAsync(deps, params) {
         optimizePrompt: params.optimizePrompt,
         operation: "grok_request_async",
         maxTurns: params.maxTurns,
+        workingDir: params.workingDir,
     }, runtime);
     if (!("args" in prep))
         return prep;
@@ -2065,6 +2090,8 @@ export async function handleMistralRequest(deps, params) {
         trust: params.trust,
         maxTurns: params.maxTurns,
         maxPrice: params.maxPrice,
+        workingDir: params.workingDir,
+        addDir: params.addDir,
     }, runtime);
     if (!("args" in prep))
         return prep;
@@ -2200,6 +2227,8 @@ export async function handleMistralRequestAsync(deps, params) {
         trust: params.trust,
         maxTurns: params.maxTurns,
         maxPrice: params.maxPrice,
+        workingDir: params.workingDir,
+        addDir: params.addDir,
     }, runtime);
     if (!("args" in prep))
         return prep;
@@ -2288,6 +2317,8 @@ export async function handleCodexRequestAsync(deps, params) {
         images: params.images,
         ignoreUserConfig: params.ignoreUserConfig,
         ignoreRules: params.ignoreRules,
+        workingDir: params.workingDir,
+        addDir: params.addDir,
     }, runtime);
     if (!("args" in prep))
         return prep;
@@ -2481,6 +2512,21 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .optional()
             .describe("Claude --exclude-dynamic-system-prompt-sections: trim dynamic context blocks from the system prompt."),
+        // Phase 4 slice η — Claude reliability + structured-output parity
+        fallbackModel: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Claude --fallback-model: model name to auto-fallback to when the default model is overloaded (effective only with --print, which the gateway always uses)."),
+        jsonSchema: z
+            .union([z.string(), z.record(z.unknown())])
+            .optional()
+            .describe("Claude --json-schema: JSON Schema literal (NOT a path) constraining structured output. Object values are JSON.stringify-d; string values are passed verbatim. Use with outputFormat='json'."),
+        // Phase 4 slice ζ — Claude additional-workspace-dirs parity
+        addDir: z
+            .array(z.string())
+            .optional()
+            .describe("Claude --add-dir: additional directories the CLI is allowed to read/write beyond the process cwd. Each entry is emitted as its own --add-dir instance."),
         approvalStrategy: z
             .enum(["legacy", "mcp_managed"])
             .default("legacy")
@@ -2511,7 +2557,7 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .default(false)
             .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
-    }, async ({ prompt, promptParts, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, permissionMode, agent, agents, forkSession, systemPrompt, appendSystemPrompt, maxBudgetUsd, maxTurns, effort, excludeDynamicSystemPromptSections, 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, 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)."));
@@ -2541,6 +2587,9 @@ export function createGatewayServer(deps = {}) {
             maxTurns,
             effort,
             excludeDynamicSystemPromptSections,
+            fallbackModel,
+            jsonSchema,
+            addDir,
         }, runtime);
         if (!("args" in prep))
             return prep;
@@ -2795,7 +2844,17 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .optional()
             .describe("Codex --ignore-rules: skip project rule files for this run."),
-    }, 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, }) => {
+        // Phase 4 slice ζ — Codex working-dir + add-dir parity (new sessions only).
+        workingDir: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Codex -C/--cd <DIR>: working root for this session. Emitted on new sessions only; resume inherits the original session's cwd via CODEX_RESUME_FILTERED_FLAGS."),
+        addDir: z
+            .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."),
+    }, 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, }) => {
         const startTime = Date.now();
         const prep = prepareCodexRequest({
             prompt,
@@ -2824,6 +2883,8 @@ export function createGatewayServer(deps = {}) {
             images,
             ignoreUserConfig,
             ignoreRules,
+            workingDir,
+            addDir,
         }, runtime);
         if (!("args" in prep))
             return prep;
@@ -3195,7 +3256,13 @@ export function createGatewayServer(deps = {}) {
             .default(false)
             .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
         maxTurns: MAX_TURNS_SCHEMA.optional().describe("Grok `--max-turns N`: cap on agent-loop iterations for cost / latency control (Phase 4 slice δ). Bounded to safe integers ≤ 10000."),
-    }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, maxTurns, }) => {
+        // Phase 4 slice ζ — Grok working-directory parity.
+        workingDir: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Grok --cwd <DIR>: working directory for this invocation. Lets headless callers run Grok against a directory other than the gateway process's cwd."),
+    }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, maxTurns, workingDir, }) => {
         return handleGrokRequest({ sessionManager, logger, runtime }, {
             prompt,
             promptParts,
@@ -3219,6 +3286,7 @@ export function createGatewayServer(deps = {}) {
             idleTimeoutMs,
             forceRefresh,
             maxTurns,
+            workingDir,
         });
     });
     //──────────────────────────────────────────────────────────────────────────────
@@ -3298,7 +3366,17 @@ export function createGatewayServer(deps = {}) {
             .describe("Emit `--trust` so Vibe trusts the cwd for this invocation only (not persisted to trusted_folders.toml) and skips the interactive trust prompt (Phase 4 slice γ)."),
         maxTurns: MAX_TURNS_SCHEMA.optional().describe("Vibe `--max-turns N`: cap the agent-loop iteration count (programmatic mode only, Phase 4 slice δ). Bounded to safe integers ≤ 10000."),
         maxPrice: MAX_PRICE_SCHEMA.optional().describe("Vibe `--max-price DOLLARS`: interrupt the session when cumulative cost crosses this cap (programmatic mode only, Phase 4 slice δ). Bounded to finite values ≤ 10000 USD."),
-    }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, trust, maxTurns, maxPrice, }) => {
+        // Phase 4 slice ζ — Vibe working-directory + additional-dirs parity.
+        workingDir: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Vibe --workdir <DIR>: change to this directory before running. Single value (Vibe accepts one --workdir per invocation)."),
+        addDir: z
+            .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)."),
+    }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, trust, maxTurns, maxPrice, workingDir, addDir, }) => {
         return handleMistralRequest({ sessionManager, logger, runtime }, {
             prompt,
             promptParts,
@@ -3323,6 +3401,8 @@ export function createGatewayServer(deps = {}) {
             trust,
             maxTurns,
             maxPrice,
+            workingDir,
+            addDir,
         });
     });
     //──────────────────────────────────────────────────────────────────────────────
@@ -3408,6 +3488,21 @@ export function createGatewayServer(deps = {}) {
                 .boolean()
                 .optional()
                 .describe("Claude --exclude-dynamic-system-prompt-sections: trim dynamic context blocks from the system prompt."),
+            // Phase 4 slice η — Claude reliability + structured-output parity
+            fallbackModel: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Claude --fallback-model: model name to auto-fallback to when the default model is overloaded (effective only with --print, which the gateway always uses)."),
+            jsonSchema: z
+                .union([z.string(), z.record(z.unknown())])
+                .optional()
+                .describe("Claude --json-schema: JSON Schema literal (NOT a path) constraining structured output. Object values are JSON.stringify-d; string values are passed verbatim. Use with outputFormat='json'."),
+            // Phase 4 slice ζ — Claude additional-workspace-dirs parity
+            addDir: z
+                .array(z.string())
+                .optional()
+                .describe("Claude --add-dir: additional directories the CLI is allowed to read/write beyond the process cwd. Each entry is emitted as its own --add-dir instance."),
             approvalStrategy: z
                 .enum(["legacy", "mcp_managed"])
                 .default("legacy")
@@ -3437,7 +3532,7 @@ export function createGatewayServer(deps = {}) {
                 .boolean()
                 .default(false)
                 .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
-        }, async ({ prompt, promptParts, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, permissionMode, agent, agents, forkSession, systemPrompt, appendSystemPrompt, maxBudgetUsd, maxTurns, effort, excludeDynamicSystemPromptSections, 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, 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)."));
             }
@@ -3466,6 +3561,9 @@ export function createGatewayServer(deps = {}) {
                 maxTurns,
                 effort,
                 excludeDynamicSystemPromptSections,
+                fallbackModel,
+                jsonSchema,
+                addDir,
             }, runtime);
             if (!("args" in prep))
                 return prep;
@@ -3620,7 +3718,17 @@ export function createGatewayServer(deps = {}) {
             images: z.array(z.string()).optional().describe("Codex -i <path>: image attachments."),
             ignoreUserConfig: z.boolean().optional().describe("Codex --ignore-user-config."),
             ignoreRules: z.boolean().optional().describe("Codex --ignore-rules."),
-        }, 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, }) => {
+            // Phase 4 slice ζ — Codex working-dir + add-dir parity (new sessions only).
+            workingDir: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Codex -C/--cd <DIR>: working root for this session. New sessions only; resume inherits the original session's cwd."),
+            addDir: z
+                .array(z.string())
+                .optional()
+                .describe("Codex --add-dir <DIR>: additional writable workspace directories (repeat per entry). New sessions only."),
+        }, 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, }) => {
             return handleCodexRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
                 promptParts,
@@ -3649,6 +3757,8 @@ export function createGatewayServer(deps = {}) {
                 images,
                 ignoreUserConfig,
                 ignoreRules,
+                workingDir,
+                addDir,
             });
         });
         server.tool("gemini_request_async", {
@@ -3815,7 +3925,13 @@ export function createGatewayServer(deps = {}) {
                 .default(false)
                 .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
             maxTurns: MAX_TURNS_SCHEMA.optional().describe("Grok `--max-turns N`: cap on agent-loop iterations for cost / latency control (Phase 4 slice δ). Bounded to safe integers ≤ 10000."),
-        }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, maxTurns, }) => {
+            // Phase 4 slice ζ — Grok working-directory parity.
+            workingDir: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Grok --cwd <DIR>: working directory for this invocation. Lets headless callers run Grok against a directory other than the gateway process's cwd."),
+        }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, maxTurns, workingDir, }) => {
             return handleGrokRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
                 promptParts,
@@ -3838,6 +3954,7 @@ export function createGatewayServer(deps = {}) {
                 idleTimeoutMs,
                 forceRefresh,
                 maxTurns,
+                workingDir,
             });
         });
         server.tool("mistral_request_async", {
@@ -3913,7 +4030,17 @@ export function createGatewayServer(deps = {}) {
                 .describe("Emit `--trust` so Vibe trusts the cwd for this invocation only (not persisted to trusted_folders.toml) and skips the interactive trust prompt (Phase 4 slice γ)."),
             maxTurns: MAX_TURNS_SCHEMA.optional().describe("Vibe `--max-turns N`: cap the agent-loop iteration count (programmatic mode only, Phase 4 slice δ). Bounded to safe integers ≤ 10000."),
             maxPrice: MAX_PRICE_SCHEMA.optional().describe("Vibe `--max-price DOLLARS`: interrupt the session when cumulative cost crosses this cap (programmatic mode only, Phase 4 slice δ). Bounded to finite values ≤ 10000 USD."),
-        }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, trust, maxTurns, maxPrice, }) => {
+            // Phase 4 slice ζ — Vibe working-directory + additional-dirs parity.
+            workingDir: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Vibe --workdir <DIR>: change to this directory before running. Single value per invocation."),
+            addDir: z
+                .array(z.string())
+                .optional()
+                .describe("Vibe --add-dir <DIR>: additional writable workspace directories. Each entry is emitted as its own --add-dir instance."),
+        }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, trust, maxTurns, maxPrice, workingDir, addDir, }) => {
             return handleMistralRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
                 promptParts,
@@ -3937,6 +4064,8 @@ export function createGatewayServer(deps = {}) {
                 trust,
                 maxTurns,
                 maxPrice,
+                workingDir,
+                addDir,
             });
         });
         server.tool("llm_job_status", {

package/dist/request-helpers.d.ts

@@ -125,6 +125,17 @@ export interface PrepareMistralRequestInput {
      * only).
      */
     maxPrice?: number;
+    /**
+     * Phase 4 slice ζ: emit `--workdir <DIR>` so Vibe changes into the named
+     * directory before running. Single value (Vibe accepts one --workdir).
+     */
+    workingDir?: string;
+    /**
+     * Phase 4 slice ζ: emit `--add-dir <DIR>` per directory. Vibe's `--help`
+     * states the flag "Can be specified multiple times" — each entry is its
+     * own argv pair.
+     */
+    addDir?: string[];
 }
 export interface PrepareMistralRequestResult {
     args: string[];
@@ -350,6 +361,29 @@ export interface ClaudeHighImpactFlagsInput {
     maxTurns?: number;
     effort?: ClaudeEffortLevel;
     excludeDynamicSystemPromptSections?: boolean;
+    /**
+     * Phase 4 slice η — Claude `--fallback-model <model>`. Routes overloaded-model
+     * requests to the named fallback. Only effective with `--print` (we always pass
+     * `-p`, so no extra gating required here).
+     */
+    fallbackModel?: string;
+    /**
+     * Phase 4 slice η — Claude `--json-schema <schema>`. Per `claude --help`, the
+     * argument is the JSON Schema *literal*, not a path. Object values are
+     * `JSON.stringify`-d; string values are passed verbatim (caller already wrote
+     * a JSON literal). No temp file lifecycle needed (contrast with Codex
+     * `--output-schema`, which takes a path).
+     */
+    jsonSchema?: string | Record<string, unknown>;
+    /**
+     * Phase 4 slice ζ — Claude `--add-dir <dirs...>`. Additional directories the
+     * Claude CLI is allowed to read/write beyond the process cwd. The CLI accepts
+     * a single variadic flag (space-separated values) per `claude --help`; we
+     * emit one `--add-dir` instance per directory so each path is its own argv
+     * token (survives any future tightening of the variadic parser without
+     * changing the call site).
+     */
+    addDir?: string[];
 }
 /**
  * Emit Claude high-impact feature flags (U25) as a flat argv segment.

package/dist/request-helpers.js

@@ -185,6 +185,14 @@ export function prepareMistralRequest(input) {
     if (input.maxPrice !== undefined) {
         args.push("--max-price", String(input.maxPrice));
     }
+    if (input.workingDir) {
+        args.push("--workdir", input.workingDir);
+    }
+    if (input.addDir && input.addDir.length > 0) {
+        for (const dir of input.addDir) {
+            args.push("--add-dir", dir);
+        }
+    }
     const ignoredDisallowedTools = Boolean(input.disallowedTools && input.disallowedTools.length > 0);
     return { args, env, ignoredDisallowedTools };
 }
@@ -438,6 +446,18 @@ export function prepareClaudeHighImpactFlags(input) {
     if (input.excludeDynamicSystemPromptSections) {
         args.push("--exclude-dynamic-system-prompt-sections");
     }
+    if (input.fallbackModel !== undefined) {
+        args.push("--fallback-model", input.fallbackModel);
+    }
+    if (input.jsonSchema !== undefined) {
+        const schemaArg = typeof input.jsonSchema === "string" ? input.jsonSchema : JSON.stringify(input.jsonSchema);
+        args.push("--json-schema", schemaArg);
+    }
+    if (input.addDir && input.addDir.length > 0) {
+        for (const dir of input.addDir) {
+            args.push("--add-dir", dir);
+        }
+    }
     return args;
 }
 //──────────────────────────────────────────────────────────────────────────────

package/dist/upstream-contracts.js

@@ -37,6 +37,10 @@ export const UPSTREAM_CLI_CONTRACTS = {
             "maxTurns",
             "effort",
             "excludeDynamicSystemPromptSections",
+            "fallbackModel",
+            "jsonSchema",
+            // Phase 4 slice ζ
+            "addDir",
             "approvalStrategy",
             "mcpServers",
             "strictMcpConfig",
@@ -78,6 +82,18 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 arity: "none",
                 description: "Trim dynamic system prompt sections",
             },
+            "--fallback-model": {
+                arity: "one",
+                description: "Auto-fallback model when default is overloaded (Claude --print only)",
+            },
+            "--json-schema": {
+                arity: "one",
+                description: "JSON Schema literal constraining structured output",
+            },
+            "--add-dir": {
+                arity: "one",
+                description: "Additional workspace directory (Phase 4 slice ζ; repeat once per directory)",
+            },
             "--continue": { arity: "none", description: "Continue active session" },
             "--session-id": { arity: "one", description: "Session id" },
         },
@@ -95,6 +111,37 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 args: ["-p", "hello", "--not-a-claude-flag"],
                 expect: "fail",
             },
+            {
+                // Phase 4 slice η: --fallback-model wired through prepareClaudeRequest.
+                id: "claude-fallback-model",
+                description: "Phase 4 slice η: --fallback-model accepted",
+                args: ["-p", "hello", "--fallback-model", "claude-haiku-4-5-20251001"],
+                expect: "pass",
+            },
+            {
+                // Phase 4 slice η: --json-schema accepts an inline JSON Schema literal
+                // (per `claude --help` example), not a path. Codex parity for
+                // structured-output validation in one slice.
+                id: "claude-json-schema",
+                description: "Phase 4 slice η: --json-schema accepts inline JSON literal",
+                args: [
+                    "-p",
+                    "hello",
+                    "--output-format",
+                    "json",
+                    "--json-schema",
+                    '{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}',
+                ],
+                expect: "pass",
+            },
+            {
+                // Phase 4 slice ζ: --add-dir wired through prepareClaudeHighImpactFlags.
+                // Repeated once per directory; each instance has arity:"one".
+                id: "claude-add-dir",
+                description: "Phase 4 slice ζ: repeated --add-dir is accepted",
+                args: ["-p", "hello", "--add-dir", "/tmp/a", "--add-dir", "/tmp/b"],
+                expect: "pass",
+            },
         ],
     },
     codex: {
@@ -131,6 +178,9 @@ export const UPSTREAM_CLI_CONTRACTS = {
             "images",
             "ignoreUserConfig",
             "ignoreRules",
+            // Phase 4 slice ζ
+            "workingDir",
+            "addDir",
         ],
         resumeOnlyFlags: ["--last"],
         // Phase 4 slice α (v1.8.0) verified that `codex exec resume` accepts
@@ -170,6 +220,18 @@ export const UPSTREAM_CLI_CONTRACTS = {
             "-i": { arity: "one", description: "Image path" },
             "--ignore-user-config": { arity: "none", description: "Ignore user config" },
             "--ignore-rules": { arity: "none", description: "Ignore rule files" },
+            // The gateway only ever emits the short form `-C` (codex 0.134.0 accepts
+            // both `-C` and `--cd` as aliases). The contract registers exactly what
+            // we emit; if a future code path emits `--cd` instead, the contract
+            // check will fail loudly — which is the intended catch.
+            "-C": {
+                arity: "one",
+                description: "Working root for the session (Phase 4 slice ζ; new sessions only)",
+            },
+            "--add-dir": {
+                arity: "one",
+                description: "Additional writable workspace directory (Phase 4 slice ζ; repeat once per directory; new sessions only)",
+            },
         },
         env: {},
         conformanceFixtures: [
@@ -206,6 +268,26 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 args: ["exec", "resume", "--search", "session-id", "hello"],
                 expect: "fail",
             },
+            {
+                id: "codex-working-dir",
+                description: "Phase 4 slice ζ: -C <DIR> accepted on a new session",
+                args: ["exec", "--skip-git-repo-check", "-C", "/tmp/work", "hello"],
+                expect: "pass",
+            },
+            {
+                id: "codex-add-dir",
+                description: "Phase 4 slice ζ: repeated --add-dir accepted on a new session",
+                args: [
+                    "exec",
+                    "--skip-git-repo-check",
+                    "--add-dir",
+                    "/tmp/a",
+                    "--add-dir",
+                    "/tmp/b",
+                    "hello",
+                ],
+                expect: "pass",
+            },
         ],
     },
     gemini: {
@@ -317,6 +399,8 @@ export const UPSTREAM_CLI_CONTRACTS = {
             "disallowedTools",
             // Phase 4 slice δ
             "maxTurns",
+            // Phase 4 slice ζ
+            "workingDir",
         ],
         flags: {
             "-p": { arity: "one", description: "Prompt text" },
@@ -346,6 +430,10 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 pattern: /^[1-9][0-9]*$/,
                 description: "Agent-loop iteration cap (Phase 4 slice δ)",
             },
+            "--cwd": {
+                arity: "one",
+                description: "Working directory for the invocation (Phase 4 slice ζ)",
+            },
         },
         env: {},
         conformanceFixtures: [
@@ -373,6 +461,12 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 args: ["-p", "hello", "--max-turns", "0"],
                 expect: "fail",
             },
+            {
+                id: "grok-working-dir",
+                description: "Phase 4 slice ζ: --cwd <DIR> is accepted",
+                args: ["-p", "hello", "--cwd", "/tmp/work"],
+                expect: "pass",
+            },
         ],
     },
     mistral: {
@@ -401,6 +495,9 @@ export const UPSTREAM_CLI_CONTRACTS = {
             // Phase 4 slice δ
             "maxTurns",
             "maxPrice",
+            // Phase 4 slice ζ
+            "workingDir",
+            "addDir",
         ],
         flags: {
             "-p": { arity: "one", description: "Prompt text" },
@@ -435,6 +532,14 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 pattern: /^(0|[1-9][0-9]*)(\.[0-9]+)?$/,
                 description: "Cumulative cost cap in USD (Phase 4 slice δ, programmatic mode only)",
             },
+            "--workdir": {
+                arity: "one",
+                description: "Working directory for the invocation (Phase 4 slice ζ)",
+            },
+            "--add-dir": {
+                arity: "one",
+                description: "Additional writable workspace directory (Phase 4 slice ζ; repeat once per directory)",
+            },
         },
         env: {
             VIBE_ACTIVE_MODEL: {
@@ -479,6 +584,29 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 env: { VIBE_ACTIVE_MODEL: "mistral-medium-3.5" },
                 expect: "fail",
             },
+            {
+                id: "mistral-working-dir",
+                description: "Phase 4 slice ζ: --workdir <DIR> is accepted",
+                args: ["-p", "hello", "--agent", "auto-approve", "--workdir", "/tmp/work"],
+                env: { VIBE_ACTIVE_MODEL: "mistral-medium-3.5" },
+                expect: "pass",
+            },
+            {
+                id: "mistral-add-dir",
+                description: "Phase 4 slice ζ: repeated --add-dir is accepted",
+                args: [
+                    "-p",
+                    "hello",
+                    "--agent",
+                    "auto-approve",
+                    "--add-dir",
+                    "/tmp/a",
+                    "--add-dir",
+                    "/tmp/b",
+                ],
+                env: { VIBE_ACTIVE_MODEL: "mistral-medium-3.5" },
+                expect: "pass",
+            },
         ],
     },
 };

package/package.json

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