pi-openai-toolkit 0.14.6 → 0.14.8

package/README.md

@@ -13,7 +13,7 @@ Add Codex context windows, Responses compaction, hosted tools, and reviewed tool
 | --- | --- |
 | Codex Remote Context | Start a new context window and retrieve earlier windows with `history`. |
 | Remote Compaction v2 | Continue an eligible Responses session with an encrypted server checkpoint. |
-| Hosted Web Search | Give selected models OpenAI's hosted search tool. |
+| Web Search routes | Choose local `pi-web-access`, hosted Responses `web_search`, or CPA standalone `web.run` per exact model route. |
 | Image generation | Generate images or edit explicitly supplied local reference images. |
 | Tool-call review | Ask a reviewer model whether selected tool calls may run. |
 
@@ -31,7 +31,7 @@ pi install npm:pi-openai-toolkit
 
 Use `--local` to install it in the current project.
 
-Installing the package alone does not enable every feature. With no extension config, compaction is enabled but Remote Context is off, the Web Search model list is empty, image generation is disabled, and Auto Mode has no allowed models or reviewer.
+Installing the package alone does not enable every feature. With no extension config, compaction is enabled but Remote Context is off, Web Search has no toolkit-selected route, image generation is disabled, and Auto Mode has no allowed models or reviewer.
 
 The extension config file is:
 
@@ -130,19 +130,44 @@ Earlier windows remain available through `history`, but they are not all automat
 
 Leave Remote Context off when you want the Responses compaction path instead. Remote Compaction v2 stores and replays an encrypted checkpoint for eligible Responses models. Set `compaction.remoteCompactModel` only when the compaction request should use a separate model.
 
-### Enable hosted Web Search
+When `compaction.remoteV2ContextSource` is omitted, Remote V2 keeps the original `"legacy"` input chain: first compaction uses Pi's current session context (or the supplied preparation as a last resort), and recursive compaction uses the raw branch tail. This preserves existing behavior, but can diverge from provider-visible context when other extensions rewrite messages.
 
-List exact model specifications under `webSearch.models`:
+Set `compaction.remoteV2ContextSource` to `"pi-context-hook"` to opt into the Pi 0.85.1 runtime bridge. The toolkit then uses the same ordered `context` hook chain as the live provider request. If Pi cannot expose that public hook path, Remote V2 cancels instead of sending an unprojected history. Checkpoint replay is accepted only when its source marker matches the current setting. Switching between the two modes requires a new Remote V2 checkpoint; disable Remote V2 or use Pi's native compaction when custom-only state must survive inside the opaque checkpoint.
+
+### Choose a Web Search route
+
+Web Search has three mutually exclusive routes. Configure one global default and, when needed, exact `provider/model-id` overrides:
 
 ```json
 {
   "webSearch": {
-    "models": ["my-gateway/gpt-5.6-luna"]
+    "enabled": true,
+    "defaultRoute": "hosted",
+    "routes": {
+      "uwoacrimson/gpt-6-astra": "standalone-alpha",
+      "my-gateway/gpt-5.6-luna": "local"
+    }
   }
 }
 ```
 
-For those models, the extension replaces Pi's local `web_search` tool with OpenAI's hosted Responses search tool.
+Route selection is exact and deterministic: `routes[provider/model-id]` wins over `defaultRoute`; `defaultRoute` wins over the legacy `models` list. There is no wildcard, fuzzy model matching, capability guessing, fallback, or retry between routes. Invalid route values/keys are ignored with warnings rather than guessed, and overlapping new/legacy fields produce migration warnings. `enabled: false` releases toolkit ownership and disables all three toolkit-selected paths.
+
+- **`local`** keeps the already-installed `pi-web-access` `web_search` tool. The toolkit does not activate it when it was not active, and it does not add a hosted provider tool or `web.run`.
+- **`hosted`** removes the local function named `web_search` and injects the native Responses `{ "type": "web_search" }` tool plus source annotations. The legacy configuration remains valid:
+
+  ```json
+  {
+    "webSearch": {
+      "models": ["my-gateway/gpt-5.6-luna"]
+    }
+  }
+  ```
+
+  With no new route fields, only models in this exact list and the existing Responses-family APIs (`openai-responses` or `openai-codex-responses`) use hosted search.
+- **`standalone-alpha`** exposes one sequential `web.run` tool and sends one isolated `POST` request to the provider-relative `/alpha/search` endpoint. A base URL such as `https://gateway.example/v1` therefore receives `https://gateway.example/v1/alpha/search`, not a Responses endpoint. Supported command families are `search_query`, `image_query`, `open`, `click`, `find`, `screenshot`, `finance`, `weather`, `sports`, and `time`; `response_length` controls the requested result size.
+
+The standalone route is an experimental CPA/Codex gateway protocol, not a stable public OpenAI Responses endpoint. The gateway/provider must expose `/alpha/search`, enable its `alpha-search` capability, and support standalone web search (Codex providers commonly expose this as `supports_standalone_web_search = true`). The request reuses Pi's current model, authentication, provider headers, session identity, and Codex/gateway affinity; it does not change the active model. The MVP sends the bounded command envelope rather than the full conversation transcript, relies on provider session/reference handling for `ref_id` follow-ups, makes at most one request per tool call, and fails closed on invalid configuration, unavailable routes, cancellation, timeout, non-2xx, malformed, or oversized responses.
 
 ### Generate an image
 
