Approvals

Teammates do real things: they send, publish, buy and delete. Approvals put you in the loop for the consequential ones, without making you approve every step.

Autonomy levels

Each teammate has one of three autonomy levels (bots.autonomy). It controls two things: Codex's own approval policy, and the approval rules written into the teammate's AGENTS.md.

Payments and emails don't depend on these instructions. start_purchase and send_email ask you themselves (an email from a full teammate sends right away).

Kinds of approval

The flow

Creating an approval

ApprovalService (apps/worker/src/services/approvals.ts) first checks the teammate's Always allow rules. If a rule covers the request, it is approved on the spot and nothing is shown.

Otherwise it:

1. inserts an approvals row with the run, the teammate, the chat, a title, the detail and a payload;
2. adds an approval item to the run's timeline, which renders as a card with Approve, Deny and Always allow;
3. creates a notification, which reaches open tabs, push and Telegram (with buttons);
4. publishes an approvals app event, so the Approvals inbox updates;
5. waits, with the run's status set to waiting for approval.

For a shell command, the title is the script itself. Codex sends commands wrapped in a shell, like /bin/bash -lc 'npm install', so shellScript() unwraps them for display and for matching.

Deciding

You decide in the chat, the Approvals inbox, or on Telegram. All three call ApprovalService.decide(), which:

1. updates the row only if it is still pending, so a double click or two devices can't decide twice;
2. saves an Always allow rule if you asked for one;
3. replaces the timeline card with the decision (through the live session, or by appending an event to the finished run);
4. emits approvalDecided, which updates the Telegram message's buttons to show the outcome;
5. hands the decision to the waiting tool call, if there is one.

If no tool call is waiting anymore, because the turn ended or the 10 minutes passed, an action or purchase decision queues a new run in the same chat with trigger approval:

[Approval] The user approved: "Post the weekly update to the team channel". Go ahead and do it now, then report back.

A denial says "Don't do it. Briefly acknowledge, and continue with anything else that is left."

Expiry

Codex's own command and file approvals can't outlive their turn. When a run ends, its pending command and file_change approvals become expired. action, purchase and email approvals stay answerable after the run ends.

Always allow

Always allow approves the request and saves a rule in approval_rules, so the teammate stops asking about requests like it. Rules are listed on the teammate's page, where you can remove them. They are also written into AGENTS.md and into every prompt, so the teammate knows it doesn't need request_approval for them.

Matching (rulesCover() in packages/shared/src/approval-rules.ts) depends on the kind:

• file_change: one rule covers every file change.
• action: the rule matches an action with the same wording, ignoring case and spacing.
• command: the rule is a command prefix, like npm install or git status. A script is covered only if every command it chains with ;, &&, ||, |, & or a new line starts with an allowed prefix, on a word boundary.

Some scripts can never be covered:

• Scripts that redirect (<, >) or substitute (`, $(...)) always ask, because a prefix can't say what they do.
• A pattern must be a single simple command.
• A pattern that would allow everything, like bash -lc or sh, is refused.
• Purchases and emails can't be Always allowed at all.

When you press Always allow, the app suggests a rule: the first command's program and subcommand (git push for git push origin main), or the action's wording.

npm install                    covered
npm install && npm test        asks: npm test isn't allowed
npm installer                  asks: not on a word boundary
npm install > log.txt          asks: redirects always ask