llm-cli-gateway 1.13.2 → 1.14.0

package/CHANGELOG.md

@@ -2,6 +2,154 @@
 
 All notable changes to the llm-cli-gateway project.
 
+## [1.14.0] - 2026-05-28 — Phase 4 slice κ (Claude explicit `cache_control` via `--input-format stream-json`)
+
+Ships the ninth Phase 4 slice. Callers can now opt their stable
+`promptParts` blocks into Anthropic's explicit `cache_control`
+breakpoints — the gateway switches from positional `-p <prompt>` to
+`claude -p --input-format stream-json` and pipes a JSON content-blocks
+payload via stdin. Smoke-test against a live 1-hour-cache-enabled
+account observed a **15,511-token shift from `cache_creation` to
+`cache_read` on the second call, 82 % cost drop, 36 % latency drop**.
+
+Seven recommendation commits land alongside the feature (default
+`outputFormat`, auto-emit-from-config, observability split, warning,
+schema mutex, smoke-script gate, tool description) plus three
+falsifiability-tightening commits driven by the multi-LLM review gate.
+
+### Added — slice κ feature
+
+- **`PromptParts.cacheControl`** (`src/prompt-parts.ts`): per-block
+  boolean opt-in (`system?`/`tools?`/`context?`) with strict Zod
+  schema. The `task` field is intentionally never markable — it's the
+  volatile tail. Setting any flag activates the κ emission path.
+- **`assembleClaudeCacheBlocks(parts)`** helper (`src/prompt-parts.ts`):
+  builds the `{type:"user",message:{role:"user",content:[…]}}` payload
+  in `system → tools → context → task` order. Each marked non-empty
+  block gets `cache_control: {type:"ephemeral", ttl:"1h"}`. Empty
+  parts are silently skipped; markers on empty parts are a no-op.
+- **`prepareClaudeRequest` κ branch** (`src/index.ts`): when the
+  caller marks any block AND requests `outputFormat: "stream-json"`,
+  argv switches to `-p --input-format stream-json --output-format
+  stream-json --include-partial-messages --verbose` with NO positional
+  prompt; the prep result carries `stdinPayload` + `cacheControlBlocks`.
+  Mixing `cacheControl` with `text`/`json` output returns an
+  actionable error instead of silently coercing.
+- **`-p` arity widened** to a new `"optional"` (`src/upstream-contracts.ts`):
+  consumes the next token as a value iff it does not start with `-`.
+  Preserves the legacy `-p <prompt>` positional form AND validates the
+  κ `-p` standalone form. New `--input-format` flag registered with
+  `values: ["text","stream-json"]`. New conformance fixture
+  `claude-input-format-stream-json` pins the exact κ argv combo.
+- **Executor + AsyncJobManager stdin** (`src/executor.ts`,
+  `src/async-job-manager.ts`): both gain `stdin?: string` options.
+  When set, stdio[0] switches from `"ignore"` to `"pipe"` and the
+  payload is written. The stdin payload participates in the
+  AsyncJobManager dedup key — two requests with identical argv but
+  different cache_control payloads cannot collide.
+- **Flight recorder migration v4** (`src/flight-recorder.ts`):
+  `cache_control_blocks INTEGER` column added idempotently;
+  `FlightLogStart.cacheControlBlocks?` persists the per-request
+  marker count for cache_state aggregates.
+
+### Added — seven recommendations (rec #1..#7)
+
+- **Rec #1** — `claude_request` + `claude_request_async` default
+  `outputFormat` changes from `"text"` to `"stream-json"`. The gateway
+  already parses NDJSON usage events; the prior default routed every
+  call through unparseable text, leaving 1,078 historic FR rows with
+  NULL tokens. Override to `"text"` still works for callers that
+  truly want raw stdout (loses observability).
+- **Rec #2** — `[cache_awareness].emit_anthropic_cache_control`
+  config flag is now wired. When enabled AND the caller passes a
+  `promptParts` whose stable prefix exceeds the per-model threshold
+  (`minStableTokensForModel`), the gateway auto-marks the rightmost
+  non-empty stable block (context → tools → system priority) with
+  `ttl: "1h"`. Skipped when `optimizePrompt: true` (rec #5 desync
+  risk) or `outputFormat !== "stream-json"`.
+- **Rec #3** — `GlobalCacheStats` (`src/cache-stats.ts`) gains five
+  derived metrics that distinguish κ-explicit hits from Claude Code's
+  baseline cache reads in the same flight-recorder window:
+  `explicitCacheControlRows`, `explicitCacheControlHits`,
+  `explicitCacheControlHitRate`, `stablePrefixReuseCount`,
+  `avgCacheCreationAfterFirstCall` (averaged over rows AFTER the
+  first-by-datetime in each stable-prefix reuse group).
+- **Rec #4** — new structured warning `cacheable_prefix_uncached`
+  (`src/index.ts`): fires when `promptParts`' stable prefix is above
+  the per-model threshold but no `cache_control` breakpoint will be
+  emitted (caller didn't set it AND auto-emit also didn't fire). The
+  warning includes the measured `stablePrefixTokens`, `threshold`,
+  and `reason` (outputFormat-not-streamjson / config-off /
+  no-eligible-block). Threaded through both Claude handlers.
+- **Rec #5** — `prepareClaudeRequest` refuses `optimizePrompt: true`
+  combined with `promptParts.cacheControl` (`src/index.ts:1455`)
+  before optimization runs. Without this mutex the FR `prompt` column
+  would log optimized text while Claude actually received raw
+  promptParts blocks via stdin, breaking prefix-cache reuse on the
+  next call. Actionable error message points the caller at the
+  combination to drop.
+- **Rec #6** — new `npm run smoke:cache-control` script
+  (`package.json`). Runs `docs/plans/slice-kappa-smoke-test.mjs`,
+  which gates on `SMOKE_CACHE_CONTROL=1` env var with a "BILLABLE
+  TEST" banner so accidental invocation in CI does not burn live
+  Anthropic credit (~$0.08 per run).
+- **Rec #7** — both Claude tools' `promptParts` descriptions now
+  explicitly document the `cacheControl` opt-in, the
+  `outputFormat: "stream-json"` requirement, the `ttl='1h'`
+  hard-code, and the "task is the volatile tail" convention.
+
+### Tests + multi-LLM review gate
+
+`886 → 940` tests pass. 54 new tests across `Kα/Kβ/Kγ/Kδ/Kε/Kζ`
+regression sets + 13 falsifiability-gap closures + 1 SQL-drop
+falsifier strengthening. Every new test is mutation-probe-verified:
+the targeted regression goes red on the predicted mutation.
+
+The branch passed a strict-evidence multi-LLM review gate per the
+project's standing protocol (`feedback_multi_llm_review_gate.md` and
+`feedback_test_veracity_audit_protocol.md`). Round 3 was sequential
+to avoid concurrent gateway contention; all four reviewers — Codex
+(`gpt-5.4`), Grok (`grok-build`), Mistral (`mistral-medium-3.5`),
+Claude (`sonnet-4-6`) — issued **UNCONDITIONAL APPROVE** against the
+head with file:line citations and executed mutation probes. The
+iteration trail (Codex round-3 REJECT → fix → recheck APPROVE; Grok
+round-3 REJECT → fix → recheck APPROVE; Mistral + Claude first-pass
+APPROVE) is preserved in commit history (`bea1aee` and `bbc3b5f`).
+
+### Caller-honest framing
+
+- κ adds caller-side reuse ON TOP of the irreducible ~10–12K
+  `cache_creation` token floor that every fresh `claude -p` session
+  rebuilds (Claude Code's session-wrap content). The *added* benefit
+  scales with the caller's stable block size, not the total prompt.
+- The `ttl='1h'` hard-code is mandatory because Anthropic rejects a
+  `5m` block after Claude Code's own 1h-marked session blocks; the
+  gateway warns if `[cache_awareness].anthropic_ttl_seconds` says 300.
+- Recommended migration: callers running batch / orchestration /
+  repeated similar prompts should opt in; callers running one-shot
+  ad-hoc prompts won't see benefit.
+
+### Files
+
+```
+src/prompt-parts.ts          — PromptParts.cacheControl + assembleClaudeCacheBlocks
+src/index.ts                 — prepareClaudeRequest κ branch + rec #1/#2/#4/#5/#7 + handler threading
+src/upstream-contracts.ts    — arity "optional", --input-format, claude-input-format-stream-json fixture
+src/executor.ts              — ExecuteOptions.stdin? threading
+src/async-job-manager.ts     — stdin? + dedup-key + cacheControlBlocks plumbing
+src/flight-recorder.ts       — migration v4 + cache_control_blocks column
+src/cache-stats.ts           — GlobalCacheStats 5 new derived metrics
+package.json                 — smoke:cache-control script
+docs/plans/slice-kappa.spec.md                   — audit spec
+docs/plans/slice-kappa-final-review.spec.md      — round-3 review spec
+docs/plans/slice-kappa-captures/                 — live smoke evidence
+docs/plans/slice-kappa-smoke-test.mjs            — billable smoke script (SMOKE_CACHE_CONTROL gated)
+src/__tests__/test-veracity-regressions-slice-kappa.test.ts — 40 κ regressions (Kα/Kβ/Kγ/Kδ/Kε/Kζ)
+src/__tests__/cache-stats.test.ts                — +7 rec #3 + SQL-drop falsifier tests
+src/__tests__/prompt-parts-tool-wiring.test.ts   — +5 B1/B2/D1/D2 schema falsifiers
+src/__tests__/smoke-script-gate.test.ts          — 2 I2 subprocess tests
+```
+
 ## [1.13.2] - 2026-05-27 — Claude stream-json regression fix (--verbose now required)
 
 Patch release. Single user-facing fix to `claude_request` /

package/dist/async-job-manager.d.ts

@@ -16,6 +16,13 @@ export interface AsyncJobFlightRecorderEntry {
     sessionId?: string;
     stablePrefixHash?: string;
     stablePrefixTokens?: number;
+    /**
+     * Slice κ: count of caller-supplied prompt-parts content blocks the
+     * gateway emitted with explicit Anthropic `cache_control` markers
+     * (ttl='1h'). Only set for Claude requests that opt into κ; left
+     * undefined elsewhere so legacy rows stay NULL.
+     */
+    cacheControlBlocks?: number;
 }
 /**
  * Slice 1.5 usage-extraction callback. Closures MUST be constructed from
@@ -66,6 +73,13 @@ export interface StartJobOptions {
      * therefore do NOT collide on dedup.
      */
     env?: Record<string, string>;
+    /**
+     * Slice κ: optional UTF-8 payload to pipe into the child's stdin.
+     * Participates in the dedup key — two requests with identical argv
+     * but different stdin do NOT collide. When set, stdio[0] is "pipe";
+     * when unset, stdio[0] stays "ignore" (regression-protected).
+     */
+    stdin?: string;
     /**
      * Optional hook fired exactly once when the job reaches a terminal state.
      * Used by callers that own per-request resources (outputSchema temp files,
@@ -168,7 +182,7 @@ export declare class AsyncJobManager {
      * Existing callers keep working unchanged; forceRefresh is exposed as a trailing
      * optional param for the dedup-aware path.
      */
-    startJob(cli: LlmCli, args: string[], correlationId: string, cwd?: string, idleTimeoutMs?: number, outputFormat?: string, forceRefresh?: boolean, env?: Record<string, string>, onComplete?: () => void, flightRecorderEntry?: AsyncJobFlightRecorderEntry, extractUsage?: AsyncJobUsageExtractor, writeFlightStart?: boolean): AsyncJobSnapshot;
+    startJob(cli: LlmCli, args: string[], correlationId: string, cwd?: string, idleTimeoutMs?: number, outputFormat?: string, forceRefresh?: boolean, env?: Record<string, string>, onComplete?: () => void, flightRecorderEntry?: AsyncJobFlightRecorderEntry, extractUsage?: AsyncJobUsageExtractor, writeFlightStart?: boolean, stdin?: string): AsyncJobSnapshot;
     /**
      * Start a job, with optional dedup against recent identical requests.
      * Returns `{ snapshot, deduped }` so callers can log/report the short-circuit.

package/dist/async-job-manager.js

@@ -207,8 +207,16 @@ export class AsyncJobManager {
      * (sorted keys → JSON-stringified). This prevents two Mistral requests with the
      * same argv but different `VIBE_ACTIVE_MODEL` from deduping onto each other.
      */
-    buildRequestKey(cli, args, env) {
-        return computeRequestKey(cli, args, canonicaliseEnvForKey(env));
+    buildRequestKey(cli, args, env, stdin) {
+        // Slice κ: stdin participates in the dedup key. Two Claude requests
+        // with identical argv but different cache_control content blocks
+        // would otherwise collide on dedup and the second caller would get
+        // the wrong response. The legacy "no stdin" code path passes
+        // stdin=undefined, which serialises to the same empty marker the
+        // previous version emitted — non-κ dedup is unchanged.
+        const extraEnv = canonicaliseEnvForKey(env);
+        const extra = stdin === undefined ? extraEnv : `${extraEnv}|stdin:${stdin}`;
+        return computeRequestKey(cli, args, extra);
     }
     fireOnComplete(job) {
         if (job.onCompleteFired)
@@ -417,13 +425,14 @@ export class AsyncJobManager {
      * Existing callers keep working unchanged; forceRefresh is exposed as a trailing
      * optional param for the dedup-aware path.
      */
-    startJob(cli, args, correlationId, cwd, idleTimeoutMs, outputFormat, forceRefresh, env, onComplete, flightRecorderEntry, extractUsage, writeFlightStart) {
+    startJob(cli, args, correlationId, cwd, idleTimeoutMs, outputFormat, forceRefresh, env, onComplete, flightRecorderEntry, extractUsage, writeFlightStart, stdin) {
         return this.startJobWithDedup(cli, args, correlationId, {
             cwd,
             idleTimeoutMs,
             outputFormat,
             forceRefresh,
             env,
+            stdin,
             onComplete,
             flightRecorderEntry,
             extractUsage,
@@ -439,8 +448,8 @@ export class AsyncJobManager {
      * is returned without spawning a new process. forceRefresh skips dedup entirely.
      */
     startJobWithDedup(cli, args, correlationId, opts = {}) {
-        const { cwd, idleTimeoutMs, outputFormat, forceRefresh, env: extraEnv, onComplete, flightRecorderEntry, extractUsage, writeFlightStart, } = opts;
-        const requestKey = this.buildRequestKey(cli, args, extraEnv);
+        const { cwd, idleTimeoutMs, outputFormat, forceRefresh, env: extraEnv, stdin, onComplete, flightRecorderEntry, extractUsage, writeFlightStart, } = opts;
+        const requestKey = this.buildRequestKey(cli, args, extraEnv, stdin);
         if (!forceRefresh && this.store) {
             try {
                 const existing = this.store.findByRequestKey(requestKey);
@@ -489,9 +498,18 @@ export class AsyncJobManager {
         const baseEnv = envWithExtendedPath(process.env, getExtendedPath());
         const child = spawnCliProcess(command, args, {
             cwd,
-            stdio: ["ignore", "pipe", "pipe"],
+            stdio: stdin === undefined ? ["ignore", "pipe", "pipe"] : ["pipe", "pipe", "pipe"],
             env: { ...baseEnv, ...(extraEnv ?? {}) },
         });
+        if (stdin !== undefined && child.stdin) {
+            try {
+                child.stdin.write(stdin);
+            }
+            catch (err) {
+                this.logger.error(`Job ${id} failed to write stdin payload`, err);
+            }
+            child.stdin.end();
+        }
         // Single cleanup flag to prevent double-unregister
         let groupCleaned = false;
         const cleanupGroup = () => {
@@ -560,6 +578,7 @@ export class AsyncJobManager {
                     asyncJobId: id,
                     stablePrefixHash: flightRecorderEntry.stablePrefixHash,
                     stablePrefixTokens: flightRecorderEntry.stablePrefixTokens,
+                    cacheControlBlocks: flightRecorderEntry.cacheControlBlocks,
                 });
             }
             catch (err) {

package/dist/cache-stats.d.ts

@@ -76,6 +76,32 @@ export interface GlobalCacheStats {
         estimatedSavingsUsd: number;
     }>;
     estimatedSavingsUsd: number;
+    /**
+     * Rec #3 (slice κ): derived metrics that distinguish gateway-driven
+     * κ-explicit `cache_control` breakpoints from Claude Code's
+     * own baseline cache reads.
+     *
+     * - explicitCacheControlRows: rows where the gateway emitted at
+     *   least one `cache_control` marker (`cache_control_blocks > 0`).
+     * - explicitCacheControlHits: those rows whose `cache_read_tokens
+     *   > 0` — closest signal we have to "the caller's marked block
+     *   actually hit Anthropic's cache" (still includes Claude Code's
+     *   baseline cache reads on top, which is unavoidable without
+     *   per-block token accounting from Anthropic).
+     * - explicitCacheControlHitRate: ratio explicit hits / explicit rows.
+     * - stablePrefixReuseCount: distinct `stable_prefix_hash` values
+     *   that appear in >1 row in-window (i.e. real reuse opportunities).
+     * - avgCacheCreationAfterFirstCall: averaged across stable-prefix
+     *   reuse groups, the cache_creation_tokens on rows AFTER the
+     *   first-by-datetime in each group. Drops sharply when caller
+     *   blocks are reused; stays high when Claude Code's session-wrap
+     *   floor dominates.
+     */
+    explicitCacheControlRows: number;
+    explicitCacheControlHits: number;
+    explicitCacheControlHitRate: number;
+    stablePrefixReuseCount: number;
+    avgCacheCreationAfterFirstCall: number | null;
 }
 export declare function computeSessionCacheStats(db: FlightRecorderQuery, sessionId: string): SessionCacheStats;
 export interface TtlPolicy {

package/dist/cache-stats.js

@@ -159,14 +159,16 @@ export function computeGlobalCacheStats(db, opts = {}) {
               COALESCE(cache_read_tokens, 0) AS cache_read_tokens,
               COALESCE(cache_creation_tokens, 0) AS cache_creation_tokens,
               stable_prefix_hash,
-              datetime_utc
+              datetime_utc,
+              cache_control_blocks
        FROM requests
        WHERE datetime_utc >= ?`
         : `SELECT cli, model,
               COALESCE(cache_read_tokens, 0) AS cache_read_tokens,
               COALESCE(cache_creation_tokens, 0) AS cache_creation_tokens,
               stable_prefix_hash,
-              datetime_utc
+              datetime_utc,
+              cache_control_blocks
        FROM requests`;
     const rows = sinceIso ? db.queryRequests(sql, sinceIso) : db.queryRequests(sql);
     const perCliMap = new Map();
@@ -175,6 +177,17 @@ export function computeGlobalCacheStats(db, opts = {}) {
     let totalRead = 0;
     let totalCreation = 0;
     let totalSavings = 0;
+    // Rec #3: κ-explicit metrics. A row is "κ-explicit" iff it has
+    // `cache_control_blocks > 0` — i.e. the gateway emitted at least one
+    // caller-supplied `cache_control` marker. Rows with NULL or 0 are
+    // either pre-v4 or non-κ Claude / non-Claude requests.
+    let explicitRows = 0;
+    let explicitHits = 0;
+    // Per-prefix reuse tracking: collect cache_creation_tokens for every
+    // row keyed by stable_prefix_hash, ordered ascending by datetime_utc.
+    // For each group with >1 row, drop the first (the cache-write call)
+    // and average the rest (the cache-read calls).
+    const perPrefix = new Map();
     for (const row of rows) {
         totalRequests += 1;
         const reads = safeNum(row.cache_read_tokens);
@@ -183,6 +196,17 @@ export function computeGlobalCacheStats(db, opts = {}) {
         totalCreation += creation;
         if (reads > 0)
             totalHits += 1;
+        const ccBlocks = safeNum(row.cache_control_blocks);
+        if (ccBlocks > 0) {
+            explicitRows += 1;
+            if (reads > 0)
+                explicitHits += 1;
+        }
+        if (row.stable_prefix_hash) {
+            const arr = perPrefix.get(row.stable_prefix_hash) ?? [];
+            arr.push({ datetime_utc: row.datetime_utc, cache_creation_tokens: creation });
+            perPrefix.set(row.stable_prefix_hash, arr);
+        }
         if (!isCacheStatsCli(row.cli))
             continue;
         const cli = row.cli;
@@ -203,6 +227,20 @@ export function computeGlobalCacheStats(db, opts = {}) {
         agg.estimatedSavingsUsd += savings;
         perCliMap.set(cli, agg);
     }
+    let stablePrefixReuseCount = 0;
+    let creationAfterFirstSum = 0;
+    let creationAfterFirstCount = 0;
+    for (const arr of perPrefix.values()) {
+        if (arr.length <= 1)
+            continue;
+        stablePrefixReuseCount += 1;
+        arr.sort((a, b) => a.datetime_utc < b.datetime_utc ? -1 : a.datetime_utc > b.datetime_utc ? 1 : 0);
+        for (let i = 1; i < arr.length; i++) {
+            creationAfterFirstSum += arr[i].cache_creation_tokens;
+            creationAfterFirstCount += 1;
+        }
+    }
+    const avgCacheCreationAfterFirstCall = creationAfterFirstCount > 0 ? creationAfterFirstSum / creationAfterFirstCount : null;
     const perCli = Array.from(perCliMap.entries()).map(([cli, agg]) => ({
         cli,
         requestCount: agg.requestCount,
@@ -221,5 +259,10 @@ export function computeGlobalCacheStats(db, opts = {}) {
         totalCacheCreationTokens: totalCreation,
         perCli,
         estimatedSavingsUsd: totalSavings,
+        explicitCacheControlRows: explicitRows,
+        explicitCacheControlHits: explicitHits,
+        explicitCacheControlHitRate: explicitRows > 0 ? explicitHits / explicitRows : 0,
+        stablePrefixReuseCount,
+        avgCacheCreationAfterFirstCall,
     };
 }

package/dist/executor.d.ts

@@ -7,6 +7,14 @@ export interface ExecuteOptions {
     logger?: Logger;
     /** Extra environment variables to inject; merged after PATH. */
     env?: NodeJS.ProcessEnv;
+    /**
+     * Slice κ: optional UTF-8 payload to write to the child's stdin
+     * immediately after spawn. When provided, stdio for stdin switches
+     * from "ignore" to "pipe" so the CLI can read the payload (used by
+     * `claude --input-format stream-json`). Undefined preserves the
+     * legacy stdio:["ignore","pipe","pipe"] shape.
+     */
+    stdin?: string;
 }
 export interface ExecuteResult {
     stdout: string;

package/dist/executor.js

@@ -296,16 +296,21 @@ export function spawnCliProcess(command, args, options) {
     return proc;
 }
 export async function executeCli(command, args, options = {}) {
-    const { timeout, idleTimeout, cwd, env: extraEnv } = options;
+    const { timeout, idleTimeout, cwd, env: extraEnv, stdin } = options;
     const extendedPath = getExtendedPath();
     const baseEnv = envWithExtendedPath(process.env, extendedPath);
     const circuitBreaker = getCircuitBreaker(command);
     const runOnce = () => new Promise((resolve, reject) => {
+        const stdio = stdin === undefined ? ["ignore", "pipe", "pipe"] : ["pipe", "pipe", "pipe"];
         const proc = spawnCliProcess(command, args, {
             cwd,
-            stdio: ["ignore", "pipe", "pipe"],
+            stdio,
             env: { ...baseEnv, ...(extraEnv ?? {}) },
         });
+        if (stdin !== undefined && proc.stdin) {
+            proc.stdin.write(stdin);
+            proc.stdin.end();
+        }
         let stdout = "";
         let stderr = "";
         let timedOut = false;

package/dist/flight-recorder.d.ts

@@ -8,6 +8,13 @@ export interface FlightLogStart {
     asyncJobId?: string;
     stablePrefixHash?: string;
     stablePrefixTokens?: number;
+    /**
+     * Slice κ: number of caller-supplied prompt-parts content blocks
+     * that the gateway emitted with an explicit `cache_control`
+     * breakpoint on this request. `null` (default) for non-κ requests,
+     * including pre-κ rows after a v4 migration of a legacy DB.
+     */
+    cacheControlBlocks?: number;
 }
 export interface FlightLogResult {
     response: string;

package/dist/flight-recorder.js

@@ -55,6 +55,20 @@ function ensureStablePrefixColumns(db) {
     }
     db.exec("CREATE INDEX IF NOT EXISTS idx_requests_stable_hash ON requests(stable_prefix_hash)");
 }
+/**
+ * Idempotent v4 migration (slice κ): add `cache_control_blocks` column
+ * to the `requests` table. Counts the caller-supplied content blocks
+ * the gateway emitted with an explicit Anthropic `cache_control`
+ * marker. Pre-κ rows keep NULL; only κ-opt-in callers ever set the
+ * column to a non-NULL integer.
+ */
+function ensureCacheControlBlocksColumn(db) {
+    const rows = db.prepare("PRAGMA table_info(requests)").all?.() ?? [];
+    const names = new Set(rows.map((row) => (row && typeof row.name === "string" ? row.name : "")));
+    if (!names.has("cache_control_blocks")) {
+        db.exec("ALTER TABLE requests ADD COLUMN cache_control_blocks INTEGER");
+    }
+}
 export function resolveFlightRecorderDbPath() {
     const configured = process.env.LLM_GATEWAY_LOGS_DB;
     if (configured !== undefined) {
@@ -176,6 +190,14 @@ export class FlightRecorder {
         this.db
             .prepare("INSERT OR IGNORE INTO _migrations(version, applied_at) VALUES(3, ?)")
             .run(new Date().toISOString());
+        // Migration v4: cache_control_blocks (slice κ). Pre-κ rows keep NULL;
+        // only κ-opt-in writes populate this. Aggregates in cache-stats /
+        // MCP resources can use this to separate explicit κ hits from
+        // implicit prefix-cache hits.
+        ensureCacheControlBlocksColumn(this.db);
+        this.db
+            .prepare("INSERT OR IGNORE INTO _migrations(version, applied_at) VALUES(4, ?)")
+            .run(new Date().toISOString());
         if (process.platform !== "win32") {
             try {
                 chmodSync(dbPath, 0o600);
@@ -186,9 +208,11 @@ export class FlightRecorder {
         }
         const insertRequest = this.db.prepare(`
       INSERT INTO requests (id, cli, model, prompt, system, session_id, datetime_utc,
-                            stable_prefix_hash, stable_prefix_tokens)
+                            stable_prefix_hash, stable_prefix_tokens,
+                            cache_control_blocks)
       VALUES (@id, @cli, @model, @prompt, @system, @session_id, @datetime_utc,
-              @stable_prefix_hash, @stable_prefix_tokens)
+              @stable_prefix_hash, @stable_prefix_tokens,
+              @cache_control_blocks)
     `);
         const insertMetadata = this.db.prepare(`
       INSERT INTO gateway_metadata (request_id, async_job_id, status)
@@ -205,6 +229,7 @@ export class FlightRecorder {
                 datetime_utc: new Date().toISOString(),
                 stable_prefix_hash: entry.stablePrefixHash ?? null,
                 stable_prefix_tokens: entry.stablePrefixTokens ?? null,
+                cache_control_blocks: entry.cacheControlBlocks ?? null,
             });
             insertMetadata.run({
                 request_id: entry.correlationId,

package/dist/index.d.ts

@@ -82,7 +82,7 @@ export interface GatewayServerDeps {
     persistence?: PersistenceConfig;
     cacheAwareness?: CacheAwarenessConfig;
 }
-interface GatewayServerRuntime {
+export interface GatewayServerRuntime {
     sessionManager: ISessionManager;
     resourceProvider: ResourceProvider;
     db: DatabaseConnection | null;
@@ -94,6 +94,9 @@ interface GatewayServerRuntime {
     persistence: PersistenceConfig;
     cacheAwareness: CacheAwarenessConfig;
 }
+export declare function resolveGatewayServerRuntime(deps?: GatewayServerDeps, options?: {
+    isolateState?: boolean;
+}): GatewayServerRuntime;
 export declare function extractUsageAndCost(cli: "claude" | "codex" | "gemini" | "grok" | "mistral", output: string, outputFormat?: string, 
 /**
  * Optional context for off-stdout telemetry sources. Today only Mistral
@@ -129,6 +132,27 @@ interface CliRequestPrep {
     stablePrefixHash: string | null;
     /** Heuristic token count (bytes/4) of the same stable prefix. */
     stablePrefixTokens: number | null;
+    /**
+     * Slice κ (Claude only): JSON stream-json payload to feed on stdin
+     * when the gateway emits `-p --input-format stream-json`. Undefined
+     * when the caller did not opt into Anthropic `cache_control`
+     * breakpoints. Non-κ providers always leave this undefined.
+     */
+    stdinPayload?: string;
+    /**
+     * Slice κ (Claude only): number of caller-supplied content blocks
+     * that carry an explicit `cache_control` marker. Threaded into the
+     * flight recorder so `cache_state` aggregates can distinguish
+     * κ-explicit breakpoints from implicit prefix-cache hits.
+     */
+    cacheControlBlocks?: number;
+    /**
+     * Rec #4: structured warnings produced during prep (e.g. cacheable
+     * stable prefix without cacheControl). Handlers merge these with any
+     * other warnings (cache_ttl_expiring_soon, etc.) before returning to
+     * the caller.
+     */
+    warnings?: WarningEntry[];
 }
 export declare function prepareClaudeRequest(params: {
     prompt?: string;

package/dist/index.js

@@ -16,7 +16,7 @@ import { createSessionManager } from "./session-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, } from "./config.js";
+import { loadConfig, loadPersistenceConfig, loadCacheAwarenessConfig, minStableTokensForModel, } from "./config.js";
 import { checkHealth } from "./health.js";
 import { clearModelRegistryCache, getAvailableCliInfo, getCliInfo, resolveModelAlias, } from "./model-registry.js";
 import { AsyncJobManager, } from "./async-job-manager.js";
@@ -26,7 +26,7 @@ import { checkReviewIntegrity } from "./review-integrity.js";
 import { buildClaudeMcpConfig, CLAUDE_MCP_SERVER_NAMES, } from "./claude-mcp-config.js";
 import { resolveGrokSessionArgs, resolveMistralSessionArgs, resolveCodexSessionArgs, sanitizeCliArgValues, prepareMistralRequest as buildMistralCliInvocation, MISTRAL_AGENT_MODES, GATEWAY_SESSION_PREFIX, resolveClaudePermissionFlags, resolveCodexSandboxFlags, CLAUDE_PERMISSION_MODES, GEMINI_APPROVAL_MODES, CODEX_SANDBOX_MODES, CODEX_ASK_FOR_APPROVAL_MODES, CLAUDE_EFFORT_LEVELS, prepareClaudeHighImpactFlags, validateClaudeAgentsMap, prepareCodexHighImpactFlags, prepareCodexForkRequest, CODEX_CONFIG_OVERRIDES_SCHEMA, prepareGeminiHighImpactFlags, prependGeminiAttachments, resolveGeminiSessionPlan, GEMINI_HIGH_IMPACT_PARAMS_SCHEMA, } from "./request-helpers.js";
 import { createFlightRecorder } from "./flight-recorder.js";
-import { resolvePromptInput, PromptPartsSchema } from "./prompt-parts.js";
+import { resolvePromptInput, PromptPartsSchema, assembleClaudeCacheBlocks, } from "./prompt-parts.js";
 import { computeSessionCacheStats, computeTtlRemaining } from "./cache-stats.js";
 import { getCliVersions, runCliUpgrade } from "./cli-updater.js";
 import { startHttpGateway } from "./http-transport.js";
@@ -253,7 +253,7 @@ export const SESSION_PROVIDER_VALUES = ["claude", "codex", "gemini", "grok", "mi
 export const SESSION_PROVIDER_ENUM = z.enum(SESSION_PROVIDER_VALUES);
 let activeServer = null;
 let activeHttpGateway = null;
-function resolveGatewayServerRuntime(deps = {}, options = {}) {
+export function resolveGatewayServerRuntime(deps = {}, options = {}) {
     const runtimeLogger = deps.logger ?? logger;
     const runtimeSessionManager = deps.sessionManager ?? sessionManager;
     const runtimePerformanceMetrics = deps.performanceMetrics ??
@@ -316,7 +316,14 @@ async function awaitJobOrDefer(cli, args, corrId, idleTimeoutMs, outputFormat, f
  * `writeFlightStart` is NEVER true on this path: the sync handler is
  * always the upstream logStart writer.
  */
-flightRecorderEntry, extractUsage) {
+flightRecorderEntry, extractUsage, 
+/**
+ * Slice κ: optional stdin payload piped to the child CLI. Currently
+ * only Claude's `--input-format stream-json` path sets this. Threaded
+ * through both the direct-execute fallback (SYNC_DEADLINE_MS===0) and
+ * the AsyncJobManager spawn path, and participates in the dedup key.
+ */
+stdin) {
     // U26 fix: ownership of onComplete is a contract. Once this function returns
     // OR throws, the caller MUST consider onComplete consumed — i.e. it has
     // either been run, or the AsyncJobManager has taken ownership of it. The
@@ -350,6 +357,7 @@ flightRecorderEntry, extractUsage) {
                 idleTimeout: idleTimeoutMs,
                 logger: runtime.logger,
                 env: env ? { ...process.env, ...env } : undefined,
+                stdin,
             });
         }
         finally {
@@ -365,6 +373,7 @@ flightRecorderEntry, extractUsage) {
             outputFormat,
             forceRefresh,
             env,
+            stdin,
             onComplete,
             // Sync-deferred path: the upstream sync handler already wrote
             // logStart for this corrId, so writeFlightStart stays false. The
@@ -575,6 +584,7 @@ function buildAsyncFlightRecorderHandoff(cliName, prep, sessionId, outputFormat)
             sessionId,
             stablePrefixHash: prep.stablePrefixHash ?? undefined,
             stablePrefixTokens: prep.stablePrefixTokens ?? undefined,
+            cacheControlBlocks: prep.cacheControlBlocks,
         },
         extractUsage: (stdout) => extractUsageAndCost(cli, stdout, fmt, { sessionId: sid, home }),
     };
@@ -919,6 +929,19 @@ export function prepareClaudeRequest(params, runtime = resolveGatewayServerRunti
             score: reviewIntegrity.totalScore,
         });
     }
+    // Rec #5 (slice κ): refuse the optimizePrompt + cacheControl combo
+    // before running optimization. Optimization rewrites the assembled
+    // prompt text the flight-recorder logs, but the κ stdin payload is
+    // built from raw `promptParts` content blocks — letting both run
+    // produces a FR row whose `prompt` no longer matches what Claude
+    // actually received, AND any optimisation-driven text change would
+    // silently break Anthropic prefix-cache reuse on the next call.
+    const ccEarly = params.promptParts?.cacheControl;
+    const cacheControlRequestedEarly = !!(ccEarly &&
+        (ccEarly.system || ccEarly.tools || ccEarly.context));
+    if (params.optimizePrompt && cacheControlRequestedEarly) {
+        return createErrorResponse(params.operation, 1, "", corrId, new Error("optimizePrompt is incompatible with promptParts.cacheControl (slice κ): optimization rewrites the assembled prompt text the flight recorder logs, while the cache_control payload is built from raw promptParts; the two would desync and break Anthropic prefix-cache reuse. Disable optimizePrompt when opting into cacheControl."));
+    }
     let effectivePrompt = assembledPrompt;
     if (params.optimizePrompt) {
         const optimized = optimizePromptText(effectivePrompt);
@@ -950,19 +973,127 @@ export function prepareClaudeRequest(params, runtime = resolveGatewayServerRunti
             return createApprovalDeniedResponse(params.operation, approvalDecision);
         }
     }
-    const args = ["-p", effectivePrompt];
+    // Rec #2 (slice κ): auto-emit `cache_control` when the caller passes
+    // `promptParts` whose stable prefix exceeds the per-model minimum,
+    // the caller has NOT explicitly set `cacheControl`, the gateway
+    // config has opted in (`[cache_awareness].emit_anthropic_cache_control`),
+    // and outputFormat is stream-json. Auto-emit marks the LAST non-empty
+    // stable block (context → tools → system priority — the rightmost
+    // stable block covers the widest prefix). Skipped when optimizePrompt
+    // is on (same rec #5 desync risk).
+    //
+    // The 1h ttl is forced regardless of `anthropic_ttl_seconds`: 5m
+    // breakpoints from caller content are rejected by Anthropic once
+    // Claude Code's own 1h-marked session-wrap blocks land ahead of them.
+    let autoEmittedCacheControlBlock = null;
+    if (!cacheControlRequestedEarly &&
+        runtime.cacheAwareness.emitAnthropicCacheControl &&
+        !params.optimizePrompt &&
+        params.outputFormat === "stream-json" &&
+        params.promptParts &&
+        stablePrefixTokens !== null) {
+        const threshold = minStableTokensForModel(runtime.cacheAwareness, resolvedModel ?? "default");
+        if (stablePrefixTokens >= threshold) {
+            const pp = params.promptParts;
+            // Rightmost non-empty stable block — its cache_control breakpoint
+            // covers everything above it in the message (the API matches
+            // breakpoints in order).
+            if (pp.context && pp.context.length > 0)
+                autoEmittedCacheControlBlock = "context";
+            else if (pp.tools && pp.tools.length > 0)
+                autoEmittedCacheControlBlock = "tools";
+            else if (pp.system && pp.system.length > 0)
+                autoEmittedCacheControlBlock = "system";
+            if (autoEmittedCacheControlBlock !== null) {
+                runtime.logger.info(`[${corrId}] auto-emitting cache_control on '${autoEmittedCacheControlBlock}' (stablePrefixTokens=${stablePrefixTokens} >= ${threshold} for model='${resolvedModel ?? "default"}')`);
+                if (runtime.cacheAwareness.anthropicTtlSeconds !== 3600) {
+                    runtime.logger.warn(`[${corrId}] [cache_awareness].anthropic_ttl_seconds=${runtime.cacheAwareness.anthropicTtlSeconds} ignored for Claude CLI path — Anthropic rejects 5m blocks after Claude Code's 1h-marked session-wrap content; using ttl='1h'.`);
+                }
+            }
+        }
+    }
+    // Rec #4: warn when promptParts has a cacheable stable prefix but no
+    // cache_control breakpoint is being emitted (neither explicit nor
+    // auto). Either the caller forgot to set `cacheControl` or
+    // `[cache_awareness].emit_anthropic_cache_control` is off — both
+    // leave the stable prefix bytes unreused across calls, defeating the
+    // point of using `promptParts`.
+    const warnings = [];
+    if (!cacheControlRequestedEarly &&
+        autoEmittedCacheControlBlock === null &&
+        params.promptParts &&
+        stablePrefixTokens !== null) {
+        const threshold = minStableTokensForModel(runtime.cacheAwareness, resolvedModel ?? "default");
+        if (stablePrefixTokens >= threshold) {
+            const reason = params.outputFormat !== "stream-json"
+                ? "outputFormat is not 'stream-json'"
+                : !runtime.cacheAwareness.emitAnthropicCacheControl
+                    ? "[cache_awareness].emit_anthropic_cache_control is false"
+                    : "no eligible non-empty stable block";
+            warnings.push({
+                code: "cacheable_prefix_uncached",
+                message: `Stable prefix is cacheable (${stablePrefixTokens} tokens >= ${threshold} for model='${resolvedModel ?? "default"}') but no cache_control breakpoint will be emitted (${reason}). Set promptParts.cacheControl explicitly, switch outputFormat to 'stream-json', or enable [cache_awareness].emit_anthropic_cache_control.`,
+                stablePrefixTokens,
+                threshold,
+                reason,
+            });
+        }
+    }
+    // Slice κ: switch from the legacy positional `-p <prompt>` emission
+    // to `claude -p --input-format stream-json` and feed a JSON
+    // content-blocks payload via stdin. Non-κ callers (no cacheControl,
+    // or cacheControl with all flags false) take the existing positional
+    // path bit-for-bit. The κ path activates on EITHER an explicit caller
+    // opt-in (`cacheControlRequestedEarly`) OR a gateway-driven auto-emit
+    // (`autoEmittedCacheControlBlock`).
+    const cacheControlRequested = cacheControlRequestedEarly || autoEmittedCacheControlBlock !== null;
+    let stdinPayload;
+    let cacheControlBlocks;
+    if (cacheControlRequested) {
+        if (params.outputFormat !== "stream-json") {
+            return createErrorResponse(params.operation, 1, "", corrId, new Error("promptParts.cacheControl requires outputFormat: 'stream-json' (slice κ pipes the cache_control blocks over --input-format stream-json; text/json output formats cannot carry the required NDJSON usage events)."));
+        }
+        // promptParts is non-null whenever cacheControlRequested is true
+        // (explicit opt-in lives in PromptParts; auto-emit guard requires
+        // promptParts to be defined).
+        const effectiveParts = autoEmittedCacheControlBlock !== null
+            ? {
+                ...params.promptParts,
+                cacheControl: {
+                    ...(params.promptParts.cacheControl ?? {}),
+                    [autoEmittedCacheControlBlock]: true,
+                },
+            }
+            : params.promptParts;
+        const built = assembleClaudeCacheBlocks(effectiveParts);
+        stdinPayload = `${JSON.stringify(built.payload)}\n`;
+        cacheControlBlocks = built.markedBlockCount;
+    }
+    const args = cacheControlRequested
+        ? [
+            "-p",
+            "--input-format",
+            "stream-json",
+            "--output-format",
+            "stream-json",
+            "--include-partial-messages",
+            "--verbose",
+        ]
+        : ["-p", effectivePrompt];
     if (resolvedModel)
         args.push("--model", resolvedModel);
-    if (params.outputFormat === "json") {
-        args.push("--output-format", "json");
-    }
-    else if (params.outputFormat === "stream-json") {
-        // Claude CLI 2.x rejects `--print --output-format stream-json` without
-        // `--verbose`: "When using --print, --output-format=stream-json requires
-        // --verbose". --verbose only affects what claude logs to stderr; the
-        // stream-json stdout payload is unchanged, so the gateway's NDJSON
-        // parser is unaffected.
-        args.push("--output-format", "stream-json", "--include-partial-messages", "--verbose");
+    if (!cacheControlRequested) {
+        if (params.outputFormat === "json") {
+            args.push("--output-format", "json");
+        }
+        else if (params.outputFormat === "stream-json") {
+            // Claude CLI 2.x rejects `--print --output-format stream-json` without
+            // `--verbose`: "When using --print, --output-format=stream-json requires
+            // --verbose". --verbose only affects what claude logs to stderr; the
+            // stream-json stdout payload is unchanged, so the gateway's NDJSON
+            // parser is unaffected.
+            args.push("--output-format", "stream-json", "--include-partial-messages", "--verbose");
+        }
     }
     if (params.allowedTools && params.allowedTools.length > 0) {
         sanitizeCliArgValues(params.allowedTools, "allowedTools");
@@ -1025,6 +1156,9 @@ export function prepareClaudeRequest(params, runtime = resolveGatewayServerRunti
         args,
         stablePrefixHash,
         stablePrefixTokens,
+        stdinPayload,
+        cacheControlBlocks,
+        warnings: warnings.length > 0 ? warnings : undefined,
     };
 }
 export function prepareCodexRequest(params, runtime = resolveGatewayServerRuntime()) {
@@ -2481,15 +2615,15 @@ export function createGatewayServer(deps = {}) {
             .max(100000, "Prompt too long (max 100k chars)")
             .optional()
             .describe("Prompt text for Claude (mutually exclusive with promptParts)"),
-        promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking."),
+        promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task, cacheControl? }. Use for repeated calls that share a stable prefix — `system`/`tools`/`context` are the stable head; `task` is the volatile tail (never marked). Set `cacheControl: { system?: boolean, tools?: boolean, context?: boolean }` to opt into explicit Anthropic prefix caching via `--input-format stream-json` (slice κ). Requires `outputFormat: 'stream-json'` and hard-codes `ttl='1h'` (Anthropic rejects 5m blocks after Claude Code's 1h-marked session-wrap content). Mutually exclusive with `prompt`. The stable prefix hash is logged to the flight recorder for cache_state aggregates."),
         model: z
             .string()
             .optional()
             .describe("Model name or alias (e.g. sonnet, claude-sonnet-4-5-20250929, latest)"),
         outputFormat: z
             .enum(["text", "json", "stream-json"])
-            .default("text")
-            .describe("Output format (text|json|stream-json). stream-json: NDJSON with idle timeout."),
+            .default("stream-json")
+            .describe("Output format (text|json|stream-json). DEFAULT: stream-json — the gateway parses NDJSON usage events to extract input/output/cache_read/cache_creation tokens + cost + model, persists them to the flight recorder for cache_state aggregates, and still returns the assistant text. Override to 'text' only when you truly want unparsed stdout (loses observability)."),
         sessionId: z.string().optional().describe("Session ID (uses active if omitted)"),
         continueSession: z.boolean().default(false).describe("Continue active session"),
         createNewSession: z.boolean().default(false).describe("Force new session"),
@@ -2665,7 +2799,11 @@ export function createGatewayServer(deps = {}) {
             sessionId: effectiveSessionId,
             cli: "claude",
         });
-        const warnings = ttlWarning ? [ttlWarning] : [];
+        // Rec #4: include any prep-time warnings (e.g. cacheable_prefix_uncached).
+        const warnings = [
+            ...(ttlWarning ? [ttlWarning] : []),
+            ...(prep.warnings ?? []),
+        ];
         safeFlightStart({
             correlationId: corrId,
             cli: "claude",
@@ -2674,8 +2812,9 @@ export function createGatewayServer(deps = {}) {
             sessionId: effectiveSessionId,
             stablePrefixHash: prep.stablePrefixHash ?? undefined,
             stablePrefixTokens: prep.stablePrefixTokens ?? undefined,
+            cacheControlBlocks: prep.cacheControlBlocks,
         }, runtime);
-        logger.info(`[${corrId}] claude_request invoked with model=${prep.resolvedModel || "default"}, outputFormat=${outputFormat}, prompt length=${prep.effectivePrompt.length}, sessionId=${effectiveSessionId}`);
+        logger.info(`[${corrId}] claude_request invoked with model=${prep.resolvedModel || "default"}, outputFormat=${outputFormat}, prompt length=${prep.effectivePrompt.length}, sessionId=${effectiveSessionId}, cacheControlBlocks=${prep.cacheControlBlocks ?? 0}`);
         try {
             if (useContinue) {
                 args.push("--continue");
@@ -2687,7 +2826,7 @@ export function createGatewayServer(deps = {}) {
             // Idle timeout only for stream-json (text/json produce no output until done)
             const effectiveIdleTimeout = outputFormat === "stream-json" ? resolveIdleTimeout("claude", idleTimeoutMs) : undefined;
             const claudeSyncFrHandoff = buildAsyncFlightRecorderHandoff("claude", prep, effectiveSessionId, outputFormat);
-            const result = await awaitJobOrDefer("claude", args, corrId, effectiveIdleTimeout, outputFormat, forceRefresh, runtime, undefined, undefined, claudeSyncFrHandoff.flightRecorderEntry, claudeSyncFrHandoff.extractUsage);
+            const result = await awaitJobOrDefer("claude", args, corrId, effectiveIdleTimeout, outputFormat, forceRefresh, runtime, undefined, undefined, claudeSyncFrHandoff.flightRecorderEntry, claudeSyncFrHandoff.extractUsage, prep.stdinPayload);
             // Deferred — job still running, return async reference
             if (isDeferredResponse(result)) {
                 return buildDeferredToolResponse(result, effectiveSessionId);
@@ -3486,15 +3625,15 @@ export function createGatewayServer(deps = {}) {
                 .max(100000, "Prompt too long (max 100k chars)")
                 .optional()
                 .describe("Prompt text for Claude (mutually exclusive with promptParts)"),
-            promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking."),
+            promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task, cacheControl? }. Same semantics as claude_request: stable head (system/tools/context) + volatile tail (task). Set `cacheControl: { system?, tools?, context?: boolean }` to opt into explicit Anthropic prefix caching via `--input-format stream-json` (slice κ); requires `outputFormat: 'stream-json'` and hard-codes `ttl='1h'`. Mutually exclusive with `prompt`. Stable prefix hash logged to flight recorder."),
             model: z
                 .string()
                 .optional()
                 .describe("Model name or alias (e.g. sonnet, claude-sonnet-4-5-20250929, latest)"),
             outputFormat: z
                 .enum(["text", "json", "stream-json"])
-                .default("text")
-                .describe("Output format (text|json|stream-json). stream-json: NDJSON with idle timeout."),
+                .default("stream-json")
+                .describe("Output format (text|json|stream-json). DEFAULT: stream-json — same rationale as claude_request: keeps usage/cache/cost observable for cache_state aggregates. Override to 'text' only when raw stdout is required (loses observability)."),
             sessionId: z.string().optional().describe("Session ID (uses active if omitted)"),
             continueSession: z.boolean().default(false).describe("Continue active session"),
             createNewSession: z.boolean().default(false).describe("Force new session"),
@@ -3669,7 +3808,7 @@ export function createGatewayServer(deps = {}) {
                 assertUpstreamCliArgs("claude", args);
                 assertUpstreamCliEnv("claude", undefined);
                 const claudeAsyncFrHandoff = buildAsyncFlightRecorderHandoff("claude", prep, effectiveSessionId, outputFormat);
-                const job = asyncJobManager.startJob("claude", args, corrId, undefined, effectiveIdleTimeout, outputFormat, forceRefresh, undefined, undefined, claudeAsyncFrHandoff.flightRecorderEntry, claudeAsyncFrHandoff.extractUsage, true);
+                const job = asyncJobManager.startJob("claude", args, corrId, undefined, effectiveIdleTimeout, outputFormat, forceRefresh, undefined, undefined, claudeAsyncFrHandoff.flightRecorderEntry, claudeAsyncFrHandoff.extractUsage, true, prep.stdinPayload);
                 logger.info(`[${corrId}] claude_request_async started job ${job.id}, outputFormat=${outputFormat}`);
                 const asyncResponse = {
                     success: true,
@@ -3685,8 +3824,14 @@ export function createGatewayServer(deps = {}) {
                 if (prep.reviewIntegrity && prep.reviewIntegrity.violations.length > 0) {
                     asyncResponse.reviewIntegrity = prep.reviewIntegrity;
                 }
-                if (ttlWarning) {
-                    asyncResponse.warnings = [ttlWarning];
+                // Rec #4: include any prep-time warnings (e.g.
+                // cacheable_prefix_uncached) alongside ttlWarning.
+                const mergedWarnings = [
+                    ...(ttlWarning ? [ttlWarning] : []),
+                    ...(prep.warnings ?? []),
+                ];
+                if (mergedWarnings.length > 0) {
+                    asyncResponse.warnings = mergedWarnings;
                 }
                 return {
                     content: [

package/dist/prompt-parts.d.ts

@@ -1,25 +1,68 @@
 import { z } from "zod";
+export interface PromptPartsCacheControl {
+    system?: boolean;
+    tools?: boolean;
+    context?: boolean;
+}
 export interface PromptParts {
     system?: string;
     tools?: string;
     context?: string;
     task: string;
+    /**
+     * Slice κ (Claude only): per-block opt-in to Anthropic `cache_control`
+     * breakpoints. Setting `system: true` (or tools/context) marks that
+     * block with `cache_control: {type:"ephemeral", ttl:"1h"}` in the
+     * stream-json payload the gateway pipes to `claude --input-format
+     * stream-json`. The `task` block is NEVER marked (it's the volatile
+     * tail). Empty parts are silently skipped even if their flag is true.
+     *
+     * Constraint: callers MUST also pass `outputFormat:"stream-json"` —
+     * mixing cacheControl with text/json output returns an error response.
+     * `ttl` is hard-coded to `"1h"` because Claude Code injects its own
+     * 1h-marked system blocks ahead of caller content and Anthropic
+     * rejects a 1h block after a 5m block.
+     */
+    cacheControl?: PromptPartsCacheControl;
 }
 export declare const PromptPartsSchema: z.ZodObject<{
     system: z.ZodOptional<z.ZodString>;
     tools: z.ZodOptional<z.ZodString>;
     context: z.ZodOptional<z.ZodString>;
     task: z.ZodString;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        system: z.ZodOptional<z.ZodBoolean>;
+        tools: z.ZodOptional<z.ZodBoolean>;
+        context: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        system?: boolean | undefined;
+        tools?: boolean | undefined;
+        context?: boolean | undefined;
+    }, {
+        system?: boolean | undefined;
+        tools?: boolean | undefined;
+        context?: boolean | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     task: string;
     system?: string | undefined;
     tools?: string | undefined;
     context?: string | undefined;
+    cacheControl?: {
+        system?: boolean | undefined;
+        tools?: boolean | undefined;
+        context?: boolean | undefined;
+    } | undefined;
 }, {
     task: string;
     system?: string | undefined;
     tools?: string | undefined;
     context?: string | undefined;
+    cacheControl?: {
+        system?: boolean | undefined;
+        tools?: boolean | undefined;
+        context?: boolean | undefined;
+    } | undefined;
 }>;
 export interface AssembleResult {
     text: string;
@@ -36,3 +79,34 @@ export interface ResolvePromptInputArgs {
     promptParts?: PromptParts;
 }
 export declare function resolvePromptInput(input: ResolvePromptInputArgs): ResolvedPromptInput;
+export interface ClaudeContentBlock {
+    type: "text";
+    text: string;
+    cache_control?: {
+        type: "ephemeral";
+        ttl: "1h";
+    };
+}
+export interface ClaudeStreamJsonUserMessage {
+    type: "user";
+    message: {
+        role: "user";
+        content: ClaudeContentBlock[];
+    };
+}
+export interface AssembleClaudeCacheBlocksResult {
+    payload: ClaudeStreamJsonUserMessage;
+    markedBlockCount: number;
+}
+/**
+ * Slice κ: build the Claude `--input-format stream-json` payload from
+ * a `PromptParts`. Each non-empty part becomes one content block in
+ * `system → tools → context → task` order; parts whose name is `true`
+ * in `cacheControl` get `cache_control: {type:"ephemeral", ttl:"1h"}`.
+ *
+ * Empty parts are skipped (no zero-byte blocks) — a true flag on an
+ * empty part is silently a no-op and not counted in `markedBlockCount`.
+ * The `task` block is never marked, even if a caller accidentally
+ * tries (the schema doesn't expose `task` in `cacheControl`).
+ */
+export declare function assembleClaudeCacheBlocks(parts: PromptParts): AssembleClaudeCacheBlocksResult;

package/dist/prompt-parts.js

@@ -1,10 +1,18 @@
 import { createHash } from "crypto";
 import { z } from "zod";
+const CacheControlSchema = z
+    .object({
+    system: z.boolean().optional(),
+    tools: z.boolean().optional(),
+    context: z.boolean().optional(),
+})
+    .strict();
 export const PromptPartsSchema = z.object({
     system: z.string().optional(),
     tools: z.string().optional(),
     context: z.string().optional(),
     task: z.string().min(1),
+    cacheControl: CacheControlSchema.optional(),
 });
 const SEPARATOR = "\n\n";
 export function assemble(parts) {
@@ -40,3 +48,42 @@ export function resolvePromptInput(input) {
         stablePrefixTokens: null,
     };
 }
+/**
+ * Slice κ: build the Claude `--input-format stream-json` payload from
+ * a `PromptParts`. Each non-empty part becomes one content block in
+ * `system → tools → context → task` order; parts whose name is `true`
+ * in `cacheControl` get `cache_control: {type:"ephemeral", ttl:"1h"}`.
+ *
+ * Empty parts are skipped (no zero-byte blocks) — a true flag on an
+ * empty part is silently a no-op and not counted in `markedBlockCount`.
+ * The `task` block is never marked, even if a caller accidentally
+ * tries (the schema doesn't expose `task` in `cacheControl`).
+ */
+export function assembleClaudeCacheBlocks(parts) {
+    const blocks = [];
+    let markedBlockCount = 0;
+    const cc = parts.cacheControl ?? {};
+    const stableEntries = [
+        ["system", parts.system],
+        ["tools", parts.tools],
+        ["context", parts.context],
+    ];
+    for (const [name, value] of stableEntries) {
+        if (value === undefined || value.length === 0)
+            continue;
+        const block = { type: "text", text: value };
+        if (cc[name]) {
+            block.cache_control = { type: "ephemeral", ttl: "1h" };
+            markedBlockCount += 1;
+        }
+        blocks.push(block);
+    }
+    blocks.push({ type: "text", text: parts.task });
+    return {
+        payload: {
+            type: "user",
+            message: { role: "user", content: blocks },
+        },
+        markedBlockCount,
+    };
+}

package/dist/upstream-contracts.d.ts

@@ -1,5 +1,12 @@
 import type { CliType } from "./session-manager.js";
-export type CliFlagArity = "none" | "one" | "variadic";
+/**
+ * `optional` (slice κ): consumes the next token as the flag's value
+ * ONLY if that token does not start with `-`. Used for Claude's
+ * `-p`/`--print`, which is a no-arg switch in claude-code 2.x but
+ * also doubles as the legacy `-p <prompt>` positional shorthand that
+ * the gateway has emitted since v0.x.
+ */
+export type CliFlagArity = "none" | "one" | "optional" | "variadic";
 export interface CliFlagContract {
     arity: CliFlagArity;
     values?: readonly string[];

package/dist/upstream-contracts.js

@@ -46,8 +46,16 @@ export const UPSTREAM_CLI_CONTRACTS = {
             "strictMcpConfig",
         ],
         flags: {
-            "-p": { arity: "one", description: "Prompt text" },
+            "-p": {
+                arity: "optional",
+                description: "Print/non-interactive mode. Legacy gateway emission used `-p <prompt>` (consumed as positional in claude's grammar); slice κ emits `-p` standalone followed by `--input-format stream-json` so the prompt flows in on stdin.",
+            },
             "--model": { arity: "one", description: "Model selector" },
+            "--input-format": {
+                arity: "one",
+                values: ["text", "stream-json"],
+                description: "Slice κ: realtime JSON stdin payload. `stream-json` enables Anthropic cache_control breakpoints from caller-supplied content blocks.",
+            },
             "--output-format": {
                 arity: "one",
                 values: ["json", "stream-json"],
@@ -163,6 +171,26 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 ],
                 expect: "pass",
             },
+            {
+                // Slice κ: when caller marks promptParts with cache_control, the
+                // gateway emits `-p` as a standalone flag and pipes the JSON
+                // content-blocks payload over stdin via `--input-format
+                // stream-json`. The fixture pins the exact argv combination so
+                // a future regression (re-emitting a positional prompt, dropping
+                // `--input-format`, etc.) trips loudly here.
+                id: "claude-input-format-stream-json",
+                description: "Slice κ: `-p` standalone + --input-format stream-json + --output-format stream-json + --include-partial-messages + --verbose",
+                args: [
+                    "-p",
+                    "--input-format",
+                    "stream-json",
+                    "--output-format",
+                    "stream-json",
+                    "--include-partial-messages",
+                    "--verbose",
+                ],
+                expect: "pass",
+            },
         ],
     },
     codex: {
@@ -764,6 +792,14 @@ export function validateUpstreamCliArgs(cli, args) {
             i += 1;
             continue;
         }
+        if (flag.arity === "optional") {
+            const value = args[i + 1];
+            if (value !== undefined && !value.startsWith("-")) {
+                validateFlagValue(cli, arg, flag, value, i + 1, violations);
+                i += 1;
+            }
+            continue;
+        }
         let consumed = 0;
         while (i + 1 < args.length && !args[i + 1].startsWith("-")) {
             validateFlagValue(cli, arg, flag, args[i + 1], i + 1, violations);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-cli-gateway",
-  "version": "1.13.2",
+  "version": "1.14.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",
@@ -70,6 +70,7 @@
     "test:integration": "INTEGRATION_TESTS=1 vitest run src/__tests__/integration.test.ts",
     "test:pg": "bash ./scripts/test-pg.sh",
     "test:all": "npm run test && npm run test:pg",
+    "smoke:cache-control": "node docs/plans/slice-kappa-smoke-test.mjs",
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix",
     "format": "prettier --write 'src/**/*.ts'",