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

> Learn how the Codex plugin validates native review requests by enforcing empty focus text and translating targets. Discover how it handles unsupported configurations with clear error messages.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-07-11

---

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

```typescript
// 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}`

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

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

```typescript
// 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:

```json
{
  "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:

```json
{
  "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.