From 60106b608df55f069bc46861075ea06aea7a51d0 Mon Sep 17 00:00:00 2001
From: ndycode <405533+ndycode@users.noreply.github.com>
Date: Sun, 22 Mar 2026 17:41:06 +0800
Subject: [PATCH 1/2] Document responses contract additions

---
 docs/development/CONFIG_FIELDS.md |  2 ++
 docs/reference/public-api.md      | 24 ++++++++++++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/docs/development/CONFIG_FIELDS.md b/docs/development/CONFIG_FIELDS.md
index 9a3ee4cf..f345e793 100644
--- a/docs/development/CONFIG_FIELDS.md
+++ b/docs/development/CONFIG_FIELDS.md
@@ -31,6 +31,7 @@ Used only for host plugin mode through the host runtime config file.
 | `reasoningEffort` | string | `none\|minimal\|low\|medium\|high\|xhigh` | Reasoning effort hint |
 | `reasoningSummary` | string | `auto\|concise\|detailed` | Summary detail hint |
 | `textVerbosity` | string | `low\|medium\|high` | Text verbosity target |
+| `promptCacheRetention` | string | `5m\|1h\|24h\|7d` | Default server-side prompt cache retention when the request body omits `prompt_cache_retention` |
 | `include` | string[] | `reasoning.encrypted_content` | Extra payload include |
 | `store` | boolean | `false` | Required for stateless backend mode |
 
@@ -74,6 +75,7 @@ Used only for host plugin mode through the host runtime config file.
 | `tokenRefreshSkewMs` | `60000` |
 | `sessionRecovery` | `true` |
 | `autoResume` | `true` |
+| `responseContinuation` | `false` |
 | `proactiveRefreshGuardian` | `true` |
 | `proactiveRefreshIntervalMs` | `60000` |
 | `proactiveRefreshBufferMs` | `300000` |
diff --git a/docs/reference/public-api.md b/docs/reference/public-api.md
index 865189ff..43ca69f4 100644
--- a/docs/reference/public-api.md
+++ b/docs/reference/public-api.md
@@ -63,6 +63,30 @@ Positional signatures are preserved for backward compatibility.
 
 ---
 
+## Responses Contract Notes
+
+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.
+- `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.
+- Hosted built-in tool definitions are typed and supported for:
+  - `tool_search`
+  - remote `mcp`
+  - `computer` / `computer_use_preview`
+  - `namespace` bundles containing nested tools
+- Unsupported hosted search/computer tools are filtered before the upstream request when the selected model profile does not advertise that capability.
+- Semantic SSE parsing synthesizes compatibility fields such as:
+  - `output_text`
+  - `reasoning_summary_text`
+  - `commentary_text`
+  - `final_answer_text`
+  - `phase_text`
+
+These behaviors are compatibility guarantees for the current release line because they protect caller intent while keeping the plugin stateless against the ChatGPT Codex backend.
+
+---
+
 ## Semver Guidance
 
 - Breaking Tier A change: `MAJOR`

From 7cc6bf63d92ad09735dbcb2ca2945c211a5f6c9e Mon Sep 17 00:00:00 2001
From: ndycode <405533+ndycode@users.noreply.github.com>
Date: Sun, 22 Mar 2026 18:56:30 +0800
Subject: [PATCH 2/2] clarify responses contract docs

---
 docs/reference/public-api.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/reference/public-api.md b/docs/reference/public-api.md
index 43ca69f4..a31a12c1 100644
--- a/docs/reference/public-api.md
+++ b/docs/reference/public-api.md
@@ -67,9 +67,7 @@ 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.
-- `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.
+- 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.
 - Hosted built-in tool definitions are typed and supported for:
   - `tool_search`
   - remote `mcp`
@@ -83,6 +81,8 @@ The request-transform layer intentionally preserves and/or normalizes modern Res
   - `final_answer_text`
   - `phase_text`
 
+These SSE compatibility fields are synthesized only when the corresponding content is present in the response stream.
+
 These behaviors are compatibility guarantees for the current release line because they protect caller intent while keeping the plugin stateless against the ChatGPT Codex backend.
 
 ---