dsh-oauth-login 0.2.8 → 0.2.9

package/INSTALL.md

@@ -7,7 +7,7 @@
 Open **Settings → Plugins → Add plugin** and enter this in “Package name or address”:
 
 ```text
-github:aa2246740/dsh-oauth-login#v0.2.7
+dsh-oauth-login@0.2.9
 ```
 
 The in-app plugin manager owns the Desktop profile and bundled package manager. This release includes built `lib/`; normal use needs no clone, build, or DSHX installation. Follow the app if it asks you to reload or reopen.
@@ -17,20 +17,21 @@ The in-app plugin manager owns the Desktop profile and bundled package manager.
 Stock DeepSeek Harness **0.2.0-rc.2** users install to the Web profile with the official CLI:
 
 ```sh
-dsh plugin --profile web add github:aa2246740/dsh-oauth-login#v0.2.7
+dsh plugin --profile web add dsh-oauth-login@0.2.9
 ```
 
 If `dsh` is not on PATH:
 
 ```sh
-npx @deepseek-ai/dsh plugin --profile web add github:aa2246740/dsh-oauth-login#v0.2.7
+npx @deepseek-ai/dsh plugin --profile web add dsh-oauth-login@0.2.9
 ```
 
-That `github:` spec works because the package declares `dsh.bundle.patch` and
-commits built `lib/`. Official add runs pnpm in `$DSH_HOME/profiles/web` and
+The package declares `dsh.bundle.patch` and includes built `lib/`.
+Official add runs pnpm in `$DSH_HOME/profiles/web` and
 appends the package to `dsh.profile.bundles`. This command writes only `web`,
-not the Desktop App profile. Reopen an already-running Web Host once and reload
-the page. You do not need Creator Mode or a second toolchain.
+not the Desktop App profile. Follow the installer's activation result; reopen
+the original launcher only when it reports that a restart is required.
+You do not need Creator Mode or a second toolchain.
 
 Use `file:` only when editing a local clone. Keep the prefix. A bare
 `./dsh-oauth-login` becomes a symlink, while this plugin intentionally resolves
@@ -54,7 +55,7 @@ dsh plugin --profile web exec dsh-oauth-login logout openai-codex
 For Zhipu GLM Coding Plan, the command opens the official Plan page and asks
 for its API key locally. The plugin never reads your browser session.
 
-After upgrading the server plugin and restarting DSH once, open Settings →
+After upgrading and following the installer's activation result, open Settings →
 Subscription Login → Network proxy. Configure HTTP and WebSocket independently.
 The address defaults to `http://127.0.0.1`, with the port left empty. An enabled
 channel with an explicit address and port overrides automatic discovery; an

package/INSTALL.zh.md

@@ -7,7 +7,7 @@
 打开 **设置 → 插件 → 添加插件**，在“包名或地址”中输入：
 
 ```text
-github:aa2246740/dsh-oauth-login#v0.2.7
+dsh-oauth-login@0.2.9
 ```
 
 应用内插件管理器负责 Desktop profile 和内置包管理器。本发布已包含编译好的 `lib/`；普通使用不需要 clone、构建或安装 DSHX。若应用提示刷新或重新打开，请按提示完成。
@@ -17,16 +17,16 @@ github:aa2246740/dsh-oauth-login#v0.2.7
 官方 DeepSeek Harness **0.2.0-rc.2** 用户用官方 CLI 安装到 Web profile：
 
 ```sh
-dsh plugin --profile web add github:aa2246740/dsh-oauth-login#v0.2.7
+dsh plugin --profile web add dsh-oauth-login@0.2.9
 ```
 
 没有 `dsh` 时：
 
 ```sh
-npx @deepseek-ai/dsh plugin --profile web add github:aa2246740/dsh-oauth-login#v0.2.7
+npx @deepseek-ai/dsh plugin --profile web add dsh-oauth-login@0.2.9
 ```
 
