# Codex Config Generator — AI-Readable Schema

> This file describes every configuration field the codexapp.cc generator supports.
> AI agents can read this to understand what fields exist, their types, valid values,
> and how to generate config.toml / requirements.toml / shell env / .rules files.
>
> Base URL: https://codexapp.cc
> Source docs: https://developers.openai.com/codex/

## File Types

This tool generates 4 file types. Select one via the top tab:

1. **config.toml** — User-level Codex configuration (`~/.codex/config.toml`)
2. **requirements.toml** — Admin-enforced constraints (managed)
3. **Shell environment variables** — CODEX_HOME, RUST_LOG, etc. (export/.env/PowerShell)
4. **.rules** — Starlark command rules (`~/.codex/rules/default.rules`)

---

# config.toml Fields

## Core / Basics

| Key | Type | Default | Valid Values | Description |
|-----|------|---------|--------------|-------------|
| model | string | (unset) | e.g. "gpt-5.5" | Default model Codex uses |
| review_model | string | (unset) | any model slug | Model override for /review |
| model_provider | string | "openai" | "openai" \| custom provider id | Which provider to use |
| openai_base_url | string | (unset) | URL | Override base URL for built-in openai provider |
| oss_provider | string | (unset) | "ollama" \| "lmstudio" | Default local provider for --oss |
| approval_policy | string | "on-request" | "untrusted" \| "on-request" \| "never" \| { granular = {...} } | When to pause for approval |
| sandbox_mode | string | "read-only" | "read-only" \| "workspace-write" \| "danger-full-access" | Filesystem/network sandbox level |
| model_reasoning_effort | string | (model default) | "minimal" \| "low" \| "medium" \| "high" \| "xhigh" | Reasoning depth |
| plan_mode_reasoning_effort | string | (preset) | "none" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" | Plan-mode reasoning override |
| personality | string | (unset) | "friendly" \| "pragmatic" \| "none" | Communication style |
| web_search | string | "cached" | "cached" \| "live" \| "disabled" | Web search mode |
| service_tier | string | (unset) | "fast" \| "flex" \| custom tier id | Service tier preference |
| model_reasoning_summary | string | (model default) | "auto" \| "concise" \| "detailed" \| "none" | Reasoning summary detail |
| model_verbosity | string | (model default) | "low" \| "medium" \| "high" | Response verbosity (Responses API only) |
| model_context_window | number | (auto) | token count | Override context window size |
| model_auto_compact_token_limit | number | (model default) | token count | Threshold for auto-compaction |
| model_supports_reasoning_summaries | boolean | (unset) | true \| false | Force enable/disable reasoning summaries |
| model_catalog_json | string | (unset) | file path | Custom model catalog JSON path |
| log_dir | string | $CODEX_HOME/log | absolute path | Log directory (enables codex-tui.log) |
| sqlite_home | string | CODEX_HOME | path | SQLite state DB directory |
| check_for_update_on_startup | boolean | true | true \| false | Check for updates on startup |
| commit_attribution | string | "Codex <noreply@openai.com>" | string \| "" | Git commit co-author trailer ("" disables) |
| tool_output_token_limit | number | (unset) | token count | Max tokens stored per tool output |
| background_terminal_max_timeout | number | 300000 | ms | Max empty write_stdin poll window |
| disable_paste_burst | boolean | false | true \| false | Disable burst-paste detection |
| suppress_unstable_features_warning | boolean | false | true \| false | Suppress unstable feature warnings |
| hide_agent_reasoning | boolean | false | true \| false | Hide reasoning events |
| show_raw_agent_reasoning | boolean | false | true \| false | Show raw reasoning content |

## Approval & Sandbox (Advanced)

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| approvals_reviewer | string | "user" | "user" \| "auto_review" — who reviews approvals |
| allow_login_shell | boolean | true | Allow login-shell semantics |
| approval_policy (granular) | table | — | `{ granular = { sandbox_approval, rules, mcp_elicitations, request_permissions, skill_approval } }` each boolean |

### [sandbox_workspace_write]

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| writable_roots | array<string> | [] | Extra writable paths |
| network_access | boolean | false | Allow outbound network |
| exclude_tmpdir_env_var | boolean | false | Exclude $TMPDIR |
| exclude_slash_tmp | boolean | false | Exclude /tmp |