@@ -186,8 +211,12 @@ The config file is `~/.pi/agent/extensions/pi-openai-toolkit/config.json`. Unkno
 | `compaction.contextManagement` | `"off"` | Enables Codex Remote Context when set to `"remote"`. |
 | `compaction.gatewayContextModels` | `[]` | Gateway models allowed to use Remote Context. |
 | `compaction.remoteCompactModel` | unset | Optional model used only for a v2 compaction request. |
+| `compaction.remoteV2ContextSource` | `"legacy"` | Preserve the original raw session/branch input path. Set `"pi-context-hook"` to opt into Pi's ordered context-hook projection. Checkpoints are mode-specific. |
 | `compaction.contextReminderThresholdPercent` | `5` | Remaining budget percentage for the once-per-window reminder. `0` disables the reminder and exhausted-window fallback. |
-| `webSearch.models` | `[]` | Models that receive hosted Web Search. |
+| `webSearch.enabled` | `true` | Total switch for the toolkit's Web Search route selection. `false` selects no toolkit route. |
+| `webSearch.defaultRoute` | unset | Default route: `local`, `hosted`, or `standalone-alpha`. Unset preserves legacy behavior. |
+| `webSearch.routes` | unset | Exact `provider/model-id` to route overrides. Exact entries take precedence over `defaultRoute`. |
+| `webSearch.models` | `[]` | Legacy exact allowlist; without the new route fields, listed Responses-family models receive hosted Web Search. |
 | `imageGeneration.enabled` | `false` | Enables `openai_generate_image`. |
 | `imageGeneration.models` | `["gpt-image-2.5"]` | Bare image-generation model IDs; the first entry is the default. |
 | `autoMode.models` | `[]` | Models allowed to use Auto Mode. |

package/README.zh.md

@@ -13,7 +13,7 @@
 | --- | --- |
 | Codex 远程上下文 | 切换到新上下文窗口，并通过 `history` 按需检索较早窗口。 |
 | 远程压缩 v2 | 使用服务端返回的加密检查点继续符合条件的 Responses 会话。 |
-| 托管联网搜索 | 为指定模型启用 OpenAI 托管的搜索工具。 |
+| 联网搜索路由 | 按精确模型路由选择本地 `pi-web-access`、Responses 托管 `web_search` 或 CPA standalone `web.run`。 |
 | 图像生成 | 生成图片，或根据明确传入的本地参考图片进行编辑。 |
 | 工具调用审查 | 在指定范围的工具调用执行前，由审查模型判断是否允许执行。 |
 
@@ -31,7 +31,7 @@ pi install npm:pi-openai-toolkit
 
 在当前项目中安装时，在命令后加上 `--local`。
 
-只安装扩展不会自动启用所有功能。没有扩展配置时，压缩模块处于开启状态，但远程上下文关闭，联网搜索没有目标模型，图像生成关闭，自动模式也没有允许的模型和审查模型。
+只安装扩展不会自动启用所有功能。没有扩展配置时，压缩模块处于开启状态，但远程上下文关闭，联网搜索没有工具包选择的路由，图像生成关闭，自动模式也没有允许的模型和审查模型。
 
 扩展配置文件位于：
 
@@ -130,19 +130,44 @@ pi --model my-gateway/gpt-5.6-luna
 
 如果希望使用 Responses 压缩路径，就保持远程上下文关闭。远程压缩 v2 会为符合条件的 Responses 模型保存并回放加密检查点。只有在压缩请求需要使用其他模型时，才设置 `compaction.remoteCompactModel`。
 