-这条 `github:` 命令能装上，是因为包装了 `dsh.bundle.patch`，并且仓库提交了编好的 `lib/`。官方 add 在 `$DSH_HOME/profiles/web` 里跑 pnpm，再把这个包装进 `dsh.profile.bundles`。这条命令只写 `web` profile，不能修改 Desktop App 的 profile；已运行的 Web Host 需要重新打开一次，再刷新网页。不需要 Creator Mode，也不需要另装一套工具。
+包中声明了 `dsh.bundle.patch`，并包含编好的 `lib/`。官方 add 在 `$DSH_HOME/profiles/web` 里跑 pnpm，再把这个包装进 `dsh.profile.bundles`。这条命令只写 `web` profile，不能修改 Desktop App 的 profile；按安装器的生效结果继续，只有提示需要重启时才用原启动方式重新打开。不需要 Creator Mode，也不需要另装一套工具。
 
 本机改源码时再用 `file:`，并且必须保留前缀。直接写 `./dsh-oauth-login` 会变成符号链接；本插件有意从 profile 复用 DSH 运行时的 peer dependency，因此必须使用 `file:` 副本，才能正确解析依赖。
 
@@ -47,7 +47,7 @@ dsh plugin --profile web exec dsh-oauth-login logout openai-codex
 智谱 GLM Coding Plan 会打开官方套餐页，再在本机提示你输入 API Key；
 插件不会读取你的浏览器登录状态。
 
-升级服务端插件后先重启一次 DSH，再进入「设置 → 订阅登录 → 网络代理」。HTTP 与 WebSocket 可以独立配置，地址默认填入 `http://127.0.0.1`，端口留空。开启并填写端口时优先使用该代理；默认地址且端口留空时沿用自动发现，不会默认使用 80 端口；关闭时直接连接。请使用 HTTP(S) CONNECT / 混合代理端口，不能填纯 SOCKS 端口。页面保存后用于新请求，不需要再次重启；改变启动时继承的环境变量则需要重启。详见[网络代理与恢复机制](docs/network-proxy.md)。
+升级服务端插件并按安装器提示完成生效后，进入「设置 → 订阅登录 → 网络代理」。HTTP 与 WebSocket 可以独立配置，地址默认填入 `http://127.0.0.1`，端口留空。开启并填写端口时优先使用该代理；默认地址且端口留空时沿用自动发现，不会默认使用 80 端口；关闭时直接连接。请使用 HTTP(S) CONNECT / 混合代理端口，不能填纯 SOCKS 端口。页面保存后用于新请求，不需要再次重启；改变启动时继承的环境变量则需要重启。详见[网络代理与恢复机制](docs/network-proxy.md)。
 
 卸载：
 

package/README.en.md

@@ -9,7 +9,7 @@
 Open **Settings → Plugins → Add plugin** and enter this in “Package name or address”:
 
 ```text
-github:aa2246740/dsh-oauth-login#v0.2.7
+dsh-oauth-login@0.2.9
 ```
 
 The desktop plugin manager owns the Desktop profile and bundled package manager. This release includes built `lib/`; normal use needs no clone, build, or DSHX installation. Follow the app if it asks you to reload or reopen after installation.
@@ -17,10 +17,10 @@ The desktop plugin manager owns the Desktop profile and bundled package manager.
 ### Web CLI
 
 ```sh
-dsh plugin --profile web add github:aa2246740/dsh-oauth-login#v0.2.7
+dsh plugin --profile web add dsh-oauth-login@0.2.9
 ```
 
-This official CLI command writes only the `web` profile; it cannot modify the Desktop App profile. For an already-running Web Host, reopen that Host once and reload the page.
+This official CLI command writes only the `web` profile; it cannot modify the Desktop App profile. Follow the installer's activation result and reopen the original launcher only when a restart is required.
 
 OAuth login for ChatGPT, Claude, Grok, Copilot, OpenRouter, and Kimi on [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), plus Zhipu GLM Coding Plan via its official plan API key. Credentials go only to `$DSH_HOME/.dsh-oauth-auth.json`.
 
@@ -47,7 +47,7 @@ That `github:` command works because this package declares `dsh.bundle.patch` an
 If `dsh` is not on PATH:
 
 ```sh
-npx @deepseek-ai/dsh plugin --profile web add github:aa2246740/dsh-oauth-login#v0.2.7
+npx @deepseek-ai/dsh plugin --profile web add dsh-oauth-login@0.2.9
 ```
 
 Use `file:` only when you are editing a local clone (development/local testing; do not drop the prefix):