### [auto_review]

| Key | Type | Description |
|-----|------|-------------|
| policy | string (multiline) | Local auto-review policy instructions |

## [features]

Feature flags. Each key is boolean. Leave unset for default.

| Key | Default | Description |
|-----|---------|-------------|
| shell_tool | true | Enable default shell tool |
| unified_exec | true (not Windows) | Unified PTY exec tool |
| shell_snapshot | true | Snapshot shell env |
| hooks | true | Enable lifecycle hooks |
| codex_git_commit | false | Codex-generated git commits |
| fast_mode | true | Fast mode / service_tier="fast" |
| memories | false | Enable Memories |
| multi_agent | true | Multi-agent collaboration tools |
| personality | true | Personality selection |
| undo | false | Undo support |
| apps | false | ChatGPT Apps/connectors |
| network_proxy | false | Sandboxed networking (table form available) |
| enable_request_compression | true | zstd request compression |
| skill_mcp_dependency_install | true | Auto-install MCP deps for skills |
| prevent_idle_sleep | false | Prevent machine sleep during turns |
| web_search | (deprecated) | Use top-level web_search instead |

### [features.network_proxy]

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | boolean | false | Enable sandboxed networking |
| domains | map<string, allow\|deny> | {} | Domain policy (exact / *.sub / **.apex+sub / *) |
| unix_sockets | map<string, allow\|deny> | {} | Unix socket policy |
| allow_local_binding | boolean | false | Allow local/private network |
| enable_socks5 | boolean | true | SOCKS5 listener |
| enable_socks5_udp | boolean | true | UDP over SOCKS5 |
| allow_upstream_proxy | boolean | true | Chain through upstream proxy |
| proxy_url | string | "http://127.0.0.1:3128" | HTTP listener |
| socks_url | string | "http://127.0.0.1:8081" | SOCKS5 listener |
| dangerously_allow_non_loopback_proxy | boolean | false | Non-loopback listener bind |
| dangerously_allow_all_unix_sockets | boolean | false | Bypass Unix socket allowlist |

## [tui]

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| notifications | boolean\|array | true | Desktop notifications |
| notification_method | string | "auto" | "auto" \| "osc9" \| "bel" |
| notification_condition | string | "unfocused" | "unfocused" \| "always" |
| animations | boolean | true | Terminal animations |
| alternate_screen | string | "auto" | "auto" \| "always" \| "never" |
| show_tooltips | boolean | true | Welcome screen tooltips |
| vim_mode_default | boolean | false | Start in Vim normal mode |
| raw_output_mode | boolean | false | Raw scrollback mode |
| status_line | array<string>\|null | (preset) | Footer status line items |
| terminal_title | array<string>\|null | ["spinner","project"] | Terminal title items |
| theme | string | (unset) | Syntax highlight theme (kebab-case) |

### [tui.keymap.<context>]

Contexts: global, chat, composer, editor, vim_normal, vim_operator, vim_text_object, pager, list, approval

| Key | Type | Description |
|-----|------|-------------|
| <action> | string \| array<string> | Key binding (e.g. "ctrl-t", ["enter","ctrl-m"]) |
| <action> = [] | empty array | Unbind the action |

## [shell_environment_policy]

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| inherit | string | "all" | "all" \| "core" \| "none" — baseline inheritance |
| set | map<string,string> | {} | Explicit env overrides |
| ignore_default_excludes | boolean | false | Keep KEY/SECRET/TOKEN vars |
| exclude | array<string> | [] | Glob patterns to remove |
| include_only | array<string> | [] | Whitelist (if non-empty) |
| experimental_use_profile | boolean | false | Use user shell profile |

## [permissions.<name>]

Named permission profiles. Set `default_permissions` to activate.

