@yhong91/cpac 0.1.32 → 0.1.34

package/README.md

@@ -38,18 +38,18 @@ cpac status
 
 # 4a. 持久注入（长期生效，写入 agent 配置，可完整恢复）
 cpac install --all                     # 注入所有检测到的目标（codex/pi/kimi）
-cpac install --target codex            # 只注入 Codex（默认开启 multi-agent v2）
-cpac install --target codex --v2_models  # 先多选 spawn_agent 模型再注入
-cpac install --target codex --max_context  # 注入时把模型上下文提升到实测上限（opt-in，仅限 codex）
-cpac restore --target codex            # 撤掉注入；注入期间的用户改动会留下
+cpac install codex                     # 只注入 Codex（默认开启 multi-agent v2）
+cpac install codex --v2_models         # 先多选 spawn_agent 模型再注入
+cpac install codex --max_context       # 注入时把模型上下文提升到实测上限（opt-in，仅限 codex）
+cpac restore codex                     # 撤掉注入；注入期间的用户改动会留下
 
 # 4b. 临时接管（退出无痕，不写任何配置文件）
 cpac claude                            # Claude Code 走 CPA
 cpac opencode                          # opencode 走 CPA（模型选 cpac/<模型名>）
 
 # 5. 可选：Agent 配置向导与模型选择
-cpac codex --setup                     # Codex 配置向导 → 注入 → 启动
-cpac claude --setup                    # Claude 模型向导 → 启动
+cpac setup codex                       # Codex 配置向导 → 注入 → 启动
+cpac setup claude                      # Claude 模型向导 → 启动
 
 # 6. 升级（装上新版本后自动 sync 已接入的 agent）
 cpac upgrade
@@ -80,7 +80,7 @@ cpac status   # 验证：CPA_API_KEY 应显示 configured
 }
 ```
 
-   Claude 槽位（opus/sonnet/haiku）通常不用配：cpac 启动时自动选择——同家族 claude 模型优先，否则 gemini → grok → luna → 目录第一个；opus 无匹配则不设。这个链条在常见目录上正好给出理想结果：sonnet 落在 claude-sonnet-*（它同时充当 Auto mode 分类器的替身，避免分类请求失败后回退到昂贵的会话主模型），haiku 落在快的 gemini flash。只有目录奇怪时才用 `cpac claude --setup` 交互式配置。codex spawn subagent 取三个 GPT + gemini + grok 五席（顺序即优先级，Codex 只广告 catalog 前 5），可通过 `cpac codex --setup` 交互式配置。候选替换：`mimo-v2.5`（haiku）、`grok-4.5`（haiku）。若上述 slug 不在目录中（`curl -s -H "Authorization: Bearer $CPA_API_KEY" "$CPA_BASE_URL/v1/models"` 可查），按家族就近替换。分类器机制细节见 [docs/claude-auto-mode-classifier.md](docs/claude-auto-mode-classifier.md)。
+   Claude 槽位（opus/sonnet/haiku）通常不用配：cpac 启动时自动选择——同家族 claude 模型优先，否则 gemini → grok → luna → 目录第一个；opus 无匹配则不设。这个链条在常见目录上正好给出理想结果：sonnet 落在 claude-sonnet-*（它同时充当 Auto mode 分类器的替身，避免分类请求失败后回退到昂贵的会话主模型），haiku 落在快的 gemini flash。只有目录奇怪时才用 `cpac setup claude` 交互式配置。codex spawn subagent 取三个 GPT + gemini + grok 五席（顺序即优先级，Codex 只广告 catalog 前 5），可通过 `cpac setup codex` 交互式配置。候选替换：`mimo-v2.5`（haiku）、`grok-4.5`（haiku）。若上述 slug 不在目录中（`curl -s -H "Authorization: Bearer $CPA_API_KEY" "$CPA_BASE_URL/v1/models"` 可查），按家族就近替换。分类器机制细节见 [docs/claude-auto-mode-classifier.md](docs/claude-auto-mode-classifier.md)。
 
 1. **持久注入**（只对检测到的目标；codex 会应用步骤 3 的 spawn_models）：
 
@@ -91,12 +91,12 @@ cpac status   # 验证：各 target 显示 ready/injected
 
 1. **统一启动与配置**：
    - 启动：`cpac <codex|claude|kimi|grok|pi|opencode> [args...]`（所有原生参数如 `-c` 等原样透明传递）
-   - 配置并启动：`cpac <codex|claude> --setup`（向导结束后注入并拉起）
+   - 配置并启动：`cpac setup <codex|claude>`（向导结束后注入并拉起）
    - 还原：`cpac <agent> clear`（还原或重置配置）
 
 2. **已安装后升级**：npm 发布新版本后，等 publish 成功再执行 `cpac upgrade`。它会按需 `npm install -g`，再对已接入的 Codex / Pi / Kimi / Grok 做 `sync`。不要拆成 `npm install -g @yhong91/cpac` 再手动 `cpac sync`。只刷新配置、不升 CLI 时才用 `cpac sync`。
 
-失败处理：任何一步报错时先跑 `cpac status`；密钥未配置回到步骤 2；注入后异常用 `cpac <agent> clear` 或 `cpac restore --target <id>` 恢复原配置。
+失败处理：任何一步报错时先跑 `cpac status`；密钥未配置回到步骤 2；注入后异常用 `cpac <agent> clear` 或 `cpac restore <id>` 恢复原配置。
 
 ## 首次引导
 
@@ -110,9 +110,9 @@ CPA_API_KEY: configured / not configured
 
 Commands:
   cpac claude [args...]  Launch Claude Code through CPA
-  cpac inject            Inject CPA into Codex
+  cpac setup <codex|claude> Configure then launch
   cpac status            Show Codex injection status
-  cpac restore --target <id> | --all  Detach injected agents
+  cpac restore <id> | --all  Detach injected agents
   cpac --help            Show command usage
 ```
 
