Approvals & human-in-the-loop

Headmaster keeps you in control. The agent asks for your approval before doing things that affect your files, your system, or external services.

What triggers an approval

Work Along mode
Run It Yourself mode
Hands-Off / Autopilot

The agent asks before every action:

🔧 Running a tool (web search, code execution, file read/write, MCP call, image generation)
📁 Accessing a file outside the project folder
🌐 Making a network request (external API call, HTTP request, webhook)
⚙️ Executing code (running a script, shell command, or code block)

The agent runs most tools without asking, but still asks before destructive actions:

🗑️ Deleting a file
⚠️ Overwriting an existing file
📧 Sending an email or message
⬆️ Pushing to a remote (git push)
🔐 Running a command with sudo / admin privileges

The approval prompt

When the agent wants to do something that needs approval, a card appears in the chat:

The agent wants to run: web_search
Query: "latest Python release notes"

[Approve]  [Deny]  [Approve always for this conversation]

Approve — let the action run.
Deny — block the action. The agent stops and asks what to do instead.
Approve always — let the agent run this tool type without asking again for the rest of this conversation.

Clarification requests

Sometimes the agent needs more information before it can proceed. Instead of guessing, it asks:

The agent needs clarification:
"You mentioned 'the config file' — do you mean config.yaml or config.json?"

[config.yaml]  [config.json]  [Type your answer]

Click one of the suggested options, or type your own answer. The agent incorporates your response and continues.

Permission requests

When the agent needs elevated permissions (e.g., sudo to install a package), it sends a permission request:

The agent needs sudo access to run: apt install postgresql-client

[Grant sudo for this command]  [Deny]

The request shows the exact command. Granting sudo is scoped to that specific command only — not blanket sudo access.

Secret requests

When the agent needs a credential it doesn’t have:

The agent needs your Stripe API key to list recent charges.

[Enter key...]  [Skip]

The key you enter is stored encrypted in the Connections area and is available to the agent in future conversations. Revoke it any time from Settings.

Audit trail

Every approval, denial, clarification, and permission grant is logged in the conversation transcript:

What’s logged	Detail
What was requested	Tool name, action type, parameters
What you decided	Approved, denied, or always-approved
Timestamp	When the decision was made
Parameters	The exact inputs for the action

The transcript is stored in the session file and can be exported for compliance reviews.

Modes

Approval behavior is controlled by your active mode.

Security

Container isolation, secret blocking, and the full security model.

Getting Started

Core Concepts

HeadmasterUI Settings

Runtime Settings

Features

Security & Privacy

Maintenance

Reference

Approvals & human-in-the-loop

Approvals & human-in-the-loop

What triggers an approval

The approval prompt

Clarification requests

Permission requests

Secret requests

Audit trail

Modes

Security

​Approvals & human-in-the-loop

​What triggers an approval

​The approval prompt

​Clarification requests

​Permission requests

​Secret requests

​Audit trail

Modes

Security

Approvals & human-in-the-loop

What triggers an approval

The approval prompt

Clarification requests

Permission requests

Secret requests

Audit trail