| Key | Type | Description |
|-----|------|-------------|
| default_permissions | string | Profile name or builtin (:read-only \| :workspace \| :danger-full-access) |
| description | string | Human-readable description |
| extends | string | Parent profile (:read-only \| :workspace \| named) |
| workspace_roots.<path> | boolean | Add path to workspace root set |
| filesystem.<path> | "read"\|"write"\|"deny" | Filesystem access rule |
| filesystem.glob_scan_max_depth | number | Max depth for deny glob expansion (≥1) |
| filesystem.":workspace_roots".<subpath> | "read"\|"write"\|"deny" | Scoped rule (". "for root, glob for subpaths) |
| network.enabled | boolean | Enable network access |
| network.mode | string | "limited" \| "full" |
| network.proxy_url | string | HTTP proxy listener |
| network.socks_url | string | SOCKS5 listener |
| network.enable_socks5 | boolean | SOCKS5 support |
| network.enable_socks5_udp | boolean | UDP over SOCKS5 |
| network.allow_upstream_proxy | boolean | Chain upstream proxy |
| network.allow_local_binding | boolean | Local/private network access |
| network.dangerously_allow_non_loopback_proxy | boolean | Non-loopback bind |
| network.dangerously_allow_all_unix_sockets | boolean | Bypass socket allowlist |
| network.domains.<pattern> | "allow"\|"deny" | Domain rule (*, *., **.) |
| network.unix_sockets.<path> | "allow"\|"deny" | Unix socket rule |

Path tokens: :root, :minimal, :workspace_roots, :tmpdir, :slash_tmp, /absolute, ~/home

Precedence: deny > write > read. More specific path wins.

## [mcp_servers.<id>]

### STDIO server

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| command | string | (required) | Launcher command |
| args | array<string> | [] | Arguments |
| env | map<string,string> | {} | Environment variables |
| env_vars | array<string\|{name,source}> | [] | Forwarded env vars (source: "local"\|"remote") |
| cwd | string | (unset) | Working directory |
| experimental_environment | string | "local" | "local" \| "remote" |

### HTTP server

| Key | Type | Description |
|-----|------|-------------|
| url | string | (required) Server endpoint |
| bearer_token_env_var | string | Env var for bearer token |
| http_headers | map<string,string> | Static headers |
| env_http_headers | map<string,string> | Headers from env vars |

### Common options

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | boolean | true | Enable/disable |
| required | boolean | false | Fail startup if can't init |
| startup_timeout_sec | number | 10 | Startup timeout |
| startup_timeout_ms | number | — | Alias (ms) |
| tool_timeout_sec | number | 60 | Per-tool timeout |
| enabled_tools | array<string> | [] | Tool allowlist |
| disabled_tools | array<string> | [] | Tool denylist |
| default_tools_approval_mode | string | (unset) | "auto" \| "prompt" \| "approve" |
| tools.<tool>.approval_mode | string | (unset) | Per-tool override |
| scopes | array<string> | [] | OAuth scopes |
| oauth_resource | string | (unset) | OAuth resource param |

## [hooks]

Inline lifecycle hooks. Same schema as hooks.json.

### [[hooks.<Event>]]

Events: SessionStart, SubagentStart, PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, UserPromptSubmit, SubagentStop, Stop

| Key | Type | Description |
|-----|------|-------------|
| matcher | string (regex) | Filter (tool name, source, trigger, etc.) |

### [[hooks.<Event>.hooks]]

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| type | string | — | "command" (only supported type) |
| command | string | (required) | Shell command to run |
| command_windows | string | (unset) | Windows command override |
| timeout | number | 600 | Timeout in seconds |
| statusMessage | string | (unset) | Status display text |

## [agents]

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| max_threads | number | 6 | Max concurrent agent threads |
| max_depth | number | 1 | Max nesting depth (root = 0) |
| job_max_runtime_seconds | number | 1800 | Per-worker timeout for CSV jobs |

### [agents.<name>]

| Key | Type | Description |
|-----|------|-------------|
| description | string | Role guidance |
| config_file | string | Path to standalone agent TOML |
| nickname_candidates | array<string> | Display nickname pool |

