pi-openai-toolkit 0.14.12 → 0.15.0

package/docs/configuration.md

@@ -0,0 +1,176 @@
+# Toolkit configuration
+
+Toolkit reads only `~/.pi/agent/extensions/pi-openai-toolkit/config.json`. There are no project overrides, environment policy overlays, profiles, `extends`, or wildcard rules. Pi still owns extension loading, provider endpoints, model registration, and credentials. A project-local extension installation does not create project-local Toolkit policy.
+
+This reference describes schema v2. Unversioned legacy configuration remains supported. Configuration schema v2 and Remote Compaction v2 are separate version numbers.
+
+---
+
+### Start with a small document
+
+Create the file and parent directory if absent. This example states the shipped feature defaults; it is not a conversion of an existing legacy file:
+
+```json
+{
+  "schemaVersion": 2,
+  "defaults": {
+    "context": { "mode": "remote-compaction" },
+    "webSearch": { "route": "unmanaged" },
+    "imageGeneration": {
+      "enabled": false,
+      "defaultModel": "gpt-image-2.5",
+      "allowedModels": ["gpt-image-2.5"]
+    },
+    "autoMode": { "available": false }
+  },
+  "models": {},
+  "diagnostics": {
+    "level": "info",
+    "notifyOnLoad": false,
+    "captureRequests": false,
+    "captureResponses": false,
+    "redactSensitiveData": true
+  }
+}
+```
+
+`$schema` is optional editor metadata pointing to the shipped [config.schema.json](../config.schema.json). It does not change runtime schema selection. The editor schema describes canonical spelling; runtime also trims surrounding whitespace in supported strings and deduplicates lists. Runtime validation checks normalized key collisions and image-default membership that the editor schema cannot express.
+
+---
+
+### Resolution and errors
+
+Precedence is built-ins, then `defaults`, then `models["provider/model-id"]`. Keys are exact and case-sensitive. Leading/trailing whitespace is trimmed; conflicting normalized keys are rejected. Model IDs may contain further slashes. No pattern matching or endpoint/capability guessing occurs.
+
+Known nested objects merge by field. Missing fields inherit, arrays replace instead of append, and `false`/`0` retain their meanings. Only optional model references accept `null`: context producer, native-fallback model, auto reviewer, and classifier model. `null` elsewhere is invalid. Defaults do not prohibit exact overrides; an exact model can set `available: true` over a default of `false`.
+
+A missing file uses independent built-in defaults. Invalid JSON, an unreadable file, missing/unsupported `schemaVersion` on a v2-shaped document, or mixed legacy/v2 fields are reported distinctly. Unknown v2 policy keys are errors in their owning scope. Invalid selected settings block dependent operations; they never silently pick a more permissive route. Errors in other models remain visible without replacing a valid current model's policy. A valid exact leaf may shadow an invalid default leaf, but cannot hide a malformed containing object or unknown field in that feature scope.
+
+Each public callback, tool execution, compaction, reviewer/classifier operation, or config command uses an immutable snapshot across its awaited helpers. The next operation reads again. This does not make separate Pi headers, payload, and tool events one atomic transaction. Engagement, overrides, scores, windows, and results stay out of the config file.
+
+---
+
+### Context
+
+Place `context` under `defaults` or an exact `models` entry.
+
+| Relative field | Default | Contract |
+| --- | --- | --- |
+| `mode` | `"remote-compaction"` | `"pi"` relinquishes Toolkit context management; `"remote-compaction"` uses the eligible Responses checkpoint path; `"remote-windows"` selects Codex windows where supported. |
+| `remoteCompaction.model` | `null` | Exact producer reference; `null` uses the active model. It must share the effective base URL required by the existing compaction path. |
+| `remoteCompaction.inputSource` | `"legacy"` | `"legacy"` preserves session/raw-branch input; `"pi-context-hook"` opts into Pi's ordered context projection. Checkpoint provenance must match. |
+| `remoteCompaction.allowContinuityBreak` | `false` | Allow restarting from Pi context after a foreign compaction entry. It does not make malformed opaque checkpoints replayable. |
+| `remoteCompaction.apis` | `["openai-responses", "openai-codex-responses"]` | May narrow this set; `[]` permits no remote-compaction API. Unsupported entries are errors. |
+| `nativeFallback.enabled` | `true` | Enable the existing native-method fallback tier. |
+| `nativeFallback.model` | `null` | Optional summary-model reference on the remote-ineligible path. After a remote attempt fails, the existing producer-first fallback order is retained. |
+| `nativeFallback.thinkingLevel` | `"off"` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`; actual model support still applies. |
+| `remoteWindows.leaveManagedMode` | `"warn"` | `"compact"` also requests a close-out when retired history exceeds 80% of the next model's window and compaction can finish. Print mode remains warning-only; turn-end close-out requires a queued trim. |
+| `remoteWindows.reminderThresholdPercent` | `5` | Integer 0-100. `0` disables both the once-per-window reminder and exhausted-window fallback. |
+
+Native Codex eligibility derives from the actual Pi provider/API. Gateways additionally need the exact transport opt-in below. `remote-windows` retains the compaction chain for models outside window capability. A configured window model whose activation fails does not silently receive a summary fallback. The rollover notes gate, durable history, producer/consumer identities, and checkpoint provenance are unchanged. See [Toolkit internals](internals.md).
+
+---
+
+### Compatibility transport
+
+Only `models["provider/model-id"].compatibility.transport` is configurable: `"standard"` is the internal baseline and `"codex-gateway"` is an exact opt-in. There is no global `defaults.compatibility` and no built-in gateway model list.
+
+This selects an existing Toolkit protocol profile, independently of context mode. It does not change Pi's provider, API, endpoint, or model. The same decoded document supplies compatibility for search, image generation, and a separately named compaction producer. A successful config resolution is not a backend capability test.
+
+---
+
+### Web Search
+
+`defaults.webSearch.route` and `models[exact].webSearch.route` accept:
+
+| Route | Behavior |
+| --- | --- |
+| `unmanaged` | Default. Release Toolkit ownership and remove Toolkit-owned standalone exposure. Third-party search and unrelated network tools remain possible. |
+| `local` | Restore the original local tool state and remove native/standalone search conflicts from provider payloads. Never activate a previously inactive local tool. |
+| `hosted` | Use native Responses search with source annotations; suppress conflicting local and standalone tools. |
+| `standalone-alpha` | Experimental, explicit opt-in. Expose sequential `web_run` and call the provider-relative `/alpha/search` endpoint once per execution. |
+
+There is no v2 search master switch. `local` and `unmanaged` differ in payload cleanup and ownership. Missing auth, an unavailable route, a tool conflict, or invalid selected policy does not trigger another route. Standalone supports `search_query`, `image_query`, `open`, `click`, `find`, `screenshot`, `finance`, `weather`, `sports`, and `time`, with `response_length`. It sends a bounded command envelope rather than the full transcript; follow-up references depend on the provider's session/reference handling. The gateway must expose the endpoint and its standalone-search capability.
+
+---
+
+### Images
+
+Image settings are global-only under `defaults.imageGeneration`. `enabled` defaults to `false`. `defaultModel` defaults to `"gpt-image-2.5"`; `allowedModels` defaults to `["gpt-image-2.5"]`.
+
+These are bare output-model IDs, not active-session model keys. Each normalized ID must contain 1-256 characters. The allowed list must remain nonempty after normalization and contain the explicit default. Order has no default-selection meaning. A caller's one-call `model` must be a member; policy and membership are checked before auth, local-reference preparation/upload, and paid dispatch. The active session remains the Responses routing model. Config does not grant permission to upload arbitrary local files or imply that a provider supports a particular image model.
+
+---
+
+### Auto Mode
+
+Place `autoMode` under `defaults` or an exact model. `available` permits engagement; it does not engage the runtime. Use `/auto on` or `--auto`, and `/auto off` to disengage. If an engaged session encounters invalid policy, calls remain blocked until policy is corrected or the user explicitly turns the gate off. A review timeout never means approval.
+
+| Relative field | Default | Contract |
+| --- | --- | --- |
+| `available` | `false` | Model eligibility for engagement. |
+| `reviewerModel` | `null` | Exact review-model reference; required for useful engagement. |
+| `gate` | `"side-effect"` | Reviews `bash`, `write`, `edit`, and `extraTools`; `"all"` reviews every tool. Session gate overrides remain runtime state. |
+| `extraTools` | `[]` | Additional names for the side-effect gate. |
+| `timeoutMs` | `30000` | Integer 1000-120000 milliseconds. |
+| `transcript` | `true` | Include transcript context in the blocking review. |
+| `evidenceTools` | `true` | Permit the reviewer's existing read-only evidence tools. |
+| `maxEvidenceRounds` | `3` | Integer 0-8. |
+| `classifier.enabled` | `false` | Enable nonblocking trajectory pre-scoring. |
+| `classifier.model` | `null` | Exact reference; `null` uses the reviewer. |
+| `classifier.timeoutMs` | `15000` | Integer 1000-120000 milliseconds. |
+| `classifier.maxLag` | `2` | Integer 0-20. |
+| `circuitBreaker.consecutiveDenials` | `3` | Integer 0-100; `0` disables this limit. |
+| `circuitBreaker.recentDenials` | `10` | Integer 0-100; `0` disables this limit. |
+| `circuitBreaker.windowSize` | `50` | Integer 1-200, recent-verdict window size. |
+
+Reviewer and classifier references are not active-session overrides. Classifier scores, denial history, and human decisions never become config entries.
+
+---
+
+### Diagnostics and inspection
+
+Diagnostics are plugin-wide, not model-scoped.
+
+| Field | Default | Contract |
+| --- | --- | --- |
+| `level` | `"info"` | `error`, `warn`, `info`, or `debug`. Debug enables lifecycle/compaction debug artifacts. Configuration issues and operation-blocking failures remain visible at every level. |
+| `notifyOnLoad` | `false` | Optional informational load notification. |
+| `captureRequests` | `false` | Independently opt into provider request artifacts. |
+| `captureResponses` | `false` | Independently capture compact responses; this is not an ordinary chat-response logger. |
+| `redactSensitiveData` | `true` | Optional additional redaction. Critical credentials, account IDs, and opaque encrypted data are always redacted. |
+| `artifactRoot` | `"~/.pi/agent/artifacts/pi-openai-toolkit/compaction"` | Relative paths resolve against the canonical config directory, not the current project. |
+
+`/toolkit-config` (or `show`) displays effective values with built-in/default/exact/legacy origins. `/toolkit-config validate` reports document issues, including unrelated model entries. Reports are bounded and redacted; unknown field names are masked. Repeated issue notifications are deduplicated within a session and do not depend on compaction enablement or debug mode.
+
+`/toolkit-config migration-preview` analyzes a legacy file without changing it. These are human commands using Pi's UI; no model tool, new headless stdout protocol, network probe, auth lookup, tool mutation, or persistent state write is added. Headless operation failures and typed resolution issues remain observable. A truncated candidate is not usable JSON.
+
+---
+
+### Legacy compatibility and migration
+
+Do not combine unversioned roots (`compaction`, `webSearch`, `imageGeneration`, `autoMode`) with `schemaVersion: 2`. Valid legacy behavior is retained through a compatibility adapter, including nullable model clears, legacy image-list defaults, and source-dependent hosted-search failure handling. Invalid selected legacy route values are now blocked instead of disappearing into another selection.
+
+The preview maps recognized fields into a candidate, supplies leaf origins, lists unmapped/dormant paths, and reports `ready`, `needs-review`, `already-v2`, or `unavailable`. `ready` means no known semantic difference was found in recognized active policy; it is not authorization to apply or proof of provider support. Unknown names are masked and their values are never copied into the report. The original source bytes remain the authoritative copy of unknown and dormant content.
+
+| Legacy input | v2 destination |
+| --- | --- |
+| `compaction.enabled` / `contextManagement` | `defaults.context.mode` |
+| `compaction.remoteCompactModel`, `remoteV2ContextSource`, `allowCompactionContinuityBreak`, `responsesApis` | `defaults.context.remoteCompaction` fields |
+| `compaction.nativeFallback` | `defaults.context.nativeFallback` |
+| `compaction.leaveManagedMode`, `contextReminderThresholdPercent` | `defaults.context.remoteWindows` fields |
+| `compaction.gatewayContextModels` | Exact `models[key].compatibility.transport` |
+| `webSearch.defaultRoute`, `routes`, `models` | Default/exact search route candidates, subject to review below |
+| `imageGeneration.models` | `allowedModels` plus an explicit default taken from the legacy first entry |
+| `autoMode.enabled` / `models` | Default/exact `autoMode.available` |
+| Legacy auto reviewer/classifier/breaker controls | Corresponding `autoMode` controls |
+| Legacy compaction debug/capture/path settings | `diagnostics` |
+
+The preview cannot claim universal lossless conversion:
+
+- A legacy hosted allowlist ignores unsupported APIs and malformed payloads; explicit v2 hosted selection fails closed. Moving a list entry to an exact hosted route changes those failure paths.
+- Disabled legacy features can retain dormant model lists/routes. A simplified v2 policy cannot preserve enable-later intent without review.
+- Gateway compatibility is now shared independently of context mode; review effects on compaction and image affinity.
+- Unknown fields, invalid normalization, or candidate validation failures require review. `remoteV2ContextSource: "legacy"` remains `inputSource: "legacy"`; preview does not upgrade checkpoint provenance or opt any model into standalone search.
+
+There is no automatic migration, writer, or `--write` option. Before a separately approved manual cutover, back up the original bytes and verify that every installed Toolkit copy supports v2. Older copies, including 0.14.13, do not support this format. Updating source in a checkout does not update an installed package. Keep the legacy file until that cutover is ready.

package/docs/internals.md

@@ -6,6 +6,7 @@ Developer-facing reference for [pi-openai-toolkit](../README.md). The README kee
 
 ### Table of Contents
 
+- [Configuration resolution](#configuration-resolution)
 - [Remote Context protocol](#remote-context-protocol)
 - [Rollover lifecycle](#rollover-lifecycle)
 - [Remote Compaction v2 wire contract](#remote-compaction-v2-wire-contract)
@@ -15,6 +16,16 @@ Developer-facing reference for [pi-openai-toolkit](../README.md). The README kee
 
 ---
 
+### Configuration resolution
+
+The single global document is loaded through [src/config.ts](../src/config.ts). [src/config/legacy.ts](../src/config/legacy.ts) owns unversioned compatibility; [src/config/v2.ts](../src/config/v2.ts) validates v2 scopes, resolves exact policy, and records leaf origins. [src/config/policy.ts](../src/config/policy.ts) defines effective values independently of persisted session data. See the [configuration reference](configuration.md) for supported fields and migration limits.
+
+Feature entrypoints resolve once per public operation and pass that immutable snapshot through awaited helpers. A separately named compaction producer is resolved from the same decoded document for its own identity. Subsequent callbacks reload; there is no cross-event provider transaction, project lookup, singleton cache, or config state writer. Internal legacy-shaped engine adapters preserve compaction/search algorithms without exposing v2 parsing to consumers. Cross-feature gateway policy belongs to the resolver, not the context enable switch.
+
+Selected invalid policy blocks dependent operations; unrelated model errors remain reportable without replacing the selected model. An engaged auto gate stays blocking when its policy becomes invalid. Image choices are checked before auth, uploads, or paid requests. The human `/toolkit-config` command inspects effective values, validation, or a migration candidate without action APIs or network access. Migration is preview-only; source bytes and unknown/dormant content stay untouched.
+
+---
+
 ### Remote Context protocol
 
 Internal alpha endpoints, adapted from `@howaboua/pi-codex-conversion`:
@@ -29,7 +40,7 @@ The native route uses `{base} = <backend-api>/codex` with `Authorization: Bearer
 
 Search text and note bodies are sent under the encrypted-argument policy. Live model requests carry `x-codex-window-id` and `x-codex-turn-metadata` request headers derived from the active window identity.
 