@@ -164,21 +164,21 @@ cpac --help
 
 ```bash
 cpac detect [--json] [--home PATH]
-cpac install [--target codex,pi,kimi] [--all] [--dry-run] [--force] [--v2_off] [--v2_models] [--max_context] [--home PATH]
-cpac sync [--target codex,pi,kimi] [--all] [--dry-run] [--v2_off] [--v2_models] [--max_context] [--home PATH]
-cpac restore --target <id> | --all [--dry-run] [--home PATH]
+cpac install [codex|pi|kimi|grok...] [--all] [--dry-run] [--force] [--v2_off] [--v2_models] [--max_context] [--home PATH]
+cpac sync [codex|pi|kimi|grok...] [--all] [--dry-run] [--v2_off] [--v2_models] [--max_context] [--home PATH]
+cpac restore <id...> | --all [--dry-run] [--home PATH]
 cpac uninstall [--dry-run]
 cpac upgrade [--check]
 cpac -v | --version
 ```
 
 - `detect` 列出每个目标是否被检测到、是否已接入 CPAC；`--json` 输出机器可读结果。
-- `install` 默认作用于检测到的目标；`--target` 指定目标、`--all` 全部。各目标映射到既有逻辑：`codex` → `cpac inject`，`pi` → `cpac pi install`，`kimi` → `cpac kimi install`。`--dry-run` 只打印将要做的事，`--force` 允许重装已安装目标。
-- `sync` 按当前 `cpa_url` 和 CPA 目录强制刷新**已经接入**的目标（Codex 重新注入、Pi 扩展重写、Kimi 配置重写），用来在 CPA 地址或模型目录变化后一次对齐本地配置。不带参数只动已安装目标；`--all` 会对检测到的目标做同样的强制刷新（尚未安装的会装上）。`--max_context` 仍只对 `--target codex` 有效。
-- Codex 注入默认开启 multi-agent v2（写入 `[features.multi_agent_v2] enabled = true`）；`install --target codex --v2_off` 写入 `enabled = false`。服务端还需在 CPA 配置中开启 `codex.optimize-multi-agent-v2`。
+- `install` 默认作用于检测到的目标；后面直接写 agent 名（`cpac install codex pi`），`--all` 全部。`codex` 写入 catalog 并拉起 loopback 代理；`pi`/`kimi`/`grok` 写入各自配置。`--dry-run` 只打印将要做的事，`--force` 允许重装已安装目标。
+- `sync` 按当前 `cpa_url` 和 CPA 目录强制刷新**已经接入**的目标（Codex 重新注入、Pi 确认 `npm:@yhong91/cpac` 并清理旧的 `extensions/pi-cpac.ts`、Kimi 配置重写），用来在 CPA 地址或模型目录变化后一次对齐本地配置。不带参数只动已安装目标；`--all` 会对检测到的目标做同样的强制刷新（尚未安装的会装上）。`--max_context` 仍只对 `cpac install codex` 有效。
+- Codex 注入默认开启 multi-agent v2（写入 `[features.multi_agent_v2] enabled = true`，catalog 行打 `multi_agent_version: "v2"`）；`install codex --v2_off` 关掉 toml 并去掉 catalog 戳。v2 开着时会剥掉 `[agents] max_threads`（Codex 否则拒启动）。`cpac status` 对照 config 里的 `v2_off` / `max_context` 和 live toml / catalog。服务端还需在 CPA 配置中开启 `codex.optimize-multi-agent-v2`。
 - `--v2_models` 进入 arrow-key 复选框选择最多 5 个 spawn_agent 模型（勾选顺序即推荐顺序），选择结果存入配置文件的 `spawn_models`，注入时把这些模型排到 `codex-models.json` 最前——Codex 客户端只把 catalog 前 5 个可见模型广告为 spawn 覆盖项。
