@ask-llm/plugin 0.16.3 → 0.17.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ask-llm",
-  "version": "0.16.3",
+  "version": "0.17.0",
   "description": "AI-to-AI collaboration — review code and debate plans across Codex, Grok, Antigravity, Ollama, and Gemini",
   "author": {
     "name": "Anton Lykhoyda",

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ask-llm",
   "displayName": "Ask LLM",
-  "version": "0.16.3",
+  "version": "0.17.0",
   "description": "Portable AI-to-AI review and pairing workflows for Cursor Agent with explicit provider transports.",
   "author": {
     "name": "Anton Lykhoyda"

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ask-llm/plugin
 
+## 0.17.0
+
+### Minor Changes
+
+- [#327](https://github.com/Lykhoyda/ask-llm/pull/327) [`4e0e436`](https://github.com/Lykhoyda/ask-llm/commit/4e0e436b43f7a1bff897bd690c71765420ff32ae) Thanks [@Lykhoyda](https://github.com/Lykhoyda)! - Add Codex `preferred` and `sandbox` to unified `ask-llm` (fail closed on other providers) and let plugin Codex workflows use fully pinned unified MCP when no `ask-codex` leaf is present, without stripping provider options ([#266](https://github.com/Lykhoyda/ask-llm/issues/266)).
+
+### Patch Changes
+
+- Updated dependencies [[`124d93d`](https://github.com/Lykhoyda/ask-llm/commit/124d93dd6dae941ffac37d6583be7cbf0eb0c30f), [`4e0e436`](https://github.com/Lykhoyda/ask-llm/commit/4e0e436b43f7a1bff897bd690c71765420ff32ae)]:
+  - @ask-llm/antigravity-mcp@0.7.6
+  - @ask-llm/mcp@0.10.0
+
 ## 0.16.3
 
 ### Patch Changes

package/README.md

@@ -23,16 +23,20 @@ Part of the [Ask LLM](https://github.com/Lykhoyda/ask-llm) monorepo.
 
 ### MCP Servers
 
-The plugin bundles only the Codex MCP registration under Claude Code's plugin namespace. After installation or upgrade, fully restart Claude Code and run `/mcp`; `plugin:ask-llm:codex` should be connected. `/sol-review` selects `ask-codex`.
+The recommended cross-provider server is `@ask-llm/mcp`. Keep `npx -y @ask-llm/mcp` as the primary registration; `npm install -g @ask-llm/mcp` is a first-class alternative when you want a pinned global binary. Split provider packages (`@ask-llm/codex-mcp`, `@ask-llm/grok-mcp`, and the others) remain an advanced optimization for a richer per-provider tool surface.
+
+The plugin bundles only the Codex MCP registration under Claude Code's plugin namespace. After installation or upgrade, fully restart Claude Code and run `/mcp`; `plugin:ask-llm:codex` should be connected. Codex-facing workflows prefer that bundled `ask-codex` leaf (or a user-scoped `ask-codex`), then a fully pinned unified `ask-llm` call (`provider: "codex"` plus model and Codex options), then the disclosed `codex exec` fallback. An older unified schema that cannot honor those options is reported rather than stripped.
 
 `/grok-pair` does not add servers to the plugin. Register the unified Ask LLM server at user scope (the recommended install: it exposes `ask-cursor-agent` for the Cursor Agent route plus the unified `ask-llm` tool, which pair skills call only fully pinned) and, optionally, the split Grok server for the `ask-grok` leaf:
 
 ```bash
 claude mcp add --scope user ask-llm -- npx -y @ask-llm/mcp
+# first-class alternative after `npm install -g @ask-llm/mcp`:
+# claude mcp add --scope user ask-llm -- ask-llm-mcp
 claude mcp add --scope user grok -- npx -y @ask-llm/grok-mcp
 ```
 
-Existing user-scoped Codex registrations remain compatible and keep their shorter names. Other providers are registered explicitly at user scope:
+Existing user-scoped Codex registrations remain compatible and keep their shorter names. Other providers are registered explicitly at user scope only when you want their split leaves:
 
 ```bash
 claude mcp add --scope user gemini -- npx -y @ask-llm/gemini-mcp
@@ -40,6 +44,8 @@ claude mcp add --scope user ollama -- npx -y @ask-llm/ollama-mcp
 claude mcp add --scope user antigravity -- npx -y @ask-llm/antigravity-mcp
 ```
 
+If Codex is missing entirely, provision the unified server first (`claude mcp add --scope user ask-llm -- npx -y @ask-llm/mcp`) or the split Codex leaf with `claude mcp add --scope user codex -- npx -y @ask-llm/codex-mcp`. If `/mcp` shows the bundled registration but it is disconnected, run `npx -y @ask-llm/mcp doctor` and restart Claude Code. `/sol-review` preserves source-plugin and session-local MCP/settings context when reading the active `claude mcp list` inventory, reports missing, unavailable, and unsupported-schema states separately, and discloses the explicit `codex exec` fallback after failed health, an incomplete unified schema, or MCP transport failure.
+
 ### Cursor Agent
 
 Cursor's supported Agent Skills surface exposes exactly `/codex-pair` and `/grok-pair` (the manifest sets `agents: []`, `commands: []`, and `hooks: {}` so Claude agents and the Claude-format hooks file are never auto-discovered, and the other skills stay Claude/Pi-only until they get Cursor adapters); its MCP surface is `mcp.json`, which bundles only the unified `ask-llm` server. For a source checkout:
@@ -48,9 +54,7 @@ Cursor's supported Agent Skills surface exposes exactly `/codex-pair` and `/grok
 agent --plugin-dir ./packages/claude-plugin
 ```
 
-`/codex-pair` requires explicit `model=` and `effort=` values before consent, then uses a separately user-installed `ask-codex` leaf when exposed, otherwise the bundled unified `ask-llm` fully pinned (`provider: "codex"`, model, effort, include directories, session), with resumable Thread ID, cancellation, and result relay. It never guesses MCP-process environment defaults and does not pretend Claude-only hooks are active. `/grok-pair` gives Cursor-native `.cursor/mcp.json` and Tools & MCP reload guidance; it never sends Cursor users to `claude mcp add`. If installing only MCP configuration, the recommended minimal entry is `ask-llm` → `npx -y @ask-llm/mcp` in project `.cursor/mcp.json` or user `~/.cursor/mcp.json` (keep one registration per server — do not duplicate it when the plugin is loaded); add `codex` → `@ask-llm/codex-mcp` or `grok` → `@ask-llm/grok-mcp` only when you specifically want their `ask-codex`/`ask-grok` leaves, then reload MCP/restart Cursor Agent. When Cursor hosts `/grok-pair`, it never recursively invokes Cursor Agent.
-
-If Codex is missing entirely, register it explicitly with `claude mcp add --scope user codex -- npx -y @ask-llm/codex-mcp`. If `/mcp` shows the bundled registration but it is disconnected, run `npx -y @ask-llm/mcp doctor` and restart Claude Code. `/sol-review` preserves source-plugin and session-local MCP/settings context when reading the active `claude mcp list` inventory, reports missing and unavailable states separately, and discloses the explicit `codex exec` fallback after failed health or MCP transport failure.
+`/codex-pair` requires explicit `model=` and `effort=` values before consent, then uses a separately user-installed `ask-codex` leaf when exposed, otherwise the bundled unified `ask-llm` fully pinned (`provider: "codex"`, model, effort, include directories, sandbox, session), with resumable Thread ID, cancellation, and result relay. It never guesses MCP-process environment defaults and does not pretend Claude-only hooks are active. `/grok-pair` gives Cursor-native `.cursor/mcp.json` and Tools & MCP reload guidance; it never sends Cursor users to `claude mcp add`. If installing only MCP configuration, the recommended minimal entry is `ask-llm` → `npx -y @ask-llm/mcp` in project `.cursor/mcp.json` or user `~/.cursor/mcp.json` (keep one registration per server — do not duplicate it when the plugin is loaded); add `codex` → `@ask-llm/codex-mcp` or `grok` → `@ask-llm/grok-mcp` only when you specifically want their `ask-codex`/`ask-grok` leaves, then reload MCP/restart Cursor Agent. When Cursor hosts `/grok-pair`, it never recursively invokes Cursor Agent.
 
 ### Pi
 
@@ -80,7 +84,7 @@ See the [Pi host guide](https://lykhoyda.github.io/ask-llm/plugin/pi) for securi
 | `/gemini-review` | Gemini-only code review with confidence filtering |
 | `/codex-review` | Codex-only code review (precision-first, ≥80 confidence — default for routine PR review) |
 | `/fable-review` | Isolated, read-only review requesting native Fable, with runtime verification limits disclosed |
-| `/sol-review` | Model-pinned GPT-5.6 Sol review through the bundled `ask-codex` MCP tool; missing registration and service unavailability are diagnosed separately before the explicit CLI fallback |
+| `/sol-review` | Model-pinned GPT-5.6 Sol review: prefer bundled or user-scoped `ask-codex`, then fully pinned unified `ask-llm`, then the disclosed CLI fallback |
 | `/ollama-review` | Local review — no data leaves your machine |
 | `/brainstorm` | Explicit multi-model brainstorm (default external: Antigravity + Codex); supports an exact no-Gemini Grok + GPT-5.6 Sol panel through Cursor Agent |
 | `/grok-review` | Grok review through explicit xAI API or Grok CLI harness; no fallback |

package/agents/codex-reviewer.md

@@ -10,6 +10,7 @@ tools:
   - Read
   - mcp__codex__ask-codex
   - mcp__plugin_ask-llm_codex__ask-codex
+  - mcp__ask-llm__ask-llm
 ---
 
 <!-- PORTABLE-CONTRACT:START -->
@@ -62,7 +63,11 @@ You are a code review coordinator that leverages OpenAI Codex for independent an
 
 ### Phase 2: Review Prompt Construction
 
-When calling `ask-codex`, leave `model` and `preferred` unset and set `reasoningEffort: "high"`. This uses GPT-5.6 Sol at high effort and transparently falls back to GPT-5.6 Terra on quota. Structure the prompt to request confidence scoring AND severity classification:
+When calling Codex, leave `model` and `preferred` unset and set `reasoningEffort: "high"` plus `sandbox: "read-only"`. This uses GPT-5.6 Sol at high effort and transparently falls back to GPT-5.6 Terra on quota.
+
+Prefer an exact `ask-codex` leaf (`mcp__codex__ask-codex` or `mcp__plugin_ask-llm_codex__ask-codex`). If none is exposed, call `mcp__ask-llm__ask-llm` with `provider: "codex"` and the same options. Inspect the unified input schema first: if it lacks `reasoningEffort`, `includeDirs`, `preferred`, or `sandbox`, stop and tell the user to upgrade `@ask-llm/mcp` (`npx -y @ask-llm/mcp@latest` or `npm install -g @ask-llm/mcp`); do not omit those fields to make the call succeed. Never make an unpinned generic `ask-llm` call.
+
+Structure the prompt to request confidence scoring AND severity classification:
 
 ```
 Review the following code changes. For each issue found, rate:

package/agents/codex-verifier.md

@@ -9,6 +9,8 @@ tools:
   - Grep
   - Read
   - mcp__codex__ask-codex
+  - mcp__plugin_ask-llm_codex__ask-codex
+  - mcp__ask-llm__ask-llm
 ---
 
 <!-- PORTABLE-CONTRACT:START -->
@@ -35,7 +37,7 @@ If the assistant said "I added retry logic to the executor," `codex-reviewer` lo
 
 ## Tool surface (read-only by contract)
 
-Allowed: `Read`, `Grep`, `Glob`, `Bash` (read-only commands only — `cat`, `head`, `tail`, `wc`, `diff`, `git diff|log|show|status|blame`, `jq`, language-native test runners in dry-run/list mode), `mcp__codex__ask-codex`.
+Allowed: `Read`, `Grep`, `Glob`, `Bash` (read-only commands only — `cat`, `head`, `tail`, `wc`, `diff`, `git diff|log|show|status|blame`, `jq`, language-native test runners in dry-run/list mode), `mcp__codex__ask-codex`, `mcp__plugin_ask-llm_codex__ask-codex`, `mcp__ask-llm__ask-llm`.
 
 Forbidden: anything that mutates state. Never run `rm`, `mv`, `chmod`, redirections (`>`, `>>`, `tee`), package installs (`npm install`, `pip install`), or DB writes (`INSERT`, `UPDATE`, `DELETE`, `DROP`). No `Write`, no `Edit`, no `NotebookEdit`.
 
@@ -77,9 +79,9 @@ Evidence sources, in order of cost:
 - `Bash`: `git log --diff-filter=A -- <path>` — confirm a file was added in this branch.
 - `Bash`: `git diff <ref> -- <path>` — confirm what specifically changed.
 - `Bash`: `node -e "..."` (dry-run only, no side effects) — evaluate a small expression to confirm a constant value.
-- `mcp__codex__ask-codex` — when the verification needs Codex's broader code-tracing (e.g., "does function X actually call function Y in the new path?"), send a focused single-claim prompt.
+- `mcp__codex__ask-codex` or `mcp__plugin_ask-llm_codex__ask-codex` — when the verification needs Codex's broader code-tracing (e.g., "does function X actually call function Y in the new path?"), send a focused single-claim prompt. Prefer any exact `ask-codex` leaf; if only unified `mcp__ask-llm__ask-llm` is exposed, call it with `provider: "codex"`, `reasoningEffort: "high"`, `sandbox: "read-only"`, and `preferred` unset. If the unified schema lacks those Codex options, stop and report that `@ask-llm/mcp` must be upgraded; do not omit the fields.
 
-When you call `mcp__codex__ask-codex` for verification, scope the prompt narrowly:
+When you call an exact `ask-codex` leaf or the fully pinned unified `ask-llm` equivalent for verification, scope the prompt narrowly:
 
 ```
 Verify this single claim against actual source: <claim>.

package/agents/sol-reviewer.md

@@ -29,19 +29,23 @@ You are a code review coordinator for a model-pinned OpenAI GPT-5.6 Sol review.
 
 1. Inspect `git diff` and `git diff --cached`. Read each affected file around the changed lines.
 2. Apply the nearest `CLAUDE.md` instructions and inspect any ADR explicitly cited by changed code.
-3. Call `mcp__codex__ask-codex` with:
+3. Call an available Ask LLM Codex transport with:
    - `model: "gpt-5.6-sol"`
    - `reasoningEffort: "high"`
+   - `sandbox: "read-only"`
    - `preferred` unset
    - a prompt containing the scoped conventions, relevant ADR summaries, and the diff
 
-   The tool name may be plugin-namespaced in some sessions (for example `mcp__plugin_ask-llm_codex__ask-codex`). Treat a tool as authoritative only when its server identity maps to an active `@ask-llm/codex-mcp` registration. If no authoritative `ask-codex` tool is available in this subagent context, pass the same prompt on stdin to the shipped fallback runner:
+   Transport ladder (do not skip rungs, and never strip an option to make a call succeed):
+   1. Prefer any exact `ask-codex` leaf whose server identity maps to an active `@ask-llm/codex-mcp` registration (`mcp__codex__ask-codex` or plugin-namespaced `mcp__plugin_ask-llm_codex__ask-codex`).
+   2. Otherwise call `mcp__ask-llm__ask-llm` (or another namespaced `__ask-llm` leaf whose server maps to `@ask-llm/mcp`) with `provider: "codex"` plus the same model, reasoningEffort, sandbox, preferred, and any `includeDirs`. Inspect the advertised input schema first. If it lacks `reasoningEffort`, `includeDirs`, `preferred`, or `sandbox`, stop: the installed `@ask-llm/mcp` is too old to honor Codex options. Upgrade with `npx -y @ask-llm/mcp@latest` or `npm install -g @ask-llm/mcp`; do not omit those fields.
+   3. If no authoritative MCP tool is available in this subagent context, pass the same prompt on stdin to the shipped fallback runner:
 
    ```bash
    node "${CLAUDE_PLUGIN_ROOT}/scripts/sol-review-transport.mjs" --fallback --plugin-dir "${CLAUDE_PLUGIN_ROOT}" --cli-path "$(command -v codex || true)"
    ```
 
-   Before executing Codex, the runner queries the active Claude MCP inventory again with the active plugin preserved; mirror any session-local `--mcp-config`, `--settings`, `--setting-sources`, and `--strict-mcp-config` flags on the runner command. This makes a parent `preferred` result followed by an absent or disconnected subagent tool a registered-but-unavailable state with the corresponding remediation. If the MCP call itself fails at the transport/service boundary, rerun the same fallback command with `--mcp-failed`; do not use that flag for a provider/model response. The runner then executes `codex exec -m gpt-5.6-sol -c model_reasoning_effort="high" -s read-only --ignore-user-config --ignore-rules --skip-git-repo-check`. The model pin, reasoning-effort override, read-only sandbox, and isolation flags are load-bearing; never drop or substitute them. On a quota or rate-limit failure only, the runner retries once with `${ASK_CODEX_FALLBACK_MODEL:-gpt-5.6-terra}` and identical flags, matching the MCP executor's configurable quota ladder. It writes the review result to stdout unchanged so the validated findings can be relayed without loss. If the `codex` CLI is also unavailable, stop and report that the Sol review could not run. Do not review on another transport, on any model outside the Sol-to-fallback ladder, or in another sandbox mode.
+   Before executing Codex, the runner queries the active Claude MCP inventory again with the active plugin preserved; mirror any session-local `--mcp-config`, `--settings`, `--setting-sources`, and `--strict-mcp-config` flags on the runner command. When the resolved tool is unified `ask-llm`, pass `--tool "<resolved tool name>" --tool-schema "<advertised input JSON schema>"` so an older schema is classified as `unsupported-schema` rather than being called. This makes a parent `preferred` or `unified` result followed by an absent or disconnected subagent tool a registered-but-unavailable state with the corresponding remediation. If the MCP call itself fails at the transport/service boundary, rerun the same fallback command with `--mcp-failed`; do not use that flag for a provider/model response. The runner then executes `codex exec -m gpt-5.6-sol -c model_reasoning_effort="high" -s read-only --ignore-user-config --ignore-rules --skip-git-repo-check`. The model pin, reasoning-effort override, read-only sandbox, and isolation flags are load-bearing; never drop or substitute them. On a quota or rate-limit failure only, the runner retries once with `${ASK_CODEX_FALLBACK_MODEL:-gpt-5.6-terra}` and identical flags, matching the MCP executor's configurable quota ladder. It writes the review result to stdout unchanged so the validated findings can be relayed without loss. If the `codex` CLI is also unavailable, stop and report that the Sol review could not run. Do not review on another transport, on any model outside the Sol-to-fallback ladder, or in another sandbox mode.
 4. Ask Sol for concrete correctness, security, data-loss, concurrency, resource-lifecycle, and compatibility failures with confidence scores and reproduction conditions.
 5. Read the reported source locations and trace each reproduction path. Drop style preferences, speculative improvements, pre-existing issues, linter/type-checker findings, and behavior documented as intentional.
 6. Report only validated findings with confidence of at least 80/100. Never invent findings to fill a report.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ask-llm/plugin",
-  "version": "0.16.3",
+  "version": "0.17.0",
   "description": "Ask LLM review, comparison, brainstorming, image, verification, and pairing workflows for Claude Code, Cursor Agent, and Pi",
   "type": "module",
   "main": "dist/index.js",
@@ -83,11 +83,11 @@
     ]
   },
   "dependencies": {
-    "@ask-llm/antigravity-mcp": "^0.7.5",
+    "@ask-llm/antigravity-mcp": "^0.7.6",
     "@ask-llm/codex-mcp": "^0.7.8",
     "@ask-llm/gemini-mcp": "^1.9.1",
     "@ask-llm/grok-mcp": "^0.1.5",
-    "@ask-llm/mcp": "^0.9.3",
+    "@ask-llm/mcp": "^0.10.0",
     "@ask-llm/ollama-mcp": "^0.6.2"
   },
   "peerDependencies": {

package/scripts/sol-review-transport.mjs

@@ -7,9 +7,18 @@ import { prepareCommandInvocation } from "./lib/process.mjs";
 
 export const ASK_CODEX_PACKAGE = "@ask-llm/codex-mcp";
 export const ASK_CODEX_TOOL = "ask-codex";
+export const ASK_LLM_PACKAGE = "@ask-llm/mcp";
+export const ASK_LLM_TOOL = "ask-llm";
+export const UNIFIED_CODEX_OPTION_KEYS = ["reasoningEffort", "includeDirs", "preferred", "sandbox"];
 export const SOL_MODEL = "gpt-5.6-sol";
 export const TERRA_MODEL = "gpt-5.6-terra";
 
+const MISSING_REGISTRATION_REMEDIATION =
+  "Run `claude mcp add --scope user ask-llm -- npx -y @ask-llm/mcp`, fully restart Claude Code, then verify with `/mcp`. Split Codex remains an advanced optimization: `claude mcp add --scope user codex -- npx -y @ask-llm/codex-mcp`.";
+const SERVICE_REMEDIATION = "Run `npx -y @ask-llm/mcp doctor`, inspect `/mcp`, then fully restart Claude Code.";
+const UPGRADE_UNIFIED_REMEDIATION =
+  "Upgrade `@ask-llm/mcp` with `npx -y @ask-llm/mcp@latest` or `npm install -g @ask-llm/mcp`, fully restart Claude Code, then verify with `/mcp`.";
+
 const scriptPath = fileURLToPath(import.meta.url);
 const quotaSignals = [
   "rate_limit_exceeded",
@@ -38,6 +47,29 @@ export function isAskCodexRegistration(server) {
   );
 }
 
+export function isAskLlmToolName(name) {
+  return name === ASK_LLM_TOOL || /^mcp__.+__ask-llm$/.test(name);
+}
+
+export function isAskLlmRegistration(server) {
+  if (!server || typeof server !== "object") return false;
+  const command = typeof server.command === "string" ? server.command : "";
+  const args = Array.isArray(server.args) ? server.args.filter((arg) => typeof arg === "string") : [];
+  const commandLine = typeof server.commandLine === "string" ? server.commandLine : "";
+  return (
+    /(?:^|[/\\])ask-llm-mcp(?:\.cmd|\.exe)?$/.test(command) ||
+    args.includes(ASK_LLM_PACKAGE) ||
+    /(?:^|\s)@ask-llm\/mcp(?:@[^\s]+)?(?:\s|$)/.test(commandLine) ||
+    /(?:^|[/\\])ask-llm-mcp(?:\.cmd|\.exe)?(?:\s|$)/.test(commandLine)
+  );
+}
+
+export function unifiedSchemaHonorsCodexOptions(schema) {
+  const properties = schema?.properties;
+  if (!properties || typeof properties !== "object") return false;
+  return UNIFIED_CODEX_OPTION_KEYS.every((key) => Object.hasOwn(properties, key));
+}
+
 export function parseClaudeMcpList(output) {
   const servers = {};
   for (const line of output.split(/\r?\n/)) {
@@ -77,8 +109,8 @@ export function readActiveMcpServers({
   return parseClaudeMcpList(result.stdout || "");
 }
 
-function expectedToolName(serverName) {
-  return `mcp__${serverName.replaceAll(":", "_")}__${ASK_CODEX_TOOL}`;
+function expectedToolName(serverName, tool = ASK_CODEX_TOOL) {
+  return `mcp__${serverName.replaceAll(":", "_")}__${tool}`;
 }
 
 function isAvailableMcpServer(server) {
@@ -86,12 +118,34 @@ function isAvailableMcpServer(server) {
   return !status || /^✔\s*Connected\b/i.test(status) || /^cached\b.*\bconnects on first use\b/i.test(status);
 }
 
+function withCliFallback({ state, reason, remediation, cliPath }) {
+  if (!cliPath) {
+    return {
+      state,
+      transport: null,
+      toolName: null,
+      diagnostic: `${reason} The explicit CLI fallback is also unavailable.`,
+      remediation: `${remediation} Install the fallback with \`npm install -g @openai/codex\` if needed.`,
+      fallbackDisclosure: null,
+    };
+  }
+  return {
+    state,
+    transport: "cli",
+    toolName: null,
+    diagnostic: reason,
+    remediation,
+    fallbackDisclosure: `Transport disclosure: ${reason} Running the review through the explicit \`codex exec\` CLI fallback; validated findings will be relayed unchanged.`,
+  };
+}
+
 export function classifySolReviewTransport({
   availableTools = [],
   mcpServers = {},
   cliPath = "",
   inventoryError = null,
   mcpFailed = false,
+  toolSchemas = {},
 }) {
   if (inventoryError) {
     const reason = `Ask LLM Codex MCP availability could not be determined because the active Claude MCP inventory could not be inspected: ${inventoryError}`;
@@ -116,28 +170,60 @@ export function classifySolReviewTransport({
     };
   }
 
-  const registrations = Object.entries(mcpServers).filter(([, server]) => isAskCodexRegistration(server));
-  const availableRegistrations = registrations.filter(([, server]) => isAvailableMcpServer(server));
-  const registeredToolNames = new Set(availableRegistrations.map(([name]) => expectedToolName(name)));
-  const toolName = availableTools.find((name) => isAskCodexToolName(name) && registeredToolNames.has(name));
-  if (toolName && !mcpFailed) {
+  const codexRegistrations = Object.entries(mcpServers).filter(([, server]) => isAskCodexRegistration(server));
+  const availableCodexRegistrations = codexRegistrations.filter(([, server]) => isAvailableMcpServer(server));
+  const registeredCodexToolNames = new Set(
+    availableCodexRegistrations.map(([name]) => expectedToolName(name, ASK_CODEX_TOOL)),
+  );
+  const askCodexToolName = availableTools.find(
+    (name) => isAskCodexToolName(name) && registeredCodexToolNames.has(name),
+  );
+  if (askCodexToolName && !mcpFailed) {
     return {
       state: "preferred",
       transport: "mcp",
-      toolName,
-      diagnostic: `Ask LLM Codex transport available as ${toolName}.`,
+      toolName: askCodexToolName,
+      diagnostic: `Ask LLM Codex transport available as ${askCodexToolName}.`,
+      remediation: null,
+      fallbackDisclosure: null,
+    };
+  }
+
+  const unifiedRegistrations = Object.entries(mcpServers).filter(([, server]) => isAskLlmRegistration(server));
+  const availableUnifiedRegistrations = unifiedRegistrations.filter(([, server]) => isAvailableMcpServer(server));
+  const registeredUnifiedToolNames = new Set(
+    availableUnifiedRegistrations.map(([name]) => expectedToolName(name, ASK_LLM_TOOL)),
+  );
+  const askLlmToolName = availableTools.find((name) => isAskLlmToolName(name) && registeredUnifiedToolNames.has(name));
+  if (askLlmToolName && !mcpFailed) {
+    const schema = toolSchemas[askLlmToolName];
+    if (!unifiedSchemaHonorsCodexOptions(schema)) {
+      const schemaMissing = !schema;
+      return withCliFallback({
+        state: "unsupported-schema",
+        reason: schemaMissing
+          ? "Ask LLM unified MCP is registered, but its `ask-llm` schema was not provided so Codex options (reasoningEffort, includeDirs, preferred, sandbox) cannot be verified. Pass `--tool-schema` with the advertised input JSON schema; never omit those fields to make the call succeed."
+          : "Ask LLM unified MCP is registered, but its `ask-llm` schema cannot honor Codex options (reasoningEffort, includeDirs, preferred, sandbox). Upgrade `@ask-llm/mcp`; never omit those fields to make the call succeed.",
+        remediation: UPGRADE_UNIFIED_REMEDIATION,
+        cliPath,
+      });
+    }
+    return {
+      state: "unified",
+      transport: "mcp",
+      toolName: askLlmToolName,
+      diagnostic: `Ask LLM unified transport available as ${askLlmToolName}. Call it with provider "codex" and pass reasoningEffort, includeDirs, preferred, and sandbox; do not strip unsupported fields.`,
       remediation: null,
       fallbackDisclosure: null,
     };
   }
 
-  const registered = registrations.length > 0;
+  const registered = codexRegistrations.length > 0 || unifiedRegistrations.length > 0;
   const state = registered || mcpFailed ? "unavailable" : "missing-registration";
-  const remediation =
-    registered || mcpFailed
-      ? "Run `npx -y @ask-llm/mcp doctor`, inspect `/mcp`, then fully restart Claude Code."
-      : "Run `claude mcp add --scope user codex -- npx -y @ask-llm/codex-mcp`, fully restart Claude Code, then verify with `/mcp`.";
-  const unavailableRegistration = registrations.find(([, server]) => !isAvailableMcpServer(server));
+  const remediation = registered || mcpFailed ? SERVICE_REMEDIATION : MISSING_REGISTRATION_REMEDIATION;
+  const unavailableRegistration =
+    codexRegistrations.find(([, server]) => !isAvailableMcpServer(server)) ||
+    unifiedRegistrations.find(([, server]) => !isAvailableMcpServer(server));
   const reason = mcpFailed
     ? "Ask LLM Codex MCP invocation failed in this session, so the preferred transport is unavailable."
     : unavailableRegistration
@@ -146,25 +232,7 @@ export function classifySolReviewTransport({
         ? "Ask LLM Codex MCP is registered, but its `ask-codex` tool is unavailable in this session."
         : "Ask LLM Codex MCP registration is missing from this Claude Code installation.";
 
-  if (!cliPath) {
-    return {
-      state,
-      transport: null,
-      toolName: null,
-      diagnostic: `${reason} The explicit CLI fallback is also unavailable.`,
-      remediation: `${remediation} Install the fallback with \`npm install -g @openai/codex\` if needed.`,
-      fallbackDisclosure: null,
-    };
-  }
-
-  return {
-    state,
-    transport: "cli",
-    toolName: null,
-    diagnostic: reason,
-    remediation,
-    fallbackDisclosure: `Transport disclosure: ${reason} Running the review through the explicit \`codex exec\` CLI fallback; validated findings will be relayed unchanged.`,
-  };
+  return withCliFallback({ state, reason, remediation, cliPath });
 }
 
 export function codexFallbackArgs(model) {
@@ -255,6 +323,7 @@ function parseArgs(args) {
     mcpList: null,
     fallback: false,
     mcpFailed: false,
+    toolSchema: null,
     claudeContextArgs: [],
   };
   const claudeContextValueFlags = new Set(["--plugin-dir", "--mcp-config", "--settings", "--setting-sources"]);
@@ -265,7 +334,14 @@ function parseArgs(args) {
     else if (arg === "--tool") parsed.tools.push(args[++index] ?? "");
     else if (arg === "--cli-path") parsed.cliPath = args[++index] ?? "";
     else if (arg === "--mcp-list") parsed.mcpList = args[++index] ?? "";
-    else if (arg === "--strict-mcp-config") parsed.claudeContextArgs.push(arg);
+    else if (arg === "--tool-schema") {
+      const raw = args[++index] ?? "";
+      try {
+        parsed.toolSchema = JSON.parse(raw);
+      } catch {
+        throw new Error("Invalid --tool-schema JSON");
+      }
+    } else if (arg === "--strict-mcp-config") parsed.claudeContextArgs.push(arg);
     else if (claudeContextValueFlags.has(arg)) {
       const value = args[++index];
       if (value === undefined) throw new Error(`Missing value for ${arg}`);
@@ -295,12 +371,17 @@ function readMcpServers(parsed) {
 async function main() {
   const parsed = parseArgs(process.argv.slice(2));
   const { mcpServers, inventoryError } = readMcpServers(parsed);
+  const toolSchemas = {};
+  if (parsed.toolSchema) {
+    for (const name of parsed.tools) toolSchemas[name] = parsed.toolSchema;
+  }
   const decision = classifySolReviewTransport({
     availableTools: parsed.tools,
     mcpServers,
     cliPath: parsed.cliPath,
     inventoryError,
     mcpFailed: parsed.mcpFailed,
+    toolSchemas,
   });
 
   if (parsed.fallback) {

package/skills/codex-image/SKILL.md

@@ -38,7 +38,7 @@ Codex's `image_generation` tool selects the image model server-side; as of 2026-
 
 - `codex-cli` >= 0.125.0 installed and authenticated
 - `image_generation` feature flag enabled (default: stable + true). Verify with `codex features list | grep image_generation`
-- The `ask-codex` MCP tool available (from `@ask-llm/codex-mcp` or the `@ask-llm/mcp` orchestrator)
+- The `ask-codex` MCP tool available (from `@ask-llm/codex-mcp`) or the unified `mcp__ask-llm__ask-llm` tool (from `@ask-llm/mcp`) whose schema includes `sandbox`
 
 ## Instructions
 
@@ -65,9 +65,9 @@ Example slug derivation:
 - "Generate an image of a dark terminal with two reviewers" → `dark-terminal-with-two-reviewers.png`
 - "Make me a cat picture" → `cat-picture.png`
 
-### Phase 3: Dispatch to ask-codex
+### Phase 3: Dispatch to Codex
 
-Call the `ask-codex` MCP tool (NOT raw `codex exec` — that bypasses ADR-044 quota fallback, ADR-042 stdin handling, and ADR-047 PATH resolution). Use this prompt template:
+Call an exact `ask-codex` leaf when exposed (NOT raw `codex exec` — that bypasses ADR-044 quota fallback, ADR-042 stdin handling, and ADR-047 PATH resolution). If only unified `mcp__ask-llm__ask-llm` is exposed, use that instead with `provider: "codex"`. If the unified schema lacks `sandbox`, stop and tell the user to upgrade `@ask-llm/mcp` (`npx -y @ask-llm/mcp@latest` or `npm install -g @ask-llm/mcp`); do not omit `sandbox` to make the call succeed. Use this prompt template:
 
 ```
 Use your image_generation tool to create the following image and save it as a PNG file.
@@ -80,7 +80,7 @@ Save the file to this absolute path: <path from Phase 2>
 After saving, confirm the absolute path of the created file and its byte size in your reply. If image_generation fails or the file cannot be written, explain what went wrong and do not invent a fake path.
 ```
 
-**Sandbox:** pass `sandbox: "workspace-write"` on this `ask-codex` call. `ask-codex` defaults to the read-only review sandbox (ADR-136), under which Codex cannot write the PNG to disk; image generation is the sanctioned exception that needs Codex to write the output file itself.
+**Sandbox:** pass `sandbox: "workspace-write"` on this `ask-codex` or fully pinned `ask-llm({ provider: "codex", ... })` call. Codex defaults to the read-only review sandbox (ADR-136), under which it cannot write the PNG to disk; image generation is the sanctioned exception that needs Codex to write the output file itself. The unified server will not silently strip `sandbox`; an older `@ask-llm/mcp` that cannot honor it must fail closed.
 
 **Default model:** let `ask-codex` use its default (`gpt-5.6-sol`). The image_generation tool is invoked by the model regardless of which Codex chat model is selected — model selection here is about the orchestrating agent, not the image model itself.
 

package/skills/codex-pair/SKILL.md

@@ -19,7 +19,7 @@ Pi requires project trust, this repository marker, and explicit user-owned allow
 
 Cursor discovers this `SKILL.md` through its supported Agent Skills surface; `/codex-pair` attaches it as an explicit command. Do **not** use Claude Code's `PostToolUse`, `Stop`, `SessionStart`, `SessionEnd`, `CLAUDE_PLUGIN_ROOT`, `AskUserQuestion`, or plugin tool namespaces. This adapter is an on-demand iterative pairing session, not a claim that Claude hooks were registered in Cursor.
 
-1. Read `../pairing-contract.md`. The Cursor plugin bundle registers only the unified `ask-llm` server; if the user separately installed `@ask-llm/codex-mcp`, prefer that deterministic `ask-codex` leaf. Resolve an exposed MCP tool whose exact leaf is `ask-codex`; do not assume its server prefix. When only the unified `ask-llm` leaf is registered, it may serve as the transport with `provider: "codex"` and every option (model, reasoning effort, include directories, session) pinned explicitly; its schema rejects unsupported combinations instead of stripping them and Codex runs read-only by default. Never make an unpinned generic call. If neither tool is exposed, stop with the recommended user-installed unified server:
+1. Read `../pairing-contract.md`. The Cursor plugin bundle registers only the unified `ask-llm` server; if the user separately installed `@ask-llm/codex-mcp`, prefer that deterministic `ask-codex` leaf. Resolve an exposed MCP tool whose exact leaf is `ask-codex`; do not assume its server prefix. When only the unified `ask-llm` leaf is registered, it may serve as the transport with `provider: "codex"` and every option (model, reasoning effort, include directories, sandbox, session) pinned explicitly; its schema rejects unsupported combinations instead of stripping them. Inspect the advertised schema before the first call: if `sandbox` or another required Codex option is missing, stop and upgrade `@ask-llm/mcp` rather than omitting the field. Never make an unpinned generic call. If neither tool is exposed, stop with the recommended user-installed unified server:
    ```json
    {"mcpServers":{"ask-llm":{"command":"npx","args":["-y","@ask-llm/mcp"]}}}
    ```
@@ -48,13 +48,14 @@ Cursor discovers this `SKILL.md` through its supported Agent Skills surface; `/c
          "model": "<required exact ID>",
          "reasoningEffort": "<required effort>",
          "includeDirs": ["<validated relative directory>"],
-         "sessionId": ""
+         "sessionId": "",
+         "sandbox": "read-only"
        }
      }
    ]
    ```
    The prompt assigns Codex the independent reviewer role and requests actionable severity/file/line evidence. Capture the returned structured `sessionId`/Thread ID and actual model. Relay feedback before changing code; verify every finding against source and label it accepted, rejected, or deferred.
-5. At meaningful checkpoints, call the same tool with the captured `sessionId`, same model/effort, and bounded delta. On `ask-codex`, keep `sandbox: "read-only"`; unified `ask-llm` has no sandbox input and is read-only by default, so do not send an unsupported sandbox field. Omit `includeDirs` on resumed calls because `codex exec resume` does not support them (every Codex transport — split `ask-codex`, unified `ask-llm`, and Pi — rejects that combination at the shared executor instead of dropping the directories); never silently strip them from the first call. If no session ID was returned, stop with a session diagnostic instead of pretending continuity.
+5. At meaningful checkpoints, call the same tool with the captured `sessionId`, same model/effort, and bounded delta. Keep `sandbox: "read-only"` on both `ask-codex` and unified `ask-llm`. If the unified schema lacks `sandbox`, stop and upgrade `@ask-llm/mcp` rather than omitting it. Omit `includeDirs` on resumed calls because `codex exec resume` does not support them (every Codex transport — split `ask-codex`, unified `ask-llm`, and Pi — rejects that combination at the shared executor instead of dropping the directories); never silently strip them from the first call. If no session ID was returned, stop with a session diagnostic instead of pretending continuity.
 6. A Cursor interrupt cancels the MCP request. Report `cancelled` and never retry another tool/model/provider. Preserve earlier feedback on later failure and report `failed (partial)`. On success report `completed` with host, provider, requested/actual model, effort, session reuse count, context/include directories, accepted/rejected/deferred actions, and any reported Codex quota fallback. Never conceal fallback or rewrite a model.
 
 <!-- HOST-ADAPTER:CLAUDE-CODE:START -->

package/skills/pairing-contract.md

@@ -20,7 +20,7 @@ Additional directories must be explicit relative workspace paths: no absolute pa
 
 ## Transport, options, and attribution
 
-Select one route before the first call and keep it immutable for the run. Resolve tools by their exact leaf capability (`ask-codex`, `ask-grok`, or `ask-cursor-agent`), not by assuming a Claude plugin namespace. The unified `ask-llm` tool is an acceptable transport only when the call pins provider, harness where applicable, exact model, reasoning effort, include directories, and session explicitly and its schema rejects unsupported combinations rather than stripping them; it is never an unpinned generic call and never a fallback for a failed split tool. A missing tool is a setup failure, never permission to use a generic call.
+Select one route before the first call and keep it immutable for the run. Resolve tools by their exact leaf capability (`ask-codex`, `ask-grok`, or `ask-cursor-agent`), not by assuming a Claude plugin namespace. The unified `ask-llm` tool is an acceptable transport only when the call pins provider, harness where applicable, exact model, reasoning effort, include directories, sandbox where the route supports it, and session explicitly and its schema rejects unsupported combinations rather than stripping them; it is never an unpinned generic call and never a fallback for a failed split tool. If the advertised schema lacks a required Codex option (`reasoningEffort`, `includeDirs`, `preferred`, `sandbox`), stop and upgrade `@ask-llm/mcp` rather than omitting the field. A missing tool is a setup failure, never permission to use a generic call.
 
 Every call and final report must keep these separate:
 

package/skills/sol-review/SKILL.md

@@ -33,13 +33,13 @@ Run a read-only, precision-first review explicitly pinned to GPT-5.6 Sol at high
 3. If the combined diff is empty, report that there are no changes to review.
 4. Read the root and file-scoped `CLAUDE.md` files plus any ADRs cited by changed code.
 5. Preflight the transport through the shipped executable contract:
-   - Search the current tool surface for the exact `ask-codex` leaf tool. The executable correlates its client-assigned server prefix with an active `@ask-llm/codex-mcp` registration; similarly named tools and tools from unrelated servers are not authoritative.
-   - Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/sol-review-transport.mjs" --plugin-dir "${CLAUDE_PLUGIN_ROOT}" --cli-path "$(command -v codex || true)"`, adding `--tool "<resolved tool name>"` only when the exact `ask-codex` tool resolved. Mirror any session-local `--mcp-config`, `--settings`, `--setting-sources`, and `--strict-mcp-config` flags so the nested inventory sees the same configuration as the active session.
-   - Preserve the returned `state`, `diagnostic`, `remediation`, and `fallbackDisclosure`. The executable reads `claude mcp list` with that session context: `missing-registration` means that active inventory has no supported registration; `unavailable` means it contains the registration but the current tool surface does not expose a usable tool, reports failed health, or the MCP invocation failed; `inventory-unavailable` means the active inventory could not be inspected, so registration and service health are unknown. Do not collapse those states into a generic "no MCP" message. If `transport` is null, stop and show the executable remediation instead of launching the agent.
+   - Search the current tool surface for an exact `ask-codex` leaf first, then an `ask-llm` leaf. The executable correlates each client-assigned server prefix with an active `@ask-llm/codex-mcp` or `@ask-llm/mcp` registration; similarly named tools and tools from unrelated servers are not authoritative.
+   - Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/sol-review-transport.mjs" --plugin-dir "${CLAUDE_PLUGIN_ROOT}" --cli-path "$(command -v codex || true)"`, adding `--tool "<resolved tool name>"` when an exact `ask-codex` or `ask-llm` tool resolved. For unified `ask-llm`, also pass `--tool-schema "<advertised input JSON schema>"` so a missing `reasoningEffort`/`includeDirs`/`preferred`/`sandbox` property is `unsupported-schema`, not a silent strip. Mirror any session-local `--mcp-config`, `--settings`, `--setting-sources`, and `--strict-mcp-config` flags so the nested inventory sees the same configuration as the active session.
+   - Preserve the returned `state`, `diagnostic`, `remediation`, and `fallbackDisclosure`. The executable reads `claude mcp list` with that session context: `preferred` is a usable `ask-codex` leaf; `unified` is a usable `mcp__ask-llm__ask-llm` (or namespaced) leaf whose advertised schema honors Codex options and that must be called with `provider: "codex"` and the complete Codex option set; `missing-registration` means that active inventory has no supported registration; `unavailable` means it contains the registration but the current tool surface does not expose a usable tool, reports failed health, or the MCP invocation failed; `unsupported-schema` means unified MCP is present but its schema was not supplied or cannot honor Codex options — pass `--tool-schema` or upgrade `@ask-llm/mcp` rather than omitting fields; `inventory-unavailable` means the active inventory could not be inspected, so registration and service health are unknown. Do not collapse those states into a generic "no MCP" message. If `transport` is null, stop and show the executable remediation instead of launching the agent.
    - Parent availability remains advisory because subagents do not always inherit the session's MCP servers. The reviewer's fallback runner re-reads the active inventory and reclassifies the absent subagent tool before executing the CLI fallback.
 6. Launch the `sol-reviewer` agent with the diff and a compact context brief containing the changed files, applicable conventions, referenced ADRs, the user's requested review focus, and the complete preflight result.
 7. Return the agent's validated findings without adding unverified issues.
 
-The reviewer must call `ask-codex` with `model: "gpt-5.6-sol"` and `reasoningEffort: "high"`, or use the shipped CLI fallback runner when no usable `ask-codex` MCP tool is available or its invocation fails at the transport/service boundary. That runner executes the sanctioned `codex exec -m gpt-5.6-sol -c model_reasoning_effort="high" -s read-only --ignore-user-config --ignore-rules --skip-git-repo-check` contract and relays its result unchanged. This explicit pin distinguishes `/sol-review` from `/codex-review`, which follows the configured Codex default. Both fallback kinds must be disclosed in the report: a Terra quota fallback means the requested Sol review did not complete on Sol, and a CLI transport fallback must report missing registration, registered-service unavailability, or an unreadable inventory without claiming a state that could not be determined.
+The reviewer must call `ask-codex` with `model: "gpt-5.6-sol"`, `reasoningEffort: "high"`, and `sandbox: "read-only"`, or the unified `ask-llm` equivalent with `provider: "codex"` and those same fields, or use the shipped CLI fallback runner when no usable MCP tool is available, its schema cannot honor those options, or its invocation fails at the transport/service boundary. That runner executes the sanctioned `codex exec -m gpt-5.6-sol -c model_reasoning_effort="high" -s read-only --ignore-user-config --ignore-rules --skip-git-repo-check` contract and relays its result unchanged. This explicit pin distinguishes `/sol-review` from `/codex-review`, which follows the configured Codex default. Both fallback kinds must be disclosed in the report: a Terra quota fallback means the requested Sol review did not complete on Sol, and a CLI transport fallback must report missing registration, registered-service unavailability, an unsupported unified schema, or an unreadable inventory without claiming a state that could not be determined.
 
 <!-- HOST-ADAPTER:CLAUDE-CODE:END -->