-Coverage is never inferred from model names. A native session uses provider `openai-codex` with API `openai-codex-responses` for any model ID. A gateway session uses API `openai-responses` and must carry an exact `provider/model` key listed in `compaction.gatewayContextModels`; the list ships empty and there is no built-in gateway SKU. See [src/context-management/codex-provider.ts](../src/context-management/codex-provider.ts). The toolkit registers no provider or model with Pi. It resolves credentials and base URLs through Pi's `ModelRegistry`.
+Coverage is never inferred from model names. A native session uses provider `openai-codex` with API `openai-codex-responses` for any model ID. A gateway session uses API `openai-responses` and must carry an exact `provider/model` key whose `models[exact].compatibility.transport` is `"codex-gateway"` (legacy `compaction.gatewayContextModels`); no gateway is opted in by default. See [src/context-management/codex-provider.ts](../src/context-management/codex-provider.ts). The toolkit registers no provider or model with Pi. It resolves credentials and base URLs through Pi's `ModelRegistry`.
 
 ---
 
@@ -63,26 +74,32 @@ 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.
-- A successful rollover closes the pre-rollover checkpoint phase. The first turn in the new window reads the receipt once and resumes the active user task; it must not immediately create another checkpoint or call `new_context` as part of that handoff. A later checkpoint is only for a later rollover.
+- A successful rollover closes the pre-rollover checkpoint phase. The first turn in the new window reads the receipt once and resumes the active user task; it must not immediately create another checkpoint or call `new_context` as part of that handoff. A later checkpoint is only for a later rollover, and `canRolloverFromCurrentWindow()` enforces it: a window entered by a rollover has to produce a tool result from a tool that is not one of `new_context`, `get_context_remaining`, `history`, or `notes` before it can roll over again.
+- Pi 0.86 sends the system prompt and the entire tool loadout as `system` messages inside the transcript: `Agent#createContextSnapshot()` passes messages only, and the Responses transport rebuilds `params.tools` from the leading system message. Trimming everything before a window boundary therefore deletes the model's only tool declaration, and Pi never re-declares it because the persisted transcript still looks unchanged. `preserveSystemHead()` re-anchors the merged pre-boundary state as the leading message of every trimmed window.
+- When even that rebuild would lose declared tools, the trim is refused and the full message list is sent: a window that still carries the previous turns is usable, a window with no tools silently degrades into a chat the model can only narrate. Each refusal is reported once per window and lost-tool set through `takeProjectionDiagnostics()`, which writes a `context.projection.tool_loadout_shrink` compaction artifact and warns in the UI.
+- The manager also remembers the head it last anchored. When a boundary compaction retires the transcript entry that declared the tools, the branch itself no longer contains a system message, and the remembered head is re-anchored instead of sending a tool-less window. The cache is request-time only, refreshed by every projection, and cleared by `reset()`.
 - `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.
+- Retiring windows is a projection-level act: the session branch keeps every retired window until a compaction consumes the scheduled trim. `evaluateWindowBulk()` measures that gap and compares it with the model about to receive it, `decideBulkCliffAction()` maps the report onto the `leaveManagedMode` policy (`warn` default, `compact`), and `decideBulkCloseOut()` only allows the automatic compaction where a compaction can actually finish: never in print mode (the process exits with the turn and would kill the summary), and at turn end only while a rollover trim is queued, because the window policy cancels every other compaction. Each window and model is surfaced once, and every decision writes a `window-bulk.<action>` compaction artifact with its trigger.
+- The close-out runs from `model_select` and `agent_settled`, never from `before_agent_start`: `ExtensionContext.compact()` aborts the running turn, and a hook inside turn processing is exactly the busy lane it must not fight.
+- A configured native-fallback summary model is checked against the size of the request Pi is about to send it (`estimateSummarizationRequest`). A narrower summary model than the active one - 272k summarizing a 400k session - returns `model-window-too-small` before authentication or the model call, so the current model gets the first attempt instead of a terminated stream.
 
 ---
 
 ### Remote Compaction v2 wire contract
 
-v2 is what an uncovered session gets. Any model that Remote Context declines, such as a gateway model absent from `gatewayContextModels`, can still compact through v2 when its API appears in `responsesApis`. The two strategies never compete for one session.
+v2 is what an uncovered session gets. Any model that Remote Context declines, such as a gateway without an exact transport opt-in, can still compact through v2 when its API appears in `context.remoteCompaction.apis`. The two strategies never compete for one session.
 
 A `compaction_trigger` item appended to the live streaming request yields one output item of `type: "compaction"` with non-empty `encrypted_content`, stored in `CompactionEntry.details.compactedWindow`. On later requests the opaque checkpoint is replayed ahead of live turns, with no text summary. Replay fails closed: if the summary anchor cannot be located, the request is aborted with a notification and a content-free failure artifact. The sentinel-only payload is never sent.
 
 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.
+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 `context.remoteCompaction.inputSource` 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.
+Setting `context.remoteCompaction.inputSource: "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.
 
