How the Codex Plugin Validates Native Review Requests

The Codex plugin validates native review requests by ensuring no custom focus text is provided, translating the abstract target into a supported native format, and rejecting unsupported target modes before delegating to the built-in reviewer.

When you trigger the /codex:review command in the openai/codex-plugin-cc repository, the plugin executes a strict validation routine to ensure the request conforms to the built-in reviewer's capabilities. This validation process, implemented in plugins/codex/scripts/codex-companion.mjs, prevents unsupported configurations and guides users toward the appropriate commands for custom review scenarios. Understanding how the Codex plugin validates native review requests helps developers debug integration issues and leverage the correct review workflows.

The Three-Step Validation Process

The validateNativeReviewRequest function performs a concise, three-step validation routine before any review logic executes. Each step ensures the request matches the narrow contract expected by the native reviewer.

Step 1: Enforcing Empty Focus Text

The function first checks that focus text is empty. Native reviews do not support custom focus instructions, so the plugin throws an error if focusText.trim() returns a non-empty string.

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."
  );
}

This check ensures users who want focused reviews use the /codex:adversarial-review command instead.

Step 2: Mapping to Native Target Types

Next, the function calls buildNativeReviewTarget(target) to translate the abstract target object into a concrete native format. This helper maps the input to one of two supported shapes:

• {type: "uncommittedChanges"} for working-tree reviews
• {type: "baseBranch", branch: ...} for branch comparisons

const nativeTarget = buildNativeReviewTarget(target);

Step 3: Rejecting Unsupported Modes

Finally, the validator ensures the target translation succeeded. If buildNativeReviewTarget returns null, the plugin throws an error indicating the target mode is unsupported.

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."
  );
}

This prevents attempts to review unsupported modes such as pull requests or custom diffs.

Source Code Implementation

The validation logic resides in plugins/codex/scripts/codex-companion.mjs at lines 71-84. The validateNativeReviewRequest function orchestrates the checks, while the helper buildNativeReviewTarget (lines 59-68) handles the target mapping.

The Validation Function

function validateNativeReviewRequest(target, focusText) {
  // 1️⃣ Disallow custom focus text
  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."
    );
  }

  // 2️⃣ Translate the abstract target into a concrete native target
  const nativeTarget = buildNativeReviewTarget(target);

  // 3️⃣ Verify the translation succeeded
  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."
    );
  }

  // Passed validation → return the concrete native target
  return nativeTarget;
}

The Target Builder Helper

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
}

Error Handling and User Recovery

When validation fails, the plugin provides specific error messages directing users to the correct command. Here are the two primary failure scenarios:

Invalid: Focus text provided

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

Result:

/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.

Invalid: Unsupported target mode

If the target mode is neither working-tree nor branch, the plugin returns:

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 validation occurs within executeReviewRun (lines 68-70 of codex-companion.mjs) before invoking the actual review logic. This ensures only sanitized inputs reach the built-in reviewer.

if (reviewName === "Review") {
  const reviewTarget = validateNativeReviewRequest(target, focusText);
  const result = await runAppServerReview(request.cwd, {
    target: reviewTarget,
    model: request.model,
    onProgress: request.onProgress,
  });
  // …
}

A valid request for a branch comparison produces the native target { type: "baseBranch", branch: "main" }, while a working-tree request produces { type: "uncommittedChanges" }.

Summary

• Focus text prohibition: The Codex plugin rejects any native review request containing custom focus instructions, redirecting users to /codex:adversarial-review.
• Target translation: The buildNativeReviewTarget helper converts abstract targets into concrete uncommittedChanges or baseBranch objects.
• Unsupported mode rejection: Any target mode outside working-tree or branch triggers a validation error.
• Source location: All validation logic resides in plugins/codex/scripts/codex-companion.mjs within the openai/codex-plugin-cc repository.

Frequently Asked Questions

What triggers the validation of a native review request?

Validation triggers when a user invokes the /codex:review command. The executeReviewRun function calls validateNativeReviewRequest immediately after determining the review type, ensuring all inputs meet the built-in reviewer's requirements before processing begins.

Why does the Codex plugin reject focus text for native reviews?

The built-in reviewer operates on a fixed scope and does not accept custom instructions. By rejecting focus text, the plugin enforces a clear separation: /codex:review handles standard, scope-defined reviews, while /codex:adversarial-review accepts custom focus instructions for targeted analysis.

Which target modes are supported for native review validation?

The validator supports exactly two modes: working-tree (mapped to {type: "uncommittedChanges"}) and branch (mapped to {type: "baseBranch", branch: ...}). All other modes return null from buildNativeReviewTarget and trigger a validation error.

What happens if an unsupported target mode is submitted?

The plugin throws an error stating the target is not supported by the built-in reviewer and suggests using /codex:adversarial-review for custom targeting. This prevents the system from attempting to process review types that the native reviewer cannot handle, such as pull requests or arbitrary diff specifications.

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