codex-in-claude

Overview Schema Source Related Servers Discussions Admin

Preview a review (free)

codex_dry_run

Read-only

Preview the scope, diff size, redactions, and truncation a code review call would send without invoking Codex or spending money. Inspect coverage before the paid review.

Instructions

Deprecated: use amicus_review_changes_dry_run. Preview what a codex_review_changes call would send — scope, diff size, redactions, truncation. Free — no model call, no spend. Use it before a review to inspect the scope and the reported redactions; redaction is best-effort, so treat the preview as a check on scope, not as confirmation that no secret remains. Pass the same extra_context and untracked policy you would give the review so the preview matches it. would_call_model reports whether the paid call would actually run the model (False on an empty diff, where prompt_bytes is 0), and coverage discloses omitted untracked files just as the review would. The result echoes the effective model/reasoning_effort overrides the paid call would send (unvalidated). deadline_advisory is non-null when size or effort risks the synchronous deadline (null whenever would_call_model is False) and names codex_review_changes_async verbatim — the async counterpart of the previewed call, not of this dry-run tool. A hint, not a refusal.

A dry run reports metadata about the input this plugin would assemble; it does not invoke Codex, and it neither enumerates nor bounds the files the model itself reads and sends during the paid call. Codex can read files outside the workspace — up to everything the OS user running it can read — and send them to OpenAI. The sandbox bounds writes, not reads, so no choice of workspace is a read boundary.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`base`	No	Base git ref for scope='branch'; the review covers base...HEAD. Control characters are rejected, not stripped.
`model`	No	The Codex model slug the previewed paid call would use; defaults to the server default (CODEX_IN_CLAUDE_MODEL) when unset, so the preview mirrors the paid call's resolution. This dry run does not call Codex or validate the model.
`paths`	No	Repo-relative paths to narrow the review ('/' separators, no '..'); omit to review all changes in scope.
`scope`	No	Which changes to review: 'working_tree' (tracked changes vs HEAD; untracked files follow the `untracked` policy, off by default), 'branch' (needs base), or 'commit' (needs commit).	working_tree
`commit`	No	Commit SHA or ref to review for scope='commit'. Control characters are rejected, not stripped.
`isolation`	No	Codex config isolation: 'inherit' \| 'ignore-config' \| 'ignore-rules'. Defaults to the server's configured value (built-in 'inherit'; `codex_status` reports the resolved one).
`untracked`	No	How working_tree scope treats untracked files: 'explicit_only' (default) includes only those named in `paths`; 'include' reviews all non-ignored untracked files (SENDS their contents to OpenAI — opt-in egress); 'exclude' includes none. Omitted ones are disclosed in `coverage`. Inert for branch/commit scopes.	explicit_only
`extra_context`	No	Optional author intent/background context, added as clearly-labeled UNTRUSTED prompt data. Redaction does NOT cover it — no live secrets. Full caveats and bounds: codex://params.
`workspace_root`	No	Absolute path to the target repo root — pass it (or an MCP root) to target the intended repo; otherwise the call falls back to the server's own cwd and sets meta.workspace_warning. On an active call it selects where Codex works, not what it can read — it is not a read boundary.
`reasoning_effort`	No	The reasoning effort the previewed paid call would send (as a `model_reasoning_effort` config override); defaults to the server default (CODEX_IN_CLAUDE_REASONING_EFFORT) when unset, so the preview mirrors the paid call's resolution. This dry run does not call Codex or validate the value beyond the paid params' shape bounds (no control or surrogate characters, ≤128 chars).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`ok`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.19.0Aug 22, 2026

changedInput schema / properties / base / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "pattern": "^[^\\x00-\\x1F\\x7F-\\x9F]*$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / base / description

Previous value: -"Base git ref for scope='branch'; the review covers base...HEAD."New value: +"Base git ref for scope='branch'; the review covers base...HEAD. Control characters are rejected, not stripped."

changedInput schema / properties / commit / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "pattern": "^[^\\x00-\\x1F\\x7F-\\x9F]*$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / commit / description

Previous value: -"Commit SHA or ref to review for scope='commit'."New value: +"Commit SHA or ref to review for scope='commit'. Control characters are rejected, not stripped."