-- `restore` 必须带 `--target` 或 `--all`，卸掉指定（或全部）已注入目标。`--all` 时未安装的目标静默跳过。
-- `uninstall` 先用和 `cpac codex --setup` 相同的方向键选择器确认（默认 Cancel），再 `restore --all`，最后 `npm uninstall -g @yhong91/cpac`。不要用 `--target`。非终端取消。`--dry-run` 跳过确认。
+- `restore` 必须带 agent 名或 `--all`，卸掉指定（或全部）已注入目标。`--all` 时未安装的目标静默跳过。
+- `uninstall` 先用和 `cpac setup codex` 相同的方向键选择器确认（默认 Cancel），再 `restore --all`，最后 `npm uninstall -g @yhong91/cpac`。不要跟 agent 名；卸载的是 cpac 包本身。非终端取消。`--dry-run` 跳过确认。
 - `--home PATH` 临时把 `HOME` 指向给定目录，便于在隔离环境中试验。
 - `upgrade` 是发布后更新本机的一次性入口：查 npm → 需要时 `npm install -g` → 对**已接入**的 Codex / Pi / Kimi 执行 `sync`。已是最新也会 sync。不要先手动 `npm install -g` 再 `cpac sync`。`--check` 只报告版本，不安装也不 sync。没有已安装目标时跳过 sync，不报错。只刷新配置、不升 CLI 时用 `cpac sync`。
 
@@ -196,7 +196,7 @@ cpac claude -- -p "检查当前项目"
 #### 配置与清除
 
 ```bash
-cpac claude --setup                    # 交互式依次配置 Sonnet / Haiku / Opus，然后启动
+cpac setup claude                      # 交互式依次配置 Sonnet / Haiku / Opus，然后启动
 cpac claude clear                      # 重置所有覆盖，恢复自动选择
 ```
 
@@ -225,18 +225,18 @@ cpac codex exec "帮我写一个测试"
 #### 配置与清除
 
 ```bash
-cpac codex --setup                     # 交互式配置后注入并启动 Codex
+cpac setup codex                       # 交互式配置后注入并启动 Codex
 cpac codex clear                       # 还原 Codex 原生配置并关闭代理
 ```
 
-#### 传统注入命令
+#### 注入（`cpac install codex`）
 
 ```bash
-cpac inject [--v2_off] [--v2_models] [--max_context] [--config PATH]
-cpac restore --target codex
+cpac install codex [--v2_off] [--v2_models] [--max_context] [--config PATH]
+cpac restore codex
 ```
 