-### 启用托管联网搜索
+不配置 `compaction.remoteV2ContextSource` 时，Remote V2 保持原来的 `"legacy"` 输入链路：首次压缩使用 Pi 当前的 session context（最后才回退到事件提供的 preparation），递归压缩使用原始 branch tail。这会保留既有行为，但如果其他扩展改写消息，可能与 provider 实际看到的上下文不同。
 
-在 `webSearch.models` 中填写精确的模型标识：
+将 `compaction.remoteV2ContextSource` 设为 `"pi-context-hook"` 可主动启用 Pi 0.85.1 runtime bridge，让 Remote V2 压缩使用与实时 provider 请求相同的有序 `context` hook 链。如果 Pi 无法提供这条公开 hook 路径，Remote V2 会取消压缩，而不会发送未投影的历史。只有检查点来源标记与当前设置一致时，才会继续回放。在两种模式之间切换后，必须重新创建 Remote V2 检查点；如果自定义状态必须保留在不透明检查点中，请关闭 Remote V2，或使用 Pi 原生压缩。
+
+### 选择联网搜索路由
+
+联网搜索有三条互斥路由。可以设置一个全局默认路由，也可以按精确的 `provider/model-id` 覆盖：
 
 ```json
 {
   "webSearch": {
-    "models": ["my-gateway/gpt-5.6-luna"]
+    "enabled": true,
+    "defaultRoute": "hosted",
+    "routes": {
+      "uwoacrimson/gpt-6-astra": "standalone-alpha",
+      "my-gateway/gpt-5.6-luna": "local"
+    }
   }
 }
 ```
 
-对于这些模型，扩展会用 OpenAI 托管的 Responses 搜索工具替代 Pi 本地的 `web_search` 工具。
+路由选择是精确且确定的：`routes[provider/model-id]` 优先于 `defaultRoute`，`defaultRoute` 优先于旧版 `models` 列表。不支持通配符、模糊模型匹配、按模型名称猜能力、路由间 fallback 或重试。无效的路由值或模型键会告警后忽略，不会猜测路由；新旧字段重叠时会给出迁移告警。`enabled: false` 会释放工具包的工具所有权，并关闭工具包选择的全部三条路径。
+
+- **`local`** 保留已经安装的 `pi-web-access` `web_search` 工具。如果它原本没有激活，工具包不会替你激活；同时不会添加托管 provider 工具或 `web.run`。
+- **`hosted`** 移除名为 `web_search` 的本地 function，并注入原生 Responses `{ "type": "web_search" }` 工具和来源标注。旧版配置仍然有效：
+
+  ```json
+  {
+    "webSearch": {
+      "models": ["my-gateway/gpt-5.6-luna"]
+    }
+  }
+  ```
+
+  没有配置新路由字段时，只有精确命中该列表、且 API 属于现有 Responses 系列（`openai-responses` 或 `openai-codex-responses`）的模型会使用托管搜索。
+- **`standalone-alpha`** 暴露一个 sequential 的 `web.run` 工具，并向 provider 相对的 `/alpha/search` 端点发送一次隔离的 `POST` 请求。例如基础地址是 `https://gateway.example/v1` 时，请求地址是 `https://gateway.example/v1/alpha/search`，不会变成 Responses 端点。支持的命令族包括 `search_query`、`image_query`、`open`、`click`、`find`、`screenshot`、`finance`、`weather`、`sports` 和 `time`；`response_length` 用于调整请求的结果长度。
+
+standalone 路由属于实验性的 CPA/Codex 网关协议，不是稳定的公开 OpenAI Responses 端点。网关/provider 必须提供 `/alpha/search`、启用 `alpha-search` 能力，并支持 standalone web search（Codex provider 通常以 `supports_standalone_web_search = true` 表示）。请求会复用 Pi 当前模型、认证、provider headers、会话标识及 Codex/gateway affinity，不会切换当前模型。MVP 发送受边界限制的命令 envelope，而不是完整会话 transcript；`ref_id` 后续操作依赖 provider 的会话/引用处理；每次工具调用最多发送一次请求；配置无效、路由不可用、取消、超时、非 2xx、响应畸形或超限时都会 fail closed。
 
 ### 生成图片
 
@@ -186,8 +211,12 @@ pi --model my-gateway/gpt-5.6-luna
 | `compaction.contextManagement` | `"off"` | 设置为 `"remote"` 后启用 Codex 远程上下文。 |
 | `compaction.gatewayContextModels` | `[]` | 允许使用远程上下文的网关模型。 |
 | `compaction.remoteCompactModel` | 未设置 | 仅用于 v2 压缩请求的可选模型。 |