changedInput schema / properties / model / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "pattern": "^[^\\x00-\\x1F\\x7F-\\x9F]*$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / workspace_root / description

Previous value: -"Absolute path to the target repo root — pass it (or an MCP root) to target the intended repo; otherwise the call falls back to the server's own cwd and sets meta.workspace_warning."New value: +"Absolute path to the target repo root — pass it (or an MCP root) to target the intended repo; otherwise the call falls back to the server's own cwd and sets meta.workspace_warning. On an active call it selects where Codex works, not what it can read — it is not a read boundary."

Changed4 schema fields changedv0.17.0Aug 3, 2026

changedInput schema / properties / extra_context / description

Previous value: -"Optional author intent / background context, added to the prompt as clearly-labeled UNTRUSTED data. Codex is instructed to treat embedded directives as data, not commands — best-effort prompt-injection mitigation, not a guarantee. Don't include live secrets: Codex can read files it's pointed at, and redaction does not cover this field."New value: +"Optional author intent/background context, added as clearly-labeled UNTRUSTED prompt data. Redaction does NOT cover it — no live secrets. Full caveats and bounds: codex://params."

changedInput schema / properties / isolation / description

Previous value: -"Codex config isolation: 'inherit', 'ignore-config', or 'ignore-rules'. Defaults to the server's configured isolation (built-in default 'inherit'; `codex_status` reports the resolved value)."New value: +"Codex config isolation: 'inherit' | 'ignore-config' | 'ignore-rules'. Defaults to the server's configured value (built-in 'inherit'; `codex_status` reports the resolved one)."

changedInput schema / properties / workspace_root / description