## [memories]

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| generate_memories | boolean | true | Store threads for memory generation |
| use_memories | boolean | true | Inject memories into sessions |
| disable_on_external_context | boolean | false | Skip MCP/web-search threads |
| max_raw_memories_for_consolidation | number | 256 | Retention cap (max 4096) |
| max_unused_days | number | 30 | Days before ineligible (0-365) |
| max_rollout_age_days | number | 30 | Max thread age (0-90) |
| max_rollouts_per_startup | number | 16 | Candidates per pass (max 128) |
| min_rollout_idle_hours | number | 6 | Min idle time (1-48) |
| min_rate_limit_remaining_percent | number | 25 | Min rate limit (0-100) |
| extract_model | string | (unset) | Model for extraction |
| consolidation_model | string | (unset) | Model for consolidation |

## [apps._default] / [apps.<id>]

| Key | Type | Description |
|-----|------|-------------|
| enabled | boolean | App on/off |
| destructive_enabled | boolean | Allow destructive_hint tools |
| open_world_enabled | boolean | Allow open_world_hint tools |
| default_tools_enabled | boolean | Default tool state |
| default_tools_approval_mode | string | "auto" \| "prompt" \| "approve" |
| tools.<tool>.enabled | boolean | Per-tool override |
| tools.<tool>.approval_mode | string | Per-tool approval |

## [tools]

| Key | Type | Description |
|-----|------|-------------|
| view_image | boolean | Enable local-image attachment tool |
| web_search | boolean\|object | `{ context_size, allowed_domains, location }` |

## [[skills.config]]

| Key | Type | Description |
|-----|------|-------------|
| path | string | Path to SKILL.md |
| enabled | boolean | Enable/disable skill |

## [tool_suggest]

| Key | Type | Description |
|-----|------|-------------|
| discoverables | array<{type,id}> | Suggested connectors/plugins |
| disabled_tools | array<{type,id}> | Disabled suggestions |

type: "connector" \| "plugin"

## [otel]

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| environment | string | "dev" | Environment tag |
| exporter | string | "none" | "none" \| "otlp-http" \| "otlp-grpc" |
| trace_exporter | string | "none" | Same options |
| metrics_exporter | string | "statsig" | "none" \| "statsig" \| "otlp-http" \| "otlp-grpc" |
| log_user_prompt | boolean | false | Log raw user prompts |

### [otel.exporter.<id>] / [otel.trace_exporter.<id>]

| Key | Type | Description |
|-----|------|-------------|
| endpoint | string | Exporter endpoint |
| protocol | string | "binary" \| "json" |
| headers | map<string,string> | Static headers |

## [windows]

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| sandbox | string | (unset) | "elevated" \| "unelevated" |
| sandbox_private_desktop | boolean | (unset) | Private desktop for sandboxed child |

## Auth & Credentials

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| chatgpt_base_url | string | (unset) | ChatGPT auth flow URL |
| cli_auth_credentials_store | string | "file" | "file" \| "keyring" \| "auto" |
| mcp_oauth_credentials_store | string | "auto" | "auto" \| "file" \| "keyring" |
| mcp_oauth_callback_port | number | (ephemeral) | Fixed OAuth callback port |
| mcp_oauth_callback_url | string | (unset) | OAuth redirect URI override |
| forced_login_method | string | (unset) | "chatgpt" \| "api" |
| forced_chatgpt_workspace_id | string | (unset) | Lock to workspace UUID |

## Instructions & Docs

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| instructions | string | (unset) | Reserved; use model_instructions_file |
| developer_instructions | string | (unset) | Extra developer instructions |
| model_instructions_file | string | (unset) | Override built-in instructions |
| compact_prompt | string | (unset) | Inline compaction prompt |
| experimental_compact_prompt_file | string | (unset) | Compaction prompt from file |
| project_doc_max_bytes | number | 32768 | Max AGENTS.md bytes |
| project_doc_fallback_filenames | array<string> | [] | Fallback filenames |
| project_root_markers | array<string> | [".git"] | Project root markers |

## History & Misc

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| history.persistence | string | "save-all" | "save-all" \| "none" |
| history.max_bytes | number | (unset) | History file size cap |
| analytics.enabled | boolean | (unset) | Analytics toggle |
| feedback.enabled | boolean | true | /feedback toggle |
| notify | array<string> | (unset) | External notifier program (argv) |
| file_opener | string | "vscode" | "vscode" \| "cursor" \| "windsurf" \| "vscode-insiders" \| "none" |

## [notice] (state tracking)