+| `compaction.remoteV2ContextSource` | `"legacy"` | 保留原来的原始 session/branch 输入路径。设置为 `"pi-context-hook"` 后才启用 Pi 的有序 context hook projection。检查点与模式绑定。 |
 | `compaction.contextReminderThresholdPercent` | `5` | 每个窗口触发一次提醒的剩余预算百分比。设置为 `0` 会关闭提醒和窗口耗尽兜底。 |
-| `webSearch.models` | `[]` | 使用托管联网搜索的模型。 |
+| `webSearch.enabled` | `true` | 工具包联网搜索路由的总开关。设为 `false` 时不选择任何工具包路由。 |
+| `webSearch.defaultRoute` | 未设置 | 默认路由：`local`、`hosted` 或 `standalone-alpha`。未设置时保留旧版行为。 |
+| `webSearch.routes` | 未设置 | 精确的 `provider/model-id` 路由覆盖。精确条目优先于 `defaultRoute`。 |
+| `webSearch.models` | `[]` | 旧版精确白名单；没有新路由字段时，列表中的 Responses 系列模型使用托管联网搜索。 |
 | `imageGeneration.enabled` | `false` | 启用 `openai_generate_image`。 |
 | `imageGeneration.models` | `["gpt-image-2.5"]` | 裸生图模型 ID；列表第一项是默认模型。 |
 | `autoMode.models` | `[]` | 允许使用自动模式的模型。 |

package/docs/internals.md

@@ -59,8 +59,10 @@ sequenceDiagram
 State invariants the lifecycle code must keep honest:
 
 - The checkpoint gate verifies a successful `notes` `append_to_file` or `write_file` against the persisted session branch after the latest window boundary, so it survives restarts and forks. A response with `ok: false` or `success: false` is not successful, even when HTTP returns 200.
+- The gate uses the live session/branch identity from `ctx.sessionManager`; cached manager identity must not hide a valid current-window pair, and old or foreign-session evidence must remain rejected.
 - Every rollover carries the most recent successful checkpoint path in its handoff message. The optional `thread_hint` is supplemental; a hint failure must not erase the local receipt.
-- `new_context` has no force escape hatch: a successful notes checkpoint is always required before rollover.
+- `new_context` has no force escape hatch: a persisted successful notes checkpoint in the current window is always required before rollover. The model must wait for the notes result to be persisted before retrying.
+- After a marker is accepted for sending, the manager keeps a session/window-anchored pending guard until that exact target marker is persisted or the session changes. A duplicate `new_context` during this persistence gap returns `started: false` and sends no second marker; projected/in-memory messages do not retire the guard.
 - Budget checks are skipped until the current window has produced its own assistant usage. Acting on the previous window's usage anchor would burn the once-per-window reminder on a false alarm.
 - The scheduled trim is consumed exactly once, synchronously, by the first compaction attempt whose boundary window ID matches. Every other compaction path, including a threshold without a scheduled rollover, manual `/compact`, and overflow, is cancelled.
 - A window boundary is persisted as a `codex-context-window` custom message. `session_start` replays boundaries from the branch and rebuilds identity after forks.
@@ -75,6 +77,12 @@ A `compaction_trigger` item appended to the live streaming request yields one ou
 
 A v2 response with a missing or empty checkpoint is never stored, and the `nativeFallback` tier is skipped. Pi's own threshold drives the next attempt, which may use `remoteCompactModel` when configured. `remoteCompactModel` must resolve to the same effective base URL as the active model.
 
+Pi 0.85.1's `session_before_compact` event supplies preparation and branch data, while the direct Remote V2 client can bypass the provider `context` hook chain. To preserve compatibility, an omitted `compaction.remoteV2ContextSource` keeps the original `"legacy"` behavior: first compaction uses `buildSessionContext()` and falls back to `SessionBeforeCompactEvent.preparation`, while recursion uses the opaque window plus the raw branch tail.
+
+Setting `compaction.remoteV2ContextSource: "pi-context-hook"` opts into a narrow runtime bridge around Pi's public `ExtensionRunner.createContext()`. It adds a non-enumerable `ctx.projectContextForCompaction(messages)` method backed by `ExtensionRunner.emitContext()`. In this opt-in mode, Remote V2 first reads `buildSessionContext()` and then runs the ordered projection. If the bridge, session context, or recursive summary anchor is unavailable, the extension cancels rather than sending an unprojected history. The legacy mode is an intentional compatibility trade-off and does not claim parity with provider-visible context hooks.
+
+New checkpoints record `inputProvenance: "pi-context-hook-v1"` or `"legacy-raw-context-v1"`, and replay/recursion reject missing or mode-mismatched markers without searching past the latest compaction. Retained `role: "custom"` messages are optional during replay because they may be changed or removed by context hooks; required user, assistant, and complete tool-call/result content remains ordered and fail-closed.
+
 ---
 
 ### Artifacts and debugging

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.14.6",
+  "version": "0.14.8",
   "private": false,
   "type": "module",
   "engines": {
     "node": ">=22.19.0"
   },