-`inject` 从远端 `/v1/models?client_version=1` 获取 Codex rich catalog，并启动只监听 `127.0.0.1` 的轻量转发代理。Codex 配置保留内置 `openai` provider，只写入根级 `model_catalog_json` 和：
+`install codex` 从远端 `/v1/models?client_version=1` 获取 Codex rich catalog，并启动只监听 `127.0.0.1` 的轻量转发代理。Codex 配置保留内置 `openai` provider，只写入根级 `model_catalog_json` 和：
 
 ```toml
 openai_base_url = "http://127.0.0.1:10101/v1"
@@ -244,21 +244,13 @@ openai_base_url = "http://127.0.0.1:10101/v1"
 
 Codex App/CLI 发给本地代理的 ChatGPT bearer 不会转发到 CPA；代理会改用 `CPA_API_KEY`，并将请求和流式响应原样转发到远端 CPA。这保留了 Codex App 的原生 `openai` provider 身份、历史和账号相关界面。已有用户自定义根级 `openai_base_url` 或非 `openai` 的活动 `model_provider` 时，CPAC 会拒绝覆盖。
 
-Codex App 的长驻 `app-server` 可能缓存旧目录。`inject` 会删除 `models_cache.json`；如果选择器仍未更新，请重启 Codex App。
+Codex App 的长驻 `app-server` 可能缓存旧目录。注入会删除 `models_cache.json`；如果选择器仍未更新，请重启 Codex App。
 
-注入命令可选 `--max_context`（`cpac inject --max_context` 或 `cpac install --target codex --max_context`，默认不带）：把 catalog 中 `max_context_window` 高于 `context_window` 的模型提升到上限，并把 `auto_compact_token_limit` 设为上限的 90%。Codex 把 `context_window` 当输入预算而非展示标签，上游默认保留保守运营值（如 GPT-5.6 家族 272k），带上该参数后可用到实测上限（约 921k，opencodex 实测）；90% 压缩线确保在硬上限前触发 auto-compact。不带参数注入的仍是原本上下文的目录。该参数仅限 codex，与其他 target 组合使用会直接报错。
+注入命令可选 `--max_context`（`cpac install codex --max_context`，默认不带）：把 catalog 中 `max_context_window` 高于 `context_window` 的模型提升到上限，并把 `auto_compact_token_limit` 设为上限的 90%。Codex 把 `context_window` 当输入预算而非展示标签，上游默认保留保守运营值（如 GPT-5.6 家族 272k），带上该参数后可用到实测上限（约 921k，opencodex 实测）；90% 压缩线确保在硬上限前触发 auto-compact。不带参数注入的仍是原本上下文的目录。该参数仅限 codex，与其他 target 组合使用会直接报错。
 
-`config.toml` 不存在时拒绝注入。当前是 native 时把原文件备份到 `state_dir/codex/config.toml`（覆盖更旧的 native 快照）；已注入后再 inject 不覆盖备份。kimi/grok/pi 同样：没有旧配置不写空备份，native 覆盖旧快照，已接入则保留。`restore --target codex`：若 `config.toml` 相对注入未改，按原 mode 逐字节还原备份；若用户在注入期间改过文件，只撤掉 CPAC 写入的 catalog、url 和标记。没有其它需要代理的 agent 时才关闭代理。
+`config.toml` 不存在时拒绝注入。当前是 native 时把原文件备份到 `state_dir/codex/config.toml`（覆盖更旧的 native 快照）；已注入后再装不覆盖备份。kimi/grok 同样：没有旧配置不写空备份，native 覆盖旧快照，已接入则保留。Pi 只改 `settings.json` 的 `packages`，不备份。`restore codex`：若 `config.toml` 相对注入未改，按原 mode 逐字节还原备份；若用户在注入期间改过文件，只撤掉 CPAC 写入的 catalog、url 和标记。没有其它需要代理的 agent 时才关闭代理。
 
-loopback 代理是 detached 用户进程，不安装系统服务。机器重启或进程意外退出后，`cpac status` 会报告 `loopback proxy stopped`；重新执行 `cpac inject` 或 `cpac kimi` / `cpac grok` 即可恢复。
-
-需要由现有进程管理器监督时，可使用前台入口：
-
-```bash
-cpac proxy
-```
-
-它复用 `state.json` 里记录的端口和实例身份；没有 loopback 记录时会拒绝启动。
+loopback 代理是 detached 用户进程，不安装系统服务。机器重启或进程意外退出后，`cpac status` 会报告 `loopback proxy stopped`；重新执行 `cpac install codex` 或 `cpac kimi` / `cpac grok` 即可恢复。
 
 默认路径：
 
@@ -267,7 +259,6 @@ Codex 配置：$CODEX_HOME/config.toml，未设置 CODEX_HOME 时为 ~/.codex/co
 CPAC state：~/.cpac/state.json（公用 proxy 字段 + 已接入 agent 记录）
 各 agent 配置备份：~/.cpac/<agent>/<原文件名>
   Codex  ~/.cpac/codex/config.toml
-  Pi     ~/.cpac/pi/pi-cpac.ts
   Kimi   ~/.cpac/kimi/config.toml
   Grok   ~/.cpac/grok/config.toml
 restore / `<agent> clear` 会删掉该 agent 的备份目录和 state.json 里的对应记录
@@ -291,13 +282,13 @@ cpac opencode [--] [opencode args...]
 cpac pi install
 ```
 
-它将生成 `pi-cpac.ts` 写入 `~/.pi/agent/extensions/`，Pi 启动时自动加载并从 CPA 动态注册模型目录。卸载：
+在 `~/.pi/agent/settings.json` 的 `packages` 中加入 `npm:@yhong91/cpac`。Pi 启动时按 npm 包加载 `extensions/pi-cpac.ts`，从 CPA 动态注册模型。旧版写入的 `~/.pi/agent/extensions/pi-cpac.ts` 会在 install / restore 时删掉。卸载：
 
 ```bash
-cpac restore --target pi
+cpac restore pi
 ```
 
-Pi 扩展尊重 `PI_CODING_AGENT_DIR` 环境变量。
+尊重 `PI_CODING_AGENT_DIR`。扩展代码随 npm 包更新，已装过的副本用 `pi update npm:@yhong91/cpac`（或 `pi update --extensions`）。
 
 ### Kimi Code
 