@@ -97,7 +97,7 @@ On these routes the plugin removes DSH `web_search` / `web_fetch` and attaches t
 | Route | Hosted tools |
 |---|---|
 | `pi-xai` | `web_search`, `x_search`, `image_generation` |
-| `pi-openai-codex` | `web_search`, `image_generation` |
+| `pi-openai-codex` | `web_search` (cached by default) |
 | `pi-anthropic` | `web_search_20250305` |
 
 Copilot, OpenRouter, Kimi, and Zhipu do not get hosted tools. To keep DSH search:
@@ -111,6 +111,8 @@ Copilot, OpenRouter, Kimi, and Zhipu do not get hosted tools. To keep DSH search
 
 `nativeImage: false` keeps search and drops image generation.
 
+Codex uses its own tool declaration. `codexSearch: cached` sends `external_web_access: false`; `live` explicitly enables external access; `off` leaves the DSH client web tools available. Cached results may be stale. Account or backend rejections remain visible, and the plugin never silently changes model or search mode. Codex does not inherit generic Responses image-generation tools. Grok and Anthropic retain their own protocols.
+
 Chat retries use official `dsh-llm-retry`. HTTP 429 is not the same as quota exhaustion. **Settings → 订阅登录 → 网络代理** affects only this plugin.
 
 ## License

package/README.md

@@ -9,7 +9,7 @@
 打开 **设置 → 插件 → 添加插件**，在“包名或地址”中输入：
 
 ```text
-github:aa2246740/dsh-oauth-login#v0.2.7
+dsh-oauth-login@0.2.9
 ```
 
 桌面端插件管理器负责 Desktop profile 和内置包管理器。本发布已包含编译好的 `lib/`；普通使用不需要 clone、构建或安装 DSHX。若应用提示刷新或重新打开，请按提示完成。
@@ -17,10 +17,10 @@ github:aa2246740/dsh-oauth-login#v0.2.7
 ### Web CLI
 
 ```sh
-dsh plugin --profile web add github:aa2246740/dsh-oauth-login#v0.2.7
+dsh plugin --profile web add dsh-oauth-login@0.2.9
 ```
 
-这条官方 CLI 命令只写入 `web` profile，不能修改 Desktop App 的 profile。对于已经运行的 Web Host，请重新打开该 Host 一次，再刷新网页。
+这条官方 CLI 命令只写入 `web` profile，不能修改 Desktop App 的 profile。按安装器的生效结果继续；只有提示需要重启时才用原启动方式重新打开 Host。
 
 把 ChatGPT、Claude、Grok、Copilot、OpenRouter、Kimi 的 OAuth 登录和智谱 GLM Coding Plan 接到 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)。凭据只写 `$DSH_HOME/.dsh-oauth-auth.json`。
 
@@ -47,7 +47,7 @@ dsh plugin --profile web add github:aa2246740/dsh-oauth-login#v0.2.7
 没有 `dsh` 时：
 
 ```sh
-npx @deepseek-ai/dsh plugin --profile web add github:aa2246740/dsh-oauth-login#v0.2.7
+npx @deepseek-ai/dsh plugin --profile web add dsh-oauth-login@0.2.9
 ```
 
 本机改源码时再用 `file:`（开发/本地测试；不要写成裸的 `./`）：
