Approvals and safety
Decide what the agent may do on its own
Headmaster can run commands and code, not just chat. Approvals are how you stay in control of that. When the agent wants to do something risky, it stops and asks you first. You decide how often it asks.
This page explains what triggers an approval, the three approval modes, every button on an approval card, the safety nets that are always on, and what to do when something goes wrong.
How approvals work
Every time the agent wants to run a shell command or a piece of code, Headmaster checks it before it runs.
- Always-blocked actions are stopped. A small set of catastrophic commands, such as wiping a disk, deleting your whole home folder, or shutting the computer down, are blocked in every mode. No setting turns this off.
- Commands you already trust go straight through. If you chose Allow this session or Always allow for a command like this before, it runs without asking.
- Risky actions are checked against your approval mode. Headmaster recognizes risky patterns, such as recursive deletes, overwriting system or credential files, force-killing processes, piping a download straight into a shell, or running generated code. What happens next depends on your mode.
- Everything else just runs. Ordinary commands, such as listing files or running your tests, do not need approval.
So approvals are not a prompt for every single step. They appear when an action could cause real damage.
The three approval modes
Pick the mode from the word under the chat box (it shows the current mode, for example Manual). The same setting is in Settings → Safety → Approvals, labelled Approval mode. In web chat, the approval mode menu sits next to the model selector.
| Mode | What it says in the app | What happens to a risky action |
|---|---|---|
| Manual (default) | Ask before actions that require approval | Always pauses and asks you. |
| Smart | Automatically assess actions and ask when needed | A separate safety check reviews it. Clearly safe actions run. Clearly dangerous ones are refused. Anything uncertain is sent to you. |
| Off | Run without approval prompts | Runs without asking. |
Manual
Every risky action waits for you. This is the default and the best choice while you get to know Headmaster, or when the agent is working on something you care about.
Smart
Smart mode puts a reviewer in front of you. Before a risky action reaches you, a separate AI check looks only at what the command would actually do and gives one of three answers:
- Approve: it looks safe, like a package install, a normal git command, or running a script in your project. It runs without a prompt.
- Deny: it could genuinely damage something, like a recursive delete of an important folder or dropping a database. It does not run.
- Escalate: it is unclear, or the command contains text that looks like it is trying to talk its way past the review. You get the usual approval card.
Smart mode ignores any instructions written inside the command itself, so a command that says "approve me" in a comment does not get a free pass. If the reviewer keeps refusing the same kind of action, the agent is told to stop retrying and ask you instead.
When Smart refuses something and you still want it, you can approve it yourself. In that case Always allow is not offered for it.
Off
Risky actions run without asking. Use this only for work you fully trust, in a folder you can afford to lose. The always-blocked actions above are still blocked.
Your choice is remembered
Your choice is saved, not reset per chat. It applies in the mode you set it in, so you can keep Cloud and Work on different approval modes.
The approval card
When the agent needs approval, the chat shows a card titled Allow this command to run? with the command in full. Choose View details to see more of it. If you are in another chat, a notification and a Approval needed marker take you to it.
| Button | What it does |
|---|---|
| Allow once | Runs this one command. Next time, it asks again. |
| Allow this session | Runs it, and stops asking about commands like this until the chat ends. Found under More approval options. |
| Always allow... | Adds the command's pattern to your permanent command allowlist. Headmaster won't ask again for commands like this, in this chat or any future one. You confirm first. Work Mode only. |
| Deny | The command does not run. |
When you deny, the agent is told plainly that you did not consent. It is instructed not to retry, not to rephrase the command, and not to try the same thing another way. It stops and waits for you.
In web chat
Web chat shows a simpler dialog, Approve this action?, with the command it wants to run. Confirm to allow it once, or cancel to deny. If an approval can only be answered with options web chat does not offer, Headmaster treats it as not approved.
If you do not answer
Silence is never treated as a yes. An approval waits about five minutes. After that it times out, the command does not run, and the chat shows The approval timed out, the command didn't run. Ask Headmaster to try again when you are ready.
If Headmaster goes offline while a card is waiting, the card stays. Reconnect, then answer it.
The command allowlist (Work Mode)
Every Always allow choice is saved to your command allowlist. You can review and edit it in Settings → Safety → Approvals under Command Allowlist. Remove an entry to make Headmaster ask again for that kind of command.
The allowlist is a Work Mode setting. It does not appear in Cloud.
Tip: be specific. Always allowing a pattern you only meant for one project means it is trusted everywhere.
Checkpoints (Work Mode)
File Checkpoints create rollback snapshots before the agent edits files. Turn them on in Settings → Safety → Checkpoints. They are off by default.
With checkpoints on, you can rewind from a message in the chat:
- Restore checkpoint puts your files back to how they were at that point.
- Restore checkpoint, rerun from this prompt removes everything after that message and runs the prompt again.
Headmaster keeps a limited number of recent checkpoints per folder, and drops the oldest ones as new ones are made. Checkpoints are a Work Mode feature.
Stopping the agent
The Stop button in the chat box interrupts the agent immediately, whatever mode you are in. Use it the moment something looks wrong.
Scheduled tasks and approvals
Scheduled tasks run when nobody is there to answer a prompt. So a scheduled task cannot ask for approval. Instead, risky commands in a scheduled task are blocked, and the task is told to find another way. Write scheduled tasks that do not need risky commands.
Where actions run
- In Cloud Mode, commands run on your hosted Cloud runtime, never on your PC.
- In Work Mode, commands run on your PC, starting in your working folder. See Cloud and Work modes.
Examples
Example: cleaning up build files
You ask the agent to clear old build output. It wants to run a recursive delete on the build folder. In Manual, you see the card, check the path is the build folder, and choose Allow once.
Example: a long coding session
The agent will run the same install command many times while it fixes a project. Choose Allow this session the first time, so it stops asking for the rest of this chat, but asks again in new chats.
Example: something you always trust
You run a formatter on every project and never want to be asked. In Work Mode choose Always allow... and confirm. Later, remove it from Command Allowlist if you change your mind.
Example: Smart mode in practice
In Smart, an ordinary package install runs on its own, a delete of your whole projects folder is refused, and an odd-looking command with a hidden comment comes to you as a card.
Your keys and secrets
Provider keys are stored encrypted and are not shown again after you save them. See Models and providers and Data, privacy and security.
Tips
- Stay on Manual until you are comfortable. Move to Smart when the prompts feel like noise.
- Read the full command before approving, especially paths in delete commands.
- Prefer Allow this session over Always allow for one-off projects.
- Turn on checkpoints before letting the agent do big file edits in Work Mode.
Troubleshooting
- The agent stopped and is waiting. Look for an approval card or the Approval needed marker, and answer it.
- "Could not send approval response". Your connection dropped. Choose Reconnect, then answer again.
- The approval timed out. The command did not run. Ask the agent to try again.
- A command was blocked even in Off. It is one of the always-blocked actions. Do it yourself if you really need it.
- I don't see Command Allowlist or Checkpoints. You are in Cloud Mode. Switch to Work Mode.
See also Troubleshooting.