@@ -307,10 +298,10 @@ Pi 扩展尊重 `PI_CODING_AGENT_DIR` 环境变量。
 cpac kimi install
 ```
 
-它在 `~/.kimi-code/config.toml` 追加一个由 CPAC 管理的块，注册 `cpac` OpenAI 兼容 provider，并把 CPA 目录里的每个模型映射为一个 `cpac/<模型名>` 条目。带 `supported_reasoning_levels` 的模型会写入 `capabilities`、`support_efforts` 和 `default_effort`，否则 Kimi 只给 Claude 名套内置 thinking profile，其它模型会停在 thinking off 且无法改 effort。`base_url` 指向共享 loopback 代理，因此密钥不落盘。install 会写入 `state.json` 并在需要时启动代理，不必先 `cpac inject`。卸载与状态：
+它在 `~/.kimi-code/config.toml` 追加一个由 CPAC 管理的块，注册 `cpac` OpenAI 兼容 provider，并把 CPA 目录里的每个模型映射为一个 `cpac/<模型名>` 条目。带 `supported_reasoning_levels` 的模型会写入 `capabilities`、`support_efforts` 和 `default_effort`，否则 Kimi 只给 Claude 名套内置 thinking profile，其它模型会停在 thinking off 且无法改 effort。`base_url` 指向共享 loopback 代理，因此密钥不落盘。install 会写入 `state.json` 并在需要时启动代理，不必先单独注入 Codex。卸载与状态：
 
 ```bash
-cpac restore --target kimi
+cpac restore kimi
 ```
 
 Kimi Code 配置目录尊重 `KIMI_CODE_HOME` 环境变量。首次写入前若 `config.toml` 已存在，会在 `state_dir/kimi/config.toml` 保留一份原始快照（只存最早版本），万一文件损坏可手动复制回去。
@@ -321,7 +312,7 @@ Kimi Code 配置目录尊重 `KIMI_CODE_HOME` 环境变量。首次写入前若
 | --- | --- | --- |
 | `CPA_API_KEY` | 无 | CPA Bearer key；可由 `cpac` 首次引导写入 shell 启动文件 |
 | `CPA_BASE_URL` | `http://124.223.178.52:8317` | 覆盖内置 CPA 地址 |
-| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | 覆盖 Pi agent 目录（影响 `cpac pi install` 写入位置） |
+| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | 覆盖 Pi agent 目录（影响 `settings.json` 写入位置） |
 | `KIMI_CODE_HOME` | `~/.kimi-code` | 覆盖 Kimi Code 目录（影响 `cpac kimi install` 写入位置） |
 | `CPAC_CONFIG` | `~/.config/cpac/config.json` | 指定可选 JSON 配置路径 |
 | `CODEX_HOME` | `~/.codex` | Codex home 目录 |
@@ -332,7 +323,7 @@ CPAC CLI 可临时覆盖 CPA 地址：
 CPA_BASE_URL='https://cpa.example.com' cpac claude
 ```
 
-`pi-cpac.ts` 插件固定连接配置指定的 CPA 地址，并且只从 Pi 进程环境读取 `CPA_API_KEY`；不读取用户 home 中的私有文件。
+Pi 扩展只从进程环境读取 `CPA_BASE_URL`（默认内置地址）和 `CPA_API_KEY`；不读取 `config.json` 的 `cpa_url`，也不读用户 home 中的私有文件。
 
 ## 可选 JSON 配置
 
@@ -359,7 +350,7 @@ CPA_BASE_URL='https://cpa.example.com' cpac claude
 使用自定义配置：
 
 ```bash
