How the Codex Plugin Validates Native Review Requests and Handles Unsupported Targets

The Codex plugin validates native review requests by enforcing empty focus text, translating abstract targets into concrete native formats via buildNativeReviewTarget, and throwing descriptive errors for unsupported configurations, directing users to /codex:adversarial-review instead.

When invoking the /codex:review command in the openai/codex-plugin-cc repository, the plugin executes a strict validation routine to ensure compatibility with the built-in reviewer. Implemented in plugins/codex/scripts/codex-companion.mjs, this validation pipeline prevents malformed requests and clearly distinguishes between native review capabilities and adversarial review features.

The Three-Step Validation Pipeline

The validateNativeReviewRequest function (lines 71-84) implements a concise three-step validation routine before delegating work to the built-in reviewer.

Enforcing Empty Focus Text

Native reviews do not support custom focus instructions. The function immediately throws an error if focusText.trim() returns a non-empty string, preventing users from attempting to scope the review to specific concerns.

// Lines 71-78 in codex-companion.mjs
if (focusText.trim()) {
  throw new Error(
    "`/codex:review` now maps directly to the built‑in reviewer and does not support custom focus text. " +
    "Retry with `/codex:adversarial-review ${focusText.trim()}` for focused review instructions."
  );
}

Translating Targets with buildNativeReviewTarget

The helper function buildNativeReviewTarget (lines 59-68) maps abstract target objects to concrete native review formats. According to the source code, it supports exactly two modes:

• working-tree: Maps to {type: "uncommittedChanges"}
• branch: Maps to {type: "baseBranch", branch: target.baseRef}

// Lines 59-68 in codex-companion.mjs
function buildNativeReviewTarget(target) {
  if (target.mode === "working-tree") {
    return { type: "uncommittedChanges" };
  }
  if (target.mode === "branch") {
    return { type: "baseBranch", branch: target.baseRef };
  }
  return null; // unsupported mode
}

Rejecting Unsupported Modes

If buildNativeReviewTarget returns null, the validation function throws an error indicating the target is not supported. This prevents attempts to review pull requests, custom diffs, or other non-standard targets through the native pipeline.

// Lines 79-84 in codex-companion.mjs
const nativeTarget = buildNativeReviewTarget(target);
if (!nativeTarget) {
  throw new Error(
    "This `/codex:review` target is not supported by the built‑in reviewer. " +
    "Retry with `/codex:adversarial-review` for custom targeting."
  );
}

Integration with Command Execution

The executeReviewRun function orchestrates the validation before delegating to the native reviewer. After successful validation, the concrete native target passes to runAppServerReview along with the model configuration and progress callback.

// From executeReviewRun (around lines 68-70)
if (reviewName === "Review") {
  const reviewTarget = validateNativeReviewRequest(target, focusText);
  const result = await runAppServerReview(request.cwd, {
    target: reviewTarget,
    model: request.model,
    onProgress: request.onProgress,
  });
  // ...
}

Error Handling Examples

When validation fails, the plugin provides actionable error messages that distinguish between focus text violations and unsupported target types.

Focus Text Violation

Request:

{
  "target": { "mode": "branch", "baseRef": "main" },
  "focusText": "Check the security of the login flow"
}

Error response:

/codex:review now maps directly to the built‑in reviewer and does not support custom focus text.
Retry with /codex:adversarial-review Check the security of the login flow for focused review instructions.

Unsupported Target

Request:

{
  "target": { "mode": "pull-request", "prNumber": 42 },
  "focusText": ""
}

Error response:

This `/codex:review` target is not supported by the built‑in reviewer.
Retry with `/codex:adversarial-review` for custom targeting.

Summary

• Validation location: plugins/codex/scripts/codex-companion.mjs, lines 71-84
• Focus text restriction: Native reviews require empty focus text; custom instructions require /codex:adversarial-review
• Supported targets: Only working-tree (uncommitted changes) and branch (base branch comparison) modes are accepted
• Error strategy: Unsupported targets trigger descriptive errors that redirect users to the adversarial review command
• Target translation: The buildNativeReviewTarget helper (lines 59-68) performs the abstraction mapping

Frequently Asked Questions

What target types does the native Codex reviewer support?

The native reviewer supports exactly two target types: uncommitted changes in the working tree ({type: "uncommittedChanges"}) and branch comparisons against a base branch ({type: "baseBranch", branch: ...}). These map to the working-tree and branch modes respectively in the abstract target specification, as implemented in buildNativeReviewTarget.

Why can't I use focus text with /codex:review?

The /codex:review command maps directly to the built-in reviewer, which analyzes the complete diff without applying custom focus filters. If you need to review specific aspects like security concerns or particular functions, you must use /codex:adversarial-review with your focus text, as that command employs a different review strategy capable of handling targeted instructions.

What happens if I try to review an unsupported target?

The plugin throws an error stating the target is not supported by the built-in reviewer and suggests retrying with /codex:adversarial-review. This occurs when buildNativeReviewTarget returns null for modes other than working-tree or branch, such as pull request reviews or custom diff specifications.

Where is the validation logic located in the codebase?

The core validation function validateNativeReviewRequest and its helper buildNativeReviewTarget are implemented in plugins/codex/scripts/codex-companion.mjs at lines 71-84 and 59-68 respectively. The orchestration occurs in executeReviewRun within the same file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}