document and test background responses compatibility

Author: ndycode

README.md

@@ -199,6 +199,7 @@ Selected runtime/environment overrides:
 | `CODEX_TUI_V2=0/1` | Disable/enable TUI v2 |
 | `CODEX_TUI_COLOR_PROFILE=truecolor|ansi256|ansi16` | TUI color profile |
 | `CODEX_TUI_GLYPHS=ascii|unicode|auto` | TUI glyph style |
+| `CODEX_AUTH_BACKGROUND_RESPONSES=0/1` | Opt in/out of stateful Responses `background: true` compatibility |
 | `CODEX_AUTH_FETCH_TIMEOUT_MS=<ms>` | Request timeout override |
 | `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=<ms>` | Stream stall timeout override |
 
@@ -210,6 +211,8 @@ codex auth check
 codex auth forecast --live
 ```
 
+Responses background mode stays opt-in. Enable `backgroundResponses` in settings or `CODEX_AUTH_BACKGROUND_RESPONSES=1` only for callers that intentionally send `background: true`, because those requests switch from stateless `store=false` routing to stateful `store=true`. See [docs/upgrade.md](docs/upgrade.md) for rollout guidance.
+
 ---
 
 ## Experimental Settings Highlights

docs/development/CONFIG_FIELDS.md

@@ -83,6 +83,11 @@ Used only for host plugin mode through the host runtime config file.
 
 `backgroundResponses` is an opt-in compatibility switch for Responses API `background: true` requests. When enabled, those requests become stateful (`store=true`) instead of following the default stateless Codex routing.
 
+Upgrade note:
+- Leave this disabled for existing stateless pipelines that do not intentionally send `background: true`.
+- Enable it only for callers that need stateful background responses and can accept forced `store=true`, preserved input item IDs, and the loss of stateless-only defaults such as fast-session trimming.
+- After enabling it, test one known `background: true` request end to end before rolling it across shared automation.
+
 ### Storage / Sync
 
 | Key | Default |

docs/reference/public-api.md

@@ -67,11 +67,10 @@ Positional signatures are preserved for backward compatibility.
 
 The request-transform layer intentionally preserves and/or normalizes modern Responses API fields that callers may already send through the host SDK.
 
-- `previous_response_id` is preserved when explicitly provided and may be auto-filled from plugin continuation state when `pluginConfig.responseContinuation` is enabled.
+- The plugin preserves `previous_response_id` when explicitly provided and may auto-fill it from plugin continuation state when `pluginConfig.responseContinuation` is enabled, maintains `text.format` when verbosity defaults are applied, and honors `prompt_cache_retention` from the request body before falling back to `providerOptions.openai.promptCacheRetention` or user config defaults.
 - `background` is typed as a first-class request field. It remains disabled by default and only passes through when `pluginConfig.backgroundResponses` or `CODEX_AUTH_BACKGROUND_RESPONSES=1` explicitly enables the stateful compatibility path.
-- `text.format` is preserved when verbosity defaults are applied, so structured-output contracts continue to flow through untouched.
-- `prompt_cache_retention` is preserved from the request body and can fall back to `providerOptions.openai.promptCacheRetention` or user config defaults.
 - Background-mode requests force `store=true`, keep caller-supplied input item IDs, and skip stateless-only defaults such as `reasoning.encrypted_content` injection and fast-session trimming.
+- Upgrade note: leave background mode disabled for existing stateless pipelines. Enable it only for callers that intentionally send `background: true` and are ready for stateful `store=true` routing. For rollout steps, see [../upgrade.md](../upgrade.md).
 - Hosted built-in tool definitions are typed and supported for:
   - `tool_search`
   - remote `mcp`

docs/upgrade.md

@@ -76,6 +76,16 @@ For maintainer/debug flows, see advanced/internal controls in [development/CONFI
 
 ---
 
+## Responses Background Mode Upgrade Note
+
+`backgroundResponses` and `CODEX_AUTH_BACKGROUND_RESPONSES=1` are opt-in compatibility controls for callers that intentionally send Responses API `background: true`.
+
+- Leave them disabled for existing stateless pipelines. The default routing remains `store=false`.
+- Enabling them switches background requests onto the stateful path, forces `store=true`, preserves caller-supplied input item IDs, and skips stateless-only defaults such as fast-session trimming and `reasoning.encrypted_content` injection.
+- No new npm scripts or storage migrations are required, but you should validate one known `background: true` request end to end before enabling the flag across shared automation.
+
+---
+
 ## Onboarding Restore Note
 
 `codex auth login` now opens directly into the sign-in menu when the active pool is empty, instead of opening the account dashboard first.

test/fetch-helpers.test.ts

@@ -1179,6 +1179,30 @@ describe('createEntitlementErrorResponse', () => {
 				expect(result?.deferredFastSessionInputTrim).toBeUndefined();
 			});
 
+			it('rethrows store=false background guardrail errors at the fetch layer', async () => {
+				const { transformRequestForCodex } = await import('../lib/request/fetch-helpers.js');
+
+				await expect(
+					transformRequestForCodex(
+						{
+							body: JSON.stringify({
+								model: 'gpt-5.4',
+								background: true,
+								store: false,
+								input: [{ type: 'message', role: 'user', content: 'hello' }],
+							}),
+						},
+						'https://example.com',
+						{ global: {}, models: {} },
+						true,
+						undefined,
+						{ allowBackgroundResponses: true },
+					),
+				).rejects.toThrow(
+					'Responses background mode requires store=true and cannot be combined with stateless store=false routing.',
+				);
+			});
+
 			it('returns undefined when parsedBody is empty object and init body is unavailable', async () => {
 				const { transformRequestForCodex } = await import('../lib/request/fetch-helpers.js');
 				const result = await transformRequestForCodex(

test/plugin-config.test.ts

@@ -66,6 +66,7 @@ describe('Plugin Configuration', () => {
 		'CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL',
 		'CODEX_AUTH_FALLBACK_GPT53_TO_GPT52',
 		'CODEX_AUTH_RESPONSE_CONTINUATION',
+		'CODEX_AUTH_BACKGROUND_RESPONSES',
 		'CODEX_AUTH_PREEMPTIVE_QUOTA_ENABLED',
 		'CODEX_AUTH_PREEMPTIVE_QUOTA_5H_REMAINING_PCT',
 		'CODEX_AUTH_PREEMPTIVE_QUOTA_7D_REMAINING_PCT',

test/request-transformer.test.ts

@@ -2537,6 +2537,29 @@ describe('Request Transformer Module', () => {
 					);
 				});
 
+				it('rejects background mode when providerOptions still forces store=false', async () => {
+					await expect(
+						transformRequestBody(
+							{
+								model: 'gpt-5.4',
+								background: true,
+								providerOptions: { openai: { store: false } },
+								input: [{ type: 'message', role: 'user', content: 'hello' }],
+							},
+							codexInstructions,
+							{ global: {}, models: {} },
+							true,
+							false,
+							'hybrid',
+							30,
+							false,
+							true,
+						),
+					).rejects.toThrowError(
+						'Responses background mode requires store=true and cannot be combined with stateless store=false routing.',
+					);
+				});
+
 				it('throws clear TypeError when named-parameter body is invalid', async () => {
 					await expect(
 						transformRequestBody({