-cpac inject --config ./cpac.json
+cpac install codex --config ./cpac.json
 cpac claude --config ./cpac.json -- --model claude-sonnet-4-5
 ```
 

package/cpac.example.json

@@ -7,5 +7,7 @@
     "sonnet": "claude-sonnet-4-6",
     "haiku": "glm-5.3"
   },
-  "spawn_models": ["gpt-5.5", "claude-opus-4-8"]
+  "spawn_models": ["gpt-5.5", "claude-opus-4-8"],
+  "max_context": false,
+  "v2_off": false
 }

package/dist/agents.js

@@ -3,12 +3,16 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { pickSpawnModels, saveSpawnModels } from "./config.js";
+import { MAX_SPAWN_MODELS, loadCatalogSlugs, pickSpawnModels, saveCodexSetup, saveSpawnModels, } from "./config.js";
 import { MANAGED_MARKER, inject, restore } from "./targets/codex.js";
 import { grokConfigPath, grokHome, installGrokConfig, isGrokConfigInstalled, uninstallGrokConfig, } from "./targets/grok.js";
 import { installKimiConfig, isKimiConfigInstalled, kimiConfigPath, uninstallKimiConfig, } from "./targets/kimi.js";
-import { installPiExtension, isPiExtensionInstalled, piExtensionsDir, uninstallPiExtension, } from "./targets/pi.js";
-import { CPACError, atomicWrite, checkboxPicker, expandUserPath, objectValue, } from "./util.js";
+import { PI_PACKAGE, installPiExtension, isPiExtensionInstalled, piAgentDir, piSettingsPath, uninstallPiExtension, } from "./targets/pi.js";
+import { CPACError, atomicWrite, checkboxPicker, expandUserPath, objectValue, tabWizard, } from "./util.js";
+const CODEX_CTX_STD = "Standard (default input budget, e.g. 200K~272K)";
+const CODEX_CTX_MAX = "Max Context Window (lift to full upper bound, e.g. 921K~1M, 90% auto-compact limit)";
+const CODEX_V2_ON = "Enabled (Default)";
+const CODEX_V2_OFF = "Disabled (--v2_off)";
 export async function runCodexConfig(config, configPath, options = {}) {
     if (options.reset) {
         let raw = {};
@@ -26,38 +30,75 @@ export async function runCodexConfig(config, configPath, options = {}) {
             }
         }
         delete raw.spawn_models;
+        delete raw.max_context;
+        delete raw.v2_off;
         atomicWrite(configPath, Buffer.from(`${JSON.stringify(raw, null, 2)}\n`));
         await runRestore(config, ["codex"], { all: false, dryRun: false });
         console.log("Codex configuration reset to default");
         return 0;
     }
     if (options.interactive && (!process.stdin.isTTY || !process.stderr.isTTY)) {
-        console.log(config.spawn_models
-            ? JSON.stringify(config.spawn_models, null, 2)
-            : "spawn_models not set");
+        console.log(JSON.stringify({
+            spawn_models: config.spawn_models ?? [],
+            max_context: !!config.max_context,
+            v2_off: !!config.v2_off,
+        }, null, 2));
         return 0;
     }
     let spawnModels = config.spawn_models;
-    let v2Off = options.v2Off ?? false;
-    let maxContext = options.maxContext ?? false;
-    if (options.interactive || options.v2Models) {
+    let v2Off = options.v2Off || !!config.v2_off;
+    let maxContext = options.maxContext || !!config.max_context;
+    if (options.interactive) {
+        const slugs = await loadCatalogSlugs(config);
+        const picked = await tabWizard([
+            {
+                id: "models",
+                label: "Models",
+                items: slugs,
+                max: MAX_SPAWN_MODELS,
+                selected: config.spawn_models?.filter((slug) => slugs.includes(slug)),
+            },
+            {
+                id: "context",
+                label: "Context",
+                items: [CODEX_CTX_STD, CODEX_CTX_MAX],
+                max: 1,
+                selected: [maxContext ? CODEX_CTX_MAX : CODEX_CTX_STD],
+            },
+            {
+                id: "v2",
+                label: "V2",
+                items: [CODEX_V2_ON, CODEX_V2_OFF],
+                max: 1,
+                selected: [v2Off ? CODEX_V2_OFF : CODEX_V2_ON],
+            },
+        ]);
+        if (picked.models.length === 0)
+            throw new CPACError("no models selected");
+        spawnModels = picked.models;
+        maxContext = picked.context[0] === CODEX_CTX_MAX;
+        v2Off = picked.v2[0] === CODEX_V2_OFF;
+        saveCodexSetup(configPath, {
+            spawn_models: picked.models,
+            max_context: maxContext,
+            v2_off: v2Off,
+        });
+        console.log(`codex setup saved to ${configPath}: models=${picked.models.join(", ")} max_context=${maxContext} v2_off=${v2Off}`);
+    }
+    else if (options.v2Models) {
         const picked = await pickSpawnModels(config);
         if (picked.length > 0) {
             spawnModels = picked;
             saveSpawnModels(configPath, picked);
             console.log(`spawn_models saved to ${configPath}: ${picked.join(", ")}`);
         }
-        if (options.interactive) {
-            const [maxCtxChoice] = await checkboxPicker("Codex Context Window Size:", [
-                "Standard (default input budget, e.g. 200K~272K)",
-                "Max Context Window (lift to full upper bound, e.g. 921K~1M, 90% auto-compact limit)",
-            ], 1);
-            maxContext = maxCtxChoice?.startsWith("Max Context") ?? false;
-            const [v2Choice] = await checkboxPicker("Codex Multi-Agent V2 mode:", ["Enabled (Default)", "Disabled (--v2_off)"], 1);
-            v2Off = v2Choice === "Disabled (--v2_off)";
-        }
     }
-    const updatedConfig = { ...config, spawn_models: spawnModels };
+    const updatedConfig = {
+        ...config,
+        spawn_models: spawnModels,
+        max_context: maxContext || undefined,
+        v2_off: v2Off || undefined,
+    };
     await runInstall(updatedConfig, ["codex"], {
         all: false,
         dryRun: false,
@@ -174,20 +215,20 @@ const TARGETS = [
     },
     {
         id: "pi",
-        home: () => piExtensionsDir(),
-        detected: () => binaryOnPath("pi") || existsSync(piExtensionsDir()),
+        home: () => piAgentDir(),
+        detected: () => binaryOnPath("pi") || existsSync(piAgentDir()),
         installed: () => isPiExtensionInstalled(),
         version: () => detectClientVersion("pi"),
         install: async (config, dryRun) => {
             if (dryRun) {
-                console.log(`would write Pi extension: ${join(piExtensionsDir(), "pi-cpac.ts")}`);
+                console.log(`would add ${PI_PACKAGE} to ${piSettingsPath()}`);
                 return;
             }
             await installPiExtension(config);
         },
         uninstall: async (config, dryRun) => {
             if (dryRun) {
-                console.log(`would remove Pi extension: ${join(piExtensionsDir(), "pi-cpac.ts")}`);
+                console.log(`would remove ${PI_PACKAGE} from ${piSettingsPath()}`);
                 return;
             }
             await uninstallPiExtension(config);
@@ -272,12 +313,12 @@ export async function runInstall(config, requested, options) {
     const eligible = TARGETS.filter((target) => target.detected()).map((target) => target.id);
     const selected = selectTargets(requested, options.all, eligible);
     if (selected.length === 0) {
-        throw new CPACError(`no supported targets detected; use --target ${TARGETS.map((target) => target.id).join(",")} or --all`);
+        throw new CPACError(`no supported targets detected; use: cpac install ${TARGETS.map((target) => target.id).join(" ")} or --all`);
     }
     // Catalog context lifting is Codex-specific; refuse to silently skip it on
     // other targets so the flag never gains cross-agent meaning.
     if (options.maxContext && selected.some((target) => target.id !== "codex")) {
-        throw new CPACError("--max_context is only valid with --target codex");
+        throw new CPACError("--max_context is only valid with codex");
     }
     for (const target of selected) {
         if (target.installed(config) && !options.force) {
@@ -312,7 +353,7 @@ export async function runSync(config, requested, options) {
 }
 export async function runRestore(config, requested, options) {
     if (requested.length === 0 && !options.all) {
-        throw new CPACError("restore requires --target <id> or --all");
+        throw new CPACError("restore requires an agent name or --all");
     }
     const eligible = TARGETS.filter((target) => target.installed(config)).map((target) => target.id);
     const selected = selectTargets(requested, options.all, eligible);

package/dist/config.js

@@ -15,10 +15,12 @@ const CONFIG_KEYS = new Set([
     "state_dir",
     "claude_models",
     "spawn_models",
+    "max_context",
+    "v2_off",
 ]);
 // Codex advertises only the first 5 picker-visible catalog models as
 // spawn_agent overrides (codex-rs MAX_SPAWN_AGENT_MODEL_OVERRIDES).
-const MAX_SPAWN_MODELS = 5;
+export const MAX_SPAWN_MODELS = 5;
 export const CLAUDE_SLOT_KEYS = ["opus", "sonnet", "haiku"];
 export const AGENT_IDS = ["codex", "pi", "kimi", "grok"];
 const AGENT_ID_SET = new Set(AGENT_IDS);
@@ -143,6 +145,12 @@ export function loadConfig(path, useDefaultsIfMissing = false) {
             return model.trim();
         });
     }
+    const maxContextRaw = value.max_context;
+    if (maxContextRaw !== undefined && typeof maxContextRaw !== "boolean")
+        throw new CPACError("max_context must be a boolean");
+    const v2OffRaw = value.v2_off;
+    if (v2OffRaw !== undefined && typeof v2OffRaw !== "boolean")
+        throw new CPACError("v2_off must be a boolean");
     const codexHome = expandUserPath(process.env.CODEX_HOME?.trim() || join(homedir(), ".codex"));
     const codexConfig = resolve(expandUserPath(value.codex_config || join(codexHome, "config.toml")));
     const stateDir = resolve(expandUserPath(value.state_dir || join(homedir(), ".cpac")));
@@ -160,6 +168,8 @@ export function loadConfig(path, useDefaultsIfMissing = false) {
         state_dir: stateDir,
         claude_models: claudeModels,
         spawn_models: spawnModels,
+        max_context: maxContextRaw === true ? true : undefined,
+        v2_off: v2OffRaw === true ? true : undefined,
     };
 }
 export function apiBase(cpaUrl) {
@@ -233,6 +243,10 @@ export async function fetchCatalog(cpaUrl, apiKey) {
     if (models.some((model) => !objectValue(model) || typeof model.slug !== "string" || !model.slug.trim())) {
         throw new CPACError("CPA catalog contains a model without a slug");
     }
+    for (const model of models) {
+        if (objectValue(model))
+            sanitizeModelModalities(model);
+    }
     return {
         bytes: Buffer.from(`${JSON.stringify(document, null, 2)}\n`),
         modelCount: models.length,
@@ -292,7 +306,65 @@ export function reorderCatalog(bytes, order) {
     document.models = models.map((entry) => entry.model);
     return Buffer.from(`${JSON.stringify(document, null, 2)}\n`);
 }
-export function saveSpawnModels(configPath, models) {
+function catalogDocument(bytes) {
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new CPACError("invalid CPA catalog");
+    }
+}
+// Codex parses input_modalities as a closed enum. One extra value (e.g. "video")
+// rejects the entire catalog. Keep unknown fields, but coerce this one.
+function sanitizeModelModalities(model) {
+    if (!("input_modalities" in model))
+        return;
+    const raw = model.input_modalities;
+    const accepted = Array.isArray(raw)
+        ? raw.filter((value) => value === "text" || value === "image" || value === "audio")
+        : [];
+    model.input_modalities = accepted.length > 0 ? accepted : ["text"];
+}
+export function sanitizeCatalogModalities(bytes) {
+    const document = catalogDocument(bytes);
+    for (const model of document.models) {
+        if (objectValue(model))
+            sanitizeModelModalities(model);
+    }
+    return Buffer.from(`${JSON.stringify(document, null, 2)}\n`);
+}
+export function stampMultiAgentVersion(bytes, enabled) {
+    const document = catalogDocument(bytes);
+    for (const model of document.models) {
+        if (!objectValue(model))
+            continue;
+        if (enabled)
+            model.multi_agent_version = "v2";
+        else
+            delete model.multi_agent_version;
+    }
+    return Buffer.from(`${JSON.stringify(document, null, 2)}\n`);
+}
+export function catalogMaxContextLive(bytes) {
+    const document = catalogDocument(bytes);
+    for (const model of document.models) {
+        if (!objectValue(model))
+            continue;
+        const maxWindow = typeof model.max_context_window === "number" && model.max_context_window > 0
+            ? Math.floor(model.max_context_window)
+            : 0;
+        const window = typeof model.context_window === "number"
+            ? Math.floor(model.context_window)
+            : 0;
+        if (maxWindow > 0 &&
+            window === maxWindow &&
+            model.auto_compact_token_limit === Math.floor(maxWindow * 0.9)) {
+            return true;
+        }
+    }
+    return false;
+}
+function patchConfig(configPath, fields) {
     let document = {};
     if (existsSync(configPath)) {
         let parsed;
@@ -306,23 +378,33 @@ export function saveSpawnModels(configPath, models) {
             throw new CPACError("config must be a JSON object");
         document = parsed;
     }
-    document.spawn_models = models;
+    Object.assign(document, fields);
     atomicWrite(configPath, Buffer.from(`${JSON.stringify(document, null, 2)}\n`));
 }
-// Arrow-key checkbox picker on raw stdin; resolves with the checked labels in
-export async function pickSpawnModels(config) {
-    const apiKey = process.env[config.api_key_env]?.trim();
-    if (!apiKey)
-        throw new CPACError(`environment variable ${config.api_key_env} is not set`);
-    const catalog = await fetchCatalog(config.cpa_url, apiKey);
+export function saveSpawnModels(configPath, models) {
+    patchConfig(configPath, { spawn_models: models });
+}
+export function saveCodexSetup(configPath, setup) {
+    patchConfig(configPath, setup);
+}
+export function catalogSlugs(bytes) {
     let document;
     try {
-        document = JSON.parse(new TextDecoder().decode(catalog.bytes));
+        document = JSON.parse(new TextDecoder().decode(bytes));
     }
     catch {
         throw new CPACError("invalid CPA catalog");
     }
-    const slugs = document.models.map((model) => model.slug);
+    return document.models.map((model) => model.slug);
+}
+export async function loadCatalogSlugs(config) {
+    const apiKey = process.env[config.api_key_env]?.trim();
+    if (!apiKey)
+        throw new CPACError(`environment variable ${config.api_key_env} is not set`);
+    return catalogSlugs((await fetchCatalog(config.cpa_url, apiKey)).bytes);
+}
+export async function pickSpawnModels(config) {
+    const slugs = await loadCatalogSlugs(config);
     const picked = await checkboxPicker("Select spawn_agent models", slugs, MAX_SPAWN_MODELS);
     if (picked.length === 0)
         throw new CPACError("no models selected");