| Key | Type | Description |
|-----|------|-------------|
| hide_full_access_warning | boolean | Ack full-access warning |
| hide_world_writable_warning | boolean | Ack world-writable warning |
| hide_rate_limit_model_nudge | boolean | Opt out of model nudge |
| model_migrations | map<string,string> | Acknowledged migrations (old→new) |

## [projects.<path>]

| Key | Type | Description |
|-----|------|-------------|
| trust_level | string | "trusted" \| "untrusted" |

## [plugins.<id>] / [plugins.<plugin>.mcp_servers.<server>]

| Key | Type | Description |
|-----|------|-------------|
| enabled | boolean | Plugin or MCP server on/off |
| default_tools_approval_mode | string | "auto" \| "prompt" \| "approve" |
| enabled_tools | array<string> | Tool allowlist |
| disabled_tools | array<string> | Tool denylist |
| tools.<tool>.approval_mode | string | Per-tool override |

## [model_providers.<id>]

Built-in IDs (reserved): openai, ollama, lmstudio, amazon-bedrock

| Key | Type | Description |
|-----|------|-------------|
| name | string | Display name |
| base_url | string | API base URL |
| env_key | string | Env var for API key |
| env_key_instructions | string | Setup guidance |
| wire_api | string | "responses" (default, only supported) |
| query_params | map<string,string> | Extra URL params |
| http_headers | map<string,string> | Static headers |
| env_http_headers | map<string,string> | Headers from env |
| request_max_retries | number | HTTP retry count (default 4) |
| stream_max_retries | number | Stream retry count (default 5) |
| stream_idle_timeout_ms | number | Stream idle timeout (default 300000) |
| supports_websockets | boolean | WebSocket transport support |
| experimental_bearer_token | string | Direct bearer token (discouraged) |
| requires_openai_auth | boolean | Uses OpenAI auth |

### [model_providers.<id>.auth]

Cannot combine with env_key/experimental_bearer_token/requires_openai_auth.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| command | string | (required) | Token fetch command |
| args | array<string> | [] | Command arguments |
| timeout_ms | number | 5000 | Command timeout |
| refresh_interval_ms | number | 300000 | Proactive refresh (0 = retry-only) |
| cwd | string | (unset) | Working directory |

### [model_providers.amazon-bedrock.aws]

| Key | Type | Description |
|-----|------|-------------|
| profile | string | AWS profile name |
| region | string | AWS region |

---

# requirements.toml Fields

Admin-enforced constraints. Users cannot override these.

## Top-level constraints

| Key | Type | Description |
|-----|------|-------------|
| allowed_approval_policies | array<string> | Permitted approval_policy values |
| allowed_approvals_reviewers | array<string> | Permitted approvals_reviewer values |
| allowed_sandbox_modes | array<string> | Permitted sandbox_mode values |
| allowed_web_search_modes | array<string> | Permitted web_search values ("disabled" always allowed) |
| default_permissions | string | Managed default permission profile |
| guardian_policy_config | string (multiline) | Managed auto-review policy (overrides local) |
| enforce_residency | string | "us" — require data residency |
| allow_managed_hooks_only | boolean | Skip user/project/session/plugin hooks |
| allow_appshots | boolean | Enable/disable Appshots |
| allow_remote_control | boolean | Enable/disable device remote control |

## [allowed_permission_profiles]

| Key | Type | Description |
|-----|------|-------------|
| <name> | boolean | true = allowed, false/omitted = denied |

## [windows]

| Key | Type | Description |
|-----|------|-------------|
| allowed_sandbox_implementations | array<string> | ["elevated", "unelevated"] (non-empty) |

## [[remote_sandbox_config]]

| Key | Type | Description |
|-----|------|-------------|
| hostname_patterns | array<string> | Host match (* and ? wildcards) |
| allowed_sandbox_modes | array<string> | Permitted modes for matching hosts |

## [features]

Same keys as config.toml [features], but pinned as requirements.

Additional managed keys: in_app_browser, browser_use, browser_use_external, browser_use_full_cdp_access, guardian_approval, plugins, computer_use, workspace_dependencies, plugin_sharing

## [computer_use]