@@ -109,7 +109,9 @@ Copilot、OpenRouter、Kimi、智谱不挂 hosted tool。要继续用 DSH 自己
     nativeTools: false
 ```
 
-`nativeImage: false` 只留搜索，去掉出图。
+`nativeImage: false` 关闭受支持路由的托管出图。
+
+Codex 订阅路由使用独立的工具声明：`codexSearch: cached` 默认发送 `external_web_access: false`；`live` 显式请求实时外部访问，`off` 不注入托管搜索并保留 DSH 的客户端搜索工具。缓存搜索不保证结果实时性；账户和后端仍可能拒绝工具请求，插件不会自动换模型或在失败后静默重试另一种搜索模式。Codex 不再继承通用 Responses 的托管图片生成声明。Grok、Anthropic 保持各自协议。
 
 Chat 失败重试走官方 `dsh-llm-retry`。429 不等于额度耗尽。设置 → 订阅登录 → 网络代理只影响本插件。
 

package/lib/bin.js

@@ -577,10 +577,12 @@ const HOSTED_CLIENT_LEAK_NAMES = [
 new Set(HOSTED_CLIENT_LEAK_NAMES);
 const DEFAULT_NATIVE_TOOL_POLICY = {
 	enabled: true,
-	image: true
+	image: true,
+	codexSearch: "cached"
 };
 const SEARCH_GUIDANCE = "This turn already includes this account's native hosted search. Do not call web_search or web_fetch — those DSH tools are not available on this route.";
 const SEARCH_AND_IMAGE_GUIDANCE = "This turn already includes this account's native hosted search and image generation. Do not call web_search or web_fetch — those DSH tools are not available on this route.";
+const CACHED_SEARCH_GUIDANCE = "This turn includes native cached web search. Cached results may not reflect current pages. Do not call web_search or web_fetch as client functions — those DSH tools are not available on this route.";
 function responsesSearch() {
 	return { type: "web_search" };
 }
@@ -609,12 +611,17 @@ function nativePlan(providerId, api, policy = DEFAULT_NATIVE_TOOL_POLICY) {
 			],
 			guidance: policy.image ? SEARCH_AND_IMAGE_GUIDANCE : SEARCH_GUIDANCE
 		};
-		case "openai-codex:openai-codex-responses": return {
-			providerId,
-			api: "openai-codex-responses",
-			hosted: [responsesSearch(), ...policy.image ? [responsesImage()] : []],
-			guidance: policy.image ? SEARCH_AND_IMAGE_GUIDANCE : SEARCH_GUIDANCE
-		};
+		case "openai-codex:openai-codex-responses":
+			if (policy.codexSearch === "off") return void 0;
+			return {
+				providerId,
+				api: "openai-codex-responses",
+				hosted: [{
+					type: "web_search",
+					external_web_access: policy.codexSearch === "live"
+				}],
+				guidance: policy.codexSearch === "live" ? SEARCH_GUIDANCE : CACHED_SEARCH_GUIDANCE
+			};
 		case "anthropic:anthropic-messages": return {
 			providerId,
 			api: "anthropic-messages",
@@ -644,13 +651,15 @@ function hostedToolKey(tool) {
 function applyNativeToolsToPayload(payload, providerId, api, policy = DEFAULT_NATIVE_TOOL_POLICY) {
 	const plan = nativePlan(providerId, api, policy);
 	if (plan === void 0 || !isRecord(payload) || !Array.isArray(payload.tools)) return payload;
-	const kept = payload.tools.filter((tool) => !isDshWebFunctionTool(tool));
-	const seen = new Set(kept.filter(isRecord).map((tool) => hostedToolKey(tool)));
-	const hosted = plan.hosted.filter((tool) => {
-		const key = hostedToolKey(tool);
-		if (seen.has(key)) return false;
-		seen.add(key);
-		return true;
+	const current = payload.tools;
+	const managed = new Set(plan.hosted.map(hostedToolKey));
+	const kept = current.filter((tool) => !isDshWebFunctionTool(tool) && (!isRecord(tool) || !managed.has(hostedToolKey(tool))) && !(providerId === "openai-codex" && isRecord(tool) && tool.type === "image_generation"));
+	const hosted = plan.hosted.map((tool) => {
+		const previous = current.find((candidate) => isRecord(candidate) && hostedToolKey(candidate) === hostedToolKey(tool));
+		return {
+			...isRecord(previous) ? previous : {},
+			...tool
+		};
 	});
 	return {
 		...payload,
@@ -664,8 +673,8 @@ function wrapOnPayload(existing, providerId, api, policy = DEFAULT_NATIVE_TOOL_P
 			...payload,
 			tools: []
 		} : payload, providerId, api, policy);
-		if (existing === void 0) return injected;
-		return await existing(injected, model);
+		const customized = existing === void 0 ? void 0 : await existing(injected, model);
+		return applyNativeToolsToPayload(customized === void 0 ? injected : customized, providerId, api, policy);
 	};
 }
 function filterPiContext(context, providerId, api, policy = DEFAULT_NATIVE_TOOL_POLICY) {
@@ -1981,7 +1990,12 @@ z.object({
 	streamIdleTimeoutMs: z.number().min(1).default(PI_LOGIN_STREAM_IDLE_TIMEOUT_MS),
 	retryPolicy: RetryPolicySchema,
 	nativeTools: z.boolean().default(true),
-	nativeImage: z.boolean().default(true)
+	nativeImage: z.boolean().default(true),
+	codexSearch: z.union([
+		"cached",
+		"live",
+		"off"
+	]).default("cached")
 });
 //#endregion
 //#region src/bin.ts

package/lib/index.d.ts

@@ -20,8 +20,10 @@ interface Config {
    * search, and attach those hosted tools to the provider request.
    */
   nativeTools?: boolean;
-  /** Also attach hosted image generation on Grok and Codex. */
+  /** Also attach hosted image generation on transports that support it (Grok). */
   nativeImage?: boolean;
+  /** Codex defaults to cached search; live external access is explicit. */
+  codexSearch?: 'cached' | 'live' | 'off';
 }
 declare const Config: z<Config>;
 //#endregion
@@ -117,6 +119,8 @@ interface NativeToolPolicy {
   enabled: boolean;
   /** Also attach hosted image generation where the provider documents it. Default true. */
   image: boolean;
+  /** Codex search distinguishes cached content from live external access. */
+  codexSearch?: 'cached' | 'live' | 'off';
 }
 declare const DEFAULT_NATIVE_TOOL_POLICY: NativeToolPolicy;
 interface NativeToolPlan {

package/lib/index.js

@@ -796,10 +796,12 @@ const HOSTED_CLIENT_LEAK_NAMES = [
 const HOSTED_CLIENT_LEAK_NAME_SET = new Set(HOSTED_CLIENT_LEAK_NAMES);
 const DEFAULT_NATIVE_TOOL_POLICY = {
 	enabled: true,
-	image: true
+	image: true,
+	codexSearch: "cached"
 };
 const SEARCH_GUIDANCE = "This turn already includes this account's native hosted search. Do not call web_search or web_fetch — those DSH tools are not available on this route.";
 const SEARCH_AND_IMAGE_GUIDANCE = "This turn already includes this account's native hosted search and image generation. Do not call web_search or web_fetch — those DSH tools are not available on this route.";
+const CACHED_SEARCH_GUIDANCE = "This turn includes native cached web search. Cached results may not reflect current pages. Do not call web_search or web_fetch as client functions — those DSH tools are not available on this route.";
 function responsesSearch() {
 	return { type: "web_search" };
 }
@@ -828,12 +830,17 @@ function nativePlan(providerId, api, policy = DEFAULT_NATIVE_TOOL_POLICY) {
 			],
 			guidance: policy.image ? SEARCH_AND_IMAGE_GUIDANCE : SEARCH_GUIDANCE
 		};
-		case "openai-codex:openai-codex-responses": return {
-			providerId,
-			api: "openai-codex-responses",
-			hosted: [responsesSearch(), ...policy.image ? [responsesImage()] : []],
-			guidance: policy.image ? SEARCH_AND_IMAGE_GUIDANCE : SEARCH_GUIDANCE
-		};
+		case "openai-codex:openai-codex-responses":
+			if (policy.codexSearch === "off") return void 0;
+			return {
+				providerId,
+				api: "openai-codex-responses",
+				hosted: [{
+					type: "web_search",
+					external_web_access: policy.codexSearch === "live"
+				}],
+				guidance: policy.codexSearch === "live" ? SEARCH_GUIDANCE : CACHED_SEARCH_GUIDANCE
+			};
 		case "anthropic:anthropic-messages": return {
 			providerId,
 			api: "anthropic-messages",
@@ -1020,13 +1027,15 @@ function hostedToolKey(tool) {
 function applyNativeToolsToPayload(payload, providerId, api, policy = DEFAULT_NATIVE_TOOL_POLICY) {
 	const plan = nativePlan(providerId, api, policy);
 	if (plan === void 0 || !isRecord(payload) || !Array.isArray(payload.tools)) return payload;
-	const kept = payload.tools.filter((tool) => !isDshWebFunctionTool(tool));
-	const seen = new Set(kept.filter(isRecord).map((tool) => hostedToolKey(tool)));
-	const hosted = plan.hosted.filter((tool) => {
-		const key = hostedToolKey(tool);
-		if (seen.has(key)) return false;
-		seen.add(key);
-		return true;
+	const current = payload.tools;
+	const managed = new Set(plan.hosted.map(hostedToolKey));
+	const kept = current.filter((tool) => !isDshWebFunctionTool(tool) && (!isRecord(tool) || !managed.has(hostedToolKey(tool))) && !(providerId === "openai-codex" && isRecord(tool) && tool.type === "image_generation"));
+	const hosted = plan.hosted.map((tool) => {
+		const previous = current.find((candidate) => isRecord(candidate) && hostedToolKey(candidate) === hostedToolKey(tool));
+		return {
+			...isRecord(previous) ? previous : {},
+			...tool
+		};
 	});
 	return {
 		...payload,
@@ -1040,8 +1049,8 @@ function wrapOnPayload(existing, providerId, api, policy = DEFAULT_NATIVE_TOOL_P
 			...payload,
 			tools: []
 		} : payload, providerId, api, policy);
-		if (existing === void 0) return injected;
-		return await existing(injected, model);
+		const customized = existing === void 0 ? void 0 : await existing(injected, model);
+		return applyNativeToolsToPayload(customized === void 0 ? injected : customized, providerId, api, policy);
 	};
 }
 function filterPiContext(context, providerId, api, policy = DEFAULT_NATIVE_TOOL_POLICY) {
@@ -3050,7 +3059,12 @@ const Config = z.object({
 	streamIdleTimeoutMs: z.number().min(1).default(PI_LOGIN_STREAM_IDLE_TIMEOUT_MS),
 	retryPolicy: RetryPolicySchema,
 	nativeTools: z.boolean().default(true),
-	nativeImage: z.boolean().default(true)
+	nativeImage: z.boolean().default(true),
+	codexSearch: z.union([
+		"cached",
+		"live",
+		"off"
+	]).default("cached")
 });
 //#endregion
 //#region src/index.ts
@@ -3067,6 +3081,7 @@ function apply(ctx, config) {
 	console.log("[my-plugins/dsh-oauth-login] loaded");
 	const native = {
 		enabled: config.nativeTools !== false,
+		codexSearch: config.codexSearch ?? "cached",
 		image: config.nativeImage !== false
 	};
 	const session = new PiLoginSession(new PiLoginCredentialStore(), native);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-oauth-login",
   "description": "DSH-owned subscription login powered by Pi AI adapters: OAuth plus official Plan API keys, with an independent credential store.",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/src/index.ts

@@ -131,6 +131,7 @@ export function apply(ctx: Context, config: Config): void {
   console.log('[my-plugins/dsh-oauth-login] loaded')
   const native = {
     enabled: config.nativeTools !== false,
+    codexSearch: config.codexSearch ?? 'cached',
     image: config.nativeImage !== false,
   }
   const session = new PiLoginSession(new PiLoginCredentialStore(), native)

package/src/native-tools.ts

@@ -48,11 +48,14 @@ export interface NativeToolPolicy {
   enabled: boolean
   /** Also attach hosted image generation where the provider documents it. Default true. */
   image: boolean
+  /** Codex search distinguishes cached content from live external access. */
+  codexSearch?: 'cached' | 'live' | 'off'
 }
 
 export const DEFAULT_NATIVE_TOOL_POLICY: NativeToolPolicy = {
   enabled: true,
   image: true,
+  codexSearch: 'cached',
 }
 
 export interface NativeToolPlan {
@@ -68,6 +71,9 @@ const SEARCH_GUIDANCE =
 const SEARCH_AND_IMAGE_GUIDANCE =
   'This turn already includes this account\'s native hosted search and image generation. Do not call web_search or web_fetch — those DSH tools are not available on this route.'
 
+const CACHED_SEARCH_GUIDANCE =
+  'This turn includes native cached web search. Cached results may not reflect current pages. Do not call web_search or web_fetch as client functions — those DSH tools are not available on this route.'
+
 function responsesSearch(): Record<string, unknown> {
   return { type: 'web_search' }
 }
@@ -103,14 +109,15 @@ export function nativePlan(
         guidance: policy.image ? SEARCH_AND_IMAGE_GUIDANCE : SEARCH_GUIDANCE,
       }
     case 'openai-codex:openai-codex-responses':
+      if (policy.codexSearch === 'off') return undefined
       return {
         providerId,
         api: 'openai-codex-responses',
-        hosted: [
-          responsesSearch(),
-          ...policy.image ? [responsesImage()] : [],
-        ],
-        guidance: policy.image ? SEARCH_AND_IMAGE_GUIDANCE : SEARCH_GUIDANCE,
+        // Codex is a distinct transport. Its official tool specification makes
+        // external access explicit; the generic Responses default is not a
+        // substitute. Hosted image generation is not part of this contract.
+        hosted: [{ type: 'web_search', external_web_access: policy.codexSearch === 'live' }],
+        guidance: policy.codexSearch === 'live' ? SEARCH_GUIDANCE : CACHED_SEARCH_GUIDANCE,
       }
     case 'anthropic:anthropic-messages':
       return {
@@ -352,15 +359,14 @@ export function applyNativeToolsToPayload(
   const plan = nativePlan(providerId, api, policy)
   if (plan === undefined || !isRecord(payload) || !Array.isArray(payload.tools)) return payload
   const current = payload.tools
-  const kept = current.filter(tool => !isDshWebFunctionTool(tool))
-  const seen = new Set(
-    kept.filter(isRecord).map(tool => hostedToolKey(tool)),
-  )
-  const hosted = plan.hosted.filter(tool => {
-    const key = hostedToolKey(tool)
-    if (seen.has(key)) return false
-    seen.add(key)
-    return true
+  const managed = new Set(plan.hosted.map(hostedToolKey))
+  const kept = current.filter(tool => !isDshWebFunctionTool(tool)
+    && (!isRecord(tool) || !managed.has(hostedToolKey(tool)))
+    && !(providerId === 'openai-codex' && isRecord(tool) && tool.type === 'image_generation'))
+  const hosted = plan.hosted.map(tool => {
+    const previous = current.find(candidate => isRecord(candidate) && hostedToolKey(candidate) === hostedToolKey(tool))
+    // Preserve caller filters, but explicit transport capability fields win.
+    return { ...(isRecord(previous) ? previous : {}), ...tool }
   })
   return { ...payload, tools: [...hosted, ...kept] }
 }
@@ -381,8 +387,10 @@ export function wrapOnPayload(
       ? { ...payload, tools: [] }
       : payload
     const injected = applyNativeToolsToPayload(requestPayload, providerId, api, policy)
-    if (existing === undefined) return injected
-    return await existing(injected, model)
+    // Preserve the existing callback's observation contract, then revalidate
+    // the actual returned payload so it cannot restore an unsupported tool.
+    const customized = existing === undefined ? undefined : await existing(injected, model)
+    return applyNativeToolsToPayload(customized === undefined ? injected : customized, providerId, api, policy)
   }
 }
 

package/src/plugin-config.ts

@@ -18,8 +18,10 @@ export interface Config {
    * search, and attach those hosted tools to the provider request.
    */
   nativeTools?: boolean
-  /** Also attach hosted image generation on Grok and Codex. */
+  /** Also attach hosted image generation on transports that support it (Grok). */
   nativeImage?: boolean
+  /** Codex defaults to cached search; live external access is explicit. */
+  codexSearch?: 'cached' | 'live' | 'off'
 }
 
 export const Config: z<Config> = z.object({
@@ -27,4 +29,5 @@ export const Config: z<Config> = z.object({
   retryPolicy: RetryPolicySchema,
   nativeTools: z.boolean().default(true),
   nativeImage: z.boolean().default(true),
+  codexSearch: z.union(['cached', 'live', 'off']).default('cached'),
 })