@@ -107,11 +124,11 @@ This is a version-coupled adapter, not a stable Pi extension contract. It is fea
 
 ### Artifacts and debugging
 
-With `debug: true`, the toolkit writes lifecycle and compaction artifacts under `artifactRoot` (default `~/.pi/agent/artifacts/pi-openai-toolkit/compaction`):
+With `diagnostics.level: "debug"`, the toolkit writes lifecycle and compaction artifacts under `diagnostics.artifactRoot` (default `~/.pi/agent/artifacts/pi-openai-toolkit/compaction`):
 
 - Each `session_start` writes a lifecycle artifact whose `activation` field records `active` or the exact inactive reason, such as `unsupported-model`, `unsupported-api`, `missing-api-key`, `auth-resolution-failed`, or `tool-name-conflict`.
-- `logProviderPayloads` additionally writes provider request metadata and payloads, while `logCompactResponses` writes compact status and structural summaries with complete response and body fields critically redacted. Keep both off unless inspecting a specific request.
-- Artifacts always redact Authorization credentials, API keys and tokens, Codex account IDs, and opaque `encrypted_content` or `encrypted_output`, even when `redactSensitiveData` is `false`.
+- `diagnostics.captureRequests` independently writes provider request metadata and payloads, while `diagnostics.captureResponses` writes compact status and structural summaries with complete response and body fields critically redacted. Keep both off unless inspecting a specific request.
+- Artifacts always redact Authorization credentials, API keys and tokens, Codex account IDs, and opaque `encrypted_content` or `encrypted_output`, even when `diagnostics.redactSensitiveData` is `false`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.14.12",
+  "version": "0.15.0",
   "private": false,
   "type": "module",
   "engines": {
@@ -46,6 +46,13 @@
     "src/compaction-projection.ts",
     "src/pi-context-hook.ts",
     "src/config.ts",
+    "src/config-command.ts",
+    "src/config/policy.ts",
+    "src/config/legacy.ts",
+    "src/config/v2.ts",
+    "src/config/migration.ts",
+    "src/config/notifications.ts",
+    "config.schema.json",
     "src/debug.ts",
     "src/details-store.ts",
     "src/deferred-tool-carryover.ts",
@@ -54,6 +61,7 @@
     "src/context-management/messages.ts",
     "src/context-management/window-budget.ts",
     "src/context-management/window-request.ts",
+    "src/context-management/window-bulk.ts",
     "src/context-management/window-manager.ts",
     "src/context-management/codex-provider.ts",
     "src/context-management/history-notes.ts",
@@ -96,6 +104,7 @@
     "src/web-search/prompt.ts",
     "src/web-search/types.ts",
     "docs/internals.md",
+    "docs/configuration.md",
     "README.md",
     "README.zh.md",
     "LICENSE",

package/src/auto-mode/extension.ts

@@ -1,6 +1,7 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { createReadOnlyTools, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { loadToolkitConfig } from "../config";
+import { loadToolkitConfig, resolveToolkitConfig, type ResolvedToolkitConfig } from "../config";
+import { notifyConfigIssues } from "../config/notifications";
 import {
 	DEFAULT_AUTO_MODE_CONFIG,
 	type AutoModeConfig,
@@ -152,6 +153,12 @@ export function registerAutoModeExtension(
 	let callIndex = 0;
 	let scoringInFlight = false;
 
+	function readConfig(ctx: ExtensionContext, model = ctx.model): ResolvedToolkitConfig {
+		const resolved = resolveToolkitConfig(loadConfig(), model);
+		notifyConfigIssues(ctx, resolved);
+		return resolved;
+	}
+
 	function updateStatus(ctx: ExtensionContext, reviewingTool?: string): void {
 		if (!ctx.hasUI) return;
 		if (ctx.mode === "tui") {
@@ -188,7 +195,7 @@ export function registerAutoModeExtension(
 		if (!isAutoModeEligible(ctx.model, config)) {
 			if (ctx.hasUI) {
 				ctx.ui.notify(
-					"Auto mode needs an allowlisted model in autoMode.models and a configured autoMode.reviewerModel.",
+					"Auto mode needs availability for the current model and a configured reviewerModel.",
 					"warning",
 				);
 			}
@@ -373,10 +380,14 @@ export function registerAutoModeExtension(
 	pi.registerCommand(AUTO_MODE_COMMAND, {
 		description: "Model-reviewed tool approval: /auto [on|off|status|all|side]",
 		handler: async (args, ctx) => {
-			const { config } = loadConfig();
-			const auto = config.autoMode;
-			applyConfiguredGate(runtime, auto);
+			const resolved = readConfig(ctx);
+			const auto = resolved.config.autoMode;
 			const sub = args.trim().toLowerCase();
+			if (resolved.invalidFeatures.includes("autoMode") && sub !== "off") {
+				if (ctx.hasUI) ctx.ui.notify("Auto-mode configuration is invalid; the existing gate remains engaged until /auto off or a valid configuration is supplied.", "error");
+				return;
+			}
+			applyConfiguredGate(runtime, auto);
 
 			switch (sub) {
 				case "on":
@@ -419,7 +430,8 @@ export function registerAutoModeExtension(
 	});
 
 	pi.on("session_start", (event, ctx) => {
-		const { config } = loadConfig();
+		const resolved = readConfig(ctx);
+		const { config } = resolved;
 		toolReviewRenderer.clear();
 		if (
 			!toolReviewRenderer.supported &&
@@ -438,7 +450,8 @@ export function registerAutoModeExtension(
 		resetScoreTracker(tracker);
 		resetRejectionBreaker(breaker);
 		callIndex = 0;
-		const startedFromFlag = pi.getFlag(AUTO_MODE_FLAG) === true && engage(ctx, config.autoMode);
+		const requestedFromFlag = pi.getFlag(AUTO_MODE_FLAG) === true;
+		const startedFromFlag = requestedFromFlag && (resolved.invalidFeatures.includes("autoMode") ? (runtime.engaged = true) : engage(ctx, config.autoMode));
 		if (startedFromFlag && event.reason === "startup" && ctx.mode === "tui") {
 			ctx.ui.notify(`Auto mode on. Reviewing: ${describeGate(runtime)}`, "info");
 		}
@@ -446,8 +459,9 @@ export function registerAutoModeExtension(
 	});
 
 	pi.on("model_select", (event, ctx) => {
-		const { config } = loadConfig();
-		if (runtime.engaged && !isAutoModeEligible(event.model, config.autoMode)) {
+		const resolved = readConfig(ctx, event.model);
+		const { config } = resolved;
+		if (!resolved.invalidFeatures.includes("autoMode") && runtime.engaged && !isAutoModeEligible(event.model, config.autoMode)) {
 			disengage(ctx);
 			if (ctx.hasUI) ctx.ui.notify("Auto mode off: this model is not allowlisted.", "warning");
 		}
@@ -455,7 +469,9 @@ export function registerAutoModeExtension(
 	});
 
 	pi.on("before_agent_start", (_event, ctx) => {
-		const { config } = loadConfig();
+		const resolved = readConfig(ctx);
+		const { config } = resolved;
+		if (resolved.invalidFeatures.includes("autoMode")) { resetScoreTracker(tracker); updateStatus(ctx); return; }
 		applyConfiguredGate(runtime, config.autoMode);
 		if (runtime.engaged && !isAutoModeEligible(ctx.model, config.autoMode)) {
 			disengage(ctx);
@@ -472,8 +488,12 @@ export function registerAutoModeExtension(
 		callIndex += 1;
 		if (!runtime.engaged) return undefined;
 
-		const { config } = loadConfig();
-		const auto = config.autoMode;
+		const resolved = readConfig(ctx);
+		if (resolved.invalidFeatures.includes("autoMode")) {
+			resetScoreTracker(tracker);
+			return { block: true, reason: "Auto-mode configuration is invalid. The gate remains engaged; fix the configuration or explicitly use /auto off." };
+		}
+		const auto = resolved.config.autoMode;
 		applyConfiguredGate(runtime, auto);
 
 		if (!isAutoModeEligible(ctx.model, auto)) {
@@ -622,8 +642,10 @@ export function registerAutoModeExtension(
 
 	pi.on("tool_result", (event, ctx) => {
 		if (!runtime.engaged) return undefined;
-		const { config } = loadConfig();
+		const resolved = readConfig(ctx);
+		const { config } = resolved;
 		const auto = config.autoMode;
+		if (resolved.invalidFeatures.includes("autoMode") || !isAutoModeEligible(ctx.model, auto)) { resetScoreTracker(tracker); return undefined; }
 		if (auto.classifier.enabled && shouldReviewTool(event.toolName, runtime)) {
 			scheduleClassification(ctx, auto, {
 				toolName: event.toolName,