From 9e7c957a3db4229b12e3b85bee6ed110a1c930f9 Mon Sep 17 00:00:00 2001
From: Alex Clarke <alex.j.tusa@gmail.com>
Date: Wed, 16 Sep 2026 13:21:10 -0600
Subject: [PATCH] docs(TASK-044): document wire_api selection, defaults, and
 wire-aware patch migration

---
 CHANGELOG.md                | 21 +++++++++++++++++++++
 assets/config-template.yaml | 24 ++++++++++++++++++++++++
 2 files changed, 45 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ad3bd9b..a24f88d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,24 @@
+## Unreleased
+
+### BREAKING CHANGE
+
+- The stock `openai` client (no custom `api_base`) now defaults to the OpenAI Responses API
+(`/v1/responses`) instead of Chat Completions. Pin the old wire by adding `wire_api: chat` to the
+client block. Openai clients with a custom `api_base` and `openai-compatible` clients still
+default to `chat`; Codex OAuth always uses `responses` (`wire_api: chat` there is a config error).
+- Request patches are now wire-aware and chat-keyed patches never apply to the responses wire: if
+your stock openai client relied on `patch.chat_completions` blocks (or top-level model patches),
+migrate them to the sibling `patch.responses` key / the model patch's `responses:` sub-key
+(env override: `COYOTE_PATCH_<client>_RESPONSES`).
+- Sessions saved after this change may contain the new `reasoning` thinking blocks (encrypted
+reasoning items from the Responses API); older coyote binaries cannot load those sessions.
+
+### Feat
+
+- support `wire_api: responses | chat` on the openai and openai-compatible clients, with wire-aware request patching on both patch layers
+- report token usage (including cached input tokens) on the openai responses path
+- opting a third-party endpoint into `wire_api: responses` sends `include: ["reasoning.encrypted_content"]` and `"strict": false` tool definitions — strict `/v1/responses` servers may reject these as unknown params
+
 ## v0.10.3 (2026-09-15)
 
 ### Feat
diff --git a/assets/config-template.yaml b/assets/config-template.yaml
index 4ac410d..0e6ae22 100644
--- a/assets/config-template.yaml
+++ b/assets/config-template.yaml
@@ -290,4 +290,28 @@ sync_models_ttl_hours: 24        # Hours before the synced model catalog is cons
 #
 # The claude, bedrock, and vertexai clients also support:
 #   prompt_cache: true                              # Enable Anthropic prompt caching (default: true)
+#
+# The openai and openai-compatible clients also support:
+#   wire_api: responses                             # Which OpenAI wire protocol to use; Possible values: responses and chat
+#                                                   # Defaults when unset: stock openai (no api_base) -> responses;
+#                                                   # openai with a custom api_base -> chat; openai-compatible -> chat.
+#                                                   # Codex OAuth always uses responses (`wire_api: chat` there is a config error)
+#
+# Patches are selected per wire: `chat_completions` patches only ever touch chat bodies. To patch
+# requests on the responses wire, use the `responses` key on the client `patch` block (same
+# <regex> -> url/body/headers shape as chat_completions):
+#   patch:
+#     responses:
+#       <regex>:
+#         body:
+#           <json>
+# Model patches likewise: the top-level `patch` keys apply to the chat wire only, and a
+# `responses:` sub-key applies to the responses wire only:
+#   models:
+#     - name: xxxx
+#       patch:
+#         responses:
+#           body:
+#             <json>
+# Env override per wire: COYOTE_PATCH_<client>_RESPONSES / COYOTE_PATCH_<client>_CHAT_COMPLETIONS
 __CLIENTS_BLOCK__