-  "description": "OpenAI toolkit for Pi: Codex Remote Context windows, remote compaction v2, hosted Web Search, image gen, auto mode.",
+  "description": "OpenAI toolkit for Pi: Codex Remote Context windows, remote compaction v2, routed Web Search, image gen, auto mode.",
   "author": "awoaCrim and contributors",
   "license": "MIT",
   "repository": {
@@ -47,6 +47,8 @@
     "extensions/image-generation.ts",
     "extensions/auto-mode.ts",
     "src/compact-client.ts",
+    "src/compaction-projection.ts",
+    "src/pi-context-hook.ts",
     "src/config.ts",
     "src/debug.ts",
     "src/details-store.ts",
@@ -92,6 +94,7 @@
     "src/serializer.ts",
     "src/supported-environment.ts",
     "src/types.ts",
+    "src/web-search/alpha-client.ts",
     "src/web-search/extension.ts",
     "src/web-search/payload.ts",
     "src/web-search/prompt.ts",

package/src/compaction-projection.ts

@@ -0,0 +1,31 @@
+import type {
+	NativeCompactionDetails,
+	NativeCompactionInputProvenance,
+} from "./types";
+
+/** The configured Pi context-hook projector is unavailable or failed. */
+export const COMPACTION_PROJECTION_UNAVAILABLE = "no-supported-projection-seam" as const;
+/** The current session context could not be read before projection. */
+export const COMPACTION_SESSION_CONTEXT_UNAVAILABLE = "session-context-unavailable" as const;
+/** A projected recursive context did not contain the current compaction summary. */
+export const COMPACTION_PROJECTED_CONTEXT_UNAVAILABLE = "projected-compaction-context-unavailable" as const;
+/** The latest opaque checkpoint was created with no or a different input marker. */
+export const COMPACTION_CHECKPOINT_PROVENANCE_UNAVAILABLE = "unverified-compaction-checkpoint" as const;
+
+export type UnprojectedCompactionReason =
+	| typeof COMPACTION_PROJECTION_UNAVAILABLE
+	| typeof COMPACTION_SESSION_CONTEXT_UNAVAILABLE
+	| typeof COMPACTION_CHECKPOINT_PROVENANCE_UNAVAILABLE
+	| typeof COMPACTION_PROJECTED_CONTEXT_UNAVAILABLE;
+
+/**
+ * A Remote V2 checkpoint is safe for the current replay chain only when its
+ * marker matches the configured input source. Structural persistence validation
+ * intentionally remains more permissive for old session files.
+ */
+export function hasVerifiedCompactionInputProvenance(
+	details: Pick<NativeCompactionDetails, "inputProvenance"> | undefined,
+	expected: NativeCompactionInputProvenance,
+): boolean {
+	return details?.inputProvenance === expected;
+}

package/src/config.ts

@@ -31,10 +31,12 @@ import {
 	type CompactionConfig,
 	type ContextManagementMode,
 	type ImageGenerationConfig,
+	type RemoteV2ContextSource,
 	type LoadedToolkitConfig,
 	type NativeFallbackConfig,
 	type ToolkitConfig,
 	type WebSearchConfig,
+	type WebSearchRoute,
 } from "./types";
 import { MAX_IMAGE_MODEL_ID_CHARS } from "./image-generation/types";
 
@@ -47,6 +49,7 @@ const COMPACTION_FIELDS = new Set([
 	"contextManagement",
 	"allowCompactionContinuityBreak",
 	"remoteCompactModel",
+	"remoteV2ContextSource",
 	"nativeFallback",
 	"responsesApis",
 	"gatewayContextModels",
@@ -59,7 +62,7 @@ const COMPACTION_FIELDS = new Set([
 	"artifactRoot",
 ]);
 const NATIVE_FALLBACK_FIELDS = new Set(["enabled", "model", "thinkingLevel"]);
-const WEB_SEARCH_FIELDS = new Set(["enabled", "models"]);
+const WEB_SEARCH_FIELDS = new Set(["enabled", "models", "defaultRoute", "routes"]);
 const IMAGE_GENERATION_FIELDS = new Set(["enabled", "models"]);
 const AUTO_MODE_FIELDS = new Set([
 	"enabled",
@@ -148,6 +151,20 @@ function toContextManagementMode(
 	return undefined;
 }
 
+function toRemoteV2ContextSource(
+	value: unknown,
+	fieldPath: string,
+	warnings: string[],
+): RemoteV2ContextSource | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value === "string") {
+		const normalized = value.trim();
+		if (normalized === "pi-context-hook" || normalized === "legacy") return normalized;
+	}
+	warnings.push(`Ignoring ${fieldPath}: expected one of pi-context-hook, legacy.`);
+	return undefined;
+}
+
 function toModelSpec(value: unknown, fieldPath: string, warnings: string[]): string | null | undefined {
 	if (value === undefined) return undefined;
 	if (value === null) return null;
@@ -231,6 +248,53 @@ function toImageGenerationModels(value: unknown, fieldPath: string, warnings: st
 	return models;
 }
 
+function toWebSearchRoute(
+	value: unknown,
+	fieldPath: string,
+	warnings: string[],
+): WebSearchRoute | undefined {
+	if (value === undefined) return undefined;
+	if (value === "local" || value === "hosted" || value === "standalone-alpha") {
+		return value;
+	}
+	warnings.push(`Ignoring ${fieldPath}: expected one of local, hosted, standalone-alpha.`);
+	return undefined;
+}
+
+function isExactWebSearchModelKey(value: string): boolean {
+	const trimmed = value.trim();
+	const separatorIndex = trimmed.indexOf("/");
+	if (separatorIndex <= 0 || separatorIndex >= trimmed.length - 1) return false;
+	if (/[\s*?\[\]{}]/.test(trimmed)) return false;
+	const provider = trimmed.slice(0, separatorIndex);
+	const modelId = trimmed.slice(separatorIndex + 1);
+	return provider.length > 0 && modelId.length > 0;
+}
+
+function toWebSearchRoutes(
+	value: unknown,
+	fieldPath: string,
+	warnings: string[],
+): Record<string, WebSearchRoute> | undefined {
+	if (value === undefined) return undefined;
+	if (!isRecord(value)) {
+		warnings.push(`Ignoring ${fieldPath}: expected a JSON object.`);
+		return undefined;
+	}
+
+	const routes: Record<string, WebSearchRoute> = {};
+	for (const [rawKey, rawRoute] of Object.entries(value)) {
+		const key = rawKey.trim();
+		if (!isExactWebSearchModelKey(key)) {
+			warnings.push(`Ignoring ${fieldPath}.${rawKey}: expected an exact "provider/model-id" key.`);
+			continue;
+		}
+		const route = toWebSearchRoute(rawRoute, `${fieldPath}.${rawKey}`, warnings);
+		if (route !== undefined) routes[key] = route;
+	}
+	return routes;
+}
+
 function toAutoModeGate(value: unknown, fieldPath: string, warnings: string[]): AutoModeGate | undefined {
 	if (value === undefined) return undefined;
 	if (value === "side-effect" || value === "all") return value;
@@ -264,6 +328,12 @@ function cloneDefaults(): ToolkitConfig {
 		webSearch: {
 			...DEFAULT_WEB_SEARCH_CONFIG,
 			models: [...DEFAULT_WEB_SEARCH_CONFIG.models],
+			...(DEFAULT_WEB_SEARCH_CONFIG.defaultRoute
+				? { defaultRoute: DEFAULT_WEB_SEARCH_CONFIG.defaultRoute }
+				: {}),
+			...(DEFAULT_WEB_SEARCH_CONFIG.routes
+				? { routes: { ...DEFAULT_WEB_SEARCH_CONFIG.routes } }
+				: {}),
 		},
 		imageGeneration: {
 			...DEFAULT_IMAGE_GENERATION_CONFIG,
@@ -347,6 +417,10 @@ function applyCompactionConfig(
 		resolved.remoteCompactModel = remoteCompactModelSpec === null ? undefined : remoteCompactModelSpec;
 	}
 
+	resolved.remoteV2ContextSource =
+		toRemoteV2ContextSource(raw.remoteV2ContextSource, "compaction.remoteV2ContextSource", warnings) ??
+		resolved.remoteV2ContextSource;
+
 	if (raw.nativeFallback !== undefined) {
 		if (isRecord(raw.nativeFallback)) {
 			applyNativeFallbackConfig(raw.nativeFallback, resolved.nativeFallback, warnings);
@@ -393,6 +467,31 @@ function applyWebSearchConfig(
 	if (models !== undefined) {
 		resolved.models = models;
 	}
+
+	const defaultRoute = toWebSearchRoute(raw.defaultRoute, "webSearch.defaultRoute", warnings);
+	if (defaultRoute !== undefined) {
+		resolved.defaultRoute = defaultRoute;
+	}
+
+	const routes = toWebSearchRoutes(raw.routes, "webSearch.routes", warnings);
+	if (routes !== undefined) {
+		resolved.routes = routes;
+	}
+
+	if (defaultRoute !== undefined && resolved.models.length > 0) {
+		warnings.push(
+			"webSearch.defaultRoute overrides legacy webSearch.models for models without an exact webSearch.routes entry.",
+		);
+	}
+	if (routes !== undefined) {
+		for (const key of Object.keys(routes)) {
+			if (resolved.models.includes(key)) {
+				warnings.push(
+					`webSearch.routes.${key} overrides the legacy webSearch.models entry for the same exact model.`,
+				);
+			}
+		}
+	}
 }
 
 function applyImageGenerationConfig(

package/src/context-management/messages.ts

@@ -35,7 +35,7 @@ export const CONTEXT_WINDOW_COMPACTION_SUMMARY =
 	"[Pi Codex context-window boundary; no conversation summary was generated.]";
 
 const CONTEXT_WINDOW_GUIDANCE = `<context_window_guidance>
-Checkpoint the active request, known history IDs, decisions, progress, learnings and next steps in notes before new_context; no summary carries over. After rollover, read the checkpoint receipt note first when present; use a thread hint only as supplemental guidance. Use history only for a missing detail.
+Checkpoint the active request, known history IDs, decisions, progress, learnings and next steps in notes before new_context, and wait for that notes result to be persisted; only a persisted successful result in the current window unlocks the rollover, and no summary carries over. If new_context reports that a rollover is already scheduled, do not call it again in the same window. After rollover, read the checkpoint receipt note first when present; use a thread hint only as supplemental guidance. Use history only for a missing detail.
 </context_window_guidance>`;
 
 export function renderContextWindowMessage(

package/src/context-management/tools.ts

@@ -61,8 +61,10 @@ export interface NewContextDetails { started: boolean; }
 export const NEW_CONTEXT_PARAMETERS = Type.Object({}, { additionalProperties: false });
 
 export const NEW_CONTEXT_CHECKPOINT_REQUIRED_MESSAGE =
-	"new_context refused: no successful notes checkpoint in this window. "
-	+ "Save the active request, decisions, progress and next steps with notes append_to_file or write_file, then retry.";
+	"new_context refused: no persisted successful notes checkpoint in the current context window. "
+	+ "Write the active request, decisions, progress and next steps with notes append_to_file or write_file, "
+	+ "wait until that notes result is persisted, then retry new_context in a later tool turn. "
+	+ "Do not pass force arguments and do not repeat new_context while a rollover is already scheduled.";
 export interface ContextRemainingDetails {
 	remainingTokens?: number;
 	windowId?: string;
@@ -88,13 +90,23 @@ export function createContextManagementTools(
 	const newContext: ToolDefinition<typeof NEW_CONTEXT_PARAMETERS, NewContextDetails> = {
 		name: "new_context",
 		label: "new_context",
-		description: "Start a new remote Codex context window without generating a conversation summary. Requires a successful notes checkpoint in the current window.",
+		description: "Start a new remote Codex context window without generating a conversation summary. Requires a persisted successful notes checkpoint in the current window.",
 		parameters: NEW_CONTEXT_PARAMETERS,
 		promptSnippet: "Start a new remote Codex context window without summarizing history.",
-		promptGuidelines: ["Checkpoint active work in notes before calling new_context; no conversation summary carries over. A successful notes append/write in this window is required."],
+		promptGuidelines: [
+			"Checkpoint active work in notes before calling new_context; no conversation summary carries over. Only a persisted successful notes append/write in the current window unlocks the rollover.",
+			"Wait for the notes tool result before calling new_context; an in-flight or failed write is not a checkpoint. If new_context reports that a rollover is already scheduled, do not call it again in the same window.",
+		],
 		executionMode: "sequential",
 		async execute(_id, _params, signal, _update, ctx) {
 			await assertActive(ctx);
+			manager.synchronize(ctx);
+			if (manager.hasPendingRollover(ctx)) {
+				return {
+					content: [{ type: "text", text: "A new context window is already scheduled." }],
+					details: { started: false },
+				};
+			}
 			if (!manager.hasNotesCheckpointSinceBoundary(ctx)) {
 				throw new Error(NEW_CONTEXT_CHECKPOINT_REQUIRED_MESSAGE);
 			}
@@ -148,7 +160,7 @@ export function createContextManagementTools(
 		parameters: NOTES_PARAMETERS,
 		promptSnippet: "Read and checkpoint remote Codex notes across context windows.",
 		promptGuidelines: [
-			"Before calling new_context, checkpoint the current turn's active work (unfinished tasks, decisions, open questions, references) into notes with append_to_file or write_file so it survives the window change.",
+			"Before calling new_context, checkpoint the current turn's active work (unfinished tasks, decisions, open questions, references) into notes with append_to_file or write_file so it survives the window change; wait for that result to be persisted before calling new_context.",
 			"When a large task spans multiple context windows, keep a running note per line of work and read it at the start of each new window; append new state instead of replacing it unless the note is stale.",
 			"Prefer read_file or search_contents for looking things up; reserve write_file for explicit rewrite/clear and append_to_file for incremental state.",
 			"Keep note text concise and self-contained: it may be read later without the rest of the conversation, so include identifiers and verbatim key decisions, not hearsay summaries.",
@@ -170,12 +182,9 @@ export class ContextManagementToolController {
 		parameters: unknown;
 		promptGuidelines?: string[];
 	}>();
-	private readonly ownedNames = new Set<string>();
-	private readonly baselineNames = new Set<string>();
 	private registered = false;
 	private registrationChecked = false;
 	private registrationValid = false;
-	private baselineCaptured = false;
 
 	constructor(private readonly pi: ExtensionAPI) {}
 
@@ -233,44 +242,22 @@ export class ContextManagementToolController {
 		} catch {
 			this.registrationValid = false;
 		}
-		if (!this.registrationValid) this.ownedNames.clear();
 		return this.registrationValid;
 	}
 
-	private captureBaseline(): boolean {
-		if (this.baselineCaptured) return true;
-		try {
-			const api = this.pi as ExtensionAPI & { getActiveTools?: () => string[] };
-			if (typeof api.getActiveTools !== "function") return false;
-			this.baselineNames.clear();
-			for (const name of api.getActiveTools()) this.baselineNames.add(name);
-			this.baselineCaptured = true;
-			return true;
-		} catch {
-			return false;
-		}
-	}
-
 	sync(active: boolean): boolean {
-		if (!this.verifyRegistration() || !this.captureBaseline()) return false;
+		if (!this.verifyRegistration()) return false;
 		const api = this.pi as ExtensionAPI & { getActiveTools?: () => string[]; setActiveTools?: (names: string[]) => void };
 		if (typeof api.getActiveTools !== "function" || typeof api.setActiveTools !== "function") return false;
 		try {
 			const current = api.getActiveTools();
-			if (active) {
-				const next = [...current];
-				for (const name of this.registeredNames) {
-					if (!next.includes(name) && !this.baselineNames.has(name)) {
-						next.push(name);
-						this.ownedNames.add(name);
-					}
-				}
-				if (next.length !== current.length) api.setActiveTools(next);
-				return true;
-			}
-			const next = current.filter((name) => !this.ownedNames.has(name));
+			// Pi may activate a newly registered tool before the first sync. Once
+			// registration is verified, every registered name belongs to this
+			// controller: active models get all four, inactive models get none.
+			const next = active
+				? [...current, ...[...this.registeredNames].filter((name) => !current.includes(name))]
+				: current.filter((name) => !this.registeredNames.has(name));
 			if (next.length !== current.length) api.setActiveTools(next);
-			this.ownedNames.clear();
 			return true;
 		} catch {
 			return false;
@@ -279,8 +266,6 @@ export class ContextManagementToolController {
 
 	reset(): void {
 		this.sync(false);
-		this.baselineNames.clear();
-		this.baselineCaptured = false;
 	}
 	get isRegistered(): boolean { return this.registrationValid; }
 }