Codex Execpolicy

Overview

Define and maintain Codex execpolicy rules so the agent can allow, prompt, or forbid command prefixes, and validate the policy before use.

Workflow

1. Clarify scope and location.

   • Ask: “Should this be a global rule or project-specific?”
   • If global: default to ~/.codex/rules/default.rules unless the user provides another path or uses a different Codex home.
   • If project-specific: ask for the exact file path; a common pattern is .codex/rules/default.rules at repo root.
   • If the file already exists, inspect it before editing.

2. Clarify intent.

   • Ask for the decision: allow, prompt, or forbidden.
   • Ask for the command prefix and any alternatives.
   • Ask for at least one “should match” and “should not match” example if the rule is non-trivial.

3. Implement the rule.

   • Use prefix_rule(...) with a precise pattern list.
   • Use union lists for alternatives when only one argument varies.
   • Add match / not_match as inline tests when the rule is tricky.

4. Validate before finishing.

   • Run codex execpolicy check --pretty --rules <path> -- <command> using realistic examples.
   • If validation fails, adjust pattern or tests and re-check.

5. Summarize outcomes.

   • State what command prefixes are allowed/prompted/blocked and where the rule lives.

Examples

Block all git commands:

prefix_rule(
  pattern = ["git"],
  decision = "forbidden",
)

Prompt for either gh pr view or gh pr list:

prefix_rule(
  pattern = ["gh", "pr", ["view", "list"]],
  decision = "prompt",
)

Resources

• See references/execpolicy.md for syntax notes, decision precedence, and validation commands.