untrusted
Codex prompts for every non-safe command. This is the closest fit to Claude Code's default permission UI when tool-gates returns ask or defer.
Permission Modes
Clients send permission_mode with hook events, but each client gives that value a different shape. tool-gates treats mode as a policy layer above the normal gate decision so the same shell rule can behave differently in planning, batch-edit, and classifier-driven sessions.
Mode matrix
What changes by mode.
| Mode | Clients | tool-gates behavior |
|---|---|---|
default |
Claude Code, Codex CLI, Antigravity CLI, Gemini CLI | Normal gate flow. Known-safe commands can allow, dangerous commands deny, and unknown or mutating commands ask or defer. Claude Code labels this mode "Manual" in its UI and accepts manual as an alias; hooks still receive default. On Codex, whether an ask becomes a visible prompt also depends on approval_policy. On Antigravity, a hook allow does not suppress a prompt (agy keeps the strictest decision); its native permissions.allow does. |
acceptEdits |
Claude Code; any client that sends the exact string | Path-safe file-editing commands can auto-allow inside the project and configured additional directories. Deny rules, ask rules, guarded AI config paths, sensitive paths, and tool block rules still win. [[accept_edits_mcp]] can extend this to scoped MCP tools. Codex does not currently emit this mode; its project-edit shortcut is configured separately under [codex]. |
auto |
Claude Code (default for new sessions on Pro, Max, and Team plans since August 14, 2026) | Allowed commands skip the classifier and run. Denied commands stay denied. Asks go to Claude Code's classifier instead of a human prompt. tool-gates promotes high-risk asks such as pipe-to-shell and eval to deny, avoids adding classifier approvals to the human pending queue, and emits PermissionDenied retry hints when the classifier rejects a command the gate engine would allow. See Auto mode for the rollout details and repo-level opt-out. |
plan |
Claude Code | Read-only planning stays allowed, but mutations are blocked. Mutating shell asks, defers, unknowns, and unapproved Claude acceptEdits bases deny instead of reaching a prompt. Settings allow rules and acceptEdits shortcuts do not turn mutations into allows while the client is in plan mode. |
bypassPermissions |
Client-specific; Codex emits this value today | No special auto-allow path inside tool-gates. If the client still invokes hooks, hard denies and configured block rules remain the floor. Client-native bypass behavior controls which prompts or sandbox checks run outside tool-gates. |
dontAsk |
Simulator and compatibility inputs | No dedicated branch in the current gate pipeline. tool-gates treats it like the normal gate path; the client decides what reaches hooks and how prompts are displayed. |
Codex axis
Codex approval policy is separate from mode.
on-request / on-failure
Codex leans on the sandbox and asks only when a command requests elevation or when a sandboxed attempt fails. tool-gates still evaluates the hook event it receives, but an ask may not surface as an immediate prompt.
never
Codex never asks the operator for approval. tool-gates deny decisions still matter for hook events, but ask/defer behavior is constrained by Codex's no-prompt policy.
Use the Codex approval model for the full wire-format details, including why Codex hooks use the explicit --client codex flag and why non-deny PreToolUse output is silent.
Rule of thumb
Pick the smallest mode that matches the work.
Plan is for exploration only. acceptEdits is for path-safe batch edits where deny and ask rules still matter. auto is for deterministic gate decisions first, then classifier review of remaining asks.
Related pages: Hook model, Auto mode, Codex approval model, and Configuration.