| Key | Type | Description |
|-----|------|-------------|
| allow_locked_computer_use | boolean | Allow Computer Use after macOS lock |

## [experimental_network]

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | boolean | — | Enable managed networking |
| http_port | number | — | HTTP listener port |
| socks_port | number | — | SOCKS5 listener port |
| allow_upstream_proxy | boolean | — | Chain upstream proxy |
| domains | map<string,allow\|deny> | — | Domain policy |
| allowed_domains | array<string> | — | Allow list (alternative) |
| denied_domains | array<string> | — | Deny list (alternative) |
| managed_allowed_domains_only | boolean | — | Ignore user allowlist additions |
| unix_sockets | map<string,allow\|deny> | — | Unix socket policy |
| allow_local_binding | boolean | — | Local/private network |
| dangerously_allow_non_loopback_proxy | boolean | — | Non-loopback bind |
| dangerously_allow_all_unix_sockets | boolean | — | Bypass socket allowlist |

## [hooks] (managed)

| Key | Type | Description |
|-----|------|-------------|
| managed_dir | string | Hook scripts dir (macOS/Linux) |
| windows_managed_dir | string | Hook scripts dir (Windows) |
| [[hooks.<Event>]] | table | Same event schema as config.toml |

## [permissions]

| Key | Type | Description |
|-----|------|-------------|
| filesystem.deny_read | array<string> | Forced read denials (paths/globs) |
| <name> | table | Admin-defined profile (same fields as config.toml) |

## [mcp_servers.<id>.identity]

| Key | Type | Description |
|-----|------|-------------|
| command | string | Allow stdio when command matches |
| url | string | Allow HTTP when URL matches |

## [apps.<id>]

| Key | Type | Description |
|-----|------|-------------|
| enabled | boolean | Force disable app |
| tools.<tool>.approval_mode | string | Managed approval mode |

## [[rules.prefix_rules]]

| Key | Type | Description |
|-----|------|-------------|
| pattern | array<table> | Pattern tokens ({token} or {any_of:[]}) |
| decision | string | "prompt" \| "forbidden" (requirements can't "allow") |
| justification | string | Reason (surfaced in prompts) |

---

# Environment Variables

Shell/installer-level variables (not in config.toml).

## Core

| Variable | Default | Description |
|----------|---------|-------------|
| CODEX_HOME | ~/.codex | Root for Codex state (must exist) |
| CODEX_SQLITE_HOME | CODEX_HOME | SQLite state location (sqlite_home config overrides) |

## Installer

| Variable | Default | Description |
|----------|---------|-------------|
| CODEX_NON_INTERACTIVE | false | 1/true/yes = skip installer prompts |
| CODEX_INSTALL_DIR | ~/.local/bin (macOS/Linux) | Visible codex command location |

## Auth & Network

| Variable | Description |
|----------|-------------|
| CODEX_API_KEY | API key for single codex exec run (exec only) |
| CODEX_ACCESS_TOKEN | ChatGPT/Codex access token for automation |
| CODEX_CA_CERTIFICATE | PEM CA bundle (overrides SSL_CERT_FILE) |
| SSL_CERT_FILE | Fallback PEM CA bundle |

## Diagnostics

| Variable | Description |
|----------|-------------|
| RUST_LOG | Log filter: error/warn/info/debug/trace or codex_core=debug |

---

# .rules (Starlark)

File location: `rules/default.rules` next to config layer.

## prefix_rule()

```python
prefix_rule(
    pattern = ["gh", "pr", "view"],           # required, non-empty
    decision = "prompt",                       # "allow" | "prompt" | "forbidden" (default: "allow")
    justification = "Reason text",             # optional
    match = ["gh pr view 7888"],               # optional: should-match examples
    not_match = ["gh pr --repo x view 7888"],  # optional: should-not-match examples
)
```

### pattern elements

| Form | Meaning |
|------|---------|
| "literal" | Exact match at this position |
| ["a", "b"] | Match any_of at this position |

### decision precedence

forbidden > prompt > allow (most restrictive wins when multiple match)

### Shell splitting

- Safe scripts (plain words + &&/||/;/|): split into individual commands
- Complex scripts (redirection, vars, globs, control flow): treated as single command