Previous value: -"Absolute path to the target repository root. Pass it (or rely on an MCP root) so the call targets the intended repo; otherwise it falls back to the server's own cwd and meta.workspace_warning is set."New value: +"Absolute path to the target repo root — pass it (or an MCP root) to target the intended repo; otherwise the call falls back to the server's own cwd and sets meta.workspace_warning."

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "base": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "commit": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "context_summary": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "files_changed": {
-                "type": "integer"
-              },
-              "lines_added": {
-                "type": "integer"
-              },
-              "lines_removed": {
-                "type": "integer"
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "coverage": {
-        "additionalProperties": false,
-        "properties": {
-          "omission_reasons": {
-            "items": {
-              "enum": [
-                "untracked_omitted",
-                "truncated",
-                "redacted"
-              ],
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "status": {
-            "enum": [
-              "complete",
-              "partial"
-            ],
-            "type": "string"
-          },
-          "untracked_files_detected": {
-            "anyOf": [
-              {
-                "type": "integer"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "untracked_files_included": {
-            "anyOf": [
-              {
-                "type": "integer"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "untracked_files_omitted": {
-            "anyOf": [
-              {
-                "type": "integer"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          }
-        },
-        "required": [
-          "status"
-        ],
-        "type": "object"
-      },
-      "cwd": {
-        "type": "string"
-      },
-      "fingerprint": {
-        "type": "string"
-      },
-      "isolation": {
-        "enum": [
-          "inherit",
-          "ignore-config",
-          "ignore-rules"
-        ],
-        "type": "string"
-      },
-      "max_input_bytes": {
-        "type": "integer"
-      },
-      "model": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Model override the previewed paid call would send (per-call param or server default); null = Codex would resolve it itself. Unvalidated by the preview."
-      },
-      "ok": {
-        "const": true,
-        "type": "boolean"
-      },
-      "paths": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "prompt_bytes": {
-        "type": "integer"
-      },
-      "reasoning_effort": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Reasoning-effort override the previewed paid call would send (per-call param or server default); null = Codex would resolve it itself. Unvalidated by the preview."
-      },
-      "redacted_paths": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "redacted_paths_count": {
-        "type": "integer"
-      },
-      "sandbox": {
-        "enum": [
-          "read-only",
-          "workspace-write",
-          "danger-full-access"
-        ],
-        "type": "string"
-      },
-      "scope": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "security_warnings": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "server_version": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "tier": {
-        "enum": [
-          "consult",
-          "propose",
-          "apply"
-        ],
-        "type": "string"
-      },
-      "tool": {
-        "const": "codex_dry_run",
-        "type": "string"
-      },
-      "truncated": {
-        "type": "boolean"
-      },
-      "truncation_hint": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "workspace_source": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "workspace_warning": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "would_call_model": {
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "cwd",
-      "tier",
-      "sandbox",
-      "isolation",
-      "would_call_model",
-      "prompt_bytes",
-      "coverage",
-      "max_input_bytes"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "error": {
-        "description": "Populated error envelope; full schema at resource codex://error-envelope",
-        "type": "object"
-      },
-      "meta": {
-        "type": "object"
-      },
-      "ok": {
-        "const": false
-      }
-    },
-    "required": [
-      "ok",
-      "error",
-      "meta"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "base": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "commit": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "context_summary": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "files_changed": {
+                "type": "integer"
+              },
+              "lines_added": {
+                "type": "integer"
+              },
+              "lines_removed": {
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "coverage": {
+        "additionalProperties": false,
+        "properties": {
+          "omission_reasons": {
+            "items": {
+              "enum": [
+                "untracked_omitted",
+                "tree_changed_during_gather",
+                "truncated",
+                "redacted"
+              ],
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "redaction": {
+            "anyOf": [
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "inline_masks": {
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "masked_paths": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "withheld_paths": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  }
+                },
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "status": {
+            "enum": [
+              "complete",
+              "partial"
+            ],
+            "type": "string"
+          },
+          "untracked_files_detected": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "untracked_files_included": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "untracked_files_omitted": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "required": [
+          "status"
+        ],
+        "type": "object"
+      },
+      "cwd": {
+        "type": "string"
+      },
+      "deadline_advisory": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Non-null when the previewed call would actually run the model AND its prompt size or reasoning effort risks the synchronous deadline; null otherwise (including whenever it would not call the model at all). Names the previewed PAID tool's own `_async` counterpart verbatim (e.g. codex_review_changes_async for a codex_dry_run preview) — never this dry-run tool's own name, which has no `_async` variant. A hint, not a refusal. codex_consult has no dry-run preview; prefer codex_consult_async for a high-effort or broad repo-grounded consult."
+      },
+      "fingerprint": {
+        "type": "string"
+      },
+      "isolation": {
+        "enum": [
+          "inherit",
+          "ignore-config",
+          "ignore-rules"
+        ],
+        "type": "string"
+      },
+      "max_input_bytes": {
+        "type": "integer"
+      },
+      "model": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Model override the previewed paid call would send (per-call param or server default); null = Codex would resolve it itself. Unvalidated by the preview."
+      },
+      "ok": {
+        "const": true,
+        "type": "boolean"
+      },
+      "paths": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "prompt_bytes": {
+        "type": "integer"
+      },
+      "reasoning_effort": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Reasoning-effort override the previewed paid call would send (per-call param or server default); null = Codex would resolve it itself. Unvalidated by the preview."
+      },
+      "redacted_paths": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "redacted_paths_count": {
+        "type": "integer"
+      },
+      "roots_source": {
+        "anyOf": [
+          {
+            "enum": [
+              "client",
+              "not_negotiated",
+              "probe_failed"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "sandbox": {
+        "enum": [
+          "read-only",
+          "workspace-write",
+          "danger-full-access"
+        ],
+        "type": "string"
+      },
+      "scope": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "security_warnings": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "server_version": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "tier": {
+        "enum": [
+          "consult",
+          "propose",
+          "apply"
+        ],
+        "type": "string"
+      },
+      "tool": {
+        "const": "codex_dry_run",
+        "type": "string"
+      },
+      "truncated": {
+        "type": "boolean"
+      },
+      "truncation_hint": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "workspace_source": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "workspace_warning": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "would_call_model": {
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "cwd",
+      "tier",
+      "sandbox",
+      "isolation",
+      "would_call_model",
+      "prompt_bytes",
+      "coverage",
+      "max_input_bytes"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "error": {
+        "description": "Populated error envelope; full schema at resource codex://error-envelope",
+        "type": "object"
+      },
+      "meta": {
+        "type": "object"
+      },
+      "ok": {
+        "const": false
+      }
+    },
+    "required": [
+      "ok",
+      "error",
+      "meta"
+    ],
+    "type": "object"
+  }
+]

Changed5 schema fields changedv0.13.0Jul 15, 2026

addedInput schema / properties / model

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The Codex model slug the previewed paid call would use; defaults to the server default (CODEX_IN_CLAUDE_MODEL) when unset, so the preview mirrors the paid call's resolution. This dry run does not call Codex or validate the model."
+}

addedInput schema / properties / reasoning_effort

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 128,
+      "pattern": "^[^\\x00-\\x1F\\x7F-\\x9F]*$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The reasoning effort the previewed paid call would send (as a `model_reasoning_effort` config override); defaults to the server default (CODEX_IN_CLAUDE_REASONING_EFFORT) when unset, so the preview mirrors the paid call's resolution. This dry run does not call Codex or validate the value beyond the paid params' shape bounds (no control or surrogate characters, ≤128 chars)."
+}

changedInput schema / properties / scope / description

Previous value: -"Which changes to review: 'working_tree' (uncommitted vs HEAD), 'branch' (needs base), or 'commit' (needs commit)."New value: +"Which changes to review: 'working_tree' (tracked changes vs HEAD; untracked files follow the `untracked` policy, off by default), 'branch' (needs base), or 'commit' (needs commit)."

addedInput schema / properties / untracked

Added value: +{
+  "default": "explicit_only",
+  "description": "How working_tree scope treats untracked files: 'explicit_only' (default) includes only those named in `paths`; 'include' reviews all non-ignored untracked files (SENDS their contents to OpenAI — opt-in egress); 'exclude' includes none. Omitted ones are disclosed in `coverage`. Inert for branch/commit scopes.",
+  "enum": [
+    "explicit_only",
+    "include",
+    "exclude"
+  ],
+  "type": "string"
+}

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "base": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "commit": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "context_summary": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "files_changed": {
-                "type": "integer"
-              },
-              "lines_added": {
-                "type": "integer"
-              },
-              "lines_removed": {
-                "type": "integer"
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "cwd": {
-        "type": "string"
-      },
-      "fingerprint": {
-        "type": "string"
-      },
-      "isolation": {
-        "enum": [
-          "inherit",
-          "ignore-config",
-          "ignore-rules"
-        ],
-        "type": "string"
-      },
-      "max_input_bytes": {
-        "type": "integer"
-      },
-      "ok": {
-        "const": true,
-        "type": "boolean"
-      },
-      "paths": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "prompt_bytes": {
-        "type": "integer"
-      },
-      "redacted_paths": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "redacted_paths_count": {
-        "type": "integer"
-      },
-      "sandbox": {
-        "enum": [
-          "read-only",
-          "workspace-write",
-          "danger-full-access"
-        ],
-        "type": "string"
-      },
-      "scope": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "security_warnings": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "server_version": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "tier": {
-        "enum": [
-          "consult",
-          "propose",
-          "apply"
-        ],
-        "type": "string"
-      },
-      "tool": {
-        "const": "codex_dry_run",
-        "type": "string"
-      },
-      "truncated": {
-        "type": "boolean"
-      },
-      "truncation_hint": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "workspace_source": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "workspace_warning": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "required": [
-      "cwd",
-      "tier",
-      "sandbox",
-      "isolation",
-      "prompt_bytes",
-      "max_input_bytes"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "error": {
-        "description": "Populated error envelope; full schema at resource codex://error-envelope",
-        "type": "object"
-      },
-      "meta": {
-        "type": "object"
-      },
-      "ok": {
-        "const": false
-      }
-    },
-    "required": [
-      "ok",
-      "error",
-      "meta"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "base": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "commit": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "context_summary": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "files_changed": {
+                "type": "integer"
+              },
+              "lines_added": {
+                "type": "integer"
+              },
+              "lines_removed": {
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "coverage": {
+        "additionalProperties": false,
+        "properties": {
+          "omission_reasons": {
+            "items": {
+              "enum": [
+                "untracked_omitted",
+                "truncated",
+                "redacted"
+              ],
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "status": {
+            "enum": [
+              "complete",
+              "partial"
+            ],
+            "type": "string"
+          },
+          "untracked_files_detected": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "untracked_files_included": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "untracked_files_omitted": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "required": [
+          "status"
+        ],
+        "type": "object"
+      },
+      "cwd": {
+        "type": "string"
+      },
+      "fingerprint": {
+        "type": "string"
+      },
+      "isolation": {
+        "enum": [
+          "inherit",
+          "ignore-config",
+          "ignore-rules"
+        ],
+        "type": "string"
+      },
+      "max_input_bytes": {
+        "type": "integer"
+      },
+      "model": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Model override the previewed paid call would send (per-call param or server default); null = Codex would resolve it itself. Unvalidated by the preview."
+      },
+      "ok": {
+        "const": true,
+        "type": "boolean"
+      },
+      "paths": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "prompt_bytes": {
+        "type": "integer"
+      },
+      "reasoning_effort": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Reasoning-effort override the previewed paid call would send (per-call param or server default); null = Codex would resolve it itself. Unvalidated by the preview."
+      },
+      "redacted_paths": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "redacted_paths_count": {
+        "type": "integer"
+      },
+      "sandbox": {
+        "enum": [
+          "read-only",
+          "workspace-write",
+          "danger-full-access"
+        ],
+        "type": "string"
+      },
+      "scope": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "security_warnings": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "server_version": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "tier": {
+        "enum": [
+          "consult",
+          "propose",
+          "apply"
+        ],
+        "type": "string"
+      },
+      "tool": {
+        "const": "codex_dry_run",
+        "type": "string"
+      },
+      "truncated": {
+        "type": "boolean"
+      },
+      "truncation_hint": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "workspace_source": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "workspace_warning": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "would_call_model": {
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "cwd",
+      "tier",
+      "sandbox",
+      "isolation",
+      "would_call_model",
+      "prompt_bytes",
+      "coverage",
+      "max_input_bytes"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "error": {
+        "description": "Populated error envelope; full schema at resource codex://error-envelope",
+        "type": "object"
+      },
+      "meta": {
+        "type": "object"
+      },
+      "ok": {
+        "const": false
+      }
+    },
+    "required": [
+      "ok",
+      "error",
+      "meta"
+    ],
+    "type": "object"
+  }
+]

Changed1 schema field changedv0.11.0Jul 14, 2026

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "base": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "commit": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "context_summary": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "files_changed": {
-                "type": "integer"
-              },
-              "lines_added": {
-                "type": "integer"
-              },
-              "lines_removed": {
-                "type": "integer"
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "cwd": {
-        "type": "string"
-      },
-      "fingerprint": {
-        "type": "string"
-      },
-      "isolation": {
-        "enum": [
-          "inherit",
-          "ignore-config",
-          "ignore-rules"
-        ],
-        "type": "string"
-      },
-      "max_input_bytes": {
-        "type": "integer"
-      },
-      "ok": {
-        "const": true,
-        "type": "boolean"
-      },
-      "paths": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "prompt_bytes": {
-        "type": "integer"
-      },
-      "redacted_paths": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "redacted_paths_count": {
-        "type": "integer"
-      },
-      "sandbox": {
-        "enum": [
-          "read-only",
-          "workspace-write",
-          "danger-full-access"
-        ],
-        "type": "string"
-      },
-      "scope": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "security_warnings": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "tier": {
-        "enum": [
-          "consult",
-          "propose",
-          "apply"
-        ],
-        "type": "string"
-      },
-      "tool": {
-        "const": "codex_dry_run",
-        "type": "string"
-      },
-      "truncated": {
-        "type": "boolean"
-      },
-      "truncation_hint": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "workspace_source": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "workspace_warning": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "required": [
-      "cwd",
-      "tier",
-      "sandbox",
-      "isolation",
-      "prompt_bytes",
-      "max_input_bytes"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "error": {
-        "description": "Populated error envelope; full schema at resource codex://error-envelope",
-        "type": "object"
-      },
-      "meta": {
-        "type": "object"
-      },
-      "ok": {
-        "const": false
-      }
-    },
-    "required": [
-      "ok",
-      "error",
-      "meta"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "base": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "commit": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "context_summary": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "files_changed": {
+                "type": "integer"
+              },
+              "lines_added": {
+                "type": "integer"
+              },
+              "lines_removed": {
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "cwd": {
+        "type": "string"
+      },
+      "fingerprint": {
+        "type": "string"
+      },
+      "isolation": {
+        "enum": [
+          "inherit",
+          "ignore-config",
+          "ignore-rules"
+        ],
+        "type": "string"
+      },
+      "max_input_bytes": {
+        "type": "integer"
+      },
+      "ok": {
+        "const": true,
+        "type": "boolean"
+      },
+      "paths": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "prompt_bytes": {
+        "type": "integer"
+      },
+      "redacted_paths": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "redacted_paths_count": {
+        "type": "integer"
+      },
+      "sandbox": {
+        "enum": [
+          "read-only",
+          "workspace-write",
+          "danger-full-access"
+        ],
+        "type": "string"
+      },
+      "scope": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "security_warnings": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "server_version": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "tier": {
+        "enum": [
+          "consult",
+          "propose",
+          "apply"
+        ],
+        "type": "string"
+      },
+      "tool": {
+        "const": "codex_dry_run",
+        "type": "string"
+      },
+      "truncated": {
+        "type": "boolean"
+      },
+      "truncation_hint": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "workspace_source": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "workspace_warning": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "cwd",
+      "tier",
+      "sandbox",
+      "isolation",
+      "prompt_bytes",
+      "max_input_bytes"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "error": {
+        "description": "Populated error envelope; full schema at resource codex://error-envelope",
+        "type": "object"
+      },
+      "meta": {
+        "type": "object"
+      },
+      "ok": {
+        "const": false
+      }
+    },
+    "required": [
+      "ok",
+      "error",
+      "meta"
+    ],
+    "type": "object"
+  }
+]

Changed2 schema fields changedv0.8.0Jul 6, 2026

changedInput schema / properties / isolation / description

Previous value: -"Codex config isolation: 'inherit' (default), 'ignore-config', or 'ignore-rules'."New value: +"Codex config isolation: 'inherit', 'ignore-config', or 'ignore-rules'. Defaults to the server's configured isolation (built-in default 'inherit'; `codex_status` reports the resolved value)."

addedOutput schema / $schema

Added value: +"https://json-schema.org/draft/2020-12/schema"

Changed1 schema field changedv0.6.0Jun 29, 2026

changedInput schema / properties / extra_context / description

Previous value: -"Optional author intent / background, added to the prompt as clearly-labeled UNTRUSTED context (directives inside it are never obeyed)."New value: +"Optional author intent / background context, added to the prompt as clearly-labeled UNTRUSTED data. Codex is instructed to treat embedded directives as data, not commands — best-effort prompt-injection mitigation, not a guarantee. Don't include live secrets: Codex can read files it's pointed at, and redaction does not cover this field."

First observedv0.5.0Jun 28, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations (`readOnlyHint=true`, `openWorldHint=false`) are consistent and the description goes well beyond them: it explains `would_call_model` semantics (False on empty diff, `prompt_bytes` 0), `coverage` disclosure of omitted untracked files, `deadline_advisory` naming the async counterpart, unvalidated model/effort echoes, and best-effort redaction. It also discloses a non-obvious security boundary — the sandbox bounds writes, not reads — which annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with deprecation and purpose, then caveats and return-field semantics; nearly every sentence carries distinct information. It is nonetheless long (three paragraphs) with mild redundancy ('Free — no model call, no spend'), so not a perfect 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 parameters, an output schema, and annotations all present, the description fills the remaining gaps an agent needs: the free/no-model guarantee, preview-vs-paid fidelity requirements, interpretation of `would_call_model`/`coverage`/`deadline_advisory`, and the read-boundary caveat.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema carries the per-parameter burden and baseline is 3. The description still adds cross-parameter meaning the schema does not: mirroring `extra_context` and `untracked` between dry run and paid call, and what the returned `model`/`reasoning_effort` echoes represent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and object — 'Preview what a `codex_review_changes` call would send — scope, diff size, redactions, truncation' — and immediately signals deprecation in favor of `amicus_review_changes_dry_run`. An agent can distinguish it from the paid `codex_review_changes` and its async counterpart without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use ('Use it before a review to inspect the scope and the reported redactions'), an explicit when-*not* caveat ('treat the preview as a check on scope, not as confirmation that no secret remains'), and a routing hint to the async sibling. It also tells the caller to mirror `extra_context`/`untracked` so the preview matches the paid call.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Preview a review (free)

Instructions

Input Schema

Output Schema

Schema Changelog

TDQS

Other Tools